hvp-shared 6.84.0 → 6.85.0

package/dist/constants/client-billing.enums.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Client Billing Enums
+ *
+ * Enums for the client-facing billing portal where pet owners
+ * request CFDI income invoices for their veterinary visits.
+ */
+/**
+ * Status of a client invoice request through the processing pipeline.
+ */
+export declare enum ClientInvoiceStatus {
+    /** Request created, not yet processing */
+    pending = "pending",
+    /** Background job is running (lookup, CFDI build, stamping) */
+    processing = "processing",
+    /** CFDI stamped successfully, PDF/XML available */
+    stamped = "stamped",
+    /** Processing failed (see errorMessage) */
+    failed = "failed"
+}
+/**
+ * All ClientInvoiceStatus values as array (for dropdowns/filters)
+ */
+export declare const CLIENT_INVOICE_STATUS_VALUES: ClientInvoiceStatus[];
+/**
+ * ClientInvoiceStatus labels in Spanish (for UI)
+ */
+export declare const CLIENT_INVOICE_STATUS_LABELS: Record<ClientInvoiceStatus, string>;

package/dist/constants/client-billing.enums.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Client Billing Enums
+ *
+ * Enums for the client-facing billing portal where pet owners
+ * request CFDI income invoices for their veterinary visits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIENT_INVOICE_STATUS_LABELS = exports.CLIENT_INVOICE_STATUS_VALUES = exports.ClientInvoiceStatus = void 0;
+/**
+ * Status of a client invoice request through the processing pipeline.
+ */
+var ClientInvoiceStatus;
+(function (ClientInvoiceStatus) {
+    /** Request created, not yet processing */
+    ClientInvoiceStatus["pending"] = "pending";
+    /** Background job is running (lookup, CFDI build, stamping) */
+    ClientInvoiceStatus["processing"] = "processing";
+    /** CFDI stamped successfully, PDF/XML available */
+    ClientInvoiceStatus["stamped"] = "stamped";
+    /** Processing failed (see errorMessage) */
+    ClientInvoiceStatus["failed"] = "failed";
+})(ClientInvoiceStatus || (exports.ClientInvoiceStatus = ClientInvoiceStatus = {}));
+/**
+ * All ClientInvoiceStatus values as array (for dropdowns/filters)
+ */
+exports.CLIENT_INVOICE_STATUS_VALUES = Object.values(ClientInvoiceStatus);
+/**
+ * ClientInvoiceStatus labels in Spanish (for UI)
+ */
+exports.CLIENT_INVOICE_STATUS_LABELS = {
+    [ClientInvoiceStatus.pending]: "Pendiente",
+    [ClientInvoiceStatus.processing]: "Procesando",
+    [ClientInvoiceStatus.stamped]: "Facturada",
+    [ClientInvoiceStatus.failed]: "Error",
+};

package/dist/constants/index.d.ts

@@ -24,3 +24,5 @@ export * from './payroll-features.constants';
 export * from './inventory-session.enums';
 export * from './documentation.enums';
 export * from './settlement.enums';
+export * from './client-billing.enums';
+export * from './sat-income-invoice';

package/dist/constants/index.js

@@ -40,3 +40,5 @@ __exportStar(require("./payroll-features.constants"), exports);
 __exportStar(require("./inventory-session.enums"), exports);
 __exportStar(require("./documentation.enums"), exports);
 __exportStar(require("./settlement.enums"), exports);
+__exportStar(require("./client-billing.enums"), exports);
+__exportStar(require("./sat-income-invoice"), exports);

package/dist/constants/sat-income-invoice.d.ts

