hvp-shared 6.68.0 → 6.70.0

package/dist/constants/hris.constants.d.ts

@@ -49,5 +49,12 @@ export declare const MONTH_WORK_DAYS: number;
 export declare const DAILY_WORK_HOURS = 8;
 /** Working days in a week (alias for clarity) */
 export declare const WEEK_WORK_DAYS = 6;
-/** Calculate hourly rate from monthly fixed income: income / 30 / 8 */
+/** Weeks per month (52 / 12 ≈ 4.333) — used for hourly rate calculation */
+export declare const WEEKS_PER_MONTH: number;
+/**
+ * Calculate hourly rate from monthly fixed income.
+ * Formula: income / (52/12) / 48
+ * Divides by work-weeks per month and max weekly hours (48).
+ * Hourly workers are NOT paid for rest days, so we use actual work hours, not calendar days.
+ */
 export declare function calculateHourlyRate(jobFixedIncome: number): number;

package/dist/constants/hris.constants.js

@@ -11,7 +11,7 @@
  * - Derived/calculated (computed from other constants)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WEEK_WORK_DAYS = exports.DAILY_WORK_HOURS = exports.MONTH_WORK_DAYS = exports.MONTH_DAYS = exports.WEEKS_IN_MONTH = exports.AVERAGE_WORK_DAYS_PER_MONTH = exports.EXCELLENCE_BONUS_RATE = exports.EXCELLENCE_BONUS_MIN_CLOSINGS = exports.DEDUCTION_INVALID_WITHDRAWAL = exports.DEDUCTION_INVALID_CLOSING = exports.BONUS_PER_CLOSING = exports.BONUS_SMALL_CLOSING = exports.BONUS_LARGE_CLOSING = exports.CLOSING_LARGE_THRESHOLD = exports.COMMISSION_SENIORITY_BONUS_PER_SEMESTER = exports.COMMISSION_PERCENTAGE_FOR_YEAR_END_BONUS = exports.YEAR_END_BONUS_DAYS = exports.ANNUAL_RAISE_PERCENT = exports.WORKING_DAYS_IN_A_WEEK = exports.MAX_DOUBLE_PLAY_WORK_WEEK_LIMIT = exports.MAX_WORK_WEEK_LIMIT = exports.HOLIDAY_OR_REST_EXTRA_PAY_PERCENTAGE = exports.SUNDAY_BONUS_PERCENTAGE = exports.VACATION_BONUS_PERCENTAGE = void 0;
+exports.WEEKS_PER_MONTH = exports.WEEK_WORK_DAYS = exports.DAILY_WORK_HOURS = exports.MONTH_WORK_DAYS = exports.MONTH_DAYS = exports.WEEKS_IN_MONTH = exports.AVERAGE_WORK_DAYS_PER_MONTH = exports.EXCELLENCE_BONUS_RATE = exports.EXCELLENCE_BONUS_MIN_CLOSINGS = exports.DEDUCTION_INVALID_WITHDRAWAL = exports.DEDUCTION_INVALID_CLOSING = exports.BONUS_PER_CLOSING = exports.BONUS_SMALL_CLOSING = exports.BONUS_LARGE_CLOSING = exports.CLOSING_LARGE_THRESHOLD = exports.COMMISSION_SENIORITY_BONUS_PER_SEMESTER = exports.COMMISSION_PERCENTAGE_FOR_YEAR_END_BONUS = exports.YEAR_END_BONUS_DAYS = exports.ANNUAL_RAISE_PERCENT = exports.WORKING_DAYS_IN_A_WEEK = exports.MAX_DOUBLE_PLAY_WORK_WEEK_LIMIT = exports.MAX_WORK_WEEK_LIMIT = exports.HOLIDAY_OR_REST_EXTRA_PAY_PERCENTAGE = exports.SUNDAY_BONUS_PERCENTAGE = exports.VACATION_BONUS_PERCENTAGE = void 0;
 exports.calculateHourlyRate = calculateHourlyRate;
 // ── Mexican Labor Law (not configurable) ──
 /** Prima vacacional: 25% of vacation days' salary (Art. 80 LFT) */
@@ -61,9 +61,16 @@ exports.DAILY_WORK_HOURS = 8;
 /** Working days in a week (alias for clarity) */
 exports.WEEK_WORK_DAYS = 6;
 // ── Utility Functions ──
-/** Calculate hourly rate from monthly fixed income: income / 30 / 8 */
+/** Weeks per month (52 / 12 ≈ 4.333) — used for hourly rate calculation */
+exports.WEEKS_PER_MONTH = 52 / 12;
+/**
+ * Calculate hourly rate from monthly fixed income.
+ * Formula: income / (52/12) / 48
+ * Divides by work-weeks per month and max weekly hours (48).
+ * Hourly workers are NOT paid for rest days, so we use actual work hours, not calendar days.
+ */
 function calculateHourlyRate(jobFixedIncome) {
     if (!jobFixedIncome || jobFixedIncome <= 0)
         return 0;
-    return Math.round((jobFixedIncome / exports.MONTH_DAYS / exports.DAILY_WORK_HOURS) * 100) / 100;
+    return Math.round((jobFixedIncome / exports.WEEKS_PER_MONTH / exports.MAX_WORK_WEEK_LIMIT) * 100) / 100;
 }

