@markwharton/eh-payroll 2.3.0 → 2.4.0

package/README.md

@@ -123,7 +123,11 @@ const employees = result.data;
 
 ### `getLeaveRequests()`
 
-Returns leave requests with all filters applied server-side. Unlike paginated endpoints, this returns a flat array.
+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`:**
 

package/dist/client.d.ts

@@ -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

package/dist/client.js

@@ -59,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.
@@ -240,7 +245,7 @@ export class EHClient {
                 return (await r.json())
                     .map(item => pickFields(item, LEAVE_REQUEST_FIELDS));
             });
-        });
+        }, this.restrictedPersistOpt);
     }
     // ============================================================================
     // Employees
@@ -258,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)
@@ -278,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) => {
@@ -298,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
@@ -505,6 +510,6 @@ export class EHClient {
             return this.fetchAndParse(url, async (r) => {
                 return await r.json();
             });
-        });
+        }, this.restrictedPersistOpt);
     }
 }

package/dist/index.d.ts

@@ -22,6 +22,8 @@
 export { EHClient } from './client.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

@@ -23,6 +23,7 @@
 export { EHClient } from './client.js';
 // Field key constants (whitelists for pickFields)
 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

@@ -50,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
@@ -370,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

@@ -123,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.3.0",
+  "version": "2.4.0",
   "description": "Employment Hero Payroll API client",
   "type": "module",
   "main": "dist/index.js",