platform-types 1.10.714 → 1.10.716

package/dist/cjs/delivery.js

@@ -1,2 +1,50 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DELIVERY_ERROR_CODES = void 0;
+/**
+ * Every refusal code the delivery handlers (`POST /deliveries`,
+ * `POST /deliveries/{id}/events`, `GET /deliveries`, `GET /deliveries/{id}`)
+ * put on the wire, beyond the platform-wide set (`VALIDATION_FAILED`,
+ * `ROLE_FORBIDDEN`, `tryCatch`'s generic `UNHANDLED_ERROR`). Pinned against
+ * the handler sources by `tests/unit/deliveryErrorCodesPublished.test.ts`.
+ *
+ * - `INVALID_DELIVERY_ID` · 400 — no delivery id in the path.
+ * - `DELIVERY_NOT_FOUND` · 404 — unknown id, or another tenant's.
+ * - `DELIVERY_NOT_ASSIGNED` · 403 — the delivery names a platform courier
+ *   (`courier.userId`) and the caller is neither that user nor ADMIN-tier.
+ * - `DELIVERY_TERMINAL` · 409 — the delivery is already `'delivered'` or
+ *   `'failed'`; a failed delivery is re-dispatched through `POST /deliveries`.
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — the key is not ≤200 chars of
+ *   `[A-Za-z0-9._:-]`.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — the key was used with a different body.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — the attempt under the key failed after it
+ *   may have written proof, or the attempt lookup fenced the key; ask the
+ *   lookup, then use a new key.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the same key is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — the key's marker could not be
+ *   claimed; retry under the SAME key.
+ * - `INVALID_CURSOR` · 400 — a `?mine=true` `startKey` that is malformed or
+ *   names another store's partition.
+ * - `IMPERSONATION_READONLY` · 403 — the attempt lookup, under a support
+ *   session, could answer only by fencing the key (`op: 'delivery.attemptFence'`).
+ * - `INVALID_BASE64` · 400, `CONTENT_TOO_LARGE` · 413,
+ *   `UNSUPPORTED_MEDIA_TYPE` · 415 — the inline proof payload was refused
+ *   before anything was stored.
+ */
+exports.DELIVERY_ERROR_CODES = [
+    'DELIVERY_NOT_FOUND',
+    'DELIVERY_NOT_ASSIGNED',
+    'DELIVERY_TERMINAL',
+    'INVALID_DELIVERY_ID',
+    'INVALID_IDEMPOTENCY_KEY',
+    'IDEMPOTENCY_KEY_REUSE',
+    'IDEMPOTENCY_KEY_FAILED',
+    'IDEMPOTENCY_IN_PROGRESS',
+    'IDEMPOTENCY_LOCK_CONTENTION',
+    'INVALID_CURSOR',
+    'IMPERSONATION_READONLY',
+    // The proof payload gate (`deliveryAttachmentValidation.ts`).
+    'INVALID_BASE64',
+    'CONTENT_TOO_LARGE',
+    'UNSUPPORTED_MEDIA_TYPE',
+];

package/dist/cjs/index.js

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

package/dist/cjs/order.js

@@ -464,6 +464,22 @@ exports.orderFulfilmentProgress = orderFulfilmentProgress;
  * `IDEMPOTENCY_KEY_FAILED`, ask `POST /orders { mode: 'collection-attempt' }`
  * (`OrderCollectionAttemptVerdict`) — never resend it under a new key first.
  *
+ * Completion-attempt refusals, on `mode: 'delivery'` under an `oc1~`
+ * `Idempotency-Key` (`ORDER_COMPLETION_ATTEMPT_KEY_PATTERN`). A legacy key never
+ * gets either; the key refusals are the create's own `ORDER_ATTEMPT_KEY_EXPIRED`
+ * and `ORDER_ATTEMPT_KEY_SCOPE_MISMATCH` above. ⚠️ On a delivery their remedy is
+ * NOT "mint a new key and resend": the original may have applied, so run
+ * `mode: 'completion-attempt'` on the old key first and send a new attempt only
+ * on `not-written`. Nothing was written on any of them:
+ * - `ORDER_COMPLETION_ATTEMPT_COMMITTED` · 409 — this key's original attempt
+ *   already applied; `data` is the `committed` `OrderCompletionAttemptVerdict`.
+ *   Do not resend.
+ * - `ORDER_COMPLETION_ATTEMPT_ABANDONED` · 409 — a completion-attempt lookup
+ *   fenced this key and answered `not-written`. Re-read the order and send a NEW
+ *   attempt under a NEW key.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — the key's recorded attempt carried a
+ *   different `orderId`, `delivered` or `sendSms`.
+ *
  * Idempotency answers, all six from `withIdempotency`:
  * - `INVALID_IDEMPOTENCY_KEY` · 400 · `IDEMPOTENCY_KEY_REUSE` · 422 (the same
  *   key with a different body)
@@ -613,4 +629,7 @@ exports.ORDER_ERROR_CODES = [
     'ORDER_ATTEMPT_ABANDONED',
     'ORDER_ATTEMPT_KEY_EXPIRED',
     'ORDER_ATTEMPT_KEY_SCOPE_MISMATCH',
+    // `mode: 'delivery'` under an `oc1~` key — see `ORDER_COMPLETION_ATTEMPT_KEY_PATTERN`.
+    'ORDER_COMPLETION_ATTEMPT_COMMITTED',
+    'ORDER_COMPLETION_ATTEMPT_ABANDONED',
 ];

