@classytic/payroll 1.0.2 → 2.3.0

package/dist/calculators/index.d.ts

@@ -0,0 +1,433 @@
+import { X as Compensation, b8 as TaxBracket, aM as PayrollBreakdown } from '../types-BN3K_Uhr.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 - Pro-Rating Calculator
+ *
+ * Pure functions for salary pro-rating calculations.
+ * No database dependencies - can be used client-side!
+ *
+ * Handles:
+ * - Mid-period hires
+ * - Mid-period terminations
+ * - Working days (not calendar days)
+ * - Holidays exclusion
+ *
+ * @packageDocumentation
+ */
+/**
+ * Input for pro-rating calculation
+ */
+interface ProRatingInput {
+    /**
+     * Employee hire date
+     */
+    hireDate: Date;
+    /**
+     * Employee termination date (null if still employed)
+     */
+    terminationDate: Date | null;
+    /**
+     * Start of the salary period
+     */
+    periodStart: Date;
+    /**
+     * End of the salary period
+     */
+    periodEnd: Date;
+    /**
+     * Working days of the week (1=Monday, 7=Sunday)
+     * @default [1, 2, 3, 4, 5] (Monday-Friday)
+     */
+    workingDays: number[];
+    /**
+     * Public holidays to exclude from working days
+     * @default []
+     */
+    holidays?: Date[];
+}
+/**
+ * Result of pro-rating calculation
+ */
+interface ProRatingResult {
+    /**
+     * Whether the salary needs to be pro-rated
+     */
+    isProRated: boolean;
+    /**
+     * Pro-rating ratio (0-1)
+     * 1 = full salary, 0.5 = half salary, etc.
+     */
+    ratio: number;
+    /**
+     * Total working days in the period
+     */
+    periodWorkingDays: number;
+    /**
+     * Working days the employee was actually employed
+     */
+    effectiveWorkingDays: number;
+    /**
+     * Effective start date (max of hire date and period start)
+     */
+    effectiveStart: Date;
+    /**
+     * Effective end date (min of termination date and period end)
+     */
+    effectiveEnd: Date;
+}
+/**
+ * Calculate pro-rating for mid-period hires/terminations
+ *
+ * This function uses WORKING DAYS (not calendar days) for accurate pro-rating.
+ *
+ * @example
+ * ```typescript
+ * // Employee hired on March 15th, process March salary
+ * const result = calculateProRating({
+ *   hireDate: new Date('2024-03-15'),
+ *   terminationDate: null,
+ *   periodStart: new Date('2024-03-01'),
+ *   periodEnd: new Date('2024-03-31'),
+ *   workingDays: [1, 2, 3, 4, 5], // Mon-Fri
+ * });
+ *
+ * console.log(result);
+ * // {
+ * //   isProRated: true,
+ * //   ratio: 0.64,  // Worked 14 out of 22 working days
+ * //   periodWorkingDays: 22,
+ * //   effectiveWorkingDays: 14
+ * // }
+ * ```
+ *
+ * @param input - Pro-rating calculation parameters
+ * @returns Pro-rating result with ratio and working days breakdown
+ *
+ * @pure This function has no side effects and doesn't access external state
+ */
+declare function calculateProRating(input: ProRatingInput): ProRatingResult;
+/**
+ * Calculate pro-rated amount from base amount and ratio
+ *
+ * @example
+ * ```typescript
+ * const proRatedSalary = applyProRating(100000, 0.64); // 64000
+ * ```
+ *
+ * @param baseAmount - Original amount
+ * @param ratio - Pro-rating ratio (0-1)
+ * @returns Pro-rated amount (rounded)
+ *
+ * @pure No side effects
+ */
+declare function applyProRating(baseAmount: number, ratio: number): number;
+/**
+ * Check if pro-rating should be applied for a given hire/termination scenario
+ *
+ * @param hireDate - Employee hire date
+ * @param terminationDate - Employee termination date (null if active)
+ * @param periodStart - Salary period start
+ * @param periodEnd - Salary period end
+ * @returns True if pro-rating is needed
+ *
+ * @pure No side effects
+ */
+declare function shouldProRate(hireDate: Date, terminationDate: Date | null, periodStart: Date, periodEnd: Date): boolean;
+
+/**
+ * @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 ProRatingInput, type ProRatingResult, type ProcessedAllowance, type ProcessedDeduction, type SalaryCalculationInput, applyProRating, calculateAttendanceDeduction, calculateDailyRate, calculateHourlyRate, calculatePartialDayDeduction, calculateProRating, calculateSalaryBreakdown, calculateTotalAttendanceDeduction, shouldProRate };

package/dist/calculators/index.js

@@ -0,0 +1,283 @@
+// src/utils/calculation.ts
+function sumBy(items, getter) {
+  return items.reduce((total, item) => total + getter(item), 0);
+}
+function sumAllowances(allowances) {
+  return sumBy(allowances, (a) => a.amount);
+}
+function sumDeductions(deductions) {
+  return sumBy(deductions, (d) => d.amount);
+}
+function calculateGross(baseAmount, allowances) {
+  return baseAmount + sumAllowances(allowances);
+}
+function calculateNet(gross, deductions) {
+  return Math.max(0, gross - sumDeductions(deductions));
+}
+function applyTaxBrackets(amount, brackets) {
+  let tax = 0;
+  for (const bracket of brackets) {
+    if (amount > bracket.min) {
+      const taxableAmount = Math.min(amount, bracket.max) - bracket.min;
+      tax += taxableAmount * bracket.rate;
+    }
+  }
+  return Math.round(tax);
+}
+
+// src/core/config.ts
+var DEFAULT_WORK_SCHEDULE = {
+  workingDays: [1, 2, 3, 4, 5]};
+function countWorkingDays(startDate, endDate, options = {}) {
+  const workDays = options.workingDays || DEFAULT_WORK_SCHEDULE.workingDays;
+  const holidaySet = new Set(
+    (options.holidays || []).map((d) => new Date(d).toDateString())
+  );
+  let totalDays = 0;
+  let workingDays = 0;
+  let holidays = 0;
+  let weekends = 0;
+  const current = new Date(startDate);
+  current.setHours(0, 0, 0, 0);
+  const end = new Date(endDate);
+  end.setHours(0, 0, 0, 0);
+  while (current <= end) {
+    totalDays++;
+    const isHoliday = holidaySet.has(current.toDateString());
+    const isWorkDay = workDays.includes(current.getDay());
+    if (isHoliday) {
+      holidays++;
+    } else if (isWorkDay) {
+      workingDays++;
+    } else {
+      weekends++;
+    }
+    current.setDate(current.getDate() + 1);
+  }
+  return { totalDays, workingDays, weekends, holidays };
+}
+
+// src/calculators/prorating.calculator.ts
+function calculateProRating(input) {
+  const { hireDate, terminationDate, periodStart, periodEnd, workingDays, holidays = [] } = input;
+  const hire = new Date(hireDate);
+  const termination = terminationDate ? new Date(terminationDate) : null;
+  const effectiveStart = hire > periodStart ? hire : periodStart;
+  const effectiveEnd = termination && termination < periodEnd ? termination : periodEnd;
+  if (effectiveStart > periodEnd || termination && termination < periodStart) {
+    const periodWorkingDays2 = countWorkingDays(periodStart, periodEnd, { workingDays, holidays }).workingDays;
+    return {
+      isProRated: true,
+      ratio: 0,
+      periodWorkingDays: periodWorkingDays2,
+      effectiveWorkingDays: 0,
+      effectiveStart: periodStart,
+      effectiveEnd: periodStart
+      // Effectively zero days
+    };
+  }
+  const periodWorkingDays = countWorkingDays(periodStart, periodEnd, { workingDays, holidays }).workingDays;
+  const effectiveWorkingDays = countWorkingDays(effectiveStart, effectiveEnd, { workingDays, holidays }).workingDays;
+  const ratio = periodWorkingDays > 0 ? Math.min(1, Math.max(0, effectiveWorkingDays / periodWorkingDays)) : 0;
+  const isProRated = ratio < 1;
+  return {
+    isProRated,
+    ratio,
+    periodWorkingDays,
+    effectiveWorkingDays,
+    effectiveStart,
+    effectiveEnd
+  };
+}
+function applyProRating(baseAmount, ratio) {
+  return Math.round(baseAmount * ratio);
+}
+function shouldProRate(hireDate, terminationDate, periodStart, periodEnd) {
+  const hire = new Date(hireDate);
+  const termination = terminationDate ? new Date(terminationDate) : null;
+  if (hire > periodStart) return true;
+  if (termination && termination < periodEnd) return true;
+  return false;
+}
+
+// src/calculators/attendance.calculator.ts
+function calculateAttendanceDeduction(input) {
+  const { expectedWorkingDays, actualWorkingDays, dailyRate } = input;
+  const expected = Math.max(0, expectedWorkingDays);
+  const actual = Math.max(0, actualWorkingDays);
+  const rate = Math.max(0, dailyRate);
+  const absentDays = Math.max(0, expected - actual);
+  const deductionAmount = Math.round(absentDays * rate);
+  return {
+    absentDays,
+    deductionAmount,
+    dailyRate: rate,
+    hasDeduction: deductionAmount > 0
+  };
+}
+function calculateDailyRate(monthlySalary, workingDays) {
+  if (workingDays <= 0) return 0;
+  return Math.round(monthlySalary / workingDays);
+}
+function calculateHourlyRate(monthlySalary, workingDays, hoursPerDay = 8) {
+  const dailyRate = calculateDailyRate(monthlySalary, workingDays);
+  if (hoursPerDay <= 0) return 0;
+  return Math.round(dailyRate / hoursPerDay);
+}
+function calculatePartialDayDeduction(dailyRate, fractionAbsent) {
+  const fraction = Math.min(1, Math.max(0, fractionAbsent));
+  return Math.round(dailyRate * fraction);
+}
+function calculateTotalAttendanceDeduction(input) {
+  const { dailyRate, fullDayAbsences = 0, partialDayAbsences = [] } = input;
+  const fullDayDeduction = Math.round(dailyRate * Math.max(0, fullDayAbsences));
+  const partialDayDeduction = partialDayAbsences.reduce(
+    (sum, fraction) => sum + calculatePartialDayDeduction(dailyRate, fraction),
+    0
+  );
+  return {
+    fullDayDeduction,
+    partialDayDeduction,
+    totalDeduction: fullDayDeduction + partialDayDeduction
+  };
+}
+
+// src/calculators/salary.calculator.ts
+function calculateSalaryBreakdown(input) {
+  const { employee, period, attendance, options = {}, config, taxBrackets } = input;
+  const comp = employee.compensation;
+  const originalBaseAmount = comp.baseAmount;
+  const proRating = calculateProRatingForSalary(
+    employee.hireDate,
+    employee.terminationDate || null,
+    period.startDate,
+    period.endDate,
+    options,
+    employee.workSchedule
+  );
+  let baseAmount = originalBaseAmount;
+  if (proRating.isProRated && config.allowProRating && !options.skipProration) {
+    baseAmount = Math.round(baseAmount * proRating.ratio);
+  }
+  const effectiveAllowances = (comp.allowances || []).filter((a) => isEffectiveForPeriod(a, period.startDate, period.endDate));
+  const effectiveDeductions = (comp.deductions || []).filter((d) => isEffectiveForPeriod(d, period.startDate, period.endDate)).filter((d) => d.auto || d.recurring);
+  const allowances = processAllowances(effectiveAllowances, originalBaseAmount, proRating, config);
+  const deductions = processDeductions(effectiveDeductions, originalBaseAmount, proRating, config);
+  if (!options.skipAttendance && config.attendanceIntegration && attendance) {
+    const attendanceDeductionResult = calculateAttendanceDeductionFromData(
+      attendance,
+      baseAmount,
+      proRating.effectiveWorkingDays
+    );
+    if (attendanceDeductionResult.hasDeduction) {
+      deductions.push({
+        type: "absence",
+        amount: attendanceDeductionResult.deductionAmount,
+        description: `Unpaid leave deduction (${attendanceDeductionResult.absentDays} days)`
+      });
+    }
+  }
+  const grossSalary = calculateGross(baseAmount, allowances);
+  const taxableAllowances = allowances.filter((a) => a.taxable);
+  const taxableAmount = baseAmount + sumAllowances(taxableAllowances);
+  let taxAmount = 0;
+  if (!options.skipTax && taxBrackets.length > 0 && config.autoDeductions) {
+    const annualTaxable = taxableAmount * 12;
+    const annualTax = applyTaxBrackets(annualTaxable, taxBrackets);
+    taxAmount = Math.round(annualTax / 12);
+  }
+  if (taxAmount > 0) {
+    deductions.push({
+      type: "tax",
+      amount: taxAmount,
+      description: "Income tax"
+    });
+  }
+  const netSalary = calculateNet(grossSalary, deductions);
+  return {
+    baseAmount,
+    allowances,
+    deductions,
+    grossSalary,
+    netSalary,
+    taxableAmount,
+    taxAmount,
+    workingDays: proRating.periodWorkingDays,
+    actualDays: proRating.effectiveWorkingDays,
+    proRatedAmount: proRating.isProRated && !options.skipProration ? baseAmount : 0,
+    attendanceDeduction: attendance ? deductions.find((d) => d.type === "absence")?.amount || 0 : 0
+  };
+}
+function isEffectiveForPeriod(item, periodStart, periodEnd) {
+  const effectiveFrom = item.effectiveFrom ? new Date(item.effectiveFrom) : /* @__PURE__ */ new Date(0);
+  const effectiveTo = item.effectiveTo ? new Date(item.effectiveTo) : /* @__PURE__ */ new Date("2099-12-31");
+  return effectiveFrom <= periodEnd && effectiveTo >= periodStart;
+}
+function calculateProRatingForSalary(hireDate, terminationDate, periodStart, periodEnd, options, employeeWorkSchedule) {
+  const workingDays = options?.workSchedule?.workingDays || employeeWorkSchedule?.workingDays || [1, 2, 3, 4, 5];
+  const holidays = options?.holidays || [];
+  return calculateProRating({
+    hireDate,
+    terminationDate,
+    periodStart,
+    periodEnd,
+    workingDays,
+    holidays
+  });
+}
+function processAllowances(allowances, originalBaseAmount, proRating, config) {
+  return allowances.map((a) => {
+    let amount = a.isPercentage && a.value !== void 0 ? Math.round(originalBaseAmount * a.value / 100) : a.amount;
+    const originalAmount = amount;
+    if (proRating.isProRated && config.allowProRating) {
+      amount = Math.round(amount * proRating.ratio);
+    }
+    return {
+      type: a.type,
+      amount,
+      taxable: a.taxable ?? true,
+      originalAmount,
+      isPercentage: a.isPercentage,
+      value: a.value
+    };
+  });
+}
+function processDeductions(deductions, originalBaseAmount, proRating, config) {
+  return deductions.map((d) => {
+    let amount = d.isPercentage && d.value !== void 0 ? Math.round(originalBaseAmount * d.value / 100) : d.amount;
+    const originalAmount = amount;
+    if (proRating.isProRated && config.allowProRating) {
+      amount = Math.round(amount * proRating.ratio);
+    }
+    return {
+      type: d.type,
+      amount,
+      description: d.description,
+      originalAmount,
+      isPercentage: d.isPercentage,
+      value: d.value
+    };
+  });
+}
+function calculateAttendanceDeductionFromData(attendance, baseAmount, effectiveWorkingDays) {
+  const expectedDays = attendance.expectedDays ?? effectiveWorkingDays;
+  const actualDays = attendance.actualDays;
+  if (actualDays === void 0) {
+    return { hasDeduction: false, deductionAmount: 0, absentDays: 0 };
+  }
+  const dailyRate = calculateDailyRate(baseAmount, expectedDays);
+  const result = calculateAttendanceDeduction({
+    expectedWorkingDays: expectedDays,
+    actualWorkingDays: actualDays,
+    dailyRate
+  });
+  return {
+    hasDeduction: result.hasDeduction,
+    deductionAmount: result.deductionAmount,
+    absentDays: result.absentDays
+  };
+}
+
+export { applyProRating, calculateAttendanceDeduction, calculateDailyRate, calculateHourlyRate, calculatePartialDayDeduction, calculateProRating, calculateSalaryBreakdown, calculateTotalAttendanceDeduction, shouldProRate };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map