@asstio-dev/storefront 0.7.0 → 0.9.2

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

package/dist/checkout/server.js

@@ -0,0 +1,68 @@
+import { localProblem, retryAfterSeconds } from "./types.js";
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** `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 async function startCheckout(client, cartToken, opts = {}) {
+    const { data, error, response } = await client.POST("/v1/checkout", {
+        body: { option: opts.option ?? null, returnOrigin: opts.returnOrigin ?? null },
+        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 };
+}
+/** 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 async function syncCheckout(client, cartToken, opts = {}, retry = {}) {
+    const sleep = retry.sleep ?? defaultSleep;
+    const retries = retry.retries ?? 2; // *(plan review 3 #5)*
+    let result = await startCheckout(client, cartToken, opts);
+    for (let attempt = 0; attempt < retries && !result.ok && result.problem.code === "CHECKOUT_IN_PROGRESS"; attempt++) {
+        await sleep((result.retryAfter ?? 1) * 1000);
+        result = await startCheckout(client, cartToken, opts);
+    }
+    return result;
+}
+/** `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 async function completeCheckout(client, attemptId, cartToken) {
+    const { data, error, response } = await client.POST("/v1/checkout/{attemptId}/complete", {
+        params: { path: { attemptId } },
+        headers: cartToken ? { "X-Cart-Token": cartToken } : {},
+    });
+    if (error || !data)
+        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}`: the non-mutating status read the browser module polls with. */
+export async function getCheckoutStatus(client, attemptId, cartToken) {
+    const { data, error, response } = await client.GET("/v1/checkout/{attemptId}", { params: { path: { attemptId } }, headers: { "X-Cart-Token": cartToken } });
+    if (error || !data)
+        return { ok: false, status: response.status, problem: (error ?? localProblem("SDK_EMPTY_ANSWER", "no body")), retryAfter: retryAfterSeconds(response) };
+    return { ok: true, data };
+}
+/** `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 } });
+    if (error || !data)
+        return { ok: false, status: response.status, problem: (error ?? localProblem("SDK_EMPTY_ANSWER", "no body")) };
+    return { ok: true, data };
+}
+const FINAL = new Set(["completed", "pending", "declined", "expired"]);
+/** 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 async function awaitCompletion(complete, opts = {}) {
+    const first = opts.firstDelayMs ?? 1000;
+    const max = opts.maxDelayMs ?? 10_000;
+    const timeout = opts.timeoutMs ?? 120_000;
+    const sleep = opts.sleep ?? defaultSleep;
+    let delay = first;
+    let waited = 0;
+    let last = await complete();
+    while (last.ok && !FINAL.has(last.data.status) && waited + delay <= timeout) {
+        await sleep(delay);
+        waited += delay;
+        delay = Math.min(delay * 2, max);
+        last = await complete();
+    }
+    return last;
+}

package/dist/checkout/types.d.ts

@@ -0,0 +1,42 @@
+import type { components } from "../schema";
+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 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). */
+export type StorefrontProblem = components["schemas"]["StorefrontProblem"] & {
+    cart?: unknown;
+};
+export type CheckoutResult = {
+    ok: true;
+    data: CheckoutDto;
+    retryAfter?: number;
+} | {
+    ok: false;
+    status: number;
+    problem: StorefrontProblem;
+    retryAfter?: number;
+};
+export type StatusResult = {
+    ok: true;
+    data: CheckoutStatusDto;
+} | {
+    ok: false;
+    status: number;
+    problem: StorefrontProblem;
+    retryAfter?: number;
+};
+export type OrderResult = {
+    ok: true;
+    data: OrderDto;
+} | {
+    ok: false;
+    status: number;
+    problem: StorefrontProblem;
+};
+/** `Retry-After` in seconds: a delay, or an HTTP-date turned into one; garbage is 1 s, absence is undefined. */
+export declare function retryAfterSeconds(response: Response, now?: () => number): number | undefined;
+/** A problem shaped like the API's, for failures that never reached it (a thrown fetch, a timeout). */
+export declare function localProblem(code: string, detail: string): StorefrontProblem;

package/dist/checkout/types.js

@@ -0,0 +1,17 @@
+/** `Retry-After` in seconds: a delay, or an HTTP-date turned into one; garbage is 1 s, absence is undefined. */
+export function retryAfterSeconds(response, now = Date.now) {
+    const raw = response.headers.get("Retry-After");
+    if (raw === null || raw === "")
+        return undefined;
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds))
+        return Math.max(0, Math.ceil(seconds));
+    const date = Date.parse(raw);
+    if (Number.isFinite(date))
+        return Math.max(0, Math.ceil((date - now()) / 1000));
+    return 1;
+}
+/** A problem shaped like the API's, for failures that never reached it (a thrown fetch, a timeout). */
+export function localProblem(code, detail) {
+    return { type: "https://docs.asstio.com/storefront/errors#" + code, title: code, status: 0, detail, code };
+}

package/dist/index.d.ts

@@ -47,3 +47,7 @@ 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 { 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";

package/dist/index.js

@@ -36,3 +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 { retryAfterSeconds } from "./checkout/types.js";
+export { mountCheckout } from "./checkout/browser.js";
+export { controllers } from "./checkout/controllers.js";