@markwharton/eh-payroll 1.3.0 → 2.0.0

package/dist/client.d.ts

@@ -6,8 +6,9 @@
  *
  * @see https://api.keypay.com.au/
  */
-import type { EHConfig, EHEmployeeOptions, EHSingleEmployeeOptions, EHStandardHours, EHLocation, EHEmployeeGroup, EHRosterShift, EHRosterShiftOptions, EHKiosk, EHKioskEmployee, EHKioskStaffOptions, EHErrorInfo, EHReportField, EHEmployeeDetailsReportOptions } from './types.js';
+import type { EHConfig, EHEmployeeOptions, EHSingleEmployeeOptions, EHStandardHours, EHLocation, EHEmployeeGroup, EHRosterShift, EHRosterShiftOptions, EHKiosk, EHKioskEmployee, EHKioskStaffOptions, EHReportField, EHEmployeeDetailsReportOptions } from './types.js';
 import type { EHAuEmployee } from './employee-types.generated.js';
+import type { Result } from '@markwharton/api-core';
 /**
  * Employment Hero Payroll API Client
  *
@@ -19,7 +20,7 @@ import type { EHAuEmployee } from './employee-types.generated.js';
  * await client.validateApiKey();
  *
  * // Get employees
- * const { employees } = await client.getEmployees();
+ * const { data: employees } = await client.getEmployees();
  * ```
  */
 export declare class EHClient {
@@ -54,45 +55,27 @@ export declare class EHClient {
     /**
      * Validate the API key by calling GET /user
      */
-    validateApiKey(): Promise<{
-        valid: boolean;
-        error?: string;
-    }>;
+    validateApiKey(): Promise<Result<void>>;
     /**
      * Get all employees (unstructured format)
      */
-    getEmployees(options?: EHEmployeeOptions): Promise<{
-        employees?: EHAuEmployee[];
-        error?: EHErrorInfo;
-    }>;
+    getEmployees(options?: EHEmployeeOptions): Promise<Result<EHAuEmployee[]>>;
     /**
      * Get a single employee by ID
      */
-    getEmployee(employeeId: number, options?: EHSingleEmployeeOptions): Promise<{
-        employee?: EHAuEmployee;
-        error?: EHErrorInfo;
-    }>;
+    getEmployee(employeeId: number, options?: EHSingleEmployeeOptions): Promise<Result<EHAuEmployee>>;
     /**
      * Get standard hours for an employee (includes FTE value)
      */
-    getStandardHours(employeeId: number): Promise<{
-        standardHours?: EHStandardHours;
-        error?: EHErrorInfo;
-    }>;
+    getStandardHours(employeeId: number): Promise<Result<EHStandardHours>>;
     /**
      * Get all business locations
      */
-    getLocations(): Promise<{
-        locations?: EHLocation[];
-        error?: EHErrorInfo;
-    }>;
+    getLocations(): Promise<Result<EHLocation[]>>;
     /**
      * Get all employee groups
      */
-    getEmployeeGroups(): Promise<{
-        employeeGroups?: EHEmployeeGroup[];
-        error?: EHErrorInfo;
-    }>;
+    getEmployeeGroups(): Promise<Result<EHEmployeeGroup[]>>;
     /**
      * Get roster shifts for a date range
      *
@@ -100,45 +83,30 @@ export declare class EHClient {
      * @param toDate - End date (YYYY-MM-DD)
      * @param options - Optional filters
      */
-    getRosterShifts(fromDate: string, toDate: string, options?: EHRosterShiftOptions): Promise<{
-        rosterShifts?: EHRosterShift[];
-        error?: EHErrorInfo;
-    }>;
+    getRosterShifts(fromDate: string, toDate: string, options?: EHRosterShiftOptions): Promise<Result<EHRosterShift[]>>;
     /**
      * Get all kiosks for the business
      */
-    getKiosks(): Promise<{
-        kiosks?: EHKiosk[];
-        error?: EHErrorInfo;
-    }>;
+    getKiosks(): Promise<Result<EHKiosk[]>>;
     /**
      * Get kiosk staff for time and attendance
      *
      * @param kioskId - Kiosk identifier
      * @param options - Optional query parameters
      */
-    getKioskStaff(kioskId: number, options?: EHKioskStaffOptions): Promise<{
-        staff?: EHKioskEmployee[];
-        error?: EHErrorInfo;
-    }>;
+    getKioskStaff(kioskId: number, options?: EHKioskStaffOptions): Promise<Result<EHKioskEmployee[]>>;
     /**
      * 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.
      */
-    getReportFields(): Promise<{
-        fields?: EHReportField[];
-        error?: EHErrorInfo;
-    }>;
+    getReportFields(): Promise<Result<EHReportField[]>>;
     /**
      * 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.
      */
-    getEmployeeDetailsReport(options?: EHEmployeeDetailsReportOptions): Promise<{
-        records?: Record<string, unknown>[];
-        error?: EHErrorInfo;
-    }>;
+    getEmployeeDetailsReport(options?: EHEmployeeDetailsReportOptions): Promise<Result<Record<string, unknown>[]>>;
 }

package/dist/client.js

@@ -10,7 +10,7 @@ import { AU_EMPLOYEE_OPERATIONAL_FIELDS, AU_EMPLOYEE_FIELDS, LOCATION_FIELDS, EM
 import { buildBasicAuthHeader, pickFields } 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 { TTLCache, getErrorMessage, fetchWithRetry, ok, err } from '@markwharton/api-core';
 import { RateLimiter } from './rate-limiter.js';
 /** Default page size for paginated endpoints */
 const DEFAULT_PAGE_SIZE = 100;
@@ -28,7 +28,7 @@ const DEFAULT_PAGE_SIZE = 100;
  * await client.validateApiKey();
  *
  * // Get employees
- * const { employees } = await client.getEmployees();
+ * const { data: employees } = await client.getEmployees();
  * ```
  */
 export class EHClient {
@@ -122,12 +122,12 @@ export class EHClient {
             if (!response.ok) {
                 const errorText = await response.text();
                 const { message } = parseEHErrorResponse(errorText, response.status);
-                return { error: { message, statusCode: response.status } };
+                return err(message, response.status);
             }
-            return { data: await parse(response) };
+            return ok(await parse(response));
         }
         catch (error) {
-            return { error: { message: getErrorMessage(error), statusCode: 0 } };
+            return err(getErrorMessage(error), 0);
         }
     }
     // ============================================================================
@@ -141,15 +141,15 @@ export class EHClient {
         try {
             const response = await this.fetch(url);
             if (response.ok) {
-                return { valid: true };
+                return { ok: true };
             }
             if (response.status === 401 || response.status === 403) {
-                return { valid: false, error: 'Invalid or expired API key' };
+                return err('Invalid or expired API key', response.status);
             }
-            return { valid: false, error: `Unexpected response: HTTP ${response.status}` };
+            return err(`Unexpected response: HTTP ${response.status}`, response.status);
         }
         catch (error) {
-            return { valid: false, error: getErrorMessage(error) || 'Connection failed' };
+            return err(getErrorMessage(error) || 'Connection failed');
         }
     }
     // ============================================================================
@@ -185,7 +185,7 @@ export class EHClient {
                     if (!response.ok) {
                         const errorText = await response.text();
                         const { message } = parseEHErrorResponse(errorText, response.status);
-                        return { error: { message, statusCode: response.status } };
+                        return err(message, response.status);
                     }
                     const page = (await response.json())
                         .map(item => pickFields(item, fields));
@@ -194,10 +194,10 @@ export class EHClient {
                         break;
                     skip += DEFAULT_PAGE_SIZE;
                 }
-                return { employees: allEmployees };
+                return ok(allEmployees);
             }
             catch (error) {
-                return { error: { message: getErrorMessage(error), statusCode: 0 } };
+                return err(getErrorMessage(error), 0);
             }
         });
     }
@@ -209,10 +209,9 @@ export class EHClient {
         const cacheKey = options?.includePii ? `employee:${employeeId}:pii` : `employee:${employeeId}`;
         return this.cached(cacheKey, this.cacheTtl.employeesTtl, async () => {
             const url = `${this.baseUrl}/business/${this.businessId}/employee/unstructured/${employeeId}`;
-            const { data, error } = await this.fetchAndParse(url, async (r) => {
+            return this.fetchAndParse(url, async (r) => {
                 return pickFields(await r.json(), fields);
             });
-            return error ? { error } : { employee: data };
         });
     }
     // ============================================================================
@@ -224,10 +223,9 @@ export class EHClient {
     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 this.fetchAndParse(url, async (r) => {
                 return await r.json();
             }, { description: `Get standard hours for employee ${employeeId}` });
-            return error ? { error } : { standardHours: data };
         });
     }
     // ============================================================================
@@ -251,7 +249,7 @@ export class EHClient {
                     if (!response.ok) {
                         const errorText = await response.text();
                         const { message } = parseEHErrorResponse(errorText, response.status);
-                        return { error: { message, statusCode: response.status } };
+                        return err(message, response.status);
                     }
                     const page = (await response.json())
                         .map(item => pickFields(item, LOCATION_FIELDS));
@@ -260,10 +258,10 @@ export class EHClient {
                         break;
                     skip += DEFAULT_PAGE_SIZE;
                 }
-                return { locations: allLocations };
+                return ok(allLocations);
             }
             catch (error) {
-                return { error: { message: getErrorMessage(error), statusCode: 0 } };
+                return err(getErrorMessage(error), 0);
             }
         });
     }
@@ -288,7 +286,7 @@ export class EHClient {
                     if (!response.ok) {
                         const errorText = await response.text();
                         const { message } = parseEHErrorResponse(errorText, response.status);
-                        return { error: { message, statusCode: response.status } };
+                        return err(message, response.status);
                     }
                     const page = (await response.json())
                         .map(item => pickFields(item, EMPLOYEE_GROUP_FIELDS));
@@ -297,10 +295,10 @@ export class EHClient {
                         break;
                     skip += DEFAULT_PAGE_SIZE;
                 }
-                return { employeeGroups: allGroups };
+                return ok(allGroups);
             }
             catch (error) {
-                return { error: { message: getErrorMessage(error), statusCode: 0 } };
+                return err(getErrorMessage(error), 0);
             }
         });
     }
@@ -392,7 +390,7 @@ export class EHClient {
                     if (!response.ok) {
                         const errorText = await response.text();
                         const { message } = parseEHErrorResponse(errorText, response.status);
-                        return { error: { message, statusCode: response.status } };
+                        return err(message, response.status);
                     }
                     const page = (await response.json())
                         .map(item => pickFields(item, ROSTER_SHIFT_FIELDS));
@@ -401,10 +399,10 @@ export class EHClient {
                         break;
                     currentPage++;
                 }
-                return { rosterShifts: allShifts };
+                return ok(allShifts);
             }
             catch (error) {
-                return { error: { message: getErrorMessage(error), statusCode: 0 } };
+                return err(getErrorMessage(error), 0);
             }
         });
     }
@@ -429,7 +427,7 @@ export class EHClient {
                     if (!response.ok) {
                         const errorText = await response.text();
                         const { message } = parseEHErrorResponse(errorText, response.status);
-                        return { error: { message, statusCode: response.status } };
+                        return err(message, response.status);
                     }
                     const page = (await response.json())
                         .map(item => pickFields(item, KIOSK_FIELDS));
@@ -438,10 +436,10 @@ export class EHClient {
                         break;
                     skip += DEFAULT_PAGE_SIZE;
                 }
-                return { kiosks: allKiosks };
+                return ok(allKiosks);
             }
             catch (error) {
-                return { error: { message: getErrorMessage(error), statusCode: 0 } };
+                return err(getErrorMessage(error), 0);
             }
         });
     }
@@ -464,11 +462,10 @@ export class EHClient {
             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 this.fetchAndParse(url, async (r) => {
                 return (await r.json())
                     .map(item => pickFields(item, KIOSK_EMPLOYEE_FIELDS));
             });
-            return error ? { error } : { staff: data };
         });
     }
     // ============================================================================
@@ -483,10 +480,9 @@ export class EHClient {
     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 this.fetchAndParse(url, async (r) => {
                 return await r.json();
             });
-            return error ? { error } : { fields: data };
         });
     }
     /**
@@ -514,9 +510,8 @@ export class EHClient {
         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 this.fetchAndParse(url, async (r) => {
             return await r.json();
         });
-        return error ? { error } : { records: data };
     }
 }

package/dist/errors.d.ts

@@ -26,10 +26,10 @@ export declare function parseEHErrorResponse(errorText: string, statusCode: numb
  */
 export declare class EHError extends Error {
     /** HTTP status code */
-    statusCode: number;
+    status: number;
     /** Raw error response */
     rawResponse?: string;
-    constructor(message: string, statusCode: number, options?: {
+    constructor(message: string, status: number, options?: {
         rawResponse?: string;
     });
     /**

package/dist/errors.js

@@ -34,10 +34,10 @@ export function parseEHErrorResponse(errorText, statusCode) {
  * Custom error class for EH API errors
  */
 export class EHError extends Error {
-    constructor(message, statusCode, options) {
+    constructor(message, status, options) {
         super(message);
         this.name = 'EHError';
-        this.statusCode = statusCode;
+        this.status = status;
         this.rawResponse = options?.rawResponse;
     }
     /**

package/dist/index.d.ts

@@ -13,19 +13,20 @@
  * await client.validateApiKey();
  *
  * // Get employees
- * const { employees } = await client.getEmployees();
+ * const { data: employees } = await client.getEmployees();
  *
  * // Get roster shifts
- * const { rosterShifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
+ * const { data: rosterShifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
  * ```
  */
 export { EHClient } from './client.js';
-export type { EHConfig, EHCacheConfig, EHRetryConfig, EHEmployee, EHEmployeeOptions, EHSingleEmployeeOptions, EHStandardHours, EHLocation, EHEmployeeGroup, EHRosterShift, EHRosterShiftOptions, EHAttendanceStatus, EHKiosk, EHKioskEmployee, EHKioskStaffOptions, EHReportField, EHEmployeeDetailsReportOptions, EHErrorInfo, } from './types.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 { getErrorMessage } from '@markwharton/api-core';
+export { ok, err, getErrorMessage } from '@markwharton/api-core';
+export type { Result, RetryConfig } 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

@@ -13,10 +13,10 @@
  * await client.validateApiKey();
  *
  * // Get employees
- * const { employees } = await client.getEmployees();
+ * const { data: employees } = await client.getEmployees();
  *
  * // Get roster shifts
- * const { rosterShifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
+ * const { data: rosterShifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
  * ```
  */
 // Main client
@@ -27,7 +27,8 @@ export { AU_EMPLOYEE_OPERATIONAL_FIELDS, AU_EMPLOYEE_PII_FIELDS, AU_EMPLOYEE_FIE
 export { RateLimiter } from './rate-limiter.js';
 // Utilities
 export { buildBasicAuthHeader, pickFields } from './utils.js';
-export { getErrorMessage } from '@markwharton/api-core';
+// Result pattern (re-exported from @markwharton/api-core)
+export { ok, err, getErrorMessage } from '@markwharton/api-core';
 // Constants
 export { EH_API_BASE, EH_REGION_URLS } from './constants.js';
 // Errors

package/dist/types.d.ts

@@ -5,6 +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';
 /**
  * Cache configuration for EHClient
  *
@@ -29,21 +30,8 @@ export interface EHCacheConfig {
     /** TTL for report fields (default: 600000 = 10 min) */
     reportFieldsTtl?: number;
 }
-/**
- * Retry configuration for EHClient
- *
- * Controls automatic retry behavior for transient failures
- * (HTTP 429 Too Many Requests, 503 Service Unavailable).
- * Uses exponential backoff with optional Retry-After header support.
- */
-export interface EHRetryConfig {
-    /** Maximum number of retry attempts (default: 3) */
-    maxRetries?: number;
-    /** Initial delay in milliseconds before first retry (default: 1000) */
-    initialDelayMs?: number;
-    /** Maximum delay cap in milliseconds (default: 10000) */
-    maxDelayMs?: number;
-}
+/** @deprecated Use `RetryConfig` from `@markwharton/api-core` directly. */
+export type EHRetryConfig = RetryConfig;
 /**
  * Employment Hero Payroll configuration for API access
  */
@@ -313,15 +301,6 @@ export interface EHEmployeeDetailsReportOptions {
     /** Include inactive employees (default: false) */
     includeInactive?: boolean;
 }
-/**
- * Structured error information from EH API
- */
-export interface EHErrorInfo {
-    /** Human-readable error message */
-    message: string;
-    /** HTTP status code from the response */
-    statusCode: number;
-}
 /** Whitelisted fields for EHLocation */
 export declare const LOCATION_FIELDS: readonly ["id", "parentId", "name", "externalId", "source", "fullyQualifiedName", "isGlobal", "state", "country"];
 /** Whitelisted fields for EHKiosk */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/eh-payroll",
-  "version": "1.3.0",
+  "version": "2.0.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.0.0"
+    "@markwharton/api-core": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",