hvp-shared 9.3.0 → 9.5.0

package/dist/contracts/index.d.ts

@@ -21,3 +21,4 @@ export * from './supplier-overlay';
 export * from './external-study';
 export * from './pending-dashboard';
 export * from './document';
+export * from './supplier-orders';

package/dist/contracts/index.js

@@ -37,3 +37,4 @@ __exportStar(require("./supplier-overlay"), exports);
 __exportStar(require("./external-study"), exports);
 __exportStar(require("./pending-dashboard"), exports);
 __exportStar(require("./document"), exports);
+__exportStar(require("./supplier-orders"), exports);

package/dist/contracts/supplier-orders/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Supplier Orders API Contracts
+ */
+export * from './requests';
+export * from './responses';

package/dist/contracts/supplier-orders/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Supplier Orders API Contracts
+ */
+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/supplier-orders/requests.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Supplier Orders API Requests
+ */
+/**
+ * Query filters for fetching supplier order suggestions.
+ *
+ * Used for: GET /api/inventory/supplier-orders
+ *
+ * @example GET /api/inventory/supplier-orders?supplier=DESEGO&months=12
+ */
+export interface SupplierOrderQueryFilters {
+    supplier: string;
+    months?: number;
+}
+/**
+ * Query filters for the supplier list endpoint.
+ *
+ * Used for: GET /api/inventory/supplier-orders/suppliers
+ *
+ * @example GET /api/inventory/supplier-orders/suppliers?months=12
+ */
+export interface SupplierListQueryFilters {
+    months?: number;
+}

package/dist/contracts/supplier-orders/requests.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Supplier Orders API Requests
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/supplier-orders/responses.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Supplier Orders API Responses
+ */
+/**
+ * Stock figures (current / min / optimal) for a single warehouse or aggregated globally.
+ *
+ * Values are expressed in **sale units** (the unit that stock is tracked in:
+ * ml, tablets, individual items). To convert to purchase units (bottle, box,
+ * case), divide by `conversionFactor`.
+ */
+export interface SupplierOrderStockFigures {
+    currentStock: number;
+    minStock: number;
+    optimalStock: number;
+}
+/**
+ * Per-warehouse breakdown of stock for a single product (in sale units).
+ */
+export interface SupplierOrderWarehouseBreakdown extends SupplierOrderStockFigures {
+    warehouse: string;
+}
+/**
+ * Single product line in the supplier order suggestions response.
+ *
+ * Stock and the sale-unit gap are tracked in **sale units**, but the suggested
+ * order quantity is expressed in **purchase units** (bottle, box) — that's how
+ * suppliers actually fulfill orders. The conversion uses `ceil` because you
+ * can't buy 0.9 bottles.
+ *
+ * - `gapSaleUnits` = max(optimalStock - currentStock, 0) (sale units)
+ * - `global.suggested` = ceil(gapSaleUnits / conversionFactor) (purchase units)
+ * - `suggestedSubtotal` = global.suggested × purchaseUnitPrice (MXN, no IVA)
+ */
+export interface SupplierOrderItemResponse {
+    qvetCode: number;
+    name: string;
+    /** Unit in which the supplier sells (e.g. "BOTELLA", "CAJA"). Drives the order quantity. */
+    purchaseUnit: string;
+    /** Unit in which the product is dispensed/sold (e.g. "ML", "PIEZA"). Drives stock figures. */
+    saleUnit: string;
+    /** Sale units contained in one purchase unit (e.g. 100 if a bottle has 100 ml). */
+    conversionFactor: number;
+    /** Price per purchase unit (BI, no IVA). */
+    purchaseUnitPrice: number;
+    /** Price per sale unit (BI, no IVA). Informative — used for granular calculations. */
+    saleUnitPrice: number;
+    /**
+     * Global stock figures across all warehouses, in sale units.
+     * `suggested` here is in **purchase units** (the field used in the order).
+     * `gapSaleUnits` is the raw gap before conversion.
+     */
+    global: SupplierOrderStockFigures & {
+        gapSaleUnits: number;
+        suggested: number;
+    };
+    /** Per-warehouse breakdown (sale units). */
+    byWarehouse: SupplierOrderWarehouseBreakdown[];
+    /** Line cost = global.suggested × purchaseUnitPrice (MXN, no IVA). */
+    suggestedSubtotal: number;
+}
+/**
+ * Aggregate totals for the suggested order across all items.
+ */
+export interface SupplierOrderTotals {
+    subtotalBeforeTax: number;
+    subtotalAfterTax: number;
+}
+/**
+ * Supplier Order Suggestions Response.
+ *
+ * Lists all products purchased from the given supplier within the time window,
+ * with current stock, min/opt thresholds, suggested quantity to order and totals.
+ *
+ * Used for: Supplier Orders dashboard page (manual order planning by supplier).
+ *
+ * @example GET /api/inventory/supplier-orders?supplier=DESEGO&months=12
+ */
+export interface SupplierOrderSuggestionsResponse {
+    supplier: string;
+    months: number;
+    items: SupplierOrderItemResponse[];
+    totals: SupplierOrderTotals;
+}
+/**
+ * Supplier List Response.
+ *
+ * Distinct list of supplier names with at least one purchase within the window.
+ *
+ * Used for: Supplier dropdown on the Supplier Orders dashboard page.
+ *
+ * @example GET /api/inventory/supplier-orders/suppliers?months=12
+ */
+export interface SupplierListResponse {
+    suppliers: string[];
+}

package/dist/contracts/supplier-orders/responses.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Supplier Orders API Responses
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

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