@usethrottle/catalog 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @usethrottle/catalog
 
+## 1.4.0
+
+### Minor Changes
+
+- c9636d7: Dynamic storefront. Everything is additive except the cache defaults below.
+
+  - `client.settings()` returns the store's theme, navigation, home page, strings and route patterns with `settingsVersion` and `generation`. `t(settings, key, vars)`, `resolveMenuTarget(settings, target)`, `DEFAULT_STRINGS` and `fontStylesheetHref` read them.
+  - `client.pages.list()` and `client.pages.get(handle)` read the store's content pages.
+  - `createServerCatalogClient({ cachePolicy })` sets how long each kind of read is cached (`'until-changed'`, `'no-store'` or a duration such as `'90s'`), with `DEFAULT_CACHE_POLICY`, `cacheKindForPath` and `policyToNext` exported from `/server`. Every read is tagged by family (`throttle-catalog:config`, `:pages`, `:data`) as well as by route and handle, and `scopesToTags(scopes)` turns the scopes of a change notice into the tags to clear.
+  - New entry `@usethrottle/catalog/next` for the Next.js App Router (`next` 14 or later, an optional peer): `createRevalidateHandler` verifies the signed `storefront.changed` webhook and revalidates the matching tags; the helpers `previewMiddleware` and `getPreviewToken` carry a dashboard preview token in an HTTP-only cookie; `noteMinGeneration` makes the next `/config` read at least that fresh.
+  - `previewToken` client option and a per-call `minGeneration` on settings and pages reads.
+  - React: `useStorefrontSettings` and `useGenerationWatch` (`/react`), `usePages` and `usePage` (`/react/extras`).
+
+  Behaviour changes: the default `revalidate` of `/config`, settings, pages and product reads is now 3600 seconds (it was 60), cleared sooner by tag revalidation; lists, filters, related products, reviews and search keep 60 seconds. Set `cachePolicy` to restore the old numbers. `x-storefront-preview` is a reserved header: the SDK sets it from `previewToken`.
+
+## 1.3.0
+
+### Minor Changes
+
+- e159fc9: Multi-currency slice 2. Everything is additive: without the new calls the SDK behaves as 1.2.0.
+
+  - Money helpers from `@usethrottle/money` (a new dependency, `^1.0.0`): the `money` namespace and, by name, `formatMoney`, `currencySymbol`, `toDecimalString`, `toMinor`, `parseMoney`, `minorUnitsOf`, `isKnownCurrency`, `moneyValue`, `CURRENCIES`, `UnknownCurrencyError` and the `CurrencyCode` and `MoneyValue` types. Prices are integers in the minor units of their currency; format them with `formatMoney`.
+  - `CurrencyCode` typing on every price object's `currency` (product, variant, price list and cart line), `CartView.currency` and `OpenCartRef.currency`. `CartOptions.currency` stays `string`.
+  - `useCart().format(minor)` formats an amount in the cart's currency.
+  - `useCart().switchCurrency(next)` finds or creates the shopper's cart in `next` and moves the current cart's lines into it through Throttle's absorb route. Signed in, it finds the customer's open cart in that currency; as a guest, it reads the optional `CartStorage` per-currency slots (`getFor`, `setFor`, `removeFor`, implemented by `createMemoryCartStorage`). With no target it creates an empty cart in `next`. Removed lines and a dropped discount are reported through the hook's `warnings`. Any failure keeps the old cart, its stored id and its currency.
+  - The catalog Worker now accepts an empty cart create (`items: []`), which the switch needs. Older clients are unaffected.
+
 ## 1.2.0
 
 ### Minor Changes

package/README.md

@@ -32,18 +32,19 @@ for (const product of products) {
 }
 ```
 
-Prices are integers in minor units (cents for USD). The client talks to `https://catalog.usethrottle.dev` by default (`baseUrl` changes it). Every call takes `{ signal, timeoutMs }`; the default timeout is 10 seconds.
+Prices are integers in the minor units of their currency; format them with `formatMoney` (`formatMoney(product.priceRange.minMinor, product.priceRange.currency)` gives `$19.99` for USD and `¥1,999` for JPY, the same on the server and in the browser). The root re-exports `@usethrottle/money` as `money` and by name (`formatMoney`, `currencySymbol`, `minorUnitsOf`, `toDecimalString`, `toMinor`, `parseMoney`, `moneyValue`, `CURRENCIES`, `isKnownCurrency`, `UnknownCurrencyError`, and the types `CurrencyCode` and `MoneyValue`); every `currency` the SDK answers is a `CurrencyCode`, which is still assignable to `string`. The client talks to `https://catalog.usethrottle.dev` by default (`baseUrl` changes it). Every call takes `{ signal, timeoutMs }`; the default timeout is 10 seconds.
 
 ## Entries
 