@@ -0,0 +1,95 @@
+/**
+ * SAT Catalog Constants for CFDI Income Invoices (Facturas de Ingreso)
+ *
+ * Based on SAT catalogs for electronic invoicing (CFDI 4.0).
+ * These are specific to income invoices — payroll catalogs are in sat-catalogs.ts.
+ *
+ * @see SAT Catalogs: http://omawww.sat.gob.mx/tramitesyservicios/Paginas/anexo_20_version3-3.htm
+ */
+/**
+ * SAT Fiscal Regime codes applicable to invoice receivers (clients).
+ * Broader set than payroll (which only uses 605/616).
+ */
+export declare const SATClientFiscalRegime: {
+    readonly GeneralLaw: "601";
+    readonly LegalPersonsNonProfit: "603";
+    readonly SalariesAndWages: "605";
+    readonly LeaseIncome: "606";
+    readonly TaxIncorporation: "612";
+    readonly WithoutFiscalObligations: "616";
+    readonly BusinessActivityIncome: "621";
+    readonly SimplifiedTrust: "625";
+    readonly SimplifiedTrustLegal: "626";
+};
+export type SATClientFiscalRegimeCode = (typeof SATClientFiscalRegime)[keyof typeof SATClientFiscalRegime];
+/**
+ * Fiscal regime labels in Spanish for client portal dropdowns
+ */
+export declare const SAT_CLIENT_FISCAL_REGIME_LABELS: Record<SATClientFiscalRegimeCode, string>;
+/**
+ * Fiscal regimes array for dropdowns
+ */
+export declare const SAT_CLIENT_FISCAL_REGIMES_ARRAY: {
+    code: SATClientFiscalRegimeCode;
+    label: string;
+}[];
+/**
+ * SAT CFDI Use codes applicable to income invoices for veterinary services/products.
+ * Subset of the full catalog — only codes relevant to HVP clients.
+ */
+export declare const SATCfdiUse: {
+    readonly GeneralExpenses: "G03";
+    readonly MedicalExpenses: "D01";
+    readonly NoFiscalEffect: "S01";
+    readonly PeriodicPayments: "CP01";
+    readonly Acquisitions: "G01";
+};
+export type SATCfdiUseCode = (typeof SATCfdiUse)[keyof typeof SATCfdiUse];
+/**
+ * CFDI Use labels in Spanish for client portal dropdowns
+ */
+export declare const SAT_CFDI_USE_LABELS: Record<SATCfdiUseCode, string>;
+/**
+ * CFDI Use array for dropdowns
+ */
+export declare const SAT_CFDI_USE_ARRAY: {
+    code: SATCfdiUseCode;
+    label: string;
+}[];
+/**
+ * SAT Payment Form codes.
+ * Maps from QVET payment methods to SAT-compliant codes.
+ */
+export declare const SATPaymentForm: {
+    readonly Cash: "01";
+    readonly NominalCheck: "02";
+    readonly ElectronicTransfer: "03";
+    readonly CreditCard: "04";
+    readonly ElectronicWallet: "05";
+    readonly ElectronicMoney: "06";
+    readonly DigitalVouchers: "08";
+    readonly DebitCard: "28";
+    readonly ServiceCard: "29";
+    readonly ToBeDefined: "99";
+};
+export type SATPaymentFormCode = (typeof SATPaymentForm)[keyof typeof SATPaymentForm];
+/**
+ * Payment form labels in Spanish
+ */
+export declare const SAT_PAYMENT_FORM_LABELS: Record<SATPaymentFormCode, string>;
+/**
+ * Maps QVET payment method strings to SAT payment form codes.
+ * QVET uses Spanish descriptors; SAT uses numeric codes.
+ *
+ * TODO: Validate actual QVET payment method strings from qvet_collection_details data.
+ */
+export declare const QVET_PAYMENT_METHOD_TO_SAT: Record<string, SATPaymentFormCode>;
+/**
+ * Default SAT payment form when QVET payment method is unknown
+ */
+export declare const DEFAULT_SAT_PAYMENT_FORM: SATPaymentFormCode;
+/**
+ * Resolves a QVET payment method string to SAT payment form code.
+ * Falls back to "99" (Por definir) if unknown.
+ */
+export declare function resolvePaymentForm(qvetPaymentMethod: string): SATPaymentFormCode;

