@usethrottle/catalog 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @usethrottle/catalog
+
+## 0.1.0
+
+### Minor Changes
+
+- 7266f03: First release: the storefront client, React hooks, server helpers and URL helpers

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Epic Design Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,269 @@
-# Temporary Holding Version
+# @usethrottle/catalog
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The storefront SDK for the Throttle Product Catalog: a typed client for every `/v1/storefront` route, React hooks with a small stale-while-revalidate cache and a session-backed cart, Next.js server helpers, and URL helpers for shop pages.
+
+Full guides: https://usethrottle.dev/docs/product-catalog/
+
+## Install
+
+```sh
+npm install @usethrottle/catalog
+# or
+pnpm add @usethrottle/catalog
+```
+
+Node 20 or later, or any evergreen browser. The only runtime dependency is `@usethrottle/errors`. `react` (18.2 or 19) is an optional peer, needed only for `@usethrottle/catalog/react`. TypeScript needs `moduleResolution` `node16`, `nodenext` or `bundler`: the package has only an `exports` map, which the older `node` setting cannot read.
+
+## Quickstart
+
+Create a publishable key in the catalog dashboard (Storefront › Keys). For a script or a server, use a **server** key; for a browser, a **browser** key with your site's origin on its list.
+
+```ts
+import { createCatalogClient } from '@usethrottle/catalog';
+
+const catalog = createCatalogClient({
+  publishableKey: process.env.CATALOG_SERVER_KEY ?? '',
+});
+
+const { products } = await catalog.products.list({ limit: 5 });
+
+for (const product of products) {
+  console.log(product.handle, product.title, product.priceRange?.minMinor);
+}
+```
+
+Prices are integers in minor units (cents for USD). The client talks to `https://catalog.usethrottle.dev` by default (`baseUrl` changes it). Every call takes `{ signal, timeoutMs }`; the default timeout is 10 seconds.
+
+## Entries
+
+| Import                        | What it holds                                                                                                                                                                                                |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@usethrottle/catalog`        | `createCatalogClient`, the error classes and `isCatalogError`, and the answer types. No DOM and no Node-only API.                                                                                            |
+| `@usethrottle/catalog/react`  | `CatalogProvider`, the read hooks, `useCart` and `useSubmitReview` (marked `"use client"`).                                                                                                                  |
+| `@usethrottle/catalog/server` | `createServerCatalogClient`, `catalogTags`, `syncCatalogGeneration` and the paging helpers (`listAllProductHandles`, `staticProductParams`, `listAllCollectionHandles`, `listAllCategoryHandles`).           |
+| `@usethrottle/catalog/url`    | `parseShopQuery`, `serializeShopQuery`, `toProductsQuery`, `parseRange` and `formatRange`. Standalone: none of the client or React code (the ESM and CommonJS builds each load one tiny shared helper file). |
+
+Everything `/react` exports is a client reference in a server component, `SDK_VERSION` and `catalogQueryKey` included: in server code import `SDK_VERSION` from the root or `/server`, and call `catalogQueryKey` only in client code.
+
+The client's namespaces: `products` (`list`, `get`, `related`), `filters.values`, `categories` (`tree`, `get`), `tags.list`, `collections` (`list`, `get`), `suggest`, `config`, `reviews` (`list`, `eligibility`, `submit`) and `carts` (`check`, `create`, `session`). `products.get` always asks for the full product; lists default to the lite projection (`fields: 'full'` or a list of keys changes it).
+
+## Keys
+
+Only publishable keys (`pc_pk_`) are accepted. Anything else throws `CatalogError` `INVALID_PUBLISHABLE_KEY` when the client is created, and a secret key (`pc_sk_`) gets its own message: secret keys must never reach a storefront. The key itself is never part of an error message.
+
+Publishable keys have a type, chosen when you create them:
+
+- **browser**: the request must come from an `https` origin on the key's list. Use it in client-side code.
+- **app**: a request with no `Origin` is fine; one with an `Origin` must be on the list. For native apps and other non-browser clients.
+- **server**: a request with any `Origin` is refused (`403 SERVER_KEY_IN_BROWSER`). Use it for SSR, static builds and scripts; it has higher rate limits and no per-visitor bucket.
+
+The allowed origins protect browsers only; a publishable key is public by design. For carts, the same origins must also be on Throttle's allowed origins.
+
+## Customer prices
+
+Pass `customerToken`, a function the client calls on every request, to get the signed-in customer's prices. With `@usethrottle/auth` 0.10.1 or later:
+
+```ts
+const catalog = createCatalogClient({
+  publishableKey,
+  customerToken: () => auth.getAccessToken(),
+});
+```
+
+The token travels only in the `X-Customer-Token` header; it is never stored on the client, put in a URL or logged. A token the catalog refuses is asked for once more; a read then falls back to list prices (the answer has no `priceContext`), while `reviews.eligibility`, `reviews.submit` and a cart create with a token throw `CustomerTokenInvalidError`.
+
+## Errors
+
+Every error the SDK throws is a `CatalogError` (which extends `ThrottleError` from `@usethrottle/errors`), with `code`, `statusCode`, `retryAfterSeconds`, `issues`, `retryable` and `source` (`'catalog'`, `'throttle'` for Throttle's cart-session routes, or `'client'` when nothing answered).
+
+| Class                       | When                                                                                                                                                                                                                                                                                                         |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `RateLimitedError`          | every `429`; `retryAfterSeconds` comes from `Retry-After` (60 when it is missing or unusable). The client never retries a `429` itself.                                                                                                                                                                      |
+| `OriginNotAllowedError`     | `ORIGIN_NOT_ALLOWED`, `SERVER_KEY_IN_BROWSER`, and Throttle's `origin_not_allowed`.                                                                                                                                                                                                                          |
+| `CustomerTokenInvalidError` | a refused customer token on a call that cannot fall back to list prices.                                                                                                                                                                                                                                     |
+| `CartLineError`             | `CART_ITEMS_INVALID` and Throttle's `quantity_unavailable` and `line_not_purchasable`, with `lines: { sku, code, maxQuantity? }[]`.                                                                                                                                                                          |
+| `TimeoutError`              | `TIMEOUT`: no answer within `timeoutMs`.                                                                                                                                                                                                                                                                     |
+| `NetworkError`              | `NETWORK_ERROR`: the request never got an answer.                                                                                                                                                                                                                                                            |
+| `FeatureUnavailableError`   | `FEATURE_UNAVAILABLE`: a `404` marked as a route this catalog does not have (an older catalog), or a `404` from a route that never answers a missing resource (`config`, the category tree, `tags`, the collections list, `suggest`, `carts/check`, `carts`). Any other `404` is `CatalogError` `NOT_FOUND`. |
+| `CatalogError`              | everything else, including `INVALID_RESPONSE` (an answer that is not the JSON expected) and `CLIENT_ERROR` (a `cartStorage` adapter failed).                                                                                                                                                                 |
+
+A `503 STOREFRONT_INDEXING` (the catalog's first index build) on a read is retried once after `Retry-After` when that is at most 30 seconds (`indexingRetry` changes or turns it off); otherwise it throws with `retryAfterSeconds`. Your own `AbortSignal` rethrows its native abort reason, never wrapped.
+
+```ts
+import { isCatalogError, RateLimitedError } from '@usethrottle/catalog';
+
+try {
+  await catalog.products.list({ q: 'brake pads' });
+} catch (error) {
+  if (error instanceof RateLimitedError) wait(error.retryAfterSeconds);
+  else if (isCatalogError(error)) show(error.code, error.issues);
+  else throw error;
+}
+```
+
+## Carts and checkout
+
+Carts are resolved by the catalog: the browser sends SKUs and quantities, never prices. `carts.create` answers Throttle's hosted cart URL (`cartUrl`) and a session id. It takes three optional URLs, each an absolute `https` URL on the store's Checkout settings › Allowed return websites (otherwise `422 RETURN_URL_NOT_ALLOWED`, one issue per refused field):
+
+```ts
+const cart = await catalog.carts.create({
+  items: [{ sku: 'BRK-PAD-01', quantity: 2 }],
+  returnUrl: 'https://shop.example.com/complete', // after payment
+  cancelUrl: 'https://shop.example.com/cart', // the hosted cart's cancel link
+  storefrontUrl: 'https://shop.example.com/shop', // "Continue shopping"
+});
+// cart.returnUrlApplied is false when Throttle did not store them.
+```
+
+Without them the shopper ends on Throttle's own completion page. To build your own cart page instead, use `catalog.carts.session(cart.sessionId)` (`get`, `add`, `update`, `remove`, `refresh`, `checkout({ returnUrl, cancelUrl })`). `checkout()` answers the checkout URL; it never navigates. Both are checked before any request: `carts.create` refuses a URL that is not absolute `https` (`INVALID_REQUEST`, naming the field), and `checkout()` one that is not absolute `http` or `https`.
+
+## React
+
+```tsx
+'use client';
+import { useMemo } from 'react';
+import { createCatalogClient } from '@usethrottle/catalog';
+import {
+  CatalogProvider,
+  useCart,
+  useProducts,
+  type CartStorage,
+} from '@usethrottle/catalog/react';
+
+// One client for the life of the app.
+const client = createCatalogClient({
+  publishableKey: process.env.NEXT_PUBLIC_CATALOG_KEY ?? '',
+  customerToken: () => auth.getAccessToken(),
+});
+
+// Keeps the cart across reloads, one slot per customer.
+function localCartStorage(customerId: string | null): CartStorage {
+  const key = `catalog-cart:${customerId ?? 'guest'}`;
+  return {
+    get: () => localStorage.getItem(key),
+    set: (id) => localStorage.setItem(key, id),
+    remove: () => localStorage.removeItem(key),
+  };
+}
+
+export function Shop({ customerId }: { customerId: string | null }) {
+  const cartStorage = useMemo(() => localCartStorage(customerId), [customerId]);
+  return (
+    <CatalogProvider
+      client={client}
+      customerKey={customerId}
+      cartStorage={cartStorage}
+      cartUrls={{
+        returnUrl: 'https://shop.example.com/complete',
+        cancelUrl: 'https://shop.example.com/cart',
+        storefrontUrl: 'https://shop.example.com/shop',
+      }}
+    >
+      <ProductGrid />
+    </CatalogProvider>
+  );
+}
+
+function ProductGrid() {
+  const { data, error } = useProducts({ limit: 24 });
+  const cart = useCart(); // cart.add(sku, quantity) from a product page
+  const checkout = async () =>
+    location.assign((await cart.checkout()).checkoutUrl);
+  if (error) return <p>{error.message}</p>;
+  return (
+    <>
+      <ul>
+        {data?.products.map((product) => (
+          <li key={product.handle}>{product.title}</li>
+        ))}
+      </ul>
+      <button disabled={!cart.cart || cart.pending} onClick={checkout}>
+        Checkout ({cart.cart?.unitCount ?? 0})
+      </button>
+    </>
+  );
+}
+```
+
+- **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`.
+- **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).
+- **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.
+
+## Next.js
+
+On the server, use a **server** key and `createServerCatalogClient`. Every catalog read's `fetch` carries `next: { revalidate, tags }` (60 seconds by default); carts, Throttle calls and any request with a customer token are `cache: 'no-store'`. Next.js itself is never imported.
+
+```ts
+// lib/catalog.ts
+import { createServerCatalogClient } from '@usethrottle/catalog/server';
+
+export const catalog = createServerCatalogClient({
+  publishableKey: process.env.CATALOG_SERVER_KEY ?? '',
+  next: { revalidate: 300 },
+});
+```
+
+During the catalog's first index build, a read that meets `503 STOREFRONT_INDEXING` waits its `Retry-After` (when that is at most 30 seconds by default; `indexingRetry: { maxWaitSeconds }` changes the limit) and asks once more. Pass `indexingRetry: false` to `createServerCatalogClient` to fail fast inside a page render or route handler instead.
+
+Tags are `throttle-catalog`, `throttle-catalog:<route>` and, on a route for one handle (a product, its related products or reviews, a category or a collection), `throttle-catalog:<route>:<handle>`; `catalogTags(route, handle)` builds them. Two catalog installations in one Next.js app share these tags, so revalidating one also refreshes the other. To refresh pages when the catalog changes, poll `syncCatalogGeneration` (from a cron job, every minute for example) and revalidate on a change. Keep the last generation somewhere durable (KV, a database row, an edge config): on a serverless host a call often lands on a fresh instance, where a module variable starts empty, so that call only records the generation and a change made since is never revalidated. The pages' `revalidate` still bounds how stale they get if a change is missed.
+
+```ts
+// app/api/catalog-sync/route.ts
+import { revalidateTag } from 'next/cache';
+import { syncCatalogGeneration } from '@usethrottle/catalog/server';
+import { catalog } from '@/lib/catalog';
+import { kv } from '@/lib/kv'; // any durable store: KV, a database row, an edge config
+
+export async function GET() {
+  const previous = (await kv.get<number>('catalog-generation')) ?? undefined;
+  const { generation, changed } = await syncCatalogGeneration({
+    client: catalog,
+    previous,
+    onChange: () => revalidateTag('throttle-catalog'),
+  });
+  await kv.set('catalog-generation', generation);
+  return Response.json({ generation, changed });
+}
+```
+
+`staticProductParams(catalog)` feeds `generateStaticParams`, and `listAllProductHandles(catalog)` (an async iterable) feeds a sitemap. In the browser, use a browser key and the React provider.
+
+## URL helpers
+
+`@usethrottle/catalog/url` keeps a shop page's selection in its URL, with one canonical string per selection and every parameter it does not know kept in order:
+
+```ts
+import {
+  parseShopQuery,
+  serializeShopQuery,
+  toProductsQuery,
+} from '@usethrottle/catalog/url';
+
+const shop = parseShopQuery(location.search); // or URLSearchParams, or a record
+const query = toProductsQuery(shop, { limit: 24, facets: true });
+const next = serializeShopQuery({
+  ...shop,
+  filters: { ...shop.filters, brand: ['Bosch'] },
+  page: 1,
+});
+history.pushState(null, '', `?${next}`);
+```
+
+Ranges stay strings (`10..50`); `parseRange` and `formatRange` convert them.
+
+## Module formats
+
+The package ships ESM and CommonJS builds. Within one format, every entry shares one copy of the client and the error classes, so `instanceof` works across `/react`, `/server` and the root. An app that loads the package through both `import` and `require` gets two copies: `instanceof RateLimitedError` (or any other class) is then true only for errors from the same format. `isCatalogError` works across both, because it also checks a shared brand; use it, then branch on `error.code`.
+
+## 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`).
+
+The OpenAPI 3.1 document of the storefront API is at https://catalog.usethrottle.dev/v1/storefront/openapi.json.
+
+## License
+
+MIT

