hvp-shared 6.69.0 → 6.70.0

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.69.0",
+  "version": "6.70.0",
   "description": "Shared types and utilities for HVP backend and frontend",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",