@markwharton/eh-payroll 2.2.0 → 2.3.0

package/README.md

@@ -43,6 +43,14 @@ const pubResult = await client.getRosterShifts('2026-02-03', '2026-02-09', {
 });
 if (pubResult.ok) console.log(pubResult.data); // EHRosterShift[]
 
+// Get leave requests for a date range (all filters server-side)
+const leaveResult = await client.getLeaveRequests({
+  fromDate: '2026-01-01',
+  toDate: '2026-03-31',
+  status: 'Approved',
+});
+if (leaveResult.ok) console.log(leaveResult.data); // EHLeaveRequest[]
+
 // Get business locations
 const locResult = await client.getLocations();
 if (locResult.ok) console.log(locResult.data); // EHLocation[]
@@ -110,15 +118,35 @@ const employees = result.data;
 | `getKiosks()` | — | `Result<EHKiosk[]>` |
 | `getKioskStaff(kioskId, options?)` | `number, EHKioskStaffOptions?` | `Result<EHKioskEmployee[]>` |
 | `getReportFields()` | — | `Result<EHReportField[]>` |
+| `getLeaveRequests(options?)` | `EHLeaveRequestOptions?` | `Result<EHLeaveRequest[]>` |
 | `getEmployeeDetailsReport(options?)` | `EHEmployeeDetailsReportOptions?` | `Result<Record<string, unknown>[]>` |
 
+### `getLeaveRequests()`
+
+Returns leave requests with all filters applied server-side. Unlike paginated endpoints, this returns a flat array.
+
+**`EHLeaveRequestOptions`:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `fromDate` | `string` | Start date filter (YYYY-MM-DD) |
+| `toDate` | `string` | End date filter (YYYY-MM-DD) |
+| `status` | `EHLeaveRequestStatus` | `'Approved'`, `'Pending'`, `'Rejected'`, or `'Cancelled'` |
+| `employeeId` | `number` | Filter by employee ID |
+| `leaveCategoryId` | `number` | Filter by leave category ID |
+| `locationId` | `number` | Filter by location ID |
+
+### `getEmployeeDetailsReport()`
+
+Returns all employees with the requested columns in a single API call. The response is dynamic — field keys depend on `selectedColumns`. Results are cached with `employeeDetailsReportTtl` (default: 2 min).
+
 ### `getRosterShifts()`
 
 Automatically paginates through all results (100 per page). Returns the complete set of roster shifts for the requested date range. All filter options are applied server-side, reducing the number of results and pages fetched.
 
 ### Query Parameter Casing
 
