@asstio-dev/storefront 0.11.0 → 0.13.0

package/README.md

@@ -380,6 +380,27 @@ Problem codes you will meet here: `CART_EMPTY`, `CHECKOUT_CART_CHANGED` (with `c
 - 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.
 
+#### Kustom (`klarna-kco`)
+
+- The widget is Kustom's HTML snippet (Kustom Checkout v3); `mountCheckout` re-creates its scripts so they run.
+- After every cart change, `handle.sync(update)` suspends the checkout with `suspend({ autoResume: { enabled: false } })`,
+  so Kustom never reopens payment by itself during a slow sync or while the SDK retries a `locked` answer. It resumes only
+  on the confirmed `open` answer for the same attempt; Kustom re-reads its order on `resume()`. A change made before the
+  snippet's script has defined `window._klarnaCheckout` is handed over as soon as it has.
+- When our validation declines a purchase, Kustom sends the **whole page** to your checkout page with `declined=validation`
+  added to its query (the server answers Kustom with a 303 to the attempt's checkout page). That page is a fresh load:
+  show a short message for `declined=validation`, sync the real cart, and handle `completed`/`pending` before mounting a
+  widget, as on any page load. There is no `onDeclined` for Kustom.
+- `can_not_complete_order` (no offered payment method can complete the order) reaches `onProblem` with the code
+  `SDK_PROVIDER_CANNOT_COMPLETE`; the copy is yours.
+- The re-entry refresh (a stored snippet older than ten minutes is re-fetched) and the acknowledgement to Kustom are the
+  server's; the page does nothing for them.
+- The checkout page needs a `checkoutPath` and a `termsPath` in the market's checkout block (Purchase refuses a Kustom
+  option without them).
+- **CSP hosts: pending K-C10** (`docs/ops/kustom-playground-checks.md`). Until the playground run records the hosts the
+  snippet really loads (card with 3-D Secure and the default method), allow `*.kustom.co` and `*.klarna.com` for
+  `script-src`, `frame-src` and `connect-src` as the general paragraph above says, and watch the console for blocked requests.
+
 ## Headers
 
 Every call the client makes carries these; you never set them by hand.

package/dist/checkout/browser.js

@@ -35,6 +35,7 @@ export function mountCheckout(container, checkout, options) {
     let active = 0;
     let queue = Promise.resolve(); // *(plan review 1 #43)*
     let unsubscribeDeclined;
+    let unsubscribeCannotComplete;
     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
@@ -107,10 +108,16 @@ export function mountCheckout(container, checkout, options) {
     }
     function suspend() {
         suspended = true;
-        if (suspendedOn !== controller) {
-            suspendedOn = controller;
-            controller.suspend();
-        }
+        if (suspendedOn === controller)
+            return;
+        // Recorded before the call, as on main: a controller whose suspend throws (a broken provider `lock()`) stays recorded, so a
+        // later autonomous sync reaches the server instead of throwing again *(final review B3 T2; review F2-#21)*. Only the
+        // explicit "not handed over yet" answer (`false`, spec F §7.1) un-records it, so the next suspend() offers it again —
+        // recording it while the provider global was absent made every later suspend() skip the controller (round B).
+        const target = controller;
+        suspendedOn = target;
+        if (target.suspend() === false && suspendedOn === target)
+            suspendedOn = undefined;
     }
     function resume(target) { if (suspended) {
         suspended = false;
@@ -182,28 +189,36 @@ export function mountCheckout(container, checkout, options) {
         // and the new widget's decline signal was never bound *(plan review 2 #13)*.
         unsubscribeDeclined?.();
         unsubscribeDeclined = undefined;
+        unsubscribeCannotComplete?.();
+        unsubscribeCannotComplete = 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
+        // does not exist yet. Each signal the controller offers is retried every `bindRetryMs` until it is registered
+        // (the subscribe function 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. A controller without the signal binds nothing and
+        // retries nothing. 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;
+        const bind = (subscribe, handler, keep) => {
+            if (!subscribe)
                 return;
-            }
-            const h = setT(() => { timers.delete(h); attach(); }, bindRetryMs);
-            timers.add(h);
+            const attach = () => {
+                if (!alive(gen))
+                    return;
+                const off = subscribe(handler);
+                if (off) {
+                    keep(off);
+                    return;
+                }
+                const h = setT(() => { timers.delete(h); attach(); }, bindRetryMs);
+                timers.add(h);
+            };
+            attach();
         };
-        attach();
+        bind(bound.onDeclined, () => autonomousSync("declined", gen), (off) => { unsubscribeDeclined = off; });
+        // 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; });
     }
     function remount(dto) {
         if (dto.status !== "open" || !dto.widget)
@@ -211,6 +226,7 @@ export function mountCheckout(container, checkout, options) {
         // 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);
+        controller.dispose?.(); // spec F §7.1: the old mount's deferred callbacks and timers do nothing now
         generation++;
         cancelTimers(); // *(plan review 1 #37)*
         expiryTimer = undefined;
@@ -419,6 +435,9 @@ export function mountCheckout(container, checkout, options) {
             cancelTimers(); // *(plan review 1 #37)*
             unsubscribeDeclined?.();
             unsubscribeDeclined = undefined;
+            unsubscribeCannotComplete?.();
+            unsubscribeCannotComplete = undefined;
+            controller.dispose?.();
             doc.removeEventListener("visibilitychange", onVisible);
         },
         sync(update) {

package/dist/checkout/controllers.d.ts

@@ -1,3 +1,14 @@
+/** Kustom's client API (docs.kustom.co → Client-side events). A no-argument `suspend()` auto-resumes after 10 s; the SDK
+ * always passes `{ autoResume: { enabled: false } }` (spec F §7.1, review #5). */
+export interface KlarnaCheckoutApi {
+    suspend(options?: {
+        autoResume?: {
+            enabled: boolean;
+        };
+    }): void;
+    resume(): void;
+    on?(events: Record<string, (data?: unknown) => void>): void;
+}
 /** 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?: {
@@ -10,10 +21,7 @@ export interface ProviderWindow {
          * (developers.qliro.com → Listeners). */
         onPaymentDeclined?(cb: (declineReason?: string, declineReasonMessage?: string) => void): void;
     };
-    _klarnaCheckout?: (cb: (api: {
-        suspend(): void;
-        resume(): void;
-    }) => void) => void;
+    _klarnaCheckout?: (cb: (api: KlarnaCheckoutApi) => void) => void;
     walley?: {
         checkout?: {
             api?: {
@@ -33,7 +41,9 @@ export interface ResumeTarget {
     onUnsynced(): void;
 }
 export interface CheckoutController {
-    suspend(): void;
+    /** Returns `false` when the suspension could not be handed to the provider yet (its script has not defined its API): the
+     * handle does not record it, and the controller hands it over once the script is ready (spec F §7.1). */
+    suspend(): void | false;
     /** `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
@@ -41,7 +51,14 @@ export interface CheckoutController {
      * 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;
+    /** 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;
+    /** This mount is over (remount, destroy): every deferred provider callback and timer of this controller does nothing after it. */
+    dispose?(): void;
 }
+/** How often `klarna-kco` checks whether the snippet has defined `_klarnaCheckout`, while a suspension waits for it. */
+export declare const KLARNA_READY_POLL_MS = 100;
 /** 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;

package/dist/checkout/controllers.js

@@ -1,3 +1,5 @@
+/** How often `klarna-kco` checks whether the snippet has defined `_klarnaCheckout`, while a suspension waits for it. */
+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;
@@ -58,10 +60,103 @@ export const controllers = {
             },
         };
     },
