@wocart/storefront 1.5.0 → 1.7.0

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

@@ -89,7 +89,7 @@ export declare const ProductListSchema: z.ZodObject<{
     }>;
     showInStore: z.ZodBoolean;
     storeFeatured: z.ZodBoolean;
-    deletedAt: z.ZodNullable<z.ZodString>;
+    deletedAt: z.ZodOptional<z.ZodNull>;
     publishedAt: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
@@ -142,7 +142,7 @@ export declare const ProductSchema: z.ZodObject<{
     }>;
     showInStore: z.ZodBoolean;
     storeFeatured: z.ZodBoolean;
-    deletedAt: z.ZodNullable<z.ZodString>;
+    deletedAt: z.ZodOptional<z.ZodNull>;
     publishedAt: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
@@ -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>;
@@ -546,7 +564,7 @@ export declare const LandingPageSchema: z.ZodObject<{
         }>;
         showInStore: z.ZodBoolean;
         storeFeatured: z.ZodBoolean;
-        deletedAt: z.ZodNullable<z.ZodString>;
+        deletedAt: z.ZodOptional<z.ZodNull>;
         publishedAt: z.ZodNullable<z.ZodString>;
         createdAt: z.ZodString;
         updatedAt: z.ZodString;
@@ -740,6 +758,18 @@ export declare const OtpVerifyResultSchema: z.ZodObject<{
     status: z.ZodLiteral<"verified">;
     otpToken: z.ZodString;
 }, z.core.$strip>;
+export declare const ReviewMediaSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        audio: "audio";
+        image: "image";
+    }>;
+    url: z.ZodString;
+    thumbUrl: z.ZodNullable<z.ZodString>;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
 export declare const ReviewSchema: z.ZodPreprocess<z.ZodObject<{
     id: z.ZodString;
     customerName: z.ZodString;
@@ -747,7 +777,51 @@ export declare const ReviewSchema: z.ZodPreprocess<z.ZodObject<{
     title: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
     body: z.ZodString;
     createdAt: z.ZodString;
+    verified: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    media: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            audio: "audio";
+            image: "image";
+        }>;
+        url: z.ZodString;
+        thumbUrl: z.ZodNullable<z.ZodString>;
+        width: z.ZodNullable<z.ZodNumber>;
+        height: z.ZodNullable<z.ZodNumber>;
+        durationMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>>>;
 }, z.core.$strip>, unknown>;