package/dist/cjs/orderCompletionAttempt.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Staff completion attempt evidence — the recovery protocol for
+ * `POST /orders { mode: 'delivery' }` (pickup completion and its same-day
+ * reversal) when the client lost the reply and has to decide whether the
+ * delivery it sent landed before it sends anything again.
+ *
+ * The protocol is opt-in and rides on the `Idempotency-Key` value. A key
+ * matching {@link ORDER_COMPLETION_ATTEMPT_KEY_PATTERN} makes the delivery
+ * write a durable `committed` record IN THE SAME TRANSACTION as the order, the
+ * customer balance and the receivable, bound to the store, the user, the key
+ * and the request (`orderId`, `delivered`, `sendSms`). That record — not the
+ * 24-hour `Idempotency-Key` replay cache — is what keeps the attempt from
+ * applying twice: a same-key resend after the cache is gone, after the order was
+ * un-delivered on another device, or after a crash between the commit and the
+ * reply is refused `409 ORDER_COMPLETION_ATTEMPT_COMMITTED` and writes nothing.
+ * Any other key is a legacy key and behaves exactly as before.
+ *
+ * `POST /orders { mode: 'completion-attempt', attemptKey }` answers for a
+ * protocol key ({@link OrderCompletionAttemptVerdict}).
+ *
+ * The key carries the same scope tag, mint window, clock skew and retention as
+ * the order-create attempt key: `ORDER_ATTEMPT_SCOPE_TAG_LENGTH`,
+ * `ORDER_ATTEMPT_CREATE_WINDOW_MS`, `ORDER_ATTEMPT_CLOCK_SKEW_MS` and
+ * `ORDER_ATTEMPT_RETENTION_MS`. A delivery under a key older than the window,
+ * or minted for another store or user session, is refused before anything is
+ * read or written (`400 ORDER_ATTEMPT_KEY_EXPIRED` /
+ * `400 ORDER_ATTEMPT_KEY_SCOPE_MISMATCH`). ⚠️ Neither says the original did not
+ * apply: before sending again under a new key, look the OLD key up — the
+ * lookup answers from the record for the whole retention, past the window —
+ * and resend only on `not-written`.
+ *
+ * What a client does with each outcome:
+ *
+ * - `200` — applied now. Done.
+ * - `409 ORDER_COMPLETION_ATTEMPT_COMMITTED` or a `committed` verdict — the
+ *   ORIGINAL attempt applied; `data` names the order, the leg (`delivered`) and
+ *   `committedAt`, which is also the `updatedAt` that write stamped. Done:
+ *   refresh the order, never resend. The order may have moved since (an
+ *   un-delivery on the web is a later, separate write).
+ * - `pending` — the original is still running. Ask again after `retryAfterMs`.
+ * - `not-written` or `409 ORDER_COMPLETION_ATTEMPT_ABANDONED` — the attempt
+ *   never applied and never will. A resend is allowed only as a NEW attempt:
+ *   re-read the order, then send under a NEW key.
+ * - `unknown` — the server cannot decide. Never treat it as `not-written` and
+ *   never resend automatically; the operator verifies the order first.
+ *
+ * ⚠️ `409 ORDER_DELIVERY_STATE_UNCHANGED`, a missing list row or an absent
+ * replay are NOT evidence of either outcome; only the codes and verdicts above
+ * are.
+ *
+ * ⚠️ A backend that predates this protocol refuses a protocol key with
+ * `400 INVALID_IDEMPOTENCY_KEY` before writing anything (`~` is outside the
+ * legacy key grammar). Do not mint protocol keys against a backend that has not
+ * shipped it: every delivery would fail, safely but entirely.
+ *
+ * The staff READY mark is a field edit (`POST /orders` with `readyAt` and
+ * `expectedUpdatedAt`), not this protocol: its `expectedUpdatedAt` is a frozen
+ * version precondition, so a resend of the same frozen body can never apply
+ * over a later change of the order — it is refused `409 ORDER_VERSION_CONFLICT`.
+ * ⚠️ Only when the token is sent: it is optional, and a ready mark without it
+ * is pinned to the server's own read at resend time, so a token-less resend
+ * after a later un-ready marks the order ready again. Send `expectedUpdatedAt`
+ * with every ready mark a client may resend.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORDER_COMPLETION_ATTEMPT_UNKNOWN_REASONS = exports.ORDER_COMPLETION_ATTEMPT_VERDICTS = exports.ORDER_COMPLETION_ATTEMPT_KEY_PREFIX = exports.ORDER_COMPLETION_ATTEMPT_KEY_PATTERN = void 0;
+/**
+ * The completion attempt key: `oc1~<mintMs>~<scopeTag>~<nonce>` — the
+ * order-create grammar under its own version tag, so neither route accepts the
+ * other's key. `mintMs` is 13 digits of epoch milliseconds, `scopeTag` is
+ * `ORDER_ATTEMPT_SCOPE_TAG_LENGTH` base64url characters computed exactly as for
+ * the create key, and `nonce` is 16 to 64 base64url characters.
+ *
+ * Mint ONE key per completion attempt and keep it, with the same body, for
+ * every resend of that attempt; a new key is a new attempt.
+ *
+ * A string, not a `RegExp`, and it carries no flags.
+ */
+exports.ORDER_COMPLETION_ATTEMPT_KEY_PATTERN = '^oc1~\\d{13}~[A-Za-z0-9_-]{12}~[A-Za-z0-9_-]{16,64}$';
+/** The version tag every completion attempt key starts with. */
+exports.ORDER_COMPLETION_ATTEMPT_KEY_PREFIX = 'oc1~';
+/** Every `verdict` a completion-attempt lookup answers — see `OrderCompletionAttemptVerdict`. */
+exports.ORDER_COMPLETION_ATTEMPT_VERDICTS = ['committed', 'pending', 'not-written', 'unknown'];
+/**
+ * Every `reason` on an `unknown` verdict — the same four, with the same
+ * meaning, as the order-create lookup's.
+ */
+exports.ORDER_COMPLETION_ATTEMPT_UNKNOWN_REASONS = [
+    'LEGACY_KEY',
+    'SCOPE_MISMATCH',
+    'EVIDENCE_EXPIRED',
+    'KEY_CLOCK_AHEAD',
+];

