@markwharton/eh-payroll 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @markwharton/eh-payroll
+ *
+ * Employment Hero Payroll API client.
+ *
+ * @example
+ * ```typescript
+ * import { EHClient } from '@markwharton/eh-payroll';
+ *
+ * const client = new EHClient({ apiKey: 'xxx', businessId: 123 });
+ *
+ * // Validate credentials
+ * await client.validateApiKey();
+ *
+ * // Get employees
+ * const { employees } = await client.getEmployees();
+ *
+ * // Get roster shifts
+ * const { shifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
+ * ```
+ */
+export { EHClient } from './client.js';
+export type { EHConfig, EHCacheConfig, EHRetryConfig, EHEmployee, EHEmployeeOptions, EHStandardHours, EHEmployeeGroup, EHRosterShift, EHRosterShiftOptions, EHAttendanceStatus, EHKioskEmployee, EHKioskStaffOptions, EHReportField, EHEmployeeDetailsReportOptions, EHErrorInfo, } from './types.js';
+export type { EHAuEmployee } from './employee-types.generated.js';
+export { RateLimiter } from './rate-limiter.js';
+export { buildBasicAuthHeader } from './utils.js';
+export { getErrorMessage } from '@markwharton/api-core';
+export { EH_API_BASE, EH_REGION_URLS } from './constants.js';
+export type { EHRegion } from './constants.js';
+export { EHError, parseEHErrorResponse } from './errors.js';
+export type { EHParsedError } from './errors.js';

package/dist/index.js

@@ -0,0 +1,32 @@
+/**
+ * @markwharton/eh-payroll
+ *
+ * Employment Hero Payroll API client.
+ *
+ * @example
+ * ```typescript
+ * import { EHClient } from '@markwharton/eh-payroll';
+ *
+ * const client = new EHClient({ apiKey: 'xxx', businessId: 123 });
+ *
+ * // Validate credentials
+ * await client.validateApiKey();
+ *
+ * // Get employees
+ * const { employees } = await client.getEmployees();
+ *
+ * // Get roster shifts
+ * const { shifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
+ * ```
+ */
+// Main client
+export { EHClient } from './client.js';
+// Rate limiting
+export { RateLimiter } from './rate-limiter.js';
+// Utilities
+export { buildBasicAuthHeader } from './utils.js';
+export { getErrorMessage } from '@markwharton/api-core';
+// Constants
+export { EH_API_BASE, EH_REGION_URLS } from './constants.js';
+// Errors
+export { EHError, parseEHErrorResponse } from './errors.js';

package/dist/rate-limiter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Sliding window rate limiter
+ *
+ * Enforces a maximum number of requests per time window.
+ * Callers that exceed the limit are queued and released when capacity opens.
+ *
+ * Uses a sliding window approach: tracks timestamps of recent requests and
+ * checks that no more than `maxRequests` fall within any `windowMs` period.
+ *
+ * Thread-safe in single-threaded JS — no races between concurrent acquire() calls.
+ */
+export declare class RateLimiter {
+    private maxRequests;
+    private windowMs;
+    private timestamps;
+    private queue;
+    private timer;
+    /**
+     * @param maxRequests - Maximum requests allowed per window
+     * @param windowMs - Window size in milliseconds (default: 1000)
+     */
+    constructor(maxRequests: number, windowMs?: number);
+    /**
+     * Acquire a rate limit token.
+     *
+     * Resolves immediately if under the limit, otherwise queues until capacity opens.
+     */
+    acquire(): Promise<void>;
+    /** Remove timestamps outside the current window */
+    private pruneTimestamps;
+    /** Schedule a flush to release queued callers when the oldest timestamp expires */
+    private scheduleFlush;
+}

package/dist/rate-limiter.js

