sinfactura-types 1.10.263 → 1.10.264

package/dist/product.d.ts

@@ -330,13 +330,20 @@ declare global {
             quantity: number;
             cost: number;
         }[];
-        sales?: {
-            stockId: string;
-            orderId: string;
-            fullName: string;
-            quantity: number;
-            price: number;
-        }[];
+        /**
+         * ⚠️ **Two shapes, chosen by `statsWindow`, and this field declares only
+         * the first.** `products/_get.ts` returns `ProductSalesLineRow[]` when
+         * `statsWindow` is the default, and `ProductSalesRollupRow[]` — a
+         * per-month aggregate — for any other window.
+         *
+         * The declared type is deliberately NOT a union: widening it would break
+         * every consumer that reads `sales[].orderId` without narrowing first,
+         * and this package publishes patch versions, so a breaking type change
+         * would arrive as one. A consumer reading a non-default window should
+         * assert to `ProductSalesRollupRow[]` — a published type it can name —
+         * rather than restating the shape locally.
+         */
+        sales?: ProductSalesLineRow[];
         totalIncome?: number;
         totalSales?: number;
         zone?: string;
@@ -401,6 +408,46 @@ declare global {
             evidence?: string;
         }[];
     }
+    /**
+     * One sale LINE on a product's stats — the shape `Product.sales` carries when
+     * `statsWindow` is the default. One entry per movement, not per period.
+     */
+    interface ProductSalesLineRow {
+        stockId: string;
+        orderId: string;
+        fullName: string;
+        quantity: number;
+        price: number;
+    }
+    /**
+     * One MONTH of a product's stats — the shape `Product.sales` carries for any
+     * non-default `statsWindow`. Built by `products/_get.ts`, which folds the
+     * line rows into per-period buckets.
+     *
+     * ⚠️ `orders`, `serviceOrders` and `adjustments` are three DISJOINT counts,
+     * not a total and two of its parts. A movement lands in exactly one, and the
+     * split is the point: a service order and a manual stock adjustment are both
+     * real movements that must stay visible, and neither is an order. Summing
+     * them to get "total movements" is fine; reading `orders` as that total is
+     * the misread this split exists to prevent.
+     */
+    interface ProductSalesRollupRow {
+        /** Period start, as the handler's own bucket key. */
+        date: number;
+        /** Units moved in the period, across all three counts below. */
+        quantity: number;
+        /** Movements from a customer order. */
+        orders: number;
+        /** Movements from a service order — real, and not an order. */
+        serviceOrders: number;
+        /**
+         * Movements from a manual stock adjustment (`products/_postStockAdjust.ts`).
+         * Counted under its own key for the same reason `serviceOrders` is: the
+         * movement is real and must stay visible, but it is not an order and must
+         * not be counted as one.
+         */
+        adjustments: number;
+    }
     interface ProductBarcode {
         value: string;
         type: 'EAN13' | 'EAN8' | 'UPC' | 'GTIN14' | 'CODE128' | 'internal';

package/dist/report.d.ts

@@ -92,9 +92,28 @@ declare global {
         CBTE_NUMERO: number;
         RAZON_SOCIAL: string;
         CUIT: string;
+        /**
+         * Sum of EVERY declared alícuota base, so `NETO` reconciles with `TOTAL`.
+         * ⚠️ NOT `NETO10 + NETO21` — a voucher on one of the four rates the row
+         * does not persist would be under-reported by that sum. The two named
+         * columns stay as their own explicit columns beside this one; do not
+         * derive or cross-check `NETO` from them.
+         */
         NETO: number;
         NETO10: number;
         NETO21: number;
+        /**
+         * The declared perception, as its own column. `0` on every row that
+         * declared nothing and on every row predating the field, so it is
+         * required rather than optional — `reports/_invoices.ts` emits it
+         * unconditionally.
+         *
+         * ⚠️ Without this column `NETO` and `TOTAL` stop reconciling the moment a
+         * voucher carries a perception: it sits INSIDE `TOTAL` (`ImpTotal` is
+         * derived from `ImpTrib`) and in none of the columns beside it, so the
+         * sheet showed a gap it gave the reader no way to name.
+         */
+        PERCEPCIONES: number;
         TOTAL: number;
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sinfactura-types",
-	"version": "1.10.263",
+	"version": "1.10.264",
 	"description": "Shared wire and entity contracts for the SINFACTURA platform.",
 	"type": "module",
 	"main": "dist/index.js",