@wocart/storefront 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ follows [semantic versioning](https://semver.org/): breaking changes ship only
 in a new major version, and an export is marked `@deprecated` for at least one
 minor release before a major removes it.
 
+## 1.8.0 — 2026-10-17
+
+### Added
+
+- **Collections.** `products.list({ collection: "best-sellers" })` lists a
+  collection — a list of products the merchant curates by hand — in the
+  merchant's order; an unknown handle lists nothing. `products.list({ onSale:
+  true })` lists the products priced below their compare-at price. Both need
+  a server with collections.
+
+### Deprecated
+
+- `products.list({ featured: true })` and `ProductList.storeFeatured`: they
+  mean the `featured` collection; removed in 2.0.
+- `StoreConfig.primaryColor`, `accentColor`, `bgColor`, `fontFamily` and
+  `fontUrl`. A store's colors and font are its theme's settings: a theme
+  declares them (`defineTheme({ settings })` in `@wocart/theme`) and reads
+  `themeSettings`. The fields still arrive — the values saved before, no
+  longer editable (`fontUrl` is always null) — and are removed in 2.0.
+- `StoreConfig.announcementBar`: always null. An announcement is a theme's
+  own content, declared as a theme setting; removed in 2.0.
+
+## 1.7.0 — 2026-10-17
+
+### Added
+
+- **Page types and their URLs.** `STOREFRONT_PAGE_PATHS` is the platform's
+  table of public paths (`home`, `catalog`, `category`, `product`, `page`,
+  `landing`, `checkout`, `thankYou`); `storefrontPath(type, params)` builds
+  one (encoded; a missing parameter throws) and `matchStorefrontPath(pathname)`
+  recognises one, exactly. Types `StorefrontPageType`, `StorefrontPathParams`,
+  `StorefrontPageMatch`.
+- **Navigation menus.** `store.menus.get(handle)` reads a menu as a shopper
+  sees it: labels in the client's language, every `href` resolved by the
+  server, items leading nowhere public already left out; `null` for an
+  unknown handle, which is not reported to `onError`. Types `StoreMenu`,
+  `StoreMenuItem`, schemas `StoreMenuSchema`, `StoreMenuItemSchema`.
+- `StoreConfig.themeSettings`: the merchant's values for the requesting
+  theme's settings, as saved — resolve them with `resolveThemeSettings` from
+  `@wocart/theme` 1.1. Optional: absent from a server that predates them.
+
+### Deprecated
+
+- `STOREFRONT_ROUTES` lists six of the paths, without the home and the
+  catalog; use `STOREFRONT_PAGE_PATHS` and `matchStorefrontPath`.
+
 ## 1.6.0 — 2026-10-17
 
 ### Added

package/USAGE.md

@@ -90,34 +90,55 @@ 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
+## Page types and their URLs
 
-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:
+A URL *means* something to the platform — a product, a category, a store
+page — and that meaning is a **page type**. Each page type lives at one
+public path. The paths are a platform contract, not a theme preference: the
+platform builds them without running your theme (the dashboard prints a page's
+public link, the server names the landing page in the URL Meta is told about,
+the AI tools hand out landing-page links), so a theme that moved one would
+break those links.
 
-| 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.
+| Page type | Path | Renders | Your theme |
+| --- | --- | --- | --- |
+| `home` | `/` | the home page | required |
+| `catalog` | `/products` | every product | required |
+| `category` | `/category/:slug` | one category's products | required when the store has categories |
+| `product` | `/products/:handle` | one product (its public handle, never an id) | required |
+| `page` | `/pages/:slug` | a legal or merchant page | required — checkout consent links to the store's legal pages |
+| `landing` | `/lp/:slug` | a landing page | required when the store runs landing pages |
+| `checkout` | `/checkout` | the cart's checkout | required when the store turns the cart on |
+| `thankYou` | `/thank-you` | the order confirmation | required |
+
+How a theme implements them, in Astro's own terms:
+
+- **Render each page type at its path with a file route**:
+  `src/pages/products/[handle].astro`, `src/pages/lp/[slug].astro` … The
+  parameter's name in your file is yours; the path is the platform's.
+- **Build every link with `storefrontPath`**, never a hand-written string:
+  `storefrontPath("product", { handle: product.handle })` → `/products/robe`,
+  `storefrontPath("checkout")` → `/checkout`. Parameters are encoded for you;
+  a missing one throws, so a link to nowhere fails loudly. Add the language
+  prefix with `localizeHref(storefrontPath(…), locale, routing)`.
+- **Recognise a page with `matchStorefrontPath(pathname)`** →
+  `{ type: "product", params: { handle: "robe" } }`, or `null` for any other
+  path. It matches exactly — `/productsomething`, `/products/a/b` and
+  `/checkout-success` are nothing — and ignores the query, fragment and a
+  trailing slash. Pass the path without its language prefix.
+- **Answer a missing resource with a real 404** (`return Astro.rewrite("/404")`),
+  never a redirect to the home page: a redirect turns a dead link into a
+  "soft 404" for search engines and ad reviews.
+- **Every other route is yours.** `/about`, `/offers/summer`, a store
+  locator — add them as Astro file routes; nothing in the contract restricts
+  them. Avoid the platform's paths above and `/api/*` (your same-origin
+  endpoints, see "Storefront API routes").
+
+`showsWidgetOn(surfaces, pathname)` is the platform's half of "should the
+WhatsApp widget show here": the merchant switches surfaces on; the page type
+says which surface a pathname is. `STOREFRONT_PAGE_PATHS` is the table above
+as data. `STOREFRONT_ROUTES` is deprecated: it lists six of the paths, without
+the home and the catalog.
 
 ## The five rules to remember
 
@@ -196,7 +217,8 @@ server directly.
 | `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) |
+| `storefrontPath`, `matchStorefrontPath`, `STOREFRONT_PAGE_PATHS` | The page types and their public paths: build a link, recognise a page |
+| `showsWidgetOn`, `STOREFRONT_ROUTES` | Which widget surface a pathname is (`STOREFRONT_ROUTES` deprecated) |
 | `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 |
@@ -295,6 +317,7 @@ carries the key, which the package's own contract test asserts.
 | 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 |
+| menus | The store's navigation menus | StoreMenu 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 |
@@ -460,29 +483,46 @@ store.
 ## Store configuration
 
 Use config.get() near the root of every page. It is the theme's starting point
-for branding and feature flags:
+for store identity 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;
+- name, domain, logoUrl and themeId (the colors, fontFamily and fontUrl
+  fields are deprecated: colors and fonts are theme settings, read from
+  themeSettings);
+- lang (the primary language), locales, contentOverrides, themeSettings,
+  currency, currencySymbol, metaTitle, metaDescription, and ogImage;
+- reviewsEnabled (announcementBar is deprecated and always null: an
+  announcement is a theme's own setting);
 - cartEnabled, freeShippingThreshold, and cartShippingMode;
 - checkoutForm policy;
 - OTP and Turnstile settings;
 - pixelId and conversionEvent;
 - public page links, legal contact information, and WhatsApp widget settings.
 
+`themeSettings` holds the merchant's values for your theme's settings (the
+ones it declares with `defineTheme({ settings })` in `@wocart/theme`), by
+setting key, exactly as saved. It is sent only to a client created with
+`theme`, is `{}` when the store saved none, and is absent from a server that
+predates theme settings — `resolveThemeSettings` takes either. Never read it raw: resolve it
+against your declaration, which checks every value and falls back to your
+default for one it no longer accepts:
+
+~~~ts
+import { resolveThemeSettings } from "@wocart/theme";
+
+const { values } = resolveThemeSettings(theme, config?.themeSettings, { locales: [locale] });
+const headerMenu = values.headerMenu; // a menu handle, for store.menus.get()
+~~~
+
 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:
@@ -592,11 +632,28 @@ decides whether a product is publicly available.
 ~~~ts
 const products = await store.products.list({
   categoryId: selectedCategoryId,
-  featured: true,
   limit: 12,
 });
 ~~~
 
+**Collections** are lists of products the merchant curates by hand in the
+dashboard (Products → Collections): every store starts with `featured`,
+`best-sellers` and `new-arrivals`, and may add any other. A collection lists
+in the merchant's order:
+
+~~~ts
+const bestSellers = await store.products.list({ collection: "best-sellers", limit: 8 });
+const onSale = await store.products.list({ onSale: true, limit: 8 });
+~~~
+
+- Never hardcode which collection a section shows: declare a `collection`
+  field (`@wocart/theme`) with a default handle, so the merchant picks it.
+- An empty or unknown collection lists nothing — show nothing, never the
+  whole catalog instead: "Best sellers" means the merchant's picks.
+- `onSale` is computed: a product priced below its compare-at price.
+- `featured: true` and `ProductList.storeFeatured` are deprecated: they mean
+  the `featured` collection.
+
 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
@@ -716,6 +773,36 @@ 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.
 
+### Navigation menus
+
+A store's menus are store data, like its products: the merchant builds them in
+the dashboard (Navigation) — a handle such as `main-menu`, a title, and up to
+three levels of items, each pointing at a product, a category, a store page, a
+landing page, the home, the catalog, or a URL. Your theme decides *where* a
+menu shows; the merchant decides *what* it holds.
+
+~~~ts
+const menu = await store.menus.get(settings.headerMenu); // "main-menu"
+
+for (const item of menu?.items ?? []) {
+  const href = item.type === "url" ? item.href : localizeHref(item.href, locale, routing);
+  // item.label, item.children (same shape, at most three levels)
+}
+~~~
+
+- Name the menu through a `menu` theme setting rather than a hard-coded
+  handle, so the merchant picks which menu each place shows.
+- Every link is resolved by the server: `href` is a path of the store without
+  a language prefix (pass it through `localizeHref`) or, for `type: "url"`,
+  the address the merchant entered — render it as is.
+- An item whose destination is deleted or not public (a draft page, an
+  inactive product) is already left out, with its children. You never filter.
+- Labels arrive in the client's language when the store translated them.
+- `null` means the store has no menu with that handle, or the read failed:
+  render your own fallback navigation (for example the home and the catalog
+  from `storefrontPath`). A missing menu is not a failure and is not reported
+  to `onError`.
+
 ### Landing pages
 
 ~~~ts

package/dist/client/index.d.ts

@@ -2,7 +2,7 @@
  * Store Client Factory — the SDK's front door.
  *
  * One server-side call builds the whole read/write surface a theme needs, over one
- * shared core: config, products, categories, pages, shipping, geo, cart,
+ * shared core: config, products, categories, pages, menus, shipping, geo, cart,
  * orders. The core is internal — consumers see only namespaces.
  *
  * One core means one connection story for every namespace: every read is
@@ -31,6 +31,7 @@ export declare function createStoreClient(config: StoreScope): {
     products: import("./products.js").ProductsNamespace;
     categories: import("./categories.js").CategoriesNamespace;
     pages: import("./pages.js").PagesNamespace;
+    menus: import("./menus.js").MenusNamespace;
     pageData: import("./page-data.js").PageDataNamespace;
     shipping: import("./shipping.js").ShippingNamespace;
     geo: import("./geo.js").GeoNamespace;

package/dist/client/index.js

@@ -2,7 +2,7 @@
  * Store Client Factory — the SDK's front door.
  *
  * One server-side call builds the whole read/write surface a theme needs, over one
- * shared core: config, products, categories, pages, shipping, geo, cart,
+ * shared core: config, products, categories, pages, menus, shipping, geo, cart,
  * orders. The core is internal — consumers see only namespaces.
  *
  * One core means one connection story for every namespace: every read is
@@ -31,6 +31,7 @@ import { createConfigNamespace } from "./config.js";
 import { createProductsNamespace } from "./products.js";
 import { createCategoriesNamespace } from "./categories.js";
 import { createPagesNamespace } from "./pages.js";
+import { createMenusNamespace } from "./menus.js";
 import { createPageDataNamespace } from "./page-data.js";
 import { createShippingNamespace } from "./shipping.js";
 import { createGeoNamespace } from "./geo.js";
@@ -44,6 +45,7 @@ export function createStoreClient(config) {
         products: createProductsNamespace(core),
         categories: createCategoriesNamespace(core),
         pages: createPagesNamespace(core),
+        menus: createMenusNamespace(core),
         pageData: createPageDataNamespace(core),
         shipping: createShippingNamespace(core),
         geo: createGeoNamespace(core),

package/dist/client/menus.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Menus Namespace - the store's navigation menus
+ *
+ * A menu is store data the merchant edits in the dashboard; a theme names it
+ * by handle (usually through a `menu` theme setting) and renders what comes
+ * back. Every link is resolved by the server: an item's `href` is a path of
+ * the store without a language prefix, or the merchant's URL, and items
+ * leading nowhere public are already left out. Fetched fresh every request.
+ *
+ * Failure contract: `get(handle)` → null means "no such menu" or a failed
+ * read — the theme renders its own fallback navigation.
+ */
+import { type ClientCore } from "./core.js";
+import type { StoreMenu } from "../types.js";
+export interface MenusNamespace {
+    /**
+     * A menu by handle (`main-menu`), labels in the client's language.
+     * Resolves to `null` for an unknown handle or a failed read.
+     */
+    get(handle: string): Promise<StoreMenu | null>;
+}
+export declare function createMenusNamespace(core: ClientCore): MenusNamespace;

