platform-types 1.10.709 → 1.10.711

package/dist/cjs/cycleCount.js

@@ -124,7 +124,16 @@ exports.isOverCycleCountToleranceRule = isOverCycleCountToleranceRule;
  * - `CYCLE_COUNT_VERSION_CONFLICT` · 409 — a cancel or finalise that lost the
  *   compare-and-set on the session row. ⚠️ On finalise it is CONDITIONAL: the
  *   handler re-reads consistently, and a winner that FINALISED the session makes
- *   it a `200` replay instead; only a concurrent CANCEL surfaces as this.
+ *   it a `200` replay instead; only a concurrent CANCEL surfaces as this. Never
+ *   answered to `mode: 'edit'`.
+ * - `CYCLE_COUNT_CONTENT_CONFLICT` · 409 — the session is still `open` but no
+ *   longer at the revision the request was composed against; top-level
+ *   `currentUpdatedAt` is the revision to re-send after re-reviewing, and
+ *   nothing was written. ONE meaning in both modes: a finalise whose lines or
+ *   tolerance moved (or whose `expectedUpdatedAt` was stale on arrival), and an
+ *   edit whose `expectedUpdatedAt` is stale — on arrival or overtaken before
+ *   the write — or a token-less edit overtaken on both of its attempts. On an
+ *   edit `data` is {@link CycleCountEditConflict}.
  * - `CYCLE_COUNT_TOLERANCE_EXCEEDED` · 403 — a finalise with at least one
  *   over-tolerance line, from a caller who is neither ADMIN nor MANAGER. The
  *   session stays `open` and NO stock moved.
