@markwharton/eh-payroll 2.2.0 → 2.4.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,39 @@ 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. The business-level endpoint (`/api/v2/business/{businessId}/leaverequest`) returns a flat array — no pagination is available.
+
+**Leave requests are time-series data** — unlike employees and locations which remain relatively stable, leave requests grow continuously as new requests accumulate. Always use `fromDate`/`toDate` filters to bound the result set. Without date filters, the API returns the entire leave request history.
+
+> **Note:** The Payroll API also provides a per-employee endpoint (`/api/v2/business/{businessId}/employee/{employeeId}/leaverequest`) with OData support (`$filter`, `$orderby`, `$top`, `$skip`). This client currently uses only the business-level endpoint.
+
+**`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 +183,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';
 /**
@@ -32,7 +32,10 @@ export declare class EHClient {
     private readonly cacheTtl;
     private readonly retryConfig?;
     private readonly rateLimiter?;
+    private readonly persistRestricted;
     constructor(config: EHConfig);
+    /** Cache options for restricted-tier methods: skip persistent stores when persistRestricted is false. */
+    private get restrictedPersistOpt();
     /**
      * Route through cache if enabled, otherwise call factory directly.
      * Failed Results (ok === false) are never cached — transient errors
@@ -43,6 +46,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 +77,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);
@@ -57,6 +59,11 @@ export class EHClient {
         if (rateLimitPerSecond > 0) {
             this.rateLimiter = new RateLimiter(rateLimitPerSecond);
         }
+        this.persistRestricted = config.persistRestricted ?? true;
+    }
+    /** Cache options for restricted-tier methods: skip persistent stores when persistRestricted is false. */
+    get restrictedPersistOpt() {
+        return this.persistRestricted ? undefined : { persist: false };
     }
     /**
      * Route through cache if enabled, otherwise call factory directly.
@@ -77,6 +84,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 +201,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));
+            });
+        }, this.restrictedPersistOpt);
+    }
+    // ============================================================================
     // Employees
     // ============================================================================
     /**
@@ -201,7 +263,7 @@ export class EHClient {
         if (options?.includePii)
             parts.push('pii');
         const cacheKey = parts.join(':');
-        const persistOpt = options?.includePii ? { persist: false } : undefined;
+        const persistOpt = (options?.includePii || !this.persistRestricted) ? { persist: false } : undefined;
         return this.cached(cacheKey, this.cacheTtl.employeesTtl, () => {
             const params = new URLSearchParams();
             if (options?.payScheduleId != null)
@@ -221,7 +283,7 @@ export class EHClient {
     async getEmployee(employeeId, options) {
         const fields = options?.includePii ? AU_EMPLOYEE_FIELDS : AU_EMPLOYEE_OPERATIONAL_FIELDS;
         const cacheKey = options?.includePii ? `employee:${employeeId}:pii` : `employee:${employeeId}`;
-        const persistOpt = options?.includePii ? { persist: false } : undefined;
+        const persistOpt = (options?.includePii || !this.persistRestricted) ? { persist: false } : undefined;
         return this.cached(cacheKey, this.cacheTtl.employeesTtl, async () => {
             const url = `${this.baseUrl}/business/${this.businessId}/employee/unstructured/${employeeId}`;
             return this.fetchAndParse(url, async (r) => {
@@ -241,7 +303,7 @@ export class EHClient {
             return this.fetchAndParse(url, async (r) => {
                 return await r.json();
             }, { description: `Get standard hours for employee ${employeeId}` });
-        });
+        }, this.restrictedPersistOpt);
     }
     // ============================================================================
     // Locations
@@ -386,10 +448,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 +479,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();
+            });
+        }, this.restrictedPersistOpt);
     }
 }

package/dist/index.d.ts

@@ -20,8 +20,10 @@
  * ```
  */
 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 { AccessTier } from './types.js';
+export { METHOD_TIERS } 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,8 @@
 // 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';
