@markwharton/eh-payroll 2.1.1 → 2.2.0

package/README.md

@@ -131,6 +131,7 @@ const client = new EHClient({
   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)
+  cacheInstance: cache,         // Optional: custom cache backend (e.g., LayeredCache)
   retry: {                      // Optional: retry on 429/503
     maxRetries: 3,
     initialDelayMs: 1000,
@@ -139,7 +140,7 @@ const client = new EHClient({
 });
 ```
 
-`EHConfig` extends `ClientConfig` from api-core, which provides the `baseUrl`, `onRequest`, and `retry` fields. `apiKey`, `businessId`, `region`, `cache`, and `rateLimitPerSecond` are EH-specific.
+`EHConfig` extends `ClientConfig` from api-core, which provides the `baseUrl`, `onRequest`, `retry`, and `cacheInstance` fields. `apiKey`, `businessId`, `region`, `cache`, and `rateLimitPerSecond` are EH-specific. Pass `cacheInstance` to use a custom cache backend (e.g., `LayeredCache` with persistent stores); otherwise `cache: {}` creates an in-memory `TTLCache`. PII data (`includePii: true`) automatically skips persistent stores.
 
 ### Cache TTLs
 
@@ -154,6 +155,8 @@ const client = new EHClient({
 | Kiosk staff | 1 min |
 | Report fields | 10 min |
 
+Failed API results (`ok: false`) are never cached — transient errors won't persist for the full TTL. See the [root README Cache System section](../../README.md#cache-system) for the full cache architecture (layered stores, PII handling, request coalescing).
+
 ### 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). The `RateLimiter` class is provided by api-core and operates per-instance (see Known Limitations in the root README).

package/dist/client.d.ts

@@ -35,6 +35,8 @@ export declare class EHClient {
     constructor(config: EHConfig);
     /**
      * Route through cache if enabled, otherwise call factory directly.
+     * Failed Results (ok === false) are never cached — transient errors
+     * shouldn't persist for the full TTL.
      */
     private cached;
     /**
@@ -52,6 +54,18 @@ export declare class EHClient {
      * Fetch a URL and parse the response, with standardized error handling.
      */
     private fetchAndParse;
+    /**
+     * Fetch all pages of a paginated endpoint.
+     *
+     * Payroll API pagination uses either OData ($skip/$top) or PascalCase
+     * (CurrentPage/PageSize). The caller provides a buildUrl callback that
+     * receives the current skip offset and returns the full URL with
+     * pagination parameters set.
+     *
+     * Consumer always receives the complete array — pageSize controls
+     * the internal batch size (items per API call).
+     */
+    private fetchPaginated;
     /**
      * Validate the API key by calling GET /user
      */

package/dist/client.js

@@ -8,9 +8,9 @@
  */
 import { AU_EMPLOYEE_OPERATIONAL_FIELDS, AU_EMPLOYEE_FIELDS, LOCATION_FIELDS, EMPLOYEE_GROUP_FIELDS, ROSTER_SHIFT_FIELDS, KIOSK_FIELDS, KIOSK_EMPLOYEE_FIELDS, } from './types.js';
 import { buildBasicAuthHeader } from './utils.js';
-import { parseEHErrorResponse } from './errors.js';
+import { parseEHPayrollErrorResponse } from './errors.js';
 import { EH_API_BASE, EH_REGION_URLS } from './constants.js';
-import { TTLCache, pickFields, RateLimiter, getErrorMessage, fetchWithRetry, resolveRetryConfig, ok, err } from '@markwharton/api-core';
+import { TTLCache, pickFields, RateLimiter, getErrorMessage, fetchWithRetry, resolveRetryConfig, ok, okVoid, err } from '@markwharton/api-core';
 /** Default page size for paginated endpoints */
 const DEFAULT_PAGE_SIZE = 100;
 // ============================================================================
@@ -37,8 +37,8 @@ export class EHClient {
         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();
+        if (config.cache || config.cacheInstance) {
+            this.cache = config.cacheInstance ?? new TTLCache();
         }
         this.cacheTtl = {
             employeesTtl: config.cache?.employeesTtl ?? 300000,
@@ -60,12 +60,16 @@ export class EHClient {
     }
     /**
      * Route through cache if enabled, otherwise call factory directly.
+     * Failed Results (ok === false) are never cached — transient errors
+     * shouldn't persist for the full TTL.
      */
-    async cached(key, ttlMs, factory) {
-        if (this.cache) {
-            return this.cache.get(key, ttlMs, factory);
-        }
-        return factory();
+    async cached(key, ttlMs, factory, options) {
+        if (!this.cache)
+            return factory();
+        return this.cache.get(key, ttlMs, factory, {
+            ...options,
+            shouldCache: (data) => data.ok !== false,
+        });
     }
     /**
      * Clear all cached API responses.
@@ -114,7 +118,7 @@ export class EHClient {
             const response = await this.fetch(url, fetchOptions);
             if (!response.ok) {
                 const errorText = await response.text();
-                const { message } = parseEHErrorResponse(errorText, response.status);
+                const { message } = parseEHPayrollErrorResponse(errorText, response.status);
                 return err(message, response.status);
             }
             return ok(await parse(response));
@@ -123,6 +127,42 @@ export class EHClient {
             return err(getErrorMessage(error), 0);
         }
     }
+    /**
+     * Fetch all pages of a paginated endpoint.
+     *
+     * Payroll API pagination uses either OData ($skip/$top) or PascalCase
+     * (CurrentPage/PageSize). The caller provides a buildUrl callback that
+     * receives the current skip offset and returns the full URL with
+     * pagination parameters set.
+     *
+     * Consumer always receives the complete array — pageSize controls
+     * the internal batch size (items per API call).
+     */
+    async fetchPaginated(buildUrl, fields, pageSize = DEFAULT_PAGE_SIZE) {
+        try {
+            const allItems = [];
+            let skip = 0;
+            while (true) {
+                const url = buildUrl(skip);
+                const response = await this.fetch(url);
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    const { message } = parseEHPayrollErrorResponse(errorText, response.status);
+                    return err(message, response.status);
+                }
+                const page = (await response.json())
+                    .map(item => pickFields(item, fields));
+                allItems.push(...page);
+                if (page.length < pageSize)
+                    break;
+                skip += pageSize;
+            }
+            return ok(allItems);
+        }
+        catch (error) {
+            return err(getErrorMessage(error), 0);
+        }
+    }
     // ============================================================================
     // Validation
     // ============================================================================
@@ -134,7 +174,7 @@ export class EHClient {
         try {
             const response = await this.fetch(url);
             if (response.ok) {
-                return { ok: true };
+                return okVoid();
             }
             if (response.status === 401 || response.status === 403) {
                 return err('Invalid or expired API key', response.status);
@@ -161,38 +201,19 @@ export class EHClient {
         if (options?.includePii)
             parts.push('pii');
         const cacheKey = parts.join(':');
-        return this.cached(cacheKey, this.cacheTtl.employeesTtl, async () => {
+        const persistOpt = options?.includePii ? { persist: false } : undefined;
+        return this.cached(cacheKey, this.cacheTtl.employeesTtl, () => {
             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));
             params.set('$top', String(DEFAULT_PAGE_SIZE));
-            try {
-                const allEmployees = [];
-                let skip = 0;
-                while (true) {
-                    params.set('$skip', String(skip));
-                    const url = `${this.baseUrl}/business/${this.businessId}/employee/unstructured?${params}`;
-                    const response = await this.fetch(url);
-                    if (!response.ok) {
-                        const errorText = await response.text();
-                        const { message } = parseEHErrorResponse(errorText, response.status);
-                        return err(message, response.status);
-                    }
-                    const page = (await response.json())
-                        .map(item => pickFields(item, fields));
-                    allEmployees.push(...page);
-                    if (page.length < DEFAULT_PAGE_SIZE)
-                        break;
-                    skip += DEFAULT_PAGE_SIZE;
-                }
-                return ok(allEmployees);
-            }
-            catch (error) {
-                return err(getErrorMessage(error), 0);
-            }
-        });
+            return this.fetchPaginated((skip) => {
+                params.set('$skip', String(skip));
+                return `${this.baseUrl}/business/${this.businessId}/employee/unstructured?${params}`;
+            }, fields);
+        }, persistOpt);
     }
     /**
      * Get a single employee by ID
@@ -200,12 +221,13 @@ export class EHClient {
     async getEmployee(employeeId, options) {
         const fields = options?.includePii ? AU_EMPLOYEE_FIELDS : AU_EMPLOYEE_OPERATIONAL_FIELDS;
         const cacheKey = options?.includePii ? `employee:${employeeId}:pii` : `employee:${employeeId}`;
+        const persistOpt = options?.includePii ? { persist: false } : undefined;
         return this.cached(cacheKey, this.cacheTtl.employeesTtl, async () => {
             const url = `${this.baseUrl}/business/${this.businessId}/employee/unstructured/${employeeId}`;
             return this.fetchAndParse(url, async (r) => {
                 return pickFields(await r.json(), fields);
             });
-        });
+        }, persistOpt);
     }
     // ============================================================================
     // Standard Hours
@@ -228,34 +250,12 @@ export class EHClient {
      * Get all business locations
      */
     async getLocations() {
-        return this.cached('locations', this.cacheTtl.locationsTtl, async () => {
-            const params = new URLSearchParams({
-                '$top': String(DEFAULT_PAGE_SIZE),
-            });
-            try {
-                const allLocations = [];
-                let skip = 0;
-                while (true) {
-                    params.set('$skip', String(skip));
-                    const url = `${this.baseUrl}/business/${this.businessId}/location?${params}`;
-                    const response = await this.fetch(url);
-                    if (!response.ok) {
-                        const errorText = await response.text();
-                        const { message } = parseEHErrorResponse(errorText, response.status);
-                        return err(message, response.status);
-                    }
-                    const page = (await response.json())
-                        .map(item => pickFields(item, LOCATION_FIELDS));
-                    allLocations.push(...page);
-                    if (page.length < DEFAULT_PAGE_SIZE)
-                        break;
-                    skip += DEFAULT_PAGE_SIZE;
-                }
-                return ok(allLocations);
-            }
-            catch (error) {
-                return err(getErrorMessage(error), 0);
-            }
+        return this.cached('locations', this.cacheTtl.locationsTtl, () => {
+            const params = new URLSearchParams({ '$top': String(DEFAULT_PAGE_SIZE) });
+            return this.fetchPaginated((skip) => {
+                params.set('$skip', String(skip));
+                return `${this.baseUrl}/business/${this.businessId}/location?${params}`;
+            }, LOCATION_FIELDS);
         });
     }
     // ============================================================================
@@ -265,34 +265,12 @@ export class EHClient {
      * Get all employee groups
      */
     async getEmployeeGroups() {
-        return this.cached('employeeGroups', this.cacheTtl.groupsTtl, async () => {
-            const params = new URLSearchParams({
-                '$top': String(DEFAULT_PAGE_SIZE),
-            });
-            try {
-                const allGroups = [];
-                let skip = 0;
-                while (true) {
-                    params.set('$skip', String(skip));
-                    const url = `${this.baseUrl}/business/${this.businessId}/employeegroup?${params}`;
-                    const response = await this.fetch(url);
-                    if (!response.ok) {
-                        const errorText = await response.text();
-                        const { message } = parseEHErrorResponse(errorText, response.status);
-                        return err(message, response.status);
-                    }
-                    const page = (await response.json())
-                        .map(item => pickFields(item, EMPLOYEE_GROUP_FIELDS));
-                    allGroups.push(...page);
-                    if (page.length < DEFAULT_PAGE_SIZE)
-                        break;
-                    skip += DEFAULT_PAGE_SIZE;
-                }
-                return ok(allGroups);
-            }
-            catch (error) {
-                return err(getErrorMessage(error), 0);
-            }
+        return this.cached('employeegroups', this.cacheTtl.groupsTtl, () => {
+            const params = new URLSearchParams({ '$top': String(DEFAULT_PAGE_SIZE) });
+            return this.fetchPaginated((skip) => {
+                params.set('$skip', String(skip));
+                return `${this.baseUrl}/business/${this.businessId}/employeegroup?${params}`;
+            }, EMPLOYEE_GROUP_FIELDS);
         });
     }
     // ============================================================================
@@ -332,7 +310,7 @@ export class EHClient {
         if (options?.includeWarnings)
             parts.push('iw');
         const cacheKey = parts.join(':');
-        return this.cached(cacheKey, this.cacheTtl.rosterShiftsTtl, async () => {
+        return this.cached(cacheKey, this.cacheTtl.rosterShiftsTtl, () => {
             // 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({
@@ -372,31 +350,10 @@ export class EHClient {
                 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 err(message, response.status);
-                    }
-                    const page = (await response.json())
-                        .map(item => pickFields(item, ROSTER_SHIFT_FIELDS));
-                    allShifts.push(...page);
-                    if (page.length < DEFAULT_PAGE_SIZE)
-                        break;
-                    currentPage++;
-                }
-                return ok(allShifts);
-            }
-            catch (error) {
-                return err(getErrorMessage(error), 0);
-            }
+            return this.fetchPaginated((skip) => {
+                params.set('CurrentPage', String(skip / DEFAULT_PAGE_SIZE + 1));
+                return `${this.baseUrl}/business/${this.businessId}/rostershift?${params}`;
+            }, ROSTER_SHIFT_FIELDS);
         });
     }
     // ============================================================================
@@ -406,34 +363,12 @@ export class EHClient {
      * Get all kiosks for the business
      */
     async getKiosks() {
-        return this.cached('kiosks', this.cacheTtl.kiosksTtl, async () => {
-            const params = new URLSearchParams({
-                '$top': String(DEFAULT_PAGE_SIZE),
-            });
-            try {
-                const allKiosks = [];
-                let skip = 0;
-                while (true) {
-                    params.set('$skip', String(skip));
-                    const url = `${this.baseUrl}/business/${this.businessId}/kiosk?${params}`;
-                    const response = await this.fetch(url);
-                    if (!response.ok) {
-                        const errorText = await response.text();
-                        const { message } = parseEHErrorResponse(errorText, response.status);
-                        return err(message, response.status);
-                    }
-                    const page = (await response.json())
-                        .map(item => pickFields(item, KIOSK_FIELDS));
-                    allKiosks.push(...page);
-                    if (page.length < DEFAULT_PAGE_SIZE)
-                        break;
-                    skip += DEFAULT_PAGE_SIZE;
-                }
-                return ok(allKiosks);
-            }
-            catch (error) {
-                return err(getErrorMessage(error), 0);
-            }
+        return this.cached('kiosks', this.cacheTtl.kiosksTtl, () => {
+            const params = new URLSearchParams({ '$top': String(DEFAULT_PAGE_SIZE) });
+            return this.fetchPaginated((skip) => {
+                params.set('$skip', String(skip));
+                return `${this.baseUrl}/business/${this.businessId}/kiosk?${params}`;
+            }, KIOSK_FIELDS);
         });
     }
     /**

package/dist/errors.d.ts

@@ -11,7 +11,7 @@ import type { ParsedError } from '@markwharton/api-core';
 /**
  * Parsed EH error response
  */
-export type EHParsedError = ParsedError;
+export type EHPayrollParsedError = ParsedError;
 /**
  * Parse EH API error response text into a human-readable message.
  *
@@ -19,19 +19,19 @@ export type EHParsedError = ParsedError;
  * JSON error formats with no API-specific extensions.
  *
  * @param errorText - Raw error response text
- * @param statusCode - HTTP status code
+ * @param status - HTTP status code
  * @returns Parsed error with message
  */
-export declare function parseEHErrorResponse(errorText: string, statusCode: number): EHParsedError;
+export declare function parseEHPayrollErrorResponse(errorText: string, status: number): EHPayrollParsedError;
 /**
  * Custom error class for EH API errors
  */
-export declare class EHError extends ApiError {
+export declare class EHPayrollError extends ApiError {
     constructor(message: string, status: number, options?: {
         rawResponse?: string;
     });
     /**
-     * Create an EHError from an API response
+     * Create an EHPayrollError from an API response
      */
-    static fromResponse(statusCode: number, responseText: string): EHError;
+    static fromResponse(status: number, responseText: string): EHPayrollError;
 }

package/dist/errors.js

@@ -14,26 +14,26 @@ import { ApiError, parseJsonErrorResponse } from '@markwharton/api-core';
  * JSON error formats with no API-specific extensions.
  *
  * @param errorText - Raw error response text
- * @param statusCode - HTTP status code
+ * @param status - HTTP status code
  * @returns Parsed error with message
  */
-export function parseEHErrorResponse(errorText, statusCode) {
-    return parseJsonErrorResponse(errorText, statusCode);
+export function parseEHPayrollErrorResponse(errorText, status) {
+    return parseJsonErrorResponse(errorText, status);
 }
 /**
  * Custom error class for EH API errors
  */
-export class EHError extends ApiError {
+export class EHPayrollError extends ApiError {
     constructor(message, status, options) {
         super(message, status, options);
-        this.name = 'EHError';
+        this.name = 'EHPayrollError';
     }
     /**
-     * Create an EHError from an API response
+     * Create an EHPayrollError from an API response
      */
-    static fromResponse(statusCode, responseText) {
-        const parsed = parseEHErrorResponse(responseText, statusCode);
-        return new EHError(parsed.message, statusCode, {
+    static fromResponse(status, responseText) {
+        const parsed = parseEHPayrollErrorResponse(responseText, status);
+        return new EHPayrollError(parsed.message, status, {
             rawResponse: responseText,
         });
     }

package/dist/index.d.ts

@@ -24,9 +24,9 @@ export type { EHConfig, EHCacheConfig, EHRetryConfig, EHEmployee, EHEmployeeOpti
 export { AU_EMPLOYEE_OPERATIONAL_FIELDS, AU_EMPLOYEE_PII_FIELDS, AU_EMPLOYEE_FIELDS, LOCATION_FIELDS, EMPLOYEE_GROUP_FIELDS, ROSTER_SHIFT_FIELDS, KIOSK_FIELDS, KIOSK_EMPLOYEE_FIELDS, } from './types.js';
 export type { EHAuEmployee } from './employee-types.generated.js';
 export { buildBasicAuthHeader } from './utils.js';
-export { ok, err, getErrorMessage, pickFields, RateLimiter } from '@markwharton/api-core';
-export type { Result, RetryConfig, OnRequestCallback, ClientConfig } from '@markwharton/api-core';
+export { ok, err, getErrorMessage, pickFields, RateLimiter, TTLCache, MemoryCacheStore, LayeredCache } from '@markwharton/api-core';
+export type { Result, RetryConfig, OnRequestCallback, ClientConfig, Cache, CacheStore, CacheGetOptions } 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';
+export { EHPayrollError, parseEHPayrollErrorResponse } from './errors.js';
+export type { EHPayrollParsedError } from './errors.js';

package/dist/index.js

@@ -26,8 +26,8 @@ export { AU_EMPLOYEE_OPERATIONAL_FIELDS, AU_EMPLOYEE_PII_FIELDS, AU_EMPLOYEE_FIE
 // Utilities
 export { buildBasicAuthHeader } from './utils.js';
 // Re-exported from @markwharton/api-core
-export { ok, err, getErrorMessage, pickFields, RateLimiter } from '@markwharton/api-core';
+export { ok, err, getErrorMessage, pickFields, RateLimiter, TTLCache, MemoryCacheStore, LayeredCache } from '@markwharton/api-core';
 // Constants
 export { EH_API_BASE, EH_REGION_URLS } from './constants.js';
 // Errors
-export { EHError, parseEHErrorResponse } from './errors.js';
+export { EHPayrollError, parseEHPayrollErrorResponse } from './errors.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/eh-payroll",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Employment Hero Payroll API client",
   "type": "module",
   "main": "dist/index.js",
@@ -16,7 +16,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@markwharton/api-core": "^1.2.0"
+    "@markwharton/api-core": "^1.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",