@usequeek/theme-kit 0.1.22 → 0.1.24

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to `@usequeek/theme-kit`. See the README for the versioning
+policy. Versions before this file started are in the git tags.
+
+## 0.1.24 - 2026-10-12
+
+### Added
+
+- `ApiRequestError` and `ApiTimeoutError` carry a stable `code` (`unauthenticated`,
+  `forbidden`, `not_found`, `rate_limited`, `client_error`, `server_error`,
+  `timeout`) and a `retryable` flag. `ApiRequestError` also carries `requestId`,
+  `retryAfterSeconds` and `detail`. Their messages say what happened and what to do
+  next, and never include the query string.
+- The fetching hooks (`useProducts`, `useProductBySlug`, `useShop`, `usePosts`,
+  `useReviews`, `useProductQuestions`, `useCategories`, `useRelatedProducts`,
+  `useProductDetail`) return an `error` field (`Error | null`).
+- One warning, in production builds only, when `QUEEK_API_URL` is not set.
+- JSDoc with examples on the hooks, providers, clients, stores and the main
+  components.
+
+### Fixed
+
+- `useProducts` and `useShop` no longer leave an unhandled promise rejection when
+  the request fails.
+- Slugs and ids are URL-encoded when they are placed in a request path
+  (products, collections, related products, questions, orders).
+- Google sign-in no longer logs the sign-in URL or the response body.
+- Hook errors raised outside a provider name the missing provider and the fix.
+
+### Packaging
+
+- The published package no longer contains `tests/` or `scripts/`.
+- Peer dependency `@queekai/client-sdk` is `^0.3.1 || ^0.4.0` (was `*`); `engines.node` is
+  `>=22`; `bugs`, `homepage`, `author` and `keywords` are set; releases publish
+  with npm provenance.
+- The licence names the legal entity, Queekx Technology LTD.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Queek
+Copyright (c) 2026 Queekx Technology LTD
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,9 +1,21 @@
 # @usequeek/theme-kit
 
