hvp-shared 6.88.0 → 6.90.0

package/dist/constants/global-invoice.enums.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Global Invoice (Factura Global) Enums and Constants
+ *
+ * Used for monthly consolidated invoices issued to RFC XAXX010101000
+ * (Público en General) per Mexican SAT requirements.
+ */
+export declare enum GlobalInvoiceStatus {
+    draft = "draft",
+    stamping = "stamping",
+    stamped = "stamped",
+    failed = "failed",
+    cancelled = "cancelled"
+}
+export declare const GLOBAL_INVOICE_STATUS_LABELS: Record<GlobalInvoiceStatus, string>;
+/**
+ * Fixed receiver data for global invoices (Público en General).
+ * Per SAT CFDI 4.0 specifications.
+ */
+export declare const GLOBAL_INVOICE_RECEIVER: {
+    readonly rfc: "XAXX010101000";
+    readonly name: "PUBLICO EN GENERAL";
+    readonly cfdiUse: "S01";
+    readonly fiscalRegime: "616";
+};
+/**
+ * SAT periodicity codes for the GlobalInformation node in global invoices.
+ * @see SAT Catalog c_Periodicidad
+ */
+export declare const SAT_GLOBAL_PERIODICITY: {
+    readonly daily: "01";
+    readonly weekly: "02";
+    readonly biweekly: "03";
+    readonly monthly: "04";
+    readonly bimonthly: "05";
+};
+export type SATGlobalPeriodicityCode = (typeof SAT_GLOBAL_PERIODICITY)[keyof typeof SAT_GLOBAL_PERIODICITY];
+/**
+ * Fallback SAT product code when section mapping is not found.
+ */
+export declare const DEFAULT_SAT_PRODUCT_CODE = "01010101";

package/dist/constants/global-invoice.enums.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Global Invoice (Factura Global) Enums and Constants
+ *
+ * Used for monthly consolidated invoices issued to RFC XAXX010101000
+ * (Público en General) per Mexican SAT requirements.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SAT_PRODUCT_CODE = exports.SAT_GLOBAL_PERIODICITY = exports.GLOBAL_INVOICE_RECEIVER = exports.GLOBAL_INVOICE_STATUS_LABELS = exports.GlobalInvoiceStatus = void 0;
+// ============================================================================
+// Global Invoice Status
+// ============================================================================
+var GlobalInvoiceStatus;
+(function (GlobalInvoiceStatus) {
+    GlobalInvoiceStatus["draft"] = "draft";
+    GlobalInvoiceStatus["stamping"] = "stamping";
+    GlobalInvoiceStatus["stamped"] = "stamped";
+    GlobalInvoiceStatus["failed"] = "failed";
+    GlobalInvoiceStatus["cancelled"] = "cancelled";
+})(GlobalInvoiceStatus || (exports.GlobalInvoiceStatus = GlobalInvoiceStatus = {}));
+exports.GLOBAL_INVOICE_STATUS_LABELS = {
+    [GlobalInvoiceStatus.draft]: "Borrador",
+    [GlobalInvoiceStatus.stamping]: "Timbrando...",
+    [GlobalInvoiceStatus.stamped]: "Timbrada",
+    [GlobalInvoiceStatus.failed]: "Error",
+    [GlobalInvoiceStatus.cancelled]: "Cancelada",
+};
+// ============================================================================
+// Global Invoice Receiver (SAT standard)
+// ============================================================================
+/**
+ * Fixed receiver data for global invoices (Público en General).
+ * Per SAT CFDI 4.0 specifications.
+ */
+exports.GLOBAL_INVOICE_RECEIVER = {
+    rfc: "XAXX010101000",
+    name: "PUBLICO EN GENERAL",
+    cfdiUse: "S01",
+    fiscalRegime: "616",
+};
+// ============================================================================
+// SAT Global Information - Periodicity (c_Periodicidad)
+// ============================================================================
+/**
+ * SAT periodicity codes for the GlobalInformation node in global invoices.
+ * @see SAT Catalog c_Periodicidad
+ */
+exports.SAT_GLOBAL_PERIODICITY = {
+    daily: "01",
+    weekly: "02",
+    biweekly: "03",
+    monthly: "04",
+    bimonthly: "05",
+};
+/**
+ * Fallback SAT product code when section mapping is not found.
+ */
+exports.DEFAULT_SAT_PRODUCT_CODE = "01010101";

