@classytic/payroll 1.0.0 → 2.7.5

package/dist/types-BVDjiVGS.d.ts

@@ -0,0 +1,1856 @@
+import * as mongoose from 'mongoose';
+import { Types, ClientSession, Document, Model } from 'mongoose';
+
+/**
+ * @classytic/payroll - Event System
+ *
+ * Type-safe event emitter for payroll lifecycle events
+ * Enables loose coupling and extensibility
+ */
+
+interface EmployeeHiredEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+        position: string;
+        department?: string;
+    };
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface EmployeeTerminatedEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+        name?: string;
+    };
+    terminationDate: Date;
+    reason?: string;
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface EmployeeRehiredEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+        position: string;
+    };
+    previousTerminationDate?: Date;
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface SalaryUpdatedEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+    };
+    previousSalary: number;
+    newSalary: number;
+    effectiveFrom: Date;
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface SalaryProcessedEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+        name?: string;
+    };
+    payroll: {
+        id: ObjectId;
+        period: {
+            month: number;
+            year: number;
+        };
+        grossAmount: number;
+        netAmount: number;
+    };
+    transactionId: ObjectId;
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface SalaryFailedEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+    };
+    period: {
+        month: number;
+        year: number;
+    };
+    error: string;
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface PayrollCompletedEventPayload {
+    organizationId: ObjectId;
+    period: {
+        month: number;
+        year: number;
+    };
+    summary: {
+        total: number;
+        successful: number;
+        failed: number;
+        totalAmount: number;
+    };
+    context?: OperationContext;
+}
+interface PayrollExportedEventPayload {
+    organizationId: ObjectId;
+    dateRange: {
+        start: Date;
+        end: Date;
+    };
+    recordCount: number;
+    format: string;
+    context?: OperationContext;
+}
+interface CompensationChangedEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+    };
+    changeType: 'allowance_added' | 'allowance_removed' | 'deduction_added' | 'deduction_removed';
+    details: {
+        type: string;
+        amount: number;
+    };
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface MilestoneAchievedEventPayload {
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+        name?: string;
+    };
+    milestone: {
+        type: 'tenure' | 'salary' | 'payments';
+        value: number;
+        message: string;
+    };
+    organizationId: ObjectId;
+}
+interface TaxWithheldEventPayload {
+    withholding: {
+        id: ObjectId;
+        taxType: string;
+        amount: number;
+    };
+    employee: {
+        id: ObjectId;
+        employeeId: string;
+    };
+    payrollRecord: {
+        id: ObjectId;
+    };
+    period: {
+        month: number;
+        year: number;
+    };
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface TaxPaidEventPayload {
+    withholdings: Array<{
+        id: ObjectId;
+        taxType: string;
+        amount: number;
+    }>;
+    transaction?: {
+        id: ObjectId;
+        amount: number;
+    };
+    totalAmount: number;
+    referenceNumber?: string;
+    paidAt: Date;
+    organizationId: ObjectId;
+    context?: OperationContext;
+}
+interface TaxVoidedEventPayload {
+    withholdings: Array<{
+        id: ObjectId;
+        taxType: string;
+        amount: number;
+    }>;
+    payrollRecordId: ObjectId;
+    organizationId: ObjectId;
+    reason: string;
+    voidedAt: Date;
+    voidedBy?: ObjectIdLike;
+}
+interface PayrollEventMap {
+    'employee:hired': EmployeeHiredEventPayload;
+    'employee:terminated': EmployeeTerminatedEventPayload;
+    'employee:rehired': EmployeeRehiredEventPayload;
+    'salary:updated': SalaryUpdatedEventPayload;
+    'salary:processed': SalaryProcessedEventPayload;
+    'salary:failed': SalaryFailedEventPayload;
+    'payroll:completed': PayrollCompletedEventPayload;
+    'payroll:exported': PayrollExportedEventPayload;
+    'compensation:changed': CompensationChangedEventPayload;
+    'milestone:achieved': MilestoneAchievedEventPayload;
+    'tax:withheld': TaxWithheldEventPayload;
+    'tax:paid': TaxPaidEventPayload;
+    'tax:voided': TaxVoidedEventPayload;
+}
+type PayrollEventType = keyof PayrollEventMap;
+type EventHandler<T> = (payload: T) => void | Promise<void>;
+type PayrollEventHandler<K extends PayrollEventType> = EventHandler<PayrollEventMap[K]>;
+declare class EventBus {
+    private handlers;
+    /**
+     * Register an event handler
+     */
+    on<K extends PayrollEventType>(event: K, handler: PayrollEventHandler<K>): () => void;
+    /**
+     * Register a one-time event handler
+     */
+    once<K extends PayrollEventType>(event: K, handler: PayrollEventHandler<K>): () => void;
+    /**
+     * Remove an event handler
+     */
+    off<K extends PayrollEventType>(event: K, handler: PayrollEventHandler<K>): void;
+    /**
+     * Emit an event
+     */
+    emit<K extends PayrollEventType>(event: K, payload: PayrollEventMap[K]): Promise<void>;
+    /**
+     * Emit event synchronously (fire-and-forget)
+     */
+    emitSync<K extends PayrollEventType>(event: K, payload: PayrollEventMap[K]): void;
+    /**
+     * Remove all handlers for an event
+     */
+    removeAllListeners(event?: PayrollEventType): void;
+    /**
+     * Get listener count for an event
+     */
+    listenerCount(event: PayrollEventType): number;
+    /**
+     * Get all registered events
+     */
+    eventNames(): PayrollEventType[];
+}
+
+/**
+ * Webhook System
+ * Sends HTTP notifications when payroll events occur
+ */
+
+interface WebhookConfig {
+    url: string;
+    events: PayrollEventType[];
+    secret?: string;
+    headers?: Record<string, string>;
+    retries?: number;
+    timeout?: number;
+}
+interface WebhookDelivery {
+    id: string;
+    event: PayrollEventType;
+    url: string;
+    payload: unknown;
+    attempt: number;
+    status: 'pending' | 'sent' | 'failed';
+    response?: {
+        status: number;
+        body: string;
+    };
+    error?: string;
+    sentAt?: Date;
+}
+declare class WebhookManager {
+    private webhooks;
+    private deliveryLog;
+    /**
+     * Register a webhook
+     */
+    register(config: WebhookConfig): void;
+    /**
+     * Remove a webhook
+     */
+    unregister(url: string): void;
+    /**
+     * Send webhook for event
+     */
+    send<K extends PayrollEventType>(event: K, payload: PayrollEventMap[K]): Promise<void>;
+    /**
+     * Deliver webhook with retries
+     */
+    private deliver;
+    /**
+     * Generate HMAC-SHA256 signature for webhook (Stripe-style)
+     *
+     * Format: t=<timestamp>,v1=<hmac_signature>
+     *
+     * The signed payload is: timestamp.JSON(requestBody)
+     * where requestBody = { event, payload, deliveredAt }
+     *
+     * Consumers should verify:
+     * 1. Timestamp is within tolerance (e.g., 5 minutes)
+     * 2. HMAC signature matches
+     *
+     * @example Verify signature (consumer side)
+     * ```typescript
+     * import crypto from 'crypto';
+     *
+     * const signature = req.headers['x-payroll-signature'];
+     * const timestamp = req.headers['x-payroll-timestamp'];
+     * const requestBody = req.body; // { event, payload, deliveredAt }
+     *
+     * // Check timestamp (replay protection)
+     * const now = Math.floor(Date.now() / 1000);
+     * if (Math.abs(now - parseInt(timestamp)) > 300) {
+     *   throw new Error('Signature expired');
+     * }
+     *
+     * // Verify signature
+     * const signedPayload = `${timestamp}.${JSON.stringify(requestBody)}`;
+     * const expectedSignature = crypto
+     *   .createHmac('sha256', secret)
+     *   .update(signedPayload)
+     *   .digest('hex');
+     *
+     * const parts = signature.split(',');
+     * const providedSignature = parts.find(p => p.startsWith('v1='))?.split('=')[1];
+     *
+     * if (providedSignature !== expectedSignature) {
+     *   throw new Error('Invalid signature');
+     * }
+     * ```
+     */
+    private generateSignature;
+    /**
+     * Sleep for ms
+     */
+    private sleep;
+    /**
+     * Get delivery log
+     */
+    getDeliveries(options?: {
+        event?: PayrollEventType;
+        status?: WebhookDelivery['status'];
+        limit?: number;
+    }): WebhookDelivery[];
+    /**
+     * Clear delivery log
+     */
+    clearLog(): void;
+    /**
+     * Get all registered webhooks
+     */
+    getWebhooks(): WebhookConfig[];
+}
+
+/**
+ * @classytic/payroll - Configuration & Calculation Utilities
+ *
+ * DESIGN PRINCIPLES:
+ * 1. Accept data, don't manage it
+ * 2. Pure functions - easy to test, no side effects
+ * 3. Smart defaults that work out of the box
+ * 4. Override at operation time when needed
+ *
+ * The payroll package CALCULATES, it doesn't STORE calendars/holidays.
+ * Your app manages that data and passes it when needed.
+ */
+/** Work schedule configuration */
+interface WorkSchedule$1 {
+    /** Working days (0=Sun, 1=Mon, ..., 6=Sat). Default: Mon-Fri */
+    workingDays: number[];
+    /** Hours per work day. Default: 8 */
+    hoursPerDay: number;
+}
+/** Options passed when processing payroll */
+interface PayrollProcessingOptions {
+    /** Holidays in this period (from YOUR app's holiday model) */
+    holidays?: Date[];
+    /** Override work schedule for this operation */
+    workSchedule?: Partial<WorkSchedule$1>;
+    /** Skip tax calculation */
+    skipTax?: boolean;
+    /** Skip proration (pay full amount regardless of hire/termination date) */
+    skipProration?: boolean;
+    /** Skip attendance deduction */
+    skipAttendance?: boolean;
+}
+/** Attendance data (from YOUR attendance system) */
+interface AttendanceInput {
+    /**
+     * Expected work days in period.
+     * If not provided, derived from employee's workSchedule and period dates.
+     */
+    expectedDays?: number;
+    /** Actual days worked */
+    actualDays: number;
+}
+
+/**
+ * @classytic/payroll - Plugin System
+ *
+ * Extensible plugin architecture for customization
+ * Follows patterns from popular libraries like Mongoose, Fastify
+ */
+
+interface PluginContext {
+    /** Payroll instance */
+    payroll: PayrollInstance;
+    /** Event bus for subscribing to events */
+    events: EventBus;
+    /** Logger instance */
+    logger: PluginLogger;
+    /** Configuration getter */
+    getConfig: <T>(key: string) => T | undefined;
+    /** Register a hook */
+    addHook: <K extends PayrollEventType>(event: K, handler: (payload: PayrollEventMap[K]) => void | Promise<void>) => () => void;
+}
+interface PluginLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+interface PluginHooks {
+    /** Called before employee is hired */
+    beforeHire?: (params: unknown) => void | Promise<void>;
+    /** Called after employee is hired */
+    afterHire?: (employee: unknown) => void | Promise<void>;
+    /** Called before salary is processed */
+    beforeProcessSalary?: (params: unknown) => void | Promise<void>;
+    /** Called after salary is processed */
+    afterProcessSalary?: (result: unknown) => void | Promise<void>;
+    /** Called before termination */
+    beforeTerminate?: (params: unknown) => void | Promise<void>;
+    /** Called after termination */
+    afterTerminate?: (employee: unknown) => void | Promise<void>;
+    /** Called on any error */
+    onError?: (error: Error, context: string) => void | Promise<void>;
+}
+interface PayrollPluginDefinition {
+    name: string;
+    version?: string;
+    hooks?: PluginHooks;
+    init?: (context: PluginContext) => void | Promise<void>;
+    destroy?: () => void | Promise<void>;
+}
+
+/** Query filter type */
+type FilterQuery<T> = {
+    [P in keyof T]?: T[P] | {
+        $in?: T[P][];
+    } | {
+        $ne?: T[P];
+    } | {
+        $gte?: T[P];
+    } | {
+        $lte?: T[P];
+    };
+} & Record<string, unknown>;
+/** Re-export mongoose ObjectId */
+type ObjectId = Types.ObjectId;
+/** ObjectId or string representation */
+type ObjectIdLike = ObjectId | string;
+/** Generic document type */
+type AnyDocument = Document & Record<string, unknown>;
+/** Generic model type */
+type AnyModel = Model<AnyDocument>;
+/** Deep partial type for nested objects */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/** Nullable type helper */
+type Nullable<T> = T | null;
+/** Employment type */
+type EmploymentType = 'full_time' | 'part_time' | 'contract' | 'intern' | 'consultant';
+/** Employee status */
+type EmployeeStatus = 'active' | 'on_leave' | 'suspended' | 'terminated';
+/** Department type */
+type Department = 'management' | 'training' | 'sales' | 'operations' | 'support' | 'hr' | 'maintenance' | 'marketing' | 'finance' | 'it';
+/** Payment frequency */
+type PaymentFrequency = 'monthly' | 'bi_weekly' | 'weekly' | 'hourly' | 'daily';
+/** Payment method */
+type PaymentMethod = 'bank' | 'cash' | 'check' | 'mobile' | 'bkash' | 'nagad' | 'rocket';
+/** Allowance type */
+type AllowanceType = 'housing' | 'transport' | 'meal' | 'mobile' | 'medical' | 'education' | 'bonus' | 'other';
+/** Deduction type */
+type DeductionType = 'tax' | 'loan' | 'advance' | 'provident_fund' | 'insurance' | 'absence' | 'other';
+/** Payroll status */
+type PayrollStatus = 'pending' | 'processing' | 'paid' | 'failed' | 'voided' | 'reversed';
+/** Termination reason */
+type TerminationReason = 'resignation' | 'retirement' | 'termination' | 'contract_end' | 'mutual_agreement' | 'other';
+/** HRM transaction category */
+type HRMTransactionCategory = 'salary' | 'bonus' | 'commission' | 'overtime' | 'severance';
+/** Salary band */
+type SalaryBand = 'intern' | 'junior' | 'mid' | 'senior' | 'lead' | 'executive' | 'custom';
+/** Organization role (app-defined) */
+type OrgRole = string;
+/** Leave type */
+type LeaveType = 'annual' | 'sick' | 'unpaid' | 'maternity' | 'paternity' | 'bereavement' | 'compensatory' | 'other';
+/** Leave request status */
+type LeaveRequestStatus = 'pending' | 'approved' | 'rejected' | 'cancelled';
+/** Data retention configuration */
+interface DataRetentionConfig {
+    /** TTL for payroll records in seconds (default: 2 years) */
+    payrollRecordsTTL: number;
+    /** Days before TTL to warn (default: 30) */
+    exportWarningDays: number;
+    /** Archive records before deletion */
+    archiveBeforeDeletion: boolean;
+}
+/** Payroll configuration */
+interface PayrollConfig {
+    /** Default currency code */
+    defaultCurrency: string;
+    /** Allow pro-rating for mid-month hires */
+    allowProRating: boolean;
+    /** Enable attendance integration */
+    attendanceIntegration: boolean;
+    /** Auto-apply deductions */
+    autoDeductions: boolean;
+    /** Enable overtime calculations */
+    overtimeEnabled: boolean;
+    /** Overtime multiplier (e.g., 1.5 for 150%) */
+    overtimeMultiplier: number;
+}
+/** Salary configuration */
+interface SalaryConfig {
+    /** Minimum wage threshold */
+    minimumWage: number;
+    /** Maximum number of allowances */
+    maximumAllowances: number;
+    /** Maximum number of deductions */
+    maximumDeductions: number;
+    /** Default payment frequency */
+    defaultFrequency: PaymentFrequency;
+}
+/** Employment configuration */
+interface EmploymentConfig {
+    /** Default probation period in months */
+    defaultProbationMonths: number;
+    /** Maximum probation period in months */
+    maxProbationMonths: number;
+    /** Allow re-hiring terminated employees */
+    allowReHiring: boolean;
+    /** Track employment history */
+    trackEmploymentHistory: boolean;
+}
+/** Employee identity mode - how employees are identified and looked up */
+type EmployeeIdentityMode = 'userId' | 'employeeId' | 'email' | 'any';
+/** Validation configuration */
+interface ValidationConfig {
+    /** Require bank details for salary payment */
+    requireBankDetails: boolean;
+    /** Require userId for all employees (false = allow guest employees) */
+    requireUserId: boolean;
+    /** Primary identity mode for lookups */
+    identityMode: EmployeeIdentityMode;
+    /** Fallback modes if primary lookup fails */
+    identityFallbacks: EmployeeIdentityMode[];
+}
+/** Tax bracket definition */
+interface TaxBracket {
+    /** Minimum income for bracket */
+    min: number;
+    /** Maximum income for bracket */
+    max: number;
+    /** Tax rate (0-1) */
+    rate: number;
+}
+/** Salary band range */
+interface SalaryBandRange {
+    /** Minimum salary */
+    min: number;
+    /** Maximum salary */
+    max: number;
+}
+/** Role mapping configuration */
+interface RoleMappingConfig {
+    /** Department to role mapping */
+    byDepartment: Record<string, OrgRole>;
+    /** Employment type to role mapping */
+    byEmploymentType: Record<string, OrgRole>;
+    /** Default role */
+    default: OrgRole;
+}
+/** Main HRM configuration */
+interface HRMConfig {
+    /** Data retention settings */
+    dataRetention: DataRetentionConfig;
+    /** Payroll settings */
+    payroll: PayrollConfig;
+    /** Salary settings */
+    salary: SalaryConfig;
+    /** Employment settings */
+    employment: EmploymentConfig;
+    /** Validation settings */
+    validation: ValidationConfig;
+}
+/** Single-tenant configuration */
+interface SingleTenantConfig {
+    /** Fixed organization ID (optional - will use default if not provided) */
+    organizationId?: ObjectIdLike;
+    /** Auto-inject organizationId if missing (default: true) */
+    autoInject?: boolean;
+}
+/** Main Payroll initialization config with strong generics */
+interface PayrollInitConfig<TEmployee extends EmployeeDocument = EmployeeDocument, TPayrollRecord extends PayrollRecordDocument = PayrollRecordDocument, TTransaction extends AnyDocument = AnyDocument, TAttendance extends AnyDocument = AnyDocument, TLeaveRequest extends LeaveRequestDocument = LeaveRequestDocument, TTaxWithholding extends TaxWithholdingDocument = TaxWithholdingDocument> {
+    /** Employee model (required) - strongly typed */
+    EmployeeModel: Model<TEmployee>;
+    /** Payroll record model (required) - strongly typed */
+    PayrollRecordModel: Model<TPayrollRecord>;
+    /** Transaction model (required) - strongly typed */
+    TransactionModel: Model<TTransaction>;
+    /** Attendance model (optional, for integration) - strongly typed */
+    AttendanceModel?: Model<TAttendance> | null;
+    /** Leave request model (optional) - strongly typed */
+    LeaveRequestModel?: Model<TLeaveRequest> | null;
+    /** Tax withholding model (optional) - strongly typed */
+    TaxWithholdingModel?: Model<TTaxWithholding> | null;
+    /** Single-tenant configuration */
+    singleTenant?: SingleTenantConfig | null;
+    /** Custom logger */
+    logger?: Logger;
+    /** Custom HRM config overrides */
+    config?: DeepPartial<HRMConfig>;
+}
+/** User reference for audit */
+interface UserReference {
+    userId?: ObjectId;
+    name?: string;
+    role?: string;
+}
+/** Bank details */
+interface BankDetails {
+    accountName?: string;
+    accountNumber?: string;
+    bankName?: string;
+    branchName?: string;
+    routingNumber?: string;
+}
+/** Allowance entry */
+interface Allowance {
+    type: AllowanceType;
+    name?: string;
+    amount: number;
+    /** Whether amount is percentage of base salary */
+    isPercentage?: boolean;
+    /** Percentage value if isPercentage is true */
+    value?: number;
+    taxable?: boolean;
+    recurring?: boolean;
+    effectiveFrom?: Date;
+    effectiveTo?: Date | null;
+}
+/** Deduction entry */
+interface Deduction {
+    type: DeductionType;
+    name?: string;
+    amount: number;
+    /** Whether amount is percentage of base salary */
+    isPercentage?: boolean;
+    /** Percentage value if isPercentage is true */
+    value?: number;
+    auto?: boolean;
+    recurring?: boolean;
+    effectiveFrom?: Date;
+    effectiveTo?: Date | null;
+    description?: string;
+}
+/** Compensation structure */
+interface Compensation {
+    /** Base salary amount */
+    baseAmount: number;
+    /** Payment frequency */
+    frequency: PaymentFrequency;
+    /** Currency code */
+    currency: string;
+    /** Allowances array */
+    allowances: Allowance[];
+    /** Deductions array */
+    deductions: Deduction[];
+    /** Calculated gross salary */
+    grossSalary?: number;
+    /** Calculated net salary */
+    netSalary?: number;
+    /** When compensation became effective */
+    effectiveFrom?: Date;
+    /** Last modified timestamp */
+    lastModified?: Date;
+}
+/** Work schedule */
+interface WorkSchedule {
+    hoursPerWeek?: number;
+    hoursPerDay?: number;
+    /** Working days (0=Sunday, 6=Saturday) */
+    workingDays?: number[];
+    shiftStart?: string;
+    shiftEnd?: string;
+}
+/** Employment history entry */
+interface EmploymentHistoryEntry {
+    hireDate: Date;
+    terminationDate: Date;
+    reason?: TerminationReason;
+    finalSalary?: number;
+    position?: string;
+    department?: string;
+    notes?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+/** Payroll stats (pre-calculated) */
+interface PayrollStats {
+    totalPaid: number;
+    lastPaymentDate?: Date | null;
+    nextPaymentDate?: Date | null;
+    paymentsThisYear: number;
+    averageMonthly: number;
+    updatedAt?: Date;
+}
+/** Employee document structure */
+interface EmployeeDocument extends Document {
+    _id: ObjectId;
+    /**
+     * User reference (optional - guest employees don't have user accounts)
+     * In real Mongoose usage this can be either:
+     * - an ObjectId
+     * - a populated user document containing at least `_id`
+     * - undefined (guest employee)
+     */
+    userId?: ObjectId | {
+        _id: ObjectId;
+        name?: string;
+        email?: string;
+        phone?: string;
+    };
+    /** Email for guest employees (when userId is not present) */
+    email?: string;
+    organizationId: ObjectId;
+    employeeId: string;
+    employmentType: EmploymentType;
+    status: EmployeeStatus;
+    department?: Department;
+    position: string;
+    hireDate: Date;
+    terminationDate?: Date | null;
+    probationEndDate?: Date | null;
+    employmentHistory: EmploymentHistoryEntry[];
+    compensation: Compensation;
+    workSchedule?: WorkSchedule;
+    bankDetails?: BankDetails;
+    payrollStats: PayrollStats;
+    notes?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+    save(options?: {
+        session?: ClientSession;
+    }): Promise<this>;
+    toObject(): Record<string, unknown>;
+}
+/** Payroll period */
+interface PayrollPeriod {
+    month: number;
+    year: number;
+    startDate: Date;
+    endDate: Date;
+    payDate: Date;
+}
+/** Payroll breakdown */
+interface PayrollBreakdown {
+    baseAmount: number;
+    allowances: Array<{
+        type: string;
+        amount: number;
+        taxable?: boolean;
+    }>;
+    deductions: Array<{
+        type: string;
+        amount: number;
+        description?: string;
+    }>;
+    grossSalary: number;
+    netSalary: number;
+    /** Taxable amount (base + taxable allowances) */
+    taxableAmount?: number;
+    /** Calculated tax amount */
+    taxAmount?: number;
+    workingDays?: number;
+    actualDays?: number;
+    proRatedAmount?: number;
+    attendanceDeduction?: number;
+    overtimeAmount?: number;
+    bonusAmount?: number;
+}
+/** Payroll correction entry */
+interface PayrollCorrection {
+    previousAmount: number;
+    newAmount: number;
+    reason: string;
+    correctedBy: ObjectId;
+    correctedAt: Date;
+}
+/** Payroll record document */
+interface PayrollRecordDocument extends Document {
+    _id: ObjectId;
+    organizationId: ObjectId;
+    employeeId: ObjectId;
+    userId?: ObjectId;
+    period: PayrollPeriod;
+    breakdown: PayrollBreakdown;
+    transactionId?: ObjectId | null;
+    status: PayrollStatus;
+    paidAt?: Date | null;
+    processedAt?: Date | null;
+    paymentMethod?: PaymentMethod;
+    metadata?: Record<string, unknown>;
+    processedBy?: ObjectId;
+    notes?: string;
+    payslipUrl?: string;
+    exported: boolean;
+    exportedAt?: Date | null;
+    corrections?: PayrollCorrection[];
+    /**
+     * Payroll run type (regular, off-cycle, supplemental, retroactive)
+     * Default: 'regular'
+     */
+    payrollRunType?: PayrollRunType;
+    /**
+     * Retroactive adjustment details (for back-pay or corrections)
+     * Only populated when payrollRunType is 'retroactive'
+     */
+    retroactiveAdjustment?: RetroactiveAdjustment;
+    /**
+     * Employer contributions for this payroll
+     * Costs borne by employer (not deducted from employee pay)
+     */
+    employerContributions?: EmployerContribution[];
+    /** Whether this record has been voided or reversed */
+    isVoided?: boolean;
+    /** When the record was voided/reversed */
+    voidedAt?: Date | null;
+    /** User who voided/reversed the record */
+    voidedBy?: ObjectId | null;
+    /** Reason for voiding/reversing */
+    voidReason?: string | null;
+    /** When the record was reversed (for REVERSED status) */
+    reversedAt?: Date | null;
+    /** User who reversed the record */
+    reversedBy?: ObjectId | null;
+    /** Reason for reversing the record */
+    reversalReason?: string | null;
+    /** For reversed payrolls: ID of the reversal transaction */
+    reversalTransactionId?: ObjectId | null;
+    /** For reversal records: ID of the original payroll record being reversed */
+    originalPayrollId?: ObjectId | null;
+    createdAt?: Date;
+    updatedAt?: Date;
+    /**
+     * Optional per-document expiration date for MongoDB TTL index.
+     *
+     * When set, this document will be automatically deleted by MongoDB at this date,
+     * overriding the global TTL configuration. Use for jurisdiction-specific retention.
+     *
+     * @example 7-year retention for USA
+     * expireAt: new Date(Date.now() + 7 * 365 * 24 * 60 * 60 * 1000)
+     *
+     * @example Never expire
+     * expireAt: undefined
+     */
+    expireAt?: Date | null;
+    save(options?: {
+        session?: ClientSession;
+    }): Promise<this>;
+    toObject(): Record<string, unknown>;
+}
+/** Base operation context */
+interface OperationContext {
+    /** User performing the operation */
+    userId?: ObjectIdLike;
+    /** User name */
+    userName?: string;
+    /** User role */
+    userRole?: string;
+    /** Organization ID (auto-injected in single-tenant mode) */
+    organizationId?: ObjectIdLike;
+    /** MongoDB session for transactions */
+    session?: ClientSession;
+}
+/**
+ * Base parameters for all employee operations
+ * Enforces multi-tenant isolation and supports dual identity
+ */
+/**
+ * Employee ID resolution mode
+ *
+ * @example
+ * // Auto-detect (recommended)
+ * { employeeId: 'EMP-001' } // Treated as business ID
+ *
+ * @example
+ * // Force business ID (for 24-hex IDs that look like ObjectId)
+ * { employeeId: '000000000000000000000001', employeeIdMode: 'businessId' }
+ *
+ * @example
+ * // Force ObjectId lookup
+ * { employeeId: employee._id, employeeIdMode: 'objectId' }
+ */
+type EmployeeIdMode = 'auto' | 'objectId' | 'businessId';
+interface EmployeeOperationParams {
+    /**
+     * Employee identifier (supports both formats):
+     * - ObjectId: employee._id (MongoDB document ID)
+     * - String: "EMP-001" (business identifier)
+     */
+    employeeId: ObjectIdLike | string;
+    /**
+     * How to interpret employeeId (explicit control for edge cases)
+     *
+     * @default 'auto' - Smart detection
+     *
+     * Explicit mode hint for employeeId disambiguation
+     *
+     * - 'auto' (default): Auto-detect via isValidObjectId()
+     * - 'objectId': Force treat as MongoDB _id (ObjectId)
+     * - 'businessId': Force treat as business employeeId string
+     *
+     * Use 'businessId' if your employeeIds are 24-hex strings like
+     * "507f1f77bcf86cd799439011" to prevent ObjectId collision.
+     *
+     * @default 'auto'
+     * @since v2.3.0
+     *
+     * @example
+     * // Force treat as business ID (prevents ObjectId collision)
+     * await payroll.processSalary({
+     *   employeeId: "507f1f77bcf86cd799439011",
+     *   employeeIdMode: 'businessId',
+     *   organizationId: org._id,
+     *   month: 3, year: 2024
+     * });
+     */
+    employeeIdMode?: EmployeeIdMode;
+    /**
+     * Organization ID for multi-tenant isolation
+     *
+     * **Multi-tenant mode:** REQUIRED (enforced at runtime)
+     * **Single-tenant mode:** Optional (auto-injected if autoInject=true)
+     *
+     * **Resolution Priority:**
+     * 1. This explicit value (highest)
+     * 2. context.organizationId (from middleware/auth)
+     * 3. Single-tenant config (if autoInject enabled)
+     * 4. Error thrown (if none found in multi-tenant mode)
+     *
+     * @example
+     * // Multi-tenant: explicit organizationId
+     * await payroll.processSalary({
+     *   employeeId: emp._id,
+     *   organizationId: org._id,  // Required
+     *   month: 3, year: 2024
+     * });
+     *
+     * @example
+     * // Multi-tenant: via context
+     * await payroll.processSalary({
+     *   employeeId: emp._id,
+     *   month: 3, year: 2024,
+     *   context: { organizationId: org._id }  // From middleware
+     * });
+     *
+     * @example
+     * // Single-tenant: auto-injected
+     * const payroll = createPayrollInstance()
+     *   .forSingleTenant({ organizationId: myOrg._id, autoInject: true })
+     *   .build();
+     *
+     * await payroll.processSalary({
+     *   employeeId: emp._id,
+     *   // organizationId auto-injected ✨
+     *   month: 3, year: 2024
+     * });
+     */
+    organizationId?: ObjectIdLike;
+    /**
+     * Operation context (auth, session, metadata)
+     */
+    context?: OperationContext;
+}
+/** Hire employee parameters */
+interface HireEmployeeParams {
+    /** User ID (optional - for guest employees without user account) */
+    userId?: ObjectIdLike;
+    /** Organization ID (optional in single-tenant mode - auto-injected) */
+    organizationId?: ObjectIdLike;
+    /** Employment details */
+    employment: {
+        employeeId?: string;
+        /** Email for guest employees (when userId is not provided) */
+        email?: string;
+        type?: EmploymentType;
+        department?: Department | string;
+        position: string;
+        hireDate?: Date;
+        probationMonths?: number;
+        workSchedule?: WorkSchedule;
+    };
+    /** Compensation details */
+    compensation: {
+        baseAmount: number;
+        frequency?: PaymentFrequency;
+        currency?: string;
+        allowances?: Array<Partial<Allowance>>;
+        deductions?: Array<Partial<Deduction>>;
+    };
+    /** Bank details */
+    bankDetails?: BankDetails;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Update employment parameters */
+interface UpdateEmploymentParams extends EmployeeOperationParams {
+    /** Fields to update */
+    updates: {
+        department?: Department;
+        position?: string;
+        employmentType?: EmploymentType;
+        status?: EmployeeStatus;
+        workSchedule?: WorkSchedule;
+    };
+}
+/** Terminate employee parameters */
+interface TerminateEmployeeParams extends EmployeeOperationParams {
+    /** Termination date */
+    terminationDate?: Date;
+    /** Termination reason */
+    reason?: TerminationReason;
+    /** Notes */
+    notes?: string;
+}
+/** Re-hire employee parameters */
+interface ReHireEmployeeParams extends EmployeeOperationParams {
+    /** New hire date */
+    hireDate?: Date;
+    /** New position */
+    position?: string;
+    /** New department */
+    department?: Department;
+    /** New compensation */
+    compensation?: DeepPartial<Compensation>;
+}
+/** Update salary parameters */
+interface UpdateSalaryParams extends EmployeeOperationParams {
+    /** Compensation updates */
+    compensation: {
+        baseAmount?: number;
+        frequency?: PaymentFrequency;
+        currency?: string;
+    };
+    /** Effective from date */
+    effectiveFrom?: Date;
+}
+/** Add allowance parameters */
+interface AddAllowanceParams extends EmployeeOperationParams {
+    /** Allowance type */
+    type: AllowanceType;
+    /** Amount (fixed or ignored if isPercentage is true) */
+    amount: number;
+    /** Whether amount is percentage of base salary */
+    isPercentage?: boolean;
+    /** Percentage value if isPercentage is true */
+    value?: number;
+    /** Is taxable */
+    taxable?: boolean;
+    /** Is recurring */
+    recurring?: boolean;
+    /** Effective from */
+    effectiveFrom?: Date;
+    /** Effective to */
+    effectiveTo?: Date | null;
+}
+/** Remove allowance parameters */
+interface RemoveAllowanceParams extends EmployeeOperationParams {
+    /** Allowance type to remove */
+    type: AllowanceType;
+}
+/** Add deduction parameters */
+interface AddDeductionParams extends EmployeeOperationParams {
+    /** Deduction type */
+    type: DeductionType;
+    /** Amount (fixed or ignored if isPercentage is true) */
+    amount: number;
+    /** Whether amount is percentage of base salary */
+    isPercentage?: boolean;
+    /** Percentage value if isPercentage is true */
+    value?: number;
+    /** Auto-deduct from salary */
+    auto?: boolean;
+    /** Is recurring */
+    recurring?: boolean;
+    /** Description */
+    description?: string;
+    /** Effective from */
+    effectiveFrom?: Date;
+    /** Effective to */
+    effectiveTo?: Date | null;
+}
+/** Remove deduction parameters */
+interface RemoveDeductionParams extends EmployeeOperationParams {
+    /** Deduction type to remove */
+    type: DeductionType;
+}
+/** Update bank details parameters */
+interface UpdateBankDetailsParams extends EmployeeOperationParams {
+    /** Bank details */
+    bankDetails: BankDetails;
+}
+/** Get employee parameters */
+interface GetEmployeeParams extends EmployeeOperationParams {
+    /** Whether to populate user reference */
+    populateUser?: boolean;
+    /** MongoDB session for transactions */
+    session?: mongoose.ClientSession;
+}
+/**
+ * Payroll run types
+ *
+ * - `regular`: Normal monthly/bi-weekly payroll cycle
+ * - `off-cycle`: Unscheduled payroll run (bonuses, corrections, missed payments)
+ * - `supplemental`: Additional payment outside regular cycle (commissions, one-time bonuses)
+ * - `retroactive`: Adjustment for previous period (back-pay, corrections)
+ */
+type PayrollRunType = 'regular' | 'off-cycle' | 'supplemental' | 'retroactive';
+/**
+ * Retroactive adjustment details
+ *
+ * Used when correcting payroll from a previous period
+ */
+interface RetroactiveAdjustment {
+    /** Original period being adjusted */
+    originalPeriod: {
+        month: number;
+        year: number;
+    };
+    /** Original payroll record ID being corrected */
+    originalPayrollId?: ObjectId;
+    /** Reason for retroactive adjustment */
+    reason: string;
+    /** Adjustment amount (positive for back-pay, negative for recovery) */
+    adjustmentAmount: number;
+    /** Whether this was approved by management */
+    approved?: boolean;
+    /** Approver user ID */
+    approvedBy?: ObjectId;
+    /** Approval date */
+    approvedAt?: Date;
+}
+/**
+ * Employer contributions (beyond employee tax withholding)
+ *
+ * These are costs borne by the employer, not deducted from employee pay.
+ * Examples: Social security (employer portion), pension matching, unemployment insurance
+ */
+interface EmployerContribution {
+    /** Type of contribution */
+    type: 'social_security' | 'pension' | 'unemployment' | 'health_insurance' | 'other';
+    /** Contribution amount */
+    amount: number;
+    /** Description */
+    description?: string;
+    /** Whether this is mandatory by law */
+    mandatory?: boolean;
+    /** Reference number for filing */
+    referenceNumber?: string;
+}
+/** Process salary parameters */
+interface ProcessSalaryParams extends EmployeeOperationParams {
+    /** Month (1-12) */
+    month: number;
+    /** Year */
+    year: number;
+    /** Payment date */
+    paymentDate?: Date;
+    /** Payment method */
+    paymentMethod?: PaymentMethod;
+    /**
+     * Payroll run type (default: 'regular')
+     *
+     * Use for off-cycle payments, supplemental runs, or retroactive adjustments
+     */
+    payrollRunType?: PayrollRunType;
+    /**
+     * Retroactive adjustment details
+     *
+     * Required when payrollRunType is 'retroactive'
+     */
+    retroactiveAdjustment?: RetroactiveAdjustment;
+    /**
+     * Employer contributions for this payroll
+     *
+     * These are costs borne by the employer (not deducted from employee pay)
+     */
+    employerContributions?: EmployerContribution[];
+    /**
+     * Idempotency key (Stripe-style)
+     * If provided, duplicate calls with same key return cached result
+     * Auto-generated if not provided: `payroll:{orgId}:{empId}:{year}-{month}`
+     */
+    idempotencyKey?: string;
+    /**
+     * Optional attendance override (useful when embedding into any HRM system).
+     * If provided, payroll will use this instead of querying AttendanceModel.
+     */
+    attendance?: AttendanceInput | null;
+    /**
+     * Optional processing options (holidays/work schedule/skip flags).
+     * This aligns with the pure functions in `@classytic/payroll/core`.
+     */
+    options?: PayrollProcessingOptions;
+}
+/** Bulk payroll progress information */
+interface BulkPayrollProgress {
+    /** Number of employees processed so far */
+    processed: number;
+    /** Total number of employees to process */
+    total: number;
+    /** Number of successful processings */
+    successful: number;
+    /** Number of failed processings */
+    failed: number;
+    /** Currently processing employee ID (optional) */
+    currentEmployee?: string;
+    /** Completion percentage (0-100) */
+    percentage?: number;
+}
+/** Process bulk payroll parameters */
+interface ProcessBulkPayrollParams {
+    /** Organization ID */
+    organizationId: ObjectIdLike;
+    /** Month (1-12) */
+    month: number;
+    /** Year */
+    year: number;
+    /** Specific employee IDs (empty = all active) */
+    employeeIds?: ObjectIdLike[];
+    /** Payment date */
+    paymentDate?: Date;
+    /** Payment method */
+    paymentMethod?: PaymentMethod;
+    /**
+     * Optional processing options (holidays/work schedule/skip flags).
+     * Passed through to each employee's salary processing.
+     */
+    options?: PayrollProcessingOptions;
+    /** Operation context */
+    context?: OperationContext;
+    /**
+     * Progress callback - called after each employee is processed
+     * Useful for updating job queue progress, UI updates, etc.
+     * @example
+     * onProgress: async (progress) => {
+     *   await Job.findByIdAndUpdate(jobId, { progress });
+     * }
+     */
+    onProgress?: (progress: BulkPayrollProgress) => void | Promise<void>;
+    /**
+     * Cancellation signal - check signal.aborted to allow graceful cancellation
+     * @example
+     * const controller = new AbortController();
+     * processBulkPayroll({ ..., signal: controller.signal });
+     * // Later: controller.abort();
+     */
+    signal?: AbortSignal;
+    /**
+     * Batch size - number of employees to process before pausing (default: 10)
+     * Helps prevent resource exhaustion and allows event loop to process other tasks
+     */
+    batchSize?: number;
+    /**
+     * Batch delay in milliseconds - pause between batches (default: 0)
+     * Useful for rate limiting or preventing database connection pool exhaustion
+     */
+    batchDelay?: number;
+    /**
+     * Concurrency - number of employees to process in parallel (default: 1)
+     * - 1: Sequential processing (safest, default)
+     * - 2-5: Moderate parallelism (faster, uses more resources)
+     * - 10+: High parallelism (fastest, requires robust infrastructure)
+     */
+    concurrency?: number;
+    /**
+     * Use cursor-based streaming for processing (default: auto)
+     * - false: Load all into memory (fast for <10k employees)
+     * - true: Stream via cursor (scales to millions, constant memory)
+     * - undefined/auto: Automatically use streaming for >10k employees
+     */
+    useStreaming?: boolean;
+}
+/** Payroll history parameters */
+interface PayrollHistoryParams {
+    /** Employee identifier (ObjectId _id or string business ID like "EMP-001") */
+    employeeId?: ObjectIdLike | string;
+    /** Explicit mode hint for employeeId disambiguation @since v2.3.0 */
+    employeeIdMode?: EmployeeIdMode;
+    /** Organization ID */
+    organizationId?: ObjectIdLike;
+    /** Month filter */
+    month?: number;
+    /** Year filter */
+    year?: number;
+    /** Status filter */
+    status?: PayrollStatus;
+    /** Pagination */
+    pagination?: {
+        page?: number;
+        limit?: number;
+        sort?: Record<string, 1 | -1>;
+    };
+}
+/** Payroll summary parameters */
+interface PayrollSummaryParams {
+    /** Organization ID */
+    organizationId: ObjectIdLike;
+    /** Month */
+    month?: number;
+    /** Year */
+    year?: number;
+}
+/** Export payroll parameters */
+interface ExportPayrollParams {
+    /** Organization ID */
+    organizationId: ObjectIdLike;
+    /** Start date */
+    startDate: Date;
+    /** End date */
+    endDate: Date;
+    /** Export format */
+    format?: 'json' | 'csv';
+}
+/**
+ * Void payroll parameters
+ *
+ * Use this for payrolls that haven't been paid yet (pending, processing, failed).
+ * Voiding marks the record as invalid without creating 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 },
+ * });
+ * ```
+ */
+interface VoidPayrollParams {
+    /** Organization ID for multi-tenant isolation */
+    organizationId: ObjectIdLike;
+    /** Payroll record ID to void */
+    payrollRecordId: ObjectIdLike;
+    /** Reason for voiding (required for audit trail) */
+    reason: string;
+    /** Operation context */
+    context?: OperationContext;
+    /** Also void/cancel the associated transaction */
+    voidTransaction?: boolean;
+}
+/**
+ * Reverse payroll parameters
+ *
+ * Use this for payrolls that have already been paid.
+ * Creates a reversal (negative) transaction to offset the original payment.
+ *
+ * @example
+ * ```typescript
+ * const result = await payroll.reversePayroll({
+ *   organizationId: org._id,
+ *   payrollRecordId: record._id,
+ *   reason: 'Duplicate payment - reversing',
+ *   createReversalTransaction: true,
+ *   context: { userId: admin._id },
+ * });
+ * console.log(result.reversalTransaction); // Negative amount transaction
+ * ```
+ */
+interface ReversePayrollParams {
+    /** Organization ID for multi-tenant isolation */
+    organizationId: ObjectIdLike;
+    /** Payroll record ID to reverse */
+    payrollRecordId: ObjectIdLike;
+    /** Reason for reversal (required for audit trail) */
+    reason: string;
+    /** Create a reversal (negative) transaction (default: true) */
+    createReversalTransaction?: boolean;
+    /** Payment method for reversal transaction (default: 'manual') */
+    paymentMethod?: string;
+    /** Operation context */
+    context?: OperationContext;
+}
+/**
+ * Restore payroll parameters
+ *
+ * Restores a voided (not reversed) payroll record.
+ * Cannot restore reversed payrolls as they have financial transactions.
+ */
+interface RestorePayrollParams {
+    /** Organization ID for multi-tenant isolation */
+    organizationId: ObjectIdLike;
+    /** Payroll record ID to restore */
+    payrollRecordId: ObjectIdLike;
+    /** Reason for restoration */
+    reason?: string;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Result of voiding a payroll */
+interface VoidPayrollResult {
+    /** The voided payroll record */
+    payrollRecord: PayrollRecordDocument;
+    /** Whether the transaction was also voided */
+    transactionVoided: boolean;
+    /** Number of tax withholdings voided */
+    taxWithholdingsVoided: number;
+}
+/** Result of reversing a payroll */
+interface ReversePayrollResult {
+    /** The reversed payroll record */
+    payrollRecord: PayrollRecordDocument;
+    /** The reversal transaction (if createReversalTransaction was true) */
+    reversalTransaction?: AnyDocument;
+    /** Number of tax withholdings cancelled */
+    taxWithholdingsCancelled: number;
+}
+/** Result of restoring a payroll */
+interface RestorePayrollResult {
+    /** The restored payroll record */
+    payrollRecord: PayrollRecordDocument;
+}
+/** Process salary result (generic for best DX) */
+interface ProcessSalaryResult<TEmployee extends EmployeeDocument = EmployeeDocument, TPayrollRecord extends PayrollRecordDocument = PayrollRecordDocument, TTransaction extends AnyDocument = AnyDocument> {
+    payrollRecord: TPayrollRecord;
+    transaction: TTransaction;
+    employee: TEmployee;
+}
+/** Bulk payroll result */
+interface BulkPayrollResult {
+    successful: Array<{
+        employeeId: string;
+        amount: number;
+        transactionId: ObjectId;
+    }>;
+    failed: Array<{
+        employeeId: string;
+        error: string;
+    }>;
+    total: number;
+}
+/** Payroll summary result */
+interface PayrollSummaryResult {
+    totalGross: number;
+    totalNet: number;
+    totalDeductions: number;
+    employeeCount: number;
+    paidCount: number;
+    pendingCount: number;
+}
+/** Tax calculation result */
+interface TaxCalculationResult {
+    gross: number;
+    tax: number;
+    net: number;
+}
+/** Compensation breakdown result */
+interface CompensationBreakdownResult {
+    baseAmount: number;
+    allowances: Array<Allowance & {
+        calculatedAmount: number;
+    }>;
+    deductions: Array<Deduction & {
+        calculatedAmount: number;
+    }>;
+    grossAmount: number;
+    netAmount: number;
+}
+/**
+ * Payroll instance interface (public surface) used for plugin typing.
+ * This matches the actual `Payroll` class and keeps generics flowing.
+ */
+interface PayrollInstance<TEmployee extends EmployeeDocument = EmployeeDocument, TPayrollRecord extends PayrollRecordDocument = PayrollRecordDocument, TTransaction extends AnyDocument = AnyDocument, TAttendance extends AnyDocument = AnyDocument> {
+    /** Check if initialized */
+    isInitialized(): boolean;
+    /** Register a plugin */
+    use(plugin: PayrollPluginDefinition): Promise<this>;
+    /** Subscribe to typed payroll events */
+    on<K extends PayrollEventType>(event: K, handler: (payload: PayrollEventMap[K]) => void | Promise<void>): () => void;
+    /** Register webhook (Stripe-style) */
+    registerWebhook(config: WebhookConfig): void;
+    /** Unregister webhook */
+    unregisterWebhook(url: string): void;
+    /** Get webhook delivery log */
+    getWebhookDeliveries(options?: {
+        event?: PayrollEventType;
+        status?: 'pending' | 'sent' | 'failed';
+        limit?: number;
+    }): WebhookDelivery[];
+    hire(params: HireEmployeeParams): Promise<TEmployee>;
+    getEmployee(params: GetEmployeeParams): Promise<TEmployee>;
+    updateEmployment(params: UpdateEmploymentParams): Promise<TEmployee>;
+    terminate(params: TerminateEmployeeParams): Promise<TEmployee>;
+    reHire(params: ReHireEmployeeParams): Promise<TEmployee>;
+    updateSalary(params: UpdateSalaryParams): Promise<TEmployee>;
+    addAllowance(params: AddAllowanceParams): Promise<TEmployee>;
+    removeAllowance(params: RemoveAllowanceParams): Promise<TEmployee>;
+    addDeduction(params: AddDeductionParams): Promise<TEmployee>;
+    removeDeduction(params: RemoveDeductionParams): Promise<TEmployee>;
+    updateBankDetails(params: UpdateBankDetailsParams): Promise<TEmployee>;
+    processSalary(params: ProcessSalaryParams): Promise<ProcessSalaryResult<TEmployee, TPayrollRecord, TTransaction>>;
+    processBulkPayroll(params: ProcessBulkPayrollParams): Promise<BulkPayrollResult>;
+    payrollHistory(params: PayrollHistoryParams): Promise<TPayrollRecord[]>;
+    payrollSummary(params: PayrollSummaryParams): Promise<PayrollSummaryResult>;
+    exportPayroll(params: ExportPayrollParams): Promise<TPayrollRecord[]>;
+    /**
+     * Void a payroll record (before payment)
+     *
+     * Use for: pending, processing, or failed payrolls
+     * Creates audit trail but no reversal transaction
+     */
+    voidPayroll(params: VoidPayrollParams): Promise<VoidPayrollResult>;
+    /**
+     * Reverse a paid payroll
+     *
+     * Creates a reversal (negative) transaction to offset the original
+     * Required for compliance: maintains full audit trail
+     */
+    reversePayroll(params: ReversePayrollParams): Promise<ReversePayrollResult>;
+    /**
+     * Restore a voided payroll
+     *
+     * Only works for voided payrolls (not reversed)
+     */
+    restorePayroll(params: RestorePayrollParams): Promise<RestorePayrollResult>;
+    /** Extended properties from plugins */
+    [key: string]: unknown;
+}
+/**
+ * @deprecated Use `PayrollPluginDefinition` from `@classytic/payroll/core`.
+ * This legacy plugin shape is kept for compatibility with older code.
+ */
+interface PayrollPlugin {
+    name: string;
+    apply(payroll: PayrollInstance): void;
+}
+/** Plugin function signature */
+type PluginFunction = (payroll: PayrollInstance) => void;
+/** Plugin type (object or function) */
+type PluginType = PayrollPlugin | PluginFunction;
+/** Event names */
+type PayrollEvent = 'employee:hired' | 'employee:terminated' | 'employee:rehired' | 'salary:updated' | 'salary:processed' | 'salary:failed' | 'payroll:completed' | 'payroll:exported' | 'compensation:changed' | 'milestone:achieved';
+/** Event payload base */
+interface EventPayloadBase {
+    type: PayrollEvent;
+    timestamp: Date;
+}
+/** Employee hired event */
+interface EmployeeHiredEvent extends EventPayloadBase {
+    type: 'employee:hired';
+    data: {
+        employee: {
+            id: ObjectId;
+            employeeId: string;
+            position: string;
+            department?: string;
+        };
+        organizationId: ObjectId;
+        context?: OperationContext;
+    };
+}
+/** Salary processed event */
+interface SalaryProcessedEvent extends EventPayloadBase {
+    type: 'salary:processed';
+    data: {
+        employee: {
+            id: ObjectId;
+            employeeId: string;
+            name?: string;
+        };
+        payroll: {
+            id: ObjectId;
+            period: {
+                month: number;
+                year: number;
+            };
+            amount: number;
+        };
+        transactionId: ObjectId;
+        context?: OperationContext;
+    };
+}
+/** All event payloads union */
+type EventPayload = EmployeeHiredEvent | SalaryProcessedEvent;
+/** Logger interface */
+interface Logger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+/** Error codes */
+type ErrorCode = 'PAYROLL_ERROR' | 'NOT_INITIALIZED' | 'EMPLOYEE_NOT_FOUND' | 'INVALID_EMPLOYEE' | 'DUPLICATE_PAYROLL' | 'VALIDATION_ERROR' | 'EMPLOYEE_TERMINATED' | 'ALREADY_PROCESSED' | 'NOT_ELIGIBLE' | 'SECURITY_ERROR';
+/** HTTP error with status code */
+interface HttpError extends Error {
+    code: ErrorCode;
+    status: number;
+    context?: Record<string, unknown>;
+    timestamp: Date;
+}
+/** Pay period info */
+interface PayPeriodInfo {
+    month: number;
+    year: number;
+    startDate: Date;
+    endDate: Date;
+}
+/** Employee validation result */
+interface EmployeeValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/** Query builder options */
+interface QueryOptions {
+    session?: ClientSession;
+    lean?: boolean;
+}
+/**
+ * Base employee interface that Payroll expects
+ * Extend this in your application
+ */
+interface PayrollEmployee {
+    _id: ObjectId;
+    userId: ObjectId;
+    organizationId: ObjectId;
+    employeeId: string;
+    status: EmployeeStatus;
+    compensation: Compensation;
+    payrollStats?: PayrollStats;
+    bankDetails?: BankDetails;
+}
+/**
+ * Employee model with Payroll fields applied
+ * Use this to type your employee model
+ */
+type WithPayroll<TEmployee> = TEmployee & {
+    compensation: Compensation;
+    payrollStats: PayrollStats;
+    employmentHistory: EmploymentHistoryEntry[];
+};
+/** Leave balance entry (embedded in Employee) */
+interface LeaveBalance {
+    /** Leave type */
+    type: LeaveType;
+    /** Allocated days for the year */
+    allocated: number;
+    /** Used days */
+    used: number;
+    /** Pending days (requested but not yet approved) */
+    pending: number;
+    /** Days carried over from previous year */
+    carriedOver: number;
+    /** When carried-over days expire */
+    expiresAt?: Date | null;
+    /** Year this balance applies to */
+    year: number;
+}
+/** Leave request document */
+interface LeaveRequestDocument extends Document {
+    _id: ObjectId;
+    organizationId?: ObjectId;
+    employeeId: ObjectId;
+    userId?: ObjectId;
+    type: LeaveType;
+    startDate: Date;
+    endDate: Date;
+    days: number;
+    halfDay?: boolean;
+    reason?: string;
+    status: LeaveRequestStatus;
+    reviewedBy?: ObjectId | null;
+    reviewedAt?: Date | null;
+    reviewNotes?: string;
+    attachments?: string[];
+    metadata?: Record<string, unknown>;
+    createdAt?: Date;
+    updatedAt?: Date;
+    save(options?: {
+        session?: ClientSession;
+    }): Promise<this>;
+    toObject(): Record<string, unknown>;
+}
+/** Request leave input */
+interface RequestLeaveInput {
+    type: LeaveType;
+    startDate: Date;
+    endDate: Date;
+    halfDay?: boolean;
+    reason?: string;
+    attachments?: string[];
+}
+/** Review leave request input */
+interface ReviewLeaveRequestInput {
+    requestId: ObjectIdLike;
+    action: 'approve' | 'reject';
+    notes?: string;
+}
+/** Leave history filters */
+interface LeaveHistoryFilters {
+    type?: LeaveType;
+    status?: LeaveRequestStatus;
+    startDate?: Date;
+    endDate?: Date;
+    year?: number;
+}
+/** Accrue leave options */
+interface AccrueLeaveOptions {
+    type?: LeaveType;
+    amount?: number;
+    proRate?: boolean;
+    asOfDate?: Date;
+}
+/** Reset annual leave options */
+interface ResetAnnualLeaveOptions {
+    year?: number;
+    carryOverLimit?: number;
+    leaveTypes?: LeaveType[];
+}
+/** Leave summary result */
+interface LeaveSummaryResult {
+    year: number;
+    balances: LeaveBalance[];
+    totalAllocated: number;
+    totalUsed: number;
+    totalPending: number;
+    totalAvailable: number;
+    byType: Record<LeaveType, {
+        allocated: number;
+        used: number;
+        pending: number;
+        available: number;
+    }>;
+}
+/** Leave initialization config */
+interface LeaveInitConfig {
+    /** Default leave allocations by type */
+    defaultAllocations?: Partial<Record<LeaveType, number>>;
+    /** Whether to pro-rate for mid-year hires */
+    proRateNewHires?: boolean;
+    /** Fiscal year start month (1-12, default: 1 for January) */
+    fiscalYearStartMonth?: number;
+    /** Maximum carry-over days by type */
+    maxCarryOver?: Partial<Record<LeaveType, number>>;
+}
+/** Working days calculation options */
+interface WorkingDaysOptions {
+    /** Working days of week (0=Sunday, 6=Saturday). Default: [1,2,3,4,5] */
+    workingDays?: number[];
+    /** Holiday dates to exclude */
+    holidays?: Date[];
+    /** Include end date in calculation (default: true) */
+    includeEndDate?: boolean;
+}
+/** Tax types supported by the system */
+type TaxType = 'income_tax' | 'social_security' | 'health_insurance' | 'pension' | 'employment_insurance' | 'local_tax' | 'other';
+/** Tax withholding status */
+type TaxStatus = 'pending' | 'submitted' | 'paid' | 'cancelled';
+/** Tax withholding document */
+interface TaxWithholdingDocument extends Document {
+    _id: ObjectId;
+    organizationId: ObjectId;
+    employeeId: ObjectId;
+    userId?: ObjectId;
+    payrollRecordId: ObjectId;
+    transactionId: ObjectId;
+    period: PayrollPeriod;
+    amount: number;
+    currency: string;
+    taxType: TaxType;
+    taxRate: number;
+    taxableAmount: number;
+    status: TaxStatus;
+    submittedAt?: Date;
+    paidAt?: Date;
+    governmentTransactionId?: ObjectId;
+    referenceNumber?: string;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+    voidedAt?: Date;
+    voidedBy?: ObjectId;
+    voidReason?: string;
+    voidMetadata?: Record<string, unknown>;
+    createdAt?: Date;
+    updatedAt?: Date;
+    markAsSubmitted(submittedAt?: Date): void;
+    markAsPaid(transactionId?: ObjectId, referenceNumber?: string, paidAt?: Date): void;
+    save(options?: {
+        session?: ClientSession;
+    }): Promise<this>;
+    toObject(): Record<string, unknown>;
+}
+
+/** Parameters for querying pending tax withholdings */
+interface GetPendingTaxParams {
+    organizationId: ObjectIdLike;
+    fromPeriod?: {
+        month: number;
+        year: number;
+    };
+    toPeriod?: {
+        month: number;
+        year: number;
+    };
+    taxType?: TaxType;
+    employeeId?: ObjectIdLike;
+}
+/** Parameters for tax summary aggregation */
+interface TaxSummaryParams {
+    organizationId: ObjectIdLike;
+    fromPeriod: {
+        month: number;
+        year: number;
+    };
+    toPeriod: {
+        month: number;
+        year: number;
+    };
+    groupBy?: 'type' | 'period' | 'employee';
+}
+/** Tax summary grouped by type */
+interface TaxSummaryByType {
+    taxType: TaxType;
+    totalAmount: number;
+    count: number;
+    withholdingIds: ObjectId[];
+}
+/** Tax summary result */
+interface TaxSummaryResult {
+    totalAmount: number;
+    count: number;
+    byType: TaxSummaryByType[];
+    period: {
+        fromMonth: number;
+        fromYear: number;
+        toMonth: number;
+        toYear: number;
+    };
+}
+/** Parameters for marking tax withholdings as paid */
+interface MarkTaxPaidParams {
+    organizationId: ObjectIdLike;
+    withholdingIds: ObjectIdLike[];
+    createTransaction?: boolean;
+    referenceNumber?: string;
+    paidAt?: Date;
+    notes?: string;
+    context?: OperationContext;
+}
+
+export { type ExportPayrollParams as $, type Allowance as A, type BankDetails as B, type Compensation as C, type Deduction as D, type EmployeeDocument as E, type EmployeeIdentityMode as F, type UpdateSalaryParams as G, type HireEmployeeParams as H, type AddAllowanceParams as I, type RemoveAllowanceParams as J, type AddDeductionParams as K, type LeaveType as L, type RemoveDeductionParams as M, type UpdateBankDetailsParams as N, type ObjectIdLike as O, type PayPeriodInfo as P, type ProcessSalaryParams as Q, type ReHireEmployeeParams as R, type ProcessSalaryResult as S, type TaxWithholdingDocument as T, type UpdateEmploymentParams as U, type ProcessBulkPayrollParams as V, type WorkingDaysOptions as W, type BulkPayrollResult as X, type PayrollHistoryParams as Y, type PayrollSummaryParams as Z, type PayrollSummaryResult as _, type LeaveBalance as a, WebhookManager as a$, type VoidPayrollParams as a0, type VoidPayrollResult as a1, type ReversePayrollParams as a2, type ReversePayrollResult as a3, type RestorePayrollParams as a4, type RestorePayrollResult as a5, type GetPendingTaxParams as a6, type TaxSummaryParams as a7, type TaxSummaryResult as a8, type MarkTaxPaidParams as a9, type GetEmployeeParams as aA, type HRMTransactionCategory as aB, type LeaveHistoryFilters as aC, type Nullable as aD, type PaymentMethod as aE, type PayrollConfig as aF, type PayrollCorrection as aG, type PayrollEmployee as aH, type PayrollEvent as aI, type PayrollPeriod as aJ, type PayrollPlugin as aK, type PayrollStats as aL, type PluginFunction as aM, type PluginType as aN, type QueryOptions as aO, type RequestLeaveInput as aP, type ResetAnnualLeaveOptions as aQ, type ReviewLeaveRequestInput as aR, type RoleMappingConfig as aS, type SalaryBand as aT, type SalaryBandRange as aU, type SalaryConfig as aV, type SalaryProcessedEvent as aW, type TaxBracket as aX, type TaxSummaryByType as aY, type UserReference as aZ, type ValidationConfig as a_, type DeepPartial as aa, type HRMConfig as ab, type SingleTenantConfig as ac, type PayrollBreakdown as ad, type ObjectId as ae, type OrgRole as af, type WorkSchedule as ag, type PaymentFrequency as ah, type TerminationReason as ai, type HttpError as aj, type ErrorCode as ak, type AttendanceInput as al, type AccrueLeaveOptions as am, type AllowanceType as an, type AnyModel as ao, type BulkPayrollProgress as ap, type DataRetentionConfig as aq, type DeductionType as ar, type EmployeeHiredEvent as as, type EmployeeIdMode as at, type EmployeeOperationParams as au, type EmploymentConfig as av, type EmploymentHistoryEntry as aw, type EventPayload as ax, type EventPayloadBase as ay, type FilterQuery as az, type LeaveSummaryResult as b, type WithPayroll as b0, type LeaveInitConfig as c, type OperationContext as d, type TaxType as e, type TaxStatus as f, type LeaveRequestDocument as g, type LeaveRequestStatus as h, type Logger as i, type CompensationBreakdownResult as j, type TaxCalculationResult as k, type EmployeeStatus as l, type EmployeeValidationResult as m, type EmploymentType as n, type Department as o, type PayrollStatus as p, type PayrollRecordDocument as q, type AnyDocument as r, type PayrollInstance as s, type PayrollInitConfig as t, type PayrollPluginDefinition as u, type PayrollEventMap as v, type WebhookConfig as w, type PayrollEventType as x, type WebhookDelivery as y, type TerminateEmployeeParams as z };