@usethrottle/catalog 1.2.0 → 1.4.0

package/dist/react.js

@@ -10,19 +10,22 @@ import {
   useConfig,
   useCustomerKey,
   useFilterValues,
+  useGenerationWatch,
   useProduct,
   useProducts,
   useRelated,
   useReviews,
+  useStorefrontSettings,
   useSuggest
-} from "./chunk-JNBKKAMP.js";
+} from "./chunk-3FX2HISB.js";
 import {
   CatalogError,
   RateLimitedError,
   SDK_VERSION,
   THROTTLE_CHECKOUT_URL,
+  formatMoney,
   isCatalogError
-} from "./chunk-55G4ZTD5.js";
+} from "./chunk-VJHA7J7B.js";
 import "./chunk-PKBMQBKP.js";
 
 // src/react/use-cart.ts
@@ -99,7 +102,8 @@ var EMPTY = {
   cartUrl: null,
   status: "idle",
   error: void 0,
-  pending: false
+  pending: false,
+  warnings: []
 };
 var ENDED = /* @__PURE__ */ new Set([
   "cart_session_expired",
@@ -132,6 +136,7 @@ function createController(home) {
     moving: void 0,
     unremoved: false,
     reads: /* @__PURE__ */ new Map(),
+    slots: /* @__PURE__ */ new Set(),
     abort: new AbortController(),
     writing: Promise.resolve(),
     tail: Promise.resolve()
@@ -168,7 +173,7 @@ function createController(home) {
       if (signal.aborted) throw error;
     }
   }
-  async function find(signal, wantedCurrency) {
+  async function find(signal, wantedCurrency, strict = false) {
     const source = ctx().customerCart;
     if (source === void 0 || wantedCurrency === void 0) return null;
     const asked = wantedCurrency.toUpperCase();
@@ -176,9 +181,27 @@ function createController(home) {
       const found = await live(signal, source.getOpenCart({ currency: asked }));
       return found !== null && found.currency.toUpperCase() === asked ? found : null;
     } catch (error) {
-      if (signal.aborted) throw error;
+      if (signal.aborted || strict) throw error;
+      return null;
+    }
+  }
+  async function findTarget(signal, code, storage) {
+    if (resuming()) {
+      const found = await find(signal, code, true);
+      return found === null ? null : { id: found.sessionId, cartUrl: fallbackUrl(found.sessionId) };
+    }
+    if (ctx().customerKey !== null || storage.getFor === void 0) return null;
+    const id = await live(signal, storage.getFor(code));
+    if (id === null || id === "") return null;
+    try {
+      const answer = await live(signal, session(id).get({ signal }));
+      if (answer.cart.status !== "open" || answer.cart.currency.toUpperCase() !== code)
+        return null;
+    } catch (error) {
+      if (signal.aborted || !ended(error)) throw error;
       return null;
     }
+    return { id, cartUrl: fallbackUrl(id) };
   }
   async function findOnce(signal, storage) {
     var _a2;
@@ -197,13 +220,21 @@ function createController(home) {
     }
     if (found !== null) await soft(signal, () => adopt(signal, found, storage));
   }
+  async function forgetSlots(storage, codes) {
+    for (const code of codes)
+      if (storage.removeFor !== void 0) await storage.removeFor(code);
+      else await storage.setFor?.(code, "");
+  }
+  async function save(signal, storage, id) {
+    const write = storage.set(id);
+    me.writing = Promise.resolve(write).catch(() => void 0);
+    await live(signal, write);
+  }
   async function adopt(signal, found, storage) {
     const id = found.sessionId;
     const answer = await live(signal, session(id).get({ signal }));
     me.reads.set(id, Date.now());
-    const write = storage.set(id);
-    me.writing = Promise.resolve(write).catch(() => void 0);
-    await live(signal, write);
+    await save(signal, storage, id);
     box.set({
       sessionId: id,
       cartUrl: fallbackUrl(id),
@@ -229,7 +260,7 @@ function createController(home) {
     if (converted(error)) reset();
     else box.set({ sessionId: null, cartUrl: null });
   }
-  async function create(signal, options, items, whole = false) {
+  async function start(signal, options, items) {
     const context = ctx();
     const body = {
       items: [...items].map(([sku, quantity]) => ({ sku, quantity }))
@@ -253,28 +284,18 @@ function createController(home) {
       throw error;
     }
     const id = answer.sessionId;
-    const cartUrl = isHttpUrl(answer.cartUrl) ? answer.cartUrl : fallbackUrl(id);
-    if (whole) {
-      const snapshot = await live(signal, session(id).get({ signal }));
-      me.reads.set(id, Date.now());
-      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;
-    }
+    return {
+      id,
+      cartUrl: isHttpUrl(answer.cartUrl) ? answer.cartUrl : fallbackUrl(id)
+    };
+  }
+  async function create(signal, options, items) {
+    const storage = ctx().cartStorage;
+    const { id, cartUrl } = await start(signal, options, items);
     box.set({ sessionId: id, cartUrl });
     let unsaved;
     try {
-      const write = context.cartStorage.set(id);
-      me.writing = Promise.resolve(write).catch(() => void 0);
-      await live(signal, write);
+      await save(signal, storage, id);
     } catch (error) {
       if (signal.aborted) throw error;
       unsaved = error;
@@ -432,6 +453,11 @@ function createController(home) {
       if (signal.aborted) return;
       if (fresh && !me.unremoved) await restore(signal, guest, false);
       if (signal.aborted) return;
+      const codes = new Set(me.slots);
+      const shown = box.get().cart?.currency;
+      if (shown !== void 0) codes.add(shown.toUpperCase());
+      await live(signal, forgetSlots(guest, codes));
+      me.slots.clear();
       const id = box.get().sessionId;
       if (id === null) {
         if (box.get().cart === null && !me.unremoved) {
@@ -480,9 +506,15 @@ function createController(home) {
     const outgoing = prior ?? me.seen;
     const left = me.moving;
     me.moving = void 0;
+    const slots = [...me.slots];
+    me.slots.clear();
     const remove = async () => {
       await outgoing.remove();
-      if (left !== void 0 && left !== outgoing) await left.remove();
+      await forgetSlots(outgoing, slots);
+      if (left !== void 0 && left !== outgoing) {
+        await left.remove();
+        await forgetSlots(left, slots);
+      }
     };
     me.tail = me.writing.then(remove).catch(remove).then(
       () => {
@@ -508,6 +540,7 @@ function createController(home) {
     mutate,
     create,
     session,
+    wanted,
     async switchCurrency(signal, options, next) {
       checkPause(ctx().store);
       const storage = ctx().cartStorage;
@@ -524,21 +557,60 @@ function createController(home) {
       }
       const before = currency;
       currency = next;
-      const items = itemsOf(box.get().cart);
-      if (items.size === 0) {
-        if (box.get().sessionId !== null) await live(signal, storage.remove());
-        reset();
+      const code = next.toUpperCase();
+      const from = box.get().sessionId;
+      const cart = box.get().cart;
+      const items = itemsOf(cart);
+      if (from === null || items.size === 0) {
+        if (from !== null) await live(signal, storage.remove());
+        if (items.size === 0) reset();
         return;
       }
+      if (cart?.currency.toUpperCase() === code) return;
+      let target;
+      let moved;
       try {
-        await create(signal, options, items, true);
+        target = await findTarget(signal, code, storage) ?? await start(signal, options, /* @__PURE__ */ new Map());
+        moved = await live(signal, session(target.id).absorb(from, { signal }));
       } catch (error) {
         if (!signal.aborted) currency = before;
         throw error;
       }
+      me.reads.set(target.id, Date.now());
+      box.set({
+        sessionId: target.id,
+        cartUrl: target.cartUrl,
+        cart: moved.cart,
+        status: "ready",
+        error: void 0,
+        warnings: moved.warnings.filter(
+          (warning) => warning.code !== "lines_stale"
+        )
+      });
+      let unsaved;
+      try {
+        await save(signal, storage, target.id);
+      } catch (error) {
+        if (signal.aborted) throw error;
+        unsaved = error;
+        try {
+          await live(signal, storage.remove());
+        } catch (failure) {
+          if (signal.aborted) throw failure;
+        }
+      }
+      if (ctx().customerKey === null && storage.setFor !== void 0) {
+        me.slots.add(code);
+        await live(signal, storage.setFor(code, target.id));
+      }
+      if (unsaved !== void 0) throw unsaved;
     },
     async clear(signal) {
-      await live(signal, ctx().cartStorage.remove());
+      const storage = ctx().cartStorage;
+      const shown = box.get().cart?.currency;
+      await live(signal, storage.remove());
+      if (shown !== void 0)
+        await live(signal, storage.removeFor?.(shown.toUpperCase()));
       currency = void 0;
       reset();
     }
@@ -656,7 +728,9 @@ function useCart(options = {}) {
   }, [controller, home, currency, locale]);
   const owner = controller.owner();
   const view = owner !== void 0 && owner !== null && owner !== customerKey ? { ...EMPTY, pending: state.pending } : state;
-  return { ...view, ...actions };
+  const shownCurrency = view.cart?.currency ?? controller.wanted(options) ?? "";
+  const format = (minor) => formatMoney(minor, shownCurrency);
+  return { ...view, ...actions, format };
 }
 
 // src/react/use-submit-review.ts
@@ -732,10 +806,12 @@ export {
   useConfig,
   useCustomerKey,
   useFilterValues,
+  useGenerationWatch,
   useProduct,
   useProducts,
   useRelated,
   useReviews,
+  useStorefrontSettings,
   useSubmitReview,
   useSuggest
 };

package/dist/server.cjs

@@ -8,91 +8,79 @@
 
 
 
+var _chunkPZ3SFYH4cjs = require('./chunk-PZ3SFYH4.cjs');
+
+
+
 
-var _chunkB2DYAHNRcjs = require('./chunk-B2DYAHNR.cjs');
-require('./chunk-ETV4XYOV.cjs');
 
-// src/server/tags.ts
-function catalogTags(route, handle) {
-  const tags = [_chunkB2DYAHNRcjs.CACHE_TAG, `${_chunkB2DYAHNRcjs.CACHE_TAG}:${route}`];
-  if (handle !== void 0) tags.push(`${_chunkB2DYAHNRcjs.CACHE_TAG}:${route}:${handle}`);
-  return tags.filter((tag) => tag.length <= _chunkB2DYAHNRcjs.TAG_MAX_CHARS);
-}
-function decode(segment) {
-  try {
-    return decodeURIComponent(segment);
-  } catch (e) {
-    return segment;
-  }
-}
-function tagsForUrl(url, storefront) {
-  const path = _nullishCoalesce(url.split(/[?#]/u, 1)[0], () => ( ""));
-  if (!path.startsWith(storefront)) return null;
-  const parts = path.slice(storefront.length).split("/");
-  if (parts.length > 3) return null;
-  const [first, segment, sub] = parts;
-  if (segment === void 0) {
-    switch (first) {
-      case "config":
-      case "products":
-      case "categories":
-      case "tags":
-      case "collections":
-      case "suggest":
-        return catalogTags(first);
-      default:
-        return null;
-    }
-  }
-  const handle = decode(segment);
-  if (handle === "") return null;
-  switch (first) {
-    case "filters":
-      return sub === "values" ? catalogTags("filters") : null;
-    case "products":
-      if (sub === "related" || sub === "reviews")
-        return catalogTags(sub, handle);
-      return sub === void 0 ? catalogTags("product", handle) : null;
-    case "categories":
-      return sub === void 0 ? catalogTags("category", handle) : null;
-    case "collections":
-      return sub === void 0 ? catalogTags("collection", handle) : null;
-    default:
-      return null;
-  }
-}
+
+
+
+var _chunkJ2GHGQY6cjs = require('./chunk-J2GHGQY6.cjs');
+require('./chunk-ETV4XYOV.cjs');
 
 // src/server/client.ts
-function serverInit(url, init, storefront, revalidate, extraTags) {
+function serverInit(url, init, storefront, policies, extraTags) {
   const { next, ...rest } = init;
-  const tags = rest.method === "GET" ? tagsForUrl(url, storefront) : null;
+  const tags = rest.method === "GET" ? _chunkPZ3SFYH4cjs.tagsForUrl.call(void 0, url, storefront) : null;
   if (tags === null || rest.cache === "no-store")
     return { ...rest, cache: "no-store" };
   if (next !== void 0) return init;
-  return { ...rest, next: { revalidate, tags: [...tags, ...extraTags] } };
+  const kind = _chunkPZ3SFYH4cjs.cacheKindForPath.call(void 0, url.slice(storefront.length));
+  const policy = kind === null ? "no-store" : policies(kind);
+  if (policy === "no-store") return { ...rest, cache: "no-store" };
+  return {
+    ...rest,
+    next: { revalidate: policy.revalidate, tags: [...tags, ...extraTags] }
+  };
 }
 function createServerCatalogClient(options) {
   const {
     next,
+    cachePolicy,
+    floorKey: namedFloorKey,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars -- dropped on purpose (P8-R21)
     keyInQuery: _ignored,
     ...rest
   } = options;
-  const revalidate = _nullishCoalesce(_optionalChain([next, 'optionalAccess', _ => _.revalidate]), () => ( _chunkB2DYAHNRcjs.DEFAULT_REVALIDATE_S));
+  const named = /* @__PURE__ */ new Map();
+  for (const [kind, policy] of Object.entries(_nullishCoalesce(cachePolicy, () => ( {}))))
+    if (policy !== void 0)
+      named.set(kind, _chunkPZ3SFYH4cjs.policyToNext.call(void 0, policy));
+  const policies = (kind) => _nullishCoalesce(named.get(kind), () => ( (_optionalChain([next, 'optionalAccess', _ => _.revalidate]) === void 0 ? _chunkPZ3SFYH4cjs.policyToNext.call(void 0, _chunkPZ3SFYH4cjs.DEFAULT_CACHE_POLICY[kind]) : { revalidate: next.revalidate })));
+  const floorKey = _nullishCoalesce(namedFloorKey, () => ( rest.publishableKey));
   const extraTags = _nullishCoalesce(_optionalChain([next, 'optionalAccess', _2 => _2.tags]), () => ( []));
-  const storefront = `${(_nullishCoalesce(rest.baseUrl, () => ( _chunkB2DYAHNRcjs.DEFAULT_BASE_URL))).replace(/\/+$/u, "")}/v1/storefront/`;
+  const storefront = `${(_nullishCoalesce(rest.baseUrl, () => ( _chunkJ2GHGQY6cjs.DEFAULT_BASE_URL))).replace(/\/+$/u, "")}/v1/storefront/`;
   const base = rest.fetch;
   const serverFetch = (input, init = {}) => {
+    let target = String(input);
+    const isConfig = init.method === "GET" && target.startsWith(storefront) && _optionalChain([_chunkPZ3SFYH4cjs.storefrontRoute.call(void 0, target.slice(storefront.length)), 'optionalAccess', _3 => _3.route]) === "config";
+    const floor = isConfig ? _chunkPZ3SFYH4cjs.pendingMinGeneration.call(void 0, floorKey) : void 0;
+    if (floor !== void 0 && !target.includes("minGeneration="))
+      target += `${target.includes("?") ? "&" : "?"}minGeneration=${floor}`;
     const out = serverInit(
-      String(input),
+      target,
       init,
       storefront,
-      revalidate,
+      policies,
       extraTags
     );
-    return base !== void 0 ? base(input, out) : globalThis.fetch(input, out);
+    const answer = base !== void 0 ? base(target, out) : globalThis.fetch(target, out);
+    if (floor === void 0) return answer;
+    return answer.then(async (response) => {
+      if (response.ok)
+        try {
+          _chunkPZ3SFYH4cjs.observeGeneration.call(void 0, 
+            (await response.clone().json()).generation,
+            floorKey
+          );
+        } catch (e) {
+        }
+      return response;
+    });
   };
-  return _chunkB2DYAHNRcjs.createCatalogClient.call(void 0, {
+  return _chunkJ2GHGQY6cjs.createCatalogClient.call(void 0, {
     ...rest,
     fetch: serverFetch
   });
@@ -112,16 +100,16 @@ async function syncCatalogGeneration(input) {
 
 // src/server/paging.ts
 function bounds(opts) {
-  const pageSize = _nullishCoalesce(opts.pageSize, () => ( _chunkB2DYAHNRcjs.LIST_PAGE_SIZE));
-  const max = _nullishCoalesce(opts.max, () => ( _chunkB2DYAHNRcjs.LIST_MAX_HANDLES));
-  if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > _chunkB2DYAHNRcjs.LIST_PAGE_SIZE)
+  const pageSize = _nullishCoalesce(opts.pageSize, () => ( _chunkJ2GHGQY6cjs.LIST_PAGE_SIZE));
+  const max = _nullishCoalesce(opts.max, () => ( _chunkJ2GHGQY6cjs.LIST_MAX_HANDLES));
+  if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > _chunkJ2GHGQY6cjs.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, _chunkB2DYAHNRcjs.CatalogError)({
+  return new (0, _chunkJ2GHGQY6cjs.CatalogError)({
     code: "INVALID_REQUEST",
     message,
     statusCode: 0,
@@ -191,7 +179,7 @@ function listAllCollectionHandles(client, opts = {}) {
 }
 async function listAllCategoryHandles(client, opts = {}) {
   const { categories } = await client.categories.tree({
-    depth: _chunkB2DYAHNRcjs.CATEGORY_TREE_MAX_DEPTH,
+    depth: _chunkJ2GHGQY6cjs.CATEGORY_TREE_MAX_DEPTH,
     ...call(opts.signal)
   });
   const out = [];
@@ -213,4 +201,8 @@ async function listAllCategoryHandles(client, opts = {}) {
 
 
 
-exports.SDK_VERSION = _chunkB2DYAHNRcjs.SDK_VERSION; exports.catalogTags = catalogTags; exports.createServerCatalogClient = createServerCatalogClient; exports.listAllCategoryHandles = listAllCategoryHandles; exports.listAllCollectionHandles = listAllCollectionHandles; exports.listAllProductHandles = listAllProductHandles; exports.staticProductParams = staticProductParams; exports.syncCatalogGeneration = syncCatalogGeneration;
+
+
+
+
+exports.DEFAULT_CACHE_POLICY = _chunkPZ3SFYH4cjs.DEFAULT_CACHE_POLICY; exports.SDK_VERSION = _chunkJ2GHGQY6cjs.SDK_VERSION; exports.cacheKindForPath = _chunkPZ3SFYH4cjs.cacheKindForPath; exports.catalogTags = _chunkPZ3SFYH4cjs.catalogTags; exports.createServerCatalogClient = createServerCatalogClient; exports.listAllCategoryHandles = listAllCategoryHandles; exports.listAllCollectionHandles = listAllCollectionHandles; exports.listAllProductHandles = listAllProductHandles; exports.policyToNext = _chunkPZ3SFYH4cjs.policyToNext; exports.scopesToTags = _chunkPZ3SFYH4cjs.scopesToTags; exports.staticProductParams = staticProductParams; exports.syncCatalogGeneration = syncCatalogGeneration;

package/dist/server.d.cts

@@ -1,11 +1,48 @@
 export { S as SDK_VERSION } from './version-ev3p03v2.cjs';
 import { CatalogClient } from './index.cjs';
 import { CatalogClientOptions, NextFetchOptions } from './index.cjs';
-import './contract-types-BPSzY_Co.cjs';
+import '@usethrottle/money';
+import './contract-types-D2-SSPM9.cjs';
+
+/** A kind of storefront data, each with its own cache policy. */
+type CacheKind = 'settings' | 'navigation' | 'pages' | 'listings' | 'facets' | 'product' | 'related' | 'reviews' | 'search';
+/**
+ * How long a read is cached: `'until-changed'` (an hour's safety TTL, cleared
+ * sooner by its cache tags), `'no-store'`, or a duration such as `'90s'` or
+ * `'5m'`.
+ */
+type CachePolicy = 'until-changed' | 'no-store' | `${number}s` | `${number}m`;
+declare const DEFAULT_CACHE_POLICY: Readonly<Record<CacheKind, CachePolicy>>;
+/** The kind of data a storefront path serves, or `null` when it is not a cacheable catalog read. */
+declare function cacheKindForPath(path: string): CacheKind | null;
+/**
+ * The `fetch` cache option a policy means: `{ revalidate }` for Next, or
+ * `'no-store'` (also for a zero duration). A string that is not a policy is
+ * `INVALID_REQUEST`.
+ */
+declare function policyToNext(policy: CachePolicy): {
+    revalidate: number | false;
+} | 'no-store';
 
 type ServerCatalogClientOptions = Omit<CatalogClientOptions, 'keyInQuery'> & {
-    /** `revalidate` defaults to 60 seconds; `tags` are appended to the route's own. */
+    /**
+     * `revalidate` replaces the default of every kind of read that
+     * `cachePolicy` does not name; `tags` are appended to the route's own.
+     */
     next?: NextFetchOptions;
+    /**
+     * How long each kind of read is cached, over the defaults (`settings`,
+     * `navigation`, `pages` and `product` `'until-changed'`, the rest `'60s'`).
+     * Navigation arrives inside `/config`, so its policy follows `settings`.
+     * A customer-token, cart or preview request is `no-store` regardless.
+     */
+    cachePolicy?: Partial<Record<CacheKind, CachePolicy>>;
+    /**
+     * Names this store's generation floor (see `noteMinGeneration`). Defaults
+     * to `publishableKey`: one client per store needs nothing. Pass the same
+     * value to `createRevalidateHandler({ floorKey })`.
+     */
+    floorKey?: string;
 };
 /**
  * `createCatalogClient` for Next.js and other SSR: every catalog storefront
@@ -18,14 +55,25 @@ type ServerCatalogClientOptions = Omit<CatalogClientOptions, 'keyInQuery'> & {
 declare function createServerCatalogClient(options: ServerCatalogClientOptions): CatalogClient;
 
 /**
- * The cache tags of one storefront route (P6-R17): always `throttle-catalog`
- * and `throttle-catalog:<route>`, plus `throttle-catalog:<route>:<handle>`
- * for a handle route. Next refuses a tag over 256 characters, so one is
- * dropped. `route` is one of `config`, `products`, `filters`, `product`,
- * `related`, `categories`, `category`, `tags`, `collections`, `collection`,
- * `suggest`, `reviews`.
+ * The cache tags of one storefront route (P6-R17): always `throttle-catalog`,
+ * the route's family (`throttle-catalog:config`, `:pages` or `:data`) and
+ * `throttle-catalog:<route>`, plus `throttle-catalog:<route>:<handle>` for a
+ * handle route. Next refuses a tag over 256 characters, so one is dropped.
+ * `route` is one of `config`, `products`, `filters`, `product`, `related`,
+ * `categories`, `category`, `tags`, `collections`, `collection`, `suggest`,
+ * `reviews`, `pages`, `page`.
  */
 declare function catalogTags(route: string, handle?: string): string[];
+/**
+ * The cache tags a storefront change notice clears, for the revalidate
+ * handler and any custom receiver. `settings` and `navigation` clear
+ * `throttle-catalog:config`; `filters` that and `:data`; `pages`
+ * `:pages`; `taxonomy` and `catalog` `:data`; `product:<h>`, `collection:<h>`
+ * and `category:<h>` their handle tag and `:data`; `reviews:<h>` the
+ * reviews and product handle tags. Anything else clears `:data`. In order,
+ * without repeats; a tag over 256 characters is dropped, as in `catalogTags`.
+ */
+declare function scopesToTags(scopes: readonly string[]): string[];
 
 type SyncCatalogGenerationInput = {
     client: CatalogClient;
@@ -76,5 +124,5 @@ declare function listAllCategoryHandles(client: CatalogClient, opts?: {
     signal?: AbortSignal;
 }): Promise<string[]>;
 
-export { catalogTags, createServerCatalogClient, listAllCategoryHandles, listAllCollectionHandles, listAllProductHandles, staticProductParams, syncCatalogGeneration };
-export type { ListHandlesOptions, ServerCatalogClientOptions, SyncCatalogGenerationInput };
+export { DEFAULT_CACHE_POLICY, cacheKindForPath, catalogTags, createServerCatalogClient, listAllCategoryHandles, listAllCollectionHandles, listAllProductHandles, policyToNext, scopesToTags, staticProductParams, syncCatalogGeneration };
+export type { CacheKind, CachePolicy, ListHandlesOptions, ServerCatalogClientOptions, SyncCatalogGenerationInput };

package/dist/server.d.ts

@@ -1,11 +1,48 @@
 export { S as SDK_VERSION } from './version-ev3p03v2.js';
 import { CatalogClient } from './index.js';
 import { CatalogClientOptions, NextFetchOptions } from './index.js';
-import './contract-types-BPSzY_Co.js';
+import '@usethrottle/money';
+import './contract-types-D2-SSPM9.js';
+
+/** A kind of storefront data, each with its own cache policy. */
+type CacheKind = 'settings' | 'navigation' | 'pages' | 'listings' | 'facets' | 'product' | 'related' | 'reviews' | 'search';
+/**
+ * How long a read is cached: `'until-changed'` (an hour's safety TTL, cleared
+ * sooner by its cache tags), `'no-store'`, or a duration such as `'90s'` or
+ * `'5m'`.
+ */
+type CachePolicy = 'until-changed' | 'no-store' | `${number}s` | `${number}m`;
+declare const DEFAULT_CACHE_POLICY: Readonly<Record<CacheKind, CachePolicy>>;
+/** The kind of data a storefront path serves, or `null` when it is not a cacheable catalog read. */
+declare function cacheKindForPath(path: string): CacheKind | null;
+/**
+ * The `fetch` cache option a policy means: `{ revalidate }` for Next, or
+ * `'no-store'` (also for a zero duration). A string that is not a policy is
+ * `INVALID_REQUEST`.
+ */
+declare function policyToNext(policy: CachePolicy): {
+    revalidate: number | false;
+} | 'no-store';
 
 type ServerCatalogClientOptions = Omit<CatalogClientOptions, 'keyInQuery'> & {
-    /** `revalidate` defaults to 60 seconds; `tags` are appended to the route's own. */
+    /**
+     * `revalidate` replaces the default of every kind of read that
+     * `cachePolicy` does not name; `tags` are appended to the route's own.
+     */
     next?: NextFetchOptions;
+    /**
+     * How long each kind of read is cached, over the defaults (`settings`,
+     * `navigation`, `pages` and `product` `'until-changed'`, the rest `'60s'`).
+     * Navigation arrives inside `/config`, so its policy follows `settings`.
+     * A customer-token, cart or preview request is `no-store` regardless.
+     */
+    cachePolicy?: Partial<Record<CacheKind, CachePolicy>>;
+    /**
+     * Names this store's generation floor (see `noteMinGeneration`). Defaults
+     * to `publishableKey`: one client per store needs nothing. Pass the same
+     * value to `createRevalidateHandler({ floorKey })`.
+     */
+    floorKey?: string;
 };
 /**
  * `createCatalogClient` for Next.js and other SSR: every catalog storefront
@@ -18,14 +55,25 @@ type ServerCatalogClientOptions = Omit<CatalogClientOptions, 'keyInQuery'> & {
 declare function createServerCatalogClient(options: ServerCatalogClientOptions): CatalogClient;
 
 /**
- * The cache tags of one storefront route (P6-R17): always `throttle-catalog`
- * and `throttle-catalog:<route>`, plus `throttle-catalog:<route>:<handle>`
- * for a handle route. Next refuses a tag over 256 characters, so one is
- * dropped. `route` is one of `config`, `products`, `filters`, `product`,
- * `related`, `categories`, `category`, `tags`, `collections`, `collection`,
- * `suggest`, `reviews`.
+ * The cache tags of one storefront route (P6-R17): always `throttle-catalog`,
+ * the route's family (`throttle-catalog:config`, `:pages` or `:data`) and
+ * `throttle-catalog:<route>`, plus `throttle-catalog:<route>:<handle>` for a
+ * handle route. Next refuses a tag over 256 characters, so one is dropped.
+ * `route` is one of `config`, `products`, `filters`, `product`, `related`,
+ * `categories`, `category`, `tags`, `collections`, `collection`, `suggest`,
+ * `reviews`, `pages`, `page`.
  */
 declare function catalogTags(route: string, handle?: string): string[];
+/**
+ * The cache tags a storefront change notice clears, for the revalidate
+ * handler and any custom receiver. `settings` and `navigation` clear
+ * `throttle-catalog:config`; `filters` that and `:data`; `pages`
+ * `:pages`; `taxonomy` and `catalog` `:data`; `product:<h>`, `collection:<h>`
+ * and `category:<h>` their handle tag and `:data`; `reviews:<h>` the
+ * reviews and product handle tags. Anything else clears `:data`. In order,
+ * without repeats; a tag over 256 characters is dropped, as in `catalogTags`.
+ */
+declare function scopesToTags(scopes: readonly string[]): string[];
 
 type SyncCatalogGenerationInput = {
     client: CatalogClient;
@@ -76,5 +124,5 @@ declare function listAllCategoryHandles(client: CatalogClient, opts?: {
     signal?: AbortSignal;
 }): Promise<string[]>;
 
-export { catalogTags, createServerCatalogClient, listAllCategoryHandles, listAllCollectionHandles, listAllProductHandles, staticProductParams, syncCatalogGeneration };
-export type { ListHandlesOptions, ServerCatalogClientOptions, SyncCatalogGenerationInput };
+export { DEFAULT_CACHE_POLICY, cacheKindForPath, catalogTags, createServerCatalogClient, listAllCategoryHandles, listAllCollectionHandles, listAllProductHandles, policyToNext, scopesToTags, staticProductParams, syncCatalogGeneration };
+export type { CacheKind, CachePolicy, ListHandlesOptions, ServerCatalogClientOptions, SyncCatalogGenerationInput };