@classytic/payroll 2.7.5 → 2.8.0

package/dist/index.d.ts

@@ -1,13 +1,15 @@
-import { E as EmployeeDocument, q as PayrollRecordDocument, r as AnyDocument, s as PayrollInstance, t as PayrollInitConfig, u as PayrollPluginDefinition, v as PayrollEventMap, w as WebhookConfig, x as PayrollEventType, y as WebhookDelivery, H as HireEmployeeParams, U as UpdateEmploymentParams, z as TerminateEmployeeParams, R as ReHireEmployeeParams, O as ObjectIdLike, d as OperationContext, F as EmployeeIdentityMode, G as UpdateSalaryParams, I as AddAllowanceParams, J as RemoveAllowanceParams, K as AddDeductionParams, M as RemoveDeductionParams, N as UpdateBankDetailsParams, Q as ProcessSalaryParams, S as ProcessSalaryResult, V as ProcessBulkPayrollParams, X as BulkPayrollResult, Y as PayrollHistoryParams, Z as PayrollSummaryParams, _ as PayrollSummaryResult, $ as ExportPayrollParams, a0 as VoidPayrollParams, a1 as VoidPayrollResult, a2 as ReversePayrollParams, a3 as ReversePayrollResult, a4 as RestorePayrollParams, a5 as RestorePayrollResult, a6 as GetPendingTaxParams, T as TaxWithholdingDocument, a7 as TaxSummaryParams, a8 as TaxSummaryResult, a9 as MarkTaxPaidParams, g as LeaveRequestDocument, aa as DeepPartial, ab as HRMConfig, ac as SingleTenantConfig, i as Logger, ad as PayrollBreakdown, ae as ObjectId, h as LeaveRequestStatus, f as TaxStatus, L as LeaveType, e as TaxType, p as PayrollStatus, o as Department, n as EmploymentType, af as OrgRole, c as LeaveInitConfig, ag as WorkSchedule, ah as PaymentFrequency, A as Allowance, D as Deduction, B as BankDetails, C as Compensation, ai as TerminationReason, aj as HttpError, ak as ErrorCode, al as AttendanceInput } from './types-BVDjiVGS.js';
-export { am as AccrueLeaveOptions, an as AllowanceType, ao as AnyModel, ap as BulkPayrollProgress, j as CompensationBreakdownResult, aq as DataRetentionConfig, ar as DeductionType, as as EmployeeHiredEvent, at as EmployeeIdMode, au as EmployeeOperationParams, l as EmployeeStatus, m as EmployeeValidationResult, av as EmploymentConfig, aw as EmploymentHistoryEntry, ax as EventPayload, ay as EventPayloadBase, az as FilterQuery, aA as GetEmployeeParams, aB as HRMTransactionCategory, a as LeaveBalance, aC as LeaveHistoryFilters, b as LeaveSummaryResult, aD as Nullable, P as PayPeriodInfo, aE as PaymentMethod, aF as PayrollConfig, aG as PayrollCorrection, aH as PayrollEmployee, aI as PayrollEvent, aJ as PayrollPeriod, aK as PayrollPlugin, aL as PayrollStats, aM as PluginFunction, aN as PluginType, aO as QueryOptions, aP as RequestLeaveInput, aQ as ResetAnnualLeaveOptions, aR as ReviewLeaveRequestInput, aS as RoleMappingConfig, aT as SalaryBand, aU as SalaryBandRange, aV as SalaryConfig, aW as SalaryProcessedEvent, aX as TaxBracket, k as TaxCalculationResult, aY as TaxSummaryByType, aZ as UserReference, a_ as ValidationConfig, a$ as WebhookManager, b0 as WithPayroll, W as WorkingDaysOptions } from './types-BVDjiVGS.js';
+import { E as EmployeeDocument, P as PayrollRecordDocument, A as AnyDocument, aq as PayrollInstance, ar as PayrollInitConfig, l as PayrollPluginDefinition, i as PayrollEventMap, W as WebhookConfig, j as PayrollEventType, v as WebhookDelivery, as as HireEmployeeParams, at as UpdateEmploymentParams, au as TerminateEmployeeParams, av as ReHireEmployeeParams, a2 as ObjectIdLike, ap as OperationContext, aw as EmployeeIdentityMode, ax as UpdateSalaryParams, ay as AddAllowanceParams, az as RemoveAllowanceParams, aA as AddDeductionParams, aB as RemoveDeductionParams, aC as UpdateBankDetailsParams, aD as ProcessSalaryParams, aE as ProcessSalaryResult, aF as ProcessBulkPayrollParams, aG as BulkPayrollResult, aH as PayrollHistoryParams, aI as PayrollSummaryParams, aJ as PayrollSummaryResult, aK as VoidPayrollParams, aL as VoidPayrollResult, aM as ReversePayrollParams, aN as ReversePayrollResult, aO as RestorePayrollParams, aP as RestorePayrollResult, aQ as GetPendingTaxParams, T as TaxWithholdingDocument, aR as TaxSummaryParams, aS as TaxSummaryResult, aT as MarkTaxPaidParams, a3 as ObjectId, aU as ExportPayrollParams, L as LeaveRequestDocument, aV as DeepPartial, H as HRMConfig, S as SingleTenantConfig, a as Logger, a1 as PayrollBreakdown, a6 as LeaveRequestStatus, a5 as TaxStatus, a7 as LeaveType, a4 as TaxType, ai as PayrollStatus, ah as Department, ag as EmploymentType, aW as OrgRole, ao as LeaveInitConfig, aX as WorkSchedule, aY as PaymentFrequency, a9 as Allowance, ab as Deduction, af as BankDetails, _ as Compensation, aZ as TerminationReason, b as AttendanceInput } from './types-bZdAJueH.js';
+export { a_ as AccrueLeaveOptions, a$ as AllowanceType, b0 as AnyModel, b1 as BulkPayrollProgress, aa as CompensationBreakdownResult, b2 as DataRetentionConfig, b3 as DeductionType, b4 as EmployeeHiredEvent, b5 as EmployeeIdMode, b6 as EmployeeOperationParams, ad as EmployeeStatus, ae as EmployeeValidationResult, b7 as EmploymentConfig, b8 as EmploymentHistoryEntry, ak as ErrorCode, b9 as EventPayload, ba as EventPayloadBase, bb as FilterQuery, bc as GetEmployeeParams, bd as HRMTransactionCategory, aj as HttpError, al as LeaveBalance, be as LeaveHistoryFilters, an as LeaveSummaryResult, bf as Nullable, a8 as PayPeriodInfo, bg as PaymentMethod, bh as PayrollConfig, bi as PayrollCorrection, bj as PayrollEmployee, bk as PayrollEvent, bl as PayrollPeriod, bm as PayrollPlugin, bn as PayrollStats, n as PluginContext, bo as PluginFunction, o as PluginHooks, bp as PluginType, bq as PreTaxDeductionInput, br as QueryOptions, bs as RequestLeaveInput, bt as ResetAnnualLeaveOptions, bu as ReviewLeaveRequestInput, bv as RoleMappingConfig, bw as SalaryBand, bx as SalaryBandRange, by as SalaryConfig, bz as SalaryProcessedEvent, $ as TaxBracket, a0 as TaxCalculationOptions, ac as TaxCalculationResult, bA as TaxCreditInput, bB as TaxSummaryByType, bC as UserReference, bD as ValidationConfig, w as WebhookManager, bE as WithPayroll, am as WorkingDaysOptions, I as definePlugin } from './types-bZdAJueH.js';
 import * as mongoose from 'mongoose';
-import { ClientSession, Model, Schema, SchemaDefinition } from 'mongoose';
+import { ClientSession, Model, Schema, Types, Document, SchemaDefinition } from 'mongoose';
 import { ITransaction, ITransactionCreateInput } from '@classytic/shared-types';
