platform-types 1.10.710 → 1.10.712

package/dist/cjs/purchaseReceipt.js

@@ -40,10 +40,13 @@ exports.PURCHASE_RECEIPT_MAX_LINES_DEPOSITOS = 32;
  * - `STOCK_INCOME_RACED` · 409 — the ledger-key retry budget ran out. Nothing moved.
  * - `PRODUCT_NOT_FOUND` · 404 — a line's product no longer exists. Nothing moved.
  * - `PURCHASE_RECEIPT_NOT_FOUND` · 404 — `mode=receipt` addressed nothing.
+ * - `PURCHASE_RECEIPT_KEY_CONFLICT` · 409 — the `receiptKey` already booked a
+ *   receipt from a different body. Nothing moved; a new delivery needs a new key.
  * - `INVALID_CURSOR` · 400
  *
- * A replay of a `receiptKey` that already committed is NOT a refusal: it answers
- * 200 with the stored receipt and `replayed: true`.
+ * A replay of a `receiptKey` that already committed with the SAME body is NOT a
+ * refusal: it answers 200 with the stored receipt and `replayed: true`. A receipt
+ * stored with no `requestFingerprint` replays whatever the body.
  *
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
  * as well.

package/dist/purchaseReceipt.d.ts

@@ -75,7 +75,10 @@ declare global {
         /** Original order FX stamp retained for receipt-linked valuation reversals. */
         currencyValue?: number;
         currencyValueAt?: number;
-        /** Internal request identity for safe receipt-key retries. */
+        /**
+         * Internal request identity for safe receipt-key retries, written on every
+         * receipt booked by `mode: 'receive'`. Opaque: a client must ignore it.
+         */
         requestFingerprint?: string;
         updatedAt?: number;
         /** Optimistic revision for cumulative receipt-linked reversals. */
@@ -99,6 +102,78 @@ declare global {
         notes?: string;
         items: PurchaseReceiptItem[];
     }
+    /** The fields every receipt line carries, whichever quantity and cost it names. */
+    interface PurchaseReceiptLineBaseInput {
+        /** Index into the ordering `PurchaseOrder.items`; at most once per receipt. */
+        purchaseOrderItemIndex: number;
+        /** Batch the units arrived as — recorded as sent, see `PurchaseReceiptItem.lotId`. */
+        lotId?: string;
+    }
+    /**
+     * How much arrived: EXACTLY one of the line's base-unit `quantity` or its
+     * `purchaseQuantity` in the order line's frozen purchase unit. Naming both, or
+     * neither, is `400 VALIDATION_FAILED`.
+     */
+    type PurchaseReceiptLineQuantityInput = {
+        quantity: number;
+        purchaseQuantity?: never;
+    } | {
+        purchaseQuantity: number;
+        quantity?: never;
+    };
+    /**
+     * What it cost: AT MOST one of `cost` (per base unit) or `purchaseUnitCost` (per
+     * purchase unit), both in the purchase order's currency. Naming neither values the
+     * line at the order line's own frozen `purchaseUnitCost` when it has one, else
+     * at its `unitCost`; naming both is `400 VALIDATION_FAILED`.
+     */
+    type PurchaseReceiptLineCostInput = {
+        cost?: number;
+        purchaseUnitCost?: never;
+    } | {
+        purchaseUnitCost?: number;
+        cost?: never;
+    };
+    /** One line of a `PurchaseReceiptPostRequest`. */
+    type PurchaseReceiptLineInput = PurchaseReceiptLineBaseInput & PurchaseReceiptLineQuantityInput & PurchaseReceiptLineCostInput;
+    /**
+     * `POST /purchase-orders { mode: 'receive' }` — books one physical delivery
+     * against a purchase order, ADMIN or MANAGER only (`403 ADMIN_REQUIRED`).
+     * Refusals are `PURCHASE_RECEIPT_ERROR_CODES`.
+     *
+     * Idempotent on `receiptKey`: the same key with the same body answers the stored
+     * receipt with `replayed: true`; the same key with a different body is
+     * `409 PURCHASE_RECEIPT_KEY_CONFLICT`. EVERY body field binds the key, including
+     * one the server ignores (`warehouseId` on a store whose `stockAuthority` is not
+     * `'depositos'`), so a retry must resend the identical body; only `dated` sent as
+     * a string or a number, and an empty `notes` or none, count as the same. A
+     * receipt stored with no `requestFingerprint` replays whatever the body.
+     *
+     * Tied to its validator by `AssertPurchaseReceiptPostRequestMatchesSchema` in
+     * the api's `purchaseOrders/_receive.ts`.
+     */
+    interface PurchaseReceiptPostRequest {
+        mode: 'receive';
+        /** `PO` + 6–10 digits. */
+        purchaseOrderId: string;
+        /** Client-minted UUID v4 — mint it once per delivery and reuse it on every retry. */
+        receiptKey: string;
+        /**
+         * The depósito the goods arrived at. Read only on a store whose
+         * `stockAuthority` is `'depositos'`; absent there means the primary.
+         * `WH` + 6–10 digits.
+         */
+        warehouseId?: string;
+        /** `YYYYMMDD` day the goods arrived; absent means today. */
+        dated?: string | number;
+        /** At most 1000 characters. ⚠️ Never personal data. */
+        notes?: string;
+        /**
+         * 1..`PURCHASE_RECEIPT_MAX_LINES` lines (`PURCHASE_RECEIPT_MAX_LINES_DEPOSITOS`
+         * on a depósitos store), each naming a distinct `purchaseOrderItemIndex`.
+         */
+        lines: PurchaseReceiptLineInput[];
+    }
 }
 /**
  * Refusals from `POST /purchase-orders { mode: 'receive' }` and the receipt reads
@@ -124,10 +199,13 @@ declare global {
  * - `STOCK_INCOME_RACED` · 409 — the ledger-key retry budget ran out. Nothing moved.
  * - `PRODUCT_NOT_FOUND` · 404 — a line's product no longer exists. Nothing moved.
  * - `PURCHASE_RECEIPT_NOT_FOUND` · 404 — `mode=receipt` addressed nothing.
+ * - `PURCHASE_RECEIPT_KEY_CONFLICT` · 409 — the `receiptKey` already booked a
+ *   receipt from a different body. Nothing moved; a new delivery needs a new key.
  * - `INVALID_CURSOR` · 400
  *
- * A replay of a `receiptKey` that already committed is NOT a refusal: it answers
- * 200 with the stored receipt and `replayed: true`.
+ * A replay of a `receiptKey` that already committed with the SAME body is NOT a
+ * refusal: it answers 200 with the stored receipt and `replayed: true`. A receipt
+ * stored with no `requestFingerprint` replays whatever the body.
  *
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
  * as well.

package/dist/purchaseReceipt.js

@@ -37,10 +37,13 @@ export const PURCHASE_RECEIPT_MAX_LINES_DEPOSITOS = 32;
  * - `STOCK_INCOME_RACED` · 409 — the ledger-key retry budget ran out. Nothing moved.
  * - `PRODUCT_NOT_FOUND` · 404 — a line's product no longer exists. Nothing moved.
  * - `PURCHASE_RECEIPT_NOT_FOUND` · 404 — `mode=receipt` addressed nothing.
+ * - `PURCHASE_RECEIPT_KEY_CONFLICT` · 409 — the `receiptKey` already booked a
+ *   receipt from a different body. Nothing moved; a new delivery needs a new key.
  * - `INVALID_CURSOR` · 400
  *
- * A replay of a `receiptKey` that already committed is NOT a refusal: it answers
- * 200 with the stored receipt and `replayed: true`.
+ * A replay of a `receiptKey` that already committed with the SAME body is NOT a
+ * refusal: it answers 200 with the stored receipt and `replayed: true`. A receipt
+ * stored with no `requestFingerprint` replays whatever the body.
  *
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
  * as well.

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.710",
+	"version": "1.10.712",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",