@usethrottle/catalog 0.1.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @usethrottle/catalog
 
+## 1.0.0
+
+### Major Changes
+
+- 9508bce: 1.0.0: API freeze. No change from 0.1.x beyond the patches listed; from 1.0.0, breaking changes come only in a major version.
+
+### Patch Changes
+
+- 22949b4: `useCart().switchCurrency` lands whole or not at all: the new cart is read back and saved before it replaces the old one, so when that read or save fails the call rejects and the old cart, its stored id and the old currency stay. Before, a failed read left the new cart's id stored and its currency kept while the call rejected.
+
+## 0.1.1
+
+### Patch Changes
+
+- de45b49: Hooks revalidate `initialData` at once under a signed-in customer, so an anonymous SSR answer never shows list prices for a minute
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -130,7 +130,7 @@ import {
   type CartStorage,
 } from '@usethrottle/catalog/react';
 
-// One client for the life of the app.
+// 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 ?? '',
   customerToken: () => auth.getAccessToken(),
@@ -185,10 +185,10 @@ 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`.
+- **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.
 - **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` for the app's life 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`. 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).
+- **`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).
 - **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.
 
@@ -260,10 +260,84 @@ The package ships ESM and CommonJS builds. Within one format, every entry shares
 
 ## Versioning
 
-The package stays at `0.x` until the reference store ships with `1.0.0`. While it is `0.x`, a breaking type change is a minor release, named in the changelog. SDK 0.1.0 targets the current catalog. Against an older one, everything works except the route-miss marker behind `FeatureUnavailableError`, the OpenAPI document and the cart return URLs (an older catalog refuses them with `400 INVALID_REQUEST`).
+From 1.0.0 the package follows semantic versioning: a breaking change to an exported name, a type, an error class or code, or a hook's behaviour comes only in a major version. New answer keys, new error codes in `(string & {})` positions and new optional options are minor. Deprecated names keep working for at least one major. The reference store at https://throttle-demo-store.vercel.app runs this version.
+
+The SDK targets the current catalog. Against an older one, everything works except the route-miss marker behind `FeatureUnavailableError`, the OpenAPI document and the cart return URLs (an older catalog refuses them with `400 INVALID_REQUEST`).
 
 The OpenAPI 3.1 document of the storefront API is at https://catalog.usethrottle.dev/v1/storefront/openapi.json.
 
+### 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.
+
+```tsx
+'use client';
+import { useMemo, useState, type ReactNode } from 'react';
+import { createCatalogClient } from '@usethrottle/catalog';
+import { CatalogProvider, useCart } from '@usethrottle/catalog/react';
+
+export function Shop({ children }: { children: ReactNode }) {
+  const [prefs, setPrefs] = useState({ currency: 'USD', locale: 'en' });
+  const client = useMemo(
+    () =>
+      createCatalogClient({
+        publishableKey: process.env.NEXT_PUBLIC_CATALOG_KEY ?? '',
+        currency: prefs.currency,
+        locale: prefs.locale,
+        customerToken: () => auth.getAccessToken(),
+      }),
+    [prefs.currency, prefs.locale],
+  );
+  // Pass customerKey, cartStorage and cartUrls as in the React example.
+  return (
+    <CatalogProvider client={client}>
+      <CurrencyPicker
+        currency={prefs.currency}
+        onSwitched={(currency) => setPrefs((p) => ({ ...p, currency }))}
+      />
+      {children}
+    </CatalogProvider>
+  );
+}
+
+function CurrencyPicker(props: {
+  currency: string;
+  onSwitched: (currency: string) => void;
+}) {
+  const cart = useCart();
+  const choose = async (currency: string) => {
+    await cart.switchCurrency(currency); // rejects and keeps the old cart on failure
+    props.onSwitched(currency); // only now swap the client
+  };
+  return (
+    <select
+      value={props.currency}
+      disabled={cart.pending}
+      onChange={(e) => void choose(e.target.value).catch(() => undefined)}
+    >
+      <option>USD</option>
+      <option>EUR</option>
+    </select>
+  );
+}
+```
+
+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.
+
+- `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
 
 MIT

