@wocart/storefront 1.16.0 → 1.18.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.18.0 — 2026-10-21
+
+The basket carries the offer a shopper chose for a line, so a quantity tier
+that two offers share is priced as the shopper picked it.
+
+### Added
+
+- `BasketLine.offerId` (optional): the offer chosen for the line. `addLine`
+  keeps it; a plain add to the line keeps the chosen offer, and a later explicit
+  choice replaces it. A stored offer survives a reload; a value that is not a
+  string is dropped.
+- `toOrderItems` and `BasketStore.toOrderItems()` send `offerId` with the line,
+  so checkout and cart validation receive the choice. A line that chose no offer
+  sends none.
+
+## 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

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

@@ -1639,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/basket.js

@@ -107,6 +107,7 @@ function sanitizeLine(raw, maxQuantity) {
         unitPrice: Number.isFinite(unitPrice) && unitPrice >= 0 ? unitPrice : 0,
         href: typeof line.href === "string" ? line.href : undefined,
         image: typeof line.image === "string" ? line.image : undefined,
+        offerId: typeof line.offerId === "string" && line.offerId ? line.offerId : undefined,
     };
 }
 function normalizeLines(lines, maxLines, maxQuantity) {
@@ -119,6 +120,8 @@ function normalizeLines(lines, maxLines, maxQuantity) {
             existing.variantLabel ??= line.variantLabel;
             existing.image ??= line.image;
             existing.href ??= line.href;
+            // The newest explicit choice of offer wins; a plain add keeps the one chosen.
+            existing.offerId = line.offerId ?? existing.offerId;
         }
         else {
             merged.set(key, { ...line });
@@ -143,6 +146,7 @@ export function toOrderItems(lines) {
         variantLabel: line.variantLabel ?? undefined,
         quantity: line.quantity,
         pricePerUnit: line.unitPrice,
+        ...(line.offerId !== undefined ? { offerId: line.offerId } : {}),
     }));
 }
 /**

package/dist/domain.d.ts

@@ -75,6 +75,7 @@ export declare const BasketLineSchema: z.ZodObject<{
     unitPrice: z.ZodNumber;
     href: z.ZodOptional<z.ZodString>;
     image: z.ZodOptional<z.ZodString>;
+    offerId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type BasketLine = z.infer<typeof BasketLineSchema>;
 /**
@@ -106,6 +107,7 @@ export declare const BasketSchema: z.ZodObject<{
         unitPrice: z.ZodNumber;
         href: z.ZodOptional<z.ZodString>;
         image: z.ZodOptional<z.ZodString>;
+        offerId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Basket = z.infer<typeof BasketSchema>;

package/dist/domain.js

@@ -31,6 +31,11 @@ export const BasketLineSchema = z.object({
     unitPrice: z.number().finite().nonnegative(),
     href: z.string().min(1).optional(),
     image: z.string().min(1).optional(),
+    /**
+     * The offer the shopper chose for this line, when they picked a tier. The
+     * server still applies it only if it holds for the quantity.
+     */
+    offerId: z.string().min(1).max(200).optional(),
 });
 /**
  * The server-facing projection of a basket line. UI-only fields are omitted,

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.16.0",
+  "version": "1.18.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",