hvp-shared 2.0.1 → 3.0.0

package/dist/constants/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Constants barrel export for hvp-shared
+ */
+export * from './mexican-states';
+export * from './sat-catalogs';

package/dist/constants/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Constants barrel export for hvp-shared
+ */
+__exportStar(require("./mexican-states"), exports);
+__exportStar(require("./sat-catalogs"), exports);

package/dist/constants/mexican-states.d.ts

@@ -1,43 +1,61 @@
 /**
- * Mexican States - Official INEGI codes
- * Used for address validation
+ * Mexican States - SAT Federal Entity Codes (c_Estado)
+ *
+ * Using SAT codes instead of INEGI codes for CFDI compatibility.
+ * These codes are required for electronic invoicing (CFDI) in Mexico.
+ *
+ * @see SAT Catalog: http://omawww.sat.gob.mx/tramitesyservicios/Paginas/anexo_20_version3-3.htm
  */
 export declare const MEXICAN_STATES: {
-    readonly AGS: "Aguascalientes";
-    readonly BC: "Baja California";
+    readonly AGU: "Aguascalientes";
+    readonly BCN: "Baja California";
     readonly BCS: "Baja California Sur";
-    readonly CAMP: "Campeche";
-    readonly CHIS: "Chiapas";
-    readonly CHIH: "Chihuahua";
-    readonly COAH: "Coahuila";
+    readonly CAM: "Campeche";
+    readonly CHP: "Chiapas";
+    readonly CHH: "Chihuahua";
+    readonly COA: "Coahuila de Zaragoza";
     readonly COL: "Colima";
-    readonly CDMX: "Ciudad de México";
-    readonly DGO: "Durango";
-    readonly GTO: "Guanajuato";
+    readonly DIF: "Ciudad de México";
+    readonly DUR: "Durango";
+    readonly GUA: "Guanajuato";
     readonly GRO: "Guerrero";
-    readonly HGO: "Hidalgo";
+    readonly HID: "Hidalgo";
     readonly JAL: "Jalisco";
     readonly MEX: "Estado de México";
-    readonly MICH: "Michoacán";
+    readonly MIC: "Michoacán de Ocampo";
     readonly MOR: "Morelos";
     readonly NAY: "Nayarit";
-    readonly NL: "Nuevo León";
+    readonly NLE: "Nuevo León";
     readonly OAX: "Oaxaca";
     readonly PUE: "Puebla";
-    readonly QRO: "Querétaro";
-    readonly QROO: "Quintana Roo";
+    readonly QUE: "Querétaro";
+    readonly ROO: "Quintana Roo";
     readonly SLP: "San Luis Potosí";
     readonly SIN: "Sinaloa";
     readonly SON: "Sonora";
     readonly TAB: "Tabasco";
-    readonly TAMPS: "Tamaulipas";
-    readonly TLAX: "Tlaxcala";
-    readonly VER: "Veracruz";
+    readonly TAM: "Tamaulipas";
+    readonly TLA: "Tlaxcala";
+    readonly VER: "Veracruz de Ignacio de la Llave";
     readonly YUC: "Yucatán";
     readonly ZAC: "Zacatecas";
 };
 export type MexicanStateCode = keyof typeof MEXICAN_STATES;
+/**
+ * Helper array for frontend dropdowns
+ * Sorted alphabetically by state name for better UX
+ */
 export declare const MEXICAN_STATES_ARRAY: {
     code: MexicanStateCode;
-    name: "Aguascalientes" | "Baja California" | "Baja California Sur" | "Campeche" | "Chiapas" | "Chihuahua" | "Coahuila" | "Colima" | "Ciudad de México" | "Durango" | "Guanajuato" | "Guerrero" | "Hidalgo" | "Jalisco" | "Estado de México" | "Michoacán" | "Morelos" | "Nayarit" | "Nuevo León" | "Oaxaca" | "Puebla" | "Querétaro" | "Quintana Roo" | "San Luis Potosí" | "Sinaloa" | "Sonora" | "Tabasco" | "Tamaulipas" | "Tlaxcala" | "Veracruz" | "Yucatán" | "Zacatecas";
+    name: "Aguascalientes" | "Baja California" | "Baja California Sur" | "Campeche" | "Chiapas" | "Chihuahua" | "Coahuila de Zaragoza" | "Colima" | "Ciudad de México" | "Durango" | "Guanajuato" | "Guerrero" | "Hidalgo" | "Jalisco" | "Estado de México" | "Michoacán de Ocampo" | "Morelos" | "Nayarit" | "Nuevo León" | "Oaxaca" | "Puebla" | "Querétaro" | "Quintana Roo" | "San Luis Potosí" | "Sinaloa" | "Sonora" | "Tabasco" | "Tamaulipas" | "Tlaxcala" | "Veracruz de Ignacio de la Llave" | "Yucatán" | "Zacatecas";
 }[];
