@wocart/storefront 0.0.0-stage → 1.1.0

package/USAGE.md

@@ -0,0 +1,1470 @@
+# @wocart/storefront — the guide
+
+## What this guide is for
+
+This guide is the working contract between a Wocart storefront theme and the
+store's server.
+
+It is written for:
+
+- A first-time theme developer who wants to focus on layout, motion, copy,
+  photography, and conversion.
+- A vibe coder using an AI agent to build or change a theme safely.
+- An experienced developer who needs the exact data, failure, checkout, and
+  security boundaries.
+
+The SDK is the stable seam between the creative theme layer and the Wocart
+platform. Your theme should decide how the store feels and looks. The SDK and
+the server decide what products, prices, delivery options, policies, and order
+states are valid.
+
+Read this document in order the first time. For a focused task, start with the
+namespace table, then open the section for the namespace you need.
+
+## The mental model
+
+There are three layers:
+
+1. **Theme UI** — Astro pages, components, CSS, client-side interactions,
+   content presentation, loading states, empty states, and error messages.
+2. **Storefront SDK** — typed client methods, form schemas, action helpers,
+   browser proxy helpers, money formatting, and image URL helpers.
+3. **The server** — the source of truth for catalog visibility, prices, stock,
+   offers, checkout policy, delivery rates, OTP, order creation, tracking, and
+   authorization.
+
+A theme does not query the database. A theme does not reimplement pricing. A browser
+bundle does not receive the store API key. A theme renders the result it gets
+from the SDK and gives the shopper a useful next action when the result is
+empty or unsuccessful.
+
+The SDK is a theme boundary, not a second business-logic layer. If a feature
+requires a new server rule, change the server contract first and then update
+the SDK usage.
+
+## Canonical domain vocabulary
+
+Use the SDK's names when describing storefront data in theme code, tickets, or
+AI-agent prompts. These names prevent a UI concept from quietly becoming a
+second business rule:
+
+| SDK term | Meaning | Authority |
+| --- | --- | --- |
+| `ProductListItem` | Compact product projection for grids, cards, and search | server |
+| `ProductDetail` | Complete product projection for a product page | server |
+| `Basket` | Browser-owned shopper intent; it may be empty while persisted | browser, never the server |
+| `BasketLine` | One product-plus-variant identity with an optimistic display price | browser intent |
+| `BasketLineInput` | The wire projection of one basket line (`pricePerUnit` is display-only) — what `cart.validate()` and `/api/cart/validate` accept | SDK |
+| `CheckoutDraft` | Mutable customer, delivery, basket, custom-field, attribution, and OTP input | theme/SDK until submitted |
+| `DeliverySelection` | Wilaya, commune, delivery mode, and optional address | server policy decides validity |
+| `OtpProof` | Verified proof or an explicit provider-unavailable bypass token | server |
+| `Order` | Purchase accepted by the server with authoritative totals | server |
+| `OrderTracking` | The pixel/event the thank-you page may fire (`event: null` → nothing fires) | server |
+| `LandingPage` | A paid-traffic page (`/lp/:slug`) with its images and CTA | server |
+| `AbandonedCheckoutInput` | The optional abandoned-checkout signal `orders.abandoned.upsert()` accepts | SDK schema, server bounds |
+| `PlaceOrderInput` | The checkout form whitelist (`@wocart/storefront/astro`) — the body `executePlaceOrder()` submits | SDK |
+| `TrackingDecision` | Server-selected pixel/event instruction after an accepted outcome | server |
+
+Import browser-safe contracts from the package root:
+
+~~~ts
+import {
+  BasketSchema,
+  type Basket,
+  type BasketLine,
+  type CheckoutDraft,
+  type DeliverySelection,
+  type OtpProof,
+  type ProductDetail,
+  type ProductListItem,
+} from "@wocart/storefront";
+~~~
+
+The canonical basket has at most 20 lines, at most 100 units per line, and no
+duplicate product-plus-variant identities. An empty basket is valid storage
+state; checkout is not. `BasketLine.unitPrice` is only a display hint. The
+server re-prices it during both cart validation and order creation.
+
+Do not make a theme responsible for required address fields, custom-field
+allowlists, delivery availability, stock, discounts, final totals, OTP
+acceptance, or tracking eligibility. Those rules are platform data or platform
+decisions. The theme presents them and gives the shopper a clear next action.
+
+## The storefront route contract
+
+A storefront's public paths are a platform contract, not a theme preference.
+Three parts of the platform meet on them: the theme renders the pages, the server writes the
+URL Meta is told about (`/lp/:slug` for a sale attributed to a landing page,
+`/thank-you` otherwise), and the dashboard prints them as the store's public
+links. These six patterns are frozen — restyle anything else, but change one of
+these only as a platform change:
+
+| Route | Renders |
+| --- | --- |
+| `/products/:handle` | product detail (public handle, never an internal id) |
+| `/category/:slug` | a category listing |
+| `/pages/:slug` | a legal or CMS page |
+| `/lp/:slug` | a landing page |
+| `/checkout` | the checkout |
+| `/thank-you` | order confirmation |
+
+The root (`/`) and the catalog index (`/products`) carry no parameter and are
+the two further surfaces a theme implements.
+
+The contract is exported, so a theme can read it instead of repeating it:
+`STOREFRONT_ROUTES` is the table above, and `showsWidgetOn(surfaces, pathname)`
+is the platform's half of "which surface is this page" — the merchant's
+per-surface switches then mean the same thing as the dashboard's preview. The
+gate never prefix-matches: `/productsomething`, `/checkout-success` and
+`/thank-you-again` are no surface at all, never a widget on a page the merchant
+switched off.
+
+## The five rules to remember
+
+1. **Create a client for one store scope.** Do not share a client between
+   unrelated stores or tenants.
+2. **Keep the API key on the server.** Browser code calls same-origin theme
+   routes created with the proxy helper.
+3. **Treat server data as authoritative.** The browser may suggest quantities
+   and display prices, but the server re-prices and validates before an order.
+4. **Handle null, empty arrays, and unsuccessful results deliberately.** They
+   are normal states, not exceptional UI bugs.
+5. **Use public handles and documented fields.** Do not guess endpoints, spread
+   raw server records into browser responses, or invent missing business rules.
+
+## Quick start
+
+### Create the client
+
+The server-only package entry creates a client for one store scope:
+
+~~~ts
+import { createStoreClient } from "@wocart/storefront/server";
+
+// Use a server-only environment variable for the key.
+const store = createStoreClient({
+  serverUrl: process.env.COD_SERVER_URL,
+  apiKey: process.env.STORE_API_KEY,
+});
+~~~
+
+The exact environment-variable mechanism depends on the theme runtime. The
+important rule is that STORE_API_KEY must never be included in client-side
+JavaScript, HTML, public Astro variables, or a browser request.
+
+Create the client in a server loader, request handler, or server action. A
+request-scoped client is the simplest safe default:
+
+~~~ts
+const [config, featuredProducts] = await Promise.all([
+  store.config.get(),
+  store.products.list({ featured: true, limit: 8 }),
+]);
+~~~
+
+Every call makes its own request; a call never waits on another call's
+pending request, even an identical one. Within one render, ask once and share
+the result (`Promise.all`, or a per-request memo) when several parts of a page
+need the same data. A client never holds pending work across calls, so one
+kept for several requests cannot leave a request waiting on another's read.
+
+### Available imports
+
+The root package is browser-safe. It exports types, runtime schemas, money and
+image utilities, and the static reference datasets (wilayas and the 1,551-row
+commune bundle). It does not export the client factory or any function that
+carries the store API key.
+
+The two server-only entry points:
+
+~~~ts
+@wocart/storefront/server
+@wocart/storefront/astro
+~~~
+
+Use `/server` only in server loaders, request handlers, or server actions. Use
+`/astro` only in server-side Astro routes/actions/middleware. Browser bundles
+import the root only, and they must never receive the API key or call the
+server directly.
+
+#### The names you will look up, and what they are for
+
+| Export | Use it for |
+| --- | --- |
+| `formatMoney`, `optimizeImage`, `generateSrcSet` | Money text and image URLs |
+| `createImageHelpers(mediaDomain)`, `getCardImage`, `getGalleryImage`, `getThumbnailImage`, `getHeroImage`, `getCategoryImage`, `getLogoImage` | The bound image toolkit (`IMAGE_SIZES` holds the presets) |
+| `WILAYAS`, `ALGERIA_COMMUNES`, `communesForWilaya` | Reference data: 58 wilayas, 1,551 communes, one wilaya's rows |
+| `normalizeAlgerianPhone`, `toLocalAlgerianMobile` | The one Algerian phone rule (accept/format) |
+| `resolvePrefillText`, `buildWhatsAppHref`, `stripTrackingParams`, `truncateAtWordBoundary`, `PREFILL_TOKENS`, `MAX_RESOLVED_PREFILL_LENGTH` | WhatsApp prefill text and the `wa.me` link |
+| `showsWidgetOn`, `STOREFRONT_ROUTES` | Which surface a pathname is (the frozen route contract) |
+| `productImageSource` | Which photo represents a product (cover → gallery fallback) |
+| `getProductView`, `getProductListView` | Pure price, discount, default-variant, and stock values for detail and list projections |
+| `getOfferTierView` | Pure offer-tier price, compare-price, savings, and free-shipping projection; display-only, never order authority |
+| `META_CURRENCY`, `buildMetaProductPayload`, `buildMetaViewContentPayload`, `buildMetaAddToCartPayload`, `buildMetaInitiateCheckoutPayload` | Browser-safe Meta event payloads with the platform currency and catalog shape |
+| `createMetaPixelTracker` | Injected browser-pixel dispatch; the theme supplies the vendor global and keeps bootstrap/timing |
+| `createBasketStore`, `createLocalStorageAdapter`, `createMemoryStorageAdapter`, `DEFAULT_BASKET_STORAGE_KEY` | The browser basket, its storage, and the key it persists under (`cod_cart_v1`) |
+| `basketLineKey`, `toOrderItems`, `MAX_BASKET_LINES`, `MAX_BASKET_LINE_QUANTITY` | Basket identity, the wire projection, and the caps the server re-checks |
+| `createOtpMachine` | The OTP step's state machine |
+| `createOtpTransport`, `mapOtpResponse`, `otpTransportFailure` | Route-agnostic OTP result mapping; the theme supplies its same-origin route functions |
+| `createAbandonedCheckoutTracker` | Port-injected session, capture eligibility, debounce, update, cookie, fetch, and exit-beacon policy |
+| `STOREFRONT_OPERATIONS` | The exact operation labels used by namespace calls |
+| `STOREFRONT_RETRY_POLICIES` | Which operations retry, by exact operation label |
+
+### Commerce projections
+
+`getProductView`, `getProductListView`, and `getOfferTierView` are pure screen
+projections. They make repeated storefront surfaces agree on what to display;
+they do not authorize stock, discounts, offer eligibility, totals, or orders.
+The server remains authoritative at cart validation and order creation.
+
+Import these projections directly from `@wocart/storefront`. A theme should
+not add a local product-view or offer-price module around them.
+
+## Configuration
+
+### The client's options
+
+`createStoreClient` takes a `StoreScope` (`@wocart/storefront/server`):
+
+| Field | Required | What it is |
+| --- | --- | --- |
+| `serverUrl` | yes | Your store's API origin. No default: a wrong origin must be a visible mistake, not a silent one. |
+| `apiKey` | yes | The store's API key. Sent as `X-Store-API-Key` on every request. **Server-only.** |
+| `locale` | no | The language to read merchant text in — see "Store languages". |
+| `theme` | no | Your theme's key, to receive the merchant's edits to your theme's text — see "Store languages". |
+| `onError` | no | Observability hook for degraded reads — see "When a read degrades: onError". |
+
+`serverUrl` and `apiKey` are checked at construction: an empty or whitespace-only value throws a
+`StorefrontError` with code `MISSING_CONFIGURATION` (category
+`authentication`, operation `client.create`) naming the variable to set. That
+is deliberate — an empty key would otherwise send unauthenticated requests and
+turn every read into an empty store, which looks like "no products" instead of
+"misconfigured". After construction, reads never throw.
+
+```ts
+import { createStoreClient } from "@wocart/storefront/server";
+
+const store = createStoreClient({
+  serverUrl: process.env.COD_SERVER_URL!,
+  apiKey: process.env.STORE_API_KEY!,
+});
+```
+
+### Environment variables
+
+The SDK reads **no** environment variables itself — you pass the values in. A
+storefront deployed by Wocart receives these:
+
+| Variable | Kind | Purpose |
+| --- | --- | --- |
+| `COD_SERVER_URL` | server variable | the store's API origin, e.g. `https://api.your-store.com` |
+| `STORE_API_KEY` | server secret | the store API key |
+| `MEDIA_DOMAIN` | server variable (optional) | media domain for `createImageHelpers(mediaDomain)`; unset → image URLs pass through unchanged |
+
+Never put `STORE_API_KEY` in a browser-exposed variable (no `PUBLIC_*`, no
+`import.meta.env` in client code, no HTML attribute). In Astro, declare it in
+`astro.config.mjs` → `env.schema` with `context: "server"`, `access: "secret"`,
+and read it with `astro:env/server`.
+
+### Where the API key comes from
+
+Each store has its own API origin and store API key; the server stores only a
+hash of the key. A storefront Wocart deploys receives both automatically. To
+develop a theme against a store, ask the store's operator for its origin and a
+key, and keep the key in a local, uncommitted secrets file. The SDK cannot mint
+or rotate keys.
+
+### What may run where
+
+| Surface | Import from | May hold the key? |
+| --- | --- | --- |
+| Server loaders, request handlers, actions, endpoints | `@wocart/storefront/server` | yes |
+| Astro server routes/actions/middleware | `@wocart/storefront/astro` | yes |
+| Browser scripts, islands, client components | `@wocart/storefront` (root) | **no** |
+
+Browser code reaches the platform only through same-origin routes you own
+(`src/pages/api/**`) that call the SDK server-side. The root entry is
+browser-safe by construction: it exports no client factory and no function that
+carries the key, which the package's own contract test asserts.
+
+### The namespaces
+
+| Namespace | Use it for | Important result shapes |
+| --- | --- | --- |
+| config | Branding and store-wide checkout/display policy | StoreConfig or null |
+| products | Product catalog and reviews | Product, ProductList, or empty/null |
+| categories | Catalog navigation | Category array |
+| pages | Legal and CMS pages, landing pages | StorePagePublic, LandingPage, or null |
+| pageData | The store's saved page document | PageDocumentPayload or null |
+| shipping | Delivery prices | ShippingRates or one rate/null |
+| geo | Wilayas and communes | Static wilayas or Commune array |
+| cart | Server validation of a browser basket | CartValidation result |
+| orders | OTP, order creation, abandoned checkout, tracking | ClientResult or tracking/null |
+
+The following sections explain each namespace and the UI decisions it
+requires.
+
+## Failure and result contracts
+
+### Read methods
+
+Read methods use safe empty results so a theme can still render its shell:
+
+| Call | Empty or unavailable result |
+| --- | --- |
+| config.get() | null |
+| products.get(handle) | null |
+| products.list() | [] |
+| products.reviews.list() | { rows: [], total: 0 } |
+| categories.list() | [] |
+| pages.get(slug) | null |
+| pages.landing(slug) | null |
+| pageData.get(surface) | null |
+| shipping.rates() | {} |
+| shipping.rate(wilayaId) | null |
+| geo.communes(wilayaId) | [] |
+| orders.tracking(orderId) | null |
+
+These results do not mean the theme should crash. They mean the theme should
+show a deliberate fallback: a default brand shell, an empty catalog state, a
+not-found page, a delivery-rate fallback, or no conversion event.
+
+### When a read degrades: `onError`
+
+An empty result is the right thing to *render*, but it is the wrong thing to
+*observe*: "no products" and "the store's key is wrong" look identical on the
+page. `onError` is the hook that tells them apart, and it is the only place a
+degraded read is visible:
+
+```ts
+const store = createStoreClient({
+  serverUrl: env.COD_SERVER_URL,
+  apiKey: env.STORE_API_KEY,
+  onError: (error) => {
+    // error: DomainError — same shape mutations return
+    logger.warn({ operation: error.operation, code: error.code, requestId: error.requestId });
+  },
+});
+```
+
+- **When it fires:** every read that could not complete — transport failure
+  (no connection, DNS, timeout), HTTP failure (401/403 misconfiguration, 5xx,
+  429), a response the schema rejected, a malformed body, or an aborted
+  request. Never on success.
+- **What it receives:** one `DomainError` with the same fields a mutation
+  failure carries — `operation` (`"products.list"`, `"geo.communes"`, …),
+  `code`, `category`, `retryable`, `sideEffect`, and `requestId` when the
+  server sent one. `requestId` is the safe line to log: it never contains
+  customer data.
+- **Its exceptions:** a throwing `onError` cannot break anything. The hook is
+  wrapped, so a bug in your logger still resolves the read to `null`/`[]`/`{}`.
+- **Where it runs:** server-side, next to the client. It is not serialized into
+  the page, and browser code has no client to attach it to.
+- **What it is not:** a retry switch. It reports; it does not change SDK
+  behaviour (`retryable` tells you whether *you* may repeat the call — reads
+  already retry transport and 5xx failures internally).
+
+`StorefrontError` is the thrown counterpart: an aborted or malformed **read**
+throws it, and it always carries `domainError`. Inside a namespace read the SDK
+catches it and reports through `onError`; `isStorefrontError(value)` recognises
+it across a realm boundary (an Astro action, a worker), where `instanceof` fails.
+
+### Mutations
+
+Mutations return ClientResult rather than making the theme parse arbitrary
+HTTP responses:
+
+~~~ts
+type ClientResult<T> =
+  | { success: true; data: T }
+  | {
+      success: false;
+      error: string;
+      code?: string;
+      domainError?: DomainError;
+      [key: string]: unknown;
+    };
+~~~
+
+Every failure also carries `domainError`: the stable, serializable contract to
+branch on instead of a status code or an error string.
+
+~~~ts
+interface DomainError {
+  category:
+    | "validation"
+    | "authentication"
+    | "business"
+    | "system"
+    | "transport"
+    | "unknown";
+  code: string;       // the server's code, or HTTP_<status>, NETWORK_ERROR,
+                      // REQUEST_ABORTED, REQUEST_TIMEOUT,
+                      // MALFORMED_RESPONSE, SCHEMA_VALIDATION_FAILED
+  message: string;    // safe to show to the shopper
+  retryable: boolean; // whether this same call may be replayed
+  operation: string;  // stable label, e.g. "orders.otp.send"
+  sideEffect: "not_started" | "rejected" | "committed" | "unknown";
+  fieldIssues?: { field: string; code: string; message: string }[];
+  retryAfterSeconds?: number;
+  requestId?: string; // the server log line this failure belongs to
+}
+~~~
+
+`category` is the server's own classification whenever the failure names one;
+the SDK only falls back to the status code for gateway or proxy failures that
+never reached the application. The server stays the authority on which context
+is valid, so treat `fieldIssues`, `retryAfterSeconds`, and `requestId` as
+server-authored data and read `requestId` only for logging or support.
+
+Use the success branch before reading data:
+
+~~~ts
+const result = await store.orders.create(orderBody);
+
+if (!result.success) {
+  // Show result.error and use result.code or other context for field-level UI.
+  return;
+}
+
+// result.data is now CreatedOrder.
+~~~
+
+Validation failures may include useful context such as field errors,
+attemptsRemaining, windowSeconds, or a terminal OTP state. Preserve that
+context when mapping an SDK result to UI.
+
+Public namespace methods are designed to resolve to these documented results.
+Do not turn a failed result into a successful-looking order, empty price, or
+conversion event.
+
+### Caching and retries
+
+- GET requests are fresh by default, and each call makes its own request.
+- config.get(), categories.list(), and geo.communes() keep their finished
+  result for the client's lifetime; a call made while the first is still
+  pending makes its own request rather than waiting on it.
+- Every read is bounded by `readTimeoutMs` (10 seconds by default), retries
+  included; a read that runs out of time degrades and reports
+  `REQUEST_TIMEOUT` to `onError`. Writes have no default limit.
+- null results and failures are not cached, so a temporary failure can recover
+  on the next call.
+- GET network failures use two short exponential backoff retries.
+- POST and PATCH requests are not retried. This is intentional: retrying order
+  creation or another side effect can duplicate the shopper's action.
+
+The cache belongs to a StoreClient instance. Do not put a multi-tenant client
+in a process-global singleton unless the cache is explicitly isolated by
+store.
+
+## Store configuration
+
+Use config.get() near the root of every page. It is the theme's starting point
+for branding and feature flags:
+
+~~~ts
+const config = await store.config.get();
+
+const cartEnabled = config?.cartEnabled === true;
+const currencySymbol = config?.currencySymbol ?? "دج";
+const announcement = config?.announcementBar ?? null;
+~~~
+
+StoreConfig contains the current store identity and presentation fields,
+including:
+
+- name, domain, logoUrl, themeId, colors, fontFamily, and fontUrl;
+- lang (the primary language), locales, contentOverrides, currency,
+  currencySymbol, metaTitle, metaDescription, and ogImage;
+- announcementBar and reviewsEnabled;
+- cartEnabled, freeShippingThreshold, and cartShippingMode;
+- checkoutForm policy;
+- OTP and Turnstile settings;
+- pixelId and conversionEvent;
+- public page links, legal contact information, and WhatsApp widget settings.
+
+The checkout policy is not a suggestion. Use it to decide whether address,
+email, notes, delivery options, and custom fields are required, optional, or
+hidden. The policy includes:
+
+- address: required, optional, or hidden;
+- notes: optional or hidden;
+- email: required, optional, or hidden;
+- deliveryOptions.home and deliveryOptions.stopDesk;
+- customFields with stable IDs, labels, types, required flags, and select
+  options.
+
+When cartEnabled is false, do not render cart markup or basket controls. A
+store can intentionally run a single-product checkout.
+
+The config response also contains public integration settings such as the
+tracking pixel choice and WhatsApp presentation. It must not be treated as a
+place to expose the store API key. Render only documented public fields.
+
+### Store languages
+
+A store has a primary language (`lang`) and publishes the languages in
+`locales`, primary first; a single-language store is one entry. Each entry
+carries what a theme needs to render it — `code` (BCP 47), `nativeName` and
+`direction` — so a language the platform adds later reaches your theme without
+an SDK release. `servedLanguage(config, code?)` finds one (the primary by
+default), or `null` when the store does not serve it:
+
+~~~ts
+import { servedLanguage } from "@wocart/storefront";
+
+const dir = servedLanguage(config)?.direction ?? "ltr"; // "rtl" for Arabic
+const switcher = config.locales.map((language) => language.nativeName);
+const fromUrl = servedLanguage(config, segment)?.code ?? config.lang;
+~~~
+
+`contentOverrides` holds the merchant's edits of **your theme's** text, one map
+per published language. They belong to the theme that declares the keys, so
+they arrive only when the client names the theme:
+
+~~~ts
+const store = createStoreClient({ serverUrl, apiKey, theme: "my-theme" }); // defineTheme({ key })
+~~~
+
+Merge `contentOverrides[locale]` over your own pack for that same language, and
+never use another language's map: a store that switches language must not show
+text left over from the old one.
+
+To read the store's own data — products, categories, offers, legal pages, the
+announcement bar — in another language, create the client with `locale`
+(one client per language; each keeps its own caches):
+
+~~~ts
+const store = createStoreClient({ serverUrl, apiKey, theme: "my-theme", locale: "fr" });
+const config = await store.config.get(); // config.locale: "fr" if the store publishes French, else config.lang
+~~~
+
+Untranslated fields fall back to the primary language one by one, so a page can
+mix both; render merchant text with `dir="auto"` so an Arabic name inside a
+French page still reads right-to-left. Landing pages are not translated.
+
+### Language URLs
+
+The primary language keeps bare URLs; every other published language lives
+under its code (`/fr/products/phone`), and the primary has one address
+(`/ar/…` redirects). Read a request's language with `resolveLocalePath`, build
+every internal link with `localizeHref`, and list a page's versions for
+`<link rel="alternate" hreflang>` with `alternateLinks`:
+
+~~~ts
+import { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "@wocart/storefront";
+
+const routing = localeRouting(config);                    // from the primary config
+const path = resolveLocalePath(url.pathname, routing);
+if (path.kind === "redirect") return redirect(path.location, 301);
+// path.locale: "fr", path.pathname: "/products/phone" — render that route
+localizeHref("/checkout", path.locale, routing);          // "/fr/checkout"
+alternateLinks(path.pathname, routing, url.origin);       // [{ hreflang: "ar", href }, …, x-default]
+~~~
+
+`localizeHref` leaves external URLs, fragments, endpoints, files and already
+prefixed links alone, so it is safe on any `href`. Never redirect a shopper by
+browser language: offer the other languages as links and let them choose.
+`products.list({ limit, offset })` pages through the whole catalog, for a
+sitemap.
+
+## Products and catalog presentation
+
+### Product detail
+
+Use a public product handle, not an internal product ID:
+
+~~~ts
+const product = await store.products.get("linen-shirt");
+
+if (!product) {
+  // Render the theme's product-not-found state or redirect to the catalog.
+  return;
+}
+~~~
+
+Product detail includes the product fields, parsed variant options and tags,
+the category, variants, images, review statistics, and offers. The server
+decides whether a product is publicly available.
+
+### Product lists
+
+~~~ts
+const products = await store.products.list({
+  categoryId: selectedCategoryId,
+  featured: true,
+  limit: 12,
+});
+~~~
+
+Product lists return ProductList objects. ProductList and Product are
+different shapes: a list item is not a detail object and must not be cast to
+Product. ProductList carries list-oriented fields such as coverImage and
+reviewStats, while variantOptions and tags remain their raw serialized form.
+
+The limit is optional. An explicit limit of 0 is preserved, so do not replace
+it with a truthiness fallback.
+
+The server controls active, listed, visible, and stock-related catalog rules.
+The theme owns the visual treatment of:
+
+- product cards and comparison;
+- badges, offer labels, and review summaries;
+- image galleries and zoom;
+- variant selection;
+- loading, empty, and unavailable states.
+
+### Reviews
+
+~~~ts
+const reviews = await store.products.reviews.list(productId, {
+  limit: 10,
+  offset: 0,
+});
+~~~
+
+The result is { rows: Review[], total: number }. The default page size is 20
+and the default offset is 0. For submitting a review:
+
+~~~ts
+const submitted = await store.products.reviews.submit({
+  orderNumber: customerVisibleOrderNumber,
+  productId,
+  rating: 5,
+  title: "Beautiful",
+  body: "Exactly as described.",
+});
+~~~
+
+orderNumber is the customer-visible order number, not the internal order UUID.
+
+## Categories, legal pages, and landing pages
+
+### Categories
+
+categories.list() returns full category rows including name, slug,
+description, parentId, imageUrl, SEO fields, position, and timestamps. The
+result is cached after success.
+
+Use category slugs and category IDs only where the SDK method requires them.
+Do not recreate category hierarchy rules in the theme.
+
+### CMS and legal pages
+
+~~~ts
+const page = await store.pages.get("privacy-policy");
+
+if (page) {
+  // bodyHtml is sanitized by the server.
+  return page.bodyHtml;
+}
+~~~
+
+bodyHtml is server-sanitized rich HTML. In an Astro page, render it through
+Astro's HTML rendering mechanism, for example:
+
+~~~astro
+<article set:html={page.bodyHtml} />
+~~~
+
+Do not hardcode the legal navigation list. Use config.pages so the store's
+available public pages determine the links. If a page is null, render the
+theme's not-found or fallback state.
+
+### Landing pages
+
+~~~ts
+const landing = await store.pages.landing("summer-sale");
+~~~
+
+A landing page can contain its own name, SEO metadata, image gap, images,
+product, publishedAt, and tracking information. The product may be null.
+Draft, archived, or unknown landing pages resolve to null.
+
+Landing tracking is already resolved by the server:
+
+~~~ts
+if (landing?.tracking.pixelId) {
+  // Fire only the configured event for the configured pixel.
+}
+~~~
+
+Do not invent tracking events from a landing-page slug.
+
+### The saved page document (theme composition)
+
+~~~ts
+const saved = await store.pageData.get("home");   // null = never saved / failed
+~~~
+
+One document per surface ("home" today), owned by the store and written by
+the platform's page editor — a storefront never writes it. `null` means the store has never saved one (or the read
+failed): render the theme's shipped default document. The payload is
+**transport-checked only** (`version`, `surface`, `sections`) and fetched
+fresh on every call, so a save reaches the next render.
+
+What the sections *mean* is `@wocart/theme`'s job — validate and render with
+the theme SDK:
+
+~~~ts
+import { parsePageData } from "@wocart/theme";
+import InstanceView from "@wocart/theme/astro/InstanceView.astro";
+import { createReadCache } from "@wocart/theme/astro";
+
+const { page } = parsePageData(saved ?? shippedDefault);
+const reads = createReadCache();   // one per render — sections share reads
+
+// {page?.sections.map((section) => (
+//   <InstanceView instance={section} theme={theme} context={ctx}
+//     storefront={store} reads={reads} />
+// ))}
+~~~
+
+An unparseable or unsupported-version document is the theme's decision to
+degrade (its non-composed fallback), never an exception.
+
+## Shipping and geography
+
+### Delivery rates
+
+~~~ts
+const rates = await store.shipping.rates();
+const wilayaRate = await store.shipping.rate(String(wilayaId));
+~~~
+
+ShippingRates is a map keyed by wilaya ID. Each value contains whole-DZD
+home and stop-desk prices:
+
+~~~ts
+type ShippingRate = {
+  home: number;
+  stopDesk: number;
+};
+~~~
+
+If the map is empty or one rate is null, show a useful unavailable state. Do
+not silently display zero shipping.
+
+### Wilayas and communes
+
+~~~ts
+const wilayas = await store.geo.wilayas(); // static 58-wilaya dataset, no network
+const communes = await store.geo.communes(wilayaId); // server rows, cached
+
+// zero-network rows for the checkout's locality field:
+import { communesForWilaya } from "@wocart/storefront";
+const rows = communesForWilaya(wilayaId); // Commune[] — [] if unknown
+~~~
+
+Wilayas are local and do not use the network. `geo.communes()` reads the
+server's reference rows and caches them after success; the wilaya argument may
+be a number or a numeric string, and a failure is an empty list, never a throw.
+
+The commune dataset is also bundled (1,551 rows across all 58 wilayas,
+`ALGERIA_COMMUNES` plus `communesForWilaya`). Use it when the locality field
+must fill with no round-trip to fail on — the bundled rows are the same rows
+the server returns, checked against each other before every release (count,
+id, wilaya, French name, Arabic name). One caveat carried by the data: `c-01-024` (Talmine)
+has no Arabic spelling, so an RTL label is `nameAr || name`.
+
+## Cart and checkout: the money path
+
+### The basket lives in the browser
+
+The shopper's basket is stored by the theme in browser storage or another
+client-side mechanism. It is never stored on the server.
+
+The browser's pricePerUnit is display-only. Never trust a browser subtotal,
+delivery fee, total, stock value, or offer. Before checkout, send the selected
+lines to cart.validate:
+
+~~~ts
+const validation = await store.cart.validate(items);
+
+if (!validation.success) {
+  // The request itself failed. Keep the basket and show validation.error.
+  return;
+}
+
+const { lines, subtotal, rewards, freeDelivery } = validation.data;
+~~~
+
+The server re-prices catalog lines, merges duplicate lines, checks stock and
+offers, and calculates free-delivery eligibility. CartValidation contains:
+
+- lines with productId, variantId, variantLabel, productName, quantity,
+  unitPrice, lineTotal, maxQuantity, and blocker;
+- subtotal and rewards;
+- freeDelivery with fromOffer, threshold, qualified, and remaining.
+
+Line blockers include missing, unlisted, and out_of_stock. The creative
+experience is yours: inline warnings, a highlighted invalid line, a drawer,
+or a guided correction step. The server result is not optional.
+
+### Using the SDK's BasketStore
+
+The SDK provides an out-of-the-box, deep `createBasketStore` so themes do not
+have to implement duplicate merging, storage validation, private-mode
+fallbacks, or cross-tab synchronization manually:
+
+~~~ts
+import { createBasketStore } from "@wocart/storefront";
+
+const basket = createBasketStore();
+
+// Add or merge a line
+basket.addLine({
+  productId: "p1",
+  productName: "T-Shirt",
+  variantId: "red-m",
+  variantLabel: "Red / M",
+  quantity: 1,
+  unitPrice: 2500,
+});
+
+// Reactive subscription (updates on local and cross-tab storage events)
+const unsubscribe = basket.subscribe((lines) => {
+  renderCartBadge(basket.getCount());
+  renderSubtotal(basket.getSubtotal());
+});
+
+// Ready-to-validate server payload
+const items = basket.toOrderItems();
+const validation = await store.cart.validate(items);
+~~~
+
+The basket persists under `DEFAULT_BASKET_STORAGE_KEY` and holds at most
+`MAX_BASKET_LINES` lines of at most `MAX_BASKET_LINE_QUANTITY` units each —
+the same caps the server re-checks.
+
+### Single-product order versus basket order
+
+An order is either:
+
+- a basket order with a non-empty items array; or
+- a single-product order with productId, productName, pricePerUnit, and
+  quantity.
+
+The basket shape supersedes the flat product fields. Do not send both shapes
+as competing sources of truth. The server re-prices all lines again during
+order creation.
+
+### Create an order
+
+~~~ts
+const placed = await store.orders.create({
+  customerName,
+  phone,
+  wilayaId,
+  communeId,
+  address,
+  deliveryType,
+  productId,
+  productName,
+  quantity,
+  pricePerUnit,
+  otpToken,
+});
+
+if (!placed.success) {
+  // Keep the checkout state and map placed.error/context to the UI.
+  return;
+}
+
+const order = placed.data;
+// order.orderId, order.orderNumber, order.price, order.deliveryFee, order.total
+~~~
+
+For a basket, send a non-empty items array with the selected product and
+variant details. The displayed price can be included for the request shape,
+but the server is authoritative and recalculates the actual amount.
+
+CreatedOrder contains the order ID, customer-facing order number, product
+price, delivery fee, and total, all in whole DZD.
+
+### OTP
+
+Use OTP only when config.otpEnabled says the store requires or offers it.
+
+~~~ts
+const sent = await store.orders.otp.send(phone);
+
+if (sent.success && sent.data.status === "sent") {
+  const verified = await store.orders.otp.verify(
+    phone,
+    sent.data.requestId,
+    code,
+  );
+
+  if (verified.success && verified.data.status === "verified") {
+    // Send verified.data.otpToken with the order.
+  }
+}
+~~~
+
+send can return:
+
+- sent with requestId, expiresAt, and maxAttempts;
+- unavailable with reason and bypassToken.
+
+If OTP is unavailable, the checkout may continue through the documented
+fail-open path by sending bypassToken as otpToken. Do not treat unavailable as
+verified, and do not make the shopper wait for a code that was never sent.
+
+verify returns a verified status with otpToken on success. Failure context can
+include attemptsRemaining and a terminal state. Use it for the countdown,
+retry, and lockout UI.
+
+### Using the SDK's OtpMachine
+
+The SDK exports `createOtpMachine` to manage the complete interactive WhatsApp
+verification lifecycle without managing timers and attempts manually. It talks
+to your own same-origin OTP routes through a transport; `mapOtpResponse` turns
+each route's response into the SDK's typed result, and `otpTransportFailure`
+covers a request that never completed:
+
+~~~ts
+import {
+  OtpSendResultSchema,
+  OtpVerifyResultSchema,
+  STOREFRONT_OPERATIONS,
+  createOtpMachine,
+  createOtpTransport,
+  mapOtpResponse,
+  otpTransportFailure,
+} from "@wocart/storefront";
+
+async function post(path, body, schema, operation) {
+  try {
+    const response = await fetch(path, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    return await mapOtpResponse(response, { schema, operation, fallbackError: "Please try again" });
+  } catch (error) {
+    return otpTransportFailure(error, operation, "Please try again");
+  }
+}
+
+const otp = createOtpMachine({
+  transport: createOtpTransport({
+    send: (phone) =>
+      post("/api/otp/send", { phone }, OtpSendResultSchema, STOREFRONT_OPERATIONS.ordersOtpSend),
+    verify: (phone, requestId, code) =>
+      post("/api/otp/verify", { phone, requestId, code }, OtpVerifyResultSchema, STOREFRONT_OPERATIONS.ordersOtpVerify),
+  }),
+  initialPhone: "0551234567",
+});
+
+otp.subscribe((state) => {
+  // state.status: "idle" | "sending" | "code_sent" | "verifying" | "verified" | "bypassed" | "error"
+  // state.cooldownRemaining: seconds until resend allowed
+  // state.attemptsRemaining: attempts left before terminal lockout
+  // state.otpToken: ready to place order
+});
+
+await otp.send();
+await otp.verify("123456");
+~~~
+
+### Order tracking and conversion events
+
+~~~ts
+const tracking = await store.orders.tracking(order.orderId);
+
+if (tracking) {
+  // tracking.pixelId and tracking.event are the server-selected values.
+}
+~~~
+
+tracking returns pixelId and an event of Purchase or Lead, or null. If it is
+null, fire no conversion event. Do not infer an event from a successful HTTP
+response alone.
+
+### Meta browser primitives
+
+The payload builders are pure and browser-safe. Use the server-validated value
+for `buildMetaInitiateCheckoutPayload`; the add-to-cart builder derives the
+value from the lines that were added. `createMetaPixelTracker` takes an
+injected `fbq`-compatible function and stays silent when it is unavailable.
+
+The theme owns pixel bootstrap, DOM collection, and first-interaction timing.
+Pixel-specific events use `trackSingle`; basket events retain their existing
+`track` dispatch. The thank-you page uses the server-selected `pixelId` and
+event, and passes the order id as `eventID` to the browser event. The server
+uses that same order id for the mirrored Lead event; do not generate a second
+browser id or infer a conversion when `orders.tracking()` returns `event: null`.
+
+### Abandoned checkout
+
+The SDK also exposes abandoned-order methods:
+
+- abandoned.upsert(body, forwardedHeaders?) saves the current checkout state;
+- abandoned.convert(sessionId, orderId, orderNumber) marks it converted.
+
+Use these only when the theme has a real abandoned-checkout flow. Keep the
+normal mutation result handling and never block order creation on optional
+analytics.
+
+## Astro actions and form handling
+
+The SDK cannot import Astro virtual modules, so a theme owns the thin Astro
+wrapper while the SDK owns reusable validation and execution logic.
+
+### Validate and execute place-order forms
+
+placeOrderInput is the shared form schema. It:
+
+- whitelists supported fields and strips unknown fields;
+- coerces form number strings;
+- turns empty optional values into undefined;
+- canonicalizes phone input;
+- accepts items, variantSelections, and customFieldResponses as JSON strings
+  or arrays;
+- preserves item offerId values.
+
+Use executePlaceOrder to keep form behavior consistent:
+
+~~~ts
+import { ActionError, defineAction } from "astro:actions";
+import {
+  executePlaceOrder,
+  placeOrderInput,
+} from "@wocart/storefront/astro";
+
+export const server = {
+  placeOrder: defineAction({
+    accept: "form",
+    input: placeOrderInput,
+    handler: async (input, context) => {
+      const result = await executePlaceOrder(
+        input,
+        context.request,
+        store,
+      );
+
+      if (!result.success) {
+        throw new ActionError({
+          code: "BAD_REQUEST",
+          message: result.error,
+        });
+      }
+
+      return result.data;
+    },
+  }),
+};
+~~~
+
+executePlaceOrder distinguishes:
+
+- shape failures, when there is neither a non-empty basket nor a complete flat
+  product order;
+- upstream failures, when the server rejects or cannot complete the request.
+
+The action should preserve the distinction when the UI needs different
+messages.
+
+collectForwardedHeaders(request) extracts attribution headers for an upstream
+order request:
+
+- User-Agent;
+- client IP from CF-Connecting-IP, then the first X-Forwarded-For value;
+- Referer.
+
+Use it when the server route is the trusted boundary that forwards the order.
+Do not let arbitrary browser code choose identity headers.
+
+### Redirect behavior
+
+The middleware helper resolveActionRedirectDecision handles the form POST
+flow:
+
+- form actions execute and serialize their result;
+- form errors redirect to the referer, or the current pathname, with status
+  303;
+- successful form actions return next so the result cookie survives;
+- non-form and JSON requests continue without a redirect.
+
+The common mistake is redirecting successful actions too early. Let success
+continue through next, then redirect from the successful page/action flow to
+the thank-you experience.
+
+## Browser-facing proxy routes
+
+Browser code should call a same-origin theme route. That route uses
+createProxyEndpoint to call the SDK with the server-only API key.
+
+This keeps the key out of the browser and centralizes CSRF checks, input
+validation, parameter parsing, attribution forwarding, and error shape.
+
+### Cart validation route
+
+~~~ts
+import { z } from "zod";
+import { createProxyEndpoint } from "@wocart/storefront/astro";
+
+import { BasketLineInputSchema, MAX_BASKET_LINES } from "@wocart/storefront";
+
+const cartInputSchema = z.object({
+  items: z.array(BasketLineInputSchema).min(1).max(MAX_BASKET_LINES),
+});
+
+export const POST = createProxyEndpoint({
+  method: "POST",
+  client: (input) => store.cart.validate(input.items),
+  inputSchema: cartInputSchema,
+  successBody: (data) => ({ success: true, data }),
+});
+~~~
+
+The browser can now call the theme's own route. It never calls the server
+directly and never needs the API key.
+
+### Order route with attribution
+
+~~~ts
+export const POST = createProxyEndpoint({
+  method: "POST",
+  client: (input, headers) => store.orders.create(input, headers),
+  forwardAttribution: true,
+  successStatus: 201,
+  errorStatus: 422,
+});
+~~~
+
+### GET route with a numeric path parameter
+
+~~~ts
+export const GET = createProxyEndpoint({
+  method: "GET",
+  client: (input) => store.geo.communes(input.wilayaId),
+  pathParams: { wilayaId: "number" },
+});
+~~~
+
+Proxy configuration supports:
+
+- GET and POST methods;
+- a client function receiving parsed input and optional forwarded headers;
+- inputSchema for body validation;
+- queryParams and pathParams allowlists;
+- numeric or string path parameter parsing;
+- CSRF protection, enabled by default for POST and disabled by default for GET;
+- attribution forwarding;
+- custom success and error status codes;
+- custom successBody;
+- noContent responses.
+
+Use same-origin proxy routes for browser operations. Do not solve a proxy
+problem by moving the API key into public environment variables.
+
+## Money, images, and presentation utilities
+
+### Money
+
+~~~ts
+import { formatMoney } from "@wocart/storefront";
+
+const priceLabel = formatMoney(45000, {
+  symbol: "دج",
+  locale: "ar-DZ",
+});
+~~~
+
+Amounts are whole DZD values. formatMoney supports a symbol, locale, and
+optional decimal count. Arabic locales place the symbol as a suffix; other
+locales use the appropriate prefix behavior. Use this utility consistently so
+price presentation does not drift between cards, product pages, and checkout.
+
+### Images
+
+~~~ts
+import {
+  generateSrcSet,
+  getCardImage,
+  optimizeImage,
+} from "@wocart/storefront";
+
+const mediaDomain = env.MEDIA_DOMAIN;
+const originalImage = product.images[0]?.src ?? "";
+const cardImage = getCardImage(originalImage, mediaDomain);
+const src = optimizeImage(originalImage, {
+  width: 480,
+  height: 480,
+  quality: 82,
+  format: "auto",
+  fit: "cover",
+}, mediaDomain);
+const srcSet = generateSrcSet(originalImage, 480, 480, mediaDomain);
+~~~
+
+The image utility accepts the original media URL and can target a media
+domain. Use it to produce appropriately sized URLs rather than downloading
+original assets into every card.
+
+### Which photo a product is
+
+`coverImage` is nullable and a merchant who uploads a gallery may never pick
+one — reading that field alone renders a product with four photos and no
+thumbnail. `productImageSource` answers which image represents the product, so
+a cart drawer, a checkout summary and a product card cannot disagree:
+
+~~~ts
+import { getThumbnailImage, productImageSource } from "@wocart/storefront";
+
+const src = productImageSource(product); // Product | ProductList
+const thumbnail = src ? getThumbnailImage(src) : null;
+~~~
+
+It prefers the merchant's cover and falls back to the first usable gallery
+image; `null` means the product genuinely has no photograph, so that is the
+moment to render a placeholder. The list model carries no gallery at all, so a
+card gets the cover or `null`.
+
+Available semantic helpers include:
+
+- getCardImage;
+- getGalleryImage;
+- getThumbnailImage;
+- getHeroImage;
+- getCategoryImage;
+- getLogoImage.
+
+The helper chooses the appropriate image role. The theme still owns layout,
+aspect ratio, alt text, lazy loading, placeholders, and art direction.
+
+#### Bind the media domain once
+
+Do not thread the media domain through every call site — a missed argument
+silently ships an unoptimized image. Bind it once and use the URL-only helper
+set:
+
+~~~ts
+import { createImageHelpers } from "@wocart/storefront";
+
+const images = createImageHelpers(env.MEDIA_DOMAIN);
+
+const thumbnail = images.getThumbnailImage(product.images[0].src);
+const preview = images.getCardImage(product.images[0].src);
+const srcSet = images.generateSrcSet(product.images[0].src, 480, 480);
+~~~
+
+The returned toolkit exposes the same helpers plus `optimizeImage`,
+`generateSrcSet`, and `IMAGE_SIZES`. With no domain bound, every helper returns
+the original URL unchanged, so a store without a media domain needs no branch —
+and `optimizeImage` / `generateSrcSet` still take a per-call domain that
+overrides the bound one.
+
+## WhatsApp prefill messages
+
+The storefront's WhatsApp launcher hands the shopper to WhatsApp with a message
+already written, and the thank-you page offers the same handoff for an order.
+The template belongs to the merchant — the dashboard authors and previews it
+within the platform's limits — while the page resolves it:
+
+~~~ts
+import {
+  buildWhatsAppHref,
+  resolvePrefillText,
+} from "@wocart/storefront";
+
+const text = resolvePrefillText({
+  template: config.whatsapp.prefillProduct ?? "Hello {store}, about {product}: {url}",
+  storeName: config.name,
+  productName: product.name, // falls back to the store name when absent
+  url: Astro.url.href,       // ad-click parameters (`utm_*`, `fbclid`) stripped
+  orderNumber: null,         // resolves to nothing when absent
+});
+
+const href = buildWhatsAppHref(config.whatsapp.href, text);
+~~~
+
+Three rules come with it, and a theme must not re-implement them:
+
+- the resolved message is capped at `MAX_RESOLVED_PREFILL_LENGTH` characters and
+  cut at a word boundary, because browsers and WhatsApp both truncate silently
+  past a point;
+- `{url}` never carries ad-click parameters;
+- the encoded `text=` is appended to the base href, preserving a query string
+  the href already carries.
+
+`PREFILL_TOKENS` is the token vocabulary the dashboard offers (`product`, `url`,
+`order`, `store`); an unknown placeholder is left verbatim so a template typo is
+visible rather than silently swallowed. The cap and the token list are the
+same ones the dashboard enforces.
+
+## A recommended theme structure
+
+Keep the theme visually expressive while making the platform boundary obvious:
+
+~~~text
+src/
+  lib/
+    store.ts             server-only client factory
+    loaders/             page data loaders
+  components/             cards, gallery, cart, checkout, navigation
+  content/                copy and visual configuration owned by the theme
+  layouts/
+  pages/
+    api/                  same-origin proxy endpoints
+  actions/
+  styles/
+~~~
+
+The exact structure can change. The responsibilities should not:
+
+- store.ts owns client construction and environment access;
+- loaders compose SDK calls into page data;
+- components render data and states without calling the server directly;
+- actions validate and execute mutations;
+- API routes are the browser-to-server seam;
+- CSS and content remain theme-owned and swappable.
+
+Keep loaders thin. They should compose platform data, not calculate new
+prices, decide catalog visibility, or duplicate server policy.
+
+## A safe workflow for AI agents
+
+When an AI agent changes a theme, give it this sequence:
+
+1. Identify the user-visible task: page, section, component, checkout step,
+   or server route.
+2. Find the relevant SDK namespace in this document.
+3. Read the exported type and implementation before guessing a field or
+   endpoint.
+4. If behavior is unclear, read the method's type and doc comment, then the
+   result it actually returns: the server is the source of truth.
+5. Keep the API key and all server-only environment values out of browser
+   code.
+6. Reuse the SDK's result shape, validation, caching, and retry behavior.
+7. Add the UI states for loading, empty, unavailable, validation failure, and
+   success.
+8. For checkout changes, test both direct-product and basket orders, including
+   re-pricing and invalid-stock cases.
+9. Run typecheck and the relevant tests.
+10. Report any contract ambiguity instead of inventing a fallback that could
+    change money, stock, authorization, or tracking behavior.
+
+An AI agent should prefer an existing namespace method over a new fetch call.
+It should prefer a same-origin proxy route over exposing a secret. It should
+prefer a small loader or component change over moving business logic into the
+theme.
+
+## Common mistakes and their fixes
+
+### The page has no config
+
+config.get() returned null. Render safe theme defaults and keep the page
+usable, but investigate the server URL, API key, store scope, and server
+availability.
+
+### The catalog is empty
+
+products.list() returned an empty array. Check whether the products are
+publicly active, visible, listed, and assigned to the expected store. Do not
+replace the empty result with hardcoded products.
+
+### A product route works for an ID but not a slug
+
+products.get() accepts a public handle. Use the handle from the route and
+render null as not found.
+
+### The cart total is different after checkout
+
+This is expected when a browser price, offer, stock state, or delivery value
+was stale. Render cart.validate results and treat order creation as the final
+server decision.
+
+### OTP says unavailable
+
+Use the documented bypassToken path when the server supplies one. Do not
+pretend that a code was sent or repeatedly poll for a code.
+
+### A legal page looks like escaped HTML
+
+Render page.bodyHtml through Astro's HTML rendering mechanism. The server has
+already sanitized it; do not print it as ordinary text or apply a second
+sanitizer in the theme.
+
+### A browser request gets a CSRF or validation error
+
+Call the same-origin proxy route with the expected method and body shape.
+Check inputSchema, queryParams, pathParams, and the route's CSRF policy before
+changing the server.
+
+### Images are slow
+
+Use the image helpers and request dimensions appropriate to the component.
+Do not use a full original asset for every thumbnail.
+
+## Definition of done for a new theme
+
+Before calling a theme ready, confirm:
+
+- A server-only StoreClient is created with the correct server URL and API key.
+- No browser bundle, public variable, HTML page, or client route exposes the
+  API key.
+- Config flags control cart, reviews, OTP, checkout fields, delivery options,
+  and tracking.
+- Product lists use ProductList and product pages use Product.
+- Product routes use public handles.
+- Null, empty, loading, validation, and upstream failure states are designed.
+- All displayed and submitted prices are treated as whole-DZD server values.
+- Browser baskets are validated before checkout.
+- Direct-product and basket order shapes are both handled when the store
+  supports them.
+- OTP sent, verified, unavailable, retry, and terminal states are covered.
+- Tracking null means no conversion event.
+- Legal pages render sanitized bodyHtml safely and use config.pages for links.
+- Browser mutations go through same-origin proxy routes.
+- Money and image utilities are used consistently.
+- The theme typechecks against the SDK's declarations.
+- Relevant tests pass.
+
+## Compatibility and versioning
+
+What this SDK promises, and what it needs from the platform:
+
+| Dimension | Status |
+| --- | --- |
+| Versioning | [Semantic versioning](https://semver.org/). A breaking change ships only in a new major version; an export is marked `@deprecated` for at least one minor release before a major removes it |
+| Server contract | The store's public `/store/*` API. Every path the SDK calls, and every constant it shares with the server (basket caps, WhatsApp prefill cap and tokens, the 1,551-row commune bundle), is checked against the server before each release |
+| zod | A peer dependency (`^4.4.3`): the SDK's schemas are part of its API, so your app and the SDK share one copy. Astro 7 depends on zod 4 as well, so `astro/zod` resolves to that same copy |
+| Unknown response fields | Tolerated: schemas strip fields they do not know, so a server that adds a field before this SDK documents it cannot break a theme |
+| Missing response fields | Rejected for required fields and normalised for optional ones (`null` → the documented empty value) — a drifted response degrades rather than crashing a page, and reports through `onError` |
+| Node / runtime | ESM-only, `node >= 22.12` for tooling. The code targets ES2022 + DOM and runs in browsers, workers, and Astro server runtimes; there is no CJS build and no Node built-in in the browser-safe entries |
+| Astro | Framework-neutral core. `@wocart/storefront/astro` has **no Astro import** — its adapter types are structural mirrors of `APIRoute`, `defineAction` and `getActionContext`, so it works with the Astro version your theme pins (7.x verified) without a peer dependency |
+
+Depend on a major range (`^1.0.0`) to receive fixes and additions.
+
+## Testing a theme
+
+Test your theme against a running store: a server origin and a store key in a
+local, uncommitted secrets file, then your theme's dev server. In unit tests,
+stand in for the server with your own `StoreClient` double — every namespace
+method resolves to the documented result shapes, so a double only needs the
+methods a component calls.
+
+## Where to look when this guide is not enough
+
+1. The declarations shipped with the package (`dist/*.d.ts`): every export is
+   typed and documented in place.
+2. The browser-safe surface is `@wocart/storefront`; the client is
+   `@wocart/storefront/server`; the Astro adapters are
+   `@wocart/storefront/astro`. Nothing else is public.
+3. The changelog, for what changed and when.
+
+Do not work around a server contract by duplicating it in a theme.
+
+## What the SDK does not do
+
+- It does not provide database access, merchant permissions, or merchant authentication.
+- It does not replace Astro pages, layouts, virtual modules, or UI state.
+- It does not make browser prices trustworthy.
+- It does not store the browser basket on the server.
+- It does not decide a theme's visual language, copy, layout, motion, or
+  accessibility design.
+- It does not make an unavailable resource, empty catalog, invalid order, or
+  missing tracking configuration look successful.