platform-types 1.10.815 → 1.10.816

package/dist/audit.d.ts

@@ -177,6 +177,30 @@ declare global {
      * `holdReason`. `after`: `obligationId`, `state`, `refundDueAt?` and the reason by presence only.
      */
      | 'refund_obligation_reopened'
+    /**
+     * A purchase withdrawal was requested on the order (`POST /orders/purchase-withdrawal`, origin
+     * `customer`). `after`: `withdrawalId`, `state` (`'requested'`), `source`, `wholeOrder`,
+     * `lineCount`, `amount`, `currency`, `windowClosesAt?`.
+     */
+     | 'purchase_withdrawal_requested'
+    /**
+     * An operator relayed a purchase withdrawal the store received by email or WhatsApp
+     * (`POST /purchase-withdrawals { mode: 'relay' }`). `after`: as `purchase_withdrawal_requested`,
+     * plus `channel`, `receivedAt`, `codeMintedLate` and the operator's note as `'[present]'` |
+     * `'[absent]'` — presence only, the words stay on the withdrawal.
+     */
+     | 'purchase_withdrawal_relayed'
+    /**
+     * An operator accepted a purchase withdrawal (`POST /purchase-withdrawals { mode: 'accept' }`).
+     * `before`/`after`: `withdrawalId`, `state`, `revision`.
+     */
+     | 'purchase_withdrawal_accepted'
+    /**
+     * An operator declined a purchase withdrawal (`POST /purchase-withdrawals { mode: 'decline' }`).
+     * `before`/`after`: `withdrawalId`, `state`, `revision`; `after` adds the typed `declineReason` and
+     * the note as `'[present]'` | `'[absent]'` — presence only, the words stay on the withdrawal.
+     */
+     | 'purchase_withdrawal_declined'
     /** HISTORICAL: written only by the removed outbound MercadoPago refund; kept so old timeline rows still parse. */
      | 'payment_refunded'
     /** At least one till tender leg was appended (an absorbed replay writes none). */

package/dist/cjs/index.js

@@ -91,6 +91,7 @@ __exportStar(require("./productBulkEdit.js"), exports);
 __exportStar(require("./productDuplicate.js"), exports);
 __exportStar(require("./productGroup.js"), exports);
 __exportStar(require("./purchaseOrder.js"), exports);
+__exportStar(require("./purchaseWithdrawal.js"), exports);
 __exportStar(require("./purchaseReceipt.js"), exports);
 __exportStar(require("./pushDevice.js"), exports);
 __exportStar(require("./refundObligation.js"), exports);

package/dist/cjs/purchaseWithdrawal.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Purchase withdrawals — the shopper's statutory right to withdraw from a
+ * distance purchase (*arrepentimiento*), as a record of its own.
+ *
+ * A withdrawal is a REQUEST with an identification code (`withdrawalId`, `ARR`
+ * plus 6–10 digits), a window and a decision. It never moves stock or money by
+ * itself: once accepted, the order's own cancellation (before fulfilment) or a
+ * return (after it) does, and the money owed back is a {@link RefundObligation}
+ * whose `parentId` is the `withdrawalId`.
+ *
+ * Naming: "withdrawal" alone already names the guest-telemetry consent
+ * withdrawal and `cash.withdrawal` on the till, so every name here carries the
+ * `PurchaseWithdrawal` / `purchaseWithdrawal` stem.
+ *
+ * ⚠️ The stored row carries one main-table index-key attribute on purpose,
+ * `customerId` (the order's customer when the request was made, a guest row's
+ * id for a guest order), so the customer erasure finds it through the existing
+ * `PK-customerId` read. It carries none of the others: `state` replaces
+ * `status`, `revisedAt` replaces `updatedAt`, and there is no `dated`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PURCHASE_WITHDRAWAL_CODE_DUE_MS = exports.PURCHASE_WITHDRAWAL_CODE_DUE_SOURCE = exports.PURCHASE_WITHDRAWAL_WINDOW_SOURCE = exports.PURCHASE_WITHDRAWAL_WINDOW_DAYS = exports.PURCHASE_WITHDRAWAL_LINES_MAX = exports.PURCHASE_WITHDRAWAL_NOTE_MAX = exports.PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = exports.PURCHASE_WITHDRAWAL_ACTION_MODES = exports.PURCHASE_WITHDRAWAL_RELAY_CHANNELS = exports.PURCHASE_WITHDRAWAL_DECLINE_REASONS = exports.PURCHASE_WITHDRAWAL_SOURCES = exports.PURCHASE_WITHDRAWAL_LIST_FILTERS = exports.PURCHASE_WITHDRAWAL_STATES = void 0;
+/**
+ * - `requested` — submitted, the code minted, the order's dispatch locked
+ *   (`purchase-withdrawal-pending`) until an operator decides.
+ * - `declined` — an operator declined it with a typed exemption reason.
+ *   Terminal.
+ * - `accepted` — an operator accepted it. The order's cancellation (before
+ *   fulfilment) or its return authorisation (after it) follows from here.
+ * - `awaiting-goods` — after fulfilment, the goods are on their way back.
+ * - `refund-pending` — money is owed back (an open refund obligation).
+ * - `completed` — nothing is owed any more. Not final while money can still
+ *   arrive: a late capture moves it back to `refund-pending`.
+ */
+exports.PURCHASE_WITHDRAWAL_STATES = [
+    'requested',
+    'declined',
+    'accepted',
+    'awaiting-goods',
+    'refund-pending',
+    'completed',
+];
+/**
+ * The `state` filter of `GET /purchase-withdrawals`: one state, or `open` —
+ * every state but `declined` and `completed`.
+ */
+exports.PURCHASE_WITHDRAWAL_LIST_FILTERS = [...exports.PURCHASE_WITHDRAWAL_STATES, 'open'];
+/** `shopper` — the storefront form; `operator-relay` — an operator recording a request received by email or WhatsApp. */
+exports.PURCHASE_WITHDRAWAL_SOURCES = ['shopper', 'operator-relay'];
+/**
+ * The only reasons an operator may decline a request, each backed by a row of
+ * the consumer-commerce applicability matrix: made to order or personalised,
+ * quick deterioration, unsealed media or software, periodicals, a used
+ * product, perishables, and a purchase made for resale or production.
+ */
+exports.PURCHASE_WITHDRAWAL_DECLINE_REASONS = [
+    'exempt-custom-made',
+    'exempt-quick-deterioration',
+    'exempt-unsealed-media',
+    'exempt-periodical',
+    'exempt-used-product',
+    'exempt-perishable',
+    'resale-purchase',
+];
+/** Where a relayed request reached the store. */
+exports.PURCHASE_WITHDRAWAL_RELAY_CHANNELS = ['email', 'whatsapp'];
+/** The modes of `POST /purchase-withdrawals`. */
+exports.PURCHASE_WITHDRAWAL_ACTION_MODES = ['accept', 'decline', 'relay'];
+/**
+ * Why a request is refused `409 PURCHASE_WITHDRAWAL_INELIGIBLE` (`data.reason`):
+ *
+ * - `order-cancelled` — the order is cancelled or disabled.
+ * - `no-customer` — the order names no customer (a relay on a walk-in sale).
+ * - `partial-before-fulfilment` — `lines` were named on an order not yet
+ *   delivered or shipped; before fulfilment a withdrawal is the whole order.
+ * - `line-not-on-order` — a named line is not a goods line of the order.
+ * - `line-unavailable` — a named line (or quantity) is already in another
+ *   withdrawal that was not declined, in an open return authorisation, or
+ *   already returned (`data.orderItemIndex`).
+ * - `nothing-to-withdraw` — every line is already withdrawn or returned.
+ */
+exports.PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = [
+    'order-cancelled',
+    'no-customer',
+    'partial-before-fulfilment',
+    'line-not-on-order',
+    'line-unavailable',
+    'nothing-to-withdraw',
+];
+/** The longest decline or relay `note`, in characters after trimming. */
+exports.PURCHASE_WITHDRAWAL_NOTE_MAX = 500;
+/** The most lines one request may name. */
+exports.PURCHASE_WITHDRAWAL_LINES_MAX = 100;
+/** Calendar days of the withdrawal window after the later of delivery and purchase. */
+exports.PURCHASE_WITHDRAWAL_WINDOW_DAYS = 10;
+/** The matrix row {@link PurchaseWithdrawal.windowClosesAt} is computed from. */
+exports.PURCHASE_WITHDRAWAL_WINDOW_SOURCE = 'W2';
+/** The matrix row a relayed request's `codeDueAt` (24 hours after it was received) comes from. */
+exports.PURCHASE_WITHDRAWAL_CODE_DUE_SOURCE = 'W1';
+/** How long after a relayed request was received its code is due, in ms. */
+exports.PURCHASE_WITHDRAWAL_CODE_DUE_MS = 24 * 60 * 60 * 1000;

package/dist/cjs/socket.js

@@ -543,6 +543,27 @@ exports.SOCKET_ACTIONS = [
      * a customer socket: the shopper's own frame is `orderPaymentAttempt`.
      */
     'paymentAttemptChanged',
+    /**
+     * A storefront order's purchase withdrawal was requested or decided. `data`
+     * is `OrderPurchaseWithdrawalFrameData` (`purchaseWithdrawal.ts`) — the order
+     * id and the shopper's `OrderPurchaseWithdrawalView`, never the operator's
+     * notes.
+     *
+     * ⚠️ To the order's OWN customer only (`wsPostCustomer`), never a store-wide
+     * customer broadcast. The operator frame for the same write is
+     * `purchaseWithdrawalChanged`.
+     */
+    'orderPurchaseWithdrawal',
+    /**
+     * A purchase withdrawal was requested, relayed or decided. `data` is the
+     * `PurchaseWithdrawal` record as `GET /purchase-withdrawals` answers it.
+     *
+     * ⚠️ OPERATOR sockets of the store only, and ADMIN tier only (`wsPostStore`
+     * with `audience: 'operator'` and `lowTierData: null`): it carries the
+     * customer id and the operator's notes. The shopper's own frame is
+     * `orderPurchaseWithdrawal`.
+     */
+    'purchaseWithdrawalChanged',
     'stripe',
     'subscription',
     // Fiscal.

package/dist/customer.d.ts

@@ -1355,7 +1355,7 @@ declare global {
      * many operator notes existed about them, and minus the RMA reason counts,
      * for the same reason (the rejection reasons are operator-written).
      */
-    type WebAnonymizeCustomerResult = Omit<AnonymizeCustomerResult, 'notesErased' | 'notesEraseComplete' | 'rmaReasonsErased' | 'rmaEraseComplete'> & {
+    type WebAnonymizeCustomerResult = Omit<AnonymizeCustomerResult, 'notesErased' | 'notesEraseComplete' | 'rmaReasonsErased' | 'rmaEraseComplete' | 'purchaseWithdrawalNotesErased' | 'purchaseWithdrawalEraseComplete'> & {
         /**
          * `false` until the store's analytics events about the subject are erased
          * and verified — what folds the request's retention job to `completed`
@@ -1626,6 +1626,21 @@ declare global {
          * (`WebAnonymizeCustomerResult`).
          */
         rmaEraseComplete: boolean;
+        /**
+         * `PURCHASE_WITHDRAWAL#` rows of this customer (or of an id folded into it, a
+         * guest row an attach merged in included) whose operator notes (`declineNote`,
+         * `relay.note`) this erasure REMOVEd. The withdrawal itself is kept, with its
+         * ids and amounts — it is the record of a consumer right exercised. Operator
+         * wire only. Optional only so the field is additive.
+         */
+        purchaseWithdrawalNotesErased?: number;
+        /**
+         * `false` when those rows could not be read or written to the end, so a note
+         * may remain. Re-issuing the erasure re-runs the step; BOTH erasure handlers
+         * write a deduped `ERROR` row (`CUSTOMER_ANONYMIZE_PURCHASE_WITHDRAWAL_INCOMPLETE`).
+         * Operator wire only — the storefront response omits both.
+         */
+        purchaseWithdrawalEraseComplete?: boolean;
         /**
          * Storefront quote requests the subject sent signed in
          * (`QUOTEREQUEST#{storeId}`), DELETED by this erasure — the whole row goes:

package/dist/index.d.ts

@@ -67,6 +67,7 @@ export * from './productBulkEdit.ts';
 export * from './productDuplicate.ts';
 export * from './productGroup.ts';
 export * from './purchaseOrder.ts';
+export * from './purchaseWithdrawal.ts';
 export * from './purchaseReceipt.ts';
 export * from './pushDevice.ts';
 export * from './refundObligation.ts';

package/dist/index.js

@@ -75,6 +75,7 @@ export * from "./productBulkEdit.js";
 export * from "./productDuplicate.js";
 export * from "./productGroup.js";
 export * from "./purchaseOrder.js";
+export * from "./purchaseWithdrawal.js";
 export * from "./purchaseReceipt.js";
 export * from "./pushDevice.js";
 export * from "./refundObligation.js";

package/dist/order.d.ts

@@ -1270,6 +1270,20 @@ declare global {
         /** Who cancelled: the customerId for a self-cancellation, the operator's userId for an operator cancellation. */
         cancelledBy?: string;
         cancellationSource?: OrderCancellationSource;
+        /**
+         * The purchase withdrawal awaiting an operator's decision, while there is
+         * one (`POST /orders/purchase-withdrawal`, or an operator's relay). Server-
+         * owned: written in the request's transaction and removed in the
+         * decision's. Its presence is the `purchase-withdrawal-pending` dispatch
+         * lock; `GET /purchase-withdrawals?orderId=` reads the request itself.
+         */
+        purchaseWithdrawalPending?: OrderPurchaseWithdrawalPending;
+        /**
+         * How many purchase withdrawals were ever requested on the order. Server-
+         * owned: every request pins it and bumps it, so two requests on one order
+         * never commit off the same read.
+         */
+        purchaseWithdrawalCount?: number;
         /** Bounded free text supplied by the canceller. */
         cancellationReason?: string;
         mercadolibreCreditNote?: {
@@ -1389,6 +1403,12 @@ declare global {
      *   A voucher with no `fiscalStatus` at all is legacy and counts as live.
      * - `payment-linked` — `linkedPayments` is non-empty. The platform never
      *   unlinks or refunds a provider payment on the operator's behalf.
+     * - `purchase-withdrawal-pending` — `purchaseWithdrawalPending` is set: the
+     *   shopper asked to withdraw from the purchase and no operator has decided
+     *   yet. The DISPATCH lock: marking the order ready (or clearing the mark),
+     *   delivering it and shipping it are refused until the request is decided,
+     *   so a dispatch cannot race a withdrawal before fulfilment. Last in the
+     *   order, so every other reason reports first.
      *
      * ⚠️ As a FIRST match this list rarely reports `cancelled`: both dead-state
      * writers stamp `readyAt`, so `ready` wins on `mode: 'edit'`. The rank pays
@@ -1396,7 +1416,7 @@ declare global {
      * the single-field legs (`mode: 'delivery'`, `'return'`) test
      * `cancelled` ahead of `disabled` explicitly for the same reason.
      */
-    type OrderLockReason = 'ready' | 'delivered' | 'disabled' | 'invoiced' | 'payment-linked' | 'cancelled';
+    type OrderLockReason = 'ready' | 'delivered' | 'disabled' | 'invoiced' | 'payment-linked' | 'cancelled' | 'purchase-withdrawal-pending';
     /**
      * FULFILMENT axis of the order state model: where the goods are.
      *

package/dist/paymentAttempt.d.ts

@@ -126,12 +126,16 @@ declare global {
     /**
      * The shopper's own order read: the order plus its payment attempt, when it
      * has one, and where its delivery stands (`OrderDeliveryView`, `delivery.ts`),
-     * when there is anything to show. Both are attached on read and never stored
-     * on the order.
+     * when there is anything to show. Also its purchase withdrawals, newest
+     * first (`purchaseWithdrawal.ts`), when it has any, and whether the
+     * withdrawal window is open. Each is attached on read and never stored on
+     * the order.
      */
     type StorefrontOrderView = Order & {
         paymentAttempt?: OrderPaymentAttemptView;
         delivery?: OrderDeliveryView;
+        purchaseWithdrawals?: OrderPurchaseWithdrawalView[];
+        purchaseWithdrawalEligibility?: OrderPurchaseWithdrawalEligibility;
     };
     /**
      * `data` of an `orderPaymentAttempt` socket frame, sent to the order's own

package/dist/platform.d.ts

@@ -26,6 +26,7 @@ export interface PlatformConfigEntry extends Partial<StorefrontRegistryMetadata>
     max?: number;
     integer?: true;
     calendarDay?: true;
+    calendarDayList?: true;
     nonDecreasing?: true;
     maxLength?: number;
     allowedValues?: string[];

package/dist/purchaseWithdrawal.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Purchase withdrawals — the shopper's statutory right to withdraw from a
+ * distance purchase (*arrepentimiento*), as a record of its own.
+ *
+ * A withdrawal is a REQUEST with an identification code (`withdrawalId`, `ARR`
+ * plus 6–10 digits), a window and a decision. It never moves stock or money by
+ * itself: once accepted, the order's own cancellation (before fulfilment) or a
+ * return (after it) does, and the money owed back is a {@link RefundObligation}
+ * whose `parentId` is the `withdrawalId`.
+ *
+ * Naming: "withdrawal" alone already names the guest-telemetry consent
+ * withdrawal and `cash.withdrawal` on the till, so every name here carries the
+ * `PurchaseWithdrawal` / `purchaseWithdrawal` stem.
+ *
+ * ⚠️ The stored row carries one main-table index-key attribute on purpose,
+ * `customerId` (the order's customer when the request was made, a guest row's
+ * id for a guest order), so the customer erasure finds it through the existing
+ * `PK-customerId` read. It carries none of the others: `state` replaces
+ * `status`, `revisedAt` replaces `updatedAt`, and there is no `dated`.
+ */
+/**
+ * - `requested` — submitted, the code minted, the order's dispatch locked
+ *   (`purchase-withdrawal-pending`) until an operator decides.
+ * - `declined` — an operator declined it with a typed exemption reason.
+ *   Terminal.
+ * - `accepted` — an operator accepted it. The order's cancellation (before
+ *   fulfilment) or its return authorisation (after it) follows from here.
+ * - `awaiting-goods` — after fulfilment, the goods are on their way back.
+ * - `refund-pending` — money is owed back (an open refund obligation).
+ * - `completed` — nothing is owed any more. Not final while money can still
+ *   arrive: a late capture moves it back to `refund-pending`.
+ */
+export declare const PURCHASE_WITHDRAWAL_STATES: readonly ["requested", "declined", "accepted", "awaiting-goods", "refund-pending", "completed"];
+/**
+ * The `state` filter of `GET /purchase-withdrawals`: one state, or `open` —
+ * every state but `declined` and `completed`.
+ */
+export declare const PURCHASE_WITHDRAWAL_LIST_FILTERS: readonly ["requested", "declined", "accepted", "awaiting-goods", "refund-pending", "completed", "open"];
+/** `shopper` — the storefront form; `operator-relay` — an operator recording a request received by email or WhatsApp. */
+export declare const PURCHASE_WITHDRAWAL_SOURCES: readonly ["shopper", "operator-relay"];
+/**
+ * The only reasons an operator may decline a request, each backed by a row of
+ * the consumer-commerce applicability matrix: made to order or personalised,
+ * quick deterioration, unsealed media or software, periodicals, a used
+ * product, perishables, and a purchase made for resale or production.
+ */
+export declare const PURCHASE_WITHDRAWAL_DECLINE_REASONS: readonly ["exempt-custom-made", "exempt-quick-deterioration", "exempt-unsealed-media", "exempt-periodical", "exempt-used-product", "exempt-perishable", "resale-purchase"];
+/** Where a relayed request reached the store. */
+export declare const PURCHASE_WITHDRAWAL_RELAY_CHANNELS: readonly ["email", "whatsapp"];
+/** The modes of `POST /purchase-withdrawals`. */
+export declare const PURCHASE_WITHDRAWAL_ACTION_MODES: readonly ["accept", "decline", "relay"];
+/**
+ * Why a request is refused `409 PURCHASE_WITHDRAWAL_INELIGIBLE` (`data.reason`):
+ *
+ * - `order-cancelled` — the order is cancelled or disabled.
+ * - `no-customer` — the order names no customer (a relay on a walk-in sale).
+ * - `partial-before-fulfilment` — `lines` were named on an order not yet
+ *   delivered or shipped; before fulfilment a withdrawal is the whole order.
+ * - `line-not-on-order` — a named line is not a goods line of the order.
+ * - `line-unavailable` — a named line (or quantity) is already in another
+ *   withdrawal that was not declined, in an open return authorisation, or
+ *   already returned (`data.orderItemIndex`).
+ * - `nothing-to-withdraw` — every line is already withdrawn or returned.
+ */
+export declare const PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS: readonly ["order-cancelled", "no-customer", "partial-before-fulfilment", "line-not-on-order", "line-unavailable", "nothing-to-withdraw"];
+/** The longest decline or relay `note`, in characters after trimming. */
+export declare const PURCHASE_WITHDRAWAL_NOTE_MAX = 500;
+/** The most lines one request may name. */
+export declare const PURCHASE_WITHDRAWAL_LINES_MAX = 100;
+/** Calendar days of the withdrawal window after the later of delivery and purchase. */
+export declare const PURCHASE_WITHDRAWAL_WINDOW_DAYS = 10;
+/** The matrix row {@link PurchaseWithdrawal.windowClosesAt} is computed from. */
+export declare const PURCHASE_WITHDRAWAL_WINDOW_SOURCE = "W2";
+/** The matrix row a relayed request's `codeDueAt` (24 hours after it was received) comes from. */
+export declare const PURCHASE_WITHDRAWAL_CODE_DUE_SOURCE = "W1";
+/** How long after a relayed request was received its code is due, in ms. */
+export declare const PURCHASE_WITHDRAWAL_CODE_DUE_MS: number;
+declare global {
+    type PurchaseWithdrawalState = (typeof PURCHASE_WITHDRAWAL_STATES)[number];
+    type PurchaseWithdrawalSource = (typeof PURCHASE_WITHDRAWAL_SOURCES)[number];
+    type PurchaseWithdrawalDeclineReason = (typeof PURCHASE_WITHDRAWAL_DECLINE_REASONS)[number];
+    type PurchaseWithdrawalRelayChannel = (typeof PURCHASE_WITHDRAWAL_RELAY_CHANNELS)[number];
+    type PurchaseWithdrawalActionMode = (typeof PURCHASE_WITHDRAWAL_ACTION_MODES)[number];
+    type PurchaseWithdrawalIneligibleReason = (typeof PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS)[number];
+    /** One withdrawn order line, by its index in `Order.items`. */
+    interface PurchaseWithdrawalLine {
+        orderItemIndex: number;
+        quantity: number;
+    }
+    /**
+     * How the identification code reached the shopper. `shownAt` is when the
+     * `201` carried it on screen (the same medium as the request); the
+     * `purchase-withdrawal-received` mail is queued after the commit and
+     * stamps `emailQueuedAt`, and the mail worker records `emailStatus`:
+     * `sent`, or `not-sent` when the order's customer has no address to mail
+     * or the send was refused for good (a suppressed address included).
+     */
+    interface PurchaseWithdrawalAcknowledgement {
+        /** Unix ms. */
+        shownAt: number;
+        /** Unix ms. */
+        emailQueuedAt?: number;
+        emailStatus?: 'sent' | 'not-sent';
+    }
+    /**
+     * A request an operator relayed from another channel. `codeDueAt` is
+     * `receivedAt` + 24 hours (`W1`); `codeMintedLate` is `true` when the code
+     * was minted after it.
+     */
+    interface PurchaseWithdrawalRelay {
+        channel: PurchaseWithdrawalRelayChannel;
+        /** Unix ms — when the shopper's message reached the store. */
+        receivedAt: number;
+        codeDueAt: StatutoryInstant;
+        codeMintedLate: boolean;
+        /** The operator's own words. Removed by a customer erasure; never in an audit row. */
+        note?: string;
+    }
+    /** Who decided a request, and when. */
+    interface PurchaseWithdrawalDecision {
+        /** `operator` — `POST /purchase-withdrawals`; `auto` — accepted with nothing to undo (reserved). */
+        by: 'operator' | 'auto';
+        /** Unix ms. */
+        at: number;
+        /** The store user, for `operator`. */
+        actor?: string;
+    }
+    /**
+     * A purchase withdrawal: `PURCHASE_WITHDRAWAL#{storeId}` / SK
+     * `{orderId}#{withdrawalId}`, no `ttl` (evidence of a consumer right
+     * exercised). One request per order can be undecided at a time.
+     */
+    interface PurchaseWithdrawal {
+        /** The identification code: `ARR` + 6–10 digits. */
+        withdrawalId: string;
+        orderId: string;
+        /** The order's customer when the request was made (a guest row's id for a guest order). */
+        customerId: string;
+        state: PurchaseWithdrawalState;
+        source: PurchaseWithdrawalSource;
+        /**
+         * `true` when the request is for the whole order — always before
+         * fulfilment, and after it when no lines were named.
+         */
+        wholeOrder: boolean;
+        /** The withdrawn lines and quantities, never freight (a later return decides freight). */
+        lines: PurchaseWithdrawalLine[];
+        /** What the withdrawn lines were charged, in `currency` (the order total for a whole-order request). */
+        amount: number;
+        currency: string;
+        /** Unix ms — when the request was made (`relay.receivedAt` for a relay). */
+        requestedAt: number;
+        /**
+         * The end of the window the request was judged against, when the order
+         * was delivered (source `W2`). Absent before delivery: the window was open.
+         */
+        windowClosesAt?: StatutoryInstant;
+        relay?: PurchaseWithdrawalRelay;
+        /** For a `shopper` request. */
+        acknowledgement?: PurchaseWithdrawalAcknowledgement;
+        /** Set by the move out of `requested`. */
+        decision?: PurchaseWithdrawalDecision;
+        /** Set by a decline. */
+        declineReason?: PurchaseWithdrawalDeclineReason;
+        /** The operator's own words on a decline. Removed by a customer erasure; never in an audit row. */
+        declineNote?: string;
+        /** Bumped by every move, for a compare-and-set. */
+        revision: number;
+        /** Unix ms. */
+        createdAt: number;
+        /** Unix ms of the last move. */
+        revisedAt: number;
+    }
+    /**
+     * The undecided request an order carries, stamped on the ORDER row while
+     * the request is `requested` and removed in the decision's transaction. Its
+     * presence is the dispatch lock (`OrderLockReason`
+     * `purchase-withdrawal-pending`).
+     */
+    interface OrderPurchaseWithdrawalPending {
+        withdrawalId: string;
+        /** Unix ms. */
+        requestedAt: number;
+    }
+    /** One refund owed on a withdrawal, as the shopper sees it — one per refund obligation. */
+    interface OrderPurchaseWithdrawalRefundView {
+        /** `pending` — owed (`open` or `overdue`, or awaiting the goods); `in-review` — held by a dispute; `refunded` — closed. */
+        state: 'pending' | 'in-review' | 'refunded';
+        amount: number;
+        currency: string;
+        /** Unix ms — when it is due, while `pending` with a due date. */
+        dueAt?: number;
+        /** Unix ms — when it was closed. */
+        refundedAt?: number;
+    }
+    /**
+     * A withdrawal as its shopper sees it, on `StorefrontOrderView` and in the
+     * `orderPurchaseWithdrawal` socket frame. Never the operator's notes.
+     */
+    interface OrderPurchaseWithdrawalView {
+        /** The identification code. */
+        withdrawalId: string;
+        state: PurchaseWithdrawalState;
+        /** Unix ms. */
+        requestedAt: number;
+        wholeOrder: boolean;
+        lines: PurchaseWithdrawalLine[];
+        declineReason?: PurchaseWithdrawalDeclineReason;
+        /** One per refund obligation of this withdrawal, when there is any. */
+        refunds?: OrderPurchaseWithdrawalRefundView[];
+    }
+    /**
+     * Whether the shopper may submit a withdrawal for the order now. `open` is
+     * the window alone (not the lines); `windowClosesAt` is set once the order
+     * was delivered.
+     */
+    interface OrderPurchaseWithdrawalEligibility {
+        open: boolean;
+        /** Unix ms. */
+        windowClosesAt?: number;
+    }
+    /** `data` of an `orderPurchaseWithdrawal` socket frame, sent to the order's own customer on each change. */
+    interface OrderPurchaseWithdrawalFrameData {
+        orderId: string;
+        purchaseWithdrawal: OrderPurchaseWithdrawalView;
+    }
+    /**
+     * `POST /orders/purchase-withdrawal` (Web host, `customerToken`). Strict body.
+     * `lines` names the lines to withdraw after fulfilment; absent, the request is
+     * for every line still withdrawable. Before fulfilment it must be absent.
+     */
+    interface PurchaseWithdrawalSubmitRequest {
+        /** `ORD` + 6–10 digits. */
+        orderId: string;
+        /** 1–{@link PURCHASE_WITHDRAWAL_LINES_MAX} distinct lines, each with a positive quantity. */
+        lines?: PurchaseWithdrawalLine[];
+    }
+    /** `data` of the `201` of `POST /orders/purchase-withdrawal`: the code is `purchaseWithdrawal.withdrawalId`. */
+    interface PurchaseWithdrawalSubmitResponse {
+        purchaseWithdrawal: OrderPurchaseWithdrawalView;
+    }
+    /** `data` of `409 PURCHASE_WITHDRAWAL_ALREADY_REQUESTED`: the undecided request's code. */
+    interface PurchaseWithdrawalAlreadyRequestedData {
+        withdrawalId: string;
+    }
+    /** `data` of `409 PURCHASE_WITHDRAWAL_WINDOW_CLOSED`. */
+    interface PurchaseWithdrawalWindowClosedData {
+        /** Unix ms. */
+        windowClosesAt: number;
+        source: 'W2';
+    }
+    /** `data` of `409 PURCHASE_WITHDRAWAL_INELIGIBLE`. */
+    interface PurchaseWithdrawalIneligibleData {
+        reason: PurchaseWithdrawalIneligibleReason;
+        /** The line refused, for `line-not-on-order` and `line-unavailable`. */
+        orderItemIndex?: number;
+    }
+    /** One of {@link PURCHASE_WITHDRAWAL_LIST_FILTERS}. */
+    type PurchaseWithdrawalListFilter = (typeof PURCHASE_WITHDRAWAL_LIST_FILTERS)[number];
+    /**
+     * The query of `GET /purchase-withdrawals` (App host, `staffToken`). Reads the
+     * token's store only, in `{orderId}#{withdrawalId}` order.
+     */
+    interface PurchaseWithdrawalListQuery {
+        state?: PurchaseWithdrawalListFilter;
+        /** Only this order's withdrawals (`ORD` + 6–10 digits), by key. */
+        orderId?: string;
+        /** Rows EVALUATED per page, 1–100 (default 25): a page can be short or empty with `nextCursor` present. */
+        limit?: number;
+        /** The previous page's `nextCursor`, bound to the store and to `state` + `orderId`. */
+        cursor?: string;
+    }
+    /** `data` of `GET /purchase-withdrawals`. Page on `nextCursor`'s presence, never on the page's length. */
+    interface PurchaseWithdrawalListResponse {
+        purchaseWithdrawals: PurchaseWithdrawal[];
+        /** Opaque. Absent on the last page. */
+        nextCursor?: string;
+    }
+    /**
+     * `POST /purchase-withdrawals` (App host, `adminToken`). Strict body.
+     *
+     * - `accept` / `decline` — decide a `requested` withdrawal under
+     *   `expectedRevision` (the `revision` the operator acted on). A decline
+     *   names one {@link PurchaseWithdrawalDeclineReason} and may carry a note.
+     *   Both release the order's dispatch lock in the same transaction.
+     * - `relay` — record a request the store received by email or WhatsApp and
+     *   mint its code, which the operator then sends on that channel.
+     */
+    type PurchaseWithdrawalActionRequest = {
+        mode: 'accept';
+        orderId: string;
+        withdrawalId: string;
+        expectedRevision: number;
+    } | {
+        mode: 'decline';
+        orderId: string;
+        withdrawalId: string;
+        expectedRevision: number;
+        reason: PurchaseWithdrawalDeclineReason;
+        /** 1–{@link PURCHASE_WITHDRAWAL_NOTE_MAX} characters after trimming. */
+        note?: string;
+    } | {
+        mode: 'relay';
+        orderId: string;
+        channel: PurchaseWithdrawalRelayChannel;
+        /** Unix ms, not in the future. */
+        receivedAt: number;
+        /** As on the shopper's request. */
+        lines?: PurchaseWithdrawalLine[];
+        /** 1–{@link PURCHASE_WITHDRAWAL_NOTE_MAX} characters after trimming. */
+        note?: string;
+    };
+    /**
+     * `data` of a successful `POST /purchase-withdrawals`: the withdrawal as it
+     * now stands. For `relay` (`201`) its `withdrawalId` is the code to send.
+     */
+    interface PurchaseWithdrawalActionResponse {
+        purchaseWithdrawal: PurchaseWithdrawal;
+    }
+    /** `data` of `409 PURCHASE_WITHDRAWAL_ALREADY_DECIDED`: the decision that stands. */
+    interface PurchaseWithdrawalAlreadyDecidedData {
+        state: PurchaseWithdrawalState;
+        decision?: PurchaseWithdrawalDecision;
+        declineReason?: PurchaseWithdrawalDeclineReason;
+    }
+    /** `data` of `409 PURCHASE_WITHDRAWAL_CHANGED`: the withdrawal as it now stands — review it and resend. */
+    interface PurchaseWithdrawalChangedData {
+        purchaseWithdrawal: PurchaseWithdrawal;
+    }
+}
+export {};

package/dist/purchaseWithdrawal.js

@@ -0,0 +1,99 @@
+/**
+ * Purchase withdrawals — the shopper's statutory right to withdraw from a
+ * distance purchase (*arrepentimiento*), as a record of its own.
+ *
+ * A withdrawal is a REQUEST with an identification code (`withdrawalId`, `ARR`
+ * plus 6–10 digits), a window and a decision. It never moves stock or money by
+ * itself: once accepted, the order's own cancellation (before fulfilment) or a
+ * return (after it) does, and the money owed back is a {@link RefundObligation}
+ * whose `parentId` is the `withdrawalId`.
+ *
+ * Naming: "withdrawal" alone already names the guest-telemetry consent
+ * withdrawal and `cash.withdrawal` on the till, so every name here carries the
+ * `PurchaseWithdrawal` / `purchaseWithdrawal` stem.
+ *
+ * ⚠️ The stored row carries one main-table index-key attribute on purpose,
+ * `customerId` (the order's customer when the request was made, a guest row's
+ * id for a guest order), so the customer erasure finds it through the existing
+ * `PK-customerId` read. It carries none of the others: `state` replaces
+ * `status`, `revisedAt` replaces `updatedAt`, and there is no `dated`.
+ */
+/**
+ * - `requested` — submitted, the code minted, the order's dispatch locked
+ *   (`purchase-withdrawal-pending`) until an operator decides.
+ * - `declined` — an operator declined it with a typed exemption reason.
+ *   Terminal.
+ * - `accepted` — an operator accepted it. The order's cancellation (before
+ *   fulfilment) or its return authorisation (after it) follows from here.
+ * - `awaiting-goods` — after fulfilment, the goods are on their way back.
+ * - `refund-pending` — money is owed back (an open refund obligation).
+ * - `completed` — nothing is owed any more. Not final while money can still
+ *   arrive: a late capture moves it back to `refund-pending`.
+ */
+export const PURCHASE_WITHDRAWAL_STATES = [
+    'requested',
+    'declined',
+    'accepted',
+    'awaiting-goods',
+    'refund-pending',
+    'completed',
+];
+/**
+ * The `state` filter of `GET /purchase-withdrawals`: one state, or `open` —
+ * every state but `declined` and `completed`.
+ */
+export const PURCHASE_WITHDRAWAL_LIST_FILTERS = [...PURCHASE_WITHDRAWAL_STATES, 'open'];
+/** `shopper` — the storefront form; `operator-relay` — an operator recording a request received by email or WhatsApp. */
+export const PURCHASE_WITHDRAWAL_SOURCES = ['shopper', 'operator-relay'];
+/**
+ * The only reasons an operator may decline a request, each backed by a row of
+ * the consumer-commerce applicability matrix: made to order or personalised,
+ * quick deterioration, unsealed media or software, periodicals, a used
+ * product, perishables, and a purchase made for resale or production.
+ */
+export const PURCHASE_WITHDRAWAL_DECLINE_REASONS = [
+    'exempt-custom-made',
+    'exempt-quick-deterioration',
+    'exempt-unsealed-media',
+    'exempt-periodical',
+    'exempt-used-product',
+    'exempt-perishable',
+    'resale-purchase',
+];
+/** Where a relayed request reached the store. */
+export const PURCHASE_WITHDRAWAL_RELAY_CHANNELS = ['email', 'whatsapp'];
+/** The modes of `POST /purchase-withdrawals`. */
+export const PURCHASE_WITHDRAWAL_ACTION_MODES = ['accept', 'decline', 'relay'];
+/**
+ * Why a request is refused `409 PURCHASE_WITHDRAWAL_INELIGIBLE` (`data.reason`):
+ *
+ * - `order-cancelled` — the order is cancelled or disabled.
+ * - `no-customer` — the order names no customer (a relay on a walk-in sale).
+ * - `partial-before-fulfilment` — `lines` were named on an order not yet
+ *   delivered or shipped; before fulfilment a withdrawal is the whole order.
+ * - `line-not-on-order` — a named line is not a goods line of the order.
+ * - `line-unavailable` — a named line (or quantity) is already in another
+ *   withdrawal that was not declined, in an open return authorisation, or
+ *   already returned (`data.orderItemIndex`).
+ * - `nothing-to-withdraw` — every line is already withdrawn or returned.
+ */
+export const PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = [
+    'order-cancelled',
+    'no-customer',
+    'partial-before-fulfilment',
+    'line-not-on-order',
+    'line-unavailable',
+    'nothing-to-withdraw',
+];
+/** The longest decline or relay `note`, in characters after trimming. */
+export const PURCHASE_WITHDRAWAL_NOTE_MAX = 500;
+/** The most lines one request may name. */
+export const PURCHASE_WITHDRAWAL_LINES_MAX = 100;
+/** Calendar days of the withdrawal window after the later of delivery and purchase. */
+export const PURCHASE_WITHDRAWAL_WINDOW_DAYS = 10;
+/** The matrix row {@link PurchaseWithdrawal.windowClosesAt} is computed from. */
+export const PURCHASE_WITHDRAWAL_WINDOW_SOURCE = 'W2';
+/** The matrix row a relayed request's `codeDueAt` (24 hours after it was received) comes from. */
+export const PURCHASE_WITHDRAWAL_CODE_DUE_SOURCE = 'W1';
+/** How long after a relayed request was received its code is due, in ms. */
+export const PURCHASE_WITHDRAWAL_CODE_DUE_MS = 24 * 60 * 60 * 1000;

package/dist/socket.d.ts

@@ -26,7 +26,7 @@
  * A client must ignore actions it does not own rather than assume it
  * receives all of them.
  */
-export declare const SOCKET_ACTIONS: readonly ["account", "appointments", "appointmentWaitlist", "attendance", "attributes", "automation-rules", "baskets", "cart", "brands", "cash", "catalogOperation", "categories", "campaigns", "customers", "customerNote", "customerAddress", "customerContact", "deliveries", "globals", "inventory", "invoices", "literals", "loyalty", "orders", "presupuestos", "products", "promotions", "segments", "returns", "rma", "templates", "services", "service-templates", "shifts", "stores", "suppliers", "supplier-invoice", "support", "surveys", "users", "warehouses", "zones", "favorites", "webhooks", "account-delete", "baskets-delete", "cart-delete", "log-delete", "notifications", "support-message", "payment_received", "mp_payment_status_changed", "payment_linked", "payment_unlinked", "mercadopago", "mercadopago_dynamic_qr_created", "mercadopago_static_qr_created", "mp_hook_log_appended", "mp_ipn_log_appended", "orderPaymentAttempt", "orderDelivery", "paymentAttemptChanged", "stripe", "subscription", "caea", "print", "print-order", "print-invoice", "print-product", "print-tag", "print_job_failed", "request_printers", "printers_changed", "agent_status_changed", "print_rules_changed", "printers_active", "agent_command", "maintenance", "currency_auto_updated", "drain_progress", "integration_event_appended", "userActivityRecorded", "mercadolibre_settlement_period", "customDomain", "purchaseOrders", "cycleCounts", "stockTransfers", "workItems", "wholesaleRequests"];
+export declare const SOCKET_ACTIONS: readonly ["account", "appointments", "appointmentWaitlist", "attendance", "attributes", "automation-rules", "baskets", "cart", "brands", "cash", "catalogOperation", "categories", "campaigns", "customers", "customerNote", "customerAddress", "customerContact", "deliveries", "globals", "inventory", "invoices", "literals", "loyalty", "orders", "presupuestos", "products", "promotions", "segments", "returns", "rma", "templates", "services", "service-templates", "shifts", "stores", "suppliers", "supplier-invoice", "support", "surveys", "users", "warehouses", "zones", "favorites", "webhooks", "account-delete", "baskets-delete", "cart-delete", "log-delete", "notifications", "support-message", "payment_received", "mp_payment_status_changed", "payment_linked", "payment_unlinked", "mercadopago", "mercadopago_dynamic_qr_created", "mercadopago_static_qr_created", "mp_hook_log_appended", "mp_ipn_log_appended", "orderPaymentAttempt", "orderDelivery", "paymentAttemptChanged", "orderPurchaseWithdrawal", "purchaseWithdrawalChanged", "stripe", "subscription", "caea", "print", "print-order", "print-invoice", "print-product", "print-tag", "print_job_failed", "request_printers", "printers_changed", "agent_status_changed", "print_rules_changed", "printers_active", "agent_command", "maintenance", "currency_auto_updated", "drain_progress", "integration_event_appended", "userActivityRecorded", "mercadolibre_settlement_period", "customDomain", "purchaseOrders", "cycleCounts", "stockTransfers", "workItems", "wholesaleRequests"];
 /** Union of every server→client data-frame action. */
 export type SocketAction = (typeof SOCKET_ACTIONS)[number];
 /**

package/dist/socket.js

@@ -540,6 +540,27 @@ export const SOCKET_ACTIONS = [
      * a customer socket: the shopper's own frame is `orderPaymentAttempt`.
      */
     'paymentAttemptChanged',
+    /**
+     * A storefront order's purchase withdrawal was requested or decided. `data`
+     * is `OrderPurchaseWithdrawalFrameData` (`purchaseWithdrawal.ts`) — the order
+     * id and the shopper's `OrderPurchaseWithdrawalView`, never the operator's
+     * notes.
+     *
+     * ⚠️ To the order's OWN customer only (`wsPostCustomer`), never a store-wide
+     * customer broadcast. The operator frame for the same write is
+     * `purchaseWithdrawalChanged`.
+     */
+    'orderPurchaseWithdrawal',
+    /**
+     * A purchase withdrawal was requested, relayed or decided. `data` is the
+     * `PurchaseWithdrawal` record as `GET /purchase-withdrawals` answers it.
+     *
+     * ⚠️ OPERATOR sockets of the store only, and ADMIN tier only (`wsPostStore`
+     * with `audience: 'operator'` and `lowTierData: null`): it carries the
+     * customer id and the operator's notes. The shopper's own frame is
+     * `orderPurchaseWithdrawal`.
+     */
+    'purchaseWithdrawalChanged',
     'stripe',
     'subscription',
     // Fiscal.

package/dist/store.d.ts

@@ -567,6 +567,13 @@ declare global {
                 whatsapp?: StorefrontPublicContact['whatsapp'];
             };
             hours?: StorefrontContactHours;
+            /**
+             * `true` while the platform's purchase-withdrawal form is on
+             * (`purchaseWithdrawalFormEnabled`): the button opens the form
+             * (`POST /orders/purchase-withdrawal`) and the storefront retires the
+             * prefilled email or WhatsApp link. `false` keeps that link as the request.
+             */
+            requestForm: boolean;
         };
         privacy: {
             /** The same verdict as `ecommerce.config.guestCheckoutAvailable`. */

package/package.json

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