@wocart/storefront 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -5,6 +5,77 @@ 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.
 
+## 3.1.0 — 2026-11-03
+
+The theme's request lifecycle, revalidation route, API paths and thank-you
+address come from the SDK, and a landing page is single-language. Additions
+and fixes only; requires platform v7.0.0, like 3.0.0.
+
+### Added
+
+- `createStorefrontMiddleware(options)` in `@wocart/storefront/astro`: the
+  theme's whole `onRequest` in one call. A prerendered file and the
+  revalidation route pass through; a request that already has a store keeps
+  it; the editor's preview opens only for a verified token and never runs an
+  action; any other page gets its store and language, its redirect, its
+  form-called action and its unprefixed route. The preview key may be a
+  function, read on each request (a secret from `astro:env/server` can be
+  set after the module loads). Types `PreviewLocals`,
+  `StorefrontMiddleware`, `StorefrontMiddlewareContext`,
+  `StorefrontMiddlewareOptions`, `StorefrontActionContext`.
+- `revalidateEndpoint({ publicKey, theme })` in `@wocart/storefront/astro`:
+  the theme's `/wocart-revalidate` route, `{ POST, ALL }`. `POST` drops every
+  page cached under `PAGES_CACHE_TAG` for a verified platform token (204) and
+  nothing otherwise; `ALL` answers 405. Types `RevalidateEndpointContext`,
+  `RevalidateEndpointOptions`.
+- `STOREFRONT_API_PATHS` and `storefrontApiPath(name, params?)`: where a
+  theme mounts each of `createStorefrontRoutes`' routes and where its browser
+  scripts call them (`/api/communes/:wilayaId`, …), keyed like
+  `StorefrontRoutes` and checked against it. Defaults, not requirements:
+  every browser helper still takes its `endpoint`. Types `StorefrontApiName`,
+  `StorefrontApiParams`.
+- `PAGES_CACHE_TAG` (`"pages"`) in `@wocart/storefront/server`: the cache
+  tag every cached page carries and a revalidation drops, spelled once.
+- `thankYouHref(order, language?)` and `readThankYou(url)`: the thank-you
+  page's address for a placed order (`/thank-you?order=…&total=…&oid=…`, in
+  the request's language when given) and its reading back, so no theme spells
+  the query itself and an editor can preview the page with a sample order.
+  Type `ThankYouOrder`.
+- `SINGLE_LANGUAGE_PAGE_TYPES` (`["landing"]`) and
+  `isSingleLanguagePage(pathname)`: the pages that exist in the store's
+  primary language only.
+
+### Fixed
+
+- A page's `notFound()` kept the shopper's language only in themes that
+  remembered to keep the store on the rewrite to `/404`;
+  `createStorefrontMiddleware` always keeps it.
+- A landing page is single-language: `resolveLocalePath` and
+  `resolveStoreRequest` send `/fr/lp/x?…` to `/lp/x?…` (301, the query kept,
+  the other language never read); `localizeHref` leaves a landing link
+  unprefixed; `alternateLinks` lists no alternates for it; an endpoint a
+  landing page asks for answers in the primary language.
+
+### Theme migration
+
+- Replace the body of `src/middleware.ts` with `createStorefrontMiddleware`,
+  passing the client factory, the fallback config, the preview route and key
+  (`THEME_PREVIEW_PATH`, `() => WOCART_PREVIEW_KEY`, the theme's key), the
+  context builder and `getActionContext`. Delete any check of
+  `locals.store` on a rewrite and any landing-page language redirect of the
+  theme's own.
+- `src/pages/wocart-revalidate.ts` becomes
+  `export const { POST, ALL } = revalidateEndpoint({ publicKey: () => WOCART_PREVIEW_KEY, theme: THEME_KEY })`;
+  tag cached routes with `PAGES_CACHE_TAG` rather than the literal.
+- A theme's own table of `/api/…` paths becomes `STOREFRONT_API_PATHS`;
+  a route with a parameter is called through `storefrontApiPath`.
+- Replace a theme's own thank-you query helpers with `thankYouHref` and
+  `readThankYou`; the query keeps its names (`order`, `total`, `oid`), so
+  links already sent keep working. A total that is not a whole number reads
+  as `null`.
+- A language menu built from `localizeHref` should list no languages on a
+  page where `isSingleLanguagePage(pathname)` is true.
+
 ## 3.0.0 — 2026-11-01
 
 The SDK reads exactly what platform v7.0.0 serves: `/store/config` and the

package/USAGE.md

@@ -632,7 +632,14 @@ alternateLinks(path.pathname, routing, url.origin);       // [{ hreflang: "ar",
 ~~~
 
 `localizeHref` leaves external URLs, fragments, endpoints, files and already
-prefixed links alone, so it is safe on any `href`. Never redirect a shopper by
+prefixed links alone, so it is safe on any `href`.
+
+A landing page (`/lp/:slug`) exists in the primary language only:
+`SINGLE_LANGUAGE_PAGE_TYPES` names its page type and
+`isSingleLanguagePage(pathname)` tells such a page from any other.
+`resolveLocalePath` sends `/fr/lp/x` to `/lp/x`, `localizeHref` leaves a
+landing link unprefixed, and `alternateLinks` lists nothing for it; a
+language menu should list no languages there either. Never redirect a shopper by
 browser language: offer the other languages as links and let them choose.
 `products.list({ limit, offset })` pages through the whole catalog, for a
 sitemap.
@@ -1678,11 +1685,68 @@ The page reads the result with `Astro.getActionResult()`: on success it
 redirects to the thank-you page, and on a refusal it renders the form again
 with the error in place.
 
+The thank-you address is the SDK's: `thankYouHref(order, { locale, routing })`
+builds `/fr/thank-you?order=…&total=…&oid=…` from the placed order (its
+number, total and id, never the shopper's details), and the thank-you page
+reads it back with `readThankYou(Astro.url)`: `{ orderNumber, orderId, total }`,
+each empty or null when the address lacks it. An editor previews the page
+with a sample order by building the same address.
+
+~~~ts
+import { readThankYou, thankYouHref } from "@wocart/storefront";
+
+if (result?.data?.orderNumber) return Astro.redirect(thankYouHref(result.data, { locale, routing }));
+const { orderNumber, total } = readThankYou(Astro.url);   // on /thank-you
+~~~
+
 Never redirect from the middleware, on success or on error. Astro 7 keeps an
 action result for the response being rendered only, so a redirect arrives at
 the next page with no result: the thank-you redirect never fires, and a
 refused order shows no message.
 
+### The whole middleware in one call
+
+`createStorefrontMiddleware` is a theme's whole `onRequest`: the store and
+language of every request, its redirects, the editor's preview and the
+form-called action, in the order below.
+
+~~~ts
+// src/middleware.ts
+import { getActionContext } from "astro:actions";
+import { createStorefrontMiddleware } from "@wocart/storefront/astro";
+import { unavailableStoreConfig } from "@wocart/storefront";
+import { THEME_PREVIEW_PATH } from "@wocart/theme";
+
+export const onRequest = createStorefrontMiddleware({
+  client: createStore,
+  fallback: unavailableStoreConfig({ serverUrl, locale: "ar" }),
+  preview: { path: THEME_PREVIEW_PATH, publicKey: () => WOCART_PREVIEW_KEY, theme: THEME_KEY },
+  context: (store) => buildContext(store),
+  getActionContext,
+});
+~~~
+
+1. A prerendered file and the revalidation route (`REVALIDATE_PATH`) pass
+   through with no store.
+2. A request that already has a store keeps it: `notFound()` rewrites to
+   `/404`, Astro runs the middleware again, and the 404 stays in the
+   shopper's language.
+3. The preview route reads the draft with `readPreviewRequest`; a refused
+   token answers its status with `Cache-Control: no-store`. A verified one
+   sets `locals.store` from `resolvePreviewStore` and `locals.preview` to
+   `{ claims, draft, token }`, and never runs an action.
+4. Any other request resolves its store with `resolveStoreRequest`, answers
+   its redirect, sets `locals.store` to the theme's `context(store)`, runs a
+   form-called action with `runFormAction`, then renders the unprefixed
+   route.
+
+Pass the preview key as a function: a secret from `astro:env/server` can be
+set after the module loads, and the function reads it on each request.
+`astro:actions` exists only inside an Astro project, so the theme passes
+`getActionContext` in. A theme that needs a step of its own composes this
+handler with Astro's `sequence()`. The sections below are the parts it
+calls, for a theme that wires them itself.
+
 ### The request's store and language
 
 `resolveStoreRequest` decides which store a request renders and in which
@@ -1691,7 +1755,9 @@ from its path (`/fr/products/robe`); the primary's own prefix redirects for
 good to its one address, and a language the store stopped publishing
 redirects for now to the primary page; an endpoint (`/api/…`) or a server
 island takes the language of the page that asked, from its same-origin
-`Referer`, and is never redirected or rewritten. It answers data — the
+`Referer`, and is never redirected or rewritten; a landing page asked for
+under a language prefix redirects for good to its unprefixed address, the
+query kept. It answers data — the
 request's client, config, language, routing and unprefixed path — and the
 theme builds its own context from it:
 
@@ -1784,6 +1850,21 @@ export const POST = routes.otpSend;
 | `reviewSubmit` | POST | `ReviewInput` | 201 `{ success: true, data: { id, visibility } }` |
 | `orderStatus` | POST | `{ orderNumber, phone }` | `{ data: ShopperOrderStatus }` |
 
+Mount each route at its path in `STOREFRONT_API_PATHS` (`src/pages/api/otp/send.ts`
+for `otpSend`, `src/pages/api/communes/[wilayaId].ts` for
+`/api/communes/:wilayaId`), and call it from the browser through the same
+table, so the files and the scripts never drift:
+
+~~~ts
+import { STOREFRONT_API_PATHS, createQuoter, storefrontApiPath } from "@wocart/storefront";
+
+const quoter = createQuoter({ endpoint: STOREFRONT_API_PATHS.cartValidate });
+const communes = await fetch(storefrontApiPath("communes", { wilayaId: 16 }));   // /api/communes/16
+~~~
+
+`orderStatus` has no path there: a theme follows an order with the
+`orderStatus` action.
+
 What every route gets right:
 
 - every POST and PUT refuses a cross-origin request with 403;
@@ -2034,22 +2115,22 @@ editor — is `@wocart/theme`'s (its README, "Preview").
 ## Showing a publish at once (revalidation)
 
 A theme that caches its pages (route rules with `maxAge` and `tags`) shows a
-merchant's publish when the cache expires. To show it at once, the theme
-answers the platform's revalidation request and drops its pages:
+merchant's publish when the cache expires. To show it at once, every cached
+route carries `PAGES_CACHE_TAG` (`"pages"`, from `@wocart/storefront/server`)
+and the theme exports the SDK's revalidation route, which drops them:
 
 ```ts
 // src/pages/wocart-revalidate.ts — REVALIDATE_PATH
-import type { APIRoute } from "astro";
-import { readRevalidateRequest } from "@wocart/storefront/server";
+import { revalidateEndpoint } from "@wocart/storefront/astro";
 export const prerender = false;
-export const POST: APIRoute = async (context) => {
-  const revalidation = await readRevalidateRequest(context.request, { publicKey: WOCART_PREVIEW_KEY, theme: THEME_KEY });
-  if (!revalidation.ok) return new Response(null, { status: revalidation.status });
-  await context.cache.invalidate({ tags: ["pages"] }); // the tag every cached page carries
-  return new Response(null, { status: 204 });
-};
+export const { POST, ALL } = revalidateEndpoint({ publicKey: () => WOCART_PREVIEW_KEY, theme: THEME_KEY });
 ```
 
+`POST` answers 204 after `cache.invalidate({ tags: [PAGES_CACHE_TAG] })` for
+a verified token, and the token's refusal status otherwise, dropping
+nothing; `ALL` answers any other method 405. No answer is cached. A theme
+that wires it itself reads the request with `readRevalidateRequest`.
+
 The request is a `POST` from the platform's server with
 `Authorization: Bearer <token>`: signed with the same key as previews, but
 made only for revalidation (`use: "revalidate"`), for this storefront's

package/dist/astro.d.ts

@@ -10,3 +10,7 @@ export { lookupOrder, orderLookupInput } from "./order-lookup.js";
 export type { OrderLookup, OrderLookupInput } from "./order-lookup.js";
 export { notFound, resolvePreviewStore, resolveStoreRequest } from "./store-request.js";
 export type { NotFoundContext, ResolvedStore, StoreRequestOptions, StoreRequestResolution } from "./store-request.js";
+export { createStorefrontMiddleware } from "./storefront-middleware.js";
+export type { PreviewLocals, StorefrontActionContext, StorefrontMiddleware, StorefrontMiddlewareContext, StorefrontMiddlewareOptions, } from "./storefront-middleware.js";
+export { revalidateEndpoint } from "./endpoints/revalidate-endpoint.js";
+export type { RevalidateEndpointContext, RevalidateEndpointOptions } from "./endpoints/revalidate-endpoint.js";

package/dist/astro.js

@@ -4,3 +4,5 @@ export { placeOrderInput, executePlaceOrder, collectForwardedHeaders, } from "./
 export { runFormAction } from "./middleware.js";
 export { lookupOrder, orderLookupInput } from "./order-lookup.js";
 export { notFound, resolvePreviewStore, resolveStoreRequest } from "./store-request.js";
+export { createStorefrontMiddleware } from "./storefront-middleware.js";
+export { revalidateEndpoint } from "./endpoints/revalidate-endpoint.js";

package/dist/endpoints/revalidate-endpoint.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The revalidation route a theme exports, ready-made:
+ *
+ * ```ts
+ * // src/pages/wocart-revalidate.ts
+ * import { revalidateEndpoint } from "@wocart/storefront/astro";
+ *
+ * export const prerender = false;
+ * export const { POST, ALL } = revalidateEndpoint({ publicKey: () => WOCART_PREVIEW_KEY, theme: THEME_KEY });
+ * ```
+ *
+ * `POST` verifies the platform's token (`readRevalidateRequest`), drops every
+ * page cached under `PAGES_CACHE_TAG` and answers 204; a refused token
+ * answers its status and drops nothing. `ALL` answers any other method 405.
+ * Neither answer is ever cached.
+ */
+import { type RevalidateRequestOptions } from "../revalidate.js";
+/** What the route uses of Astro's `APIContext`. */
+export interface RevalidateEndpointContext {
+    request: Request;
+    cache: {
+        invalidate(options: {
+            tags: string[];
+        }): Promise<void>;
+    };
+}
+export interface RevalidateEndpointOptions {
+    /** The deployment's preview public key; a function reads it on each request. Absent: every request answers 404. */
+    publicKey: RevalidateRequestOptions["publicKey"] | (() => RevalidateRequestOptions["publicKey"]);
+    /** This theme's key. */
+    theme: string;
+}
+/** The theme's `/wocart-revalidate` route: `POST` drops the cached pages for a verified token, `ALL` answers 405. */
+export declare function revalidateEndpoint(options: RevalidateEndpointOptions): {
+    POST: (context: RevalidateEndpointContext) => Promise<Response>;
+    ALL: () => Response;
+};

package/dist/endpoints/revalidate-endpoint.js

@@ -0,0 +1,32 @@
+/**
+ * The revalidation route a theme exports, ready-made:
+ *
+ * ```ts
+ * // src/pages/wocart-revalidate.ts
+ * import { revalidateEndpoint } from "@wocart/storefront/astro";
+ *
+ * export const prerender = false;
+ * export const { POST, ALL } = revalidateEndpoint({ publicKey: () => WOCART_PREVIEW_KEY, theme: THEME_KEY });
+ * ```
+ *
+ * `POST` verifies the platform's token (`readRevalidateRequest`), drops every
+ * page cached under `PAGES_CACHE_TAG` and answers 204; a refused token
+ * answers its status and drops nothing. `ALL` answers any other method 405.
+ * Neither answer is ever cached.
+ */
+import { PAGES_CACHE_TAG, readRevalidateRequest } from "../revalidate.js";
+const noStore = (status, headers = {}) => new Response(null, { status, headers: { "Cache-Control": "no-store", ...headers } });
+/** The theme's `/wocart-revalidate` route: `POST` drops the cached pages for a verified token, `ALL` answers 405. */
+export function revalidateEndpoint(options) {
+    return {
+        POST: async (context) => {
+            const publicKey = typeof options.publicKey === "function" ? options.publicKey() : options.publicKey;
+            const revalidation = await readRevalidateRequest(context.request, { publicKey, theme: options.theme });
+            if (!revalidation.ok)
+                return noStore(revalidation.status);
+            await context.cache.invalidate({ tags: [PAGES_CACHE_TAG] });
+            return noStore(204);
+        },
+        ALL: () => noStore(405, { Allow: "POST" }),
+    };
+}

package/dist/index.d.ts

@@ -17,13 +17,13 @@ export { productImageSource } from "./utils/product-image.js";
 export type { ProductImageSourceInput } from "./utils/product-image.js";
 export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, whatsAppContact } from "./whatsapp.js";
 export type { PrefillToken, WhatsAppContact, WhatsAppPage, WhatsAppWords } from "./whatsapp.js";
-export { STOREFRONT_PAGE_PATHS, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";
+export { SINGLE_LANGUAGE_PAGE_TYPES, STOREFRONT_API_PATHS, STOREFRONT_PAGE_PATHS, isSingleLanguagePage, matchStorefrontPath, showsWidgetOn, storefrontApiPath, storefrontPath } from "./routes.js";
 export { servedLanguage } from "./locales.js";
 export { unavailableStoreConfig } from "./unavailable-store.js";
 export type { UnavailableStoreOptions } from "./unavailable-store.js";
 export { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "./locale-routing.js";
 export type { LocalePath, LocaleRouting } from "./locale-routing.js";
-export type { StorefrontPageMatch, StorefrontPageType, StorefrontPathParams } from "./routes.js";
+export type { StorefrontApiName, StorefrontApiParams, StorefrontPageMatch, StorefrontPageType, StorefrontPathParams } from "./routes.js";
 export { addedLines, createBasketStore, createMemoryStorageAdapter, createLocalStorageAdapter, DEFAULT_BASKET_STORAGE_KEY, toOrderItems, } from "./basket.js";
 export { MAX_BASKET_LINES, MAX_BASKET_LINE_QUANTITY, basketLineKey } from "./basket-line.js";
 export type { BasketStore, BasketStorageAdapter, BasketStoreOptions, BasketListener, BasketSelectionLine, } from "./basket.js";
@@ -38,6 +38,8 @@ export { readCartQuote, readCouponOutcome, readShippingRates } from "./answer-re
 export { createQuoter } from "./quote.js";
 export type { Quoter, QuoterOptions, QuoteResult } from "./quote.js";
 export { isOrderNumber, ORDER_NUMBER_PATTERN } from "./order-number.js";
+export { readThankYou, thankYouHref } from "./thank-you.js";
+export type { ThankYouOrder } from "./thank-you.js";
 export { DEFAULT_COLLECTION_HANDLES, PRODUCT_SORTS, SHOPPER_ORDER_JOURNEY, SHOPPER_ORDER_STAGES } from "./catalog.js";
 export { SEO_TEXT_LIMITS, canonicalUrl, jsonLd, productMeta, productStructuredData } from "./seo.js";
 export type { CanonicalPage, PageMeta, ProductStructuredDataOptions } from "./seo.js";

package/dist/index.js

@@ -13,7 +13,7 @@ export { formatMoney } from "./utils/money.js";
 export { isMediaKey, mediaImageSrcset, mediaImageUrl, mediaUrl, pictureOf } from "./utils/image.js";
 export { productImageSource } from "./utils/product-image.js";
 export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, whatsAppContact } from "./whatsapp.js";
-export { STOREFRONT_PAGE_PATHS, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";
+export { SINGLE_LANGUAGE_PAGE_TYPES, STOREFRONT_API_PATHS, STOREFRONT_PAGE_PATHS, isSingleLanguagePage, matchStorefrontPath, showsWidgetOn, storefrontApiPath, storefrontPath } from "./routes.js";
 export { servedLanguage } from "./locales.js";
 export { unavailableStoreConfig } from "./unavailable-store.js";
 export { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "./locale-routing.js";
@@ -27,6 +27,7 @@ export { isWilayaId } from "./wilaya-id.js";
 export { readCartQuote, readCouponOutcome, readShippingRates } from "./answer-readers.js";
 export { createQuoter } from "./quote.js";
 export { isOrderNumber, ORDER_NUMBER_PATTERN } from "./order-number.js";
+export { readThankYou, thankYouHref } from "./thank-you.js";
 export { DEFAULT_COLLECTION_HANDLES, PRODUCT_SORTS, SHOPPER_ORDER_JOURNEY, SHOPPER_ORDER_STAGES } from "./catalog.js";
 export { SEO_TEXT_LIMITS, canonicalUrl, jsonLd, productMeta, productStructuredData } from "./seo.js";
 export { REVIEW_REFUSAL_CODES, REVIEW_TEXT_LIMITS } from "./reviews.js";

package/dist/locale-routing.d.ts

@@ -1,16 +1,3 @@
-/**
- * Language-prefixed storefront URLs — Shopify's
- * subfolders: the primary language keeps today's URLs (`/products/x`), every
- * other published language lives under its code (`/fr/products/x`), and the
- * primary has exactly one address (`/ar/products/x` redirects to
- * `/products/x`).
- *
- * Pure functions over the store's own languages (`StoreConfig.lang` and
- * `StoreConfig.locales`): a theme reads the request's language with
- * `resolveLocalePath`, builds every internal link with `localizeHref`, and
- * lists a page's language versions with `alternateLinks` — the counterpart of
- * Shopify's `request.locale.root_url` and `routes`.
- */
 import type { StoreConfig } from "./types.js";
 /** The store's languages as URLs need them. */
 export interface LocaleRouting {
@@ -27,7 +14,7 @@ export type LocalePath =
     locale: string;
     pathname: string;
 }
-/** The primary under a prefix: send the shopper to its one address. */
+/** The primary under a prefix, or a single-language page under any: send the shopper to its one address. */
  | {
     kind: "redirect";
     location: string;
@@ -35,23 +22,27 @@ export type LocalePath =
 /**
  * Which language a request is for, and the path it renders. A first segment
  * that is a published language other than the primary selects it; the
- * primary's own prefix redirects; anything else — an unpublished or unknown
- * code included — is an ordinary path in the primary language, so it renders
- * or 404s exactly as before.
+ * primary's own prefix redirects, and so does any prefix on a page that
+ * exists in the primary language only (`isSingleLanguagePage`: `/fr/lp/x` →
+ * `/lp/x`); anything else — an unpublished or unknown code included — is an
+ * ordinary path in the primary language, so it renders or 404s exactly as
+ * before.
  */
 export declare function resolveLocalePath(pathname: string, routing: LocaleRouting): LocalePath;
 /**
  * An internal link in `locale`: `/products/x` → `/fr/products/x`, `/` → `/fr`.
  * Left unchanged: the primary language, external and protocol-relative URLs,
- * fragments, `mailto:`/`tel:`, endpoints and files, and a link that already
- * carries a language prefix. Query strings and fragments are kept.
+ * fragments, `mailto:`/`tel:`, endpoints and files, a page that exists in the
+ * primary language only (a landing page), and a link that already carries a
+ * language prefix. Query strings and fragments are kept.
  */
 export declare function localizeHref(href: string, locale: string, routing: LocaleRouting): string;
 /**
  * Every published language's URL for one page, primary first, plus
  * `x-default` (the primary) — the `<link rel="alternate" hreflang>` set.
  * `pathname` is the page's unprefixed path; `origin` makes the URLs absolute,
- * as search engines require.
+ * as search engines require. None for a page that exists in the primary
+ * language only.
  */
 export declare function alternateLinks(pathname: string, routing: LocaleRouting, origin: string): {
     hreflang: string;

package/dist/locale-routing.js

@@ -1,3 +1,17 @@
+/**
+ * Language-prefixed storefront URLs — Shopify's
+ * subfolders: the primary language keeps today's URLs (`/products/x`), every
+ * other published language lives under its code (`/fr/products/x`), and the
+ * primary has exactly one address (`/ar/products/x` redirects to
+ * `/products/x`).
+ *
+ * Pure functions over the store's own languages (`StoreConfig.lang` and
+ * `StoreConfig.locales`): a theme reads the request's language with
+ * `resolveLocalePath`, builds every internal link with `localizeHref`, and
+ * lists a page's language versions with `alternateLinks` — the counterpart of
+ * Shopify's `request.locale.root_url` and `routes`.
+ */
+import { isSingleLanguagePage } from "./routes.js";
 export function localeRouting(config) {
     const published = config.locales.map((language) => language.code);
     return {
@@ -12,16 +26,18 @@ function isPagePath(pathname) {
 /**
  * Which language a request is for, and the path it renders. A first segment
  * that is a published language other than the primary selects it; the
- * primary's own prefix redirects; anything else — an unpublished or unknown
- * code included — is an ordinary path in the primary language, so it renders
- * or 404s exactly as before.
+ * primary's own prefix redirects, and so does any prefix on a page that
+ * exists in the primary language only (`isSingleLanguagePage`: `/fr/lp/x` →
+ * `/lp/x`); anything else — an unpublished or unknown code included — is an
+ * ordinary path in the primary language, so it renders or 404s exactly as
+ * before.
  */
 export function resolveLocalePath(pathname, routing) {
     const match = /^\/([^/]+)(\/.*)?$/.exec(pathname);
     const segment = match?.[1];
     if (segment !== undefined && routing.published.includes(segment)) {
         const rest = match?.[2] ?? "/";
-        if (segment === routing.primary)
+        if (segment === routing.primary || isSingleLanguagePage(rest))
             return { kind: "redirect", location: rest };
         return { kind: "page", locale: segment, pathname: rest };
     }
@@ -30,8 +46,9 @@ export function resolveLocalePath(pathname, routing) {
 /**
  * An internal link in `locale`: `/products/x` → `/fr/products/x`, `/` → `/fr`.
  * Left unchanged: the primary language, external and protocol-relative URLs,
- * fragments, `mailto:`/`tel:`, endpoints and files, and a link that already
- * carries a language prefix. Query strings and fragments are kept.
+ * fragments, `mailto:`/`tel:`, endpoints and files, a page that exists in the
+ * primary language only (a landing page), and a link that already carries a
+ * language prefix. Query strings and fragments are kept.
  */
 export function localizeHref(href, locale, routing) {
     if (locale === routing.primary || !href.startsWith("/") || href.startsWith("//"))
@@ -39,7 +56,7 @@ export function localizeHref(href, locale, routing) {
     const split = /^([^?#]*)(.*)$/.exec(href);
     const pathname = split[1];
     const rest = split[2];
-    if (!isPagePath(pathname))
+    if (!isPagePath(pathname) || isSingleLanguagePage(pathname))
         return href;
     const first = /^\/([^/]+)/.exec(pathname)?.[1];
     if (first !== undefined && routing.published.includes(first))
@@ -50,9 +67,12 @@ export function localizeHref(href, locale, routing) {
  * Every published language's URL for one page, primary first, plus
  * `x-default` (the primary) — the `<link rel="alternate" hreflang>` set.
  * `pathname` is the page's unprefixed path; `origin` makes the URLs absolute,
- * as search engines require.
+ * as search engines require. None for a page that exists in the primary
+ * language only.
  */
 export function alternateLinks(pathname, routing, origin) {
+    if (isSingleLanguagePage(pathname))
+        return [];
     const base = origin.replace(/\/+$/, "");
     const links = routing.published.map((locale) => ({
         hreflang: locale,

package/dist/revalidate.d.ts

@@ -1,5 +1,11 @@
 /** Where a theme that can drop its cached pages answers a revalidation. */
 export declare const REVALIDATE_PATH = "/wocart-revalidate";
+/**
+ * The cache tag every cached page carries, and the one a revalidation drops:
+ * a publish (pages, settings or text) can change any page, so a theme tags
+ * every cached route with it (`routeRules` in `astro.config.mjs`).
+ */
+export declare const PAGES_CACHE_TAG = "pages";
 /** What a verified revalidation token says. */
 export interface RevalidateClaims {
     /** The storefront origin the token was made for. */

package/dist/revalidate.js

@@ -17,6 +17,12 @@
 import { timingRefusal, verifiedPayload } from "./signed-token.js";
 /** Where a theme that can drop its cached pages answers a revalidation. */
 export const REVALIDATE_PATH = "/wocart-revalidate";
+/**
+ * The cache tag every cached page carries, and the one a revalidation drops:
+ * a publish (pages, settings or text) can change any page, so a theme tags
+ * every cached route with it (`routeRules` in `astro.config.mjs`).
+ */
+export const PAGES_CACHE_TAG = "pages";
 /** The longest a revalidation token may live. */
 const MAX_LIFETIME_SECONDS = 5 * 60;
 const refuse = (status, reason) => ({ ok: false, status, reason });

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: {
@@ -52,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,
@@ -60,6 +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;
+/**
+ * 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 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

@@ -23,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) => {
@@ -60,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",

package/dist/server.d.ts

@@ -3,7 +3,7 @@ export type { StoreClient } from "./client/index.js";
 export type { ClientResult } from "./client/core.js";
 export { StorefrontError, isStorefrontError } from "./client/errors.js";
 export { previewConfig, previewResponseHeaders, readPreviewRequest, verifyPreviewToken } from "./preview.js";
-export { REVALIDATE_PATH, readRevalidateRequest } from "./revalidate.js";
+export { PAGES_CACHE_TAG, REVALIDATE_PATH, readRevalidateRequest } from "./revalidate.js";
 export type { RevalidateClaims, RevalidateRequest, RevalidateRequestOptions } from "./revalidate.js";
 export type { PreviewClaims, PreviewDraft, PreviewRequest, PreviewRequestOptions, PreviewTokenCheck, PreviewTokenOptions, PreviewTokenRefusal, } from "./preview.js";
 export { catalogPaths, sitemapXml } from "./sitemap.js";

package/dist/server.js

@@ -1,5 +1,5 @@
 export { createStoreClient } from "./client/index.js";
 export { StorefrontError, isStorefrontError } from "./client/errors.js";
 export { previewConfig, previewResponseHeaders, readPreviewRequest, verifyPreviewToken } from "./preview.js";
-export { REVALIDATE_PATH, readRevalidateRequest } from "./revalidate.js";
+export { PAGES_CACHE_TAG, REVALIDATE_PATH, readRevalidateRequest } from "./revalidate.js";
 export { catalogPaths, sitemapXml } from "./sitemap.js";

package/dist/storefront-middleware.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The request lifecycle every theme's `src/middleware.ts` runs, in one call:
+ *
+ * ```ts
+ * // src/middleware.ts
+ * import { getActionContext } from "astro:actions";
+ * import { createStorefrontMiddleware } from "@wocart/storefront/astro";
+ * import { THEME_PREVIEW_PATH } from "@wocart/theme";
+ *
+ * export const onRequest = createStorefrontMiddleware({
+ *   client: createStore,
+ *   fallback: unavailableStoreConfig({ serverUrl, locale: "ar" }),
+ *   preview: { path: THEME_PREVIEW_PATH, publicKey: () => WOCART_PREVIEW_KEY, theme: THEME_KEY },
+ *   context: (store) => buildStoreContext(store),
+ *   getActionContext,
+ * });
+ * ```
+ *
+ * In order:
+ *
+ * - A prerendered file (the manifest, the theme's styles) and the
+ *   revalidation route (`REVALIDATE_PATH`) need no store.
+ * - A request that already has a store keeps it: a page's `notFound()`
+ *   rewrites to `/404` and Astro runs the middleware again, and the 404 must
+ *   stay in the language the shopper asked for.
+ * - The editor's preview (`preview.path`) renders the store as the draft
+ *   would leave it, after its token is verified; it never runs a form action.
+ * - Any other request resolves its store and language
+ *   (`resolveStoreRequest`), answers its redirect if it has one, builds the
+ *   theme's context, runs a form-called action for the page this POST renders
+ *   (`runFormAction`), then renders the unprefixed route.
+ *
+ * `astro:actions` is an Astro virtual module, so the theme passes
+ * `getActionContext` in. The theme's context becomes `locals.store`; a
+ * verified preview's claims, draft and token become `locals.preview`.
+ */
+import type { StoreClient } from "./client/index.js";
+import { type ActionDescriptor, type ActionHandlerResult } from "./middleware.js";
+import { type PreviewClaims, type PreviewDraft, type PreviewRequestOptions } from "./preview.js";
+import { type ResolvedStore } from "./store-request.js";
+import type { StoreConfig } from "./types.js";
+/** What a verified preview leaves on `locals.preview`. */
+export interface PreviewLocals {
+    claims: PreviewClaims;
+    draft: PreviewDraft;
+    token: string;
+}
+/** What the middleware uses of Astro's `APIContext`. */
+export interface StorefrontMiddlewareContext {
+    isPrerendered: boolean;
+    url: URL;
+    request: Request;
+    /** `App.Locals`: the middleware writes `store` and, on a preview, `preview`. */
+    locals: object;
+    redirect(location: string, status: 301 | 302): Response;
+}
+/** What the middleware uses of `getActionContext(context)`. */
+export interface StorefrontActionContext<TResult extends ActionHandlerResult, TSerialized> {
+    action?: ActionDescriptor<TResult> | undefined;
+    setActionResult: (name: string, serialized: TSerialized) => void;
+    serializeActionResult: (result: TResult) => TSerialized;
+}
+export interface StorefrontMiddlewareOptions<TContext extends StorefrontMiddlewareContext, TStore, TResult extends ActionHandlerResult, TSerialized> {
+    /** The theme's one client factory: in `locale`, or in the store's primary language when absent. */
+    client: (locale?: string) => StoreClient;
+    /** What renders when the store's config cannot be read: `unavailableStoreConfig(…)`. */
+    fallback: StoreConfig;
+    /**
+     * The editor's preview route (`THEME_PREVIEW_PATH`) and how its token is
+     * checked; no `publicKey`: the route answers 404. Pass the key as a
+     * function to read it on each request: a secret from `astro:env/server`
+     * can be set after the module loads.
+     */
+    preview: {
+        path: string;
+        publicKey: PreviewRequestOptions["publicKey"] | (() => PreviewRequestOptions["publicKey"]);
+    } & Pick<PreviewRequestOptions, "theme" | "maxBytes">;
+    /** The theme's context for a resolved store; it becomes `locals.store`. */
+    context: (store: ResolvedStore) => TStore;
+    /** Astro's `getActionContext`, from `astro:actions`. */
+    getActionContext: (context: TContext) => StorefrontActionContext<TResult, TSerialized>;
+    /** Whether a path serves part of a page rather than a page. Default: `/api/` and `/_server-islands/`. */
+    embedded?: (pathname: string) => boolean;
+}
+/** An Astro middleware handler (`onRequest`). */
+export type StorefrontMiddleware<TContext extends StorefrontMiddlewareContext> = (context: TContext, next: (rewrite?: string) => Promise<Response>) => Promise<Response>;
+/** The theme's `onRequest`: store, language, redirects, preview and form actions, as described above. */
+export declare function createStorefrontMiddleware<TContext extends StorefrontMiddlewareContext, TStore, TResult extends ActionHandlerResult, TSerialized>(options: StorefrontMiddlewareOptions<TContext, TStore, TResult, TSerialized>): StorefrontMiddleware<TContext>;

package/dist/storefront-middleware.js

@@ -0,0 +1,37 @@
+import { runFormAction } from "./middleware.js";
+import { readPreviewRequest } from "./preview.js";
+import { REVALIDATE_PATH } from "./revalidate.js";
+import { resolvePreviewStore, resolveStoreRequest } from "./store-request.js";
+/** The theme's `onRequest`: store, language, redirects, preview and form actions, as described above. */
+export function createStorefrontMiddleware(options) {
+    const store = { client: options.client, fallback: options.fallback, ...(options.embedded ? { embedded: options.embedded } : {}) };
+    const { path: previewPath, publicKey, ...previewOptions } = options.preview;
+    return async (context, next) => {
+        const locals = context.locals;
+        if (context.isPrerendered)
+            return next();
+        if (context.url.pathname === REVALIDATE_PATH)
+            return next();
+        if (locals.store !== undefined)
+            return next();
+        if (context.url.pathname === previewPath) {
+            const preview = await readPreviewRequest(context.request, { ...previewOptions, publicKey: typeof publicKey === "function" ? publicKey() : publicKey });
+            if (!preview.ok)
+                return new Response(null, { status: preview.status, headers: { "Cache-Control": "no-store" } });
+            locals.store = options.context(await resolvePreviewStore(preview.draft, store));
+            locals.preview = { claims: preview.claims, draft: preview.draft, token: preview.token };
+            return next();
+        }
+        const request = await resolveStoreRequest({ url: context.url, referer: context.request.headers.get("Referer") }, store);
+        if (request.kind === "redirect")
+            return context.redirect(request.location, request.status);
+        locals.store = options.context(request);
+        const { action, setActionResult, serializeActionResult } = options.getActionContext(context);
+        await runFormAction({
+            ...(action ? { action: { calledFrom: action.calledFrom, name: action.name, handler: action.handler } } : {}),
+            setActionResult,
+            serializeActionResult,
+        });
+        return request.rewrite === null ? next() : next(request.rewrite);
+    };
+}

package/dist/thank-you.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The thank-you page's address for a placed order, and its reading back. The
+ * query carries the order's number, total and id — never the shopper's
+ * details — so the page can thank, show the total and fire a conversion
+ * without reading the order again. One spelling, here: a theme writes it
+ * after `placeOrder`, its thank-you page reads it, and an editor previews
+ * the page with a sample order by building the same address.
+ */
+import { type LocaleRouting } from "./locale-routing.js";
+/** What the thank-you page reads from its address. */
+export interface ThankYouOrder {
+    /** The order number the shopper is given; empty when the address has none. */
+    orderNumber: string;
+    /** The order's id, for a conversion's deduplication; empty when the address has none. */
+    orderId: string;
+    /** The order's total in the store's currency; null when missing or not a number. */
+    total: number | null;
+}
+/**
+ * The thank-you page for a placed order: `/thank-you?order=…&total=…&oid=…`,
+ * in the request's language when `language` is given (`/fr/thank-you?…`).
+ */
+export declare function thankYouHref(order: {
+    orderNumber: string;
+    total: number;
+    orderId?: string | null;
+}, language?: {
+    locale: string;
+    routing: LocaleRouting;
+}): string;
+/** The order a thank-you address names: `thankYouHref`'s query, read back and trimmed. */
+export declare function readThankYou(url: URL | URLSearchParams): ThankYouOrder;

package/dist/thank-you.js

@@ -0,0 +1,33 @@
+/**
+ * The thank-you page's address for a placed order, and its reading back. The
+ * query carries the order's number, total and id — never the shopper's
+ * details — so the page can thank, show the total and fire a conversion
+ * without reading the order again. One spelling, here: a theme writes it
+ * after `placeOrder`, its thank-you page reads it, and an editor previews
+ * the page with a sample order by building the same address.
+ */
+import { localizeHref } from "./locale-routing.js";
+import { storefrontPath } from "./routes.js";
+const ORDER_NUMBER = "order";
+const TOTAL = "total";
+const ORDER_ID = "oid";
+/**
+ * The thank-you page for a placed order: `/thank-you?order=…&total=…&oid=…`,
+ * in the request's language when `language` is given (`/fr/thank-you?…`).
+ */
+export function thankYouHref(order, language) {
+    const query = new URLSearchParams({ [ORDER_NUMBER]: order.orderNumber, [TOTAL]: String(order.total), [ORDER_ID]: order.orderId ?? "" });
+    const path = storefrontPath("thankYou");
+    return `${language ? localizeHref(path, language.locale, language.routing) : path}?${query.toString()}`;
+}
+/** The order a thank-you address names: `thankYouHref`'s query, read back and trimmed. */
+export function readThankYou(url) {
+    const params = url instanceof URLSearchParams ? url : url.searchParams;
+    const raw = params.get(TOTAL)?.trim() ?? "";
+    const total = /^-?\d+$/.test(raw) ? Number.parseInt(raw, 10) : Number.NaN;
+    return {
+        orderNumber: (params.get(ORDER_NUMBER) ?? "").trim(),
+        orderId: (params.get(ORDER_ID) ?? "").trim(),
+        total: Number.isFinite(total) ? total : null,
+    };
+}

package/package.json

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