@markwharton/eh-payroll 2.1.0 → 2.1.2

package/README.md

@@ -139,6 +139,8 @@ 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.
+
 ### Cache TTLs
 
 | Cache Key | Default TTL |
@@ -154,7 +156,7 @@ const client = new EHClient({
 
 ### 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 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).
 
 ### Retry
 

package/dist/client.d.ts

@@ -52,6 +52,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;
 // ============================================================================
@@ -114,7 +114,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 +123,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 +170,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,37 +197,17 @@ export class EHClient {
         if (options?.includePii)
             parts.push('pii');
         const cacheKey = parts.join(':');
-        return this.cached(cacheKey, this.cacheTtl.employeesTtl, async () => {
+        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);
         });
     }
     /**
@@ -228,34 +244,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 +259,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 +304,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 +344,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 +357,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

@@ -25,8 +25,8 @@ export { AU_EMPLOYEE_OPERATIONAL_FIELDS, AU_EMPLOYEE_PII_FIELDS, AU_EMPLOYEE_FIE
 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, BaseClientConfig } from '@markwharton/api-core';
+export type { Result, RetryConfig, OnRequestCallback, ClientConfig } 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

@@ -30,4 +30,4 @@ export { ok, err, getErrorMessage, pickFields, RateLimiter } from '@markwharton/
 // 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/dist/types.d.ts

@@ -5,7 +5,7 @@
  * Based on the API reference and KeyPay .NET SDK models.
  */
 import type { EHRegion } from './constants.js';
-import type { RetryConfig, BaseClientConfig } from '@markwharton/api-core';
+import type { RetryConfig, ClientConfig } from '@markwharton/api-core';
 /**
  * Cache configuration for EHClient
  *
@@ -35,7 +35,7 @@ export type EHRetryConfig = RetryConfig;
 /**
  * Employment Hero Payroll configuration for API access
  */
-export interface EHConfig extends BaseClientConfig {
+export interface EHConfig extends ClientConfig {
     /** API key for authentication (used as Basic Auth username) */
     apiKey: string;
     /** Business ID to operate on */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/eh-payroll",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Employment Hero Payroll API client",
   "type": "module",
   "main": "dist/index.js",