@classytic/payroll 2.7.5 → 2.8.0

package/dist/attendance.calculator-BZcv2iii.d.ts

@@ -0,0 +1,336 @@
+import { _ as Compensation, $ as TaxBracket, a0 as TaxCalculationOptions, a1 as PayrollBreakdown } from './types-bZdAJueH.js';
+
+/**
+ * @classytic/payroll - Salary Calculator
+ *
+ * Pure functions for complete salary breakdown calculations.
+ * No database dependencies - can be used client-side!
+ *
+ * This is the SINGLE SOURCE OF TRUTH for all salary calculations.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Input for salary breakdown calculation
+ */
+interface SalaryCalculationInput {
+    /**
+     * Employee data (minimal subset needed for calculation)
+     */
+    employee: {
+        hireDate: Date;
+        terminationDate?: Date | null;
+        compensation: Compensation;
+        workSchedule?: {
+            workingDays?: number[];
+            hoursPerDay?: number;
+        };
+    };
+    /**
+     * Salary period
+     */
+    period: {
+        month: number;
+        year: number;
+        startDate: Date;
+        endDate: Date;
+    };
+    /**
+     * Attendance data (optional)
+     */
+    attendance?: {
+        expectedDays?: number;
+        actualDays?: number;
+    } | null;
+    /**
+     * Processing options
+     */
+    options?: {
+        holidays?: Date[];
+        workSchedule?: {
+            workingDays?: number[];
+            hoursPerDay?: number;
+        };
+        skipTax?: boolean;
+        skipAttendance?: boolean;
+        skipProration?: boolean;
+    };
+    /**
+     * Configuration (minimal subset)
+     */
+    config: {
+        allowProRating: boolean;
+        autoDeductions: boolean;
+        defaultCurrency: string;
+        attendanceIntegration: boolean;
+    };
+    /**
+     * Tax brackets for the employee's currency
+     */
+    taxBrackets: TaxBracket[];
+    /**
+     * Enhanced tax calculation options (optional)
+     *
+     * When provided, enables jurisdiction-aware tax calculation with:
+     * - Standard deduction / tax-free threshold
+     * - Demographic-based thresholds (senior, disabled, etc.)
+     * - Pre-tax deductions handling
+     * - Tax credits/rebates
+     *
+     * @example
+     * ```typescript
+     * taxOptions: {
+     *   applyStandardDeduction: true,
+     *   taxpayerCategory: 'senior',
+     *   preTaxDeductions: [{ type: 'provident_fund', amount: 5000 }],
+     *   taxCredits: [{ type: 'investment', amount: 2000 }],
+     * }
+     * ```
+     */
+    taxOptions?: TaxCalculationOptions;
+    /**
+     * Jurisdiction tax configuration (optional)
+     *
+     * When provided alongside taxOptions, enables lookup of:
+     * - standardDeduction from jurisdiction
+     * - thresholdsByCategory for taxpayer category
+     * - preTaxDeductionTypes for automatic pre-tax detection
+     */
+    jurisdictionTaxConfig?: {
+        /** Standard deduction amount (annual) */
+        standardDeduction?: number;
+        /** Tax-free thresholds by taxpayer category (annual) */
+        thresholdsByCategory?: Record<string, number>;
+        /** Recognized pre-tax deduction types */
+        preTaxDeductionTypes?: string[];
+    };
+}
+/**
+ * Processed allowance with calculated amount
+ */
+interface ProcessedAllowance {
+    type: string;
+    amount: number;
+    taxable: boolean;
+    originalAmount?: number;
+    isPercentage?: boolean;
+    value?: number;
+}
+/**
+ * Processed deduction with calculated amount
+ */
+interface ProcessedDeduction {
+    type: string;
+    amount: number;
+    description?: string;
+    originalAmount?: number;
+    isPercentage?: boolean;
+    value?: number;
+}
+/**
+ * Calculate complete salary breakdown
+ *
+ * This is the SINGLE SOURCE OF TRUTH for salary calculations.
+ * All payroll processing uses this function.
+ *
+ * @example
+ * ```typescript
+ * const breakdown = calculateSalaryBreakdown({
+ *   employee: {
+ *     hireDate: new Date('2024-01-01'),
+ *     compensation: {
+ *       baseAmount: 100000,
+ *       currency: 'USD',
+ *       allowances: [{ type: 'housing', amount: 20000, taxable: true }],
+ *       deductions: [{ type: 'insurance', amount: 5000 }],
+ *     },
+ *   },
+ *   period: {
+ *     month: 3,
+ *     year: 2024,
+ *     startDate: new Date('2024-03-01'),
+ *     endDate: new Date('2024-03-31'),
+ *   },
+ *   attendance: {
+ *     expectedDays: 22,
+ *     actualDays: 20, // 2 days absent
+ *   },
+ *   options: {
+ *     holidays: [new Date('2024-03-26')],
+ *   },
+ *   config: {
+ *     allowProRating: true,
+ *     autoDeductions: true,
+ *     defaultCurrency: 'USD',
+ *     attendanceIntegration: true,
+ *   },
+ *   taxBrackets: [...],
+ * });
+ * ```
+ *
+ * @param input - Salary calculation parameters
+ * @returns Complete payroll breakdown
+ *
+ * @pure This function has no side effects and doesn't access database
+ */
+declare function calculateSalaryBreakdown(input: SalaryCalculationInput): PayrollBreakdown;
+
+/**
+ * @classytic/payroll - Attendance Deduction Calculator
+ *
+ * Pure functions for calculating salary deductions based on attendance.
+ * No database dependencies - can be used client-side!
+ *
+ * All monetary calculations use banker's rounding for financial accuracy.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Input for attendance deduction calculation
+ */
+interface AttendanceDeductionInput {
+    /**
+     * Expected working days in the period (for this specific employee)
+     * Should account for hire/termination dates
+     */
+    expectedWorkingDays: number;
+    /**
+     * Actual working days the employee was present
+     */
+    actualWorkingDays: number;
+    /**
+     * Daily salary rate for this employee
+     * Calculated as: baseAmount / expectedWorkingDays
+     */
+    dailyRate: number;
+}
+/**
+ * Result of attendance deduction calculation
+ */
+interface AttendanceDeductionResult {
+    /**
+     * Number of absent days
+     */
+    absentDays: number;
+    /**
+     * Total deduction amount
+     */
+    deductionAmount: number;
+    /**
+     * Daily rate used for calculation
+     */
+    dailyRate: number;
+    /**
+     * Whether any deduction was applied
+     */
+    hasDeduction: boolean;
+}
+/**
+ * Calculate attendance deduction based on absent days
+ *
+ * @example
+ * ```typescript
+ * const result = calculateAttendanceDeduction({
+ *   expectedWorkingDays: 22,
+ *   actualWorkingDays: 20,  // 2 days absent
+ *   dailyRate: 4545,  // 100000 / 22
+ * });
+ *
+ * console.log(result);
+ * // {
+ * //   absentDays: 2,
+ * //   deductionAmount: 9090,
+ * //   dailyRate: 4545,
+ * //   hasDeduction: true
+ * // }
+ * ```
+ *
+ * @param input - Attendance deduction parameters
+ * @returns Deduction result with breakdown
+ *
+ * @pure This function has no side effects
+ */
+declare function calculateAttendanceDeduction(input: AttendanceDeductionInput): AttendanceDeductionResult;
+/**
+ * Calculate daily rate from monthly salary and working days
+ *
+ * @example
+ * ```typescript
+ * const daily = calculateDailyRate(100000, 22); // 4545
+ * ```
+ *
+ * @param monthlySalary - Monthly base salary
+ * @param workingDays - Working days in the month
+ * @returns Daily rate (rounded)
+ *
+ * @pure No side effects
+ */
+declare function calculateDailyRate(monthlySalary: number, workingDays: number): number;
+/**
+ * Calculate hourly rate from monthly salary
+ *
+ * @example
+ * ```typescript
+ * const hourly = calculateHourlyRate(100000, 22, 8); // 568
+ * ```
+ *
+ * @param monthlySalary - Monthly base salary
+ * @param workingDays - Working days in the month
+ * @param hoursPerDay - Hours per working day (default: 8)
+ * @returns Hourly rate (rounded)
+ *
+ * @pure No side effects
+ */
+declare function calculateHourlyRate(monthlySalary: number, workingDays: number, hoursPerDay?: number): number;
+/**
+ * Calculate deduction for partial day absence (half-day, quarter-day, etc.)
+ *
+ * @example
+ * ```typescript
+ * // Half-day absence
+ * const deduction = calculatePartialDayDeduction(4545, 0.5); // 2272
+ * ```
+ *
+ * @param dailyRate - Daily salary rate
+ * @param fractionAbsent - Fraction of day absent (0-1)
+ * @returns Deduction amount (rounded)
+ *
+ * @pure No side effects
+ */
+declare function calculatePartialDayDeduction(dailyRate: number, fractionAbsent: number): number;
+/**
+ * Calculate total attendance deduction including full and partial day absences
+ *
+ * @example
+ * ```typescript
+ * const result = calculateTotalAttendanceDeduction({
+ *   dailyRate: 4545,
+ *   fullDayAbsences: 2,
+ *   partialDayAbsences: [0.5, 0.25], // Half-day + quarter-day
+ * });
+ *
+ * console.log(result);
+ * // {
+ * //   fullDayDeduction: 9090,
+ * //   partialDayDeduction: 3408,
+ * //   totalDeduction: 12498
+ * // }
+ * ```
+ *
+ * @param input - Absence breakdown
+ * @returns Deduction breakdown and total
+ *
+ * @pure No side effects
+ */
+declare function calculateTotalAttendanceDeduction(input: {
+    dailyRate: number;
+    fullDayAbsences?: number;
+    partialDayAbsences?: number[];
+}): {
+    fullDayDeduction: number;
+    partialDayDeduction: number;
+    totalDeduction: number;
+};
+
+export { type AttendanceDeductionInput as A, type ProcessedAllowance as P, type SalaryCalculationInput as S, type AttendanceDeductionResult as a, type ProcessedDeduction as b, calculateAttendanceDeduction as c, calculateDailyRate as d, calculateHourlyRate as e, calculatePartialDayDeduction as f, calculateSalaryBreakdown as g, calculateTotalAttendanceDeduction as h };

