@nok-integration/storefront-react 0.17.2 → 0.18.0

package/dist/index.d.ts

@@ -114,6 +114,33 @@ declare const CartItem: z.ZodObject<{
         amount: number;
         currency: string;
     }>;
+    /**
+     * The undiscounted per-unit price, from the catalogue. Display only.
+     *
+     * Drawn as a struck-through figure under what the line costs now, with a `-NN%` badge
+     * over the thumbnail — Figma's cart draws every discounted line that way and, until
+     * this field existed, a consumer had no way to. The saving was simply invisible in the
+     * basket and appeared for the first time at checkout.
+     *
+     * Absent means the line is at full price, which is the ordinary case. Present only when
+     * it is strictly greater than `unit_price`: a compare-at equal to or below the live
+     * price is not a sale, and drawing one would be an invented discount.
+     *
+     * **The catalogue's figure, not an order's.** `OrderItem.compare_at_unit_price` is the
+     * one DAZN sent at intake and is frozen there, because a receipt whose struck price
+     * moves next week is not a receipt. A cart is live, so this one moves with
+     * merchandising — that is correct here and wrong there.
+     */
+    compare_at_unit_price: z.ZodOptional<z.ZodObject<{
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        amount: number;
+        currency: string;
+    }, {
+        amount: number;
+        currency: string;
+    }>>;
     /**
      * Product title for this line, e.g. "Signature Hoodie".
      *
@@ -168,6 +195,10 @@ declare const CartItem: z.ZodObject<{
         amount: number;
         currency: string;
     };
+    compare_at_unit_price?: {
+        amount: number;
+        currency: string;
+    } | undefined;
     title?: string | undefined;
     image?: string | undefined;
     attributes?: Record<string, string> | undefined;
@@ -183,6 +214,10 @@ declare const CartItem: z.ZodObject<{
         amount: number;
         currency: string;
     };
+    compare_at_unit_price?: {
+        amount: number;
+        currency: string;
+    } | undefined;
     title?: string | undefined;
     image?: string | undefined;
     attributes?: Record<string, string> | undefined;
@@ -222,6 +257,10 @@ export declare interface CartLineItemProps {
      * above, for a host with its own catalogue data.
      */
     compareAt?: Money;
+    /**
+     * Overrides the percentage on the badge. Normally omitted: given a `compareAt`, the
+     * badge is derived from it and the two figures cannot then disagree.
+     */
     discountPct?: number;
     maxQty?: number;
     onQtyChange: (qty: number) => void;
@@ -297,10 +336,7 @@ export declare interface CartViewProps {
      * Label for the primary CTA. Default `Proceed to checkout`.
      *
      * DAZN's checkout is the next step and DAZN name it; a host whose own wording is
-     * "Continue" or "Go to checkout" should not have to accept ours. The locked-cart label
-     * is deliberately NOT configurable — it takes the fan back to a checkout that already
-     * exists, which is a different action from starting one, and a host renaming it could
-     * imply a second checkout is being created.
+     * "Continue" or "Go to checkout" should not have to accept ours.
      */
     checkoutLabel?: string;
 }
@@ -2498,6 +2534,10 @@ declare function createClient(options: ClientOptions): {
                 image?: string | undefined;
                 available?: number | undefined;
                 title?: string | undefined;
+                compare_at_unit_price?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
             }[];
             cart_id: string;
             totals: {
@@ -2517,12 +2557,20 @@ declare function createClient(options: ClientOptions): {
                     amount: number;
                     currency: string;
                 };
+                discount?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
             };
             locked?: {
                 since: string;
                 reason: "checkout_handoff";
                 expires_at?: string | undefined;
             } | undefined;