-    "klarna-kco": (win) => ({
-        suspend: () => win._klarnaCheckout?.((api) => api.suspend()),
-        resume: () => win._klarnaCheckout?.((api) => api.resume()),
-    }),
+    "klarna-kco": (win, timer) => {
+        // Spec F §7.1: every deferred _klarnaCheckout callback carries this mount (`disposed`) and the desired state when it was
+        // queued (`seq`, `desired`); it acts only while it is still the latest wish of a live mount. KCO re-reads its order on
+        // resume(), so no total comparison is needed — the lifecycle guards are.
+        let disposed = false;
+        let seq = 0;
+        let desired;
+        let waiting = false;
+        // 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 kco = win._klarnaCheckout;
+            if (!kco)
+                return false;
+            const before = handed;
+            handed = mine;
+            try {
+                kco((api) => {
+                    if (disposed || mine !== seq || desired !== want)
+                        return;
+                    if (want === "suspended")
+                        api.suspend({ autoResume: { enabled: false } });
+                    else
+                        api.resume();
+                });
+            }
+            catch (e) {
+                handed = before; // the provider never took it: a later handover is not suppressed
+                throw e;
+            }
+            return true;
+        };
+        const awaitScript = () => {
+            if (waiting)
+                return;
+            waiting = true;
+            const tick = () => {
+                if (disposed)
+                    return;
+                if (!win._klarnaCheckout) {
+                    timer(tick, KLARNA_READY_POLL_MS);
+                    return;
+                }
+                if (desired === "suspended" && handed !== seq) {
+                    // A global that throws is not ready yet: keep waiting, never throw out of the handle's timer (review I1).
+                    try {
+                        hand("suspended", seq);
+                    }
+                    catch {
+                        timer(tick, KLARNA_READY_POLL_MS);
+                        return;
+                    }
+                }
+                waiting = false;
+            };
+            timer(tick, KLARNA_READY_POLL_MS);
+        };
+        return {
+            suspend: () => {
+                const mine = ++seq;
+                desired = "suspended";
+                if (hand("suspended", mine))
+                    return;
+                awaitScript();
+                return false;
+            },
+            resume: () => {
+                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).
+                try {
+                    hand("resumed", mine);
+                }
+                catch { /* nothing to resume yet */ }
+            },
+            onCannotComplete: (handler) => {
+                const kco = win._klarnaCheckout;
+                if (!kco)
+                    return undefined;
+                let live = true;
+                // A global that throws at bind time is "not bound yet": the handle retries, and mount/remount never throw for it
+                // (main's klarna-kco made no controller call at bind time) (review I1).
+                try {
+                    kco((api) => api.on?.({ can_not_complete_order: () => { if (live && !disposed)
+                            handler(); } }));
+                }
+                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(),

package/dist/gtin.d.ts

@@ -0,0 +1,3 @@
+/** Schema.org's GTIN property for a `gtin` value from the API (GTIN spec §13.3): gtin8, gtin12, gtin13 or gtin14 by
+ *  length. The API sends the canonical form, so the length is the format. Spread it into a Product or Offer object. */
+export declare function gtinJsonLd(gtin: string | null | undefined): Record<string, string>;

package/dist/gtin.js

@@ -0,0 +1,13 @@
+/** Schema.org's GTIN property for a `gtin` value from the API (GTIN spec §13.3): gtin8, gtin12, gtin13 or gtin14 by
+ *  length. The API sends the canonical form, so the length is the format. Spread it into a Product or Offer object. */
+export function gtinJsonLd(gtin) {
+    if (!gtin || !/^\d+$/.test(gtin))
+        return {};
+    switch (gtin.length) {
+        case 8: return { gtin8: gtin };
+        case 12: return { gtin12: gtin };
+        case 13: return { gtin13: gtin };
+        case 14: return { gtin14: gtin };
+        default: return {};
+    }
+}

package/dist/index.d.ts

@@ -53,6 +53,7 @@ export { mountCheckout, type CheckoutHandle, type MountOptions, type MinimalDocu
 export { controllers, type CheckoutController, type ProviderWindow } from "./checkout/controllers.js";
 export { breadcrumbJsonLd } from "./seo/breadcrumb.js";
 export { brandHead, collectionHead, productHead, toNextMetadata } from "./seo/head.js";
+export { gtinJsonLd } from "./gtin.js";
 export { productJsonLd } from "./seo/product.js";
 export { jsonLdScript } from "./seo/serialize.js";
 export { SeoError, type BreadcrumbLink, type CollectionHeadOptions, type HeadOptions, type JsonLd, type NextMetadataLike, type ProductJsonLdOptions, type SchemaProperty, type SeoContext, type SeoHead, type SeoMeta, } from "./seo/types.js";

package/dist/index.js

@@ -42,6 +42,7 @@ export { mountCheckout } from "./checkout/browser.js";
 export { controllers } from "./checkout/controllers.js";
 export { breadcrumbJsonLd } from "./seo/breadcrumb.js";
 export { brandHead, collectionHead, productHead, toNextMetadata } from "./seo/head.js";
+export { gtinJsonLd } from "./gtin.js";
 export { productJsonLd } from "./seo/product.js";
 export { jsonLdScript } from "./seo/serialize.js";
 export { SeoError, } from "./seo/types.js";

package/dist/schema.d.ts

@@ -852,6 +852,8 @@ export interface components {
             collections: components["schemas"]["CollectionRefDto"][];
             description: null | components["schemas"]["DescriptionDto"];
             files: components["schemas"]["MediaDescriptorDto"][];
+            gtin: null | string;
+            gtins: string[];
             id: string;
             image: null | components["schemas"]["MediaDescriptorDto"];
             images: components["schemas"]["MediaDescriptorDto"][];
@@ -1003,6 +1005,8 @@ export interface components {
         };
         VariantDto: {
             brand: null | components["schemas"]["BrandDto"];
+            gtin: null | string;
+            gtins: string[];
             hasOwnImages: boolean;
             id: string;
             image: null | components["schemas"]["MediaDescriptorDto"];

package/dist/seo/product.js

@@ -1,3 +1,4 @@
+import { gtinJsonLd } from "../gtin.js";
 import { jsonLdDescription, pickImages, productDescription, rejectRedirect, requireMarket } from "./shared.js";
 import { SeoError } from "./types.js";
 const PROPERTIES = ["size", "color", "material", "pattern"];
@@ -81,8 +82,13 @@ export function productJsonLd(p, ctx) {
         ...offerExtras(ctx),
     });
     const gtin = (v) => {
-        const g = ctx.gtin?.(v);
-        return g ? { gtin: g } : {};
+        // GTIN spec §13.3 (plan P14): the hook wins when given, and may omit; otherwise the variant's own gtin. A value of
+        // 8, 12, 13 or 14 digits becomes gtin8/12/13/14; any other hook value keeps the generic property.
+        const g = ctx.gtin ? ctx.gtin(v) : (v.gtin ?? undefined);
+        if (!g)
+            return {};
+        const keyed = gtinJsonLd(g);
+        return Object.keys(keyed).length > 0 ? keyed : { gtin: g };
     };
     if (list === null || sellable.length === 0)
         return { ...common("Product"), sku: p.sku, ...(p.brand ? { brand: brandNode(p.brand.label) } : {}) };

package/dist/seo/types.d.ts

@@ -41,6 +41,7 @@ export type ProductJsonLdOptions = SeoContext & {
     variesBy?: Record<string, SchemaProperty>;
     /** Used only when `p.variants` is `null` (more than 100 variants), e.g. the first page of `/variants`. */
     variants?: VariantDto[];
+    /** Overrides the GTIN per variant; return `undefined` to omit. Defaults to the variant's `gtin`. */
     gtin?: (v: VariantDto) => string | undefined;
     seller?: {
         name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asstio-dev/storefront",
-  "version": "0.11.0",
+  "version": "0.13.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\\\", \\\"breadcrumbJsonLd\\\", \\\"productHead\\\", \\\"collectionHead\\\", \\\"brandHead\\\", \\\"toNextMetadata\\\", \\\"jsonLdScript\\\", \\\"SeoError\\\"]) 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\\\", \\\"getOrder\\\", \\\"awaitCompletion\\\", \\\"mountCheckout\\\", \\\"productJsonLd\\\", \\\"gtinJsonLd\\\", \\\"breadcrumbJsonLd\\\", \\\"productHead\\\", \\\"collectionHead\\\", \\\"brandHead\\\", \\\"toNextMetadata\\\", \\\"jsonLdScript\\\", \\\"SeoError\\\"]) if (typeof m[f] !== \\\"function\\\") throw new Error(\\\"missing export \\\" + f) })\""
   },
   "dependencies": {
     "openapi-fetch": "0.17.0"

package/src/schema.d.ts

@@ -852,6 +852,8 @@ export interface components {
             collections: components["schemas"]["CollectionRefDto"][];
             description: null | components["schemas"]["DescriptionDto"];
             files: components["schemas"]["MediaDescriptorDto"][];
+            gtin: null | string;
+            gtins: string[];
             id: string;
             image: null | components["schemas"]["MediaDescriptorDto"];
             images: components["schemas"]["MediaDescriptorDto"][];
@@ -1003,6 +1005,8 @@ export interface components {
         };
         VariantDto: {
             brand: null | components["schemas"]["BrandDto"];
+            gtin: null | string;
+            gtins: string[];
             hasOwnImages: boolean;
             id: string;
             image: null | components["schemas"]["MediaDescriptorDto"];