@markwharton/eh-payroll 2.0.0 → 2.1.0

package/README.md

@@ -20,65 +20,97 @@ const client = new EHClient({
 });
 
 // Validate credentials
-await client.validateApiKey();
+const validation = await client.validateApiKey();
+if (!validation.ok) throw new Error(validation.error);
 
 // Get all employees
-const { employees } = await client.getEmployees();
+const empResult = await client.getEmployees();
+if (empResult.ok) console.log(empResult.data); // EHAuEmployee[]
 
 // Get employees filtered by location
-const { employees: filtered } = await client.getEmployees({ locationId: 5 });
+const filteredResult = await client.getEmployees({ locationId: 5 });
+if (filteredResult.ok) console.log(filteredResult.data); // EHAuEmployee[]
 
 // Get roster shifts for a date range (auto-paginates)
-const { rosterShifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
+const rosterResult = await client.getRosterShifts('2026-02-03', '2026-02-09');
+if (rosterResult.ok) console.log(rosterResult.data); // EHRosterShift[]
 
 // Get roster shifts with filters
-const { rosterShifts: published } = await client.getRosterShifts('2026-02-03', '2026-02-09', {
+const pubResult = await client.getRosterShifts('2026-02-03', '2026-02-09', {
   employeeId: 42,
   shiftStatus: 'Published',
   selectAllRoles: true
 });
+if (pubResult.ok) console.log(pubResult.data); // EHRosterShift[]
 
 // Get business locations
-const { locations } = await client.getLocations();
+const locResult = await client.getLocations();
+if (locResult.ok) console.log(locResult.data); // EHLocation[]
 
 // List kiosks
-const { kiosks } = await client.getKiosks();
+const kioskResult = await client.getKiosks();
+if (kioskResult.ok) console.log(kioskResult.data); // EHKiosk[]
 
 // Get kiosk staff (time and attendance)
-const { staff } = await client.getKioskStaff(kioskId);
+const staffResult = await client.getKioskStaff(kioskId);
+if (staffResult.ok) console.log(staffResult.data); // EHKioskEmployee[]
 
 // Get employee groups
-const { employeeGroups } = await client.getEmployeeGroups();
+const groupResult = await client.getEmployeeGroups();
+if (groupResult.ok) console.log(groupResult.data); // EHEmployeeGroup[]
 
 // Get standard hours for an employee (includes FTE value)
-const { standardHours } = await client.getStandardHours(employeeId);
+const hoursResult = await client.getStandardHours(employeeId);
+if (hoursResult.ok) console.log(hoursResult.data); // EHStandardHours
 
 // Discover available report columns
-const { fields } = await client.getReportFields();
+const fieldsResult = await client.getReportFields();
+if (fieldsResult.ok) console.log(fieldsResult.data); // EHReportField[]
 
 // Run Employee Details Report with selected columns
-const { records } = await client.getEmployeeDetailsReport({
+const reportResult = await client.getEmployeeDetailsReport({
   selectedColumns: ['FirstName', 'Surname', 'ExternalId']
 });
+if (reportResult.ok) console.log(reportResult.data); // Record<string, unknown>[]
 ```
 
-## API Reference
+## Result Pattern
+
+All methods return `Result<T>` objects rather than throwing exceptions. Always check `ok` before accessing `data`:
+
+```typescript
+interface Result<T> {
+  ok: boolean;
+  data?: T;       // present when ok is true
+  error?: string;  // present when ok is false
+  status?: number; // HTTP status code on error
+}
+```
 
-All methods return `{ data?, error? }` result objects rather than throwing exceptions.
+```typescript
+const result = await client.getEmployees();
+if (!result.ok) {
+  console.error(result.error, result.status);
+  return;
+}
+const employees = result.data;
+```
+
+## API Reference
 
 | Method | Parameters | Returns |
 |--------|-----------|---------|
-| `validateApiKey()` | — | `{ valid, error? }` |
-| `getEmployees(options?)` | `EHEmployeeOptions?` | `{ employees?, error? }` |
-| `getEmployee(employeeId)` | `number` | `{ employee?, error? }` |
-| `getStandardHours(employeeId)` | `number` | `{ standardHours?, error? }` |
-| `getLocations()` | — | `{ locations?, error? }` |
-| `getEmployeeGroups()` | — | `{ employeeGroups?, error? }` |
-| `getRosterShifts(from, to, options?)` | `string, string, EHRosterShiftOptions?` | `{ rosterShifts?, error? }` |
-| `getKiosks()` | — | `{ kiosks?, error? }` |
-| `getKioskStaff(kioskId, options?)` | `number, EHKioskStaffOptions?` | `{ staff?, error? }` |
-| `getReportFields()` | — | `{ fields?, error? }` |
-| `getEmployeeDetailsReport(options?)` | `EHEmployeeDetailsReportOptions?` | `{ records?, error? }` |
+| `validateApiKey()` | — | `Result<void>` |
+| `getEmployees(options?)` | `EHEmployeeOptions?` | `Result<EHAuEmployee[]>` |
+| `getEmployee(employeeId)` | `number` | `Result<EHAuEmployee>` |
+| `getStandardHours(employeeId)` | `number` | `Result<EHStandardHours>` |
+| `getLocations()` | — | `Result<EHLocation[]>` |
+| `getEmployeeGroups()` | — | `Result<EHEmployeeGroup[]>` |
+| `getRosterShifts(from, to, options?)` | `string, string, EHRosterShiftOptions?` | `Result<EHRosterShift[]>` |
+| `getKiosks()` | — | `Result<EHKiosk[]>` |
+| `getKioskStaff(kioskId, options?)` | `number, EHKioskStaffOptions?` | `Result<EHKioskEmployee[]>` |
+| `getReportFields()` | — | `Result<EHReportField[]>` |
+| `getEmployeeDetailsReport(options?)` | `EHEmployeeDetailsReportOptions?` | `Result<Record<string, unknown>[]>` |
 
 ### `getRosterShifts()`
 

package/dist/client.js

@@ -7,11 +7,10 @@
  * @see https://api.keypay.com.au/
  */
 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, pickFields } from './utils.js';
+import { buildBasicAuthHeader } from './utils.js';
 import { parseEHErrorResponse } from './errors.js';
 import { EH_API_BASE, EH_REGION_URLS } from './constants.js';
-import { TTLCache, getErrorMessage, fetchWithRetry, ok, err } from '@markwharton/api-core';
-import { RateLimiter } from './rate-limiter.js';
+import { TTLCache, pickFields, RateLimiter, getErrorMessage, fetchWithRetry, resolveRetryConfig, ok, err } from '@markwharton/api-core';
 /** Default page size for paginated endpoints */
 const DEFAULT_PAGE_SIZE = 100;
 // ============================================================================
@@ -52,13 +51,7 @@ export class EHClient {
             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,
-            };
-        }
+        this.retryConfig = resolveRetryConfig(config.retry);
         // Initialize rate limiter (default: 5 req/s per API spec)
         const rateLimitPerSecond = config.rateLimitPerSecond ?? 5;
         if (rateLimitPerSecond > 0) {
@@ -149,7 +142,7 @@ export class EHClient {
             return err(`Unexpected response: HTTP ${response.status}`, response.status);
         }
         catch (error) {
-            return err(getErrorMessage(error) || 'Connection failed');
+            return err(getErrorMessage(error, 'Connection failed'));
         }
     }
     // ============================================================================

package/dist/errors.d.ts

@@ -1,21 +1,23 @@
 /**
  * Employment Hero Payroll Error Handling
  *
- * EH/KeyPay API returns errors in various formats:
+ * EH/KeyPay API returns errors in standard JSON formats handled by api-core:
  * - {"message":"..."} or {"error":"..."}
  * - Plain text
  * - HTML error pages (for server errors)
  */
+import { ApiError } from '@markwharton/api-core';
+import type { ParsedError } from '@markwharton/api-core';
 /**
  * Parsed EH error response
  */
-export interface EHParsedError {
-    /** Human-readable error message */
-    message: string;
-}
+export type EHParsedError = ParsedError;
 /**
  * Parse EH API error response text into a human-readable message.
  *
+ * Delegates to api-core's parseJsonErrorResponse — EH uses standard
+ * JSON error formats with no API-specific extensions.
+ *
  * @param errorText - Raw error response text
  * @param statusCode - HTTP status code
  * @returns Parsed error with message
@@ -24,11 +26,7 @@ export declare function parseEHErrorResponse(errorText: string, statusCode: numb
 /**
  * Custom error class for EH API errors
  */
-export declare class EHError extends Error {
-    /** HTTP status code */
-    status: number;
-    /** Raw error response */
-    rawResponse?: string;
+export declare class EHError extends ApiError {
     constructor(message: string, status: number, options?: {
         rawResponse?: string;
     });

package/dist/errors.js

@@ -1,44 +1,32 @@
 /**
  * Employment Hero Payroll Error Handling
  *
- * EH/KeyPay API returns errors in various formats:
+ * EH/KeyPay API returns errors in standard JSON formats handled by api-core:
  * - {"message":"..."} or {"error":"..."}
  * - Plain text
  * - HTML error pages (for server errors)
  */
+import { ApiError, parseJsonErrorResponse } from '@markwharton/api-core';
 /**
  * Parse EH API error response text into a human-readable message.
  *
+ * Delegates to api-core's parseJsonErrorResponse — EH uses standard
+ * JSON error formats with no API-specific extensions.
+ *
  * @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}` };
-    }
+    return parseJsonErrorResponse(errorText, statusCode);
 }
 /**
  * Custom error class for EH API errors
  */
-export class EHError extends Error {
+export class EHError extends ApiError {
     constructor(message, status, options) {
-        super(message);
+        super(message, status, options);
         this.name = 'EHError';
-        this.status = status;
-        this.rawResponse = options?.rawResponse;
     }
     /**
      * Create an EHError from an API response

package/dist/index.d.ts

@@ -23,10 +23,9 @@ export { EHClient } from './client.js';
 export type { EHConfig, EHCacheConfig, EHRetryConfig, EHEmployee, EHEmployeeOptions, EHSingleEmployeeOptions, EHStandardHours, EHLocation, EHEmployeeGroup, EHRosterShift, EHRosterShiftOptions, EHAttendanceStatus, EHKiosk, EHKioskEmployee, EHKioskStaffOptions, EHReportField, EHEmployeeDetailsReportOptions, } from './types.js';
 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 { RateLimiter } from './rate-limiter.js';
-export { buildBasicAuthHeader, pickFields } from './utils.js';
-export { ok, err, getErrorMessage } from '@markwharton/api-core';
-export type { Result, RetryConfig } from '@markwharton/api-core';
+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 { EH_API_BASE, EH_REGION_URLS } from './constants.js';
 export type { EHRegion } from './constants.js';
 export { EHError, parseEHErrorResponse } from './errors.js';

package/dist/index.js

@@ -23,12 +23,10 @@
 export { EHClient } from './client.js';
 // Field key constants (whitelists for pickFields)
 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';
-// Rate limiting
-export { RateLimiter } from './rate-limiter.js';
 // Utilities
-export { buildBasicAuthHeader, pickFields } from './utils.js';
-// Result pattern (re-exported from @markwharton/api-core)
-export { ok, err, getErrorMessage } from '@markwharton/api-core';
+export { buildBasicAuthHeader } from './utils.js';
+// Re-exported from @markwharton/api-core
+export { ok, err, getErrorMessage, pickFields, RateLimiter } from '@markwharton/api-core';
 // Constants
 export { EH_API_BASE, EH_REGION_URLS } from './constants.js';
 // Errors

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 } from '@markwharton/api-core';
+import type { RetryConfig, BaseClientConfig } from '@markwharton/api-core';
 /**
  * Cache configuration for EHClient
  *
@@ -35,25 +35,15 @@ export type EHRetryConfig = RetryConfig;
 /**
  * Employment Hero Payroll configuration for API access
  */
-export interface EHConfig {
+export interface EHConfig extends BaseClientConfig {
     /** 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;
 }

package/dist/utils.d.ts

@@ -7,8 +7,3 @@
  * EH API uses the API key as the username with an empty password.
  */
 export declare function buildBasicAuthHeader(apiKey: string): string;
-/**
- * Pick only specified keys from an object.
- * Strips any upstream fields not in the whitelist.
- */
-export declare function pickFields<T>(obj: Record<string, unknown>, keys: readonly string[]): T;

package/dist/utils.js

@@ -12,19 +12,3 @@
 export function buildBasicAuthHeader(apiKey) {
     return 'Basic ' + btoa(apiKey + ':');
 }
-// ============================================================================
-// Field Stripping
-// ============================================================================
-/**
- * Pick only specified keys from an object.
- * Strips any upstream fields not in the whitelist.
- */
-export function pickFields(obj, keys) {
-    const result = {};
-    for (const key of keys) {
-        if (key in obj) {
-            result[key] = obj[key];
-        }
-    }
-    return result;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/eh-payroll",
-  "version": "2.0.0",
+  "version": "2.1.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.1.0"
+    "@markwharton/api-core": "^1.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",