@asstio-dev/storefront 0.18.0 → 0.20.0

package/README.md

@@ -243,6 +243,28 @@ config. Holes in the data never throw: a missing image, description or price onl
 
 hreflang sets are only as reciprocal as the API's `alternateUrls`; the SDK renders what the API gives.
 
+### Search events
+
+`trackSearchEvents(client, events, { consent })` posts search exposures, product clicks and add-to-carts to
+`POST /v1/events`, for measuring search quality. It sends **nothing** unless `consent === true`: the storefront stores
+no PII and cannot verify consent, so the frontend decides, and passes `sessionId` (opaque, frontend-generated) only
+under the same consent.
+
+```ts
+const exposure = { type: "search_exposure", occurredAt: new Date().toISOString(), resultId: listing.search!.resultId, query, page: 1, productIds };
+await trackSearchEvents(client, [exposure], { consent: shopperAcceptedMeasurement });
+await trackSearchEvents(client, [{ type: "product_click", occurredAt: new Date().toISOString(), exposureId: exposure.eventId, productId, position: 3 }], { consent });
+```
+
+- An event without `eventId` gets a UUID **written into the object**. Retry the same objects after an uncertain
+  answer (a timeout, a dropped connection) and the ids are reused, so the server counts the repeats as `duplicates`.
+  A second click from the same exposure is a new event: build a new object.
+- `occurredAt` is UTC ISO-8601 (`new Date().toISOString()`), within 7 days back and 5 minutes ahead.
+- At most 50 events per call (a larger batch throws `RangeError`), 64 KB per body. The answer lists `rejected`
+  events with their `index` and `member`; the others are kept. Any non-2xx answer throws: a malformed envelope (a
+  `400` problem) and a bare `5xx` alike, so a failed send is never mistaken for "no consent" (`null`).
+- Exposures come only from the client; a catalog GET is never one.
+
 ### Product facts and GA4
 
 Cards and cart lines carry the product facts the product page has: `brand`, `categories`, `shortDescription` and
@@ -436,6 +458,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 +481,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 +531,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/analytics/events.d.ts

@@ -0,0 +1,20 @@
+import type { Client } from "openapi-fetch";
+import type { components } from "../schema";
+import type { StorefrontPaths } from "../index.js";
+type Schemas = components["schemas"];
+/** One search event. `eventId` may be left out: `trackSearchEvents` writes a UUID into the object. */
+export type SearchEvent = Omit<Schemas["SearchEventDto"], "eventId"> & {
+    eventId?: string | null;
+};
+export type SearchEventsResponse = Schemas["SearchEventsResponse"];
+/**
+ * `POST /v1/events` (spec 2026-10-13 §9.2). A no-op unless `consent` is exactly `true`: the storefront cannot verify
+ * consent, so the caller decides (and sends `sessionId` only under the same consent). An event without `eventId` gets
+ * a UUID written into the object, so retrying the same objects after an uncertain response reuses the ids and the
+ * server counts them as duplicates. Throws a `RangeError` for more than 50 events (split the batch) and an `Error` on any
+ * non-2xx answer (a problem body or none). Build `occurredAt` with `new Date().toISOString()`: the server wants UTC.
+ */
+export declare function trackSearchEvents(client: Client<StorefrontPaths>, events: SearchEvent[], options: {
+    consent: boolean;
+}): Promise<SearchEventsResponse | null>;
+export {};

package/dist/analytics/events.js

@@ -0,0 +1,23 @@
+/** The server's per-envelope cap (spec 2026-10-13 §9.2); a larger batch is a `400` that stores nothing. */
+const MAX_EVENTS_PER_REQUEST = 50;
+/**
+ * `POST /v1/events` (spec 2026-10-13 §9.2). A no-op unless `consent` is exactly `true`: the storefront cannot verify
+ * consent, so the caller decides (and sends `sessionId` only under the same consent). An event without `eventId` gets
+ * a UUID written into the object, so retrying the same objects after an uncertain response reuses the ids and the
+ * server counts them as duplicates. Throws a `RangeError` for more than 50 events (split the batch) and an `Error` on any
+ * non-2xx answer (a problem body or none). Build `occurredAt` with `new Date().toISOString()`: the server wants UTC.
+ */
+export async function trackSearchEvents(client, events, options) {
+    if (options?.consent !== true || events.length === 0)
+        return null;
+    if (events.length > MAX_EVENTS_PER_REQUEST)
+        throw new RangeError(`trackSearchEvents takes at most ${MAX_EVENTS_PER_REQUEST} events per call, got ${events.length}`);
+    for (const e of events)
+        if (!e.eventId)
+            e.eventId = crypto.randomUUID();
+    const { data, error, response } = await client.POST("/v1/events", { body: { events: events } });
+    // `error` is undefined for an empty-body 5xx (openapi-fetch parses nothing), so the status decides: a non-2xx always throws.
+    if (!response.ok)
+        throw new Error(`trackSearchEvents failed: ${response.status} ${error === undefined ? "" : JSON.stringify(error)}`.trimEnd());
+    return data ?? null;
+}

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>;