package/dist/constants/sat-income-invoice.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * SAT Catalog Constants for CFDI Income Invoices (Facturas de Ingreso)
+ *
+ * Based on SAT catalogs for electronic invoicing (CFDI 4.0).
+ * These are specific to income invoices — payroll catalogs are in sat-catalogs.ts.
+ *
+ * @see SAT Catalogs: http://omawww.sat.gob.mx/tramitesyservicios/Paginas/anexo_20_version3-3.htm
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SAT_PAYMENT_FORM = exports.QVET_PAYMENT_METHOD_TO_SAT = exports.SAT_PAYMENT_FORM_LABELS = exports.SATPaymentForm = exports.SAT_CFDI_USE_ARRAY = exports.SAT_CFDI_USE_LABELS = exports.SATCfdiUse = exports.SAT_CLIENT_FISCAL_REGIMES_ARRAY = exports.SAT_CLIENT_FISCAL_REGIME_LABELS = exports.SATClientFiscalRegime = void 0;
+exports.resolvePaymentForm = resolvePaymentForm;
+// ============================================================================
+// Fiscal Regime - Client (c_RegimenFiscal)
+// ============================================================================
+/**
+ * SAT Fiscal Regime codes applicable to invoice receivers (clients).
+ * Broader set than payroll (which only uses 605/616).
+ */
+exports.SATClientFiscalRegime = {
+    GeneralLaw: "601",
+    LegalPersonsNonProfit: "603",
+    SalariesAndWages: "605",
+    LeaseIncome: "606",
+    TaxIncorporation: "612", // RIF (being phased out)
+    WithoutFiscalObligations: "616",
+    BusinessActivityIncome: "621",
+    SimplifiedTrust: "625", // RESICO Personas Físicas
+    SimplifiedTrustLegal: "626", // RESICO Personas Morales
+};
+/**
+ * Fiscal regime labels in Spanish for client portal dropdowns
+ */
+exports.SAT_CLIENT_FISCAL_REGIME_LABELS = {
+    "601": "General de Ley Personas Morales",
+    "603": "Personas Morales con Fines no Lucrativos",
+    "605": "Sueldos y Salarios e Ingresos Asimilados a Salarios",
+    "606": "Arrendamiento",
+    "612": "Personas Físicas con Actividades Empresariales y Profesionales",
+    "616": "Sin obligaciones fiscales",
+    "621": "Incorporación Fiscal",
+    "625": "Régimen Simplificado de Confianza (Persona Física)",
+    "626": "Régimen Simplificado de Confianza (Persona Moral)",
+};
+/**
+ * Fiscal regimes array for dropdowns
+ */
+exports.SAT_CLIENT_FISCAL_REGIMES_ARRAY = Object.entries(exports.SAT_CLIENT_FISCAL_REGIME_LABELS).map(([code, label]) => ({
+    code: code,
+    label: `${code} - ${label}`,
+}));
+// ============================================================================
+// CFDI Use (c_UsoCFDI)
+// ============================================================================
+/**
+ * SAT CFDI Use codes applicable to income invoices for veterinary services/products.
+ * Subset of the full catalog — only codes relevant to HVP clients.
+ */
+exports.SATCfdiUse = {
+    GeneralExpenses: "G03",
+    MedicalExpenses: "D01",
+    NoFiscalEffect: "S01",
+    PeriodicPayments: "CP01",
+    Acquisitions: "G01",
+};
+/**
+ * CFDI Use labels in Spanish for client portal dropdowns
+ */
+exports.SAT_CFDI_USE_LABELS = {
+    G03: "Gastos en general",
+    D01: "Honorarios médicos, dentales y gastos hospitalarios",
+    S01: "Sin efectos fiscales",
+    CP01: "Pagos",
+    G01: "Adquisición de mercancías",
+};
+/**
+ * CFDI Use array for dropdowns
+ */
+exports.SAT_CFDI_USE_ARRAY = Object.entries(exports.SAT_CFDI_USE_LABELS).map(([code, label]) => ({
+    code: code,
+    label: `${code} - ${label}`,
+}));
+// ============================================================================
+// Payment Form (c_FormaPago)
+// ============================================================================
+/**
+ * SAT Payment Form codes.
+ * Maps from QVET payment methods to SAT-compliant codes.
+ */
+exports.SATPaymentForm = {
+    Cash: "01",
+    NominalCheck: "02",
+    ElectronicTransfer: "03",
+    CreditCard: "04",
+    ElectronicWallet: "05",
+    ElectronicMoney: "06",
+    DigitalVouchers: "08",
+    DebitCard: "28",
+    ServiceCard: "29",
+    ToBeDefined: "99",
+};
+/**
+ * Payment form labels in Spanish
+ */
+exports.SAT_PAYMENT_FORM_LABELS = {
+    "01": "Efectivo",
+    "02": "Cheque nominativo",
+    "03": "Transferencia electrónica de fondos",
+    "04": "Tarjeta de crédito",
+    "05": "Monedero electrónico",
+    "06": "Dinero electrónico",
+    "08": "Vales de despensa",
+    "28": "Tarjeta de débito",
+    "29": "Tarjeta de servicios",
+    "99": "Por definir",
+};
+/**
+ * Maps QVET payment method strings to SAT payment form codes.
+ * QVET uses Spanish descriptors; SAT uses numeric codes.
+ *
+ * TODO: Validate actual QVET payment method strings from qvet_collection_details data.
+ */
+exports.QVET_PAYMENT_METHOD_TO_SAT = {
+    Efectivo: "01",
+    "Tarjeta de Crédito": "04",
+    "Tarjeta de Débito": "28",
+    Transferencia: "03",
+    "Tarjeta crédito": "04",
+    "Tarjeta débito": "28",
+};
+/**
+ * Default SAT payment form when QVET payment method is unknown
+ */
+exports.DEFAULT_SAT_PAYMENT_FORM = "99";
+/**
+ * Resolves a QVET payment method string to SAT payment form code.
+ * Falls back to "99" (Por definir) if unknown.
+ */
+function resolvePaymentForm(qvetPaymentMethod) {
+    if (!qvetPaymentMethod)
+        return exports.DEFAULT_SAT_PAYMENT_FORM;
+    const normalized = qvetPaymentMethod.trim();
+    // Direct match
+    if (exports.QVET_PAYMENT_METHOD_TO_SAT[normalized]) {
+        return exports.QVET_PAYMENT_METHOD_TO_SAT[normalized];
+    }
+    // Case-insensitive partial match
+    const lc = normalized.toLowerCase();
+    if (lc.includes("efectivo"))
+        return "01";
+    if (lc.includes("crédito") || lc.includes("credito"))
+        return "04";
+    if (lc.includes("débito") || lc.includes("debito"))
+        return "28";
+    if (lc.includes("transferencia"))
+        return "03";
+    if (lc.includes("cheque"))
+        return "02";
+    return exports.DEFAULT_SAT_PAYMENT_FORM;
+}

