@classytic/payroll 1.0.1 → 2.0.0

package/dist/payroll.d.ts

@@ -0,0 +1,233 @@
+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
+ *
+ * Clean, Stripe-like API for payroll management
+ * Builder pattern for configuration
+ */
+
+declare class Payroll {
+    private _container;
+    private _events;
+    private _plugins;
+    private _initialized;
+    constructor();
+    /**
+     * Initialize Payroll with models and configuration
+     */
+    initialize(config: PayrollInitConfig): this;
+    /**
+     * Check if initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Ensure initialized
+     */
+    private ensureInitialized;
+    /**
+     * Get models
+     */
+    private get models();
+    /**
+     * Get config
+     */
+    private get config();
+    /**
+     * 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;
+    /**
+     * Hire a new employee
+     */
+    hire(params: HireEmployeeParams): Promise<EmployeeDocument>;
+    /**
+     * Update employment details
+     * NOTE: Status changes to 'terminated' must use terminate() method
+     */
+    updateEmployment(params: UpdateEmploymentParams): Promise<EmployeeDocument>;
+    /**
+     * Terminate employee
+     */
+    terminate(params: TerminateEmployeeParams): Promise<EmployeeDocument>;
+    /**
+     * Re-hire terminated employee
+     */
+    reHire(params: ReHireEmployeeParams): Promise<EmployeeDocument>;
+    /**
+     * Get employee by ID
+     */
+    getEmployee(params: {
+        employeeId: ObjectIdLike;
+        populateUser?: boolean;
+        session?: ClientSession;
+    }): Promise<EmployeeDocument>;
+    /**
+     * List employees
+     */
+    listEmployees(params: ListEmployeesParams): Promise<{
+        docs: EmployeeDocument[];
+        totalDocs: number;
+        page: number;
+        limit: number;
+    }>;
+    /**
+     * Update employee salary
+     */
+    updateSalary(params: UpdateSalaryParams): Promise<EmployeeDocument>;
+    /**
+     * Add allowance to employee
+     */
+    addAllowance(params: AddAllowanceParams): Promise<EmployeeDocument>;
+    /**
+     * Remove allowance from employee
+     */
+    removeAllowance(params: RemoveAllowanceParams): Promise<EmployeeDocument>;
+    /**
+     * Add deduction to employee
+     */
+    addDeduction(params: AddDeductionParams): Promise<EmployeeDocument>;
+    /**
+     * Remove deduction from employee
+     */
+    removeDeduction(params: RemoveDeductionParams): Promise<EmployeeDocument>;
+    /**
+     * Update bank details
+     */
+    updateBankDetails(params: UpdateBankDetailsParams): Promise<EmployeeDocument>;
+    /**
+     * 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>;
+    /**
+     * Process bulk payroll
+     *
+     * 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.
+     */
+    processBulkPayroll(params: ProcessBulkPayrollParams): Promise<BulkPayrollResult>;
+    /**
+     * Get payroll history
+     */
+    payrollHistory(params: PayrollHistoryParams): Promise<PayrollRecordDocument[]>;
+    /**
+     * Get payroll summary
+     */
+    payrollSummary(params: PayrollSummaryParams): Promise<PayrollSummaryResult>;
+    /**
+     * Export payroll data
+     */
+    exportPayroll(params: ExportPayrollParams): Promise<PayrollRecordDocument[]>;
+    /**
+     * 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
+     */
+    private calculateSalaryBreakdown;
+    /**
+     * Advanced pro-rating calculation that handles:
+     * - Mid-period hires
+     * - Mid-period terminations
+     * - Working days (not calendar days)
+     */
+    private calculateProRatingAdvanced;
+    /**
+     * Calculate attendance deduction using working days (not calendar days)
+     */
+    private calculateAttendanceDeduction;
+    private updatePayrollStats;
+    /**
+     * Create a new Payroll instance
+     */
+    static create(): Payroll;
+}
+interface ModelsConfig {
+    EmployeeModel: Model<any>;
+    PayrollRecordModel: Model<any>;
+    TransactionModel: Model<any>;
+    AttendanceModel?: Model<any> | null;
+}
+interface PayrollBuilderOptions {
+    models?: ModelsConfig;
+    config?: DeepPartial<HRMConfig>;
+    singleTenant?: SingleTenantConfig | null;
+    logger?: Logger;
+}
+declare class PayrollBuilder {
+    private _models;
+    private _config;
+    private _singleTenant;
+    private _logger;
+    /**
+     * Set models
+     */
+    withModels(models: ModelsConfig): this;
+    /**
+     * 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
+     */
+    build(): Payroll;
+}
+/**
+ * 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 };