package/dist/client/menus.js

@@ -0,0 +1,30 @@
+/**
+ * Menus Namespace - the store's navigation menus
+ *
+ * A menu is store data the merchant edits in the dashboard; a theme names it
+ * by handle (usually through a `menu` theme setting) and renders what comes
+ * back. Every link is resolved by the server: an item's `href` is a path of
+ * the store without a language prefix, or the merchant's URL, and items
+ * leading nowhere public are already left out. Fetched fresh every request.
+ *
+ * Failure contract: `get(handle)` → null means "no such menu" or a failed
+ * read — the theme renders its own fallback navigation.
+ */
+import { StoreMenuSchema } from "../schemas.js";
+import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { localizedPath } from "./paths.js";
+import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
+export function createMenusNamespace(core) {
+    return {
+        async get(handle) {
+            try {
+                return await core.get(localizedPath(core.config, `/store/menus/${encodeURIComponent(handle)}`), StoreMenuSchema, { operation: STOREFRONT_OPERATIONS.menusGet });
+            }
+            catch (error) {
+                if (!isNotFoundAnswer(error))
+                    reportDegradedRead(core.config, error, "menus.get");
+                return null;
+            }
+        },
+    };
+}

package/dist/client/products.d.ts

@@ -26,7 +26,7 @@ export interface ProductsNamespace {
     get(handle: string): Promise<Product | null>;
     /**
      * List products with optional filters
-     * @param filters - Optional category, featured flag, limit and offset
+     * @param filters - Optional collection, category, on-sale flag, limit and offset
      * @returns Array of products
      */
     list(filters?: ProductListFilters): Promise<ProductList[]>;

package/dist/client/products.js

@@ -28,6 +28,8 @@ export function createProductsNamespace(core) {
         try {
             const products = await core.get(localizedPath(core.config, "/store/products", {
                 categoryId: filters?.categoryId || undefined,
+                collection: filters?.collection || undefined,
+                onSale: filters?.onSale ? "true" : undefined,
                 featured: filters?.featured ? "true" : undefined,
                 limit: filters?.limit === undefined ? undefined : String(filters.limit),
                 offset: filters?.offset ? String(filters.offset) : undefined,

package/dist/domain.d.ts

@@ -353,6 +353,7 @@ export declare const STOREFRONT_OPERATIONS: {
     readonly productsReviewsUpload: "products.reviews.upload";
     readonly pagesGet: "pages.get";
     readonly pagesLanding: "pages.landing";
+    readonly menusGet: "menus.get";
     readonly shippingRates: "shipping.rates";
     readonly shippingRate: "shipping.rate";
     readonly geoCommunes: "geo.communes";
@@ -390,6 +391,7 @@ export declare const STOREFRONT_RETRY_POLICIES: {
     readonly "pageData.get": "safe-read";
     readonly "pages.get": "safe-read";
     readonly "pages.landing": "safe-read";
+    readonly "menus.get": "safe-read";
     readonly "products.get": "safe-read";
     readonly "products.list": "safe-read";
     readonly "products.reviews.list": "safe-read";

package/dist/domain.js

@@ -206,6 +206,7 @@ export const STOREFRONT_OPERATIONS = {
     productsReviewsUpload: "products.reviews.upload",
     pagesGet: "pages.get",
     pagesLanding: "pages.landing",
+    menusGet: "menus.get",
     shippingRates: "shipping.rates",
     shippingRate: "shipping.rate",
     geoCommunes: "geo.communes",
@@ -242,6 +243,7 @@ export const STOREFRONT_RETRY_POLICIES = {
     [STOREFRONT_OPERATIONS.pageDataGet]: "safe-read",
     [STOREFRONT_OPERATIONS.pagesGet]: "safe-read",
     [STOREFRONT_OPERATIONS.pagesLanding]: "safe-read",
+    [STOREFRONT_OPERATIONS.menusGet]: "safe-read",
     [STOREFRONT_OPERATIONS.productsGet]: "safe-read",
     [STOREFRONT_OPERATIONS.productsList]: "safe-read",
     [STOREFRONT_OPERATIONS.productsReviewsList]: "safe-read",

package/dist/index.d.ts

@@ -17,11 +17,11 @@ export { productImageSource } from "./utils/product-image.js";
 export type { ProductImageSourceInput } from "./utils/product-image.js";
 export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, } from "./whatsapp.js";
 export type { PrefillToken, ResolvePrefillParams } from "./whatsapp.js";
-export { STOREFRONT_ROUTES, showsWidgetOn } from "./routes.js";
+export { STOREFRONT_PAGE_PATHS, STOREFRONT_ROUTES, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";
 export { servedLanguage } from "./locales.js";
 export { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "./locale-routing.js";
 export type { LocalePath, LocaleRouting } from "./locale-routing.js";
-export type { StorefrontRoute } from "./routes.js";
+export type { StorefrontPageMatch, StorefrontPageType, StorefrontPathParams, StorefrontRoute } from "./routes.js";
 export { createBasketStore, createMemoryStorageAdapter, createLocalStorageAdapter, DEFAULT_BASKET_STORAGE_KEY, toOrderItems, } from "./basket.js";
 export type { BasketStore, BasketStorageAdapter, BasketStoreOptions, BasketListener, } from "./basket.js";
 export { createOtpMachine, createOtpTransport, mapOtpResponse, otpTransportFailure, } from "./otp.js";

package/dist/index.js

@@ -13,7 +13,7 @@ export { formatMoney } from "./utils/money.js";
 export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, } from "./utils/image.js";
 export { productImageSource } from "./utils/product-image.js";
 export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, } from "./whatsapp.js";
-export { STOREFRONT_ROUTES, showsWidgetOn } from "./routes.js";
+export { STOREFRONT_PAGE_PATHS, STOREFRONT_ROUTES, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";
 export { servedLanguage } from "./locales.js";
 export { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "./locale-routing.js";
 export { createBasketStore, createMemoryStorageAdapter, createLocalStorageAdapter, DEFAULT_BASKET_STORAGE_KEY, toOrderItems, } from "./basket.js";

package/dist/routes.d.ts

@@ -1,20 +1,59 @@
 /**
- * The canonical storefront route contract.
+ * The storefront's page types and their public paths.
  *
- * One deployment serves one store, and three parts of the platform meet on the
- * same public URLs: the theme renders them, the server writes them into a conversion's
- * landing URL (`/lp/:slug` for an attributed sale, `/thank-you` otherwise), and
- * the dashboard shows them as the store's public links (`/pages/:slug`). These
- * patterns are what all three already assume, so they are written down here: a
- * theme may restyle everything else, but these paths are a platform contract,
- * not a theme decision.
+ * A page type is what a URL *means* — a product, a category, a store page, a
+ * landing page — and the path is where it lives. The paths are a platform
+ * contract, not a theme decision: the platform builds them without running
+ * the theme (the dashboard shows a page's public link, the server names the
+ * landing page in a conversion's source URL), so a theme renders each page
+ * type it supports at its path and builds every link to one with
+ * `storefrontPath` — never a hand-written string. Any other route is the
+ * theme's own (`/about`, `/offers/summer` …): Astro's file routing owns those,
+ * and nothing here constrains them.
  *
- * Two further paths carry no parameter and no pattern: the root (`/`, the home
- * surface) and the catalog index (`/products`, the catalog surface). The
- * surface gate below handles them alongside the six frozen patterns.
+ * Language prefixes are applied on top: `localizeHref(storefrontPath(…),
+ * locale, routing)`.
  */
 import type { WidgetSurfaces } from "./types.js";
-/** One route in the contract: the pattern and the surface that renders it. */
+/** Each page type's public path; `:handle` / `:slug` mark its one parameter. */
+export declare const STOREFRONT_PAGE_PATHS: {
+    readonly home: "/";
+    readonly catalog: "/products";
+    readonly category: "/category/:slug";
+    readonly product: "/products/:handle";
+    readonly page: "/pages/:slug";
+    readonly landing: "/lp/:slug";
+    readonly checkout: "/checkout";
+    readonly thankYou: "/thank-you";
+};
+/** What a storefront URL means. */
+export type StorefrontPageType = keyof typeof STOREFRONT_PAGE_PATHS;
+type ParamOf<P extends string> = P extends `${string}:${infer Name}` ? Name : never;
+/** The parameter a page type's path needs: `{ handle }` for a product, `{ slug }` for a category, page or landing page, nothing otherwise. */
+export type StorefrontPathParams<T extends StorefrontPageType> = ParamOf<(typeof STOREFRONT_PAGE_PATHS)[T]> extends never ? Record<string, never> : {
+    [K in ParamOf<(typeof STOREFRONT_PAGE_PATHS)[T]>]: string;
+};
+/** A pathname recognised as one of the page types, with its parameter. */
+export interface StorefrontPageMatch {
+    readonly type: StorefrontPageType;
+    readonly params: Readonly<Record<string, string>>;
+}
+/**
+ * The public path of a page type, its parameter encoded:
+ * `storefrontPath("product", { handle: "robe" })` → `/products/robe`.
+ * Throws when the parameter is missing — a link to nowhere is a bug to see,
+ * not a path to render.
+ */
+export declare function storefrontPath<T extends StorefrontPageType>(type: T, params?: StorefrontPathParams<T>): string;
+/**
+ * Which page type a pathname is, and its parameter (decoded) — or null for
+ * any other path. Exact matches only: `/products/` is the catalog,
+ * `/productsomething` and `/products/a/b` are nothing. The query, the
+ * fragment and a trailing slash are ignored. Pass a pathname without its
+ * language prefix (`resolveLocalePath` gives it).
+ */
+export declare function matchStorefrontPath(rawPathname: string): StorefrontPageMatch | null;
+/** One route with a parameter or a fixed path of its own, and the widget surface that renders it. */
 export interface StorefrontRoute {
     /** Path pattern; `:handle` and `:slug` mark the single path parameter. */
     readonly path: string;
@@ -22,24 +61,17 @@ export interface StorefrontRoute {
     readonly surface: keyof WidgetSurfaces;
 }
 /**
- * The frozen contract. Adding a route is a deliberate platform change: a path
- * that renders a surface but is missing here is a surface the merchant cannot
- * switch on with any confidence.
+ * @deprecated Use `STOREFRONT_PAGE_PATHS` (every page type, the home and the
+ * catalog index included) with `storefrontPath` and `matchStorefrontPath`.
+ * Kept equal to what it always listed.
  */
 export declare const STOREFRONT_ROUTES: readonly StorefrontRoute[];
 /**
- * Whether the widget belongs on a pathname.
- *
- * The merchant answers "which surfaces" (`surfaces[surface]`); this function
- * answers the platform half — which surface a pathname *is* — and it reads the
- * contract above:
- *
- * - `/` → the home surface;
- * - `/products` (the catalog index) and `/category/:slug` → the catalog surface;
- * - `/products/:handle` → the product surface;
- * - `/pages/:slug`, `/lp/:slug`, `/checkout`, `/thank-you` → their own surfaces;
- * - anything else — a 404, `/productsomething`, `/checkout-success` — → no
- *   surface at all, never a prefix match that leaks a widget onto a page the
- *   merchant switched off.
+ * Whether the widget belongs on a pathname: the merchant answers "which
+ * surfaces" (`surfaces[surface]`); this answers which surface a pathname *is*,
+ * from the page types above. Any other path — a 404, `/productsomething`,
+ * `/checkout-success` — is no surface at all, never a prefix match that leaks
+ * the widget onto a page the merchant switched off.
  */
 export declare function showsWidgetOn(surfaces: WidgetSurfaces | null | undefined, rawPathname: string): boolean;
+export {};

package/dist/routes.js

@@ -1,59 +1,88 @@
+/** Each page type's public path; `:handle` / `:slug` mark its one parameter. */
+export const STOREFRONT_PAGE_PATHS = {
+    home: "/",
+    catalog: "/products",
+    category: "/category/:slug",
+    product: "/products/:handle",
+    page: "/pages/:slug",
+    landing: "/lp/:slug",
+    checkout: "/checkout",
+    thankYou: "/thank-you",
+};
 /**
- * The frozen contract. Adding a route is a deliberate platform change: a path
- * that renders a surface but is missing here is a surface the merchant cannot
- * switch on with any confidence.
+ * The public path of a page type, its parameter encoded:
+ * `storefrontPath("product", { handle: "robe" })` → `/products/robe`.
+ * Throws when the parameter is missing — a link to nowhere is a bug to see,
+ * not a path to render.
  */
-export const STOREFRONT_ROUTES = [
-    { path: "/products/:handle", surface: "product" },
-    { path: "/category/:slug", surface: "catalog" },
-    { path: "/pages/:slug", surface: "pages" },
-    { path: "/lp/:slug", surface: "landing" },
-    { path: "/checkout", surface: "checkout" },
-    { path: "/thank-you", surface: "thankYou" },
-];
+export function storefrontPath(type, params) {
+    return STOREFRONT_PAGE_PATHS[type].replace(/:([a-z]+)/g, (_, name) => {
+        const value = params?.[name];
+        if (!value)
+            throw new Error(`storefrontPath("${type}") needs "${name}"`);
+        return encodeURIComponent(value);
+    });
+}
+const MATCHERS = Object.entries(STOREFRONT_PAGE_PATHS).map(([type, path]) => {
+    const names = [];
+    const source = path.replace(/:([a-z]+)/g, (_, name) => {
+        names.push(name);
+        return "([^/]+)";
+    });
+    return { type, names, pattern: new RegExp(`^${source}$`) };
+});
+/**
+ * Which page type a pathname is, and its parameter (decoded) — or null for
+ * any other path. Exact matches only: `/products/` is the catalog,
+ * `/productsomething` and `/products/a/b` are nothing. The query, the
+ * fragment and a trailing slash are ignored. Pass a pathname without its
+ * language prefix (`resolveLocalePath` gives it).
+ */
+export function matchStorefrontPath(rawPathname) {
+    const pathname = rawPathname.split(/[?#]/)[0].replace(/\/+$/, "") || "/";
+    for (const { type, names, pattern } of MATCHERS) {
+        const match = pattern.exec(pathname);
+        if (!match)
+            continue;
+        try {
+            return { type, params: Object.fromEntries(names.map((name, i) => [name, decodeURIComponent(match[i + 1])])) };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/** The WhatsApp widget surface each page type belongs to (the home surface is the root). */
+const WIDGET_SURFACE = {
+    home: "home",
+    catalog: "catalog",
+    category: "catalog",
+    product: "product",
+    page: "pages",
+    landing: "landing",
+    checkout: "checkout",
+    thankYou: "thankYou",
+};
+/**
+ * @deprecated Use `STOREFRONT_PAGE_PATHS` (every page type, the home and the
+ * catalog index included) with `storefrontPath` and `matchStorefrontPath`.
+ * Kept equal to what it always listed.
+ */
+export const STOREFRONT_ROUTES = ["product", "category", "page", "landing", "checkout", "thankYou"].map((type) => ({
+    path: STOREFRONT_PAGE_PATHS[type],
+    surface: WIDGET_SURFACE[type],
+}));
 /**
- * Whether the widget belongs on a pathname.
- *
- * The merchant answers "which surfaces" (`surfaces[surface]`); this function
- * answers the platform half — which surface a pathname *is* — and it reads the
- * contract above:
- *
- * - `/` → the home surface;
- * - `/products` (the catalog index) and `/category/:slug` → the catalog surface;
- * - `/products/:handle` → the product surface;
- * - `/pages/:slug`, `/lp/:slug`, `/checkout`, `/thank-you` → their own surfaces;
- * - anything else — a 404, `/productsomething`, `/checkout-success` — → no
- *   surface at all, never a prefix match that leaks a widget onto a page the
- *   merchant switched off.
+ * Whether the widget belongs on a pathname: the merchant answers "which
+ * surfaces" (`surfaces[surface]`); this answers which surface a pathname *is*,
+ * from the page types above. Any other path — a 404, `/productsomething`,
+ * `/checkout-success` — is no surface at all, never a prefix match that leaks
+ * the widget onto a page the merchant switched off.
  */
 export function showsWidgetOn(surfaces, rawPathname) {
     if (!surfaces)
         return false;
-    // Normalise: strip query/hash, strip trailing slashes (except root "/")
-    const pathname = rawPathname.split("?")[0].split("#")[0].replace(/\/+$/, "") || "/";
-    if (pathname === "/") {
-        return Boolean(surfaces.home);
-    }
-    if (pathname === "/products" || pathname.startsWith("/category/")) {
-        return Boolean(surfaces.catalog);
-    }
-    if (pathname.startsWith("/products/")) {
-        const slug = pathname.slice("/products/".length);
-        return slug.length > 0 ? Boolean(surfaces.product) : Boolean(surfaces.catalog);
-    }
-    if (pathname === "/checkout") {
-        return Boolean(surfaces.checkout);
-    }
-    if (pathname === "/thank-you") {
-        return Boolean(surfaces.thankYou);
-    }
-    if (pathname.startsWith("/pages/")) {
-        const slug = pathname.slice("/pages/".length);
-        return slug.length > 0 ? Boolean(surfaces.pages) : false;
-    }
-    if (pathname.startsWith("/lp/")) {
-        const slug = pathname.slice("/lp/".length);
-        return slug.length > 0 ? Boolean(surfaces.landing) : false;
-    }
-    return false;
+    const match = matchStorefrontPath(rawPathname);
+    return match ? Boolean(surfaces[WIDGET_SURFACE[match.type]]) : false;
 }

package/dist/schemas.d.ts

@@ -234,6 +234,23 @@ export declare const StorePagePublicSchema: z.ZodObject<{
     metaTitle: z.ZodNullable<z.ZodString>;
     metaDescription: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * A navigation menu as a shopper sees it — GET /store/menus/{handle}.
+ * `type` is an open string: the server owns which destinations exist, so a
+ * new one never fails this parse.
+ */
+export declare const StoreMenuItemSchema: z.ZodType<StoreMenuItemShape>;
+interface StoreMenuItemShape {
+    label: string;
+    href: string;
+    type: string;
+    children: StoreMenuItemShape[];
+}
+export declare const StoreMenuSchema: z.ZodObject<{
+    handle: z.ZodString;
+    title: z.ZodString;
+    items: z.ZodArray<z.ZodType<StoreMenuItemShape, unknown, z.core.$ZodTypeInternals<StoreMenuItemShape, unknown>>>;
+}, z.core.$strip>;
 /**
  * The persisted theme page document (PageData): the
  * TRANSPORT shape only. `sections` stays `unknown[]` so instances of a newer
@@ -373,6 +390,7 @@ export declare const StoreConfigSchema: z.ZodObject<{
         }>;
     }, z.core.$strip>>;
     contentOverrides: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>;
+    themeSettings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     currency: z.ZodString;
     currencySymbol: z.ZodString;
     metaTitle: z.ZodNullable<z.ZodString>;
@@ -832,3 +850,4 @@ export declare const ReviewListEnvelopeSchema: z.ZodObject<{
     }, z.core.$strip>, unknown>>;
     total: z.ZodNumber;
 }, z.core.$strip>;
+export {};

package/dist/schemas.js

@@ -82,6 +82,7 @@ const productBaseFields = {
     visibility: z.boolean(),
     status: z.enum(["DRAFT", "ACTIVE", "ARCHIVED"]),
     showInStore: z.boolean(),
+    /** @deprecated Whether the product is in the `featured` collection; list it with `collection: "featured"`. Removed in 2.0. */
     storeFeatured: z.boolean(),
     /**
      * @deprecated Always null: the server never serves a removed product. The
@@ -133,6 +134,22 @@ export const StorePagePublicSchema = z.object({
     metaTitle: z.string().nullable(),
     metaDescription: z.string().nullable(),
 });
+/**
+ * A navigation menu as a shopper sees it — GET /store/menus/{handle}.
+ * `type` is an open string: the server owns which destinations exist, so a
+ * new one never fails this parse.
+ */
+export const StoreMenuItemSchema = z.lazy(() => z.object({
+    label: z.string(),
+    href: z.string(),
+    type: z.string(),
+    children: z.array(StoreMenuItemSchema),
+}));
+export const StoreMenuSchema = z.object({
+    handle: z.string(),
+    title: z.string(),
+    items: z.array(StoreMenuItemSchema),
+});
 /**
  * The persisted theme page document (PageData): the
  * TRANSPORT shape only. `sections` stays `unknown[]` so instances of a newer
@@ -225,6 +242,11 @@ export const StoreConfigSchema = z.object({
     locales: z.array(StorefrontLanguageSchema),
     /** The requesting theme's text edits, one map per published language. */
     contentOverrides: z.record(z.string(), z.record(z.string(), z.string())),
+    /**
+     * The store's values for the requesting theme's settings, as saved. Absent
+     * from a server older than theme settings.
+     */
+    themeSettings: z.record(z.string(), z.unknown()).optional(),
     currency: z.string(),
     currencySymbol: z.string(),
     metaTitle: z.string().nullable(),

package/dist/types.d.ts

@@ -64,10 +64,31 @@ export interface StoreConfig {
     domain: string | null;
     logoUrl: string | null;
     themeId: string;
+    /**
+     * @deprecated A store's colors and font are its theme's settings: declare
+     * them in `defineTheme({ settings })` and read `themeSettings`. This is the
+     * value saved before that, no longer editable; removed in 2.0.
+     */
     primaryColor: string;
+    /**
+     * @deprecated A store's colors and font are its theme's settings: declare
+     * them in `defineTheme({ settings })` and read `themeSettings`. This is the
+     * value saved before that, no longer editable; removed in 2.0.
+     */
     accentColor: string;
+    /**
+     * @deprecated A store's colors and font are its theme's settings: declare
+     * them in `defineTheme({ settings })` and read `themeSettings`. This is the
+     * value saved before that, no longer editable; removed in 2.0.
+     */
     bgColor: string;
+    /**
+     * @deprecated A store's colors and font are its theme's settings: declare
+     * them in `defineTheme({ settings })` and read `themeSettings`. This is the
+     * value saved before that, no longer editable; removed in 2.0.
+     */
     fontFamily: string;
+    /** @deprecated Always null; removed in 2.0. */
     fontUrl: string | null;
     /** The store's primary language: a BCP 47 code such as `ar`. */
     lang: string;
@@ -85,11 +106,24 @@ export interface StoreConfig {
      * language — never another language's map.
      */
     contentOverrides: Record<string, Record<string, string>>;
+    /**
+     * The merchant's values for this theme's settings, by setting key, exactly
+     * as saved — `{}` when there are none or the client was created without
+     * `theme`, absent from a server that predates theme settings. Read them
+     * against the theme's declaration with `resolveThemeSettings` from
+     * `@wocart/theme` (which takes either): a value the theme no longer accepts
+     * falls back to its default there.
+     */
+    themeSettings?: Record<string, unknown> | undefined;
     currency: string;
     currencySymbol: string;
     metaTitle: string | null;
     metaDescription: string | null;
     ogImage: string | null;
+    /**
+     * @deprecated Always null. An announcement is a theme's own content: declare
+     * it as a theme setting and read `themeSettings`. Removed in 2.0.
+     */
     announcementBar: string | null;
     reviewsEnabled: boolean;
     /** When true the storefront renders the cart alongside the direct order form. */
@@ -178,6 +212,25 @@ export interface StorePagePublic {
     metaTitle: string | null;
     metaDescription: string | null;
 }
+/** A navigation menu — GET /store/menus/{handle}. */
+export interface StoreMenu {
+    handle: string;
+    title: string;
+    /** Only items a shopper can follow, in the merchant's order; at most three levels. */
+    items: StoreMenuItem[];
+}
+export interface StoreMenuItem {
+    /** In the client's language when the store translated it, else the primary. */
+    label: string;
+    /**
+     * A path of the store without a language prefix (`/products/robe`) — pass
+     * it through `localizeHref` — or the absolute URL the merchant entered.
+     */
+    href: string;
+    /** The page type it opens (`home`, `catalog`, `category`, `product`, `page`, `landing`), or `url`. */
+    type: string;
+    children: StoreMenuItem[];
+}
 export interface ShippingRates {
     [wilayaId: string]: WilayaRates;
 }
@@ -466,6 +519,16 @@ export interface ReviewSubmitResult {
  */
 export interface ProductListFilters {
     categoryId?: string;
+    /**
+     * Only this collection's products, by handle (`best-sellers`), in the order
+     * the merchant gave them. A collection is a list the merchant curates in the
+     * dashboard; a theme names it through a `collection` theme setting. An
+     * unknown handle lists nothing.
+     */
+    collection?: string;
+    /** Only products priced below their compare-at price. */
+    onSale?: boolean;
+    /** @deprecated Use `collection: "featured"`. */
     featured?: boolean;
     /** Server-side cap; the server clamps anything larger. */
     limit?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/storefront",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",