sinfactura-types 1.10.320 → 1.10.321

package/dist/order.d.ts

@@ -102,6 +102,38 @@ declare global {
         /** userId of the operator who rang it. */
         recordedBy?: string;
     }
+    /**
+     * One line of an ORDER — a cart line plus the ledger stamp only an order has.
+     *
+     * Separate from {@link CartLine} deliberately: a cart has no `SALE#` ledger
+     * row, so a stamp declared there would be a field no cart writer can ever
+     * populate and every cart reader would have to explain away. `Order.items`
+     * stays assignable from a cart's own lines, because every added field is
+     * optional and orders copy cart lines verbatim.
+     */
+    interface OrderLine extends CartLine {
+        /**
+         * The stamp THIS line's `SALE#` ledger row is keyed by —
+         * `${productId}-${saleTs}`.
+         *
+         * ⚠️ **Server-owned, always.** The edit request schema is `.strict()` and
+         * accepts only `productId`/`quantity`/`price`, so a client cannot supply
+         * one; the server carries it forward from the stored line, or allocates a
+         * fresh one when it mints a replacement row. A writer that echoed a
+         * client value here would let a caller re-point another order's ledger row.
+         *
+         * ⚠️ **Lines of the SAME product share one value.** The ledger SK carries
+         * no line index, so a product spanning several lines owns exactly one row
+         * and every one of those lines names it.
+         *
+         * ⚠️ OPTIONAL PERMANENTLY. Absent means "resolve through the ORDER row's
+         * own `saleTs`, then its `createdAt`" — which is every line written before
+         * per-line stamping, forward-only, never backfilled. Resolution belongs to
+         * ONE helper (`saleLedgerTsForLine`); reading this field directly
+         * addresses nothing for the whole legacy population.
+         */
+        saleTs?: number;
+    }
     interface Order {
         storeId: string;
         orderId: string;
@@ -669,7 +701,7 @@ declare global {
             source?: 'auto' | 'manual';
         };
         disabled?: boolean;
-        items: Partial<CartLine>[];
+        items: Partial<OrderLine>[];
         rating?: number;
         comment?: string;
         surveyDate?: number;

package/dist/stock.d.ts

@@ -49,7 +49,26 @@ declare global {
          * movement is UNVALUED, never that it was free.
          */
         cost?: number;
+        /**
+         * The movement has been RETRACTED and must not count toward on-hand.
+         *
+         * ⚠️ Supersedes the legacy `notEvaluate` spelling, which no writer ever
+         * used. This one HAS writers: every order-lifecycle reversal stamps it —
+         * a cancelled sale, a disabled order, the replaced half of an edited one
+         * and a voided MercadoLibre sale — because the ledger is retract-only and
+         * a movement row is never deleted and never overwritten.
+         */
         skip?: boolean;
+        /**
+         * When the retraction happened, in Unix ms. Present only alongside
+         * {@link StockBase.skip}.
+         *
+         * ⚠️ OPTIONAL PERMANENTLY, and absence does NOT mean "not retracted" —
+         * `skip` alone answers that. Rows stamped before this field existed carry
+         * none, this platform never backfills, and a reader that treats a missing
+         * `retractedAt` as "still live" re-counts every one of them.
+         */
+        retractedAt?: number;
     }
     /**
      * Attributes persisted on every stock-movement row. `storeId` and `stockId`
@@ -81,7 +100,21 @@ declare global {
          * `reports?mode=stocks` reports `costlessProducts` beside its totals.
          */
         cost?: number;
+        /**
+         * The movement has been RETRACTED — see {@link StockBase.skip}. The ledger
+         * is retract-only: a reversal stamps this in place rather than deleting
+         * the row, so the audit trail survives the retraction.
+         *
+         * ⚠️ A writer stamping this owes {@link StoredStockBase.retractedAt}
+         * beside it. Nothing structurally forces the pair, so the writer owes it.
+         */
         skip?: boolean;
+        /**
+         * When the retraction happened, in Unix ms — see
+         * {@link StockBase.retractedAt} for why absence is permanent and is not
+         * the same statement as `skip` being absent.
+         */
+        retractedAt?: number;
     }
     /**
      * Why an operator moved stock by hand, rather than through a purchase, a sale

package/package.json

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