platform-types 1.10.819 → 1.10.821

package/dist/cjs/purchaseWithdrawal.js

@@ -20,7 +20,7 @@
  * `status`, `revisedAt` replaces `updatedAt`, and there is no `dated`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PURCHASE_WITHDRAWAL_VERIFICATION_FAILED = exports.PURCHASE_WITHDRAWAL_GUEST_INTENTS = 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;
+exports.PURCHASE_WITHDRAWAL_VERIFICATION_FAILED = exports.SHOPPER_REQUEST_INTENTS = exports.PURCHASE_WITHDRAWAL_GUEST_INTENTS = 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_FISCAL_IN_FLIGHT_CAUSES = 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.
@@ -82,6 +82,7 @@ exports.PURCHASE_WITHDRAWAL_ACTION_MODES = ['accept', 'decline', 'relay'];
  *   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.
+ * - `not-delivered` — a warranty request on an order not yet delivered.
  */
 exports.PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = [
     'order-cancelled',
@@ -90,7 +91,22 @@ exports.PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = [
     'line-not-on-order',
     'line-unavailable',
     'nothing-to-withdraw',
+    'not-delivered',
 ];
+/**
+ * Why accepting a withdrawal before fulfilment is refused
+ * `409 PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT` (`data.cause`) — a factura is in
+ * flight on the order, so cancelling it now could leave a voucher on a
+ * withdrawn order:
+ *
+ * - `in-progress` — a factura issuance holds the order's fence right now.
+ *   Retry once it ends.
+ * - `uncertain` — an earlier factura issuance was interrupted and its outcome
+ *   at ARCA is not confirmed. Retryable only after support reconciles it.
+ * - `stranded` — a voucher ARCA authorised could not be recorded on the order.
+ *   Retryable only after support records it.
+ */
+exports.PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT_CAUSES = ['in-progress', 'uncertain', 'stranded'];
 /** The longest decline or relay `note`, in characters after trimming. */
 exports.PURCHASE_WITHDRAWAL_NOTE_MAX = 500;
 /** The most lines one request may name. */
@@ -104,11 +120,18 @@ 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;
 /**
- * The `intent` a guest's `POST /orders/purchase-withdrawal/guest` names. Only
- * the purchase withdrawal (*"Me arrepentí"*) today; the warranty intent joins
- * this tuple with the warranty request.
+ * The `intent` a guest's withdrawal body names: the purchase withdrawal
+ * (*"Me arrepentí"*) only. A warranty request is a separate body variant
+ * ({@link SHOPPER_REQUEST_INTENTS}), never a widening of this tuple — the
+ * withdrawal handler does not branch on `intent`.
  */
 exports.PURCHASE_WITHDRAWAL_GUEST_INTENTS = ['purchase-withdrawal'];
+/**
+ * The two intents of the shopper request form: *"Me arrepentí"* and *"El
+ * producto tiene un problema"*. Change of mind is not an intent — the server
+ * routes a late withdrawal-shaped request to it.
+ */
+exports.SHOPPER_REQUEST_INTENTS = ['purchase-withdrawal', 'warranty'];
 /**
  * The one refusal of every guest code failure on `POST
  * /orders/purchase-withdrawal/guest` (`401`): a wrong, expired, exhausted or

package/dist/cjs/return.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RETURN_LINE_DISPOSITIONS = void 0;
+exports.RETURN_REASON_FLOWS = exports.RETURN_FLOWS = exports.RETURN_LINE_DISPOSITIONS = void 0;
 /**
  * Every state a returned line's physical disposition can be in, as a runtime
  * value so the api's Zod enum, the app's picker and the union below derive
@@ -12,3 +12,24 @@ exports.RETURN_LINE_DISPOSITIONS = [
     'confirmed_sellable',
     'confirmed_damaged',
 ];
+/**
+ * The legal track a return follows: the statutory purchase withdrawal, a
+ * store's voluntary change-of-mind policy, the legal warranty, or an
+ * administrative correction. Server-derived, never chosen by the shopper.
+ */
+exports.RETURN_FLOWS = ['purchase-withdrawal', 'change-of-mind', 'warranty', 'administrative'];
+/**
+ * The flow each {@link ReturnReason} belongs to. `purchase-withdrawal` is never
+ * a reason's flow: only the withdrawal record itself opens that track.
+ */
+exports.RETURN_REASON_FLOWS = {
+    defective: 'warranty',
+    wrong_item: 'warranty',
+    damaged_shipping: 'warranty',
+    not_as_described: 'warranty',
+    customer_changed_mind: 'change-of-mind',
+    duplicate_order: 'administrative',
+    price_adjustment: 'administrative',
+    billing_error: 'administrative',
+    other: 'administrative',
+};

package/dist/cjs/rma.js

@@ -1,6 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.canTransitionRma = exports.RMA_STATUSES = exports.RMA_TRANSITIONS = void 0;
+exports.canTransitionRma = exports.RMA_STATUSES = exports.RMA_TRANSITIONS = exports.SHOPPER_RETURN_REQUEST_DESCRIPTION_MAX = exports.WARRANTY_WINDOW_SOURCE = exports.WARRANTY_MONTHS = exports.RMA_SOURCES = void 0;
+/** Who opened an RMA: an operator, the shopper's own request, or a purchase withdrawal. */
+exports.RMA_SOURCES = ['operator', 'shopper', 'purchase-withdrawal'];
+/** Calendar months of the legal warranty window after delivery. */
+exports.WARRANTY_MONTHS = 6;
+/** The matrix row {@link Rma.warrantyEndsAt} is computed from. */
+exports.WARRANTY_WINDOW_SOURCE = 'W3';
+/** The longest shopper return-request description, in characters after trimming. */
+exports.SHOPPER_RETURN_REQUEST_DESCRIPTION_MAX = 500;
 /**
  * Runtime value, not just a type — the handler validates against it and the FE
  * renders from it, so there is exactly one source of truth.

package/dist/cjs/store.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STORE_PATCH_ERROR_CODES = exports.STORE_MODULE_ERROR_CODES = exports.isStoreModuleOn = exports.isStoreModuleKey = exports.STORE_MODULE_KEYS = exports.STOREFRONT_METHOD_KINDS = exports.STORE_ONBOARDING_REVIEW_AREAS = exports.CUSTOM_DOMAIN_ROW_LIMIT = exports.CUSTOM_DOMAIN_SLOT_LIMIT = void 0;
+exports.CHANGE_OF_MIND_WINDOW_SOURCE = exports.CHANGE_OF_MIND_RETURN_DAYS_MAX = exports.CHANGE_OF_MIND_REFUND_AS = exports.CHANGE_OF_MIND_RETURN_SHIPPING_PAYERS = exports.STORE_PATCH_ERROR_CODES = exports.STORE_MODULE_ERROR_CODES = exports.isStoreModuleOn = exports.isStoreModuleKey = exports.STORE_MODULE_KEYS = exports.STOREFRONT_METHOD_KINDS = exports.STORE_ONBOARDING_REVIEW_AREAS = exports.CUSTOM_DOMAIN_ROW_LIMIT = exports.CUSTOM_DOMAIN_SLOT_LIMIT = void 0;
 /**
  * How many custom-domain rows a store may hold that count: one active domain
  * and one spare, so a replacement can be verified and provisioned before the
@@ -200,3 +200,11 @@ exports.STORE_PATCH_ERROR_CODES = [
     'FORBIDDEN',
     'STORE_NOT_FOUND',
 ];
+/** Who pays the return shipping under a store's change-of-mind policy. */
+exports.CHANGE_OF_MIND_RETURN_SHIPPING_PAYERS = ['merchant', 'shopper'];
+/** How a change-of-mind return is paid back: a refund, or store credit. */
+exports.CHANGE_OF_MIND_REFUND_AS = ['refund', 'store-credit'];
+/** The longest change-of-mind window a store may set, in calendar days after delivery. */
+exports.CHANGE_OF_MIND_RETURN_DAYS_MAX = 365;
+/** The source of a change-of-mind deadline: the store's own setting, not a statutory row. */
+exports.CHANGE_OF_MIND_WINDOW_SOURCE = 'store:changeOfMindReturns';

package/dist/guestOrderStatus.d.ts

@@ -106,6 +106,10 @@ declare global {
         purchaseWithdrawals?: OrderPurchaseWithdrawalView[];
         /** Whether the withdrawal window is open now — as on `StorefrontOrderView`. Always present. */
         purchaseWithdrawalEligibility: OrderPurchaseWithdrawalEligibility;
+        /** Shopper-sourced return requests, newest first. Reserved — not attached yet. */
+        returnRequests?: OrderReturnRequestView[];
+        /** Reserved — not attached yet. */
+        returnRequestEligibility?: OrderReturnRequestEligibility;
         contact: {
             /** The stored address, masked (e.g. `j***@d***.com`). */
             emailMasked: string;

package/dist/order.d.ts

@@ -1269,7 +1269,11 @@ declare global {
          * All four fields are absent on a non-cancelled order.
          */
         cancelledAt?: number;
-        /** Who cancelled: the customerId for a self-cancellation, the operator's userId for an operator cancellation. */
+        /**
+         * Who cancelled: the customerId for a self-cancellation, the operator's
+         * userId for an operator cancellation and for a purchase-withdrawal one
+         * (the operator who accepted it), `'system'` for the payment-hold expiry.
+         */
         cancelledBy?: string;
         cancellationSource?: OrderCancellationSource;
         /**
@@ -1380,8 +1384,14 @@ declare global {
      * (`services/orderSystemCancellation.ts`, run by the payment-attempt sweep),
      * which cancels an order whose online payment attempt lapsed unpaid; its
      * `cancelledBy` is `'system'`, never a user id.
+     *
+     * `purchase-withdrawal` is written only by the purchase-withdrawal door
+     * (`lambdas/orders/_purchaseWithdrawalCancel.ts`): the order cancelled
+     * because an operator accepted the shopper's purchase withdrawal before
+     * fulfilment. Its `cancelledBy` is the accepting operator's userId (the
+     * commit is the operator's act), and it carries no `cancellationReason`.
      */
-    type OrderCancellationSource = 'customer' | 'operator' | 'system';
+    type OrderCancellationSource = 'customer' | 'operator' | 'system' | 'purchase-withdrawal';
     /**
      * Machine-readable reason an order is locked against a mutation — the
      * payload of `409 ORDER_LOCKED` (on the customer cancellation's `409 ORDER_CANCELLATION_LOCKED` it rides in `message` as `reason: <r>` and that body has no `reason` key; the operator cancellation's carries both), and the

package/dist/paymentAttempt.d.ts

@@ -136,6 +136,10 @@ declare global {
         delivery?: OrderDeliveryView;
         purchaseWithdrawals?: OrderPurchaseWithdrawalView[];
         purchaseWithdrawalEligibility?: OrderPurchaseWithdrawalEligibility;
+        /** Shopper-sourced return requests, newest first. Reserved — not attached yet. */
+        returnRequests?: OrderReturnRequestView[];
+        /** Reserved — not attached yet. */
+        returnRequestEligibility?: OrderReturnRequestEligibility;
     };
     /**
      * `data` of an `orderPaymentAttempt` socket frame, sent to the order's own

package/dist/purchaseWithdrawal.d.ts

@@ -64,8 +64,23 @@ export declare const PURCHASE_WITHDRAWAL_ACTION_MODES: readonly ["accept", "decl
  *   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.
+ * - `not-delivered` — a warranty request on an order not yet delivered.
  */
-export declare const PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS: readonly ["order-cancelled", "no-customer", "partial-before-fulfilment", "line-not-on-order", "line-unavailable", "nothing-to-withdraw"];
+export declare const PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS: readonly ["order-cancelled", "no-customer", "partial-before-fulfilment", "line-not-on-order", "line-unavailable", "nothing-to-withdraw", "not-delivered"];
+/**
+ * Why accepting a withdrawal before fulfilment is refused
+ * `409 PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT` (`data.cause`) — a factura is in
+ * flight on the order, so cancelling it now could leave a voucher on a
+ * withdrawn order:
+ *
+ * - `in-progress` — a factura issuance holds the order's fence right now.
+ *   Retry once it ends.
+ * - `uncertain` — an earlier factura issuance was interrupted and its outcome
+ *   at ARCA is not confirmed. Retryable only after support reconciles it.
+ * - `stranded` — a voucher ARCA authorised could not be recorded on the order.
+ *   Retryable only after support records it.
+ */
+export declare const PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT_CAUSES: readonly ["in-progress", "uncertain", "stranded"];
 /** 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. */
@@ -79,11 +94,18 @@ 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;
 /**
- * The `intent` a guest's `POST /orders/purchase-withdrawal/guest` names. Only
- * the purchase withdrawal (*"Me arrepentí"*) today; the warranty intent joins
- * this tuple with the warranty request.
+ * The `intent` a guest's withdrawal body names: the purchase withdrawal
+ * (*"Me arrepentí"*) only. A warranty request is a separate body variant
+ * ({@link SHOPPER_REQUEST_INTENTS}), never a widening of this tuple — the
+ * withdrawal handler does not branch on `intent`.
  */
 export declare const PURCHASE_WITHDRAWAL_GUEST_INTENTS: readonly ["purchase-withdrawal"];
+/**
+ * The two intents of the shopper request form: *"Me arrepentí"* and *"El
+ * producto tiene un problema"*. Change of mind is not an intent — the server
+ * routes a late withdrawal-shaped request to it.
+ */
+export declare const SHOPPER_REQUEST_INTENTS: readonly ["purchase-withdrawal", "warranty"];
 /**
  * The one refusal of every guest code failure on `POST
  * /orders/purchase-withdrawal/guest` (`401`): a wrong, expired, exhausted or
@@ -100,6 +122,7 @@ declare global {
     type PurchaseWithdrawalActionMode = (typeof PURCHASE_WITHDRAWAL_ACTION_MODES)[number];
     type PurchaseWithdrawalIneligibleReason = (typeof PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS)[number];
     type PurchaseWithdrawalGuestIntent = (typeof PURCHASE_WITHDRAWAL_GUEST_INTENTS)[number];
+    type PurchaseWithdrawalFiscalInFlightCause = (typeof PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT_CAUSES)[number];
     /** One withdrawn order line, by its index in `Order.items`. */
     interface PurchaseWithdrawalLine {
         orderItemIndex: number;
@@ -314,6 +337,50 @@ declare global {
         /** Unix ms. */
         windowClosesAt: number;
         source: 'W2';
+        /** Unix ms. Present only when the store's change-of-mind policy is on but its window has passed too. */
+        changeOfMindEndsAt?: number;
+    }
+    type ShopperRequestIntent = (typeof SHOPPER_REQUEST_INTENTS)[number];
+    /**
+     * The warranty variant of `POST /orders/purchase-withdrawal`. Reserved — the
+     * live strict body refuses it `400` until the warranty request ships.
+     */
+    interface ShopperWarrantySubmitRequest {
+        intent: 'warranty';
+        /** `ORD` + 6–10 digits. */
+        orderId: string;
+        lines?: PurchaseWithdrawalLine[];
+        /**
+         * 1–`SHOPPER_RETURN_REQUEST_DESCRIPTION_MAX` characters after trimming.
+         * Never stored for an erased customer; never in an audit row.
+         */
+        description: string;
+    }
+    type ShopperOrderRequest = PurchaseWithdrawalSubmitRequest | ShopperWarrantySubmitRequest;
+    /** The warranty variant of the guest submit. Reserved, as {@link ShopperWarrantySubmitRequest}. */
+    interface ShopperWarrantyGuestSubmitRequest {
+        challengeHandle: string;
+        code: string;
+        intent: 'warranty';
+        lines?: PurchaseWithdrawalLine[];
+        description: string;
+    }
+    type ShopperOrderGuestRequest = PurchaseWithdrawalGuestSubmitRequest | ShopperWarrantyGuestSubmitRequest;
+    /** `data` of the `201` when the request opened a return request rather than a withdrawal. */
+    interface ShopperReturnRequestSubmitResponse {
+        returnRequest: OrderReturnRequestView;
+    }
+    interface ShopperReturnRequestGuestSubmitResponse extends ShopperReturnRequestSubmitResponse {
+        statusToken?: string;
+    }
+    /** Tell apart by key: `purchaseWithdrawal` or `returnRequest`. */
+    type ShopperOrderRequestResponse = PurchaseWithdrawalSubmitResponse | ShopperReturnRequestSubmitResponse;
+    type ShopperOrderGuestRequestResponse = PurchaseWithdrawalGuestSubmitResponse | ShopperReturnRequestGuestSubmitResponse;
+    /** `data` of `409 WARRANTY_WINDOW_CLOSED`. */
+    interface WarrantyWindowClosedData {
+        /** Unix ms. */
+        warrantyEndsAt: number;
+        source: 'W3';
     }
     /** `data` of `409 PURCHASE_WITHDRAWAL_INELIGIBLE`. */
     interface PurchaseWithdrawalIneligibleData {
@@ -389,6 +456,13 @@ declare global {
         decision?: PurchaseWithdrawalDecision;
         declineReason?: PurchaseWithdrawalDeclineReason;
     }
+    /**
+     * `data` of `409 PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT`: why the order's
+     * cancellation must wait on its fiscal state. Nothing was written.
+     */
+    interface PurchaseWithdrawalFiscalInFlightData {
+        cause: PurchaseWithdrawalFiscalInFlightCause;
+    }
     /** `data` of `409 PURCHASE_WITHDRAWAL_CHANGED`: the withdrawal as it now stands — review it and resend. */
     interface PurchaseWithdrawalChangedData {
         purchaseWithdrawal: PurchaseWithdrawal;

package/dist/purchaseWithdrawal.js

@@ -79,6 +79,7 @@ export const PURCHASE_WITHDRAWAL_ACTION_MODES = ['accept', 'decline', 'relay'];
  *   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.
+ * - `not-delivered` — a warranty request on an order not yet delivered.
  */
 export const PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = [
     'order-cancelled',
@@ -87,7 +88,22 @@ export const PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = [
     'line-not-on-order',
     'line-unavailable',
     'nothing-to-withdraw',
+    'not-delivered',
 ];
+/**
+ * Why accepting a withdrawal before fulfilment is refused
+ * `409 PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT` (`data.cause`) — a factura is in
+ * flight on the order, so cancelling it now could leave a voucher on a
+ * withdrawn order:
+ *
+ * - `in-progress` — a factura issuance holds the order's fence right now.
+ *   Retry once it ends.
+ * - `uncertain` — an earlier factura issuance was interrupted and its outcome
+ *   at ARCA is not confirmed. Retryable only after support reconciles it.
+ * - `stranded` — a voucher ARCA authorised could not be recorded on the order.
+ *   Retryable only after support records it.
+ */
+export const PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT_CAUSES = ['in-progress', 'uncertain', 'stranded'];
 /** The longest decline or relay `note`, in characters after trimming. */
 export const PURCHASE_WITHDRAWAL_NOTE_MAX = 500;
 /** The most lines one request may name. */
@@ -101,11 +117,18 @@ 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;
 /**
- * The `intent` a guest's `POST /orders/purchase-withdrawal/guest` names. Only
- * the purchase withdrawal (*"Me arrepentí"*) today; the warranty intent joins
- * this tuple with the warranty request.
+ * The `intent` a guest's withdrawal body names: the purchase withdrawal
+ * (*"Me arrepentí"*) only. A warranty request is a separate body variant
+ * ({@link SHOPPER_REQUEST_INTENTS}), never a widening of this tuple — the
+ * withdrawal handler does not branch on `intent`.
  */
 export const PURCHASE_WITHDRAWAL_GUEST_INTENTS = ['purchase-withdrawal'];
+/**
+ * The two intents of the shopper request form: *"Me arrepentí"* and *"El
+ * producto tiene un problema"*. Change of mind is not an intent — the server
+ * routes a late withdrawal-shaped request to it.
+ */
+export const SHOPPER_REQUEST_INTENTS = ['purchase-withdrawal', 'warranty'];
 /**
  * The one refusal of every guest code failure on `POST
  * /orders/purchase-withdrawal/guest` (`401`): a wrong, expired, exhausted or

package/dist/return.d.ts

@@ -4,7 +4,21 @@
  * from ONE list. See {@link ReturnLineDisposition} for the machine.
  */
 export declare const RETURN_LINE_DISPOSITIONS: readonly ["pending_inspection", "suspicious", "confirmed_sellable", "confirmed_damaged"];
+/**
+ * The legal track a return follows: the statutory purchase withdrawal, a
+ * store's voluntary change-of-mind policy, the legal warranty, or an
+ * administrative correction. Server-derived, never chosen by the shopper.
+ */
+export declare const RETURN_FLOWS: readonly ["purchase-withdrawal", "change-of-mind", "warranty", "administrative"];
+/**
+ * The flow each {@link ReturnReason} belongs to. `purchase-withdrawal` is never
+ * a reason's flow: only the withdrawal record itself opens that track.
+ */
+export declare const RETURN_REASON_FLOWS: {
+    readonly [R in ReturnReason]: Exclude<ReturnFlow, 'purchase-withdrawal'>;
+};
 declare global {
+    type ReturnFlow = (typeof RETURN_FLOWS)[number];
     /** Where a customer return's value is paid. Omission on a request or legacy row means account. */
     type ReturnRefundMethod = 'account' | 'cash';
     /** Return planning refusals: invalid selected lines, too many return summaries, or more than 100 transaction items. */

package/dist/return.js

@@ -9,3 +9,24 @@ export const RETURN_LINE_DISPOSITIONS = [
     'confirmed_sellable',
     'confirmed_damaged',
 ];
+/**
+ * The legal track a return follows: the statutory purchase withdrawal, a
+ * store's voluntary change-of-mind policy, the legal warranty, or an
+ * administrative correction. Server-derived, never chosen by the shopper.
+ */
+export const RETURN_FLOWS = ['purchase-withdrawal', 'change-of-mind', 'warranty', 'administrative'];
+/**
+ * The flow each {@link ReturnReason} belongs to. `purchase-withdrawal` is never
+ * a reason's flow: only the withdrawal record itself opens that track.
+ */
+export const RETURN_REASON_FLOWS = {
+    defective: 'warranty',
+    wrong_item: 'warranty',
+    damaged_shipping: 'warranty',
+    not_as_described: 'warranty',
+    customer_changed_mind: 'change-of-mind',
+    duplicate_order: 'administrative',
+    price_adjustment: 'administrative',
+    billing_error: 'administrative',
+    other: 'administrative',
+};

package/dist/rma.d.ts

@@ -125,6 +125,14 @@ declare global {
          * field's meaning does not change.
          */
         expiresAt?: number;
+        /** Who opened the request. Absent means `operator`. No writer sets another value yet. */
+        source?: RmaSource;
+        /** Server-derived legal track. Absent on an operator request. */
+        flow?: ReturnFlow;
+        /** End of the legal warranty window (W3). Set only on a `warranty` request. */
+        warrantyEndsAt?: StatutoryInstant;
+        /** The store's change-of-mind terms as they stood when requested. Set only on a `change-of-mind` request. */
+        changeOfMind?: RmaChangeOfMindTerms;
         /** Lowercase, rebuilt on every write. A row missing it is invisible to search. */
         search?: string;
         createdAt: number;
@@ -197,7 +205,67 @@ declare global {
         returnId: string;
     }
     type RmaPostInput = RmaCreateInput | RmaAuthorizeInput | RmaRejectInput | RmaReceiveInput | RmaTrackingInput | RmaSettleInput;
+    type RmaSource = (typeof RMA_SOURCES)[number];
+    /** The flows a shopper's own return request can land in. */
+    type ShopperReturnRequestFlow = Extract<ReturnFlow, 'warranty' | 'change-of-mind'>;
+    /** The change-of-mind terms snapshotted onto a request, so a later policy edit does not rewrite them. */
+    interface RmaChangeOfMindTerms {
+        endsAt: StatutoryInstant;
+        returnShippingPaidBy: ChangeOfMindReturnShippingPayer;
+        refundAs: ChangeOfMindRefundAs;
+    }
+    interface OrderReturnRequestItemView {
+        orderItemIndex: number;
+        requestedQuantity: number;
+        /** Present once authorised; `0` = that line was refused. */
+        approvedQuantity?: number;
+    }
+    /**
+     * A shopper-sourced return request as the shopper sees it, by ALLOW-LIST:
+     * never the operator's reasons or actors, carrier, tracking, nor the
+     * shopper's own description. Reserved — no read serves it yet.
+     */
+    interface OrderReturnRequestView {
+        rmaId: string;
+        flow: ShopperReturnRequestFlow;
+        status: RmaStatus;
+        requestedAt: number;
+        items: OrderReturnRequestItemView[];
+        /** Unix ms. */
+        warrantyEndsAt?: number;
+        changeOfMind?: {
+            /** Unix ms. */
+            endsAt: number;
+            returnShippingPaidBy: ChangeOfMindReturnShippingPayer;
+            refundAs: ChangeOfMindRefundAs;
+        };
+        refunds?: OrderPurchaseWithdrawalRefundView[];
+    }
+    /** Whether the shopper can open a return request on the order now. Reserved — no read serves it yet. */
+    interface OrderReturnRequestEligibility {
+        warranty: {
+            open: boolean;
+            /** Unix ms. */
+            warrantyEndsAt?: number;
+        };
+        /** Present only while the store's policy is on and the order was delivered. */
+        changeOfMind?: {
+            open: boolean;
+            /** Unix ms. */
+            endsAt: number;
+            returnShippingPaidBy: ChangeOfMindReturnShippingPayer;
+            refundAs: ChangeOfMindRefundAs;
+        };
+    }
 }
+/** Who opened an RMA: an operator, the shopper's own request, or a purchase withdrawal. */
+export declare const RMA_SOURCES: readonly ["operator", "shopper", "purchase-withdrawal"];
+/** Calendar months of the legal warranty window after delivery. */
+export declare const WARRANTY_MONTHS = 6;
+/** The matrix row {@link Rma.warrantyEndsAt} is computed from. */
+export declare const WARRANTY_WINDOW_SOURCE = "W3";
+/** The longest shopper return-request description, in characters after trimming. */
+export declare const SHOPPER_RETURN_REQUEST_DESCRIPTION_MAX = 500;
 /**
  * Runtime value, not just a type — the handler validates against it and the FE
  * renders from it, so there is exactly one source of truth.

package/dist/rma.js

@@ -1,3 +1,11 @@
+/** Who opened an RMA: an operator, the shopper's own request, or a purchase withdrawal. */
+export const RMA_SOURCES = ['operator', 'shopper', 'purchase-withdrawal'];
+/** Calendar months of the legal warranty window after delivery. */
+export const WARRANTY_MONTHS = 6;
+/** The matrix row {@link Rma.warrantyEndsAt} is computed from. */
+export const WARRANTY_WINDOW_SOURCE = 'W3';
+/** The longest shopper return-request description, in characters after trimming. */
+export const SHOPPER_RETURN_REQUEST_DESCRIPTION_MAX = 500;
 /**
  * Runtime value, not just a type — the handler validates against it and the FE
  * renders from it, so there is exactly one source of truth.

package/dist/store.d.ts

@@ -989,6 +989,13 @@ declare global {
              * storefront.
              */
             publicContact?: boolean;
+            /**
+             * The store's voluntary change-of-mind return policy, beyond the
+             * statutory withdrawal window. Absent, or `enabled: false`, means off.
+             * Reserved — no `PATCH /store` validator accepts it yet. Written whole,
+             * never cleared with `null`.
+             */
+            changeOfMindReturns?: ChangeOfMindReturnsConfig;
             /**
              * Per-category × per-channel notification/feedback defaults; absent ⇒
              * FE falls back to all-on. FE-read only — `PATCH /store` validates shape only.
@@ -2648,3 +2655,23 @@ export type StoreModuleRefusalBody = {
  */
 export declare const STORE_PATCH_ERROR_CODES: readonly ["STORE_CONFIG_FORBIDDEN", "STORE_ECOMMERCE_FORBIDDEN", "STORE_FISCAL_FIELD_FORBIDDEN", "STORE_JURISDICTION_FORBIDDEN", "AFIP_RELACION_FLAG_FORBIDDEN", "FX_TABLE_FORBIDDEN", "FX_AUTO_UPDATE_FORBIDDEN", "FIELD_NOT_WRITABLE_HERE", "AFIP_POINT_OF_SALE_NOT_CLEARABLE", "CURRENCY_CATALOG_ID_UNKNOWN", "ARS_RATE_MUST_BE_ONE", "CURRENCY_RATE_ABOVE_CEILING", "FX_CATALOG_ID_UNKNOWN", "FX_SOURCE_ID_UNKNOWN", "DISPLAY_CURRENCY_NOT_INVOICEABLE", "PRODUCT_CURRENCY_NOT_INVOICEABLE", "PRICE_LIST_NOT_FOUND", "DELIVERY_FEE_INVALID", "WHOLESALE_LIST_REQUIRED", "NET_PLUS_IVA_REQUIRES_RI", "DATA_FISCAL_URL_INVALID", "STORE_PUBLIC_HOST_MISSING", "FORBIDDEN", "STORE_NOT_FOUND"];
 export type StorePatchErrorCode = (typeof STORE_PATCH_ERROR_CODES)[number];
+/** Who pays the return shipping under a store's change-of-mind policy. */
+export declare const CHANGE_OF_MIND_RETURN_SHIPPING_PAYERS: readonly ["merchant", "shopper"];
+/** How a change-of-mind return is paid back: a refund, or store credit. */
+export declare const CHANGE_OF_MIND_REFUND_AS: readonly ["refund", "store-credit"];
+/** The longest change-of-mind window a store may set, in calendar days after delivery. */
+export declare const CHANGE_OF_MIND_RETURN_DAYS_MAX = 365;
+/** The source of a change-of-mind deadline: the store's own setting, not a statutory row. */
+export declare const CHANGE_OF_MIND_WINDOW_SOURCE = "store:changeOfMindReturns";
+declare global {
+    type ChangeOfMindReturnShippingPayer = (typeof CHANGE_OF_MIND_RETURN_SHIPPING_PAYERS)[number];
+    type ChangeOfMindRefundAs = (typeof CHANGE_OF_MIND_REFUND_AS)[number];
+    /** `Store.config.changeOfMindReturns`. Absent, or `enabled: false`, means off. */
+    interface ChangeOfMindReturnsConfig {
+        enabled: boolean;
+        /** Whole calendar days after delivery, 1–{@link CHANGE_OF_MIND_RETURN_DAYS_MAX}. */
+        days: number;
+        returnShippingPaidBy: ChangeOfMindReturnShippingPayer;
+        refundAs: ChangeOfMindRefundAs;
+    }
+}

package/dist/store.js

@@ -195,3 +195,11 @@ export const STORE_PATCH_ERROR_CODES = [
     'FORBIDDEN',
     'STORE_NOT_FOUND',
 ];
+/** Who pays the return shipping under a store's change-of-mind policy. */
+export const CHANGE_OF_MIND_RETURN_SHIPPING_PAYERS = ['merchant', 'shopper'];
+/** How a change-of-mind return is paid back: a refund, or store credit. */
+export const CHANGE_OF_MIND_REFUND_AS = ['refund', 'store-credit'];
+/** The longest change-of-mind window a store may set, in calendar days after delivery. */
+export const CHANGE_OF_MIND_RETURN_DAYS_MAX = 365;
+/** The source of a change-of-mind deadline: the store's own setting, not a statutory row. */
+export const CHANGE_OF_MIND_WINDOW_SOURCE = 'store:changeOfMindReturns';

package/package.json

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