platform-types 1.10.712 → 1.10.714

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/invoice.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INVOICE_POST_VOUCHER_ERROR_CODES = void 0;
+exports.INVOICE_ISSUANCE_REFUSAL_RECOVERY = exports.INVOICE_ISSUANCE_REFUSAL_CODES = exports.INVOICE_POST_VOUCHER_ERROR_CODES = void 0;
 /**
  * The codes `POST /invoices` answers AFTER a voucher number was spent — ARCA
  * was asked, or a CAEA number was claimed — as a runtime value the app maps.
@@ -32,3 +32,44 @@ exports.INVOICE_POST_VOUCHER_ERROR_CODES = [
     'INVOICE_EXPORT_OUTCOME_UNKNOWN',
     'CAEA_COMMIT_FAILED_AFTER_CLAIM',
 ];
+/**
+ * The codes `POST /invoices` answers when it REFUSED to start an issuance — or
+ * could not confirm it — before any voucher of this request was recorded, as a
+ * runtime value a client maps. Distinct from
+ * {@link INVOICE_POST_VOUCHER_ERROR_CODES}: each has its own recovery, given by
+ * {@link INVOICE_ISSUANCE_REFUSAL_RECOVERY}.
+ *
+ * - `INVOICE_ISSUANCE_IN_PROGRESS` · 409 — another issuance of this order is
+ *   live: the same request's idempotency lock, or another request holding the
+ *   order's factura issuance guard inside its horizon. Also answered after the
+ *   order read, when the guard's owner-conditioned pre-ARCA mark or attempt
+ *   record finds the guard taken over by a successor — before that request's
+ *   submit went on the wire, so it spent nothing. Retry the same body shortly.
+ * - `CAEA_CLAIM_AMBIGUOUS` · 503 — ARCA was down and the CAEA number claim could
+ *   not be confirmed: the claim may have landed (an operator row records it), no
+ *   invoice was recorded and nothing was sent to ARCA, and the request released
+ *   its idempotency record. Retry the same body shortly — a retry claims again,
+ *   so the worst case is one unused CAEA number, never a second voucher.
+ * - `INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH` · 409 — the request's key is bound to
+ *   an issuance with a different voucher-shaping body (or to a record from
+ *   before payload hashing, which matches nothing). It does NOT say a voucher
+ *   exists on the order. Resend only the body that was issued, or credit the
+ *   voucher first.
+ * - `INVOICE_ISSUANCE_OUTCOME_UNCERTAIN` · 409 — an earlier factura of this
+ *   order was interrupted once it may have spent a voucher number, with no
+ *   recorded outcome. `data`
+ *   is {@link InvoiceIssuanceOutcomeUncertainErrorData}. Never retry; support
+ *   reconciles.
+ */
+exports.INVOICE_ISSUANCE_REFUSAL_CODES = [
+    'INVOICE_ISSUANCE_IN_PROGRESS',
+    'CAEA_CLAIM_AMBIGUOUS',
+    'INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH',
+    'INVOICE_ISSUANCE_OUTCOME_UNCERTAIN',
+];
+exports.INVOICE_ISSUANCE_REFUSAL_RECOVERY = {
+    INVOICE_ISSUANCE_IN_PROGRESS: 'retry',
+    CAEA_CLAIM_AMBIGUOUS: 'retry',
+    INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH: 'resend-issued-body',
+    INVOICE_ISSUANCE_OUTCOME_UNCERTAIN: 'reconcile',
+};

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

@@ -837,6 +837,86 @@ declare global {
         /** The fortnight's CAEA code the number was claimed under. */
         CAEA: string;
     }
