@classytic/payroll 1.0.0 → 2.7.5

package/dist/index.d.ts

@@ -0,0 +1,2924 @@
+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 * as mongoose from 'mongoose';
+import { ClientSession, Model, Schema, 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';
+import 'bson';
+
+/**
+ * Fully generic Payroll class for best-in-class TypeScript DX.
+ *
+ * Type parameters flow through to all methods, providing complete type inference.
+ *
+ * @typeParam TEmployee - Your Employee document type (extends EmployeeDocument)
+ * @typeParam TPayrollRecord - Your PayrollRecord document type (extends PayrollRecordDocument)
+ * @typeParam TTransaction - Your Transaction document type
+ * @typeParam TAttendance - Your Attendance document type (optional)
+ *
+ * @example
+ * ```typescript
+ * // Full type inference
+ * const payroll = createPayrollInstance()
+ *   .withModels({
+ *     EmployeeModel,      // Model<MyEmployeeDoc>
+ *     PayrollRecordModel, // Model<MyPayrollDoc>
+ *     TransactionModel,   // Model<MyTransactionDoc>
+ *   })
+ *   .build();
+ *
+ * // employee is typed as MyEmployeeDoc
+ * const employee = await payroll.hire({ ... });
+ * ```
+ */
+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;
+    private _initialized;
+    private repositoryManager;
+    private salaryProcessingManager;
+    private bulkOperationsManager;
+    private employeeOperationsManager;
+    private compensationManager;
+    private payrollHistoryManager;
+    private payrollStateManager;
+    private _idempotency;
+    private _webhooks;
+    /**
+     * Create a new Payroll instance with its own container.
+     * Each instance is isolated - no shared global state.
+     */
+    constructor();
+    /**
+     * Initialize Payroll with models and configuration
+     */
+    initialize(config: PayrollInitConfig<TEmployee, TPayrollRecord, TTransaction, TAttendance>): this;
+    /**
+     * Check if initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Ensure initialized
+     */
+    private ensureInitialized;
+    /**
+     * Resolve employeeId to ObjectId _id (respects explicit mode)
+     *
+     * Mode priority:
+     * - 'objectId': Always treat as MongoDB ObjectId (direct _id lookup)
+     * - 'businessId': Always treat as business ID (lookup by employeeId field)
+     * - 'auto': Smart detection (ObjectId-like → _id, otherwise → businessId)
+     */
+    private resolveEmployeeId;
+    /**
+     * Create request-scoped services with proper organizationId filtering.
+     *
+     * SECURITY: Services are created from request-scoped repositories to ensure
+     * multi-tenant isolation at the query level.
+     *
+     * @param repos - Request-scoped repositories
+     */
+    private getServicesForRequest;
+    /**
+     * Get models (strongly typed)
+     */
+    private get models();
+    /**
+     * Create request-scoped repositories with proper organizationId filtering.
+     *
+     * SECURITY: This ensures multi-tenant isolation at the query level by creating
+     * repositories with the request-specific organizationId injected into plugins.
+     *
+     * @param organizationId - Required in multi-tenant mode, optional in single-tenant
+     */
+    private getReposForRequest;
+    /**
+     * Resolve organizationId for the current operation.
+     *
+     * SECURITY:
+     * - Multi-tenant mode: organizationId MUST be provided in params
+     * - Single-tenant with autoInject=true (default): Uses container organizationId
+     * - Single-tenant with autoInject=false: organizationId MUST be provided in params
+     *
+     * @param providedOrgId - OrganizationId from operation parameters
+     * @returns Resolved ObjectId
+     * @throws SecurityError if organizationId is missing when required
+     */
+    private resolveOrganizationId;
+    /**
+     * Get config
+     */
+    private get config();
+    /**
+     * Get container (for org resolution and single-tenant detection)
+     */
+    private get container();
+    /**
+     * Find employee securely with organizational isolation at query level.
+     *
+     * SECURITY: Creates request-scoped repositories with organizationId injected into
+     * query filters, ensuring multi-tenant isolation at the database level.
+     *
+     * In multi-tenant mode, organizationId MUST be provided in options.
+     * In single-tenant mode, organizationId is retrieved from container.
+     */
+    private findEmployee;
+    /**
+     * Register a plugin
+     */
+    use(plugin: PayrollPluginDefinition): Promise<this>;
+    /**
+     * Subscribe to events
+     */
+    on<K extends keyof PayrollEventMap>(event: K, handler: (payload: PayrollEventMap[K]) => void | Promise<void>): () => void;
+    /**
+     * Register webhook URL for events (Stripe-style)
+     */
+    registerWebhook(config: WebhookConfig): void;
+    /**
+     * Unregister webhook URL
+     */
+    unregisterWebhook(url: string): void;
+    /**
+     * Get webhook delivery log
+     */
+    getWebhookDeliveries(options?: {
+        event?: PayrollEventType;
+        status?: 'pending' | 'sent' | 'failed';
+        limit?: number;
+    }): WebhookDelivery[];
+    /**
+     * Setup webhook bridge (connects event bus to webhook manager)
+     */
+    private setupWebhookBridge;
+    /**
+     * Hire a new employee
+     */
+    hire(params: HireEmployeeParams): Promise<TEmployee>;
+    /**
+     * Update employment details
+     * NOTE: Status changes to 'terminated' must use terminate() method
+     */
+    updateEmployment(params: UpdateEmploymentParams): Promise<TEmployee>;
+    /**
+     * Terminate employee
+     */
+    terminate(params: TerminateEmployeeParams): Promise<TEmployee>;
+    /**
+     * Re-hire terminated employee
+     */
+    reHire(params: ReHireEmployeeParams): Promise<TEmployee>;
+    /**
+     * Get employee by ID
+     */
+    getEmployee(params: {
+        employeeId: ObjectIdLike | string;
+        employeeIdMode?: 'auto' | 'objectId' | 'businessId';
+        organizationId?: ObjectIdLike;
+        populateUser?: boolean;
+        session?: ClientSession;
+        context?: OperationContext;
+    }): Promise<TEmployee>;
+    /**
+     * Get employee by flexible identity (userId, employeeId, or email)
+     *
+     * Supports multiple identity modes with automatic fallback:
+     * - 'userId': Lookup by user account ID (traditional)
+     * - 'employeeId': Lookup by human-readable employee ID (e.g., "EMP-001")
+     * - 'email': Lookup by email address (for guest employees)
+     * - 'any': Try all modes until found
+     *
+     * @example
+     * // By user ID (traditional)
+     * const emp = await payroll.getEmployeeByIdentity({
+     *   identity: userId,
+     *   organizationId,
+     *   mode: 'userId'
+     * });
+     *
+     * // By employee ID (human-readable)
+     * const emp = await payroll.getEmployeeByIdentity({
+     *   identity: 'EMP-001',
+     *   organizationId,
+     *   mode: 'employeeId'
+     * });
+     *
+     * // By email (guest employees)
+     * const emp = await payroll.getEmployeeByIdentity({
+     *   identity: 'driver@example.com',
+     *   organizationId,
+     *   mode: 'email'
+     * });
+     *
+     * // Auto-detect (uses config.identityMode + fallbacks)
+     * const emp = await payroll.getEmployeeByIdentity({
+     *   identity: 'EMP-001',
+     *   organizationId
+     * });
+     */
+    getEmployeeByIdentity(params: {
+        identity: ObjectIdLike | string;
+        organizationId?: ObjectIdLike;
+        mode?: EmployeeIdentityMode;
+        populateUser?: boolean;
+        session?: ClientSession;
+    }): Promise<TEmployee>;
+    /**
+     * Update employee salary
+     */
+    updateSalary(params: UpdateSalaryParams): Promise<TEmployee>;
+    /**
+     * Add allowance to employee
+     */
+    addAllowance(params: AddAllowanceParams): Promise<TEmployee>;
+    /**
+     * Remove allowance from employee
+     */
+    removeAllowance(params: RemoveAllowanceParams): Promise<TEmployee>;
+    /**
+     * Add deduction to employee
+     */
+    addDeduction(params: AddDeductionParams): Promise<TEmployee>;
+    /**
+     * Remove deduction from employee
+     */
+    removeDeduction(params: RemoveDeductionParams): Promise<TEmployee>;
+    /**
+     * Update bank details
+     */
+    updateBankDetails(params: UpdateBankDetailsParams): Promise<TEmployee>;
+    /**
+     * Process salary for single employee
+     *
+     * ATOMICITY GUARANTEE:
+     * This method ALWAYS ensures atomic operations. All database writes
+     * (PayrollRecord, Transaction, Employee stats) either all succeed or all fail.
+     *
+     * Transaction Handling:
+     * - No session provided: Creates session and starts transaction
+     * - Session provided WITHOUT transaction: Starts transaction on that session
+     * - Session provided WITH transaction: Uses existing transaction
+     *
+     * This means atomicity is enforced automatically - callers cannot
+     * accidentally cause partial writes by providing session without transaction.
+     *
+     * @example
+     * // Simple usage - transaction handled automatically
+     * await payroll.processSalary({ employeeId, organizationId, month, year });
+     *
+     * @example
+     * // Use existing session (transaction started automatically if needed)
+     * const session = await mongoose.startSession();
+     * await payroll.processSalary({
+     *   employeeId,
+     *   organizationId,
+     *   month,
+     *   year,
+     *   context: { session }
+     * });
+     *
+     * @example
+     * // Nested in caller's transaction (uses existing transaction)
+     * await session.withTransaction(async () => {
+     *   await payroll.processSalary({
+     *     employeeId,
+     *     organizationId,
+     *     month,
+     *     year,
+     *     context: { session }
+     *   });
+     *   // Other operations...
+     * });
+     */
+    processSalary(params: ProcessSalaryParams): Promise<ProcessSalaryResult<TEmployee, TPayrollRecord, TTransaction>>;
+    /**
+     * Process bulk payroll for multiple employees
+     *
+     * ATOMICITY STRATEGY: Each employee is processed in its own transaction.
+     * This allows partial success - some employees can succeed while others fail.
+     * Failed employees don't affect successful ones.
+     *
+     * NEW FEATURES (all optional, backward compatible):
+     * - Progress tracking via onProgress callback
+     * - Cancellation support via AbortSignal
+     * - Batch processing to prevent resource exhaustion
+     * - Concurrency control for parallel processing
+     *
+     * @example Basic usage (unchanged)
+     * ```typescript
+     * const result = await payroll.processBulkPayroll({
+     *   organizationId, month, year
+     * });
+     * ```
+     *
+     * @example With progress tracking
+     * ```typescript
+     * await payroll.processBulkPayroll({
+     *   organizationId, month, year,
+     *   onProgress: (p) => console.log(`${p.percentage}% done`)
+     * });
+     * ```
+     *
+     * @example With job queue integration
+     * ```typescript
+     * await payroll.processBulkPayroll({
+     *   organizationId, month, year,
+     *   batchSize: 10,
+     *   onProgress: async (p) => {
+     *     await Job.findByIdAndUpdate(jobId, { progress: p });
+     *   }
+     * });
+     * ```
+     *
+     * @example With cancellation
+     * ```typescript
+     * const controller = new AbortController();
+     * payroll.processBulkPayroll({ signal: controller.signal });
+     * // Later: controller.abort();
+     * ```
+     */
+    processBulkPayroll(params: ProcessBulkPayrollParams): Promise<BulkPayrollResult>;
+    /**
+     * Get payroll history
+     */
+    payrollHistory(params: PayrollHistoryParams): Promise<TPayrollRecord[]>;
+    /**
+     * Get payroll summary
+     */
+    payrollSummary(params: PayrollSummaryParams): Promise<PayrollSummaryResult>;
+    /**
+     * Export payroll data
+     */
+    exportPayroll(params: ExportPayrollParams): Promise<TPayrollRecord[]>;
+    /**
+     * Void a payroll record (before payment)
+     *
+     * Use for payrolls that haven't been paid yet (pending, processing, failed).
+     * Creates audit trail but doesn't create a reversal transaction.
+     *
+     * @example
+     * ```typescript
+     * await payroll.voidPayroll({
+     *   organizationId: org._id,
+     *   payrollRecordId: record._id,
+     *   reason: 'Test payroll - not intended for production',
+     *   context: { userId: admin._id },
+     * });
+     * ```
+     */
+    voidPayroll(params: VoidPayrollParams): Promise<VoidPayrollResult>;
+    /**
+     * Reverse a paid payroll
+     *
+     * Creates a reversal (negative) transaction to offset the original payment.
+     * Required for compliance as it maintains a full audit trail.
+     *
+     * @example
+     * ```typescript
+     * const result = await payroll.reversePayroll({
+     *   organizationId: org._id,
+     *   payrollRecordId: record._id,
+     *   reason: 'Duplicate payment - reversing',
+     *   createReversalTransaction: true,
+     * });
+     * ```
+     */
+    reversePayroll(params: ReversePayrollParams): Promise<ReversePayrollResult>;
+    /**
+     * Restore a voided payroll
+     *
+     * Only works for voided payrolls (not reversed ones, as they have financial transactions).
+     *
+     * @example
+     * ```typescript
+     * await payroll.restorePayroll({
+     *   organizationId: org._id,
+     *   payrollRecordId: record._id,
+     *   reason: 'Voided in error, restoring',
+     * });
+     * ```
+     */
+    restorePayroll(params: RestorePayrollParams): Promise<RestorePayrollResult>;
+    /**
+     * Get pending tax withholdings with optional filters
+     */
+    getPendingTaxWithholdings(params: GetPendingTaxParams): Promise<TaxWithholdingDocument[]>;
+    /**
+     * Get tax summary aggregated by type, period, or employee
+     */
+    getTaxSummary(params: TaxSummaryParams): Promise<TaxSummaryResult>;
+    /**
+     * Mark tax withholdings as paid
+     *
+     * Updates status, optionally creates government payment transaction,
+     * and emits tax:paid event
+     */
+    markTaxWithholdingsPaid(params: MarkTaxPaidParams): Promise<{
+        withholdings: TaxWithholdingDocument[];
+        transaction?: any;
+    }>;
+    /**
+     * Calculate salary breakdown
+     *
+     * Delegates to pure calculator for testability and reusability
+     */
+    private calculateSalaryBreakdown;
+    /**
+     * Calculate attendance deduction using working days (not calendar days)
+     */
+    private calculateAttendanceDeduction;
+    private updatePayrollStats;
+    /**
+     * Create a new Payroll instance with default types
+     */
+    static create<E extends EmployeeDocument = EmployeeDocument, P extends PayrollRecordDocument = PayrollRecordDocument, T extends AnyDocument = AnyDocument, A extends AnyDocument = AnyDocument>(): Payroll<E, P, T, A>;
+}
+/**
+ * Generic models configuration - infers types from your models
+ */
+interface ModelsConfig<TEmployee extends EmployeeDocument = EmployeeDocument, TPayrollRecord extends PayrollRecordDocument = PayrollRecordDocument, TTransaction extends AnyDocument = AnyDocument, TAttendance extends AnyDocument = AnyDocument, TLeaveRequest extends LeaveRequestDocument = LeaveRequestDocument, TTaxWithholding extends TaxWithholdingDocument = TaxWithholdingDocument> {
+    EmployeeModel: Model<TEmployee>;
+    PayrollRecordModel: Model<TPayrollRecord>;
+    TransactionModel: Model<TTransaction>;
+    AttendanceModel?: Model<TAttendance> | null;
+    LeaveRequestModel?: Model<TLeaveRequest> | null;
+    TaxWithholdingModel?: Model<TTaxWithholding> | null;
+}
+/**
+ * Generic Payroll Builder with full type inference.
+ *
+ * Types flow from withModels() through to build(), giving you a fully typed Payroll instance.
+ *
+ * @typeParam TEmployee - Inferred from EmployeeModel
+ * @typeParam TPayrollRecord - Inferred from PayrollRecordModel
+ * @typeParam TTransaction - Inferred from TransactionModel
+ * @typeParam TAttendance - Inferred from AttendanceModel
+ *
+ * @example
+ * ```typescript
+ * // Types are automatically inferred!
+ * const payroll = createPayrollInstance()
+ *   .withModels({
+ *     EmployeeModel,      // Model<MyEmployee>
+ *     PayrollRecordModel, // Model<MyPayroll>
+ *     TransactionModel,   // Model<MyTransaction>
+ *   })
+ *   .build(); // Returns PayrollInstance<MyEmployee, MyPayroll, MyTransaction, AnyDocument>
+ * ```
+ */
+declare class PayrollBuilder<TEmployee extends EmployeeDocument = EmployeeDocument, TPayrollRecord extends PayrollRecordDocument = PayrollRecordDocument, TTransaction extends AnyDocument = AnyDocument, TAttendance extends AnyDocument = AnyDocument, TLeaveRequest extends LeaveRequestDocument = LeaveRequestDocument, TTaxWithholding extends TaxWithholdingDocument = TaxWithholdingDocument> {
+    private _models;
+    private _config;
+    private _singleTenant;
+    private _logger;
+    /**
+     * Set models - types are inferred automatically
+     *
+     * @example
+     * ```typescript
+     * .withModels({
+     *   EmployeeModel,      // Your typed model
+     *   PayrollRecordModel,
+     *   TransactionModel,
+     *   AttendanceModel,    // Optional
+     * })
+     * ```
+     */
+    withModels<E extends EmployeeDocument, P extends PayrollRecordDocument, T extends AnyDocument, A extends AnyDocument = AnyDocument, L extends LeaveRequestDocument = LeaveRequestDocument, TW extends TaxWithholdingDocument = TaxWithholdingDocument>(models: ModelsConfig<E, P, T, A, L, TW>): PayrollBuilder<E, P, T, A, L, TW>;
+    /**
+     * Set config overrides
+     */
+    withConfig(config: DeepPartial<HRMConfig>): this;
+    /**
+     * Enable single-tenant mode
+     *
+     * Use this when building a single-organization HRM (no organizationId needed)
+     *
+     * @example
+     * ```typescript
+     * const payroll = createPayrollInstance()
+     *   .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
+     *   .withSingleTenant({ organizationId: 'my-company' })
+     *   .build();
+     * ```
+     */
+    withSingleTenant(config: SingleTenantConfig): this;
+    /**
+     * Enable single-tenant mode (shorthand)
+     *
+     * Alias for withSingleTenant() - consistent with @classytic/clockin API
+     *
+     * @example
+     * ```typescript
+     * const payroll = createPayrollInstance()
+     *   .withModels({ ... })
+     *   .forSingleTenant() // ← No organizationId needed!
+     *   .build();
+     * ```
+     */
+    forSingleTenant(config?: SingleTenantConfig): this;
+    /**
+     * Set custom logger
+     */
+    withLogger(logger: Logger): this;
+    /**
+     * Build and initialize Payroll instance with inferred types
+     */
+    build(): PayrollInstance<TEmployee, TPayrollRecord, TTransaction, TAttendance>;
+}
+/**
+ * Create a new Payroll builder
+ */
+declare function createPayrollInstance(): PayrollBuilder;
+
+/**
+ * Transaction Interface
+ * @classytic/payroll
+ *
+ * Payroll uses the unified transaction interface from @classytic/shared-types
+ * so revenue and payroll share a single cashflow event model.
+ */
+
+/**
+ * Core transaction interface expected by payroll package
+ * Apps must provide a Transaction model with AT LEAST these fields
+ */
+type IPayrollTransaction = ITransaction;
+/**
+ * Transaction write input (what payroll package creates)
+ */
+type IPayrollTransactionCreateInput = ITransactionCreateInput;
+/**
+ * Type guard to check if object is a Transaction
+ */
+declare function isPayrollTransaction(obj: unknown): obj is IPayrollTransaction;
+
+/**
+ * @classytic/payroll - Transaction Factory
+ *
+ * Pure functions for building transaction objects aligned with @classytic/shared-types.
+ * Ensures consistency with revenue package for unified cashflow.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Input for creating a payroll transaction
+ */
+interface CreatePayrollTransactionInput {
+    organizationId: ObjectIdLike;
+    employee: {
+        _id: ObjectIdLike;
+        userId?: ObjectIdLike | {
+            _id: ObjectIdLike;
+            name?: string;
+        } | null;
+        employeeId: string;
+        email?: string;
+        compensation: {
+            currency?: string;
+        };
+    };
+    payrollRecord: {
+        _id: ObjectIdLike;
+    };
+    breakdown: PayrollBreakdown;
+    period: {
+        month: number;
+        year: number;
+    };
+    paymentDate: Date;
+    paymentMethod?: string;
+    processedBy?: ObjectIdLike;
+    idempotencyKey?: string;
+    jurisdiction?: string;
+    defaultCurrency?: string;
+}
+/**
+ * Input for creating a tax payment transaction
+ */
+interface CreateTaxPaymentTransactionInput {
+    organizationId: ObjectIdLike;
+    totalAmount: number;
+    currency: string;
+    referenceNumber?: string;
+    notes?: string;
+    withholdingIds: ObjectIdLike[];
+}
+/**
+ * Create payroll transaction aligned with @classytic/shared-types
+ *
+ * This is the SINGLE SOURCE OF TRUTH for payroll transaction structure.
+ * Aligns with revenue package for unified cashflow.
+ *
+ * @param input - Payroll transaction parameters
+ * @returns Transaction data ready for DB creation (ITransactionCreateInput)
+ *
+ * @pure This function has no side effects
+ */
+declare function createPayrollTransaction(input: CreatePayrollTransactionInput): ITransactionCreateInput;
+/**
+ * Create tax payment transaction aligned with @classytic/shared-types
+ *
+ * For government tax payments (withholding remittance).
+ *
+ * @param input - Tax payment parameters
+ * @returns Transaction data ready for DB creation (ITransactionCreateInput)
+ *
+ * @pure This function has no side effects
+ */
+declare function createTaxPaymentTransaction(input: CreateTaxPaymentTransactionInput): ITransactionCreateInput;
+/**
+ * Transaction Factory class (for builder pattern if needed)
+ */
+declare class TransactionFactory {
+    static createPayrollTransaction: typeof createPayrollTransaction;
+    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";
+    readonly CONTRACT: "contract";
+    readonly INTERN: "intern";
+    readonly CONSULTANT: "consultant";
+};
+declare const EMPLOYEE_STATUS: {
+    readonly ACTIVE: "active";
+    readonly ON_LEAVE: "on_leave";
+    readonly SUSPENDED: "suspended";
+    readonly TERMINATED: "terminated";
+};
+declare const DEPARTMENT: {
+    readonly MANAGEMENT: "management";
+    readonly TRAINING: "training";
+    readonly SALES: "sales";
+    readonly OPERATIONS: "operations";
+    readonly SUPPORT: "support";
+    readonly HR: "hr";
+    readonly MAINTENANCE: "maintenance";
+    readonly MARKETING: "marketing";
+    readonly FINANCE: "finance";
+    readonly IT: "it";
+};
+declare const PAYMENT_FREQUENCY: {
+    readonly MONTHLY: "monthly";
+    readonly BI_WEEKLY: "bi_weekly";
+    readonly WEEKLY: "weekly";
+    readonly HOURLY: "hourly";
+    readonly DAILY: "daily";
+};
+declare const ALLOWANCE_TYPE: {
+    readonly HOUSING: "housing";
+    readonly TRANSPORT: "transport";
+    readonly MEAL: "meal";
+    readonly MOBILE: "mobile";
+    readonly MEDICAL: "medical";
+    readonly EDUCATION: "education";
+    readonly BONUS: "bonus";
+    readonly OTHER: "other";
+};
+declare const DEDUCTION_TYPE: {
+    readonly TAX: "tax";
+    readonly LOAN: "loan";
+    readonly ADVANCE: "advance";
+    readonly PROVIDENT_FUND: "provident_fund";
+    readonly INSURANCE: "insurance";
+    readonly ABSENCE: "absence";
+    readonly OTHER: "other";
+};
+declare const PAYROLL_STATUS: {
+    readonly PENDING: "pending";
+    readonly PROCESSING: "processing";
+    readonly PAID: "paid";
+    readonly FAILED: "failed";
+    readonly VOIDED: "voided";
+    readonly REVERSED: "reversed";
+};
+/** Check if payroll can be voided (not yet paid) */
+declare function isVoidablePayrollStatus(status: PayrollStatus): boolean;
+/** Check if payroll requires reversal (already paid) */
+declare function requiresReversalPayrollStatus(status: PayrollStatus): boolean;
+/** Check if payroll is in a terminal void/reverse state */
+declare function isVoidedOrReversedStatus(status: PayrollStatus): boolean;
+declare const TERMINATION_REASON: {
+    readonly RESIGNATION: "resignation";
+    readonly RETIREMENT: "retirement";
+    readonly TERMINATION: "termination";
+    readonly CONTRACT_END: "contract_end";
+    readonly MUTUAL_AGREEMENT: "mutual_agreement";
+    readonly OTHER: "other";
+};
+declare const LEAVE_TYPE: {
+    readonly ANNUAL: "annual";
+    readonly SICK: "sick";
+    readonly UNPAID: "unpaid";
+    readonly MATERNITY: "maternity";
+    readonly PATERNITY: "paternity";
+    readonly BEREAVEMENT: "bereavement";
+    readonly COMPENSATORY: "compensatory";
+    readonly OTHER: "other";
+};
+declare function isValidLeaveType(value: string): value is LeaveType;
+declare function isPaidLeaveType(type: LeaveType): boolean;
+declare const LEAVE_REQUEST_STATUS: {
+    readonly PENDING: "pending";
+    readonly APPROVED: "approved";
+    readonly REJECTED: "rejected";
+    readonly CANCELLED: "cancelled";
+};
+declare function isValidLeaveRequestStatus(value: string): value is LeaveRequestStatus;
+declare function isPendingLeaveStatus(status: LeaveRequestStatus): boolean;
+declare function isApprovedLeaveStatus(status: LeaveRequestStatus): boolean;
+declare const TAX_TYPE: {
+    readonly INCOME_TAX: "income_tax";
+    readonly SOCIAL_SECURITY: "social_security";
+    readonly HEALTH_INSURANCE: "health_insurance";
+    readonly PENSION: "pension";
+    readonly EMPLOYMENT_INSURANCE: "employment_insurance";
+    readonly LOCAL_TAX: "local_tax";
+    readonly OTHER: "other";
+};
+declare const TAX_TYPE_VALUES: ("other" | "income_tax" | "social_security" | "health_insurance" | "pension" | "employment_insurance" | "local_tax")[];
+declare function isValidTaxType(value: string): value is TaxType;
+declare const TAX_STATUS: {
+    readonly PENDING: "pending";
+    readonly SUBMITTED: "submitted";
+    readonly PAID: "paid";
+    readonly CANCELLED: "cancelled";
+};
+declare const TAX_STATUS_VALUES: ("pending" | "paid" | "cancelled" | "submitted")[];
+declare function isValidTaxStatus(value: string): value is TaxStatus;
+declare function isPendingTaxStatus(status: TaxStatus): boolean;
+declare function isPaidTaxStatus(status: TaxStatus): boolean;
+declare function isCancelledTaxStatus(status: TaxStatus): boolean;
+
+/**
+ * @classytic/payroll - Configuration
+ *
+ * Centralized configuration with type safety
+ * Configurable defaults for different use cases
+ */
+
+declare const HRM_CONFIG: HRMConfig;
+/**
+ * Determine the appropriate organization role for an employee
+ */
+declare function determineOrgRole(employmentData: {
+    department?: Department | string;
+    type?: EmploymentType | string;
+    position?: string;
+}): OrgRole;
+/**
+ * Merge configuration with defaults
+ */
+declare function mergeConfig(customConfig: Partial<HRMConfig> | DeepPartial<HRMConfig> | undefined): HRMConfig;
+
+/**
+ * @classytic/payroll - Employee Plugin
+ *
+ * Mongoose plugin that adds HRM methods and virtuals to Employee schema
+ */
+
+interface EmployeePluginOptions {
+    /** Require bank details for salary payment */
+    requireBankDetails?: boolean;
+    /** Field name for compensation */
+    compensationField?: string;
+    /** Field name for status */
+    statusField?: string;
+    /** Enable auto salary calculation on save */
+    autoCalculateSalary?: boolean;
+    /** Create indexes on schema (default: false) */
+    createIndexes?: boolean;
+    /** Enable leave management methods (default: false) */
+    enableLeave?: boolean;
+    /** Leave configuration */
+    leaveConfig?: LeaveInitConfig;
+    /** Field name for leave balances (default: 'leaveBalances') */
+    leaveBalancesField?: string;
+}
+/**
+ * Mongoose plugin that adds HRM functionality to Employee schema
+ *
+ * @example
+ * ```typescript
+ * const employeeSchema = new Schema({
+ *   ...createEmploymentFields({ organizationRef: 'Branch' }),
+ *   // Custom fields
+ * });
+ *
+ * employeeSchema.plugin(employeePlugin);
+ * ```
+ */
+declare function employeePlugin(schema: Schema, options?: EmployeePluginOptions): void;
+
+/**
+ * @classytic/payroll - Employee Factory
+ *
+ * Clean object creation for employee documents
+ * Builder pattern for fluent API
+ */
+
+interface CreateEmployeeParams {
+    userId?: ObjectIdLike;
+    organizationId: ObjectIdLike;
+    employment: {
+        employeeId?: string;
+        email?: string;
+        type?: EmploymentType;
+        department?: Department | string;
+        position: string;
+        hireDate?: Date;
+        probationMonths?: number;
+        workSchedule?: WorkSchedule;
+    };
+    compensation: {
+        baseAmount: number;
+        frequency?: PaymentFrequency;
+        currency?: string;
+        allowances?: Array<Partial<Allowance>>;
+        deductions?: Array<Partial<Deduction>>;
+    };
+    bankDetails?: BankDetails;
+}
+interface EmployeeData {
+    userId?: ObjectIdLike;
+    email?: string;
+    organizationId: ObjectIdLike;
+    employeeId: string;
+    employmentType: EmploymentType;
+    status: 'active';
+    department?: Department;
+    position: string;
+    hireDate: Date;
+    probationEndDate: Date | null;
+    compensation: Compensation;
+    workSchedule: WorkSchedule;
+    bankDetails: BankDetails;
+    payrollStats: {
+        totalPaid: number;
+        paymentsThisYear: number;
+        averageMonthly: number;
+    };
+}
+interface TerminationData {
+    terminatedAt: Date;
+    terminationReason: TerminationReason;
+    terminationNotes?: string;
+    terminatedBy: {
+        userId?: ObjectIdLike;
+        name?: string;
+        role?: string;
+    };
+}
+declare class EmployeeFactory {
+    /**
+     * Create employee data object
+     */
+    static create(params: CreateEmployeeParams, config?: HRMConfig): EmployeeData;
+    /**
+     * Create compensation object
+     */
+    static createCompensation(params: {
+        baseAmount: number;
+        frequency?: PaymentFrequency;
+        currency?: string;
+        allowances?: Array<Partial<Allowance>>;
+        deductions?: Array<Partial<Deduction>>;
+    }, config?: HRMConfig): Compensation;
+    /**
+     * Create allowance object
+     */
+    static createAllowance(params: {
+        type: Allowance['type'];
+        amount: number;
+        name?: string;
+        isPercentage?: boolean;
+        taxable?: boolean;
+        recurring?: boolean;
+    }): Allowance;
+    /**
+     * Create deduction object
+     */
+    static createDeduction(params: {
+        type: Deduction['type'];
+        amount: number;
+        name?: string;
+        isPercentage?: boolean;
+        auto?: boolean;
+        recurring?: boolean;
+        description?: string;
+    }): Deduction;
+    /**
+     * Default work schedule
+     */
+    static defaultWorkSchedule(): WorkSchedule;
+    /**
+     * Create termination data
+     */
+    static createTermination(params: {
+        reason: TerminationReason;
+        date?: Date;
+        notes?: string;
+        context?: {
+            userId?: ObjectIdLike;
+            userName?: string;
+            userRole?: string;
+        };
+    }): TerminationData;
+}
+declare class EmployeeBuilder {
+    private data;
+    /**
+     * Set user ID
+     */
+    forUser(userId: ObjectIdLike): this;
+    /**
+     * Set organization ID
+     */
+    inOrganization(organizationId: ObjectIdLike): this;
+    /**
+     * Set employee ID
+     */
+    withEmployeeId(employeeId: string): this;
+    /**
+     * Set department
+     */
+    inDepartment(department: Department): this;
+    /**
+     * Set position
+     */
+    asPosition(position: string): this;
+    /**
+     * Set employment type
+     */
+    withEmploymentType(type: EmploymentType): this;
+    /**
+     * Set hire date
+     */
+    hiredOn(date: Date): this;
+    /**
+     * Set probation period
+     */
+    withProbation(months: number): this;
+    /**
+     * Set work schedule
+     */
+    withSchedule(schedule: WorkSchedule): this;
+    /**
+     * Set base salary
+     */
+    withBaseSalary(amount: number, frequency?: PaymentFrequency, currency?: string): this;
+    /**
+     * Add allowance
+     */
+    addAllowance(type: Allowance['type'], amount: number, options?: {
+        taxable?: boolean;
+        recurring?: boolean;
+    }): this;
+    /**
+     * Add deduction
+     */
+    addDeduction(type: Deduction['type'], amount: number, options?: {
+        auto?: boolean;
+        recurring?: boolean;
+        description?: string;
+    }): this;
+    /**
+     * Set bank details
+     */
+    withBankDetails(bankDetails: BankDetails): this;
+    /**
+     * Build employee data
+     */
+    build(config?: HRMConfig): EmployeeData;
+}
+/**
+ * Create new employee builder
+ */
+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
+ *
+ * Native integration with @classytic/clockin.
+ * ClockIn is an optional peer dependency for attendance-based deductions.
+ */
+
+/**
+ * Get attendance for payroll calculation
+ *
+ * @example
+ * ```typescript
+ * import { getAttendance } from '@classytic/payroll';
+ *
+ * const attendance = await getAttendance(Attendance, {
+ *   organizationId: org._id,
+ *   employeeId: emp._id,
+ *   month: 3,
+ *   year: 2024,
+ *   expectedDays: 22,
+ * });
+ *
+ * await payroll.processSalary({ employeeId, month: 3, year: 2024, attendance });
+ * ```
+ */
+declare function getAttendance(AttendanceModel: Model<unknown>, params: {
+    organizationId: ObjectIdLike;
+    employeeId: ObjectIdLike;
+    month: number;
+    year: number;
+    expectedDays: number;
+}): Promise<(AttendanceInput & {
+    absentDays: number;
+    overtimeDays: number;
+}) | null>;
+/**
+ * Get attendance for multiple employees (efficient batch operation)
+ *
+ * @example
+ * ```typescript
+ * const attendanceMap = await batchGetAttendance(Attendance, {
+ *   organizationId: org._id,
+ *   employeeIds: [emp1._id, emp2._id, emp3._id],
+ *   month: 3,
+ *   year: 2024,
+ *   expectedDays: 22,
+ * });
+ *
+ * const emp1Attendance = attendanceMap.get(emp1._id.toString());
+ * ```
+ */
+declare function batchGetAttendance(AttendanceModel: Model<unknown>, params: {
+    organizationId: ObjectIdLike;
+    employeeIds: ObjectIdLike[];
+    month: number;
+    year: number;
+    expectedDays: number;
+}): Promise<Map<string, AttendanceInput & {
+    absentDays: number;
+    overtimeDays: number;
+}>>;
+
+/**
+ * @classytic/payroll - Holiday Management
+ *
+ * Simple holiday storage and retrieval.
+ * ONE way to manage holidays - no confusion.
+ */
+
+/**
+ * Holiday document
+ */
+interface Holiday {
+    organizationId?: any;
+    date: Date;
+    name: string;
+    type: 'public' | 'company' | 'religious';
+    paid: boolean;
+}
+/**
+ * Create holiday schema
+ *
+ * @example
+ * ```typescript
+ * import { createHolidaySchema } from '@classytic/payroll';
+ *
+ * // Multi-tenant
+ * const Holiday = model('Holiday', createHolidaySchema());
+ *
+ * // Single-tenant
+ * const Holiday = model('Holiday', createHolidaySchema({ singleTenant: true }));
+ * ```
+ */
+declare function createHolidaySchema(options?: {
+    singleTenant?: boolean;
+}): Schema;
+/**
+ * Get holidays for a period
+ *
+ * @example
+ * ```typescript
+ * const holidays = await getHolidays(Holiday, {
+ *   organizationId: org._id, // optional for single-tenant
+ *   startDate: new Date('2024-03-01'),
+ *   endDate: new Date('2024-03-31'),
+ * });
+ * ```
+ */
+declare function getHolidays(HolidayModel: Model<any>, params: {
+    organizationId?: any;
+    startDate: Date;
+    endDate: Date;
+}): Promise<Date[]>;
+
+/**
+ * @classytic/payroll - Shift Compliance Types
+ *
+ * Clean, modern type definitions for shift-based attendance management.
+ * No legacy baggage - one proper standard.
+ */
+
+/** How penalties are calculated */
+type PenaltyMode = 'flat' | 'per-minute' | 'percentage' | 'tiered';
+/** When overtime kicks in */
+type OvertimeMode = 'daily' | 'weekly' | 'monthly';
+/** When to reset occurrence counters */
+type ResetPeriod = 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly';
+/** Clock-in rounding mode */
+type RoundingMode = 'nearest' | 'up' | 'down';
+/**
+ * Tiered penalty configuration for progressive discipline.
+ *
+ * @example
+ * ```typescript
+ * [
+ *   { from: 1, to: 2, penalty: 0, warning: true },  // 1st-2nd: warning only
+ *   { from: 3, to: 4, penalty: 25 },                 // 3rd-4th: $25
+ *   { from: 5, penalty: 50 }                         // 5th+: $50
+ * ]
+ * ```
+ */
+interface PenaltyTier {
+    /** Occurrence number start (inclusive) */
+    from: number;
+    /** Occurrence number end (inclusive, optional for open-ended) */
+    to?: number;
+    /** Penalty amount for this tier */
+    penalty: number;
+    /** If true, log warning but don't deduct money */
+    warning?: boolean;
+}
+/**
+ * Maximum penalties per period configuration
+ */
+interface MaxPenaltiesPerPeriod {
+    /** Maximum number of penalties allowed */
+    count: number;
+    /** Period type */
+    period: ResetPeriod;
+}
+/**
+ * Weekend premium configuration
+ */
+interface WeekendPremium {
+    /** Saturday premium multiplier (e.g., 1.5 for time-and-a-half) */
+    saturday: number;
+    /** Sunday premium multiplier (e.g., 2.0 for double time) */
+    sunday: number;
+}
+/**
+ * Night shift differential configuration
+ */
+interface NightShiftDifferential {
+    /** Start hour (24h format, e.g., 22 = 10pm) */
+    startHour: number;
+    /** End hour (24h format, e.g., 6 = 6am) */
+    endHour: number;
+    /** Premium multiplier (e.g., 1.2 = 20% extra) */
+    multiplier: number;
+}
+/**
+ * Late arrival policy configuration
+ */
+interface LateArrivalPolicy {
+    /** Enable late arrival tracking */
+    enabled: boolean;
+    /** Grace period in minutes (no penalty if late < this) */
+    gracePeriod: number;
+    /** How to calculate penalty */
+    mode: PenaltyMode;
+    /** Fixed penalty amount per occurrence */
+    flatAmount?: number;
+    /** Penalty per minute late */
+    perMinuteRate?: number;
+    /** Penalty as percentage of daily wage (e.g., 2 = 2%) */
+    percentageRate?: number;
+    /** Progressive penalties based on occurrence count */
+    tiers?: PenaltyTier[];
+    /** Maximum penalties allowed per period */
+    maxPenaltiesPerPeriod?: MaxPenaltiesPerPeriod;
+    /** Maximum total penalty amount per period */
+    maxPenaltyAmount?: {
+        amount: number;
+        period: ResetPeriod;
+    };
+    /** When to reset occurrence counter */
+    resetOccurrenceCount?: ResetPeriod;
+}
+/**
+ * Early departure policy configuration
+ * (Same structure as late arrival)
+ */
+type EarlyDeparturePolicy = LateArrivalPolicy;
+/**
+ * Overtime bonus configuration
+ */
+interface OvertimePolicy {
+    /** Enable overtime bonuses */
+    enabled: boolean;
+    /** When overtime kicks in */
+    mode: OvertimeMode;
+    /** Hours per day before overtime (e.g., 8) */
+    dailyThreshold?: number;
+    /** Overtime multiplier for daily (e.g., 1.5 = time and half) */
+    dailyMultiplier?: number;
+    /** Hours per week before overtime (e.g., 40) */
+    weeklyThreshold?: number;
+    /** Overtime multiplier for weekly */
+    weeklyMultiplier?: number;
+    /** Hours per month before overtime (e.g., 160) */
+    monthlyThreshold?: number;
+    /** Overtime multiplier for monthly */
+    monthlyMultiplier?: number;
+    /** Weekend premium pay (null = disabled) */
+    weekendPremium?: WeekendPremium;
+    /** Night shift premium (null = disabled) */
+    nightShiftDifferential?: NightShiftDifferential;
+}
+/**
+ * Clock-in rounding configuration
+ */
+interface ClockRoundingPolicy {
+    /** Enable clock-in rounding */
+    enabled: boolean;
+    /** Round to nearest X minutes */
+    roundTo: 5 | 10 | 15;
+    /** Rounding mode */
+    mode: RoundingMode;
+}
+/**
+ * Complete attendance policy configuration.
+ *
+ * This is what organizations define and what we use for calculations.
+ * Users can store this in DB, config file, or pass directly.
+ */
+interface AttendancePolicy {
+    /** Unique policy ID (optional, for DB storage) */
+    id?: string;
+    /** Organization this policy belongs to (optional, for multi-tenant) */
+    organizationId?: ObjectIdLike;
+    /** Policy name for display */
+    name: string;
+    /** Policy description */
+    description?: string;
+    /** Who this policy applies to (optional, for targeted policies) */
+    appliesTo?: {
+        departments?: string[];
+        positions?: string[];
+        employeeIds?: ObjectIdLike[];
+        all?: boolean;
+    };
+    /** Late arrival rules */
+    lateArrival: LateArrivalPolicy;
+    /** Early departure rules */
+    earlyDeparture: EarlyDeparturePolicy;
+    /** Overtime bonus rules */
+    overtime: OvertimePolicy;
+    /** Clock-in rounding rules */
+    clockRounding?: ClockRoundingPolicy;
+    /** When this policy becomes effective */
+    effectiveFrom: Date;
+    /** When this policy expires (null = no expiry) */
+    effectiveTo?: Date | null;
+    /** Is this policy active */
+    active: boolean;
+}
+/**
+ * Single late arrival occurrence
+ */
+interface LateOccurrence {
+    /** Date of late arrival */
+    date: Date;
+    /** Scheduled clock-in time */
+    scheduledTime: Date;
+    /** Actual clock-in time */
+    actualTime: Date;
+    /** Minutes late (calculated: actual - scheduled) */
+    minutesLate: number;
+}
+/**
+ * Single early departure occurrence
+ */
+interface EarlyOccurrence {
+    /** Date of early departure */
+    date: Date;
+    /** Scheduled clock-out time */
+    scheduledTime: Date;
+    /** Actual clock-out time */
+    actualTime: Date;
+    /** Minutes early (calculated: scheduled - actual) */
+    minutesEarly: number;
+}
+/**
+ * Single overtime occurrence
+ */
+interface OvertimeOccurrence {
+    /** Date of overtime */
+    date: Date;
+    /** Type of overtime */
+    type: 'daily' | 'weekly' | 'monthly' | 'weekend-saturday' | 'weekend-sunday' | 'night-shift';
+    /** Overtime hours */
+    hours: number;
+    /** Applicable multiplier */
+    multiplier: number;
+}
+/**
+ * Shift compliance data for a period.
+ *
+ * This is what users send us - we do the calculations.
+ */
+interface ShiftComplianceData {
+    /** Number of late arrivals */
+    lateArrivals?: number;
+    /** Total minutes late (sum of all occurrences) */
+    totalLateMinutes?: number;
+    /** Detailed late occurrences (optional, for breakdown) */
+    lateOccurrences?: LateOccurrence[];
+    /** Number of early departures */
+    earlyDepartures?: number;
+    /** Total minutes early */
+    totalEarlyMinutes?: number;
+    /** Detailed early occurrences */
+    earlyOccurrences?: EarlyOccurrence[];
+    /** Total overtime hours */
+    overtimeHours?: number;
+    /** Total overtime days (for daily mode) */
+    overtimeDays?: number;
+    /** Detailed overtime breakdown */
+    overtimeOccurrences?: OvertimeOccurrence[];
+}
+/**
+ * Late penalty calculation result
+ */
+interface LatePenaltyResult {
+    /** Total penalty amount */
+    amount: number;
+    /** Number of occurrences processed */
+    occurrences: number;
+    /** Breakdown per occurrence */
+    breakdown: Array<{
+        date: Date;
+        minutesLate: number;
+        penaltyAmount: number;
+        tier?: number;
+        waived: boolean;
+        reason?: string;
+    }>;
+}
+/**
+ * Early departure penalty result
+ */
+type EarlyDeparturePenaltyResult = LatePenaltyResult;
+/**
+ * Overtime bonus calculation result
+ */
+interface OvertimeBonusResult {
+    /** Total bonus amount */
+    amount: number;
+    /** Total overtime hours */
+    hours: number;
+    /** Breakdown by type */
+    breakdown: Array<{
+        date: Date;
+        type: string;
+        hours: number;
+        rate: number;
+        multiplier: number;
+        amount: number;
+    }>;
+}
+/**
+ * Shift differential calculation result
+ */
+interface ShiftDifferentialResult {
+    /** Total differential amount */
+    amount: number;
+    /** Hours that qualify for differential */
+    hours: number;
+    /** Type of differential */
+    type: 'night' | 'weekend';
+    /** Multiplier applied */
+    multiplier: number;
+}
+/**
+ * Complete shift compliance calculation result.
+ *
+ * This is what we return after processing.
+ */
+interface ShiftComplianceResult {
+    /** Late arrival penalties */
+    latePenalty: LatePenaltyResult;
+    /** Early departure penalties */
+    earlyDeparturePenalty: EarlyDeparturePenaltyResult;
+    /** Overtime bonuses */
+    overtimeBonus: OvertimeBonusResult;
+    /** Shift differential bonuses (if any) */
+    shiftDifferential?: ShiftDifferentialResult;
+    /** Total penalties (to deduct from salary) */
+    totalPenalties: number;
+    /** Total bonuses (to add to salary) */
+    totalBonuses: number;
+    /** Net adjustment (bonuses - penalties) */
+    netAdjustment: number;
+    /** Compliance score (0-100) */
+    complianceScore: number;
+    /** Total occurrence count (late + early) */
+    occurrenceCount: number;
+    /** Is employee at risk (near termination threshold) */
+    isAtRisk: boolean;
+    /** Policy ID that was used */
+    policyId?: string;
+    /** Policy name */
+    policyName: string;
+}
+/**
+ * Input for shift compliance calculation
+ */
+interface CalculateShiftComplianceInput {
+    /** Attendance data for the period */
+    attendance: ShiftComplianceData;
+    /** Policy to apply */
+    policy: AttendancePolicy;
+    /** Daily wage (for percentage-based penalties) */
+    dailyWage: number;
+    /** Hourly rate (for overtime calculations) */
+    hourlyRate: number;
+    /** Current occurrence count (for tiered penalties, optional) */
+    currentOccurrenceCount?: number;
+    /** Employee ID (for logging, optional) */
+    employeeId?: ObjectIdLike;
+    /** Period info (for logging, optional) */
+    period?: {
+        month: number;
+        year: number;
+    };
+}
+/**
+ * Manager override for waiving penalties
+ */
+interface PenaltyOverride {
+    /** Which penalty to override */
+    penaltyId: string;
+    /** Employee affected */
+    employeeId: ObjectIdLike;
+    /** Manager who made the override */
+    overriddenBy: ObjectIdLike;
+    /** When the override was made */
+    overriddenAt: Date;
+    /** Original penalty amount */
+    originalAmount: number;
+    /** New amount (0 = fully waived) */
+    newAmount: number;
+    /** Reason for override */
+    reason: string;
+    /** Does this need approval */
+    approvalRequired?: boolean;
+    /** Who approved (if approval required) */
+    approvedBy?: ObjectIdLike;
+    /** When approved */
+    approvedAt?: Date;
+}
+
+/**
+ * @classytic/payroll - Late Penalty Calculator
+ *
+ * Pure functions for calculating late arrival penalties.
+ * No side effects, no DB calls - just math.
+ */
+
+/**
+ * Calculate penalty using flat rate per occurrence
+ *
+ * @example
+ * ```typescript
+ * // $50 per late occurrence
+ * const result = calculateFlatPenalty(3, 50);
+ * // → { amount: 150, occurrences: 3 }
+ * ```
+ */
+declare function calculateFlatPenalty(occurrenceCount: number, flatAmount: number): {
+    amount: number;
+    occurrences: number;
+};
+/**
+ * Calculate penalty based on minutes late
+ *
+ * @example
+ * ```typescript
+ * // $2 per minute, 45 minutes late
+ * const result = calculatePerMinutePenalty(45, 2);
+ * // → { amount: 90, minutes: 45 }
+ * ```
+ */
+declare function calculatePerMinutePenalty(totalMinutesLate: number, perMinuteRate: number): {
+    amount: number;
+    minutes: number;
+};
+/**
+ * Calculate penalty as percentage of daily wage
+ *
+ * @example
+ * ```typescript
+ * // 2% of $500 daily wage, 3 late occurrences
+ * const result = calculatePercentagePenalty(3, 2, 500);
+ * // → { amount: 30, percentage: 2 }
+ * ```
+ */
+declare function calculatePercentagePenalty(occurrenceCount: number, percentageRate: number, dailyWage: number): {
+    amount: number;
+    percentage: number;
+};
+/**
+ * Calculate total tiered penalties for multiple occurrences
+ *
+ * @example
+ * ```typescript
+ * const tiers = [
+ *   { from: 1, to: 2, penalty: 0, warning: true },
+ *   { from: 3, to: 4, penalty: 25 },
+ *   { from: 5, penalty: 50 },
+ * ];
+ *
+ * // Employee has 5 late occurrences
+ * const result = calculateTieredPenalty(5, 2, tiers);
+ * // → {
+ * //   amount: 125,  // 0 + 0 + 25 + 25 + 50
+ * //   breakdown: [...]
+ * // }
+ * ```
+ */
+declare function calculateTieredPenalty(newOccurrences: number, currentOccurrenceCount: number, tiers: PenaltyTier[]): {
+    amount: number;
+    breakdown: Array<{
+        occurrence: number;
+        penalty: number;
+        tier?: number;
+        warning: boolean;
+    }>;
+};
+/**
+ * Calculate late arrival penalties based on policy
+ *
+ * @example
+ * ```typescript
+ * const policy: LateArrivalPolicy = {
+ *   enabled: true,
+ *   gracePeriod: 5,
+ *   mode: 'flat',
+ *   flatAmount: 50,
+ * };
+ *
+ * const occurrences: LateOccurrence[] = [
+ *   { date: new Date(), scheduledTime, actualTime, minutesLate: 10 },
+ *   { date: new Date(), scheduledTime, actualTime, minutesLate: 3 },  // Within grace
+ * ];
+ *
+ * const result = calculateLatePenalty({
+ *   policy,
+ *   occurrences,
+ *   dailyWage: 500,
+ * });
+ * // → { amount: 50, occurrences: 1, breakdown: [...] }
+ * ```
+ */
+declare function calculateLatePenalty(input: {
+    policy: LateArrivalPolicy;
+    occurrences?: LateOccurrence[];
+    lateCount?: number;
+    totalLateMinutes?: number;
+    dailyWage?: number;
+    currentOccurrenceCount?: number;
+}): LatePenaltyResult;
+
+/**
+ * @classytic/payroll - Overtime Calculator
+ *
+ * Pure functions for calculating overtime bonuses.
+ * No side effects, no DB calls - just math.
+ */
+
+/**
+ * Calculate daily overtime bonus
+ *
+ * @example
+ * ```typescript
+ * // Employee worked 10 hours, threshold is 8, rate is $100/hour
+ * const result = calculateDailyOvertime(10, 8, 1.5, 100);
+ * // → { amount: 100, overtimeHours: 2 }
+ * // Calculation: 2 hours × $100 × 0.5 (extra) = $100
+ * ```
+ */
+declare function calculateDailyOvertime(hoursWorked: number, threshold: number, multiplier: number, hourlyRate: number): {
+    amount: number;
+    overtimeHours: number;
+};
+/**
+ * Calculate weekly overtime bonus
+ *
+ * @example
+ * ```typescript
+ * // Employee worked 45 hours, threshold is 40, rate is $100/hour
+ * const result = calculateWeeklyOvertime(45, 40, 1.5, 100);
+ * // → { amount: 250, overtimeHours: 5 }
+ * ```
+ */
+declare function calculateWeeklyOvertime(hoursWorked: number, threshold: number, multiplier: number, hourlyRate: number): {
+    amount: number;
+    overtimeHours: number;
+};
+/**
+ * Calculate monthly overtime bonus
+ *
+ * @example
+ * ```typescript
+ * // Employee worked 170 hours, threshold is 160
+ * const result = calculateMonthlyOvertime(170, 160, 1.5, 100);
+ * // → { amount: 500, overtimeHours: 10 }
+ * ```
+ */
+declare function calculateMonthlyOvertime(hoursWorked: number, threshold: number, multiplier: number, hourlyRate: number): {
+    amount: number;
+    overtimeHours: number;
+};
+/**
+ * Calculate weekend premium pay
+ *
+ * @example
+ * ```typescript
+ * // Employee worked 8 hours on Saturday
+ * const result = calculateWeekendPremium(8, 1.5, 100, 'saturday');
+ * // → { amount: 400, hours: 8 }
+ * // Regular: 8 × $100 = $800
+ * // Premium: 8 × $100 × 0.5 (extra) = $400
+ * ```
+ */
+declare function calculateWeekendPremium(hours: number, multiplier: number, hourlyRate: number, day: 'saturday' | 'sunday'): {
+    amount: number;
+    hours: number;
+    day: string;
+};
+/**
+ * Calculate night shift differential
+ *
+ * @example
+ * ```typescript
+ * // Employee worked 8 hours during night shift (10pm-6am)
+ * const result = calculateNightShiftDifferential(8, 1.2, 100);
+ * // → { amount: 160, hours: 8 }
+ * // Differential: 8 × $100 × 0.2 (extra) = $160
+ * ```
+ */
+declare function calculateNightShiftDifferential(hours: number, multiplier: number, hourlyRate: number): {
+    amount: number;
+    hours: number;
+};
+/**
+ * Calculate all overtime bonuses based on policy
+ *
+ * @example
+ * ```typescript
+ * const policy: OvertimePolicy = {
+ *   enabled: true,
+ *   mode: 'daily',
+ *   dailyThreshold: 8,
+ *   dailyMultiplier: 1.5,
+ * };
+ *
+ * const occurrences: OvertimeOccurrence[] = [
+ *   { date: new Date(), type: 'daily', hours: 2, multiplier: 1.5 },
+ *   { date: new Date(), type: 'weekend-sunday', hours: 8, multiplier: 2.0 },
+ * ];
+ *
+ * const result = calculateOvertimeBonus({
+ *   policy,
+ *   occurrences,
+ *   hourlyRate: 100,
+ * });
+ * ```
+ */
+declare function calculateOvertimeBonus(input: {
+    policy: OvertimePolicy;
+    occurrences?: OvertimeOccurrence[];
+    overtimeHours?: number;
+    overtimeDays?: number;
+    hourlyRate: number;
+}): OvertimeBonusResult;
+
+/**
+ * @classytic/payroll - Shift Compliance Calculators
+ *
+ * Main calculator that orchestrates all shift compliance calculations.
+ */
+
+/**
+ * Calculate complete shift compliance adjustments.
+ *
+ * This is the main function users call. It takes attendance data + policy
+ * and returns penalties + bonuses.
+ *
+ * @example
+ * ```typescript
+ * const attendance: ShiftComplianceData = {
+ *   lateArrivals: 3,
+ *   totalLateMinutes: 45,
+ *   earlyDepartures: 1,
+ *   totalEarlyMinutes: 20,
+ *   overtimeHours: 8,
+ * };
+ *
+ * const policy: AttendancePolicy = {
+ *   name: 'Manufacturing Policy',
+ *   lateArrival: {
+ *     enabled: true,
+ *     gracePeriod: 0,
+ *     mode: 'flat',
+ *     flatAmount: 50,
+ *   },
+ *   earlyDeparture: {
+ *     enabled: true,
+ *     gracePeriod: 0,
+ *     mode: 'flat',
+ *     flatAmount: 75,
+ *   },
+ *   overtime: {
+ *     enabled: true,
+ *     mode: 'daily',
+ *     dailyThreshold: 8,
+ *     dailyMultiplier: 1.5,
+ *   },
+ *   effectiveFrom: new Date(),
+ *   active: true,
+ * };
+ *
+ * const result = calculateShiftCompliance({
+ *   attendance,
+ *   policy,
+ *   dailyWage: 1500,
+ *   hourlyRate: 200,
+ * });
+ *
+ * // result = {
+ * //   latePenalty: { amount: 150, ... },
+ * //   earlyDeparturePenalty: { amount: 75, ... },
+ * //   overtimeBonus: { amount: 800, ... },
+ * //   totalPenalties: 225,
+ * //   totalBonuses: 800,
+ * //   netAdjustment: 575,  // +800 - 225
+ * //   ...
+ * // }
+ * ```
+ */
+declare function calculateShiftCompliance(input: CalculateShiftComplianceInput): ShiftComplianceResult;
+
+/**
+ * @classytic/payroll - Shift Compliance Configuration
+ *
+ * Default configurations and industry-standard preset policies.
+ */
+
+/**
+ * Default attendance policy (moderate, office-friendly)
+ */
+declare const DEFAULT_ATTENDANCE_POLICY: Omit<AttendancePolicy, 'name' | 'effectiveFrom' | 'active'>;
+/**
+ * Manufacturing/Factory policy (strict, zero tolerance)
+ */
+declare const MANUFACTURING_POLICY: Omit<AttendancePolicy, 'name' | 'effectiveFrom' | 'active'>;
+/**
+ * Retail policy (flexible with weekend premiums)
+ */
+declare const RETAIL_POLICY: Omit<AttendancePolicy, 'name' | 'effectiveFrom' | 'active'>;
+/**
+ * Office/Tech policy (very flexible, progressive discipline)
+ */
+declare const OFFICE_POLICY: Omit<AttendancePolicy, 'name' | 'effectiveFrom' | 'active'>;
+/**
+ * Healthcare policy (night shift differential, weekend premiums)
+ */
+declare const HEALTHCARE_POLICY: Omit<AttendancePolicy, 'name' | 'effectiveFrom' | 'active'>;
+/**
+ * Hospitality policy (flexible, weekend/night premiums)
+ */
+declare const HOSPITALITY_POLICY: Omit<AttendancePolicy, 'name' | 'effectiveFrom' | 'active'>;
+/**
+ * Get a complete policy from a preset
+ *
+ * @example
+ * ```typescript
+ * const policy = createPolicyFromPreset('manufacturing', {
+ *   name: 'Factory Floor Policy',
+ *   organizationId: orgId,
+ * });
+ * ```
+ */
+declare function createPolicyFromPreset(preset: 'default' | 'manufacturing' | 'retail' | 'office' | 'healthcare' | 'hospitality', overrides?: Partial<AttendancePolicy>): AttendancePolicy;
+
+/**
+ * @classytic/payroll - Shift Compliance Fluent Builders
+ *
+ * DX-friendly fluent API for creating attendance policies programmatically.
+ *
+ * @example
+ * ```typescript
+ * const policy = AttendancePolicyBuilder.create()
+ *   .named('Tech Department Policy')
+ *   .description('Flexible policy for tech workers')
+ *   .lateArrival()
+ *     .enable()
+ *     .gracePeriod(15)
+ *     .tieredPenalty()
+ *       .tier(1, 3).warning()
+ *       .tier(4, 5).penalty(20)
+ *       .tier(6).penalty(40)
+ *     .end()
+ *     .maxPenalties(3, 'monthly')
+ *     .resetOccurrences('quarterly')
+ *   .end()
+ *   .overtime()
+ *     .enable()
+ *     .mode('weekly')
+ *     .weeklyThreshold(40, 1.5)
+ *   .end()
+ *   .build();
+ * ```
+ */
+
+/**
+ * Builder for late arrival or early departure policies.
+ * Uses same structure for both since the logic is identical.
+ */
+declare class LatePolicyBuilder<TParent = unknown> {
+    private policy;
+    private parent?;
+    constructor(parent?: TParent);
+    /**
+     * Enable this policy
+     */
+    enable(): this;
+    /**
+     * Disable this policy
+     */
+    disable(): this;
+    /**
+     * Set grace period in minutes (how many minutes late before penalty applies)
+     */
+    gracePeriod(minutes: number): this;
+    /**
+     * Use flat penalty mode (same penalty for each occurrence)
+     *
+     * @param amount - Penalty amount per occurrence
+     */
+    flatPenalty(amount: number): this;
+    /**
+     * Use per-minute penalty mode (penalty based on minutes late)
+     *
+     * @param rate - Penalty per minute late
+     */
+    perMinutePenalty(rate: number): this;
+    /**
+     * Use percentage penalty mode (percentage of daily wage)
+     *
+     * @param percentage - Percentage of daily wage (e.g., 2 for 2%)
+     */
+    percentagePenalty(percentage: number): this;
+    /**
+     * Start building tiered penalty (progressive discipline)
+     *
+     * @example
+     * ```typescript
+     * .tieredPenalty()
+     *   .tier(1, 2).warning()
+     *   .tier(3, 4).penalty(25)
+     *   .tier(5).penalty(50)
+     * .end()
+     * ```
+     */
+    tieredPenalty(): TieredPenaltyBuilder<this>;
+    /**
+     * Set maximum penalties per period (caps total penalties)
+     *
+     * @param count - Max number of penalties
+     * @param period - Period type ('daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly')
+     */
+    maxPenalties(count: number, period: 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly'): this;
+    /**
+     * Set when to reset occurrence counter
+     *
+     * @param period - Reset period ('monthly' | 'quarterly' | 'yearly')
+     */
+    resetOccurrences(period: 'monthly' | 'quarterly' | 'yearly'): this;
+    /**
+     * Add a custom tier (advanced usage)
+     */
+    addTier(tier: PenaltyTier): this;
+    /**
+     * Finish building this policy and return to parent builder
+     */
+    end(): TParent;
+    /**
+     * Build the policy (for standalone usage)
+     */
+    build(): LateArrivalPolicy;
+    /** @internal */
+    _getPolicy(): Partial<LateArrivalPolicy>;
+}
+/**
+ * Builder for tiered penalties (progressive discipline)
+ */
+declare class TieredPenaltyBuilder<TParent> {
+    private tiers;
+    private parent;
+    private currentTier;
+    constructor(parent: TParent);
+    /**
+     * Start a new tier
+     *
+     * @param from - Starting occurrence number (1-indexed)
+     * @param to - Ending occurrence number (optional, omit for open-ended tier)
+     */
+    tier(from: number, to?: number): this;
+    /**
+     * Set this tier as warning only (no financial penalty)
+     */
+    warning(): this;
+    /**
+     * Set penalty amount for this tier
+     */
+    penalty(amount: number): this;
+    /**
+     * Finish building tiers and return to parent
+     */
+    end(): TParent;
+    private saveTier;
+}
+/**
+ * Builder for overtime policies
+ */
+declare class OvertimePolicyBuilder<TParent = unknown> {
+    private policy;
+    private parent?;
+    constructor(parent?: TParent);
+    /**
+     * Enable overtime calculations
+     */
+    enable(): this;
+    /**
+     * Disable overtime calculations
+     */
+    disable(): this;
+    /**
+     * Set overtime calculation mode
+     */
+    mode(mode: 'daily' | 'weekly' | 'monthly'): this;
+    /**
+     * Set daily overtime threshold and multiplier
+     *
+     * @param hours - Hours threshold (e.g., 8)
+     * @param multiplier - Overtime multiplier (e.g., 1.5 for time-and-a-half)
+     */
+    dailyThreshold(hours: number, multiplier: number): this;
+    /**
+     * Set weekly overtime threshold and multiplier
+     *
+     * @param hours - Hours threshold (e.g., 40)
+     * @param multiplier - Overtime multiplier (e.g., 1.5 for time-and-a-half)
+     */
+    weeklyThreshold(hours: number, multiplier: number): this;
+    /**
+     * Set monthly overtime threshold and multiplier
+     *
+     * @param hours - Hours threshold (e.g., 160)
+     * @param multiplier - Overtime multiplier (e.g., 2.0 for double time)
+     */
+    monthlyThreshold(hours: number, multiplier: number): this;
+    /**
+     * Set weekend premium rates
+     *
+     * @param saturday - Saturday multiplier (e.g., 1.5)
+     * @param sunday - Sunday multiplier (e.g., 2.0)
+     */
+    weekendPremium(saturday: number, sunday: number): this;
+    /**
+     * Set night shift differential
+     *
+     * @param startHour - Start hour (24-hour format, e.g., 22 for 10pm)
+     * @param endHour - End hour (24-hour format, e.g., 6 for 6am)
+     * @param multiplier - Night shift multiplier (e.g., 1.3 for 30% premium)
+     */
+    nightShiftDifferential(startHour: number, endHour: number, multiplier: number): this;
+    /**
+     * Finish building this policy and return to parent builder
+     */
+    end(): TParent;
+    /**
+     * Build the policy (for standalone usage)
+     */
+    build(): OvertimePolicy;
+    /** @internal */
+    _getPolicy(): Partial<OvertimePolicy>;
+}
+/**
+ * Builder for clock rounding policies
+ */
+declare class ClockRoundingPolicyBuilder<TParent = unknown> {
+    private policy;
+    private parent?;
+    constructor(parent?: TParent);
+    /**
+     * Enable clock rounding
+     */
+    enable(): this;
+    /**
+     * Disable clock rounding
+     */
+    disable(): this;
+    /**
+     * Set rounding interval in minutes
+     *
+     * @param minutes - Round to nearest N minutes (e.g., 5, 10, 15)
+     */
+    roundTo(minutes: 5 | 10 | 15): this;
+    /**
+     * Set rounding mode
+     *
+     * @param mode - 'up' (favor employee) | 'down' (favor employer) | 'nearest' (neutral)
+     */
+    roundingMode(mode: 'up' | 'down' | 'nearest'): this;
+    /**
+     * Finish building this policy and return to parent builder
+     */
+    end(): TParent;
+    /**
+     * Build the policy (for standalone usage)
+     */
+    build(): ClockRoundingPolicy;
+    /** @internal */
+    _getPolicy(): Partial<ClockRoundingPolicy>;
+}
+/**
+ * Main builder for creating complete attendance policies
+ *
+ * @example
+ * ```typescript
+ * const policy = AttendancePolicyBuilder.create()
+ *   .named('Manufacturing Policy')
+ *   .description('Strict policy for factory floor')
+ *   .organizationId(orgId)
+ *   .lateArrival()
+ *     .enable()
+ *     .gracePeriod(0)
+ *     .flatPenalty(100)
+ *     .maxPenalties(5, 'monthly')
+ *     .resetOccurrences('quarterly')
+ *   .end()
+ *   .earlyDeparture()
+ *     .enable()
+ *     .gracePeriod(0)
+ *     .flatPenalty(150)
+ *   .end()
+ *   .overtime()
+ *     .enable()
+ *     .mode('daily')
+ *     .dailyThreshold(8, 1.5)
+ *     .weeklyThreshold(40, 2.0)
+ *   .end()
+ *   .clockRounding()
+ *     .enable()
+ *     .roundTo(15)
+ *     .roundingMode('down')
+ *   .end()
+ *   .effectiveFrom(new Date('2025-01-01'))
+ *   .build();
+ * ```
+ */
+declare class AttendancePolicyBuilder {
+    private policy;
+    private lateArrivalBuilder?;
+    private earlyDepartureBuilder?;
+    private overtimeBuilder?;
+    private clockRoundingBuilder?;
+    /**
+     * Create a new policy builder
+     */
+    static create(): AttendancePolicyBuilder;
+    /**
+     * Set policy name
+     */
+    named(name: string): this;
+    /**
+     * Set policy description
+     */
+    description(description: string): this;
+    /**
+     * Set organization ID (for multi-tenant systems)
+     */
+    organizationId(id: ObjectIdLike): this;
+    /**
+     * Set policy ID (for updates)
+     */
+    id(id: string): this;
+    /**
+     * Set effective from date
+     */
+    effectiveFrom(date: Date): this;
+    /**
+     * Set effective to date (when policy expires)
+     */
+    effectiveTo(date: Date | null): this;
+    /**
+     * Set policy active status
+     */
+    active(active: boolean): this;
+    /**
+     * Start building late arrival policy
+     */
+    lateArrival(): LatePolicyBuilder<this>;
+    /**
+     * Start building early departure policy
+     */
+    earlyDeparture(): LatePolicyBuilder<this>;
+    /**
+     * Start building overtime policy
+     */
+    overtime(): OvertimePolicyBuilder<this>;
+    /**
+     * Start building clock rounding policy
+     */
+    clockRounding(): ClockRoundingPolicyBuilder<this>;
+    /**
+     * Build the complete attendance policy
+     */
+    build(): AttendancePolicy;
+}
+/**
+ * Create a standalone late arrival policy builder
+ */
+declare function createLatePolicyBuilder(): LatePolicyBuilder<void>;
+/**
+ * Create a standalone overtime policy builder
+ */
+declare function createOvertimePolicyBuilder(): OvertimePolicyBuilder<void>;
+/**
+ * Create a standalone clock rounding policy builder
+ */
+declare function createClockRoundingPolicyBuilder(): ClockRoundingPolicyBuilder<void>;
+
+/**
+ * Schema definition for penalty tiers (progressive discipline)
+ */
+declare const PenaltyTierSchemaDefinition: SchemaDefinition;
+/**
+ * Schema for penalty tiers
+ */
+declare const PenaltyTierSchema: Schema;
+/**
+ * Schema definition for max penalties per period
+ */
+declare const MaxPenaltiesSchemaDefinition: SchemaDefinition;
+/**
+ * Schema for max penalties per period
+ */
+declare const MaxPenaltiesSchema: Schema;
+/**
+ * Schema definition for late arrival policy
+ */
+declare const LateArrivalPolicySchemaDefinition: SchemaDefinition;
+/**
+ * Schema for late arrival policy
+ */
+declare const LateArrivalPolicySchema: Schema;
+/**
+ * Schema definition for early departure policy
+ * (Same structure as late arrival policy)
+ */
+declare const EarlyDeparturePolicySchemaDefinition: {
+    [path: string]: mongoose.SchemaDefinitionProperty<undefined, any, any>;
+};
+/**
+ * Schema for early departure policy
+ */
+declare const EarlyDeparturePolicySchema: Schema;
+/**
+ * Schema definition for weekend premium
+ */
+declare const WeekendPremiumSchemaDefinition: SchemaDefinition;
+/**
+ * Schema for weekend premium
+ */
+declare const WeekendPremiumSchema: Schema;
+/**
+ * Schema definition for night shift differential
+ */
+declare const NightShiftDifferentialSchemaDefinition: SchemaDefinition;
+/**
+ * Schema for night shift differential
+ */
+declare const NightShiftDifferentialSchema: Schema;
+/**
+ * Schema definition for overtime policy
+ */
+declare const OvertimePolicySchemaDefinition: SchemaDefinition;
+/**
+ * Schema for overtime policy
+ */
+declare const OvertimePolicySchema: Schema;
+/**
+ * Schema definition for clock rounding policy
+ */
+declare const ClockRoundingPolicySchemaDefinition: SchemaDefinition;
+/**
+ * Schema for clock rounding policy
+ */
+declare const ClockRoundingPolicySchema: Schema;
+/**
+ * Schema definition for attendance policy
+ *
+ * Users can extend this with their own fields:
+ * ```typescript
+ * const CustomPolicySchema = new Schema({
+ *   ...AttendancePolicySchemaDefinition,
+ *   approvedBy: { type: Schema.Types.ObjectId, ref: 'User' },
+ *   department: String,
+ * });
+ * ```
+ */
+declare const AttendancePolicySchemaDefinition: SchemaDefinition;
+/**
+ * Main Attendance Policy Schema
+ *
+ * @example
+ * ```typescript
+ * import { AttendancePolicySchema } from '@classytic/payroll';
+ * import { model } from 'mongoose';
+ *
+ * const AttendancePolicy = model('AttendancePolicy', AttendancePolicySchema);
+ *
+ * // Create a new policy
+ * const policy = new AttendancePolicy({
+ *   name: 'Tech Department Policy',
+ *   lateArrival: { ... },
+ *   earlyDeparture: { ... },
+ *   overtime: { ... },
+ * });
+ * await policy.save();
+ * ```
+ */
+declare const AttendancePolicySchema: Schema;
+/**
+ * Instance methods interface
+ */
+interface AttendancePolicyDocument {
+    isCurrentlyActive(): boolean;
+}
+/**
+ * Static methods interface
+ */
+interface AttendancePolicyModel {
+    findActiveForOrganization(organizationId: any, date?: Date): Promise<any>;
+}
+
+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 };