+/**
+ * Migration helper: INEGI to SAT code mapping
+ * Use this for database migrations from old INEGI codes to SAT codes
+ */
+export declare const INEGI_TO_SAT_CODE_MAP: Record<string, MexicanStateCode>;
+/**
+ * Convert INEGI code to SAT code
+ * Returns the code unchanged if already a valid SAT code
+ */
+export declare function toSATStateCode(code: string): MexicanStateCode | null;

package/dist/constants/mexican-states.js

@@ -1,46 +1,107 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MEXICAN_STATES_ARRAY = exports.MEXICAN_STATES = void 0;
+exports.INEGI_TO_SAT_CODE_MAP = exports.MEXICAN_STATES_ARRAY = exports.MEXICAN_STATES = void 0;
+exports.toSATStateCode = toSATStateCode;
 /**
- * Mexican States - Official INEGI codes
- * Used for address validation
+ * Mexican States - SAT Federal Entity Codes (c_Estado)
+ *
+ * Using SAT codes instead of INEGI codes for CFDI compatibility.
+ * These codes are required for electronic invoicing (CFDI) in Mexico.
+ *
+ * @see SAT Catalog: http://omawww.sat.gob.mx/tramitesyservicios/Paginas/anexo_20_version3-3.htm
  */
 exports.MEXICAN_STATES = {
-    AGS: 'Aguascalientes',
-    BC: 'Baja California',
+    AGU: 'Aguascalientes',
+    BCN: 'Baja California',
     BCS: 'Baja California Sur',
-    CAMP: 'Campeche',
-    CHIS: 'Chiapas',
-    CHIH: 'Chihuahua',
-    COAH: 'Coahuila',
+    CAM: 'Campeche',
+    CHP: 'Chiapas',
+    CHH: 'Chihuahua',
+    COA: 'Coahuila de Zaragoza',
     COL: 'Colima',
-    CDMX: 'Ciudad de México',
-    DGO: 'Durango',
-    GTO: 'Guanajuato',
+    DIF: 'Ciudad de México', // Distrito Federal in SAT codes
+    DUR: 'Durango',
+    GUA: 'Guanajuato',
     GRO: 'Guerrero',
-    HGO: 'Hidalgo',
+    HID: 'Hidalgo',
     JAL: 'Jalisco',
     MEX: 'Estado de México',
-    MICH: 'Michoacán',
+    MIC: 'Michoacán de Ocampo',
     MOR: 'Morelos',
     NAY: 'Nayarit',
-    NL: 'Nuevo León',
+    NLE: 'Nuevo León',
     OAX: 'Oaxaca',
     PUE: 'Puebla',
-    QRO: 'Querétaro',
-    QROO: 'Quintana Roo',
+    QUE: 'Querétaro',
+    ROO: 'Quintana Roo',
     SLP: 'San Luis Potosí',
     SIN: 'Sinaloa',
     SON: 'Sonora',
     TAB: 'Tabasco',
-    TAMPS: 'Tamaulipas',
-    TLAX: 'Tlaxcala',
-    VER: 'Veracruz',
+    TAM: 'Tamaulipas',
+    TLA: 'Tlaxcala',
+    VER: 'Veracruz de Ignacio de la Llave',
     YUC: 'Yucatán',
-    ZAC: 'Zacatecas'
+    ZAC: 'Zacatecas',
 };