-The [KeyPay Swagger spec](https://api.keypay.com.au/swagger-au.json) uses inconsistent query parameter casing across endpoints. Roster shifts use PascalCase (`EmployeeId`, `ShiftStatus`), while all other endpoints use camelCase (`selectedColumns`, `filter.locationId`). The library accepts camelCase options throughout and converts to PascalCase for roster shifts internally.
+The [KeyPay Swagger spec](https://api.keypay.com.au/swagger-au.json) uses inconsistent query parameter casing across endpoints. Roster shifts and leave requests use PascalCase (`EmployeeId`, `ShiftStatus`, `FromDate`), while other endpoints use camelCase (`selectedColumns`, `filter.locationId`). The library accepts camelCase options throughout and converts to PascalCase internally where needed.
 
 ## Configuration
 
@@ -151,9 +179,11 @@ const client = new EHClient({
 | Employee groups | 5 min |
 | Standard hours | 5 min |
 | Roster shifts | 2 min |
+| Leave requests | 2 min |
 | Kiosks | 5 min |
 | Kiosk staff | 1 min |
 | Report fields | 10 min |
+| Employee details report | 2 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).
 

package/dist/client.d.ts

@@ -6,7 +6,7 @@
  *
  * @see https://api.keypay.com.au/
  */
-import type { EHConfig, EHEmployeeOptions, EHSingleEmployeeOptions, EHStandardHours, EHLocation, EHEmployeeGroup, EHRosterShift, EHRosterShiftOptions, EHKiosk, EHKioskEmployee, EHKioskStaffOptions, EHReportField, EHEmployeeDetailsReportOptions } from './types.js';
+import type { EHConfig, EHLeaveRequest, EHLeaveRequestOptions, 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';
 /**
@@ -43,6 +43,10 @@ export declare class EHClient {
      * Clear all cached API responses.
      */
     clearCache(): void;
+    /**
+     * Build a URL for a business-scoped endpoint.
+     */
+    private businessUrl;
     /**
      * Make an authenticated request to the EH API
      *
@@ -70,6 +74,15 @@ export declare class EHClient {
      * Validate the API key by calling GET /user
      */
     validateApiKey(): Promise<Result<void>>;
+    /**
+     * Get leave requests (server-side filtering)
+     *
+     * All filter options are passed as query parameters to the API.
+     * The endpoint returns a flat array (not paginated).
+     *
+     * @see https://api.keypay.com.au/australia/reference/leave-requests/au-business-hours-leave-request--list-leave-requests.html
+     */
+    getLeaveRequests(options?: EHLeaveRequestOptions): Promise<Result<EHLeaveRequest[]>>;
     /**
      * Get all employees (unstructured format)
      */

package/dist/client.js

@@ -6,7 +6,7 @@
  *
  * @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 { AU_EMPLOYEE_OPERATIONAL_FIELDS, AU_EMPLOYEE_FIELDS, LEAVE_REQUEST_FIELDS, LOCATION_FIELDS, EMPLOYEE_GROUP_FIELDS, ROSTER_SHIFT_FIELDS, KIOSK_FIELDS, KIOSK_EMPLOYEE_FIELDS, } from './types.js';
 import { buildBasicAuthHeader } from './utils.js';
 import { parseEHPayrollErrorResponse } from './errors.js';
 import { EH_API_BASE, EH_REGION_URLS } from './constants.js';
@@ -42,6 +42,7 @@ export class EHClient {
         }
         this.cacheTtl = {
             employeesTtl: config.cache?.employeesTtl ?? 300000,
+            leaveRequestsTtl: config.cache?.leaveRequestsTtl ?? 120000,
             locationsTtl: config.cache?.locationsTtl ?? 300000,
             groupsTtl: config.cache?.groupsTtl ?? 300000,
             standardHoursTtl: config.cache?.standardHoursTtl ?? 300000,
@@ -49,6 +50,7 @@ export class EHClient {
             kiosksTtl: config.cache?.kiosksTtl ?? 300000,
             kioskStaffTtl: config.cache?.kioskStaffTtl ?? 60000,
             reportFieldsTtl: config.cache?.reportFieldsTtl ?? 600000,
+            employeeDetailsReportTtl: config.cache?.employeeDetailsReportTtl ?? 120000,
         };
         // Initialize retry config with defaults if provided
         this.retryConfig = resolveRetryConfig(config.retry);
@@ -77,6 +79,14 @@ export class EHClient {
     clearCache() {
         this.cache?.clear();
     }
+    /**
+     * Build a URL for a business-scoped endpoint.
+     */
+    businessUrl(path, params) {
+        const base = `${this.baseUrl}/business/${this.businessId}/${path}`;
+        const qs = params?.toString();
+        return qs ? `${base}?${qs}` : base;
+    }
     /**
      * Make an authenticated request to the EH API
      *
@@ -186,6 +196,53 @@ export class EHClient {
         }
     }
     // ============================================================================
+    // Leave Requests
+    // ============================================================================
+    /**
+     * Get leave requests (server-side filtering)
+     *
+     * All filter options are passed as query parameters to the API.
+     * The endpoint returns a flat array (not paginated).
+     *
+     * @see https://api.keypay.com.au/australia/reference/leave-requests/au-business-hours-leave-request--list-leave-requests.html
+     */
+    async getLeaveRequests(options) {
+        const parts = ['leaverequests'];
+        if (options?.fromDate)
+            parts.push(`from:${options.fromDate}`);
+        if (options?.toDate)
+            parts.push(`to:${options.toDate}`);
+        if (options?.status)
+            parts.push(`s:${options.status}`);
+        if (options?.employeeId != null)
+            parts.push(`eid:${options.employeeId}`);
+        if (options?.leaveCategoryId != null)
+            parts.push(`lcid:${options.leaveCategoryId}`);
+        if (options?.locationId != null)
+            parts.push(`lid:${options.locationId}`);
+        const cacheKey = parts.join(':');
+        return this.cached(cacheKey, this.cacheTtl.leaveRequestsTtl, async () => {
+            const params = new URLSearchParams();
+            if (options?.fromDate)
+                params.set('FromDate', options.fromDate);
+            if (options?.toDate)
+                params.set('ToDate', options.toDate);
+            if (options?.status)
+                params.set('Status', options.status);
+            if (options?.employeeId != null)
+                params.set('EmployeeId', String(options.employeeId));
+            if (options?.leaveCategoryId != null)
+                params.set('LeaveCategoryId', String(options.leaveCategoryId));
+            if (options?.locationId != null)
+                params.set('LocationId', String(options.locationId));
+            const url = this.businessUrl('leaverequest', params);
+            return this.fetchAndParse(url, async (r) => {
+                return (await r.json())
+                    .map(item => pickFields(item, LEAVE_REQUEST_FIELDS));
+            });
+        });
+    }
+    // ============================================================================
     // Employees
     // ============================================================================
     /**
@@ -386,10 +443,7 @@ export class EHClient {
             if (options?.restrictCurrentShiftsToCurrentKioskLocation) {
                 params.set('restrictCurrentShiftsToCurrentKioskLocation', 'true');
             }
-            const queryString = params.toString();
-            const url = queryString
-                ? `${this.baseUrl}/business/${this.businessId}/kiosk/${kioskId}/staff?${queryString}`
-                : `${this.baseUrl}/business/${this.businessId}/kiosk/${kioskId}/staff`;
+            const url = this.businessUrl(`kiosk/${kioskId}/staff`, params);
             return this.fetchAndParse(url, async (r) => {
                 return (await r.json())
                     .map(item => pickFields(item, KIOSK_EMPLOYEE_FIELDS));
@@ -420,26 +474,37 @@ export class EHClient {
      * The response is dynamic (JObject[]) — field keys depend on selectedColumns.
      */
     async getEmployeeDetailsReport(options) {
-        const params = new URLSearchParams();
-        if (options?.selectedColumns) {
-            for (const col of options.selectedColumns) {
-                params.append('selectedColumns', col);
-            }
-        }
+        const parts = ['report:employeedetails'];
+        if (options?.selectedColumns?.length)
+            parts.push(`cols:${options.selectedColumns.join(',')}`);
         if (options?.locationId != null)
-            params.set('locationId', String(options.locationId));
+            parts.push(`loc:${options.locationId}`);
         if (options?.employingEntityId != null)
-            params.set('employingEntityId', String(options.employingEntityId));
+            parts.push(`ee:${options.employingEntityId}`);
         if (options?.includeActive != null)
-            params.set('includeActive', String(options.includeActive));
+            parts.push(`a:${options.includeActive}`);
         if (options?.includeInactive != null)
-            params.set('includeInactive', String(options.includeInactive));
-        const queryString = params.toString();
-        const url = queryString
-            ? `${this.baseUrl}/business/${this.businessId}/report/employeedetails?${queryString}`
-            : `${this.baseUrl}/business/${this.businessId}/report/employeedetails`;
-        return this.fetchAndParse(url, async (r) => {
-            return await r.json();
+            parts.push(`i:${options.includeInactive}`);
+        const cacheKey = parts.join(':');
+        return this.cached(cacheKey, this.cacheTtl.employeeDetailsReportTtl, async () => {
+            const params = new URLSearchParams();
+            if (options?.selectedColumns) {
+                for (const col of options.selectedColumns) {
+                    params.append('selectedColumns', col);
+                }
+            }
+            if (options?.locationId != null)
+                params.set('locationId', String(options.locationId));
+            if (options?.employingEntityId != null)
+                params.set('employingEntityId', String(options.employingEntityId));
+            if (options?.includeActive != null)
+                params.set('includeActive', String(options.includeActive));
+            if (options?.includeInactive != null)
+                params.set('includeInactive', String(options.includeInactive));
+            const url = this.businessUrl('report/employeedetails', params);
+            return this.fetchAndParse(url, async (r) => {
+                return await r.json();
+            });
         });
     }
 }

package/dist/index.d.ts

@@ -20,8 +20,8 @@
  * ```
  */
 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 { EHConfig, EHCacheConfig, EHRetryConfig, EHLeaveRequest, EHLeaveRequestOptions, EHLeaveRequestStatus, 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, LEAVE_REQUEST_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, TTLCache, MemoryCacheStore, LayeredCache } from '@markwharton/api-core';

package/dist/index.js

@@ -22,7 +22,7 @@
 // Main client
 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';
+export { AU_EMPLOYEE_OPERATIONAL_FIELDS, AU_EMPLOYEE_PII_FIELDS, AU_EMPLOYEE_FIELDS, LEAVE_REQUEST_FIELDS, LOCATION_FIELDS, EMPLOYEE_GROUP_FIELDS, ROSTER_SHIFT_FIELDS, KIOSK_FIELDS, KIOSK_EMPLOYEE_FIELDS, } from './types.js';
 // Utilities
 export { buildBasicAuthHeader } from './utils.js';
 // Re-exported from @markwharton/api-core

package/dist/types.d.ts

@@ -15,6 +15,8 @@ import type { RetryConfig, ClientConfig } from '@markwharton/api-core';
 export interface EHCacheConfig {
     /** TTL for employee list (default: 300000 = 5 min) */
     employeesTtl?: number;
+    /** TTL for leave requests (default: 120000 = 2 min) */
+    leaveRequestsTtl?: number;
     /** TTL for locations (default: 300000 = 5 min) */
     locationsTtl?: number;
     /** TTL for employee groups (default: 300000 = 5 min) */
@@ -29,6 +31,8 @@ export interface EHCacheConfig {
     kioskStaffTtl?: number;
     /** TTL for report fields (default: 600000 = 10 min) */
     reportFieldsTtl?: number;
+    /** TTL for employee details report (default: 120000 = 2 min) */
+    employeeDetailsReportTtl?: number;
 }
 /** @deprecated Use `RetryConfig` from `@markwharton/api-core` directly. */
 export type EHRetryConfig = RetryConfig;
@@ -172,6 +176,57 @@ export interface EHKioskEmployee {
     /** Last recorded time in UTC */
     recordedTimeUtc: string | null;
 }
+/**
+ * Leave request from the Payroll API
+ *
+ * From GET /business/{id}/leaverequest
+ * Field whitelist from Swagger HourLeaveRequestResponseModel.
+ */
+export interface EHLeaveRequest {
+    /** Leave request ID */
+    id: number;
+    /** Employee ID */
+    employeeId: number;
+    /** Leave category ID */
+    leaveCategoryId: number;
+    /** Employee display name */
+    employee: string;
+    /** Leave category name */
+    leaveCategory: string;
+    /** Start date (ISO 8601 datetime) */
+    fromDate: string;
+    /** End date (ISO 8601 datetime) */
+    toDate: string;
+    /** Total hours requested */
+    totalHours: number;
+    /** Hours actually applied */
+    hoursApplied: number;
+    /** Notes on the leave request */
+    notes: string | null;
+    /** Status: Approved, Pending, Rejected, Cancelled */
+    status: string;
+}
+/** Leave request status values */
+export type EHLeaveRequestStatus = 'Approved' | 'Pending' | 'Rejected' | 'Cancelled';
+/**
+ * Options for getLeaveRequests
+ *
+ * All filters are passed server-side to the API.
+ */
+export interface EHLeaveRequestOptions {
+    /** Filter by start date (ISO 8601 date-time → API FromDate) */
+    fromDate?: string;
+    /** Filter by end date (ISO 8601 date-time → API ToDate) */
+    toDate?: string;
+    /** Filter by status (→ API Status) */
+    status?: EHLeaveRequestStatus;
+    /** Filter by employee ID (→ API EmployeeId) */
+    employeeId?: number;
+    /** Filter by leave category ID (→ API LeaveCategoryId) */
+    leaveCategoryId?: number;
+    /** Filter by location ID (→ API LocationId) */
+    locationId?: number;
+}
 /**
  * Options for getEmployees
  */
@@ -291,6 +346,8 @@ export interface EHEmployeeDetailsReportOptions {
     /** Include inactive employees (default: false) */
     includeInactive?: boolean;
 }
+/** Whitelisted fields for EHLeaveRequest */
+export declare const LEAVE_REQUEST_FIELDS: readonly ["id", "employeeId", "leaveCategoryId", "employee", "leaveCategory", "fromDate", "toDate", "totalHours", "hoursApplied", "notes", "status"];
 /** Whitelisted fields for EHLocation */
 export declare const LOCATION_FIELDS: readonly ["id", "parentId", "name", "externalId", "source", "fullyQualifiedName", "isGlobal", "state", "country"];
 /** Whitelisted fields for EHKiosk */

package/dist/types.js

@@ -7,6 +7,11 @@
 // ============================================================================
 // Field Key Constants (whitelists for pickFields)
 // ============================================================================
+/** Whitelisted fields for EHLeaveRequest */
+export const LEAVE_REQUEST_FIELDS = [
+    'id', 'employeeId', 'leaveCategoryId', 'employee', 'leaveCategory',
+    'fromDate', 'toDate', 'totalHours', 'hoursApplied', 'notes', 'status',
+];
 /** Whitelisted fields for EHLocation */
 export const LOCATION_FIELDS = [
     'id', 'parentId', 'name', 'externalId', 'source',

package/package.json

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