@classytic/payroll 1.0.2 → 2.0.0

package/dist/index-CTjHlCzz.d.ts

@@ -0,0 +1,721 @@
+import { Model, ClientSession } from 'mongoose';
+import { O as ObjectIdLike, t as EmploymentType, s as Department, W as WorkSchedule, x as PaymentFrequency, y as Allowance, z as Deduction, Q as BankDetails, C as Compensation, M as TerminationReason, _ as PaymentMethod, Y as PayrollPeriod, Z as PayrollBreakdown, E as EmployeeDocument, G as EmployeeStatus, q as OperationContext, j as PayrollRecordDocument, F as CompensationBreakdownResult } from './types-BSYyX2KJ.js';
+
+/**
+ * @classytic/payroll - Employee Factory
+ *
+ * Clean object creation for employee documents
+ * Builder pattern for fluent API
+ */
+
+interface CreateEmployeeParams {
+    userId: ObjectIdLike;
+    organizationId: ObjectIdLike;
+    employment: {
+        employeeId?: string;
+        type?: EmploymentType;
+        department?: Department | string;
+        position: string;
+        hireDate?: Date;
+        probationMonths?: number;
+        workSchedule?: WorkSchedule;
+    };
+    compensation: {
+        baseAmount: number;
+        frequency?: PaymentFrequency;
+        currency?: string;
+        allowances?: Array<Partial<Allowance>>;
+        deductions?: Array<Partial<Deduction>>;
+    };
+    bankDetails?: BankDetails;
+}
+interface EmployeeData {
+    userId: ObjectIdLike;
+    organizationId: ObjectIdLike;
+    employeeId: string;
+    employmentType: EmploymentType;
+    status: 'active';
+    department?: Department;
+    position: string;
+    hireDate: Date;
+    probationEndDate: Date | null;
+    compensation: Compensation;
+    workSchedule: WorkSchedule;
+    bankDetails: BankDetails;
+    payrollStats: {
+        totalPaid: number;
+        paymentsThisYear: number;
+        averageMonthly: number;
+    };
+}
+interface TerminationData {
+    terminatedAt: Date;
+    terminationReason: TerminationReason;
+    terminationNotes?: string;
+    terminatedBy: {
+        userId?: ObjectIdLike;
+        name?: string;
+        role?: string;
+    };
+}
+declare class EmployeeFactory {
+    /**
+     * Create employee data object
+     */
+    static create(params: CreateEmployeeParams): EmployeeData;
+    /**
+     * Create compensation object
+     */
+    static createCompensation(params: {
+        baseAmount: number;
+        frequency?: PaymentFrequency;
+        currency?: string;
+        allowances?: Array<Partial<Allowance>>;
+        deductions?: Array<Partial<Deduction>>;
+    }): Compensation;
+    /**
+     * Create allowance object
+     */
+    static createAllowance(params: {
+        type: Allowance['type'];
+        amount: number;
+        name?: string;
+        isPercentage?: boolean;
+        taxable?: boolean;
+        recurring?: boolean;
+    }): Allowance;
+    /**
+     * Create deduction object
+     */
+    static createDeduction(params: {
+        type: Deduction['type'];
+        amount: number;
+        name?: string;
+        isPercentage?: boolean;
+        auto?: boolean;
+        recurring?: boolean;
+        description?: string;
+    }): Deduction;
+    /**
+     * Default work schedule
+     */
+    static defaultWorkSchedule(): WorkSchedule;
+    /**
+     * Create termination data
+     */
+    static createTermination(params: {
+        reason: TerminationReason;
+        date?: Date;
+        notes?: string;
+        context?: {
+            userId?: ObjectIdLike;
+            userName?: string;
+            userRole?: string;
+        };
+    }): TerminationData;
+}
+declare class EmployeeBuilder {
+    private data;
+    /**
+     * Set user ID
+     */
+    forUser(userId: ObjectIdLike): this;
+    /**
+     * Set organization ID
+     */
+    inOrganization(organizationId: ObjectIdLike): this;
+    /**
+     * Set employee ID
+     */
+    withEmployeeId(employeeId: string): this;
+    /**
+     * Set department
+     */
+    inDepartment(department: Department): this;
+    /**
+     * Set position
+     */
+    asPosition(position: string): this;
+    /**
+     * Set employment type
+     */
+    withEmploymentType(type: EmploymentType): this;
+    /**
+     * Set hire date
+     */
+    hiredOn(date: Date): this;
+    /**
+     * Set probation period
+     */
+    withProbation(months: number): this;
+    /**
+     * Set work schedule
+     */
+    withSchedule(schedule: WorkSchedule): this;
+    /**
+     * Set base salary
+     */
+    withBaseSalary(amount: number, frequency?: PaymentFrequency, currency?: string): this;
+    /**
+     * Add allowance
+     */
+    addAllowance(type: Allowance['type'], amount: number, options?: {
+        taxable?: boolean;
+        recurring?: boolean;
+    }): this;
+    /**
+     * Add deduction
+     */
+    addDeduction(type: Deduction['type'], amount: number, options?: {
+        auto?: boolean;
+        recurring?: boolean;
+        description?: string;
+    }): this;
+    /**
+     * Set bank details
+     */
+    withBankDetails(bankDetails: BankDetails): this;
+    /**
+     * Build employee data
+     */
+    build(): EmployeeData;
+}
+
+/**
+ * @classytic/payroll - Payroll Factory
+ *
+ * Clean object creation for payroll records
+ * Immutable operations and builder pattern
+ */
+
+interface CreatePayrollParams {
+    employeeId: ObjectIdLike;
+    organizationId: ObjectIdLike;
+    baseAmount: number;
+    allowances?: Array<{
+        type: string;
+        amount: number;
+        taxable?: boolean;
+    }>;
+    deductions?: Array<{
+        type: string;
+        amount: number;
+        description?: string;
+    }>;
+    period?: {
+        month?: number;
+        year?: number;
+    };
+    metadata?: {
+        currency?: string;
+        paymentMethod?: PaymentMethod;
+        notes?: string;
+    };
+}
+interface PayrollData {
+    employeeId: ObjectIdLike;
+    organizationId: ObjectIdLike;
+    period: PayrollPeriod;
+    breakdown: PayrollBreakdown;
+    status: 'pending';
+    processedAt: null;
+    paidAt: null;
+    metadata: {
+        currency: string;
+        paymentMethod?: PaymentMethod;
+        notes?: string;
+    };
+}
+declare class PayrollFactory {
+    /**
+     * Create payroll data object
+     */
+    static create(params: CreatePayrollParams): PayrollData;
+    /**
+     * Create pay period
+     */
+    static createPeriod(params: {
+        month?: number;
+        year?: number;
+        payDate?: Date;
+    }): PayrollPeriod;
+    /**
+     * Calculate allowances from base amount
+     */
+    static calculateAllowances(baseAmount: number, allowances: Array<{
+        type: string;
+        amount: number;
+        taxable?: boolean;
+        isPercentage?: boolean;
+        value?: number;
+    }>): Array<{
+        type: string;
+        amount: number;
+        taxable: boolean;
+    }>;
+    /**
+     * Calculate deductions from base amount
+     */
+    static calculateDeductions(baseAmount: number, deductions: Array<{
+        type: string;
+        amount: number;
+        description?: string;
+        isPercentage?: boolean;
+        value?: number;
+    }>): Array<{
+        type: string;
+        amount: number;
+        description?: string;
+    }>;
+    /**
+     * Create bonus object
+     */
+    static createBonus(params: {
+        type: string;
+        amount: number;
+        reason: string;
+        approvedBy?: ObjectIdLike;
+    }): {
+        type: string;
+        amount: number;
+        reason: string;
+        approvedBy?: ObjectIdLike;
+        approvedAt: Date;
+    };
+    /**
+     * Mark payroll as paid (immutable)
+     * Sets both top-level transactionId and metadata for compatibility
+     */
+    static markAsPaid<T extends {
+        status: string;
+        paidAt?: Date | null;
+        processedAt?: Date | null;
+        transactionId?: unknown;
+        metadata?: Record<string, unknown>;
+    }>(payroll: T, params?: {
+        paidAt?: Date;
+        transactionId?: ObjectIdLike;
+        paymentMethod?: PaymentMethod;
+    }): T & {
+        status: 'paid';
+    };
+    /**
+     * Mark payroll as processed (immutable)
+     */
+    static markAsProcessed<T extends {
+        status: string;
+        processedAt: Date | null;
+    }>(payroll: T, params?: {
+        processedAt?: Date;
+    }): T & {
+        status: 'processing';
+    };
+}
+declare class BatchPayrollFactory {
+    /**
+     * Create payroll records for multiple employees
+     */
+    static createBatch(employees: Array<{
+        _id: ObjectIdLike;
+        organizationId: ObjectIdLike;
+        compensation: Compensation;
+    }>, params: {
+        month: number;
+        year: number;
+        organizationId?: ObjectIdLike;
+    }): PayrollData[];
+    /**
+     * Calculate total payroll amounts
+     */
+    static calculateTotalPayroll(payrolls: Array<{
+        breakdown: PayrollBreakdown;
+    }>): {
+        count: number;
+        totalGross: number;
+        totalNet: number;
+        totalAllowances: number;
+        totalDeductions: number;
+    };
+}
+
+/**
+ * @classytic/payroll - Employee Service
+ *
+ * High-level employee operations with dependency injection
+ */
+
+declare class EmployeeService {
+    private readonly EmployeeModel;
+    constructor(EmployeeModel: Model<EmployeeDocument>);
+    /**
+     * Find employee by ID
+     */
+    findById(employeeId: ObjectIdLike, options?: {
+        session?: ClientSession;
+        populate?: boolean;
+    }): Promise<EmployeeDocument | null>;
+    /**
+     * Find employee by user and organization
+     */
+    findByUserId(userId: ObjectIdLike, organizationId: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<EmployeeDocument | null>;
+    /**
+     * Find active employees in organization
+     */
+    findActive(organizationId: ObjectIdLike, options?: {
+        session?: ClientSession;
+        projection?: Record<string, number>;
+    }): Promise<EmployeeDocument[]>;
+    /**
+     * Find employed employees (not terminated)
+     */
+    findEmployed(organizationId: ObjectIdLike, options?: {
+        session?: ClientSession;
+        projection?: Record<string, number>;
+    }): Promise<EmployeeDocument[]>;
+    /**
+     * Find employees by department
+     */
+    findByDepartment(organizationId: ObjectIdLike, department: Department, options?: {
+        session?: ClientSession;
+    }): Promise<EmployeeDocument[]>;
+    /**
+     * Find employees eligible for payroll
+     */
+    findEligibleForPayroll(organizationId: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<EmployeeDocument[]>;
+    /**
+     * Create new employee
+     */
+    create(params: CreateEmployeeParams, options?: {
+        session?: ClientSession;
+    }): Promise<EmployeeDocument>;
+    /**
+     * Update employee status
+     */
+    updateStatus(employeeId: ObjectIdLike, status: EmployeeStatus, context?: OperationContext, options?: {
+        session?: ClientSession;
+    }): Promise<EmployeeDocument>;
+    /**
+     * Update employee compensation
+     *
+     * NOTE: This merges the compensation fields rather than replacing the entire object.
+     * To update allowances/deductions, use addAllowance/removeAllowance methods.
+     */
+    updateCompensation(employeeId: ObjectIdLike, compensation: Partial<Compensation>, options?: {
+        session?: ClientSession;
+    }): Promise<EmployeeDocument>;
+    /**
+     * Get employee statistics for organization
+     */
+    getEmployeeStats(organizationId: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<{
+        total: number;
+        active: number;
+        employed: number;
+        canReceiveSalary: number;
+        byStatus: Record<string, number>;
+        byDepartment: Record<string, number>;
+    }>;
+    /**
+     * Group employees by status
+     */
+    private groupByStatus;
+    /**
+     * Group employees by department
+     */
+    private groupByDepartment;
+    /**
+     * Check if employee is active
+     */
+    isActive(employee: EmployeeDocument): boolean;
+    /**
+     * Check if employee is employed
+     */
+    isEmployed(employee: EmployeeDocument): boolean;
+    /**
+     * Check if employee can receive salary
+     */
+    canReceiveSalary(employee: EmployeeDocument): boolean;
+}
+/**
+ * Create employee service instance
+ */
+declare function createEmployeeService(EmployeeModel: Model<EmployeeDocument>): EmployeeService;
+
+/**
+ * @classytic/payroll - Payroll Service
+ *
+ * High-level payroll operations with dependency injection
+ */
+
+declare class PayrollService {
+    private readonly PayrollModel;
+    private readonly employeeService;
+    constructor(PayrollModel: Model<PayrollRecordDocument>, employeeService: EmployeeService);
+    /**
+     * Find payroll by ID
+     */
+    findById(payrollId: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<PayrollRecordDocument | null>;
+    /**
+     * Find payrolls by employee
+     */
+    findByEmployee(employeeId: ObjectIdLike, organizationId: ObjectIdLike, options?: {
+        session?: ClientSession;
+        limit?: number;
+    }): Promise<PayrollRecordDocument[]>;
+    /**
+     * Find payrolls for a period
+     */
+    findForPeriod(organizationId: ObjectIdLike, month: number, year: number, options?: {
+        session?: ClientSession;
+    }): Promise<PayrollRecordDocument[]>;
+    /**
+     * Find pending payrolls
+     */
+    findPending(organizationId: ObjectIdLike, month: number, year: number, options?: {
+        session?: ClientSession;
+    }): Promise<PayrollRecordDocument[]>;
+    /**
+     * Find payroll by employee and period
+     */
+    findByEmployeeAndPeriod(employeeId: ObjectIdLike, organizationId: ObjectIdLike, month: number, year: number, options?: {
+        session?: ClientSession;
+    }): Promise<PayrollRecordDocument | null>;
+    /**
+     * Create payroll record
+     */
+    create(data: PayrollData, options?: {
+        session?: ClientSession;
+    }): Promise<PayrollRecordDocument>;
+    /**
+     * Generate payroll for employee
+     */
+    generateForEmployee(employeeId: ObjectIdLike, organizationId: ObjectIdLike, month: number, year: number, options?: {
+        session?: ClientSession;
+    }): Promise<PayrollRecordDocument>;
+    /**
+     * Generate batch payroll
+     */
+    generateBatch(organizationId: ObjectIdLike, month: number, year: number, options?: {
+        session?: ClientSession;
+    }): Promise<{
+        success: boolean;
+        generated: number;
+        skipped: number;
+        payrolls: PayrollRecordDocument[];
+        message: string;
+    }>;
+    /**
+     * Mark payroll as paid
+     */
+    markAsPaid(payrollId: ObjectIdLike, paymentDetails?: {
+        paidAt?: Date;
+        transactionId?: ObjectIdLike;
+        paymentMethod?: PaymentMethod;
+    }, options?: {
+        session?: ClientSession;
+    }): Promise<PayrollRecordDocument>;
+    /**
+     * Mark payroll as processed
+     */
+    markAsProcessed(payrollId: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<PayrollRecordDocument>;
+    /**
+     * Calculate period summary
+     */
+    calculatePeriodSummary(organizationId: ObjectIdLike, month: number, year: number, options?: {
+        session?: ClientSession;
+    }): Promise<{
+        period: {
+            month: number;
+            year: number;
+        };
+        count: number;
+        totalGross: number;
+        totalNet: number;
+        totalAllowances: number;
+        totalDeductions: number;
+        byStatus: Record<string, number>;
+    }>;
+    /**
+     * Get employee payroll history
+     */
+    getEmployeePayrollHistory(employeeId: ObjectIdLike, organizationId: ObjectIdLike, limit?: number, options?: {
+        session?: ClientSession;
+    }): Promise<PayrollRecordDocument[]>;
+    /**
+     * Get overview stats
+     */
+    getOverviewStats(organizationId: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<{
+        currentPeriod: {
+            month: number;
+            year: number;
+        };
+        count: number;
+        totalGross: number;
+        totalNet: number;
+        totalAllowances: number;
+        totalDeductions: number;
+        byStatus: Record<string, number>;
+    }>;
+    /**
+     * Group payrolls by status
+     */
+    private groupByStatus;
+}
+/**
+ * Create payroll service instance
+ */
+declare function createPayrollService(PayrollModel: Model<PayrollRecordDocument>, employeeService: EmployeeService): PayrollService;
+
+/**
+ * @classytic/payroll - Compensation Service
+ *
+ * High-level compensation operations with dependency injection
+ */
+
+declare class CompensationService {
+    private readonly EmployeeModel;
+    constructor(EmployeeModel: Model<EmployeeDocument>);
+    /**
+     * Get employee compensation
+     */
+    getEmployeeCompensation(employeeId: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<Compensation>;
+    /**
+     * Calculate compensation breakdown
+     */
+    calculateBreakdown(employeeId: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Update base amount
+     */
+    updateBaseAmount(employeeId: ObjectIdLike, newAmount: number, effectiveFrom?: Date, options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Apply salary increment
+     */
+    applyIncrement(employeeId: ObjectIdLike, params: {
+        percentage?: number;
+        amount?: number;
+        effectiveFrom?: Date;
+    }, options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Add allowance
+     */
+    addAllowance(employeeId: ObjectIdLike, allowance: {
+        type: Allowance['type'];
+        value: number;
+        isPercentage?: boolean;
+        name?: string;
+        taxable?: boolean;
+    }, options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Remove allowance
+     */
+    removeAllowance(employeeId: ObjectIdLike, allowanceType: Allowance['type'], options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Add deduction
+     */
+    addDeduction(employeeId: ObjectIdLike, deduction: {
+        type: Deduction['type'];
+        value: number;
+        isPercentage?: boolean;
+        name?: string;
+        auto?: boolean;
+    }, options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Remove deduction
+     */
+    removeDeduction(employeeId: ObjectIdLike, deductionType: Deduction['type'], options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Set standard compensation
+     */
+    setStandardCompensation(employeeId: ObjectIdLike, baseAmount: number, options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Compare compensation between two employees
+     */
+    compareCompensation(employeeId1: ObjectIdLike, employeeId2: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<{
+        employee1: CompensationBreakdownResult;
+        employee2: CompensationBreakdownResult;
+        difference: {
+            base: number;
+            gross: number;
+            net: number;
+        };
+        ratio: {
+            base: number;
+            gross: number;
+            net: number;
+        };
+    }>;
+    /**
+     * Get department compensation stats
+     */
+    getDepartmentCompensationStats(organizationId: ObjectIdLike, department: Department, options?: {
+        session?: ClientSession;
+    }): Promise<{
+        department: string;
+        employeeCount: number;
+        totalBase: number;
+        totalGross: number;
+        totalNet: number;
+        averageBase: number;
+        averageGross: number;
+        averageNet: number;
+    }>;
+    /**
+     * Get organization compensation stats
+     */
+    getOrganizationCompensationStats(organizationId: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<{
+        employeeCount: number;
+        totalBase: number;
+        totalGross: number;
+        totalNet: number;
+        averageBase: number;
+        averageGross: number;
+        averageNet: number;
+        byDepartment: Record<string, {
+            count: number;
+            totalNet: number;
+        }>;
+    }>;
+    /**
+     * Find employee helper
+     */
+    private findEmployee;
+}
+/**
+ * Create compensation service instance
+ */
+declare function createCompensationService(EmployeeModel: Model<EmployeeDocument>): CompensationService;
+
+export { BatchPayrollFactory as B, CompensationService as C, EmployeeFactory as E, PayrollFactory as P, EmployeeBuilder as a, EmployeeService as b, PayrollService as c, createEmployeeService as d, createPayrollService as e, createCompensationService as f };