@usethrottle/catalog 1.3.0 → 1.4.0

package/dist/server.d.cts

@@ -2,11 +2,47 @@ export { S as SDK_VERSION } from './version-ev3p03v2.cjs';
 import { CatalogClient } from './index.cjs';
 import { CatalogClientOptions, NextFetchOptions } from './index.cjs';
 import '@usethrottle/money';
-import './contract-types-BRyonOYH.cjs';
+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
@@ -19,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;
@@ -77,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

@@ -2,11 +2,47 @@ export { S as SDK_VERSION } from './version-ev3p03v2.js';
 import { CatalogClient } from './index.js';
 import { CatalogClientOptions, NextFetchOptions } from './index.js';
 import '@usethrottle/money';
-import './contract-types-BRyonOYH.js';
+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
@@ -19,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;
@@ -77,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.js

@@ -1,96 +1,84 @@
 import {
-  CACHE_TAG,
+  DEFAULT_CACHE_POLICY,
+  cacheKindForPath,
+  catalogTags,
+  observeGeneration,
+  pendingMinGeneration,
+  policyToNext,
+  scopesToTags,
+  storefrontRoute,
+  tagsForUrl
+} from "./chunk-SN6STYPW.js";
+import {
   CATEGORY_TREE_MAX_DEPTH,
   CatalogError,
   DEFAULT_BASE_URL,
-  DEFAULT_REVALIDATE_S,
   LIST_MAX_HANDLES,
   LIST_PAGE_SIZE,
   SDK_VERSION,
-  TAG_MAX_CHARS,
   createCatalogClient
-} from "./chunk-3DLH56OX.js";
+} from "./chunk-VJHA7J7B.js";
 import "./chunk-PKBMQBKP.js";
 