+    /**
+     * `data` of a `409 INVOICE_ISSUANCE_OUTCOME_UNCERTAIN` answer from
+     * `POST /invoices` (a factura): an earlier issuance of this order was
+     * interrupted once it may have spent a voucher number — a live or WSFEX
+     * submit was recorded, or the outage path (a CAEA stamp or a `pending_cae`
+     * degrade) began — and the server holds no evidence of its outcome: the
+     * order's `invoices[]` does not name the recorded invoice and no
+     * stranded-voucher row names it. ARCA may hold a voucher for it, or may hold
+     * nothing.
+     *
+     * ⚠️ **Never retry, and never resend the original body as proof.** An
+     * unchanged body, a refetched order with no voucher and an elapsed lock are
+     * not evidence the earlier attempt spent nothing. The order stays fenced
+     * until support reconciles the attempt at ARCA and releases it.
+     */
+    interface InvoiceIssuanceOutcomeUncertainErrorData {
+        orderId: string;
+        /** The server's id for the interrupted invoice. No order entry names it. */
+        invoiceId?: string;
+        /**
+         * How the interrupted attempt reached ARCA: `cae` (live FECAESolicitar),
+         * `export` (WSFEX FEXAuthorize) or `outage` (a CAEA stamp or a
+         * `pending_cae` degrade). Written with `invoiceId` and `submittedAt` by
+         * the same mark, so absent only on a row edited by hand.
+         */
+        path?: 'cae' | 'export' | 'outage';
+        /** Epoch ms the interrupted attempt was cleared to contact ARCA. */
+        submittedAt?: number;
+        /**
+         * The voucher the interrupted attempt spent or was about to spend. A
+         * `cae`/`export` answer always carries it — such a row with no recorded
+         * voucher proves no submit went out and is never refused. On `outage` it
+         * is the claimed CAEA number (`kind: 'caea'`) when that best-effort
+         * record landed, or a live submit's voucher (`kind: 'arca'`) when the
+         * outage branch fell through to it; absent, it proves nothing.
+         */
+        voucher?: {
+            /** `arca` — submitted to ARCA (CAE or WSFEX); `caea` — a claimed CAEA number. */
+            kind: 'arca' | 'caea';
+            /** ARCA `CbteTipo` — the voucher class. */
+            CbteTipo: number;
+            /** ARCA `PtoVta` — the punto de venta it went out under. */
+            PtoVta: number;
+            /** ARCA `CbteNro` — the number ARCA may or may not hold. */
+            CbteNro: number;
+            /**
+             * The submitted voucher's `CbteFch` (`yyyymmdd`), when the attempt
+             * recorded one. `fingerprintMatches` compares it too: a voucher found
+             * at the number under another date is not this one.
+             */
+            CbteFch?: string;
+            /**
+             * A live `FECAESolicitar` attempt's identifying fields, as submitted —
+             * compare a `FECompConsultar` answer at the number against these, never
+             * against a rebuild from the order. The receptor's `DocNro` is withheld:
+             * compare it against the order's `invoiceMethod`. Absent on a CAEA claim,
+             * a WSFEX attempt, and an attempt recorded before it was stored.
+             */
+            fingerprint?: InvoiceIssuanceAttemptFingerprint;
+        };
+    }
+    /**
+     * The fields `FECompConsultar` echoes that identify a submitted voucher, as
+     * the interrupted attempt sent them, minus the receptor's `DocNro` and the
+     * date (`CbteFch`, beside it). Amounts are in the voucher currency (`MonId`).
+     */
+    interface InvoiceIssuanceAttemptFingerprint {
+        /** ARCA `DocTipo` — the receptor's document type. */
+        DocTipo: number;
+        /** ARCA `MonId` — the voucher currency code. */
+        MonId: string;
+        /** ARCA `MonCotiz` — the rate the voucher was submitted at. */
+        MonCotiz: number;
+        ImpTotal: number;
+        ImpNeto: number;
+        ImpIVA: number;
+        ImpTotConc: number;
+        ImpOpEx: number;
+        ImpTrib: number;
+    }
 }
 /**
  * The codes `POST /invoices` answers AFTER a voucher number was spent — ARCA
@@ -866,4 +946,50 @@ declare global {
  */
 export declare const INVOICE_POST_VOUCHER_ERROR_CODES: readonly ["INVOICE_PERSIST_AFTER_CAE_FAILED", "INVOICE_EXPORT_OUTCOME_UNKNOWN", "CAEA_COMMIT_FAILED_AFTER_CLAIM"];
 export type InvoicePostVoucherErrorCode = (typeof INVOICE_POST_VOUCHER_ERROR_CODES)[number];
