@classytic/payroll 2.0.0 → 2.3.0

package/dist/payroll.d.ts

@@ -1,24 +1,51 @@
+import { E as EmployeeDocument, P as PayrollRecordDocument, A as AnyDocument, a as PayrollInstance, b as PayrollInitConfig, c as PayrollPluginDefinition, d as PayrollEventMap, W as WebhookConfig, e as PayrollEventType, f as WebhookDelivery, H as HireEmployeeParams, U as UpdateEmploymentParams, T as TerminateEmployeeParams, R as ReHireEmployeeParams, O as ObjectIdLike, g as OperationContext, h as EmployeeIdentityMode, L as ListEmployeesParams, i as UpdateSalaryParams, j as AddAllowanceParams, k as RemoveAllowanceParams, l as AddDeductionParams, m as RemoveDeductionParams, n as UpdateBankDetailsParams, o as ProcessSalaryParams, p as ProcessSalaryResult, q as ProcessBulkPayrollParams, B as BulkPayrollResult, r as PayrollHistoryParams, s as PayrollSummaryParams, t as PayrollSummaryResult, u as ExportPayrollParams, G as GetPendingTaxParams, v as TaxWithholdingDocument, w as TaxSummaryParams, x as TaxSummaryResult, M as MarkTaxPaidParams, y as LeaveRequestDocument, D as DeepPartial, z as HRMConfig, S as SingleTenantConfig, C as Logger } from './types-BN3K_Uhr.js';
 import { ClientSession, Model } from 'mongoose';
-import { P as PayrollInitConfig, H as HireEmployeeParams, E as EmployeeDocument, U as UpdateEmploymentParams, T as TerminateEmployeeParams, R as ReHireEmployeeParams, O as ObjectIdLike, L as ListEmployeesParams, a as UpdateSalaryParams, A as AddAllowanceParams, b as RemoveAllowanceParams, c as AddDeductionParams, d as RemoveDeductionParams, e as UpdateBankDetailsParams, f as ProcessSalaryParams, g as ProcessSalaryResult, h as ProcessBulkPayrollParams, B as BulkPayrollResult, i as PayrollHistoryParams, j as PayrollRecordDocument, k as PayrollSummaryParams, l as PayrollSummaryResult, m as ExportPayrollParams, D as DeepPartial, n as HRMConfig, S as SingleTenantConfig, o as Logger } from './types-BSYyX2KJ.js';
-import { P as PayrollPluginDefinition, a as PayrollEventMap } from './plugin-D9mOr3_d.js';
 
 /**
- * @classytic/payroll - Main Payroll Class
+ * Fully generic Payroll class for best-in-class TypeScript DX.
  *
- * Clean, Stripe-like API for payroll management
- * Builder pattern for configuration
+ * Type parameters flow through to all methods, providing complete type inference.
+ *
+ * @typeParam TEmployee - Your Employee document type (extends EmployeeDocument)
+ * @typeParam TPayrollRecord - Your PayrollRecord document type (extends PayrollRecordDocument)
+ * @typeParam TTransaction - Your Transaction document type
+ * @typeParam TAttendance - Your Attendance document type (optional)
+ *
+ * @example
+ * ```typescript
+ * // Full type inference
+ * const payroll = createPayrollInstance()
+ *   .withModels({
+ *     EmployeeModel,      // Model<MyEmployeeDoc>
+ *     PayrollRecordModel, // Model<MyPayrollDoc>
+ *     TransactionModel,   // Model<MyTransactionDoc>
+ *   })
+ *   .build();
+ *
+ * // employee is typed as MyEmployeeDoc
+ * const employee = await payroll.hire({ ... });
+ * ```
  */