+export { METHOD_TIERS } 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;
@@ -46,6 +50,8 @@ export interface EHConfig extends ClientConfig {
     cache?: EHCacheConfig;
     /** Max requests per second (default: 5 per API spec). Set 0 to disable. */
     rateLimitPerSecond?: number;
+    /** Whether to persist restricted-tier data in persistent cache stores (default: true). Set false to keep restricted data in memory only. */
+    persistRestricted?: boolean;
 }
 /**
  * Employee from unstructured endpoint
@@ -172,6 +178,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 +348,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 */
@@ -313,3 +372,13 @@ export declare const AU_EMPLOYEE_OPERATIONAL_FIELDS: readonly ["id", "externalId
 export declare const AU_EMPLOYEE_PII_FIELDS: readonly ["dateOfBirth", "gender", "title", "middleName", "preferredName", "previousSurname", "emailAddress", "homePhone", "mobilePhone", "workPhone", "bankAccount1_AccountName", "bankAccount1_AccountNumber", "bankAccount1_AllocatedPercentage", "bankAccount1_BSB", "bankAccount1_FixedAmount", "bankAccount2_AccountName", "bankAccount2_AccountNumber", "bankAccount2_AllocatedPercentage", "bankAccount2_BSB", "bankAccount2_FixedAmount", "bankAccount3_AccountName", "bankAccount3_AccountNumber", "bankAccount3_AllocatedPercentage", "bankAccount3_BSB", "bankAccount3_FixedAmount", "emergencyContact1_Address", "emergencyContact1_AlternateContactNumber", "emergencyContact1_ContactNumber", "emergencyContact1_Name", "emergencyContact1_Relationship", "emergencyContact2_Address", "emergencyContact2_AlternateContactNumber", "emergencyContact2_ContactNumber", "emergencyContact2_Name", "emergencyContact2_Relationship", "postalStreetAddress", "postalAddressLine2", "postalPostCode", "postalCountry", "postalState", "postalSuburb", "postalAddressIsOverseas", "residentialStreetAddress", "residentialAddressLine2", "residentialPostCode", "residentialCountry", "residentialState", "residentialSuburb", "residentialAddressIsOverseas", "taxFileNumber", "taxCategory", "taxVariation", "claimTaxFreeThreshold", "claimMedicareLevyReduction", "medicareLevyExemption", "medicareLevyReductionDependentCount", "medicareLevyReductionSpouse", "medicareLevySurchargeWithholdingTier", "seniorsTaxOffset", "otherTaxOffset", "stslDebt", "hasWithholdingVariation", "dateTaxFileDeclarationReported", "dateTaxFileDeclarationSigned", "superFund1_AllocatedPercentage", "superFund1_EmployerNominatedFund", "superFund1_FixedAmount", "superFund1_FundName", "superFund1_MemberNumber", "superFund1_ProductCode", "superFund2_AllocatedPercentage", "superFund2_EmployerNominatedFund", "superFund2_FixedAmount", "superFund2_FundName", "superFund2_MemberNumber", "superFund2_ProductCode", "superFund3_AllocatedPercentage", "superFund3_EmployerNominatedFund", "superFund3_FixedAmount", "superFund3_FundName", "superFund3_MemberNumber", "superFund3_ProductCode", "contractorABN", "employingEntityABN", "hasApprovedWorkingHolidayVisa", "workingHolidayVisaCountry", "workingHolidayVisaStartDate"];
 /** All whitelisted fields for EHAuEmployee (operational + PII) */
 export declare const AU_EMPLOYEE_FIELDS: readonly ["id", "externalId", "firstName", "surname", "status", "startDate", "endDate", "anniversaryDate", "dateCreated", "employmentType", "jobTitle", "employmentAgreement", "employmentAgreementId", "paySchedule", "payRateTemplate", "rate", "rateUnit", "hoursPerWeek", "hoursPerDay", "primaryPayCategory", "payConditionRuleSet", "overrideTemplateRate", "automaticallyPayEmployee", "primaryLocation", "locations", "tags", "workTypes", "reportingDimensionValues", "leaveAccrualStartDateType", "leaveTemplate", "leaveYearStart", "isEnabledForTimesheets", "rosteringNotificationChoices", "paySlipNotificationType", "terminationReason", "australianResident", "awardId", "businessAwardPackage", "automaticallyApplyPublicHolidayNotWorkedEarningsLines", "closelyHeldEmployee", "closelyHeldReporting", "disableAutoProgression", "dvlPaySlipDescription", "employingEntityId", "includeInPortableLongServiceLeaveReport", "portableLongServiceLeaveId", "isExemptFromFloodLevy", "isExemptFromPayrollTax", "isSeasonalWorker", "maximumQuarterlySuperContributionsBase", "superThresholdAmount", "singleTouchPayroll", "dateOfBirth", "gender", "title", "middleName", "preferredName", "previousSurname", "emailAddress", "homePhone", "mobilePhone", "workPhone", "bankAccount1_AccountName", "bankAccount1_AccountNumber", "bankAccount1_AllocatedPercentage", "bankAccount1_BSB", "bankAccount1_FixedAmount", "bankAccount2_AccountName", "bankAccount2_AccountNumber", "bankAccount2_AllocatedPercentage", "bankAccount2_BSB", "bankAccount2_FixedAmount", "bankAccount3_AccountName", "bankAccount3_AccountNumber", "bankAccount3_AllocatedPercentage", "bankAccount3_BSB", "bankAccount3_FixedAmount", "emergencyContact1_Address", "emergencyContact1_AlternateContactNumber", "emergencyContact1_ContactNumber", "emergencyContact1_Name", "emergencyContact1_Relationship", "emergencyContact2_Address", "emergencyContact2_AlternateContactNumber", "emergencyContact2_ContactNumber", "emergencyContact2_Name", "emergencyContact2_Relationship", "postalStreetAddress", "postalAddressLine2", "postalPostCode", "postalCountry", "postalState", "postalSuburb", "postalAddressIsOverseas", "residentialStreetAddress", "residentialAddressLine2", "residentialPostCode", "residentialCountry", "residentialState", "residentialSuburb", "residentialAddressIsOverseas", "taxFileNumber", "taxCategory", "taxVariation", "claimTaxFreeThreshold", "claimMedicareLevyReduction", "medicareLevyExemption", "medicareLevyReductionDependentCount", "medicareLevyReductionSpouse", "medicareLevySurchargeWithholdingTier", "seniorsTaxOffset", "otherTaxOffset", "stslDebt", "hasWithholdingVariation", "dateTaxFileDeclarationReported", "dateTaxFileDeclarationSigned", "superFund1_AllocatedPercentage", "superFund1_EmployerNominatedFund", "superFund1_FixedAmount", "superFund1_FundName", "superFund1_MemberNumber", "superFund1_ProductCode", "superFund2_AllocatedPercentage", "superFund2_EmployerNominatedFund", "superFund2_FixedAmount", "superFund2_FundName", "superFund2_MemberNumber", "superFund2_ProductCode", "superFund3_AllocatedPercentage", "superFund3_EmployerNominatedFund", "superFund3_FixedAmount", "superFund3_FundName", "superFund3_MemberNumber", "superFund3_ProductCode", "contractorABN", "employingEntityABN", "hasApprovedWorkingHolidayVisa", "workingHolidayVisaCountry", "workingHolidayVisaStartDate"];
+/** Access tier for method-level authorization */
+export type AccessTier = 'standard' | 'restricted';
+/**
+ * Access tier for each data method.
+ *
+ * Standard: operational data (locations, groups, kiosks, roster shifts, report fields).
+ * Restricted: employee-level data (employees, standard hours, leave requests, employee reports).
+ * Utility methods (validate, clear, invalidate) are not included.
+ */
+export declare const METHOD_TIERS: Record<string, AccessTier>;

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',
@@ -118,3 +123,23 @@ export const AU_EMPLOYEE_FIELDS = [
     ...AU_EMPLOYEE_OPERATIONAL_FIELDS,
     ...AU_EMPLOYEE_PII_FIELDS,
 ];
+/**
+ * Access tier for each data method.
+ *
+ * Standard: operational data (locations, groups, kiosks, roster shifts, report fields).
+ * Restricted: employee-level data (employees, standard hours, leave requests, employee reports).
+ * Utility methods (validate, clear, invalidate) are not included.
+ */
+export const METHOD_TIERS = {
+    getLocations: 'standard',
+    getEmployeeGroups: 'standard',
+    getKiosks: 'standard',
+    getKioskStaff: 'standard',
+    getRosterShifts: 'standard',
+    getReportFields: 'standard',
+    getEmployees: 'restricted',
+    getLeaveRequests: 'restricted',
+    getEmployee: 'restricted',
+    getStandardHours: 'restricted',
+    getEmployeeDetailsReport: 'restricted',
+};

package/package.json

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