@asstio-dev/storefront 0.7.0 → 0.11.0

package/dist/checkout/browser.js

@@ -0,0 +1,444 @@
+import { controllerFor } from "./controllers.js";
+import { localProblem } from "./types.js";
+const FINAL_ORDER = new Set(["completed", "pending"]);
+export function mountCheckout(container, checkout, options) {
+    if (checkout.status !== "open" || !checkout.widget)
+        throw new Error("mountCheckout needs an `open` answer with a widget");
+    const doc = options.document ?? globalThis.document;
+    const win = options.window ?? globalThis;
+    if (!doc)
+        throw new Error("mountCheckout needs a document");
+    const setT = options.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearT = options.clearTimeout ?? ((h) => clearTimeout(h));
+    const timers = new Set();
+    // A controller's own timer (qliro-q1's sync deadline) is the handle's: a remount or destroy cancels it.
+    const controllerTimer = (fn, ms) => { const h = setT(() => { timers.delete(h); fn(); }, ms); timers.add(h); };
+    const now = options.now ?? Date.now;
+    const lockedBudgetMs = options.lockedBudgetMs ?? 30_000;
+    const lockedMaxCalls = options.lockedMaxCalls ?? 10;
+    const pollFirstMs = options.pollFirstMs ?? 1000;
+    const pollMaxMs = options.pollMaxMs ?? 10_000;
+    const lockedPollsBeforeSync = options.lockedPollsBeforeSync ?? 3; // *(plan review 1 #12)*
+    const bindRetryMs = options.bindRetryMs ?? 500; // one interval while mounted *(final review S8)*
+    const preExpiryMs = options.preExpiryMs ?? 180_000;
+    let attemptId = checkout.attemptId;
+    let controller = controllerFor(checkout.widget.controller, win, controllerTimer);
+    let suspended = false;
+    // The controller that was last told to suspend: a remount replaces the controller, and a sync still queued behind
+    // it must suspend the new one when it starts *(plan review 2 #11)*.
+    let suspendedOn;
+    let destroyed = false;
+    let generation = 0; // Review Focus 2: a remount or destroy invalidates every running loop and timer
+    // Syncs accepted and not yet finished — the running one and every one queued behind it. Payment stays suspended
+    // while it is above one, an autonomous sync is skipped while it is above zero, and a running sync's waits end as soon
+    // as another is queued behind it *(plan review 2 #11, final review S7, #8)*.
+    let active = 0;
+    let queue = Promise.resolve(); // *(plan review 1 #43)*
+    let unsubscribeDeclined;
+    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
+    // the promise forever pending: an unsettled dispatch never reaches its `finally`, the queue never drains, and every
+    // later autonomous sync waits for good — and an app awaiting `handle.sync` after `destroy()` waits forever
+    // *(plan review 1 #37)*.
+    // Each sleep's timer is kept with it, so a queued update can end the running sync's waits alone *(final review #8)*.
+    const sleepers = new Map();
+    /** A wait of the running sync — a burst retry or a poll. It answers `false` (stop) when the generation is gone, and
+     * also at once when another sync is queued behind the running one: the shopper's cart update must not wait out a
+     * poll that can last minutes *(final review #8)*. */
+    const sleep = (ms, gen) => new Promise((resolve) => {
+        if (active > 1) {
+            resolve(false);
+            return;
+        }
+        const settle = (alive) => { const h = sleepers.get(settle); sleepers.delete(settle); if (h !== undefined) {
+            clearT(h);
+            timers.delete(h);
+        } resolve(alive); };
+        const h = setT(() => { timers.delete(h); sleepers.delete(settle); resolve(!destroyed && gen === generation); }, ms);
+        sleepers.set(settle, h);
+        timers.add(h);
+    });
+    /** End every pending wait of the running sync with `false`; the binding and expiry timers are left alone. */
+    function endWaits() {
+        for (const settle of Array.from(sleepers.keys()))
+            settle(false);
+    }
+    /** Clear every timer and settle every sleep with `false` (the caller's generation is gone). */
+    function cancelTimers() {
+        endWaits();
+        for (const h of timers)
+            clearT(h);
+        timers.clear();
+    }
+    const alive = (gen) => !destroyed && gen === generation;
+    const message = (e) => (e instanceof Error ? e.message : String(e));
+    /** A failure that never reached the API, reported only to the generation it belongs to *(plan review 2 #16, #17)*. */
+    function reportLocal(gen, code, e) {
+        if (alive(gen))
+            options.onProblem(localProblem(code, message(e)), { status: 0 });
+    }
+    function render(dto) {
+        const w = dto.widget;
+        container.innerHTML = "";
+        if (w.kind === "html") {
+            container.innerHTML = w.html ?? "";
+            // innerHTML never runs a script: each one is re-created with its attributes and text, in order (Review Focus 4).
+            for (const inert of Array.from(container.querySelectorAll("script"))) {
+                const live = doc.createElement("script");
+                for (const name of inert.getAttributeNames())
+                    live.setAttribute(name, inert.getAttribute(name) ?? "");
+                live.async = inert.async; // a script created this way is async by default: keep the snippet's own order *(plan review 1 #44)*
+                live.textContent = inert.textContent;
+                inert.parentNode?.replaceChild(live, inert);
+                container.appendChild(live);
+            }
+        }
+        else {
+            const live = doc.createElement("script");
+            live.async = false; // createElement scripts are async by default; a snippet's externals must run in document order *(plan review 1 #44)*
+            live.setAttribute("src", w.scriptUrl ?? "");
+            if (w.token)
+                live.setAttribute("data-token", w.token);
+            for (const [k, v] of Object.entries(w.attributes ?? {}))
+                live.setAttribute(k, v);
+            container.appendChild(live);
+        }
+    }
+    function suspend() {
+        suspended = true;
+        if (suspendedOn !== controller) {
+            suspendedOn = controller;
+            controller.suspend();
+        }
+    }
+    function resume(target) { if (suspended) {
+        suspended = false;
+        suspendedOn = undefined;
+        controller.resume(target);
+    } }
+    // ---- 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
+     * waits and the POST not-before are cut *(final review S1)*. */
+    async function post(gen) {
+        try {
+            return await options.sync();
+        }
+        catch (e) {
+            reportLocal(gen, "SDK_SYNC_FAILED", e);
+            return undefined;
+        }
+    }
+    const withinBurst = (b, waitMs) => b.calls < lockedMaxCalls && now() + waitMs - b.start < lockedBudgetMs;
+    /** One retry of the `locked`/429/503/`CHECKOUT_IN_PROGRESS` burst. The wait must land inside the burst's deadline —
+     * checked before the wait and again after it, so a `Retry-After` longer than what is left of the 30 s never turns
+     * into a call outside it *(plan review 2 #14)*. */
+    async function retry(budget, retryAfterMs, gen) {
+        if (!withinBurst(budget, retryAfterMs))
+            return "exhausted";
+        if (!(await sleep(retryAfterMs, gen)))
+            return "gone";
+        if (!withinBurst(budget, 0))
+            return "exhausted";
+        budget.calls++;
+        return (await post(gen)) ?? "gone";
+    }
+    // One rolling burst window per handle, not one per dispatch *(plan review 1 #40)*.
+    let budgetWindow = { start: now(), calls: 0 };
+    function currentBudget() {
+        if (now() - budgetWindow.start >= lockedBudgetMs)
+            budgetWindow = { start: now(), calls: 0 };
+        return budgetWindow;
+    }
+    // ---- The autonomous syncs --------------------------------------------------------------------------------------
+    function armExpiry(dto) {
+        if (expiryTimer !== undefined) {
+            clearT(expiryTimer);
+            timers.delete(expiryTimer);
+            expiryTimer = undefined;
+        }
+        // Review Focus 5: server-relative, three minutes before, never negative.
+        // The repository's OpenAPI emits every int32 as ["integer","string"], so the generated type is
+        // `number | string` and the multiplication is TS2362. The same rule for any int arithmetic in the SDK
+        // *(plan review 1 #38)*.
+        const delay = Math.max(0, Number(dto.expiresInSeconds) * 1000 - preExpiryMs);
+        // An attempt already inside the window answers `open` again, which would re-arm at delay 0 and sync in a
+        // zero-delay loop. Only that repeat is suppressed: an already-due deadline for an attempt whose pre-expiry sync
+        // has run. A future deadline from a new answer — the server extended the attempt — is armed as usual; round 1's
+        // guard blocked every later timer for the attempt *(plan review 1 #42, plan review 2 #12)*.
+        if (delay === 0 && firedPreExpiryFor === dto.attemptId)
+            return;
+        const gen = generation;
+        expiryTimer = setT(() => {
+            timers.delete(expiryTimer);
+            expiryTimer = undefined;
+            autonomousSync("expiry", gen);
+        }, delay);
+        timers.add(expiryTimer);
+    }
+    function bindProvider(dto, bound = controllerFor(dto.widget.controller, win, controllerTimer)) {
+        // Cleared, not only called: round 1 left the old unsubscriber in place, so a remount's `attach` returned at once
+        // and the new widget's decline signal was never bound *(plan review 2 #13)*.
+        unsubscribeDeclined?.();
+        unsubscribeDeclined = undefined;
+        controller = bound;
+        // A provider without the signal: nothing to bind and nothing to retry *(plan review 2 #13)*.
+        if (!bound.onDeclined)
+            return;
+        const gen = generation;
+        // `render` appends the provider's script; it has not executed when this runs, so the global the controller reads
+        // does not exist yet. Retry every `bindRetryMs` until the subscription is registered (`onDeclined` returns its
+        // unsubscriber) or the generation is gone — one interval for as long as the widget is mounted, so a script that
+        // loads late is still bound. The timers are the handle's, so a remount or destroy cancels them
+        // *(plan review 1 #43, plan review 2 #13, plan review 3 #4, final review S8)*.
+        const attach = () => {
+            if (!alive(gen))
+                return;
+            const unsubscribe = bound.onDeclined(() => autonomousSync("declined", gen));
+            if (unsubscribe) {
+                unsubscribeDeclined = unsubscribe;
+                return;
+            }
+            const h = setT(() => { timers.delete(h); attach(); }, bindRetryMs);
+            timers.add(h);
+        };
+        attach();
+    }
+    function remount(dto) {
+        if (dto.status !== "open" || !dto.widget)
+            throw new Error("remount needs an `open` answer with a widget");
+        // Resolved before any state changes: an unknown controller throws while the generation is still alive, so the
+        // 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);
+        generation++;
+        cancelTimers(); // *(plan review 1 #37)*
+        expiryTimer = undefined;
+        firedPreExpiryFor = undefined;
+        attemptId = dto.attemptId;
+        // 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)*.
+        suspended = active > 1;
+        suspendedOn = undefined;
+        render(dto);
+        bindProvider(dto, next);
+        armExpiry(dto);
+    }
+    const onVisible = () => { if (!destroyed && suspended && doc.visibilityState === "visible")
+        autonomousSync("visible", generation); };
+    doc.addEventListener("visibilitychange", onVisible);
+    /** A sync the SDK starts by itself. Skipped while another sync runs: that sync is a `POST /checkout` too, and its
+     * `open` answer re-arms the pre-expiry timer (an attempt already inside the window arms at once). The pre-expiry
+     * attempt is marked only when its sync really starts, so a skip never consumes it. The deferral queue rounds 2–3
+     * added is cut *(plan review 2 #12, final review S7)*. */
+    function autonomousSync(reason, gen) {
+        if (!alive(gen) || active > 0)
+            return;
+        if (reason === "visible" && !suspended)
+            return;
+        if (reason === "expiry")
+            firedPreExpiryFor = attemptId;
+        void enqueue(async (g) => {
+            const result = await post(g);
+            if (result)
+                await dispatch(result, g, currentBudget());
+        });
+    }
+    // ---- The rule ------------------------------------------------------------------------------------------------
+    /** Serialized: two quick quantity clicks must not run two dispatches in one generation, or the first `open` resumes
+     * the widget while the second mutation is still in flight *(plan review 1 #43)*. The widget is suspended when the
+     * request is **accepted**, before it waits its turn: round 1 suspended after `await previous`, so `handle.sync`
+     * returned with payment still enabled even on an idle queue *(plan review 2 #11)*. A sync accepted while another
+     * runs ends the running one's waits (a burst retry, a poll that can last minutes): the running sync stops, and the
+     * newer update — which supersedes what it was waiting for — runs at once *(final review #8)*. Never rejects: any
+     * other throw — an app callback, an unknown controller on remount, a provider `lock()` — is reported as
+     * `SDK_DISPATCH_FAILED` to the generation it belongs to, and the first `suspend()` is inside the `try` (still before
+     * the first `await`, so still at acceptance), so a throw cannot leave `active` stuck *(final review B3 T2)*. */
+    function enqueue(work) {
+        if (destroyed)
+            return Promise.resolve();
+        active++;
+        const previous = queue;
+        let release;
+        queue = new Promise((r) => { release = r; });
+        let gen = generation;
+        return (async () => {
+            try {
+                suspend();
+                if (active > 1)
+                    endWaits(); // *(final review #8)*
+                await previous;
+                if (destroyed)
+                    return;
+                gen = generation; // before the suspend: a new controller's throwing lock() is reported under the live generation
+                suspend(); // a remount while this waited replaced the controller: suspend the new one
+                await work(gen);
+            }
+            catch (e) {
+                // The report itself may throw (`onProblem` is an app callback, and one of the causes): swallowed, so
+                // `handle.sync` and the autonomous path still never reject.
+                try {
+                    reportLocal(gen, "SDK_DISPATCH_FAILED", e);
+                }
+                catch { /* never rejects */ }
+            }
+            finally {
+                active--;
+                release();
+            }
+        })();
+    }
+    /** Status first; identity on `open` only. */
+    async function dispatch(result, gen, budget) {
+        if (!alive(gen))
+            return;
+        if (!result.ok) {
+            const retryable503 = result.status === 503 && (result.problem.code === "CHECKOUT_UNAVAILABLE" || result.problem.code === "CHECKOUT_PROVIDER_UNAVAILABLE");
+            // `sync` and `update` are single POSTs (`{ retries: 0 }`), so the handle retries CHECKOUT_IN_PROGRESS itself, in
+            // the same burst as `locked` *(plan review 3 #5, final review S1)*.
+            const inProgress = result.status === 409 && result.problem.code === "CHECKOUT_IN_PROGRESS";
+            if (retryable503 || inProgress || result.status === 429) {
+                const next = await retry(budget, (result.retryAfter ?? 1) * 1000, gen);
+                if (next === "gone")
+                    return;
+                if (next !== "exhausted")
+                    return dispatch(next, gen, budget);
+            }
+            // The last retry's problem, not the first: the app should see the latest state of the checkout. The 503 test
+            // asserts the last code for that reason *(plan review 1 #41)*.
+            options.onProblem(result.problem, { status: result.status });
+            return;
+        }
+        const dto = result.data;
+        switch (dto.status) {
+            case "completed":
+            case "pending":
+                if (dto.order)
+                    options.onOrder(dto.order, dto.attemptId);
+                return;
+            case "locked": {
+                const next = await retry(budget, (result.retryAfter ?? 1) * 1000, gen);
+                if (next === "gone")
+                    return;
+                if (next !== "exhausted")
+                    return dispatch(next, gen, budget);
+                return poll(dto.attemptId, gen);
+            }
+            case "processing":
+                return poll(dto.attemptId, gen);
+            case "declined":
+            case "expired": {
+                const next = await post(gen);
+                if (next)
+                    return dispatchOnce(next, gen);
+                return;
+            }
+            case "open":
+                if (dto.attemptId === attemptId) {
+                    armExpiry(dto);
+                    // 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)
+                        resume({ cart: dto.cart, onUnsynced: () => { if (alive(gen))
+                                remount(dto); } });
+                }
+                else {
+                    remount(dto);
+                }
+                return;
+            default:
+                options.onProblem(localProblem("SDK_UNKNOWN_STATUS", String(dto.status)), { status: 200 });
+        }
+    }
+    /** After a `declined`/`expired` or a `GET open`: one sync, dispatched without a second closing → sync loop. */
+    async function dispatchOnce(result, gen) {
+        if (!alive(gen))
+            return;
+        if (result.ok && (result.data.status === "declined" || result.data.status === "expired")) {
+            options.onProblem(localProblem("SDK_CHECKOUT_CLOSED", result.data.status), { status: 200 });
+            return;
+        }
+        return dispatch(result, gen, currentBudget()); // *(plan review 1 #40)*
+    }
+    /** `status(attemptId)` polling with backoff; a GET answer is never payable: `open` (like `declined`/`expired`) leads to one non-mutating `sync()`. */
+    async function poll(id, gen) {
+        let delay = pollFirstMs;
+        let lockedPolls = 0;
+        for (;;) {
+            if (!(await sleep(delay, gen)))
+                return;
+            let s;
+            try {
+                s = await options.status(id);
+            }
+            catch (e) {
+                reportLocal(gen, "SDK_STATUS_FAILED", e); // *(plan review 2 #17)*
+                return;
+            }
+            if (!alive(gen))
+                return;
+            // §10.3 treats a 429 like `locked`: back off and keep polling *(plan review 1 #43)*. The client's backoff is
+            // capped at `pollMaxMs`; the server's `Retry-After` is a lower bound the cap never shortens *(plan review 2 #15)*.
+            if (!s.ok) {
+                if (s.status !== 429) {
+                    options.onProblem(s.problem, { status: s.status });
+                    return;
+                }
+                delay = Math.max(Math.min(delay * 2, pollMaxMs), (s.retryAfter ?? 1) * 1000);
+                continue;
+            }
+            if (FINAL_ORDER.has(s.data.status)) {
+                if (s.data.order)
+                    options.onOrder(s.data.order, s.data.attemptId);
+                return;
+            }
+            // `locked` means an update or an owned read is in flight (§10.2), and only a POST resolves it. An attempt whose
+            // latest snapshot was never confirmed and whose claim is gone answers `locked` to every GET with nothing in
+            // flight, so a status poller would poll for ever: escalate to one sync() *(plan review 1 #12)*. Posted directly
+            // *(final review S1)*.
+            const escalate = s.data.status === "open" || s.data.status === "declined" || s.data.status === "expired"
+                || (s.data.status === "locked" && ++lockedPolls >= lockedPollsBeforeSync);
+            if (escalate) {
+                const next = await post(gen);
+                if (next)
+                    return dispatchOnce(next, gen);
+                return;
+            }
+            delay = Math.min(delay * 2, pollMaxMs);
+        }
+    }
+    const handle = {
+        get attemptId() { return attemptId; },
+        get suspended() { return suspended; },
+        suspend, resume, remount,
+        destroy() {
+            destroyed = true;
+            generation++;
+            cancelTimers(); // *(plan review 1 #37)*
+            unsubscribeDeclined?.();
+            unsubscribeDeclined = undefined;
+            doc.removeEventListener("visibilitychange", onVisible);
+        },
+        sync(update) {
+            return enqueue(async (gen) => {
+                let result;
+                try {
+                    result = await update(); // once — never repeated (LensNow's add action has no idempotency key)
+                }
+                catch (e) {
+                    // Only for the generation it was started in: a rejection after destroy() or a remount is dropped, as a
+                    // fulfilled answer is in `dispatch` *(plan review 2 #16)*. The widget stays suspended until a sync succeeds.
+                    reportLocal(gen, "SDK_UPDATE_FAILED", e);
+                    return;
+                }
+                await dispatch(result, gen, currentBudget()); // *(plan review 1 #40)*
+            });
+        },
+    };
+    render(checkout);
+    bindProvider(checkout);
+    armExpiry(checkout);
+    return handle;
+}

