@markwharton/eh-payroll 1.2.0 → 1.3.0

package/README.md

@@ -38,6 +38,12 @@ const { rosterShifts: published } = await client.getRosterShifts('2026-02-03', '
   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);
 
@@ -66,8 +72,10 @@ 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? }` |
+| `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? }` |
@@ -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,6 +79,13 @@ export declare class EHClient {
         standardHours?: EHStandardHours;
         error?: EHErrorInfo;
     }>;
+    /**
+     * Get all business locations
+     */
+    getLocations(): Promise<{
+        locations?: EHLocation[];
+        error?: EHErrorInfo;
+    }>;
     /**
      * Get all employee groups
      */
@@ -97,6 +104,13 @@ export declare class EHClient {
         rosterShifts?: EHRosterShift[];
         error?: EHErrorInfo;
     }>;
+    /**
+     * Get all kiosks for the business
+     */
+    getKiosks(): Promise<{
+        kiosks?: EHKiosk[];
+        error?: EHErrorInfo;
+    }>;
     /**
      * Get kiosk staff for time and attendance
      *

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,11 @@ 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,
         };
@@ -229,6 +231,43 @@ 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
     // ============================================================================
     /**
@@ -372,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
      *

package/dist/index.d.ts

@@ -20,8 +20,8 @@
  * ```
  */
 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

@@ -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, 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,16 @@ 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) */
@@ -90,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
  */
@@ -212,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
  */
@@ -254,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.2.0",
+  "version": "1.3.0",
   "description": "Employment Hero Payroll API client",
   "type": "module",
   "main": "dist/index.js",