@markwharton/eh-payroll 2.1.2 → 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;
     /**

package/dist/client.js

@@ -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.
@@ -197,6 +201,7 @@ export class EHClient {
         if (options?.includePii)
             parts.push('pii');
         const cacheKey = parts.join(':');
+        const persistOpt = options?.includePii ? { persist: false } : undefined;
         return this.cached(cacheKey, this.cacheTtl.employeesTtl, () => {
             const params = new URLSearchParams();
             if (options?.payScheduleId != null)
@@ -208,7 +213,7 @@ export class EHClient {
                 params.set('$skip', String(skip));
                 return `${this.baseUrl}/business/${this.businessId}/employee/unstructured?${params}`;
             }, fields);
-        });
+        }, persistOpt);
     }
     /**
      * Get a single employee by ID
@@ -216,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

package/dist/index.d.ts

@@ -24,8 +24,8 @@ 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 { EHPayrollError, parseEHPayrollErrorResponse } from './errors.js';

package/dist/index.js

@@ -26,7 +26,7 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/eh-payroll",
-  "version": "2.1.2",
+  "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",