package/dist/constants/global-invoice.enums.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/constants/global-invoice.enums.test.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const global_invoice_enums_1 = require("./global-invoice.enums");
+describe("GlobalInvoiceStatus", () => {
+    it("should have a label for every status value", () => {
+        const statusValues = Object.values(global_invoice_enums_1.GlobalInvoiceStatus);
+        const labelKeys = Object.keys(global_invoice_enums_1.GLOBAL_INVOICE_STATUS_LABELS);
+        expect(labelKeys).toHaveLength(statusValues.length);
+        for (const status of statusValues) {
+            expect(global_invoice_enums_1.GLOBAL_INVOICE_STATUS_LABELS[status]).toBeDefined();
+            expect(typeof global_invoice_enums_1.GLOBAL_INVOICE_STATUS_LABELS[status]).toBe("string");
+            expect(global_invoice_enums_1.GLOBAL_INVOICE_STATUS_LABELS[status].length).toBeGreaterThan(0);
+        }
+    });
+    it("should have expected status values", () => {
+        expect(global_invoice_enums_1.GlobalInvoiceStatus.draft).toBe("draft");
+        expect(global_invoice_enums_1.GlobalInvoiceStatus.stamping).toBe("stamping");
+        expect(global_invoice_enums_1.GlobalInvoiceStatus.stamped).toBe("stamped");
+        expect(global_invoice_enums_1.GlobalInvoiceStatus.failed).toBe("failed");
+        expect(global_invoice_enums_1.GlobalInvoiceStatus.cancelled).toBe("cancelled");
+    });
+});
+describe("GLOBAL_INVOICE_RECEIVER", () => {
+    it("should use SAT standard RFC for público en general", () => {
+        expect(global_invoice_enums_1.GLOBAL_INVOICE_RECEIVER.rfc).toBe("XAXX010101000");
+    });
+    it("should use uppercase name without accents", () => {
+        expect(global_invoice_enums_1.GLOBAL_INVOICE_RECEIVER.name).toBe("PUBLICO EN GENERAL");
+    });
+    it("should use S01 CFDI use (sin efectos fiscales)", () => {
+        expect(global_invoice_enums_1.GLOBAL_INVOICE_RECEIVER.cfdiUse).toBe("S01");
+    });
+    it("should use 616 fiscal regime (sin obligaciones fiscales)", () => {
+        expect(global_invoice_enums_1.GLOBAL_INVOICE_RECEIVER.fiscalRegime).toBe("616");
+    });
+});
+describe("SAT_GLOBAL_PERIODICITY", () => {
+    it("should have monthly as 04", () => {
+        expect(global_invoice_enums_1.SAT_GLOBAL_PERIODICITY.monthly).toBe("04");
+    });
+    it("should have all valid SAT periodicity codes", () => {
+        const values = Object.values(global_invoice_enums_1.SAT_GLOBAL_PERIODICITY);
+        expect(values).toEqual(["01", "02", "03", "04", "05"]);
+    });
+});
+describe("DEFAULT_SAT_PRODUCT_CODE", () => {
+    it("should be 01010101 (No identificado)", () => {
+        expect(global_invoice_enums_1.DEFAULT_SAT_PRODUCT_CODE).toBe("01010101");
+    });
+});

package/dist/constants/index.d.ts

@@ -26,3 +26,4 @@ export * from './documentation.enums';
 export * from './settlement.enums';
 export * from './client-billing.enums';
 export * from './sat-income-invoice';
+export * from './global-invoice.enums';

package/dist/constants/index.js

@@ -42,3 +42,4 @@ __exportStar(require("./documentation.enums"), exports);
 __exportStar(require("./settlement.enums"), exports);
 __exportStar(require("./client-billing.enums"), exports);
 __exportStar(require("./sat-income-invoice"), exports);
+__exportStar(require("./global-invoice.enums"), exports);

package/dist/contracts/global-invoice/index.d.ts

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

