@classytic/payroll 1.0.2 → 2.3.0

package/dist/services/index.d.ts

@@ -0,0 +1,582 @@
+import { Model, ClientSession } from 'mongoose';
+import { E as EmployeeDocument, z as HRMConfig, O as ObjectIdLike, I as Department, aK as EmployeeStatus, g as OperationContext, X as Compensation, aL as PayrollPeriod, aM as PayrollBreakdown, aN as PaymentMethod, P as PayrollRecordDocument, aO as CompensationBreakdownResult, N as Allowance, Q as Deduction, v as TaxWithholdingDocument, aP as AnyModel, Z as EventBus, aQ as ObjectId, G as GetPendingTaxParams, w as TaxSummaryParams, x as TaxSummaryResult, M as MarkTaxPaidParams, aR as TaxType, aS as TaxStatus } from '../types-BN3K_Uhr.js';
+import { C as CreateEmployeeParams } from '../employee.factory-BlZqhiCk.js';
+
+/**
+ * @classytic/payroll - Employee Service
+ *
+ * High-level employee operations with dependency injection
+ *
+ * ⚠️ **INTERNAL USE ONLY**
+ *
+ * This service is for internal use by the Payroll class only.
+ * All methods enforce organizationId isolation for multi-tenant safety.
+ *
+ * **For application code:**
+ * - Use `Payroll` class methods (recommended, full orchestration)
+ * - Use `findEmployeeSecure()` utility for secure lookups
+ * - Do NOT use EmployeeService directly
+ *
+ * This service is intentionally not exported from the package.
+ *
+ * @internal
+ */
+
+declare class EmployeeService {
+    private readonly EmployeeModel;
+    private readonly config;
+    constructor(EmployeeModel: Model<EmployeeDocument>, config?: HRMConfig);
+    /**
+     * Find employee by ID with organization validation
+     *
+     * ⚠️ SECURITY: Always validates employee belongs to specified organization
+     *
+     * @throws {Error} If employee not found or doesn't belong to organization
+     */
+    findById(employeeId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    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 employee by employeeId (human-readable ID)
+     */
+    findByEmployeeId(employeeId: string, organizationId: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<EmployeeDocument | null>;
+    /**
+     * Find employee by email (guest employees)
+     */
+    findByEmail(email: string, organizationId: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<EmployeeDocument | null>;
+    /**
+     * Find all guest employees (no userId)
+     */
+    findGuestEmployees(organizationId: ObjectIdLike, options?: {
+        session?: ClientSession;
+    }): Promise<EmployeeDocument[]>;
+    /**
+     * 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 with organization validation
+     *
+     * ⚠️ SECURITY: Validates employee belongs to organization before update
+     */
+    updateStatus(employeeId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    status: EmployeeStatus, context?: OperationContext, options?: {
+        session?: ClientSession;
+    }): Promise<EmployeeDocument>;
+    /**
+     * Update employee compensation with organization validation
+     *
+     * ⚠️ SECURITY: Validates employee belongs to organization before update
+     *
+     * NOTE: This merges the compensation fields rather than replacing the entire object.
+     * To update allowances/deductions, use addAllowance/removeAllowance methods.
+     */
+    updateCompensation(employeeId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    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>, config?: HRMConfig): EmployeeService;
+
+/**
+ * @classytic/payroll - Payroll Factory
+ *
+ * Clean object creation for payroll records
+ * Immutable operations and builder pattern
+ */
+
+interface PayrollData {
+    employeeId: ObjectIdLike;
+    organizationId: ObjectIdLike;
+    period: PayrollPeriod;
+    breakdown: PayrollBreakdown;
+    status: 'pending';
+    processedAt: null;
+    paidAt: null;
+    metadata: {
+        currency: string;
+        paymentMethod?: PaymentMethod;
+        notes?: string;
+    };
+}
+
+/**
+ * @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 with organization validation
+     *
+     * ⚠️ SECURITY: Validates employee belongs to organization
+     */
+    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 with organization validation
+     *
+     * ⚠️ SECURITY: Validates payroll belongs to organization
+     */
+    markAsPaid(payrollId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    paymentDetails?: {
+        paidAt?: Date;
+        transactionId?: ObjectIdLike;
+        paymentMethod?: PaymentMethod;
+    }, options?: {
+        session?: ClientSession;
+    }): Promise<PayrollRecordDocument>;
+    /**
+     * Mark payroll as processed with organization validation
+     *
+     * ⚠️ SECURITY: Validates payroll belongs to organization
+     */
+    markAsProcessed(payrollId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    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 with organization validation
+     *
+     * ⚠️ SECURITY: Validates employee belongs to organization
+     */
+    getEmployeeCompensation(employeeId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    options?: {
+        session?: ClientSession;
+    }): Promise<Compensation>;
+    /**
+     * Calculate compensation breakdown with organization validation
+     *
+     * ⚠️ SECURITY: Validates employee belongs to organization
+     */
+    calculateBreakdown(employeeId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Update base amount with organization validation
+     *
+     * ⚠️ SECURITY: Validates employee belongs to organization before update
+     */
+    updateBaseAmount(employeeId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    newAmount: number, effectiveFrom?: Date, options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Apply salary increment with organization validation
+     *
+     * ⚠️ SECURITY: Validates employee belongs to organization before update
+     */
+    applyIncrement(employeeId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    params: {
+        percentage?: number;
+        amount?: number;
+        effectiveFrom?: Date;
+    }, options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Add allowance with organization validation
+     *
+     * ⚠️ SECURITY: Validates employee belongs to organization before update
+     */
+    addAllowance(employeeId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    allowance: {
+        type: Allowance['type'];
+        value: number;
+        isPercentage?: boolean;
+        name?: string;
+        taxable?: boolean;
+    }, options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Remove allowance with organization validation
+     *
+     * ⚠️ SECURITY: Validates employee belongs to organization before update
+     */
+    removeAllowance(employeeId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    allowanceType: Allowance['type'], options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Add deduction with organization validation
+     *
+     * ⚠️ SECURITY: Validates employee belongs to organization before update
+     */
+    addDeduction(employeeId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    deduction: {
+        type: Deduction['type'];
+        value: number;
+        isPercentage?: boolean;
+        name?: string;
+        auto?: boolean;
+    }, options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Remove deduction with organization validation
+     *
+     * ⚠️ SECURITY: Validates employee belongs to organization before update
+     */
+    removeDeduction(employeeId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    deductionType: Deduction['type'], options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Set standard compensation with organization validation
+     *
+     * ⚠️ SECURITY: Validates employee belongs to organization before update
+     */
+    setStandardCompensation(employeeId: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    baseAmount: number, options?: {
+        session?: ClientSession;
+    }): Promise<CompensationBreakdownResult>;
+    /**
+     * Compare compensation between two employees
+     *
+     * ⚠️ SECURITY: Validates both employees belong to organization
+     */
+    compareCompensation(employeeId1: ObjectIdLike, employeeId2: ObjectIdLike, organizationId: ObjectIdLike, // Required for multi-tenant isolation
+    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 with organization validation
+     *
+     * ⚠️ SECURITY: Always validates employee belongs to organization
+     */
+    private findEmployee;
+}
+/**
+ * Create compensation service instance
+ */
+declare function createCompensationService(EmployeeModel: Model<EmployeeDocument>): CompensationService;
+
+/**
+ * @classytic/payroll - Tax Withholding Service
+ *
+ * Business logic for tax withholding tracking and management
+ */
+
+interface TaxWithholdingServiceConfig {
+    TaxWithholdingModel: Model<TaxWithholdingDocument>;
+    TransactionModel?: AnyModel;
+    events?: EventBus;
+}
+interface CreateFromBreakdownParams {
+    organizationId: ObjectId;
+    employeeId: ObjectId;
+    userId?: ObjectId;
+    payrollRecordId: ObjectId;
+    transactionId: ObjectId;
+    period: PayrollPeriod;
+    breakdown: PayrollBreakdown;
+    currency?: string;
+    session?: ClientSession;
+    context?: OperationContext;
+}
+/**
+ * Service for managing tax withholdings
+ *
+ * Provides methods for creating, querying, and updating tax withholding records
+ */
+declare class TaxWithholdingService {
+    private readonly TaxWithholdingModel;
+    private readonly TransactionModel?;
+    private readonly events?;
+    constructor(TaxWithholdingModel: Model<TaxWithholdingDocument>, TransactionModel?: AnyModel | undefined, events?: EventBus | undefined);
+    /**
+     * Create tax withholding records from payroll breakdown
+     *
+     * Extracts tax deductions from the breakdown and creates separate
+     * TaxWithholding records for each tax type
+     */
+    createFromBreakdown(params: CreateFromBreakdownParams): Promise<TaxWithholdingDocument[]>;
+    /**
+     * Get pending tax withholdings with optional filters
+     */
+    getPending(params: GetPendingTaxParams): Promise<TaxWithholdingDocument[]>;
+    /**
+     * Get tax summary aggregated by type, period, or employee
+     */
+    getSummary(params: TaxSummaryParams): Promise<TaxSummaryResult>;
+    /**
+     * Mark tax withholdings as paid
+     *
+     * Updates status, optionally creates government payment transaction,
+     * and emits tax:paid event
+     */
+    markPaid(params: MarkTaxPaidParams): Promise<{
+        withholdings: TaxWithholdingDocument[];
+        transaction?: any;
+    }>;
+    /**
+     * Get tax withholdings for a specific payroll record
+     */
+    getByPayrollRecord(payrollRecordId: ObjectIdLike): Promise<TaxWithholdingDocument[]>;
+    /**
+     * Get tax withholdings for a specific employee
+     */
+    getByEmployee(employeeId: ObjectIdLike, options?: {
+        year?: number;
+        taxType?: TaxType;
+        status?: TaxStatus;
+    }): Promise<TaxWithholdingDocument[]>;
+    /**
+     * Check if deduction type is a tax deduction
+     */
+    private isTaxDeduction;
+    /**
+     * Map deduction type to TaxType enum
+     */
+    private mapDeductionTypeToTaxType;
+}
+/**
+ * Create a new TaxWithholdingService instance
+ *
+ * @example
+ * const service = createTaxWithholdingService({
+ *   TaxWithholdingModel,
+ *   TransactionModel,
+ *   events: eventBus
+ * });
+ */
+declare function createTaxWithholdingService(config: TaxWithholdingServiceConfig): TaxWithholdingService;
+
+export { CompensationService, type CreateFromBreakdownParams, EmployeeService, PayrollService, TaxWithholdingService, type TaxWithholdingServiceConfig, createCompensationService, createEmployeeService, createPayrollService, createTaxWithholdingService };