@asstio-dev/storefront 0.7.0 → 0.11.0

package/README.md

@@ -146,9 +146,11 @@ const html = `<div class="card-image"><div style="${styleToCss(f.box)}">${placeh
 
 `description` is **already sanitized** on the server: render `description.html` as-is — do not sanitize, escape or
 re-parse it — and use `description.text` wherever you need plain text (a meta description, a snippet, an
-`aria-label`). `shortDescription` is plain text. `brand.facet` is set when the brand shares a facet's source, so it
-can link straight to a filtered listing; when it is `null`, render `brand.label` as plain text and never guess a
-filter.
+`aria-label`). `shortDescription` is plain text. `brand` is the product's brand (the main product's); every variant in `variants[]` and on `/variants` carries its own
+`brand` and `responsible` — render the **selected variant's**. `brand.facet` links a filtered listing
+(`filter[facet.key]=facet.valueKey`) when the shop has a brand filter. `brand.url` is the brand page on this market and
+is `null` whenever that page would not exist here (brand pages off, or nothing of the brand sold on this market) — then
+render the label (and `brand.logo`) without a link; never build a brand URL yourself.
 
 `attributes[]` arrives ordered and labelled for display. Branch on `type` (`text` | `html` | `number` | `bool` |
 `list`): a list fills `values`, everything else fills `value`, and `html` fills `html` too — sanitized exactly like
@@ -170,6 +172,77 @@ value has no key of its own: a list is either fully linkable or not linkable at
 `related[]` holds groups of cards already resolved for this market, and `bundle.components[]` the cards a bundle is
 made of; both leave out anything that no longer exists or is not sold here.
 
+### Brands and responsible parties
+
+`responsible` is `{ manufacturer, importer, euResponsiblePerson }`, each a party or `null`. Show the selected variant's
+on the product page (EU GPSR manufacturer and responsible-person contact data). `null` means nothing applies for this
+SKU: do not fall back to the product's or the brand's. `phone` is only present when the shop publishes it.
+
+Brand pages: `GET /v1/brands` lists the brands with a page on this market (paged, by name); `GET /v1/brands/{slugOrId}`
+returns the brand's name, description (sanitized like product descriptions), logo, website, its default parties and
+`facet` — render the listing with `GET /v1/products?filter[<facet.key>]=<facet.valueKey>`. A `redirectTo` means 301 to
+that slug. `GET /v1/sitemap?type=brand` lists them for `sitemap.xml`.
+
+```ts
+const { data: brand } = await storefront.GET("/v1/brands/{slugOrId}", { params: { path: { slugOrId: "hugo-boss" } } });
+if (brand?.redirectTo) redirect(301, `/varumarken/${brand.redirectTo}`);
+const { data: listing } = await storefront.GET("/v1/products", {
+  params: { query: { filter: filterQuery({ [brand!.facet!.key]: [brand!.facet!.valueKey] }) } },
+});
+```
+
+### SEO
+
+Pure helpers that compute schema.org JSON-LD and `<head>` data from the DTOs. They render nothing: your frontend
+writes the markup. No backend call, no DOM, no dependency.
+
+**Product JSON-LD.** `productJsonLd` returns a `Product` (one variant) or a `ProductGroup` with one `Product` and
+`Offer` per variant sold on the market. `variantUrl` is required: Google needs a distinct URL per variant, and opening
+that URL **must preselect the variant** on your page. The format is yours; `?variant=` below is only an example.
+`variesBy` maps your option names to `size`, `color`, `material` or `pattern`; unmapped options still name the
+variants. A product with more than 100 variants arrives with `variants: null`: pass the first `/variants` page as
+`variants`, or the product gets no offer (valid schema.org, but not eligible for product rich results).
+
+```tsx
+const ld = productJsonLd(product, {
+  site, market: "se",
+  variantUrl: (v) => `${product.url}?variant=${v.id}`,
+  variesBy: { Storlek: "size", Färg: "color" },
+});
+<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLdScript(ld) }} />
+```
+
+In a plain template: `<script type="application/ld+json">${jsonLdScript(ld)}</script>`. `jsonLdScript` escapes
+`<`, `>`, `&`, U+2028 and U+2029, so merchant text cannot end the script element; never use plain `JSON.stringify` there.
+
+**Breadcrumbs.** On a collection page, `r.breadcrumb` holds the ancestors only. Add the collection itself as `current`:
+
+```ts
+const crumbs = breadcrumbJsonLd(r.breadcrumb, { home: { name: "Hem", url: "https://moory.se/" }, current: r.collection });
+// null below two items (Google's minimum): render nothing then.
+```
+
+**Head.** `productHead`, `collectionHead` (takes your own `description`; the API has none for collections) and
+`brandHead` return a framework-neutral `SeoHead`: title, description (cut at 160 characters on a word boundary),
+canonical, hreflang alternates (keyed `language-COUNTRY`, `x-default` from the site's default market; override with
+`xDefault: "<market>"` or `false`), and Open Graph / Twitter meta. `titleTemplate: "%s | Moory"` applies to `<title>`
+only, never to the social titles. In Next.js:
+
+```ts
+export async function generateMetadata(): Promise<Metadata> {
+  return toNextMetadata(productHead(product, { site, market: "se", titleTemplate: "%s | Moory" }));
+}
+```
+
+Titles come out as `{ absolute }` on purpose, so a layout's `title.template` does not apply a second time.
+
+**Errors.** `SeoError` means a caller or configuration error: `redirectTo` is set (answer 301 instead), an unknown
+market, a bad `variesBy` value, a `variantUrl` that is not an absolute http(s) URL or repeats for two variants, or
+two markets with the same `language-COUNTRY` and different URLs. Catch it at your SEO boundary and fix the market
+config. Holes in the data never throw: a missing image, description or price only leaves that part out.
+
+hreflang sets are only as reciprocal as the API's `alternateUrls`; the SDK renders what the API gives.
+
 ### Search-as-you-type and search-in-facet
 
 `/v1/search/suggest` answers three short lists for what the shopper has typed so far: up to 5 product cards
@@ -193,6 +266,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.
@@ -234,9 +421,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;