package/dist/contracts/global-invoice/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/global-invoice/requests.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Global Invoice API - Request Types
+ *
+ * Request types for the global invoice (Factura Global) endpoints.
+ * Admin-only operations for generating, stamping, and managing
+ * monthly consolidated invoices.
+ *
+ * @see /api/billing/global-invoices/*
+ */
+/**
+ * Generate a global invoice draft for a specific month.
+ *
+ * @example POST /api/billing/global-invoices/generate
+ */
+export interface GenerateGlobalInvoiceRequest {
+    year: number;
+    month: number;
+}
+/**
+ * Cancel a stamped global invoice with SAT motive code.
+ *
+ * @example POST /api/billing/global-invoices/:id/cancel
+ */
+export interface CancelGlobalInvoiceRequest {
+    /** SAT cancellation motive code: "01", "02", "03", "04" */
+    motive: string;
+}

package/dist/contracts/global-invoice/requests.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Global Invoice API - Request Types
+ *
+ * Request types for the global invoice (Factura Global) endpoints.
+ * Admin-only operations for generating, stamping, and managing
+ * monthly consolidated invoices.
+ *
+ * @see /api/billing/global-invoices/*
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/global-invoice/responses.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Global Invoice API - Response Types
+ *
+ * Response types for the global invoice (Factura Global) endpoints.
+ *
+ * @see /api/billing/global-invoices/*
+ */
+import { GlobalInvoiceStatus } from '../../constants/global-invoice.enums';
+/**
+ * Aggregation summary of the global invoice.
+ */
+export interface GlobalInvoiceSummaryResponse {
+    totalSubtotal: number;
+    totalIva: number;
+    totalAmount: number;
+    itemCount: number;
+    excludedInvoicedCount: number;
+    excludedLastDayCount: number;
+    cashPercentageApplied: number;
+    dominantPaymentForm: string;
+    paymentBreakdown: GlobalInvoicePaymentBreakdownItem[];
+}
+export interface GlobalInvoicePaymentBreakdownItem {
+    method: string;
+    satCode: string;
+    total: number;
+}
+/**
+ * Single line item in the global invoice.
+ */
+export interface GlobalInvoiceLineItemResponse {
+    productName: string;
+    section: string;
+    family: string;
+    satProductCode: string;
+    satUnitCode: string;
+    facturamaProductId?: string;
+    quantity: number;
+    unitPrice: number;
+    subtotal: number;
+    discount: number;
+    taxRate: number;
+    taxAmount: number;
+    total: number;
+    originalPaymentMethod: string;
+    isScaledByCashPercentage: boolean;
+}
+/**
+ * Global invoice data for the monthly grid view.
+ * Does NOT include lineItems (too large for list).
+ *
+ * @example GET /api/billing/global-invoices?year=2026
+ */
+export interface GlobalInvoiceListItemResponse {
+    id: string;
+    year: number;
+    month: number;
+    status: GlobalInvoiceStatus;
+    summary: GlobalInvoiceSummaryResponse;
+    cfdiUuid?: string;
+    stampedAt?: string;
+    cancelledAt?: string;
+    errorMessage?: string;
+    attemptCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Full global invoice detail including all line items.
+ *
+ * @example GET /api/billing/global-invoices/:id
+ */
+export interface GlobalInvoiceDetailResponse extends GlobalInvoiceListItemResponse {
+    facturamaId?: string;
+    facturamaSerie?: string;
+    facturamaFolio?: string;
+    cancellationMotive?: string;
+    isCronTriggered: boolean;
+    lastAttemptAt?: string;
+    lineItems: GlobalInvoiceLineItemResponse[];
+}

package/dist/contracts/global-invoice/responses.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Global Invoice API - Response Types
+ *
+ * Response types for the global invoice (Factura Global) endpoints.
+ *
+ * @see /api/billing/global-invoices/*
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/index.d.ts

@@ -13,3 +13,4 @@ export * from './time-off-request';
 export * from './job';
 export * from './inventory-session';
 export * from './client-billing';
+export * from './global-invoice';

package/dist/contracts/index.js

@@ -29,3 +29,4 @@ __exportStar(require("./time-off-request"), exports);
 __exportStar(require("./job"), exports);
 __exportStar(require("./inventory-session"), exports);
 __exportStar(require("./client-billing"), exports);
+__exportStar(require("./global-invoice"), exports);

package/package.json

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