@asstio-dev/storefront 0.6.0 → 0.9.2

package/README.md

@@ -53,7 +53,7 @@ const { data: page } = await storefront.GET("/v1/products/{slugOrId}/variants",
 ```
 
 Every example in this file is compiled as part of `npm run check` — the source of them is
-[`examples/readme.ts`](examples/readme.ts), which also covers product lookup, ETag revalidation and crawling.
+[`examples/readme.ts`](examples/readme.ts), which also covers product lookup, ETag revalidation, crawling, and image formats.
 
 ### Images
 
@@ -78,6 +78,70 @@ for (const file of product?.files ?? []) console.log(file.filename, fileUrl(site
 `videoSources` returns `[]` for anything that is not a video, while `mediaUrl`/`pictureSources`/`fileUrl`/`posterUrl`
 throw `MediaUrlError` when the descriptor cannot produce that URL — branch on `kind` before calling.
 
+### Image formats
+
+A site's **formats** (`site.media.formats`: `card`, `gallery`, `thumb`, `cart`, `swatch`, `default`, plus custom
+keys) say how an image is framed: aspect, fit (`contain` · `cover` · `natural`), padding and a background per
+`bg` class. They are published with the site, so the look changes without a frontend deploy. `formatImage` turns
+a descriptor and a format key into everything a `<picture>` needs:
+
+```ts
+import { formatImage } from "@asstio-dev/storefront";
+
+const f = formatImage(site.media, product.image, "card", [
+  { media: "(min-width: 1080px)", size: "25vw" },   // your slot's width per breakpoint
+  { size: "100vw" },                                // the last one without a media condition
+]);
+// React:
+// <div className={styles.cardImage}>                                  ← your slot: your class, may be a flex/grid item
+//   <div style={f.box}>                                               ← the aspect frame, the slot's only child
+//     <canvas ref={blurhashCanvas} style={f.placeholder} />           ← optional placeholder, same rectangle as the image
+//     <picture>
+//       {f.sources.map((s) => <source key={s.type} {...s} />)}
+//       <img {...f.fallback} style={f.img} alt={alt} loading="lazy" />
+//     </picture>
+//   </div>
+// </div>
+```
+
+Plain HTML (templating):
+
+```ts
+const f = formatImage(site.media, product.image, "card", [
+  { media: "(min-width: 1080px)", size: "25vw" },
+  { media: "(min-width: 640px)", size: "50vw" },
+  { size: "100vw" },
+]);
+// alt is merchant text, not SDK output: escape it for the attribute.
+const escapeAttr = (s: string) => s.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+const alt = escapeAttr(product.image.alt["sv"] ?? product.name);
+// Your slot owns the width; box is its only child in every fit:
+const picture =
+  `<picture>${f.sources.map((s) => `<source type="${s.type}" srcset="${s.srcSet}" sizes="${s.sizes}">`).join("")}` +
+  `<img src="${f.fallback.src}" srcset="${f.fallback.srcSet}" sizes="${f.fallback.sizes}" width="${f.fallback.width}" height="${f.fallback.height}" alt="${alt}" loading="lazy" style="${styleToCss(f.img)}"></picture>`;
+const placeholder = `<canvas width="32" height="32" style="${styleToCss(f.placeholder)}"></canvas>`;
+const html = `<div class="card-image"><div style="${styleToCss(f.box)}">${placeholder}${picture}</div></div>`;
+```
+
+- **Element contract.** Your slot element owns the width (grid, flex, `className`); it may be stretched. Put the
+  `box` inside it as its only child and give the box **no** padding, border or height of its own — its inline
+  styles pin its geometry, so a stretched slot never distorts the format's aspect.
+- **One rectangle.** `img` and `placeholder` are the same absolutely positioned rectangle with `object-fit: fill`,
+  computed from the descriptor: a blurhash canvas of any decode size is stretched to exactly where the image will
+  paint. The box's `backgroundColor` shows around a `contain` image and through transparent AVIF/WebP.
+- **Natural** has a box too, at the image's own aspect and without a colour; `img` and `placeholder` fill it. So
+  the layout is reserved before load in every fit, and the placeholder sits under the image the same way.
+- **`sizes`** is your slots scaled by the image's drawn fraction with `calc()`; `srcset` keeps the real widths, so
+  the browser downloads a sharp enough rendition for a cover crop and not a wasted one for a padded packshot.
+- `formats: null` (a site without formats) or an unknown key falls back to `default`, then to `natural`; your own
+  CSS keeps working. `focal` (set per placement in Asstio) positions a `cover` crop; `showWhole` renders a cover
+  format as contain for that image. `formatImage` throws `MediaUrlError` for video descriptors, file descriptors,
+  a descriptor without `w`/`h`, a descriptor without renditions, or an empty `slots` array.
+- Plain HTML: see the templating example above, or the compiled function `productCard` in [`examples/readme.ts`](examples/readme.ts).
+  `styleToCss(f.box)` gives the `style` attribute value for any element. Escape anything that is not SDK output
+  (`alt`, product names) before it goes into markup; the React example needs no escaping because React escapes
+  attribute values.
+
 ### Product content
 
 `description` is **already sanitized** on the server: render `description.html` as-is — do not sanitize, escape or
@@ -129,6 +193,120 @@ case-insensitively, or key prefix — returning at most 50. A facet with more di
 over its top 1000; no regular expression ever reaches the search index. `key` has to be a `list` or `swatch` facet:
 an unknown key is `FACET_NOT_FOUND` (404), and a range or toggle facet is `FACET_NOT_SEARCHABLE` (400).
 
+### Checkout
+
+Two small modules, because the suspend → update → resume rule spans two runtimes. The server helpers need the
+client and the cart token (an `httpOnly` cookie, so they run in Server Actions and route handlers);
+`mountCheckout` needs neither key nor fetch — it mounts the provider's widget and drives it from the answers
+your server hands it.
+
+```ts
+import { awaitCompletion, completeCheckout, getCheckoutStatus, getOrder, mountCheckout, startCheckout, syncCheckout } from "@asstio-dev/storefront";
+```
+
+**Server.** `startCheckout(client, cartToken, { option?, returnOrigin? })` creates the cart's checkout attempt
+or converges on the live one; call it from a Server Action or route handler **on the shopper's navigation to the
+checkout page, never during a Server Component's render** (a re-render would create a provider order per
+mutation). `syncCheckout` is the same `POST /v1/checkout`, retrying `CHECKOUT_IN_PROGRESS` per `Retry-After`
+twice by default — **call it after every cart mutation on the checkout page**, through the browser handle's
+`update`; there, and for the handle's `sync`, pass `{ retries: 0 }` so each call is one POST and the handle's own
+burst does the retrying. `getCheckoutStatus(client, attemptId, cartToken)` is the non-mutating
+`GET /v1/checkout/{attemptId}` behind the handle's `status` callback.
+`completeCheckout(client, attemptId, cartToken?)` is the confirmation page's call; with the cart token
+the answer carries `order.accessToken`, on every call, so a lost first answer or a reload still ends with the token.
+`awaitCompletion(() => completeCheckout(…))` polls with backoff until the order exists. `getOrder(client, orderId,
+token)` sends the token as `X-Order-Token` — a header, never a query string; send `Referrer-Policy: no-referrer`
+on the order page and keep its URL out of your logs.
+
+```ts
+// A Server Action or route handler, on the shopper's navigation to the checkout page.
+const result = await startCheckout(storefront, cartToken, { returnOrigin: "https://shop.example" });
+if (!result.ok) return { problem: result.problem, retryAfter: result.retryAfter };
+return { checkout: result.data };   // "open" with a widget, or "completed"/"pending" with an order
+
+// The Server Action behind mountCheckout's `sync`, and the POST inside every cart update: one HTTP POST per call.
+export async function syncForBrowser() {
+  return syncCheckout(storefront, cartToken, undefined, { retries: 0 });
+}
+
+// The confirmation page: complete with the cart token, keep the order's access token, then poll for the number.
+const first = await completeCheckout(storefront, attemptId, cartToken);
+const done = await awaitCompletion(() => completeCheckout(storefront, attemptId, cartToken));
+
+// The order page: the token is a header.
+const order = await getOrder(storefront, orderId, token);   // 404 ORDER_NOT_FOUND for an unknown id and a wrong token alike
+```
+
+**Browser.** `mountCheckout(container, checkout, { sync, status, onProblem, onOrder })` takes the `open` answer
+your page was rendered with and returns a handle `{ attemptId, suspended, suspend, resume, remount, destroy,
+sync(update) }`. The container is a client component **keyed by `attemptId`**. `handle.sync(update)` is the whole
+rule: it suspends the widget, runs your `update` **once** (mutate the cart, `POST /checkout`, return its answer),
+then dispatches **status first, identity on `open`**: `completed`/`pending` → `onOrder(order, attemptId)` (you
+navigate); `locked` → stays suspended and retries `sync()` per `Retry-After` within the API's budget (30 s, ten
+calls — a 429 counts the same; a `Retry-After` past the 30 s is not waited out), then polls `status(attemptId)`;
+`processing` → polls `status()`; `declined`/`expired` → one `sync()`; `open` → resumes when the answer's
+`attemptId` is the mounted one, else remounts from the answer's widget (`changed` only says *this* call created a
+new attempt — never resume on it). A `status()` answer is never dispatched as payable: its `open` leads to one
+non-mutating `sync()`. An `update` that throws leaves the widget suspended. The widget is suspended the moment
+`handle.sync` is called, and stays suspended while another update is queued behind it; a newly queued update ends
+the running sync's waits (a retry or a status poll), so it runs at once. `CHECKOUT_IN_PROGRESS` is retried like
+`locked`, within the same burst. If the provider's script loads late, the handle keeps trying to bind its decline
+signal every half second for as long as the widget is mounted. A 503 `CHECKOUT_UNAVAILABLE` or
+`CHECKOUT_PROVIDER_UNAVAILABLE` is retried per its `Retry-After` by non-mutating syncs within the same budget, then
+reported; any other 503 (`SITE_KEYS_SYNCING`, `SITE_REGISTRY_WARMING`) and every other non-2xx of the SDK's own calls
+reaches `onProblem(problem, { status })` at once, `status` being the HTTP status — a `409 CHECKOUT_CART_CHANGED`
+carries the corrected cart in `problem.cart`: show it and its warnings, then `handle.sync(() => POST /checkout)`.
+`handle.sync` never rejects. `onProblem` also receives the SDK's own codes: `SDK_SYNC_FAILED` or `SDK_STATUS_FAILED`
+when one of its calls throws (a network failure), `SDK_UPDATE_FAILED` when your `update` throws, and
+`SDK_DISPATCH_FAILED` for any other throw while dispatching (an `onOrder` that throws, an unknown widget controller) —
+each with `{ status: 0 }` and the widget left suspended; `SDK_CHECKOUT_CLOSED` when the one `sync()` after a
+`declined`/`expired` answers closed again, and `SDK_UNKNOWN_STATUS` for an answer status the SDK does not know (both
+`{ status: 200 }`); and `SDK_EMPTY_ANSWER`, which the server helpers return when an answer carried no body (with that
+answer's HTTP status). The SDK also syncs **by itself**: once on the provider's
+payment-declined signal where its JavaScript offers one, when the page becomes visible again while suspended, and
+**three minutes before expiry, timed from the DTO's `expiresInSeconds`** (server-relative, so a browser clock ahead
+of the server's still lands inside the server's five-minute window). An autonomous sync is skipped while another
+sync is running or queued.
+
+```ts
+// A client component, keyed by attemptId so a re-render never resets it.
+const handle = mountCheckout(container, checkout, {
+  sync: callSync,       // a Server Action calling syncForBrowser()
+  status: callStatus,   // a Server Action calling getCheckoutStatus(storefront, attemptId, cartToken)
+  onProblem: (problem) => { /* problem.cart when code === "CHECKOUT_CART_CHANGED"; otherwise the message for problem.code */ },
+  onOrder: (order, attemptId) => { location.assign(`/kassa/tack?attempt=${attemptId}&order=${order.id}`); },
+});
+// Every cart mutation on the page goes through the handle: suspend → your update once → status first, identity on open.
+await handle.sync(() => callAddLine(sku));   // callAddLine mutates the cart, then syncs, and returns that answer
+```
+
+**After completion.** Every cart endpoint answers `410 CART_EXPIRED` for the converted cart, while the cart token
+is still what re-delivers the order's access token — so **a `410` from a cart mutation on the checkout or
+confirmation path does not end the cart cookie**: call `GET /v1/checkout/{attemptId}` (or `POST /checkout`, which
+answers the converted cart's completed attempt) with the same token, navigate to the confirmation from its
+`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
+integration guide lists the exact hosts.
+
+Problem codes you will meet here: `CART_EMPTY`, `CHECKOUT_CART_CHANGED` (with `cart`), `CHECKOUT_PREVIEW_KEY`,
+`CHECKOUT_MARKET_MISMATCH` (switch the cart's market first, then sync), `OPTION_NOT_AVAILABLE`,
+`ORIGIN_NOT_ALLOWED`, `CHECKOUT_UNAVAILABLE` and `CHECKOUT_PROVIDER_UNAVAILABLE` (503, `Retry-After`),
+`CHECKOUT_IN_PROGRESS` (409, `Retry-After`), `CHECKOUT_PROVIDER_REJECTED` (502), `CHECKOUT_NOT_FOUND`,
+`ORDER_NOT_FOUND`, `SITE_KEYS_SYNCING` (503 for a secret key on a freshly created site, `Retry-After`).
+
+#### Qliro (`qliro-q1`)
+
+- 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.
+- 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.
+
 ## Headers
 
 Every call the client makes carries these; you never set them by hand.
@@ -170,9 +348,14 @@ Codes you will meet: `SITE_KEY_MISSING`, `SITE_KEY_INVALID`, `SITE_INACTIVE`, `S
 `SITE_REGISTRY_WARMING`, `MARKET_UNKNOWN`, `RATE_LIMITED` (with `retryAfterSeconds`, plus a `Retry-After`
 header), `PRODUCT_NOT_FOUND`, `COLLECTION_NOT_FOUND`, `INVALID_PAGE`, `INVALID_SINCE`, `INVALID_TYPE`,
 `INDEX_UNAVAILABLE` (retry — a preview index is being rebuilt), `NOT_FOUND`, `INVALID_QUERY`,
-`FACET_NOT_FOUND`, `FACET_NOT_SEARCHABLE`.
-
-`SITE_REGISTRY_WARMING` and `INDEX_UNAVAILABLE` are retries, not bugs in your call.
+`FACET_NOT_FOUND`, `FACET_NOT_SEARCHABLE`,
+and, from the checkout ([above](#checkout)): `CART_EMPTY`, `CHECKOUT_CART_CHANGED`, `CHECKOUT_PREVIEW_KEY`,
+`CHECKOUT_MARKET_MISMATCH`, `OPTION_NOT_AVAILABLE`, `ORIGIN_NOT_ALLOWED`, `CHECKOUT_UNAVAILABLE`,
+`CHECKOUT_PROVIDER_UNAVAILABLE`, `CHECKOUT_IN_PROGRESS`, `CHECKOUT_PROVIDER_REJECTED`, `CHECKOUT_NOT_FOUND`,
+`ORDER_NOT_FOUND`, `SITE_KEYS_SYNCING`, `CART_EXPIRED`.
+
+`SITE_REGISTRY_WARMING` and `INDEX_UNAVAILABLE` are retries, not bugs in your call, as are the checkout's
+`CHECKOUT_IN_PROGRESS`, `CHECKOUT_UNAVAILABLE`, `CHECKOUT_PROVIDER_UNAVAILABLE` and `SITE_KEYS_SYNCING` (each with `Retry-After`).
 
 ## Warnings
 

package/dist/checkout/browser.d.ts

@@ -0,0 +1,76 @@
+import { type ProviderWindow } from "./controllers.js";
+import { type CheckoutDto, type CheckoutOrderRefDto, type CheckoutResult, type StatusResult, type StorefrontProblem } from "./types.js";
+export interface MinimalScript {
+    src: string;
+    textContent: string | null;
+    async: boolean;
+    defer: boolean;
+    type: string;
+    getAttributeNames(): string[];
+    getAttribute(name: string): string | null;
+    setAttribute(name: string, value: string): void;
+    parentNode?: {
+        replaceChild(newNode: unknown, oldNode: unknown): void;
+    } | null;
+}
+export interface MinimalElement {
+    innerHTML: string;
+    querySelectorAll(selector: "script"): ArrayLike<MinimalScript>;
+    appendChild(node: unknown): unknown;
+    ownerDocument?: MinimalDocument | null;
+}
+export interface MinimalDocument {
+    createElement(tag: "script"): MinimalScript;
+    visibilityState: string;
+    addEventListener(type: "visibilitychange", fn: () => void): void;
+    removeEventListener(type: "visibilitychange", fn: () => void): void;
+}
+export interface MinimalWindow {
+    document?: MinimalDocument;
+}
+export interface MountOptions {
+    /** A plain, non-mutating `POST /checkout` (server-side, with the cart token). Recommended: one HTTP POST per call,
+     * `syncCheckout(client, cartToken, opts, { retries: 0 })` — the handle retries `CHECKOUT_IN_PROGRESS` itself inside
+     * its 30 s burst *(plan review 3 #5, final review S1)*. */
+    sync: () => Promise<CheckoutResult>;
+    /** A `GET /checkout/{attemptId}` on the attempt named. */
+    status: (attemptId: string) => Promise<StatusResult>;
+    /** Every non-2xx the SDK's own calls meet, a call of its own that threw, an `update` that threw, and any other
+     * throw while dispatching (`SDK_DISPATCH_FAILED`: an `onOrder` that threw, an unknown controller). A 409
+     * CHECKOUT_CART_CHANGED carries the corrected cart in `problem.cart`. */
+    onProblem: (problem: StorefrontProblem, context: {
+        status: number;
+    }) => void;
+    /** An order exists: navigate to the confirmation from it. The SDK never navigates itself. */
+    onOrder: (order: CheckoutOrderRefDto, attemptId: string) => void;
+    document?: MinimalDocument;
+    window?: ProviderWindow & MinimalWindow;
+    now?: () => number;
+    setTimeout?: (fn: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+    /** The `locked` burst, sized to the API's checkout:{cartToken} policy (20/min): 30 s and at most ten calls (spec
+     * §10.3). The spec's burst is the whole client-side budget: the rolling-minute POST ledger rounds 2–3 added is cut —
+     * the server enforces the policy and a 429 is handled like `locked` *(final review S1)*. */
+    lockedBudgetMs?: number;
+    lockedMaxCalls?: number;
+    pollFirstMs?: number;
+    pollMaxMs?: number;
+    /** How many consecutive `locked` status answers lead to one sync() rather than more polling *(plan review 1 #12)*. */
+    lockedPollsBeforeSync?: number;
+    /** Binding the provider's decline signal until its script has run: every `bindRetryMs` (500 ms) for as long as the
+     * widget is mounted — one interval, no fast and slow phases *(plan review 2 #13, plan review 3 #4, final review S8)*. */
+    bindRetryMs?: number;
+    /** How long before `expiresInSeconds` the SDK syncs by itself (inside the server's five-minute window). */
+    preExpiryMs?: number;
+}
+export interface CheckoutHandle {
+    readonly attemptId: string;
+    readonly suspended: boolean;
+    suspend(): void;
+    resume(): void;
+    remount(checkout: CheckoutDto): void;
+    destroy(): void;
+    /** The whole rule: suspend → `await update()` once → status first, identity on `open`. Never rejects. */
+    sync(update: () => Promise<CheckoutResult>): Promise<void>;
+}
+export declare function mountCheckout(container: MinimalElement, checkout: CheckoutDto, options: MountOptions): CheckoutHandle;