@markwharton/eh-payroll 1.1.1 → 1.3.0

package/README.md

@@ -29,20 +29,26 @@ const { employees } = await client.getEmployees();
 const { employees: filtered } = await client.getEmployees({ locationId: 5 });
 
 // Get roster shifts for a date range (auto-paginates)
-const { shifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
+const { rosterShifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
 
 // Get roster shifts with filters
-const { shifts: published } = await client.getRosterShifts('2026-02-03', '2026-02-09', {
+const { rosterShifts: published } = await client.getRosterShifts('2026-02-03', '2026-02-09', {
   employeeId: 42,
   shiftStatus: 'Published',
   selectAllRoles: true
 });
 
+// Get business locations
+const { locations } = await client.getLocations();
+
+// List kiosks
+const { kiosks } = await client.getKiosks();
+
 // Get kiosk staff (time and attendance)
 const { staff } = await client.getKioskStaff(kioskId);
 
 // Get employee groups
-const { groups } = await client.getEmployeeGroups();
+const { employeeGroups } = await client.getEmployeeGroups();
 
 // Get standard hours for an employee (includes FTE value)
 const { standardHours } = await client.getStandardHours(employeeId);
@@ -66,15 +72,17 @@ All methods return `{ data?, error? }` result objects rather than throwing excep
 | `getEmployees(options?)` | `EHEmployeeOptions?` | `{ employees?, error? }` |
 | `getEmployee(employeeId)` | `number` | `{ employee?, error? }` |
 | `getStandardHours(employeeId)` | `number` | `{ standardHours?, error? }` |
-| `getEmployeeGroups()` | — | `{ groups?, error? }` |
-| `getRosterShifts(from, to, options?)` | `string, string, EHRosterShiftOptions?` | `{ shifts?, 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? }` |
 
 ### `getRosterShifts()`
 
-Automatically paginates through all results (100 per page). Returns the complete set of shifts for the requested date range. All filter options are applied server-side, reducing the number of results and pages fetched.
+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
 
@@ -104,9 +112,12 @@ const client = new EHClient({
 | Cache Key | Default TTL |
 |-----------|-------------|
 | Employees | 5 min |
+| Locations | 5 min |
 | Employee groups | 5 min |
 | Standard hours | 5 min |
 | Roster shifts | 2 min |
+| Kiosks | 5 min |
+| Kiosk staff | 1 min |
 | Report fields | 10 min |
 
 ### Rate Limiting

package/dist/client.d.ts

@@ -6,7 +6,7 @@
  *
  * @see https://api.keypay.com.au/
  */
-import type { EHConfig, EHEmployeeOptions, EHSingleEmployeeOptions, EHStandardHours, EHEmployeeGroup, EHRosterShift, EHRosterShiftOptions, EHKioskEmployee, EHKioskStaffOptions, EHErrorInfo, EHReportField, EHEmployeeDetailsReportOptions } from './types.js';
+import type { EHConfig, EHEmployeeOptions, EHSingleEmployeeOptions, EHStandardHours, EHLocation, EHEmployeeGroup, EHRosterShift, EHRosterShiftOptions, EHKiosk, EHKioskEmployee, EHKioskStaffOptions, EHErrorInfo, EHReportField, EHEmployeeDetailsReportOptions } from './types.js';
 import type { EHAuEmployee } from './employee-types.generated.js';
 /**
  * Employment Hero Payroll API Client
@@ -79,11 +79,18 @@ export declare class EHClient {
         standardHours?: EHStandardHours;
         error?: EHErrorInfo;
     }>;
+    /**
+     * Get all business locations
+     */
+    getLocations(): Promise<{
+        locations?: EHLocation[];
+        error?: EHErrorInfo;
+    }>;
     /**
      * Get all employee groups
      */
     getEmployeeGroups(): Promise<{
-        groups?: EHEmployeeGroup[];
+        employeeGroups?: EHEmployeeGroup[];
         error?: EHErrorInfo;
     }>;
     /**
@@ -94,7 +101,14 @@ export declare class EHClient {
      * @param options - Optional filters
      */
     getRosterShifts(fromDate: string, toDate: string, options?: EHRosterShiftOptions): Promise<{
-        shifts?: EHRosterShift[];
+        rosterShifts?: EHRosterShift[];
+        error?: EHErrorInfo;
+    }>;
+    /**
+     * Get all kiosks for the business
+     */
+    getKiosks(): Promise<{
+        kiosks?: EHKiosk[];
         error?: EHErrorInfo;
     }>;
     /**

package/dist/client.js

@@ -6,7 +6,7 @@
  *
  * @see https://api.keypay.com.au/
  */
-import { AU_EMPLOYEE_OPERATIONAL_FIELDS, AU_EMPLOYEE_FIELDS, EMPLOYEE_GROUP_FIELDS, ROSTER_SHIFT_FIELDS, KIOSK_EMPLOYEE_FIELDS, } from './types.js';
+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 { parseEHErrorResponse } from './errors.js';
 import { EH_API_BASE, EH_REGION_URLS } from './constants.js';
@@ -43,9 +43,12 @@ export class EHClient {
         }
         this.cacheTtl = {
             employeesTtl: config.cache?.employeesTtl ?? 300000,
+            locationsTtl: config.cache?.locationsTtl ?? 300000,
             groupsTtl: config.cache?.groupsTtl ?? 300000,
             standardHoursTtl: config.cache?.standardHoursTtl ?? 300000,
             rosterShiftsTtl: config.cache?.rosterShiftsTtl ?? 120000,
+            kiosksTtl: config.cache?.kiosksTtl ?? 300000,
+            kioskStaffTtl: config.cache?.kioskStaffTtl ?? 60000,
             reportFieldsTtl: config.cache?.reportFieldsTtl ?? 600000,
         };
         // Initialize retry config with defaults if provided
@@ -228,13 +231,50 @@ export class EHClient {
         });
     }
     // ============================================================================
+    // Locations
+    // ============================================================================
+    /**
+     * 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 { error: { message, statusCode: 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 { locations: allLocations };
+            }
+            catch (error) {
+                return { error: { message: getErrorMessage(error), statusCode: 0 } };
+            }
+        });
+    }
+    // ============================================================================
     // Employee Groups
     // ============================================================================
     /**
      * Get all employee groups
      */
     async getEmployeeGroups() {
-        return this.cached('groups', this.cacheTtl.groupsTtl, async () => {
+        return this.cached('employeeGroups', this.cacheTtl.groupsTtl, async () => {
             const params = new URLSearchParams({
                 '$top': String(DEFAULT_PAGE_SIZE),
             });
@@ -257,7 +297,7 @@ export class EHClient {
                         break;
                     skip += DEFAULT_PAGE_SIZE;
                 }
-                return { groups: allGroups };
+                return { employeeGroups: allGroups };
             }
             catch (error) {
                 return { error: { message: getErrorMessage(error), statusCode: 0 } };
@@ -361,7 +401,7 @@ export class EHClient {
                         break;
                     currentPage++;
                 }
-                return { shifts: allShifts };
+                return { rosterShifts: allShifts };
             }
             catch (error) {
                 return { error: { message: getErrorMessage(error), statusCode: 0 } };
@@ -371,6 +411,40 @@ export class EHClient {
     // ============================================================================
     // Time & Attendance (Kiosk)
     // ============================================================================
+    /**
+     * 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 { error: { message, statusCode: 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 { kiosks: allKiosks };
+            }
+            catch (error) {
+                return { error: { message: getErrorMessage(error), statusCode: 0 } };
+            }
+        });
+    }
     /**
      * Get kiosk staff for time and attendance
      *
@@ -378,19 +452,24 @@ export class EHClient {
      * @param options - Optional query parameters
      */
     async getKioskStaff(kioskId, options) {
-        const params = new URLSearchParams();
-        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 { data, error } = await this.fetchAndParse(url, async (r) => {
-            return (await r.json())
-                .map(item => pickFields(item, KIOSK_EMPLOYEE_FIELDS));
+        const cacheKey = options?.restrictCurrentShiftsToCurrentKioskLocation
+            ? `kiosk:${kioskId}:rcs`
+            : `kiosk:${kioskId}`;
+        return this.cached(cacheKey, this.cacheTtl.kioskStaffTtl, async () => {
+            const params = new URLSearchParams();
+            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 { data, error } = await this.fetchAndParse(url, async (r) => {
+                return (await r.json())
+                    .map(item => pickFields(item, KIOSK_EMPLOYEE_FIELDS));
+            });
+            return error ? { error } : { staff: data };
         });
-        return error ? { error } : { staff: data };
     }
     // ============================================================================
     // Employee Details Report

package/dist/index.d.ts

@@ -16,12 +16,12 @@
  * const { employees } = await client.getEmployees();
  *
  * // Get roster shifts
- * const { shifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
+ * const { rosterShifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
  * ```
  */
 export { EHClient } from './client.js';
-export type { EHConfig, EHCacheConfig, EHRetryConfig, EHEmployee, EHEmployeeOptions, EHSingleEmployeeOptions, EHStandardHours, EHEmployeeGroup, EHRosterShift, EHRosterShiftOptions, EHAttendanceStatus, EHKioskEmployee, EHKioskStaffOptions, EHReportField, EHEmployeeDetailsReportOptions, EHErrorInfo, } from './types.js';
-export { AU_EMPLOYEE_OPERATIONAL_FIELDS, AU_EMPLOYEE_PII_FIELDS, AU_EMPLOYEE_FIELDS, EMPLOYEE_GROUP_FIELDS, ROSTER_SHIFT_FIELDS, KIOSK_EMPLOYEE_FIELDS, } from './types.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 { 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';

package/dist/index.js

@@ -16,13 +16,13 @@
  * const { employees } = await client.getEmployees();
  *
  * // Get roster shifts
- * const { shifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
+ * const { rosterShifts } = await client.getRosterShifts('2026-02-03', '2026-02-09');
  * ```
  */
 // 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, EMPLOYEE_GROUP_FIELDS, ROSTER_SHIFT_FIELDS, KIOSK_EMPLOYEE_FIELDS, } 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';
 // Rate limiting
 export { RateLimiter } from './rate-limiter.js';
 // Utilities

package/dist/types.d.ts

@@ -14,12 +14,18 @@ import type { EHRegion } from './constants.js';
 export interface EHCacheConfig {
     /** TTL for employee list (default: 300000 = 5 min) */
     employeesTtl?: number;
+    /** TTL for locations (default: 300000 = 5 min) */
+    locationsTtl?: number;
     /** TTL for employee groups (default: 300000 = 5 min) */
     groupsTtl?: number;
     /** TTL for standard hours (default: 300000 = 5 min) */
     standardHoursTtl?: number;
     /** TTL for roster shifts (default: 120000 = 2 min) */
     rosterShiftsTtl?: number;
+    /** TTL for kiosks list (default: 300000 = 5 min) */
+    kiosksTtl?: number;
+    /** TTL for kiosk staff (default: 60000 = 1 min) */
+    kioskStaffTtl?: number;
     /** TTL for report fields (default: 600000 = 10 min) */
     reportFieldsTtl?: number;
 }
@@ -88,6 +94,31 @@ export interface EHStandardHours {
     /** Full-time equivalent hours (the FTE value) */
     fullTimeEquivalentHours: number | null;
 }
+/**
+ * Business location
+ *
+ * From GET /business/{id}/location
+ */
+export interface EHLocation {
+    /** Location ID */
+    id: number;
+    /** Parent location ID (for hierarchy) */
+    parentId: number | null;
+    /** Location name */
+    name: string;
+    /** External identifier */
+    externalId: string | null;
+    /** Source system that created this location */
+    source: string | null;
+    /** Fully qualified name (includes parent hierarchy) */
+    fullyQualifiedName: string | null;
+    /** Whether this is a global/default location */
+    isGlobal: boolean;
+    /** Australian state */
+    state: string | null;
+    /** Country */
+    country: string | null;
+}
 /**
  * Employee group
  */
@@ -210,6 +241,45 @@ export interface EHRosterShiftOptions {
     /** Include warning data in response */
     includeWarnings?: boolean;
 }
+/**
+ * Kiosk configuration
+ *
+ * From GET /business/{id}/kiosk
+ */
+export interface EHKiosk {
+    /** Kiosk ID */
+    id: number;
+    /** External identifier */
+    externalId: string | null;
+    /** Kiosk name */
+    name: string;
+    /** Associated location ID */
+    locationId: number | null;
+    /** Windows timezone name */
+    timeZone: string | null;
+    /** IANA timezone name (read-only) */
+    ianaTimeZone: string | null;
+    /** Allow higher classification selection */
+    allowHigherClassificationSelection: boolean;
+    /** Whether location is required for clock on */
+    isLocationRequired: boolean;
+    /** Whether work type is required for clock on */
+    isWorkTypeRequired: boolean;
+    /** Restrict locations for employees */
+    restrictLocationsForEmployees: boolean;
+    /** Allow employee shift selection */
+    allowEmployeeShiftSelection: boolean | null;
+    /** Clock on window in minutes */
+    clockOnWindowMinutes: number | null;
+    /** Clock off window in minutes */
+    clockOffWindowMinutes: number | null;
+    /** Whether photo is required for clock on */
+    isPhotoRequired: boolean | null;
+    /** Whether kiosk can add employees */
+    canAddEmployees: boolean;
+    /** Whether paid breaks are enabled */
+    paidBreaksEnabled: boolean;
+}
 /**
  * Options for getKioskStaff
  */
@@ -252,6 +322,10 @@ export interface EHErrorInfo {
     /** 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 */
+export declare const KIOSK_FIELDS: readonly ["id", "externalId", "name", "locationId", "timeZone", "ianaTimeZone", "allowHigherClassificationSelection", "isLocationRequired", "isWorkTypeRequired", "restrictLocationsForEmployees", "allowEmployeeShiftSelection", "clockOnWindowMinutes", "clockOffWindowMinutes", "isPhotoRequired", "canAddEmployees", "paidBreaksEnabled"];
 /** Whitelisted fields for EHKioskEmployee */
 export declare const KIOSK_EMPLOYEE_FIELDS: readonly ["employeeId", "firstName", "surname", "name", "status", "clockOnTimeUtc", "breakStartTimeUtc", "currentShiftId", "employeeStartDate", "employeeGroupIds", "longShift", "recordedTimeUtc"];
 /** Whitelisted fields for EHEmployeeGroup */

package/dist/types.js

@@ -7,6 +7,19 @@
 // ============================================================================
 // Field Key Constants (whitelists for pickFields)
 // ============================================================================
+/** Whitelisted fields for EHLocation */
+export const LOCATION_FIELDS = [
+    'id', 'parentId', 'name', 'externalId', 'source',
+    'fullyQualifiedName', 'isGlobal', 'state', 'country',
+];
+/** Whitelisted fields for EHKiosk */
+export const KIOSK_FIELDS = [
+    'id', 'externalId', 'name', 'locationId', 'timeZone', 'ianaTimeZone',
+    'allowHigherClassificationSelection', 'isLocationRequired', 'isWorkTypeRequired',
+    'restrictLocationsForEmployees', 'allowEmployeeShiftSelection',
+    'clockOnWindowMinutes', 'clockOffWindowMinutes',
+    'isPhotoRequired', 'canAddEmployees', 'paidBreaksEnabled',
+];
 /** Whitelisted fields for EHKioskEmployee */
 export const KIOSK_EMPLOYEE_FIELDS = [
     'employeeId', 'firstName', 'surname', 'name', 'status',

package/package.json

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