-// src/server/tags.ts
-function catalogTags(route, handle) {
-  const tags = [CACHE_TAG, `${CACHE_TAG}:${route}`];
-  if (handle !== void 0) tags.push(`${CACHE_TAG}:${route}:${handle}`);
-  return tags.filter((tag) => tag.length <= TAG_MAX_CHARS);
-}
-function decode(segment) {
-  try {
-    return decodeURIComponent(segment);
-  } catch {
-    return segment;
-  }
-}
-function tagsForUrl(url, storefront) {
-  const path = 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;
-  }
-}
-
 // 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;
   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 = cacheKindForPath(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 = next?.revalidate ?? DEFAULT_REVALIDATE_S;
+  const named = /* @__PURE__ */ new Map();
+  for (const [kind, policy] of Object.entries(cachePolicy ?? {}))
+    if (policy !== void 0)
+      named.set(kind, policyToNext(policy));
+  const policies = (kind) => named.get(kind) ?? (next?.revalidate === void 0 ? policyToNext(DEFAULT_CACHE_POLICY[kind]) : { revalidate: next.revalidate });
+  const floorKey = namedFloorKey ?? rest.publishableKey;
   const extraTags = next?.tags ?? [];
   const storefront = `${(rest.baseUrl ?? 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) && storefrontRoute(target.slice(storefront.length))?.route === "config";
+    const floor = isConfig ? pendingMinGeneration(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 {
+          observeGeneration(
+            (await response.clone().json()).generation,
+            floorKey
+          );
+        } catch {
+        }
+      return response;
+    });
   };
   return createCatalogClient({
     ...rest,
@@ -205,12 +193,16 @@ async function listAllCategoryHandles(client, opts = {}) {
   return out;
 }
 export {
+  DEFAULT_CACHE_POLICY,
   SDK_VERSION,
+  cacheKindForPath,
   catalogTags,
   createServerCatalogClient,
   listAllCategoryHandles,
   listAllCollectionHandles,
   listAllProductHandles,
+  policyToNext,
+  scopesToTags,
   staticProductParams,
   syncCatalogGeneration
 };

package/dist/{types-D0PywKnN.d.cts → types-jNpOwEUw.d.cts}

@@ -1,5 +1,5 @@
 import { CurrencyCode } from '@usethrottle/money';
-import { C as CartCheckAnswer, h as CartCreateRequest, g as CartCreateAnswer, b as StorefrontListAnswer, e as StorefrontProductAnswer, p as StorefrontRelatedAnswer, o as StorefrontFilterValuesAnswer, j as StorefrontCategoriesAnswer, k as StorefrontCategoryAnswer, s as StorefrontTagsAnswer, m as StorefrontCollectionsAnswer, l as StorefrontCollectionAnswer, r as StorefrontSuggestAnswer, n as StorefrontConfigAnswer, q as StorefrontReviewsAnswer, d as ReviewEligibilityAnswer, a as ReviewSubmitInput, R as ReviewSubmitAnswer } from './contract-types-BRyonOYH.cjs';
+import { C as CartCheckAnswer, j as CartCreateRequest, i as CartCreateAnswer, d as StorefrontListAnswer, g as StorefrontProductAnswer, u as StorefrontRelatedAnswer, r as StorefrontFilterValuesAnswer, l as StorefrontCategoriesAnswer, m as StorefrontCategoryAnswer, x as StorefrontTagsAnswer, o as StorefrontCollectionsAnswer, n as StorefrontCollectionAnswer, w as StorefrontSuggestAnswer, p as StorefrontConfigAnswer, S as StorefrontSettings, t as StorefrontPagesAnswer, s as StorefrontPageAnswer, v as StorefrontReviewsAnswer, f as ReviewEligibilityAnswer, a as ReviewSubmitInput, R as ReviewSubmitAnswer } from './contract-types-D2-SSPM9.cjs';
 
 type QueryPairs = [string, string][];
 
@@ -36,6 +36,13 @@ type CatalogClientOptions = {
      * the header.
      */
     keyInQuery?: boolean;
+    /**
+     * A preview token (from the dashboard's preview link). Settings and pages
+     * reads then send it as `X-Storefront-Preview` and answer the draft: they
+     * are never cached, here or in the `cache` store. A token that does not
+     * verify is a `401` `PREVIEW_EXPIRED`. Other routes never carry it.
+     */
+    previewToken?: string;
 };
 /** Next.js's `fetch` cache options; the SDK never imports Next. */
 type NextFetchOptions = {
@@ -57,6 +64,14 @@ type CallOptions = {
      */
     next?: NextFetchOptions;
 };
+/** Options of the reads that answer settings (`config`, `settings`, `pages`). */
+type SettingsCallOptions = CallOptions & {
+    /**
+     * The storefront generation the caller knows exists (a change notice names
+     * it). Above the one the edge holds, the answer is read fresh.
+     */
+    minGeneration?: number;
+};
 type RequestSpec = {
     method: 'GET' | 'POST';
     /** Already encoded, starting with `/`. */
@@ -85,6 +100,8 @@ type RequestSpec = {
      * options). A POST takes them in its body, from `context()`.
      */
     context?: 'priced' | 'locale';
+    /** The route answers a draft to a preview token, so the client sends one. */
+    preview?: boolean;
 };
 
 /** A list sort the catalog knows. */
@@ -309,6 +326,24 @@ type CartsNamespace = {
         throttleBaseUrl?: string;
     }): CartSession;
 };
+/** `settings()`: the storefront settings and what versions them. */
+type StorefrontSettingsResult = {
+    settings: StorefrontSettings;
+    settingsVersion: number;
+    generation: number;
+};
+/**
+ * `client.settings()`. The document may later be assembled from more than one
+ * extension (site design and catalog display); callers always read it through
+ * here, so its source can move without a change in the store.
+ */
+type SettingsNamespace = (call?: SettingsCallOptions) => Promise<StorefrontSettingsResult>;
+type PagesNamespace = {
+    /** The published pages, in the store's order. */
+    list(call?: SettingsCallOptions): Promise<StorefrontPagesAnswer>;
+    /** One page; an unknown handle is a `404` `PAGE_NOT_FOUND`. */
+    get(handle: string, call?: SettingsCallOptions): Promise<StorefrontPageAnswer>;
+};
 type CatalogNamespaces = {
     readonly products: ProductsNamespace;
     readonly filters: FiltersNamespace;
@@ -318,7 +353,9 @@ type CatalogNamespaces = {
     readonly suggest: (q: string, opts?: {
         limit?: number;
     } & CallOptions) => Promise<StorefrontSuggestAnswer>;
-    readonly config: (call?: CallOptions) => Promise<StorefrontConfigAnswer>;
+    readonly config: (call?: SettingsCallOptions) => Promise<StorefrontConfigAnswer>;
+    readonly settings: SettingsNamespace;
+    readonly pages: PagesNamespace;
     readonly reviews: ReviewsNamespace;
     readonly carts: CartsNamespace;
 };
@@ -346,4 +383,4 @@ type CustomerCartSource = {
     whenClaimSettled(): Promise<void>;
 };
 
-export type { CustomerCartSource as C, FieldsOption as F, NextFetchOptions as N, OpenCartRef as O, ProductsQuery as P, Redirect as R, SessionCallOptions as S, ThrottleCart as T, CategoryTreeDepth as a, CartWarning as b, CallOptions as c, CartAbsorb as d, CartCheckout as e, CartCheckoutInput as f, CartSession as g, CartSessionBranding as h, CartSessionDetail as i, CartSessionSnapshot as j, CartsNamespace as k, CatalogClientOptions as l, CatalogHttpCache as m, CatalogHttpCacheEntry as n, CatalogNamespaces as o, CategoriesNamespace as p, CollectionsNamespace as q, CustomerTokenSource as r, FiltersNamespace as s, ProductsNamespace as t, ReviewsNamespace as u, StorefrontSort as v, TagsNamespace as w, ThrottleLine as x, RequestSpec as y };
+export type { TagsNamespace as A, ThrottleLine as B, CustomerCartSource as C, RequestSpec as D, FieldsOption as F, NextFetchOptions as N, OpenCartRef as O, ProductsQuery as P, Redirect as R, SessionCallOptions as S, ThrottleCart as T, CategoryTreeDepth as a, CartWarning as b, CallOptions as c, CartAbsorb as d, CartCheckout as e, CartCheckoutInput as f, CartSession as g, CartSessionBranding as h, CartSessionDetail as i, CartSessionSnapshot as j, CartsNamespace as k, CatalogClientOptions as l, CatalogHttpCache as m, CatalogHttpCacheEntry as n, CatalogNamespaces as o, CategoriesNamespace as p, CollectionsNamespace as q, CustomerTokenSource as r, FiltersNamespace as s, PagesNamespace as t, ProductsNamespace as u, ReviewsNamespace as v, SettingsCallOptions as w, SettingsNamespace as x, StorefrontSettingsResult as y, StorefrontSort as z };

package/dist/{types-BfveENg1.d.ts → types-z57bkjjB.d.ts}

@@ -1,5 +1,5 @@
 import { CurrencyCode } from '@usethrottle/money';
-import { C as CartCheckAnswer, h as CartCreateRequest, g as CartCreateAnswer, b as StorefrontListAnswer, e as StorefrontProductAnswer, p as StorefrontRelatedAnswer, o as StorefrontFilterValuesAnswer, j as StorefrontCategoriesAnswer, k as StorefrontCategoryAnswer, s as StorefrontTagsAnswer, m as StorefrontCollectionsAnswer, l as StorefrontCollectionAnswer, r as StorefrontSuggestAnswer, n as StorefrontConfigAnswer, q as StorefrontReviewsAnswer, d as ReviewEligibilityAnswer, a as ReviewSubmitInput, R as ReviewSubmitAnswer } from './contract-types-BRyonOYH.js';
+import { C as CartCheckAnswer, j as CartCreateRequest, i as CartCreateAnswer, d as StorefrontListAnswer, g as StorefrontProductAnswer, u as StorefrontRelatedAnswer, r as StorefrontFilterValuesAnswer, l as StorefrontCategoriesAnswer, m as StorefrontCategoryAnswer, x as StorefrontTagsAnswer, o as StorefrontCollectionsAnswer, n as StorefrontCollectionAnswer, w as StorefrontSuggestAnswer, p as StorefrontConfigAnswer, S as StorefrontSettings, t as StorefrontPagesAnswer, s as StorefrontPageAnswer, v as StorefrontReviewsAnswer, f as ReviewEligibilityAnswer, a as ReviewSubmitInput, R as ReviewSubmitAnswer } from './contract-types-D2-SSPM9.js';
 
 type QueryPairs = [string, string][];
 
@@ -36,6 +36,13 @@ type CatalogClientOptions = {
      * the header.
      */
     keyInQuery?: boolean;
+    /**
+     * A preview token (from the dashboard's preview link). Settings and pages
+     * reads then send it as `X-Storefront-Preview` and answer the draft: they
+     * are never cached, here or in the `cache` store. A token that does not
+     * verify is a `401` `PREVIEW_EXPIRED`. Other routes never carry it.
+     */
+    previewToken?: string;
 };
 /** Next.js's `fetch` cache options; the SDK never imports Next. */
 type NextFetchOptions = {
@@ -57,6 +64,14 @@ type CallOptions = {
      */
     next?: NextFetchOptions;
 };
+/** Options of the reads that answer settings (`config`, `settings`, `pages`). */
+type SettingsCallOptions = CallOptions & {
+    /**
+     * The storefront generation the caller knows exists (a change notice names
+     * it). Above the one the edge holds, the answer is read fresh.
+     */
+    minGeneration?: number;
+};
 type RequestSpec = {
     method: 'GET' | 'POST';
     /** Already encoded, starting with `/`. */
@@ -85,6 +100,8 @@ type RequestSpec = {
      * options). A POST takes them in its body, from `context()`.
      */
     context?: 'priced' | 'locale';
+    /** The route answers a draft to a preview token, so the client sends one. */
+    preview?: boolean;
 };
 
 /** A list sort the catalog knows. */
@@ -309,6 +326,24 @@ type CartsNamespace = {
         throttleBaseUrl?: string;
     }): CartSession;
 };
+/** `settings()`: the storefront settings and what versions them. */
+type StorefrontSettingsResult = {
+    settings: StorefrontSettings;
+    settingsVersion: number;
+    generation: number;
+};
+/**
+ * `client.settings()`. The document may later be assembled from more than one
+ * extension (site design and catalog display); callers always read it through
+ * here, so its source can move without a change in the store.
+ */
+type SettingsNamespace = (call?: SettingsCallOptions) => Promise<StorefrontSettingsResult>;
+type PagesNamespace = {
+    /** The published pages, in the store's order. */
+    list(call?: SettingsCallOptions): Promise<StorefrontPagesAnswer>;
+    /** One page; an unknown handle is a `404` `PAGE_NOT_FOUND`. */
+    get(handle: string, call?: SettingsCallOptions): Promise<StorefrontPageAnswer>;
+};
 type CatalogNamespaces = {
     readonly products: ProductsNamespace;
     readonly filters: FiltersNamespace;
@@ -318,7 +353,9 @@ type CatalogNamespaces = {
     readonly suggest: (q: string, opts?: {
         limit?: number;
     } & CallOptions) => Promise<StorefrontSuggestAnswer>;
-    readonly config: (call?: CallOptions) => Promise<StorefrontConfigAnswer>;
+    readonly config: (call?: SettingsCallOptions) => Promise<StorefrontConfigAnswer>;
+    readonly settings: SettingsNamespace;
+    readonly pages: PagesNamespace;
     readonly reviews: ReviewsNamespace;
     readonly carts: CartsNamespace;
 };
@@ -346,4 +383,4 @@ type CustomerCartSource = {
     whenClaimSettled(): Promise<void>;
 };
 
-export type { CustomerCartSource as C, FieldsOption as F, NextFetchOptions as N, OpenCartRef as O, ProductsQuery as P, Redirect as R, SessionCallOptions as S, ThrottleCart as T, CategoryTreeDepth as a, CartWarning as b, CallOptions as c, CartAbsorb as d, CartCheckout as e, CartCheckoutInput as f, CartSession as g, CartSessionBranding as h, CartSessionDetail as i, CartSessionSnapshot as j, CartsNamespace as k, CatalogClientOptions as l, CatalogHttpCache as m, CatalogHttpCacheEntry as n, CatalogNamespaces as o, CategoriesNamespace as p, CollectionsNamespace as q, CustomerTokenSource as r, FiltersNamespace as s, ProductsNamespace as t, ReviewsNamespace as u, StorefrontSort as v, TagsNamespace as w, ThrottleLine as x, RequestSpec as y };
+export type { TagsNamespace as A, ThrottleLine as B, CustomerCartSource as C, RequestSpec as D, FieldsOption as F, NextFetchOptions as N, OpenCartRef as O, ProductsQuery as P, Redirect as R, SessionCallOptions as S, ThrottleCart as T, CategoryTreeDepth as a, CartWarning as b, CallOptions as c, CartAbsorb as d, CartCheckout as e, CartCheckoutInput as f, CartSession as g, CartSessionBranding as h, CartSessionDetail as i, CartSessionSnapshot as j, CartsNamespace as k, CatalogClientOptions as l, CatalogHttpCache as m, CatalogHttpCacheEntry as n, CatalogNamespaces as o, CategoriesNamespace as p, CollectionsNamespace as q, CustomerTokenSource as r, FiltersNamespace as s, PagesNamespace as t, ProductsNamespace as u, ReviewsNamespace as v, SettingsCallOptions as w, SettingsNamespace as x, StorefrontSettingsResult as y, StorefrontSort as z };

package/dist/url.d.cts

@@ -1,6 +1,6 @@
 import { ProductsQuery } from './index.cjs';
 import '@usethrottle/money';
-import './contract-types-BRyonOYH.cjs';
+import './contract-types-D2-SSPM9.cjs';
 
 /** The shop page's selection as URL state (P6-R16). */
 type ShopQuery = {

package/dist/url.d.ts

@@ -1,6 +1,6 @@
 import { ProductsQuery } from './index.js';
 import '@usethrottle/money';
-import './contract-types-BRyonOYH.js';
+import './contract-types-D2-SSPM9.js';
 
 /** The shop page's selection as URL state (P6-R16). */
 type ShopQuery = {

package/dist/{use-query-CR7r5tam.d.ts → use-query-COqRZJnC.d.ts}

@@ -1,4 +1,4 @@
-import { b as CatalogError } from './catalog-error-CSoPS0-d.js';
+import { b as CatalogError } from './catalog-error-BnabMMEy.js';
 
 type QueryResult<T> = {
     data: T | undefined;

package/dist/{use-query-UWf6Pi5g.d.cts → use-query-H1xgL3_e.d.cts}

@@ -1,4 +1,4 @@
-import { b as CatalogError } from './catalog-error-BOaSKgY3.cjs';
+import { b as CatalogError } from './catalog-error-BKN5hNWP.cjs';
 
 type QueryResult<T> = {
     data: T | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usethrottle/catalog",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Storefront SDK for the Throttle Product Catalog: a typed client, React hooks, server helpers and URL helpers.",
   "license": "MIT",
   "repository": {
@@ -56,6 +56,16 @@
         "default": "./dist/server.cjs"
       }
     },
+    "./next": {
+      "import": {
+        "types": "./dist/next.d.ts",
+        "default": "./dist/next.js"
+      },
+      "require": {
+        "types": "./dist/next.d.cts",
+        "default": "./dist/next.cjs"
+      }
+    },
     "./url": {
       "import": {
         "types": "./dist/url.d.ts",
@@ -92,9 +102,13 @@
     "@usethrottle/money": "^1.0.0"
   },
   "peerDependencies": {
+    "next": ">=14",
     "react": "^18.2.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
     "react": {
       "optional": true
     }