@asstio-dev/storefront 0.18.0 → 0.19.0

package/README.md

@@ -436,6 +436,8 @@ Problem codes you will meet here: `CART_EMPTY`, `CHECKOUT_CART_CHANGED` (with `c
   Qliro shows the confirmed total or version.
 - When our validation declines a purchase (the cart moved on, the attempt expired, a line is out of stock), Qliro shows
   its out-of-stock message and fires `q1.onPaymentDeclined`; the SDK then syncs by itself and remounts or resumes.
+- `q1` callbacks replace per event. The SDK owns `onOrderUpdated` and `onPaymentDeclined`, and with `onShipping` also
+  `onShippingMethodChanged` and `onShippingPriceChanged`: a listener of your own on these silently stops the SDK's.
 
 #### Kustom (`klarna-kco`)
 
@@ -457,6 +459,8 @@ Problem codes you will meet here: `CART_EMPTY`, `CHECKOUT_CART_CHANGED` (with `c
 - Never bind `can_not_complete_order` yourself through `window._klarnaCheckout(api => api.on(...))`. Kustom's `api.on`
   replaces the listener per event instead of adding one, so yours and the SDK's would replace each other. Use
   `onProblem`. Listeners for other events are not affected.
+  With `onShipping` set (see "Live shipping view" below) the SDK also owns `shipping_option_change`,
+  `shipping_address_change` and `order_total_change` (one separate `api.on`); use `onShipping` for those.
 - **CSP hosts** (K-C10, `docs/ops/kustom-playground-checks.md`, 2026-10-09: a card with 3-D Secure and the default
   method, no blocked request). The checkout page itself loads only Kustom's script host. Everything else
   (`kco.assets.kustomcdn.co`, Klarna, Stripe, hCaptcha, Google Pay, Amazon Pay) loads inside Kustom's iframe under
@@ -505,6 +509,40 @@ if (estimate?.available) {
   normally held in Asstio with its reason (rarely the export waits for an operator instead); the page has nothing to
   do for it.
 
+#### Live shipping view
+
+Optionally show what the shopper has chosen inside the widget, from `GET /v1/checkout/{attemptId}/shipping`. The view is
+not a promise: the order's `lines` and `totals` stay the truth.
+
+```ts
+// Server route: forwards the view and Retry-After. The cart token stays on the server.
+const r = await liveShippingFor(client, cartToken, attemptId);
+// r.ok ? r.data : r.problem, with r.retryAfter as the Retry-After header
+
+// Page:
+mountCheckout(el, widget, {
+  /* … */
+  liveShipping: (attemptId) => callMyProxy(attemptId), // returns LiveShippingResult
+  onShipping: (view) => {
+    if (view === null) return showEstimate();            // invalidated: a change is in flight
+    if (view.state === "selected") showLine(view.name, view.shippingInc, view.totalInc);
+  },
+});
+```
+
+- `liveShipping` and `onShipping` are required together (one without the other throws at mount). Without them nothing
+  shipping-related is bound, scheduled or called.
+- `view.state`: `selected`, `unselected`, `unmatched`, `unavailable` (with `reason`: `syncing`, `closed`, `provider`,
+  `throttled`, `mismatch`, `erased`, `not_supported`, and `retryAfterSeconds`).
+- Members: `goodsInc`, `shippingInc`, `totalInc`, `otherInc`, `totalSource`, `option`, `name`, `deliveryType`, `point`,
+  `readAt`, `cartVersion`. `totalInc` is the provider-reported total, before payment-method charges the provider does
+  not report before purchase. `name` can differ from Kustom's display copy.
+- Freshness: a method change on both providers, and an address change on Kustom, typically follows the provider's event
+  within a couple of seconds. A Kustom pickup-point change and a Qliro address change fire no client event we know of and
+  are seen only by the safety net (every 45 to 60 s, best-effort, up to about 60 s), which runs only while the tab is
+  visible.
+- The SDK owns the provider's shipping events while `onShipping` is set; do not bind them yourself.
+
 ## Headers
 
 Every call the client makes carries these; you never set them by hand.

package/dist/checkout/browser.d.ts

@@ -1,5 +1,5 @@
 import { type ProviderWindow } from "./controllers.js";
-import { type CheckoutDto, type CheckoutOrderRefDto, type CheckoutResult, type StatusResult, type StorefrontProblem } from "./types.js";
+import { type CheckoutDto, type CheckoutOrderRefDto, type CheckoutResult, type CheckoutShippingViewDto, type LiveShippingResult, type StatusResult, type StorefrontProblem } from "./types.js";
 export interface MinimalScript {
     src: string;
     textContent: string | null;
@@ -62,6 +62,12 @@ export interface MountOptions {
     bindRetryMs?: number;
     /** How long before `expiresInSeconds` the SDK syncs by itself (inside the server's five-minute window). */
     preExpiryMs?: number;
+    /** A `GET /checkout/{attemptId}/shipping` on the attempt named (server-side, with the cart token, e.g.
+     * `liveShippingFor`). Must be provided together with `onShipping`; one without the other throws at mount. */
+    liveShipping?: (attemptId: string) => Promise<LiveShippingResult>;
+    /** Receives the live shipping view; `null` means invalidated: show the estimate or a placeholder. Must be provided
+     * together with `liveShipping`. Without both, nothing shipping-related is bound, scheduled or called. */
+    onShipping?: (view: CheckoutShippingViewDto | null) => void;
 }
 export interface CheckoutHandle {
     readonly attemptId: string;
@@ -73,4 +79,10 @@ export interface CheckoutHandle {
     /** The whole rule: suspend → `await update()` once → status first, identity on `open`. Never rejects. */
     sync(update: () => Promise<CheckoutResult>): Promise<void>;
 }
+/** Kustom replays its events once, about 1 s after the first `api.on` registration (K-L15). A shipping event within this
+ * window of a mount's first successful shipping subscription, before any later event, is that replay: it carries no
+ * change, so it is not an invalidation. It joins the explicit first read if that read has not started, and is dropped
+ * if a read already started at or after the subscription (that read already covers it). Applied to `klarna-kco` only:
+ * no other provider replays, so their events always invalidate. */
+export declare const REPLAY_WINDOW_MS = 1500;
 export declare function mountCheckout(container: MinimalElement, checkout: CheckoutDto, options: MountOptions): CheckoutHandle;

package/dist/checkout/browser.js

@@ -1,7 +1,16 @@
 import { controllerFor } from "./controllers.js";
+import { createLiveShippingObserver } from "./live-shipping.js";
 import { localProblem } from "./types.js";
 const FINAL_ORDER = new Set(["completed", "pending"]);
+/** Kustom replays its events once, about 1 s after the first `api.on` registration (K-L15). A shipping event within this
+ * window of a mount's first successful shipping subscription, before any later event, is that replay: it carries no
+ * change, so it is not an invalidation. It joins the explicit first read if that read has not started, and is dropped
+ * if a read already started at or after the subscription (that read already covers it). Applied to `klarna-kco` only:
+ * no other provider replays, so their events always invalidate. */
+export const REPLAY_WINDOW_MS = 1500;
 export function mountCheckout(container, checkout, options) {
+    if ((options.liveShipping === undefined) !== (options.onShipping === undefined))
+        throw new Error("liveShipping and onShipping must be provided together");
     if (checkout.status !== "open" || !checkout.widget)
         throw new Error("mountCheckout needs an `open` answer with a widget");
     const doc = options.document ?? globalThis.document;
@@ -36,6 +45,7 @@ export function mountCheckout(container, checkout, options) {
     let queue = Promise.resolve(); // *(plan review 1 #43)*
     let unsubscribeDeclined;
     let unsubscribeCannotComplete;
+    let unsubscribeShipping;
     let expiryTimer;
     let firedPreExpiryFor; // *(plan review 1 #42, plan review 2 #12)*
     // Every pending sleep's resolver, so a remount or destroy can settle it instead of clearing its timer and leaving
@@ -79,6 +89,87 @@ export function mountCheckout(container, checkout, options) {
         if (alive(gen))
             options.onProblem(localProblem(code, message(e)), { status: 0 });
     }
+    // ---- Live shipping (spec 2026-10-12 §4.6) ---------------------------------------------------------------------
+    // A separate observation flow, never driven through `dispatch` or `poll`. One observer per mount: a remount or destroy
+    // destroys it, so an answer or a provider callback of an older mount is dropped. Without `onShipping` it never exists.
+    let observer;
+    let observerSuspended = false; // the observer was told `suspended()` and not yet `resumed()`
+    let observerResumeReady = false; // the provider reported it is resumed (or this mount is fresh): resume once drained
+    let shippingBoundAt; // this mount's first successful shipping subscription
+    let lastReadAt; // when this mount's observer last started a read
+    let replayOver = false; // a non-replay shipping event was handled on this mount
+    function createObserver(gen) {
+        if (!options.onShipping || !options.liveShipping)
+            return undefined;
+        const onShipping = options.onShipping;
+        const liveShipping = options.liveShipping;
+        let reported = false; // SDK_LIVE_SHIPPING_FAILED once per mount, for liveShipping and onShipping alike
+        const report = (e) => {
+            if (reported || !alive(gen))
+                return;
+            reported = true;
+            try {
+                reportLocal(gen, "SDK_LIVE_SHIPPING_FAILED", e);
+            }
+            catch { /* an app callback: never reaches checkout */ }
+        };
+        shippingBoundAt = undefined;
+        lastReadAt = undefined;
+        replayOver = false;
+        return createLiveShippingObserver({
+            // A synchronous throw and a rejection are both reported, then rethrown: the observer still sees a failed read.
+            // The attempt is read at call time.
+            read: async () => {
+                lastReadAt = now();
+                try {
+                    return await liveShipping(attemptId);
+                }
+                catch (e) {
+                    report(e);
+                    throw e;
+                }
+            },
+            deliver: (view) => {
+                if (!alive(gen))
+                    return;
+                try {
+                    onShipping(view);
+                }
+                catch (e) {
+                    report(e);
+                }
+            },
+            now,
+            // The handle's timers, so a remount or destroy cancels them with every other.
+            setTimeout: (fn, ms) => { const h = setT(() => { timers.delete(h); fn(); }, ms); timers.add(h); return h; },
+            clearTimeout: (h) => { clearT(h); timers.delete(h); },
+            visible: () => doc.visibilityState === "visible",
+            random: Math.random,
+        });
+    }
+    function observerSuspend() {
+        if (!observer)
+            return;
+        observerResumeReady = false;
+        if (observerSuspended)
+            return;
+        observerSuspended = true;
+        observer.suspended();
+    }
+    /** The refresh after a sync waits for both: the provider is actually resumed and the sync queue has drained. */
+    function observerTryResume() {
+        if (!observer || !observerSuspended || !observerResumeReady || active > 0)
+            return;
+        observerSuspended = false;
+        observerResumeReady = false;
+        observer.resumed();
+    }
+    function observerProviderResumed(target) {
+        if (!observer || observer !== target)
+            return;
+        observerResumeReady = true;
+        observerTryResume();
+    }
     function render(dto) {
         const w = dto.widget;
         container.innerHTML = "";
@@ -108,6 +199,7 @@ export function mountCheckout(container, checkout, options) {
     }
     function suspend() {
         suspended = true;
+        observerSuspend();
         if (suspendedOn === controller)
             return;
         // Recorded before the call, as on main: a controller whose suspend throws (a broken provider `lock()`) stays recorded, so a
@@ -124,6 +216,13 @@ export function mountCheckout(container, checkout, options) {
         suspendedOn = undefined;
         controller.resume(target);
     } }
+    /** The app's own `handle.resume()`: no confirmed answer to wait for, so the observer resumes once the queue drains. */
+    function appResume() {
+        const was = suspended;
+        resume();
+        if (was)
+            observerProviderResumed(observer);
+    }
     // ---- The locked burst (spec §10.3) ---------------------------------------------------------------------------
     /** One SDK-owned `POST /checkout`; a transport rejection is reported and swallowed — the caller stops, the widget
      * stays suspended and the queue is released *(plan review 2 #17)*. Posted directly: the rolling-minute ledger, its
@@ -191,6 +290,8 @@ export function mountCheckout(container, checkout, options) {
         unsubscribeDeclined = undefined;
         unsubscribeCannotComplete?.();
         unsubscribeCannotComplete = undefined;
+        unsubscribeShipping?.();
+        unsubscribeShipping = undefined;
         controller = bound;
         const gen = generation;
         // `render` appends the provider's script; it has not executed when this runs, so the global the controller reads
@@ -219,6 +320,25 @@ export function mountCheckout(container, checkout, options) {
         // Spec F §7.1: Kustom's can_not_complete_order is the app's problem to show, not a validation decline (no sync).
         bind(bound.onCannotComplete, () => { if (alive(gen))
             options.onProblem(localProblem("SDK_PROVIDER_CANNOT_COMPLETE", "can_not_complete_order"), { status: 0 }); }, (off) => { unsubscribeCannotComplete = off; });
+        // Live shipping: only with `onShipping`. The provider's shipping signals are a trigger only (spec §4.6).
+        const obs = observer;
+        // Only Kustom replays its shipping events after registration (K-L15); every other provider's event is real, also
+        // inside the window, and always invalidates *(final review B)*.
+        const replays = dto.widget.controller === "klarna-kco";
+        const onShippingEvent = () => {
+            if (!alive(gen))
+                return;
+            if (replays && !replayOver && shippingBoundAt !== undefined && now() - shippingBoundAt <= REPLAY_WINDOW_MS) {
+                // Kustom's replay: no invalidation. Covered by a read started since the subscription, else it joins the first read.
+                if (lastReadAt === undefined || lastReadAt < shippingBoundAt)
+                    obs.trigger("first");
+                return;
+            }
+            replayOver = true;
+            obs.trigger("event");
+        };
+        if (obs)
+            bind(bound.onShippingEvent, onShippingEvent, (off) => { unsubscribeShipping = off; shippingBoundAt ??= now(); });
     }
     function remount(dto) {
         if (dto.status !== "open" || !dto.widget)
@@ -227,11 +347,20 @@ export function mountCheckout(container, checkout, options) {
         // dispatch's catch reports it instead of dropping it for a generation that moved on *(final review B3 T2)*.
         const next = controllerFor(dto.widget.controller, win, controllerTimer);
         controller.dispose?.(); // spec F §7.1: the old mount's deferred callbacks and timers do nothing now
+        observer?.destroy(); // the old observation's sequence is gone with its mount
         generation++;
         cancelTimers(); // *(plan review 1 #37)*
         expiryTimer = undefined;
         firedPreExpiryFor = undefined;
         attemptId = dto.attemptId;
+        // The new mount owns the recovery read: invalidate (`null`) now, read once the sync queue has drained — a remount
+        // inside a dispatch runs while `active > 0`, so the refresh is queued, never skipped (spec §4.6 Resume). The new
+        // widget needs no provider resume signal (no controller call after a remount); a sync still queued suspends it again.
+        observer = createObserver(generation);
+        observerSuspended = false;
+        observerResumeReady = false;
+        observerSuspend();
+        observerResumeReady = !!observer;
         // The ruling of round 1 #39: no controller call after a remount (the new widget's script has not loaded), and the
         // flag is cleared. Unless a sync is queued behind the one running: then payment stays suspended, and that sync
         // suspends the new controller when it starts (`suspendedOn` is cleared) *(plan review 2 #11)*.
@@ -240,6 +369,7 @@ export function mountCheckout(container, checkout, options) {
         render(dto);
         bindProvider(dto, next);
         armExpiry(dto);
+        observerTryResume();
     }
     const onVisible = () => { if (!destroyed && suspended && doc.visibilityState === "visible")
         autonomousSync("visible", generation); };
@@ -302,6 +432,7 @@ export function mountCheckout(container, checkout, options) {
             finally {
                 active--;
                 release();
+                observerTryResume(); // the refresh after a sync waits for the queue to drain (spec §4.6 Resume)
             }
         })();
     }
@@ -356,9 +487,13 @@ export function mountCheckout(container, checkout, options) {
                     // Another update is queued behind this one: its mutation is still to come, so payment stays suspended
                     // until its own answer *(plan review 2 #11)*. The provider unlocks once its view shows `dto.cart`; if it
                     // never does, the widget is re-rendered from this answer *(plan review 1 #3)*.
-                    if (active <= 1)
+                    if (active <= 1) {
+                        const obs = observer;
                         resume({ cart: dto.cart, cartVersion: Number(dto.cartVersion), onUnsynced: () => { if (alive(gen))
-                                remount(dto); } });
+                                remount(dto); },
+                            onResumed: () => { if (alive(gen))
+                                observerProviderResumed(obs); } });
+                    }
                 }
                 else {
                     remount(dto);
@@ -428,11 +563,15 @@ export function mountCheckout(container, checkout, options) {
     const handle = {
         get attemptId() { return attemptId; },
         get suspended() { return suspended; },
-        suspend, resume, remount,
+        suspend, resume: appResume, remount,
         destroy() {
             destroyed = true;
             generation++;
+            observer?.destroy();
+            observer = undefined;
             cancelTimers(); // *(plan review 1 #37)*
+            unsubscribeShipping?.();
+            unsubscribeShipping = undefined;
             unsubscribeDeclined?.();
             unsubscribeDeclined = undefined;
             unsubscribeCannotComplete?.();
@@ -456,8 +595,12 @@ export function mountCheckout(container, checkout, options) {
             });
         },
     };
+    observer = createObserver(generation);
     render(checkout);
     bindProvider(checkout);
     armExpiry(checkout);
+    // The explicit first read: Kustom replays its events once after the first registration and Qliro never replays, so the
+    // first view never depends on a provider event; a replay inside the debounce coalesces with it (spec §4.6 Binding).
+    observer?.trigger("first");
     return handle;
 }

package/dist/checkout/controllers.d.ts

@@ -20,6 +20,10 @@ export interface ProviderWindow {
         /** Fires when our validation callback declined the purchase, with the `DeclineReason` it answered
          * (developers.qliro.com → Listeners). */
         onPaymentDeclined?(cb: (declineReason?: string, declineReasonMessage?: string) => void): void;
+        /** Shipping listeners (developers.qliro.com → Listeners). Registration replaces per event and nothing replays; the
+         * payload is never read, a call is only a refresh trigger. */
+        onShippingMethodChanged?(cb: (payload?: unknown) => void): void;
+        onShippingPriceChanged?(cb: (price?: unknown) => void): void;
     };
     _klarnaCheckout?: (cb: (api: KlarnaCheckoutApi) => void) => void;
     walley?: {
@@ -42,6 +46,10 @@ export interface ResumeTarget {
     cartVersion?: number;
     /** The provider never showed `cart` before its deadline: the handle re-renders the widget from the confirmed answer. */
     onUnsynced(): void;
+    /** The provider is actually resumed: Qliro on the matching `onOrderUpdated` (with the unlock), Kustom after `api.resume()`
+     * ran, Walley after its `resume()`; at once when nothing was held (the provider global is missing, or Kustom's throws).
+     * Never called on a Qliro deadline, nor when Qliro's lock was missed (that is `onUnsynced`). */
+    onResumed?(): void;
 }
 export interface CheckoutController {
     /** Returns `false` when the suspension could not be handed to the provider yet (its script has not defined its API): the
@@ -57,6 +65,10 @@ export interface CheckoutController {
     /** The provider says no offered payment method can complete the order (Kustom's `can_not_complete_order`). Same binding
      * contract as `onDeclined`: `undefined` until the provider's script exposes it. */
     onCannotComplete?(handler: () => void): (() => void) | undefined;
+    /** The provider's shipping-change signals (Kustom `shipping_option_change`, `shipping_address_change`,
+     * `order_total_change`; Qliro `onShippingMethodChanged`, `onShippingPriceChanged`). The handler is only a trigger. Same
+     * binding contract as `onDeclined`: `undefined` until the provider's script exposes the signals; returns the unsubscribe. */
+    onShippingEvent?(handler: () => void): (() => void) | undefined;
     /** This mount is over (remount, destroy): every deferred provider callback and timer of this controller does nothing after it. */
     dispose?(): void;
 }
@@ -68,9 +80,13 @@ export type ControllerFactory = (win: ProviderWindow, timer: ControllerTimer) =>
 /** How long `qliro-q1`'s resume waits for `q1.onOrderUpdated` to show the confirmed cart. Past it the widget is
  * re-rendered, never unlocked blindly *(plan review 1 #3)*. */
 export declare const QLIRO_SYNC_DEADLINE_MS = 10000;
+/** How often `qliro-q1`'s shipping dispatcher checks whether `window.q1` is a new object (a re-render replaces it, and a
+ * registration on a stale instance is silent). */
+export declare const QLIRO_REBIND_MS = 500;
 /** Qliro's check before `unlock()` (*Update order*: "Verify that the total amount of the order = total amount in the
- * shopping cart"), in öre, **or** the `MerchantUpdateVersion` our PUT sent (carriers 1b ruling R-S3-K1: on a shipping
- * market Qliro's total includes the fee, so the total alone never matches). The echo is a string in Qliro's schema; its
+ * shopping cart"), in öre, **or** the `MerchantUpdateVersion` our PUT sent (carriers 1b ruling R-S3-K1: Qliro's client
+ * `onOrderUpdated.totalPrice` is goods only while the GET total includes shipping (Q-L2), so on a shipping market the two
+ * totals can differ and the total alone is not a reliable match). The echo is a string in Qliro's schema; its
  * name is read case-insensitively (VQ-8 records the real one). */
 export declare function qliroOrderMatches(order: unknown, target: Pick<ResumeTarget, "cart" | "cartVersion">): boolean;
 export declare const controllers: Record<"qliro-q1" | "klarna-kco" | "walley", ControllerFactory>;

package/dist/checkout/controllers.js

@@ -3,10 +3,14 @@ export const KLARNA_READY_POLL_MS = 100;
 /** How long `qliro-q1`'s resume waits for `q1.onOrderUpdated` to show the confirmed cart. Past it the widget is
  * re-rendered, never unlocked blindly *(plan review 1 #3)*. */
 export const QLIRO_SYNC_DEADLINE_MS = 10_000;
+/** How often `qliro-q1`'s shipping dispatcher checks whether `window.q1` is a new object (a re-render replaces it, and a
+ * registration on a stale instance is silent). */
+export const QLIRO_REBIND_MS = 500;
 const ore = (v) => Math.round(Number(v) * 100);
 /** Qliro's check before `unlock()` (*Update order*: "Verify that the total amount of the order = total amount in the
- * shopping cart"), in öre, **or** the `MerchantUpdateVersion` our PUT sent (carriers 1b ruling R-S3-K1: on a shipping
- * market Qliro's total includes the fee, so the total alone never matches). The echo is a string in Qliro's schema; its
+ * shopping cart"), in öre, **or** the `MerchantUpdateVersion` our PUT sent (carriers 1b ruling R-S3-K1: Qliro's client
+ * `onOrderUpdated.totalPrice` is goods only while the GET total includes shipping (Q-L2), so on a shipping market the two
+ * totals can differ and the total alone is not a reliable match). The echo is a string in Qliro's schema; its
  * name is read case-insensitively (VQ-8 records the real one). */
 export function qliroOrderMatches(order, target) {
     const o = order;
@@ -31,6 +35,69 @@ export const controllers = {
         // Whether the last suspend reached `q1.lock()`: before the snippet's script has run there is no `q1` to lock, and the
         // iframe may load the order before the PUT *(final review #4)*.
         let locked = false;
+        // The passive-listener dispatcher (spec §4.6 Binding): each passive q1 listener (the shipping pair, onPaymentDeclined) is
+        // registered once per q1 object and fans out to every handler of its kind. The identity watch runs only while a
+        // shipping handler exists (no new work without `onShipping`); while it runs it rebinds the decline signal too, because a
+        // re-render replaces `window.q1` and a registration on the stale instance is silent.
+        let disposed = false;
+        const handlers = { shipping: new Set(), declined: new Set() };
+        const registered = new WeakMap();
+        let current; // the q1 whose callbacks may fire
+        let watchEpoch = 0;
+        let watching = false;
+        const fire = (q1, kind) => () => { if (disposed || q1 !== current)
+            return; for (const h of [...handlers[kind]])
+            h(); };
+        const register = (kind) => {
+            const q1 = win.q1;
+            if (!q1)
+                return false;
+            const ready = kind === "shipping" ? !!(q1.onShippingMethodChanged && q1.onShippingPriceChanged) : !!q1.onPaymentDeclined;
+            if (!ready)
+                return false;
+            current = q1;
+            let done = registered.get(q1);
+            if (!done)
+                registered.set(q1, (done = new Set()));
+            if (done.has(kind))
+                return true;
+            const cb = fire(q1, kind);
+            if (kind === "shipping") {
+                q1.onShippingMethodChanged(cb);
+                q1.onShippingPriceChanged(cb);
+            }
+            else
+                q1.onPaymentDeclined(() => cb());
+            done.add(kind);
+            return true;
+        };
+        const tryRegister = (kind) => { try {
+            return register(kind);
+        }
+        catch {
+            return false;
+        } };
+        const stopWatch = () => { watchEpoch++; watching = false; };
+        const startWatch = () => {
+            if (watching)
+                return;
+            watching = true;
+            const mine = ++watchEpoch;
+            const tick = () => {
+                if (disposed || mine !== watchEpoch || handlers.shipping.size === 0)
+                    return;
+                for (const kind of ["shipping", "declined"]) {
+                    if (handlers[kind].size === 0)
+                        continue;
+                    try {
+                        register(kind);
+                    }
+                    catch { /* not ready: the next tick retries */ }
+                }
+                timer(tick, QLIRO_REBIND_MS);
+            };
+            timer(tick, QLIRO_REBIND_MS);
+        };
         return {
             suspend: () => { generation++; locked = false; const q1 = win.q1; if (q1) {
                 q1.lock();
@@ -40,14 +107,22 @@ export const controllers = {
                 const q1 = win.q1;
                 const missedLock = !locked;
                 locked = false;
+                // Nothing held and nothing to resume: still a resumed signal, or the live shipping observer stays suspended.
                 if (!q1) {
                     if (missedLock && target)
                         target.onUnsynced();
+                    else
+                        target?.onResumed?.();
                     return;
                 }
                 const mine = ++generation;
-                const unlock = () => { if (generation !== mine)
-                    return; generation++; q1.unlock(); };
+                const unlock = () => {
+                    if (generation !== mine || disposed)
+                        return;
+                    generation++;
+                    q1.unlock();
+                    target?.onResumed?.();
+                };
                 // Nothing to compare — no sync API, or the app resumed without an answer: unlock at once, as B did.
                 if (!q1.onOrderUpdated || !target) {
                     unlock();
@@ -55,22 +130,33 @@ export const controllers = {
                 }
                 if (missedLock)
                     q1.lock(); // onOrderUpdated "requires q1.lock() to have been called first"
-                q1.onOrderUpdated((order) => { if (qliroOrderMatches(order, target))
+                q1.onOrderUpdated((order) => { if (!disposed && qliroOrderMatches(order, target))
                     unlock(); });
                 // Never unlocked blindly: past the deadline the handle re-renders the widget from the confirmed answer
                 // *(plan review 1 #3)*.
-                timer(() => { if (generation !== mine)
+                timer(() => { if (generation !== mine || disposed)
                     return; generation++; target.onUnsynced(); }, QLIRO_SYNC_DEADLINE_MS);
             },
             onDeclined: (handler) => {
                 // Confirmed (plan C): `q1.onPaymentDeclined` fires on our validation decline. `undefined` until `q1` and the signal
-                // exist *(plan review 2 #13)*.
-                const q1 = win.q1;
-                if (!q1?.onPaymentDeclined)
+                // exist *(plan review 2 #13)*. Registered through the dispatcher, so the shipping watch rebinds it on a new q1.
+                // A throwing q1 (a stale instance during a remount) is not ready, as the Kustom path: it must not abort the remount
+                // before its expiry is armed; the bind retry tries again *(final review E)*.
+                if (disposed || !tryRegister("declined"))
                     return undefined;
-                q1.onPaymentDeclined(() => handler());
-                return () => { };
+                handlers.declined.add(handler);
+                // q1 offers no unsubscribe: the handler leaves the fan-out, and the handle's generation guard drops late calls.
+                return () => { handlers.declined.delete(handler); };
             },
+            onShippingEvent: (handler) => {
+                if (disposed || !tryRegister("shipping"))
+                    return undefined;
+                handlers.shipping.add(handler);
+                startWatch();
+                return () => { handlers.shipping.delete(handler); if (handlers.shipping.size === 0)
+                    stopWatch(); };
+            },
+            dispose: () => { disposed = true; stopWatch(); handlers.shipping.clear(); handlers.declined.clear(); },
         };
     },
     "klarna-kco": (win, timer) => {
@@ -84,7 +170,7 @@ export const controllers = {
         // The desired-state generation already handed to `_klarnaCheckout`: the readiness timer hands over only a wish that was
         // not, so an immediate handover by a later suspend() is never repeated by the timer *(review F2-#22)*.
         let handed = 0;
-        const hand = (want, mine) => {
+        const hand = (want, mine, after) => {
             const kco = win._klarnaCheckout;
             if (!kco)
                 return false;
@@ -96,8 +182,10 @@ export const controllers = {
                         return;
                     if (want === "suspended")
                         api.suspend({ autoResume: { enabled: false } });
-                    else
+                    else {
                         api.resume();
+                        after?.();
+                    }
                 });
             }
             catch (e) {
@@ -140,15 +228,19 @@ export const controllers = {
                 awaitScript();
                 return false;
             },
-            resume: () => {
+            resume: (target) => {
                 const mine = ++seq;
                 desired = "resumed";
                 // Before the script ran there is nothing to resume; a pending readiness check sees `resumed` and stays quiet. A global
                 // that throws is the same "not ready": `hand` restores `handed`, and nothing escapes into the handle (final review, Task 19).
+                // Nothing handed over means nothing held: the resumed signal comes at once (only the live shipping observer reads it).
+                let handedOver = false;
                 try {
-                    hand("resumed", mine);
+                    handedOver = hand("resumed", mine, () => target?.onResumed?.());
                 }
                 catch { /* nothing to resume yet */ }
+                if (!handedOver)
+                    target?.onResumed?.();
             },
             onCannotComplete: (handler) => {
                 const kco = win._klarnaCheckout;
@@ -167,12 +259,37 @@ export const controllers = {
                 }
                 return () => { live = false; };
             },
+            onShippingEvent: (handler) => {
+                const kco = win._klarnaCheckout;
+                if (!kco)
+                    return undefined;
+                let live = true;
+                const fire = () => { if (live && !disposed)
+                    handler(); };
+                // One separate api.on: replacement is per event, so can_not_complete_order stays bound.
+                try {
+                    kco((api) => api.on?.({ shipping_option_change: fire, shipping_address_change: fire, order_total_change: fire }));
+                }
+                catch {
+                    live = false;
+                    return undefined;
+                }
+                return () => { live = false; };
+            },
             dispose: () => { disposed = true; },
         };
     },
     walley: (win) => ({
         suspend: () => win.walley?.checkout?.api?.suspend(),
-        resume: () => win.walley?.checkout?.api?.resume(),
+        resume: (target) => {
+            const api = win.walley?.checkout?.api;
+            if (!api) {
+                target?.onResumed?.();
+                return;
+            } // nothing held: still resumed for the observer
+            api.resume();
+            target?.onResumed?.();
+        },
     }),
 };
 export function controllerFor(name, win, timer = (fn, ms) => { setTimeout(fn, ms); }) {

package/dist/checkout/live-shipping.d.ts

@@ -0,0 +1,30 @@
+import type { CheckoutShippingViewDto, LiveShippingResult } from "./types";
+/** Everything the observation flow needs from the outside. No DOM, no provider knowledge, no real clock. */
+export interface LiveShippingDeps {
+    read: () => Promise<LiveShippingResult>;
+    deliver: (view: CheckoutShippingViewDto | null) => void;
+    now: () => number;
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    clearTimeout: (h: unknown) => void;
+    random: () => number;
+    visible: () => boolean;
+    debounceMs?: number;
+    followUpMs?: number;
+    netMinMs?: number;
+    netMaxMs?: number;
+}
+export interface LiveShippingObserver {
+    /** A provider event, or an explicit first read. An event clears the view (`deliver(null)`) before the read. */
+    trigger(kind: "event" | "first" | "resume" | "net"): void;
+    /** Sync started: invalidate and hold reads until `resumed()`. */
+    suspended(): void;
+    /** The provider is actually resumed and the sync queue drained: refresh. A shipping event seen while suspended is replayed here. */
+    resumed(): void;
+    destroy(): void;
+}
+/**
+ * The live shipping observation flow (spec 2026-10-12-checkout-live-shipping-design.md §4.6): one request in flight,
+ * one coalesced planned read, one not-before deadline for every timer, a sequence number that events, suspend and
+ * destroy bump so that an older answer is dropped.
+ */
+export declare function createLiveShippingObserver(deps: LiveShippingDeps): LiveShippingObserver;

package/dist/checkout/live-shipping.js

@@ -0,0 +1,193 @@
+/**
+ * The live shipping observation flow (spec 2026-10-12-checkout-live-shipping-design.md §4.6): one request in flight,
+ * one coalesced planned read, one not-before deadline for every timer, a sequence number that events, suspend and
+ * destroy bump so that an older answer is dropped.
+ */
+export function createLiveShippingObserver(deps) {
+    const debounceMs = deps.debounceMs ?? 300;
+    const followUpMs = deps.followUpMs ?? 500;
+    const netMinMs = deps.netMinMs ?? 45_000;
+    const netMaxMs = Math.max(netMinMs, deps.netMaxMs ?? 60_000);
+    let destroyed = false;
+    let isSuspended = false;
+    let seq = 0;
+    let notBefore = 0;
+    let inFlight = false;
+    let view = null;
+    let netStopped = false;
+    let planned = null;
+    let readTimer = null;
+    let netTimer = null;
+    const deliver = (v) => {
+        try {
+            deps.deliver(v);
+        }
+        catch { /* the host's display must not break the observation */ }
+    };
+    const clearRead = () => { if (readTimer !== null) {
+        deps.clearTimeout(readTimer);
+        readTimer = null;
+    } };
+    const clearNet = () => { if (netTimer !== null) {
+        deps.clearTimeout(netTimer);
+        netTimer = null;
+    } };
+    /** (Re)arm the single read timer for `planned`, never earlier than the not-before deadline. */
+    function arm() {
+        clearRead();
+        if (planned === null || destroyed || isSuspended || inFlight)
+            return; // a settle re-arms
+        const at = Math.max(planned.due, notBefore);
+        readTimer = deps.setTimeout(onReadTimer, Math.max(0, at - deps.now()));
+    }
+    function onReadTimer() {
+        readTimer = null;
+        if (destroyed || isSuspended || planned === null || inFlight)
+            return;
+        if (deps.now() < notBefore) {
+            arm();
+            return;
+        } // the deadline moved after this was armed
+        const { kind, followUp } = planned;
+        planned = null;
+        void start(kind, followUp);
+    }
+    function plan(kind, delayMs, followUp, debounce = false) {
+        if (destroyed || isSuspended)
+            return;
+        const due = deps.now() + delayMs;
+        if (planned === null)
+            planned = { due, kind, followUp };
+        else {
+            if (debounce)
+                planned.due = due; // an event restarts the debounce
+            if (kind !== "net" && kind !== "followUp")
+                planned.kind = planned.kind === "event" ? "event" : kind;
+            else if (planned.kind === "net")
+                planned.kind = kind;
+            planned.followUp = planned.followUp || followUp;
+        }
+        arm();
+    }
+    const retryDeadline = (seconds) => {
+        if (typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0)
+            notBefore = Math.max(notBefore, deps.now() + seconds * 1000);
+    };
+    async function start(kind, followUp) {
+        inFlight = true;
+        const mine = seq;
+        let result;
+        try {
+            result = await deps.read();
+        }
+        catch {
+            result = { ok: false, status: 0, problem: { code: "NETWORK", status: 0 } };
+        }
+        inFlight = false;
+        if (destroyed)
+            return;
+        // Whatever the answer's age, a server-demanded delay holds every later read.
+        // Only a network failure (0), 408, 429 and 5xx are transient; any other 4xx (404, 403, 400) is a real answer that
+        // clears the view on every read kind, and the net keeps its own rules *(final review C)*.
+        let transient = !result.ok && isTransientStatus(result.status);
+        retryDeadline(result.retryAfter);
+        if (!result.ok && result.status === 429 && result.retryAfter === undefined)
+            notBefore = Math.max(notBefore, deps.now() + 1000);
+        if (result.ok) {
+            const d = result.data;
+            if (d.state === "unavailable" && (d.reason === "throttled" || d.reason === "provider")) {
+                transient = true;
+                retryDeadline(typeof d.retryAfterSeconds === "number" ? d.retryAfterSeconds : undefined);
+            }
+        }
+        const current = mine === seq && !isSuspended;
+        if (current) {
+            if (!transient && result.ok) {
+                view = result.data;
+                netStopped = view.state === "unavailable" && (view.reason === "closed" || view.reason === "not_supported");
+                deliver(view);
+            }
+            else if (transient && (kind === "net" || kind === "followUp") && view !== null) {
+                // a transient failure after a good view with no event in between: keep what is shown
+            }
+            else if (view !== null) {
+                view = null;
+                deliver(null);
+            }
+            if (followUp)
+                plan("followUp", followUpMs, false);
+        }
+        if (planned !== null)
+            arm();
+        armNet();
+    }
+    function armNet() {
+        clearNet();
+        if (destroyed || isSuspended || netStopped)
+            return;
+        const delay = netMinMs + deps.random() * (netMaxMs - netMinMs);
+        netTimer = deps.setTimeout(onNet, delay);
+    }
+    function onNet() {
+        netTimer = null;
+        if (destroyed || isSuspended || netStopped)
+            return;
+        if (!deps.visible() || inFlight || planned !== null) {
+            armNet();
+            return;
+        }
+        plan("net", 0, false);
+    }
+    return {
+        trigger(kind) {
+            if (destroyed)
+                return;
+            if (kind === "event") {
+                seq++;
+                view = null;
+                deliver(null);
+                // a shipping event seen while suspended is the pending trigger resumed() replays
+                if (isSuspended)
+                    return;
+                plan("event", debounceMs, true, true);
+            }
+            else if (kind === "net") {
+                if (isSuspended || netStopped)
+                    return;
+                plan("net", 0, false);
+            }
+            else {
+                if (isSuspended)
+                    return; // replayed by resumed()
+                plan(kind, 0, kind === "resume");
+            }
+        },
+        suspended() {
+            if (destroyed)
+                return;
+            planned = null;
+            clearRead();
+            clearNet();
+            isSuspended = true;
+            seq++;
+            view = null;
+            deliver(null);
+        },
+        resumed() {
+            if (destroyed)
+                return;
+            isSuspended = false;
+            plan("resume", 0, true);
+        },
+        destroy() {
+            destroyed = true;
+            planned = null;
+            clearRead();
+            clearNet();
+        },
+    };
+}
+/** A failed read worth keeping the shown view for: no answer (0), a timeout (408), a throttle (429) or a server error (5xx). */
+function isTransientStatus(status) {
+    return status === 0 || status === 408 || status === 429 || status >= 500;
+}

package/dist/checkout/server.d.ts

@@ -1,6 +1,6 @@
 import type { Client } from "openapi-fetch";
 import type { StorefrontPaths } from "../index.js";
-import { type CheckoutResult, type OrderResult, type StatusResult } from "./types.js";
+import { type CheckoutResult, type LiveShippingResult, type OrderResult, type StatusResult } from "./types.js";
 export type CheckoutClient = Client<StorefrontPaths>;
 export interface StartCheckoutOptions {
     /** One of `GET /v1/site` → `markets[].checkout.options[].key`; omit for the market's default. */
@@ -25,6 +25,9 @@ export declare function syncCheckout(client: CheckoutClient, cartToken: string,
 export declare function completeCheckout(client: CheckoutClient, attemptId: string, cartToken?: string): Promise<StatusResult>;
 /** `GET /v1/checkout/{attemptId}`: the non-mutating status read the browser module polls with. */
 export declare function getCheckoutStatus(client: CheckoutClient, attemptId: string, cartToken: string): Promise<StatusResult>;
+/** `GET /v1/checkout/{attemptId}/shipping` with the cart token: the live shipping view behind `mountCheckout`'s `liveShipping`.
+ * Forward `retryAfter` (the `Retry-After` header) from a proxy; a 200 `unavailable` view may carry it too. */
+export declare function liveShippingFor(client: CheckoutClient, cartToken: string, attemptId: string): Promise<LiveShippingResult>;
 /** `GET /v1/orders/{orderId}` with `X-Order-Token` — a header only, never a query string (spec §8.3). */
 export declare function getOrder(client: CheckoutClient, orderId: string, token: string): Promise<OrderResult>;
 export interface AwaitCompletionOptions {

package/dist/checkout/server.js

@@ -41,6 +41,15 @@ export async function getCheckoutStatus(client, attemptId, cartToken) {
         return { ok: false, status: response.status, problem: (error ?? localProblem("SDK_EMPTY_ANSWER", "no body")), retryAfter: retryAfterSeconds(response) };
     return { ok: true, data };
 }
+/** `GET /v1/checkout/{attemptId}/shipping` with the cart token: the live shipping view behind `mountCheckout`'s `liveShipping`.
+ * Forward `retryAfter` (the `Retry-After` header) from a proxy; a 200 `unavailable` view may carry it too. */
+export async function liveShippingFor(client, cartToken, attemptId) {
+    const { data, error, response } = await client.GET("/v1/checkout/{attemptId}/shipping", { params: { path: { attemptId } }, headers: { "X-Cart-Token": cartToken } });
+    const retryAfter = retryAfterSeconds(response);
+    if (error || !data)
+        return { ok: false, status: response.status, problem: (error ?? localProblem("SDK_EMPTY_ANSWER", "no body")), retryAfter };
+    return { ok: true, data, retryAfter };
+}
 /** `GET /v1/orders/{orderId}` with `X-Order-Token` — a header only, never a query string (spec §8.3). */
 export async function getOrder(client, orderId, token) {
     const { data, error, response } = await client.GET("/v1/orders/{orderId}", { params: { path: { orderId } }, headers: { "X-Order-Token": token } });

package/dist/checkout/types.d.ts

@@ -3,6 +3,7 @@ export type CheckoutDto = components["schemas"]["CheckoutDto"];
 export type CheckoutStatusDto = components["schemas"]["CheckoutStatusDto"];
 export type CheckoutOrderRefDto = components["schemas"]["CheckoutOrderRefDto"];
 export type CheckoutWidgetDto = components["schemas"]["CheckoutWidgetDto"];
+export type CheckoutShippingViewDto = components["schemas"]["CheckoutShippingViewDto"];
 export type OrderDto = components["schemas"]["OrderDto"];
 export type StartCheckoutRequest = components["schemas"]["StartCheckoutRequest"];
 /** The problem body; `cart` is the corrected cart on 409 CHECKOUT_CART_CHANGED (an extension, so it is typed loosely here). */
@@ -28,6 +29,17 @@ export type StatusResult = {
     problem: StorefrontProblem;
     retryAfter?: number;
 };
+/** `GET /v1/checkout/{attemptId}/shipping`: the live shipping view, the HTTP status on failure and the `Retry-After` delay in seconds. */
+export type LiveShippingResult = {
+    ok: true;
+    data: CheckoutShippingViewDto;
+    retryAfter?: number;
+} | {
+    ok: false;
+    status: number;
+    problem: StorefrontProblem;
+    retryAfter?: number;
+};
 export type OrderResult = {
     ok: true;
     data: OrderDto;

package/dist/index.d.ts

@@ -47,8 +47,8 @@ export type FilterSelection = NonNullable<NonNullable<paths["/v1/products"]["get
 export declare function filterQuery(selection: Record<string, string | string[] | undefined>): FilterSelection;
 export { decodeFilterValues, encodeFilterValues } from "./filters.js";
 export { coverOffset, fileUrl, fillFactor, formatFactor, formatImage, imageRect, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, scaledSizes, srcSet, styleToCss, videoSources, type FormatFit, type FormattedImage, type MediaConfig, type MediaDescriptor, type MediaFormat, type PictureSources, type SlotSize, type VideoSource, } from "./media.js";
-export { awaitCompletion, completeCheckout, getCheckoutStatus, getOrder, startCheckout, syncCheckout, type CheckoutClient, type StartCheckoutOptions, type SyncRetryOptions, type AwaitCompletionOptions } from "./checkout/server.js";
-export { retryAfterSeconds, type CheckoutDto, type CheckoutOrderRefDto, type CheckoutResult, type CheckoutStatusDto, type CheckoutWidgetDto, type OrderDto, type OrderResult, type StatusResult, type StorefrontProblem } from "./checkout/types.js";
+export { awaitCompletion, completeCheckout, getCheckoutStatus, getOrder, liveShippingFor, startCheckout, syncCheckout, type CheckoutClient, type StartCheckoutOptions, type SyncRetryOptions, type AwaitCompletionOptions } from "./checkout/server.js";
+export { retryAfterSeconds, type CheckoutDto, type CheckoutOrderRefDto, type CheckoutResult, type CheckoutShippingViewDto, type LiveShippingResult, type CheckoutStatusDto, type CheckoutWidgetDto, type OrderDto, type OrderResult, type StatusResult, type StorefrontProblem } from "./checkout/types.js";
 export { mountCheckout, type CheckoutHandle, type MountOptions, type MinimalDocument, type MinimalElement, type MinimalScript } from "./checkout/browser.js";
 export { controllers, type CheckoutController, type ProviderWindow } from "./checkout/controllers.js";
 export { breadcrumbJsonLd } from "./seo/breadcrumb.js";

package/dist/index.js

@@ -36,7 +36,7 @@ export function filterQuery(selection) {
 }
 export { decodeFilterValues, encodeFilterValues } from "./filters.js";
 export { coverOffset, fileUrl, fillFactor, formatFactor, formatImage, imageRect, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, scaledSizes, srcSet, styleToCss, videoSources, } from "./media.js";
-export { awaitCompletion, completeCheckout, getCheckoutStatus, getOrder, startCheckout, syncCheckout } from "./checkout/server.js"; // SyncRetryOptions *(plan review 3 #5)*
+export { awaitCompletion, completeCheckout, getCheckoutStatus, getOrder, liveShippingFor, startCheckout, syncCheckout } from "./checkout/server.js"; // SyncRetryOptions *(plan review 3 #5)*
 export { retryAfterSeconds } from "./checkout/types.js";
 export { mountCheckout } from "./checkout/browser.js";
 export { controllers } from "./checkout/controllers.js";

package/dist/schema.d.ts

@@ -183,6 +183,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/checkout/{attemptId}/shipping": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["GetCheckoutShipping"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/collections": {
         parameters: {
             query?: never;
@@ -593,6 +609,32 @@ export interface components {
             kind: string;
             url: null | string;
         };
+        CheckoutShippingPointDto: {
+            city: null | string;
+            name: string;
+            postalCode: null | string;
+            street: null | string;
+        };
+        CheckoutShippingViewDto: {
+            /** Format: int32 */
+            cartVersion: number | null | string;
+            currency: null | string;
+            deliveryType: null | string;
+            goodsInc: null | string;
+            name: null | string;
+            option: null | string;
+            otherInc: null | string;
+            point: null | components["schemas"]["CheckoutShippingPointDto"];
+            /** Format: date-time */
+            readAt: null | string;
+            reason: null | string;
+            /** Format: int32 */
+            retryAfterSeconds: number | null | string;
+            shippingInc: null | string;
+            state: string;
+            totalInc: null | string;
+            totalSource: null | string;
+        };
         CheckoutStatusDto: {
             attemptId: string;
             order: null | components["schemas"]["CheckoutOrderRefDto"];
@@ -2401,6 +2443,91 @@ export interface operations {
             };
         };
     };
+    GetCheckoutShipping: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Publishable, preview or secret site key. Required on every request; secret keys are server-side only. */
+                "X-Site-Key": string;
+                /** @description Market code (e.g. "se"). Omit for the site's default market. */
+                "X-Market"?: string;
+                /** @description BCP-47 language tag. Omit to use the market's language. */
+                "Accept-Language"?: string;
+                /** @description The cart's bearer token. The checkout works on this cart. */
+                "X-Cart-Token": string;
+            };
+            path: {
+                attemptId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CheckoutShippingViewDto"];
+                };
+            };
+            /** @description problem+json. NOT_FOUND (X-Cart-Token missing). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_KEY_MISSING or SITE_KEY_INVALID. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SECRET_KEY_FROM_BROWSER: a secret key was sent from a browser. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. CHECKOUT_NOT_FOUND: no such attempt for this site and cart; or SITE_INACTIVE. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. RATE_LIMITED; retryAfterSeconds and the Retry-After header say how long to wait. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_REGISTRY_WARMING or INDEX_UNAVAILABLE — retry, the request was not wrong. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+        };
+    };
     GetCollections: {
         parameters: {
             query?: never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asstio-dev/storefront",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Typed client for the Asstio Storefront API (generated from OpenAPI).",
   "repository": {
     "type": "git",
@@ -21,7 +21,7 @@
     "test": "vitest run",
     "test:browser": "playwright test -c browser/playwright.config.ts",
     "check": "npm run generate && npm run typecheck-examples && npm test && git diff --exit-code -- src/schema.d.ts && test -z \"$(git status --porcelain -- src/schema.d.ts)\"",
-    "smoke": "node --input-type=module -e \"import(\\\"./dist/index.js\\\").then(m => { for (const f of [\\\"createStorefrontClient\\\", \\\"filterQuery\\\", \\\"encodeFilterValues\\\", \\\"decodeFilterValues\\\", \\\"pictureSources\\\", \\\"mediaUrl\\\", \\\"formatImage\\\", \\\"styleToCss\\\", \\\"startCheckout\\\", \\\"syncCheckout\\\", \\\"completeCheckout\\\", \\\"getCheckoutStatus\\\", \\\"getOrder\\\", \\\"awaitCompletion\\\", \\\"mountCheckout\\\", \\\"productJsonLd\\\", \\\"gtinJsonLd\\\", \\\"breadcrumbJsonLd\\\", \\\"productHead\\\", \\\"collectionHead\\\", \\\"brandHead\\\", \\\"toNextMetadata\\\", \\\"jsonLdScript\\\", \\\"SeoError\\\", \\\"productFacts\\\", \\\"toGa4Item\\\", \\\"toGa4Ecommerce\\\", \\\"AnalyticsError\\\"]) if (typeof m[f] !== \\\"function\\\") throw new Error(\\\"missing export \\\" + f) })\""
+    "smoke": "node --input-type=module -e \"import(\\\"./dist/index.js\\\").then(m => { for (const f of [\\\"createStorefrontClient\\\", \\\"filterQuery\\\", \\\"encodeFilterValues\\\", \\\"decodeFilterValues\\\", \\\"pictureSources\\\", \\\"mediaUrl\\\", \\\"formatImage\\\", \\\"styleToCss\\\", \\\"startCheckout\\\", \\\"syncCheckout\\\", \\\"completeCheckout\\\", \\\"getCheckoutStatus\\\", \\\"liveShippingFor\\\", \\\"getOrder\\\", \\\"awaitCompletion\\\", \\\"mountCheckout\\\", \\\"productJsonLd\\\", \\\"gtinJsonLd\\\", \\\"breadcrumbJsonLd\\\", \\\"productHead\\\", \\\"collectionHead\\\", \\\"brandHead\\\", \\\"toNextMetadata\\\", \\\"jsonLdScript\\\", \\\"SeoError\\\", \\\"productFacts\\\", \\\"toGa4Item\\\", \\\"toGa4Ecommerce\\\", \\\"AnalyticsError\\\"]) if (typeof m[f] !== \\\"function\\\") throw new Error(\\\"missing export \\\" + f) })\""
   },
   "dependencies": {
     "openapi-fetch": "0.17.0"

package/src/schema.d.ts

@@ -183,6 +183,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/checkout/{attemptId}/shipping": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["GetCheckoutShipping"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/collections": {
         parameters: {
             query?: never;
@@ -593,6 +609,32 @@ export interface components {
             kind: string;
             url: null | string;
         };
+        CheckoutShippingPointDto: {
+            city: null | string;
+            name: string;
+            postalCode: null | string;
+            street: null | string;
+        };
+        CheckoutShippingViewDto: {
+            /** Format: int32 */
+            cartVersion: number | null | string;
+            currency: null | string;
+            deliveryType: null | string;
+            goodsInc: null | string;
+            name: null | string;
+            option: null | string;
+            otherInc: null | string;
+            point: null | components["schemas"]["CheckoutShippingPointDto"];
+            /** Format: date-time */
+            readAt: null | string;
+            reason: null | string;
+            /** Format: int32 */
+            retryAfterSeconds: number | null | string;
+            shippingInc: null | string;
+            state: string;
+            totalInc: null | string;
+            totalSource: null | string;
+        };
         CheckoutStatusDto: {
             attemptId: string;
             order: null | components["schemas"]["CheckoutOrderRefDto"];
@@ -2401,6 +2443,91 @@ export interface operations {
             };
         };
     };
+    GetCheckoutShipping: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Publishable, preview or secret site key. Required on every request; secret keys are server-side only. */
+                "X-Site-Key": string;
+                /** @description Market code (e.g. "se"). Omit for the site's default market. */
+                "X-Market"?: string;
+                /** @description BCP-47 language tag. Omit to use the market's language. */
+                "Accept-Language"?: string;
+                /** @description The cart's bearer token. The checkout works on this cart. */
+                "X-Cart-Token": string;
+            };
+            path: {
+                attemptId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CheckoutShippingViewDto"];
+                };
+            };
+            /** @description problem+json. NOT_FOUND (X-Cart-Token missing). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_KEY_MISSING or SITE_KEY_INVALID. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SECRET_KEY_FROM_BROWSER: a secret key was sent from a browser. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. CHECKOUT_NOT_FOUND: no such attempt for this site and cart; or SITE_INACTIVE. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. RATE_LIMITED; retryAfterSeconds and the Retry-After header say how long to wait. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_REGISTRY_WARMING or INDEX_UNAVAILABLE — retry, the request was not wrong. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+        };
+    };
     GetCollections: {
         parameters: {
             query?: never;