hvp-shared 6.69.0 → 6.71.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/dist/types/payroll-v2.types.d.ts

@@ -6,6 +6,7 @@
  * how the amount was calculated.
  */
 import { CfdiStatus, PayrollStatus } from '../constants/hr.enums';
+import { CompensationType, EmploymentType, PayrollStampingMode } from '../constants/employment.enums';
 export declare enum PayrollItemCategory {
     BASE_SALARY = "BASE_SALARY",
     ADDITIONAL_FIXED = "ADDITIONAL_FIXED",
@@ -118,6 +119,29 @@ export interface PayrollEditableOverrides {
     readonly otherFixedDeductions?: PayrollConceptDto[];
     readonly otherVariableDeductions?: PayrollConceptDto[];
 }
+/**
+ * Snapshot of the employment configuration that affects payroll visualization.
+ * Stored on each PayrollV2 so the frontend can render it without external lookups.
+ */
+export interface PayrollV2EmploymentConfig {
+    readonly employmentType: EmploymentType;
+    readonly compensationType: CompensationType;
+    readonly payrollStampingMode: PayrollStampingMode;
+}
+/**
+ * Embedded nominal payroll data for employees that require CFDI stamping
+ * at minimum wage (casual with IMSS, coverage_only).
+ *
+ * Instead of generating a separate PayrollV2 record, the nominal component
+ * is embedded inside the main payroll record.
+ */
+export interface NominalPayrollData {
+    readonly perceptions: PayrollItem[];
+    readonly deductions: PayrollItem[];
+    readonly otherPayments: PayrollItem[];
+    readonly totals: PayrollV2Totals;
+    readonly cfdi?: PayrollV2Cfdi;
+}
 export interface PayrollV2 {
     readonly collaboratorId?: string;
     readonly employmentId?: string;
@@ -126,7 +150,10 @@ export interface PayrollV2 {
     readonly periodEndDate?: string;
     readonly payrollStatus?: PayrollStatus;
     readonly daysPaid?: number;
-    readonly isNominal?: boolean;
+    /** Snapshot of employment config at generation time */
+    readonly employmentConfig?: PayrollV2EmploymentConfig;
+    /** Embedded nominal payroll (casual+IMSS, coverage_only) */
+    readonly nominalPayroll?: NominalPayrollData;
     readonly perceptions: PayrollItem[];
     readonly deductions: PayrollItem[];
     readonly otherPayments: PayrollItem[];

package/package.json

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