@sixtyninecommerce/client 0.30.0 → 0.32.0

package/README.md

@@ -125,7 +125,7 @@ const results = await client.commerce.searchProducts(
 // Pricing helpers
 client.pricing.formatPrice(2999, 'EUR'); // "€29.99"
 client.pricing.getTierForQuantity(variant.priceTiers, 10);
-client.pricing.validateOrderMinimums(order, { minOrderAmount: 5000 });
+client.pricing.validateOrderMinimums(order, await client.commerce.getOrderConstraints());
 
 // Media helpers
 client.media.assetUrl('shop/source/photo.jpg');
@@ -135,11 +135,91 @@ client.media.getResponsiveImageData(asset); // { src, srcSet, sizes, alt }
 // Language & auth
 client.setLanguage('nl');
 client.setAuthToken(token);
+```
+
+## Several stores in one process
+
+One storefront app can serve several stores. Pass `resolveStore` instead of `storeCode`, and you
+get a **store router** back (not a promise). Each request asks it for a client of its own:
+
+```typescript
+import { createStorefrontClient, storeFromHostMap } from '@sixtyninecommerce/client';
+
+export const stores = createStorefrontClient({
+  cdnUrl: 'https://cdn.example.com',
+  // Your rule for which store a request belongs to. Return null for "none".
+  resolveStore: storeFromHostMap({
+    'fashion.example.com': 'fashion-store',
+    'trade.fashion.example.com': { storeCode: 'fashion-store', head: 'trade' },
+    'gear.example.com': { storeCode: 'gear-store', language: 'nl' },
+  }),
+  stores: ['fashion-store', 'gear-store'], // optional allow-list
+  privateToken: { 'fashion-store': process.env.FASHION_TOKEN! }, // per store, server only
+});
+
+// Per request (a route handler, a server component, middleware):
+const client = await stores.forRequest(request, {
+  customerToken: cookies.get('token'),   // this shopper's session
+  currencyCode: cookies.get('currency'), // this shopper's currency
+  buyerIp: clientAddress,                // sent only to a store with a private token
+  onAuthToken: (token) => cookies.set('token', token),
+});
+await client.commerce.getProduct('blue-shirt');
+
+// Or name the store yourself:
+const gear = await stores.forStore('gear-store');
+```
 
-// Escape hatch for custom queries
-const data = await client.graphql(`query { activeChannel { id } }`);
+- **Nothing a shopper does crosses requests.** The sign-in, language, currency, order scope, head
+  and buyer address belong to the client `forRequest`/`forStore` returned and to nothing else —
+  two concurrent requests, for one store or two, never send each other's. That is also why the
+  router's config refuses `customerToken`, `currencyCode` and `buyerIp`: pass them per request.
+- **What a store shares** between its requests: the channel (read once, refreshed when the
+  platform's answer changes), its CDN, its redirect map and its private token. One channel lookup
+  serves every store.
+- **Private tokens are per store.** A token is bound to one channel, and the platform ignores it on
+  any other store's requests, so `privateToken` is `{ [storeCode]: token }` or a function.
+- **Which store** is your rule (`resolveStore(request) → code | { storeCode, head?, language? } |
+  null`). Two ready-made rules for a fixed list: `storeFromHostMap` (the `Host` header the server
+  received — exact, then on any port — and the URL only when there is none, since self-hosted
+  Next builds `request.url` on its own host; never `X-Forwarded-Host`, which a visitor can send)
+  and `storeFromPathPrefix`
+  (`{ '/nl': 'store-nl', '/be': 'store-be' }`, whole segments, longest prefix first). Host keys
+  may be written in Unicode or punycode (`bücher.example` = `xn--bcher-kva.example`). The URL you
+  pass must be absolute — on a plain `node:http` server, build it from the `Host` you trust.
+- **Refusals** are `StorefrontError`s with status 404, so a page can render its not-found view from
+  `error.status`: `STORE_NOT_RESOLVED` (your rule returned null), `STORE_NOT_ALLOWED` (outside
+  `stores`), `CHANNEL_NOT_FOUND` (an unknown code, the bootstrap root, or an organization's
+  workspace — a hub is never a store). Set `stores` whenever your rule passes on anything taken
+  from the request, so a visitor cannot make the process look up codes it does not serve.
+- **Canonical links** are always built on each store's main shop address (`storefrontUrl`),
+  whichever host or head the request came in on.
+- **Cache tags** carry the store: every tag a read is sent with also goes out as
+  `store:<code>:<tag>` (`storeCacheTag`), so one store's events purge that store's pages only (see
+  [Next.js revalidation](#nextjs-revalidation-platform-events)). The `/next` and `/web` adapters
+  accept the router too: `createSeoArtifactHandler(stores, 'sitemap')` /
+  `createSeoArtifactResponder(stores, 'sitemap')`, `createProductFeedHandler(stores)` /
+  `createProductFeedResponder(stores)` and `createRedirectMiddleware({ client: stores, onError })`
+  serve each request from its own store, and answer a request no store serves with 404 (the
+  middleware falls through; its `onError` also hears when a store's redirect map fails to load).
+  The `/next` handlers tag their upstream fetch store-scoped too; `/web` sets no cache tags.
+- **Per router, not per request:** a `conditionalReads: { maxEntries, maxBytes }` cache, and the
+  once-per-route deprecation warning, are kept for the router's whole life.
+
+### Heads (`head`)
+
+A store can have several sites — a consumer shop and a trade portal, say — registered as heads.
+`head` names the one a client speaks for, sent as `x-head`, and the platform composes every link it
+emails for that request (sign-in, magic link, invite, password reset) on that head's address:
+
+```typescript
+const client = await createStorefrontClient({ storeCode: 'fashion-store', cdnUrl, head: 'trade' });
 ```
 
+Any key the store registered (lowercase letters, digits, single hyphens); the platform honours a
+`web`, `trade` or `native` head and ignores any other, falling back to the store's default head.
+Unset, nothing is sent — exactly as before. Canonical links do not follow it.
+
 ## Deprecated: the `/admin` surface
 
 `@sixtyninecommerce/client/admin` (`createCommerceAdminClient`) is **deprecated**. Use
@@ -161,16 +241,77 @@ Five things have no successor yet, and are the reason to stay on this surface:
 This surface still works and is unchanged; it will be removed in a future major, not before those
 land.
 
+## Deprecated: `client.graphql()`
+
+`client.graphql(query, variables)` — a raw Shop API document — is **deprecated**. It keeps
+working until 1.0, and the first call in a process prints one line saying so. Every common use has
+a typed method now:
+
+| Instead of a raw query for | Call |
+|---|---|
+| a collection or product by id | `commerce.getCollectionById(id)`, `commerce.getProductById(id)` |
+| storefront metafields | `commerce.getProduct(slug, { metafields: true })` (also `getProductById`, `getCollection`, `getCollectionById`) |
+| the session currency | `createStorefrontClient({ currencyCode })`, `commerce.setOrderCurrency(code)` |
+| what the store is ready to serve | `commerce.getCapabilities()` |
+| one content string | `content.getContentString(id)` |
+| logo, cover, favicon / a CMS asset | `commerce.getBranding()` / `content.getAsset(id)` |
+| a named sign-in strategy, order custom fields, unsetting addresses, order states | `commerce.authenticate`, `setOrderCustomFields`, `unsetShippingAddress` / `unsetBillingAddress`, `getNextOrderStates` / `transitionOrder` |
+
+The Shop API fields no method sends yet are listed in the MCP capability catalog
+(`storefront://capability-catalog`). Route the notice to your logger, or silence it, with
+`onDeprecation`:
+
+```typescript
+const client = await createStorefrontClient({
+  storeCode: 'fashion-store',
+  cdnUrl: 'https://cdn.fashion-store.com',
+  // kind 'method' (client.graphql) or 'endpoint' (a platform route sent a Deprecation header)
+  onDeprecation: (notice) => logger.warn({ deprecation: notice }),
+});
+```
+
+Unset, a deprecated method is printed once per process, a deprecated platform route once per
+client. Set, the hook is called once per client for each (once per router with `resolveStore`).
+
 ## Modules
 
 | Module | Description |
 |--------|-------------|
-| `commerce` | Products, collections, property trees, search, cart, checkout, customer auth |
-| `content` | CMS resolve, content items, assets, forms, content strings, menus |
+| `commerce` | Products, collections, property trees, search, cart, checkout, customer auth, the store's capability manifest (`getCapabilities`), store pickup (`getStorePickupLocations`, `chooseStorePickup`, `clearStorePickup`, `getActiveOrderStorePickup`; see `docs/storefront/store-pickup.md`), the receipt account claim (`claimReceipt`; see below) |
+| `content` | CMS resolve, content items, assets, forms, content strings (all, or one by id), menus |
 | `navigation` | Unified route manifest, route lookup |
 | `pricing` | Price formatting, tier lookup, order validation (pure), resolved tax display mode |
 | `media` | CDN URLs, preset URLs, responsive image data (pure functions) |
 | `currency` | Exchange rates, currency conversion |
+| `feeds` | Product-feed URLs (Google Shopping, Meta, Pinterest, TikTok) |
+
+## Registration
+
+`register` creates the account and **signs nobody in**. The store emails the address a
+"finish creating your account" link; the account works once the shopper opens it and chooses a
+password there, which proves the address is theirs. Opening it signs them in. So after `register`
+show "check your email", never a signed-in page, and do not call `login`: until the link is used,
+a login answers `PASSWORD_RESET_REQUIRED` and emails the link again.
+
+```typescript
+await client.commerce.register({ emailAddress, firstName, lastName });
+// → { success: true } whether or not the address already has an account (no enumeration).
+showMessage('Check your email to finish creating your account.');
+```
+
+- **The link lands on the reset route you already serve**: `/reset-password?token=…` (a trade
+  account: `/b2b/login/reset?token=…`), finished with `resetPassword(token, password)`, which sets
+  the password, verifies the account and starts the session. A magic-link sign-in on the address
+  finishes it too. Nothing new to build.
+- **A password sent to `register` is checked, then ignored.** It still answers
+  `PASSWORD_VALIDATION_ERROR` for one that breaks the length rule, so a form that keeps the field
+  behaves as before, but nothing stores it: drop the field and ask for the password on the reset
+  page.
+- **A lost email recovers on its own**: registering again, "forgot password" and a sign-in attempt
+  each send the link again (rate-limited like a reset).
+- **`NATIVE_AUTH_STRATEGY_ERROR`** from `register` means the store has no storefront address to
+  link the email to; its `message` says so. Nothing was created.
+- The store sends its welcome email once the account is finished, not at registration.
 
 ## Passwordless (Magic Link) Login
 
@@ -180,9 +321,14 @@ with password login (`login`) — both are available. For unknown emails the ser
 creates a verified account on first sign-in (when the channel enables signup).
 
 ```typescript
-// 1. Request — always resolves (anti-enumeration). Show "check your inbox" regardless.
+// 1. Request — resolves whether or not the account exists (anti-enumeration).
+//    Show "check your inbox" regardless. Throws only on a rate limit or a real error.
 await client.commerce.requestMagicLink(email);
 
+// A B2B portal says where the shopper started, so the link opens the B2B page:
+await client.commerce.requestMagicLink(email, { portal: 'B2B' }); // → /b2b/login/magic
+// 'CONSUMER' → /sign-in/magic. Omitted: derived from the account (a B2B customer gets the B2B path).
+
 // 2a. Consume the LINK (token from the emailed URL's ?token= param)
 const user = await client.commerce.loginWithMagicLink(token);
 
@@ -191,8 +337,78 @@ const user = await client.commerce.loginWithMagicCode(email, code);
 // Either path starts a session and fires onAuthToken — no extra token handling needed.
 ```
 
+`portal` picks the landing page only and grants nothing: B2B portal access is still checked when
+the link or code is consumed.
+
 Errors thrown (via `MutationError.errorCode`): `MAGIC_LINK_INVALID_ERROR`,
-`MAGIC_LINK_EXPIRED_ERROR`, `MAGIC_LINK_LOCKED_ERROR` (too many wrong codes).
+`MAGIC_LINK_EXPIRED_ERROR`, `MAGIC_LINK_LOCKED_ERROR` (too many wrong codes), and, from
+`requestMagicLink`, `MAGIC_LINK_RATE_LIMITED_ERROR` with the wait on `error.retryAfterSeconds`.
+
+### Sign-in rate limits
+
+Two limiters can refuse a sign-in call. Both put the wait in `error.retryAfterSeconds`, and neither
+says whether the account exists, so the message is safe to show.
+
+| Limiter | Calls | Thrown as |
+|---|---|---|
+| The store's magic-link limiter (per email, per address) | `requestMagicLink` | `MutationError`, `errorCode: 'MAGIC_LINK_RATE_LIMITED_ERROR'` |
+| The platform's credential limiter (by default 5 a minute per email per store, plus a per-address budget) | `login`, `loginWithMagicCode`, `requestMagicLink`, `register`, `requestPasswordReset`, `refreshVerification` | `StorefrontError`, `statusCode: 429`, `code: 'RATE_LIMITED'`, `retryable: true` |
+
+The credential limiter answers with HTTP 429 before the mutation runs, so `login` throws rather
+than resolving to a `LoginResult`. The SDK never retries a mutation, so wait `retryAfterSeconds`
+before letting the shopper try again:
+
+```typescript
+import { StorefrontError } from '@sixtyninecommerce/client';
+
+try {
+  await client.commerce.login(email, password);
+} catch (error) {
+  const rateLimited =
+    error instanceof StorefrontError &&
+    (error.statusCode === 429 || error.errorCode === 'MAGIC_LINK_RATE_LIMITED_ERROR');
+  if (!rateLimited) throw error;
+  showError(`Too many attempts. Try again in ${error.retryAfterSeconds ?? 60} seconds.`);
+}
+```
+
+**Server-side storefronts.** When your server calls the Shop API, every shopper shares your
+server's address, so they all spend one per-address budget. Create the client with the head's
+private storefront token and the shopper's address, and each shopper is metered on their own:
+
+```typescript
+// Per request, on the server only (the client refuses a private token in a browser).
+const client = await createStorefrontClient({
+  storeCode: 'my-store',
+  cdnUrl: 'https://cdn.my-store.com',
+  privateToken: process.env.SIXTYNINE_PRIVATE_TOKEN, // s69p_…, issued with admin.heads.privateTokens.issue
+  buyerIp: shopperIp, // the address YOUR server saw the shopper connect from
+});
+```
+
+### Setting a first password
+
+A customer who signs in by link or code has no password, so `updatePassword(current, next)` cannot
+serve them. `getCurrentCustomer()` returns `hasPassword`; when it is `false`, offer "Set password"
+and call `setPassword`:
+
+```typescript
+const me = await client.commerce.getCurrentCustomer();
+if (me && !me.hasPassword) {
+  await client.commerce.setPassword(newPassword); // the account is emailed a notice
+} else {
+  await client.commerce.updatePassword(currentPassword, newPassword);
+}
+```
+
+`setPassword` works only while the account has no password: afterwards it throws `MutationError`
+`PASSWORD_ALREADY_SET_ERROR`. It also throws `PASSWORD_VALIDATION_ERROR` (the reason is in
+`error.fields.validationErrorMessage`), `NATIVE_AUTH_STRATEGY_ERROR` (password sign-in is not
+available for this account on this store) and `SET_PASSWORD_REQUIRES_EMAIL_SIGN_IN_ERROR` (the
+session did not sign in to this store by email link or code, for example it signed in on another
+store: have the customer sign in with a link or code again, or send them through
+`requestPasswordReset`; `error.message` says so in words a shopper can read). The platform's
+credential limiter meters it like `updatePassword`.
 
 ### Reference UI (storefront)
 
@@ -206,7 +422,17 @@ function MagicLinkRequest() {
 
   async function request(e: React.FormEvent) {
     e.preventDefault();
-    await client.commerce.requestMagicLink(email.trim()); // never reveals existence
+    try {
+      // never reveals existence; a B2B portal passes { portal: 'B2B' }
+      await client.commerce.requestMagicLink(email.trim());
+    } catch (error) {
+      const rateLimited =
+        error instanceof StorefrontError &&
+        (error.statusCode === 429 || error.errorCode === 'MAGIC_LINK_RATE_LIMITED_ERROR');
+      if (!rateLimited) throw error;
+      /* show "too many requests — try again in {error.retryAfterSeconds}s" */
+      return;
+    }
     setStatus('sent'); // always advance — even if no account exists
   }
 
@@ -352,6 +578,94 @@ Two language modes are transparent to the storefront — the resolver picks the
 
 Visibility is gated server-side: `PUBLIC` (everyone), `AUTHENTICATED` (logged-in only), `CUSTOMER_GROUP` (allowlist of customer groups). Anonymous visitors only ever see PUBLIC docs.
 
+## Invoices and credit notes (customer account)
+
+A signed-in customer reads the invoices and retail credit notes of their OWN orders, by order code
+(a credit account's accounts-receivable credit notes are not listed yet).
+Anything else — another customer's order, a guest checkout's, another store's — is refused
+`FORBIDDEN`, indistinguishable from an order that does not exist.
+
+```typescript
+const invoices = await client.commerce.getMyOrderInvoices(order.code);
+const creditNotes = await client.commerce.getMyOrderCreditNotes(order.code);
+// creditNotes[n]: { id, creditNoteNumber, issuedOn, totalWithTax, currencyCode,
+//                   kind, reason, invoiceNumber, createdAt }
+
+// Mint on the Download click, never earlier and never cached — e.g. a route handler
+// behind the button:
+const { url } = await client.commerce.getMyCreditNoteDownloadUrl(creditNoteId);
+return Response.redirect(url, 303);
+```
+
+| Field | Notes |
+|---|---|
+| `totalWithTax` | The credited amount, positive minor units; the PDF prints it negative |
+| `kind` | `adjustment` (an over-charge, goods kept), `return` (a settled return), `cancellation` (the whole invoice, nothing replaces it), `correction` (the whole invoice, a corrected one replaces it) |
+| `invoiceNumber` | The invoice the note credits. On a `cancellation` or `correction` that invoice is void and `getMyOrderInvoices` no longer lists it |
+| `issuedOn` | ISO-8601 date |
+
+Documents are stored privately: there is no permanent URL. `getMyInvoiceDownloadUrl` and
+`getMyCreditNoteDownloadUrl` mint a signed link that works for five minutes (`expiresAt`) and
+is a bearer link for that time, so hand it to the browser at once. A credit note whose PDF is not
+stored yet answers `DOCUMENT_PDF_NOT_AVAILABLE` until the store draws it again: show the shopper
+that the document is not available yet rather than an error.
+
+## Receipt account claim (in-store purchases)
+
+A store that sells at its tills can let shoppers add an anonymous in-store purchase to their
+account from the receipt. When the store has switched it on, the receipt's page links to
+`<storefront>/account/claim-receipt#<token>`. Build that page: read the token from the URL
+FRAGMENT (which never reaches a server, a referrer or an analytics hit), have the shopper sign in,
+then send it once.
+
+```typescript
+import { receiptClaimTokenFrom } from '@sixtyninecommerce/client';
+
+const token = receiptClaimTokenFrom(window.location); // null when the link carries none
+if (token) {
+  const { orderCode, alreadyYours } = await client.commerce.claimReceipt(token);
+  // orderCode: the purchase, now in activeCustomer.orders; alreadyYours: nothing changed
+}
+```
+
+Only a completed till sale made at most 30 days ago on no named customer can be claimed, from a
+live receipt link (never a gift receipt's). Every refusal answers `POS_RECEIPT_CLAIM_NOT_FOUND`
+with one message, whatever the reason, so the page says one thing ("this receipt cannot be added
+to an account"); a guest is `FORBIDDEN`. Treat the token as a password for the receipt: never log
+it or send it anywhere but `claimReceipt`.
+
+## Metafields (custom data from apps and the store)
+
+Apps and the store can attach custom fields to products, variants and collections. The ones
+declared `storefront: read` come back WITH the entity when you ask for them, in the same request:
+
+```typescript
+const product = await client.commerce.getProduct('blue-shirt', { metafields: true });
+product.metafields; // [{ namespace: 'acme-badges', key: 'badge', value: 'eco' }]
+product.variants[0].metafields; // each variant's own
+
+// One app's fields only (its slug is the namespace):
+await client.commerce.getProduct('blue-shirt', { metafields: { namespace: 'acme-badges' } });
+await client.commerce.getCollection('summer', { metafields: true }); // collection.metafields
+```
+
+Also on `getProductById`, `getCollectionById`. Without the option the reads are unchanged and
+carry no `metafields`. Fields marked `hidden`, and fields of an app that was uninstalled, never
+reach the storefront, and a store sees only its own values on a product it shares with another.
+`value` is whatever the field's type describes (a string, a number, money in minor units, …).
+
+The option needs an engine that serves `metafields` on these entities; against an older engine
+only a read that asks for them fails (a GraphQL validation error), and every other read keeps
+working.
+
+**Caching:** a metafield read is tagged like the plain read (`product:<id>`, `collection:<id>`,
+`catalog`), but no platform event reports a metafield change on a product, variant or collection
+yet. That includes a value an app writes, a field turned `hidden`, and an uninstalled app's
+fields being withdrawn. So the event revalidation handler below never refreshes `metafields`
+alone. A page cached by tag keeps the old values until the product itself changes or the cache
+expires, while the engine already answers the new ones. Give metafield-bearing pages a time-based
+revalidation if their custom fields must follow quickly.
+
 ## Next.js revalidation (platform events)
 
 Create an event subscription (Dashboard → Settings → Event Subscriptions) pointing at
@@ -377,8 +691,12 @@ pass a wrapper such as `(tag) => revalidateTag(tag, 'max')`.
 
 **Cache tags.** Product and collection reads carry `next: { tags }`, and the handler purges the
 same tags: `product:<id>` on `getProductById` / `getProductProperties`, `collection:<id>` on
-`getCollectionById`, `getProductsInCollectionById` and `searchProducts({ collectionId })`. Load
-pages by the id the routes manifest resolves:
+`getCollectionById`, `getProductsInCollectionById` and `searchProducts({ collectionId })`, and
+`catalog` on EVERY catalogue read (products, collections, search, facets, properties,
+recommendations) — the tag
+the facet and price-list events purge, since neither names the products it moves. `getMenu(id)`
+carries `menu:<id>`, which `menu.changed` purges. Load pages by the id the routes manifest
+resolves:
 
 ```typescript
 const route = await client.navigation.findRoute(path, locale);
@@ -393,17 +711,228 @@ if (route?.type === 'collection') {
 
 `findRoute` also returns `route.cacheTags` for any other read on the page (and
 `cacheTagsForRoute(entry)` covers `getRoutes()` entries). Raw slug reads (`getProduct(slug)`,
-`getCollection(slug)`, `getProductsInCollection(slug)`) stay untagged — pass
+`getCollection(slug)`, `getProductsInCollection(slug)`) carry only `catalog`, no id tag — pass
 `{ cacheTags: route.cacheTags }` if you must use one.
 
+What each event revalidates is `planRevalidation`'s mapping: `product.*` (including
+`channel_assigned`/`channel_removed`) and `product_variant.*` → `product:<id>`; `collection.membership_changed` → `collection:<id>`; `facet.*` and
+`price_list.changed` → `catalog`; `menu.changed` → `menu:<id>`; `head.changed` → `seo-artifact`
+and a fresh URL context; `channel.renamed` → a fresh URL context only; `promotion.changed` and
+`asset.changed` → nothing (promotions price orders, not catalogue reads; an asset edit also sends
+`content.site_content_changed`, which revalidates the whole site); content, collection-tree,
+URL-setting and SEO-path events → paths or the whole site. A plan with `invalidateUrlContext`
+(URL settings, head and rename events) tells a pull-feed consumer to re-read its URL context. Any other type is answered 200
+`skipped`.
+
+**Several stores on one route.** Each store's subscription has its own signing secret: pass a
+function from the store code to it, and the store router as `urls`. Each event is then planned for
+its own store (the envelope's `channel_code`): paths are composed on that store's address and
+handed to `toRoutePath(url, locale, store)` — map them onto your routes (e.g. a host rewritten to
+`/[store]/…`) — and every tag is purged store-scoped, which is what the router's reads carry beside
+the bare tags. A whole-site plan still revalidates the whole app.
+
+```typescript
+export const POST = createEventRevalidateHandler({
+  secret: (storeCode) => secrets[storeCode], // undefined → 500 (unset, retried), like a missing secret
+  urls: stores,                              // the store router
+  toRoutePath: (url, _locale, store) => `/${store}${url.pathname}`,
+  revalidatePath,
+  revalidateTag,
+});
+```
+
+A pull-feed consumer asks `planRevalidation(envelope, urls, { storeScoped: true })` for the same
+store-scoped tags. Only for a router's reads: a single-store client's reads carry bare tags alone.
+
 Opt out with `createStorefrontClient({ cacheTags: false })`, or pass a resolver
 `(tags, { operation }) => tags` to rewrite them. The SDK never sets a cache policy.
 
-`verifyEventDelivery`, `planRevalidation` and the payload types are exported from
-`@sixtyninecommerce/client/events` for pull-feed consumers and custom handlers.
+`verifyEventDelivery`, `planRevalidation` and the payload type of EVERY platform event are exported
+from `@sixtyninecommerce/client/events` for pull-feed consumers and custom handlers, with
+`createEventHandler` — a verified, typed webhook endpoint for any event, beyond revalidation:
+
+```typescript
+import { createEventHandler } from '@sixtyninecommerce/client/events';
+
+export const POST = createEventHandler({
+  secret: process.env.EVENTS_SECRET!,
+  on: {
+    'menu.changed': async (event) => { /* event.data is MenuChangedV1 */ },
+  },
+});
+```
+
+There is no `poll` or `stream` here: the pull feed and the live stream need an API token holding
+`ReadPlatformEvents`, which a storefront must not hold — a server-side job that has one uses
+`@sixtyninecommerce/admin`.
 `createRevalidateHandler` (the legacy `/api/revalidate` SEO webhook) is deprecated and unchanged,
 and receives nothing: the platform has retired its sender.
 
+## Conditional reads (ETag)
+
+Public CMS and plugins reads — menus, content strings, collections, the routes and capability
+manifests — are remembered and revalidated: the next read of the same thing sends `If-None-Match`,
+and an unchanged answer comes back as a bodyless 304 that the SDK answers from memory. **On by
+default, except on Next.js's patched `fetch`** (below). The server is still asked every time, so
+nothing is ever served stale; what you save is the payload.
+
+```typescript
+createStorefrontClient({ storeCode, cdnUrl });                                        // on (off on Next's fetch): 500 reads / 5 MB per process
+createStorefrontClient({ storeCode, cdnUrl, conditionalReads: true });                // on, Next included
+createStorefrontClient({ storeCode, cdnUrl, conditionalReads: { maxEntries: 100 } }); // a cache of this client's own
+createStorefrontClient({ storeCode, cdnUrl, conditionalReads: false });               // off
+```
+
+- **Never signed in.** Shop API calls (cart, checkout, account, every price) are never cached, and
+  the CMS/plugins reads never carry the shopper's session — they are the same request for a
+  signed-in shopper as for a guest.
+- **Never across stores, languages or tokens.** The cache key is everything the request sends: the
+  store, the language, the private storefront token, the query.
+- **Process-wide.** Every client on the same `fetch` shares one cache, so a client built per request
+  still benefits. Identical reads in flight at the same moment share one request, and each caller
+  gets its own copy of the answer. Errors are never stored.
+- **Next.js: off by default.** On Next's patched `fetch` (it carries `__nextPatched`) the default
+  is `false`. The SDK cache sits above that `fetch`, and Next's data cache lives inside it: Next keys
+  a cached fetch on its request headers and stores only 200s, so an added `If-None-Match` would turn
+  Next's zero-request cache hits into 304 round trips. An app that does not cache its fetches with
+  Next (no `cache: 'force-cache'`, segment `revalidate` or `fetchCache`) can pass
+  `conditionalReads: true`. A wrapper around Next's `fetch` hides the marker: pass `false` then.
+
+## Product Feeds
+
+The platform renders one RSS 2.0 product feed per configured destination (Google Shopping, Meta, Pinterest, TikTok) and serves it at a token-guarded public URL. `client.feeds.feedUrl(token)` builds that URL — the token is the feed's shared secret (Dashboard → Marketing → Product feeds), so treat the URL as unlisted.
+
+```typescript
+client.feeds.feedUrl('9f3c…'); // https://plugins.example.com/feeds/megamart/9f3c….xml
+```
+
+You can hand that platform URL to a merchant centre directly. To serve the feed from the storefront's **own** origin instead, proxy it with `createProductFeedHandler` — the same fetch-and-serve shape as `createSeoArtifactHandler`, so it works on any hosting adapter (unlike `next.config` rewrites):
+
+```typescript
+// src/app/product-feed.xml/route.ts — one fixed feed
+import { createProductFeedHandler } from '@sixtyninecommerce/client/next';
+
+export const GET = createProductFeedHandler(getClient(), {
+  token: process.env.GOOGLE_FEED_TOKEN, // server-only
+});
+
+// src/app/feeds/[token]/route.ts — several feeds off one route
+export const GET = createProductFeedHandler(getClient());
+```
+
+| Behavior | Notes |
+|---|---|
+| Caching | `public, max-age=300, s-maxage=1800, stale-while-revalidate=86400` by default — override with `cacheControl` |
+| `ETag` / `If-None-Match` | Forwarded upstream and passed back, so an unchanged feed answers `304` |
+| Body | Buffered before the `200` goes out, so a timeout mid-transfer is a clean `503`, never a truncated feed a CDN would cache |
+| User-Agent | The inbound crawler UA is **not** forwarded; the platform must see your server |
+| `X-Robots-Tag` | Dropped from the upstream response |
+| Failures | Upstream `404` → `404`; anything else (or a timeout, default 30s) → `503` with `Retry-After: 60` |
+
+## SEO artifacts, feeds and redirects on any framework (`/web`)
+
+`@sixtyninecommerce/client/web` serves the platform-rendered sitemap, robots.txt, llms.txt,
+IndexNow key and product feeds on the storefront's own origin, and applies the store's redirects,
+from any server that speaks the Fetch API — `(request: Request) => Promise<Response>`, no framework
+imports. The `/next` handlers are these same responders plus Next's cache tag, so the statuses,
+headers and bodies are identical. Each takes a store router in place of a client too
+([several stores in one process](#several-stores-in-one-process)):
+
+| Behavior | Notes |
+|---|---|
+| `ETag` / `If-None-Match` | Forwarded upstream and passed back; an unchanged file answers `304` with its `ETag` |
+| Caching | The storefront's `Cache-Control` (`cacheControl` option); the platform's is replaced |
+| `X-Robots-Tag` | Dropped from the upstream response |
+| User-Agent | The inbound crawler UA is **not** forwarded; the platform must see your server |
+| Credentials | None sent upstream — the files are public; a private storefront token never leaves the server |
+| Child sitemaps | A name the platform could never serve (`<kind>-<n>.xml`) is a `404`, without a request |
+| Failures | Upstream `404` → `404`; anything else (or the timeout: 15s, feeds 30s) → `503` + `Retry-After: 60` |
+| `fetch` | The one you configured the client with (the `/next` handlers use Next's patched global) |
+
+```typescript
+import {
+  createProductFeedResponder,
+  createRedirectMiddleware,
+  createSeoArtifactResponder,
+} from '@sixtyninecommerce/client/web';
+
+const client = getClient(); // a client or a client promise, built on the server
+const sitemap = createSeoArtifactResponder(client, 'sitemap');
+const sitemapChild = createSeoArtifactResponder(client, 'sitemap-child'); // (request, { name })
+const robots = createSeoArtifactResponder(client, 'robots');
+const llmsTxt = createSeoArtifactResponder(client, 'llms-txt');
+const feed = createProductFeedResponder(client, { token: process.env.GOOGLE_FEED_TOKEN }); // server-only
+const redirects = createRedirectMiddleware({ store: (await client).redirects }); // Response | undefined
+```
+
+Plain `node:http`:
+
+```typescript
+import { createServer } from 'node:http';
+
+createServer(async (req, res) => {
+  const request = new Request(new URL(req.url ?? '/', `https://${req.headers.host}`), {
+    headers: req.headers as Record<string, string>,
+  });
+  const { pathname } = new URL(request.url);
+  const response =
+    (await redirects(request)) ??
+    (pathname === '/sitemap.xml' ? await sitemap(request)
+      : pathname.startsWith('/sitemaps/') ? await sitemapChild(request, { name: pathname.slice(10) })
+      : pathname === '/robots.txt' ? await robots(request)
+      : pathname === '/llms.txt' ? await llmsTxt(request)
+      : new Response('Not found', { status: 404 }));
+  res.writeHead(response.status, Object.fromEntries(response.headers));
+  res.end(Buffer.from(await response.arrayBuffer()));
+}).listen(3000);
+```
+
+Remix / React Router (resource routes):
+
+```typescript
+// app/routes/sitemap[.]xml.ts
+export const loader = ({ request }: LoaderFunctionArgs) => sitemap(request);
+// app/routes/sitemaps.$name.ts
+export const loader = ({ request, params }: LoaderFunctionArgs) => sitemapChild(request, params);
+```
+
+Astro (endpoints):
+
+```typescript
+// src/pages/robots.txt.ts
+export const GET: APIRoute = ({ request }) => robots(request);
+// src/pages/sitemaps/[name].ts
+export const GET: APIRoute = ({ request, params }) => sitemapChild(request, params);
+```
+
+SvelteKit (`+server.ts` and the `handle` hook):
+
+```typescript
+// src/routes/llms.txt/+server.ts
+export const GET: RequestHandler = ({ request }) => llmsTxt(request);
+// src/hooks.server.ts
+export const handle: Handle = async ({ event, resolve }) =>
+  (await redirects(event.request)) ?? resolve(event);
+```
+
+Hono / Cloudflare Workers:
+
+```typescript
+app.use(async (c, next) => (await redirects(c.req.raw)) ?? next());
+app.get('/sitemap.xml', (c) => sitemap(c.req.raw));
+app.get('/sitemaps/:name', (c) => sitemapChild(c.req.raw, { name: c.req.param('name') }));
+app.get('/product-feed.xml', (c) => feed(c.req.raw));
+```
+
+To read an artifact yourself, `client.seo.artifacts.fetch(artifact, { childFile?, ifNoneMatch?,
+signal?, timeoutMs? })` answers `{ status: 200, body, contentType, etag }`, `{ status: 304, etag }`,
+`{ status: 404 }` or `{ status: 503, retryAfterSeconds, error? }` — it never throws for an upstream
+problem, and throws `INVALID_ARGUMENT` for an unknown artifact or a bad `childFile`.
+
+There is no data cache in `/web`: your CDN caches per the `Cache-Control` above. When an event
+plan from `planRevalidation` carries the `seo-artifact` tag (`head.changed`, and every plan that
+revalidates anything), purge your CDN's copies of these paths.
+
 ## Tree-Shakeable Imports
 
 ```typescript
@@ -414,6 +943,26 @@ import { formatPrice, getTierForQuantity } from '@sixtyninecommerce/client/prici
 import { PRESETS, getResponsiveImageData } from '@sixtyninecommerce/client/media';
 ```
 
+## Generated types
+
+The catalogue types are generated from the Shop API schema and the SDK's own queries, so they
+describe exactly what each method returns: `ProductVariantFragment`, `ProductSummaryFragment`,
+`CollectionDetailFragment`, `SearchResultFragment`, … A shape the SDK transforms keeps an SDK name
+derived from the generated one (`Product` is `ProductFragment` with `metadata` parsed).
+
+```typescript
+import type { Product, ProductVariantFragment } from '@sixtyninecommerce/client';
+
+// Every generated type — operations, fragments, the schema's enums and inputs — type-only:
+import type { CurrencyCode, GetProductQuery } from '@sixtyninecommerce/client/types';
+```
+
+`getProducts` types its rows from the options: `ProductSummaryFragment` by default,
+`ProductCardFragment` with `{ detail: 'card' }`.
+
+Upgrading from 0.30: the rename table and every changed field are in
+[docs/storefront/generated-types.md](https://github.com/SIXTYNINE-digital/sixtynine-commerce-engine/blob/main/docs/storefront/generated-types.md).
+
 ## Error Handling
 
 Every error this SDK throws is a `StorefrontError`, and every `StorefrontError` is a
@@ -439,7 +988,16 @@ try {
     // error.code / error.status — the platform code and HTTP status
     // error.statusCode          — the same status, `undefined` when there was none
     // error.details             — [{ field?, code, message }]
-    // error.retryAfterSeconds   — set on a 429
+    // error.retryable           — true for a 429 and a 502/503/504 (an outage:
+    //                             code SERVICE_UNAVAILABLE when the engine's
+    //                             database is down); false for a 500 fault
+    // error.outcomeUnknown      — true when the write may or may not have
+    //                             landed (never retryable): the engine said so,
+    //                             or the mutation timed out / was aborted by your
+    //                             signal after it was sent / lost its connection
+    //                             / got a 5xx nobody coded. Re-read the cart or
+    //                             order before trying again. Never set on a query.
+    // error.retryAfterSeconds   — the wait hint, on a 429 or a 503
     // error.traceId             — W3C trace id, on failures the service ANSWERED
     //                             (not on a timeout, abort or network failure)
     // error.problem             — the RFC 9457 body, when the service sent one
@@ -456,3 +1014,5 @@ try {
 ## Subscription purchases and management
 
 Use `previewSubscriptionPurchase` before `startSubscriptionPurchase`, then poll `getSubscriptionPurchaseStatus` after provider-hosted checkout. Customer lifecycle changes also have a preview: `previewMySubscriptionChange` followed by `manageMySubscription` with the same persisted request key. See the [subscription integration guide](../../docs/integrations/subscriptions.md) for payment recovery, trials, cancellation commitments, allowed actions, and compatibility.
+
+Every refusal the subscriptions plugin makes is a `StorefrontError` with a `SUBSCRIPTION_*` `code` (each method's TSDoc lists its codes; the guide has what to do about each) and the engine's sentence. Branch on `code`, never on the sentence. A method that needs a signed-in shopper answers a signed-out session with the platform's `FORBIDDEN` before the plugin runs; `SUBSCRIPTION_GUEST_NOT_ALLOWED` means signed in but with no customer in this store. An engine before these codes answered all of them as `USER_INPUT_ERROR` (400) with the same sentence.