+            hold?: {
+                expires_at: string;
+                taken_at: string;
+            } | undefined;
             hidden_lines?: ("shipping" | "tax")[] | undefined;
         }>;
         get: () => Promise<{
@@ -2542,6 +2590,10 @@ declare function createClient(options: ClientOptions): {
                 image?: string | undefined;
                 available?: number | undefined;
                 title?: string | undefined;
+                compare_at_unit_price?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
             }[];
             cart_id: string;
             totals: {
@@ -2561,12 +2613,20 @@ declare function createClient(options: ClientOptions): {
                     amount: number;
                     currency: string;
                 };
+                discount?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
             };
             locked?: {
                 since: string;
                 reason: "checkout_handoff";
                 expires_at?: string | undefined;
             } | undefined;
+            hold?: {
+                expires_at: string;
+                taken_at: string;
+            } | undefined;
             hidden_lines?: ("shipping" | "tax")[] | undefined;
         }>;
         addItem: (body: AddCartItemRequest) => Promise<{
@@ -2586,6 +2646,10 @@ declare function createClient(options: ClientOptions): {
                 image?: string | undefined;
                 available?: number | undefined;
                 title?: string | undefined;
+                compare_at_unit_price?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
             }[];
             cart_id: string;
             totals: {
@@ -2605,12 +2669,20 @@ declare function createClient(options: ClientOptions): {
                     amount: number;
                     currency: string;
                 };
+                discount?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
             };
             locked?: {
                 since: string;
                 reason: "checkout_handoff";
                 expires_at?: string | undefined;
             } | undefined;
+            hold?: {
+                expires_at: string;
+                taken_at: string;
+            } | undefined;
             hidden_lines?: ("shipping" | "tax")[] | undefined;
         }>;
         updateItem: (sku: string, body: UpdateCartItemRequest) => Promise<{
@@ -2630,6 +2702,10 @@ declare function createClient(options: ClientOptions): {
                 image?: string | undefined;
                 available?: number | undefined;
                 title?: string | undefined;
+                compare_at_unit_price?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
             }[];
             cart_id: string;
             totals: {
@@ -2649,12 +2725,20 @@ declare function createClient(options: ClientOptions): {
                     amount: number;
                     currency: string;
                 };
+                discount?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
             };
             locked?: {
                 since: string;
                 reason: "checkout_handoff";
                 expires_at?: string | undefined;
             } | undefined;
+            hold?: {
+                expires_at: string;
+                taken_at: string;
+            } | undefined;
             hidden_lines?: ("shipping" | "tax")[] | undefined;
         }>;
         removeItem: (sku: string) => Promise<{
@@ -2674,6 +2758,10 @@ declare function createClient(options: ClientOptions): {
                 image?: string | undefined;
                 available?: number | undefined;
                 title?: string | undefined;
+                compare_at_unit_price?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
             }[];
             cart_id: string;
             totals: {
@@ -2693,12 +2781,20 @@ declare function createClient(options: ClientOptions): {
                     amount: number;
                     currency: string;
                 };
+                discount?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
             };
             locked?: {
                 since: string;
                 reason: "checkout_handoff";
                 expires_at?: string | undefined;
             } | undefined;
+            hold?: {
+                expires_at: string;
+                taken_at: string;
+            } | undefined;
             hidden_lines?: ("shipping" | "tax")[] | undefined;
         }>;
         /**
@@ -2810,6 +2906,104 @@ declare function createClient(options: ClientOptions): {
                 brand: string;
                 last4?: string | undefined;
             } | undefined;
+            returns?: {
+                status: "reported" | "package_received" | "completed";
+                return_ref: string;
+                reported_at: string;
+            }[] | undefined;
+            estimated_delivery?: {
+                from: string;
+                to: string;
+            } | undefined;
+            tracking?: {
+                carrier: string;
+                url?: string | undefined;
+                reference?: string | undefined;
+            } | undefined;
+            can_cancel?: boolean | undefined;
+            can_return?: boolean | undefined;
+        }>;
+        /**
+         * Ask for the order to be cancelled (ADR-0024). Returns the order as it now stands.
+         *
+         * A request, not a refund: DAZN are merchant of record and the money is theirs to
+         * move. This records the fan's ask and hands it on.
+         */
+        requestCancellation: (orderRef: string, body: RequestCancellationRequest) => Promise<{
+            status: "packing" | "on_its_way" | "out_for_delivery" | "delivered" | "cancelled";
+            currency: string;
+            items: {
+                sku: string;
+                qty: number;
+                unit_price: {
+                    amount: number;
+                    currency: string;
+                };
+                line_total: {
+                    amount: number;
+                    currency: string;
+                };
+                line_ref: string;
+                cancelled_qty: number;
+                refunded_qty: number;
+                attributes?: Record<string, string> | undefined;
+                image?: string | undefined;
+                title?: string | undefined;
+                compare_at_unit_price?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
+            }[];
+            totals: {
+                shipping: {
+                    amount: number;
+                    currency: string;
+                };
+                tax: {
+                    amount: number;
+                    currency: string;
+                };
+                items: {
+                    amount: number;
+                    currency: string;
+                };
+                grand_total: {
+                    amount: number;
+                    currency: string;
+                };
+                discount?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
+            };
+            order_ref: string;
+            placed_at: string;
+            ship_to: {
+                country: string;
+                name: string;
+                line1: string;
+                city: string;
+                postcode: string;
+                line2?: string | undefined;
+                region?: string | undefined;
+            };
+            headline: string;
+            progress: {
+                label: string;
+                step: "packing" | "on_its_way" | "out_for_delivery" | "delivered" | "cancelled";
+                current: boolean;
+                at?: string | undefined;
+            }[];
+            email?: string | undefined;
+            payment?: {
+                brand: string;
+                last4?: string | undefined;
+            } | undefined;
+            returns?: {
+                status: "reported" | "package_received" | "completed";
+                return_ref: string;
+                reported_at: string;
+            }[] | undefined;
             estimated_delivery?: {
                 from: string;
                 to: string;
@@ -2819,6 +3013,73 @@ declare function createClient(options: ClientOptions): {
                 url?: string | undefined;
                 reference?: string | undefined;
             } | undefined;
+            can_cancel?: boolean | undefined;
+            can_return?: boolean | undefined;
+        }>;
+        /** Report items coming back, and get the return — including its label when ready. */
+        createReturn: (orderRef: string, body: CreateReturnRequest) => Promise<{
+            status: "reported" | "package_received" | "completed";
+            items: {
+                sku: string;
+                qty: number;
+                unit_price: {
+                    amount: number;
+                    currency: string;
+                };
+                reason: "too_small" | "changed_my_mind" | "too_large" | "arrived_too_late" | "item_damaged" | "not_as_described";
+                line_ref: string;
+                attributes?: Record<string, string> | undefined;
+                image?: string | undefined;
+                title?: string | undefined;
+                compare_at_unit_price?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
+            }[];
+            order_ref: string;
+            return_ref: string;
+            reported_at: string;
+            progress: {
+                label: string;
+                step: "reported" | "package_received" | "completed";
+                current: boolean;
+                at?: string | undefined;
+            }[];
+            label_url?: string | undefined;
+            label_email?: string | undefined;
+        }>;
+    };
+    returns: {
+        get: (returnRef: string) => Promise<{
+            status: "reported" | "package_received" | "completed";
+            items: {
+                sku: string;
+                qty: number;
+                unit_price: {
+                    amount: number;
+                    currency: string;
+                };
+                reason: "too_small" | "changed_my_mind" | "too_large" | "arrived_too_late" | "item_damaged" | "not_as_described";
+                line_ref: string;
+                attributes?: Record<string, string> | undefined;
+                image?: string | undefined;
+                title?: string | undefined;
+                compare_at_unit_price?: {
+                    amount: number;
+                    currency: string;
+                } | undefined;
+            }[];
+            order_ref: string;
+            return_ref: string;
+            reported_at: string;
+            progress: {
+                label: string;
+                step: "reported" | "package_received" | "completed";
+                current: boolean;
+                at?: string | undefined;
+            }[];
+            label_url?: string | undefined;
+            label_email?: string | undefined;
         }>;
     };
     /**
@@ -2868,6 +3129,37 @@ declare function createClient(options: ClientOptions): {
     };
 };
 
+/** `POST /v1/orders/{order_ref}/returns` */
+declare const CreateReturnRequest: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        line_ref: z.ZodString;
+        qty: z.ZodNumber;
+        reason: z.ZodEnum<["too_large", "too_small", "arrived_too_late", "item_damaged", "not_as_described", "changed_my_mind"]>;
+    }, "strip", z.ZodTypeAny, {
+        qty: number;
+        reason: "too_small" | "changed_my_mind" | "too_large" | "arrived_too_late" | "item_damaged" | "not_as_described";
+        line_ref: string;
+    }, {
+        qty: number;
+        reason: "too_small" | "changed_my_mind" | "too_large" | "arrived_too_late" | "item_damaged" | "not_as_described";
+        line_ref: string;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    items: {
+        qty: number;
+        reason: "too_small" | "changed_my_mind" | "too_large" | "arrived_too_late" | "item_damaged" | "not_as_described";
+        line_ref: string;
+    }[];
+}, {
+    items: {
+        qty: number;
+        reason: "too_small" | "changed_my_mind" | "too_large" | "arrived_too_late" | "item_damaged" | "not_as_described";
+        line_ref: string;
+    }[];
+}>;
+
+declare type CreateReturnRequest = z.infer<typeof CreateReturnRequest>;
+
 /**
  * The session seam, implemented once at the transport level.
  *
@@ -3000,7 +3292,7 @@ export declare interface EmptyStateProps {
  * | invalid_request    | 400  | malformed body or missing field               |
  * | unauthorized       | 401  | missing/invalid session or credentials        |
  * | out_of_stock       | 409  | requested qty exceeds available stock         |
- * | cart_locked        | 409  | cart handed to checkout; mutations refused    |
+ * | cart_locked        | 409  | RETIRED (ADR-0025); defined, never raised     |
  * | sku_not_found      | 404  | a referenced SKU/product does not exist       |
  * | category_not_found | 404  | a referenced category code does not exist     |
  * | amount_mismatch    | 422  | totals do not match the authorised amount     |
@@ -3023,7 +3315,7 @@ declare type ErrorCode = z.infer<typeof ErrorCode>;
  * | invalid_request    | 400  | malformed body or missing field               |
  * | unauthorized       | 401  | missing/invalid session or credentials        |
  * | out_of_stock       | 409  | requested qty exceeds available stock         |
- * | cart_locked        | 409  | cart handed to checkout; mutations refused    |
+ * | cart_locked        | 409  | RETIRED (ADR-0025); defined, never raised     |
  * | sku_not_found      | 404  | a referenced SKU/product does not exist       |
  * | category_not_found | 404  | a referenced category code does not exist     |
  * | amount_mismatch    | 422  | totals do not match the authorised amount     |
@@ -3079,6 +3371,11 @@ export declare function ExploreList({ title, links }: {
     links: ExploreLink[];
 }): JSX.Element;
 
+/** Why an item is coming back, from Figma's `Reason for return` sheet. */
+declare const FanReturnReason: z.ZodEnum<["too_large", "too_small", "arrived_too_late", "item_damaged", "not_as_described", "changed_my_mind"]>;
+
+declare type FanReturnReason = z.infer<typeof FanReturnReason>;
+
 /** Horizontal chip filter bar for the PLP. Chips are toggle buttons. */
 export declare function FilterBar({ options, active, onToggle, onClear }: FilterBarProps): JSX.Element;
 
