---

name: bamboohr-sdk-patterns description: >- Select and wrap BambooHR's official Python or PHP SDK, or a narrow direct HTTP adapter, with tenant isolation and typed errors. Use when implementing a reusable client or replacing an unverified community package. Trigger with "BambooHR SDK", "BambooHR client", or "BambooHR integration patterns". allowed-tools: Read,Glob,Grep,Write,Edit argument-hint: "<python|php|http> " version: 1.5.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags: [saas, hr, bamboohr, sdk, architecture] model: inherit effort: high compatibility: Designed for Claude Code

BambooHR SDK and Client Patterns

Overview

Build a small application-owned adapter around a verified BambooHR transport. Keep BambooHR models and error details at the adapter boundary so upstream SDK regeneration or endpoint migration does not ripple through business logic.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

• BambooHR/bhr-api-python and BambooHR/bhr-api-php are official repositories.
• bamboohr/api 2.0.1 is published on Packagist.
• The Python repository documents bamboohr-sdk 1.0.0, but public PyPI did not expose that distribution on 2026-09-11 and the repository had no tag or release. Treat it as source-visible, not registry-proven.
• No official npm BambooHR SDK was found; a TypeScript integration should use a narrow HTTP adapter rather than claim an official package.

Authentication

Expose constructors for OAuth and API-key identities, not raw headers. Bind each client to one validated tenant subdomain. If OAuth refresh is enabled, persist rotated tokens through the caller-owned callback; the Python SDK does not store them across restarts.

Instructions

1. Inventory language, package lock, existing HTTP client, and supported auth modes with Read, Glob, and Grep.
2. Verify the selected package in its public registry at implementation time. For an approved source install, pin an immutable commit and record its hash, license, provenance, and update owner.
3. Define an adapter with explicit operations such as getCompanyInformation, listEmployees, and queryDatasetV2; do not expose an arbitrary URL method to untrusted callers.
4. Normalize errors into status, operation, retryability, request ID, and a redacted summary. Preserve the original exception only in protected logs.
5. Keep tenant, authentication, timeout, retry budget, and user-agent immutable for the life of a client instance.
6. Test request construction, tenant rejection, secret redaction, typed error mapping, token-refresh persistence, and response-shape drift with fixtures.

Tool Discipline

Use Read, Glob, and Grep to establish the project's language and package state. Use Write/Edit only for the approved adapter and tests. This skill does not authorize package installation, remote registry mutation, or live tenant calls.

Approval Boundaries

Require approval before adding a dependency, using an unreleased commit, making a tenant request, broadening OAuth scopes, or enabling debug logging around HR data. Never silently fall back from OAuth to an API key.

Output

Return the chosen transport and exact version/commit, registry verification, adapter operations, auth and tenant boundary, error taxonomy, test results, and remaining publication or live-test approvals.

Error Handling

• Package absent from registry: stop; offer pinned-source review or direct HTTP.
• SDK method absent for a documented endpoint: use the generated manual client only after checking the current OpenAPI, or implement a bounded HTTP adapter.
• Response schema drift: quarantine the payload and fail the contract test.

Examples

• "Install the official Python SDK" first proves public registry availability.
• "Use an npm BambooHR SDK" reports that no official package was verified and proposes a three-operation HTTP adapter.

Resources

Read official evidence before choosing a transport.