-| Import                              | What it holds                                                                                                                                                                                                                                                                           |
-| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@usethrottle/catalog`              | `createCatalogClient`, the error classes and `isCatalogError`, and the answer types. No DOM and no Node-only API.                                                                                                                                                                       |
-| `@usethrottle/catalog/react`        | `CatalogProvider`, the read hooks, `useCart`, `useSubmitReview` and `useCustomerKey` (marked `"use client"`).                                                                                                                                                                           |
-| `@usethrottle/catalog/react/extras` | `useTags`, `useCollections` and `useReviewEligibility` (marked `"use client"`). They share `CatalogProvider` and the cache with `/react`: import the provider from `/react` and these three from here.                                                                                  |
-| `@usethrottle/catalog/server`       | `createServerCatalogClient`, `catalogTags`, `syncCatalogGeneration` and the paging helpers (`listAllProductHandles`, `staticProductParams`, `listAllCollectionHandles`, `listAllCategoryHandles`: it asks for `CATEGORY_TREE_MAX_DEPTH` levels, 10, so a sitemap lists the whole tree). |
-| `@usethrottle/catalog/url`          | `parseShopQuery`, `serializeShopQuery`, `toProductsQuery`, `parseRange` and `formatRange`. Standalone: none of the client or React code (the ESM and CommonJS builds each load one tiny shared helper file).                                                                            |
-| `@usethrottle/catalog/admin`        | **Experimental, server only.** `createCatalogAdmin` and `verifyCatalogWebhook` for the catalog push API (sync jobs, single batches, runs, products, stock), and the push request and answer types. See [Admin](#admin-server-only-experimental).                                        |
+| Import                              | What it holds                                                                                                                                                                                                                                                                                     |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@usethrottle/catalog`              | `createCatalogClient`, the error classes and `isCatalogError`, the answer types, and the `@usethrottle/money` helpers (`money`, `formatMoney`, …). No DOM and no Node-only API.                                                                                                                   |
+| `@usethrottle/catalog/react`        | `CatalogProvider`, the read hooks, `useCart`, `useSubmitReview` and `useCustomerKey` (marked `"use client"`).                                                                                                                                                                                     |
+| `@usethrottle/catalog/react/extras` | `useTags`, `useCollections` and `useReviewEligibility` (marked `"use client"`). They share `CatalogProvider` and the cache with `/react`: import the provider from `/react` and these three from here.                                                                                            |
+| `@usethrottle/catalog/server`       | `createServerCatalogClient`, `catalogTags`, `syncCatalogGeneration` and the paging helpers (`listAllProductHandles`, `staticProductParams`, `listAllCollectionHandles`, `listAllCategoryHandles`: it asks for `CATEGORY_TREE_MAX_DEPTH` levels, 10, so a sitemap lists the whole tree).           |
+| `@usethrottle/catalog/next`         | **Server only.** `createRevalidateHandler` (the change-notice webhook), `previewMiddleware`, `getPreviewToken` and `noteMinGeneration` for the Next.js App Router. `next` (14 or later) is an optional peer. See [Revalidation webhook](#revalidation-webhook) and [Preview mode](#preview-mode). |
+| `@usethrottle/catalog/url`          | `parseShopQuery`, `serializeShopQuery`, `toProductsQuery`, `parseRange` and `formatRange`. Standalone: none of the client or React code (the ESM and CommonJS builds each load one tiny shared helper file).                                                                                      |
+| `@usethrottle/catalog/admin`        | **Experimental, server only.** `createCatalogAdmin` and `verifyCatalogWebhook` for the catalog push API (sync jobs, single batches, runs, products, stock), and the push request and answer types. See [Admin](#admin-server-only-experimental).                                                  |
 
 Everything `/react` exports is a client reference in a server component, `SDK_VERSION` and `catalogQueryKey` included: in server code import `SDK_VERSION` from the root or `/server`, and call `catalogQueryKey` only in client code.
 
@@ -105,7 +106,7 @@ try {
 
 ## Carts and checkout
 
-Carts are resolved by the catalog: the browser sends SKUs and quantities, never prices. `carts.create` answers Throttle's hosted cart URL (`cartUrl`) and a session id. It takes three optional URLs, each an absolute `https` URL on the store's Checkout settings › Allowed return websites (otherwise `422 RETURN_URL_NOT_ALLOWED`, one issue per refused field):
+Carts are resolved by the catalog: the browser sends SKUs and quantities, never prices. `carts.create` answers Throttle's hosted cart URL (`cartUrl`) and a session id; `items` may be empty, for an empty cart in a currency. It takes three optional URLs, each an absolute `https` URL on the store's Checkout settings › Allowed return websites (otherwise `422 RETURN_URL_NOT_ALLOWED`, one issue per refused field):
 
 ```ts
 const cart = await catalog.carts.create({
@@ -117,7 +118,7 @@ const cart = await catalog.carts.create({
 // cart.returnUrlApplied is false when Throttle did not store them.
 ```
 
-Without them the shopper ends on Throttle's own completion page. To build your own cart page instead, use `catalog.carts.session(cart.sessionId)` (`get`, `add`, `update`, `remove`, `refresh`, `checkout({ returnUrl, cancelUrl })`). `checkout()` answers the checkout URL; it never navigates. Both are checked before any request: `carts.create` refuses a URL that is not absolute `https` (`INVALID_REQUEST`, naming the field), and `checkout()` one that is not absolute `http` or `https`.
+Without them the shopper ends on Throttle's own completion page. To build your own cart page instead, use `catalog.carts.session(cart.sessionId)` (`get`, `add`, `update`, `remove`, `refresh`, `checkout({ returnUrl, cancelUrl })`, and `absorb(fromSessionId)`, which moves another session's cart into this one in this cart's currency, answering `{ cart, warnings }`; `useCart().switchCurrency` is built on it). `checkout()` answers the checkout URL; it never navigates. Both are checked before any request: `carts.create` refuses a URL that is not absolute `https` (`INVALID_REQUEST`, naming the field), and `checkout()` one that is not absolute `http` or `https`.
 
 ## React
 
@@ -191,7 +192,7 @@ function ProductGrid() {
 - **Hooks:** `useProducts`, `useProduct`, `useRelated`, `useFilterValues`, `useCategories`, `useCollection`, `useSuggest` (debounced 200 ms, 2 characters at least), `useReviews` and `useConfig` from `/react`; `useTags`, `useCollections` and `useReviewEligibility` from `/react/extras` (below). Each answers `{ data, dataFor, error, isLoading, isPreviousData, isStale, isValidating, refetch }` and takes `enabled`, `initialData` (for an SSR hand-off), `staleTimeMs` and `keepPreviousData`. With a signed-in customer (`customerKey` set), `initialData` is shown and revalidated at once, since a server render with the server key is anonymous; to avoid the brief list-price paint, render the server side with the customer's token.
 - **The cache** is per provider: answers are shown at once and refetched when older than 60 seconds, and calls for one key share one request. Two providers never share it.
 - **`customerKey`** partitions the cache by customer. Change it in the same update as the token: a change starts an empty cache and every mounted hook refetches, so one customer never sees another's prices. It is required whenever `customerToken` can return a token: `useCart` drops the cart on a sign-out or a customer change only by watching it, so without it one customer's cart stays for the next shopper. Keep one `client` per currency and language (see [One client per currency and language](#one-client-per-currency-and-language)) and pass `customerToken` as a function.
-- **`useCart`** keeps one cart per provider and runs its changes one at a time. It creates the cart on the first `add`, recreates it once if Throttle ended the session, and makes a new cart on `switchCurrency`. A switch lands whole or not at all: if the new cart cannot be made, read back or saved, `switchCurrency` rejects and the old cart, its stored id and the old currency stay. The cart is dropped when the signed-in customer signs out or changes, and kept on sign-in. `checkout()` uses the provider's `cartUrls` unless given URLs, and answers the checkout URL. `cartUrls` go on every cart create, so they must be absolute `https` URLs on the store's Allowed return websites, or every `add` fails; otherwise (on `http://localhost`, say) leave them out and pass the URLs to `checkout(input)`. The default `cartStorage` is memory only; key a persistent one by customer, as above: a new adapter object per customer, never one stable object that reads the current customer when called (a drop removes the outgoing customer's entry through the outgoing object, so such an adapter would delete the incoming customer's cart instead).
+- **`useCart`** keeps one cart per provider and runs its changes one at a time. It creates the cart on the first `add` and recreates it once if Throttle ended the session. `format(minor)` formats an amount in the cart's currency (`useCart().format(4763)` on a EUR cart is `€47.63`). **`switchCurrency(currency)`** keeps one cart per currency: it moves the cart into the shopper's open cart in that currency (a signed-in customer's from `customerCart`; a guest's from `cartStorage.getFor`, used only while that cart is still open), or into a new empty cart when there is none, and Throttle closes the old cart as merged. Lines with no price in the new currency stay behind and a discount code the new currency refuses is dropped; both are reported in `warnings` (`lines_removed`, `discount_dropped`). If anything fails before the move lands (the lookup, the new cart, the move itself, for example `422 currency_not_available_in_production`), `switchCurrency` rejects and the old cart, its stored id and the old currency stay. A signed-in switch needs `customerToken` on the client: the new cart is created as the customer's, and Throttle moves a customer's cart only into that customer's cart (`403 cart_owner_mismatch` otherwise). A `cartStorage` adapter may implement the optional `getFor(currency)`, `setFor(currency, id)` and `removeFor(currency)` (`createMemoryCartStorage` does); without them a guest switch always makes a new cart. These are guest slots: a signed-in switch never writes them, and the provider forgets them on a sign-in, a sign-out or a customer change (through `removeFor`, or `setFor(currency, '')` when the adapter has no `removeFor`), so the next guest never reaches a customer's cart. The cart is dropped when the signed-in customer signs out or changes, and kept on sign-in. `checkout()` uses the provider's `cartUrls` unless given URLs, and answers the checkout URL. `cartUrls` go on every cart create, so they must be absolute `https` URLs on the store's Allowed return websites, or every `add` fails; otherwise (on `http://localhost`, say) leave them out and pass the URLs to `checkout(input)`. The default `cartStorage` is memory only; key a persistent one by customer, as above: a new adapter object per customer, never one stable object that reads the current customer when called (a drop removes the outgoing customer's entry through the outgoing object, so such an adapter would delete the incoming customer's cart instead).
 - **Rate limits:** a catalog `429` pauses every read of the provider until its retry time; each mounted key then refetches once.
 - **`useSubmitReview(handle)`** submits a review with one idempotency key per submission.
 
@@ -229,7 +230,7 @@ function Shell({ customerId, children }) {
 }
 ```
 
-`useCart` looks the cart up once per visit when the slot is empty (or ended), and before it would create a new cart. **It resumes only when a currency is known:** set `currency` on the client (`createCatalogClient({ currency: 'USD' })`) or pass it to the hook, `useCart({ currency: 'USD' })`. With neither, `useCart` makes no lookup and the first `add` creates a cart as before. A found cart in another currency is not adopted. Without `customerCart` nothing changes from 1.1.0. Known limits: a write within 30 seconds of a read that predates another device's merge reopens the emptied cart, and so can a write after a re-read that failed. The lookup runs once per visit, so a currency that becomes known only after mount does not trigger it; the first `add` finds the cart instead. With two `useCart` call sites that pass different currencies, the lookup and the create can use different currencies; pass one currency (or set it on the client). `switchCurrency` while signed in creates a cart in the new currency without a lookup, so a customer with an open cart in that currency on another device can end up with a second one.
+`useCart` looks the cart up once per visit when the slot is empty (or ended), and before it would create a new cart. **It resumes only when a currency is known:** set `currency` on the client (`createCatalogClient({ currency: 'USD' })`) or pass it to the hook, `useCart({ currency: 'USD' })`. With neither, `useCart` makes no lookup and the first `add` creates a cart as before. A found cart in another currency is not adopted. Without `customerCart` nothing changes from 1.1.0. Throttle refuses a write to a cart another device merged (`409 cart_not_open`), so it is never reopened; `useCart` then looks the customer's cart up. `switchCurrency` while signed in looks up the customer's open cart in the new currency and moves the cart into it, so a customer keeps one cart per currency across devices. The lookup runs once per visit, so a currency that becomes known only after mount does not trigger it; the first `add` finds the cart instead. With two `useCart` call sites that pass different currencies, the lookup and the create can use different currencies; pass one currency (or set it on the client).
 
 ### Key transport
 
@@ -312,7 +313,7 @@ function ReviewButton({ handle }: { handle: string }) {
 
 ## Next.js
 
-On the server, use a **server** key and `createServerCatalogClient`. Every catalog read's `fetch` carries `next: { revalidate, tags }` (60 seconds by default); carts, Throttle calls and any request with a customer token are `cache: 'no-store'`. Next.js itself is never imported.
+On the server, use a **server** key and `createServerCatalogClient`. Every catalog read's `fetch` carries `next: { revalidate, tags }` (an hour for settings, pages and products, cleared sooner by tags; 60 seconds for lists, filters, related products, reviews and search: see [Cache policy](#cache-policy)); carts, Throttle calls and any request with a customer token are `cache: 'no-store'`. Next.js itself is never imported.
 
 ```ts
 // lib/catalog.ts
@@ -349,6 +350,101 @@ export async function GET() {
 
 `staticProductParams(catalog)` feeds `generateStaticParams`, and `listAllProductHandles(catalog)` (an async iterable) feeds a sitemap. In the browser, use a browser key and the React provider.
 
+## Storefront settings
+
+The store's theme, navigation, home page, strings and route patterns are edited in the dashboard and read with `client.settings()`. It is `/config` cut to `{ settings, settingsVersion, generation }`.
+
+```ts
+import { t, resolveMenuTarget } from '@usethrottle/catalog';
+import { catalog } from '@/lib/catalog'; // createServerCatalogClient(...)
+
+const { settings } = await catalog.settings();
+t(settings, 'cart.checkout'); // "Checkout", in the locale of the read; falls back to English
+settings.navigation.header.map((item) => ({
+  label: item.label,
+  href: resolveMenuTarget(settings, item.target), // null when it points at nothing
+}));
+```
+
+In React, `useStorefrontSettings()` (from `/react`) returns the same answer, and `useGenerationWatch({ onChange })` polls the generation (every 60 seconds by default, only while the tab is visible) and refreshes the cached reads when it moves. Settings and pages calls take `minGeneration`, the generation a change notice named: a read above what the edge holds is answered fresh.
+
+## Pages
+
+Pages are the store's own content pages (shipping, about, ...). `catalog.pages.list()` returns `{ pages: [{ handle, title, position }] }` and `catalog.pages.get(handle)` returns `{ handle, title, bodyHtml, seo }`. In React, `usePages()` and `usePage(handle)` come from `/react/extras`.
+
+```ts
+const { bodyHtml, seo } = await catalog.pages.get('shipping');
+```
+
+`bodyHtml` is HTML: render it only where you trust the store's editors, or sanitize it first.
+
+## Cache policy
+
+`createServerCatalogClient({ cachePolicy })` sets how long each kind of read is cached. Kinds: `settings`, `navigation`, `pages`, `listings`, `facets`, `product`, `related`, `reviews` and `search`. A policy is `'until-changed'` (an hour's safety TTL, cleared sooner by cache tags), `'no-store'`, or a duration such as `'90s'` or `'5m'`. The defaults are `'until-changed'` for `settings`, `navigation`, `pages` and `product`, and `'60s'` for the rest. Customer-token, cart and preview requests are always `no-store`.
+
+```ts
+export const catalog = createServerCatalogClient({
+  publishableKey: process.env.CATALOG_SERVER_KEY ?? '',
+  cachePolicy: { product: '5m', search: 'no-store' },
+});
+```
+
+Every read carries its tags: `throttle-catalog`, a family tag (`throttle-catalog:config`, `:pages` or `:data`), the route's own and, for one handle, `throttle-catalog:<route>:<handle>`. `scopesToTags(scopes)` turns the scopes of a change notice into the tags to clear.
+
+## Revalidation webhook
+
+Instead of polling, point a catalog webhook at a route handler. The catalog sends `storefront.changed` with the changed scopes; the handler checks the `x-catalog-signature` header, clears the matching tags and makes the next `/config` read fresh. Several secrets can be passed while one is being rotated.
+
+```ts
+// app/api/throttle/revalidate/route.ts
+import { createRevalidateHandler } from '@usethrottle/catalog/next';
+
+export const POST = createRevalidateHandler({
+  secret: process.env.THROTTLE_WEBHOOK_SECRET,
+});
+```
+
+It answers `200 { revalidated: [...tags] }`, `401` for a missing, wrong or older-than-5-minutes signature, `400` for a body that is not a change notice, `413` for a body over 64 KB and `500` when no secret is set. The secret is read on each request, so an unset variable at build time does not fail `next build`. The route expires the tags immediately (`revalidateTag(tag, { expire: 0 })`), so the next request after a change is rendered fresh rather than stale. Each notice also raises a generation floor: the server client's next `/config` read (and so `settings()`) asks for at least that generation until an answer reaches it. The floor applies to every client of the process unless you name it. With one store that needs nothing. On a server with several stores, a handler without `floorKey` raises the floor for every store, so the other stores' reads skip the cache (`no-store`) until it clears: always pass each store's publishable key. With several stores in one app, give each handler the publishable key of its store's server client (or a `floorKey` set on both), so one store's notice never touches another's reads. If the variable is unset, `floorKey: process.env.X` is `undefined` and falls back to the shared floor.
+
+```ts
+export const POST = createRevalidateHandler({
+  secret: process.env.STORE_A_WEBHOOK_SECRET,
+  floorKey: process.env.STORE_A_KEY, // the publishableKey of store A's createServerCatalogClient
+});
+```
+
+Pass `revalidateTag` to use your own function instead of the one from `next/cache`.
+
+## Preview mode
+
+The dashboard's preview opens your storefront with `?throttle_preview=<token>`. The middleware moves the token into an HTTP-only cookie (`SameSite=None; Secure`, one hour, so it works inside the preview iframe) and redirects to the same URL without it. Pass the token to the server client and settings and pages answer the draft, uncached.
+
+```ts
+// middleware.ts
+import { previewMiddleware } from '@usethrottle/catalog/next';
+
+export function middleware(req: Request) {
+  return previewMiddleware(req) ?? undefined;
+}
+```
+
+```ts
+// lib/catalog.ts
+import { createServerCatalogClient } from '@usethrottle/catalog/server';
+import { getPreviewToken } from '@usethrottle/catalog/next';
+
+export async function getCatalog() {
+  return createServerCatalogClient({
+    publishableKey: process.env.CATALOG_SERVER_KEY ?? '',
+    previewToken: await getPreviewToken(),
+  });
+}
+```
+
+Safari may drop `Secure` cookies on `http://localhost`: develop the preview over https, or use Chrome. With `exactOptionalPropertyTypes` on, pass `previewToken` only when there is one (`...(token ? { previewToken: token } : {})`), since `getPreviewToken()` can return `undefined`.
+
+`x-storefront-preview` is a reserved header: the SDK sets it from `previewToken`, and a `headers` option may not.
+
 ## URL helpers
 
 `@usethrottle/catalog/url` keeps a shop page's selection in its URL, with one canonical string per selection and every parameter it does not know kept in order:
@@ -444,7 +540,7 @@ The OpenAPI 3.1 document of the storefront API is at https://catalog.usethrottle
 
 ### One client per currency and language
 
-Hooks take no per-call currency or language: both come from the client. A store with a currency or language switcher keeps one client per `(currency, locale)`, memoised on both, so the client changes only when one of them does. On a currency switch, run `useCart().switchCurrency()` first and swap the client only once it resolves. The switch lands whole or not at all: when it rejects, the cart is still in the old currency, so keep the old client.
+Hooks take no per-call currency or language: both come from the client. A store with a currency or language switcher keeps one client per `(currency, locale)`, memoised on both, so the client changes only when one of them does. On a currency switch, run `useCart().switchCurrency()` first and swap the client only once it resolves. When it rejects, the cart is still in the old currency, so keep the old client; when it resolves, show `cart.warnings` (lines left behind, a dropped discount code).
 
 ```tsx
 'use client';

package/dist/admin.cjs

@@ -10,7 +10,7 @@
 
 
 
-var _chunkB2DYAHNRcjs = require('./chunk-B2DYAHNR.cjs');
+var _chunkJ2GHGQY6cjs = require('./chunk-J2GHGQY6.cjs');
 require('./chunk-ETV4XYOV.cjs');
 
 // src/generated/push-types.ts
@@ -45,7 +45,7 @@ var MAX_IDEMPOTENCY_KEY = 200;
 var HEADER_SAFE = /^[\x21-\x7e]+$/u;
 var MAX_RETRY_AFTER_S = 86400;
 function invalidRequest(message) {
-  return new (0, _chunkB2DYAHNRcjs.CatalogError)({
+  return new (0, _chunkJ2GHGQY6cjs.CatalogError)({
     code: "INVALID_REQUEST",
     message,
     statusCode: 0,
@@ -54,7 +54,7 @@ function invalidRequest(message) {
   });
 }
 function clientError(code, message) {
-  return new (0, _chunkB2DYAHNRcjs.CatalogError)({
+  return new (0, _chunkJ2GHGQY6cjs.CatalogError)({
     code,
     message,
     statusCode: 0,
@@ -126,13 +126,13 @@ function toError(status, headers, text) {
     requestId
   };
   if (status === 429) {
-    return new (0, _chunkB2DYAHNRcjs.RateLimitedError)({
+    return new (0, _chunkJ2GHGQY6cjs.RateLimitedError)({
       ...init,
       retryable: true,
-      retryAfterSeconds: retryAfter !== null && retryAfter >= 1 ? retryAfter : _chunkB2DYAHNRcjs.RATE_LIMIT_DEFAULT_RETRY_S
+      retryAfterSeconds: retryAfter !== null && retryAfter >= 1 ? retryAfter : _chunkJ2GHGQY6cjs.RATE_LIMIT_DEFAULT_RETRY_S
     });
   }
-  return new (0, _chunkB2DYAHNRcjs.CatalogError)(init);
+  return new (0, _chunkJ2GHGQY6cjs.CatalogError)(init);
 }
 function guarded(work, callerSignal, timeoutMs) {
   if (_optionalChain([callerSignal, 'optionalAccess', _8 => _8.aborted])) return Promise.reject(callerSignal.reason);
@@ -151,7 +151,7 @@ function guarded(work, callerSignal, timeoutMs) {
     const timer = setTimeout(() => {
       finish();
       controller.abort();
-      reject(new (0, _chunkB2DYAHNRcjs.TimeoutError)({ timeoutMs }));
+      reject(new (0, _chunkJ2GHGQY6cjs.TimeoutError)({ timeoutMs }));
     }, timeoutMs);
     _optionalChain([callerSignal, 'optionalAccess', _12 => _12.addEventListener, 'call', _13 => _13("abort", onAbort, { once: true })]);
     work(controller.signal).then(
@@ -194,7 +194,7 @@ function createHttp(key, baseUrl, fetchFn, timeoutMs) {
                 signal
               });
             } catch (cause) {
-              throw new (0, _chunkB2DYAHNRcjs.NetworkError)({ cause });
+              throw new (0, _chunkJ2GHGQY6cjs.NetworkError)({ cause });
             }
             try {
               return {
@@ -203,14 +203,14 @@ function createHttp(key, baseUrl, fetchFn, timeoutMs) {
                 text: await response.text()
               };
             } catch (cause) {
-              throw new (0, _chunkB2DYAHNRcjs.NetworkError)({ cause });
+              throw new (0, _chunkJ2GHGQY6cjs.NetworkError)({ cause });
             }
           },
           spec.signal,
           timeoutMs
         );
       } catch (error) {
-        if (error instanceof _chunkB2DYAHNRcjs.NetworkError && attempt < attempts) continue;
+        if (error instanceof _chunkJ2GHGQY6cjs.NetworkError && attempt < attempts) continue;
         throw error;
       }
     }
@@ -223,7 +223,7 @@ function createHttp(key, baseUrl, fetchFn, timeoutMs) {
         throw toError(answer.status, answer.headers, answer.text);
       const parsed = parseJson(answer.text);
       if (parsed === void 0)
-        throw new (0, _chunkB2DYAHNRcjs.CatalogError)({
+        throw new (0, _chunkJ2GHGQY6cjs.CatalogError)({
           code: "INVALID_RESPONSE",
           message: "The server answered with a body that is not JSON.",
           statusCode: answer.status,
@@ -278,7 +278,7 @@ function refQuery(ref) {
   return [[field, value]];
 }
 function unreadable() {
-  return new (0, _chunkB2DYAHNRcjs.CatalogError)({
+  return new (0, _chunkJ2GHGQY6cjs.CatalogError)({
     code: "INVALID_RESPONSE",
     message: "The server answered with an unexpected shape.",
     statusCode: 200,
@@ -367,7 +367,7 @@ async function pollUntil(read, done, options = {}) {
     const value = await read(options.signal);
     if (done(value)) return value;
     const remaining = deadline - Date.now();
-    if (remaining <= 0) throw new (0, _chunkB2DYAHNRcjs.TimeoutError)({ timeoutMs });
+    if (remaining <= 0) throw new (0, _chunkJ2GHGQY6cjs.TimeoutError)({ timeoutMs });
     await sleep(Math.min(intervalMs, remaining), options.signal);
   }
 }
@@ -452,7 +452,7 @@ function createJobs(http) {
         await handle.send(rows, { idempotencyKey });
         return;
       } catch (error) {
-        if (!(error instanceof _chunkB2DYAHNRcjs.RateLimitedError) || retry >= QUEUE_RETRIES)
+        if (!(error instanceof _chunkJ2GHGQY6cjs.RateLimitedError) || retry >= QUEUE_RETRIES)
           throw error;
         await sleep(error.retryAfterSeconds * 1e3, signal);
       }
@@ -589,7 +589,7 @@ function assertServer() {
 function createCatalogAdmin(options) {
   assertServer();
   const key = checkKey(options.key);
-  const baseUrl = (_nullishCoalesce(options.baseUrl, () => ( _chunkB2DYAHNRcjs.DEFAULT_BASE_URL))).replace(/\/+$/u, "");
+  const baseUrl = (_nullishCoalesce(options.baseUrl, () => ( _chunkJ2GHGQY6cjs.DEFAULT_BASE_URL))).replace(/\/+$/u, "");
   if (!/^https?:\/\/[^\s/]+/iu.test(baseUrl))
     throw invalidRequest("baseUrl must be an absolute http or https URL.");
   const http = createHttp(
@@ -678,4 +678,4 @@ async function verifyCatalogWebhook(input) {
 
 
 
-exports.CartLineError = _chunkB2DYAHNRcjs.CartLineError; exports.CatalogError = _chunkB2DYAHNRcjs.CatalogError; exports.CustomerTokenInvalidError = _chunkB2DYAHNRcjs.CustomerTokenInvalidError; exports.FeatureUnavailableError = _chunkB2DYAHNRcjs.FeatureUnavailableError; exports.NetworkError = _chunkB2DYAHNRcjs.NetworkError; exports.OriginNotAllowedError = _chunkB2DYAHNRcjs.OriginNotAllowedError; exports.RateLimitedError = _chunkB2DYAHNRcjs.RateLimitedError; exports.TimeoutError = _chunkB2DYAHNRcjs.TimeoutError; exports.createCatalogAdmin = createCatalogAdmin; exports.isCatalogError = _chunkB2DYAHNRcjs.isCatalogError; exports.verifyCatalogWebhook = verifyCatalogWebhook;
+exports.CartLineError = _chunkJ2GHGQY6cjs.CartLineError; exports.CatalogError = _chunkJ2GHGQY6cjs.CatalogError; exports.CustomerTokenInvalidError = _chunkJ2GHGQY6cjs.CustomerTokenInvalidError; exports.FeatureUnavailableError = _chunkJ2GHGQY6cjs.FeatureUnavailableError; exports.NetworkError = _chunkJ2GHGQY6cjs.NetworkError; exports.OriginNotAllowedError = _chunkJ2GHGQY6cjs.OriginNotAllowedError; exports.RateLimitedError = _chunkJ2GHGQY6cjs.RateLimitedError; exports.TimeoutError = _chunkJ2GHGQY6cjs.TimeoutError; exports.createCatalogAdmin = createCatalogAdmin; exports.isCatalogError = _chunkJ2GHGQY6cjs.isCatalogError; exports.verifyCatalogWebhook = verifyCatalogWebhook;

package/dist/admin.d.cts

@@ -1,5 +1,6 @@
-export { C as CartLineError, a as CartLineProblem, b as CatalogError, c as CatalogErrorCode, d as CatalogErrorInit, e as CatalogErrorIssue, f as CatalogErrorSource, g as ClientErrorCode, h as CustomerTokenInvalidError, F as FeatureUnavailableError, N as NetworkError, O as OriginNotAllowedError, R as RateLimitedError, T as TimeoutError, i as isCatalogError } from './catalog-error-yTBMAdCv.cjs';
-import './contract-types-BPSzY_Co.cjs';
+export { C as CartLineError, a as CartLineProblem, b as CatalogError, c as CatalogErrorCode, d as CatalogErrorInit, e as CatalogErrorIssue, f as CatalogErrorSource, g as ClientErrorCode, h as CustomerTokenInvalidError, F as FeatureUnavailableError, N as NetworkError, O as OriginNotAllowedError, R as RateLimitedError, T as TimeoutError, i as isCatalogError } from './catalog-error-BKN5hNWP.cjs';
+import './contract-types-D2-SSPM9.cjs';
+import '@usethrottle/money';
 
 type JobBatchAnswer = {
     batchId: string;
@@ -84,6 +85,16 @@ type PushJob = {
     updated?: number | undefined;
     unchanged?: number | undefined;
     reportExpiresAt?: string | null | undefined;
+    failureMessage?: string | null | undefined;
+    progressUpdatedAt?: string | undefined;
+    attempts?: number | undefined;
+    lastAttempt?: {
+        attempt: number;
+        at: string;
+        result: 'success' | 'retryable_failure' | 'terminal_failure';
+        code: string;
+    } | null | undefined;
+    nextAttemptAt?: string | null | undefined;
     batches?: {
         batchId: string;
         sequence: number;
@@ -138,6 +149,8 @@ type PushProduct = {
     held: boolean;
     apiArchived: boolean;
     purgeAfter: string | null;
+    createdAt: string;
+    updatedAt: string;
     vendorId: string | null;
     attributes: {
         [key: string]: JsonValue;

package/dist/admin.d.ts

@@ -1,5 +1,6 @@
-export { C as CartLineError, a as CartLineProblem, b as CatalogError, c as CatalogErrorCode, d as CatalogErrorInit, e as CatalogErrorIssue, f as CatalogErrorSource, g as ClientErrorCode, h as CustomerTokenInvalidError, F as FeatureUnavailableError, N as NetworkError, O as OriginNotAllowedError, R as RateLimitedError, T as TimeoutError, i as isCatalogError } from './catalog-error-7DCsTyB2.js';
-import './contract-types-BPSzY_Co.js';
+export { C as CartLineError, a as CartLineProblem, b as CatalogError, c as CatalogErrorCode, d as CatalogErrorInit, e as CatalogErrorIssue, f as CatalogErrorSource, g as ClientErrorCode, h as CustomerTokenInvalidError, F as FeatureUnavailableError, N as NetworkError, O as OriginNotAllowedError, R as RateLimitedError, T as TimeoutError, i as isCatalogError } from './catalog-error-BnabMMEy.js';
+import './contract-types-D2-SSPM9.js';
+import '@usethrottle/money';
 
 type JobBatchAnswer = {
     batchId: string;
@@ -84,6 +85,16 @@ type PushJob = {
     updated?: number | undefined;
     unchanged?: number | undefined;
     reportExpiresAt?: string | null | undefined;
+    failureMessage?: string | null | undefined;
+    progressUpdatedAt?: string | undefined;
+    attempts?: number | undefined;
+    lastAttempt?: {
+        attempt: number;
+        at: string;
+        result: 'success' | 'retryable_failure' | 'terminal_failure';
+        code: string;
+    } | null | undefined;
+    nextAttemptAt?: string | null | undefined;
     batches?: {
         batchId: string;
         sequence: number;
@@ -138,6 +149,8 @@ type PushProduct = {
     held: boolean;
     apiArchived: boolean;
     purgeAfter: string | null;
+    createdAt: string;
+    updatedAt: string;
     vendorId: string | null;
     attributes: {
         [key: string]: JsonValue;

package/dist/admin.js

@@ -10,7 +10,7 @@ import {
   RateLimitedError,
   TimeoutError,
   isCatalogError
-} from "./chunk-55G4ZTD5.js";
+} from "./chunk-VJHA7J7B.js";
 import "./chunk-PKBMQBKP.js";
 
 // src/generated/push-types.ts

package/dist/{catalog-error-yTBMAdCv.d.cts → catalog-error-BKN5hNWP.d.cts}

@@ -1,4 +1,4 @@
-import { i as CatalogContractErrorCode } from './contract-types-BPSzY_Co.cjs';
+import { k as CatalogContractErrorCode } from './contract-types-D2-SSPM9.cjs';
 
 /**
  * Shared error type for every Throttle SDK.
@@ -153,6 +153,16 @@ declare const THROTTLE_CART_CODES: {
         readonly statuses: readonly [501];
         readonly retryable: false;
     };
+    /** The absorb (MC2-R39): a customer's cart never moves into a guest's or another customer's. */
+    readonly cart_owner_mismatch: {
+        readonly statuses: readonly [403];
+        readonly retryable: false;
+    };
+    /** The absorb: the two carts are priced by different apps. */
+    readonly cart_resolver_mismatch: {
+        readonly statuses: readonly [422];
+        readonly retryable: false;
+    };
 };
 type ThrottleCartCode = keyof typeof THROTTLE_CART_CODES;
 

package/dist/{catalog-error-7DCsTyB2.d.ts → catalog-error-BnabMMEy.d.ts}

@@ -1,4 +1,4 @@
-import { i as CatalogContractErrorCode } from './contract-types-BPSzY_Co.js';
+import { k as CatalogContractErrorCode } from './contract-types-D2-SSPM9.js';
 
 /**
  * Shared error type for every Throttle SDK.
@@ -153,6 +153,16 @@ declare const THROTTLE_CART_CODES: {
         readonly statuses: readonly [501];
         readonly retryable: false;
     };
+    /** The absorb (MC2-R39): a customer's cart never moves into a guest's or another customer's. */
+    readonly cart_owner_mismatch: {
+        readonly statuses: readonly [403];
+        readonly retryable: false;
+    };
+    /** The absorb: the two carts are priced by different apps. */
+    readonly cart_resolver_mismatch: {
+        readonly statuses: readonly [422];
+        readonly retryable: false;
+    };
 };
 type ThrottleCartCode = keyof typeof THROTTLE_CART_CODES;
 

package/dist/{chunk-JNBKKAMP.js → chunk-3FX2HISB.js}

@@ -6,7 +6,7 @@ import {
   STALE_MS,
   SUGGEST_DEBOUNCE_MS,
   SUGGEST_MIN_CHARS
-} from "./chunk-55G4ZTD5.js";
+} from "./chunk-VJHA7J7B.js";
 
 // src/react/provider.tsx
 import {
@@ -183,6 +183,21 @@ function createStore(client, options = {}) {
       }
     }
   }
+  function invalidate() {
+    for (const [key, entry] of [...entries]) {
+      clearTimeout(entry.timer);
+      clearTimeout(entry.retry);
+      entry.flight?.abort();
+      if (entry.subs.size === 0) {
+        entries.delete(key);
+      } else {
+        entry.etag = entry.flight = entry.promise = void 0;
+        entry.indexing = false;
+        entry.retries = 0;
+        if (entry.run) void fetchKey(key, entry.run, { force: true });
+      }
+    }
+  }
   return {
     subscribe(key, listener) {
       const entry = touch(key);
@@ -202,6 +217,7 @@ function createStore(client, options = {}) {
     },
     fetch: fetchKey,
     clear,
+    invalidate,
     pause,
     pausedUntil: () => until > now() ? until : 0,
     dispose() {
@@ -218,6 +234,7 @@ function createStore(client, options = {}) {
 import { jsx } from "react/jsx-runtime";
 function createMemoryCartStorage() {
   let id = null;
+  const byCurrency = /* @__PURE__ */ new Map();
   return {
     get: () => id,
     set: (value) => {
@@ -225,6 +242,13 @@ function createMemoryCartStorage() {
     },
     remove: () => {
       id = null;
+    },
+    getFor: (currency) => byCurrency.get(currency) ?? null,
+    setFor: (currency, value) => {
+      byCurrency.set(currency, value);
+    },
+    removeFor: (currency) => {
+      byCurrency.delete(currency);
     }
   };
 }
@@ -352,7 +376,7 @@ function useQuery(route, params, run, options = {}) {
 }
 
 // src/react/hooks.ts
-import { useEffect as useEffect3, useMemo as useMemo2, useSyncExternalStore as useSyncExternalStore2 } from "react";
+import { useEffect as useEffect3, useMemo as useMemo2, useRef as useRef3, useSyncExternalStore as useSyncExternalStore2 } from "react";
 function defined(options) {
   const out = {};
   for (const name in options) {
@@ -458,6 +482,75 @@ function useConfig(options) {
     options
   );
 }
+function useStorefrontSettings(options) {
+  return useQuery(
+    "settings",
+    null,
+    (client, call) => client.settings(call),
+    options
+  );
+}
+var watches = /* @__PURE__ */ new WeakMap();
+var watchRun = (client, call) => client.config(call);
+var pageDocument = () => Reflect.get(globalThis, "document");
+function watch(store, intervalMs, listener) {
+  let w = watches.get(store);
+  if (w === void 0) {
+    const key = `\0${catalogQueryKey("generation", null)}`;
+    const visible = () => pageDocument().visibilityState === "visible";
+    const listeners = /* @__PURE__ */ new Set();
+    let known;
+    let hiddenAt = visible() ? 0 : Date.now();
+    const check = async () => {
+      if (!visible()) return;
+      await store.fetch(key, watchRun, { force: true });
+      const data = store.get(key).data;
+      if (watches.get(store) !== w || data?.generation === void 0) return;
+      const changed = known !== void 0 && data.generation !== known;
+      known = data.generation;
+      if (changed) {
+        store.invalidate();
+        for (const { current } of [...listeners]) current?.(known);
+      }
+    };
+    const onVisibility = () => {
+      if (!visible()) hiddenAt = Date.now();
+      else {
+        if (known === void 0 || Date.now() - hiddenAt >= intervalMs)
+          void check();
+        hiddenAt = 0;
+      }
+    };
+    void check();
+    const timer = setInterval(() => void check(), intervalMs);
+    const doc = pageDocument();
+    doc.addEventListener("visibilitychange", onVisibility);
+    w = {
+      listeners,
+      stop() {
+        clearInterval(timer);
+        doc.removeEventListener("visibilitychange", onVisibility);
+        watches.delete(store);
+      }
+    };
+    watches.set(store, w);
+  }
+  const mine = w;
+  mine.listeners.add(listener);
+  return () => {
+    mine.listeners.delete(listener);
+    if (mine.listeners.size === 0) mine.stop();
+  };
+}
+function useGenerationWatch({
+  intervalMs = 6e4,
+  onChange
+} = {}) {
+  const { store } = useCatalogContext();
+  const latest = useRef3(onChange);
+  latest.current = onChange;
+  useEffect3(() => watch(store, intervalMs, latest), [store, intervalMs]);
+}
 function useFilterValues(key, query = {}, options) {
   return useQuery(
     "filterValues",
@@ -484,5 +577,7 @@ export {
   useCollection,
   useReviews,
   useConfig,
+  useStorefrontSettings,
+  useGenerationWatch,
   useFilterValues
 };