-
-declare class Payroll {
+declare class Payroll<TEmployee extends EmployeeDocument = EmployeeDocument, TPayrollRecord extends PayrollRecordDocument = PayrollRecordDocument, TTransaction extends AnyDocument = AnyDocument, TAttendance extends AnyDocument = AnyDocument> implements PayrollInstance<TEmployee, TPayrollRecord, TTransaction, TAttendance> {
+    [key: string]: unknown;
     private _container;
     private _events;
     private _plugins;
     private _initialized;
+    private _employeeService?;
+    private _payrollService?;
+    private _compensationService?;
+    private _idempotency;
+    private _webhooks;
+    /**
+     * Create a new Payroll instance with its own container.
+     * Each instance is isolated - no shared global state.
+     */
     constructor();
     /**
      * Initialize Payroll with models and configuration
      */
-    initialize(config: PayrollInitConfig): this;
+    initialize(config: PayrollInitConfig<TEmployee, TPayrollRecord, TTransaction, TAttendance>): this;
     /**
      * Check if initialized
      */
@@ -28,13 +55,38 @@ declare class Payroll {
      */
     private ensureInitialized;
     /**
-     * Get models
+     * Resolve employeeId to ObjectId _id (respects explicit mode)
+     *
+     * Mode priority:
+     * - 'objectId': Always treat as MongoDB ObjectId (direct _id lookup)
+     * - 'businessId': Always treat as business ID (lookup by employeeId field)
+     * - 'auto': Smart detection (ObjectId-like → _id, otherwise → businessId)
+     */
+    private resolveEmployeeId;
+    /**
+     * Get EmployeeService (lazy initialization)
+     */
+    private get employeeService();
+    /**
+     * Get PayrollService (lazy initialization)
+     */
+    private get payrollService();
+    /**
+     * Get CompensationService (lazy initialization)
+     */
+    private get compensationService();
+    /**
+     * Get models (strongly typed)
      */
     private get models();
     /**
      * Get config
      */
     private get config();
+    /**
+     * Get container (for org resolution and single-tenant detection)
+     */
+    private get container();
     /**
      * Register a plugin
      */
@@ -43,36 +95,103 @@ declare class Payroll {
      * Subscribe to events
      */
     on<K extends keyof PayrollEventMap>(event: K, handler: (payload: PayrollEventMap[K]) => void | Promise<void>): () => void;
+    /**
+     * Register webhook URL for events (Stripe-style)
+     */
+    registerWebhook(config: WebhookConfig): void;
+    /**
+     * Unregister webhook URL
+     */
+    unregisterWebhook(url: string): void;
+    /**
+     * Get webhook delivery log
+     */
+    getWebhookDeliveries(options?: {
+        event?: PayrollEventType;
+        status?: 'pending' | 'sent' | 'failed';
+        limit?: number;
+    }): WebhookDelivery[];
+    /**
+     * Setup webhook bridge (connects event bus to webhook manager)
+     */
+    private setupWebhookBridge;
     /**
      * Hire a new employee
      */
-    hire(params: HireEmployeeParams): Promise<EmployeeDocument>;
+    hire(params: HireEmployeeParams): Promise<TEmployee>;
     /**
      * Update employment details
      * NOTE: Status changes to 'terminated' must use terminate() method
      */
-    updateEmployment(params: UpdateEmploymentParams): Promise<EmployeeDocument>;
+    updateEmployment(params: UpdateEmploymentParams): Promise<TEmployee>;
     /**
      * Terminate employee
      */
-    terminate(params: TerminateEmployeeParams): Promise<EmployeeDocument>;
+    terminate(params: TerminateEmployeeParams): Promise<TEmployee>;
     /**
      * Re-hire terminated employee
      */
-    reHire(params: ReHireEmployeeParams): Promise<EmployeeDocument>;
+    reHire(params: ReHireEmployeeParams): Promise<TEmployee>;
     /**
      * Get employee by ID
      */
     getEmployee(params: {
-        employeeId: ObjectIdLike;
+        employeeId: ObjectIdLike | string;
+        employeeIdMode?: 'auto' | 'objectId' | 'businessId';
+        organizationId?: ObjectIdLike;
         populateUser?: boolean;
         session?: ClientSession;
-    }): Promise<EmployeeDocument>;
+        context?: OperationContext;
+    }): Promise<TEmployee>;
+    /**
+     * Get employee by flexible identity (userId, employeeId, or email)
+     *
+     * Supports multiple identity modes with automatic fallback:
+     * - 'userId': Lookup by user account ID (traditional)
+     * - 'employeeId': Lookup by human-readable employee ID (e.g., "EMP-001")
+     * - 'email': Lookup by email address (for guest employees)
+     * - 'any': Try all modes until found
+     *
+     * @example
+     * // By user ID (traditional)
+     * const emp = await payroll.getEmployeeByIdentity({
+     *   identity: userId,
+     *   organizationId,
+     *   mode: 'userId'
+     * });
+     *
+     * // By employee ID (human-readable)
+     * const emp = await payroll.getEmployeeByIdentity({
+     *   identity: 'EMP-001',
+     *   organizationId,
+     *   mode: 'employeeId'
+     * });
+     *
+     * // By email (guest employees)
+     * const emp = await payroll.getEmployeeByIdentity({
+     *   identity: 'driver@example.com',
+     *   organizationId,
+     *   mode: 'email'
+     * });
+     *
+     * // Auto-detect (uses config.identityMode + fallbacks)
+     * const emp = await payroll.getEmployeeByIdentity({
+     *   identity: 'EMP-001',
+     *   organizationId
+     * });
+     */
+    getEmployeeByIdentity(params: {
+        identity: ObjectIdLike | string;
+        organizationId?: ObjectIdLike;
+        mode?: EmployeeIdentityMode;
+        populateUser?: boolean;
+        session?: ClientSession;
+    }): Promise<TEmployee>;
     /**
      * List employees
      */
     listEmployees(params: ListEmployeesParams): Promise<{
-        docs: EmployeeDocument[];
+        docs: TEmployee[];
         totalDocs: number;
         page: number;
         limit: number;
@@ -80,27 +199,27 @@ declare class Payroll {
     /**
      * Update employee salary
      */
-    updateSalary(params: UpdateSalaryParams): Promise<EmployeeDocument>;
+    updateSalary(params: UpdateSalaryParams): Promise<TEmployee>;
     /**
      * Add allowance to employee
      */
-    addAllowance(params: AddAllowanceParams): Promise<EmployeeDocument>;
+    addAllowance(params: AddAllowanceParams): Promise<TEmployee>;
     /**
      * Remove allowance from employee
      */
-    removeAllowance(params: RemoveAllowanceParams): Promise<EmployeeDocument>;
+    removeAllowance(params: RemoveAllowanceParams): Promise<TEmployee>;
     /**
      * Add deduction to employee
      */
-    addDeduction(params: AddDeductionParams): Promise<EmployeeDocument>;
+    addDeduction(params: AddDeductionParams): Promise<TEmployee>;
     /**
      * Remove deduction from employee
      */
-    removeDeduction(params: RemoveDeductionParams): Promise<EmployeeDocument>;
+    removeDeduction(params: RemoveDeductionParams): Promise<TEmployee>;
     /**
      * Update bank details
      */
-    updateBankDetails(params: UpdateBankDetailsParams): Promise<EmployeeDocument>;
+    updateBankDetails(params: UpdateBankDetailsParams): Promise<TEmployee>;
     /**
      * Process salary for single employee
      *
@@ -108,19 +227,65 @@ declare class Payroll {
      * All database operations (PayrollRecord, Transaction, Employee stats)
      * are atomic - either all succeed or all fail.
      */
-    processSalary(params: ProcessSalaryParams): Promise<ProcessSalaryResult>;
+    processSalary(params: ProcessSalaryParams): Promise<ProcessSalaryResult<TEmployee, TPayrollRecord, TTransaction>>;
     /**
-     * Process bulk payroll
+     * Process bulk payroll for multiple employees
      *
      * ATOMICITY STRATEGY: Each employee is processed in its own transaction.
      * This allows partial success - some employees can succeed while others fail.
      * Failed employees don't affect successful ones.
+     *
+     * NEW FEATURES (all optional, backward compatible):
+     * - Progress tracking via onProgress callback
+     * - Cancellation support via AbortSignal
+     * - Batch processing to prevent resource exhaustion
+     * - Concurrency control for parallel processing
+     *
+     * @example Basic usage (unchanged)
+     * ```typescript
+     * const result = await payroll.processBulkPayroll({
+     *   organizationId, month, year
+     * });
+     * ```
+     *
+     * @example With progress tracking
+     * ```typescript
+     * await payroll.processBulkPayroll({
+     *   organizationId, month, year,
+     *   onProgress: (p) => console.log(`${p.percentage}% done`)
+     * });
+     * ```
+     *
+     * @example With job queue integration
+     * ```typescript
+     * await payroll.processBulkPayroll({
+     *   organizationId, month, year,
+     *   batchSize: 10,
+     *   onProgress: async (p) => {
+     *     await Job.findByIdAndUpdate(jobId, { progress: p });
+     *   }
+     * });
+     * ```
+     *
+     * @example With cancellation
+     * ```typescript
+     * const controller = new AbortController();
+     * payroll.processBulkPayroll({ signal: controller.signal });
+     * // Later: controller.abort();
+     * ```
      */
     processBulkPayroll(params: ProcessBulkPayrollParams): Promise<BulkPayrollResult>;
+    /**
+     * Stream-based bulk payroll processing for millions of employees.
+     * Uses MongoDB cursors to avoid loading everything into memory.
+     *
+     * @private
+     */
+    private processBulkPayrollStreaming;
     /**
      * Get payroll history
      */
-    payrollHistory(params: PayrollHistoryParams): Promise<PayrollRecordDocument[]>;
+    payrollHistory(params: PayrollHistoryParams): Promise<TPayrollRecord[]>;
     /**
      * Get payroll summary
      */
@@ -128,53 +293,93 @@ declare class Payroll {
     /**
      * Export payroll data
      */
-    exportPayroll(params: ExportPayrollParams): Promise<PayrollRecordDocument[]>;
+    exportPayroll(params: ExportPayrollParams): Promise<TPayrollRecord[]>;
     /**
-     * Calculate salary breakdown with proper handling for:
-     * - Effective dates on allowances/deductions
-     * - Pro-rating for mid-period hires AND terminations
-     * - Tax calculation
-     * - Working days vs calendar days for attendance
+     * Get pending tax withholdings with optional filters
      */
-    private calculateSalaryBreakdown;
+    getPendingTaxWithholdings(params: GetPendingTaxParams): Promise<TaxWithholdingDocument[]>;
     /**
-     * Advanced pro-rating calculation that handles:
-     * - Mid-period hires
-     * - Mid-period terminations
-     * - Working days (not calendar days)
+     * Get tax summary aggregated by type, period, or employee
      */
-    private calculateProRatingAdvanced;
+    getTaxSummary(params: TaxSummaryParams): Promise<TaxSummaryResult>;
+    /**
+     * Mark tax withholdings as paid
+     *
+     * Updates status, optionally creates government payment transaction,
+     * and emits tax:paid event
+     */
+    markTaxWithholdingsPaid(params: MarkTaxPaidParams): Promise<{
+        withholdings: TaxWithholdingDocument[];
+        transaction?: any;
+    }>;
+    /**
+     * Calculate salary breakdown
+     *
+     * Delegates to pure calculator for testability and reusability
+     */
+    private calculateSalaryBreakdown;
     /**
      * Calculate attendance deduction using working days (not calendar days)
      */
     private calculateAttendanceDeduction;
     private updatePayrollStats;
     /**
-     * Create a new Payroll instance
+     * Create a new Payroll instance with default types
      */
-    static create(): Payroll;
-}
-interface ModelsConfig {
-    EmployeeModel: Model<any>;
-    PayrollRecordModel: Model<any>;
-    TransactionModel: Model<any>;
-    AttendanceModel?: Model<any> | null;
+    static create<E extends EmployeeDocument = EmployeeDocument, P extends PayrollRecordDocument = PayrollRecordDocument, T extends AnyDocument = AnyDocument, A extends AnyDocument = AnyDocument>(): Payroll<E, P, T, A>;
 }
-interface PayrollBuilderOptions {
-    models?: ModelsConfig;
-    config?: DeepPartial<HRMConfig>;
-    singleTenant?: SingleTenantConfig | null;
-    logger?: Logger;
+/**
+ * Generic models configuration - infers types from your models
+ */
+interface ModelsConfig<TEmployee extends EmployeeDocument = EmployeeDocument, TPayrollRecord extends PayrollRecordDocument = PayrollRecordDocument, TTransaction extends AnyDocument = AnyDocument, TAttendance extends AnyDocument = AnyDocument, TLeaveRequest extends LeaveRequestDocument = LeaveRequestDocument, TTaxWithholding extends TaxWithholdingDocument = TaxWithholdingDocument> {
+    EmployeeModel: Model<TEmployee>;
+    PayrollRecordModel: Model<TPayrollRecord>;
+    TransactionModel: Model<TTransaction>;
+    AttendanceModel?: Model<TAttendance> | null;
+    LeaveRequestModel?: Model<TLeaveRequest> | null;
+    TaxWithholdingModel?: Model<TTaxWithholding> | null;
 }
-declare class PayrollBuilder {
+/**
+ * Generic Payroll Builder with full type inference.
+ *
+ * Types flow from withModels() through to build(), giving you a fully typed Payroll instance.
+ *
+ * @typeParam TEmployee - Inferred from EmployeeModel
+ * @typeParam TPayrollRecord - Inferred from PayrollRecordModel
+ * @typeParam TTransaction - Inferred from TransactionModel
+ * @typeParam TAttendance - Inferred from AttendanceModel
+ *
+ * @example
+ * ```typescript
+ * // Types are automatically inferred!
+ * const payroll = createPayrollInstance()
+ *   .withModels({
+ *     EmployeeModel,      // Model<MyEmployee>
+ *     PayrollRecordModel, // Model<MyPayroll>
+ *     TransactionModel,   // Model<MyTransaction>
+ *   })
+ *   .build(); // Returns PayrollInstance<MyEmployee, MyPayroll, MyTransaction, AnyDocument>
+ * ```
+ */
+declare class PayrollBuilder<TEmployee extends EmployeeDocument = EmployeeDocument, TPayrollRecord extends PayrollRecordDocument = PayrollRecordDocument, TTransaction extends AnyDocument = AnyDocument, TAttendance extends AnyDocument = AnyDocument, TLeaveRequest extends LeaveRequestDocument = LeaveRequestDocument, TTaxWithholding extends TaxWithholdingDocument = TaxWithholdingDocument> {
     private _models;
     private _config;
     private _singleTenant;
     private _logger;
     /**
-     * Set models
+     * Set models - types are inferred automatically
+     *
+     * @example
+     * ```typescript
+     * .withModels({
+     *   EmployeeModel,      // Your typed model
+     *   PayrollRecordModel,
+     *   TransactionModel,
+     *   AttendanceModel,    // Optional
+     * })
+     * ```
      */
-    withModels(models: ModelsConfig): this;
+    withModels<E extends EmployeeDocument, P extends PayrollRecordDocument, T extends AnyDocument, A extends AnyDocument = AnyDocument, L extends LeaveRequestDocument = LeaveRequestDocument, TW extends TaxWithholdingDocument = TaxWithholdingDocument>(models: ModelsConfig<E, P, T, A, L, TW>): PayrollBuilder<E, P, T, A, L, TW>;
     /**
      * Set config overrides
      */
@@ -212,22 +417,13 @@ declare class PayrollBuilder {
      */
     withLogger(logger: Logger): this;
     /**
-     * Build and initialize Payroll instance
+     * Build and initialize Payroll instance with inferred types
      */
-    build(): Payroll;
+    build(): PayrollInstance<TEmployee, TPayrollRecord, TTransaction, TAttendance>;
 }
 /**
  * Create a new Payroll builder
  */
 declare function createPayrollInstance(): PayrollBuilder;
-/**
- * Get or create singleton Payroll instance
- */
-declare function getPayroll(): Payroll;
-/**
- * Reset singleton (for testing)
- */
-declare function resetPayroll(): void;
-declare const payroll: Payroll;
 
-export { type ModelsConfig, Payroll, PayrollBuilder, type PayrollBuilderOptions, createPayrollInstance, payroll as default, getPayroll, payroll, resetPayroll };
+export { type ModelsConfig, Payroll, PayrollBuilder, createPayrollInstance };