@usethrottle/catalog 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @usethrottle/catalog
 
+## 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
+
+- d6435da: Storefront Part 8 (1.2.0). The API is additive (no name is removed or changed), but two defaults change for everyone: `suggest` never sends the customer token, so suggestions show list prices (an integrator who showed group prices in suggestions now shows list prices), and failed revalidations retry up to twice. Everything else needs the new options.
+
+  - `keyInQuery` (opt-in): a browser read sends the publishable key as `?key=` and no `x-catalog-key` header, so it needs no CORS preflight. Reads only (a `POST` always sends the header); `createServerCatalogClient` ignores it. A server key in a URL is refused with the new error code `KEY_NOT_ALLOWED_IN_URL` (`403`).
+  - `suggest` sends no customer token in any mode, so suggestions are list prices (cached under the guest partition without `keyInQuery`). With `keyInQuery` it sends only `accept` plus any client `headers` (no `If-None-Match`; custom `headers` bring the preflight back) and bypasses the SDK's ETag cache. A customer token is never put in a URL.
+  - `customerCart` on `CatalogProvider` (types `CustomerCartSource` and `OpenCartRef`, exported from `.` and `/react`): `useCart` resumes a signed-in customer's open cart on any device. It resumes only when a currency is known (the client `currency` option or `useCart({ currency })`).
+  - New hooks `useTags`, `useCollections` and `useReviewEligibility`, imported from `@usethrottle/catalog/react/extras` (a new entry that shares `/react`'s provider and cache; it keeps `/react` within its 6,144 B budget). `HOOKS_ENTRY` is `@usethrottle/catalog/react/extras`.
+  - `useCustomerKey()` reads the provider's `customerKey`; the `ReviewEligibility` type is exported from `.` and `/react`.
+  - `keepPreviousData` option, with `dataFor` (the params the shown `data` answers; for `useSuggest`, the query echo `dataFor.q`) and `isPreviousData` on the result. Data is never kept across a `customerKey` change.
+  - `isStale` on the result and automatic retries: a failed revalidation keeps its data, sets `error`, and retries a `NetworkError`, `TimeoutError` or 5xx at 2 s and 12 s (two retries). Other 4xx are not retried and a `429` pause holds.
+  - The `640` size key in answers: `sizes` and `media.versions` can now carry `640` (types updated).
+  - `KEY_NOT_ALLOWED_IN_URL` joins the error codes.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -32,17 +32,18 @@ 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` and `useSubmitReview` (marked `"use client"`).                                                                                                                                                                                             |
-| `@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/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.
 
@@ -80,7 +81,7 @@ Every error the SDK throws is a `CatalogError` (which extends `ThrottleError` fr
 | Class                       | When                                                                                                                                                                                                                                                                                                         |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `RateLimitedError`          | every `429`; `retryAfterSeconds` comes from `Retry-After` (60 when it is missing or unusable). The client never retries a `429` itself.                                                                                                                                                                      |
-| `OriginNotAllowedError`     | `ORIGIN_NOT_ALLOWED`, `SERVER_KEY_IN_BROWSER`, and Throttle's `origin_not_allowed`.                                                                                                                                                                                                                          |
+| `OriginNotAllowedError`     | `ORIGIN_NOT_ALLOWED`, `SERVER_KEY_IN_BROWSER`, `KEY_NOT_ALLOWED_IN_URL`, and Throttle's `origin_not_allowed`.                                                                                                                                                                                                |
 | `CustomerTokenInvalidError` | a refused customer token on a call that cannot fall back to list prices.                                                                                                                                                                                                                                     |
 | `CartLineError`             | `CART_ITEMS_INVALID` and Throttle's `quantity_unavailable` and `line_not_purchasable`, with `lines: { sku, code, maxQuantity? }[]`.                                                                                                                                                                          |
 | `TimeoutError`              | `TIMEOUT`: no answer within `timeoutMs`.                                                                                                                                                                                                                                                                     |
@@ -104,7 +105,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({
@@ -116,7 +117,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
 
@@ -134,6 +135,7 @@ import {
 // One client per currency and language (see Versioning), kept for the life of the app.
 const client = createCatalogClient({
   publishableKey: process.env.NEXT_PUBLIC_CATALOG_KEY ?? '',
+  keyInQuery: true, // browser reads need no preflight (see Key transport)
   customerToken: () => auth.getAccessToken(),
 });
 
@@ -186,13 +188,128 @@ function ProductGrid() {
 }
 ```
 
-- **Hooks:** `useProducts`, `useProduct`, `useRelated`, `useFilterValues`, `useCategories`, `useCollection`, `useSuggest` (debounced 200 ms, 2 characters at least), `useReviews` and `useConfig`, each answering `{ data, error, isLoading, isValidating, refetch }` and taking `enabled`, `initialData` (for an SSR hand-off) and `staleTimeMs`. 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.
+- **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.
 
+### Customer carts
+
+With `@usethrottle/auth` 0.12 or later, a signed-in customer's open cart comes back on any device. This example needs `@usethrottle/auth` >= 0.12.0, whose `account.getOpenCart` and `whenClaimSettled` it uses. Pass `customerCart` to the provider; it is structural, so the SDK never holds a Throttle key and never imports `@usethrottle/auth`:
+
+```tsx
+import { useMemo } from 'react';
+import { useAuth } from '@usethrottle/auth/react';
+
+function Shell({ customerId, children }) {
+  const { auth, account } = useAuth();
+  // Memoised: a new object on every render would re-render every consumer.
+  const customerCart = useMemo(
+    () => ({
+      // The customer's most recently updated open cart in `currency`, or null.
+      // Both members are optional on the auth SDK, so fall back when absent.
+      getOpenCart: ({ currency }) =>
+        account.getOpenCart?.({ currency }) ?? Promise.resolve(null),
+      // Resolves once the sign-in's guest-cart claim is done.
+      whenClaimSettled: () => auth.whenClaimSettled?.() ?? Promise.resolve(),
+    }),
+    [auth, account],
+  );
+  return (
+    <CatalogProvider
+      client={client}
+      customerKey={customerId}
+      customerCart={customerCart}
+    >
+      {children}
+    </CatalogProvider>
+  );
+}
+```
+
+`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
+
+By default every request sends the publishable key in the `x-catalog-key` header, which makes a browser preflight each new URL. Set `keyInQuery: true` on a browser client and a **read** (a `GET`) sends `?key=` instead, with no custom header, so a plain read needs no preflight (a revalidation with `If-None-Match`, or any client `headers`, still preflights; only `suggest` is preflight-free when the client sets no custom `headers`):
+
+```ts
+const client = createCatalogClient({
+  publishableKey: process.env.NEXT_PUBLIC_CATALOG_KEY ?? '',
+  keyInQuery: true,
+});
+```
+
+- Reads only: a `POST` always sends the header. `createServerCatalogClient` ignores the option; a server key in a URL is refused (`403 KEY_NOT_ALLOWED_IN_URL`), so use `keyInQuery` with browser and app keys only. A URL is recorded wherever full URLs are kept (CDN and zone logs, analytics, browser history), so rotate any server key that was ever sent in a URL, even though it was refused.
+- The customer token is never put in a URL, in any mode. It travels only in `X-Customer-Token`, so a read that carries a token still preflights.
+- **`suggest` never sends the customer token**, whatever `keyInQuery` is. Suggestions are list prices (the answer has no group prices). Without `keyInQuery` they are cached under the guest partition; with it on, suggest bypasses the SDK's ETag cache and sends no `If-None-Match`. A suggest request then sends only `accept` plus any client `headers` you set, so every keystroke is one request, and a client with custom `headers` preflights again.
+
+### Keeping previous data
+
+`keepPreviousData: true` keeps a hook's last settled answer on screen while the next key loads, so a filter change or a typed query does not flash empty:
+
+```tsx
+const { data, dataFor, isPreviousData } = useProducts(
+  { q, limit: 24 },
+  { keepPreviousData: true },
+);
+// data is the old answer while isPreviousData is true; dataFor is the params it answers.
+```
+
+`isLoading` stays `false` while the old answer shows. If the new key fails, `error` is set and the old data stays (`isPreviousData` true). `dataFor` is the params object the shown `data` answers, so for `useSuggest` the query echo is `dataFor.q`. While `data` is undefined (a first load, or a new key without `keepPreviousData`), `dataFor` is the params just asked for, so check `data` before treating `dataFor` as its params. When a new key fails and the previous data stays, the hook shows `isPreviousData` together with `error`; `isStale` is for revalidation failures of the data's own key. Data is never kept across a `customerKey` change: one customer's answer is not shown to the next.
+
+### Refresh errors
+
+`isStale` is `true` while the shown `data` was not confirmed by the latest attempt: a revalidation failed, or an `initialData` seed under a `customerKey` is still being revalidated. A failed revalidation keeps the data, sets `error`, and retries by itself when the failure is retryable (a `NetworkError`, a `TimeoutError` or a 5xx): 2 seconds after the failure and again 10 seconds after that, so two retries. Other 4xx answers are not retried, and a `429` keeps its pause with no extra retry. A success clears `error` and `isStale`.
+
+```tsx
+import type { StorefrontListAnswer } from '@usethrottle/catalog';
+
+function Prices({ initialData }: { initialData: StorefrontListAnswer }) {
+  const { data, error, isStale, refetch } = useProducts(
+    { limit: 24 },
+    { initialData },
+  );
+  // Signed in: initialData is the anonymous server answer. If revalidating it fails,
+  // the list prices stay and isStale tells you they may be out of date.
+  return isStale && error ? (
+    <button onClick={() => void refetch()}>
+      Prices may be out of date. Retry
+    </button>
+  ) : null;
+}
+```
+
+### The new hooks
+
+`useTags`, `useCollections` and `useReviewEligibility` are in `@usethrottle/catalog/react/extras`. They use the provider and cache of `/react`:
+
+```tsx
+import { CatalogProvider } from '@usethrottle/catalog/react';
+import {
+  useCollections,
+  useReviewEligibility,
+  useTags,
+} from '@usethrottle/catalog/react/extras';
+
+function Filters() {
+  const tags = useTags({ q: 'fr', limit: 5 }); // client.tags.list({ q, limit })
+  const collections = useCollections({ limit: 6 }); // client.collections.list({ limit })
+  return /* tags.data?.tags, collections.data?.collections */ null;
+}
+
+function ReviewButton({ handle }: { handle: string }) {
+  // No request while signed out (customerKey null) or handle is null.
+  // Asked again on every mount (staleTimeMs 0), and kept per customer.
+  const { data } = useReviewEligibility(handle);
+  return data?.canReview ? <a href="#review">Write a review</a> : null;
+}
+```
+
+`useCustomerKey()` (from `/react`) returns the provider's `customerKey`, and the `ReviewEligibility` type (from either entry) is the answer of `reviews.eligibility`.
+
 ## 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.
@@ -257,6 +374,8 @@ Ranges stay strings (`10..50`); `parseRange` and `formatRange` convert them.
 
 ## Admin (server only, experimental)
 
+Full documentation of the push API: https://usethrottle.dev/docs/product-catalog/push/ (a first-feed guide, concepts, limits, troubleshooting and a reference for AI agents). The OpenAPI document is https://catalog.usethrottle.dev/v1/catalog/openapi.json.
+
 > **Experimental.** `@usethrottle/catalog/admin` is outside the 1.x freeze: a breaking change to it ships as a minor release, named in the changelog, until it is frozen. Every export carries a TSDoc `@experimental` tag.
 
 `createCatalogAdmin` wraps the catalog push API (`/v1/catalog/jobs`, `/variants`, `/runs`, `/products`, `/inventory`). It holds a secret key (`pc_sk_`) or a vendor key (`pc_vk_`), so it throws `CatalogError` `SERVER_ONLY` when it is created in a browser environment, and `INVALID_ADMIN_KEY` for any other key (a publishable `pc_pk_` key gets its own message). The key is never part of an error message. Errors are the same classes as the rest of the package: `CatalogError` with the server's `code`, a `RateLimitedError` (with `retryAfterSeconds`) for every `429`, `TimeoutError` and `NetworkError`.
@@ -291,7 +410,7 @@ if (done.failureCode !== null) console.error(await job.errorsCsv());
 
 **Reports.** Job report row numbers are job-wide, not per batch. A job whose error or stock CSV is too large (above 900 parts) answers `409 REPORT_TOO_LARGE`; `stockResults()` pages, so read stock rows that way.
 
-**Images.** Image copying stays on today's cron (about 20 per minute) and today's per-store resize budget (about 20k resizes a month, roughly 6,700 images). For a 120k-product feed most images are therefore served from the vendor's URL for months. The follow-up is a copy queue and a per-store resize cap (about $1.50 per 1,000 images, one-off).
+**Images.** Image copying stays on today's path (about 200–285 copies a minute at peak while a push job applies, measured once on 2026-11-01; leftovers drain on the 5-minute cron at about 20 a minute) and today's per-store resize budget (about 20k resizes a month, roughly 6,700 images). For a 120k-product feed most images are therefore served from the vendor's URL for months. The follow-up is a copy queue and a per-store resize cap (about $1.50 per 1,000 images, one-off).
 
 **Webhooks.** `verifyCatalogWebhook` checks a catalog webhook with WebCrypto only. Pass the raw body, the `x-catalog-signature` header and the signing secret; it returns `true` or `false` and never throws. The header is `t=<seconds>,v1=<hex>` with one `t` and 1 to 8 `v1` digests (any match passes, so a secret can rotate), HMAC-SHA256 over `<t>.<rawBody>`, with a tolerance of 300 seconds.
 
@@ -325,7 +444,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';
@@ -383,17 +502,9 @@ A language change needs no cart step: swap the client.
 
 ### 1.x follow-ups
 
-1.0.0 freezes the surface the reference store proved; these are additive and planned for 1.x minors. Until then the reference store's code shows the workaround.
+1.2.0 shipped `useTags`, `useCollections`, `useReviewEligibility`, `useCustomerKey`, `ReviewEligibility`, `keepPreviousData` with the query echo (`dataFor`), refresh errors with `isStale`, the customer's cart on any device, and the query key (`keyInQuery`) with token-free suggestions. What remains additive for 1.x minors:
 
-- `useTags` and `useCollections` hooks. Today: `client.tags.list()` and `client.collections.list()`, or the server client.
-- A `useReviewEligibility(handle)` hook and a `ReviewEligibility` type export. Today: `useCatalog().reviews.eligibility(handle, { signal })`, typed `ReviewEligibilityAnswer`.
-- A keep-previous-data option, so a hook shows its last answer while a new key loads.
-- `useSuggest` names the query its `data` answers.
-- A way to read the provider's `customerKey` from inside it.
-- A retry or an error surface when a signed-in customer's revalidation of `initialData` fails. Today the anonymous answer (list prices) stays until the next navigation.
-- A signed-in customer's open cart coming back after a sign-out and a sign-in with no guest cart. This needs an authenticated open-cart read for the customer in Throttle too.
 - A first `add` whose confirming read fails rejects while the line is already in the new cart; that case will settle one consistent way.
-- Fewer CORS preflights for suggestions: every query is a new URL carrying the key header, so the browser preflights each keystroke.
 
 ## License
 

package/dist/admin.cjs

@@ -10,7 +10,7 @@
 
 
 
-var _chunk4ORXUW2Ucjs = require('./chunk-4ORXUW2U.cjs');
+var _chunk2YQNMBDIcjs = require('./chunk-2YQNMBDI.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, _chunk4ORXUW2Ucjs.CatalogError)({
+  return new (0, _chunk2YQNMBDIcjs.CatalogError)({
     code: "INVALID_REQUEST",
     message,
     statusCode: 0,
@@ -54,7 +54,7 @@ function invalidRequest(message) {
   });
 }
 function clientError(code, message) {
-  return new (0, _chunk4ORXUW2Ucjs.CatalogError)({
+  return new (0, _chunk2YQNMBDIcjs.CatalogError)({
     code,
     message,
     statusCode: 0,
@@ -126,13 +126,13 @@ function toError(status, headers, text) {
     requestId
   };
   if (status === 429) {
-    return new (0, _chunk4ORXUW2Ucjs.RateLimitedError)({
+    return new (0, _chunk2YQNMBDIcjs.RateLimitedError)({
       ...init,
       retryable: true,
-      retryAfterSeconds: retryAfter !== null && retryAfter >= 1 ? retryAfter : _chunk4ORXUW2Ucjs.RATE_LIMIT_DEFAULT_RETRY_S
+      retryAfterSeconds: retryAfter !== null && retryAfter >= 1 ? retryAfter : _chunk2YQNMBDIcjs.RATE_LIMIT_DEFAULT_RETRY_S
     });
   }
-  return new (0, _chunk4ORXUW2Ucjs.CatalogError)(init);
+  return new (0, _chunk2YQNMBDIcjs.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, _chunk4ORXUW2Ucjs.TimeoutError)({ timeoutMs }));
+      reject(new (0, _chunk2YQNMBDIcjs.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, _chunk4ORXUW2Ucjs.NetworkError)({ cause });
+              throw new (0, _chunk2YQNMBDIcjs.NetworkError)({ cause });
             }
             try {
               return {
@@ -203,14 +203,14 @@ function createHttp(key, baseUrl, fetchFn, timeoutMs) {
                 text: await response.text()
               };
             } catch (cause) {
-              throw new (0, _chunk4ORXUW2Ucjs.NetworkError)({ cause });
+              throw new (0, _chunk2YQNMBDIcjs.NetworkError)({ cause });
             }
           },
           spec.signal,
           timeoutMs
         );
       } catch (error) {
-        if (error instanceof _chunk4ORXUW2Ucjs.NetworkError && attempt < attempts) continue;
+        if (error instanceof _chunk2YQNMBDIcjs.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, _chunk4ORXUW2Ucjs.CatalogError)({
+        throw new (0, _chunk2YQNMBDIcjs.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, _chunk4ORXUW2Ucjs.CatalogError)({
+  return new (0, _chunk2YQNMBDIcjs.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, _chunk4ORXUW2Ucjs.TimeoutError)({ timeoutMs });
+    if (remaining <= 0) throw new (0, _chunk2YQNMBDIcjs.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 _chunk4ORXUW2Ucjs.RateLimitedError) || retry >= QUEUE_RETRIES)
+        if (!(error instanceof _chunk2YQNMBDIcjs.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, () => ( _chunk4ORXUW2Ucjs.DEFAULT_BASE_URL))).replace(/\/+$/u, "");
+  const baseUrl = (_nullishCoalesce(options.baseUrl, () => ( _chunk2YQNMBDIcjs.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 = _chunk4ORXUW2Ucjs.CartLineError; exports.CatalogError = _chunk4ORXUW2Ucjs.CatalogError; exports.CustomerTokenInvalidError = _chunk4ORXUW2Ucjs.CustomerTokenInvalidError; exports.FeatureUnavailableError = _chunk4ORXUW2Ucjs.FeatureUnavailableError; exports.NetworkError = _chunk4ORXUW2Ucjs.NetworkError; exports.OriginNotAllowedError = _chunk4ORXUW2Ucjs.OriginNotAllowedError; exports.RateLimitedError = _chunk4ORXUW2Ucjs.RateLimitedError; exports.TimeoutError = _chunk4ORXUW2Ucjs.TimeoutError; exports.createCatalogAdmin = createCatalogAdmin; exports.isCatalogError = _chunk4ORXUW2Ucjs.isCatalogError; exports.verifyCatalogWebhook = verifyCatalogWebhook;
+exports.CartLineError = _chunk2YQNMBDIcjs.CartLineError; exports.CatalogError = _chunk2YQNMBDIcjs.CatalogError; exports.CustomerTokenInvalidError = _chunk2YQNMBDIcjs.CustomerTokenInvalidError; exports.FeatureUnavailableError = _chunk2YQNMBDIcjs.FeatureUnavailableError; exports.NetworkError = _chunk2YQNMBDIcjs.NetworkError; exports.OriginNotAllowedError = _chunk2YQNMBDIcjs.OriginNotAllowedError; exports.RateLimitedError = _chunk2YQNMBDIcjs.RateLimitedError; exports.TimeoutError = _chunk2YQNMBDIcjs.TimeoutError; exports.createCatalogAdmin = createCatalogAdmin; exports.isCatalogError = _chunk2YQNMBDIcjs.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-s1BINNkt.cjs';
-import './contract-types-DhiThMEr.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-BOaSKgY3.cjs';
+import './contract-types-BRyonOYH.cjs';
+import '@usethrottle/money';
 
 type JobBatchAnswer = {
     batchId: string;
@@ -131,6 +132,7 @@ type PushProduct = {
         base: string;
         separator: '-' | '_' | '.' | '';
     } | null | undefined;
+    taxCode?: string | null | undefined;
     externalId: string | null;
     handle: string;
     status: 'draft' | 'active' | 'archived';
@@ -243,6 +245,7 @@ type PushRow = {
             base: string;
             separator: '-' | '_' | '.' | '';
         } | null | undefined;
+        taxCode?: string | null | undefined;
     } | undefined;
     variant?: {
         title?: string | null | undefined;
@@ -382,6 +385,7 @@ type PushVariantsRequest = {
                 base: string;
                 separator: '-' | '_' | '.' | '';
             } | null | undefined;
+            taxCode?: string | null | undefined;
         } | undefined;
         variant?: {
             title?: string | null | undefined;

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-C_zLOtYA.js';
-import './contract-types-DhiThMEr.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-CSoPS0-d.js';
+import './contract-types-BRyonOYH.js';
+import '@usethrottle/money';
 
 type JobBatchAnswer = {
     batchId: string;
@@ -131,6 +132,7 @@ type PushProduct = {
         base: string;
         separator: '-' | '_' | '.' | '';
     } | null | undefined;
+    taxCode?: string | null | undefined;
     externalId: string | null;
     handle: string;
     status: 'draft' | 'active' | 'archived';
@@ -243,6 +245,7 @@ type PushRow = {
             base: string;
             separator: '-' | '_' | '.' | '';
         } | null | undefined;
+        taxCode?: string | null | undefined;
     } | undefined;
     variant?: {
         title?: string | null | undefined;
@@ -382,6 +385,7 @@ type PushVariantsRequest = {
                 base: string;
                 separator: '-' | '_' | '.' | '';
             } | null | undefined;
+            taxCode?: string | null | undefined;
         } | undefined;
         variant?: {
             title?: string | null | undefined;

package/dist/admin.js

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

package/dist/{catalog-error-s1BINNkt.d.cts → catalog-error-BOaSKgY3.d.cts}

@@ -1,4 +1,4 @@
-import { g as CatalogContractErrorCode } from './contract-types-DhiThMEr.cjs';
+import { i as CatalogContractErrorCode } from './contract-types-BRyonOYH.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;
 
@@ -206,7 +216,7 @@ declare class RateLimitedError extends CatalogError {
         retryAfterSeconds: number;
     });
 }
-/** `ORIGIN_NOT_ALLOWED`, `SERVER_KEY_IN_BROWSER` and Throttle `origin_not_allowed`. */
+/** `ORIGIN_NOT_ALLOWED`, `SERVER_KEY_IN_BROWSER`, `KEY_NOT_ALLOWED_IN_URL` and Throttle `origin_not_allowed`. */
 declare class OriginNotAllowedError extends CatalogError {
     constructor(init: CatalogErrorInit);
 }

package/dist/{catalog-error-C_zLOtYA.d.ts → catalog-error-CSoPS0-d.d.ts}

@@ -1,4 +1,4 @@
-import { g as CatalogContractErrorCode } from './contract-types-DhiThMEr.js';
+import { i as CatalogContractErrorCode } from './contract-types-BRyonOYH.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;
 
@@ -206,7 +216,7 @@ declare class RateLimitedError extends CatalogError {
         retryAfterSeconds: number;
     });
 }
-/** `ORIGIN_NOT_ALLOWED`, `SERVER_KEY_IN_BROWSER` and Throttle `origin_not_allowed`. */
+/** `ORIGIN_NOT_ALLOWED`, `SERVER_KEY_IN_BROWSER`, `KEY_NOT_ALLOWED_IN_URL` and Throttle `origin_not_allowed`. */
 declare class OriginNotAllowedError extends CatalogError {
     constructor(init: CatalogErrorInit);
 }