-// Helper array for frontend dropdowns
-exports.MEXICAN_STATES_ARRAY = Object.entries(exports.MEXICAN_STATES).map(([code, name]) => ({
+/**
+ * Helper array for frontend dropdowns
+ * Sorted alphabetically by state name for better UX
+ */
+exports.MEXICAN_STATES_ARRAY = Object.entries(exports.MEXICAN_STATES)
+    .map(([code, name]) => ({
     code: code,
-    name
-}));
+    name,
+}))
+    .sort((a, b) => a.name.localeCompare(b.name, 'es'));
+/**
+ * Migration helper: INEGI to SAT code mapping
+ * Use this for database migrations from old INEGI codes to SAT codes
+ */
+exports.INEGI_TO_SAT_CODE_MAP = {
+    AGS: 'AGU',
+    BC: 'BCN',
+    BCS: 'BCS',
+    CAMP: 'CAM',
+    CHIS: 'CHP',
+    CHIH: 'CHH',
+    COAH: 'COA',
+    COL: 'COL',
+    CDMX: 'DIF',
+    DGO: 'DUR',
+    GTO: 'GUA',
+    GRO: 'GRO',
+    HGO: 'HID',
+    JAL: 'JAL',
+    MEX: 'MEX',
+    MICH: 'MIC',
+    MOR: 'MOR',
+    NAY: 'NAY',
+    NL: 'NLE',
+    OAX: 'OAX',
+    PUE: 'PUE',
+    QRO: 'QUE',
+    QROO: 'ROO',
+    SLP: 'SLP',
+    SIN: 'SIN',
+    SON: 'SON',
+    TAB: 'TAB',
+    TAMPS: 'TAM',
+    TLAX: 'TLA',
+    VER: 'VER',
+    YUC: 'YUC',
+    ZAC: 'ZAC',
+};
+/**
+ * Convert INEGI code to SAT code
+ * Returns the code unchanged if already a valid SAT code
+ */
+function toSATStateCode(code) {
+    const upperCode = code.toUpperCase();
+    // Check if already a valid SAT code
+    if (upperCode in exports.MEXICAN_STATES) {
+        return upperCode;
+    }
+    // Try to convert from INEGI
+    return exports.INEGI_TO_SAT_CODE_MAP[upperCode] || null;
+}

package/dist/constants/sat-catalogs.d.ts

