platform-types 1.10.711 → 1.10.712

package/dist/stock.d.ts

@@ -506,6 +506,50 @@ declare global {
     /** Hydrated movement returned by readers after deriving ids from DynamoDB keys. */
     interface StockSale extends StockBase, StockSaleWrite {
     }
+    /**
+     * `data` of `GET /products?mode=stock&productId=…` — one product's ledger
+     * TOTALS, never its movement rows.
+     *
+     * - `incomes` — `Σ quantity` over the product's `INCOME#` rows.
+     * - `sales` — `Σ quantity` over the product's `SALE#` rows.
+     * - `stock` — on-hand, `incomes − sales`.
+     *
+     * Rows carrying `skip` are excluded from both sums.
+     *
+     * ⚠️ **`stock` is ABSENT exactly when the read truncated** — when either
+     * leg's paged read stopped short, which the envelope reports as top-level
+     * `truncated: true` ({@link ProductStockTotalsResponse}). It is never `0`
+     * or `null` in that case: a short read of either leg makes the difference
+     * WRONG, in either direction and by any amount, so absence is the signal.
+     * Read `stock === undefined` as "not computable from this read", never as
+     * zero. `incomes` and `sales` are still present then, but each is only the
+     * sum over the rows that were read — NOT a bound on the true leg total,
+     * because ledger quantities are signed (a service-part restore writes a
+     * negative-quantity `SALE#` row).
+     *
+     * A leg with no rows sums to `0`, never absent: a product with an empty
+     * ledger answers `incomes: 0, sales: 0, stock: 0` with `truncated: false`.
+     * The handler does not check that the product exists, so an unknown
+     * `productId` answers the same zeros rather than a 404.
+     */
+    interface ProductStockTotals {
+        incomes: number;
+        sales: number;
+        stock?: number;
+    }
+    /**
+     * The success envelope of `GET /products?mode=stock&productId=…`.
+     *
+     * `truncated` is always present: `true` exactly when `data.stock` is absent
+     * (see {@link ProductStockTotals}). There is no resume cursor — a truncated
+     * read means the on-hand figure is not computable from this endpoint, not
+     * that a next page exists.
+     */
+    interface ProductStockTotalsResponse {
+        message: string;
+        data: ProductStockTotals;
+        truncated: boolean;
+    }
     /**
      * The body of one nightly stock-drift reconciliation run
      * (`stacks/lambdas/stockReconciliationCron/index.ts`).

package/package.json

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