package/dist/constants/index.d.ts

@@ -20,3 +20,4 @@ export * from './qvet-cash-flow.enums';
 export * from './time-off.enums';
 export * from './time-off.constants';
 export * from './hris.constants';
+export * from './payroll-features.constants';

package/dist/constants/index.js

@@ -36,3 +36,4 @@ __exportStar(require("./qvet-cash-flow.enums"), exports);
 __exportStar(require("./time-off.enums"), exports);
 __exportStar(require("./time-off.constants"), exports);
 __exportStar(require("./hris.constants"), exports);
+__exportStar(require("./payroll-features.constants"), exports);

package/dist/constants/payroll-features.constants.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Payroll Features by Employment Type (GH#204)
+ *
+ * Defines which payroll calculation features each employment type supports
+ * and how legal concepts are renamed for hourly-based types.
+ *
+ * Used by:
+ * - Backend: payroll calculation engine (which items to include)
+ * - Frontend: payroll estimate UI (which fields to show/hide)
+ */
+import { EmploymentType } from "./employment.enums";
+/**
+ * Hourly-based types use non-legal denomination for certain concepts
+ * to avoid labor law implications (prima → apoyo, aguinaldo → apoyo de fin de año).
+ */
+export declare function isHourlyBasedType(type: EmploymentType): boolean;
+/**
+ * Salary-based types use legal denomination (prima dominical, aguinaldo, etc.)
+ * and are eligible for full tax calculation (ISR).
+ */
+export declare function isSalaryBasedType(type: EmploymentType): boolean;
+/**
+ * Payroll calculation features that can be toggled per employment type.
+ *
+ * Note: hasImss and hasCfdi are driven by the employment's config flags
+ * (hasImss, payrollStampingMode), NOT hardcoded here.
+ */
+export interface PayrollFeatures {
+    /** Base pay: salary (halfWeekFixedIncome) or hourly (hours × rate) */
+    usesHourlyBasePay: boolean;
+    /** Attendance-based deductions (absences, tardiness, unworked hours) */
+    hasAttendanceDiscounts: boolean;
+    /** Punctuality bonus (salary types only) */
+    hasPunctualityBonus: boolean;
+    /** Overtime: simple, double, triple (salary types only) */
+    hasOvertime: boolean;
+    /** Guaranteed income top-up */
+    hasGuaranteedIncome: boolean;
+    /** ISR tax withholding */
+    hasIsr: boolean;
+    /** Aguinaldo / apoyo de fin de año */
+    hasAguinaldo: boolean;
+    /** PTU (profit sharing) */
+    hasPtu: boolean;
+    /** Legal concept names renamed to non-legal ("apoyo") denomination */
+    usesRenamedConcepts: boolean;
+    /** Generates a real payroll (as opposed to only nominal) */
+    generatesRealPayroll: boolean;
+}
+export declare const PAYROLL_FEATURES: Record<EmploymentType, PayrollFeatures>;
+/**
+ * Payroll concept keys that have different labels depending on whether
+ * the employment type is salary-based (legal terms) or hourly-based (non-legal).
+ *
+ * Hourly-based types use "apoyo" denomination to avoid labor law implications.
+ */
+export declare const PAYROLL_CONCEPT_LABELS: Record<string, {
+    salary: string;
+    hourly: string;
+}>;
+/**
+ * Get the display label for a payroll concept based on employment type.
+ *
+ * @param conceptKey - Key from PAYROLL_CONCEPT_LABELS (e.g., "sundayBonus")
+ * @param employmentType - The employment type to determine denomination
+ * @returns The correct Spanish label for this concept
+ */
+export declare function getPayrollConceptLabel(conceptKey: string, employmentType: EmploymentType): string;

package/dist/constants/payroll-features.constants.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Payroll Features by Employment Type (GH#204)
+ *
+ * Defines which payroll calculation features each employment type supports
+ * and how legal concepts are renamed for hourly-based types.
+ *
+ * Used by:
+ * - Backend: payroll calculation engine (which items to include)
+ * - Frontend: payroll estimate UI (which fields to show/hide)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAYROLL_CONCEPT_LABELS = exports.PAYROLL_FEATURES = void 0;
+exports.isHourlyBasedType = isHourlyBasedType;
+exports.isSalaryBasedType = isSalaryBasedType;
+exports.getPayrollConceptLabel = getPayrollConceptLabel;
+const employment_enums_1 = require("./employment.enums");
+// ─── Employment Type Classification Helpers ──────────────────────────────────
+/**
+ * Hourly-based types use non-legal denomination for certain concepts
+ * to avoid labor law implications (prima → apoyo, aguinaldo → apoyo de fin de año).
+ */
+function isHourlyBasedType(type) {
+    return (type === employment_enums_1.EmploymentType.hourly_agreed ||
+        type === employment_enums_1.EmploymentType.casual ||
+        type === employment_enums_1.EmploymentType.intern);
+}
+/**
+ * Salary-based types use legal denomination (prima dominical, aguinaldo, etc.)
+ * and are eligible for full tax calculation (ISR).
+ */
+function isSalaryBasedType(type) {
+    return (type === employment_enums_1.EmploymentType.payroll ||
+        type === employment_enums_1.EmploymentType.payroll_draft);
+}
+exports.PAYROLL_FEATURES = {
+    [employment_enums_1.EmploymentType.payroll]: {
+        usesHourlyBasePay: false,
+        hasAttendanceDiscounts: true,
+        hasPunctualityBonus: true,
+        hasOvertime: true,
+        hasGuaranteedIncome: true,
+        hasIsr: true,
+        hasAguinaldo: true,
+        hasPtu: true,
+        usesRenamedConcepts: false,
+        generatesRealPayroll: true,
+    },
+    [employment_enums_1.EmploymentType.payroll_draft]: {
+        usesHourlyBasePay: false,
+        hasAttendanceDiscounts: true,
+        hasPunctualityBonus: true,
+        hasOvertime: true,
+        hasGuaranteedIncome: true,
+        hasIsr: false,
+        hasAguinaldo: true,
+        hasPtu: true,
+        usesRenamedConcepts: false,
+        generatesRealPayroll: true,
+    },
+    [employment_enums_1.EmploymentType.hourly_agreed]: {
+        usesHourlyBasePay: true,
+        hasAttendanceDiscounts: true,
+        hasPunctualityBonus: false,
+        hasOvertime: false,
+        hasGuaranteedIncome: false,
+        hasIsr: false,
+        hasAguinaldo: true,
+        hasPtu: true,
+        usesRenamedConcepts: true,
+        generatesRealPayroll: true,
+    },
+    [employment_enums_1.EmploymentType.casual]: {
+        usesHourlyBasePay: true,
+        hasAttendanceDiscounts: false,
+        hasPunctualityBonus: false,
+        hasOvertime: false,
+        hasGuaranteedIncome: false,
+        hasIsr: false,
+        hasAguinaldo: true,
+        hasPtu: true,
+        usesRenamedConcepts: true,
+        generatesRealPayroll: true,
+    },
+    [employment_enums_1.EmploymentType.intern]: {
+        usesHourlyBasePay: true,
+        hasAttendanceDiscounts: false,
+        hasPunctualityBonus: false,
+        hasOvertime: false,
+        hasGuaranteedIncome: false,
+        hasIsr: false,
+        hasAguinaldo: true,
+        hasPtu: true,
+        usesRenamedConcepts: true,
+        generatesRealPayroll: true,
+    },
+    [employment_enums_1.EmploymentType.coverage_only]: {
+        usesHourlyBasePay: false,
+        hasAttendanceDiscounts: false,
+        hasPunctualityBonus: false,
+        hasOvertime: false,
+        hasGuaranteedIncome: false,
+        hasIsr: false,
+        hasAguinaldo: false,
+        hasPtu: false,
+        usesRenamedConcepts: false,
+        generatesRealPayroll: false,
+    },
+    [employment_enums_1.EmploymentType.contractor]: {
+        usesHourlyBasePay: false,
+        hasAttendanceDiscounts: false,
+        hasPunctualityBonus: false,
+        hasOvertime: false,
+        hasGuaranteedIncome: false,
+        hasIsr: false,
+        hasAguinaldo: false,
+        hasPtu: false,
+        usesRenamedConcepts: false,
+        generatesRealPayroll: false,
+    },
+};
+// ─── Payroll Concept Denomination ───────────────────────────────────────────
+/**
+ * Payroll concept keys that have different labels depending on whether
+ * the employment type is salary-based (legal terms) or hourly-based (non-legal).
+ *
+ * Hourly-based types use "apoyo" denomination to avoid labor law implications.
+ */
+exports.PAYROLL_CONCEPT_LABELS = {
+    sundayBonus: {
+        salary: "Prima dominical",
+        hourly: "Apoyo dominical",
+    },
+    holidayOrRestExtraPay: {
+        salary: "Pago extra por día festivo",
+        hourly: "Apoyo por día festivo",
+    },
+    vacationBonus: {
+        salary: "Prima vacacional",
+        hourly: "Apoyo vacacional",
+    },
+    endYearBonus: {
+        salary: "Aguinaldo",
+        hourly: "Apoyo de fin de año",
+    },
+};
+/**
+ * Get the display label for a payroll concept based on employment type.
+ *
+ * @param conceptKey - Key from PAYROLL_CONCEPT_LABELS (e.g., "sundayBonus")
+ * @param employmentType - The employment type to determine denomination
+ * @returns The correct Spanish label for this concept
+ */
+function getPayrollConceptLabel(conceptKey, employmentType) {
+    const entry = exports.PAYROLL_CONCEPT_LABELS[conceptKey];
+    if (!entry)
+        return conceptKey;
+    return isHourlyBasedType(employmentType) ? entry.hourly : entry.salary;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hvp-shared",
-  "version": "6.68.0",
+  "version": "6.70.0",
   "description": "Shared types and utilities for HVP backend and frontend",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",