@@ -0,0 +1,183 @@
+/**
+ * SAT Catalog Constants for CFDI Nómina (Payroll)
+ *
+ * Based on SAT catalogs for electronic payroll invoicing (CFDI 4.0)
+ * These codes are required for CFDI compliance in Mexico.
+ *
+ * @see SAT Catalogs: http://omawww.sat.gob.mx/tramitesyservicios/Paginas/anexo_20_version3-3.htm
+ */
+/**
+ * SAT Contract Type codes (c_TipoContrato)
+ */
+export declare const SATContractType: {
+    readonly Permanent: "01";
+    readonly Temporary: "02";
+    readonly SeasonOrCycle: "03";
+    readonly Training: "04";
+    readonly InitialTraining: "05";
+    readonly HomeBased: "06";
+    readonly TrialPeriod: "07";
+    readonly RetiredPayments: "08";
+    readonly Retirement: "09";
+    readonly Other: "99";
+};
+export type SATContractTypeCode = (typeof SATContractType)[keyof typeof SATContractType];
+/**
+ * Contract type labels in Spanish for UI dropdowns
+ */
+export declare const SAT_CONTRACT_TYPE_LABELS: Record<SATContractTypeCode, string>;
+/**
+ * Contract types array for dropdowns
+ */
+export declare const SAT_CONTRACT_TYPES_ARRAY: {
+    code: SATContractTypeCode;
+    label: string;
+}[];
+/**
+ * SAT Regime Type codes (c_TipoRegimen)
+ * Employment regime types for payroll
+ */
+export declare const SATRegimeType: {
+    readonly Salaries: "02";
+    readonly Retirement: "03";
+    readonly Pensions: "04";
+    readonly Assimilated: "05";
+    readonly BoardMembers: "06";
+    readonly Fees: "07";
+    readonly CommissionAgents: "08";
+    readonly AssimilatedOther: "09";
+    readonly Retirement402: "10";
+    readonly Syndicate: "11";
+    readonly Severance: "12";
+    readonly DeathBenefit: "13";
+};
+export type SATRegimeTypeCode = (typeof SATRegimeType)[keyof typeof SATRegimeType];
+/**
+ * Regime type labels in Spanish for UI dropdowns
+ */
+export declare const SAT_REGIME_TYPE_LABELS: Record<SATRegimeTypeCode, string>;
+/**
+ * Regime types array for dropdowns
+ */
+export declare const SAT_REGIME_TYPES_ARRAY: {
+    code: SATRegimeTypeCode;
+    label: string;
+}[];
+/**
+ * SAT Journey/Workday Type codes (c_TipoJornada)
+ */
+export declare const SATJourneyType: {
+    readonly Day: "01";
+    readonly Night: "02";
+    readonly Mixed: "03";
+    readonly ByHour: "04";
+    readonly Reduced: "05";
+    readonly Continuous: "06";
+    readonly Split: "07";
+    readonly ByTurn: "08";
+    readonly Other: "99";
+};
+export type SATJourneyTypeCode = (typeof SATJourneyType)[keyof typeof SATJourneyType];
+/**
+ * Journey type labels in Spanish for UI dropdowns
+ */
+export declare const SAT_JOURNEY_TYPE_LABELS: Record<SATJourneyTypeCode, string>;
+/**
+ * Journey types array for dropdowns
+ */
+export declare const SAT_JOURNEY_TYPES_ARRAY: {
+    code: SATJourneyTypeCode;
+    label: string;
+}[];
+/**
+ * SAT Payment Frequency codes (c_PeriodicidadPago)
+ */
+export declare const SATPaymentFrequency: {
+    readonly Daily: "01";
+    readonly Weekly: "02";
+    readonly Biweekly: "03";
+    readonly Quincenal: "04";
+    readonly Monthly: "05";
+    readonly Bimonthly: "06";
+    readonly ByUnit: "07";
+    readonly ByCommission: "08";
+    readonly ByPrice: "09";
+    readonly Decennial: "10";
+    readonly Other: "99";
+};
+export type SATPaymentFrequencyCode = (typeof SATPaymentFrequency)[keyof typeof SATPaymentFrequency];
+/**
+ * Payment frequency labels in Spanish for UI dropdowns
+ */
+export declare const SAT_PAYMENT_FREQUENCY_LABELS: Record<SATPaymentFrequencyCode, string>;
+/**
+ * Payment frequencies array for dropdowns
+ */
+export declare const SAT_PAYMENT_FREQUENCIES_ARRAY: {
+    code: SATPaymentFrequencyCode;
+    label: string;
+}[];
+/**
+ * SAT Fiscal Regime codes for employees (c_RegimenFiscal)
+ * Subset of fiscal regimes applicable to payroll
+ */
+export declare const SATFiscalRegime: {
+    readonly SalariesAndWages: "605";
+    readonly WithoutFiscalObligations: "616";
+};
+export type SATFiscalRegimeCode = (typeof SATFiscalRegime)[keyof typeof SATFiscalRegime];
+/**
+ * Fiscal regime labels in Spanish for UI dropdowns
+ */
+export declare const SAT_FISCAL_REGIME_LABELS: Record<SATFiscalRegimeCode, string>;
+/**
+ * Fiscal regimes array for dropdowns
+ */
+export declare const SAT_FISCAL_REGIMES_ARRAY: {
+    code: SATFiscalRegimeCode;
+    label: string;
+}[];
+/**
+ * SAT Work Risk Class codes (c_RiesgoPuesto)
+ * IMSS risk classification for the workplace
+ */
+export declare const SATWorkRiskClass: {
+    readonly ClassI: "1";
+    readonly ClassII: "2";
+    readonly ClassIII: "3";
+    readonly ClassIV: "4";
+    readonly ClassV: "5";
+};
+export type SATWorkRiskClassCode = (typeof SATWorkRiskClass)[keyof typeof SATWorkRiskClass];
+/**
+ * Work risk class labels in Spanish for UI dropdowns
+ */
+export declare const SAT_WORK_RISK_CLASS_LABELS: Record<SATWorkRiskClassCode, string>;
+/**
+ * Work risk classes array for dropdowns
+ */
+export declare const SAT_WORK_RISK_CLASSES_ARRAY: {
+    code: SATWorkRiskClassCode;
+    label: string;
+}[];
+/**
+ * SAT Resource Origin codes (c_OrigenRecurso)
+ * Origin of funds for certain payment types
+ */
+export declare const SATResourceOrigin: {
+    readonly IncomePayment: "IP";
+    readonly FederalResources: "IF";
+    readonly MixedIncome: "IM";
+};
+export type SATResourceOriginCode = (typeof SATResourceOrigin)[keyof typeof SATResourceOrigin];
+/**
+ * Resource origin labels in Spanish for UI dropdowns
+ */
+export declare const SAT_RESOURCE_ORIGIN_LABELS: Record<SATResourceOriginCode, string>;
+/**
+ * Resource origins array for dropdowns
+ */
+export declare const SAT_RESOURCE_ORIGINS_ARRAY: {
+    code: SATResourceOriginCode;
+    label: string;
+}[];

