@markwharton/eh-payroll 1.0.0

package/README.md

@@ -0,0 +1,126 @@
+# @markwharton/eh-payroll
+
+Employment Hero Payroll API client for employee data, roster shifts, and time & attendance.
+
+## Install
+
+```bash
+npm install @markwharton/eh-payroll
+```
+
+## Quick Start
+
+```typescript
+import { EHClient } from '@markwharton/eh-payroll';
+
+const client = new EHClient({
+  apiKey: 'xxx',
+  businessId: 123,
+  region: 'au',  // 'au' | 'nz' | 'uk' | 'sg' | 'my' (default: 'au')
+});
+
+// Validate credentials
+await client.validateApiKey();
+
+// Get all employees
+const { employees } = await client.getEmployees();
+
+// Get employees filtered by location
+const { employees: filtered } = await client.getEmployees({ locationId: 5 });
+
+// Get roster shifts for a date range (auto-paginates)
+const { shifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
+
+// Get roster shifts with filters
+const { shifts: published } = await client.getRosterShifts('2026-02-03', '2026-02-09', {
+  employeeId: 42,
+  shiftStatus: 'Published',
+  selectAllRoles: true
+});
+
+// Get kiosk staff (time and attendance)
+const { staff } = await client.getKioskStaff(kioskId);
+
+// Get employee groups
+const { groups } = await client.getEmployeeGroups();
+
+// Get standard hours for an employee (includes FTE value)
+const { standardHours } = await client.getStandardHours(employeeId);
+
+// Discover available report columns
+const { fields } = await client.getReportFields();
+
+// Run Employee Details Report with selected columns
+const { records } = await client.getEmployeeDetailsReport({
+  selectedColumns: ['FirstName', 'Surname', 'ExternalId']
+});
+```
+
+## API Reference
+
+All methods return `{ data?, error? }` result objects rather than throwing exceptions.
+
+| Method | Parameters | Returns |
+|--------|-----------|---------|
+| `validateApiKey()` | — | `{ valid, error? }` |
+| `getEmployees(options?)` | `EHEmployeeOptions?` | `{ employees?, error? }` |
+| `getEmployee(employeeId)` | `number` | `{ employee?, error? }` |
+| `getStandardHours(employeeId)` | `number` | `{ standardHours?, error? }` |
+| `getEmployeeGroups()` | — | `{ groups?, error? }` |
+| `getRosterShifts(from, to, options?)` | `string, string, EHRosterShiftOptions?` | `{ shifts?, error? }` |
+| `getKioskStaff(kioskId, options?)` | `number, EHKioskStaffOptions?` | `{ staff?, error? }` |
+| `getReportFields()` | — | `{ fields?, error? }` |
+| `getEmployeeDetailsReport(options?)` | `EHEmployeeDetailsReportOptions?` | `{ records?, error? }` |
+
+### `getRosterShifts()`
+
+Automatically paginates through all results (100 per page). Returns the complete set of shifts for the requested date range. All filter options are applied server-side, reducing the number of results and pages fetched.
+
+### Query Parameter Casing
+
+The [KeyPay Swagger spec](https://api.keypay.com.au/swagger-au.json) uses inconsistent query parameter casing across endpoints. Roster shifts use PascalCase (`EmployeeId`, `ShiftStatus`), while all other endpoints use camelCase (`selectedColumns`, `filter.locationId`). The library accepts camelCase options throughout and converts to PascalCase for roster shifts internally.
+
+## Configuration
+
+```typescript
+const client = new EHClient({
+  apiKey: 'your-api-key',       // Required: used as Basic Auth username
+  businessId: 12345,            // Required: business ID
+  region: 'au',                 // Optional: au, nz, uk, sg, my (default: au)
+  baseUrl: '...',               // Optional: override base URL (takes priority over region)
+  rateLimitPerSecond: 5,        // Optional: rate limit (default 5, set 0 to disable)
+  onRequest: ({ method, url, description }) => { ... },  // Optional: debug callback
+  cache: {},                    // Optional: enable TTL caching (defaults below)
+  retry: {                      // Optional: retry on 429/503
+    maxRetries: 3,
+    initialDelayMs: 1000,
+    maxDelayMs: 10000,
+  },
+});
+```
+
+### Cache TTLs
+
+| Cache Key | Default TTL |
+|-----------|-------------|
+| Employees | 5 min |
+| Employee groups | 5 min |
+| Standard hours | 5 min |
+| Roster shifts | 2 min |
+| Report fields | 10 min |
+
+### Rate Limiting
+
+The client enforces a sliding-window rate limit of 5 requests per second (the [API limit](https://api.keypay.com.au/australia/guides/Usage.html)). All outbound requests pass through the rate limiter automatically. Set `rateLimitPerSecond: 0` in config to disable (useful for tests).
+
+### Retry
+
+Automatically retries on HTTP 429 (Too Many Requests) and 503 (Service Unavailable) with exponential backoff. Respects the `Retry-After` header when present.
+
+## Authentication
+
+Uses HTTP Basic Authentication with the API key as the username and an empty password, per the [KeyPay API reference](https://api.keypay.com.au/).
+
+## License
+
+MIT

package/dist/cache.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Simple in-memory TTL cache with request coalescing
+ *
+ * Provides per-instance memoization for EHClient API responses.
+ * In serverless environments (Azure Functions, Static Web Apps),
+ * module-level state persists across warm invocations within the
+ * same instance — this cache leverages that behavior.
+ *
+ * Request coalescing: when multiple concurrent callers request the
+ * same expired key, only one factory call is made. All callers
+ * receive the same resolved value (or the same rejection).
+ *
+ * Not a distributed cache: each instance has its own cache.
+ * Cold starts and instance recycling naturally clear stale data.
+ */
+export declare class TTLCache {
+    private store;
+    private inflight;
+    /**
+     * Get a cached value, or call the factory to populate it.
+     *
+     * If a factory call is already in progress for this key,
+     * returns the existing promise instead of starting a duplicate.
+     *
+     * @param key - Cache key
+     * @param ttlMs - Time-to-live in milliseconds
+     * @param factory - Async function to produce the value on cache miss
+     */
+    get<T>(key: string, ttlMs: number, factory: () => Promise<T>): Promise<T>;
+    /**
+     * Invalidate cache entries matching a key prefix.
+     */
+    invalidate(prefix: string): void;
+    /**
+     * Clear all cached data and in-flight requests.
+     */
+    clear(): void;
+}

package/dist/cache.js

@@ -0,0 +1,73 @@
+/**
+ * Simple in-memory TTL cache with request coalescing
+ *
+ * Provides per-instance memoization for EHClient API responses.
+ * In serverless environments (Azure Functions, Static Web Apps),
+ * module-level state persists across warm invocations within the
+ * same instance — this cache leverages that behavior.
+ *
+ * Request coalescing: when multiple concurrent callers request the
+ * same expired key, only one factory call is made. All callers
+ * receive the same resolved value (or the same rejection).
+ *
+ * Not a distributed cache: each instance has its own cache.
+ * Cold starts and instance recycling naturally clear stale data.
+ */
+export class TTLCache {
+    constructor() {
+        this.store = new Map();
+        this.inflight = new Map();
+    }
+    /**
+     * Get a cached value, or call the factory to populate it.
+     *
+     * If a factory call is already in progress for this key,
+     * returns the existing promise instead of starting a duplicate.
+     *
+     * @param key - Cache key
+     * @param ttlMs - Time-to-live in milliseconds
+     * @param factory - Async function to produce the value on cache miss
+     */
+    async get(key, ttlMs, factory) {
+        const existing = this.store.get(key);
+        if (existing && existing.expiresAt > Date.now()) {
+            return existing.data;
+        }
+        const pending = this.inflight.get(key);
+        if (pending) {
+            return pending;
+        }
+        const promise = factory().then((data) => {
+            this.store.set(key, { data, expiresAt: Date.now() + ttlMs });
+            this.inflight.delete(key);
+            return data;
+        }, (err) => {
+            this.inflight.delete(key);
+            throw err;
+        });
+        this.inflight.set(key, promise);
+        return promise;
+    }
+    /**
+     * Invalidate cache entries matching a key prefix.
+     */
+    invalidate(prefix) {
+        for (const key of this.store.keys()) {
+            if (key.startsWith(prefix)) {
+                this.store.delete(key);
+            }
+        }
+        for (const key of this.inflight.keys()) {
+            if (key.startsWith(prefix)) {
+                this.inflight.delete(key);
+            }
+        }
+    }
+    /**
+     * Clear all cached data and in-flight requests.
+     */
+    clear() {
+        this.store.clear();
+        this.inflight.clear();
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Employment Hero Payroll API Client
+ *
+ * Provides methods for interacting with the Employment Hero Payroll (KeyPay) API.
+ * Uses HTTP Basic Authentication (API key as username, empty password).
+ *
+ * @see https://api.keypay.com.au/
+ */
+import type { EHConfig, EHEmployeeOptions, EHStandardHours, EHEmployeeGroup, EHRosterShift, EHRosterShiftOptions, EHKioskEmployee, EHKioskStaffOptions, EHErrorInfo, EHReportField, EHEmployeeDetailsReportOptions } from './types.js';
+import type { EHAuEmployee } from './employee-types.generated.js';
+/**
+ * Employment Hero Payroll API Client
+ *
+ * @example
+ * ```typescript
+ * const client = new EHClient({ apiKey: 'xxx', businessId: 123 });
+ *
+ * // Validate credentials
+ * await client.validateApiKey();
+ *
+ * // Get employees
+ * const { employees } = await client.getEmployees();
+ * ```
+ */
+export declare class EHClient {
+    private readonly apiKey;
+    private readonly businessId;
+    private readonly baseUrl;
+    private readonly onRequest?;
+    private readonly cache?;
+    private readonly cacheTtl;
+    private readonly retryConfig?;
+    private readonly rateLimiter?;
+    constructor(config: EHConfig);
+    /**
+     * Route through cache if enabled, otherwise call factory directly.
+     */
+    private cached;
+    /**
+     * Clear all cached API responses.
+     */
+    clearCache(): void;
+    /**
+     * Make an authenticated request to the EH API
+     *
+     * When retry is configured, automatically retries on HTTP 429 and 503
+     * with exponential backoff. Respects the Retry-After header when present.
+     */
+    private fetch;
+    /**
+     * Fetch a URL and parse the response, with standardized error handling.
+     */
+    private fetchAndParse;
+    /**
+     * Validate the API key by calling GET /user
+     */
+    validateApiKey(): Promise<{
+        valid: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get all employees (unstructured format)
+     */
+    getEmployees(options?: EHEmployeeOptions): Promise<{
+        employees?: EHAuEmployee[];
+        error?: EHErrorInfo;
+    }>;
+    /**
+     * Get a single employee by ID
+     */
+    getEmployee(employeeId: number): Promise<{
+        employee?: EHAuEmployee;
+        error?: EHErrorInfo;
+    }>;
+    /**
+     * Get standard hours for an employee (includes FTE value)
+     */
+    getStandardHours(employeeId: number): Promise<{
+        standardHours?: EHStandardHours;
+        error?: EHErrorInfo;
+    }>;
+    /**
+     * Get all employee groups
+     */
+    getEmployeeGroups(): Promise<{
+        groups?: EHEmployeeGroup[];
+        error?: EHErrorInfo;
+    }>;
+    /**
+     * Get roster shifts for a date range
+     *
+     * @param fromDate - Start date (YYYY-MM-DD)
+     * @param toDate - End date (YYYY-MM-DD)
+     * @param options - Optional filters
+     */
+    getRosterShifts(fromDate: string, toDate: string, options?: EHRosterShiftOptions): Promise<{
+        shifts?: EHRosterShift[];
+        error?: EHErrorInfo;
+    }>;
+    /**
+     * Get kiosk staff for time and attendance
+     *
+     * @param kioskId - Kiosk identifier
+     * @param options - Optional query parameters
+     */
+    getKioskStaff(kioskId: number, options?: EHKioskStaffOptions): Promise<{
+        staff?: EHKioskEmployee[];
+        error?: EHErrorInfo;
+    }>;
+    /**
+     * Get available fields for the Employee Details Report
+     *
+     * Returns the list of columns that can be requested via getEmployeeDetailsReport().
+     * Use this to discover what data is available for the business.
+     */
+    getReportFields(): Promise<{
+        fields?: EHReportField[];
+        error?: EHErrorInfo;
+    }>;
+    /**
+     * Get Employee Details Report
+     *
+     * Returns all employees with the requested columns in a single API call.
+     * The response is dynamic (JObject[]) — field keys depend on selectedColumns.
+     */
+    getEmployeeDetailsReport(options?: EHEmployeeDetailsReportOptions): Promise<{
+        records?: Record<string, unknown>[];
+        error?: EHErrorInfo;
+    }>;
+}