From bamboohr-pack
Audits BambooHR API usage, reduces calls via caching and patterns, and monitors to prevent rate limits in integrations.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin bamboohr-packThis skill is limited to using the following tools:
BambooHR pricing is per-employee-per-month (not per-API-call), but excessive API usage triggers rate limiting (503 errors) which causes sync failures and operational issues. This skill covers reducing API call volume, monitoring usage, and building efficient sync patterns.
Optimizes BambooHR API performance with custom reports to eliminate N+1 queries, incremental sync via changed-since, caching, and connection pooling. For slow responses or sync throughput issues.
Optimizes Attio API costs: audit usage with trackers, reduce requests via caching, select plans, monitor limits, and set budget alerts.
Optimizes HubSpot API costs by monitoring usage against daily limits, selecting plans, and reducing calls via batch reads and tracking.
Share bugs, ideas, or general feedback.
BambooHR pricing is per-employee-per-month (not per-API-call), but excessive API usage triggers rate limiting (503 errors) which causes sync failures and operational issues. This skill covers reducing API call volume, monitoring usage, and building efficient sync patterns.
BambooHR charges by employee count, not API calls:
| Plan | Pricing Model | API Access |
|---|---|---|
| Essentials | Per employee/month | Full REST API |
| Advantage | Per employee/month | Full REST API + advanced reports |
| Custom/Enterprise | Negotiated | Full API + dedicated support |
Key insight: API call volume does not directly affect your bill, but hitting rate limits causes operational failures. Optimize for reliability, not cost.
// Instrument your client to log all API calls
class InstrumentedBambooHRClient {
private callLog: { endpoint: string; method: string; timestamp: number; durationMs: number }[] = [];
async request<T>(method: string, path: string, body?: unknown): Promise<T> {
const start = Date.now();
const result = await this.innerClient.request<T>(method, path, body);
this.callLog.push({
endpoint: path.split('?')[0], // Strip query params
method,
timestamp: start,
durationMs: Date.now() - start,
});
return result;
}
generateReport(): void {
// Group by endpoint
const byEndpoint = new Map<string, number>();
for (const call of this.callLog) {
const key = `${call.method} ${call.endpoint}`;
byEndpoint.set(key, (byEndpoint.get(key) || 0) + 1);
}
console.log('\n=== BambooHR API Usage Report ===');
console.log(`Total calls: ${this.callLog.length}`);
console.log(`Time window: ${((Date.now() - this.callLog[0]?.timestamp || 0) / 1000 / 60).toFixed(1)} minutes`);
console.log('\nBy endpoint:');
for (const [endpoint, count] of [...byEndpoint.entries()].sort((a, b) => b[1] - a[1])) {
const pct = ((count / this.callLog.length) * 100).toFixed(1);
console.log(` ${count.toString().padStart(5)} (${pct}%) ${endpoint}`);
}
}
}
Pattern 1: Replace polling with webhooks
// BAD: Polling every 5 minutes (288 calls/day minimum)
setInterval(async () => {
const dir = await client.getDirectory();
checkForChanges(dir);
}, 5 * 60 * 1000);
// GOOD: Use webhooks for real-time changes (0 polling calls)
// See bamboohr-webhooks-events skill
// Only poll as a fallback safety net (once per hour)
setInterval(async () => {
const changed = await client.request('GET',
`/employees/changed/?since=${lastSync}`);
// Only process if webhook missed something
}, 60 * 60 * 1000);
Pattern 2: Request only needed fields
// BAD: Requesting all fields when you only need 3
const emp = await client.getEmployee(id, [
'firstName', 'lastName', 'displayName', 'jobTitle', 'department',
'division', 'location', 'workEmail', 'homeEmail', 'mobilePhone',
'hireDate', 'payRate', 'payType', 'ssn', 'dateOfBirth', // ...etc
]);
// GOOD: Only request what you use
const emp = await client.getEmployee(id, ['firstName', 'lastName', 'workEmail']);
Pattern 3: Cache the directory
// BAD: Fetching directory on every page load
app.get('/employees', async (req, res) => {
const dir = await client.getDirectory(); // Called 1000x/day
res.json(dir.employees);
});
// GOOD: Cache with webhook-based invalidation
let cachedDirectory: any = null;
let cacheTimestamp = 0;
async function getDirectory() {
if (cachedDirectory && Date.now() - cacheTimestamp < 5 * 60 * 1000) {
return cachedDirectory;
}
cachedDirectory = await client.getDirectory();
cacheTimestamp = Date.now();
return cachedDirectory;
}
// Invalidate on webhook
function onWebhookReceived() {
cachedDirectory = null;
}
Pattern 4: Use custom reports for bulk data
// BAD: 500 individual employee GETs
for (const id of employeeIds) {
await client.getEmployee(id, ['firstName', 'department']);
}
// GOOD: 1 custom report
const all = await client.customReport(['firstName', 'lastName', 'department']);
class RequestBudget {
private count = 0;
private windowStart = Date.now();
private readonly maxPerHour: number;
constructor(maxPerHour = 500) {
this.maxPerHour = maxPerHour;
}
async acquire(): Promise<void> {
// Reset counter every hour
if (Date.now() - this.windowStart > 3600_000) {
this.count = 0;
this.windowStart = Date.now();
}
if (this.count >= this.maxPerHour) {
const waitMs = 3600_000 - (Date.now() - this.windowStart);
console.warn(`Request budget exhausted. Waiting ${(waitMs / 1000).toFixed(0)}s`);
await new Promise(r => setTimeout(r, waitMs));
this.count = 0;
this.windowStart = Date.now();
}
this.count++;
}
stats() {
return {
used: this.count,
budget: this.maxPerHour,
remaining: this.maxPerHour - this.count,
windowResetIn: Math.max(0, 3600_000 - (Date.now() - this.windowStart)),
};
}
}
const budget = new RequestBudget(500);
// Wrap all BambooHR calls
async function budgetedRequest<T>(operation: () => Promise<T>): Promise<T> {
await budget.acquire();
return operation();
}
-- If logging API calls to a database
SELECT
DATE_TRUNC('hour', timestamp) AS hour,
endpoint,
COUNT(*) AS calls,
AVG(duration_ms) AS avg_latency,
COUNT(*) FILTER (WHERE status >= 400) AS errors,
COUNT(*) FILTER (WHERE status = 503) AS rate_limits
FROM bamboohr_api_log
WHERE timestamp >= NOW() - INTERVAL '7 days'
GROUP BY 1, 2
ORDER BY 1 DESC, calls DESC;
| Optimization | Calls Before | Calls After | Reduction |
|---|---|---|---|
| Webhooks vs polling | 288/day | 24/day (safety net) | 92% |
| Custom reports vs N+1 | 501/sync | 1/sync | 99.8% |
| Directory caching | 1000/day | 12/day | 98.8% |
| Incremental sync | Full pull | Delta only | 90-99% |
| Issue | Cause | Solution |
|---|---|---|
| Budget exhausted | High-traffic feature | Increase budget or add caching |
| Stale cached data | Cache TTL too long | Reduce TTL or invalidate on webhook |
| Webhook delivery gaps | BambooHR delivery failure | Keep hourly polling as fallback |
| Rate limit during sync | Too many parallel requests | Use queue with concurrency limit |
For architecture patterns, see bamboohr-reference-architecture.