@classytic/payroll 1.0.2 → 2.3.0

package/dist/payroll.d.ts

@@ -0,0 +1,429 @@
+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';
+
+/**
+ * Fully generic Payroll class for best-in-class TypeScript DX.
+ *
+ * Type parameters flow through to all methods, providing complete type inference.
+ *
+ * @typeParam TEmployee - Your Employee document type (extends EmployeeDocument)
+ * @typeParam TPayrollRecord - Your PayrollRecord document type (extends PayrollRecordDocument)
+ * @typeParam TTransaction - Your Transaction document type
+ * @typeParam TAttendance - Your Attendance document type (optional)
+ *
+ * @example
+ * ```typescript
+ * // Full type inference
+ * const payroll = createPayrollInstance()
+ *   .withModels({
+ *     EmployeeModel,      // Model<MyEmployeeDoc>
+ *     PayrollRecordModel, // Model<MyPayrollDoc>
+ *     TransactionModel,   // Model<MyTransactionDoc>
+ *   })
+ *   .build();
+ *
+ * // employee is typed as MyEmployeeDoc
+ * const employee = await payroll.hire({ ... });
+ * ```
+ */
+declare class Payroll<TEmployee extends EmployeeDocument = EmployeeDocument, TPayrollRecord extends PayrollRecordDocument = PayrollRecordDocument, TTransaction extends AnyDocument = AnyDocument, TAttendance extends AnyDocument = AnyDocument> implements PayrollInstance<TEmployee, TPayrollRecord, TTransaction, TAttendance> {
+    [key: string]: unknown;
+    private _container;
+    private _events;
+    private _plugins;
+    private _initialized;
+    private _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<TEmployee, TPayrollRecord, TTransaction, TAttendance>): this;
+    /**
+     * Check if initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Ensure initialized
+     */
+    private ensureInitialized;
+    /**
+     * Resolve employeeId to ObjectId _id (respects explicit mode)
+     *
+     * Mode priority:
+     * - 'objectId': Always treat as MongoDB ObjectId (direct _id lookup)
+     * - 'businessId': Always treat as business ID (lookup by employeeId field)
+     * - 'auto': Smart detection (ObjectId-like → _id, otherwise → businessId)
+     */
+    private resolveEmployeeId;
+    /**
+     * 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
+     */
+    use(plugin: PayrollPluginDefinition): Promise<this>;
+    /**
+     * Subscribe to events
+     */
+    on<K extends keyof PayrollEventMap>(event: K, handler: (payload: PayrollEventMap[K]) => void | Promise<void>): () => void;
+    /**
+     * Register webhook URL for events (Stripe-style)
+     */
+    registerWebhook(config: WebhookConfig): void;
+    /**
+     * Unregister webhook URL
+     */
+    unregisterWebhook(url: string): void;
+    /**
+     * Get webhook delivery log
+     */
+    getWebhookDeliveries(options?: {
+        event?: PayrollEventType;
+        status?: 'pending' | 'sent' | 'failed';
+        limit?: number;
+    }): WebhookDelivery[];
+    /**
+     * Setup webhook bridge (connects event bus to webhook manager)
+     */
+    private setupWebhookBridge;
+    /**
+     * Hire a new employee
+     */
+    hire(params: HireEmployeeParams): Promise<TEmployee>;
+    /**
+     * Update employment details
+     * NOTE: Status changes to 'terminated' must use terminate() method
+     */
+    updateEmployment(params: UpdateEmploymentParams): Promise<TEmployee>;
+    /**
+     * Terminate employee
+     */
+    terminate(params: TerminateEmployeeParams): Promise<TEmployee>;
+    /**
+     * Re-hire terminated employee
+     */
+    reHire(params: ReHireEmployeeParams): Promise<TEmployee>;
+    /**
+     * Get employee by ID
+     */
+    getEmployee(params: {
+        employeeId: ObjectIdLike | string;
+        employeeIdMode?: 'auto' | 'objectId' | 'businessId';
+        organizationId?: ObjectIdLike;
+        populateUser?: boolean;
+        session?: ClientSession;
+        context?: OperationContext;
+    }): Promise<TEmployee>;
+    /**
+     * Get employee by flexible identity (userId, employeeId, or email)
+     *
+     * Supports multiple identity modes with automatic fallback:
+     * - 'userId': Lookup by user account ID (traditional)
+     * - 'employeeId': Lookup by human-readable employee ID (e.g., "EMP-001")
+     * - 'email': Lookup by email address (for guest employees)
+     * - 'any': Try all modes until found
+     *
+     * @example
+     * // By user ID (traditional)
+     * const emp = await payroll.getEmployeeByIdentity({
+     *   identity: userId,
+     *   organizationId,
+     *   mode: 'userId'
+     * });
+     *
+     * // By employee ID (human-readable)
+     * const emp = await payroll.getEmployeeByIdentity({
+     *   identity: 'EMP-001',
+     *   organizationId,
+     *   mode: 'employeeId'
+     * });
+     *
+     * // By email (guest employees)
+     * const emp = await payroll.getEmployeeByIdentity({
+     *   identity: 'driver@example.com',
+     *   organizationId,
+     *   mode: 'email'
+     * });
+     *
+     * // Auto-detect (uses config.identityMode + fallbacks)
+     * const emp = await payroll.getEmployeeByIdentity({
+     *   identity: 'EMP-001',
+     *   organizationId
+     * });
+     */
+    getEmployeeByIdentity(params: {
+        identity: ObjectIdLike | string;
+        organizationId?: ObjectIdLike;
+        mode?: EmployeeIdentityMode;
+        populateUser?: boolean;
+        session?: ClientSession;
+    }): Promise<TEmployee>;
+    /**
+     * List employees
+     */
+    listEmployees(params: ListEmployeesParams): Promise<{
+        docs: TEmployee[];
+        totalDocs: number;
+        page: number;
+        limit: number;
+    }>;
+    /**
+     * Update employee salary
+     */
+    updateSalary(params: UpdateSalaryParams): Promise<TEmployee>;
+    /**
+     * Add allowance to employee
+     */
+    addAllowance(params: AddAllowanceParams): Promise<TEmployee>;
+    /**
+     * Remove allowance from employee
+     */
+    removeAllowance(params: RemoveAllowanceParams): Promise<TEmployee>;
+    /**
+     * Add deduction to employee
+     */
+    addDeduction(params: AddDeductionParams): Promise<TEmployee>;
+    /**
+     * Remove deduction from employee
+     */
+    removeDeduction(params: RemoveDeductionParams): Promise<TEmployee>;
+    /**
+     * Update bank details
+     */
+    updateBankDetails(params: UpdateBankDetailsParams): Promise<TEmployee>;
+    /**
+     * Process salary for single employee
+     *
+     * ATOMICITY: This method creates its own transaction if none provided.
+     * All database operations (PayrollRecord, Transaction, Employee stats)
+     * are atomic - either all succeed or all fail.
+     */
+    processSalary(params: ProcessSalaryParams): Promise<ProcessSalaryResult<TEmployee, TPayrollRecord, TTransaction>>;
+    /**
+     * Process bulk payroll for multiple employees
+     *
+     * ATOMICITY STRATEGY: Each employee is processed in its own transaction.
+     * This allows partial success - some employees can succeed while others fail.
+     * Failed employees don't affect successful ones.
+     *
+     * NEW FEATURES (all optional, backward compatible):
+     * - Progress tracking via onProgress callback
+     * - Cancellation support via AbortSignal
+     * - Batch processing to prevent resource exhaustion
+     * - Concurrency control for parallel processing
+     *
+     * @example Basic usage (unchanged)
+     * ```typescript
+     * const result = await payroll.processBulkPayroll({
+     *   organizationId, month, year
+     * });
+     * ```
+     *
+     * @example With progress tracking
+     * ```typescript
+     * await payroll.processBulkPayroll({
+     *   organizationId, month, year,
+     *   onProgress: (p) => console.log(`${p.percentage}% done`)
+     * });
+     * ```
+     *
+     * @example With job queue integration
+     * ```typescript
+     * await payroll.processBulkPayroll({
+     *   organizationId, month, year,
+     *   batchSize: 10,
+     *   onProgress: async (p) => {
+     *     await Job.findByIdAndUpdate(jobId, { progress: p });
+     *   }
+     * });
+     * ```
+     *
+     * @example With cancellation
+     * ```typescript
+     * const controller = new AbortController();
+     * payroll.processBulkPayroll({ signal: controller.signal });
+     * // Later: controller.abort();
+     * ```
+     */
+    processBulkPayroll(params: ProcessBulkPayrollParams): Promise<BulkPayrollResult>;
+    /**
+     * 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<TPayrollRecord[]>;
+    /**
+     * Get payroll summary
+     */
+    payrollSummary(params: PayrollSummaryParams): Promise<PayrollSummaryResult>;
+    /**
+     * Export payroll data
+     */
+    exportPayroll(params: ExportPayrollParams): Promise<TPayrollRecord[]>;
+    /**
+     * Get pending tax withholdings with optional filters
+     */
+    getPendingTaxWithholdings(params: GetPendingTaxParams): Promise<TaxWithholdingDocument[]>;
+    /**
+     * Get tax summary aggregated by type, period, or employee
+     */
+    getTaxSummary(params: TaxSummaryParams): Promise<TaxSummaryResult>;
+    /**
+     * Mark tax withholdings as paid
+     *
+     * Updates status, optionally creates government payment transaction,
+     * and emits tax:paid event
+     */
+    markTaxWithholdingsPaid(params: MarkTaxPaidParams): Promise<{
+        withholdings: TaxWithholdingDocument[];
+        transaction?: any;
+    }>;
+    /**
+     * Calculate salary breakdown
+     *
+     * Delegates to pure calculator for testability and reusability
+     */
+    private calculateSalaryBreakdown;
+    /**
+     * Calculate attendance deduction using working days (not calendar days)
+     */
+    private calculateAttendanceDeduction;
+    private updatePayrollStats;
+    /**
+     * Create a new Payroll instance with default types
+     */
+    static create<E extends EmployeeDocument = EmployeeDocument, P extends PayrollRecordDocument = PayrollRecordDocument, T extends AnyDocument = AnyDocument, A extends AnyDocument = AnyDocument>(): Payroll<E, P, T, A>;
+}
+/**
+ * Generic models configuration - infers types from your models
+ */
+interface ModelsConfig<TEmployee extends EmployeeDocument = EmployeeDocument, TPayrollRecord extends PayrollRecordDocument = PayrollRecordDocument, TTransaction extends AnyDocument = AnyDocument, TAttendance extends AnyDocument = AnyDocument, TLeaveRequest extends LeaveRequestDocument = LeaveRequestDocument, TTaxWithholding extends TaxWithholdingDocument = TaxWithholdingDocument> {
+    EmployeeModel: Model<TEmployee>;
+    PayrollRecordModel: Model<TPayrollRecord>;
+    TransactionModel: Model<TTransaction>;
+    AttendanceModel?: Model<TAttendance> | null;
+    LeaveRequestModel?: Model<TLeaveRequest> | null;
+    TaxWithholdingModel?: Model<TTaxWithholding> | null;
+}
+/**
+ * Generic Payroll Builder with full type inference.
+ *
+ * Types flow from withModels() through to build(), giving you a fully typed Payroll instance.
+ *
+ * @typeParam TEmployee - Inferred from EmployeeModel
+ * @typeParam TPayrollRecord - Inferred from PayrollRecordModel
+ * @typeParam TTransaction - Inferred from TransactionModel
+ * @typeParam TAttendance - Inferred from AttendanceModel
+ *
+ * @example
+ * ```typescript
+ * // Types are automatically inferred!
+ * const payroll = createPayrollInstance()
+ *   .withModels({
+ *     EmployeeModel,      // Model<MyEmployee>
+ *     PayrollRecordModel, // Model<MyPayroll>
+ *     TransactionModel,   // Model<MyTransaction>
+ *   })
+ *   .build(); // Returns PayrollInstance<MyEmployee, MyPayroll, MyTransaction, AnyDocument>
+ * ```
+ */
+declare class PayrollBuilder<TEmployee extends EmployeeDocument = EmployeeDocument, TPayrollRecord extends PayrollRecordDocument = PayrollRecordDocument, TTransaction extends AnyDocument = AnyDocument, TAttendance extends AnyDocument = AnyDocument, TLeaveRequest extends LeaveRequestDocument = LeaveRequestDocument, TTaxWithholding extends TaxWithholdingDocument = TaxWithholdingDocument> {
+    private _models;
+    private _config;
+    private _singleTenant;
+    private _logger;
+    /**
+     * Set models - types are inferred automatically
+     *
+     * @example
+     * ```typescript
+     * .withModels({
+     *   EmployeeModel,      // Your typed model
+     *   PayrollRecordModel,
+     *   TransactionModel,
+     *   AttendanceModel,    // Optional
+     * })
+     * ```
+     */
+    withModels<E extends EmployeeDocument, P extends PayrollRecordDocument, T extends AnyDocument, A extends AnyDocument = AnyDocument, L extends LeaveRequestDocument = LeaveRequestDocument, TW extends TaxWithholdingDocument = TaxWithholdingDocument>(models: ModelsConfig<E, P, T, A, L, TW>): PayrollBuilder<E, P, T, A, L, TW>;
+    /**
+     * Set config overrides
+     */
+    withConfig(config: DeepPartial<HRMConfig>): this;
+    /**
+     * Enable single-tenant mode
+     *
+     * Use this when building a single-organization HRM (no organizationId needed)
+     *
+     * @example
+     * ```typescript
+     * const payroll = createPayrollInstance()
+     *   .withModels({ EmployeeModel, PayrollRecordModel, TransactionModel })
+     *   .withSingleTenant({ organizationId: 'my-company' })
+     *   .build();
+     * ```
+     */
+    withSingleTenant(config: SingleTenantConfig): this;
+    /**
+     * Enable single-tenant mode (shorthand)
+     *
+     * Alias for withSingleTenant() - consistent with @classytic/clockin API
+     *
+     * @example
+     * ```typescript
+     * const payroll = createPayrollInstance()
+     *   .withModels({ ... })
+     *   .forSingleTenant() // ← No organizationId needed!
+     *   .build();
+     * ```
+     */
+    forSingleTenant(config?: SingleTenantConfig): this;
+    /**
+     * Set custom logger
+     */
+    withLogger(logger: Logger): this;
+    /**
+     * Build and initialize Payroll instance with inferred types
+     */
+    build(): PayrollInstance<TEmployee, TPayrollRecord, TTransaction, TAttendance>;
+}
+/**
+ * Create a new Payroll builder
+ */
+declare function createPayrollInstance(): PayrollBuilder;
+
+export { type ModelsConfig, Payroll, PayrollBuilder, createPayrollInstance };