-The framework a Queek storefront theme is built against: hooks, stores, headless
-flows (auth, cart, checkout), types and the block renderer. See the
-[theme documentation](https://docs.usequeek.com/docs/themes) for how themes
-work end to end.
+The runtime a Queek storefront theme is built on: hooks for products, cart, auth
+and search, state stores, the page and block renderer, navigation, shared blocks,
+and locale strings. A theme is React components and CSS; this kit supplies
+everything that talks to Queek. See the
+[theme documentation](https://docs.usequeek.com/docs/themes) for how themes work
+end to end.
+
+## Requirements
+
+- **Next.js 15 or later (App Router)**, `react` and `react-dom` 19 or later. The
+  kit imports `next` itself (links, navigation, server request headers), so it
+  runs inside a Next.js app, not in a bare React app.
+- `@queekai/client-sdk` `^0.3.1 || ^0.4.0`, the Queek customer SDK the auth and checkout
+  hooks call.
+- Node.js 22 or later (the version CI tests on).
+- TypeScript with `moduleResolution: bundler` and `jsx: react-jsx`.
 
 ## Install
 
@@ -11,9 +23,6 @@ work end to end.
 npm install @usequeek/theme-kit
 ```
 
-Peer dependencies: `next` (>=15), `react` and `react-dom` (>=19) and
-`@queekai/client-sdk`.
-
 The package ships TypeScript source, not a build. Most modules carry a
 `'use client'` directive, and that directive is the whole contract with the
 React Server Components boundary; bundlers routinely strip or hoist it when a
@@ -26,10 +35,57 @@ bundler that enforces them:
 export default { transpilePackages: ['@usequeek/theme-kit'] };
 ```
 
-Compiling a theme against it needs `moduleResolution: bundler` and
-`jsx: react-jsx`. A vitest setup that renders kit components needs the package
-inlined (`server.deps.inline: ['@usequeek/theme-kit']`) so the shipped `.tsx`
-source is transformed like first-party code.
+A vitest setup that renders kit components needs the package inlined
+(`server.deps.inline: ['@usequeek/theme-kit']`) so the shipped `.tsx` source is
+transformed like first-party code.
+
+## Quickstart
+
+A product list that loads, handles a failed request, links to each product and
+adds to the cart:
+
+```tsx
+'use client';
+
+import { useCart } from '@usequeek/theme-kit/hooks/use-cart';
+import { useHref } from '@usequeek/theme-kit/hooks/use-href';
+import { useProducts } from '@usequeek/theme-kit/hooks/use-products';
+import { Link } from '@usequeek/theme-kit/navigation';
+import { formatMoney } from '@usequeek/theme-kit/utils/format';
+
+export function PopularProducts() {
+  const { products, isLoading, error } = useProducts({ limit: 4, sort: 'popular' });
+  const { addProduct } = useCart();
+  const href = useHref();
+
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>We could not load products. Please try again.</p>;
+
+  return (
+    <ul>
+      {products.map((product) => (
+        <li key={product.id}>
+          <Link href={href(`/products/${product.slug}`)}>{product.title}</Link>
+          <span>{formatMoney(product.pricing.sale_amount, product.currency)}</span>
+          <button type="button" onClick={() => addProduct(product)}>
+            Add to cart
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+The storefront mounts `StorefrontProvider` for every theme, so a theme never
+renders it. Hooks called outside it throw an error that says so. In a test or a
+script, wrap the component yourself:
+
+```tsx
+<StorefrontProvider vendor={vendor} config={config} menus={[]}>
+  <PopularProducts />
+</StorefrontProvider>
+```
 
 ## Use
 
@@ -53,6 +109,71 @@ Theme CSS ships with the package: `@usequeek/theme-kit/shared-blocks/core-blocks
 (framework-owned blocks), plus per-component CSS next to its component
 (`components/variant-picker.css`, `apps/apps.css`).
 
+### Hooks
+
+The hooks that fetch (products, shop, categories, posts, reviews, questions,
+related products, product detail) report failure through an `error` field (an
+`Error`, or `null`). They never throw and never leave an unhandled rejection, and
+they keep the data already on screen. They return `isLoading`, except
+`useProductDetail`, which returns `loadingDetail`. In preview, hooks read
+`previewData` from the provider and make no request.
+
+| Hook | Module | Returns |
+| --- | --- | --- |
+| `useProducts(options?)` | `hooks/use-products` | A product list: `{ products, isLoading, error }` |
+| `useProductBySlug(slug)` | `hooks/use-products` | One product by slug: `{ product, isLoading, error }` |
+| `useProductDetail(listProduct, isOpen, vendorSlug?, locale?)` | `hooks/use-product-detail` | A list product completed with variants and add-ons |
+| `useRelatedProducts(slug, limit?)` | `hooks/use-related-products` | Related products |
+| `useShop(options?)` + `useShopParams()` | `hooks/use-shop`, `hooks/use-shop-params` | The shop catalogue page and its URL state |
+| `useCollectionParams()` | `hooks/use-collection-params` | Search, sort and page state for a collection page |
+| `useCategories(options?)` | `hooks/use-categories` | Categories, flattened |
+| `usePosts(options?)` | `hooks/use-posts` | Blog posts |
+| `useReviews(block)` | `hooks/use-reviews` | Reviews and the rating summary |
+| `useProductQuestions(block)` | `hooks/use-product-questions` | Product questions and answers |
+| `useCart()` / `useShopCart(shopId)` | `hooks/use-cart`, `hooks/use-shop-cart` | The cart and its actions; one shop's lines and totals |
+| `useAuth()` | `hooks/use-auth` | The signed-in customer and sign-in modal controls |
+| `useVariantSelection(product)` | `hooks/use-variant-selection` | Option selection state and the add-to-cart gate |
+| `useSearch(query, products, collections)` | `hooks/use-search` | Instant search over data you hold |
+| `useAddressAutocomplete(text)` / `useResolveCoordinates()` | `hooks/use-address-autocomplete`, `hooks/use-resolve-coordinates` | Delivery address lookup |
+| `useHref()` | `hooks/use-href` | Builds a store-relative link |
+| `useLocales()` | `hooks/use-locales` | The store's languages and the active one |
+| `useStorefront()` / `useStorefrontLocale()` / `useThemeStrings()` | `provider` | The store, the request locale, the bound `t` |
+
+## Errors
+
+Requests go through one place (`sdk/client.ts`). A non-2xx answer throws
+`ApiRequestError`, a request that outlives its budget throws `ApiTimeoutError`.
+Branch on `code`, never on the message:
+
+| Field | Meaning |
+| --- | --- |
+| `code` | `unauthenticated` (401), `forbidden` (403), `not_found` (404), `rate_limited` (429), `client_error` (other 4xx), `server_error` (5xx), `timeout` |
+| `status`, `url` | The HTTP status and the full request URL (`ApiRequestError` only) |
+| `retryable` | `true` for 429, 5xx and timeouts. The kit never retries a write on its own: a timed-out POST may already have reached the API. |
+| `requestId` | The API's `x-request-id`, for a support ticket |
+| `retryAfterSeconds` | The API's `Retry-After`, when it sent one |
+| `detail` | The API's own error message, when its body carried one |
+| `cause` | The original `DOMException` (`ApiTimeoutError` only) |
+
+Messages never include the query string, so search terms stay out of logs.
+Server-side fetchers that must render "not found" for a missing resource use
+`swallowNotFound`, which returns `null` for a 404 and rethrows everything else,
+so an API outage never shows as a missing page.
+
+## Configuration (storefront host)
+
+Themes set none of these; the storefront host does.
+
+| Variable | Used for |
+| --- | --- |
+| `QUEEK_API_URL` (or `NEXT_PUBLIC_QUEEK_API_URL`) | Origin of the Queek API for server-side reads. Without it the kit falls back to `http://127.0.0.1:8000/api/v1` and warns once in production builds. |
+| `NEXT_PUBLIC_QUEEK_AUTH_URL` | Origin of the sign-in service (default `https://auth.usequeek.com`). |
+| `STOREFRONT_DOMAIN` | Domain whose subdomains are store slugs (default `queek.com.ng`). |
+| `CUSTOM_DOMAIN_VENDOR_MAP` | JSON object mapping a custom domain to a store slug. |
+
+Browser requests are always same-origin (`/api/v1/client/*`), so the host needs
+a rewrite from that path to the API. The browser never learns the API origin.
+
 ## Theme strings
 
 The kit's UI-string mechanism (`strings/theme-strings.ts`; pure, with no
@@ -292,7 +413,7 @@ export default function Footer() {
 - MUST: place `<PoweredByQueek />` on every footer variant (`footers/*.tsx`,
   or `footer.tsx` where a theme has no `footers/` dir). The placement and
   spacing are the theme's — the component is the content, the footer owns
-  where it sits. The theme check rule `theme/footer-shows-powered-by`
+  where it sits. The `theme/footer-shows-powered-by` rule of `npm run check`
   ([checks reference](https://docs.usequeek.com/docs/themes/checks)) enforces
   this, so a theme cannot ship without it.
 - Style only: the link emits `core-powered-by` with a
@@ -346,8 +467,10 @@ keeps the page, the query string and the hash.
 ```tsx
 import { LanguageSwitcher } from '@usequeek/theme-kit/components/language-switcher';
 
-<LanguageSwitcher />                        // native <select> (default)
-<LanguageSwitcher variant="inline-list" />  // every language as a link
+<LanguageSwitcher variant="menu" />                  // button + popover (sheet on phones) — recommended
+<LanguageSwitcher variant="menu" side="top" />       // a footer: opens upward
+<LanguageSwitcher variant="inline-list" />           // every language as a link (footer, up to four)
+<LanguageSwitcher />                                 // native <select> — legacy
 ```
 
 Place it unconditionally, in the header or the footer: it renders nothing on a
@@ -357,10 +480,114 @@ store's languages.
 | Prop | Default | |
 | --- | --- | --- |
 | `className` | | Extra class on the root, to position or restyle it. |
-| `variant` | `'select'` | `'select'`: one native dropdown (best keyboard, touch and screen-reader behaviour). `'inline-list'`: a link per language that wraps on narrow screens; suits a footer. |
+| `variant` | `'select'` | `'menu'`: a trigger button and a list of language links (below). `'inline-list'`: a link per language that wraps on narrow screens. `'select'`: one native dropdown, **legacy** — it works and is unchanged, but its open list is the operating system's menu and cannot be styled; prefer `menu`. |
+| `side` | `'bottom'` | `menu` only. `'top'` opens above the trigger, for footers. Flips by itself when the preferred side does not fit. |
+| `align` | `'end'` | `menu` only. Line the popover up with the trigger's inline `'end'` or `'start'` edge (mirrors in right-to-left). Flips and shifts to stay inside the viewport. |
 | `showNativeName` | `true` | Label languages in their own language (`Français`) instead of English (`French`). |
-| `showCode` | `false` | Append the code: `Français · FR`. |
-| `children` | | Render-prop `(state) => ReactNode`: replaces the default control entirely (never called on a single-language store). `state` is `useLocales()` plus `label`, `labelFor(locale)` and `displayName(locale)`. |
+| `showCode` | `false` | Show the language code (`FR`) next to the name. |
+| `children` | | Render-prop `(state) => ReactNode`: replaces the default control entirely (never called on a single-language store). `state` is `useLocales()` plus `label`, `labelFor(locale)`, `displayName(locale)`, `open` and `setOpen`. |
+
+### The `menu` variant
+
+A real `<button>` opens a list of language **links** (`<a href>` built from the
+current page, so open-in-new-tab and copy-link work). On screens wider than
+640px it is a popover under the trigger; below 640px it becomes a bottom sheet
+with a scrim, safe-area padding, and page scroll locked while it is open. The
+wide/narrow layout switch is CSS only (one media query), so the markup is the
+same on both and server and client agree; JavaScript only consults the media
+query while the menu opens, to lock scroll and to place the popover.
+With more than four languages in a footer, use `menu` with `side="top"` rather
+than `inline-list`. 2 to 20 languages are fine: the list scrolls past about
+eight rows, and a long list can use two columns on wide screens (below).
+
+It is the *disclosure* pattern, not a listbox, because choosing an item
+navigates: the button has `aria-expanded` and `aria-controls` and the name
+"Language: English"; the list is a `<ul>` labelled by its title; the current
+language's link has `aria-current="true"`; there are no `option` roles.
+
+| Key | |
+| --- | --- |
+| Enter, Space, ArrowDown on the button | Open, focus on the current language |
+| ArrowUp on the button | Open, focus on the last language |
+| ArrowDown / ArrowUp in the list | Next / previous link (wraps) |
+| Home / End | First / last link |
+| Typing letters | Jump to the language whose name or code starts with them (500 ms buffer) |
+| Enter on a link | Follow it (native); Space does the same |
+| Escape | Close and return focus to the button |
+| Tab | Close the menu |
+| Click outside, scrim tap | Close |
+
+Only the focused link is in the tab order (roving tabindex), so Tab leaves the
+list and closes it. Choosing a language closes the menu, returns focus to the
+button and navigates (a modified click — new tab, copy link — is left to the
+browser). Motion respects `prefers-reduced-motion` (an 80 ms fade only).
+
+**Styling surface.** Every part has a class and a `data-part` attribute; the
+root also carries state attributes:
+
+| Part | Class | `data-part` |
+| --- | --- | --- |
+| Root | `qn-lang qn-lang--menu` | `data-qn-language-switcher`, `data-variant="menu"` |
+| Trigger button | `qn-lang__trigger` | `trigger` |
+| Trigger name / code / chevron | `qn-lang__trigger-label` / `__trigger-code` / `__chevron` | `trigger-label` / `trigger-code` / `chevron` |
+| Scrim (sheet) | `qn-lang__scrim` | `scrim` |
+| Popover / sheet | `qn-lang__popover` | `popover` |
+| Sheet grabber | `qn-lang__handle` | `handle` |
+| Group label | `qn-lang__title` | `title` |
+| List / item | `qn-lang__options` / `__item` | `list` / `item` |
+| Link (current: `aria-current="true"`, `data-current="true"`) | `qn-lang__option` | `option` |
+| Name / code / current marker | `qn-lang__name` / `__code` / `__mark` | `name` / `code` / `mark` |
+
+Root attributes: `data-state="open|closed"`, `data-side="bottom|top"`,
+`data-align="start|end"`, `data-mode="popover|sheet"` (while open),
+`data-count="<n>"`, `data-many="true"` (more than ten languages),
+`data-show-code="true"`. The code spans are always rendered and hidden by
+default, so a theme can show a code-only trigger with
+`.my-header [data-part='trigger-label'] { display: none }` plus
+`.my-header [data-part='trigger-code'] { display: inline }`.
+
+| Variable | Default | Controls |
+| --- | --- | --- |
+| `--qn-lang-surface` | `--qn-surface` | popover / sheet background |
+| `--qn-lang-ink` | `--qn-text` | text colour |
+| `--qn-lang-muted` | `--qn-text-muted` | title and code colour |
+| `--qn-lang-border` | `--qn-border` | hairlines |
+| `--qn-lang-radius` | `--qn-radius-md` (8px) | trigger / popover corners |
+| `--qn-lang-item-radius` | `--qn-radius-sm` (6px) | link corners |
+| `--qn-lang-item-hover` / `--qn-lang-current-bg` | 6% ink / none | hover and current-link backgrounds |
+| `--qn-lang-accent` | `--qn-accent` | current marker colour |
+| `--qn-lang-focus` | `--qn-focus` | focus ring |
+| `--qn-lang-shadow` | subtle | popover shadow |
+| `--qn-lang-row-height` / `--qn-lang-sheet-row-height` | 44px / 52px | link height (popover / sheet) |
+| `--qn-lang-gap` / `--qn-lang-pad` | 0 / 4px | space between links / inside the popover |
+| `--qn-lang-offset` | 8px | gap between trigger and popover |
+| `--qn-lang-popover-width` | 240px | popover width |
+| `--qn-lang-many-width` / `--qn-lang-many-columns` | popover width / 1 | width and columns when `data-many="true"` (set `--qn-lang-many-columns: 2` and a wider width for two columns) |
+| `--qn-lang-list-max` | 8.5 rows | height at which the list scrolls |
+| `--qn-lang-sheet-radius` | 16px | sheet top corners |
+| `--qn-lang-scrim` | 40% black | scrim colour |
+| `--qn-lang-z` | 50 | z-index |
+| `--qn-lang-duration` / `--qn-lang-ease` | 160ms / ease-out curve | open motion |
+
+Each variable falls back to the matching `--qn-*` token, then a neutral
+value, and is never set by the kit itself — set it on the root, on an
+ancestor, or on `:root`. The sheet breakpoint (640px) is fixed.
+
+Restyling recipe — no override of internals needed:
+
+```css
+.site-header [data-qn-language-switcher] {
+  --qn-lang-surface: #f3f0e9;
+  --qn-lang-ink: #1b2029;
+  --qn-lang-radius: 0;
+  --qn-lang-item-radius: 0;
+  --qn-lang-popover-width: 280px;
+  --qn-lang-sheet-radius: 0;
+  --qn-lang-duration: 120ms;
+}
+.site-header [data-part='trigger'] { border: 0; letter-spacing: 0.12em; text-transform: uppercase; }
+.site-header [data-part='option'][aria-current='true'] { font-style: italic; }
+```
 
 **Tell the storefront the theme places it.** Set `languageSwitcher: 'theme'` in
 the theme manifest. Without it the storefront keeps rendering its own floating
@@ -432,8 +659,8 @@ the kit is the one place that knows it, and a framework change is a kit
 release, not an update to every theme. `Link` is an `<a>` that moves inside the
 store without a full page load (`href`, `prefetch`, `replace`, plus any anchor
 attribute); `useRouter()` gives `push`, `replace`, `back` and `refresh`;
-`usePathname()` returns the current path. The theme check rejects a theme that
-imports `next`.
+`usePathname()` returns the current path. `npm run check` in the theme starter rejects a
+theme that imports `next`.
 
 ## Boundary
 
@@ -443,7 +670,7 @@ framework: the kit may import `next`, a theme may not.
 ## Develop
 
 ```bash
-npm install
+npm ci
 npm run typecheck       # tsc --noEmit
 npm test                # public-text check, then vitest run
 npm run verify-package  # pack current source, typecheck a real theme against it
@@ -454,19 +681,41 @@ it from a sandbox, so a break that only external consumers would see (for
 example a module relying on the global `JSX` namespace, which React 19 removed)
 fails here instead of after publishing.
 
+## Versioning
+
+The kit is pre-1.0 (`0.x`). A change to the surface the barrels declare that can
+break a theme ships in a minor version and is listed in
+[CHANGELOG.md](./CHANGELOG.md); patch versions are fixes and additions. Pin a
+minor version (`~0.1.23`) if a theme must not move on its own.
+
 ## Release
 
-Publishing runs on tags via `.github/workflows/publish.yml`, which needs the
-`NPM_TOKEN` repository secret:
+Publishing runs on tags via `.github/workflows/publish.yml`, through npm
+trusted publishing (no stored token), with provenance:
 
 ```bash
-# 1. Bump version in package.json and commit
-# 2. Tag and push the tag — the workflow typechecks, tests, runs verify-package,
-#    then `npm publish --access public`:
+# 1. Bump version in package.json, add the CHANGELOG entry, commit
+# 2. Tag and push the tag. The workflow typechecks, tests, runs verify-package,
+#    then `npm publish --provenance --access public`:
 git tag vX.Y.Z
 git push origin main --tags
 ```
 
+## Contributing
+
+Open an issue or a pull request at
+[usequeek/theme-kit](https://github.com/usequeek/theme-kit). Run `npm run typecheck`
+and `npm test` before you push; CI runs both plus `verify-package`. Keep a change
+to the public surface small, documented with a JSDoc `@example`, and recorded in
+the CHANGELOG.
+
+## Security
+
+The kit holds no secrets and only calls the Queek API's `/client/*` routes (a
+guard in `sdk/client.ts` refuses anything else). Customer tokens live in the
+browser's `localStorage`. To report a vulnerability, use GitHub's private
+vulnerability reporting on this repository rather than a public issue.
+
 ## License
 
-MIT
+MIT, copyright Queekx Technology LTD. See [LICENSE](./LICENSE).

package/api/collections.ts

@@ -8,6 +8,7 @@ import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
  *  gets a 422 from the API. */
 export type CollectionSort = 'newest' | 'popular' | 'price_low' | 'price_high';
 
+/** Options for `fetchCollectionProducts`. */
 export interface FetchCollectionProductsOptions {
   page?: number;
   perPage?: number;
@@ -20,6 +21,10 @@ export interface FetchCollectionProductsOptions {
 // SSR collection reads go through `/client/store/*`, which resolves the store and
 // forces X-Platform=storefront (base prices, no marketplace commission) — never
 // the legacy v1 routes shared with the marketplace.
+/**
+ * The store's collections, for server components. Returns `[]` when the store
+ * has none. A 404 becomes `[]`; any other failure (timeout, 5xx) throws.
+ */
 export async function fetchCollections(vendorSlug: string, storefrontOnly = true, locale?: string): Promise<Collection[]> {
   const client = createServerStoreClient(vendorSlug, await getRequestOrigin());
 
@@ -36,12 +41,20 @@ export async function fetchCollections(vendorSlug: string, storefrontOnly = true
   }
 }
 
+/** One collection by slug, or `null` when it is not in the store's list. */
 export async function fetchCollection(vendorSlug: string, slug: string, locale?: string): Promise<Collection | null> {
   const collections = await fetchCollections(vendorSlug, true, locale);
 
   return collections.find((collection) => collection.slug === slug) ?? null;
 }
 
+/**
+ * A collection and one page of its products, for server components.
+ *
+ * A missing collection gives `{ collection: null, products: [] }`.
+ *
+ * @throws {ApiRequestError} on any other API failure (timeout, 5xx).
+ */
 export async function fetchCollectionProducts(
   vendorSlug: string,
   slug: string,
@@ -63,7 +76,7 @@ export async function fetchCollectionProducts(
   try {
     const [collection, response] = await Promise.all([
       fetchCollection(vendorSlug, slug, options?.locale),
-      client.get<ApiResponse<unknown, Record<string, unknown>>>(`/collections/${slug}/products`, query, options?.locale),
+      client.get<ApiResponse<unknown, Record<string, unknown>>>(`/collections/${encodeURIComponent(slug)}/products`, query, options?.locale),
     ]);
 
     return {

package/api/orders.ts

@@ -1,6 +1,15 @@
 import { createBrowserClient } from '../sdk/client';
 import type { OrderListResponse, OrderDetail } from '../types/order';
 
+/**
+ * One page of the current customer's orders (`GET /client/store/orders`). Pass
+ * a `status` to filter; `'all'` or omitted means no filter.
+ *
+ * @throws {ApiRequestError} when the API refuses; `code: 'unauthenticated'` means the customer must sign in.
+ *
+ * @example
+ * const { data } = await fetchOrders(vendor.slug, 1, 'completed');
+ */
 export async function fetchOrders(
   vendorSlug: string,
   page = 1,
@@ -13,11 +22,16 @@ export async function fetchOrders(
   });
 }
 
+/**
+ * One of the current customer's orders, by id.
+ *
+ * @throws {ApiRequestError} with `code: 'not_found'` when the order does not exist for this customer.
+ */
 export async function fetchOrderDetail(
   vendorSlug: string,
   id: string,
 ): Promise<OrderDetail> {
   const client = createBrowserClient(vendorSlug);
-  const res = await client.get<{ data: OrderDetail }>(`/orders/${id}`);
+  const res = await client.get<{ data: OrderDetail }>(`/orders/${encodeURIComponent(id)}`);
   return res.data;
 }

package/apps/follow-card.tsx

@@ -41,6 +41,11 @@ const POSITION_CLASS: Record<string, string> = {
   'center-left': 'core-follow-card--center-left',
 };
 
+/**
+ * The store's follow card, shown when the merchant has turned it on. It is
+ * floating by default; `display="inline"` places it in the page flow. Renders
+ * nothing when the app is off.
+ */
 export function FollowCard({ display }: { display?: 'floating' | 'inline' } = {}): JSX.Element | null {
   const { config, vendor } = useStorefront();
   const followConfig = config.apps?.follow_card;

package/apps/subscribe-form.tsx

@@ -22,8 +22,8 @@ type Status = 'idle' | 'saving' | 'done' | 'error';
  * The `subscribe` app's `inline` variant (the theme-declared default) — a
  * theme's own `getSubscribeForm` dispatch renders this directly, passing
  * heading/tagline/cta straight through with no gate of its own; gating on
- * `config.apps?.subscribe?.enabled` happens once, centrally, in whichever
- * variant dispatch mounts it (see vendor-shell.tsx / a theme's footer).
+ * `config.apps?.subscribe?.enabled` happens once, centrally, by whatever
+ * mounts it (the storefront host, or a theme's footer).
  */
 export function SubscribeForm({
   heading = 'Stay in the loop',

package/components/auth/auth-flow.tsx

@@ -18,6 +18,18 @@ function AuthFlowInner(): JSX.Element | null {
   return null;
 }
 
+/**
+ * The kit's customer sign-in and sign-up flow (email code, email and password,
+ * and Google), rendered step by step. A theme that wants its own sign-in
+ * layout provides `AuthRenderer` in its module and renders this inside it. Its
+ * markup carries `core-auth*` classes for your CSS, and every string goes
+ * through the theme strings (`auth.*`).
+ *
+ * @example
+ * export function AuthRenderer() {
+ *   return <div className="my-auth-card"><AuthFlow /></div>;
+ * }
+ */
 export function AuthFlow(): JSX.Element {
   return (
     <AuthFlowProvider>

package/components/cart/cart-panel-controller.tsx

@@ -10,6 +10,7 @@ import { useShopCart } from '../../hooks/use-shop-cart';
 import { useCartPanelStore } from '../../stores/cart-panel-store';
 import { normalizeCurrencyCode } from '../../utils/format';
 
+/** What {@link CartPanelController} hands to your render function: the panel state, this shop's lines, and the actions that change them. */
 export interface CartPanelControllerRenderProps {
   isOpen: boolean;
   items: CartItem[];
@@ -23,6 +24,18 @@ export interface CartPanelControllerRenderProps {
   onRemove: (id: string, shopId: string) => void;
 }
 
+/**
+ * Headless controller for a cart panel (drawer). It owns open and close state,
+ * the Escape key, scroll locking and navigation to checkout; you own the markup.
+ * Open it from anywhere with `useCartPanelStore.getState().open()`.
+ *
+ * @example
+ * <CartPanelController>
+ *   {({ isOpen, items, total, onClose, onCheckout }) =>
+ *     isOpen ? <MyDrawer items={items} total={total} onClose={onClose} onCheckout={onCheckout} /> : <></>
+ *   }
+ * </CartPanelController>
+ */
 export function CartPanelController({
   children,
 }: {

package/components/checkout/default-checkout-shell.tsx

@@ -8,6 +8,11 @@ import { CheckoutContactSection } from './checkout-contact';
 import { useThemeStrings } from '../../provider';
 import { PolicyLinks } from './policy-links';
 
+/**
+ * The kit's default checkout layout. The storefront fills its slots (address,
+ * payment, promo, fees, submit) and passes them in; a theme can replace the
+ * whole shell by providing its own checkout component.
+ */
 export function DefaultCheckoutShell({
   cartItems,
   deliveryModes,

package/components/checkout/policy-links.tsx

@@ -23,6 +23,10 @@ function subscribeNoop(): () => void {
   return () => {};
 }
 
+/**
+ * Links to the store's published policies (returns, shipping, privacy, terms).
+ * Each opens in the kit's policy modal. Renders nothing when `policies` is empty.
+ */
 export function PolicyLinks({ policies }: { policies: Page[] }): JSX.Element | null {
   const t = useThemeStrings();
   const activeSlug = usePolicyModalStore((s) => s.activeSlug);

package/components/image.tsx

@@ -23,6 +23,7 @@ const PLACEHOLDER_SVG = `data:image/svg+xml,${encodeURIComponent(
   </svg>`,
 )}`;
 
+/** A labelled placeholder drawn in place of an image that is missing or failed to load. Size it to the space the image will fill. */
 export interface PlaceholderProp {
   label?: string;
   sublabel?: string;
@@ -59,6 +60,15 @@ type ImageProps = ImgHTMLAttributes<HTMLImageElement> & {
  */
 type LoadStage = 'primary' | 'original' | 'failed';
 
+/**
+ * The kit's image element. Use it instead of a raw `<img>`: it picks a
+ * responsive `srcset` from the API's image variants, retries the original file
+ * when a resized one fails, and falls back to `fallback` or a branded
+ * placeholder. It accepts every `<img>` attribute.
+ *
+ * @example
+ * <Image src={product.media.image ?? ''} variants={product.media.image_variants} intent="card" alt={product.title} />
+ */
 export function Image({ fallback, placeholder, variants, intent = 'raw', onError, ...props }: ImageProps) {
   const [stage, setStage] = useState<LoadStage>('primary');
   // Read context directly — returns null outside a StorefrontProvider