package/dist/{chunk-PSCFHVZZ.js → chunk-2PJXGAZF.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-PKBMQBKP.js";
 
 // src/version.ts
-var SDK_VERSION = true ? "0.1.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.0.0" : "0.0.0-dev";
 
 // src/errors/catalog-error.ts
 import { ThrottleError } from "@usethrottle/errors";

package/dist/{chunk-O2OYOK2A.cjs → chunk-ZFUELHUU.cjs}

@@ -3,7 +3,7 @@
 var _chunkETV4XYOVcjs = require('./chunk-ETV4XYOV.cjs');
 
 // src/version.ts
-var SDK_VERSION = true ? "0.1.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.0.0" : "0.0.0-dev";
 
 // src/errors/catalog-error.ts
 var _errors = require('@usethrottle/errors');

package/dist/index.cjs

@@ -10,7 +10,7 @@
 
 
 
-var _chunkO2OYOK2Acjs = require('./chunk-O2OYOK2A.cjs');
+var _chunkZFUELHUUcjs = require('./chunk-ZFUELHUU.cjs');
 require('./chunk-ETV4XYOV.cjs');
 
 
@@ -24,4 +24,4 @@ require('./chunk-ETV4XYOV.cjs');
 
 
 
-exports.CartLineError = _chunkO2OYOK2Acjs.CartLineError; exports.CatalogError = _chunkO2OYOK2Acjs.CatalogError; exports.CustomerTokenInvalidError = _chunkO2OYOK2Acjs.CustomerTokenInvalidError; exports.FeatureUnavailableError = _chunkO2OYOK2Acjs.FeatureUnavailableError; exports.NetworkError = _chunkO2OYOK2Acjs.NetworkError; exports.OriginNotAllowedError = _chunkO2OYOK2Acjs.OriginNotAllowedError; exports.RateLimitedError = _chunkO2OYOK2Acjs.RateLimitedError; exports.SDK_VERSION = _chunkO2OYOK2Acjs.SDK_VERSION; exports.TimeoutError = _chunkO2OYOK2Acjs.TimeoutError; exports.createCatalogClient = _chunkO2OYOK2Acjs.createCatalogClient; exports.isCatalogError = _chunkO2OYOK2Acjs.isCatalogError;
+exports.CartLineError = _chunkZFUELHUUcjs.CartLineError; exports.CatalogError = _chunkZFUELHUUcjs.CatalogError; exports.CustomerTokenInvalidError = _chunkZFUELHUUcjs.CustomerTokenInvalidError; exports.FeatureUnavailableError = _chunkZFUELHUUcjs.FeatureUnavailableError; exports.NetworkError = _chunkZFUELHUUcjs.NetworkError; exports.OriginNotAllowedError = _chunkZFUELHUUcjs.OriginNotAllowedError; exports.RateLimitedError = _chunkZFUELHUUcjs.RateLimitedError; exports.SDK_VERSION = _chunkZFUELHUUcjs.SDK_VERSION; exports.TimeoutError = _chunkZFUELHUUcjs.TimeoutError; exports.createCatalogClient = _chunkZFUELHUUcjs.createCatalogClient; exports.isCatalogError = _chunkZFUELHUUcjs.isCatalogError;

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   TimeoutError,
   createCatalogClient,
   isCatalogError
-} from "./chunk-PSCFHVZZ.js";
+} from "./chunk-2PJXGAZF.js";
 import "./chunk-PKBMQBKP.js";
 export {
   CartLineError,

package/dist/react.cjs

@@ -11,7 +11,7 @@
 
 
 
-var _chunkO2OYOK2Acjs = require('./chunk-O2OYOK2A.cjs');
+var _chunkZFUELHUUcjs = require('./chunk-ZFUELHUU.cjs');
 require('./chunk-ETV4XYOV.cjs');
 
 // src/react/provider.tsx
@@ -38,7 +38,7 @@ function createStore(client, options = {}) {
   let until = 0;
   let cause;
   let pauseTimer;
-  const pausedError = () => new (0, _chunkO2OYOK2Acjs.RateLimitedError)({
+  const pausedError = () => new (0, _chunkZFUELHUUcjs.RateLimitedError)({
     code: _nullishCoalesce(_optionalChain([cause, 'optionalAccess', _ => _.code]), () => ( "RATE_LIMITED")),
     message: _nullishCoalesce(_optionalChain([cause, 'optionalAccess', _2 => _2.message]), () => ( "Too many requests.")),
     statusCode: 429,
@@ -49,17 +49,17 @@ function createStore(client, options = {}) {
     entry.snap = { ...entry.snap, ...patch };
     for (const listener of [...entry.subs]) listener();
   };
-  const touch = (key, initial) => {
+  const touch = (key, initial, stale = false) => {
     let entry = entries.get(key);
     if (entry !== void 0) {
       entries.delete(key);
     } else {
       entry = {
-        snap: initial === void 0 ? EMPTY : { ...EMPTY, data: initial, fetchedAt: now() },
+        snap: initial === void 0 ? EMPTY : { ...EMPTY, data: initial, fetchedAt: stale ? void 0 : now() },
         subs: /* @__PURE__ */ new Set()
       };
       for (const [oldKey, old] of entries) {
-        if (entries.size < _chunkO2OYOK2Acjs.CACHE_MAX_ENTRIES) break;
+        if (entries.size < _chunkZFUELHUUcjs.CACHE_MAX_ENTRIES) break;
         if (old.subs.size === 0 && old.flight === void 0) {
           clearTimeout(old.timer);
           entries.delete(oldKey);
@@ -78,7 +78,7 @@ function createStore(client, options = {}) {
       else entry.indexing = false;
     }, ms);
   };
-  function fetchKey(key, run, { force = false, staleMs = _chunkO2OYOK2Acjs.STALE_MS } = {}) {
+  function fetchKey(key, run, { force = false, staleMs = _chunkZFUELHUUcjs.STALE_MS } = {}) {
     const entry = touch(key);
     entry.run = run;
     if (entry.promise !== void 0 && !_optionalChain([entry, 'access', _4 => _4.flight, 'optionalAccess', _5 => _5.signal, 'access', _6 => _6.aborted]))
@@ -128,7 +128,7 @@ function createStore(client, options = {}) {
           return;
         }
         if (_optionalChain([result, 'access', _7 => _7.data, 'optionalAccess', _8 => _8.indexing]) === true) {
-          if (!entry.indexing) later(key, entry, _chunkO2OYOK2Acjs.INDEXING_REVALIDATE_MS);
+          if (!entry.indexing) later(key, entry, _chunkZFUELHUUcjs.INDEXING_REVALIDATE_MS);
         } else {
           entry.indexing = false;
         }
@@ -141,7 +141,7 @@ function createStore(client, options = {}) {
       },
       (error) => {
         if (!current()) return;
-        const retryMs = (_nullishCoalesce(error.retryAfterSeconds, () => ( _chunkO2OYOK2Acjs.RATE_LIMIT_DEFAULT_RETRY_S))) * 1e3;
+        const retryMs = (_nullishCoalesce(error.retryAfterSeconds, () => ( _chunkZFUELHUUcjs.RATE_LIMIT_DEFAULT_RETRY_S))) * 1e3;
         if (error.statusCode === 429 && error.code === "RATE_LIMITED")
           pause(now() + retryMs, error);
         else if (error.code === "STOREFRONT_INDEXING" && !entry.indexing)
@@ -189,10 +189,10 @@ function createStore(client, options = {}) {
         });
       };
     },
-    get: (key, initial) => key === null ? EMPTY : _nullishCoalesce(_optionalChain([(_nullishCoalesce(entries.get(key), () => ( (initial === void 0 ? void 0 : touch(key, initial))))), 'optionalAccess', _15 => _15.snap]), () => ( EMPTY)),
-    getServer(key, initial) {
+    get: (key, initial, stale) => key === null ? EMPTY : _nullishCoalesce(_optionalChain([(_nullishCoalesce(entries.get(key), () => ( (initial === void 0 ? void 0 : touch(key, initial, stale))))), 'optionalAccess', _15 => _15.snap]), () => ( EMPTY)),
+    getServer(key, initial, stale) {
       if (key === null || initial === void 0) return EMPTY;
-      const entry = _nullishCoalesce(entries.get(key), () => ( touch(key, initial)));
+      const entry = _nullishCoalesce(entries.get(key), () => ( touch(key, initial, stale)));
       return _nullishCoalesce(entry.server, () => ( (entry.server = { ...EMPTY, data: initial })));
     },
     fetch: fetchKey,
@@ -307,10 +307,11 @@ function useQuery(route, params, run, options = {}) {
     (listener) => key === null ? unsubscribe() : store.subscribe(key, listener),
     [store, key]
   );
+  const stale = customerKey !== null;
   const snap = _react.useSyncExternalStore.call(void 0, 
     subscribe,
-    () => store.get(key, initial),
-    () => store.getServer(key, initial)
+    () => store.get(key, initial, stale),
+    () => store.getServer(key, initial, stale)
   );
   const staleMs = options.staleTimeMs;
   _react.useEffect.call(void 0, () => {
@@ -388,9 +389,9 @@ function useDebounced(q, ms) {
   return _react.useSyncExternalStore.call(void 0, box.subscribe, box.get, box.get);
 }
 function useSuggest(q, options = {}) {
-  const settled = useDebounced(q, _nullishCoalesce(options.debounceMs, () => ( _chunkO2OYOK2Acjs.SUGGEST_DEBOUNCE_MS)));
+  const settled = useDebounced(q, _nullishCoalesce(options.debounceMs, () => ( _chunkZFUELHUUcjs.SUGGEST_DEBOUNCE_MS)));
   const extra = defined({ limit: options.limit });
-  const long = (value) => value.trim().length >= _chunkO2OYOK2Acjs.SUGGEST_MIN_CHARS;
+  const long = (value) => value.trim().length >= _chunkZFUELHUUcjs.SUGGEST_MIN_CHARS;
   return useQuery(
     "suggest",
     { q: settled, ...extra },
@@ -460,7 +461,7 @@ function newKey() {
   return out;
 }
 function refuse(message, path) {
-  return new (0, _chunkO2OYOK2Acjs.CatalogError)({
+  return new (0, _chunkZFUELHUUcjs.CatalogError)({
     code: "INVALID_REQUEST",
     message,
     statusCode: 0,
@@ -473,7 +474,7 @@ var UNSAFE = /[\x00-\x20\x7f]/u;
 function isHttpUrl(value) {
   return typeof value === "string" && /^https?:\/\/[^/?#\\]/iu.test(value) && !UNSAFE.test(value);
 }
-var wrap = (error) => _chunkO2OYOK2Acjs.isCatalogError.call(void 0, error) ? error : new (0, _chunkO2OYOK2Acjs.CatalogError)({
+var wrap = (error) => _chunkZFUELHUUcjs.isCatalogError.call(void 0, error) ? error : new (0, _chunkZFUELHUUcjs.CatalogError)({
   code: "CLIENT_ERROR",
   message: "The action failed.",
   statusCode: 0,
@@ -484,7 +485,7 @@ var wrap = (error) => _chunkO2OYOK2Acjs.isCatalogError.call(void 0, error) ? err
 function checkPause(store) {
   const until = store.pausedUntil();
   if (until > 0) {
-    throw new (0, _chunkO2OYOK2Acjs.RateLimitedError)({
+    throw new (0, _chunkZFUELHUUcjs.RateLimitedError)({
       code: "RATE_LIMITED",
       message: "Too many requests.",
       statusCode: 429,
@@ -494,7 +495,7 @@ function checkPause(store) {
   }
 }
 function notePause(store, error) {
-  if (error instanceof _chunkO2OYOK2Acjs.RateLimitedError && error.source === "catalog" && error.code === "RATE_LIMITED")
+  if (error instanceof _chunkZFUELHUUcjs.RateLimitedError && error.source === "catalog" && error.code === "RATE_LIMITED")
     store.pause(Date.now() + error.retryAfterSeconds * 1e3, error);
 }
 function createBox(initial) {
@@ -528,7 +529,7 @@ var ENDED = /* @__PURE__ */ new Set([
   "cart_not_open",
   "cart_not_found"
 ]);
-var ended = (error) => _chunkO2OYOK2Acjs.isCatalogError.call(void 0, error) && ENDED.has(error.code);
+var ended = (error) => _chunkZFUELHUUcjs.isCatalogError.call(void 0, error) && ENDED.has(error.code);
 var converted = (error) => _optionalChain([error, 'access', _23 => _23.details, 'optionalAccess', _24 => _24.reason]) === "converted";
 function itemsOf(cart) {
   const items = /* @__PURE__ */ new Map();
@@ -567,7 +568,7 @@ function createController(home) {
       throttleBaseUrl === void 0 ? void 0 : { throttleBaseUrl }
     );
   };
-  const fallbackUrl = (id) => `${(_nullishCoalesce(ctx().throttleCheckoutUrl, () => ( _chunkO2OYOK2Acjs.THROTTLE_CHECKOUT_URL))).replace(/\/+$/u, "")}/cart/${encodeURIComponent(id)}`;
+  const fallbackUrl = (id) => `${(_nullishCoalesce(ctx().throttleCheckoutUrl, () => ( _chunkZFUELHUUcjs.THROTTLE_CHECKOUT_URL))).replace(/\/+$/u, "")}/cart/${encodeURIComponent(id)}`;
   const live = async (signal, value) => {
     const out = await value;
     if (signal.aborted) throw signal.reason;
@@ -578,7 +579,7 @@ function createController(home) {
     if (converted(error)) reset();
     else box.set({ sessionId: null, cartUrl: null });
   }
-  async function create(signal, options, items) {
+  async function create(signal, options, items, whole = false) {
     const context = ctx();
     const body = {
       items: [...items].map(([sku, quantity]) => ({ sku, quantity }))
@@ -602,10 +603,22 @@ function createController(home) {
       throw error;
     }
     const id = answer.sessionId;
-    box.set({
-      sessionId: id,
-      cartUrl: isHttpUrl(answer.cartUrl) ? answer.cartUrl : fallbackUrl(id)
-    });
+    const cartUrl = isHttpUrl(answer.cartUrl) ? answer.cartUrl : fallbackUrl(id);
+    if (whole) {
+      const snapshot = await live(signal, session(id).get({ signal }));
+      const write = context.cartStorage.set(id);
+      me.writing = Promise.resolve(write).catch(() => void 0);
+      await live(signal, write);
+      box.set({
+        sessionId: id,
+        cartUrl,
+        cart: snapshot.cart,
+        status: "ready",
+        error: void 0
+      });
+      return;
+    }
+    box.set({ sessionId: id, cartUrl });
     let unsaved;
     try {
       const write = context.cartStorage.set(id);
@@ -799,11 +812,10 @@ function createController(home) {
         reset();
         return;
       }
-      const prior = box.get().sessionId;
       try {
-        await create(signal, options, items);
+        await create(signal, options, items, true);
       } catch (error) {
-        if (!signal.aborted && box.get().sessionId === prior) currency = before;
+        if (!signal.aborted) currency = before;
         throw error;
       }
     },
@@ -885,7 +897,7 @@ function useCart(options = {}) {
               { signal: callSignal }
             );
           } catch (error) {
-            const repriced = _chunkO2OYOK2Acjs.isCatalogError.call(void 0, error) && error.code === "cart_prices_changed" ? _optionalChain([error, 'access', _37 => _37.details, 'optionalAccess', _38 => _38.cart]) : void 0;
+            const repriced = _chunkZFUELHUUcjs.isCatalogError.call(void 0, error) && error.code === "cart_prices_changed" ? _optionalChain([error, 'access', _37 => _37.details, 'optionalAccess', _38 => _38.cart]) : void 0;
             if (!callSignal.aborted && typeof repriced === "object" && repriced !== null)
               controller.box.set({ cart: repriced });
             throw error;
@@ -905,7 +917,7 @@ function useCart(options = {}) {
         if (out === void 0)
           throw _nullishCoalesce(met, () => ( refuse("There is no cart to check out.")));
         if (!isHttpUrl(out.checkoutUrl))
-          throw new (0, _chunkO2OYOK2Acjs.CatalogError)({
+          throw new (0, _chunkZFUELHUUcjs.CatalogError)({
             code: "INVALID_RESPONSE",
             message: "Throttle answered a checkout URL that is not http or https.",
             statusCode: 200,
@@ -1003,4 +1015,4 @@ function useSubmitReview(handle) {
 
 
 
-exports.CatalogProvider = CatalogProvider; exports.SDK_VERSION = _chunkO2OYOK2Acjs.SDK_VERSION; exports.catalogQueryKey = catalogQueryKey; exports.createMemoryCartStorage = createMemoryCartStorage; exports.useCart = useCart; exports.useCatalog = useCatalog; exports.useCategories = useCategories; exports.useCollection = useCollection; exports.useConfig = useConfig; exports.useFilterValues = useFilterValues; exports.useProduct = useProduct; exports.useProducts = useProducts; exports.useRelated = useRelated; exports.useReviews = useReviews; exports.useSubmitReview = useSubmitReview; exports.useSuggest = useSuggest;
+exports.CatalogProvider = CatalogProvider; exports.SDK_VERSION = _chunkZFUELHUUcjs.SDK_VERSION; exports.catalogQueryKey = catalogQueryKey; exports.createMemoryCartStorage = createMemoryCartStorage; exports.useCart = useCart; exports.useCatalog = useCatalog; exports.useCategories = useCategories; exports.useCollection = useCollection; exports.useConfig = useConfig; exports.useFilterValues = useFilterValues; exports.useProduct = useProduct; exports.useProducts = useProducts; exports.useRelated = useRelated; exports.useReviews = useReviews; exports.useSubmitReview = useSubmitReview; exports.useSuggest = useSuggest;

package/dist/react.d.cts

@@ -57,7 +57,11 @@ type QueryResult<T> = {
 type QueryOptions<T> = {
     /** `false` makes no request; `data` stays `undefined`. */
     enabled?: boolean;
-    /** Shown at once and treated as fetched at mount (SSR hand-off). */
+    /**
+     * Shown at once (SSR hand-off). Treated as fetched at mount when the
+     * provider has no `customerKey`; under a signed-in customer it is
+     * revalidated at once, since a server render is usually anonymous (P6-R51).
+     */
     initialData?: T;
     /** Cached data younger than this is not fetched again; default `STALE_MS`. */
     staleTimeMs?: number;
@@ -132,7 +136,12 @@ type UseCartResult = CartState & {
     }): Promise<{
         checkoutUrl: string;
     }>;
-    /** A new cart with the current lines in `currency` (BC4); the old one is left to Throttle. */
+    /**
+     * A new cart with the current lines in `currency` (BC4); the old one is
+     * left to Throttle. It lands whole or not at all: if the new cart cannot be
+     * made, read back or saved, it rejects and the old cart, its stored id and
+     * the old currency stay (the unused new cart is left to Throttle).
+     */
     switchCurrency(currency: string): Promise<void>;
     /** Forgets the cart (no request). */
     clear(): Promise<void>;

package/dist/react.d.ts

@@ -57,7 +57,11 @@ type QueryResult<T> = {
 type QueryOptions<T> = {
     /** `false` makes no request; `data` stays `undefined`. */
     enabled?: boolean;
-    /** Shown at once and treated as fetched at mount (SSR hand-off). */
+    /**
+     * Shown at once (SSR hand-off). Treated as fetched at mount when the
+     * provider has no `customerKey`; under a signed-in customer it is
+     * revalidated at once, since a server render is usually anonymous (P6-R51).
+     */
     initialData?: T;
     /** Cached data younger than this is not fetched again; default `STALE_MS`. */
     staleTimeMs?: number;
@@ -132,7 +136,12 @@ type UseCartResult = CartState & {
     }): Promise<{
         checkoutUrl: string;
     }>;
-    /** A new cart with the current lines in `currency` (BC4); the old one is left to Throttle. */
+    /**
+     * A new cart with the current lines in `currency` (BC4); the old one is
+     * left to Throttle. It lands whole or not at all: if the new cart cannot be
+     * made, read back or saved, it rejects and the old cart, its stored id and
+     * the old currency stay (the unused new cart is left to Throttle).
+     */
     switchCurrency(currency: string): Promise<void>;
     /** Forgets the cart (no request). */
     clear(): Promise<void>;

package/dist/react.js

@@ -11,7 +11,7 @@ import {
   SUGGEST_MIN_CHARS,
   THROTTLE_CHECKOUT_URL,
   isCatalogError
-} from "./chunk-PSCFHVZZ.js";
+} from "./chunk-2PJXGAZF.js";
 import "./chunk-PKBMQBKP.js";
 
 // src/react/provider.tsx
@@ -49,13 +49,13 @@ function createStore(client, options = {}) {
     entry.snap = { ...entry.snap, ...patch };
     for (const listener of [...entry.subs]) listener();
   };
-  const touch = (key, initial) => {
+  const touch = (key, initial, stale = false) => {
     let entry = entries.get(key);
     if (entry !== void 0) {
       entries.delete(key);
     } else {
       entry = {
-        snap: initial === void 0 ? EMPTY : { ...EMPTY, data: initial, fetchedAt: now() },
+        snap: initial === void 0 ? EMPTY : { ...EMPTY, data: initial, fetchedAt: stale ? void 0 : now() },
         subs: /* @__PURE__ */ new Set()
       };
       for (const [oldKey, old] of entries) {
@@ -189,10 +189,10 @@ function createStore(client, options = {}) {
         });
       };
     },
-    get: (key, initial) => key === null ? EMPTY : (entries.get(key) ?? (initial === void 0 ? void 0 : touch(key, initial)))?.snap ?? EMPTY,
-    getServer(key, initial) {
+    get: (key, initial, stale) => key === null ? EMPTY : (entries.get(key) ?? (initial === void 0 ? void 0 : touch(key, initial, stale)))?.snap ?? EMPTY,
+    getServer(key, initial, stale) {
       if (key === null || initial === void 0) return EMPTY;
-      const entry = entries.get(key) ?? touch(key, initial);
+      const entry = entries.get(key) ?? touch(key, initial, stale);
       return entry.server ?? (entry.server = { ...EMPTY, data: initial });
     },
     fetch: fetchKey,
@@ -307,10 +307,11 @@ function useQuery(route, params, run, options = {}) {
     (listener) => key === null ? unsubscribe() : store.subscribe(key, listener),
     [store, key]
   );
+  const stale = customerKey !== null;
   const snap = useSyncExternalStore(
     subscribe,
-    () => store.get(key, initial),
-    () => store.getServer(key, initial)
+    () => store.get(key, initial, stale),
+    () => store.getServer(key, initial, stale)
   );
   const staleMs = options.staleTimeMs;
   useEffect2(() => {
@@ -578,7 +579,7 @@ function createController(home) {
     if (converted(error)) reset();
     else box.set({ sessionId: null, cartUrl: null });
   }
-  async function create(signal, options, items) {
+  async function create(signal, options, items, whole = false) {
     const context = ctx();
     const body = {
       items: [...items].map(([sku, quantity]) => ({ sku, quantity }))
@@ -602,10 +603,22 @@ function createController(home) {
       throw error;
     }
     const id = answer.sessionId;
-    box.set({
-      sessionId: id,
-      cartUrl: isHttpUrl(answer.cartUrl) ? answer.cartUrl : fallbackUrl(id)
-    });
+    const cartUrl = isHttpUrl(answer.cartUrl) ? answer.cartUrl : fallbackUrl(id);
+    if (whole) {
+      const snapshot = await live(signal, session(id).get({ signal }));
+      const write = context.cartStorage.set(id);
+      me.writing = Promise.resolve(write).catch(() => void 0);
+      await live(signal, write);
+      box.set({
+        sessionId: id,
+        cartUrl,
+        cart: snapshot.cart,
+        status: "ready",
+        error: void 0
+      });
+      return;
+    }
+    box.set({ sessionId: id, cartUrl });
     let unsaved;
     try {
       const write = context.cartStorage.set(id);
@@ -799,11 +812,10 @@ function createController(home) {
         reset();
         return;
       }
-      const prior = box.get().sessionId;
       try {
-        await create(signal, options, items);
+        await create(signal, options, items, true);
       } catch (error) {
-        if (!signal.aborted && box.get().sessionId === prior) currency = before;
+        if (!signal.aborted) currency = before;
         throw error;
       }
     },

package/dist/server.cjs

@@ -8,14 +8,14 @@
 
 
 
-var _chunkO2OYOK2Acjs = require('./chunk-O2OYOK2A.cjs');
+var _chunkZFUELHUUcjs = require('./chunk-ZFUELHUU.cjs');
 require('./chunk-ETV4XYOV.cjs');
 
 // src/server/tags.ts
 function catalogTags(route, handle) {
-  const tags = [_chunkO2OYOK2Acjs.CACHE_TAG, `${_chunkO2OYOK2Acjs.CACHE_TAG}:${route}`];
-  if (handle !== void 0) tags.push(`${_chunkO2OYOK2Acjs.CACHE_TAG}:${route}:${handle}`);
-  return tags.filter((tag) => tag.length <= _chunkO2OYOK2Acjs.TAG_MAX_CHARS);
+  const tags = [_chunkZFUELHUUcjs.CACHE_TAG, `${_chunkZFUELHUUcjs.CACHE_TAG}:${route}`];
+  if (handle !== void 0) tags.push(`${_chunkZFUELHUUcjs.CACHE_TAG}:${route}:${handle}`);
+  return tags.filter((tag) => tag.length <= _chunkZFUELHUUcjs.TAG_MAX_CHARS);
 }
 function decode(segment) {
   try {
@@ -72,9 +72,9 @@ function serverInit(url, init, storefront, revalidate, extraTags) {
 }
 function createServerCatalogClient(options) {
   const { next, ...rest } = options;
-  const revalidate = _nullishCoalesce(_optionalChain([next, 'optionalAccess', _ => _.revalidate]), () => ( _chunkO2OYOK2Acjs.DEFAULT_REVALIDATE_S));
+  const revalidate = _nullishCoalesce(_optionalChain([next, 'optionalAccess', _ => _.revalidate]), () => ( _chunkZFUELHUUcjs.DEFAULT_REVALIDATE_S));
   const extraTags = _nullishCoalesce(_optionalChain([next, 'optionalAccess', _2 => _2.tags]), () => ( []));
-  const storefront = `${(_nullishCoalesce(rest.baseUrl, () => ( _chunkO2OYOK2Acjs.DEFAULT_BASE_URL))).replace(/\/+$/u, "")}/v1/storefront/`;
+  const storefront = `${(_nullishCoalesce(rest.baseUrl, () => ( _chunkZFUELHUUcjs.DEFAULT_BASE_URL))).replace(/\/+$/u, "")}/v1/storefront/`;
   const base = rest.fetch;
   const serverFetch = (input, init = {}) => {
     const out = serverInit(
@@ -86,7 +86,7 @@ function createServerCatalogClient(options) {
     );
     return base !== void 0 ? base(input, out) : globalThis.fetch(input, out);
   };
-  return _chunkO2OYOK2Acjs.createCatalogClient.call(void 0, {
+  return _chunkZFUELHUUcjs.createCatalogClient.call(void 0, {
     ...rest,
     fetch: serverFetch
   });
@@ -106,16 +106,16 @@ async function syncCatalogGeneration(input) {
 
 // src/server/paging.ts
 function bounds(opts) {
-  const pageSize = _nullishCoalesce(opts.pageSize, () => ( _chunkO2OYOK2Acjs.LIST_PAGE_SIZE));
-  const max = _nullishCoalesce(opts.max, () => ( _chunkO2OYOK2Acjs.LIST_MAX_HANDLES));
-  if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > _chunkO2OYOK2Acjs.LIST_PAGE_SIZE)
+  const pageSize = _nullishCoalesce(opts.pageSize, () => ( _chunkZFUELHUUcjs.LIST_PAGE_SIZE));
+  const max = _nullishCoalesce(opts.max, () => ( _chunkZFUELHUUcjs.LIST_MAX_HANDLES));
+  if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > _chunkZFUELHUUcjs.LIST_PAGE_SIZE)
     throw invalid("pageSize must be a whole number from 1 to 100.");
   if (!Number.isInteger(max) || max < 0)
     throw invalid("max must be a whole number of 0 or more.");
   return { pageSize, max };
 }
 function invalid(message) {
-  return new (0, _chunkO2OYOK2Acjs.CatalogError)({
+  return new (0, _chunkZFUELHUUcjs.CatalogError)({
     code: "INVALID_REQUEST",
     message,
     statusCode: 0,
@@ -207,4 +207,4 @@ async function listAllCategoryHandles(client, opts = {}) {
 
 
 
-exports.SDK_VERSION = _chunkO2OYOK2Acjs.SDK_VERSION; exports.catalogTags = catalogTags; exports.createServerCatalogClient = createServerCatalogClient; exports.listAllCategoryHandles = listAllCategoryHandles; exports.listAllCollectionHandles = listAllCollectionHandles; exports.listAllProductHandles = listAllProductHandles; exports.staticProductParams = staticProductParams; exports.syncCatalogGeneration = syncCatalogGeneration;
+exports.SDK_VERSION = _chunkZFUELHUUcjs.SDK_VERSION; exports.catalogTags = catalogTags; exports.createServerCatalogClient = createServerCatalogClient; exports.listAllCategoryHandles = listAllCategoryHandles; exports.listAllCollectionHandles = listAllCollectionHandles; exports.listAllProductHandles = listAllProductHandles; exports.staticProductParams = staticProductParams; exports.syncCatalogGeneration = syncCatalogGeneration;

package/dist/server.js

@@ -8,7 +8,7 @@ import {
   SDK_VERSION,
   TAG_MAX_CHARS,
   createCatalogClient
-} from "./chunk-PSCFHVZZ.js";
+} from "./chunk-2PJXGAZF.js";
 import "./chunk-PKBMQBKP.js";
 
 // src/server/tags.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usethrottle/catalog",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Storefront SDK for the Throttle Product Catalog: a typed client, React hooks, server helpers and URL helpers.",
   "license": "MIT",
   "repository": {