package/dist/calculators/index.d.ts

@@ -1,300 +1,4 @@
-import { C as Compensation, aX as TaxBracket, ad as PayrollBreakdown } from '../types-BVDjiVGS.js';
-export { P as ProRatingInput, b as ProRatingResult, a as applyProRating, c as calculateProRating, s as shouldProRate } from '../prorating.calculator-C7sdFiG2.js';
+export { A as AttendanceDeductionInput, a as AttendanceDeductionResult, P as ProcessedAllowance, b as ProcessedDeduction, S as SalaryCalculationInput, c as calculateAttendanceDeduction, d as calculateDailyRate, e as calculateHourlyRate, f as calculatePartialDayDeduction, g as calculateSalaryBreakdown, h as calculateTotalAttendanceDeduction } from '../attendance.calculator-BZcv2iii.js';
+export { P as ProRatingInput, a as ProRatingResult, b as applyProRating, c as calculateProRating, s as shouldProRate } from '../prorating.calculator-C33fWBQf.js';
+import '../types-bZdAJueH.js';
 import 'mongoose';
-
-/**
- * @classytic/payroll - Salary Calculator
- *
- * Pure functions for complete salary breakdown calculations.
- * No database dependencies - can be used client-side!
- *
- * This is the SINGLE SOURCE OF TRUTH for all salary calculations.
- *
- * @packageDocumentation
- */
-
-/**
- * Input for salary breakdown calculation
- */
-interface SalaryCalculationInput {
-    /**
-     * Employee data (minimal subset needed for calculation)
-     */
-    employee: {
-        hireDate: Date;
-        terminationDate?: Date | null;
-        compensation: Compensation;
-        workSchedule?: {
-            workingDays?: number[];
-            hoursPerDay?: number;
-        };
-    };
-    /**
-     * Salary period
-     */
-    period: {
-        month: number;
-        year: number;
-        startDate: Date;
-        endDate: Date;
-    };
-    /**
-     * Attendance data (optional)
-     */
-    attendance?: {
-        expectedDays?: number;
-        actualDays?: number;
-    } | null;
-    /**
-     * Processing options
-     */
-    options?: {
-        holidays?: Date[];
-        workSchedule?: {
-            workingDays?: number[];
-            hoursPerDay?: number;
-        };
-        skipTax?: boolean;
-        skipAttendance?: boolean;
-        skipProration?: boolean;
-    };
-    /**
-     * Configuration (minimal subset)
-     */
-    config: {
-        allowProRating: boolean;
-        autoDeductions: boolean;
-        defaultCurrency: string;
-        attendanceIntegration: boolean;
-    };
-    /**
-     * Tax brackets for the employee's currency
-     */
-    taxBrackets: TaxBracket[];
-}
-/**
- * Processed allowance with calculated amount
- */
-interface ProcessedAllowance {
-    type: string;
-    amount: number;
-    taxable: boolean;
-    originalAmount?: number;
-    isPercentage?: boolean;
-    value?: number;
-}
-/**
- * Processed deduction with calculated amount
- */
-interface ProcessedDeduction {
-    type: string;
-    amount: number;
-    description?: string;
-    originalAmount?: number;
-    isPercentage?: boolean;
-    value?: number;
-}
-/**
- * Calculate complete salary breakdown
- *
- * This is the SINGLE SOURCE OF TRUTH for salary calculations.
- * All payroll processing uses this function.
- *
- * @example
- * ```typescript
- * const breakdown = calculateSalaryBreakdown({
- *   employee: {
- *     hireDate: new Date('2024-01-01'),
- *     compensation: {
- *       baseAmount: 100000,
- *       currency: 'USD',
- *       allowances: [{ type: 'housing', amount: 20000, taxable: true }],
- *       deductions: [{ type: 'insurance', amount: 5000 }],
- *     },
- *   },
- *   period: {
- *     month: 3,
- *     year: 2024,
- *     startDate: new Date('2024-03-01'),
- *     endDate: new Date('2024-03-31'),
- *   },
- *   attendance: {
- *     expectedDays: 22,
- *     actualDays: 20, // 2 days absent
- *   },
- *   options: {
- *     holidays: [new Date('2024-03-26')],
- *   },
- *   config: {
- *     allowProRating: true,
- *     autoDeductions: true,
- *     defaultCurrency: 'USD',
- *     attendanceIntegration: true,
- *   },
- *   taxBrackets: [...],
- * });
- * ```
- *
- * @param input - Salary calculation parameters
- * @returns Complete payroll breakdown
- *
- * @pure This function has no side effects and doesn't access database
- */
-declare function calculateSalaryBreakdown(input: SalaryCalculationInput): PayrollBreakdown;
-
-/**
- * @classytic/payroll - Attendance Deduction Calculator
- *
- * Pure functions for calculating salary deductions based on attendance.
- * No database dependencies - can be used client-side!
- *
- * @packageDocumentation
- */
-/**
- * Input for attendance deduction calculation
- */
-interface AttendanceDeductionInput {
-    /**
-     * Expected working days in the period (for this specific employee)
-     * Should account for hire/termination dates
-     */
-    expectedWorkingDays: number;
-    /**
-     * Actual working days the employee was present
-     */
-    actualWorkingDays: number;
-    /**
-     * Daily salary rate for this employee
-     * Calculated as: baseAmount / expectedWorkingDays
-     */
-    dailyRate: number;
-}
-/**
- * Result of attendance deduction calculation
- */
-interface AttendanceDeductionResult {
-    /**
-     * Number of absent days
-     */
-    absentDays: number;
-    /**
-     * Total deduction amount
-     */
-    deductionAmount: number;
-    /**
-     * Daily rate used for calculation
-     */
-    dailyRate: number;
-    /**
-     * Whether any deduction was applied
-     */
-    hasDeduction: boolean;
-}
-/**
- * Calculate attendance deduction based on absent days
- *
- * @example
- * ```typescript
- * const result = calculateAttendanceDeduction({
- *   expectedWorkingDays: 22,
- *   actualWorkingDays: 20,  // 2 days absent
- *   dailyRate: 4545,  // 100000 / 22
- * });
- *
- * console.log(result);
- * // {
- * //   absentDays: 2,
- * //   deductionAmount: 9090,
- * //   dailyRate: 4545,
- * //   hasDeduction: true
- * // }
- * ```
- *
- * @param input - Attendance deduction parameters
- * @returns Deduction result with breakdown
- *
- * @pure This function has no side effects
- */
-declare function calculateAttendanceDeduction(input: AttendanceDeductionInput): AttendanceDeductionResult;
-/**
- * Calculate daily rate from monthly salary and working days
- *
- * @example
- * ```typescript
- * const daily = calculateDailyRate(100000, 22); // 4545
- * ```
- *
- * @param monthlySalary - Monthly base salary
- * @param workingDays - Working days in the month
- * @returns Daily rate (rounded)
- *
- * @pure No side effects
- */
-declare function calculateDailyRate(monthlySalary: number, workingDays: number): number;
-/**
- * Calculate hourly rate from monthly salary
- *
- * @example
- * ```typescript
- * const hourly = calculateHourlyRate(100000, 22, 8); // 568
- * ```
- *
- * @param monthlySalary - Monthly base salary
- * @param workingDays - Working days in the month
- * @param hoursPerDay - Hours per working day (default: 8)
- * @returns Hourly rate (rounded)
- *
- * @pure No side effects
- */
-declare function calculateHourlyRate(monthlySalary: number, workingDays: number, hoursPerDay?: number): number;
-/**
- * Calculate deduction for partial day absence (half-day, quarter-day, etc.)
- *
- * @example
- * ```typescript
- * // Half-day absence
- * const deduction = calculatePartialDayDeduction(4545, 0.5); // 2272
- * ```
- *
- * @param dailyRate - Daily salary rate
- * @param fractionAbsent - Fraction of day absent (0-1)
- * @returns Deduction amount (rounded)
- *
- * @pure No side effects
- */
-declare function calculatePartialDayDeduction(dailyRate: number, fractionAbsent: number): number;
-/**
- * Calculate total attendance deduction including full and partial day absences
- *
- * @example
- * ```typescript
- * const result = calculateTotalAttendanceDeduction({
- *   dailyRate: 4545,
- *   fullDayAbsences: 2,
- *   partialDayAbsences: [0.5, 0.25], // Half-day + quarter-day
- * });
- *
- * console.log(result);
- * // {
- * //   fullDayDeduction: 9090,
- * //   partialDayDeduction: 3408,
- * //   totalDeduction: 12498
- * // }
- * ```
- *
- * @param input - Absence breakdown
- * @returns Deduction breakdown and total
- *
- * @pure No side effects
- */
-declare function calculateTotalAttendanceDeduction(input: {
-    dailyRate: number;
-    fullDayAbsences?: number;
-    partialDayAbsences?: number[];
-}): {
-    fullDayDeduction: number;
-    partialDayDeduction: number;
-    totalDeduction: number;
-};
-
-export { type AttendanceDeductionInput, type AttendanceDeductionResult, type ProcessedAllowance, type ProcessedDeduction, type SalaryCalculationInput, calculateAttendanceDeduction, calculateDailyRate, calculateHourlyRate, calculatePartialDayDeduction, calculateSalaryBreakdown, calculateTotalAttendanceDeduction };