@asstio-dev/storefront 0.15.1 → 0.16.3

package/README.md

@@ -360,8 +360,8 @@ answers the converted cart's completed attempt) with the same token, navigate to
 `order`, and clear the cookie only once the confirmation page holds the access token.
 
 **Copy and CSP.** The `pending` state ("awaiting payment approval") is your copy. Each provider's widget needs its
-domains in your CSP: Qliro One `*.qliro.com` (`pago.qit.nu` in the sandbox), Klarna/Kustom `*.klarna.com`
-(`*.kustom.co`), Walley `*.walleypay.com`, plus their `frame-src`/`script-src`/`connect-src` — the provider's
+domains in your CSP: Qliro One `*.qliro.com` (`pago.qit.nu` in the sandbox), Kustom `*.kustom.co` (verified, see
+below), Walley `*.walleypay.com`, plus their `frame-src`/`script-src`/`connect-src` — the provider's
 integration guide lists the exact hosts.
 
 Problem codes you will meet here: `CART_EMPTY`, `CHECKOUT_CART_CHANGED` (with `cart`), `CHECKOUT_PREVIEW_KEY`,
@@ -375,8 +375,10 @@ Problem codes you will meet here: `CART_EMPTY`, `CHECKOUT_CART_CHANGED` (with `c
 - The widget is Qliro's HTML snippet; `mountCheckout` re-creates its scripts so they run.
 - After every cart change, `handle.sync(update)` locks the widget (`q1.lock()`), and resumes it through
   `q1.onOrderUpdated`, which makes the iframe re-read the order. The widget unlocks only when Qliro's order shows the
-  confirmed total. If it does not within 10 seconds, or the change came before Qliro's script had loaded, the widget is
-  re-rendered from the confirmed checkout instead; it is never unlocked before Qliro shows the confirmed total.
+  confirmed total, or echoes the confirmed cart version (`MerchantUpdateVersion`, which the backend sends on a market
+  with shipping, where Qliro's total includes the fee). If it does neither within 10 seconds, or the change came before
+  Qliro's script had loaded, the widget is re-rendered from the confirmed checkout instead; it is never unlocked before
+  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.
 
@@ -397,9 +399,56 @@ Problem codes you will meet here: `CART_EMPTY`, `CHECKOUT_CART_CHANGED` (with `c
   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.
+- 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.
+- **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
+  Kustom's own policy. Allow:
+  - `script-src 'unsafe-inline' https://*.kustom.co`;
+  - `frame-src https://*.kustom.co`;
+  - `connect-src https://*.kustom.co`.
+
+  `https://*.kustom.co` covers the playground (`js.playground.kustom.co`) and production (`js.kustom.co`).
+
+### Shipping
+
+The shopper chooses delivery inside the provider's widget (Kustom's shipping assistant, Qliro's shipping step), so
+there is **no shipping picker to build and no price, VAT or method id to send**. The `klarna-kco` (Kustom) and `qliro-q1`
+controllers answer for the widget; the page's part is the estimate before the checkout and the shipping block on the order.
+
+```ts
+// The estimate: an estimate, never a quote (the destination is not known yet). No lookup, `no-store`.
+const { data: estimate } = await storefront.GET("/v1/cart/shipping-estimate", {
+  params: { header: { "X-Cart-Token": token } },
+});
+if (estimate?.available) {
+  const headline = estimate.options.find((option) => option.preselected); // `fee` is gross kronor, "49.00"
+  // estimate.freeShipping: { free, threshold, remaining } — progress comes from here, never a hard-coded threshold
+}
+// `available: false` means show nothing about shipping. `reason: null`: no block published on the market, and the
+// checkout works as before. `reason: "unavailable"`: a block that cannot be served now; the cart works, but
+// POST /v1/checkout refuses a new attempt with 503 SHIPPING_UNAVAILABLE (Retry-After 60) until it is fixed.
+
+// The order page: `order.shipping` is `OrderShippingDto | null`.
+// null = the selection was not matched or confirmed (the charged shipping line is still in `order.lines`), or the
+// market has no block. Show the block only when it is present; never read null as "no shipping was paid".
+```
+
+- `ShippingEstimateOptionDto`: `key`, `name`, `deliveryType` (`delivery`, `pickup` or `mailbox`), `fee`, `regularFee`
+  (the price without the free-shipping rule; set only when `fee` is `"0.00"` and that price is above 0, so `null`
+  for an always-free method: render no comparison price then), `labels`, `pointsAtCheckout` (the pickup point is
+  chosen in the checkout; none is listed here) and `preselected`. The estimate has **no delivery time**.
+- `OrderShippingDto`: `option`, `name`, `deliveryType`, `carrier`, `fee`, `point` (name, street, postal code, city; null
+  when the carrier assigned it or after the privacy scrub) and `deliveryTime` (`mode` `carrierEstimate`, `fixed` or
+  `text`; `minDays` and `maxDays` are each nullable: render only the bounds that are present, or `text`).
+- **Do not re-render the widget** when shipping changes, and do not write your own Qliro unlock: on a market with a
+  shipping block Qliro's total includes the fee and so can differ from the cart's, and the `qliro-q1` controller unlocks on the echoed cart version
+  (`MerchantUpdateVersion`) or on the confirmed total (see the Qliro notes above).
+- Shipping never blocks a purchase. If a selection cannot be matched when the shopper pays, the order is accepted and
+  normally held in Asstio with its reason (rarely the export waits for an operator instead); the page has nothing to
+  do for it.
 
 ## Headers
 

package/dist/checkout/browser.js

@@ -357,7 +357,7 @@ export function mountCheckout(container, checkout, options) {
                     // 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))
+                        resume({ cart: dto.cart, cartVersion: Number(dto.cartVersion), onUnsynced: () => { if (alive(gen))
                                 remount(dto); } });
                 }
                 else {

package/dist/checkout/controllers.d.ts

@@ -37,6 +37,9 @@ export interface ResumeTarget {
     cart: {
         grandTotalInc: string;
     };
+    /** The confirmed answer's cart version. On a shipping market Qliro's PUT carries it as `MerchantUpdateVersion`, so its
+     * echo in Qliro's order also shows the update landed (carriers 1b ruling R-S3-K1). */
+    cartVersion?: number;
     /** The provider never showed `cart` before its deadline: the handle re-renders the widget from the confirmed answer. */
     onUnsynced(): void;
 }
@@ -66,7 +69,9 @@ export type ControllerFactory = (win: ProviderWindow, timer: ControllerTimer) =>
  * 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;
+ * 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
+ * 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>;
 export declare function controllerFor(name: string, win: ProviderWindow, timer?: ControllerTimer): CheckoutController;

package/dist/checkout/controllers.js

@@ -5,10 +5,23 @@ export const KLARNA_READY_POLL_MS = 100;
 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);
+ * 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
+ * name is read case-insensitively (VQ-8 records the real one). */
+export function qliroOrderMatches(order, target) {
+    const o = order;
+    const total = o?.totalPrice;
+    if ((typeof total === "number" || typeof total === "string") && ore(total) === ore(target.cart.grandTotalInc))
+        return true;
+    if (target.cartVersion === undefined || !o)
+        return false;
+    const key = Object.keys(o).find((k) => k.toLowerCase() === "merchantupdateversion");
+    const raw = key === undefined ? undefined : o[key];
+    // Only a number or a non-blank string is an echo: `Number("")` and `Number(null)` are 0, which must not match version 0.
+    if (!(typeof raw === "number" || (typeof raw === "string" && raw.trim() !== "")))
+        return false;
+    const echoed = Number(raw);
+    return Number.isFinite(echoed) && echoed === Number(target.cartVersion);
 }
 export const controllers = {
     "qliro-q1": (win, timer) => {
@@ -42,7 +55,7 @@ export const controllers = {
                 }
                 if (missedLock)
                     q1.lock(); // onOrderUpdated "requires q1.lock() to have been called first"
-                q1.onOrderUpdated((order) => { if (qliroOrderMatches(order, target.cart))
+                q1.onOrderUpdated((order) => { if (qliroOrderMatches(order, target))
                     unlock(); });
                 // Never unlocked blindly: past the deadline the handle re-renders the widget from the confirmed answer
                 // *(plan review 1 #3)*.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asstio-dev/storefront",
-  "version": "0.15.1",
+  "version": "0.16.3",
   "description": "Typed client for the Asstio Storefront API (generated from OpenAPI).",
   "repository": {
     "type": "git",