package/dist/contracts/client-billing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './requests';
+export * from './responses';

package/dist/contracts/client-billing/index.js

@@ -0,0 +1,18 @@
+"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 });
+__exportStar(require("./requests"), exports);
+__exportStar(require("./responses"), exports);

package/dist/contracts/client-billing/requests.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Client Billing API - Request Types
+ *
+ * Request types for the client-facing billing portal endpoints.
+ *
+ * @see /api/client-billing/*
+ */
+/**
+ * Register a new client account.
+ *
+ * @example POST /api/client-billing/auth/register
+ */
+export interface RegisterClientRequest {
+    email: string;
+    password: string;
+    name: string;
+}
+/**
+ * Log in with email and password.
+ *
+ * @example POST /api/client-billing/auth/login
+ */
+export interface LoginClientRequest {
+    email: string;
+    password: string;
+}
+/**
+ * Update client fiscal profile data.
+ * All fields optional — only provided fields are updated.
+ *
+ * @example PATCH /api/client-billing/profile
+ */
+export interface UpdateClientProfileRequest {
+    name?: string;
+    rfc?: string;
+    businessName?: string;
+    fiscalRegime?: string;
+    postalCode?: string;
+    cfdiUse?: string;
+}
+/**
+ * Look up a ticket by albarán number and amount for verification.
+ * Amount is required as security measure (prevents facturing others' tickets).
+ *
+ * @example POST /api/client-billing/invoices/lookup
+ */
+export interface LookupTicketRequest {
+    deliveryNoteNumber: number;
+    amount: number;
+}
+/**
+ * Request an invoice to be generated for a ticket.
+ * Uses fiscal data from the client's saved profile.
+ *
+ * @example POST /api/client-billing/invoices
+ */
+export interface CreateClientInvoiceRequest {
+    deliveryNoteNumber: number;
+    amount: number;
+}

