@classytic/payroll 1.0.2 → 2.0.0

package/dist/types-BSYyX2KJ.d.ts

@@ -0,0 +1,671 @@
+import { Model, Types, ClientSession, Document } from 'mongoose';
+
+/**
+ * @classytic/payroll - Type Definitions
+ *
+ * Production-grade types for HRM and payroll management
+ * Follows industry patterns from Stripe, Netflix, Meta
+ *
+ * @module @classytic/payroll
+ */
+
+/** Re-export mongoose ObjectId */
+type ObjectId = Types.ObjectId;
+/** ObjectId or string representation */
+type ObjectIdLike = ObjectId | string;
+/** Generic document type */
+type AnyDocument = Document & Record<string, unknown>;
+/** Deep partial type for nested objects */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/** Employment type */
+type EmploymentType = 'full_time' | 'part_time' | 'contract' | 'intern' | 'consultant';
+/** Employee status */
+type EmployeeStatus = 'active' | 'on_leave' | 'suspended' | 'terminated';
+/** Department type */
+type Department = 'management' | 'training' | 'sales' | 'operations' | 'support' | 'hr' | 'maintenance' | 'marketing' | 'finance' | 'it';
+/** Payment frequency */
+type PaymentFrequency = 'monthly' | 'bi_weekly' | 'weekly' | 'hourly' | 'daily';
+/** Payment method */
+type PaymentMethod = 'bank' | 'cash' | 'check' | 'mobile' | 'bkash' | 'nagad' | 'rocket';
+/** Allowance type */
+type AllowanceType = 'housing' | 'transport' | 'meal' | 'mobile' | 'medical' | 'education' | 'bonus' | 'other';
+/** Deduction type */
+type DeductionType = 'tax' | 'loan' | 'advance' | 'provident_fund' | 'insurance' | 'absence' | 'other';
+/** Payroll status */
+type PayrollStatus = 'pending' | 'processing' | 'paid' | 'failed' | 'cancelled';
+/** Termination reason */
+type TerminationReason = 'resignation' | 'retirement' | 'termination' | 'contract_end' | 'mutual_agreement' | 'other';
+/** HRM transaction category */
+type HRMTransactionCategory = 'salary' | 'bonus' | 'commission' | 'overtime' | 'severance';
+/** Organization role */
+type OrgRole = 'owner' | 'manager' | 'trainer' | 'staff' | 'intern' | 'consultant';
+/** Data retention configuration */
+interface DataRetentionConfig {
+    /** TTL for payroll records in seconds (default: 2 years) */
+    payrollRecordsTTL: number;
+    /** Days before TTL to warn (default: 30) */
+    exportWarningDays: number;
+    /** Archive records before deletion */
+    archiveBeforeDeletion: boolean;
+}
+/** Payroll configuration */
+interface PayrollConfig {
+    /** Default currency code */
+    defaultCurrency: string;
+    /** Allow pro-rating for mid-month hires */
+    allowProRating: boolean;
+    /** Enable attendance integration */
+    attendanceIntegration: boolean;
+    /** Auto-apply deductions */
+    autoDeductions: boolean;
+    /** Enable overtime calculations */
+    overtimeEnabled: boolean;
+    /** Overtime multiplier (e.g., 1.5 for 150%) */
+    overtimeMultiplier: number;
+}
+/** Salary configuration */
+interface SalaryConfig {
+    /** Minimum wage threshold */
+    minimumWage: number;
+    /** Maximum number of allowances */
+    maximumAllowances: number;
+    /** Maximum number of deductions */
+    maximumDeductions: number;
+    /** Default payment frequency */
+    defaultFrequency: PaymentFrequency;
+}
+/** Employment configuration */
+interface EmploymentConfig {
+    /** Default probation period in months */
+    defaultProbationMonths: number;
+    /** Maximum probation period in months */
+    maxProbationMonths: number;
+    /** Allow re-hiring terminated employees */
+    allowReHiring: boolean;
+    /** Track employment history */
+    trackEmploymentHistory: boolean;
+}
+/** Validation configuration */
+interface ValidationConfig {
+    /** Require bank details for salary payment */
+    requireBankDetails: boolean;
+    /** Require employee ID */
+    requireEmployeeId: boolean;
+    /** Enforce unique employee ID per organization */
+    uniqueEmployeeIdPerOrg: boolean;
+    /** Allow same user in multiple organizations */
+    allowMultiTenantEmployees: boolean;
+}
+/** Main HRM configuration */
+interface HRMConfig {
+    /** Data retention settings */
+    dataRetention: DataRetentionConfig;
+    /** Payroll settings */
+    payroll: PayrollConfig;
+    /** Salary settings */
+    salary: SalaryConfig;
+    /** Employment settings */
+    employment: EmploymentConfig;
+    /** Validation settings */
+    validation: ValidationConfig;
+}
+/** Single-tenant configuration */
+interface SingleTenantConfig {
+    /** Fixed organization ID (optional - will use default if not provided) */
+    organizationId?: ObjectIdLike;
+    /** Auto-inject organizationId if missing (default: true) */
+    autoInject?: boolean;
+}
+/** Main Payroll initialization config */
+interface PayrollInitConfig {
+    /** Employee model (required) */
+    EmployeeModel: Model<any>;
+    /** Payroll record model (required) */
+    PayrollRecordModel: Model<any>;
+    /** Transaction model (required) */
+    TransactionModel: Model<any>;
+    /** Attendance model (optional, for integration) */
+    AttendanceModel?: Model<any> | null;
+    /** Single-tenant configuration */
+    singleTenant?: SingleTenantConfig | null;
+    /** Custom logger */
+    logger?: Logger;
+    /** Custom HRM config overrides */
+    config?: DeepPartial<HRMConfig>;
+}
+/** Bank details */
+interface BankDetails {
+    accountName?: string;
+    accountNumber?: string;
+    bankName?: string;
+    branchName?: string;
+    routingNumber?: string;
+}
+/** Allowance entry */
+interface Allowance {
+    type: AllowanceType;
+    name?: string;
+    amount: number;
+    /** Whether amount is percentage of base salary */
+    isPercentage?: boolean;
+    /** Percentage value if isPercentage is true */
+    value?: number;
+    taxable?: boolean;
+    recurring?: boolean;
+    effectiveFrom?: Date;
+    effectiveTo?: Date | null;
+}
+/** Deduction entry */
+interface Deduction {
+    type: DeductionType;
+    name?: string;
+    amount: number;
+    /** Whether amount is percentage of base salary */
+    isPercentage?: boolean;
+    /** Percentage value if isPercentage is true */
+    value?: number;
+    auto?: boolean;
+    recurring?: boolean;
+    effectiveFrom?: Date;
+    effectiveTo?: Date | null;
+    description?: string;
+}
+/** Compensation structure */
+interface Compensation {
+    /** Base salary amount */
+    baseAmount: number;
+    /** Payment frequency */
+    frequency: PaymentFrequency;
+    /** Currency code */
+    currency: string;
+    /** Allowances array */
+    allowances: Allowance[];
+    /** Deductions array */
+    deductions: Deduction[];
+    /** Calculated gross salary */
+    grossSalary?: number;
+    /** Calculated net salary */
+    netSalary?: number;
+    /** When compensation became effective */
+    effectiveFrom?: Date;
+    /** Last modified timestamp */
+    lastModified?: Date;
+}
+/** Work schedule */
+interface WorkSchedule {
+    hoursPerWeek?: number;
+    hoursPerDay?: number;
+    /** Working days (0=Sunday, 6=Saturday) */
+    workingDays?: number[];
+    shiftStart?: string;
+    shiftEnd?: string;
+}
+/** Employment history entry */
+interface EmploymentHistoryEntry {
+    hireDate: Date;
+    terminationDate: Date;
+    reason?: TerminationReason;
+    finalSalary?: number;
+    position?: string;
+    department?: string;
+    notes?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+/** Payroll stats (pre-calculated) */
+interface PayrollStats {
+    totalPaid: number;
+    lastPaymentDate?: Date | null;
+    nextPaymentDate?: Date | null;
+    paymentsThisYear: number;
+    averageMonthly: number;
+    updatedAt?: Date;
+}
+/** Employee document structure */
+interface EmployeeDocument extends Document {
+    _id: ObjectId;
+    userId: ObjectId;
+    organizationId: ObjectId;
+    employeeId: string;
+    employmentType: EmploymentType;
+    status: EmployeeStatus;
+    department?: Department;
+    position: string;
+    hireDate: Date;
+    terminationDate?: Date | null;
+    probationEndDate?: Date | null;
+    employmentHistory: EmploymentHistoryEntry[];
+    compensation: Compensation;
+    workSchedule?: WorkSchedule;
+    bankDetails?: BankDetails;
+    payrollStats: PayrollStats;
+    notes?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+    save(options?: {
+        session?: ClientSession;
+    }): Promise<this>;
+    toObject(): Record<string, unknown>;
+}
+/** Payroll period */
+interface PayrollPeriod {
+    month: number;
+    year: number;
+    startDate: Date;
+    endDate: Date;
+    payDate: Date;
+}
+/** Payroll breakdown */
+interface PayrollBreakdown {
+    baseAmount: number;
+    allowances: Array<{
+        type: string;
+        amount: number;
+        taxable?: boolean;
+    }>;
+    deductions: Array<{
+        type: string;
+        amount: number;
+        description?: string;
+    }>;
+    grossSalary: number;
+    netSalary: number;
+    /** Taxable amount (base + taxable allowances) */
+    taxableAmount?: number;
+    /** Calculated tax amount */
+    taxAmount?: number;
+    workingDays?: number;
+    actualDays?: number;
+    proRatedAmount?: number;
+    attendanceDeduction?: number;
+    overtimeAmount?: number;
+    bonusAmount?: number;
+}
+/** Payroll record document */
+interface PayrollRecordDocument extends Document {
+    _id: ObjectId;
+    organizationId: ObjectId;
+    employeeId: ObjectId;
+    userId?: ObjectId;
+    period: PayrollPeriod;
+    breakdown: PayrollBreakdown;
+    transactionId?: ObjectId | null;
+    status: PayrollStatus;
+    paidAt?: Date | null;
+    processedAt?: Date | null;
+    paymentMethod?: PaymentMethod;
+    metadata?: Record<string, unknown>;
+    processedBy?: ObjectId;
+    notes?: string;
+    payslipUrl?: string;
+    exported: boolean;
+    exportedAt?: Date | null;
+    createdAt?: Date;
+    updatedAt?: Date;
+    save(options?: {
+        session?: ClientSession;
+    }): Promise<this>;
+    toObject(): Record<string, unknown>;
+}
+/** Base operation context */
+interface OperationContext {
+    /** User performing the operation */
+    userId?: ObjectIdLike;
+    /** User name */
+    userName?: string;
+    /** User role */
+    userRole?: string;
+    /** Organization ID (auto-injected in single-tenant mode) */
+    organizationId?: ObjectIdLike;
+    /** MongoDB session for transactions */
+    session?: ClientSession;
+}
+/** Hire employee parameters */
+interface HireEmployeeParams {
+    /** User ID */
+    userId: ObjectIdLike;
+    /** Organization ID (optional in single-tenant mode - auto-injected) */
+    organizationId?: ObjectIdLike;
+    /** Employment details */
+    employment: {
+        employeeId?: string;
+        type?: EmploymentType;
+        department?: Department | string;
+        position: string;
+        hireDate?: Date;
+        probationMonths?: number;
+        workSchedule?: WorkSchedule;
+    };
+    /** Compensation details */
+    compensation: {
+        baseAmount: number;
+        frequency?: PaymentFrequency;
+        currency?: string;
+        allowances?: Array<Partial<Allowance>>;
+        deductions?: Array<Partial<Deduction>>;
+    };
+    /** Bank details */
+    bankDetails?: BankDetails;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Update employment parameters */
+interface UpdateEmploymentParams {
+    /** Employee document ID */
+    employeeId: ObjectIdLike;
+    /** Fields to update */
+    updates: {
+        department?: Department;
+        position?: string;
+        employmentType?: EmploymentType;
+        status?: EmployeeStatus;
+        workSchedule?: WorkSchedule;
+    };
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Terminate employee parameters */
+interface TerminateEmployeeParams {
+    /** Employee document ID */
+    employeeId: ObjectIdLike;
+    /** Termination date */
+    terminationDate?: Date;
+    /** Termination reason */
+    reason?: TerminationReason;
+    /** Notes */
+    notes?: string;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Re-hire employee parameters */
+interface ReHireEmployeeParams {
+    /** Employee document ID */
+    employeeId: ObjectIdLike;
+    /** New hire date */
+    hireDate?: Date;
+    /** New position */
+    position?: string;
+    /** New department */
+    department?: Department;
+    /** New compensation */
+    compensation?: DeepPartial<Compensation>;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** List employees parameters */
+interface ListEmployeesParams {
+    /** Organization ID */
+    organizationId: ObjectIdLike;
+    /** Filters */
+    filters?: {
+        status?: EmployeeStatus;
+        department?: Department;
+        employmentType?: EmploymentType;
+        minSalary?: number;
+        maxSalary?: number;
+    };
+    /** Pagination */
+    pagination?: {
+        page?: number;
+        limit?: number;
+        sort?: Record<string, 1 | -1>;
+    };
+}
+/** Update salary parameters */
+interface UpdateSalaryParams {
+    /** Employee document ID */
+    employeeId: ObjectIdLike;
+    /** Compensation updates */
+    compensation: {
+        baseAmount?: number;
+        frequency?: PaymentFrequency;
+        currency?: string;
+    };
+    /** Effective from date */
+    effectiveFrom?: Date;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Add allowance parameters */
+interface AddAllowanceParams {
+    /** Employee document ID */
+    employeeId: ObjectIdLike;
+    /** Allowance type */
+    type: AllowanceType;
+    /** Amount */
+    amount: number;
+    /** Is taxable */
+    taxable?: boolean;
+    /** Is recurring */
+    recurring?: boolean;
+    /** Effective from */
+    effectiveFrom?: Date;
+    /** Effective to */
+    effectiveTo?: Date | null;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Remove allowance parameters */
+interface RemoveAllowanceParams {
+    /** Employee document ID */
+    employeeId: ObjectIdLike;
+    /** Allowance type to remove */
+    type: AllowanceType;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Add deduction parameters */
+interface AddDeductionParams {
+    /** Employee document ID */
+    employeeId: ObjectIdLike;
+    /** Deduction type */
+    type: DeductionType;
+    /** Amount */
+    amount: number;
+    /** Auto-deduct from salary */
+    auto?: boolean;
+    /** Is recurring */
+    recurring?: boolean;
+    /** Description */
+    description?: string;
+    /** Effective from */
+    effectiveFrom?: Date;
+    /** Effective to */
+    effectiveTo?: Date | null;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Remove deduction parameters */
+interface RemoveDeductionParams {
+    /** Employee document ID */
+    employeeId: ObjectIdLike;
+    /** Deduction type to remove */
+    type: DeductionType;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Update bank details parameters */
+interface UpdateBankDetailsParams {
+    /** Employee document ID */
+    employeeId: ObjectIdLike;
+    /** Bank details */
+    bankDetails: BankDetails;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Process salary parameters */
+interface ProcessSalaryParams {
+    /** Employee document ID */
+    employeeId: ObjectIdLike;
+    /** Month (1-12) */
+    month: number;
+    /** Year */
+    year: number;
+    /** Payment date */
+    paymentDate?: Date;
+    /** Payment method */
+    paymentMethod?: PaymentMethod;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Process bulk payroll parameters */
+interface ProcessBulkPayrollParams {
+    /** Organization ID */
+    organizationId: ObjectIdLike;
+    /** Month (1-12) */
+    month: number;
+    /** Year */
+    year: number;
+    /** Specific employee IDs (empty = all active) */
+    employeeIds?: ObjectIdLike[];
+    /** Payment date */
+    paymentDate?: Date;
+    /** Payment method */
+    paymentMethod?: PaymentMethod;
+    /** Operation context */
+    context?: OperationContext;
+}
+/** Payroll history parameters */
+interface PayrollHistoryParams {
+    /** Employee document ID */
+    employeeId?: ObjectIdLike;
+    /** Organization ID */
+    organizationId?: ObjectIdLike;
+    /** Month filter */
+    month?: number;
+    /** Year filter */
+    year?: number;
+    /** Status filter */
+    status?: PayrollStatus;
+    /** Pagination */
+    pagination?: {
+        page?: number;
+        limit?: number;
+        sort?: Record<string, 1 | -1>;
+    };
+}
+/** Payroll summary parameters */
+interface PayrollSummaryParams {
+    /** Organization ID */
+    organizationId: ObjectIdLike;
+    /** Month */
+    month?: number;
+    /** Year */
+    year?: number;
+}
+/** Export payroll parameters */
+interface ExportPayrollParams {
+    /** Organization ID */
+    organizationId: ObjectIdLike;
+    /** Start date */
+    startDate: Date;
+    /** End date */
+    endDate: Date;
+    /** Export format */
+    format?: 'json' | 'csv';
+}
+/** Process salary result */
+interface ProcessSalaryResult {
+    payrollRecord: PayrollRecordDocument;
+    transaction: AnyDocument;
+    employee: EmployeeDocument;
+}
+/** Bulk payroll result */
+interface BulkPayrollResult {
+    successful: Array<{
+        employeeId: string;
+        amount: number;
+        transactionId: ObjectId;
+    }>;
+    failed: Array<{
+        employeeId: string;
+        error: string;
+    }>;
+    total: number;
+}
+/** Payroll summary result */
+interface PayrollSummaryResult {
+    totalGross: number;
+    totalNet: number;
+    totalDeductions: number;
+    employeeCount: number;
+    paidCount: number;
+    pendingCount: number;
+}
+/** Tax calculation result */
+interface TaxCalculationResult {
+    gross: number;
+    tax: number;
+    net: number;
+}
+/** Compensation breakdown result */
+interface CompensationBreakdownResult {
+    baseAmount: number;
+    allowances: Array<Allowance & {
+        calculatedAmount: number;
+    }>;
+    deductions: Array<Deduction & {
+        calculatedAmount: number;
+    }>;
+    grossAmount: number;
+    netAmount: number;
+}
+/** Payroll instance for plugin reference */
+interface PayrollInstance {
+    /** Models container */
+    _models: {
+        EmployeeModel: Model<any>;
+        PayrollRecordModel: Model<any>;
+        TransactionModel: Model<any>;
+        AttendanceModel?: Model<any> | null;
+    } | null;
+    /** Event hooks */
+    _hooks: Map<string, Array<(data: unknown) => void | Promise<void>>>;
+    /** Is initialized */
+    _initialized: boolean;
+    /** Register event listener */
+    on(event: string, listener: (data: unknown) => void | Promise<void>): this;
+    /** Emit event */
+    emit(event: string, data: unknown): void;
+    /** Extended properties from plugins */
+    [key: string]: unknown;
+}
+/** Logger interface */
+interface Logger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+/** Error codes */
+type ErrorCode = 'PAYROLL_ERROR' | 'NOT_INITIALIZED' | 'EMPLOYEE_NOT_FOUND' | 'INVALID_EMPLOYEE' | 'DUPLICATE_PAYROLL' | 'VALIDATION_ERROR' | 'EMPLOYEE_TERMINATED' | 'ALREADY_PROCESSED' | 'NOT_ELIGIBLE';
+/** HTTP error with status code */
+interface HttpError extends Error {
+    code: ErrorCode;
+    status: number;
+    context?: Record<string, unknown>;
+    timestamp: Date;
+}
+/** Pro-rating calculation result */
+interface ProRatingResult {
+    isProRated: boolean;
+    totalDays: number;
+    actualDays: number;
+    ratio: number;
+}
+/** Pay period info */
+interface PayPeriodInfo {
+    month: number;
+    year: number;
+    startDate: Date;
+    endDate: Date;
+}
+/** Employee validation result */
+interface EmployeeValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+
+export type { PayPeriodInfo as $, AddAllowanceParams as A, BulkPayrollResult as B, Compensation as C, DeepPartial as D, EmployeeDocument as E, CompensationBreakdownResult as F, EmployeeStatus as G, HireEmployeeParams as H, AllowanceType as I, DeductionType as J, PayrollStatus as K, ListEmployeesParams as L, TerminationReason as M, HRMTransactionCategory as N, ObjectIdLike as O, PayrollInitConfig as P, BankDetails as Q, ReHireEmployeeParams as R, SingleTenantConfig as S, TerminateEmployeeParams as T, UpdateEmploymentParams as U, EmploymentHistoryEntry as V, WorkSchedule as W, PayrollStats as X, PayrollPeriod as Y, PayrollBreakdown as Z, PaymentMethod as _, UpdateSalaryParams as a, ProRatingResult as a0, TaxCalculationResult as a1, EmployeeValidationResult as a2, RemoveAllowanceParams as b, AddDeductionParams as c, RemoveDeductionParams as d, UpdateBankDetailsParams as e, ProcessSalaryParams as f, ProcessSalaryResult as g, ProcessBulkPayrollParams as h, PayrollHistoryParams as i, PayrollRecordDocument as j, PayrollSummaryParams as k, PayrollSummaryResult as l, ExportPayrollParams as m, HRMConfig as n, Logger as o, ObjectId as p, OperationContext as q, PayrollInstance as r, Department as s, EmploymentType as t, OrgRole as u, HttpError as v, ErrorCode as w, PaymentFrequency as x, Allowance as y, Deduction as z };