@usequeek/theme-kit 0.1.23 → 0.1.24

package/hooks/use-search.ts

@@ -4,12 +4,22 @@ import { useMemo } from 'react';
 import type { Product } from '../types/product';
 import type { Collection } from '../types/page';
 
+/** What {@link useSearch} returns: the matches to show in a search panel. */
 export interface SearchResults {
   products: Product[];
   categories: Array<[slug: string, name: string]>;
   collections: Collection[];
 }
 
+/**
+ * Instant search over products and collections you already hold (no request).
+ * An empty query returns the first products and categories as suggestions.
+ * Matches are case-insensitive on product title, category name and collection
+ * name, capped at 5 products, 4 categories and 2 collections.
+ *
+ * @example
+ * const { products, categories, collections } = useSearch(query, allProducts, allCollections);
+ */
 export function useSearch(
   query: string,
   products: Product[],

package/hooks/use-shop-cart.ts

@@ -3,6 +3,14 @@
 import { useMemo } from 'react';
 import { useCartStore } from '../stores/cart-store';
 
+/**
+ * The cart lines for one shop, with the unit count and the total (in the
+ * currency's major unit, before delivery and discounts). Pass the shop id from
+ * `product.shop_id`; a missing id gives an empty cart.
+ *
+ * @example
+ * const { items, count, total } = useShopCart(product.shop_id);
+ */
 export function useShopCart(shopId: string | null | undefined): {
   items: ReturnType<typeof useCartStore.getState>['items'];
   count: number;

package/hooks/use-shop.ts

@@ -5,6 +5,7 @@ import { useStorefront, useStorefrontLocale } from '../provider';
 import type { Product, ApiResponse } from '../types/product';
 import { createBrowserClient } from '../sdk/client';
 import { localeCacheKeySegment, withLocaleQuery } from '../utils/locale';
+import { toError } from '../utils/to-error';
 import {
   SHOP_DEFAULT_PER_PAGE,
   normalizeShopQuery,
@@ -78,11 +79,18 @@ function filterProducts(
 }
 
 /**
- * Shop catalogue data source. Hits the live products endpoint in production.
- * In preview (when the provider carries `previewData.products`) it filters,
- * sorts and paginates the demo catalogue in-memory so themes render real cards.
+ * The shop page's catalogue: one page of products for a category, keyword,
+ * sort and page number. Reads the live products endpoint in production. In
+ * preview (when the provider carries `previewData.products`) it filters, sorts
+ * and paginates the demo catalogue in memory, so themes render real cards.
  *
- * Page is controlled by the caller — pair with `useShopParams` for URL sync.
+ * The page is controlled by the caller; pair this with `useShopParams` to keep
+ * it in the URL. On failure the previous page of products stays on screen and
+ * `error` is set; the hook never throws.
+ *
+ * @example
+ * const { categorySlug, keyword, sort, page } = useShopParams();
+ * const { products, isLoading, pagination, error } = useShop({ categorySlug, keyword, sort, page });
  */
 export function useShop(options?: {
   categorySlug?: string | null;
@@ -94,6 +102,7 @@ export function useShop(options?: {
   products: Product[];
   isLoading: boolean;
   pagination: ShopPagination;
+  error: Error | null;
 } {
   const { vendor, previewData } = useStorefront();
   const locale = useStorefrontLocale();
@@ -123,6 +132,7 @@ export function useShop(options?: {
 
   const [products, setProducts] = useState<Product[]>(seed?.products ?? []);
   const [isLoading, setIsLoading] = useState(!isPreview && !seed);
+  const [error, setError] = useState<Error | null>(null);
   const [pagination, setPagination] = useState<ShopPagination>(seed?.pagination ?? { ...EMPTY_PAGINATION, perPage });
   // The key whose results are already in state. Seeded with the prefetch so
   // the first effect run does not refetch the page the server just rendered
@@ -166,6 +176,7 @@ export function useShop(options?: {
     // a newer one (filters B) had reset it, overwriting B's products.
     let cancelled = false;
     setIsLoading(true);
+    setError(null);
 
     const client = createBrowserClient(vendor.slug ?? undefined);
     const current = JSON.parse(queryKey) as typeof query;
@@ -182,6 +193,8 @@ export function useShop(options?: {
         setPagination(parsed.pagination);
         setProducts(parsed.products);
         loadedQueryRef.current = fetchKey;
+      } catch (caught) {
+        if (!cancelled) setError(toError(caught));
       } finally {
         if (!cancelled) setIsLoading(false);
       }
@@ -195,8 +208,8 @@ export function useShop(options?: {
   }, [isPreview, vendor.slug, queryKey, fetchKey, locale]);
 
   if (isPreview && previewResult) {
-    return { products: previewResult.products, isLoading: false, pagination: previewResult.pagination };
+    return { products: previewResult.products, isLoading: false, pagination: previewResult.pagination, error: null };
   }
 
-  return { products, isLoading, pagination };
+  return { products, isLoading, pagination, error };
 }

package/hooks/use-variant-selection.ts

@@ -25,25 +25,6 @@ export interface VariantSelection {
   activeHasDiscount: boolean;
 }
 
-/**
- * The option-selection state machine every theme's product page used to
- * hand-roll — six near-identical copies, all of which gated their add button
- * on stock and addons but never on a resolved variant.
- *
- * Two things it fixes that the copies got wrong:
- *
- * 1. It seeds from a real variant (first in-stock, else first) rather than
- *    from the first value of each option independently. On a sparse matrix —
- *    Red/S is not stocked but Red/M and Blue/S are — first-value-of-each
- *    produces a combination that matches nothing, so the page opened with an
- *    unresolvable selection.
- * 2. It exposes `variantSatisfied`, so a selection that resolves to nothing
- *    (mid-change, or that sparse seed) disables the add instead of sending a
- *    line the backend rejects.
- *
- * Themes keep their own option markup and call `selectOption` — core owns the
- * state, the theme owns the design.
- */
 /**
  * The opening selection. Seeded from a variant that actually exists, so the
  * initial state is always resolvable — preferring one in stock, since opening
@@ -85,6 +66,29 @@ export function resolveVariantState(
   };
 }
 
+/**
+ * The option-selection state machine every theme's product page used to
+ * hand-roll, and which gated the add button on stock and add-ons but never on a
+ * resolved variant.
+ *
+ * It does two things a hand-rolled version tends to get wrong:
+ *
+ * 1. It seeds from a real variant (first in-stock, else first) rather than
+ *    from the first value of each option independently. On a sparse matrix —
+ *    Red/S is not stocked but Red/M and Blue/S are — first-value-of-each
+ *    produces a combination that matches nothing, so the page opened with an
+ *    unresolvable selection.
+ * 2. It exposes `variantSatisfied`, so a selection that resolves to nothing
+ *    (mid-change, or that sparse seed) disables the add instead of sending a
+ *    line the backend rejects.
+ *
+ * Themes keep their own option markup and call `selectOption`: the kit owns the
+ * state, the theme owns the design.
+ *
+ * @example
+ * const { selectedOptions, selectOption, variantSatisfied, activePrice } = useVariantSelection(product);
+ * <button disabled={!variantSatisfied || !activeInStock}>Add to cart</button>
+ */
 export function useVariantSelection(product: Product): VariantSelection {
   const [selectedOptions, setSelectedOptions] = useState<Record<string, string>>(() => seedVariantOptions(product));
 

package/index.ts

@@ -11,19 +11,18 @@
  * Two entries because the split is real, not cosmetic: this one is types and
  * pure functions, importable from anywhere including node tooling; `client.ts`
  * is React state and components and needs a client boundary at the consumer.
- * Core also holds one `next/headers` caller, which belongs in neither and is
- * deliberately unreachable from both.
+ * Modules that call `next/headers` (`sdk/server-store-client.ts` and the
+ * `api/collections.ts` and `api/shop.ts` fetchers built on it) are server-only:
+ * import them from server components, never from a client module.
  *
  * THESE ARE A DECLARATION, NOT AN IMPORT PATH. Do not migrate themes onto them.
- * Pointing a theme's files at `client.ts` fails the build outright: tooling that
- * imports theme components under tsx (a theme registry generator, for example)
- * would reach a gallery block through the barrel, which transitively pulls the
- * SDK, and the SDK does not resolve outside a bundler. It is the same reason a barrel would bloat every
- * theme chunk: the stores call `create()` at import time and package.json
- * declares no `sideEffects`, so webpack must treat every re-export as live and
- * cannot drop the unused ones. Themes keep importing the exact module they use;
- * these barrels stay the machine-checkable statement of what is in the public
- * surface.
+ * Pointing a theme's files at `client.ts` can fail the build outright: tooling
+ * that imports theme components under `tsx` (a theme registry generator, for
+ * example) would reach a gallery block through the barrel, which transitively
+ * pulls the SDK, and the SDK does not resolve outside a bundler. A barrel also
+ * makes every client module reachable from one entry, which bloats each theme
+ * chunk. Themes import the exact module they use; these barrels stay the
+ * machine-checkable statement of what is in the public surface.
  */
 
 export * from './types/theme';

package/locales/en.default.json

@@ -176,5 +176,9 @@
   "language": {
     "label": "Language",
     "named": "Language: {name}"
+  },
+  "embed": {
+    "placeholder": "Paste the link or embed code of the content you want to show",
+    "title": "Embedded content"
   }
 }

package/navigation.tsx

@@ -15,6 +15,7 @@ import NextLink from 'next/link';
 import { usePathname as useFrameworkPathname, useRouter as useFrameworkRouter } from 'next/navigation';
 import { useMemo, type AnchorHTMLAttributes, type ReactNode, type Ref } from 'react';
 
+/** Props for {@link Link}: any anchor attribute except `href`, plus `prefetch` and `replace`. */
 export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
   /** A path inside the store (`menuItemToHref()`, `useHref()`) or a full URL. */
   href: string;
@@ -31,6 +32,7 @@ export function Link({ href, prefetch, replace, ...anchor }: LinkProps) {
   return <NextLink href={href} prefetch={prefetch} replace={replace} {...anchor} />;
 }
 
+/** What {@link useRouter} returns. */
 export interface Router {
   /** Go to `href`, adding a history entry. */
   push(href: string): void;

package/package.json

@@ -1,9 +1,24 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "private": false,
   "license": "MIT",
-  "description": "The framework a Queek storefront theme is built against.",
+  "description": "The runtime a Queek storefront theme is built on: hooks, stores, page renderer, navigation, shared blocks and locale strings.",
+  "keywords": [
+    "queek",
+    "storefront",
+    "theme",
+    "themes",
+    "react",
+    "nextjs",
+    "commerce",
+    "ecommerce"
+  ],
+  "homepage": "https://docs.usequeek.com/docs/themes",
+  "bugs": {
+    "url": "https://github.com/usequeek/theme-kit/issues"
+  },
+  "author": "Queekx Technology LTD",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/usequeek/theme-kit.git"
@@ -25,13 +40,19 @@
     "**/*.css",
     "locales/*.json",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md",
+    "!tests",
+    "!scripts"
   ],
   "peerDependencies": {
     "next": ">=15",
     "react": ">=19",
     "react-dom": ">=19",
-    "@queekai/client-sdk": "*"
+    "@queekai/client-sdk": "^0.3.1 || ^0.4.0"
+  },
+  "engines": {
+    "node": ">=22"
   },
   "dependencies": {
     "zustand": "^5.0.11",

package/page-renderer.tsx

@@ -65,6 +65,17 @@ function signatureReplacer(_key: string, value: unknown): unknown {
   return value;
 }
 
+/**
+ * Renders a page's blocks in order, choosing each block's theme variant (or
+ * the kit's shared block). Block data arrives already resolved: a theme never
+ * fetches it. While a merchant edits, a draft section that cannot render shows
+ * a short "can't be previewed yet" notice instead of blanking the page.
+ *
+ * @example
+ * export default function HomePage({ blocks }: HomePageProps) {
+ *   return <PageRenderer blocks={blocks} />;
+ * }
+ */
 export function PageRenderer({ blocks }: { blocks: Block[] }): JSX.Element {
   const draftBlocks = useEditPreviewStore((state) => state.blocks);
   const reconcileDraftBlocks = useEditPreviewStore((state) => state.reconcile);

package/provider.tsx

@@ -61,8 +61,23 @@ interface StorefrontContextValue {
   locales?: StoreLocale[];
 }
 
+/** The context behind {@link StorefrontProvider}. Read it through the hooks; use it directly only to test for a provider without throwing. */
 export const StorefrontContext = createContext<StorefrontContextValue | null>(null);
 
+/**
+ * Gives every kit hook and component the store they render for: its profile,
+ * configuration, menus, locale, languages and strings. The Queek storefront
+ * mounts it for every theme, so a theme never renders it. Render it yourself
+ * only in a test, a preview or a script.
+ *
+ * `basePath` defaults to `/<vendor.slug>`; pass `''` for a store served on its
+ * own domain. Brand design tokens become CSS variables on a wrapping element.
+ *
+ * @example
+ * <StorefrontProvider vendor={vendor} config={config} menus={[]}>
+ *   <MySection />
+ * </StorefrontProvider>
+ */
 export function StorefrontProvider({
   vendor,
   config,
@@ -147,11 +162,22 @@ export function StorefrontProvider({
   );
 }
 
+/**
+ * The current store: `vendor`, `config`, `menus`, `basePath`, `locale` and the
+ * rest of what the host passed to {@link StorefrontProvider}.
+ *
+ * @throws {Error} when called outside a `StorefrontProvider`.
+ *
+ * @example
+ * const { vendor, config } = useStorefront();
+ */
 export function useStorefront(): StorefrontContextValue {
   const context = useContext(StorefrontContext);
 
   if (!context) {
-    throw new Error('useStorefront must be used within StorefrontProvider');
+    throw new Error(
+      'useStorefront() was called outside <StorefrontProvider>. Render the component inside StorefrontProvider (the Queek storefront does this for every theme). In a test, wrap it yourself.',
+    );
   }
 
   return context;
@@ -167,7 +193,7 @@ export function useStorefrontLocale(): string | null {
   const context = useContext(StorefrontContext);
 
   if (!context) {
-    throw new Error('useStorefrontLocale must be used within StorefrontProvider');
+    throw new Error('useStorefrontLocale() was called outside <StorefrontProvider>. Render the component inside StorefrontProvider.');
   }
 
   return context.locale ?? null;
@@ -188,7 +214,7 @@ export function useThemeStrings(): ThemeStringsFn {
   const context = useContext(StorefrontContext);
 
   if (!context) {
-    throw new Error('useThemeStrings must be used within StorefrontProvider');
+    throw new Error('useThemeStrings() was called outside <StorefrontProvider>. Render the component inside StorefrontProvider.');
   }
 
   const theme = useOptionalTheme();

package/sdk/client.ts

@@ -1,20 +1,38 @@
 import { getActivePlatform } from './platform';
 
-// SERVER-side only (SSR data fetching, server-to-server — never reaches the
-// browser, so the real absolute host is correct and required here).
-export const API_BASE_URL = process.env.QUEEK_API_URL ?? process.env.NEXT_PUBLIC_QUEEK_API_URL ?? 'http://127.0.0.1:8000/api/v1';
-// BROWSER-side only (createBrowserClient below, "for client components/hooks").
-// Hardcoded relative on purpose, same reasoning as queek-client.ts's
-// API_BASE_URL: the host app's `next.config` rewrite already proxies
-// /api/v1/client/:path* to the API server-side, so the browser never needs the
-// real host. This
-// used to read NEXT_PUBLIC_QUEEK_API_URL directly — when that's set to the
-// same absolute value as the server-side QUEEK_API_URL, every hook built on
-// createBrowserClient (products, shop, categories, reviews, related products,
-// product questions, QR collections) leaked api.usequeek.com straight into
-// the browser Network tab, bypassing the proxy entirely.
+const LOCAL_API_URL = 'http://127.0.0.1:8000/api/v1';
+const API_URL_FROM_ENV = process.env.QUEEK_API_URL ?? process.env.NEXT_PUBLIC_QUEEK_API_URL;
+
+/**
+ * Origin of the Queek API for SERVER-side reads (server rendering and
+ * server-to-server calls; this value never reaches the browser).
+ *
+ * Set `QUEEK_API_URL` (or `NEXT_PUBLIC_QUEEK_API_URL`) in the storefront host's
+ * environment. When neither is set the kit falls back to a local development
+ * address and warns once in production builds.
+ */
+export const API_BASE_URL = API_URL_FROM_ENV ?? LOCAL_API_URL;
+
+// BROWSER-side only (createBrowserClient below, for client components and hooks).
+// Always same-origin relative: the host app's `next.config` rewrite proxies
+// /api/v1/client/:path* to the API, so the browser never needs the API's real
+// host. Reading NEXT_PUBLIC_QUEEK_API_URL here would leak that host into every
+// browser request whenever the variable holds the same absolute value as the
+// server-side QUEEK_API_URL.
 const PUBLIC_API_BASE_URL = '/api/v1';
 
+let warnedAboutLocalApiUrl = false;
+
+function warnIfApiUrlUnset(baseUrl: string): void {
+  if (warnedAboutLocalApiUrl || baseUrl !== LOCAL_API_URL || API_URL_FROM_ENV !== undefined) return;
+  if (process.env.NODE_ENV !== 'production') return;
+  warnedAboutLocalApiUrl = true;
+  console.warn(
+    `[theme-kit] QUEEK_API_URL is not set, so server-side reads go to ${LOCAL_API_URL}. ` +
+      'Set QUEEK_API_URL to your Queek API origin in the storefront host environment.',
+  );
+}
+
 export interface RequestOptions extends RequestInit {
   query?: Record<string, string | number | boolean | string[] | null | undefined>;
   /** Abort budget. Omit to leave the request unbounded (browser default). */
@@ -42,41 +60,123 @@ export interface RequestCachePolicy {
 const BROWSER_GET_TIMEOUT_MS = 15_000;
 const BROWSER_POST_TIMEOUT_MS = 25_000;
 
+/** Stable machine-readable code for a failed request. Branch on this, not on the message. */
+export type ApiErrorCode =
+  | 'unauthenticated'
+  | 'forbidden'
+  | 'not_found'
+  | 'rate_limited'
+  | 'client_error'
+  | 'server_error'
+  | 'timeout';
+
+function codeForStatus(status: number): ApiErrorCode {
+  if (status === 401) return 'unauthenticated';
+  if (status === 403) return 'forbidden';
+  if (status === 404) return 'not_found';
+  if (status === 429) return 'rate_limited';
+  return status >= 500 ? 'server_error' : 'client_error';
+}
+
+function nextStepForStatus(status: number, retryAfterSeconds: number | null): string {
+  if (status === 401) return 'The customer session is missing or has expired. Ask the customer to sign in again.';
+  if (status === 403) return 'This session is not allowed to do that on this store.';
+  if (status === 404) return 'The resource does not exist, or it is not visible on this store. Check the slug or id.';
+  if (status === 429) {
+    return retryAfterSeconds === null
+      ? 'Too many requests. Wait a moment, then retry.'
+      : `Too many requests. Retry after ${retryAfterSeconds} seconds.`;
+  }
+  if (status >= 500) return 'The Queek API could not complete the request. Retry shortly; if it keeps failing, quote the request id to Queek support.';
+  return 'The API rejected the request. Check the inputs; `detail` carries the API message when it sent one.';
+}
+
+/** The request path without its query string, so messages and logs never carry search terms or tokens. */
+function pathOnly(url: string): string {
+  const end = url.search(/[?#]/);
+  return end === -1 ? url : url.slice(0, end);
+}
+
+/** Extra context an API failure can carry. All fields are optional. */
+export interface ApiRequestErrorDetails {
+  /** The API's request id (`x-request-id`), for support tickets. */
+  requestId?: string | null;
+  /** Seconds the API asked the caller to wait (`Retry-After`), when it sent one. */
+  retryAfterSeconds?: number | null;
+  /** The API's own error message, when its body carried one. */
+  detail?: string | null;
+}
+
 /**
+ * The API answered with a non-2xx status.
+ *
  * Carries the HTTP status so callers can tell a genuine "this does not exist"
  * (404) apart from an infrastructure failure (5xx, timeout, network). That
  * distinction is load-bearing in a host's vendor layout: 404 must render
- * not-found, while an API blip must NOT — a 404 on every URL of a live store
- * is how storefronts get deindexed.
+ * not-found, while an API blip must NOT, because a 404 on every URL of a live
+ * store is how storefronts get deindexed.
+ *
+ * @example
+ * try {
+ *   await client.get('/products/oak-chair');
+ * } catch (error) {
+ *   if (error instanceof ApiRequestError && error.code === 'not_found') return null;
+ *   throw error;
+ * }
  */
 export class ApiRequestError extends Error {
+  /** Stable machine code derived from the status. */
+  readonly code: ApiErrorCode;
+  /** True when repeating the same request later can succeed (429 and 5xx). */
+  readonly retryable: boolean;
+  readonly requestId: string | null;
+  readonly retryAfterSeconds: number | null;
+  readonly detail: string | null;
+
   constructor(
     public readonly status: number,
     public readonly url: string,
+    { requestId = null, retryAfterSeconds = null, detail = null }: ApiRequestErrorDetails = {},
   ) {
-    super(`Request failed with status ${status}`);
+    super(
+      `Request to ${pathOnly(url)} failed with status ${status}. ${nextStepForStatus(status, retryAfterSeconds)}` +
+        (requestId ? ` (request id ${requestId})` : ''),
+    );
     this.name = 'ApiRequestError';
+    this.code = codeForStatus(status);
+    this.retryable = status === 429 || status >= 500;
+    this.requestId = requestId;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.detail = detail;
   }
 }
 
 /**
+ * The request did not finish inside its time budget and was aborted.
+ *
  * Thrown in place of the raw `DOMException` that `AbortSignal.timeout()`
  * produces. `DOMException` passes `instanceof Error` but its `message` is a
- * getter with no setter — Next's dev bundler (`setup-dev-bundler.js`,
- * `logErrorWithOriginalStack`) unconditionally does `err.message = ...` on
- * anything `instanceof Error` when rendering the dev overlay, which crashes
- * with "Cannot set property message of ... which has only a getter" and
- * cascades into unhandledRejection noise. Rewrapping into a plain, settable
- * Error here — the one place every SSR/browser fetch funnels through — stops
- * that crash without touching the abort/timeout semantics themselves.
+ * getter with no setter, and Next's dev bundler unconditionally assigns
+ * `err.message` on anything `instanceof Error` when rendering its overlay,
+ * which crashes with "Cannot set property message of ... which has only a
+ * getter". Rewrapping into a plain, settable Error here, the one place every
+ * server and browser fetch funnels through, avoids that without changing the
+ * abort semantics. The original `DOMException` stays on `cause`.
  */
 export class ApiTimeoutError extends Error {
+  readonly code: ApiErrorCode = 'timeout';
+  /** A timed-out read can be repeated. A timed-out write may already have reached the API: do not repeat it blindly. */
+  readonly retryable = true;
+
   constructor(
     public readonly url: string,
     public readonly timeoutMs: number,
     { cause }: { cause?: unknown } = {},
   ) {
-    super(`Request to ${url} timed out after ${timeoutMs}ms`);
+    super(
+      `Request to ${pathOnly(url)} timed out after ${timeoutMs}ms. ` +
+        'Retry a read. For a write, check whether it was applied before sending it again.',
+    );
     this.name = 'ApiTimeoutError';
     this.cause = cause;
   }
@@ -94,6 +194,10 @@ export class ApiTimeoutError extends Error {
  * `status` is read structurally rather than via `instanceof`: the class is
  * emitted once per bundler layer, so an `instanceof` check across the RSC/SSR
  * boundary can be silently false.
+ *
+ * @example
+ * const product = await client.get<Product>(`/products/${slug}`).catch(swallowNotFound);
+ * if (!product) notFound();
  */
 export function swallowNotFound(error: unknown): null {
   if ((error as { status?: number } | null)?.status === 404) {
@@ -134,16 +238,48 @@ function withQuery(path: string, query?: RequestOptions['query']): string {
   return queryString === '' ? path : `${path}?${queryString}`;
 }
 
+function readRetryAfterSeconds(response: Response): number | null {
+  const raw = response.headers.get('retry-after');
+  if (raw === null) return null;
+  const seconds = Number(raw);
+  return Number.isFinite(seconds) && seconds >= 0 ? Math.ceil(seconds) : null;
+}
+
+async function readErrorDetail(response: Response): Promise<string | null> {
+  try {
+    const body = (await response.json()) as { message?: unknown } | null;
+    return typeof body?.message === 'string' ? body.message.slice(0, 300) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One JSON request to the Queek API. Everything the kit fetches goes through here.
+ *
+ * Only `/client/*` paths are accepted: that scope resolves the store and forces
+ * the sales channel, so prices are always the storefront's. A write is never
+ * retried: an aborted POST may already have reached the API, and sending it
+ * again could duplicate an order or a payment.
+ *
+ * @throws {ApiRequestError} on a non-2xx response (read `code`, `status`, `requestId`).
+ * @throws {ApiTimeoutError} when `timeoutMs` elapses first.
+ *
+ * @example
+ * const info = await request<{ data: { name: string } }>(API_BASE_URL, '/client/store/info', {
+ *   timeoutMs: 8000,
+ * });
+ */
 export async function request<T>(baseUrl: string, path: string, options: RequestOptions & { credentials?: RequestCredentials } = {}, extraHeaders?: Record<string, string>): Promise<T> {
-  // HARD RULE: the storefront only ever calls the `/v1/client/*` scope. That scope
-  // resolves the vendor AND forces the platform (storefront/instore_qr), so prices
-  // are always the storefront's (no marketplace commission). Legacy v1 routes
-  // (/products, /vendors/*, /categories) skip that resolution → wrong platform →
-  // wrong price. Never call them from here.
   if (!path.startsWith('/client/')) {
-    throw new Error(`Storefront may only call /v1/client/* routes — got "${path}". Use createServerStoreClient / createBrowserClient (which prefix /client/store).`);
+    throw new Error(
+      `Refused to call "${path}": storefront code may only call /client/* routes, which resolve the store and force the storefront sales channel. ` +
+        'Use createServerStoreClient (server) or createBrowserClient (browser); both add the /client/store prefix.',
+    );
   }
 
+  warnIfApiUrlUnset(baseUrl);
+
   const { query, timeoutMs, cachePolicy, ...init } = options;
   const url = `${baseUrl}${withQuery(path, query)}`;
 
@@ -155,9 +291,9 @@ export async function request<T>(baseUrl: string, path: string, options: Request
   };
 
   // Only idempotent, unauthenticated reads may be cached. A POST must always
-  // reach the origin, and a bearer token means the response is per-user — the
-  // data cache is shared across every visitor, so caching either would serve one
-  // customer's data to another.
+  // reach the origin, and a bearer token means the response is per-user: the
+  // data cache is shared across every visitor, so caching either would serve
+  // one customer's data to another.
   const method = (init.method ?? 'GET').toUpperCase();
   const cacheable = method === 'GET' && headers.Authorization === undefined && !!cachePolicy;
 
@@ -182,7 +318,11 @@ export async function request<T>(baseUrl: string, path: string, options: Request
   }
 
   if (!response.ok) {
-    throw new ApiRequestError(response.status, url);
+    throw new ApiRequestError(response.status, url, {
+      requestId: response.headers.get('x-request-id'),
+      retryAfterSeconds: readRetryAfterSeconds(response),
+      detail: await readErrorDetail(response),
+    });
   }
 
   return response.json() as Promise<T>;
@@ -193,8 +333,15 @@ export async function request<T>(baseUrl: string, path: string, options: Request
 // is always forced server-side. Do NOT reintroduce a raw-v1 client here.
 
 /**
- * Browser-side client for client components/hooks.
- * Uses client-store routes (/client/store/*) with Origin + X-Vendor-Slug vendor resolution.
+ * Browser-side client for client components and hooks.
+ *
+ * Calls the same-origin `/api/v1/client/store/*` routes, resolving the store from
+ * the page origin plus the `X-Vendor-Slug` header. Reads time out after 15 s and
+ * writes after 25 s. Failures throw `ApiRequestError` or `ApiTimeoutError`.
+ *
+ * @example
+ * const client = createBrowserClient(vendor.slug);
+ * const { data } = await client.get<{ data: Product[] }>('/products', { per_page: 8 });
  */
 export function createBrowserClient(vendorSlug?: string, token?: string): {
   get: <T>(path: string, query?: RequestOptions['query']) => Promise<T>;