+/**
+ * The codes `POST /invoices` answers when it REFUSED to start an issuance — or
+ * could not confirm it — before any voucher of this request was recorded, as a
+ * runtime value a client maps. Distinct from
+ * {@link INVOICE_POST_VOUCHER_ERROR_CODES}: each has its own recovery, given by
+ * {@link INVOICE_ISSUANCE_REFUSAL_RECOVERY}.
+ *
+ * - `INVOICE_ISSUANCE_IN_PROGRESS` · 409 — another issuance of this order is
+ *   live: the same request's idempotency lock, or another request holding the
+ *   order's factura issuance guard inside its horizon. Also answered after the
+ *   order read, when the guard's owner-conditioned pre-ARCA mark or attempt
+ *   record finds the guard taken over by a successor — before that request's
+ *   submit went on the wire, so it spent nothing. Retry the same body shortly.
+ * - `CAEA_CLAIM_AMBIGUOUS` · 503 — ARCA was down and the CAEA number claim could
+ *   not be confirmed: the claim may have landed (an operator row records it), no
+ *   invoice was recorded and nothing was sent to ARCA, and the request released
+ *   its idempotency record. Retry the same body shortly — a retry claims again,
+ *   so the worst case is one unused CAEA number, never a second voucher.
+ * - `INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH` · 409 — the request's key is bound to
+ *   an issuance with a different voucher-shaping body (or to a record from
+ *   before payload hashing, which matches nothing). It does NOT say a voucher
+ *   exists on the order. Resend only the body that was issued, or credit the
+ *   voucher first.
+ * - `INVOICE_ISSUANCE_OUTCOME_UNCERTAIN` · 409 — an earlier factura of this
+ *   order was interrupted once it may have spent a voucher number, with no
+ *   recorded outcome. `data`
+ *   is {@link InvoiceIssuanceOutcomeUncertainErrorData}. Never retry; support
+ *   reconciles.
+ */
+export declare const INVOICE_ISSUANCE_REFUSAL_CODES: readonly ["INVOICE_ISSUANCE_IN_PROGRESS", "CAEA_CLAIM_AMBIGUOUS", "INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH", "INVOICE_ISSUANCE_OUTCOME_UNCERTAIN"];
+export type InvoiceIssuanceRefusalCode = (typeof INVOICE_ISSUANCE_REFUSAL_CODES)[number];
+/**
+ * What a client may do with each {@link InvoiceIssuanceRefusalCode}:
+ *
+ * - `retry` — resend the same body after a short wait;
+ * - `resend-issued-body` — only the body of the issuance the key is bound to
+ *   (or credit that voucher first); a corrected body is refused again;
+ * - `reconcile` — do not resend at all; the order is fenced until support acts.
+ */
+export type InvoiceIssuanceRecovery = 'retry' | 'resend-issued-body' | 'reconcile';
+export declare const INVOICE_ISSUANCE_REFUSAL_RECOVERY: {
+    readonly INVOICE_ISSUANCE_IN_PROGRESS: "retry";
+    readonly CAEA_CLAIM_AMBIGUOUS: "retry";
+    readonly INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH: "resend-issued-body";
+    readonly INVOICE_ISSUANCE_OUTCOME_UNCERTAIN: "reconcile";
+};
 export {};

package/dist/invoice.js

@@ -29,3 +29,44 @@ export const INVOICE_POST_VOUCHER_ERROR_CODES = [
     'INVOICE_EXPORT_OUTCOME_UNKNOWN',
     'CAEA_COMMIT_FAILED_AFTER_CLAIM',
 ];
+/**
+ * The codes `POST /invoices` answers when it REFUSED to start an issuance — or
+ * could not confirm it — before any voucher of this request was recorded, as a
+ * runtime value a client maps. Distinct from
+ * {@link INVOICE_POST_VOUCHER_ERROR_CODES}: each has its own recovery, given by
+ * {@link INVOICE_ISSUANCE_REFUSAL_RECOVERY}.
+ *
+ * - `INVOICE_ISSUANCE_IN_PROGRESS` · 409 — another issuance of this order is
+ *   live: the same request's idempotency lock, or another request holding the
+ *   order's factura issuance guard inside its horizon. Also answered after the
+ *   order read, when the guard's owner-conditioned pre-ARCA mark or attempt
+ *   record finds the guard taken over by a successor — before that request's
+ *   submit went on the wire, so it spent nothing. Retry the same body shortly.
+ * - `CAEA_CLAIM_AMBIGUOUS` · 503 — ARCA was down and the CAEA number claim could
+ *   not be confirmed: the claim may have landed (an operator row records it), no
+ *   invoice was recorded and nothing was sent to ARCA, and the request released
+ *   its idempotency record. Retry the same body shortly — a retry claims again,
+ *   so the worst case is one unused CAEA number, never a second voucher.
+ * - `INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH` · 409 — the request's key is bound to
+ *   an issuance with a different voucher-shaping body (or to a record from
+ *   before payload hashing, which matches nothing). It does NOT say a voucher
+ *   exists on the order. Resend only the body that was issued, or credit the
+ *   voucher first.
+ * - `INVOICE_ISSUANCE_OUTCOME_UNCERTAIN` · 409 — an earlier factura of this
+ *   order was interrupted once it may have spent a voucher number, with no
+ *   recorded outcome. `data`
+ *   is {@link InvoiceIssuanceOutcomeUncertainErrorData}. Never retry; support
+ *   reconciles.
+ */
+export const INVOICE_ISSUANCE_REFUSAL_CODES = [
+    'INVOICE_ISSUANCE_IN_PROGRESS',
+    'CAEA_CLAIM_AMBIGUOUS',
+    'INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH',
+    'INVOICE_ISSUANCE_OUTCOME_UNCERTAIN',
+];
+export const INVOICE_ISSUANCE_REFUSAL_RECOVERY = {
+    INVOICE_ISSUANCE_IN_PROGRESS: 'retry',
+    CAEA_CLAIM_AMBIGUOUS: 'retry',
+    INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH: 'resend-issued-body',
+    INVOICE_ISSUANCE_OUTCOME_UNCERTAIN: 'reconcile',
+};

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