@@ -3291,74 +3588,538 @@ export declare interface OrderConfirmationViewProps {
 }
 
 /**
- * The fan's orders (Figma `mobile/order/list`, ADR-0015).
- *
- * Read-only, like the detail screen it links to. Cancellation and returns are DAZN's under
- * ADR-0008, so the design's return states have no data behind them — see
- * {@link OrderStatusBadge}.
- *
- * Scoped to the session at the engine: `GET /v1/orders` takes no customer parameter, so
- * there is no identifier a caller could supply to read somebody else's history.
- */
-export declare function OrderListView(props: OrderListViewProps): JSX.Element;
-
-export declare interface OrderListViewProps {
-    /** Opens one order. Without it the rows render as static cards rather than dead links. */
-    onOpenOrder?: (orderRef: string) => void;
-    /** The empty state's call to action — the design's "Continue shopping" button. */
-    onStartShopping?: () => void;
-    /** Overrides the provider's locale for dates. */
-    locale?: string;
-}
-
-/**
- * One row of the timeline.
- *
- * **`at` is present only for a step that has actually happened.** A future step has no
- * date, rather than a projected one: a predicted date rendered in the same place as a
- * recorded one is indistinguishable from a promise, and this timeline is the fan's
- * evidence of what occurred.
- */
-declare const OrderProgressEntry: z.ZodObject<{
-    step: z.ZodEnum<["packing", "on_its_way", "out_for_delivery", "delivered", "cancelled"]>;
-    /** Ready-to-render label for the step, localised with the rest of the response. */
-    label: z.ZodString;
-    /** When the step completed. Absent = not reached yet. */
-    at: z.ZodOptional<z.ZodString>;
-    /** Exactly one entry is `current`; every earlier one is complete. */
-    current: z.ZodBoolean;
-}, "strip", z.ZodTypeAny, {
-    label: string;
-    step: "packing" | "on_its_way" | "out_for_delivery" | "delivered" | "cancelled";
-    current: boolean;
-    at?: string | undefined;
-}, {
-    label: string;
-    step: "packing" | "on_its_way" | "out_for_delivery" | "delivered" | "cancelled";
-    current: boolean;
-    at?: string | undefined;
-}>;
-
-declare type OrderProgressEntry = z.infer<typeof OrderProgressEntry>;
-
-/**
- * A step in the fan-facing progress timeline.
- *
- * Deliberately NOT the warehouse status enum. That has eight values a picker acts on
- * (`received`, `allocated`, `picking`, `packed`, …) and a fan neither sees nor benefits
- * from the difference between them. The engine collapses them; this is the collapsed form.
+ * `GET /v1/orders/{order_ref}` — one order in full.
  *
- * The set is open-ended on purpose — `out_for_delivery` exists only when a carrier tells us
- * so, and a market with collection would add a step. A consumer must render the steps it is
- * given, in order, and must not assume a fixed count.
+ * **`estimated_delivery` is a window, not a date, and it is advisory.** It comes from the
+ * fulfilment side rather than from DAZN, so it reflects when the warehouse expects to have
+ * it delivered. Absent when nothing can be estimated — which is honest, and better than a
+ * date the fan will hold us to.
  */
