platform-types 1.10.711 → 1.10.713

package/dist/cjs/index.js

@@ -73,6 +73,7 @@ __exportStar(require("./mercadolibre.js"), exports);
 __exportStar(require("./mercadopago.js"), exports);
 __exportStar(require("./notification.js"), exports);
 __exportStar(require("./order.js"), exports);
+__exportStar(require("./orderCollectionAttempt.js"), exports);
 __exportStar(require("./orderCreateAttempt.js"), exports);
 __exportStar(require("./payment.js"), exports);
 __exportStar(require("./platform.js"), exports);

package/dist/cjs/mercadopago.js

@@ -15,7 +15,9 @@ exports.MP_DYNAMIC_QR_ERROR_CODES = void 0;
  * - 503 `PLATFORM_INTEGRATION_DISABLED`; 504 `MP_DYN_QR_UNCONFIRMED`, an unknown creation outcome.
  * A thrown error answers `400 UNHANDLED_ERROR`, never a 500. The re-sync read
  * (`GET /mercadopago/qr/dynamic?orderId=`) uses `VALIDATION_FAILED`, `PLAN_UPGRADE_REQUIRED`,
- * `CAPABILITY_REQUIRED`, `ORDER_NOT_FOUND` and `ORDER_CANCELLED` from this list.
+ * `CAPABILITY_REQUIRED`, `ORDER_NOT_FOUND` and `ORDER_CANCELLED` from this list; its
+ * `ORDER_CANCELLED` carries `data: MpDynamicQrCancelledDetails` when the dead order holds linked
+ * MercadoPago payments.
  *
  * An order-bound charge holds the order's QR fence while it mints, and another charge for the
  * same order meanwhile answers `MP_DYN_QR_IN_PROGRESS`. A `contacting` attempt (MercadoPago may

package/dist/cjs/order.js

@@ -235,6 +235,15 @@ exports.orderFulfilmentProgress = orderFulfilmentProgress;
  *   is also `mode: 'edit'`'s and the update leg's answer to a re-price that
  *   would leave the order's net señas above its new charged total. Nothing was
  *   written on any of them.
+ * - `TILL_TENDER_REQUIRES_DEPOSIT` · 400 — `mode: 'tender'` adding till money
+ *   (any leg whose `source` is not `account`) to an order that is NOT yet
+ *   delivered and holds no seña: money taken before delivery is a seña and
+ *   goes through `mode: 'deposit'`. Decided after replays are absorbed, so a
+ *   pure repeat of legs already on the ledger still answers its 200; an
+ *   account-only tender is never refused. Nothing was written and no
+ *   idempotency marker remains (refused ahead of the claim, or the claim is
+ *   released on the 400), so a collection lookup for it answers
+ *   `unknown` / `NO_EVIDENCE`.
  * - `PAYMENT_REFERENCED_BY_DEPOSIT` · 409 — the payment link (fresh, over an
  *   entry the order already holds, or a credit upgrade) of a payment whose id a
  *   seña on the order already carries as its `reference`: the same money would
@@ -442,6 +451,19 @@ exports.orderFulfilmentProgress = orderFulfilmentProgress;
  *   for another store or user session (`ORDER_ATTEMPT_SCOPE_TAG_LENGTH`). Mint
  *   a new key in this session. Nothing was written.
  *
+ * ⚠️ **A money write's attempt identity is its `Idempotency-Key`, never its
+ * `reference`.** Mint one key per tender, seña or account payment and keep it
+ * for every retry. `reference` is a duplicate-money guard with its own
+ * horizon, not an outcome, and it runs across keys: a tender absorbs a repeat
+ * leg identical on money, method and source that carries the same `reference`
+ * indefinitely, or — neither side carrying one — was recorded by the same user
+ * within 30 seconds; a seña absorbs a same-user or same-`reference` repeat
+ * only inside its 30-second replay window, and an older lookalike is
+ * `409 DEPOSIT_DUPLICATE_REFERENCE`. To learn whether a keyed
+ * write landed after a lost reply, `IDEMPOTENCY_IN_PROGRESS` or
+ * `IDEMPOTENCY_KEY_FAILED`, ask `POST /orders { mode: 'collection-attempt' }`
+ * (`OrderCollectionAttemptVerdict`) — never resend it under a new key first.
+ *
  * Idempotency answers, all six from `withIdempotency`:
  * - `INVALID_IDEMPOTENCY_KEY` · 400 · `IDEMPOTENCY_KEY_REUSE` · 422 (the same
  *   key with a different body)
@@ -521,6 +543,8 @@ exports.ORDER_ERROR_CODES = [
     'DEPOSIT_INVOICED_ORDER_MUST_FREEZE',
     'DEPOSIT_REFERENCE_IS_LINKED_PAYMENT',
     'DEPOSIT_DUPLICATE_REFERENCE',
+    // Till money on an undelivered order with no seña — `mode: 'deposit'` takes it.
+    'TILL_TENDER_REQUIRES_DEPOSIT',
     // The payment link of a payment a seña on the order already references.
     'PAYMENT_REFERENCED_BY_DEPOSIT',
     // Customer cancellation of an order still holding a seña.

package/dist/cjs/orderCollectionAttempt.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Order-collection attempt lookup — the read a client runs when a money write
+ * on an order (a till tender, a seña, an account payment) left it without an
+ * answer: a lost reply, a timeout, or one of the two uncertain refusals
+ * `409 IDEMPOTENCY_IN_PROGRESS` and `409 IDEMPOTENCY_KEY_FAILED`.
+ *
+ * ⚠️ **The attempt's identity is its `Idempotency-Key`, never its `reference`.**
+ * Mint ONE key per collection attempt and keep it for every retry of that
+ * attempt. `reference` keeps its own, narrower meaning as a duplicate-money
+ * guard, and that guard runs ACROSS keys: a tender absorbs a repeat leg
+ * identical on money, method and source that carries the same `reference`
+ * however much later it arrives, OR — neither side carrying a reference — was
+ * recorded by the same user within 30 seconds; a seña absorbs a same-user or
+ * same-`reference` repeat only inside its 30-second replay window (an older
+ * lookalike is `409 DEPOSIT_DUPLICATE_REFERENCE`). So a NEW key is a new
+ * attempt, not a guaranteed new leg: two genuine reference-less handoffs of the
+ * same amount by one cashier inside 30 s land as ONE leg, and the second key
+ * answers `committed` all the same. Give each physical payment its own
+ * `reference` when that distinction matters. Neither guard is an outcome
+ * protocol.
+ *
+ * `POST /orders { mode: 'collection-attempt', operation, orderId, idempotencyKey }`
+ * answers from the write's own idempotency marker, scoped to the CALLER's store
+ * and user. It never claims, replays, reclaims or seals the marker, never
+ * writes the marker or any business row, and calls no provider; a claim it
+ * finds stranded past 60 s logs one deduped operator row.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORDER_COLLECTION_ATTEMPT_RETENTION_MS = exports.ORDER_COLLECTION_ATTEMPT_UNKNOWN_REASONS = exports.ORDER_COLLECTION_ATTEMPT_VERDICTS = exports.ORDER_COLLECTION_ATTEMPT_OPERATIONS = void 0;
+/** Every `operation` the lookup answers for — see `OrderCollectionAttemptLookupRequest`. */
+exports.ORDER_COLLECTION_ATTEMPT_OPERATIONS = ['tender', 'deposit', 'account'];
+/** Every `verdict` the lookup answers — see `OrderCollectionAttemptVerdict`. */
+exports.ORDER_COLLECTION_ATTEMPT_VERDICTS = ['committed', 'in-progress', 'sealed', 'unknown'];
+/**
+ * Every `reason` on an `unknown` verdict:
+ *
+ * - `NO_EVIDENCE` — no marker under this key for the caller: never sent, sent
+ *   by another user or store, refused or released before it committed,
+ *   already deleted by its retention expiry — or STILL IN FLIGHT and not yet
+ *   claimed. A write holds no marker until its claim lands, and before that
+ *   it can be queued at the gateway, in a cold start, or (a tender) running
+ *   its pre-claim reads. So it is never "not collected": follow the
+ *   `unknown` remedy on `OrderCollectionAttemptVerdict` — resend the same
+ *   body under the same key first.
+ * - `EVIDENCE_EXPIRED` — the marker outlived
+ *   {@link ORDER_COLLECTION_ATTEMPT_RETENTION_MS} and is awaiting deletion,
+ *   which DynamoDB does lazily (up to days late). That is the LOOKUP's
+ *   horizon, not the writer's: the write never reads the expiry, so while
+ *   the row survives a same-key resend still replays a committed `200` (or
+ *   refuses a sealed or stranded key) and does NOT run again. Once DynamoDB
+ *   deletes the row the same resend runs as a new write — so past the
+ *   horizon verify where the operation writes before resending at all.
+ * - `UNBOUND_ATTEMPT` — the key belongs to a write that is not a collection
+ *   attempt (another order mode), or to one admitted before the server
+ *   started recording which collection a key was for.
+ * - `ATTEMPT_MISMATCH` — the key was sent for a different `operation` or
+ *   `orderId` than the lookup names.
+ * - `REFUSED` — the write's cached answer was a refusal (non-`2xx`): nothing
+ *   moved under this key. No collection write caches a refusal today; this
+ *   keeps one that ever does from reading as `committed`.
+ */
+exports.ORDER_COLLECTION_ATTEMPT_UNKNOWN_REASONS = [
+    'NO_EVIDENCE',
+    'EVIDENCE_EXPIRED',
+    'UNBOUND_ATTEMPT',
+    'ATTEMPT_MISMATCH',
+    'REFUSED',
+];
+/**
+ * How long the server keeps a collection attempt's evidence: 24 hours — the
+ * write's own idempotency retention. Past it the lookup answers `unknown`.
+ */
+exports.ORDER_COLLECTION_ATTEMPT_RETENTION_MS = 86_400_000;

package/dist/index.d.ts

@@ -49,6 +49,7 @@ export * from './mercadolibre.ts';
 export * from './mercadopago.ts';
 export * from './notification.ts';
 export * from './order.ts';
+export * from './orderCollectionAttempt.ts';
 export * from './orderCreateAttempt.ts';
 export * from './payment.ts';
 export * from './platform.ts';

package/dist/index.js

@@ -57,6 +57,7 @@ export * from "./mercadolibre.js";
 export * from "./mercadopago.js";
 export * from "./notification.js";
 export * from "./order.js";
+export * from "./orderCollectionAttempt.js";
 export * from "./orderCreateAttempt.js";
 export * from "./payment.js";
 export * from "./platform.js";

package/dist/mercadopago.d.ts

@@ -98,13 +98,73 @@ declare global {
         state: 'reserved' | 'contacting';
         since?: number;
     }
+    /**
+     * One MercadoPago payment linked to the order, as the `paid` arm of
+     * {@link MpDynamicQrStateResponse} reports it — read from the order's own
+     * `linkedPayments` entry, never matched by amount, customer or time.
+     *
+     * - `paymentId` — MercadoPago's payment id, the entry's key.
+     * - `amount` — what the store still holds for that payment, net of refunds
+     *   (`LinkedPaymentEntry.total`), in `currency`.
+     * - `currency` — the payment's denomination as `LinkedPaymentEntry.currency`
+     *   states it (an ISO code or a platform catalogId); for an entry naming
+     *   none, the order's own currency, and `'ARS'` only when the order names
+     *   none either.
+     * - `paidAt` — when the approved payment was linked to the order (epoch ms),
+     *   which follows MercadoPago's approval, never precedes it.
+     */
+    interface MpDynamicQrPaidPayment {
+        paymentId: string;
+        amount: number;
+        currency: string;
+        paidAt: number;
+    }
+    /**
+     * `data` of the re-sync read's `409 ORDER_CANCELLED`
+     * (`GET /mercadopago/qr/dynamic?orderId=`), present only when the dead order
+     * still holds linked MercadoPago payments: the money that moved before (or
+     * despite) the cancellation, from the same consistent order read that
+     * refused. The `paid` arm of {@link MpDynamicQrStateResponse} without
+     * `pending` — a dead order's QR fence is not read. Absent when no
+     * MercadoPago payment is linked, which, exactly like `none`, is no evidence
+     * of non-payment. The POST's `409 ORDER_CANCELLED` never carries it.
+     */
+    interface MpDynamicQrCancelledDetails {
+        state: 'paid';
+        payments: MpDynamicQrPaidPayment[];
+        serverNow: number;
+    }
     /**
      * `data` of `GET /mercadopago/qr/dynamic?orderId=` — the re-sync read of the order's
-     * dynamic QR. Never carries the attempt's key or owner. `pending` = an attempt
-     * holds the order's fence (`since` = its reservation instant; no `qrData`); `none` =
-     * nothing blocks the order.
+     * dynamic QR. Never carries the attempt's key or owner.
+     *
+     * - `paid` — the order holds at least one approved MercadoPago payment
+     *   (`payments`, oldest link first), from a consistent read of the order.
+     *   When another attempt ALSO holds the fence (a QR for the remaining
+     *   balance), `pending` carries its `phase` and `since`; absent otherwise.
+     * - `pending` — an attempt holds the order's fence (`since` = its reservation
+     *   instant; no `qrData`).
+     * - `none` — nothing blocks the order and no MercadoPago payment is linked
+     *   YET. ⚠️ `none` is never evidence of non-payment: an approval may not be
+     *   linked yet — a late webhook, a `409` the payment hook is waiting to
+     *   retry, or MercadoPago processing switched off by the platform kill
+     *   switch while a QR minted earlier stays payable at MercadoPago. A client
+     *   must not collect again on `none`.
+     *
+     * ⚠️ Creating or showing a QR is never payment: only `paid` says money moved,
+     * and only its absence AFTER the operator has checked MercadoPago is a reason
+     * to collect again. A dead order answers `409 ORDER_CANCELLED` instead, with
+     * `data: MpDynamicQrCancelledDetails` when it holds linked payments.
      */
     type MpDynamicQrStateResponse = {
+        state: 'paid';
+        payments: MpDynamicQrPaidPayment[];
+        pending?: {
+            phase: 'reserved' | 'contacting';
+            since?: number;
+        };
+        serverNow: number;
+    } | {
         state: 'pending';
         phase: 'reserved' | 'contacting';
         since?: number;
@@ -191,7 +251,9 @@ declare global {
  * - 503 `PLATFORM_INTEGRATION_DISABLED`; 504 `MP_DYN_QR_UNCONFIRMED`, an unknown creation outcome.
  * A thrown error answers `400 UNHANDLED_ERROR`, never a 500. The re-sync read
  * (`GET /mercadopago/qr/dynamic?orderId=`) uses `VALIDATION_FAILED`, `PLAN_UPGRADE_REQUIRED`,
- * `CAPABILITY_REQUIRED`, `ORDER_NOT_FOUND` and `ORDER_CANCELLED` from this list.
+ * `CAPABILITY_REQUIRED`, `ORDER_NOT_FOUND` and `ORDER_CANCELLED` from this list; its
+ * `ORDER_CANCELLED` carries `data: MpDynamicQrCancelledDetails` when the dead order holds linked
+ * MercadoPago payments.
  *
  * An order-bound charge holds the order's QR fence while it mints, and another charge for the
  * same order meanwhile answers `MP_DYN_QR_IN_PROGRESS`. A `contacting` attempt (MercadoPago may

package/dist/mercadopago.js

@@ -12,7 +12,9 @@
  * - 503 `PLATFORM_INTEGRATION_DISABLED`; 504 `MP_DYN_QR_UNCONFIRMED`, an unknown creation outcome.
  * A thrown error answers `400 UNHANDLED_ERROR`, never a 500. The re-sync read
  * (`GET /mercadopago/qr/dynamic?orderId=`) uses `VALIDATION_FAILED`, `PLAN_UPGRADE_REQUIRED`,
- * `CAPABILITY_REQUIRED`, `ORDER_NOT_FOUND` and `ORDER_CANCELLED` from this list.
+ * `CAPABILITY_REQUIRED`, `ORDER_NOT_FOUND` and `ORDER_CANCELLED` from this list; its
+ * `ORDER_CANCELLED` carries `data: MpDynamicQrCancelledDetails` when the dead order holds linked
+ * MercadoPago payments.
  *
  * An order-bound charge holds the order's QR fence while it mints, and another charge for the
  * same order meanwhile answers `MP_DYN_QR_IN_PROGRESS`. A `contacting` attempt (MercadoPago may

package/dist/order.d.ts

@@ -2473,6 +2473,15 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  *   is also `mode: 'edit'`'s and the update leg's answer to a re-price that
  *   would leave the order's net señas above its new charged total. Nothing was
  *   written on any of them.
+ * - `TILL_TENDER_REQUIRES_DEPOSIT` · 400 — `mode: 'tender'` adding till money
+ *   (any leg whose `source` is not `account`) to an order that is NOT yet
+ *   delivered and holds no seña: money taken before delivery is a seña and
+ *   goes through `mode: 'deposit'`. Decided after replays are absorbed, so a
+ *   pure repeat of legs already on the ledger still answers its 200; an
+ *   account-only tender is never refused. Nothing was written and no
+ *   idempotency marker remains (refused ahead of the claim, or the claim is
+ *   released on the 400), so a collection lookup for it answers
+ *   `unknown` / `NO_EVIDENCE`.
  * - `PAYMENT_REFERENCED_BY_DEPOSIT` · 409 — the payment link (fresh, over an
  *   entry the order already holds, or a credit upgrade) of a payment whose id a
  *   seña on the order already carries as its `reference`: the same money would
@@ -2680,6 +2689,19 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  *   for another store or user session (`ORDER_ATTEMPT_SCOPE_TAG_LENGTH`). Mint
  *   a new key in this session. Nothing was written.
  *
+ * ⚠️ **A money write's attempt identity is its `Idempotency-Key`, never its
+ * `reference`.** Mint one key per tender, seña or account payment and keep it
+ * for every retry. `reference` is a duplicate-money guard with its own
+ * horizon, not an outcome, and it runs across keys: a tender absorbs a repeat
+ * leg identical on money, method and source that carries the same `reference`
+ * indefinitely, or — neither side carrying one — was recorded by the same user
+ * within 30 seconds; a seña absorbs a same-user or same-`reference` repeat
+ * only inside its 30-second replay window, and an older lookalike is
+ * `409 DEPOSIT_DUPLICATE_REFERENCE`. To learn whether a keyed
+ * write landed after a lost reply, `IDEMPOTENCY_IN_PROGRESS` or
+ * `IDEMPOTENCY_KEY_FAILED`, ask `POST /orders { mode: 'collection-attempt' }`
+ * (`OrderCollectionAttemptVerdict`) — never resend it under a new key first.
+ *
  * Idempotency answers, all six from `withIdempotency`:
  * - `INVALID_IDEMPOTENCY_KEY` · 400 · `IDEMPOTENCY_KEY_REUSE` · 422 (the same
  *   key with a different body)
@@ -2701,6 +2723,6 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  * `SUBSCRIPTION_READONLY`) sit on the order CREATE leg only: an edit is not a new
  * order, so `bareOrderPostHandler` routes past `requireMetered` entirely.
  */
-export declare const ORDER_ERROR_CODES: readonly ["ORDER_COST_DENOMINATION_UNKNOWN", "SERVICE_ORDER_DELIVERY_MANAGED", "ORDER_NOT_FOUND", "ORDER_LOCKED", "ORDER_NOT_READY", "ORDER_DELIVERED_ANOTHER_DAY", "ORDER_DELIVERY_STATE_UNCHANGED", "ORDER_ILLEGAL_TRANSITION", "ORDER_VERSION_CONFLICT", "CUSTOMER_NOT_FOUND", "CUSTOMER_MERGED", "ORDER_HAS_NO_CUSTOMER", "CUSTOMER_ANONYMIZED", "FX_CONVERSION_UNAVAILABLE", "ROLE_FORBIDDEN", "ORDER_CANCELLED", "PAYMENT_SETTLED_ON_ANOTHER_ORDER", "ORDER_HAS_SHIPMENTS", "ORDER_HAS_RETURNS", "SHIPMENT_QUANTITY_EXCEEDED", "SHIPMENT_LINE_MISMATCH", "SHIPMENT_NOT_FOUND", "SHIPMENT_LIMIT_REACHED", "SHIPMENT_TOO_LARGE", "ORDER_FULFILMENT_EXTERNAL", "SHIPMENT_FAILED", "ADMIN_REQUIRED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "IDEMPOTENCY_KEY_FAILED", "IDEMPOTENT_RESPONSE_NOT_CACHED", "ORDER_CANCELLATION_NOT_PROTECTED", "ORDER_CANCELLATION_COMMITTED", "ORDER_CANCELLATION_LOCKED", "ORDER_CANCELLATION_TOO_LARGE", "ORDER_CANCELLATION_FAILED", "SALE_LEDGER_RETRACTION_REFUSED", "SALE_LEDGER_ROW_NOT_OWNED", "PRODUCT_NOT_FOUND", "PRODUCT_SALE_LIMIT_EXCEEDED", "PRODUCT_SALE_LIMIT_INVALID", "DEPOSIT_SOURCE_NOT_ALLOWED", "DEPOSIT_CURRENCY_MISMATCH", "DEPOSIT_EXCEEDS_TOTAL", "DEPOSIT_FREEZE_REQUIRES_INVOICE", "DEPOSIT_FREEZE_INVOICE_PENDING", "DEPOSIT_CHARACTERIZATION_CONFLICT", "DEPOSIT_FREEZE_INVOICE_NOT_QUALIFYING", "DEPOSIT_INVOICED_ORDER_MUST_FREEZE", "DEPOSIT_REFERENCE_IS_LINKED_PAYMENT", "DEPOSIT_DUPLICATE_REFERENCE", "PAYMENT_REFERENCED_BY_DEPOSIT", "ORDER_HAS_UNREFUNDED_DEPOSIT", "DEPOSIT_NOT_FOUND", "DEPOSIT_ALREADY_REFUNDED", "UNIT_QUANTITY_NOT_WHOLE", "UNIT_REVISION_STALE", "UNIT_QUANTITY_UNREPRESENTABLE", "KIT_RECIPE_CHANGED", "CART_PROMOTION_UNAVAILABLE", "ORDER_HAS_KIT_LINES", "ORDER_TARGET_REQUIRED", "ORDER_SOURCE_CONFLICT", "ORDER_CUSTOMER_REQUIRED", "BASKET_EMPTY", "BASKET_CHANGED_DURING_CHECKOUT", "CART_VERSION_CREATE_ONLY", "CART_VERSION_REQUIRES_CART_ID", "CART_REVISION_STALE", "CART_CUSTOMER_MISMATCH", "COUNTER_SALE_CREATE_ONLY", "SOLD_AT_CREATE_ONLY", "SOLD_AT_IN_FUTURE", "ORDER_TENDER_CREATE_ONLY", "CREDIT_OVERRIDE_CREATE_ONLY", "ON_ACCOUNT_CREATE_ONLY", "ON_ACCOUNT_WITH_TENDERS", "TENDERS_REQUIRE_COUNTER_SALE", "LINES_REQUIRE_COUNTER_SALE", "PRODUCT_COST_UNKNOWN", "PRICE_CHANGE_DISABLED", "LINE_DISCOUNT_EXCEEDS_MAX", "CUSTOMER_DISABLED", "SHIFT_NOT_AVAILABLE", "SOLD_AT_OUTSIDE_SHIFT", "ORDER_CURRENCY_NOT_SUBSCRIBED", "PAYMENT_METHODS_NOT_CONFIGURED", "PAYMENT_METHOD_NOT_FOUND", "DELIVERY_METHOD_NOT_FOUND", "ORDER_BELOW_MINIMUM_PURCHASE", "ORDER_INVALID_CART", "EMAIL_VERIFICATION_REQUIRED", "ACCOUNT_DISABLED", "CURRENCY_MISMATCH", "SHIFT_NOT_OPEN", "ORDER_DISCOUNT_AFTER_INVOICE", "ORDER_DISCOUNT_ON_SERVICE_ORDER", "ORDER_DISCOUNT_ON_MARKETPLACE_ORDER", "ORDER_INVOICE_METHOD_OUTSTANDING_FACTURA", "ORDER_SERVICE_PERIOD_AFTER_INVOICE", "ORDER_ATTEMPT_COMMITTED", "ORDER_ATTEMPT_ABANDONED", "ORDER_ATTEMPT_KEY_EXPIRED", "ORDER_ATTEMPT_KEY_SCOPE_MISMATCH"];
+export declare const ORDER_ERROR_CODES: readonly ["ORDER_COST_DENOMINATION_UNKNOWN", "SERVICE_ORDER_DELIVERY_MANAGED", "ORDER_NOT_FOUND", "ORDER_LOCKED", "ORDER_NOT_READY", "ORDER_DELIVERED_ANOTHER_DAY", "ORDER_DELIVERY_STATE_UNCHANGED", "ORDER_ILLEGAL_TRANSITION", "ORDER_VERSION_CONFLICT", "CUSTOMER_NOT_FOUND", "CUSTOMER_MERGED", "ORDER_HAS_NO_CUSTOMER", "CUSTOMER_ANONYMIZED", "FX_CONVERSION_UNAVAILABLE", "ROLE_FORBIDDEN", "ORDER_CANCELLED", "PAYMENT_SETTLED_ON_ANOTHER_ORDER", "ORDER_HAS_SHIPMENTS", "ORDER_HAS_RETURNS", "SHIPMENT_QUANTITY_EXCEEDED", "SHIPMENT_LINE_MISMATCH", "SHIPMENT_NOT_FOUND", "SHIPMENT_LIMIT_REACHED", "SHIPMENT_TOO_LARGE", "ORDER_FULFILMENT_EXTERNAL", "SHIPMENT_FAILED", "ADMIN_REQUIRED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "IDEMPOTENCY_KEY_FAILED", "IDEMPOTENT_RESPONSE_NOT_CACHED", "ORDER_CANCELLATION_NOT_PROTECTED", "ORDER_CANCELLATION_COMMITTED", "ORDER_CANCELLATION_LOCKED", "ORDER_CANCELLATION_TOO_LARGE", "ORDER_CANCELLATION_FAILED", "SALE_LEDGER_RETRACTION_REFUSED", "SALE_LEDGER_ROW_NOT_OWNED", "PRODUCT_NOT_FOUND", "PRODUCT_SALE_LIMIT_EXCEEDED", "PRODUCT_SALE_LIMIT_INVALID", "DEPOSIT_SOURCE_NOT_ALLOWED", "DEPOSIT_CURRENCY_MISMATCH", "DEPOSIT_EXCEEDS_TOTAL", "DEPOSIT_FREEZE_REQUIRES_INVOICE", "DEPOSIT_FREEZE_INVOICE_PENDING", "DEPOSIT_CHARACTERIZATION_CONFLICT", "DEPOSIT_FREEZE_INVOICE_NOT_QUALIFYING", "DEPOSIT_INVOICED_ORDER_MUST_FREEZE", "DEPOSIT_REFERENCE_IS_LINKED_PAYMENT", "DEPOSIT_DUPLICATE_REFERENCE", "TILL_TENDER_REQUIRES_DEPOSIT", "PAYMENT_REFERENCED_BY_DEPOSIT", "ORDER_HAS_UNREFUNDED_DEPOSIT", "DEPOSIT_NOT_FOUND", "DEPOSIT_ALREADY_REFUNDED", "UNIT_QUANTITY_NOT_WHOLE", "UNIT_REVISION_STALE", "UNIT_QUANTITY_UNREPRESENTABLE", "KIT_RECIPE_CHANGED", "CART_PROMOTION_UNAVAILABLE", "ORDER_HAS_KIT_LINES", "ORDER_TARGET_REQUIRED", "ORDER_SOURCE_CONFLICT", "ORDER_CUSTOMER_REQUIRED", "BASKET_EMPTY", "BASKET_CHANGED_DURING_CHECKOUT", "CART_VERSION_CREATE_ONLY", "CART_VERSION_REQUIRES_CART_ID", "CART_REVISION_STALE", "CART_CUSTOMER_MISMATCH", "COUNTER_SALE_CREATE_ONLY", "SOLD_AT_CREATE_ONLY", "SOLD_AT_IN_FUTURE", "ORDER_TENDER_CREATE_ONLY", "CREDIT_OVERRIDE_CREATE_ONLY", "ON_ACCOUNT_CREATE_ONLY", "ON_ACCOUNT_WITH_TENDERS", "TENDERS_REQUIRE_COUNTER_SALE", "LINES_REQUIRE_COUNTER_SALE", "PRODUCT_COST_UNKNOWN", "PRICE_CHANGE_DISABLED", "LINE_DISCOUNT_EXCEEDS_MAX", "CUSTOMER_DISABLED", "SHIFT_NOT_AVAILABLE", "SOLD_AT_OUTSIDE_SHIFT", "ORDER_CURRENCY_NOT_SUBSCRIBED", "PAYMENT_METHODS_NOT_CONFIGURED", "PAYMENT_METHOD_NOT_FOUND", "DELIVERY_METHOD_NOT_FOUND", "ORDER_BELOW_MINIMUM_PURCHASE", "ORDER_INVALID_CART", "EMAIL_VERIFICATION_REQUIRED", "ACCOUNT_DISABLED", "CURRENCY_MISMATCH", "SHIFT_NOT_OPEN", "ORDER_DISCOUNT_AFTER_INVOICE", "ORDER_DISCOUNT_ON_SERVICE_ORDER", "ORDER_DISCOUNT_ON_MARKETPLACE_ORDER", "ORDER_INVOICE_METHOD_OUTSTANDING_FACTURA", "ORDER_SERVICE_PERIOD_AFTER_INVOICE", "ORDER_ATTEMPT_COMMITTED", "ORDER_ATTEMPT_ABANDONED", "ORDER_ATTEMPT_KEY_EXPIRED", "ORDER_ATTEMPT_KEY_SCOPE_MISMATCH"];
 export type OrderErrorCode = (typeof ORDER_ERROR_CODES)[number];
 export {};

package/dist/order.js

@@ -228,6 +228,15 @@ export const orderFulfilmentProgress = (order) => {
  *   is also `mode: 'edit'`'s and the update leg's answer to a re-price that
  *   would leave the order's net señas above its new charged total. Nothing was
  *   written on any of them.
+ * - `TILL_TENDER_REQUIRES_DEPOSIT` · 400 — `mode: 'tender'` adding till money
+ *   (any leg whose `source` is not `account`) to an order that is NOT yet
+ *   delivered and holds no seña: money taken before delivery is a seña and
+ *   goes through `mode: 'deposit'`. Decided after replays are absorbed, so a
+ *   pure repeat of legs already on the ledger still answers its 200; an
+ *   account-only tender is never refused. Nothing was written and no
+ *   idempotency marker remains (refused ahead of the claim, or the claim is
+ *   released on the 400), so a collection lookup for it answers
+ *   `unknown` / `NO_EVIDENCE`.
  * - `PAYMENT_REFERENCED_BY_DEPOSIT` · 409 — the payment link (fresh, over an
  *   entry the order already holds, or a credit upgrade) of a payment whose id a
  *   seña on the order already carries as its `reference`: the same money would
@@ -435,6 +444,19 @@ export const orderFulfilmentProgress = (order) => {
  *   for another store or user session (`ORDER_ATTEMPT_SCOPE_TAG_LENGTH`). Mint
  *   a new key in this session. Nothing was written.
  *
+ * ⚠️ **A money write's attempt identity is its `Idempotency-Key`, never its
+ * `reference`.** Mint one key per tender, seña or account payment and keep it
+ * for every retry. `reference` is a duplicate-money guard with its own
+ * horizon, not an outcome, and it runs across keys: a tender absorbs a repeat
+ * leg identical on money, method and source that carries the same `reference`
+ * indefinitely, or — neither side carrying one — was recorded by the same user
+ * within 30 seconds; a seña absorbs a same-user or same-`reference` repeat
+ * only inside its 30-second replay window, and an older lookalike is
+ * `409 DEPOSIT_DUPLICATE_REFERENCE`. To learn whether a keyed
+ * write landed after a lost reply, `IDEMPOTENCY_IN_PROGRESS` or
+ * `IDEMPOTENCY_KEY_FAILED`, ask `POST /orders { mode: 'collection-attempt' }`
+ * (`OrderCollectionAttemptVerdict`) — never resend it under a new key first.
+ *
  * Idempotency answers, all six from `withIdempotency`:
  * - `INVALID_IDEMPOTENCY_KEY` · 400 · `IDEMPOTENCY_KEY_REUSE` · 422 (the same
  *   key with a different body)
@@ -514,6 +536,8 @@ export const ORDER_ERROR_CODES = [
     'DEPOSIT_INVOICED_ORDER_MUST_FREEZE',
     'DEPOSIT_REFERENCE_IS_LINKED_PAYMENT',
     'DEPOSIT_DUPLICATE_REFERENCE',
+    // Till money on an undelivered order with no seña — `mode: 'deposit'` takes it.
+    'TILL_TENDER_REQUIRES_DEPOSIT',
     // The payment link of a payment a seña on the order already references.
     'PAYMENT_REFERENCED_BY_DEPOSIT',
     // Customer cancellation of an order still holding a seña.

package/dist/orderCollectionAttempt.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Order-collection attempt lookup — the read a client runs when a money write
+ * on an order (a till tender, a seña, an account payment) left it without an
+ * answer: a lost reply, a timeout, or one of the two uncertain refusals
+ * `409 IDEMPOTENCY_IN_PROGRESS` and `409 IDEMPOTENCY_KEY_FAILED`.
+ *
+ * ⚠️ **The attempt's identity is its `Idempotency-Key`, never its `reference`.**
+ * Mint ONE key per collection attempt and keep it for every retry of that
+ * attempt. `reference` keeps its own, narrower meaning as a duplicate-money
+ * guard, and that guard runs ACROSS keys: a tender absorbs a repeat leg
+ * identical on money, method and source that carries the same `reference`
+ * however much later it arrives, OR — neither side carrying a reference — was
+ * recorded by the same user within 30 seconds; a seña absorbs a same-user or
+ * same-`reference` repeat only inside its 30-second replay window (an older
+ * lookalike is `409 DEPOSIT_DUPLICATE_REFERENCE`). So a NEW key is a new
+ * attempt, not a guaranteed new leg: two genuine reference-less handoffs of the
+ * same amount by one cashier inside 30 s land as ONE leg, and the second key
+ * answers `committed` all the same. Give each physical payment its own
+ * `reference` when that distinction matters. Neither guard is an outcome
+ * protocol.
+ *
+ * `POST /orders { mode: 'collection-attempt', operation, orderId, idempotencyKey }`
+ * answers from the write's own idempotency marker, scoped to the CALLER's store
+ * and user. It never claims, replays, reclaims or seals the marker, never
+ * writes the marker or any business row, and calls no provider; a claim it
+ * finds stranded past 60 s logs one deduped operator row.
+ */
+declare global {
+    /** One of {@link ORDER_COLLECTION_ATTEMPT_OPERATIONS}. */
+    type OrderCollectionAttemptOperation = (typeof ORDER_COLLECTION_ATTEMPT_OPERATIONS)[number];
+    /** One of {@link ORDER_COLLECTION_ATTEMPT_VERDICTS}. */
+    type OrderCollectionAttemptVerdictKind = (typeof ORDER_COLLECTION_ATTEMPT_VERDICTS)[number];
+    /** Why a lookup could not decide — one of {@link ORDER_COLLECTION_ATTEMPT_UNKNOWN_REASONS}. */
+    type OrderCollectionAttemptUnknownReason = (typeof ORDER_COLLECTION_ATTEMPT_UNKNOWN_REASONS)[number];
+    /**
+     * `POST /orders` body for the lookup.
+     *
+     * - `operation` — which write the key was sent with: `tender`
+     *   (`POST /orders { mode: 'tender' }`), `deposit`
+     *   (`POST /orders { mode: 'deposit' }`) or `account` (`POST /account`, a
+     *   customer-account movement sent with this `orderId`).
+     * - `orderId` — the order that write named.
+     * - `idempotencyKey` — the exact `Idempotency-Key` header the write carried.
+     *
+     * The store and user are the caller's session, never a body or header
+     * field. The lookup is not itself idempotency-keyed and is safe to repeat;
+     * an `in-progress` answer is a moment in time, so ask again after
+     * `retryAfterMs` and never cache it.
+     */
+    interface OrderCollectionAttemptLookupRequest {
+        mode: 'collection-attempt';
+        operation: OrderCollectionAttemptOperation;
+        orderId: string;
+        idempotencyKey: string;
+    }
+    /**
+     * `data` of a `200` from `POST /orders { mode: 'collection-attempt' }`.
+     *
+     * - `committed` — the write answered `2xx` (`statusCode`). `body` is the
+     *   exact JSON envelope it answered — for a tender or a seña the order's
+     *   post-commit echo with the updated settlement (a repeat the dedupe guard
+     *   absorbed appended no leg, and the echo shows the ledger as it stands);
+     *   for an account movement its ACCOUNT row. `body` is `null` when no usable
+     *   envelope was cached (a body too large to keep, or not JSON);
+     *   `statusCode` is `null` only on a marker that cached no response at all.
+     *   `claimedAt` is the instant the write was admitted (epoch ms), at or
+     *   before its commit. Do not collect again.
+     * - `in-progress` — the write is still running. Ask again after
+     *   `retryAfterMs`.
+     * - `sealed` — the write may or may not have landed and can never be
+     *   re-run under this key. `abandoned: false` — the key is sealed: by a
+     *   throw after the transaction may have committed, or by a later same-key
+     *   retry that found the claim stranded. `abandoned: true` — the claim is
+     *   still stranded `in_progress` past 60 s: the invocation died mid-flight
+     *   and nothing has sealed it yet. Show "unresolved — check", never
+     *   "pay again", and verify where the operation writes before collecting
+     *   under a NEW key: the order's `tenders` for `tender` and `deposit`; the
+     *   customer's account movements carrying this `orderId` for `account`,
+     *   which never writes the order.
+     * - `unknown` — the server holds no evidence for this attempt; `reason`
+     *   says why. Never read it as "not written": a write released before it
+     *   committed leaves no evidence, and so does one STILL IN FLIGHT that has
+     *   not claimed its key yet (`NO_EVIDENCE`). The safe remedy, in this order:
+     *   1. FIRST resend the identical request — the same body under the SAME
+     *      `Idempotency-Key`, as the SAME user. The write's claim is a
+     *      conditional put (`attribute_not_exists`), so the resend serialises
+     *      against any copy still in flight: it replays the cached `2xx` of a
+     *      write that committed, or runs exactly once. A
+     *      `409 IDEMPOTENCY_IN_PROGRESS` means a copy holds the claim — ask the
+     *      lookup again after a pause; a `409 IDEMPOTENCY_KEY_FAILED` means the
+     *      key is sealed — handle it as `sealed`. Neither is a second charge.
+     *      "Identical" is what the write fingerprints: a changed body answers
+     *      `422 IDEMPOTENCY_KEY_REUSE` (for `POST /account` a fresh
+     *      `elevationToken` is not a change).
+     *   2. Collect under a NEW key only after the operator has verified where
+     *      the operation writes (as for `sealed`) AND at least 30 seconds have
+     *      passed since the last send of this key — API Gateway stops waiting at
+     *      29 s, and the writing Lambdas time out at 25 s (`tender`, `deposit`)
+     *      and 20 s (`account`).
+     *   This holds inside {@link ORDER_COLLECTION_ATTEMPT_RETENTION_MS} of the
+     *   attempt's first send. Past it a same-key resend is no longer a safe
+     *   probe (see `EVIDENCE_EXPIRED`): verify first.
+     *
+     * ⚠️ A verdict only ever describes the caller's OWN key: another user's or
+     * another store's key answers `unknown` / `NO_EVIDENCE`, never their verdict.
+     */
+    type OrderCollectionAttemptVerdict = {
+        verdict: Extract<OrderCollectionAttemptVerdictKind, 'committed'>;
+        claimedAt: number | null;
+        statusCode: number | null;
+        body: Record<string, unknown> | null;
+    } | {
+        verdict: Extract<OrderCollectionAttemptVerdictKind, 'in-progress'>;
+        retryAfterMs: number;
+        claimedAt: number;
+    } | {
+        verdict: Extract<OrderCollectionAttemptVerdictKind, 'sealed'>;
+        claimedAt: number | null;
+        abandoned: boolean;
+    } | {
+        verdict: Extract<OrderCollectionAttemptVerdictKind, 'unknown'>;
+        reason: OrderCollectionAttemptUnknownReason;
+    };
+}
+/** Every `operation` the lookup answers for — see `OrderCollectionAttemptLookupRequest`. */
+export declare const ORDER_COLLECTION_ATTEMPT_OPERATIONS: readonly ["tender", "deposit", "account"];
+/** Every `verdict` the lookup answers — see `OrderCollectionAttemptVerdict`. */
+export declare const ORDER_COLLECTION_ATTEMPT_VERDICTS: readonly ["committed", "in-progress", "sealed", "unknown"];
+/**
+ * Every `reason` on an `unknown` verdict:
+ *
+ * - `NO_EVIDENCE` — no marker under this key for the caller: never sent, sent
+ *   by another user or store, refused or released before it committed,
+ *   already deleted by its retention expiry — or STILL IN FLIGHT and not yet
+ *   claimed. A write holds no marker until its claim lands, and before that
+ *   it can be queued at the gateway, in a cold start, or (a tender) running
+ *   its pre-claim reads. So it is never "not collected": follow the
+ *   `unknown` remedy on `OrderCollectionAttemptVerdict` — resend the same
+ *   body under the same key first.
+ * - `EVIDENCE_EXPIRED` — the marker outlived
+ *   {@link ORDER_COLLECTION_ATTEMPT_RETENTION_MS} and is awaiting deletion,
+ *   which DynamoDB does lazily (up to days late). That is the LOOKUP's
+ *   horizon, not the writer's: the write never reads the expiry, so while
+ *   the row survives a same-key resend still replays a committed `200` (or
+ *   refuses a sealed or stranded key) and does NOT run again. Once DynamoDB
+ *   deletes the row the same resend runs as a new write — so past the
+ *   horizon verify where the operation writes before resending at all.
+ * - `UNBOUND_ATTEMPT` — the key belongs to a write that is not a collection
+ *   attempt (another order mode), or to one admitted before the server
+ *   started recording which collection a key was for.
+ * - `ATTEMPT_MISMATCH` — the key was sent for a different `operation` or
+ *   `orderId` than the lookup names.
+ * - `REFUSED` — the write's cached answer was a refusal (non-`2xx`): nothing
+ *   moved under this key. No collection write caches a refusal today; this
+ *   keeps one that ever does from reading as `committed`.
+ */
+export declare const ORDER_COLLECTION_ATTEMPT_UNKNOWN_REASONS: readonly ["NO_EVIDENCE", "EVIDENCE_EXPIRED", "UNBOUND_ATTEMPT", "ATTEMPT_MISMATCH", "REFUSED"];
+/**
+ * How long the server keeps a collection attempt's evidence: 24 hours — the
+ * write's own idempotency retention. Past it the lookup answers `unknown`.
+ */
+export declare const ORDER_COLLECTION_ATTEMPT_RETENTION_MS = 86400000;
+export {};

package/dist/orderCollectionAttempt.js

@@ -0,0 +1,71 @@
+/**
+ * Order-collection attempt lookup — the read a client runs when a money write
+ * on an order (a till tender, a seña, an account payment) left it without an
+ * answer: a lost reply, a timeout, or one of the two uncertain refusals
+ * `409 IDEMPOTENCY_IN_PROGRESS` and `409 IDEMPOTENCY_KEY_FAILED`.
+ *
+ * ⚠️ **The attempt's identity is its `Idempotency-Key`, never its `reference`.**
+ * Mint ONE key per collection attempt and keep it for every retry of that
+ * attempt. `reference` keeps its own, narrower meaning as a duplicate-money
+ * guard, and that guard runs ACROSS keys: a tender absorbs a repeat leg
+ * identical on money, method and source that carries the same `reference`
+ * however much later it arrives, OR — neither side carrying a reference — was
+ * recorded by the same user within 30 seconds; a seña absorbs a same-user or
+ * same-`reference` repeat only inside its 30-second replay window (an older
+ * lookalike is `409 DEPOSIT_DUPLICATE_REFERENCE`). So a NEW key is a new
+ * attempt, not a guaranteed new leg: two genuine reference-less handoffs of the
+ * same amount by one cashier inside 30 s land as ONE leg, and the second key
+ * answers `committed` all the same. Give each physical payment its own
+ * `reference` when that distinction matters. Neither guard is an outcome
+ * protocol.
+ *
+ * `POST /orders { mode: 'collection-attempt', operation, orderId, idempotencyKey }`
+ * answers from the write's own idempotency marker, scoped to the CALLER's store
+ * and user. It never claims, replays, reclaims or seals the marker, never
+ * writes the marker or any business row, and calls no provider; a claim it
+ * finds stranded past 60 s logs one deduped operator row.
+ */
+/** Every `operation` the lookup answers for — see `OrderCollectionAttemptLookupRequest`. */
+export const ORDER_COLLECTION_ATTEMPT_OPERATIONS = ['tender', 'deposit', 'account'];
+/** Every `verdict` the lookup answers — see `OrderCollectionAttemptVerdict`. */
+export const ORDER_COLLECTION_ATTEMPT_VERDICTS = ['committed', 'in-progress', 'sealed', 'unknown'];
+/**
+ * Every `reason` on an `unknown` verdict:
+ *
+ * - `NO_EVIDENCE` — no marker under this key for the caller: never sent, sent
+ *   by another user or store, refused or released before it committed,
+ *   already deleted by its retention expiry — or STILL IN FLIGHT and not yet
+ *   claimed. A write holds no marker until its claim lands, and before that
+ *   it can be queued at the gateway, in a cold start, or (a tender) running
+ *   its pre-claim reads. So it is never "not collected": follow the
+ *   `unknown` remedy on `OrderCollectionAttemptVerdict` — resend the same
+ *   body under the same key first.
+ * - `EVIDENCE_EXPIRED` — the marker outlived
+ *   {@link ORDER_COLLECTION_ATTEMPT_RETENTION_MS} and is awaiting deletion,
+ *   which DynamoDB does lazily (up to days late). That is the LOOKUP's
+ *   horizon, not the writer's: the write never reads the expiry, so while
+ *   the row survives a same-key resend still replays a committed `200` (or
+ *   refuses a sealed or stranded key) and does NOT run again. Once DynamoDB
+ *   deletes the row the same resend runs as a new write — so past the
+ *   horizon verify where the operation writes before resending at all.
+ * - `UNBOUND_ATTEMPT` — the key belongs to a write that is not a collection
+ *   attempt (another order mode), or to one admitted before the server
+ *   started recording which collection a key was for.
+ * - `ATTEMPT_MISMATCH` — the key was sent for a different `operation` or
+ *   `orderId` than the lookup names.
+ * - `REFUSED` — the write's cached answer was a refusal (non-`2xx`): nothing
+ *   moved under this key. No collection write caches a refusal today; this
+ *   keeps one that ever does from reading as `committed`.
+ */
+export const ORDER_COLLECTION_ATTEMPT_UNKNOWN_REASONS = [
+    'NO_EVIDENCE',
+    'EVIDENCE_EXPIRED',
+    'UNBOUND_ATTEMPT',
+    'ATTEMPT_MISMATCH',
+    'REFUSED',
+];
+/**
+ * How long the server keeps a collection attempt's evidence: 24 hours — the
+ * write's own idempotency retention. Past it the lookup answers `unknown`.
+ */
+export const ORDER_COLLECTION_ATTEMPT_RETENTION_MS = 86_400_000;

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