package/dist/delivery.d.ts

@@ -84,8 +84,9 @@ declare global {
     }
     /**
      * One append-only entry in a delivery's timeline. Never overwritten and never
-     * deleted: a correction is a NEW event, so a `'delivered'` later contradicted
-     * by a `'failed'` leaves both on the record.
+     * deleted. `'delivered'` and `'failed'` are TERMINAL: nothing is appended
+     * after either (`409 DELIVERY_TERMINAL`), and a failed delivery is
+     * re-dispatched as a new delivery through `POST /deliveries`.
      *
      * PK `DELIVERY#{storeId}#{deliveryId}`, SK `EVENT#{createdAt}#{eventId}` —
      * the storeId segment is load-bearing, exactly as it is for `CashEvent`:
@@ -108,6 +109,18 @@ declare global {
         proof?: DeliveryProofAsset[];
         /** Set only on a `'failed'` event. */
         failureReason?: DeliveryFailureReason;
+        /**
+         * The `Idempotency-Key` the actor appended this event under — what lets a
+         * client match its own attempt exactly instead of guessing from type, time
+         * or photo count.
+         *
+         * ⚠️ Actor-scoped on the wire: `GET /deliveries/{id}` returns it only when
+         * the reader is this event's `actorUserId` or an ADMIN-tier role, and omits
+         * it otherwise. Absent on an event appended WITHOUT a key (still accepted —
+         * see `DeliveryEventAppendRequest`), on one written before keys existed, and
+         * on the opening `'assigned'` event `POST /deliveries` writes.
+         */
+        idempotencyKey?: string;
     }
     /**
      * A `DeliveryProofAsset` carrying the read-time-only `downloadUrl` minted by
@@ -126,5 +139,125 @@ declare global {
     type DeliveryEventWithProofUrls = Omit<DeliveryEvent, 'proof'> & {
         proof?: DeliveryProofAssetWithUrl[];
     };
+    /**
+     * Body of `POST /deliveries/{id}/events`. The `Idempotency-Key` header is
+     * OPTIONAL for now and strongly recommended — the key, not the body, is what
+     * makes a retry safe. It becomes REQUIRED in a later change, once the courier
+     * app sends it.
+     *
+     * ⚠️ WITHOUT a key the append is NOT idempotent: every call writes a new
+     * event, so a resend after a lost response records the event twice. Same
+     * validation, assignee scoping and terminal refusal; no replay protection and
+     * no attempt lookup.
+     *
+     * WITH a key, resend the SAME key with the byte-identical body after a lost
+     * response: a committed attempt answers its original event
+     * (`Idempotent-Replayed: true`), a changed body under that key is
+     * `422 IDEMPOTENCY_KEY_REUSE`.
+     *
+     * A transient fault answers `tryCatch`'s generic `400 UNHANDLED_ERROR`. A
+     * same-key resend then replays the attempt if it committed, RE-RUNS only if
+     * DynamoDB cancelled its transaction (nothing applied), and otherwise answers
+     * `409 IDEMPOTENCY_KEY_FAILED` — the attempt may have stored proof or
+     * committed, so the key is sealed. On that 409, ask
+     * `GET /deliveries/{id}?idempotencyKey=` (`DeliveryEventAttemptLookup`) and
+     * mint a new key only when it answers `'not-committed'`.
+     *
+     * The server sets `actorUserId`, `createdAt`, `gps.receivedAt` and the proof
+     * object keys; none of them is accepted here.
+     *
+     * Held to its schema by `AssertDeliveryEventAppendRequestMatchesSchema`.
+     */
+    interface DeliveryEventAppendRequest {
+        type: DeliveryEventType;
+        /** ≤ 1000 characters. */
+        note?: string;
+        gps?: Omit<DeliveryGpsFix, 'receivedAt'>;
+        /**
+         * Inline base64 proof, at most 5 assets (`MAX_PROOF_ASSETS_PER_EVENT`). Stored
+         * under a name derived from the delivery, the key, the asset's position and
+         * its bytes, written create-only — a retry can never replace an object.
+         */
+        proof?: Array<{
+            kind: DeliveryProofAsset['kind'];
+            contentType: string;
+            data: string;
+        }>;
+        /** Only on a `'failed'` event — anything else is `400 VALIDATION_FAILED`. */
+        failureReason?: DeliveryFailureReason;
+    }
+    /**
+     * What `GET /deliveries/{id}?idempotencyKey=<key>` answers about the
+     * CALLER'S OWN attempt under that key on THAT delivery — the authoritative
+     * recovery read, unlike the bounded (`truncated`) timeline, which can never
+     * prove absence.
+     *
+     * - `'committed'` — the attempt's event exists; `event` is that exact
+     *   original. Never append again for it.
+     * - `'pending'` — a request under the key is still in flight. Re-ask after
+     *   `retryAfterMs`; nothing was fenced.
+     * - `'not-committed'` — nothing was appended under the key, and the key is
+     *   FENCED: a durable tombstone (written by this read, or an earlier one, at
+     *   `fencedAt`) makes every later commit under it refuse. Only now may the
+     *   client mint a NEW key for the same intent; the old key answers
+     *   `409 IDEMPOTENCY_KEY_FAILED` forever.
+     *
+     * ⚠️ This read can WRITE: when the key is neither committed nor in flight it
+     * writes the tombstone before answering `'not-committed'`, so asking is itself
+     * a decision to give the key up. A client that would rather keep it resends
+     * under the same key instead.
+     *
+     * Attempt evidence is durable (no TTL), so both `'committed'` and
+     * `'not-committed'` stay answerable for the life of the delivery.
+     *
+     * The lookup takes the append's own authority bar: on a delivery that names
+     * a platform courier, a caller who is neither that courier nor ADMIN-tier is
+     * `403 DELIVERY_NOT_ASSIGNED`, before anything is read or written. Under an
+     * impersonated support session it answers only from stored state, and is
+     * `403 IMPERSONATION_READONLY` (`op: 'delivery.attemptFence'`) exactly where
+     * answering would need the tombstone.
+     */
+    interface DeliveryEventAttemptLookup {
+        idempotencyKey: string;
+        verdict: 'committed' | 'pending' | 'not-committed';
+        /** Present only on `'committed'`. */
+        event?: DeliveryEventWithProofUrls;
+        /** Present only on `'pending'`. */
+        retryAfterMs?: number;
+        /** Present only on `'not-committed'` — ms epoch the tombstone was written. */
+        fencedAt?: number;
+    }
 }
