@markwharton/eh-payroll 1.0.0

package/dist/client.js

@@ -0,0 +1,396 @@
+/**
+ * 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 { buildBasicAuthHeader } from './utils.js';
+import { parseEHErrorResponse } from './errors.js';
+import { EH_API_BASE, EH_REGION_URLS } from './constants.js';
+import { TTLCache, getErrorMessage, fetchWithRetry } from '@markwharton/api-core';
+import { RateLimiter } from './rate-limiter.js';
+/** Default page size for paginated endpoints */
+const DEFAULT_PAGE_SIZE = 100;
+// ============================================================================
+// Client
+// ============================================================================
+/**
+ * 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 class EHClient {
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.businessId = config.businessId;
+        this.baseUrl = config.baseUrl ?? (config.region ? EH_REGION_URLS[config.region] : EH_API_BASE);
+        this.onRequest = config.onRequest;
+        // Initialize cache if configured
+        if (config.cache) {
+            this.cache = new TTLCache();
+        }
+        this.cacheTtl = {
+            employeesTtl: config.cache?.employeesTtl ?? 300000,
+            groupsTtl: config.cache?.groupsTtl ?? 300000,
+            standardHoursTtl: config.cache?.standardHoursTtl ?? 300000,
+            rosterShiftsTtl: config.cache?.rosterShiftsTtl ?? 120000,
+            reportFieldsTtl: config.cache?.reportFieldsTtl ?? 600000,
+        };
+        // Initialize retry config with defaults if provided
+        if (config.retry) {
+            this.retryConfig = {
+                maxRetries: config.retry.maxRetries ?? 3,
+                initialDelayMs: config.retry.initialDelayMs ?? 1000,
+                maxDelayMs: config.retry.maxDelayMs ?? 10000,
+            };
+        }
+        // Initialize rate limiter (default: 5 req/s per API spec)
+        const rateLimitPerSecond = config.rateLimitPerSecond ?? 5;
+        if (rateLimitPerSecond > 0) {
+            this.rateLimiter = new RateLimiter(rateLimitPerSecond);
+        }
+    }
+    /**
+     * Route through cache if enabled, otherwise call factory directly.
+     */
+    async cached(key, ttlMs, factory) {
+        if (this.cache) {
+            return this.cache.get(key, ttlMs, factory);
+        }
+        return factory();
+    }
+    /**
+     * Clear all cached API responses.
+     */
+    clearCache() {
+        this.cache?.clear();
+    }
+    /**
+     * 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.
+     */
+    async fetch(url, options = {}) {
+        const { method = 'GET', body, description } = options;
+        // Acquire rate limit token before making request
+        if (this.rateLimiter) {
+            await this.rateLimiter.acquire();
+        }
+        // Notify listener of request (for debugging)
+        this.onRequest?.({ method, url, description });
+        return fetchWithRetry(url, {
+            method,
+            headers: {
+                Authorization: buildBasicAuthHeader(this.apiKey),
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        }, {
+            retry: this.retryConfig,
+            onRetry: ({ attempt, maxRetries, delayMs, status }) => {
+                this.onRequest?.({
+                    method,
+                    url,
+                    description: `Retry ${attempt}/${maxRetries} after ${delayMs}ms (HTTP ${status})`,
+                });
+            },
+        });
+    }
+    /**
+     * Fetch a URL and parse the response, with standardized error handling.
+     */
+    async fetchAndParse(url, parse, fetchOptions) {
+        try {
+            const response = await this.fetch(url, fetchOptions);
+            if (!response.ok) {
+                const errorText = await response.text();
+                const { message } = parseEHErrorResponse(errorText, response.status);
+                return { error: { message, statusCode: response.status } };
+            }
+            return { data: await parse(response) };
+        }
+        catch (error) {
+            return { error: { message: getErrorMessage(error), statusCode: 0 } };
+        }
+    }
+    // ============================================================================
+    // Validation
+    // ============================================================================
+    /**
+     * Validate the API key by calling GET /user
+     */
+    async validateApiKey() {
+        const url = `${this.baseUrl}/user`;
+        try {
+            const response = await this.fetch(url);
+            if (response.ok) {
+                return { valid: true };
+            }
+            if (response.status === 401 || response.status === 403) {
+                return { valid: false, error: 'Invalid or expired API key' };
+            }
+            return { valid: false, error: `Unexpected response: HTTP ${response.status}` };
+        }
+        catch (error) {
+            return { valid: false, error: getErrorMessage(error) || 'Connection failed' };
+        }
+    }
+    // ============================================================================
+    // Employees
+    // ============================================================================
+    /**
+     * Get all employees (unstructured format)
+     */
+    async getEmployees(options) {
+        const parts = ['employees'];
+        if (options?.payScheduleId != null)
+            parts.push(`ps:${options.payScheduleId}`);
+        if (options?.locationId != null)
+            parts.push(`loc:${options.locationId}`);
+        const cacheKey = parts.join(':');
+        return this.cached(cacheKey, this.cacheTtl.employeesTtl, async () => {
+            const params = new URLSearchParams();
+            if (options?.payScheduleId != null)
+                params.set('filter.payScheduleId', String(options.payScheduleId));
+            if (options?.locationId != null)
+                params.set('filter.locationId', String(options.locationId));
+            const queryString = params.toString();
+            const url = queryString
+                ? `${this.baseUrl}/business/${this.businessId}/employee/unstructured?${queryString}`
+                : `${this.baseUrl}/business/${this.businessId}/employee/unstructured`;
+            const { data, error } = await this.fetchAndParse(url, async (r) => {
+                return await r.json();
+            });
+            return error ? { error } : { employees: data };
+        });
+    }
+    /**
+     * Get a single employee by ID
+     */
+    async getEmployee(employeeId) {
+        return this.cached(`employee:${employeeId}`, this.cacheTtl.employeesTtl, async () => {
+            const url = `${this.baseUrl}/business/${this.businessId}/employee/unstructured/${employeeId}`;
+            const { data, error } = await this.fetchAndParse(url, async (r) => {
+                return await r.json();
+            });
+            return error ? { error } : { employee: data };
+        });
+    }
+    // ============================================================================
+    // Standard Hours
+    // ============================================================================
+    /**
+     * Get standard hours for an employee (includes FTE value)
+     */
+    async getStandardHours(employeeId) {
+        return this.cached(`standardhours:${employeeId}`, this.cacheTtl.standardHoursTtl, async () => {
+            const url = `${this.baseUrl}/business/${this.businessId}/employee/${employeeId}/standardhours`;
+            const { data, error } = await this.fetchAndParse(url, async (r) => {
+                return await r.json();
+            }, { description: `Get standard hours for employee ${employeeId}` });
+            return error ? { error } : { standardHours: data };
+        });
+    }
+    // ============================================================================
+    // Employee Groups
+    // ============================================================================
+    /**
+     * Get all employee groups
+     */
+    async getEmployeeGroups() {
+        return this.cached('groups', this.cacheTtl.groupsTtl, async () => {
+            const url = `${this.baseUrl}/business/${this.businessId}/employeegroup`;
+            const { data, error } = await this.fetchAndParse(url, async (r) => {
+                return await r.json();
+            });
+            return error ? { error } : { groups: data };
+        });
+    }
+    // ============================================================================
+    // Roster Shifts
+    // ============================================================================
+    /**
+     * 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
+     */
+    async getRosterShifts(fromDate, toDate, options) {
+        const parts = [`rostershifts:${fromDate}:${toDate}`];
+        if (options?.employeeId != null)
+            parts.push(`eid:${options.employeeId}`);
+        if (options?.locationId != null)
+            parts.push(`lid:${options.locationId}`);
+        if (options?.employeeGroupId != null)
+            parts.push(`gid:${options.employeeGroupId}`);
+        if (options?.shiftStatus)
+            parts.push(`ss:${options.shiftStatus}`);
+        if (options?.shiftStatuses)
+            parts.push(`sss:${options.shiftStatuses.join(',')}`);
+        if (options?.selectedLocations)
+            parts.push(`sl:${options.selectedLocations.join(',')}`);
+        if (options?.selectedEmployees)
+            parts.push(`se:${options.selectedEmployees.join(',')}`);
+        if (options?.selectedRoles)
+            parts.push(`sr:${options.selectedRoles.join(',')}`);
+        if (options?.selectAllRoles)
+            parts.push('sar');
+        if (options?.unassignedShiftsOnly)
+            parts.push('uso');
+        if (options?.excludeShiftsOverlappingFromDate)
+            parts.push('exo');
+        if (options?.includeWarnings)
+            parts.push('iw');
+        const cacheKey = parts.join(':');
+        return this.cached(cacheKey, this.cacheTtl.rosterShiftsTtl, async () => {
+            // Roster shift query params are PascalCase per the Swagger spec, unlike
+            // all other endpoints which use camelCase. See: https://api.keypay.com.au/swagger-au.json
+            const params = new URLSearchParams({
+                FromDate: fromDate,
+                ToDate: toDate,
+                PageSize: String(DEFAULT_PAGE_SIZE),
+            });
+            if (options?.employeeId != null)
+                params.set('EmployeeId', String(options.employeeId));
+            if (options?.locationId != null)
+                params.set('LocationId', String(options.locationId));
+            if (options?.employeeGroupId != null)
+                params.set('EmployeeGroupId', String(options.employeeGroupId));
+            if (options?.selectAllRoles)
+                params.set('SelectAllRoles', 'true');
+            if (options?.shiftStatus)
+                params.set('ShiftStatus', options.shiftStatus);
+            if (options?.shiftStatuses) {
+                for (const s of options.shiftStatuses)
+                    params.append('ShiftStatuses', s);
+            }
+            if (options?.selectedLocations) {
+                for (const l of options.selectedLocations)
+                    params.append('SelectedLocations', l);
+            }
+            if (options?.selectedEmployees) {
+                for (const e of options.selectedEmployees)
+                    params.append('SelectedEmployees', e);
+            }
+            if (options?.selectedRoles) {
+                for (const r of options.selectedRoles)
+                    params.append('SelectedRoles', r);
+            }
+            if (options?.unassignedShiftsOnly)
+                params.set('UnassignedShiftsOnly', 'true');
+            if (options?.excludeShiftsOverlappingFromDate)
+                params.set('ExcludeShiftsOverlappingFromDate', 'true');
+            if (options?.includeWarnings)
+                params.set('IncludeWarnings', 'true');
+            try {
+                const allShifts = [];
+                let currentPage = 1;
+                // Paginate using PageSize/CurrentPage until we get fewer than PageSize results
+                while (true) {
+                    params.set('CurrentPage', String(currentPage));
+                    const url = `${this.baseUrl}/business/${this.businessId}/rostershift?${params}`;
+                    const response = await this.fetch(url);
+                    if (!response.ok) {
+                        const errorText = await response.text();
+                        const { message } = parseEHErrorResponse(errorText, response.status);
+                        return { error: { message, statusCode: response.status } };
+                    }
+                    const page = await response.json();
+                    allShifts.push(...page);
+                    if (page.length < DEFAULT_PAGE_SIZE)
+                        break;
+                    currentPage++;
+                }
+                return { shifts: allShifts };
+            }
+            catch (error) {
+                return { error: { message: getErrorMessage(error), statusCode: 0 } };
+            }
+        });
+    }
+    // ============================================================================
+    // Time & Attendance (Kiosk)
+    // ============================================================================
+    /**
+     * Get kiosk staff for time and attendance
+     *
+     * @param kioskId - Kiosk identifier
+     * @param options - Optional query parameters
+     */
+    async getKioskStaff(kioskId, options) {
+        const params = new URLSearchParams();
+        if (options?.restrictCurrentShiftsToCurrentKioskLocation) {
+            params.set('restrictCurrentShiftsToCurrentKioskLocation', 'true');
+        }
+        const queryString = params.toString();
+        const url = queryString
+            ? `${this.baseUrl}/business/${this.businessId}/kiosk/${kioskId}/staff?${queryString}`
+            : `${this.baseUrl}/business/${this.businessId}/kiosk/${kioskId}/staff`;
+        const { data, error } = await this.fetchAndParse(url, async (r) => {
+            return await r.json();
+        });
+        return error ? { error } : { staff: data };
+    }
+    // ============================================================================
+    // Employee Details Report
+    // ============================================================================
+    /**
+     * 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.
+     */
+    async getReportFields() {
+        return this.cached('reportfields', this.cacheTtl.reportFieldsTtl, async () => {
+            const url = `${this.baseUrl}/business/${this.businessId}/report/employeedetails/fields`;
+            const { data, error } = await this.fetchAndParse(url, async (r) => {
+                return await r.json();
+            });
+            return error ? { error } : { fields: data };
+        });
+    }
+    /**
+     * 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.
+     */
+    async getEmployeeDetailsReport(options) {
+        const params = new URLSearchParams();
+        if (options?.selectedColumns) {
+            for (const col of options.selectedColumns) {
+                params.append('selectedColumns', col);
+            }
+        }
+        if (options?.locationId != null)
+            params.set('locationId', String(options.locationId));
+        if (options?.employingEntityId != null)
+            params.set('employingEntityId', String(options.employingEntityId));
+        if (options?.includeActive != null)
+            params.set('includeActive', String(options.includeActive));
+        if (options?.includeInactive != null)
+            params.set('includeInactive', String(options.includeInactive));
+        const queryString = params.toString();
+        const url = queryString
+            ? `${this.baseUrl}/business/${this.businessId}/report/employeedetails?${queryString}`
+            : `${this.baseUrl}/business/${this.businessId}/report/employeedetails`;
+        const { data, error } = await this.fetchAndParse(url, async (r) => {
+            return await r.json();
+        });
+        return error ? { error } : { records: data };
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Employment Hero Payroll Constants
+ */
+/** Supported API regions */
+export type EHRegion = 'au' | 'nz' | 'uk' | 'sg' | 'my';
+/** Base URLs for each region */
+export declare const EH_REGION_URLS: Record<EHRegion, string>;
+/** Default EH Payroll API base URL (AU) */
+export declare const EH_API_BASE: string;

package/dist/constants.js

@@ -0,0 +1,13 @@
+/**
+ * Employment Hero Payroll Constants
+ */
+/** Base URLs for each region */
+export const EH_REGION_URLS = {
+    au: 'https://api.yourpayroll.com.au/api/v2',
+    nz: 'https://apinz.yourpayroll.io/api/v2',
+    uk: 'https://api.yourpayroll.co.uk/api/v2',
+    sg: 'https://apisg.yourpayroll.io/api/v2',
+    my: 'https://apimy.yourpayroll.io/api/v2',
+};
+/** Default EH Payroll API base URL (AU) */
+export const EH_API_BASE = EH_REGION_URLS.au;

package/dist/employee-types.generated.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Auto-generated AU employee type.
+ *
+ * Generated from KeyPay AU Swagger spec. DO NOT EDIT MANUALLY.
+ * Run: npx tsx scripts/generate-types.ts
+ *
+ * Common fields: 69, AU-specific: 70
+ */
+/** Common fields shared across all 5 regions (69 fields) */
+export interface EHEmployeeCommon {
+    anniversaryDate: string | null;
+    automaticallyPayEmployee: string | null;
+    bankAccount1_AccountName: string | null;
+    bankAccount1_AccountNumber: string | null;
+    bankAccount1_AllocatedPercentage: number | null;
+    bankAccount1_FixedAmount: number | null;
+    bankAccount2_AccountName: string | null;
+    bankAccount2_AccountNumber: string | null;
+    bankAccount2_AllocatedPercentage: number | null;
+    bankAccount2_FixedAmount: number | null;
+    bankAccount3_AccountName: string | null;
+    bankAccount3_AccountNumber: string | null;
+    bankAccount3_AllocatedPercentage: number | null;
+    bankAccount3_FixedAmount: number | null;
+    dateCreated: string | null;
+    dateOfBirth: string | null;
+    emailAddress: string | null;
+    emergencyContact1_Address: string | null;
+    emergencyContact1_AlternateContactNumber: string | null;
+    emergencyContact1_ContactNumber: string | null;
+    emergencyContact1_Name: string | null;
+    emergencyContact1_Relationship: string | null;
+    emergencyContact2_Address: string | null;
+    emergencyContact2_AlternateContactNumber: string | null;
+    emergencyContact2_ContactNumber: string | null;
+    emergencyContact2_Name: string | null;
+    emergencyContact2_Relationship: string | null;
+    endDate: string | null;
+    externalId: string | null;
+    firstName: string | null;
+    gender: string | null;
+    homePhone: string | null;
+    hoursPerWeek: number | null;
+    id: number | null;
+    isEnabledForTimesheets: string | null;
+    jobTitle: string | null;
+    leaveAccrualStartDateType: 'EmployeeStartDate' | 'SpecifiedDate' | 'CalendarYear' | 'CategorySpecificDate' | null;
+    leaveTemplate: string | null;
+    leaveYearStart: string | null;
+    locations: string | null;
+    middleName: string | null;
+    mobilePhone: string | null;
+    overrideTemplateRate: string | null;
+    payConditionRuleSet: string | null;
+    payRateTemplate: string | null;
+    paySchedule: string | null;
+    paySlipNotificationType: string | null;
+    postalAddressLine2: string | null;
+    postalCountry: string | null;
+    postalPostCode: string | null;
+    postalStreetAddress: string | null;
+    preferredName: string | null;
+    primaryLocation: string | null;
+    primaryPayCategory: string | null;
+    rate: number | null;
+    rateUnit: string | null;
+    reportingDimensionValues: string | null;
+    residentialAddressLine2: string | null;
+    residentialCountry: string | null;
+    residentialPostCode: string | null;
+    residentialStreetAddress: string | null;
+    rosteringNotificationChoices: string | null;
+    startDate: string | null;
+    status: 'Active' | 'Terminated' | 'Incomplete' | null;
+    surname: string | null;
+    tags: string | null;
+    title: string | null;
+    workPhone: string | null;
+    workTypes: string | null;
+}
+/** AU region employee (70 region-specific fields) */
+export interface EHAuEmployee extends EHEmployeeCommon {
+    australianResident: boolean;
+    automaticallyApplyPublicHolidayNotWorkedEarningsLines: boolean;
+    awardId: number | null;
+    bankAccount1_BSB: string | null;
+    bankAccount2_BSB: string | null;
+    bankAccount3_BSB: string | null;
+    businessAwardPackage: string | null;
+    claimMedicareLevyReduction: boolean;
+    claimTaxFreeThreshold: boolean;
+    closelyHeldEmployee: boolean;
+    closelyHeldReporting: 'PerQuarter' | 'PerPayRun' | null;
+    contractorABN: string | null;
+    dateTaxFileDeclarationReported: string | null;
+    dateTaxFileDeclarationSigned: string | null;
+    disableAutoProgression: boolean;
+    dvlPaySlipDescription: string | null;
+    employingEntityABN: string | null;
+    employingEntityId: string | null;
+    employmentAgreement: string | null;
+    employmentAgreementId: number | null;
+    employmentType: string | null;
+    hasApprovedWorkingHolidayVisa: boolean;
+    hasWithholdingVariation: boolean;
+    hoursPerDay: number | null;
+    includeInPortableLongServiceLeaveReport: boolean;
+    isExemptFromFloodLevy: boolean;
+    isExemptFromPayrollTax: boolean;
+    isSeasonalWorker: boolean;
+    maximumQuarterlySuperContributionsBase: number | null;
+    medicareLevyExemption: string | null;
+    medicareLevyReductionDependentCount: number | null;
+    medicareLevyReductionSpouse: boolean;
+    medicareLevySurchargeWithholdingTier: 'Tier1' | 'Tier2' | 'Tier3' | null;
+    otherTaxOffset: boolean;
+    portableLongServiceLeaveId: string | null;
+    postalAddressIsOverseas: boolean;
+    postalState: string | null;
+    postalSuburb: string | null;
+    previousSurname: string | null;
+    residentialAddressIsOverseas: boolean;
+    residentialState: string | null;
+    residentialSuburb: string | null;
+    seniorsTaxOffset: boolean;
+    singleTouchPayroll: 'CloselyHeld' | 'ForeignEmployment' | 'InboundAssignee' | 'LabourHire' | 'OtherSpecifiedPayments' | null;
+    stslDebt: boolean;
+    superFund1_AllocatedPercentage: number | null;
+    superFund1_EmployerNominatedFund: boolean;
+    superFund1_FixedAmount: number | null;
+    superFund1_FundName: string | null;
+    superFund1_MemberNumber: string | null;
+    superFund1_ProductCode: string | null;
+    superFund2_AllocatedPercentage: number | null;
+    superFund2_EmployerNominatedFund: boolean;
+    superFund2_FixedAmount: number | null;
+    superFund2_FundName: string | null;
+    superFund2_MemberNumber: string | null;
+    superFund2_ProductCode: string | null;
+    superFund3_AllocatedPercentage: number | null;
+    superFund3_EmployerNominatedFund: boolean;
+    superFund3_FixedAmount: number | null;
+    superFund3_FundName: string | null;
+    superFund3_MemberNumber: string | null;
+    superFund3_ProductCode: string | null;
+    superThresholdAmount: number | null;
+    taxCategory: 'Actor_WithTaxFreeThreshold' | 'Actor_NoTaxFreeThreshold' | 'Actor_LimitedPerformancePerWeek' | 'Actor_Promotional' | 'HorticulturalistShearer_WithTaxFreeThreshold' | 'HorticulturalistShearer_ForeignResident' | 'SeniorPensioner_Single' | 'SeniorPensioner_Married' | 'SeniorPensioner_SeparatedCoupleIllness' | 'ATODefined_DeathBeneficiary' | 'ATODefined_DownwardVariation' | 'ATODefined_NonEmployee' | 'DailyCasual' | null;
+    taxFileNumber: string | null;
+    taxVariation: number | null;
+    terminationReason: string | null;
+    workingHolidayVisaCountry: string | null;
+    workingHolidayVisaStartDate: string | null;
+}

package/dist/employee-types.generated.js

@@ -0,0 +1,9 @@
+/**
+ * Auto-generated AU employee type.
+ *
+ * Generated from KeyPay AU Swagger spec. DO NOT EDIT MANUALLY.
+ * Run: npx tsx scripts/generate-types.ts
+ *
+ * Common fields: 69, AU-specific: 70
+ */
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Employment Hero Payroll Error Handling
+ *
+ * EH/KeyPay API returns errors in various formats:
+ * - {"message":"..."} or {"error":"..."}
+ * - Plain text
+ * - HTML error pages (for server errors)
+ */
+/**
+ * Parsed EH error response
+ */
+export interface EHParsedError {
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * Parse EH API error response text into a human-readable message.
+ *
+ * @param errorText - Raw error response text
+ * @param statusCode - HTTP status code
+ * @returns Parsed error with message
+ */
+export declare function parseEHErrorResponse(errorText: string, statusCode: number): EHParsedError;
+/**
+ * Custom error class for EH API errors
+ */
+export declare class EHError extends Error {
+    /** HTTP status code */
+    statusCode: number;
+    /** Raw error response */
+    rawResponse?: string;
+    constructor(message: string, statusCode: number, options?: {
+        rawResponse?: string;
+    });
+    /**
+     * Create an EHError from an API response
+     */
+    static fromResponse(statusCode: number, responseText: string): EHError;
+}

package/dist/errors.js

@@ -0,0 +1,52 @@
+/**
+ * Employment Hero Payroll Error Handling
+ *
+ * EH/KeyPay API returns errors in various formats:
+ * - {"message":"..."} or {"error":"..."}
+ * - Plain text
+ * - HTML error pages (for server errors)
+ */
+/**
+ * Parse EH API error response text into a human-readable message.
+ *
+ * @param errorText - Raw error response text
+ * @param statusCode - HTTP status code
+ * @returns Parsed error with message
+ */
+export function parseEHErrorResponse(errorText, statusCode) {
+    try {
+        const errorJson = JSON.parse(errorText);
+        // Common EH error format
+        if (errorJson.message) {
+            return { message: errorJson.message };
+        }
+        if (errorJson.error) {
+            return { message: errorJson.error };
+        }
+        return { message: `HTTP ${statusCode}` };
+    }
+    catch {
+        // Not JSON, return as-is or fallback
+        return { message: errorText || `HTTP ${statusCode}` };
+    }
+}
+/**
+ * Custom error class for EH API errors
+ */
+export class EHError extends Error {
+    constructor(message, statusCode, options) {
+        super(message);
+        this.name = 'EHError';
+        this.statusCode = statusCode;
+        this.rawResponse = options?.rawResponse;
+    }
+    /**
+     * Create an EHError from an API response
+     */
+    static fromResponse(statusCode, responseText) {
+        const parsed = parseEHErrorResponse(responseText, statusCode);
+        return new EHError(parsed.message, statusCode, {
+            rawResponse: responseText,
+        });
+    }
+}