+export declare const ReviewEligibilitySchema: z.ZodObject<{
+    orderNumber: z.ZodString;
+    customerName: z.ZodString;
+    products: z.ZodArray<z.ZodObject<{
+        productId: z.ZodString;
+        name: z.ZodString;
+        imageSrc: z.ZodNullable<z.ZodString>;
+        reviewed: z.ZodBoolean;
+    }, z.core.$strip>>;
+    media: z.ZodNullable<z.ZodObject<{
+        maxPhotos: z.ZodNumber;
+        voiceMaxSeconds: z.ZodNullable<z.ZodNumber>;
+        grant: z.ZodString;
+        expiresAt: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ReviewUploadSchema: z.ZodObject<{
+    uploadId: z.ZodString;
+    kind: z.ZodEnum<{
+        audio: "audio";
+        image: "image";
+    }>;
+    bytes: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ReviewSubmitResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        after_review: "after_review";
+        published: "published";
+    }>>;
+}, z.core.$strip>;
 /**
  * GET /store/reviews answers `{ success, data: rows, count, total }` — the
  * total lives OUTSIDE `data`, so a caller that reads only `data` loses it.
@@ -760,6 +834,20 @@ export declare const ReviewListEnvelopeSchema: z.ZodObject<{
         title: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
         body: z.ZodString;
         createdAt: z.ZodString;
+        verified: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        media: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                audio: "audio";
+                image: "image";
+            }>;
+            url: z.ZodString;
+            thumbUrl: z.ZodNullable<z.ZodString>;
+            width: z.ZodNullable<z.ZodNumber>;
+            height: z.ZodNullable<z.ZodNumber>;
+            durationMs: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>>>;
     }, z.core.$strip>, unknown>>;
     total: z.ZodNumber;
 }, z.core.$strip>;
+export {};

package/dist/schemas.js

@@ -83,7 +83,12 @@ const productBaseFields = {
     status: z.enum(["DRAFT", "ACTIVE", "ARCHIVED"]),
     showInStore: z.boolean(),
     storeFeatured: z.boolean(),
-    deletedAt: z.string().datetime().nullable(),
+    /**
+     * @deprecated Always null: the server never serves a removed product. The
+     * server still sends it for older releases; it will stop, and a later major
+     * drops it. Do not read it.
+     */
+    deletedAt: z.null().optional(),
     publishedAt: z.string().datetime().nullable(),
     createdAt: z.string().datetime(),
     updatedAt: z.string().datetime(),
@@ -128,6 +133,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
@@ -220,6 +241,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(),
@@ -359,6 +385,15 @@ export const OtpVerifyResultSchema = z.object({
     status: z.literal("verified"),
     otpToken: z.string(),
 });
+export const ReviewMediaSchema = z.object({
+    id: z.string(),
+    kind: z.enum(["image", "audio"]),
+    url: z.string(),
+    thumbUrl: z.string().nullable(),
+    width: z.number().int().nullable(),
+    height: z.number().int().nullable(),
+    durationMs: z.number().int().nullable(),
+});
 export const ReviewSchema = z.preprocess((raw) => {
     if (typeof raw === "object" && raw !== null) {
         const obj = raw;
@@ -375,7 +410,36 @@ export const ReviewSchema = z.preprocess((raw) => {
     title: z.string().nullable().optional().default(null),
     body: z.string(),
     createdAt: z.string(),
+    verified: z.boolean().optional().default(false),
+    media: z.array(ReviewMediaSchema).optional().default([]),
 }));
+export const ReviewEligibilitySchema = z.object({
+    orderNumber: z.string(),
+    customerName: z.string(),
+    products: z.array(z.object({
+        productId: z.string(),
+        name: z.string(),
+        imageSrc: z.string().nullable(),
+        reviewed: z.boolean(),
+    })),
+    media: z
+        .object({
+        maxPhotos: z.number().int().min(0),
+        voiceMaxSeconds: z.number().int().positive().nullable(),
+        grant: z.string().min(1),
+        expiresAt: z.number().int(),
+    })
+        .nullable(),
+});
+export const ReviewUploadSchema = z.object({
+    uploadId: z.string(),
+    kind: z.enum(["image", "audio"]),
+    bytes: z.number().int(),
+});
+export const ReviewSubmitResultSchema = z.object({
+    id: z.string(),
+    visibility: z.enum(["published", "after_review"]).optional(),
+});
 /**
  * GET /store/reviews answers `{ success, data: rows, count, total }` — the
  * total lives OUTSIDE `data`, so a caller that reads only `data` loses it.

package/dist/types.d.ts

@@ -85,6 +85,15 @@ 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;
@@ -178,6 +187,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;
 }
@@ -395,6 +423,19 @@ export type OtpVerifyResult = {
     /** Signed, 15-min TTL, bound to the phone. Travels with the order. */
     otpToken: string;
 };
+/** A photo or the voice note of a review. */
+export interface ReviewMedia {
+    id: string;
+    kind: "image" | "audio";
+    /** A photo at 1600 px at most, or the voice note as recorded. */
+    url: string;
+    /** A photo's 480 px version for lists; null for a voice note. */
+    thumbUrl: string | null;
+    width: number | null;
+    height: number | null;
+    /** A voice note's length, when known. */
+    durationMs: number | null;
+}
 export interface Review {
     id: string;
     customerName: string;
@@ -402,6 +443,50 @@ export interface Review {
     title: string | null;
     body: string;
     createdAt: string;
+    /** Rests on an order that reached its customer: show it as a verified purchase. */
+    verified: boolean;
+    /** Photos first, then the voice note. Empty from servers before 1.6. */
+    media: ReviewMedia[];
+}
+/** One product of the shopper's order, as `products.reviews.eligibility()` answers it. */
+export interface ReviewableProduct {
+    productId: string;
+    name: string;
+    imageSrc: string | null;
+    /** Already reviewed from this order: show it, but it cannot be reviewed again. */
+    reviewed: boolean;
+}
+/**
+ * What a shopper's order lets them review, once its number and phone proved
+ * the purchase — and, when the store takes them, what they may attach.
+ */
+export interface ReviewEligibility {
+    orderNumber: string;
+    customerName: string;
+    products: ReviewableProduct[];
+    /** null: text only. */
+    media: {
+        /** 0: no photos. */
+        maxPhotos: number;
+        /** null: no voice note. */
+        voiceMaxSeconds: number | null;
+        /** Send with each upload and with the review. Lasts until `expiresAt`. */
+        grant: string;
+        /** Unix seconds. */
+        expiresAt: number;
+    } | null;
+}
+/** A photo or voice note the server received for a review not yet submitted. */
+export interface ReviewUpload {
+    uploadId: string;
+    kind: "image" | "audio";
+    bytes: number;
+}
+/** What a submitted review answers: published now, or after the store checks it. */
+export interface ReviewSubmitResult {
+    id: string;
+    /** Absent from servers before 1.6. */
+    visibility?: "published" | "after_review" | undefined;
 }
 /**
  * Filters `products.list()` accepts — named so a theme can type its own
@@ -427,15 +512,42 @@ export interface ReviewListPagination {
     offset?: number;
 }
 /**
- * The body `products.reviews.submit()` accepts: the order number is the proof
- * of purchase, and the server owns every other rule (moderation, one-review
- * per order line).
+ * The body `products.reviews.submit()` accepts: the order number and the phone
+ * it was placed with prove the purchase, and the server owns every other rule
+ * (a delivered order, one review per product of it, moderation).
  */
 export interface ReviewInput {
     orderNumber: string;
+    /**
+     * The phone the order was placed with. Without it (the 1.5 shape) a review
+     * is text only and still needs a delivered order.
+     * @deprecated Omitting it is deprecated; a later major requires it.
+     */
+    phone?: string;
     productId: string;
     /** 1–5, the server validates the range. */
     rating: number;
     title?: string;
+    /** At least 10 characters, unless a voice note is attached. */
     body: string;
+    /** The grant from `eligibility()`, when files are attached. */
+    grant?: string;
+    /** `uploadId`s from `upload()`. */
+    uploads?: string[];
+}
+/** What `products.reviews.eligibility()` sends. */
+export interface ReviewEligibilityInput {
+    orderNumber: string;
+    phone: string;
+    /** Required when the store has Turnstile on. */
+    turnstileToken?: string;
+}
+/** What `products.reviews.upload()` sends: one file, as it is. */
+export interface ReviewUploadInput {
+    grant: string;
+    body: Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>;
+    /** Its size, when known: lets the server refuse a file too large before it arrives. */
+    contentLength?: number;
+    /** A voice note's length as the recorder reported it. */
+    durationMs?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/storefront",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",
@@ -41,6 +41,10 @@
       "types": "./dist/astro.d.ts",
       "default": "./dist/astro.js"
     },
+    "./review-media": {
+      "types": "./dist/review-media.d.ts",
+      "default": "./dist/review-media.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [