platform-types 1.10.715 → 1.10.717

package/dist/auth.d.ts

@@ -326,6 +326,8 @@ declare global {
         accessToken: string;
         /** Transport-conditional exactly as `AuthUser.refreshToken` — absent on the default cookie path. */
         refreshToken?: string;
+        /** As `AuthUser.effectiveCapabilities` — the gate's own answer for the session just issued. */
+        effectiveCapabilities: UserCapability[];
     }
     /**
      * One row of `GET /auth?mode=sessions` — a storefront customer's own

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

@@ -66,8 +66,16 @@ declare global {
      * consumer that models the row as `Omit<User, 'totp'>` throws away the only
      * signal that 2FA is enrolled. Unlike an auth body's `AuthUserTotp`, it
      * carries no `recoveryCodesRemaining`.
+     *
+     * `effectiveCapabilities` is present on the caller's OWN row only — the same
+     * answer as {@link AuthUser.effectiveCapabilities}, resolved from this
+     * request's token roles — and absent on every colleague's row, on the
+     * `POST /users` echo and on the `users` socket frame. A client keeps the list
+     * from its auth body or its own row here; a frame that omits it changes nothing.
      */
-    type PublicUserRow = Omit<User, 'accessToken' | 'search' | 'login' | 'photoData' | 'removePhotoURL' | 'warnings'>;
+    type PublicUserRow = Omit<User, 'accessToken' | 'search' | 'login' | 'photoData' | 'removePhotoURL' | 'warnings'> & {
+        effectiveCapabilities?: UserCapability[];
+    };
     /**
      * Write shape for user create/update — carries the transient photo controls
      * and the plaintext password.
@@ -345,7 +353,31 @@ declare global {
          * Absent/false means no, for a plain USER only.
          */
         percepciones?: boolean;
+        /**
+         * May issue a nota de crédito — `POST /invoices` with `cbte_numero`, and
+         * the retry of a return's credit note (`POST /orders {mode:'return-credit-note'}`).
+         *
+         * ⚠️ **Role-implied** (ADMIN, SUPERVISOR, MANAGER hold it without the flag),
+         * for the reason `percepciones` gives: every elevated operator already issues
+         * NCs, and the granted class would withdraw that on deploy. A plain USER needs
+         * `creditNote: true` on their STORED row together with the server-stamped
+         * grant marker an admin's `POST /users` writes when it turns the flag on; a
+         * flag stored without that marker grants nothing, and nothing in a request
+         * grants it.
+         * Routine factura issuance is NOT gated by it.
+         *
+         * A client never derives this from `roles` — it reads
+         * `AuthUser.effectiveCapabilities`. Absent/false means no, for a plain USER only.
+         */
+        creditNote?: boolean;
     };
+    /**
+     * A key the server's capability gate decides — every `UserPermissions` key
+     * but the reserved, unread `accountant`. A refusal names one in
+     * `403 CAPABILITY_REQUIRED`'s `data.capability`, and
+     * `AuthUser.effectiveCapabilities` lists the ones a session holds.
+     */
+    type UserCapability = Exclude<keyof UserPermissions, 'accountant'>;
     /**
      * Wire error codes for the paths that create or update a USER row:
      * `POST /users` (create AND update — one handler serves both) and
@@ -389,6 +421,24 @@ declare global {
          * absent `totp` means the user never enrolled.
          */
         totp?: AuthUserTotp;
+        /**
+         * The capabilities this session holds, resolved by the SAME server function
+         * that gates each request (`@helpers/capabilityGate`), from the minted
+         * token's roles and the stored `permissions`. Clients read it —
+         * `effectiveCapabilities.includes('creditNote')` — and never compute it
+         * from `roles`, so the role-implied/granted split stays a server decision.
+         *
+         * ⚠️ A snapshot at token issue: a grant changed afterwards is enforced on
+         * the next request at once, but shows here only on the next refresh. A
+         * `403 CAPABILITY_REQUIRED` is the authoritative answer.
+         *
+         * PRINTER and ACCOUNTANT claims carry `[]`: neither is an operator acting on
+         * the store's authority, and the credit-note routes (`POST /invoices` with
+         * `cbte_numero`, the return credit-note retry) refuse them by role before
+         * consulting it. Not every capability-gated route does: `POST /cash` reads a
+         * PRINTER's stored flag.
+         */
+        effectiveCapabilities: UserCapability[];
         /**
          * ⚠️ Delivered in the body ONLY under the body refresh transport — the
          * native-mobile opt-in. The DEFAULT is cookie transport, where the token

package/package.json

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