package/dist/catalog-error-BWUoZCzY.d.ts

@@ -0,0 +1,243 @@
+import { p as CatalogContractErrorCode } from './types-DYfIvIaI.js';
+
+/**
+ * Shared error type for every Throttle SDK.
+ *
+ * Historically each SDK shipped its own structurally-identical error class
+ * (`ThrottleApiError` in `@usethrottle/cart`, `ThrottleCheckoutError` in
+ * `@usethrottle/checkout-sdk`, `ThrottleDiscountsError`,
+ * `ThrottleSubscriptionsError`, …). Catching across two packages meant catching
+ * two names. Every SDK error class now extends `ThrottleError`, so a single
+ * `catch (e) { if (e instanceof ThrottleError) … }` covers all of them while the
+ * original per-SDK class names keep working as aliases for backward
+ * compatibility.
+ *
+ * @example
+ * ```ts
+ * import { ThrottleError } from '@usethrottle/errors';
+ * try {
+ *   await cart.items.add(cartId, item);
+ *   await checkout.completeSession(sessionId, payment);
+ * } catch (e) {
+ *   if (e instanceof ThrottleError) {
+ *     console.error(e.code, e.statusCode, e.message);
+ *   }
+ * }
+ * ```
+ */
+interface ThrottleErrorArgs {
+    /** Stable machine-readable error code from the API envelope (`error.code`). */
+    code: string;
+    /** Human-readable message (`error.message`). */
+    message: string;
+    /** HTTP status code of the failed response. */
+    statusCode: number;
+    /** Structured per-field detail when the API provides it (`error.details`). */
+    details?: unknown;
+    /** The full parsed response body, when an SDK chooses to attach it. */
+    body?: unknown;
+    /** The API's request id (x-request-id / meta.requestId), for support + Sentry correlation. */
+    requestId?: string;
+    /**
+     * The failed response's headers, when an SDK constructs the error directly
+     * from a `fetch` `Response`. Used to recover `requestId` from the
+     * `x-request-id` header for hand-built error bodies (401/403/500) that lack
+     * a `meta` envelope — the header is always set, even when `meta` isn't.
+     */
+    responseHeaders?: {
+        get(name: string): string | null | undefined;
+    } | Record<string, string | undefined>;
+}
+declare class ThrottleError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: unknown;
+    readonly body?: unknown;
+    readonly requestId?: string;
+    constructor(args: ThrottleErrorArgs);
+}
+
+declare const THROTTLE_CART_CODES: {
+    readonly price_locked: {
+        readonly statuses: readonly [400];
+        readonly retryable: false;
+    };
+    readonly quantity_unavailable: {
+        readonly statuses: readonly [409];
+        readonly retryable: false;
+    };
+    readonly line_not_purchasable: {
+        readonly statuses: readonly [422];
+        readonly retryable: false;
+    };
+    readonly line_resolver_unavailable: {
+        readonly statuses: readonly [503];
+        readonly retryable: true;
+    };
+    readonly line_resolver_not_available: {
+        readonly statuses: readonly [422];
+        readonly retryable: false;
+    };
+    readonly currency_not_enabled: {
+        readonly statuses: readonly [422];
+        readonly retryable: false;
+    };
+    readonly resolved_lines_required: {
+        readonly statuses: readonly [422];
+        readonly retryable: false;
+    };
+    readonly line_limit_reached: {
+        readonly statuses: readonly [422];
+        readonly retryable: false;
+    };
+    readonly cart_prices_changed: {
+        readonly statuses: readonly [409];
+        readonly retryable: false;
+    };
+    readonly shipping_method_unavailable: {
+        readonly statuses: readonly [422];
+        readonly retryable: false;
+    };
+    readonly shipping_quote_unavailable: {
+        readonly statuses: readonly [503];
+        readonly retryable: true;
+    };
+    readonly amount_too_large: {
+        readonly statuses: readonly [422];
+        readonly retryable: false;
+    };
+    readonly cart_changed: {
+        readonly statuses: readonly [409];
+        readonly retryable: false;
+    };
+    readonly discount_currency_unsupported: {
+        readonly statuses: readonly [422];
+        readonly retryable: false;
+    };
+    readonly shipping_currency_unsupported: {
+        readonly statuses: readonly [422];
+        readonly retryable: false;
+    };
+    readonly cart_not_open: {
+        readonly statuses: readonly [409];
+        readonly retryable: false;
+    };
+    readonly cart_not_found: {
+        readonly statuses: readonly [404];
+        readonly retryable: false;
+    };
+    readonly item_not_found: {
+        readonly statuses: readonly [404];
+        readonly retryable: false;
+    };
+    /**
+     * `details: { reason, storefrontUrl }`. Throttle sends `storefrontUrl` raw
+     * and unvalidated (its hosted cart page validates it), and the SDK passes
+     * it through untouched in `details` and `body`. Never render it as a link
+     * or navigate to it without your own check (http(s) only, an origin you
+     * trust): it may hold a `javascript:` URL.
+     */
+    readonly cart_session_expired: {
+        readonly statuses: readonly [410];
+        readonly retryable: false;
+    };
+    readonly cart_session_not_found: {
+        readonly statuses: readonly [404];
+        readonly retryable: false;
+    };
+    readonly origin_not_allowed: {
+        readonly statuses: readonly [403];
+        readonly retryable: false;
+    };
+    readonly checkout_unavailable: {
+        readonly statuses: readonly [501];
+        readonly retryable: false;
+    };
+};
+type ThrottleCartCode = keyof typeof THROTTLE_CART_CODES;
+
+/** Codes the SDK makes itself, with no server answer behind them (P6-R7). */
+type ClientErrorCode = 'TIMEOUT' | 'NETWORK_ERROR' | 'FEATURE_UNAVAILABLE' | 'INVALID_RESPONSE' | 'INVALID_PUBLISHABLE_KEY' | 'CLIENT_ERROR';
+type CatalogErrorCode = CatalogContractErrorCode | ThrottleCartCode | ClientErrorCode;
+/**
+ * Which side answered: the catalog Worker, Throttle's cart-session API, or
+ * nobody (`client`: a timeout, a network failure or a bad option).
+ */
+type CatalogErrorSource = 'catalog' | 'throttle' | 'client';
+type CatalogErrorIssue = {
+    path: string;
+    message: string;
+};
+type CartLineProblem = {
+    sku: string;
+    code: string;
+    maxQuantity?: number;
+};
+type CatalogErrorInit = {
+    code: CatalogErrorCode | (string & {});
+    message: string;
+    statusCode: number;
+    source: CatalogErrorSource;
+    /** Defaults to true exactly for a 429 or 503 status. */
+    retryable?: boolean;
+    retryAfterSeconds?: number | null;
+    issues?: readonly CatalogErrorIssue[];
+    details?: unknown;
+    body?: unknown;
+    requestId?: string | undefined;
+    cause?: unknown;
+};
+/** The base of every error the SDK throws (spec §13.2, P6-R7). */
+declare class CatalogError extends ThrottleError {
+    readonly code: CatalogErrorCode | (string & {});
+    /** Seconds to wait before retrying, when the answer says (or P6-R10/R11 default). */
+    readonly retryAfterSeconds: number | null;
+    /** Field problems from an `INVALID_REQUEST`-style answer. */
+    readonly issues: readonly CatalogErrorIssue[];
+    /** Whether the same request may succeed later. */
+    readonly retryable: boolean;
+    readonly source: CatalogErrorSource;
+    constructor(init: CatalogErrorInit);
+}
+/** Every `429`. The core never retries one (P6-R11). */
+declare class RateLimitedError extends CatalogError {
+    readonly retryAfterSeconds: number;
+    constructor(init: CatalogErrorInit & {
+        retryAfterSeconds: number;
+    });
+}
+/** `ORIGIN_NOT_ALLOWED`, `SERVER_KEY_IN_BROWSER` and Throttle `origin_not_allowed`. */
+declare class OriginNotAllowedError extends CatalogError {
+    constructor(init: CatalogErrorInit);
+}
+/** `CUSTOMER_TOKEN_INVALID`. */
+declare class CustomerTokenInvalidError extends CatalogError {
+    constructor(init: CatalogErrorInit);
+}
+/** `CART_ITEMS_INVALID` and Throttle `quantity_unavailable` / `line_not_purchasable`. */
+declare class CartLineError extends CatalogError {
+    /** One entry per refused line; `maxQuantity` may be 0. */
+    readonly lines: readonly CartLineProblem[];
+    constructor(init: CatalogErrorInit & {
+        lines: readonly CartLineProblem[];
+    });
+}
+/** The request did not finish within `timeoutMs` (P6-R9). */
+declare class TimeoutError extends CatalogError {
+    constructor(init?: Partial<CatalogErrorInit> & {
+        timeoutMs?: number;
+    });
+}
+/** `fetch` itself failed (DNS, a CORS refusal, a reset connection). */
+declare class NetworkError extends CatalogError {
+    constructor(init?: Partial<CatalogErrorInit>);
+}
+/** The catalog Worker does not have this route yet (P6-R8). */
+declare class FeatureUnavailableError extends CatalogError {
+    constructor(init?: Partial<CatalogErrorInit>);
+}
+/** True for a `CatalogError` from this or any other copy of the SDK. */
+declare function isCatalogError(value: unknown): value is CatalogError;
+
+export { CartLineError as C, FeatureUnavailableError as F, NetworkError as N, OriginNotAllowedError as O, RateLimitedError as R, CatalogError as b, CustomerTokenInvalidError as h, TimeoutError as i, isCatalogError as j };
+export type { ThrottleCartCode as T, CartLineProblem as a, CatalogErrorCode as c, CatalogErrorInit as d, CatalogErrorIssue as e, CatalogErrorSource as f, ClientErrorCode as g };