+/**
+ * Every refusal code the delivery handlers (`POST /deliveries`,
+ * `POST /deliveries/{id}/events`, `GET /deliveries`, `GET /deliveries/{id}`)
+ * put on the wire, beyond the platform-wide set (`VALIDATION_FAILED`,
+ * `ROLE_FORBIDDEN`, `tryCatch`'s generic `UNHANDLED_ERROR`). Pinned against
+ * the handler sources by `tests/unit/deliveryErrorCodesPublished.test.ts`.
+ *
+ * - `INVALID_DELIVERY_ID` · 400 — no delivery id in the path.
+ * - `DELIVERY_NOT_FOUND` · 404 — unknown id, or another tenant's.
+ * - `DELIVERY_NOT_ASSIGNED` · 403 — the delivery names a platform courier
+ *   (`courier.userId`) and the caller is neither that user nor ADMIN-tier.
+ * - `DELIVERY_TERMINAL` · 409 — the delivery is already `'delivered'` or
+ *   `'failed'`; a failed delivery is re-dispatched through `POST /deliveries`.
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — the key is not ≤200 chars of
+ *   `[A-Za-z0-9._:-]`.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — the key was used with a different body.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — the attempt under the key failed after it
+ *   may have written proof, or the attempt lookup fenced the key; ask the
+ *   lookup, then use a new key.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the same key is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — the key's marker could not be
+ *   claimed; retry under the SAME key.
+ * - `INVALID_CURSOR` · 400 — a `?mine=true` `startKey` that is malformed or
+ *   names another store's partition.
+ * - `IMPERSONATION_READONLY` · 403 — the attempt lookup, under a support
+ *   session, could answer only by fencing the key (`op: 'delivery.attemptFence'`).
+ * - `INVALID_BASE64` · 400, `CONTENT_TOO_LARGE` · 413,
+ *   `UNSUPPORTED_MEDIA_TYPE` · 415 — the inline proof payload was refused
+ *   before anything was stored.
+ */
+export declare const DELIVERY_ERROR_CODES: readonly ["DELIVERY_NOT_FOUND", "DELIVERY_NOT_ASSIGNED", "DELIVERY_TERMINAL", "INVALID_DELIVERY_ID", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_KEY_FAILED", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "INVALID_CURSOR", "IMPERSONATION_READONLY", "INVALID_BASE64", "CONTENT_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE"];
+export type DeliveryErrorCode = (typeof DELIVERY_ERROR_CODES)[number];
 export {};

package/dist/delivery.js

@@ -1 +1,47 @@
-export {};
+/**
+ * Every refusal code the delivery handlers (`POST /deliveries`,
+ * `POST /deliveries/{id}/events`, `GET /deliveries`, `GET /deliveries/{id}`)
+ * put on the wire, beyond the platform-wide set (`VALIDATION_FAILED`,
+ * `ROLE_FORBIDDEN`, `tryCatch`'s generic `UNHANDLED_ERROR`). Pinned against
+ * the handler sources by `tests/unit/deliveryErrorCodesPublished.test.ts`.
+ *
+ * - `INVALID_DELIVERY_ID` · 400 — no delivery id in the path.
+ * - `DELIVERY_NOT_FOUND` · 404 — unknown id, or another tenant's.
+ * - `DELIVERY_NOT_ASSIGNED` · 403 — the delivery names a platform courier
+ *   (`courier.userId`) and the caller is neither that user nor ADMIN-tier.
+ * - `DELIVERY_TERMINAL` · 409 — the delivery is already `'delivered'` or
+ *   `'failed'`; a failed delivery is re-dispatched through `POST /deliveries`.
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — the key is not ≤200 chars of
+ *   `[A-Za-z0-9._:-]`.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — the key was used with a different body.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — the attempt under the key failed after it
+ *   may have written proof, or the attempt lookup fenced the key; ask the
+ *   lookup, then use a new key.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the same key is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — the key's marker could not be
+ *   claimed; retry under the SAME key.
+ * - `INVALID_CURSOR` · 400 — a `?mine=true` `startKey` that is malformed or
+ *   names another store's partition.
+ * - `IMPERSONATION_READONLY` · 403 — the attempt lookup, under a support
+ *   session, could answer only by fencing the key (`op: 'delivery.attemptFence'`).
+ * - `INVALID_BASE64` · 400, `CONTENT_TOO_LARGE` · 413,
+ *   `UNSUPPORTED_MEDIA_TYPE` · 415 — the inline proof payload was refused
+ *   before anything was stored.
+ */
+export const DELIVERY_ERROR_CODES = [
+    'DELIVERY_NOT_FOUND',
+    'DELIVERY_NOT_ASSIGNED',
+    'DELIVERY_TERMINAL',
+    'INVALID_DELIVERY_ID',
+    'INVALID_IDEMPOTENCY_KEY',
+    'IDEMPOTENCY_KEY_REUSE',
+    'IDEMPOTENCY_KEY_FAILED',
+    'IDEMPOTENCY_IN_PROGRESS',
+    'IDEMPOTENCY_LOCK_CONTENTION',
+    'INVALID_CURSOR',
+    'IMPERSONATION_READONLY',
+    // The proof payload gate (`deliveryAttachmentValidation.ts`).
+    'INVALID_BASE64',
+    'CONTENT_TOO_LARGE',
+    'UNSUPPORTED_MEDIA_TYPE',
+];

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/order.d.ts

@@ -2702,6 +2702,22 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  * `IDEMPOTENCY_KEY_FAILED`, ask `POST /orders { mode: 'collection-attempt' }`
  * (`OrderCollectionAttemptVerdict`) — never resend it under a new key first.
  *
+ * Completion-attempt refusals, on `mode: 'delivery'` under an `oc1~`
+ * `Idempotency-Key` (`ORDER_COMPLETION_ATTEMPT_KEY_PATTERN`). A legacy key never
+ * gets either; the key refusals are the create's own `ORDER_ATTEMPT_KEY_EXPIRED`
+ * and `ORDER_ATTEMPT_KEY_SCOPE_MISMATCH` above. ⚠️ On a delivery their remedy is
+ * NOT "mint a new key and resend": the original may have applied, so run
+ * `mode: 'completion-attempt'` on the old key first and send a new attempt only
+ * on `not-written`. Nothing was written on any of them:
+ * - `ORDER_COMPLETION_ATTEMPT_COMMITTED` · 409 — this key's original attempt
+ *   already applied; `data` is the `committed` `OrderCompletionAttemptVerdict`.
+ *   Do not resend.
+ * - `ORDER_COMPLETION_ATTEMPT_ABANDONED` · 409 — a completion-attempt lookup
+ *   fenced this key and answered `not-written`. Re-read the order and send a NEW
+ *   attempt under a NEW key.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — the key's recorded attempt carried a
+ *   different `orderId`, `delivered` or `sendSms`.
+ *
  * Idempotency answers, all six from `withIdempotency`:
  * - `INVALID_IDEMPOTENCY_KEY` · 400 · `IDEMPOTENCY_KEY_REUSE` · 422 (the same
  *   key with a different body)
@@ -2723,6 +2739,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", "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 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", "ORDER_COMPLETION_ATTEMPT_COMMITTED", "ORDER_COMPLETION_ATTEMPT_ABANDONED"];
 export type OrderErrorCode = (typeof ORDER_ERROR_CODES)[number];
 export {};

package/dist/order.js

@@ -457,6 +457,22 @@ export const orderFulfilmentProgress = (order) => {
  * `IDEMPOTENCY_KEY_FAILED`, ask `POST /orders { mode: 'collection-attempt' }`
  * (`OrderCollectionAttemptVerdict`) — never resend it under a new key first.
  *
+ * Completion-attempt refusals, on `mode: 'delivery'` under an `oc1~`
+ * `Idempotency-Key` (`ORDER_COMPLETION_ATTEMPT_KEY_PATTERN`). A legacy key never
+ * gets either; the key refusals are the create's own `ORDER_ATTEMPT_KEY_EXPIRED`
+ * and `ORDER_ATTEMPT_KEY_SCOPE_MISMATCH` above. ⚠️ On a delivery their remedy is
+ * NOT "mint a new key and resend": the original may have applied, so run
+ * `mode: 'completion-attempt'` on the old key first and send a new attempt only
+ * on `not-written`. Nothing was written on any of them:
+ * - `ORDER_COMPLETION_ATTEMPT_COMMITTED` · 409 — this key's original attempt
+ *   already applied; `data` is the `committed` `OrderCompletionAttemptVerdict`.
+ *   Do not resend.
+ * - `ORDER_COMPLETION_ATTEMPT_ABANDONED` · 409 — a completion-attempt lookup
+ *   fenced this key and answered `not-written`. Re-read the order and send a NEW
+ *   attempt under a NEW key.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — the key's recorded attempt carried a
+ *   different `orderId`, `delivered` or `sendSms`.
+ *
  * Idempotency answers, all six from `withIdempotency`:
  * - `INVALID_IDEMPOTENCY_KEY` · 400 · `IDEMPOTENCY_KEY_REUSE` · 422 (the same
  *   key with a different body)
@@ -606,4 +622,7 @@ export const ORDER_ERROR_CODES = [
     'ORDER_ATTEMPT_ABANDONED',
     'ORDER_ATTEMPT_KEY_EXPIRED',
     'ORDER_ATTEMPT_KEY_SCOPE_MISMATCH',
+    // `mode: 'delivery'` under an `oc1~` key — see `ORDER_COMPLETION_ATTEMPT_KEY_PATTERN`.
+    'ORDER_COMPLETION_ATTEMPT_COMMITTED',
+    'ORDER_COMPLETION_ATTEMPT_ABANDONED',
 ];

package/dist/orderCompletionAttempt.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Staff completion attempt evidence — the recovery protocol for
+ * `POST /orders { mode: 'delivery' }` (pickup completion and its same-day
+ * reversal) when the client lost the reply and has to decide whether the
+ * delivery it sent landed before it sends anything again.
+ *
+ * The protocol is opt-in and rides on the `Idempotency-Key` value. A key
+ * matching {@link ORDER_COMPLETION_ATTEMPT_KEY_PATTERN} makes the delivery
+ * write a durable `committed` record IN THE SAME TRANSACTION as the order, the
+ * customer balance and the receivable, bound to the store, the user, the key
+ * and the request (`orderId`, `delivered`, `sendSms`). That record — not the
+ * 24-hour `Idempotency-Key` replay cache — is what keeps the attempt from
+ * applying twice: a same-key resend after the cache is gone, after the order was
+ * un-delivered on another device, or after a crash between the commit and the
+ * reply is refused `409 ORDER_COMPLETION_ATTEMPT_COMMITTED` and writes nothing.
+ * Any other key is a legacy key and behaves exactly as before.
+ *
+ * `POST /orders { mode: 'completion-attempt', attemptKey }` answers for a
+ * protocol key ({@link OrderCompletionAttemptVerdict}).
+ *
+ * The key carries the same scope tag, mint window, clock skew and retention as
+ * the order-create attempt key: `ORDER_ATTEMPT_SCOPE_TAG_LENGTH`,
+ * `ORDER_ATTEMPT_CREATE_WINDOW_MS`, `ORDER_ATTEMPT_CLOCK_SKEW_MS` and
+ * `ORDER_ATTEMPT_RETENTION_MS`. A delivery under a key older than the window,
+ * or minted for another store or user session, is refused before anything is
+ * read or written (`400 ORDER_ATTEMPT_KEY_EXPIRED` /
+ * `400 ORDER_ATTEMPT_KEY_SCOPE_MISMATCH`). ⚠️ Neither says the original did not
+ * apply: before sending again under a new key, look the OLD key up — the
+ * lookup answers from the record for the whole retention, past the window —
+ * and resend only on `not-written`.
+ *
+ * What a client does with each outcome:
+ *
+ * - `200` — applied now. Done.
+ * - `409 ORDER_COMPLETION_ATTEMPT_COMMITTED` or a `committed` verdict — the
+ *   ORIGINAL attempt applied; `data` names the order, the leg (`delivered`) and
+ *   `committedAt`, which is also the `updatedAt` that write stamped. Done:
+ *   refresh the order, never resend. The order may have moved since (an
+ *   un-delivery on the web is a later, separate write).
+ * - `pending` — the original is still running. Ask again after `retryAfterMs`.
+ * - `not-written` or `409 ORDER_COMPLETION_ATTEMPT_ABANDONED` — the attempt
+ *   never applied and never will. A resend is allowed only as a NEW attempt:
+ *   re-read the order, then send under a NEW key.
+ * - `unknown` — the server cannot decide. Never treat it as `not-written` and
+ *   never resend automatically; the operator verifies the order first.
+ *
+ * ⚠️ `409 ORDER_DELIVERY_STATE_UNCHANGED`, a missing list row or an absent
+ * replay are NOT evidence of either outcome; only the codes and verdicts above
+ * are.
+ *
+ * ⚠️ A backend that predates this protocol refuses a protocol key with
+ * `400 INVALID_IDEMPOTENCY_KEY` before writing anything (`~` is outside the
+ * legacy key grammar). Do not mint protocol keys against a backend that has not
+ * shipped it: every delivery would fail, safely but entirely.
+ *
+ * The staff READY mark is a field edit (`POST /orders` with `readyAt` and
+ * `expectedUpdatedAt`), not this protocol: its `expectedUpdatedAt` is a frozen
+ * version precondition, so a resend of the same frozen body can never apply
+ * over a later change of the order — it is refused `409 ORDER_VERSION_CONFLICT`.
+ * ⚠️ Only when the token is sent: it is optional, and a ready mark without it
+ * is pinned to the server's own read at resend time, so a token-less resend
+ * after a later un-ready marks the order ready again. Send `expectedUpdatedAt`
+ * with every ready mark a client may resend.
+ */
+declare global {
+    /** One of {@link ORDER_COMPLETION_ATTEMPT_VERDICTS}. */
+    type OrderCompletionAttemptVerdictKind = (typeof ORDER_COMPLETION_ATTEMPT_VERDICTS)[number];
+    /** Why a lookup could not decide — one of {@link ORDER_COMPLETION_ATTEMPT_UNKNOWN_REASONS}. */
+    type OrderCompletionAttemptUnknownReason = (typeof ORDER_COMPLETION_ATTEMPT_UNKNOWN_REASONS)[number];
+    /**
+     * `POST /orders` body for the recovery lookup. `attemptKey` is the exact
+     * `Idempotency-Key` the delivery was sent with; the store and user are the
+     * caller's session. Safe to repeat, but `pending` is a moment in time: ask
+     * again after `retryAfterMs` and never cache it. `committed`, `not-written`
+     * and every `unknown` reason but `KEY_CLOCK_AHEAD` are final.
+     */
+    interface OrderCompletionAttemptLookupRequest {
+        mode: 'completion-attempt';
+        attemptKey: string;
+    }
+    /**
+     * `data` of a `200` from `POST /orders { mode: 'completion-attempt' }`, and
+     * `data` of a `409 ORDER_COMPLETION_ATTEMPT_COMMITTED` (always the
+     * `committed` member there).
+     *
+     * - `committed` — the delivery (`delivered: true`) or un-delivery
+     *   (`delivered: false`) of `orderId` applied under this key at
+     *   `committedAt` (epoch ms, the `updatedAt` it stamped on the order).
+     * - `pending` — still running; ask again after `retryAfterMs`.
+     * - `not-written` — nothing applied under this key and nothing ever will:
+     *   the lookup fenced it at `fencedAt`. Resend under a NEW key.
+     * - `unknown` — undecidable; `reason` says why. Intervention, never a resend.
+     */
+    type OrderCompletionAttemptVerdict = {
+        verdict: Extract<OrderCompletionAttemptVerdictKind, 'committed'>;
+        orderId: string;
+        delivered: boolean;
+        committedAt: number;
+    } | {
+        verdict: Extract<OrderCompletionAttemptVerdictKind, 'pending'>;
+        retryAfterMs: number;
+    } | {
+        verdict: Extract<OrderCompletionAttemptVerdictKind, 'not-written'>;
+        fencedAt: number;
+    } | {
+        verdict: Extract<OrderCompletionAttemptVerdictKind, 'unknown'>;
+        reason: OrderCompletionAttemptUnknownReason;
+    };
+}
+/**
+ * The completion attempt key: `oc1~<mintMs>~<scopeTag>~<nonce>` — the
+ * order-create grammar under its own version tag, so neither route accepts the
+ * other's key. `mintMs` is 13 digits of epoch milliseconds, `scopeTag` is
+ * `ORDER_ATTEMPT_SCOPE_TAG_LENGTH` base64url characters computed exactly as for
+ * the create key, and `nonce` is 16 to 64 base64url characters.
+ *
+ * Mint ONE key per completion attempt and keep it, with the same body, for
+ * every resend of that attempt; a new key is a new attempt.
+ *
+ * A string, not a `RegExp`, and it carries no flags.
+ */
+export declare const ORDER_COMPLETION_ATTEMPT_KEY_PATTERN = "^oc1~\\d{13}~[A-Za-z0-9_-]{12}~[A-Za-z0-9_-]{16,64}$";
+/** The version tag every completion attempt key starts with. */
+export declare const ORDER_COMPLETION_ATTEMPT_KEY_PREFIX = "oc1~";
+/** Every `verdict` a completion-attempt lookup answers — see `OrderCompletionAttemptVerdict`. */
+export declare const ORDER_COMPLETION_ATTEMPT_VERDICTS: readonly ["committed", "pending", "not-written", "unknown"];
+/**
+ * Every `reason` on an `unknown` verdict — the same four, with the same
+ * meaning, as the order-create lookup's.
+ */
+export declare const ORDER_COMPLETION_ATTEMPT_UNKNOWN_REASONS: readonly ["LEGACY_KEY", "SCOPE_MISMATCH", "EVIDENCE_EXPIRED", "KEY_CLOCK_AHEAD"];
+export {};

package/dist/orderCompletionAttempt.js

@@ -0,0 +1,91 @@
+/**
+ * Staff completion attempt evidence — the recovery protocol for
+ * `POST /orders { mode: 'delivery' }` (pickup completion and its same-day
+ * reversal) when the client lost the reply and has to decide whether the
+ * delivery it sent landed before it sends anything again.
+ *
+ * The protocol is opt-in and rides on the `Idempotency-Key` value. A key
+ * matching {@link ORDER_COMPLETION_ATTEMPT_KEY_PATTERN} makes the delivery
+ * write a durable `committed` record IN THE SAME TRANSACTION as the order, the
+ * customer balance and the receivable, bound to the store, the user, the key
+ * and the request (`orderId`, `delivered`, `sendSms`). That record — not the
+ * 24-hour `Idempotency-Key` replay cache — is what keeps the attempt from
+ * applying twice: a same-key resend after the cache is gone, after the order was
+ * un-delivered on another device, or after a crash between the commit and the
+ * reply is refused `409 ORDER_COMPLETION_ATTEMPT_COMMITTED` and writes nothing.
+ * Any other key is a legacy key and behaves exactly as before.
+ *
+ * `POST /orders { mode: 'completion-attempt', attemptKey }` answers for a
+ * protocol key ({@link OrderCompletionAttemptVerdict}).
+ *
+ * The key carries the same scope tag, mint window, clock skew and retention as
+ * the order-create attempt key: `ORDER_ATTEMPT_SCOPE_TAG_LENGTH`,
+ * `ORDER_ATTEMPT_CREATE_WINDOW_MS`, `ORDER_ATTEMPT_CLOCK_SKEW_MS` and
+ * `ORDER_ATTEMPT_RETENTION_MS`. A delivery under a key older than the window,
+ * or minted for another store or user session, is refused before anything is
+ * read or written (`400 ORDER_ATTEMPT_KEY_EXPIRED` /
+ * `400 ORDER_ATTEMPT_KEY_SCOPE_MISMATCH`). ⚠️ Neither says the original did not
+ * apply: before sending again under a new key, look the OLD key up — the
+ * lookup answers from the record for the whole retention, past the window —
+ * and resend only on `not-written`.
+ *
+ * What a client does with each outcome:
+ *
+ * - `200` — applied now. Done.
+ * - `409 ORDER_COMPLETION_ATTEMPT_COMMITTED` or a `committed` verdict — the
+ *   ORIGINAL attempt applied; `data` names the order, the leg (`delivered`) and
+ *   `committedAt`, which is also the `updatedAt` that write stamped. Done:
+ *   refresh the order, never resend. The order may have moved since (an
+ *   un-delivery on the web is a later, separate write).
+ * - `pending` — the original is still running. Ask again after `retryAfterMs`.
+ * - `not-written` or `409 ORDER_COMPLETION_ATTEMPT_ABANDONED` — the attempt
+ *   never applied and never will. A resend is allowed only as a NEW attempt:
+ *   re-read the order, then send under a NEW key.
+ * - `unknown` — the server cannot decide. Never treat it as `not-written` and
+ *   never resend automatically; the operator verifies the order first.
+ *
+ * ⚠️ `409 ORDER_DELIVERY_STATE_UNCHANGED`, a missing list row or an absent
+ * replay are NOT evidence of either outcome; only the codes and verdicts above
+ * are.
+ *
+ * ⚠️ A backend that predates this protocol refuses a protocol key with
+ * `400 INVALID_IDEMPOTENCY_KEY` before writing anything (`~` is outside the
+ * legacy key grammar). Do not mint protocol keys against a backend that has not
+ * shipped it: every delivery would fail, safely but entirely.
+ *
+ * The staff READY mark is a field edit (`POST /orders` with `readyAt` and
+ * `expectedUpdatedAt`), not this protocol: its `expectedUpdatedAt` is a frozen
+ * version precondition, so a resend of the same frozen body can never apply
+ * over a later change of the order — it is refused `409 ORDER_VERSION_CONFLICT`.
+ * ⚠️ Only when the token is sent: it is optional, and a ready mark without it
+ * is pinned to the server's own read at resend time, so a token-less resend
+ * after a later un-ready marks the order ready again. Send `expectedUpdatedAt`
+ * with every ready mark a client may resend.
+ */
+/**
+ * The completion attempt key: `oc1~<mintMs>~<scopeTag>~<nonce>` — the
+ * order-create grammar under its own version tag, so neither route accepts the
+ * other's key. `mintMs` is 13 digits of epoch milliseconds, `scopeTag` is
+ * `ORDER_ATTEMPT_SCOPE_TAG_LENGTH` base64url characters computed exactly as for
+ * the create key, and `nonce` is 16 to 64 base64url characters.
+ *
+ * Mint ONE key per completion attempt and keep it, with the same body, for
+ * every resend of that attempt; a new key is a new attempt.
+ *
+ * A string, not a `RegExp`, and it carries no flags.
+ */
+export const ORDER_COMPLETION_ATTEMPT_KEY_PATTERN = '^oc1~\\d{13}~[A-Za-z0-9_-]{12}~[A-Za-z0-9_-]{16,64}$';
+/** The version tag every completion attempt key starts with. */
+export const ORDER_COMPLETION_ATTEMPT_KEY_PREFIX = 'oc1~';
+/** Every `verdict` a completion-attempt lookup answers — see `OrderCompletionAttemptVerdict`. */
+export const ORDER_COMPLETION_ATTEMPT_VERDICTS = ['committed', 'pending', 'not-written', 'unknown'];
+/**
+ * Every `reason` on an `unknown` verdict — the same four, with the same
+ * meaning, as the order-create lookup's.
+ */
+export const ORDER_COMPLETION_ATTEMPT_UNKNOWN_REASONS = [
+    'LEGACY_KEY',
+    'SCOPE_MISMATCH',
+    'EVIDENCE_EXPIRED',
+    'KEY_CLOCK_AHEAD',
+];

package/package.json

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