-declare const OrderProgressStep: z.ZodEnum<["packing", "on_its_way", "out_for_delivery", "delivered", "cancelled"]>;
-
-declare type OrderProgressStep = z.infer<typeof OrderProgressStep>;
-
-/**
- * Fulfilment order status. Lives here (not in a synchronous order contract) because the
- * engine no longer owns orders (ADR-0008) — order/fulfilment status reaches us only as
+declare const OrderDetail: z.ZodObject<{
+    order_ref: z.ZodBranded<z.ZodString, "OrderRef">;
+    placed_at: z.ZodString;
+    currency: z.ZodString;
+    /**
+     * Where the order confirmation went, for the confirmation screen's "We've sent a
+     * confirmation to ..." line. The address DAZN gave us at intake, echoed back.
+     *
+     * Returned only on the detail read, which is already scoped to the order's own owner,
+     * and never on the list. It is PII: render it, and keep it out of logs and analytics
+     * like every other address in this package.
+     *
+     * Optional because intake's is: a market whose carrier takes no email places orders
+     * without one. Absent means the line is not drawn, never that a placeholder is.
+     */
+    email: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<["packing", "on_its_way", "out_for_delivery", "delivered", "cancelled"]>;
+    headline: z.ZodString;
+    estimated_delivery: z.ZodOptional<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        from: string;
+        to: string;
+    }, {
+        from: string;
+        to: string;
+    }>>;
+    progress: z.ZodArray<z.ZodObject<{
+        step: z.ZodEnum<["packing", "on_its_way", "out_for_delivery", "delivered", "cancelled"]>;
+        /** Ready-to-render label for the step, localised with the rest of the response. */
+        label: z.ZodString;
+        /** When the step completed. Absent = not reached yet. */
+        at: z.ZodOptional<z.ZodString>;
+        /** Exactly one entry is `current`; every earlier one is complete. */
+        current: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        step: "packing" | "on_its_way" | "out_for_delivery" | "delivered" | "cancelled";
+        current: boolean;
+        at?: string | undefined;
+    }, {
+        label: string;
+        step: "packing" | "on_its_way" | "out_for_delivery" | "delivered" | "cancelled";
+        current: boolean;
+        at?: string | undefined;
+    }>, "many">;
+    tracking: z.ZodOptional<z.ZodObject<{
+        carrier: z.ZodString;
+        reference: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        carrier: string;
+        url?: string | undefined;
+        reference?: string | undefined;
+    }, {
+        carrier: string;
+        url?: string | undefined;
+        reference?: string | undefined;
+    }>>;
+    items: z.ZodArray<z.ZodObject<{
+        line_ref: z.ZodString;
+        sku: z.ZodString;
+        qty: z.ZodNumber;
+        unit_price: z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            amount: number;
+            currency: string;
+        }, {
+            amount: number;
+            currency: string;
+        }>;
+        line_total: z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            amount: number;
+            currency: string;
+        }, {
+            amount: number;
+            currency: string;
+        }>;
+        /**
+         * The undiscounted per-unit price, echoed from intake. Display only.
+         *
+         * Drawn as a struck-through price with a saving badge beside what was paid. Absent
+         * means the line was sold at full price, which is the ordinary case; see `OrderLine`
+         * for why this is DAZN's figure and not our catalogue's.
+         */
+        compare_at_unit_price: z.ZodOptional<z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            amount: number;
+            currency: string;
+        }, {
+            amount: number;
+            currency: string;
+        }>>;
+        title: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        /** Variant attributes, e.g. `{ size: 'M' }`. Same shape as everywhere else. */
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /**
+         * Units of this line cancelled or refunded so far. Present so a partially cancelled
+         * order reads honestly instead of showing the original quantity as though nothing
+         * happened. Zero is the normal case and is sent rather than omitted.
+         */
+        cancelled_qty: z.ZodNumber;
+        refunded_qty: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        sku: string;
+        qty: number;
+        unit_price: {
+            amount: number;
+            currency: string;
+        };
+        line_total: {
+            amount: number;
+            currency: string;
+        };
+        line_ref: string;
+        cancelled_qty: number;
+        refunded_qty: number;
+        compare_at_unit_price?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+        title?: string | undefined;
+        image?: string | undefined;
+        attributes?: Record<string, string> | undefined;
+    }, {
+        sku: string;
+        qty: number;
+        unit_price: {
+            amount: number;
+            currency: string;
+        };
+        line_total: {
+            amount: number;
+            currency: string;
+        };
+        line_ref: string;
+        cancelled_qty: number;
+        refunded_qty: number;
+        compare_at_unit_price?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+        title?: string | undefined;
+        image?: string | undefined;
+        attributes?: Record<string, string> | undefined;
+    }>, "many">;
+    ship_to: z.ZodObject<{
+        name: z.ZodString;
+        line1: z.ZodString;
+        line2: z.ZodOptional<z.ZodString>;
+        city: z.ZodString;
+        region: z.ZodOptional<z.ZodString>;
+        postcode: z.ZodString;
+        country: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        country: string;
+        name: string;
+        line1: string;
+        city: string;
+        postcode: string;
+        line2?: string | undefined;
+        region?: string | undefined;
+    }, {
+        country: string;
+        name: string;
+        line1: string;
+        city: string;
+        postcode: string;
+        line2?: string | undefined;
+        region?: string | undefined;
+    }>;
+    payment: z.ZodOptional<z.ZodObject<{
+        brand: z.ZodString;
+        last4: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        brand: string;
+        last4?: string | undefined;
+    }, {
+        brand: string;
+        last4?: string | undefined;
+    }>>;
+    /** Exactly what DAZN charged, echoed. Never recomputed here. */
+    totals: z.ZodObject<{
+        items: z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            amount: number;
+            currency: string;
+        }, {
+            amount: number;
+            currency: string;
+        }>;
+        shipping: z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            amount: number;
+            currency: string;
+        }, {
+            amount: number;
+            currency: string;
+        }>;
+        tax: z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            amount: number;
+            currency: string;
+        }, {
+            amount: number;
+            currency: string;
+        }>;
+        discount: z.ZodOptional<z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            amount: number;
+            currency: string;
+        }, {
+            amount: number;
+            currency: string;
+        }>>;
+        grand_total: z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            amount: number;
+            currency: string;
+        }, {
+            amount: number;
+            currency: string;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        shipping: {
+            amount: number;
+            currency: string;
+        };
+        tax: {
+            amount: number;
+            currency: string;
+        };
+        items: {
+            amount: number;
+            currency: string;
+        };
+        grand_total: {
+            amount: number;
+            currency: string;
+        };
+        discount?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+    }, {
+        shipping: {
+            amount: number;
+            currency: string;
+        };
+        tax: {
+            amount: number;
+            currency: string;
+        };
+        items: {
+            amount: number;
+            currency: string;
+        };
+        grand_total: {
+            amount: number;
+            currency: string;
+        };
+        discount?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+    }>;
+    /**
+     * Whether this order can still be cancelled, and whether it can be returned.
+     *
+     * **Decided by the engine and sent, not derived by the consumer from `status`.** The
+     * rule involves a dispatch cut-off and a returns window that a screen has no way of
+     * knowing, and two consumers deriving it independently would disagree the day either
+     * moves. Absent means no — an older engine that has never heard of either draws
+     * neither button, which is the safe way round for an action that cannot be undone.
+     */
+    can_cancel: z.ZodOptional<z.ZodBoolean>;
+    can_return: z.ZodOptional<z.ZodBoolean>;
+    /** Returns already reported against this order. Absent/empty = none. */
+    returns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        return_ref: z.ZodString;
+        status: z.ZodEnum<["reported", "package_received", "completed"]>;
+        reported_at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        status: "reported" | "package_received" | "completed";
+        return_ref: string;
+        reported_at: string;
+    }, {
+        status: "reported" | "package_received" | "completed";
+        return_ref: string;
+        reported_at: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    status: "packing" | "on_its_way" | "out_for_delivery" | "delivered" | "cancelled";
+    currency: string;
+    items: {
+        sku: string;
+        qty: number;
+        unit_price: {
+            amount: number;
+            currency: string;
+        };
+        line_total: {
+            amount: number;
+            currency: string;
+        };
+        line_ref: string;
+        cancelled_qty: number;
+        refunded_qty: number;
+        compare_at_unit_price?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+        title?: string | undefined;
+        image?: string | undefined;
+        attributes?: Record<string, string> | undefined;
+    }[];
+    totals: {
+        shipping: {
+            amount: number;
+            currency: string;
+        };
+        tax: {
+            amount: number;
+            currency: string;
+        };
+        items: {
+            amount: number;
+            currency: string;
+        };
+        grand_total: {
+            amount: number;
+            currency: string;
+        };
+        discount?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+    };
+    order_ref: string & z.BRAND<"OrderRef">;
+    placed_at: string;
+    ship_to: {
+        country: string;
+        name: string;
+        line1: string;
+        city: string;
+        postcode: string;
+        line2?: string | undefined;
+        region?: string | undefined;
+    };
+    headline: string;
+    progress: {
+        label: string;
+        step: "packing" | "on_its_way" | "out_for_delivery" | "delivered" | "cancelled";
+        current: boolean;
+        at?: string | undefined;
+    }[];
+    email?: string | undefined;
+    payment?: {
+        brand: string;
+        last4?: string | undefined;
+    } | undefined;
+    returns?: {
+        status: "reported" | "package_received" | "completed";
+        return_ref: string;
+        reported_at: string;
+    }[] | undefined;
+    estimated_delivery?: {
+        from: string;
+        to: string;
+    } | undefined;
+    tracking?: {
+        carrier: string;
+        url?: string | undefined;
+        reference?: string | undefined;
+    } | undefined;
+    can_cancel?: boolean | undefined;
+    can_return?: boolean | undefined;
+}, {
+    status: "packing" | "on_its_way" | "out_for_delivery" | "delivered" | "cancelled";
+    currency: string;
+    items: {
+        sku: string;
+        qty: number;
+        unit_price: {
+            amount: number;
+            currency: string;
+        };
+        line_total: {
+            amount: number;
+            currency: string;
+        };
+        line_ref: string;
+        cancelled_qty: number;
+        refunded_qty: number;
+        compare_at_unit_price?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+        title?: string | undefined;
+        image?: string | undefined;
+        attributes?: Record<string, string> | undefined;
+    }[];
+    totals: {
+        shipping: {
+            amount: number;
+            currency: string;
+        };
+        tax: {
+            amount: number;
+            currency: string;
+        };
+        items: {
+            amount: number;
+            currency: string;
+        };
+        grand_total: {
+            amount: number;
+            currency: string;
+        };
+        discount?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+    };
+    order_ref: string;
+    placed_at: string;
+    ship_to: {
+        country: string;
+        name: string;
+        line1: string;
+        city: string;
+        postcode: string;
+        line2?: string | undefined;
+        region?: string | undefined;
+    };
+    headline: string;
+    progress: {
+        label: string;
+        step: "packing" | "on_its_way" | "out_for_delivery" | "delivered" | "cancelled";
+        current: boolean;
+        at?: string | undefined;
+    }[];
+    email?: string | undefined;
+    payment?: {
+        brand: string;
+        last4?: string | undefined;
+    } | undefined;
+    returns?: {
+        status: "reported" | "package_received" | "completed";
+        return_ref: string;
+        reported_at: string;
+    }[] | undefined;
+    estimated_delivery?: {
+        from: string;
+        to: string;
+    } | undefined;
+    tracking?: {
+        carrier: string;
+        url?: string | undefined;
+        reference?: string | undefined;
+    } | undefined;
+    can_cancel?: boolean | undefined;
+    can_return?: boolean | undefined;
+}>;
+
+declare type OrderDetail = z.infer<typeof OrderDetail>;
+
+/**
+ * The fan's orders (Figma `mobile/order/list`, ADR-0015).
+ *
+ * Read-only, like the detail screen it links to. Cancellation and returns are DAZN's under
+ * ADR-0008, so the design's return states have no data behind them — see
+ * {@link OrderStatusBadge}.
+ *
+ * Scoped to the session at the engine: `GET /v1/orders` takes no customer parameter, so
+ * there is no identifier a caller could supply to read somebody else's history.
+ */
+export declare function OrderListView(props: OrderListViewProps): JSX.Element;
+
+export declare interface OrderListViewProps {
+    /** Opens one order. Without it the rows render as static cards rather than dead links. */
+    onOpenOrder?: (orderRef: string) => void;
+    /** The empty state's call to action — the design's "Continue shopping" button. */
+    onStartShopping?: () => void;
+    /** Overrides the provider's locale for dates. */
+    locale?: string;
+}
+
+/**
+ * A step in the fan-facing progress timeline.
+ *
+ * Deliberately NOT the warehouse status enum. That has eight values a picker acts on
+ * (`received`, `allocated`, `picking`, `packed`, …) and a fan neither sees nor benefits
+ * from the difference between them. The engine collapses them; this is the collapsed form.
+ *
+ * The set is open-ended on purpose — `out_for_delivery` exists only when a carrier tells us
+ * so, and a market with collection would add a step. A consumer must render the steps it is
+ * given, in order, and must not assume a fixed count.
+ */
+declare const OrderProgressStep: z.ZodEnum<["packing", "on_its_way", "out_for_delivery", "delivered", "cancelled"]>;
+
+declare type OrderProgressStep = z.infer<typeof OrderProgressStep>;
+
+/**
+ * Fulfilment order status. Lives here (not in a synchronous order contract) because the
+ * engine no longer owns orders (ADR-0008) — order/fulfilment status reaches us only as
  * async events (Odoo → engine → consumers). DAZN is authoritative for completed orders.
  */
 declare const OrderStatus: z.ZodEnum<["confirmed", "packed", "shipped", "delivered", "cancelled", "refunded"]>;