@@ -187,12 +196,13 @@ exports.CYCLE_COUNT_ERROR_CODES = [
     'CYCLE_COUNT_NOT_OPEN',
     'CYCLE_COUNT_ILLEGAL_TRANSITION',
     'CYCLE_COUNT_VERSION_CONFLICT',
-    // Finalise refuses a session whose COUNTED CONTENT moved since the caller's
-    // read, distinct from the row-version conflict above: the caller's revision
-    // is stale, and committing it would finalise a count nobody took. Answered
-    // by `cycle-counts/_finalize.ts`; landed one PR after this list was
-    // published, and the guard test that keeps this list honest caught it on
-    // `main` rather than in either PR's own gate.
+    // The session is still open but its revision moved since the caller's read,
+    // distinct from the row-version conflict above (the session went terminal):
+    // committing would finalise a count nobody took, or overwrite lines nobody
+    // reviewed. Answered by `cycle-counts/_finalize.ts` and `_edit.ts`. The
+    // finalise case landed one PR after this list was published, and the guard
+    // test that keeps this list honest caught it on `main` rather than in either
+    // PR's own gate.
     'CYCLE_COUNT_CONTENT_CONFLICT',
     'CYCLE_COUNT_TOLERANCE_EXCEEDED',
     // Finalise refuses a line that is neither counted nor skipped rather than

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/cycleCount.d.ts

@@ -187,8 +187,9 @@ declare global {
         /** Unix ms the session was opened. */
         createdAt: number;
         /**
-         * Unix ms of the last write. ABSENT on a session never revised since it
-         * was opened — this platform is forward-only and nothing backfills it.
+         * Unix ms of the last write. Stamped at creation too, so ABSENT only on a
+         * legacy row written before that — this platform is forward-only and
+         * nothing backfills it.
          *
          * ⚠️ **`updatedAt ?? createdAt` is the session's VERSION TOKEN**, and
          * `POST /cycle-counts { mode: 'finalize' }` accepts it as the OPTIONAL
@@ -211,8 +212,28 @@ declare global {
          * an already-`finalized` session, deliberately: a consumer that collapses
          * the three cannot tell "re-confirm" from "it is over" from "it already
          * landed".
+         *
+         * ⚠️ `mode: 'edit'` accepts the same token as its OPTIONAL
+         * `expectedUpdatedAt` ({@link CycleCountEditRequest}), refusing a stale one on
+         * a still-`open` session with the SAME `409 CYCLE_COUNT_CONTENT_CONFLICT` and
+         * top-level `currentUpdatedAt`, plus the current row as `data.current` — so
+         * one client handler serves both modes.
          */
         updatedAt?: number;
+        /**
+         * The operator whose `mode: 'edit'` wrote the current revision, stamped by
+         * the server on EVERY edit. ABSENT on a session never edited since it was
+         * opened (and on every edit made before this field existed — nothing is
+         * backfilled). Only `mode: 'edit'` writes it: a finalise records
+         * `finalizedBy`, and a cancel leaves it as it was.
+         *
+         * Read it on an edit's `409 CYCLE_COUNT_CONTENT_CONFLICT` `data.current`: own
+         * actor plus every field the caller sent being identical is CONSISTENT
+         * with the caller's own earlier edit having landed — never proof of it,
+         * since this is a user id and the same operator on a second device reads
+         * the same.
+         */
+        updatedBy?: string;
         /** The operator who opened it. */
         userId: string;
         status: CycleCountStatus;
@@ -472,6 +493,55 @@ declare global {
         /** Why the line was skipped. Only with `skippedAt`. ⚠️ Never personal data — same un-scrubbed, TTL-less row as `note`. */
         skippedReason?: string;
     }
+    /**
+     * `POST /cycle-counts { mode: 'edit' }` — revise an OPEN session. At least one
+     * of `items`, `dated`, `name`, `zone`, `notes`, `tolerancePercent` is
+     * required; `expectedUpdatedAt` alone is refused 400.
+     *
+     * ⚠️ `items` is a WHOLE-ARRAY replace, never a per-line merge.
+     */
+    interface CycleCountEditRequest {
+        mode: 'edit';
+        cycleCountId: string;
+        items?: CycleCountItem[];
+        /** `YYYYMMDD`, as a string or a number. */
+        dated?: string | number;
+        name?: string;
+        zone?: string;
+        notes?: string;
+        /** `null` CLEARS the per-count rung, returning the session to the store default. */
+        tolerancePercent?: number | null;
+        /**
+         * The revision the operator REVIEWED — {@link CycleCount.updatedAt} `??`
+         * {@link CycleCount.createdAt} of the row the screen shows, read from
+         * `GET /cycle-counts?cycleCountId=` (strongly consistent).
+         *
+         * When sent, the write is fenced on it: a session still `open` but revised
+         * since is refused `409 CYCLE_COUNT_CONTENT_CONFLICT` — the code a finalise
+         * answers for the same case — with the revision to re-send as top-level
+         * `currentUpdatedAt` and the current {@link CycleCount} as `data.current`,
+         * and NOTHING is written. Compare `current.updatedBy` and EVERY field that
+         * was sent: a match is consistent with an own edit whose response was lost
+         * (not proof — same user, another device, reads the same); anything else is
+         * another write. Never retry automatically. A session that went terminal
+         * underneath stays `409 CYCLE_COUNT_NOT_OPEN`.
+         *
+         * Optional for compatibility: omitted, the edit is NOT fenced on a
+         * revision — last writer wins, as before. The server still stamps the new
+         * revision strictly past the stored one, re-reading and retrying once when
+         * a concurrent edit took that value first, so it never re-issues a token
+         * another client holds; a session that churns through both attempts is
+         * answered the same `409 CYCLE_COUNT_CONTENT_CONFLICT`.
+         */
+        expectedUpdatedAt?: number;
+    }
+    /**
+     * `data` of a `409 CYCLE_COUNT_CONTENT_CONFLICT` answered to `mode: 'edit'`
+     * (a finalise's carries no `data`; both carry top-level `currentUpdatedAt`).
+     */
+    interface CycleCountEditConflict {
+        current: CycleCount;
+    }
 }
 export {};
 /**
@@ -557,7 +627,16 @@ export declare const isOverCycleCountToleranceRule: (input: {
  * - `CYCLE_COUNT_VERSION_CONFLICT` · 409 — a cancel or finalise that lost the
  *   compare-and-set on the session row. ⚠️ On finalise it is CONDITIONAL: the
  *   handler re-reads consistently, and a winner that FINALISED the session makes
- *   it a `200` replay instead; only a concurrent CANCEL surfaces as this.
+ *   it a `200` replay instead; only a concurrent CANCEL surfaces as this. Never
+ *   answered to `mode: 'edit'`.
+ * - `CYCLE_COUNT_CONTENT_CONFLICT` · 409 — the session is still `open` but no
+ *   longer at the revision the request was composed against; top-level
+ *   `currentUpdatedAt` is the revision to re-send after re-reviewing, and
+ *   nothing was written. ONE meaning in both modes: a finalise whose lines or
+ *   tolerance moved (or whose `expectedUpdatedAt` was stale on arrival), and an
+ *   edit whose `expectedUpdatedAt` is stale — on arrival or overtaken before
+ *   the write — or a token-less edit overtaken on both of its attempts. On an
+ *   edit `data` is {@link CycleCountEditConflict}.
  * - `CYCLE_COUNT_TOLERANCE_EXCEEDED` · 403 — a finalise with at least one
  *   over-tolerance line, from a caller who is neither ADMIN nor MANAGER. The
  *   session stays `open` and NO stock moved.

package/dist/cycleCount.js

@@ -119,7 +119,16 @@ export const isOverCycleCountToleranceRule = (input, tolerancePercent) => {
  * - `CYCLE_COUNT_VERSION_CONFLICT` · 409 — a cancel or finalise that lost the
  *   compare-and-set on the session row. ⚠️ On finalise it is CONDITIONAL: the
  *   handler re-reads consistently, and a winner that FINALISED the session makes
- *   it a `200` replay instead; only a concurrent CANCEL surfaces as this.
+ *   it a `200` replay instead; only a concurrent CANCEL surfaces as this. Never
+ *   answered to `mode: 'edit'`.
+ * - `CYCLE_COUNT_CONTENT_CONFLICT` · 409 — the session is still `open` but no
+ *   longer at the revision the request was composed against; top-level
+ *   `currentUpdatedAt` is the revision to re-send after re-reviewing, and
+ *   nothing was written. ONE meaning in both modes: a finalise whose lines or
+ *   tolerance moved (or whose `expectedUpdatedAt` was stale on arrival), and an
+ *   edit whose `expectedUpdatedAt` is stale — on arrival or overtaken before
+ *   the write — or a token-less edit overtaken on both of its attempts. On an
+ *   edit `data` is {@link CycleCountEditConflict}.
  * - `CYCLE_COUNT_TOLERANCE_EXCEEDED` · 403 — a finalise with at least one
  *   over-tolerance line, from a caller who is neither ADMIN nor MANAGER. The
  *   session stays `open` and NO stock moved.
@@ -182,12 +191,13 @@ export const CYCLE_COUNT_ERROR_CODES = [
     'CYCLE_COUNT_NOT_OPEN',
     'CYCLE_COUNT_ILLEGAL_TRANSITION',
     'CYCLE_COUNT_VERSION_CONFLICT',
-    // Finalise refuses a session whose COUNTED CONTENT moved since the caller's
-    // read, distinct from the row-version conflict above: the caller's revision
-    // is stale, and committing it would finalise a count nobody took. Answered
-    // by `cycle-counts/_finalize.ts`; landed one PR after this list was
-    // published, and the guard test that keeps this list honest caught it on
-    // `main` rather than in either PR's own gate.
+    // The session is still open but its revision moved since the caller's read,
+    // distinct from the row-version conflict above (the session went terminal):
+    // committing would finalise a count nobody took, or overwrite lines nobody
+    // reviewed. Answered by `cycle-counts/_finalize.ts` and `_edit.ts`. The
+    // finalise case landed one PR after this list was published, and the guard
+    // test that keeps this list honest caught it on `main` rather than in either
+    // PR's own gate.
     'CYCLE_COUNT_CONTENT_CONFLICT',
     'CYCLE_COUNT_TOLERANCE_EXCEEDED',
     // Finalise refuses a line that is neither counted nor skipped rather than

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