@@ -846,15 +846,15 @@ export interface TenantBillingRollupRow {
 }
 /**
  * @deprecated Nothing produces one any more. The copy↔entitlement consistency
- * check went with the free-text plan copy it checked, so the `warnings` array
- * on the `POST` / `PATCH /platform/billing/plans` replies is ALWAYS empty. The
- * type stays only so a consumer still naming it compiles; it will be removed
- * together with that array.
+ * check went with the free-text plan copy it checked, and the `warnings` array
+ * that carried its findings is gone from the `POST` / `PATCH
+ * /platform/billing/plans` replies. The type stays only for the archived check
+ * under `stacks/services/_retired/` and for a consumer still naming it.
  */
 export type CatalogWarningCode = 'NUMERIC_MISMATCH' | 'UNLIMITED_ADVERTISED_AS_CAPPED' | 'UNBACKED_CAPABILITY' | 'MISSING_FEATURE_ROW';
 /**
- * @deprecated See {@link CatalogWarningCode} — no writer emits one; the
- * `warnings` array that carried it is always empty.
+ * @deprecated See {@link CatalogWarningCode} — no writer emits one, and no
+ * reply carries a `warnings` array of them any more.
  */
 export interface CatalogWarning {
     code: CatalogWarningCode;
@@ -1053,7 +1053,10 @@ export interface PlatformMrrMetrics {
      * the safer direction for a number an operator acts on.
      */
     countedStatuses: SubscriptionStatus[];
-    /** `priceAnnualCents / annualDivisor` is one annual subscription's monthly contribution. */
+    /**
+     * `priceAnnualCents` is the yearly total charged once per year, so
+     * `priceAnnualCents / annualDivisor` is one annual subscription's monthly contribution.
+     */
     annualDivisor: number;
     /** Subscriptions in a counted status. The denominator for `excluded`. */
     countedSubscriptions: number;

package/dist/subscription.d.ts

@@ -249,7 +249,7 @@ declare global {
      *
      * Prices are integers in the `currency` smallest unit (centavos for ARS,
      * cents for USD). `null` = "Contactar ventas" (AVANZADO annual at launch
-     * is sales-led; basico/fundador are free) per spec §6.4.
+     * is sales-led; basico is free) per spec §6.4.
      *
      * **Breaking change vs 1.1.x:** the catalog Plan interface was reshaped
      * to match the BE wire format. Renames & removals:
@@ -293,7 +293,12 @@ declare global {
         displayOrder: number;
         /** Monthly price in `currency` smallest units. `null` = sales-led / free. */
         priceMonthlyCents: number | null;
-        /** Annual price in `currency` smallest units. `null` = sales-led / free. */
+        /**
+         * The YEARLY TOTAL, charged once per year, in `currency` smallest units —
+         * never a per-month figure. Divide by 12 for a monthly equivalent.
+         * Nothing enforces its ratio to `priceMonthlyCents`; the operator sets
+         * both. `null` = sales-led / free.
+         */
         priceAnnualCents: number | null;
         /**
          * Currency the prices are denominated in. `'ARS'` at launch; `'USD'`
@@ -313,14 +318,6 @@ declare global {
          * `limit`.
          */
         features: PlanFeature[];
-        /**
-         * @deprecated ALWAYS `[]`. The free-text card copy was retired: a plan
-         * card renders {@link Plan.highlights} instead, and no write accepts
-         * `bullets` any more (`POST`/`PATCH /platform/billing/plans` answer 400
-         * `VALIDATION_FAILED`). A value an old row still stores is ignored, never
-         * echoed. The key will be removed once the app's copy editor is gone.
-         */
-        bullets: string[];
         /**
          * Keys worth calling out on this tier's card: highlight-eligible keys with
          * status `live` or `service` whose grant improves on the next lower

package/package.json

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