@@ -3397,8 +4158,17 @@ export declare interface OrderSummaryProps {
      * changes at checkout. DAZN owns checkout and therefore owns delivery and tax
      * (ADR-0008), so in the cart both are genuinely unknown rather than genuinely free.
      *
-     * When anything is deferred the grand total is withheld too: a total that omits
-     * delivery is not a total. Subtotal carries the emphasis instead.
+     * **The grand total is still drawn.** It used to be withheld whenever anything here was
+     * deferred, on the reasoning that a total omitting delivery is not a total. DAZN
+     * reviewed that on 21 Aug 2026 against the frame — which draws a Total row — and chose
+     * the frame. So the row is drawn, carrying `pricing.total`, and on a cart that means the
+     * items total: delivery and tax are added at DAZN's checkout and can move it by the
+     * spread the design's own shipping note quotes (standard $5-16, express $15-23).
+     *
+     * Deferring a row therefore now changes only that row. If the withholding is ever
+     * wanted back, it belongs behind an explicit prop rather than as a side effect of
+     * `deferred` — a prop that silently removes a different row is the kind of surprise this
+     * comment exists to prevent.
      */
     deferred?: DeferredLine[];
     /**
@@ -3436,7 +4206,7 @@ export declare interface OrderSummaryProps {
 export declare function OrderTimeline({ progress, estimatedDelivery, locale: localeProp, }: OrderTimelineProps): JSX.Element;
 
 export declare interface OrderTimelineProps {
-    progress: OrderProgressEntry[];
+    progress: readonly TimelineEntry[];
     /**
      * The delivery window, drawn under the last step while that step is still to come.
      *
@@ -3459,14 +4229,18 @@ export declare interface OrderTimelineProps {
  * One screen with three states, and the engine's `progress` is what draws them: the widget
  * says where the parcel is, and everything under it is the same for all three.
  *
- * Read-only by design. The frame's first state carries a "Cancel order" button and its
- * last offers "Start a return"; **cancellation and returns remain DAZN's** under ADR-0008
- * and ADR-0017, and nothing in the tracking contract can express either. A control that
- * cannot complete is worse than an absent one, so neither is drawn here — the return row
- * is a prop for the host that owns the flow.
+ * The frame's first state carries a "Cancel order" button and its last offers a return,
+ * and **both are ours since 21 Aug** (ADR-0024). Cancelling happens in place, through the
+ * reason sheet at the foot of this file; a return is three screens, so "Return items"
+ * navigates to them. Neither moves money: DAZN remain merchant of record, and what the
+ * engine records is a request handed on.
+ *
+ * Both are drawn on the ENGINE's say-so — `can_cancel` is its dispatch cut-off,
+ * `can_return` its returns window. Neither is a status this screen can infer, and it does
+ * not try.
  *
- * "Contact support" is different, and is always drawn: the form behind it is DAZN's too,
- * but the row has somewhere to go without them wiring anything, because pressing it raises
+ * "Contact support" is different again: the form behind it is DAZN's, but the row has
+ * somewhere to go without them wiring anything, because pressing it raises
  * `support_requested`.
  *
  * Below the widget this is the confirmation screen: the same rows, the same two cards, the
@@ -3480,14 +4254,35 @@ export declare interface OrderTrackingViewProps {
     /** Overrides the provider's locale for dates. */
     locale?: string;
     /**
-     * The "Need help?" block's first row, under a delivered order.
+     * Open the return flow.
      *
-     * **Not ours to wire.** Returns are DAZN's under ADR-0008 and nothing in the tracking
-     * contract can start one, so the row is drawn only for a host that owns that flow and
-     * says so by passing a handler. There is no event: we cannot report a return as
-     * requested when nothing can act on it.
+     * **Optional now, and it was once required.** Returns were DAZN's under ADR-0008, so
+     * this used to be the only way the row could appear: a control that cannot complete is
+     * worse than an absent one. ADR-0024 gave us the flow — `POST /v1/orders/{ref}/returns`
+     * and the three screens behind it — so the default is no longer "nothing happens".
+     *
+     * It is still the seam, because the flow is three SCREENS and only the host knows where
+     * its routes are — the same reason `OrderListView` takes `onOpenOrder` rather than
+     * navigating itself. What changed is what the handler leads to: mount `ReturnFlowView`
+     * with this order's reference and the whole flow is there.
+     *
+     * Without it the control is not drawn. The SDK will not offer a button whose destination
+     * does not exist, and that has not changed either.
      */
     onStartReturn?: () => void;
+    /**
+     * Called once the fan has confirmed a cancellation and the engine has accepted it,
+     * with the order as it now stands. The screen redraws itself either way; this is for a
+     * host that wants to react — refresh a list, close a sheet, send an analytics event.
+     */
+    onCancelled?: (order: OrderDetail) => void;
+    /**
+     * The cancelled screen's "Reorder". Omit it and no button renders.
+     *
+     * The host's, because it means "put these items back in a cart and go somewhere", and
+     * only they know where that is. We raise `reorder_requested` regardless.
+     */
+    onReorder?: () => void;
     /**
      * The block's second row, which is always drawn under a delivered order.
      *
@@ -3879,6 +4674,11 @@ export declare interface ProductDetailProps {
  * PDP "Product details" accordion (mobile/pdp/details). Collapsed clamps the body to
  * three lines with a more/less toggle. Only renders when the catalogue provides a
  * description — no placeholder copy is invented.
+ *
+ * The toggle appears only when the clamp is actually hiding something. It used to render
+ * for every description, so a two-line one offered a "more" that expanded to the same two
+ * lines and a "Less" that collapsed to them again — reported from staging, where most
+ * products have a short description.
  */
 export declare function ProductDetails({ description }: ProductDetailsProps): JSX.Element | null;
 
@@ -4052,9 +4852,10 @@ export declare function PromoBanner({ promo }: {
  *
  * When the cap is reached the reason is stated inline rather than the control simply
  * going dead — a disabled `+` with no explanation reads as a bug, and the fan cannot
- * tell "we have no more" from "this is broken".
+ * tell "we have no more" from "this is broken". A caller that already says it passes
+ * {@link QtyStepperProps.capDescribedBy} and gets the wiring without the second copy.
  */
-export declare function QtyStepper({ qty, max, onChange, onRemove, disabled }: QtyStepperProps): JSX.Element;
+export declare function QtyStepper({ qty, max, onChange, onRemove, disabled, capDescribedBy, }: QtyStepperProps): JSX.Element;
 
 export declare interface QtyStepperProps {
     qty: number;
@@ -4064,6 +4865,18 @@ export declare interface QtyStepperProps {
     /** Called when decrementing from 1 (the decrement becomes a delete). */
     onRemove?: () => void;
     disabled?: boolean;
+    /**
+     * Id of an element that already explains the cap, drawn by the caller.
+     *
+     * Pass this when the surrounding screen states the stock itself — the cart line draws
+     * Figma's `Only N left` label under the whole line, and its out-of-stock line scrims the
+     * thumbnail. Given one, the stepper points `aria-describedby` at it and renders no
+     * message of its own, so the two can never say the same thing twice or disagree.
+     *
+     * Without it the stepper explains its own dead `+`, which is the standalone behaviour
+     * and the reason the message exists at all.
+     */
+    capDescribedBy?: string;
 }
 
 /**
@@ -4091,6 +4904,64 @@ export declare interface RailCarouselProps {
     inset?: boolean;
 }
 
+export declare interface ReasonOption<T extends string> {
+    value: T;
+    label: string;
+}
+
+/**
+ * "Pick one reason, then confirm" — Figma `Reason for cancelling` (4632:17129) and
+ * `Reason for return`.
+ *
+ * One component for both, because they are one component in the file: the same sheet, the
+ * same rows, the same footer, differing only in their title, their options and the word on
+ * the button. Building two would be two things to keep in step.
+ *
+ * **The confirm button starts disabled and the sheet does not preselect anything.** A
+ * reason is the fan's statement about their own order, and a default would put words in
+ * their mouth that the first tap then submits.
+ */
+export declare function ReasonSheet<T extends string>({ title, options, ctaLabel, selected, onConfirm, onClose, closeLabel, busy, error, }: ReasonSheetProps<T>): JSX.Element;
+
+export declare interface ReasonSheetProps<T extends string> {
+    title: string;
+    options: readonly ReasonOption<T>[];
+    /** The confirm button's label — "Cancel order" on one sheet, "Select" on the other. */
+    ctaLabel: string;
+    /** Pre-selected value, for a sheet reopened on a line that already has a reason. */
+    selected?: T;
+    onConfirm: (value: T) => void;
+    onClose: () => void;
+    /** What the close control is called to assistive technology. */
+    closeLabel: string;
+    /** Marks the confirm button busy while the request is in flight. */
+    busy?: boolean;
+    /**
+     * A failure from the action this sheet confirms, shown above the button.
+     *
+     * On the sheet rather than replacing the screen behind it: the order is still fine, it
+     * is the request that failed, and the fan's next move is to press the same button again.
+     */
+    error?: string;
+}
+
+/**
+ * `POST /v1/orders/{order_ref}/cancellation`
+ *
+ * The whole order. Figma offers no per-line cancel and neither does this: the sheet has
+ * one reason and one button, and a partial cancellation the fan cannot express is not a
+ * shape worth carrying.
+ */
+declare const RequestCancellationRequest: z.ZodObject<{
+    reason: z.ZodEnum<["changed_my_mind", "ordered_by_mistake", "delivery_too_long"]>;
+}, "strict", z.ZodTypeAny, {
+    reason: "changed_my_mind" | "ordered_by_mistake" | "delivery_too_long";
+}, {
+    reason: "changed_my_mind" | "ordered_by_mistake" | "delivery_too_long";
+}>;
+
+declare type RequestCancellationRequest = z.infer<typeof RequestCancellationRequest>;
+
 /**
  * Resolve an asset path against the host-configured asset base.
  *
@@ -4116,6 +4987,283 @@ export declare function resolveAssetUrl(src: string, base?: string): string;
  */
 export declare function resolveSku(variants: ProductVariant[], size: string | null, colour: string | null): string | null;
 
+/**
+ * The reasons the frame offers, in the frame's order.
+ *
+ * Ordered by how often a fan picks them rather than alphabetically, which is the design's
+ * choice and not ours to re-sort: the two sizing reasons lead because sizing is what most
+ * clothing returns are about.
+ */
+export declare const RETURN_REASONS: readonly ReasonOption<FanReturnReason>[];
+
+/**
+ * `GET /v1/returns/{return_ref}` — one return in full.
+ *
+ * `label_url` is **opaque and short-lived**, like carrier tracking: render it as a
+ * download, never rebuild it. Absent means the label is not ready, and the screen says so
+ * rather than offering a button that 404s — the frame's own copy promises the PDF by email
+ * as well, which is the path that does not depend on this link still working.
+ */
+declare const ReturnDetail: z.ZodObject<{
+    return_ref: z.ZodString;
+    order_ref: z.ZodBranded<z.ZodString, "OrderRef">;
+    status: z.ZodEnum<["reported", "package_received", "completed"]>;
+    reported_at: z.ZodString;
+    progress: z.ZodArray<z.ZodObject<{
+        step: z.ZodEnum<["reported", "package_received", "completed"]>;
+        label: z.ZodString;
+        /** When the step completed. Absent = not reached yet, never a projected date. */
+        at: z.ZodOptional<z.ZodString>;
+        current: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        step: "reported" | "package_received" | "completed";
+        current: boolean;
+        at?: string | undefined;
+    }, {
+        label: string;
+        step: "reported" | "package_received" | "completed";
+        current: boolean;
+        at?: string | undefined;
+    }>, "many">;
+    items: z.ZodArray<z.ZodObject<{
+        line_ref: z.ZodString;
+        sku: z.ZodString;
+        qty: z.ZodNumber;
+        reason: z.ZodEnum<["too_large", "too_small", "arrived_too_late", "item_damaged", "not_as_described", "changed_my_mind"]>;
+        unit_price: z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            amount: number;
+            currency: string;
+        }, {
+            amount: number;
+            currency: string;
+        }>;
+        compare_at_unit_price: z.ZodOptional<z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            amount: number;
+            currency: string;
+        }, {
+            amount: number;
+            currency: string;
+        }>>;
+        title: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        sku: string;
+        qty: number;
+        unit_price: {
+            amount: number;
+            currency: string;
+        };
+        reason: "too_small" | "changed_my_mind" | "too_large" | "arrived_too_late" | "item_damaged" | "not_as_described";
+        line_ref: string;
+        compare_at_unit_price?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+        title?: string | undefined;
+        image?: string | undefined;
+        attributes?: Record<string, string> | undefined;
+    }, {
+        sku: string;
+        qty: number;
+        unit_price: {
+            amount: number;
+            currency: string;
+        };
+        reason: "too_small" | "changed_my_mind" | "too_large" | "arrived_too_late" | "item_damaged" | "not_as_described";
+        line_ref: string;
+        compare_at_unit_price?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+        title?: string | undefined;
+        image?: string | undefined;
+        attributes?: Record<string, string> | undefined;
+    }>, "many">;
+    label_url: z.ZodOptional<z.ZodString>;
+    /**
+     * Where the label PDF was sent, for the frame's "You'll receive a shipping label PDF to
+     * your email as well" line. PII, like `OrderDetail.email`: render it, never log it.
+     */
+    label_email: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "reported" | "package_received" | "completed";
+    items: {
+        sku: string;
+        qty: number;
+        unit_price: {
+            amount: number;
+            currency: string;
+        };
+        reason: "too_small" | "changed_my_mind" | "too_large" | "arrived_too_late" | "item_damaged" | "not_as_described";
+        line_ref: string;
+        compare_at_unit_price?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+        title?: string | undefined;
+        image?: string | undefined;
+        attributes?: Record<string, string> | undefined;
+    }[];
+    order_ref: string & z.BRAND<"OrderRef">;
+    return_ref: string;
+    reported_at: string;
+    progress: {
+        label: string;
+        step: "reported" | "package_received" | "completed";
+        current: boolean;
+        at?: string | undefined;
+    }[];
+    label_url?: string | undefined;
+    label_email?: string | undefined;
+}, {
+    status: "reported" | "package_received" | "completed";
+    items: {
+        sku: string;
+        qty: number;
+        unit_price: {
+            amount: number;
+            currency: string;
+        };
+        reason: "too_small" | "changed_my_mind" | "too_large" | "arrived_too_late" | "item_damaged" | "not_as_described";
+        line_ref: string;
+        compare_at_unit_price?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+        title?: string | undefined;
+        image?: string | undefined;
+        attributes?: Record<string, string> | undefined;
+    }[];
+    order_ref: string;
+    return_ref: string;
+    reported_at: string;
+    progress: {
+        label: string;
+        step: "reported" | "package_received" | "completed";
+        current: boolean;
+        at?: string | undefined;
+    }[];
+    label_url?: string | undefined;
+    label_email?: string | undefined;
+}>;
+
+declare type ReturnDetail = z.infer<typeof ReturnDetail>;
+
+/**
+ * The return flow, end to end — Figma `Return flow` (4551:32294).
+ *
+ * **This is the piece that was missing.** `ReturnItemsView`, `ReturnLabelView` and
+ * `ReturnTrackingView` are presentational: they take an order or a return and draw it.
+ * Something has to load the order, post what the fan chose, and move between the three,
+ * and until now nothing did — the screens were exported and nothing in this package or in
+ * the app mounted them, so a flow that was built could not be reached.
+ *
+ * The shape follows `OrderTrackingView`: a container that owns the fetch and the state,
+ * around views that own the drawing. Same reason as there — a screen that loads itself is
+ * one a host can mount from a route with nothing but a reference.
+ *
+ * **It settles no money and it is not a refund** (ADR-0024). It records goods coming back
+ * so the warehouse can expect them; DAZN remain merchant of record and tell us about the
+ * refund afterwards through the inbound event.
+ */
+export declare function ReturnFlowView(props: ReturnFlowViewProps): JSX.Element;
+
+export declare interface ReturnFlowViewProps {
+    /** DAZN's order reference. Required to START a return. */
+    orderRef?: string;
+    /**
+     * An existing return, e.g. `ord_GB26081021-R1`. Given one, the flow opens on its
+     * progress instead of on the item picker — which is what the "Return in progress" row
+     * on the order screen leads to.
+     */
+    returnRef?: string;
+    /** The label screen's "Done". Where it goes is the host's. */
+    onDone?: () => void;
+    /** Overrides the provider's locale for dates. */
+    locale?: string;
+}
+
+/**
+ * "What do you want to return?" — Figma `Return flow` (4551:32294), screens 2 to 4.
+ *
+ * **A line is returnable only once it has a reason**, which is why the reason lives inside
+ * the card rather than being asked once for the whole return: the frame puts a `Select
+ * reason` control in every row, and a fan sending back two garments for two different
+ * reasons is the ordinary case rather than an edge one.
+ *
+ * Quantity is not asked for. The frame offers no stepper, so a selected line returns in
+ * full — and inventing a control the design does not draw would be the wrong way to
+ * discover we needed one.
+ */
+export declare function ReturnItemsView({ order, onSubmit, busy }: ReturnItemsViewProps): JSX.Element;
+
+export declare interface ReturnItemsViewProps {
+    order: OrderDetail;
+    /** Called with the lines the fan chose. The caller posts them and shows the label. */
+    onSubmit: (items: ReturnRequestItem[]) => void;
+    /** Set while the request is in flight. */
+    busy?: boolean;
+}
+
+/**
+ * "We've generated your return label" — Figma `Return flow` (4551:32294), screen 5.
+ *
+ * Two numbered steps and a download. The label is offered as a link rather than a
+ * scripted download because the sheet a fan sees this in may be a webview, and a
+ * script-driven save is exactly what a webview blocks.
+ *
+ * **The button is only drawn when there is a label.** The frame promises the PDF by email
+ * as well, and that promise is the one that survives a link this screen cannot produce —
+ * so when `label_url` is absent the email line still tells the fan where to look, and no
+ * button is offered that would 404.
+ */
+export declare function ReturnLabelView({ ret, onDone }: ReturnLabelViewProps): JSX.Element;
+
+export declare interface ReturnLabelViewProps {
+    ret: ReturnDetail;
+    /** The frame's "Done". Where it goes is the host's — see `OrderConfirmationView`. */
+    onDone?: () => void;
+}
+
+/**
+ * One line the fan is sending back.
+ *
+ * `qty` rather than a flag, because a line of three can have one returned, and `reason`
+ * per line rather than per return, because the screen asks for it per line — the frame
+ * puts a "Select reason" row inside each item card.
+ */
+declare const ReturnRequestItem: z.ZodObject<{
+    line_ref: z.ZodString;
+    qty: z.ZodNumber;
+    reason: z.ZodEnum<["too_large", "too_small", "arrived_too_late", "item_damaged", "not_as_described", "changed_my_mind"]>;
+}, "strip", z.ZodTypeAny, {
+    qty: number;
+    reason: "too_small" | "changed_my_mind" | "too_large" | "arrived_too_late" | "item_damaged" | "not_as_described";
+    line_ref: string;
+}, {
+    qty: number;
+    reason: "too_small" | "changed_my_mind" | "too_large" | "arrived_too_late" | "item_damaged" | "not_as_described";
+    line_ref: string;
+}>;
+
+declare type ReturnRequestItem = z.infer<typeof ReturnRequestItem>;
+
+export declare function ReturnTrackingView({ ret, locale: localeProp }: ReturnTrackingViewProps): JSX.Element;
+
+export declare interface ReturnTrackingViewProps {
+    ret: ReturnDetail;
+    /** Overrides the provider's locale for the reported date. */
+    locale?: string;
+}
+
 declare interface Review {
     quote: string;
     author: string;
@@ -4182,6 +5330,23 @@ declare const SessionExchangeRequest: z.ZodObject<{
 
 declare type SessionExchangeRequest = z.infer<typeof SessionExchangeRequest>;
 
+/**
+ * The design's `.sheet-header` (404:5379): an empty 48 slot, the drag handle, and a close
+ * disc — 48 tall.
+ *
+ * Three slots rather than two, so the handle is centred on the SHEET rather than on what
+ * is left of it once the close control has taken its corner. Drawn once here because the
+ * size guide and both reason sheets instance the same component, and a second hand-built
+ * copy is a second one to drift.
+ */
+export declare function SheetHeader({ onClose, closeLabel }: SheetHeaderProps): JSX.Element;
+
+export declare interface SheetHeaderProps {
+    onClose: () => void;
+    /** What the close control is called to assistive technology, e.g. "Close size guide". */
+    closeLabel: string;
+}
+
 /**
  * PDP shipping & returns block (mobile/pdp/shipping-info). Static informational copy —
  * no free-shipping threshold (per design). The shopper picks the delivery tier at
@@ -4266,6 +5431,36 @@ export declare type ShopEvent = {
 | {
     type: 'support_requested';
     orderRef: string;
+}
+/**
+* The fan confirmed a cancellation and the engine accepted it (ADR-0024).
+*
+* Raised after the write succeeds, never on the tap: this is a statement that an order
+* has been cancelled, and a host acting on it — refreshing a list, telling analytics —
+* must not act on one that then failed.
+*/
+| {
+    type: 'order_cancellation_requested';
+    orderRef: string;
+    reason: string;
+}
+/** "Reorder" on a cancelled order. The host owns where that goes; we only announce it. */
+| {
+    type: 'reorder_requested';
+    orderRef: string;
+}
+/**
+* A return has been RECORDED — the engine accepted it and minted the reference.
+*
+* Raised after the write, like the cancellation above, and for the same reason: a host
+* counting returns must not count one the engine refused. It is not a refund and must
+* not be treated as one; DAZN remain merchant of record and say what is paid back
+* (ADR-0024).
+*/
+| {
+    type: 'return_requested';
+    orderRef: string;
+    returnRef: string;
 } | {
     type: 'checkout_handoff';
     cartId: string;
@@ -4813,6 +6008,22 @@ declare type SupportTicketRequest = z.infer<typeof SupportTicketRequest>;
 
 export declare function swatchColour(name: string): string;
 
+/**
+ * One row, structurally.
+ *
+ * Deliberately not `OrderProgressEntry` itself. The return timeline (ADR-0024) is drawn
+ * by the same Figma component with a different set of steps — reported, received,
+ * completed — so its entries carry a different `step` enum and would not assign. Nothing
+ * here interprets `step` beyond keying on it, so the widened type costs nothing and saves
+ * a second copy of the timeline that would drift from this one.
+ */
+declare interface TimelineEntry {
+    step: string;
+    label: string;
+    at?: string;
+    current: boolean;
+}
+
 /** An optional inline action, e.g. the undo offered after removing a cart line. */
 export declare interface ToastAction {
     label: string;