package/dist/contracts/client-billing/requests.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Client Billing API - Request Types
+ *
+ * Request types for the client-facing billing portal endpoints.
+ *
+ * @see /api/client-billing/*
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/client-billing/responses.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Client Billing API - Response Types
+ *
+ * Response types for the client-facing billing portal endpoints.
+ *
+ * @see /api/client-billing/*
+ */
+import { ClientInvoiceStatus } from '../../constants/client-billing.enums';
+/**
+ * Client account data returned after login/register.
+ *
+ * @example POST /api/client-billing/auth/login
+ */
+export interface ClientAuthResponse {
+    token: string;
+    client: ClientProfileResponse;
+}
+/**
+ * Client profile with fiscal data.
+ *
+ * @example GET /api/client-billing/profile
+ */
+export interface ClientProfileResponse {
+    id: string;
+    email: string;
+    name: string;
+    rfc?: string;
+    businessName?: string;
+    fiscalRegime?: string;
+    postalCode?: string;
+    cfdiUse?: string;
+    isProfileComplete: boolean;
+    createdAt: string;
+}
+/**
+ * Single line item within a ticket lookup or invoice.
+ */
+export interface InvoiceLineItemResponse {
+    productName: string;
+    quantity: number;
+    unitPrice: number;
+    discount: number;
+    taxRate: number;
+    taxAmount: number;
+    total: number;
+    satProductCode?: string;
+    satUnitCode?: string;
+}
+/**
+ * Result of looking up a ticket by albarán number.
+ * Returned before the client confirms invoice creation.
+ *
+ * @example POST /api/client-billing/invoices/lookup
+ */
+export interface TicketLookupResponse {
+    deliveryNoteNumber: number;
+    date: string;
+    customerName: string;
+    subtotal: number;
+    taxTotal: number;
+    total: number;
+    paymentMethod: string;
+    lineItems: InvoiceLineItemResponse[];
+}
+/**
+ * Client invoice summary for list views.
+ *
+ * @example GET /api/client-billing/invoices
+ */
+export interface ClientInvoiceListItemResponse {
+    id: string;
+    deliveryNoteNumber: number;
+    date: string;
+    total: number;
+    status: ClientInvoiceStatus;
+    cfdiUuid?: string;
+    createdAt: string;
+}
+/**
+ * Full client invoice detail.
+ *
+ * @example GET /api/client-billing/invoices/:id
+ */
+export interface ClientInvoiceDetailResponse {
+    id: string;
+    deliveryNoteNumber: number;
+    date: string;
+    customerName: string;
+    subtotal: number;
+    taxTotal: number;
+    total: number;
+    paymentMethod: string;
+    status: ClientInvoiceStatus;
+    cfdiUuid?: string;
+    facturamaId?: string;
+    errorMessage?: string;
+    lineItems: InvoiceLineItemResponse[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Processing status for polling during invoice generation.
+ *
+ * @example GET /api/client-billing/invoices/:id/status
+ */
+export interface ClientInvoiceStatusResponse {
+    id: string;
+    status: ClientInvoiceStatus;
+    progress?: number;
+    message?: string;
+    errorMessage?: string;
+}

package/dist/contracts/client-billing/responses.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Client Billing API - Response Types
+ *
+ * Response types for the client-facing billing portal endpoints.
+ *
+ * @see /api/client-billing/*
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/index.d.ts

@@ -12,3 +12,4 @@ export * from './cash-reconciliation';
 export * from './time-off-request';
 export * from './job';
 export * from './inventory-session';
+export * from './client-billing';

package/dist/contracts/index.js

@@ -28,3 +28,4 @@ __exportStar(require("./cash-reconciliation"), exports);
 __exportStar(require("./time-off-request"), exports);
 __exportStar(require("./job"), exports);
 __exportStar(require("./inventory-session"), exports);
+__exportStar(require("./client-billing"), exports);

package/package.json

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