@@ -0,0 +1,63 @@
+/**
+ * Sliding window rate limiter
+ *
+ * Enforces a maximum number of requests per time window.
+ * Callers that exceed the limit are queued and released when capacity opens.
+ *
+ * Uses a sliding window approach: tracks timestamps of recent requests and
+ * checks that no more than `maxRequests` fall within any `windowMs` period.
+ *
+ * Thread-safe in single-threaded JS — no races between concurrent acquire() calls.
+ */
+export class RateLimiter {
+    /**
+     * @param maxRequests - Maximum requests allowed per window
+     * @param windowMs - Window size in milliseconds (default: 1000)
+     */
+    constructor(maxRequests, windowMs = 1000) {
+        this.maxRequests = maxRequests;
+        this.windowMs = windowMs;
+        this.timestamps = [];
+        this.queue = [];
+        this.timer = null;
+    }
+    /**
+     * Acquire a rate limit token.
+     *
+     * Resolves immediately if under the limit, otherwise queues until capacity opens.
+     */
+    acquire() {
+        this.pruneTimestamps();
+        if (this.timestamps.length < this.maxRequests) {
+            this.timestamps.push(Date.now());
+            return Promise.resolve();
+        }
+        return new Promise(resolve => {
+            this.queue.push({ resolve });
+            this.scheduleFlush();
+        });
+    }
+    /** Remove timestamps outside the current window */
+    pruneTimestamps() {
+        const cutoff = Date.now() - this.windowMs;
+        this.timestamps = this.timestamps.filter(t => t > cutoff);
+    }
+    /** Schedule a flush to release queued callers when the oldest timestamp expires */
+    scheduleFlush() {
+        if (this.timer || this.queue.length === 0 || this.timestamps.length === 0)
+            return;
+        const oldest = this.timestamps[0];
+        const delay = Math.max(0, this.windowMs - (Date.now() - oldest) + 1);
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.pruneTimestamps();
+            while (this.queue.length > 0 && this.timestamps.length < this.maxRequests) {
+                this.timestamps.push(Date.now());
+                this.queue.shift().resolve();
+            }
+            if (this.queue.length > 0) {
+                this.scheduleFlush();
+            }
+        }, delay);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Employment Hero Payroll Type Definitions
+ *
+ * Types for the Employment Hero Payroll (KeyPay) API.
+ * Based on the API reference and KeyPay .NET SDK models.
+ */
+import type { EHRegion } from './constants.js';
+/**
+ * Cache configuration for EHClient
+ *
+ * When provided to EHConfig, enables in-memory TTL caching of API responses.
+ * All TTL values are in milliseconds. Omit individual TTLs to use defaults.
+ */
+export interface EHCacheConfig {
+    /** TTL for employee list (default: 300000 = 5 min) */
+    employeesTtl?: number;
+    /** TTL for employee groups (default: 300000 = 5 min) */
+    groupsTtl?: number;
+    /** TTL for standard hours (default: 300000 = 5 min) */
+    standardHoursTtl?: number;
+    /** TTL for roster shifts (default: 120000 = 2 min) */
+    rosterShiftsTtl?: number;
+    /** TTL for report fields (default: 600000 = 10 min) */
+    reportFieldsTtl?: number;
+}
+/**
+ * Retry configuration for EHClient
+ *
+ * Controls automatic retry behavior for transient failures
+ * (HTTP 429 Too Many Requests, 503 Service Unavailable).
+ * Uses exponential backoff with optional Retry-After header support.
+ */
+export interface EHRetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay in milliseconds before first retry (default: 1000) */
+    initialDelayMs?: number;
+    /** Maximum delay cap in milliseconds (default: 10000) */
+    maxDelayMs?: number;
+}
+/**
+ * Employment Hero Payroll configuration for API access
+ */
+export interface EHConfig {
+    /** API key for authentication (used as Basic Auth username) */
+    apiKey: string;
+    /** Business ID to operate on */
+    businessId: number;
+    /** API region (default: 'au'). Sets the base URL automatically. */
+    region?: EHRegion;
+    /** Override base URL directly (takes priority over region) */
+    baseUrl?: string;
+    /** Optional callback invoked on each API request (for debugging/logging) */
+    onRequest?: (info: {
+        method: string;
+        url: string;
+        description?: string;
+    }) => void;
+    /** Enable caching with optional TTL overrides. Omit to disable caching. */
+    cache?: EHCacheConfig;
+    /** Retry configuration for transient failures (429, 503). Omit to disable retry. */
+    retry?: EHRetryConfig;
+    /** Max requests per second (default: 5 per API spec). Set 0 to disable. */
+    rateLimitPerSecond?: number;
+}
+/**
+ * Employee from unstructured endpoint
+ *
+ * Region-specific types are generated from Swagger specs.
+ * EHEmployee is an alias for EHAuEmployee for backward compatibility.
+ *
+ * @see employee-types.generated.ts
+ */
+export type { EHAuEmployee as EHEmployee } from './employee-types.generated.js';
+/**
+ * Standard hours for an employee
+ *
+ * From GET /business/{id}/employee/{eid}/standardhours
+ * Contains the FullTimeEquivalentHours field needed for FTE calculations.
+ */
+export interface EHStandardHours {
+    /** Employee ID */
+    employeeId: number;
+    /** Standard hours per week */
+    standardHoursPerWeek: number;
+    /** Standard hours per day */
+    standardHoursPerDay: number;
+    /** Full-time equivalent hours (the FTE value) */
+    fullTimeEquivalentHours: number | null;
+}
+/**
+ * Employee group
+ */
+export interface EHEmployeeGroup {
+    /** Group ID */
+    id: number;
+    /** Group name */
+    name: string;
+}
+/**
+ * Roster shift from EH API
+ *
+ * From GET /business/{id}/rostershift
+ */
+export interface EHRosterShift {
+    /** Shift ID */
+    id: number;
+    /** Employee ID (null for unassigned shifts) */
+    employeeId: number | null;
+    /** Employee name */
+    employeeName: string | null;
+    /** Location ID */
+    locationId: number | null;
+    /** Location name */
+    locationName: string | null;
+    /** Work type ID */
+    workTypeId: number | null;
+    /** Work type name */
+    workTypeName: string | null;
+    /** Shift start time (ISO 8601) */
+    startTime: string;
+    /** Shift end time (ISO 8601) */
+    endTime: string;
+    /** Shift notes */
+    notes: string | null;
+    /** Whether the shift has been published */
+    published: boolean;
+    /** Whether the shift has been accepted */
+    accepted: boolean;
+}
+/**
+ * Time and attendance status
+ */
+export type EHAttendanceStatus = 'NotClockedOn' | 'ClockedOn' | 'OnBreak' | 'ClockedOff';
+/**
+ * Kiosk employee from time and attendance
+ *
+ * From GET /business/{id}/kiosk/{kid}/staff
+ */
+export interface EHKioskEmployee {
+    /** Employee ID */
+    employeeId: number;
+    /** First name */
+    firstName: string | null;
+    /** Surname */
+    surname: string | null;
+    /** Full name */
+    name: string | null;
+    /** Attendance status */
+    status: EHAttendanceStatus;
+    /** Clock-on time in UTC */
+    clockOnTimeUtc: string | null;
+    /** Break start time in UTC */
+    breakStartTimeUtc: string | null;
+    /** Current shift ID */
+    currentShiftId: number | null;
+    /** Employee start date */
+    employeeStartDate: string | null;
+    /** Employee group IDs */
+    employeeGroupIds: number[];
+}
+/**
+ * Options for getEmployees
+ */
+export interface EHEmployeeOptions {
+    /** Filter by pay schedule ID */
+    payScheduleId?: number;
+    /** Filter by location ID */
+    locationId?: number;
+}
+/**
+ * Options for getRosterShifts
+ */
+export interface EHRosterShiftOptions {
+    /** Filter by employee ID */
+    employeeId?: number;
+    /** Filter by location ID */
+    locationId?: number;
+    /** Filter by employee group ID */
+    employeeGroupId?: number;
+    /** Include shifts with all roles (default: only unassigned roles) */
+    selectAllRoles?: boolean;
+    /** Filter by single shift status */
+    shiftStatus?: 'All' | 'Published' | 'Unpublished' | 'Accepted';
+    /** Filter by multiple shift statuses */
+    shiftStatuses?: ('All' | 'Published' | 'Unpublished' | 'Accepted')[];
+    /** Filter by specific locations (multiple) */
+    selectedLocations?: string[];
+    /** Filter by specific employees (multiple) */
+    selectedEmployees?: string[];
+    /** Filter by specific roles (multiple) */
+    selectedRoles?: string[];
+    /** Return only shifts without role assignments */
+    unassignedShiftsOnly?: boolean;
+    /** Exclude shifts overlapping the from date */
+    excludeShiftsOverlappingFromDate?: boolean;
+    /** Include warning data in response */
+    includeWarnings?: boolean;
+}
+/**
+ * Options for getKioskStaff
+ */
+export interface EHKioskStaffOptions {
+    /** Restrict current shifts to current kiosk location (default: false) */
+    restrictCurrentShiftsToCurrentKioskLocation?: boolean;
+}
+/**
+ * Available field for the Employee Details Report
+ *
+ * From GET /business/{id}/report/employeedetails/fields
+ */
+export interface EHReportField {
+    /** Field identifier (used in selectedColumns) */
+    value: string;
+    /** Human-readable field name */
+    displayText: string;
+}
+/**
+ * Options for getEmployeeDetailsReport
+ */
+export interface EHEmployeeDetailsReportOptions {
+    /** Column names to include in the report */
+    selectedColumns?: string[];
+    /** Filter by location ID */
+    locationId?: number;
+    /** Filter by employing entity ID */
+    employingEntityId?: number;
+    /** Include active employees (default: true) */
+    includeActive?: boolean;
+    /** Include inactive employees (default: false) */
+    includeInactive?: boolean;
+}
+/**
+ * Structured error information from EH API
+ */
+export interface EHErrorInfo {
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code from the response */
+    statusCode: number;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Employment Hero Payroll Type Definitions
+ *
+ * Types for the Employment Hero Payroll (KeyPay) API.
+ * Based on the API reference and KeyPay .NET SDK models.
+ */
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Employment Hero Payroll Utility Functions
+ */
+/**
+ * Build the Authorization header for EH API requests (HTTP Basic Auth)
+ *
+ * EH API uses the API key as the username with an empty password.
+ */
+export declare function buildBasicAuthHeader(apiKey: string): string;

package/dist/utils.js

@@ -0,0 +1,14 @@
+/**
+ * Employment Hero Payroll Utility Functions
+ */
+// ============================================================================
+// Authentication
+// ============================================================================
+/**
+ * Build the Authorization header for EH API requests (HTTP Basic Auth)
+ *
+ * EH API uses the API key as the username with an empty password.
+ */
+export function buildBasicAuthHeader(apiKey) {
+    return 'Basic ' + btoa(apiKey + ':');
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@markwharton/eh-payroll",
+  "version": "1.0.0",
+  "description": "Employment Hero Payroll API client",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@markwharton/api-core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MarkWharton/api-packages.git",
+    "directory": "packages/eh-payroll"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Mark Wharton",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}