@wocart/storefront 2.2.0 → 3.1.0

package/dist/routes.d.ts

@@ -1,19 +1,3 @@
-/**
- * The storefront's page types and their public paths.
- *
- * 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.
- *
- * Language prefixes are applied on top: `localizeHref(storefrontPath(…),
- * locale, routing)`.
- */
 import type { WidgetSurfaces } from "./types.js";
 /** Each page type's public path; `:handle` / `:slug` mark its one parameter. */
 export declare const STOREFRONT_PAGE_PATHS: {
@@ -28,6 +12,10 @@ export declare const STOREFRONT_PAGE_PATHS: {
     readonly thankYou: "/thank-you";
     /** Where a shopper follows an order by its number and phone; `?order=<number>` fills the number in. */
     readonly trackOrder: "/track-order";
+    /** The store's products matching a query; `?q=<words>` is the query. */
+    readonly search: "/search";
+    /** How to reach the store: its WhatsApp, phone, email and address. */
+    readonly contact: "/contact";
 };
 /** What a storefront URL means. */
 export type StorefrontPageType = keyof typeof STOREFRONT_PAGE_PATHS;
@@ -48,6 +36,39 @@ export interface StorefrontPageMatch {
  * not a path to render.
  */
 export declare function storefrontPath<T extends StorefrontPageType>(type: T, params?: StorefrontPathParams<T>): string;
+/**
+ * Where a theme mounts each of `createStorefrontRoutes`' routes
+ * (`src/pages/api/…`), and where its browser scripts call them: one table,
+ * keyed like `StorefrontRoutes`, so the route files and the scripts never
+ * drift. Defaults, not requirements: every browser helper still takes its
+ * `endpoint`. `:wilayaId` and `:productId` mark a route's one parameter.
+ * `orderStatus` has no path here: a theme follows an order through its
+ * `orderStatus` action, not a route.
+ */
+export declare const STOREFRONT_API_PATHS: {
+    readonly otpSend: "/api/otp/send";
+    readonly otpVerify: "/api/otp/verify";
+    readonly cartValidate: "/api/cart/validate";
+    readonly abandonedUpsert: "/api/abandoned/upsert";
+    readonly abandonedConvert: "/api/abandoned/convert";
+    readonly communes: "/api/communes/:wilayaId";
+    readonly reviewsList: "/api/reviews/:productId";
+    readonly reviewEligibility: "/api/reviews/eligibility";
+    readonly reviewUpload: "/api/reviews/upload";
+    readonly reviewSubmit: "/api/reviews/submit";
+};
+/** A storefront route of `createStorefrontRoutes`. */
+export type StorefrontApiName = keyof typeof STOREFRONT_API_PATHS;
+/** The parameter a route's path needs: `{ wilayaId }` for the communes, `{ productId }` for a product's reviews, nothing otherwise. */
+export type StorefrontApiParams<N extends StorefrontApiName> = ParamOf<(typeof STOREFRONT_API_PATHS)[N]> extends never ? Record<string, never> : {
+    [K in ParamOf<(typeof STOREFRONT_API_PATHS)[N]>]: string | number;
+};
+/**
+ * A storefront route's same-origin path, its parameter encoded:
+ * `storefrontApiPath("communes", { wilayaId: 16 })` → `/api/communes/16`.
+ * Throws when the parameter is missing.
+ */
+export declare function storefrontApiPath<N extends StorefrontApiName>(name: N, params?: StorefrontApiParams<N>): string;
 /**
  * Which page type a pathname is, and its parameter (decoded) — or null for
  * any other path. Exact matches only: `/products/` is the catalog,
@@ -56,19 +77,15 @@ export declare function storefrontPath<T extends StorefrontPageType>(type: T, pa
  * 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;
-    /** The `surfaces` key this route belongs to. */
-    readonly surface: keyof WidgetSurfaces;
-}
 /**
- * @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.
+ * The page types that exist in the store's primary language only. A landing
+ * page is one campaign — a stack of images and one order form, written once
+ * for the ads that point at it — so it has no `/fr/lp/…` address, no language
+ * menu and no alternate links.
  */
-export declare const STOREFRONT_ROUTES: readonly StorefrontRoute[];
+export declare const SINGLE_LANGUAGE_PAGE_TYPES: readonly StorefrontPageType[];
+/** Whether a pathname (without its language prefix) is a page that exists in the primary language only. */
+export declare function isSingleLanguagePage(rawPathname: string): boolean;
 /**
  * Whether the widget belongs on a pathname: the merchant answers "which
  * surfaces" (`surfaces[surface]`); this answers which surface a pathname *is*,

package/dist/routes.js

@@ -11,6 +11,10 @@ export const STOREFRONT_PAGE_PATHS = {
     thankYou: "/thank-you",
     /** Where a shopper follows an order by its number and phone; `?order=<number>` fills the number in. */
     trackOrder: "/track-order",
+    /** The store's products matching a query; `?q=<words>` is the query. */
+    search: "/search",
+    /** How to reach the store: its WhatsApp, phone, email and address. */
+    contact: "/contact",
 };
 /**
  * The public path of a page type, its parameter encoded:
@@ -19,13 +23,45 @@ export const STOREFRONT_PAGE_PATHS = {
  * not a path to render.
  */
 export function storefrontPath(type, params) {
-    return STOREFRONT_PAGE_PATHS[type].replace(/:([a-z]+)/g, (_, name) => {
+    return fillPath(STOREFRONT_PAGE_PATHS[type], `storefrontPath("${type}")`, params);
+}
+function fillPath(template, caller, params) {
+    return template.replace(/:([a-zA-Z]+)/g, (_, name) => {
         const value = params?.[name];
-        if (!value)
-            throw new Error(`storefrontPath("${type}") needs "${name}"`);
-        return encodeURIComponent(value);
+        if (value === undefined || value === "")
+            throw new Error(`${caller} needs "${name}"`);
+        return encodeURIComponent(String(value));
     });
 }
+/**
+ * Where a theme mounts each of `createStorefrontRoutes`' routes
+ * (`src/pages/api/…`), and where its browser scripts call them: one table,
+ * keyed like `StorefrontRoutes`, so the route files and the scripts never
+ * drift. Defaults, not requirements: every browser helper still takes its
+ * `endpoint`. `:wilayaId` and `:productId` mark a route's one parameter.
+ * `orderStatus` has no path here: a theme follows an order through its
+ * `orderStatus` action, not a route.
+ */
+export const STOREFRONT_API_PATHS = {
+    otpSend: "/api/otp/send",
+    otpVerify: "/api/otp/verify",
+    cartValidate: "/api/cart/validate",
+    abandonedUpsert: "/api/abandoned/upsert",
+    abandonedConvert: "/api/abandoned/convert",
+    communes: "/api/communes/:wilayaId",
+    reviewsList: "/api/reviews/:productId",
+    reviewEligibility: "/api/reviews/eligibility",
+    reviewUpload: "/api/reviews/upload",
+    reviewSubmit: "/api/reviews/submit",
+};
+/**
+ * A storefront route's same-origin path, its parameter encoded:
+ * `storefrontApiPath("communes", { wilayaId: 16 })` → `/api/communes/16`.
+ * Throws when the parameter is missing.
+ */
+export function storefrontApiPath(name, params) {
+    return fillPath(STOREFRONT_API_PATHS[name], `storefrontApiPath("${name}")`, params);
+}
 const MATCHERS = Object.entries(STOREFRONT_PAGE_PATHS).map(([type, path]) => {
     const names = [];
     const source = path.replace(/:([a-z]+)/g, (_, name) => {
@@ -56,6 +92,18 @@ export function matchStorefrontPath(rawPathname) {
     }
     return null;
 }
+/**
+ * The page types that exist in the store's primary language only. A landing
+ * page is one campaign — a stack of images and one order form, written once
+ * for the ads that point at it — so it has no `/fr/lp/…` address, no language
+ * menu and no alternate links.
+ */
+export const SINGLE_LANGUAGE_PAGE_TYPES = ["landing"];
+/** Whether a pathname (without its language prefix) is a page that exists in the primary language only. */
+export function isSingleLanguagePage(rawPathname) {
+    const match = matchStorefrontPath(rawPathname);
+    return match !== null && SINGLE_LANGUAGE_PAGE_TYPES.includes(match.type);
+}
 /** The WhatsApp widget surface each page type belongs to (the home surface is the root). */
 const WIDGET_SURFACE = {
     home: "home",
@@ -68,16 +116,9 @@ const WIDGET_SURFACE = {
     checkout: "checkout",
     thankYou: "thankYou",
     trackOrder: "pages",
+    search: "pages",
+    contact: "pages",
 };
-/**
- * @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 answers which surface a pathname *is*,