@classytic/payroll 2.0.0 → 2.3.0

package/dist/types-BN3K_Uhr.d.ts

@@ -0,0 +1,1842 @@
+import { Document, Types, ClientSession, 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 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;
+}
+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[];
+}
+/**
+ * Get or create the default event bus
+ */
+declare function getEventBus(): EventBus;
+/**
+ * Create a new event bus instance
+ */
+declare function createEventBus(): EventBus;
+/**
+ * Reset the default event bus (for testing)
+ */
+declare function resetEventBus(): void;
+/**
+ * Subscribe to employee hired events
+ */
+declare function onEmployeeHired(handler: PayrollEventHandler<'employee:hired'>): () => void;
+/**
+ * Subscribe to salary processed events
+ */
+declare function onSalaryProcessed(handler: PayrollEventHandler<'salary:processed'>): () => void;
+/**
+ * Subscribe to payroll completed events
+ */
+declare function onPayrollCompleted(handler: PayrollEventHandler<'payroll:completed'>): () => void;
+/**
+ * Subscribe to milestone achieved events
+ */
+declare function onMilestoneAchieved(handler: PayrollEventHandler<'milestone:achieved'>): () => void;
+
+/**
+ * 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 signature for webhook
+     */
+    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;
+}
+/** Working days calculation result */
+interface WorkingDaysResult {
+    /** Total calendar days in period */
+    totalDays: number;
+    /** Working days (excluding weekends and holidays) */
+    workingDays: number;
+    /** Weekend days */
+    weekends: number;
+    /** Holiday count */
+    holidays: number;
+}
+/** Proration calculation result */
+interface ProrationResult {
+    /** Proration ratio (0-1) */
+    ratio: number;
+    /** Reason for proration */
+    reason: 'full' | 'new_hire' | 'termination' | 'both';
+    /** Whether salary should be prorated */
+    isProrated: boolean;
+}
+/** Tax calculation result */
+interface TaxResult {
+    /** Tax amount */
+    amount: number;
+    /** Effective tax rate */
+    effectiveRate: number;
+}
+/** Attendance data (from YOUR attendance system) */
+interface AttendanceInput {
+    /** Expected work days in period */
+    expectedDays: number;
+    /** Actual days worked */
+    actualDays: number;
+}
+/** Complete salary calculation result */
+interface SalaryCalculationResult {
+    /** Original base salary */
+    baseSalary: number;
+    /** Prorated base salary */
+    proratedBase: number;
+    /** Total allowances */
+    totalAllowances: number;
+    /** Total deductions (excluding tax) */
+    totalDeductions: number;
+    /** Attendance deduction */
+    attendanceDeduction: number;
+    /** Gross salary (prorated base + allowances) */
+    grossSalary: number;
+    /** Tax amount */
+    taxAmount: number;
+    /** Net salary (gross - all deductions - tax) */
+    netSalary: number;
+    /** Proration details */
+    proration: ProrationResult;
+    /** Working days details */
+    workingDays: WorkingDaysResult;
+    /** Itemized breakdown */
+    breakdown: {
+        allowances: Array<{
+            type: string;
+            amount: number;
+            taxable: boolean;
+        }>;
+        deductions: Array<{
+            type: string;
+            amount: number;
+        }>;
+    };
+}
+/**
+ * Default tax brackets (US federal example)
+ * For multi-jurisdiction support, use the jurisdiction system instead
+ */
+declare const DEFAULT_TAX_BRACKETS: Array<{
+    min: number;
+    max: number;
+    rate: number;
+}>;
+declare const DEFAULT_WORK_SCHEDULE: WorkSchedule$1;
+/**
+ * Count working days in a date range
+ *
+ * @example
+ * const result = countWorkingDays(
+ *   new Date('2024-03-01'),
+ *   new Date('2024-03-31'),
+ *   { workingDays: [1,2,3,4,5], holidays: companyHolidays }
+ * );
+ */
+declare function countWorkingDays(startDate: Date, endDate: Date, options?: {
+    workingDays?: number[];
+    holidays?: Date[];
+}): WorkingDaysResult;
+/**
+ * Calculate proration ratio for partial months
+ *
+ * @example
+ * const proration = calculateProration(
+ *   employee.hireDate,
+ *   employee.terminationDate,
+ *   periodStart,
+ *   periodEnd
+ * );
+ */
+declare function calculateProration(hireDate: Date, terminationDate: Date | null | undefined, periodStart: Date, periodEnd: Date): ProrationResult;
+/**
+ * Calculate attendance deduction
+ *
+ * @example
+ * const deduction = calculateAttendanceDeduction(22, 20, dailyRate);
+ */
+declare function calculateAttendanceDeduction(expectedDays: number, actualDays: number, dailyRate: number, maxDeductionPercent?: number): number;
+/**
+ * Calculate complete salary breakdown
+ *
+ * This is the main function for salary calculation.
+ * Pass all data from YOUR app, get back complete breakdown.
+ *
+ * Note: Uses simple tax calculation. For multi-jurisdiction tax,
+ * use the jurisdiction system instead.
+ *
+ * @example
+ * const result = calculateSalaryBreakdown({
+ *   baseSalary: 100000,
+ *   hireDate: employee.hireDate,
+ *   terminationDate: employee.terminationDate,
+ *   periodStart: new Date('2024-03-01'),
+ *   periodEnd: new Date('2024-03-31'),
+ *   allowances: [{ type: 'housing', amount: 20000, taxable: true }],
+ *   deductions: [{ type: 'provident_fund', amount: 5000 }],
+ *   options: { holidays: companyHolidays },
+ *   attendance: { expectedDays: 22, actualDays: 20 },
+ * });
+ */
+declare function calculateSalaryBreakdown(params: {
+    baseSalary: number;
+    hireDate: Date;
+    terminationDate?: Date | null;
+    periodStart: Date;
+    periodEnd: Date;
+    allowances?: Array<{
+        type: string;
+        amount: number;
+        taxable?: boolean;
+    }>;
+    deductions?: Array<{
+        type: string;
+        amount: number;
+    }>;
+    options?: PayrollProcessingOptions;
+    attendance?: AttendanceInput;
+}): SalaryCalculationResult;
+/**
+ * Get pay period dates for a given month
+ *
+ * @example
+ * const period = getPayPeriod(3, 2024); // March 2024
+ */
+declare function getPayPeriod(month: number, year: number, payDay?: number): {
+    startDate: Date;
+    endDate: Date;
+    payDate: Date;
+};
+
+/**
+ * @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>;
+}
+declare class PluginManager {
+    private context;
+    private plugins;
+    private hooks;
+    constructor(context: PluginContext);
+    /**
+     * Register a plugin
+     */
+    register(plugin: PayrollPluginDefinition): Promise<void>;
+    /**
+     * Unregister a plugin
+     */
+    unregister(name: string): Promise<void>;
+    /**
+     * Add a hook handler
+     */
+    private addHook;
+    /**
+     * Execute hooks for a given event
+     */
+    executeHooks<K extends keyof PluginHooks>(hookName: K, ...args: Parameters<NonNullable<PluginHooks[K]>>): Promise<void>;
+    /**
+     * Get registered plugin names
+     */
+    getPluginNames(): string[];
+    /**
+     * Check if plugin is registered
+     */
+    hasPlugin(name: string): boolean;
+}
+/**
+ * Define a plugin with type safety
+ */
+declare function definePlugin(definition: PayrollPluginDefinition): PayrollPluginDefinition;
+/**
+ * Logging plugin - logs all payroll events
+ */
+declare const loggingPlugin: PayrollPluginDefinition;
+/**
+ * Metrics plugin - collects payroll metrics
+ */
+declare const metricsPlugin: PayrollPluginDefinition;
+/**
+ * Notification plugin - sends notifications for events
+ */
+interface NotificationPluginOptions {
+    onHired?: (employee: {
+        id: unknown;
+        name?: string;
+    }) => void | Promise<void>;
+    onTerminated?: (employee: {
+        id: unknown;
+        name?: string;
+    }) => void | Promise<void>;
+    onSalaryProcessed?: (details: {
+        employee: {
+            id: unknown;
+            name?: string;
+        };
+        amount: number;
+    }) => void | Promise<void>;
+    onMilestone?: (details: {
+        employee: {
+            id: unknown;
+            name?: string;
+        };
+        milestone: string;
+    }) => void | Promise<void>;
+}
+declare function createNotificationPlugin(options: NotificationPluginOptions): PayrollPluginDefinition;
+declare const notificationPlugin: PayrollPluginDefinition;
+
+/** 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' | 'cancelled';
+/** 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> {
+    /** 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;
+    /** 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[];
+    createdAt?: Date;
+    updatedAt?: Date;
+    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>;
+}
+/** List employees parameters */
+interface ListEmployeesParams {
+    /** Organization ID */
+    organizationId: ObjectIdLike;
+    /** Filters */
+    filters?: {
+        status?: EmployeeStatus;
+        department?: Department;
+        employmentType?: EmploymentType;
+        minSalary?: number;
+        maxSalary?: number;
+    };
+    /** Pagination */
+    pagination?: {
+        page?: number;
+        limit?: number;
+        sort?: Record<string, 1 | -1>;
+    };
+}
+/** 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;
+}
+/** Process salary parameters */
+interface ProcessSalaryParams extends EmployeeOperationParams {
+    /** Month (1-12) */
+    month: number;
+    /** Year */
+    year: number;
+    /** Payment date */
+    paymentDate?: Date;
+    /** Payment method */
+    paymentMethod?: PaymentMethod;
+    /**
+     * 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';
+}
+/** 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: {
+        employeeId: ObjectIdLike;
+        populateUser?: boolean;
+        session?: ClientSession;
+    }): Promise<TEmployee>;
+    updateEmployment(params: UpdateEmploymentParams): Promise<TEmployee>;
+    terminate(params: TerminateEmployeeParams): Promise<TEmployee>;
+    reHire(params: ReHireEmployeeParams): Promise<TEmployee>;
+    listEmployees(params: ListEmployeesParams): Promise<{
+        docs: TEmployee[];
+        totalDocs: number;
+        page: number;
+        limit: number;
+    }>;
+    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[]>;
+    /** 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';
+/** HTTP error with status code */
+interface HttpError extends Error {
+    code: ErrorCode;
+    status: number;
+    context?: Record<string, unknown>;
+    timestamp: Date;
+}
+/** Pro-rating calculation result */
+interface ProRatingResult {
+    isProRated: boolean;
+    totalDays: number;
+    actualDays: number;
+    ratio: number;
+}
+/** 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';
+/** 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>;
+    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 { getEventBus as $, type AnyDocument as A, type BulkPayrollResult as B, type Logger as C, type DeepPartial as D, type EmployeeDocument as E, type EmploymentType as F, type GetPendingTaxParams as G, type HireEmployeeParams as H, type Department as I, type WorkSchedule as J, type PaymentFrequency as K, type ListEmployeesParams as L, type MarkTaxPaidParams as M, type Allowance as N, type ObjectIdLike as O, type PayrollRecordDocument as P, type Deduction as Q, type ReHireEmployeeParams as R, type SingleTenantConfig as S, type TerminateEmployeeParams as T, type UpdateEmploymentParams as U, type BankDetails as V, type WebhookConfig as W, type Compensation as X, type TerminationReason as Y, EventBus as Z, createEventBus as _, type PayrollInstance as a, type ErrorCode as a$, resetEventBus as a0, onEmployeeHired as a1, onSalaryProcessed as a2, onPayrollCompleted as a3, onMilestoneAchieved as a4, type PayrollEventHandler as a5, type EmployeeHiredEventPayload as a6, type EmployeeTerminatedEventPayload as a7, type EmployeeRehiredEventPayload as a8, type SalaryUpdatedEventPayload as a9, countWorkingDays as aA, calculateProration as aB, calculateAttendanceDeduction as aC, calculateSalaryBreakdown as aD, getPayPeriod as aE, type LeaveType as aF, type WorkingDaysOptions as aG, type LeaveBalance as aH, type LeaveSummaryResult as aI, type LeaveInitConfig as aJ, type EmployeeStatus as aK, type PayrollPeriod as aL, type PayrollBreakdown as aM, type PaymentMethod as aN, type CompensationBreakdownResult as aO, type AnyModel as aP, type ObjectId as aQ, type TaxType as aR, type TaxStatus as aS, type PayPeriodInfo as aT, type ProRatingResult as aU, type TaxCalculationResult as aV, type EmployeeValidationResult as aW, type PayrollStatus as aX, type LeaveRequestStatus as aY, type OrgRole as aZ, type HttpError as a_, type SalaryProcessedEventPayload as aa, type SalaryFailedEventPayload as ab, type PayrollCompletedEventPayload as ac, type PayrollExportedEventPayload as ad, type CompensationChangedEventPayload as ae, type MilestoneAchievedEventPayload as af, WebhookManager as ag, PluginManager as ah, definePlugin as ai, loggingPlugin as aj, metricsPlugin as ak, notificationPlugin as al, createNotificationPlugin as am, type PluginContext as an, type PluginLogger as ao, type PluginHooks as ap, type NotificationPluginOptions as aq, type WorkSchedule$1 as ar, type PayrollProcessingOptions as as, type WorkingDaysResult as at, type ProrationResult as au, type TaxResult as av, type AttendanceInput as aw, type SalaryCalculationResult as ax, DEFAULT_WORK_SCHEDULE as ay, DEFAULT_TAX_BRACKETS as az, type PayrollInitConfig as b, type Nullable as b0, type FilterQuery as b1, type DataRetentionConfig as b2, type PayrollConfig as b3, type SalaryConfig as b4, type EmploymentConfig as b5, type ValidationConfig as b6, type EmployeeIdMode as b7, type TaxBracket as b8, type SalaryBandRange as b9, type WithPayroll as bA, type TaxSummaryByType as bB, type RoleMappingConfig as ba, type PayrollStats as bb, type PayrollCorrection as bc, type EmploymentHistoryEntry as bd, type UserReference as be, type AllowanceType as bf, type DeductionType as bg, type SalaryBand as bh, type HRMTransactionCategory as bi, type RequestLeaveInput as bj, type ReviewLeaveRequestInput as bk, type LeaveHistoryFilters as bl, type AccrueLeaveOptions as bm, type ResetAnnualLeaveOptions as bn, type EmployeeOperationParams as bo, type BulkPayrollProgress as bp, type PayrollPlugin as bq, type PluginFunction as br, type PluginType as bs, type PayrollEvent as bt, type EventPayloadBase as bu, type EmployeeHiredEvent as bv, type SalaryProcessedEvent as bw, type EventPayload as bx, type QueryOptions as by, type PayrollEmployee as bz, type PayrollPluginDefinition as c, type PayrollEventMap as d, type PayrollEventType as e, type WebhookDelivery as f, type OperationContext as g, type EmployeeIdentityMode as h, type UpdateSalaryParams as i, type AddAllowanceParams as j, type RemoveAllowanceParams as k, type AddDeductionParams as l, type RemoveDeductionParams as m, type UpdateBankDetailsParams as n, type ProcessSalaryParams as o, type ProcessSalaryResult as p, type ProcessBulkPayrollParams as q, type PayrollHistoryParams as r, type PayrollSummaryParams as s, type PayrollSummaryResult as t, type ExportPayrollParams as u, type TaxWithholdingDocument as v, type TaxSummaryParams as w, type TaxSummaryResult as x, type LeaveRequestDocument as y, type HRMConfig as z };