package/dist/constants/sat-catalogs.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * SAT Catalog Constants for CFDI Nómina (Payroll)
+ *
+ * Based on SAT catalogs for electronic payroll invoicing (CFDI 4.0)
+ * These codes are required for CFDI compliance in Mexico.
+ *
+ * @see SAT Catalogs: http://omawww.sat.gob.mx/tramitesyservicios/Paginas/anexo_20_version3-3.htm
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SAT_RESOURCE_ORIGINS_ARRAY = exports.SAT_RESOURCE_ORIGIN_LABELS = exports.SATResourceOrigin = exports.SAT_WORK_RISK_CLASSES_ARRAY = exports.SAT_WORK_RISK_CLASS_LABELS = exports.SATWorkRiskClass = exports.SAT_FISCAL_REGIMES_ARRAY = exports.SAT_FISCAL_REGIME_LABELS = exports.SATFiscalRegime = exports.SAT_PAYMENT_FREQUENCIES_ARRAY = exports.SAT_PAYMENT_FREQUENCY_LABELS = exports.SATPaymentFrequency = exports.SAT_JOURNEY_TYPES_ARRAY = exports.SAT_JOURNEY_TYPE_LABELS = exports.SATJourneyType = exports.SAT_REGIME_TYPES_ARRAY = exports.SAT_REGIME_TYPE_LABELS = exports.SATRegimeType = exports.SAT_CONTRACT_TYPES_ARRAY = exports.SAT_CONTRACT_TYPE_LABELS = exports.SATContractType = void 0;
+// ============================================================================
+// Contract Type (c_TipoContrato)
+// ============================================================================
+/**
+ * SAT Contract Type codes (c_TipoContrato)
+ */
+exports.SATContractType = {
+    Permanent: '01',
+    Temporary: '02',
+    SeasonOrCycle: '03',
+    Training: '04',
+    InitialTraining: '05',
+    HomeBased: '06',
+    TrialPeriod: '07',
+    RetiredPayments: '08',
+    Retirement: '09',
+    Other: '99',
+};
+/**
+ * Contract type labels in Spanish for UI dropdowns
+ */
+exports.SAT_CONTRACT_TYPE_LABELS = {
+    '01': 'Contrato de trabajo por tiempo indeterminado',
+    '02': 'Contrato de trabajo para obra determinada',
+    '03': 'Contrato de trabajo por temporada',
+    '04': 'Contrato de trabajo sujeto a prueba',
+    '05': 'Contrato de trabajo con capacitación inicial',
+    '06': 'Modalidad de contratación por pago de hora laborada',
+    '07': 'Modalidad de trabajo por comisión laboral',
+    '08': 'Modalidad de contratación donde no existe relación de trabajo',
+    '09': 'Jubilación, pensión, retiro',
+    '99': 'Otro contrato',
+};
+/**
+ * Contract types array for dropdowns
+ */
+exports.SAT_CONTRACT_TYPES_ARRAY = Object.entries(exports.SAT_CONTRACT_TYPE_LABELS).map(([code, label]) => ({
+    code: code,
+    label,
+}));
+// ============================================================================
+// Regime Type (c_TipoRegimen)
+// ============================================================================
+/**
+ * SAT Regime Type codes (c_TipoRegimen)
+ * Employment regime types for payroll
+ */
+exports.SATRegimeType = {
+    Salaries: '02',
+    Retirement: '03',
+    Pensions: '04',
+    Assimilated: '05',
+    BoardMembers: '06',
+    Fees: '07',
+    CommissionAgents: '08',
+    AssimilatedOther: '09',
+    Retirement402: '10',
+    Syndicate: '11',
+    Severance: '12',
+    DeathBenefit: '13',
+};
+/**
+ * Regime type labels in Spanish for UI dropdowns
+ */
+exports.SAT_REGIME_TYPE_LABELS = {
+    '02': 'Sueldos (Incluye ingresos señalados en la fracción I del artículo 94 de LISR)',
+    '03': 'Jubilados',
+    '04': 'Pensionados',
+    '05': 'Asimilados Miembros Sociedades Cooperativas Producción',
+    '06': 'Asimilados Integrantes Sociedades Asociaciones Civiles',
+    '07': 'Asimilados Honorarios',
+    '08': 'Asimilados comisionistas',
+    '09': 'Asimilados Otros',
+    '10': 'Asimilados obtengan ingresos acciones',
+    '11': 'Asimilados ingresos sindicatos',
+    '12': 'Indemnizaciones o Separaciones',
+    '13': 'Subsidios por incapacidad',
+};
+/**
+ * Regime types array for dropdowns
+ */
+exports.SAT_REGIME_TYPES_ARRAY = Object.entries(exports.SAT_REGIME_TYPE_LABELS).map(([code, label]) => ({
+    code: code,
+    label,
+}));
+// ============================================================================
+// Journey Type (c_TipoJornada)
+// ============================================================================
+/**
+ * SAT Journey/Workday Type codes (c_TipoJornada)
+ */
+exports.SATJourneyType = {
+    Day: '01',
+    Night: '02',
+    Mixed: '03',
+    ByHour: '04',
+    Reduced: '05',
+    Continuous: '06',
+    Split: '07',
+    ByTurn: '08',
+    Other: '99',
+};
+/**
+ * Journey type labels in Spanish for UI dropdowns
+ */
+exports.SAT_JOURNEY_TYPE_LABELS = {
+    '01': 'Diurna',
+    '02': 'Nocturna',
+    '03': 'Mixta',
+    '04': 'Por hora',
+    '05': 'Reducida',
+    '06': 'Continuada',
+    '07': 'Partida',
+    '08': 'Por turnos',
+    '99': 'Otra jornada',
+};
+/**
+ * Journey types array for dropdowns
+ */
+exports.SAT_JOURNEY_TYPES_ARRAY = Object.entries(exports.SAT_JOURNEY_TYPE_LABELS).map(([code, label]) => ({
+    code: code,
+    label,
+}));
+// ============================================================================
+// Payment Frequency (c_PeriodicidadPago)
+// ============================================================================
+/**
+ * SAT Payment Frequency codes (c_PeriodicidadPago)
+ */
+exports.SATPaymentFrequency = {
+    Daily: '01',
+    Weekly: '02',
+    Biweekly: '03',
+    Quincenal: '04',
+    Monthly: '05',
+    Bimonthly: '06',
+    ByUnit: '07',
+    ByCommission: '08',
+    ByPrice: '09',
+    Decennial: '10',
+    Other: '99',
+};
+/**
+ * Payment frequency labels in Spanish for UI dropdowns
+ */
+exports.SAT_PAYMENT_FREQUENCY_LABELS = {
+    '01': 'Diario',
+    '02': 'Semanal',
+    '03': 'Catorcenal',
+    '04': 'Quincenal',
+    '05': 'Mensual',
+    '06': 'Bimestral',
+    '07': 'Unidad obra',
+    '08': 'Comisión',
+    '09': 'Precio alzado',
+    '10': 'Decenal',
+    '99': 'Otra periodicidad',
+};
+/**
+ * Payment frequencies array for dropdowns
+ */
+exports.SAT_PAYMENT_FREQUENCIES_ARRAY = Object.entries(exports.SAT_PAYMENT_FREQUENCY_LABELS).map(([code, label]) => ({
+    code: code,
+    label,
+}));
+// ============================================================================
+// Fiscal Regime for Employees (c_RegimenFiscal)
+// ============================================================================
+/**
+ * SAT Fiscal Regime codes for employees (c_RegimenFiscal)
+ * Subset of fiscal regimes applicable to payroll
+ */
+exports.SATFiscalRegime = {
+    SalariesAndWages: '605',
+    WithoutFiscalObligations: '616',
+};
+/**
+ * Fiscal regime labels in Spanish for UI dropdowns
+ */
+exports.SAT_FISCAL_REGIME_LABELS = {
+    '605': 'Sueldos y Salarios e Ingresos Asimilados a Salarios',
+    '616': 'Sin obligaciones fiscales',
+};
+/**
+ * Fiscal regimes array for dropdowns
+ */
+exports.SAT_FISCAL_REGIMES_ARRAY = Object.entries(exports.SAT_FISCAL_REGIME_LABELS).map(([code, label]) => ({
+    code: code,
+    label,
+}));
+// ============================================================================
+// Work Risk Class (c_RiesgoPuesto)
+// ============================================================================
+/**
+ * SAT Work Risk Class codes (c_RiesgoPuesto)
+ * IMSS risk classification for the workplace
+ */
+exports.SATWorkRiskClass = {
+    ClassI: '1',
+    ClassII: '2',
+    ClassIII: '3',
+    ClassIV: '4',
+    ClassV: '5',
+};
+/**
+ * Work risk class labels in Spanish for UI dropdowns
+ */
+exports.SAT_WORK_RISK_CLASS_LABELS = {
+    '1': 'Clase I - Riesgo ordinario',
+    '2': 'Clase II - Riesgo bajo',
+    '3': 'Clase III - Riesgo medio',
+    '4': 'Clase IV - Riesgo alto',
+    '5': 'Clase V - Riesgo máximo',
+};
+/**
+ * Work risk classes array for dropdowns
+ */
+exports.SAT_WORK_RISK_CLASSES_ARRAY = Object.entries(exports.SAT_WORK_RISK_CLASS_LABELS).map(([code, label]) => ({
+    code: code,
+    label,
+}));
+// ============================================================================
+// Resource Origin (c_OrigenRecurso)
+// ============================================================================
+/**
+ * SAT Resource Origin codes (c_OrigenRecurso)
+ * Origin of funds for certain payment types
+ */
+exports.SATResourceOrigin = {
+    IncomePayment: 'IP',
+    FederalResources: 'IF',
+    MixedIncome: 'IM',
+};
+/**
+ * Resource origin labels in Spanish for UI dropdowns
+ */
+exports.SAT_RESOURCE_ORIGIN_LABELS = {
+    IP: 'Ingresos propios',
+    IF: 'Ingresos federales',
+    IM: 'Ingresos mixtos',
+};
+/**
+ * Resource origins array for dropdowns
+ */
+exports.SAT_RESOURCE_ORIGINS_ARRAY = Object.entries(exports.SAT_RESOURCE_ORIGIN_LABELS).map(([code, label]) => ({
+    code: code,
+    label,
+}));