-import { Plugin } from '@classytic/mongokit';
-export { L as LeaveRequestModel, P as PayrollSchemaOptions, T as TaxWithholdingModel, a as allowanceSchema, b as applyEmployeeIndexes, c as applyLeaveRequestIndexes, d as applyPayrollRecordIndexes, e as applyTaxWithholdingIndexes, f as bankDetailsSchema, g as compensationSchema, h as createEmployeeSchema, i as createEmploymentFields, j as createPayrollRecordFields, k as createPayrollRecordSchema, l as deductionSchema, m as employmentHistorySchema, n as getLeaveRequestFields, o as getLeaveRequestModel, p as getTaxWithholdingFields, q as getTaxWithholdingModel, r as leaveBalanceFields, s as leaveBalanceSchema, t as leaveRequestIndexes, u as leaveRequestSchema, v as payrollStatsSchema, w as taxWithholdingIndexes, x as taxWithholdingSchema, y as workScheduleSchema } from './index-DjB72l6e.js';
-export { P as ProRatingInput, b as ProRatingResult, a as applyProRating, c as calculateProRating, s as shouldProRate } from './prorating.calculator-C7sdFiG2.js';
-export { C as ContainerLike, D as DEFAULT_CARRY_OVER, a as DEFAULT_LEAVE_ALLOCATIONS, b as EmployeeIdType, c as EmployeeQueryFilter, R as ResolveOrganizationIdParams, S as SecureEmployeeLookupOptions, d as accrueLeaveToBalance, e as calculateCarryOver, f as calculateLeaveDays, g as calculateUnpaidLeaveDeduction, h as detectEmployeeIdType, i as employeeExistsSecure, j as findEmployeeSecure, k as findEmployeesSecure, l as formatEmployeeId, m as getAvailableDays, n as getLeaveBalance, o as getLeaveBalances, p as getLeaveSummary, q as getUnpaidLeaveDays, r as hasLeaveBalance, s as initializeLeaveBalances, t as isObjectIdEmployeeId, u as isStringEmployeeId, v as normalizeEmployeeId, w as proRateAllocation, x as requireOrganizationId, y as resolveOrganizationId, z as tryResolveOrganizationId, A as validateOrganizationId } from './employee-identity-Cq2wo9-2.js';
-export { AttendanceDeductionInput, AttendanceDeductionResult, ProcessedAllowance, ProcessedDeduction, SalaryCalculationInput, calculateAttendanceDeduction, calculateDailyRate, calculateHourlyRate, calculatePartialDayDeduction, calculateSalaryBreakdown, calculateTotalAttendanceDeduction } from './calculators/index.js';
+export { E as EMPLOYEE_TIMELINE_CONFIG, a as EmployeeStatusMachine, b as EmployeeStatusState, I as IdempotencyManager, c as IdempotentResult, L as LEAVE_REQUEST_TIMELINE_CONFIG, d as LeaveRequestStatusMachine, e as LeaveRequestStatusState, P as PAYROLL_EVENTS, f as PAYROLL_RECORD_TIMELINE_CONFIG, g as PayrollStatusMachine, h as PayrollStatusState, i as PayrollTimelineEvent, S as StateMachine, j as StateMachineConfig, k as StateTransition, T as TaxStatusMachine, l as TaxStatusState, m as TransitionResult, n as buildRequestContext, o as buildTimelineMetadata, p as createStateMachine, q as generatePayrollIdempotencyKey, r as multiTenantPlugin } from './payroll-states-DBt0XVm-.js';
+export { L as LeaveRequestModel, P as PayrollSchemaOptions, T as TaxWithholdingModel, a as allowanceSchema, b as applyEmployeeIndexes, c as applyLeaveRequestIndexes, d as applyPayrollRecordIndexes, e as applyTaxWithholdingIndexes, f as bankDetailsSchema, g as compensationSchema, h as createEmployeeSchema, i as createEmploymentFields, j as createPayrollRecordFields, k as createPayrollRecordSchema, l as deductionSchema, m as employeeIndexes, n as employmentHistorySchema, o as getLeaveRequestFields, p as getLeaveRequestModel, q as getTaxWithholdingFields, r as getTaxWithholdingModel, s as leaveBalanceFields, t as leaveBalanceSchema, u as leaveRequestIndexes, v as leaveRequestSchema, w as payrollRecordIndexes, x as payrollStatsSchema, y as taxWithholdingIndexes, z as taxWithholdingSchema, A as workScheduleSchema } from './index-BKLkuSAs.js';
+export { J as AlreadyProcessedError, C as ContainerLike, D as DEFAULT_CARRY_OVER, a as DEFAULT_LEAVE_ALLOCATIONS, b as DuplicateKeyErrorResult, K as DuplicatePayrollError, c as EmployeeIdType, L as EmployeeNotFoundError, d as EmployeeQueryFilter, M as EmployeeTerminatedError, N as InvalidEmployeeError, O as NotEligibleError, Q as NotInitializedError, U as PayrollError, P as PayrollErrorResult, R as ResolveOrganizationIdParams, S as SecureEmployeeLookupOptions, V as SecurityError, T as TransactionErrorResult, W as ValidationError, e as accrueLeaveToBalance, f as calculateCarryOver, g as calculateLeaveDays, h as calculateUnpaidLeaveDeduction, X as createError, i as detectEmployeeIdType, j as employeeExistsSecure, Y as extractErrorInfo, k as findEmployeeSecure, l as findEmployeesSecure, m as formatEmployeeId, n as formatUserError, o as getAvailableDays, p as getLeaveBalance, q as getLeaveBalances, r as getLeaveSummary, s as getUnpaidLeaveDays, t as handleDuplicateKeyError, u as handlePayrollError, v as handleTransactionError, w as hasLeaveBalance, x as initializeLeaveBalances, y as isObjectIdEmployeeId, Z as isPayrollError, z as isStringEmployeeId, A as normalizeEmployeeId, B as proRateAllocation, F as requireOrganizationId, G as resolveOrganizationId, $ as toPayrollError, H as tryResolveOrganizationId, I as validateOrganizationId } from './error-helpers-Bm6lMny2.js';
+export { P as ProRatingInput, a as ProRatingResult, b as applyProRating, c as calculateProRating, s as shouldProRate } from './prorating.calculator-C33fWBQf.js';
+export { A as AttendanceDeductionInput, a as AttendanceDeductionResult, P as ProcessedAllowance, b as ProcessedDeduction, S as SalaryCalculationInput, c as calculateAttendanceDeduction, d as calculateDailyRate, e as calculateHourlyRate, f as calculatePartialDayDeduction, g as calculateSalaryBreakdown, h as calculateTotalAttendanceDeduction } from './attendance.calculator-BZcv2iii.js';
+import { MongoServerError } from 'mongodb';
+import { Repository } from '@classytic/mongokit';
 import 'bson';
 
 /**
@@ -36,7 +38,6 @@ import 'bson';
  * ```
  */
 declare class Payroll<TEmployee extends EmployeeDocument = EmployeeDocument, TPayrollRecord extends PayrollRecordDocument = PayrollRecordDocument, TTransaction extends AnyDocument = AnyDocument, TAttendance extends AnyDocument = AnyDocument> implements PayrollInstance<TEmployee, TPayrollRecord, TTransaction, TAttendance> {
-    [key: string]: unknown;
     private _container;
     private _events;
     private _plugins;
@@ -352,10 +353,6 @@ declare class Payroll<TEmployee extends EmployeeDocument = EmployeeDocument, TPa
      * Get payroll summary
      */
     payrollSummary(params: PayrollSummaryParams): Promise<PayrollSummaryResult>;
-    /**
-     * Export payroll data
-     */
-    exportPayroll(params: ExportPayrollParams): Promise<TPayrollRecord[]>;
     /**
      * Void a payroll record (before payment)
      *
@@ -421,7 +418,7 @@ declare class Payroll<TEmployee extends EmployeeDocument = EmployeeDocument, TPa
      */
     markTaxWithholdingsPaid(params: MarkTaxPaidParams): Promise<{
         withholdings: TaxWithholdingDocument[];
-        transaction?: any;
+        transaction?: AnyDocument;
     }>;
     /**
      * Calculate salary breakdown
@@ -429,11 +426,92 @@ declare class Payroll<TEmployee extends EmployeeDocument = EmployeeDocument, TPa
      * Delegates to pure calculator for testability and reusability
      */
     private calculateSalaryBreakdown;
+    private updatePayrollStats;
     /**
-     * Calculate attendance deduction using working days (not calendar days)
+     * Recover stuck payroll records
+     *
+     * Finds payroll records stuck in 'processing' or 'pending' status for longer
+     * than the threshold and handles them appropriately:
+     * - Records WITHOUT transactionId: Marked as 'failed' (safe to retry)
+     * - Records WITH transactionId: Flagged for manual review (orphaned transaction)
+     *
+     * This helps recover from server crashes or partial failures.
+     *
+     * @example
+     * ```typescript
+     * const recovered = await payroll.recoverStuckPayrolls({
+     *   organizationId: org._id,
+     *   staleThresholdMinutes: 30,
+     * });
+     * console.log(`Recovered ${recovered.markedFailed} records`);
+     * if (recovered.requiresManualReview.length > 0) {
+     *   console.warn('Manual review needed:', recovered.requiresManualReview);
+     * }
+     * ```
      */
-    private calculateAttendanceDeduction;
-    private updatePayrollStats;
+    recoverStuckPayrolls(params: {
+        organizationId: ObjectIdLike;
+        staleThresholdMinutes?: number;
+        dryRun?: boolean;
+    }): Promise<{
+        markedFailed: number;
+        requiresManualReview: Array<{
+            _id: ObjectId;
+            status: string;
+            transactionId?: ObjectId;
+        }>;
+        scanned: number;
+    }>;
+    /**
+     * Prepare payroll data for export (Phase 1)
+     *
+     * Retrieves records but does NOT mark them as exported yet.
+     * Returns an exportId that must be used to confirm or cancel the export.
+     *
+     * @example
+     * ```typescript
+     * // Phase 1: Prepare
+     * const { records, exportId } = await payroll.prepareExport({
+     *   organizationId: org._id,
+     *   startDate: new Date('2024-01-01'),
+     *   endDate: new Date('2024-01-31'),
+     * });
+     *
+     * // Send records to external system...
+     *
+     * // Phase 2: Confirm (if successful) or Cancel (if failed)
+     * await payroll.confirmExport({ organizationId: org._id, exportId });
+     * ```
+     */
+    prepareExport(params: ExportPayrollParams): Promise<{
+        records: TPayrollRecord[];
+        exportId: string;
+        total: number;
+    }>;
+    /**
+     * Confirm export success (Phase 2a)
+     *
+     * Marks records as exported after downstream system confirms receipt.
+     */
+    confirmExport(params: {
+        organizationId: ObjectIdLike;
+        exportId: string;
+    }): Promise<{
+        confirmed: number;
+    }>;
+    /**
+     * Cancel export (Phase 2b)
+     *
+     * Called when downstream system fails to process the export.
+     * Records remain unmarked and can be exported again.
+     */
+    cancelExport(params: {
+        organizationId: ObjectIdLike;
+        exportId: string;
+        reason?: string;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
     /**
      * Create a new Payroll instance with default types
      */
@@ -642,537 +720,6 @@ declare class TransactionFactory {
     static createTaxPaymentTransaction: typeof createTaxPaymentTransaction;
 }
 
-/**
- * Idempotency Manager
- *
- * Ensures operations are not duplicated when called with the same key.
- * Uses Stripe-style idempotency pattern for payroll operations.
- *
- * ## Important: In-Memory Cache Limitations
- *
- * This implementation uses an **in-memory LRU cache** which has the following limitations:
- *
- * - **Does NOT persist across server restarts** - cache is lost on restart
- * - **Does NOT work across multiple server instances** - each instance has its own cache
- * - **Only prevents duplicates within the same process lifetime**
- *
- * For production deployments with horizontal scaling or high availability requirements,
- * you should implement database-backed idempotency. See the Payroll class documentation
- * for implementation examples.
- *
- * The database's unique index on `{ employeeId, period.month, period.year }` serves as
- * the primary duplicate protection - this cache is a secondary optimization layer.
- *
- * @see https://stripe.com/docs/api/idempotent_requests
- */
-
-interface IdempotentResult<T = any> {
-    value: T;
-    cached: boolean;
-    createdAt: Date;
-}
-/**
- * In-memory idempotency manager for preventing duplicate operations.
- *
- * @warning This is an in-memory cache. For production horizontal scaling,
- * implement database-backed idempotency instead.
- */
-declare class IdempotencyManager {
-    private cache;
-    private static hasLoggedWarning;
-    constructor(options?: {
-        max?: number;
-        ttl?: number;
-        suppressWarning?: boolean;
-    });
-    /**
-     * Check if key exists and return cached result
-     */
-    get<T>(key: string): IdempotentResult<T> | null;
-    /**
-     * Store result for idempotency key
-     */
-    set<T>(key: string, value: T): void;
-    /**
-     * Execute function with idempotency protection
-     */
-    execute<T>(key: string, fn: () => Promise<T>): Promise<IdempotentResult<T>>;
-    /**
-     * Clear a specific key
-     */
-    delete(key: string): void;
-    /**
-     * Clear all keys
-     */
-    clear(): void;
-    /**
-     * Get cache stats
-     */
-    stats(): {
-        size: number;
-        max: number;
-    };
-}
-/**
- * Generate idempotency key for payroll operations
- */
-declare function generatePayrollIdempotencyKey(organizationId: ObjectIdLike, employeeId: ObjectIdLike, month: number, year: number): string;
-
-/**
- * Repository plugins for mongokit integration
- */
-
-/**
- * Multi-tenant plugin - automatically injects organizationId into queries
- */
-declare function multiTenantPlugin(organizationId?: ObjectId): Plugin;
-
-/**
- * @classytic/payroll - Timeline Audit Integration
- *
- * Integration with @classytic/mongoose-timeline-audit for comprehensive audit trails.
- * Provides automatic tracking of WHO performed WHAT action and WHEN.
- *
- * ## Setup
- *
- * 1. Install mongoose-timeline-audit:
- *    ```bash
- *    npm install @classytic/mongoose-timeline-audit
- *    ```
- *
- * 2. Apply to your schemas BEFORE registering with Mongoose:
- *    ```typescript
- *    import timelineAuditPlugin from '@classytic/mongoose-timeline-audit';
- *    import { PAYROLL_EVENTS } from '@classytic/payroll';
- *
- *    // Apply to Employee schema
- *    employeeSchema.plugin(timelineAuditPlugin, {
- *      ownerField: 'organizationId',
- *      eventLimits: PAYROLL_EVENTS.EMPLOYEE.limits,
- *    });
- *
- *    // Apply to PayrollRecord schema
- *    payrollRecordSchema.plugin(timelineAuditPlugin, {
- *      ownerField: 'organizationId',
- *      eventLimits: PAYROLL_EVENTS.PAYROLL.limits,
- *    });
- *    ```
- *
- * 3. Use the Payroll events to add timeline entries:
- *    ```typescript
- *    payroll.on('employee:hired', async ({ data }) => {
- *      const employee = await Employee.findById(data.employee.id);
- *      employee.addTimelineEvent(
- *        PAYROLL_EVENTS.EMPLOYEE.HIRED,
- *        `Hired as ${data.employee.position}`,
- *        request,  // Express request for actor tracking
- *        { department: data.employee.department }
- *      );
- *      await employee.save();
- *    });
- *    ```
- *
- * @module @classytic/payroll/timeline-audit
- */
-/**
- * Standard payroll events for timeline tracking
- *
- * Use these constants with mongoose-timeline-audit's addTimelineEvent()
- * to maintain consistent event naming across your application.
- */
-declare const PAYROLL_EVENTS: {
-    /**
-     * Employee lifecycle events
-     */
-    readonly EMPLOYEE: {
-        /** Employee was hired */
-        readonly HIRED: "employee.hired";
-        /** Employee was terminated */
-        readonly TERMINATED: "employee.terminated";
-        /** Employee was re-hired after termination */
-        readonly REHIRED: "employee.rehired";
-        /** Employee status changed (active, on_leave, suspended) */
-        readonly STATUS_CHANGED: "employee.status_changed";
-        /** Employee department/position changed */
-        readonly ROLE_CHANGED: "employee.role_changed";
-        /** Employee probation ended */
-        readonly PROBATION_ENDED: "employee.probation_ended";
-        /** Recommended event limits for employee timeline */
-        readonly limits: {
-            readonly 'employee.status_changed': 50;
-            readonly 'employee.role_changed': 20;
-        };
-    };
-    /**
-     * Compensation events
-     */
-    readonly COMPENSATION: {
-        /** Base salary was updated */
-        readonly SALARY_UPDATED: "compensation.salary_updated";
-        /** Allowance was added */
-        readonly ALLOWANCE_ADDED: "compensation.allowance_added";
-        /** Allowance was removed */
-        readonly ALLOWANCE_REMOVED: "compensation.allowance_removed";
-        /** Deduction was added */
-        readonly DEDUCTION_ADDED: "compensation.deduction_added";
-        /** Deduction was removed */
-        readonly DEDUCTION_REMOVED: "compensation.deduction_removed";
-        /** Bank details were updated */
-        readonly BANK_UPDATED: "compensation.bank_updated";
-        /** Recommended event limits */
-        readonly limits: {
-            readonly 'compensation.salary_updated': 24;
-            readonly 'compensation.allowance_added': 20;
-            readonly 'compensation.allowance_removed': 20;
-            readonly 'compensation.deduction_added': 20;
-            readonly 'compensation.deduction_removed': 20;
-            readonly 'compensation.bank_updated': 10;
-        };
-    };
-    /**
-     * Payroll processing events
-     */
-    readonly PAYROLL: {
-        /** Salary was processed */
-        readonly PROCESSED: "payroll.processed";
-        /** Payroll was voided (before payment) */
-        readonly VOIDED: "payroll.voided";
-        /** Payroll was reversed (after payment) */
-        readonly REVERSED: "payroll.reversed";
-        /** Payroll was restored from voided state */
-        readonly RESTORED: "payroll.restored";
-        /** Payroll export was generated */
-        readonly EXPORTED: "payroll.exported";
-        /** Recommended event limits */
-        readonly limits: {
-            readonly 'payroll.processed': 36;
-            readonly 'payroll.voided': 10;
-            readonly 'payroll.reversed': 10;
-            readonly 'payroll.restored': 5;
-            readonly 'payroll.exported': 20;
-        };
-    };
-    /**
-     * Tax withholding events
-     */
-    readonly TAX: {
-        /** Tax was withheld */
-        readonly WITHHELD: "tax.withheld";
-        /** Tax was submitted to authorities */
-        readonly SUBMITTED: "tax.submitted";
-        /** Tax payment was made */
-        readonly PAID: "tax.paid";
-        /** Tax withholding was cancelled */
-        readonly CANCELLED: "tax.cancelled";
-        /** Recommended event limits */
-        readonly limits: {
-            readonly 'tax.withheld': 36;
-            readonly 'tax.submitted': 12;
-            readonly 'tax.paid': 12;
-            readonly 'tax.cancelled': 10;
-        };
-    };
-    /**
-     * Leave management events
-     */
-    readonly LEAVE: {
-        /** Leave was requested */
-        readonly REQUESTED: "leave.requested";
-        /** Leave was approved */
-        readonly APPROVED: "leave.approved";
-        /** Leave was rejected */
-        readonly REJECTED: "leave.rejected";
-        /** Leave was cancelled */
-        readonly CANCELLED: "leave.cancelled";
-        /** Leave balance was accrued */
-        readonly ACCRUED: "leave.accrued";
-        /** Annual leave was reset */
-        readonly RESET: "leave.reset";
-        /** Recommended event limits */
-        readonly limits: {
-            readonly 'leave.requested': 50;
-            readonly 'leave.approved': 50;
-            readonly 'leave.rejected': 20;
-            readonly 'leave.cancelled': 20;
-            readonly 'leave.accrued': 12;
-            readonly 'leave.reset': 5;
-        };
-    };
-};
-/**
- * All payroll event types (for TypeScript)
- */
-type PayrollTimelineEvent = typeof PAYROLL_EVENTS.EMPLOYEE[keyof typeof PAYROLL_EVENTS.EMPLOYEE] | typeof PAYROLL_EVENTS.COMPENSATION[keyof typeof PAYROLL_EVENTS.COMPENSATION] | typeof PAYROLL_EVENTS.PAYROLL[keyof typeof PAYROLL_EVENTS.PAYROLL] | typeof PAYROLL_EVENTS.TAX[keyof typeof PAYROLL_EVENTS.TAX] | typeof PAYROLL_EVENTS.LEAVE[keyof typeof PAYROLL_EVENTS.LEAVE];
-/**
- * Recommended timeline audit configuration for Employee model
- */
-declare const EMPLOYEE_TIMELINE_CONFIG: {
-    ownerField: string;
-    fieldName: string;
-    hideByDefault: boolean;
-    eventLimits: {
-        'compensation.salary_updated': 24;
-        'compensation.allowance_added': 20;
-        'compensation.allowance_removed': 20;
-        'compensation.deduction_added': 20;
-        'compensation.deduction_removed': 20;
-        'compensation.bank_updated': 10;
-        'employee.status_changed': 50;
-        'employee.role_changed': 20;
-    };
-};
-/**
- * Recommended timeline audit configuration for PayrollRecord model
- */
-declare const PAYROLL_RECORD_TIMELINE_CONFIG: {
-    ownerField: string;
-    fieldName: string;
-    hideByDefault: boolean;
-    eventLimits: {
-        readonly 'payroll.processed': 36;
-        readonly 'payroll.voided': 10;
-        readonly 'payroll.reversed': 10;
-        readonly 'payroll.restored': 5;
-        readonly 'payroll.exported': 20;
-    };
-};
-/**
- * Recommended timeline audit configuration for LeaveRequest model
- */
-declare const LEAVE_REQUEST_TIMELINE_CONFIG: {
-    ownerField: string;
-    fieldName: string;
-    hideByDefault: boolean;
-    eventLimits: {
-        readonly 'leave.requested': 50;
-        readonly 'leave.approved': 50;
-        readonly 'leave.rejected': 20;
-        readonly 'leave.cancelled': 20;
-        readonly 'leave.accrued': 12;
-        readonly 'leave.reset': 5;
-    };
-};
-/**
- * Build timeline event metadata from payroll context
- *
- * @param context - Operation context from payroll methods
- * @returns Metadata object for timeline event
- *
- * @example
- * ```typescript
- * employee.addTimelineEvent(
- *   PAYROLL_EVENTS.EMPLOYEE.HIRED,
- *   'Hired as Software Engineer',
- *   request,
- *   buildTimelineMetadata(params.context)
- * );
- * ```
- */
-declare function buildTimelineMetadata(context?: {
-    userId?: unknown;
-    userName?: string;
-    userRole?: string;
-    organizationId?: unknown;
-}): Record<string, unknown>;
-/**
- * Build context object for timeline event (IP, user agent, etc.)
- *
- * @param request - Express/Fastify request object
- * @returns Context object for timeline event
- *
- * @example
- * ```typescript
- * employee.addTimelineEvent(
- *   PAYROLL_EVENTS.COMPENSATION.SALARY_UPDATED,
- *   `Salary updated to ${newSalary}`,
- *   request,
- *   { previousSalary, newSalary },
- *   buildRequestContext(request)
- * );
- * ```
- */
-declare function buildRequestContext(request?: {
-    ip?: string;
-    headers?: Record<string, string | string[] | undefined>;
-    get?: (header: string) => string | undefined;
-}): Record<string, unknown> | undefined;
-
-/**
- * @classytic/payroll - State Machine
- *
- * Minimal state machine implementation for status management.
- * Enforces valid transitions and provides clear error messages.
- */
-/**
- * State transition definition
- */
-interface StateTransition<TState extends string> {
-    from: TState | TState[];
-    to: TState;
-}
-/**
- * State machine configuration
- */
-interface StateMachineConfig<TState extends string> {
-    /** All valid states */
-    states: readonly TState[];
-    /** Initial state */
-    initial: TState;
-    /** Valid transitions */
-    transitions: StateTransition<TState>[];
-    /** Terminal states (no outgoing transitions) */
-    terminal?: TState[];
-}
-/**
- * Transition result
- */
-type TransitionResult<TState extends string> = {
-    success: true;
-    from: TState;
-    to: TState;
-} | {
-    success: false;
-    from: TState;
-    to: TState;
-    error: string;
-};
-/**
- * Minimal state machine for status management
- *
- * @example
- * const machine = new StateMachine({
- *   states: ['pending', 'processing', 'paid', 'voided'] as const,
- *   initial: 'pending',
- *   transitions: [
- *     { from: 'pending', to: 'processing' },
- *     { from: 'pending', to: 'voided' },
- *     { from: 'processing', to: 'paid' },
- *   ],
- *   terminal: ['paid', 'voided'],
- * });
- *
- * machine.canTransition('pending', 'processing'); // true
- * machine.canTransition('paid', 'pending'); // false
- */
-declare class StateMachine<TState extends string> {
-    private readonly config;
-    private readonly validTransitions;
-    private readonly terminalStates;
-    constructor(config: StateMachineConfig<TState>);
-    /**
-     * Get the initial state
-     */
-    get initial(): TState;
-    /**
-     * Get all valid states
-     */
-    get states(): readonly TState[];
-    /**
-     * Check if a state is valid
-     */
-    isValidState(state: string): state is TState;
-    /**
-     * Check if a state is terminal (no outgoing transitions)
-     */
-    isTerminal(state: TState): boolean;
-    /**
-     * Check if transition from one state to another is valid
-     */
-    canTransition(from: TState, to: TState): boolean;
-    /**
-     * Get all valid next states from current state
-     */
-    getNextStates(from: TState): TState[];
-    /**
-     * Validate a transition and return result
-     */
-    validateTransition(from: TState, to: TState): TransitionResult<TState>;
-    /**
-     * Assert a transition is valid, throw if not
-     */
-    assertTransition(from: TState, to: TState): void;
-}
-/**
- * Create a state machine instance
- */
-declare function createStateMachine<TState extends string>(config: StateMachineConfig<TState>): StateMachine<TState>;
-
-/**
- * @classytic/payroll - Payroll State Machines
- *
- * Defines valid state transitions for all status types.
- * Single source of truth for status management.
- */
-
-/**
- * PayrollStatus state machine
- *
- * State diagram:
- * ```
- * PENDING ──┬──> PROCESSING ──┬──> PAID ──> REVERSED
- *           │        │        │
- *           │        │        └──> FAILED ──┐
- *           │        │                      │
- *           │        └──> VOIDED <──────────┘
- *           │              ↑
- *           └──────────────┘
- * ```
- *
- * - PENDING: Initial state, payroll created but not processed
- * - PROCESSING: Currently being processed (bulk operations)
- * - PAID: Payment completed successfully
- * - FAILED: Processing failed (can retry → pending, or void)
- * - VOIDED: Cancelled before payment (can restore → pending)
- * - REVERSED: Payment reversed after completion (terminal)
- */
-declare const PayrollStatusMachine: StateMachine<"pending" | "processing" | "paid" | "failed" | "voided" | "reversed">;
-type PayrollStatusState = typeof PayrollStatusMachine.states[number];
-/**
- * TaxStatus state machine
- *
- * State diagram:
- * ```
- * PENDING ──┬──> SUBMITTED ──> PAID
- *           │
- *           └──> CANCELLED
- * ```
- *
- * - PENDING: Tax withheld, not yet submitted to government
- * - SUBMITTED: Submitted to tax authority, awaiting confirmation
- * - PAID: Payment confirmed by tax authority
- * - CANCELLED: Invalidated (payroll voided/reversed)
- */
-declare const TaxStatusMachine: StateMachine<"pending" | "paid" | "cancelled" | "submitted">;
-type TaxStatusState = typeof TaxStatusMachine.states[number];
-/**
- * LeaveRequestStatus state machine
- *
- * State diagram:
- * ```
- * PENDING ──┬──> APPROVED
- *           │
- *           ├──> REJECTED
- *           │
- *           └──> CANCELLED
- * ```
- */
-declare const LeaveRequestStatusMachine: StateMachine<"pending" | "approved" | "rejected" | "cancelled">;
-type LeaveRequestStatusState = typeof LeaveRequestStatusMachine.states[number];
-/**
- * EmployeeStatus state machine
- *
- * State diagram:
- * ```
- * ACTIVE ←──┬──→ ON_LEAVE
- *           │
- *           ├──→ SUSPENDED ──→ ACTIVE
- *           │
- *           └──→ TERMINATED
- * ```
- */
-declare const EmployeeStatusMachine: StateMachine<"active" | "on_leave" | "suspended" | "terminated">;
-type EmployeeStatusState = typeof EmployeeStatusMachine.states[number];
-
 declare const EMPLOYMENT_TYPE: {
     readonly FULL_TIME: "full_time";
     readonly PART_TIME: "part_time";
@@ -1536,111 +1083,6 @@ declare class EmployeeBuilder {
  */
 declare function createEmployee(): EmployeeBuilder;
 
-/**
- * @classytic/payroll - Error Handling
- *
- * Custom error classes with error codes and HTTP status
- */
-
-declare class PayrollError extends Error implements HttpError {
-    readonly code: ErrorCode;
-    readonly status: number;
-    readonly context: Record<string, unknown>;
-    readonly timestamp: Date;
-    /**
-     * Create a PayrollError.
-     *
-     * Supports BOTH constructor styles for backwards compatibility:
-     * - new PayrollError(message, code?, status?, context?)
-     * - new PayrollError(code, status, message, context?)
-     */
-    constructor(messageOrCode: string | ErrorCode, codeOrStatus?: ErrorCode | number, statusOrMessage?: number | string, context?: Record<string, unknown>);
-    /**
-     * Convert error to JSON for API responses (ClockIn-compatible shape)
-     */
-    toJSON(): Record<string, unknown>;
-    /**
-     * Check if error is operational (expected) vs programmer error
-     */
-    isOperational(): boolean;
-}
-/**
- * Not initialized error
- */
-declare class NotInitializedError extends PayrollError {
-    constructor(message?: string);
-}
-/**
- * Employee not found error
- */
-declare class EmployeeNotFoundError extends PayrollError {
-    constructor(employeeId?: string, context?: Record<string, unknown>);
-}
-/**
- * Invalid employee error
- */
-declare class InvalidEmployeeError extends PayrollError {
-    constructor(message: string, context?: Record<string, unknown>);
-}
-/**
- * Duplicate payroll error
- */
-declare class DuplicatePayrollError extends PayrollError {
-    constructor(employeeId: string, month: number, year: number, context?: Record<string, unknown>);
-}
-/**
- * Validation error
- */
-declare class ValidationError extends PayrollError {
-    readonly errors: string[];
-    constructor(errors: string | string[], context?: Record<string, unknown>);
-}
-/**
- * Employee terminated error
- */
-declare class EmployeeTerminatedError extends PayrollError {
-    constructor(employeeId?: string, context?: Record<string, unknown>);
-}
-/**
- * Already processed error
- */
-declare class AlreadyProcessedError extends PayrollError {
-    constructor(message: string, context?: Record<string, unknown>);
-}
-/**
- * Not eligible error
- */
-declare class NotEligibleError extends PayrollError {
-    constructor(message: string, context?: Record<string, unknown>);
-}
-/**
- * Security error (unauthorized access, cross-organization access, etc.)
- */
-declare class SecurityError extends PayrollError {
-    constructor(message: string, context?: Record<string, unknown>);
-}
-/**
- * Create error from code
- */
-declare function createError(code: ErrorCode, message: string, context?: Record<string, unknown>): PayrollError;
-/**
- * Check if error is PayrollError
- */
-declare function isPayrollError(error: unknown): error is PayrollError;
-/**
- * Extract error info for logging
- */
-declare function extractErrorInfo(error: unknown): {
-    code: string;
-    status: number;
-    message: string;
-    context?: Record<string, unknown>;
-};
-/**
- * Convert unknown error to PayrollError
- */
-declare function toPayrollError(error: unknown): PayrollError;
-
 /**
  * @classytic/payroll - Attendance Integration
  *
@@ -1714,7 +1156,7 @@ declare function batchGetAttendance(AttendanceModel: Model<unknown>, params: {
  * Holiday document
  */
 interface Holiday {
-    organizationId?: any;
+    organizationId?: Types.ObjectId;
     date: Date;
     name: string;
     type: 'public' | 'company' | 'religious';
@@ -1749,8 +1191,8 @@ declare function createHolidaySchema(options?: {
  * });
  * ```
  */
-declare function getHolidays(HolidayModel: Model<any>, params: {
-    organizationId?: any;
+declare function getHolidays(HolidayModel: Model<Holiday>, params: {
+    organizationId?: Types.ObjectId;
     startDate: Date;
     endDate: Date;
 }): Promise<Date[]>;
@@ -2918,7 +2360,325 @@ interface AttendancePolicyDocument {
  * Static methods interface
  */
 interface AttendancePolicyModel {
-    findActiveForOrganization(organizationId: any, date?: Date): Promise<any>;
+    findActiveForOrganization(organizationId: Types.ObjectId, date?: Date): Promise<Document | null>;
+}
+
+/**
+ * @classytic/payroll - Type Guards
+ *
+ * Type-safe utilities for runtime type checking,
+ * especially for error handling and MongoDB errors.
+ *
+ * @module @classytic/payroll/utils/type-guards
+ */
+
+/**
+ * Check if error is a MongoDB error
+ *
+ * @param error - Unknown error object
+ * @returns True if MongoDB error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await model.create(data);
+ * } catch (error) {
+ *   if (isMongoError(error)) {
+ *     console.log('MongoDB error code:', error.code);
+ *   }
+ * }
+ * ```
+ */
+declare function isMongoError(error: unknown): error is MongoServerError;
+/**
+ * Check if error is a MongoDB duplicate key error (E11000)
+ *
+ * @param error - Unknown error object
+ * @returns True if duplicate key error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await PayrollModel.create(record);
+ * } catch (error) {
+ *   if (isDuplicateKeyError(error)) {
+ *     const field = parseDuplicateKeyError(error);
+ *     throw new DuplicatePayrollError(`Duplicate ${field}`);
+ *   }
+ * }
+ * ```
+ */
+declare function isDuplicateKeyError(error: unknown): error is MongoServerError & {
+    code: 11000;
+};
+/**
+ * Parse field name from MongoDB duplicate key error
+ *
+ * @param error - MongoDB duplicate key error
+ * @returns Field name that caused the duplicate, or 'unknown'
+ *
+ * @example
+ * ```typescript
+ * if (isDuplicateKeyError(error)) {
+ *   const field = parseDuplicateKeyError(error);
+ *   // field might be 'employeeId', 'email', etc.
+ * }
+ * ```
+ */
+declare function parseDuplicateKeyError(error: MongoServerError): string;
+/**
+ * Check if error is a MongoDB transaction error
+ *
+ * @param error - Unknown error object
+ * @returns True if transaction-related error
+ */
+declare function isTransactionError(error: unknown): error is MongoServerError;
+/**
+ * Check if MongoDB transactions are unsupported (standalone server)
+ *
+ * @param error - Unknown error object
+ * @returns True if error indicates transactions are not supported
+ */
+declare function isTransactionUnsupportedError(error: unknown): boolean;
+/**
+ * Check if error is a connection error
+ *
+ * @param error - Unknown error object
+ * @returns True if connection error
+ */
+declare function isConnectionError(error: unknown): error is MongoServerError;
+/**
+ * Type guard: Check if employee is a guest employee (no userId)
+ *
+ * @param employee - Employee document
+ * @returns True if guest employee
+ *
+ * @example
+ * ```typescript
+ * if (isGuestEmployee(employee)) {
+ *   // Handle guest-specific logic
+ *   console.log('Guest employee:', employee.email);
+ * }
+ * ```
+ */
+declare function isGuestEmployee(employee: EmployeeDocument): boolean;
+/**
+ * Type guard: Check if employee has a user ID
+ *
+ * @param employee - Employee document
+ * @returns True if employee has userId (not guest)
+ */
+declare function hasUserId(employee: EmployeeDocument): employee is EmployeeDocument & {
+    userId: NonNullable<EmployeeDocument['userId']>;
+};
+/**
+ * Check if error is a validation error
+ *
+ * @param error - Unknown error object
+ * @returns True if Mongoose/MongoDB validation error
+ */
+declare function isValidationError(error: unknown): error is Error & {
+    name: 'ValidationError';
+};
+/**
+ * Type guard for Error instances
+ *
+ * @param error - Unknown value
+ * @returns True if Error instance
+ */
+declare function isError(error: unknown): error is Error;
+/**
+ * Safe error message extraction
+ *
+ * @param error - Unknown error object
+ * @returns Error message or generic fallback
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await dangerousOperation();
+ * } catch (error) {
+ *   logger.error(getErrorMessage(error));
+ * }
+ * ```
+ */
+declare function getErrorMessage(error: unknown): string;
+
+/**
+ * Safely get email from employee (guest or regular)
+ *
+ * @param employee - Employee document
+ * @returns Email address or undefined
+ *
+ * @example
+ * ```typescript
+ * const email = getEmployeeEmail(employee);
+ * if (email) {
+ *   sendNotification(email, 'Payroll processed');
+ * }
+ * ```
+ */
+declare function getEmployeeEmail(employee: EmployeeDocument): string | undefined;
+/**
+ * Get employee name (from userId if populated, fallback to employeeId)
+ *
+ * @param employee - Employee document
+ * @returns Employee name or employee ID
+ *
+ * @example
+ * ```typescript
+ * const name = getEmployeeName(employee);
+ * console.log(`Processing payroll for ${name}`);
+ * ```
+ */
+declare function getEmployeeName(employee: EmployeeDocument): string;
+
+/**
+ * @classytic/payroll - Payroll Audit Plugin
+ *
+ * Mongokit plugin for automatic audit trail capture on all payroll operations.
+ * Auto-captures who/when/where for creates and updates.
+ *
+ * @module @classytic/payroll/core/mongokit-plugins/payroll-audit
+ */
+
+/**
+ * Audit context configuration
+ */
+interface AuditContext {
+    /** User ID performing the operation */
+    userId?: ObjectId;
+    /** User name (optional, for logging) */
+    userName?: string;
+    /** Organization ID (for multi-tenant operations) */
+    organizationId?: ObjectId;
+}
+/**
+ * Payroll audit trail plugin
+ *
+ * Automatically captures audit information on create and update operations:
+ * - Creates: Sets createdBy, createdAt, organizationId
+ * - Updates: Sets updatedBy, updatedAt
+ *
+ * @param context - Audit context with user and organization info
+ * @returns Mongokit plugin function
+ *
+ * @example
+ * ```typescript
+ * // Single-tenant mode with audit
+ * const repos = {
+ *   payrollRecord: new Repository(PayrollRecordModel, [
+ *     payrollAuditPlugin({ userId: admin._id, organizationId: org._id }),
+ *   ]),
+ * };
+ *
+ * // Create will automatically set createdBy and createdAt
+ * const record = await repos.payrollRecord.create({
+ *   employeeId: emp._id,
+ *   // ... other fields
+ *   // createdBy and createdAt will be auto-added
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multi-tenant mode with audit and multi-tenant plugin
+ * import { multiTenantPlugin } from '../repository-plugins.js';
+ *
+ * const repos = {
+ *   employee: new Repository(EmployeeModel, [
+ *     multiTenantPlugin(orgId),           // First: enforce multi-tenancy
+ *     payrollAuditPlugin({ userId, organizationId: orgId }), // Second: audit trail
+ *   ]),
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Per-request audit context
+ * function createAuditedRepos(req: Request) {
+ *   const context = {
+ *     userId: req.user._id,
+ *     userName: req.user.name,
+ *     organizationId: req.organization._id,
+ *   };
+ *
+ *   return {
+ *     payrollRecord: new Repository(PayrollRecordModel, [
+ *       payrollAuditPlugin(context),
+ *     ]),
+ *   };
+ * }
+ * ```
+ */
+declare function payrollAuditPlugin(context: AuditContext): (repo: Repository) => void;
+/**
+ * Read-only audit plugin (tracks access without modification)
+ *
+ * Logs who accessed what data, useful for compliance and security auditing.
+ *
+ * @param context - Audit context
+ * @param logger - Optional logger function
+ * @returns Mongokit plugin function
+ *
+ * @example
+ * ```typescript
+ * const repos = {
+ *   employee: new Repository(EmployeeModel, [
+ *     readAuditPlugin(
+ *       { userId: user._id, organizationId: org._id },
+ *       (event) => console.log('Access log:', event)
+ *     ),
+ *   ]),
+ * };
+ *
+ * // This will log the access
+ * await repos.employee.getById(employeeId);
+ * ```
+ */
+declare function readAuditPlugin(context: AuditContext, logger?: (event: AuditEvent) => void): (repo: Repository) => void;
+/**
+ * Audit event structure
+ */
+interface AuditEvent {
+    /** Operation type */
+    operation: 'create' | 'read' | 'update' | 'delete';
+    /** Model name */
+    model: string;
+    /** User performing operation */
+    userId?: ObjectId;
+    /** Organization context */
+    organizationId?: ObjectId;
+    /** When the operation occurred */
+    timestamp: Date;
+    /** Query or data involved */
+    query?: Record<string, unknown>;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
 }
+/**
+ * Full audit trail plugin (create/read/update/delete)
+ *
+ * Combines both modification and access audit trails.
+ *
+ * @param context - Audit context
+ * @param onEvent - Event handler for all audit events
+ * @returns Mongokit plugin function
+ *
+ * @example
+ * ```typescript
+ * const auditLog: AuditEvent[] = [];
+ *
+ * const repos = {
+ *   payrollRecord: new Repository(PayrollRecordModel, [
+ *     fullAuditPlugin(
+ *       { userId: admin._id, organizationId: org._id },
+ *       (event) => auditLog.push(event)
+ *     ),
+ *   ]),
+ * };
+ * ```
+ */
+declare function fullAuditPlugin(context: AuditContext, onEvent: (event: AuditEvent) => void | Promise<void>): (repo: Repository) => void;
 
-export { ALLOWANCE_TYPE, AddAllowanceParams, AddDeductionParams, Allowance, AlreadyProcessedError, AnyDocument, type AttendancePolicy, AttendancePolicyBuilder, type AttendancePolicyDocument, type AttendancePolicyModel, AttendancePolicySchema, AttendancePolicySchemaDefinition, BankDetails, BulkPayrollResult, type CalculateShiftComplianceInput, type ClockRoundingPolicy, ClockRoundingPolicyBuilder, ClockRoundingPolicySchema, ClockRoundingPolicySchemaDefinition, Compensation, type CreateEmployeeParams, type CreatePayrollTransactionInput, type CreateTaxPaymentTransactionInput, DEDUCTION_TYPE, DEFAULT_ATTENDANCE_POLICY, DEPARTMENT, Deduction, DeepPartial, Department, DuplicatePayrollError, EMPLOYEE_STATUS, EMPLOYEE_TIMELINE_CONFIG, EMPLOYMENT_TYPE, type EarlyDeparturePenaltyResult, type EarlyDeparturePolicy, EarlyDeparturePolicySchema, EarlyDeparturePolicySchemaDefinition, type EarlyOccurrence, EmployeeBuilder, type EmployeeData, EmployeeDocument, EmployeeFactory, EmployeeIdentityMode, EmployeeNotFoundError, type EmployeePluginOptions, EmployeeStatusMachine, type EmployeeStatusState, EmployeeTerminatedError, EmploymentType, ErrorCode, ExportPayrollParams, GetPendingTaxParams, HEALTHCARE_POLICY, HOSPITALITY_POLICY, HRMConfig, HRM_CONFIG, HireEmployeeParams, type Holiday, HttpError, type IPayrollTransaction, type IPayrollTransactionCreateInput, IdempotencyManager, type IdempotentResult, InvalidEmployeeError, LEAVE_REQUEST_STATUS, LEAVE_REQUEST_TIMELINE_CONFIG, LEAVE_TYPE, type LateArrivalPolicy, LateArrivalPolicySchema, LateArrivalPolicySchemaDefinition, type LateOccurrence, type LatePenaltyResult, LatePolicyBuilder, LeaveInitConfig, LeaveRequestDocument, LeaveRequestStatus, LeaveRequestStatusMachine, type LeaveRequestStatusState, LeaveType, Logger, MANUFACTURING_POLICY, MarkTaxPaidParams, type MaxPenaltiesPerPeriod, MaxPenaltiesSchema, MaxPenaltiesSchemaDefinition, type NightShiftDifferential, NightShiftDifferentialSchema, NightShiftDifferentialSchemaDefinition, NotEligibleError, NotInitializedError, OFFICE_POLICY, ObjectIdLike, OperationContext, OrgRole, type OvertimeBonusResult, type OvertimeMode, type OvertimeOccurrence, type OvertimePolicy, OvertimePolicyBuilder, OvertimePolicySchema, OvertimePolicySchemaDefinition, PAYMENT_FREQUENCY, PAYROLL_EVENTS, PAYROLL_RECORD_TIMELINE_CONFIG, PAYROLL_STATUS, PaymentFrequency, Payroll, PayrollBreakdown, PayrollBuilder, PayrollError, PayrollHistoryParams, PayrollInitConfig, PayrollInstance, PayrollRecordDocument, PayrollStatus, PayrollStatusMachine, type PayrollStatusState, PayrollSummaryParams, PayrollSummaryResult, type PayrollTimelineEvent, type PenaltyMode, type PenaltyOverride, type PenaltyTier, PenaltyTierSchema, PenaltyTierSchemaDefinition, ProcessBulkPayrollParams, ProcessSalaryParams, ProcessSalaryResult, RETAIL_POLICY, ReHireEmployeeParams, RemoveAllowanceParams, RemoveDeductionParams, type ResetPeriod, RestorePayrollParams, RestorePayrollResult, ReversePayrollParams, ReversePayrollResult, type RoundingMode, SecurityError, type ShiftComplianceData, type ShiftComplianceResult, type ShiftDifferentialResult, SingleTenantConfig, StateMachine, type StateMachineConfig, type StateTransition, TAX_STATUS, TAX_STATUS_VALUES, TAX_TYPE, TAX_TYPE_VALUES, TERMINATION_REASON, TaxStatus, TaxStatusMachine, type TaxStatusState, TaxSummaryParams, TaxSummaryResult, TaxType, TaxWithholdingDocument, TerminateEmployeeParams, type TerminationData, TerminationReason, TieredPenaltyBuilder, TransactionFactory, type TransitionResult, UpdateBankDetailsParams, UpdateEmploymentParams, UpdateSalaryParams, ValidationError, VoidPayrollParams, VoidPayrollResult, WebhookConfig, WebhookDelivery, type WeekendPremium, WeekendPremiumSchema, WeekendPremiumSchemaDefinition, WorkSchedule, batchGetAttendance, buildRequestContext, buildTimelineMetadata, calculateDailyOvertime, calculateFlatPenalty, calculateLatePenalty, calculateMonthlyOvertime, calculateNightShiftDifferential, calculateOvertimeBonus, calculatePerMinutePenalty, calculatePercentagePenalty, calculateShiftCompliance, calculateTieredPenalty, calculateWeekendPremium, calculateWeeklyOvertime, createClockRoundingPolicyBuilder, createEmployee, createError, createHolidaySchema, createLatePolicyBuilder, createOvertimePolicyBuilder, createPayrollInstance, createPayrollTransaction, createPolicyFromPreset, createStateMachine, createTaxPaymentTransaction, determineOrgRole, employeePlugin, extractErrorInfo, generatePayrollIdempotencyKey, getAttendance, getHolidays, isApprovedLeaveStatus, isCancelledTaxStatus, isPaidLeaveType, isPaidTaxStatus, isPayrollError, isPayrollTransaction, isPendingLeaveStatus, isPendingTaxStatus, isValidLeaveRequestStatus, isValidLeaveType, isValidTaxStatus, isValidTaxType, isVoidablePayrollStatus, isVoidedOrReversedStatus, mergeConfig, multiTenantPlugin, requiresReversalPayrollStatus, toPayrollError };
+export { ALLOWANCE_TYPE, AddAllowanceParams, AddDeductionParams, Allowance, AnyDocument, type AttendancePolicy, AttendancePolicyBuilder, type AttendancePolicyDocument, type AttendancePolicyModel, AttendancePolicySchema, AttendancePolicySchemaDefinition, type AuditContext, type AuditEvent, BankDetails, BulkPayrollResult, type CalculateShiftComplianceInput, type ClockRoundingPolicy, ClockRoundingPolicyBuilder, ClockRoundingPolicySchema, ClockRoundingPolicySchemaDefinition, Compensation, type CreateEmployeeParams, type CreatePayrollTransactionInput, type CreateTaxPaymentTransactionInput, DEDUCTION_TYPE, DEFAULT_ATTENDANCE_POLICY, DEPARTMENT, Deduction, DeepPartial, Department, EMPLOYEE_STATUS, EMPLOYMENT_TYPE, type EarlyDeparturePenaltyResult, type EarlyDeparturePolicy, EarlyDeparturePolicySchema, EarlyDeparturePolicySchemaDefinition, type EarlyOccurrence, EmployeeBuilder, type EmployeeData, EmployeeDocument, EmployeeFactory, EmployeeIdentityMode, type EmployeePluginOptions, EmploymentType, ExportPayrollParams, GetPendingTaxParams, HEALTHCARE_POLICY, HOSPITALITY_POLICY, HRMConfig, HRM_CONFIG, HireEmployeeParams, type Holiday, type IPayrollTransaction, type IPayrollTransactionCreateInput, LEAVE_REQUEST_STATUS, LEAVE_TYPE, type LateArrivalPolicy, LateArrivalPolicySchema, LateArrivalPolicySchemaDefinition, type LateOccurrence, type LatePenaltyResult, LatePolicyBuilder, LeaveInitConfig, LeaveRequestDocument, LeaveRequestStatus, LeaveType, Logger, MANUFACTURING_POLICY, MarkTaxPaidParams, type MaxPenaltiesPerPeriod, MaxPenaltiesSchema, MaxPenaltiesSchemaDefinition, type NightShiftDifferential, NightShiftDifferentialSchema, NightShiftDifferentialSchemaDefinition, OFFICE_POLICY, ObjectIdLike, OperationContext, OrgRole, type OvertimeBonusResult, type OvertimeMode, type OvertimeOccurrence, type OvertimePolicy, OvertimePolicyBuilder, OvertimePolicySchema, OvertimePolicySchemaDefinition, PAYMENT_FREQUENCY, PAYROLL_STATUS, PaymentFrequency, Payroll, PayrollBreakdown, PayrollBuilder, PayrollHistoryParams, PayrollInitConfig, PayrollInstance, PayrollPluginDefinition, PayrollRecordDocument, PayrollStatus, PayrollSummaryParams, PayrollSummaryResult, type PenaltyMode, type PenaltyOverride, type PenaltyTier, PenaltyTierSchema, PenaltyTierSchemaDefinition, ProcessBulkPayrollParams, ProcessSalaryParams, ProcessSalaryResult, RETAIL_POLICY, ReHireEmployeeParams, RemoveAllowanceParams, RemoveDeductionParams, type ResetPeriod, RestorePayrollParams, RestorePayrollResult, ReversePayrollParams, ReversePayrollResult, type RoundingMode, type ShiftComplianceData, type ShiftComplianceResult, type ShiftDifferentialResult, SingleTenantConfig, TAX_STATUS, TAX_STATUS_VALUES, TAX_TYPE, TAX_TYPE_VALUES, TERMINATION_REASON, TaxStatus, TaxSummaryParams, TaxSummaryResult, TaxType, TaxWithholdingDocument, TerminateEmployeeParams, type TerminationData, TerminationReason, TieredPenaltyBuilder, TransactionFactory, UpdateBankDetailsParams, UpdateEmploymentParams, UpdateSalaryParams, VoidPayrollParams, VoidPayrollResult, WebhookConfig, WebhookDelivery, type WeekendPremium, WeekendPremiumSchema, WeekendPremiumSchemaDefinition, WorkSchedule, batchGetAttendance, calculateDailyOvertime, calculateFlatPenalty, calculateLatePenalty, calculateMonthlyOvertime, calculateNightShiftDifferential, calculateOvertimeBonus, calculatePerMinutePenalty, calculatePercentagePenalty, calculateShiftCompliance, calculateTieredPenalty, calculateWeekendPremium, calculateWeeklyOvertime, createClockRoundingPolicyBuilder, createEmployee, createHolidaySchema, createLatePolicyBuilder, createOvertimePolicyBuilder, createPayrollInstance, createPayrollTransaction, createPolicyFromPreset, createTaxPaymentTransaction, determineOrgRole, employeePlugin, fullAuditPlugin, getAttendance, getEmployeeEmail, getEmployeeName, getErrorMessage, getHolidays, hasUserId, isApprovedLeaveStatus, isCancelledTaxStatus, isConnectionError, isDuplicateKeyError, isError, isGuestEmployee, isMongoError, isPaidLeaveType, isPaidTaxStatus, isPayrollTransaction, isPendingLeaveStatus, isPendingTaxStatus, isTransactionError, isTransactionUnsupportedError, isValidLeaveRequestStatus, isValidLeaveType, isValidTaxStatus, isValidTaxType, isValidationError, isVoidablePayrollStatus, isVoidedOrReversedStatus, mergeConfig, parseDuplicateKeyError, payrollAuditPlugin, readAuditPlugin, requiresReversalPayrollStatus };