bamboohr-sdk-patterns

name	bamboohr-sdk-patterns
description	Apply production-ready BambooHR API patterns for TypeScript and Python. Use when implementing BambooHR integrations, building reusable clients, or establishing team coding standards for BambooHR REST API. Trigger with phrases like "bamboohr SDK patterns", "bamboohr best practices", "bamboohr code patterns", "idiomatic bamboohr", "bamboohr client wrapper".
allowed-tools	Read, Write, Edit
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","hr","bamboohr","patterns"]
compatible-with	claude-code

BambooHR SDK Patterns

Overview

Production-ready patterns for the BambooHR REST API. BambooHR has no official Node.js SDK — you call the API directly via fetch or axios. These patterns wrap the raw HTTP calls into type-safe, retry-aware, multi-tenant-ready code.

Prerequisites

• Completed bamboohr-install-auth setup
• Familiarity with async/await and TypeScript generics

Instructions

Step 1: Type-Safe Client with Error Handling

// src/bamboohr/client.ts
import 'dotenv/config';

export interface BambooHRConfig {
  companyDomain: string;
  apiKey: string;
  timeoutMs?: number;
}

export interface BambooEmployee {
  id: string;
  firstName: string;
  lastName: string;
  displayName: string;
  jobTitle: string;
  department: string;
  division: string;
  workEmail: string;
  location: string;
  status: string;
  hireDate: string;
  supervisor: string;
  employeeNumber: string;
  photoUrl?: ;
}

   {
   : ;
   : ;
   : ;

  () {
    . = ;
    . = ;
    . = config. ?? ;
  }

   request<T>(: , : , ?: ): <T> {
     controller =  ();
     timer = ( controller.(), .);

     {
       res =  (, {
        method,
        : {
          : .,
          : ,
          ...(body ? { :  } : {}),
        },
        : body ? .(body) : ,
        : controller.,
      });

       (!res.) {
         errMsg = res..() || res.;
          (res., errMsg, path, {
          : res..(),
        });
      }

      
       text =  res.();
       text ? .(text) : ({}  T);
    }  {
      (timer);
    }
  }

  
   () {
     .<<, >>(, );
  }

   () {
     .<{ : []; : [] }>(, );
  }

   () {
     .<{ : { :  } }>(, , data);
  }

   () {
     .<>(, , data);
  }

  
   () {
     .<{ : ; : <, >[] }>(
      , ,
      { : , fields, filters },
    );
  }

  
   () {
     params =  ({ start, end, ...(status && { status }) });
     .<[]>(, );
  }

  
   () {
     .<[]>(, );
  }

   () {
     .<>(, , data);
  }
}

     {
  () {
    ();
    . = ;
  }

   ():  {
     . ===  || . ===  || . >= ;
  }
}