package/dist/index.d.ts

@@ -5,3 +5,4 @@
 export * from './types';
 export * from './constants';
 export * from './validation';
+export { debugLog } from './utils/debug-logger';

package/dist/index.js

@@ -18,6 +18,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.debugLog = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./constants"), exports);
 __exportStar(require("./validation"), exports);
+var debug_logger_1 = require("./utils/debug-logger");
+Object.defineProperty(exports, "debugLog", { enumerable: true, get: function () { return debug_logger_1.debugLog; } });

package/dist/utils/debug-logger.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Debug Logger for Shared Code
+ *
+ * Simple console.log wrapper - shared code is pure, no persistence needed.
+ * For full debugging with persistence, use the debugLog from backend or frontend.
+ *
+ * Enable in Node: DEBUG_LOG_ENABLED=true
+ * Enable in Browser: localStorage.setItem('DEBUG_LOG_ENABLED', 'true')
+ *
+ * @example
+ * import { debugLog } from 'hvp-shared';
+ *
+ * function validateRFC(value: string) {
+ *   debugLog('validateRFC', { value }, 'input');
+ *   // ... validation logic
+ * }
+ */
+/**
+ * Log debug data (sync, console.log only)
+ */
+export declare function debugLog(functionName: string, data: unknown, context?: string): void;

