@wocart/storefront 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.9.0 — 2026-10-17
+
+### Added
+
+- Page type `collection` at `/collections/:handle`: a collection's page,
+  which a merchant's menu can now link to. `storefrontPath("collection", {
+  handle })` builds it, `matchStorefrontPath` recognises it, and the WhatsApp
+  widget counts it as the catalog surface.
+- `store.collections.get(handle)` → `StoreCollection` (handle, title,
+  description, in the client's language), `null` for an unknown handle, which
+  is not reported as a failure. `StoreCollectionSchema`.
+
+## 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

package/USAGE.md

@@ -105,6 +105,7 @@ break those links.
 | `home` | `/` | the home page | required |
 | `catalog` | `/products` | every product | required |
 | `category` | `/category/:slug` | one category's products | required when the store has categories |
+| `collection` | `/collections/:handle` | one collection's products, in the merchant's order | required — a menu can link to any collection |
 | `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 |
@@ -483,23 +484,25 @@ 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;
+- 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;
-- announcementBar and reviewsEnabled;
+- 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;
@@ -630,11 +633,33 @@ 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.
+- A collection has a page of its own (page type `collection`,
+  `/collections/:handle`) that a merchant's menu can link to. Name it with
+  `store.collections.get(handle)` — title and description in the client's
+  language, `null` for an unknown handle (answer a real 404) — and list it
+  with `products.list({ collection: handle })`.
+- `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

package/dist/client/collections.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Collections Namespace - the merchant's curated product lists
+ *
+ * A collection has a page of its own (`/collections/:handle`, page type
+ * `collection`): `get(handle)` names it — title and description in the
+ * client's language — and `products.list({ collection })` lists its products
+ * in the merchant's order.
+ *
+ * Failure contract: `get(handle)` → null means "no such collection" or a
+ * failed read — the page answers a real 404.
+ */
+import { type ClientCore } from "./core.js";
+import type { StoreCollection } from "../types.js";
+export interface CollectionsNamespace {
+    /** A collection by handle (`best-sellers`). Resolves to `null` for an unknown handle or a failed read. */
+    get(handle: string): Promise<StoreCollection | null>;
+}
+export declare function createCollectionsNamespace(core: ClientCore): CollectionsNamespace;

package/dist/client/collections.js

@@ -0,0 +1,29 @@
+/**
+ * Collections Namespace - the merchant's curated product lists
+ *
+ * A collection has a page of its own (`/collections/:handle`, page type
+ * `collection`): `get(handle)` names it — title and description in the
+ * client's language — and `products.list({ collection })` lists its products
+ * in the merchant's order.
+ *
+ * Failure contract: `get(handle)` → null means "no such collection" or a
+ * failed read — the page answers a real 404.
+ */
+import { StoreCollectionSchema } from "../schemas.js";
+import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { localizedPath } from "./paths.js";
+import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
+export function createCollectionsNamespace(core) {
+    return {
+        async get(handle) {
+            try {
+                return await core.get(localizedPath(core.config, `/store/collections/${encodeURIComponent(handle)}`), StoreCollectionSchema, { operation: STOREFRONT_OPERATIONS.collectionsGet });
+            }
+            catch (error) {
+                if (!isNotFoundAnswer(error))
+                    reportDegradedRead(core.config, error, "collections.get");
+                return null;
+            }
+        },
+    };
+}

package/dist/client/index.d.ts

@@ -2,7 +2,8 @@
  * 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, menus, shipping, geo, cart,
+ * shared core: config, products, categories, collections, 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
@@ -32,6 +33,7 @@ export declare function createStoreClient(config: StoreScope): {
     categories: import("./categories.js").CategoriesNamespace;
     pages: import("./pages.js").PagesNamespace;
     menus: import("./menus.js").MenusNamespace;
+    collections: import("./collections.js").CollectionsNamespace;
     pageData: import("./page-data.js").PageDataNamespace;
     shipping: import("./shipping.js").ShippingNamespace;
     geo: import("./geo.js").GeoNamespace;

package/dist/client/index.js

@@ -2,7 +2,8 @@
  * 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, menus, shipping, geo, cart,
+ * shared core: config, products, categories, collections, 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
@@ -32,6 +33,7 @@ import { createProductsNamespace } from "./products.js";
 import { createCategoriesNamespace } from "./categories.js";
 import { createPagesNamespace } from "./pages.js";
 import { createMenusNamespace } from "./menus.js";
+import { createCollectionsNamespace } from "./collections.js";
 import { createPageDataNamespace } from "./page-data.js";
 import { createShippingNamespace } from "./shipping.js";
 import { createGeoNamespace } from "./geo.js";
@@ -46,6 +48,7 @@ export function createStoreClient(config) {
         categories: createCategoriesNamespace(core),
         pages: createPagesNamespace(core),
         menus: createMenusNamespace(core),
+        collections: createCollectionsNamespace(core),
         pageData: createPageDataNamespace(core),
         shipping: createShippingNamespace(core),
         geo: createGeoNamespace(core),

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

@@ -354,6 +354,7 @@ export declare const STOREFRONT_OPERATIONS: {
     readonly pagesGet: "pages.get";
     readonly pagesLanding: "pages.landing";
     readonly menusGet: "menus.get";
+    readonly collectionsGet: "collections.get";
     readonly shippingRates: "shipping.rates";
     readonly shippingRate: "shipping.rate";
     readonly geoCommunes: "geo.communes";
@@ -392,6 +393,7 @@ export declare const STOREFRONT_RETRY_POLICIES: {
     readonly "pages.get": "safe-read";
     readonly "pages.landing": "safe-read";
     readonly "menus.get": "safe-read";
+    readonly "collections.get": "safe-read";
     readonly "products.get": "safe-read";
     readonly "products.list": "safe-read";
     readonly "products.reviews.list": "safe-read";

package/dist/domain.js

@@ -207,6 +207,7 @@ export const STOREFRONT_OPERATIONS = {
     pagesGet: "pages.get",
     pagesLanding: "pages.landing",
     menusGet: "menus.get",
+    collectionsGet: "collections.get",
     shippingRates: "shipping.rates",
     shippingRate: "shipping.rate",
     geoCommunes: "geo.communes",
@@ -244,6 +245,7 @@ export const STOREFRONT_RETRY_POLICIES = {
     [STOREFRONT_OPERATIONS.pagesGet]: "safe-read",
     [STOREFRONT_OPERATIONS.pagesLanding]: "safe-read",
     [STOREFRONT_OPERATIONS.menusGet]: "safe-read",
+    [STOREFRONT_OPERATIONS.collectionsGet]: "safe-read",
     [STOREFRONT_OPERATIONS.productsGet]: "safe-read",
     [STOREFRONT_OPERATIONS.productsList]: "safe-read",
     [STOREFRONT_OPERATIONS.productsReviewsList]: "safe-read",

package/dist/routes.d.ts

@@ -20,6 +20,7 @@ export declare const STOREFRONT_PAGE_PATHS: {
     readonly home: "/";
     readonly catalog: "/products";
     readonly category: "/category/:slug";
+    readonly collection: "/collections/:handle";
     readonly product: "/products/:handle";
     readonly page: "/pages/:slug";
     readonly landing: "/lp/:slug";

package/dist/routes.js

@@ -3,6 +3,7 @@ export const STOREFRONT_PAGE_PATHS = {
     home: "/",
     catalog: "/products",
     category: "/category/:slug",
+    collection: "/collections/:handle",
     product: "/products/:handle",
     page: "/pages/:slug",
     landing: "/lp/:slug",
@@ -58,6 +59,7 @@ const WIDGET_SURFACE = {
     home: "home",
     catalog: "catalog",
     category: "catalog",
+    collection: "catalog",
     product: "product",
     page: "pages",
     landing: "landing",

package/dist/schemas.d.ts

@@ -246,6 +246,12 @@ interface StoreMenuItemShape {
     type: string;
     children: StoreMenuItemShape[];
 }
+/** A collection's page — GET /store/collections/{handle}. Its products come from `products.list({ collection })`. */
+export declare const StoreCollectionSchema: z.ZodObject<{
+    handle: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
 export declare const StoreMenuSchema: z.ZodObject<{
     handle: z.ZodString;
     title: z.ZodString;

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
@@ -144,6 +145,12 @@ export const StoreMenuItemSchema = z.lazy(() => z.object({
     type: z.string(),
     children: z.array(StoreMenuItemSchema),
 }));
+/** A collection's page — GET /store/collections/{handle}. Its products come from `products.list({ collection })`. */
+export const StoreCollectionSchema = z.object({
+    handle: z.string(),
+    title: z.string(),
+    description: z.string().nullable(),
+});
 export const StoreMenuSchema = z.object({
     handle: z.string(),
     title: z.string(),

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;
@@ -99,6 +120,10 @@ export interface StoreConfig {
     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. */
@@ -187,6 +212,13 @@ export interface StorePagePublic {
     metaTitle: string | null;
     metaDescription: string | null;
 }
+/** A collection as its page names it — GET /store/collections/{handle}. */
+export interface StoreCollection {
+    handle: string;
+    /** In the client's language when the store translated it, else the primary. */
+    title: string;
+    description: string | null;
+}
 /** A navigation menu — GET /store/menus/{handle}. */
 export interface StoreMenu {
     handle: string;
@@ -494,6 +526,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.7.0",
+  "version": "1.9.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",