@wocart/storefront 1.15.0 → 1.17.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.17.0 — 2026-10-18
+
+### Added
+
+- **Revalidation** (`@wocart/storefront/server`): `readRevalidateRequest`
+  and `REVALIDATE_PATH` (`/wocart-revalidate`), with `RevalidateClaims`. The
+  platform tells a storefront its pages changed — a publish — with a `POST`
+  carrying a bearer token signed by the same deployment key as previews but
+  made for this use only (`use: "revalidate"`, five minutes at most, for the
+  storefront's origin and theme); the theme then drops its cached pages, so a
+  publish shows at once. Without the key, revalidation is off.
+
+### Changed
+
+- `verifyPreviewToken` refuses a token made for another use (`use` other
+  than `"preview"`). Tokens without `use` are accepted as before.
+
+## 1.16.0 — 2026-10-18
+
+### Changed
+
+- `pageData.get(surface)` reads the document the store composed for the
+  client's theme: a client created with `theme` sends it
+  (`/store/page-documents/{surface}?theme=`), so a store keeps one document
+  per theme and switching themes never shows another theme's page. Without
+  `theme`, the server answers the most recently saved document for the
+  surface, as before.
+
 ## 1.15.0 — 2026-10-18
 
 ### Added

package/README.md

@@ -68,7 +68,7 @@ if (result.success) {
 | Import | Runs in | What it holds |
 | --- | --- | --- |
 | `@wocart/storefront` | browser and server | read-model types and schemas, reference data (58 wilayas, 1,551 communes), money and image helpers, the basket and OTP state machines, language routing, Meta pixel payloads |
-| `@wocart/storefront/server` | server only | `createStoreClient`, `StoreClient`, `ClientResult`, `StorefrontError` — the API key lives here — and the preview checks (`readPreviewRequest`, `verifyPreviewToken`, `previewResponseHeaders`, `previewConfig`) |
+| `@wocart/storefront/server` | server only | `createStoreClient`, `StoreClient`, `ClientResult`, `StorefrontError` — the API key lives here — the preview checks (`readPreviewRequest`, `verifyPreviewToken`, `previewResponseHeaders`, `previewConfig`) and revalidation (`readRevalidateRequest`) |
 | `@wocart/storefront/astro` | server only | `createStorefrontRoutes`, `createProxyEndpoint`, `placeOrderInput`, `executePlaceOrder`, `collectForwardedHeaders`, `runFormAction` |
 
 Browser code never receives the key. It calls your own same-origin routes

package/USAGE.md

@@ -884,8 +884,9 @@ Do not invent tracking events from a landing-page slug.
 const saved = await store.pageData.get("home");   // null = never saved / failed
 ~~~
 
-One document per surface ("home" today), owned by the store and written by
-the platform's page editor — a storefront never writes it. `null` means the store has never saved one (or the read
+One document per theme and surface ("home" today), owned by the store and
+written by the platform's page editor — a storefront never writes it. A
+client created with `theme` reads the document composed for that theme. `null` means the store has never saved one (or the read
 failed): render the theme's shipped default document. The payload is
 **transport-checked only** (`version`, `surface`, `sections`) and fetched
 fresh on every call, so a save reaches the next render.
@@ -1638,6 +1639,32 @@ A storefront can verify tokens but never make one: the private key stays with
 the editor's server. The page side — marking sections and talking to the
 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:
+
+```ts
+// src/pages/wocart-revalidate.ts — REVALIDATE_PATH
+import type { APIRoute } from "astro";
+import { readRevalidateRequest } from "@wocart/storefront/server";
+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 });
+};
+```
+
+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
+origin and this theme, living five minutes at most. A preview token can
+never purge a cache, and a revalidation token can never open a preview.
+Astro's `cache.invalidate` purges the tag on Cloudflare and on Vercel alike.
+
 ## A recommended theme structure
 
 Keep the theme visually expressive while making the platform boundary obvious:

package/dist/client/page-data.d.ts

@@ -2,8 +2,10 @@
  * Page Data Namespace — the store's saved composition document.
  *
  * Deep module: hides URL construction and transport behind one call. The
- * document belongs to the store (one per surface — "home" today) and is
- * written by the platform's editor; this namespace is the theme's read side.
+ * document belongs to the store (one per theme and surface — "home" today)
+ * and is written by the platform's editor; this namespace is the theme's
+ * read side. A client created with `theme` reads that theme's document;
+ * without it, the server answers the most recently saved one for the surface.
  *
  * Transport semantics (NOT the document contract): the payload is validated
  * as `{ version, surface, sections }` and returns `null` for "no saved

package/dist/client/page-data.js

@@ -2,8 +2,10 @@
  * Page Data Namespace — the store's saved composition document.
  *
  * Deep module: hides URL construction and transport behind one call. The
- * document belongs to the store (one per surface — "home" today) and is
- * written by the platform's editor; this namespace is the theme's read side.
+ * document belongs to the store (one per theme and surface — "home" today)
+ * and is written by the platform's editor; this namespace is the theme's
+ * read side. A client created with `theme` reads that theme's document;
+ * without it, the server answers the most recently saved one for the surface.
  *
  * Transport semantics (NOT the document contract): the payload is validated
  * as `{ version, surface, sections }` and returns `null` for "no saved
@@ -24,7 +26,9 @@ export function createPageDataNamespace(core) {
     return {
         async get(surface) {
             try {
-                const document = await core.get(`/store/page-documents/${encodeURIComponent(surface)}`, PageDocumentPayloadSchema.nullable(), { operation: STOREFRONT_OPERATIONS.pageDataGet });
+                const path = `/store/page-documents/${encodeURIComponent(surface)}`;
+                const theme = core.config.theme;
+                const document = await core.get(theme === undefined ? path : `${path}?${new URLSearchParams({ theme })}`, PageDocumentPayloadSchema.nullable(), { operation: STOREFRONT_OPERATIONS.pageDataGet });
                 return document ?? null;
             }
             catch (error) {

package/dist/domain.d.ts

@@ -12,7 +12,8 @@ export interface StoreScope {
      * The key of the theme this client renders (`defineTheme({ key })` in
      * `@wocart/theme`). The store's edits to that theme's text arrive as
      * `StoreConfig.contentOverrides`; without it there are none, because edits
-     * belong to the theme that declares their keys. The server owns the key
+     * belong to the theme that declares their keys. `pageData.get` reads the
+     * documents the store composed for that theme. The server owns the key
      * format and refuses a malformed one.
      */
     readonly theme?: string;

package/dist/preview.d.ts

@@ -14,6 +14,7 @@
  * editor's origin, `iat`/`exp` (at most an hour apart), optional `sub`/`jti`.
  */
 import type { StoreConfig } from "./types.js";
+import { type SignedTokenRefusal } from "./signed-token.js";
 /** What a verified token says. */
 export interface PreviewClaims {
     /** The storefront origin the token was made for. */
@@ -27,7 +28,7 @@ export interface PreviewClaims {
     sub?: string;
     jti?: string;
 }
-export type PreviewTokenRefusal = "malformed" | "unsupported-algorithm" | "invalid-key" | "bad-signature" | "invalid-claims" | "expired" | "not-yet-valid" | "too-long-lived" | "wrong-audience" | "wrong-theme";
+export type PreviewTokenRefusal = SignedTokenRefusal;
 export type PreviewTokenCheck = {
     ok: true;
     claims: PreviewClaims;
@@ -45,7 +46,11 @@ export interface PreviewTokenOptions {
     /** Seconds since the epoch; defaults to now. */
     now?: number;
 }
-/** Check a preview token's signature and claims against this storefront and theme. */
+/**
+ * Check a preview token's signature and claims against this storefront and
+ * theme. A token made for another use (`use` other than `"preview"`) is
+ * refused, so no other signed request can open a preview.
+ */
 export declare function verifyPreviewToken(token: string, options: PreviewTokenOptions): Promise<PreviewTokenCheck>;
 /**
  * What an editor sends to be previewed. The storefront renders it as if it

package/dist/preview.js

@@ -1,32 +1,7 @@
-/** Clock skew tolerated between the editor's server and the storefront. */
-const CLOCK_SKEW_SECONDS = 30;
+import { timingRefusal, verifiedPayload } from "./signed-token.js";
 /** The longest a preview token may live. */
 const MAX_LIFETIME_SECONDS = 60 * 60;
-const decoder = new TextDecoder();
 const encoder = new TextEncoder();
-function base64UrlBytes(value) {
-    if (!/^[A-Za-z0-9_-]*$/.test(value))
-        return null;
-    try {
-        const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (value.length % 4)) % 4));
-        return Uint8Array.from(binary, (char) => char.charCodeAt(0));
-    }
-    catch {
-        return null;
-    }
-}
-function base64UrlJson(value) {
-    const bytes = base64UrlBytes(value);
-    if (bytes === null)
-        return null;
-    try {
-        const parsed = JSON.parse(decoder.decode(bytes));
-        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
-    }
-    catch {
-        return null;
-    }
-}
 const isOrigin = (value) => {
     if (typeof value !== "string")
         return false;
@@ -38,44 +13,16 @@ const isOrigin = (value) => {
         return false;
     }
 };
-async function importKey(publicKey) {
-    try {
-        const jwk = typeof publicKey === "string" ? JSON.parse(publicKey) : publicKey;
-        if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || typeof jwk.x !== "string" || jwk.d !== undefined)
-            return null;
-        return await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, { name: "Ed25519" }, false, ["verify"]);
-    }
-    catch {
-        return null;
-    }
-}
-/** Check a preview token's signature and claims against this storefront and theme. */
+/**
+ * Check a preview token's signature and claims against this storefront and
+ * theme. A token made for another use (`use` other than `"preview"`) is
+ * refused, so no other signed request can open a preview.
+ */
 export async function verifyPreviewToken(token, options) {
-    const parts = typeof token === "string" ? token.split(".") : [];
-    if (parts.length !== 3)
-        return { ok: false, reason: "malformed" };
-    const [headerPart, payloadPart, signaturePart] = parts;
-    const header = base64UrlJson(headerPart);
-    const payload = base64UrlJson(payloadPart);
-    const signature = base64UrlBytes(signaturePart);
-    if (header === null || payload === null || signature === null)
-        return { ok: false, reason: "malformed" };
-    if (header.alg !== "EdDSA" || header.crit !== undefined)
-        return { ok: false, reason: "unsupported-algorithm" };
-    const key = await importKey(options.publicKey);
-    if (key === null)
-        return { ok: false, reason: "invalid-key" };
-    const signed = encoder.encode(`${headerPart}.${payloadPart}`);
-    let valid = false;
-    try {
-        valid = await crypto.subtle.verify({ name: "Ed25519" }, key, signature, signed);
-    }
-    catch {
-        valid = false;
-    }
-    if (!valid)
-        return { ok: false, reason: "bad-signature" };
-    const { aud, theme, editor, iat, exp, sub, jti } = payload;
+    const verified = await verifiedPayload(token, options.publicKey);
+    if (!verified.ok)
+        return verified;
+    const { aud, theme, editor, iat, exp, sub, jti, use } = verified.payload;
     if (typeof aud !== "string" ||
         typeof theme !== "string" ||
         !isOrigin(editor) ||
@@ -84,16 +31,13 @@ export async function verifyPreviewToken(token, options) {
         !Number.isFinite(iat) ||
         !Number.isFinite(exp) ||
         (sub !== undefined && typeof sub !== "string") ||
-        (jti !== undefined && typeof jti !== "string")) {
+        (jti !== undefined && typeof jti !== "string") ||
+        (use !== undefined && use !== "preview")) {
         return { ok: false, reason: "invalid-claims" };
     }
-    const now = options.now ?? Math.floor(Date.now() / 1000);
-    if (exp <= now - CLOCK_SKEW_SECONDS)
-        return { ok: false, reason: "expired" };
-    if (iat > now + CLOCK_SKEW_SECONDS)
-        return { ok: false, reason: "not-yet-valid" };
-    if (exp - iat > MAX_LIFETIME_SECONDS)
-        return { ok: false, reason: "too-long-lived" };
+    const timing = timingRefusal(iat, exp, options.now, MAX_LIFETIME_SECONDS);
+    if (timing !== null)
+        return { ok: false, reason: timing };
     if (aud !== options.audience)
         return { ok: false, reason: "wrong-audience" };
     if (theme !== options.theme)

package/dist/revalidate.d.ts

@@ -0,0 +1,37 @@
+/** Where a theme that can drop its cached pages answers a revalidation. */
+export declare const REVALIDATE_PATH = "/wocart-revalidate";
+/** What a verified revalidation token says. */
+export interface RevalidateClaims {
+    /** The storefront origin the token was made for. */
+    aud: string;
+    /** The key of the theme whose pages changed. */
+    theme: string;
+    use: "revalidate";
+    iat: number;
+    exp: number;
+    sub?: string;
+    jti?: string;
+}
+export type RevalidateRequest = {
+    ok: true;
+    claims: RevalidateClaims;
+} | {
+    ok: false;
+    status: 401 | 403 | 404 | 405;
+    reason: string;
+};
+export interface RevalidateRequestOptions {
+    /** The deployment's public key (a JWK) — the preview key; absent: revalidation is off and every request answers 404. */
+    publicKey?: string | JsonWebKey | undefined;
+    /** This theme's key. */
+    theme: string;
+    /** Seconds since the epoch; defaults to now. */
+    now?: number;
+}
+/**
+ * Read a revalidation request. `{ ok: true }` only for a `POST` carrying a
+ * token made for revalidation, for this storefront (its origin is the
+ * token's `aud`) and this theme; otherwise a status to answer, and nothing
+ * is dropped.
+ */
+export declare function readRevalidateRequest(request: Request, options: RevalidateRequestOptions): Promise<RevalidateRequest>;

package/dist/revalidate.js

@@ -0,0 +1,66 @@
+/**
+ * Revalidation: the platform tells a storefront that what its pages show has
+ * changed — an editor published a theme's pages, settings or text — so the
+ * storefront drops the pages it cached and the next visit renders fresh.
+ *
+ * The request is a `POST` to the theme's revalidation route
+ * (`REVALIDATE_PATH`) from the platform's server, with a short-lived token in
+ * `Authorization: Bearer`. The token is signed like a preview token, with the
+ * same deployment key, but made for this use only (`use: "revalidate"`): a
+ * preview token, which a framed page can see, can never purge a cache, and a
+ * revalidation token can never open a preview.
+ *
+ * Claims: `aud` the storefront origin, `theme` the key of the theme whose
+ * pages changed, `use: "revalidate"`, `iat`/`exp` at most five minutes apart,
+ * optional `sub`/`jti`.
+ */
+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 longest a revalidation token may live. */
+const MAX_LIFETIME_SECONDS = 5 * 60;
+const refuse = (status, reason) => ({ ok: false, status, reason });
+const refused = (reason) => refuse(403, `the token is refused: ${reason}`);
+/**
+ * Read a revalidation request. `{ ok: true }` only for a `POST` carrying a
+ * token made for revalidation, for this storefront (its origin is the
+ * token's `aud`) and this theme; otherwise a status to answer, and nothing
+ * is dropped.
+ */
+export async function readRevalidateRequest(request, options) {
+    if (options.publicKey === undefined || options.publicKey === "")
+        return refuse(404, "revalidation is not enabled on this storefront");
+    if (request.method !== "POST")
+        return refuse(405, "a revalidation is posted");
+    const bearer = /^Bearer ([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/.exec(request.headers.get("Authorization") ?? "");
+    if (bearer === null)
+        return refuse(401, "a revalidation carries its token as a bearer");
+    const verified = await verifiedPayload(bearer[1], options.publicKey);
+    if (!verified.ok)
+        return refused(verified.reason);
+    const { aud, theme, use, iat, exp, sub, jti } = verified.payload;
+    if (use !== "revalidate" ||
+        typeof aud !== "string" ||
+        typeof theme !== "string" ||
+        typeof iat !== "number" ||
+        typeof exp !== "number" ||
+        !Number.isFinite(iat) ||
+        !Number.isFinite(exp) ||
+        (sub !== undefined && typeof sub !== "string") ||
+        (jti !== undefined && typeof jti !== "string")) {
+        return refused("invalid-claims");
+    }
+    const timing = timingRefusal(iat, exp, options.now, MAX_LIFETIME_SECONDS);
+    if (timing !== null)
+        return refused(timing);
+    if (aud !== new URL(request.url).origin)
+        return refused("wrong-audience");
+    if (theme !== options.theme)
+        return refused("wrong-theme");
+    const claims = { aud, theme, use, iat, exp };
+    if (sub !== undefined)
+        claims.sub = sub;
+    if (jti !== undefined)
+        claims.jti = jti;
+    return { ok: true, claims };
+}

package/dist/server.d.ts

@@ -3,4 +3,6 @@ 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 type { RevalidateClaims, RevalidateRequest, RevalidateRequestOptions } from "./revalidate.js";
 export type { PreviewClaims, PreviewDraft, PreviewRequest, PreviewRequestOptions, PreviewTokenCheck, PreviewTokenOptions, PreviewTokenRefusal, } from "./preview.js";

package/dist/server.js

@@ -1,3 +1,4 @@
 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";

package/dist/signed-token.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The signed requests a deployment's key checks: a compact JWS signed with
+ * Ed25519 (`alg: "EdDSA"`), verified with the public key the storefront was
+ * deployed with. A storefront can check such a token, never make one. Each
+ * kind of request — a preview, a revalidation — checks its own claims on
+ * top of this.
+ */
+/** Why a signed token was refused. */
+export type SignedTokenRefusal = "malformed" | "unsupported-algorithm" | "invalid-key" | "bad-signature" | "invalid-claims" | "expired" | "not-yet-valid" | "too-long-lived" | "wrong-audience" | "wrong-theme";
+/** The token's payload once its signature checks out with `publicKey`. */
+export declare function verifiedPayload(token: string, publicKey: string | JsonWebKey): Promise<{
+    ok: true;
+    payload: Record<string, unknown>;
+} | {
+    ok: false;
+    reason: SignedTokenRefusal;
+}>;
+/** Why a token's times are refused at `now` (seconds; now by default), or null. */
+export declare function timingRefusal(iat: number, exp: number, now: number | undefined, maxLifetimeSeconds: number): SignedTokenRefusal | null;

package/dist/signed-token.js

@@ -0,0 +1,81 @@
+/**
+ * The signed requests a deployment's key checks: a compact JWS signed with
+ * Ed25519 (`alg: "EdDSA"`), verified with the public key the storefront was
+ * deployed with. A storefront can check such a token, never make one. Each
+ * kind of request — a preview, a revalidation — checks its own claims on
+ * top of this.
+ */
+/** Clock skew tolerated between the signer and the storefront. */
+const CLOCK_SKEW_SECONDS = 30;
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+function base64UrlBytes(value) {
+    if (!/^[A-Za-z0-9_-]*$/.test(value))
+        return null;
+    try {
+        const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (value.length % 4)) % 4));
+        return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    }
+    catch {
+        return null;
+    }
+}
+function base64UrlJson(value) {
+    const bytes = base64UrlBytes(value);
+    if (bytes === null)
+        return null;
+    try {
+        const parsed = JSON.parse(decoder.decode(bytes));
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function importKey(publicKey) {
+    try {
+        const jwk = typeof publicKey === "string" ? JSON.parse(publicKey) : publicKey;
+        if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || typeof jwk.x !== "string" || jwk.d !== undefined)
+            return null;
+        return await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, { name: "Ed25519" }, false, ["verify"]);
+    }
+    catch {
+        return null;
+    }
+}
+/** The token's payload once its signature checks out with `publicKey`. */
+export async function verifiedPayload(token, publicKey) {
+    const parts = typeof token === "string" ? token.split(".") : [];
+    if (parts.length !== 3)
+        return { ok: false, reason: "malformed" };
+    const [headerPart, payloadPart, signaturePart] = parts;
+    const header = base64UrlJson(headerPart);
+    const payload = base64UrlJson(payloadPart);
+    const signature = base64UrlBytes(signaturePart);
+    if (header === null || payload === null || signature === null)
+        return { ok: false, reason: "malformed" };
+    if (header.alg !== "EdDSA" || header.crit !== undefined)
+        return { ok: false, reason: "unsupported-algorithm" };
+    const key = await importKey(publicKey);
+    if (key === null)
+        return { ok: false, reason: "invalid-key" };
+    let valid = false;
+    try {
+        valid = await crypto.subtle.verify({ name: "Ed25519" }, key, signature, encoder.encode(`${headerPart}.${payloadPart}`));
+    }
+    catch {
+        valid = false;
+    }
+    return valid ? { ok: true, payload } : { ok: false, reason: "bad-signature" };
+}
+/** Why a token's times are refused at `now` (seconds; now by default), or null. */
+export function timingRefusal(iat, exp, now, maxLifetimeSeconds) {
+    const at = now ?? Math.floor(Date.now() / 1000);
+    if (exp <= at - CLOCK_SKEW_SECONDS)
+        return "expired";
+    if (iat > at + CLOCK_SKEW_SECONDS)
+        return "not-yet-valid";
+    if (exp - iat > maxLifetimeSeconds)
+        return "too-long-lived";
+    return null;
+}

package/package.json

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