package/dist/utils/debug-logger.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Debug Logger for Shared Code
+ *
+ * Simple console.log wrapper - shared code is pure, no persistence needed.
+ * For full debugging with persistence, use the debugLog from backend or frontend.
+ *
+ * Enable in Node: DEBUG_LOG_ENABLED=true
+ * Enable in Browser: localStorage.setItem('DEBUG_LOG_ENABLED', 'true')
+ *
+ * @example
+ * import { debugLog } from 'hvp-shared';
+ *
+ * function validateRFC(value: string) {
+ *   debugLog('validateRFC', { value }, 'input');
+ *   // ... validation logic
+ * }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debugLog = debugLog;
+/**
+ * Check if debug logging is enabled
+ */
+function isEnabled() {
+    // Node.js
+    if (typeof process !== 'undefined' && process.env) {
+        return process.env.DEBUG_LOG_ENABLED === 'true';
+    }
+    // Browser
+    if (typeof localStorage !== 'undefined') {
+        try {
+            return localStorage.getItem('DEBUG_LOG_ENABLED') === 'true';
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * Log debug data (sync, console.log only)
+ */
+function debugLog(functionName, data, context = 'default') {
+    if (!isEnabled())
+        return;
+    const time = new Date().toISOString().slice(11, 23);
+    console.log(`[DEBUG ${time}] ${functionName} (${context})`, data);
+}

package/package.json

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