platform-types 1.10.710 → 1.10.711

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/package.json

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