package/dist/checkout/controllers.d.ts

@@ -0,0 +1,55 @@
+/** What the provider's JavaScript offers (spec §4.4 `ClientSuspend`); each is optional on the page until the widget's script has loaded. */
+export interface ProviderWindow {
+    q1?: {
+        lock(): void;
+        unlock(): void;
+        /** Qliro's sync after a `PUT Orders/{id}`: the iframe re-reads the order and calls back until `unlock()` is called
+         * (developers.qliro.com → Update order). */
+        onOrderUpdated?(cb: (order: unknown) => void): void;
+        /** 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;
+    };
+    _klarnaCheckout?: (cb: (api: {
+        suspend(): void;
+        resume(): void;
+    }) => void) => void;
+    walley?: {
+        checkout?: {
+            api?: {
+                suspend(): void;
+                resume(): void;
+            };
+        };
+    };
+}
+/** What a resume must see in the provider's own view of the order before it enables payment: the confirmed answer
+ * (`open` for the mounted attempt) *(plan review 1 #3)*. */
+export interface ResumeTarget {
+    cart: {
+        grandTotalInc: string;
+    };
+    /** The provider never showed `cart` before its deadline: the handle re-renders the widget from the confirmed answer. */
+    onUnsynced(): void;
+}
+export interface CheckoutController {
+    suspend(): void;
+    /** `target` lets a controller that can see the provider's order wait for it (qliro-q1); the others ignore it. */
+    resume(target?: ResumeTarget): void;
+    /** Subscribe to the provider's payment-declined signal where its API offers one. Returns the unsubscribe once the
+     * subscription is registered, and `undefined` while the provider's script has not exposed the signal yet — the
+     * handle retries only then. A controller whose provider has no such signal leaves this member out, and the handle
+     * never retries for it *(plan review 2 #13)*. */
+    onDeclined?(handler: () => void): (() => void) | undefined;
+}
+/** A controller's own timer, scheduled on the handle so that a remount or `destroy()` cancels it. */
+export type ControllerTimer = (fn: () => void, ms: number) => void;
+export type ControllerFactory = (win: ProviderWindow, timer: ControllerTimer) => CheckoutController;
+/** 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;
+/** Qliro's check before `unlock()` (*Update order*: "Verify that the total amount of the order = total amount in the
+ * shopping cart"), in öre. The total alone, as Qliro documents it *(plan review 1 #3, final review S1)*. */
+export declare function qliroOrderMatches(order: unknown, cart: ResumeTarget["cart"]): boolean;
+export declare const controllers: Record<"qliro-q1" | "klarna-kco" | "walley", ControllerFactory>;
+export declare function controllerFor(name: string, win: ProviderWindow, timer?: ControllerTimer): CheckoutController;

package/dist/checkout/controllers.js

@@ -0,0 +1,75 @@
+/** 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;
+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. The total alone, as Qliro documents it *(plan review 1 #3, final review S1)*. */
+export function qliroOrderMatches(order, cart) {
+    const total = order?.totalPrice;
+    return (typeof total === "number" || typeof total === "string") && ore(total) === ore(cart.grandTotalInc);
+}
+export const controllers = {
+    "qliro-q1": (win, timer) => {
+        // Every suspend, every unlock and the deadline move the generation, so neither a resume's `onOrderUpdated` callback
+        // (Qliro calls it until unlock) nor its deadline acts after a newer suspend (Review Focus 3).
+        let generation = 0;
+        // 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;
+        return {
+            suspend: () => { generation++; locked = false; const q1 = win.q1; if (q1) {
+                q1.lock();
+                locked = true;
+            } },
+            resume: (target) => {
+                const q1 = win.q1;
+                const missedLock = !locked;
+                locked = false;
+                if (!q1) {
+                    if (missedLock && target)
+                        target.onUnsynced();
+                    return;
+                }
+                const mine = ++generation;
+                const unlock = () => { if (generation !== mine)
+                    return; generation++; q1.unlock(); };
+                // Nothing to compare — no sync API, or the app resumed without an answer: unlock at once, as B did.
+                if (!q1.onOrderUpdated || !target) {
+                    unlock();
+                    return;
+                }
+                if (missedLock)
+                    q1.lock(); // onOrderUpdated "requires q1.lock() to have been called first"
+                q1.onOrderUpdated((order) => { if (qliroOrderMatches(order, target.cart))
+                    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)
+                    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)
+                    return undefined;
+                q1.onPaymentDeclined(() => handler());
+                return () => { };
+            },
+        };
+    },
+    "klarna-kco": (win) => ({
+        suspend: () => win._klarnaCheckout?.((api) => api.suspend()),
+        resume: () => win._klarnaCheckout?.((api) => api.resume()),
+    }),
+    walley: (win) => ({
+        suspend: () => win.walley?.checkout?.api?.suspend(),
+        resume: () => win.walley?.checkout?.api?.resume(),
+    }),
+};
+export function controllerFor(name, win, timer = (fn, ms) => { setTimeout(fn, ms); }) {
+    const factory = controllers[name];
+    if (!factory)
+        throw new Error(`unknown checkout controller '${name}'`);
+    return factory(win, timer);
+}

package/dist/checkout/server.d.ts

@@ -0,0 +1,37 @@
+import type { Client } from "openapi-fetch";
+import type { StorefrontPaths } from "../index.js";
+import { type CheckoutResult, 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. */
+    option?: string;
+    /** Replaces the market's origin in the URLs handed to the provider; must be one of the site's allowed origins. */
+    returnOrigin?: string;
+}
+export interface SyncRetryOptions {
+    sleep?: (ms: number) => Promise<void>;
+    /** How many `CHECKOUT_IN_PROGRESS` retries this call makes itself (default 2). Pass `0` for the POST behind
+     * `mountCheckout`'s `sync` and `update`: one call is one HTTP POST, and the browser handle retries inside its own
+     * 30 s burst instead of multiplying it *(plan review 3 #5, final review S1)*. */
+    retries?: number;
+}
+/** `POST /v1/checkout`: creates the cart's attempt or converges on the live one (spec §5.3). Call it from a Server Action or route handler, never during render. */
+export declare function startCheckout(client: CheckoutClient, cartToken: string, opts?: StartCheckoutOptions): Promise<CheckoutResult>;
+/** The same `POST /v1/checkout`, retrying `CHECKOUT_IN_PROGRESS` per `Retry-After`, twice (spec §10.3) — or
+ * `retries` times; `{ retries: 0 }` is the single-attempt call to put behind `mountCheckout` *(plan review 3 #5)*.
+ * Never repeats a cart mutation: it only syncs. */
+export declare function syncCheckout(client: CheckoutClient, cartToken: string, opts?: StartCheckoutOptions, retry?: SyncRetryOptions): Promise<CheckoutResult>;
+/** `POST /v1/checkout/{attemptId}/complete`: the confirmation page's call; with the cart token the answer carries the order's access token (spec §8.3). */
+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/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 {
+    firstDelayMs?: number;
+    maxDelayMs?: number;
+    timeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Polls `complete` with doubling backoff until the attempt has an order or is closed, or the timeout passes (the last answer is returned either way). */
+export declare function awaitCompletion(complete: () => Promise<StatusResult>, opts?: AwaitCompletionOptions): Promise<StatusResult>;