@wocart/storefront 2.2.0 → 3.1.0

package/CHANGELOG.md

@@ -5,6 +5,144 @@ 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
+product reads name every field they answer, and the SDK asks for no field the
+server no longer sends nor tolerates an answer from an older server. The
+WhatsApp button speaks every language, and a theme reaches it one way.
+Requires platform v7.0.0.
+
+### Added
+
+- `whatsAppContact(config, page, words)`: the store's WhatsApp on one page —
+  the `wa.me` link with the page's message, and every text resolved: the
+  merchant's in the page's language, else the theme's `words`; the agent the
+  merchant's, else the store's name. Null when the store has none. Every
+  WhatsApp link a theme draws comes from it. Types `WhatsAppContact`,
+  `WhatsAppPage`, `WhatsAppWords`.
+- `unavailableStoreConfig({ serverUrl, locale })`: the store a page renders
+  when its config cannot be read — nothing to buy, its one language described
+  by the runtime. A theme passes it as `resolveStoreRequest`'s `fallback`
+  instead of writing its own.
+- Page types `search` (`/search`) and `contact` (`/contact`); like
+  `trackOrder`, they show the widget by the App's `pages` switch.
+- `StoreConfig.contact`: `{ phone, email, address }`, each null until the
+  merchant writes it.
+- `CartValidation.freeDelivery.by`: why delivery is free — `offer`, `coupon`
+  or `threshold` — or null.
+
+### Changed (breaking)
+
+- The WhatsApp widget's texts arrive in the page's language, or null where
+  the merchant wrote none in it — never another language's.
+- `ProductList.variantOptions` and `ProductList.tags` arrive parsed, as on a
+  product page.
+- `Product.variants` holds only the active variants, in the merchant's
+  order: `ProductVariant` drops `productId`, `currency`, `barcode`,
+  `weightKg`, `active`, `position`, `createdAt` and `updatedAt`, and the
+  variant picker takes the variants as they come.
+- Required, where they were optional for older servers:
+  `StoreConfig.themeSettings`, `ProductPage.total` (0 on a failed read, never
+  null), `StoreCollection.productCount` and `image`, `Offer.rewardUnitPrice`,
+  `Product.quantityPricing`, the product `metaTitle` and `metaDescription`,
+  `LandingPage.document`, `Review.verified` and `media`,
+  `ReviewSubmitResult.visibility`,
+  `CreatedOrder.couponDiscount`, a cart quote's `coupon`, a line's `offerId`,
+  `offerName` and `discount`, and a gift's `offerName`, `variantId` and
+  `variantLabel`. `ReviewInput.phone` is required.
+
+### Removed
+
+- `StoreConfig.primaryColor`, `accentColor`, `bgColor`, `fontFamily`,
+  `fontUrl` and `announcementBar` (a theme's settings now), `themeId`,
+  `cartShippingMode`, `status`, `createdAt`, `updatedAt`, and `legalContact`
+  (`contact` replaces it; the delivery days stay on the store's legal
+  pages).
+- `Product.costPrice`, `storeFeatured`, `deletedAt`, `visibility`, `status`,
+  `showInStore`, `publishedAt`, `createdAt`, `updatedAt` and
+  `shippingProfileId`, and `ProductListFilters.featured` (use
+  `collection: "featured"`).
+- `localWhatsAppWidget`, `resolvePrefillText`, `buildWhatsAppHref`,
+  `stripTrackingParams`, `truncateAtWordBoundary` and `ResolvePrefillParams`:
+  `whatsAppContact` applies the message rules itself. Removed without a
+  deprecated minor first: the platform they served changes with this major.
+- `productTags`: both product shapes carry their tags as a list.
+- `STOREFRONT_ROUTES` and `StorefrontRoute` (use `STOREFRONT_PAGE_PATHS`),
+  `resolveActionRedirectDecision` and `PrgDecision` (use `runFormAction`), and
+  `ActionMiddlewareDeps.referer` and `pathname`.
+
 ## 2.2.0 — 2026-11-01
 
 ### Added

package/USAGE.md

@@ -112,6 +112,8 @@ break those links.
 | `checkout` | `/checkout` | the cart's checkout | required when the store turns the cart on |
 | `thankYou` | `/thank-you` | the order confirmation | required |
 | `trackOrder` | `/track-order` | where a shopper follows an order by its number and phone; `?order=<number>` fills the number in | required |
+| `search` | `/search` | the products a shopper's words find; `?q=<words>` is the query | required — a menu can open it |
+| `contact` | `/contact` | how to reach the store: its WhatsApp (`whatsAppContact`) and `config.contact` | required — a menu can open it |
 
 How a theme implements them, in Astro's own terms:
 
@@ -139,8 +141,8 @@ How a theme implements them, in Astro's own terms:
 `showsWidgetOn(surfaces, pathname)` is the platform's half of "should the
 WhatsApp widget show here": the merchant switches surfaces on; the page type
 says which surface a pathname is. `STOREFRONT_PAGE_PATHS` is the table above
-as data. `STOREFRONT_ROUTES` is deprecated: it lists six of the paths, without
-the home and the catalog.
+as data. Order tracking, search and contact count as store pages: the App's
+`pages` switch shows the widget on them.
 
 ## The five rules to remember
 
@@ -181,7 +183,7 @@ request-scoped client is the simplest safe default:
 ~~~ts
 const [config, featuredProducts] = await Promise.all([
   store.config.get(),
-  store.products.list({ featured: true, limit: 8 }),
+  store.products.list({ collection: "featured", limit: 8 }),
 ]);
 ~~~
 
@@ -223,9 +225,10 @@ server directly.
 | `isWilayaId` | Whether a value is a wilaya id — the range `WilayaIdSchema` checks on the server, without a schema in the browser |
 | `readShippingRates`, `readCouponOutcome` | Read in the browser what the server handed it — the rates a page carries, a quote's coupon outcome — accepting exactly what `ShippingRatesSchema` / `CouponOutcomeSchema` accept, without Zod |
 | `normalizeAlgerianPhone`, `toLocalAlgerianMobile` | The one Algerian phone rule (accept/format) |
-| `localWhatsAppWidget`, `resolvePrefillText`, `buildWhatsAppHref`, `stripTrackingParams`, `truncateAtWordBoundary`, `PREFILL_TOKENS`, `MAX_RESOLVED_PREFILL_LENGTH` | the widget in the page's language, WhatsApp prefill text and the `wa.me` link |
+| `whatsAppContact`, `PREFILL_TOKENS`, `MAX_RESOLVED_PREFILL_LENGTH` | The store's WhatsApp on one page: the `wa.me` link with the page's message and every text in the page's language — the only way a theme links to WhatsApp |
 | `storefrontPath`, `matchStorefrontPath`, `STOREFRONT_PAGE_PATHS` | The page types and their public paths: build a link, recognise a page |
-| `showsWidgetOn`, `STOREFRONT_ROUTES` | Which widget surface a pathname is (`STOREFRONT_ROUTES` deprecated) |
+| `showsWidgetOn` | Which widget surface a pathname is |
+| `unavailableStoreConfig` | The store a page renders when its config cannot be read — `resolveStoreRequest`'s `fallback` |
 | `productImageSource` | Which photo represents a product (cover → gallery fallback) |
 | `getProductView`, `getProductListView` | Pure price, discount, default-variant, and stock values for detail and list projections |
 | `getOfferTierView` | Pure offer-tier price, compare-price, savings, and free-shipping projection; display-only, never order authority |
@@ -372,8 +375,9 @@ Read methods use safe empty results so a theme can still render its shell:
 | orders.tracking(orderId) | null |
 
 These results do not mean the theme should crash. They mean the theme should
-show a deliberate fallback: a default brand shell, an empty catalog state, a
-not-found page, a delivery-rate fallback, or no conversion event.
+show a deliberate fallback: the unavailable store (`unavailableStoreConfig`),
+an empty catalog state, a not-found page, a delivery-rate fallback, or no
+conversion event.
 
 ### When a read degrades: `onError`
 
@@ -515,29 +519,29 @@ const cartEnabled = config?.cartEnabled === true;
 const currencySymbol = config?.currencySymbol ?? "دج";
 ~~~
 
-StoreConfig contains the current store identity and presentation fields,
-including:
+StoreConfig holds what a theme reads of the store, every merchant text in
+the page's language (`locale`):
 
-- name, domain, logo (a MediaImage) and themeId (the colors, fontFamily and fontUrl
-  fields are deprecated: colors and fonts are theme settings, read from
-  themeSettings);
-- lang (the primary language), locales, contentOverrides, themeSettings,
-  currency, currencySymbol, metaTitle, metaDescription, and ogImage (a
-  MediaImage);
+- id, name, domain and logo (a MediaImage);
+- lang (the primary language), locale, locales, currency, currencySymbol,
+  metaTitle, metaDescription, and ogImage (a MediaImage);
 - media, the store's MediaDelivery, which every image helper takes;
-- reviewsEnabled (announcementBar is deprecated and always null: an
-  announcement is a theme's own setting);
-- cartEnabled, freeShippingThreshold, and cartShippingMode;
+- reviewsEnabled, cartEnabled and freeShippingThreshold;
+- contentOverrides and themeSettings, the merchant's edits to your theme;
 - checkoutForm policy;
-- OTP and Turnstile settings;
+- whatsapp, the WhatsApp button App — read it through `whatsAppContact`;
 - pixelId and conversionEvent;
-- public page links, legal contact information, and WhatsApp widget settings.
+- pages (the footer's page links) and contact (`{ phone, email, address }`,
+  each null until the merchant writes it);
+- OTP and Turnstile settings.
+
+A store's colours, fonts and announcement are your theme's settings, never
+config fields: declare them with `defineTheme({ settings })`.
 
 `themeSettings` holds the merchant's values for your theme's settings (the
 ones it declares with `defineTheme({ settings })` in `@wocart/theme`), by
 setting key, exactly as saved. It is sent only to a client created with
-`theme`, is `{}` when the store saved none, and is absent from a server that
-predates theme settings — `resolveThemeSettings` takes either. Never read it raw: resolve it
+`theme`, and is `{}` when the store saved none. Never read it raw: resolve it
 against your declaration, which checks every value and falls back to your
 default for one it no longer accepts:
 
@@ -628,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.
@@ -767,18 +778,17 @@ const onSale = await store.products.list({ onSale: true, limit: 8 });
   `store.collections.get(handle)` — title and description in the client's
   language, `null` for an unknown handle (answer a real 404) — and list it
   with `products.list({ collection: handle })`.
-- `featured: true` and `ProductList.storeFeatured` are deprecated: they mean
-  the `featured` collection.
+- The store's featured products are its `featured` collection:
+  `products.list({ collection: "featured" })`.
 
 A collection's page also has its size and a photo: `collections.get(handle)`
 answers `productCount` (what a shopper sees in it) and `image` (its first
-listed product's first photo, a `ProductImage`), both absent from a server
-that predates them.
+listed product's first photo, a `ProductImage`, null while it lists none with
+one).
 
 **Pages, totals and order.** `products.page(filters)` answers one page,
 whether another follows, and how many products the whole listing holds
-(`total`, null from a server that predates counts) — enough for "page 2 of 5"
-or "36 products":
+(`total`) — enough for "page 2 of 5" or "36 products":
 
 ~~~ts
 const page = await store.products.page({ collection: "best-sellers", sort: "price-ascending", limit: 24, offset: 24 });
@@ -791,15 +801,13 @@ const page = await store.products.page({ collection: "best-sellers", sort: "pric
 `DEFAULT_COLLECTION_HANDLES` names the collections every store starts with,
 the likeliest to hold products first, for a page that needs one and was named
 none. Without one a listing keeps
-its own order: a collection's, a search's best match first, else newest. A
-server that predates sorting ignores it.
+its own order: a collection's, a search's best match first, else newest.
 
 **Search.** `products.search(text, filters)` answers a page of the products
 whose name — in the client's language or the catalog's — or tags hold every
 word, with the same filters, sort and paging; names that hold every word come
-first. Blank text finds nothing without asking. Search has its own path, so a
-server that predates it answers an empty page (reported through `onError`),
-never the whole catalog:
+first. Blank text finds nothing without asking, and a failed search answers an
+empty page (reported through `onError`), never the whole catalog:
 
 ~~~ts
 const results = await store.products.search(Astro.url.searchParams.get("q") ?? "", { limit: 24 });
@@ -807,9 +815,10 @@ const results = await store.products.search(Astro.url.searchParams.get("q") ?? "
 
 Product lists return ProductList objects. ProductList and Product are
 different shapes: a list item is not a detail object and must not be cast to
-Product. ProductList carries list-oriented fields such as coverImage and
-reviewStats, while variantOptions and tags remain their raw serialized form.
-Read tags with `productTags(product)`, which gives a list from either shape.
+Product. Both carry the same product fields — variantOptions and tags parsed,
+metaTitle, metaDescription and reviewStats — and a ProductList adds its
+coverImage, a Product its photos, active variants (in the merchant's order),
+offers, quantity pricing and category.
 
 The limit is optional. An explicit limit of 0 is preserved, so do not replace
 it with a truthiness fallback.
@@ -1676,11 +1685,67 @@ 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. resolveActionRedirectDecision, the earlier
-name, is deprecated and now always answers next.
+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
 
@@ -1690,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:
 
@@ -1698,7 +1765,8 @@ theme builds its own context from it:
 // src/middleware.ts
 import { resolvePreviewStore, resolveStoreRequest, runFormAction } from "@wocart/storefront/astro";
 
-const options = { client: createStore, fallback: FALLBACK_CONFIG }; // the theme's one client factory, and its shell config
+// The theme's one client factory, and the store it renders when the config cannot be read.
+const options = { client: createStore, fallback: unavailableStoreConfig({ serverUrl: env.COD_SERVER_URL }) };
 
 export const onRequest = defineMiddleware(async (context, next) => {
   if (context.url.pathname === THEME_PREVIEW_PATH) {
@@ -1717,7 +1785,11 @@ export const onRequest = defineMiddleware(async (context, next) => {
 
 `client(locale?)` makes the request's client, in a language or the
 store's primary; `fallback` is the config rendered when the store cannot be
-read — a shell with the checkout off. `embedded(pathname)` overrides which
+read. `unavailableStoreConfig({ serverUrl, locale })` is that config, in your
+theme's default language (the platform's, Arabic, when you name none): no
+name, nothing to buy — cart, checkout, code by SMS, reviews and WhatsApp off —
+and an empty `id`, by which a theme tells it from a real store. It always has
+the config's whole shape, so never write your own. `embedded(pathname)` overrides which
 paths serve part of a page. `resolvePreviewStore(draft, options)` is the
 editor's preview: the draft's language when the store serves it, the draft's
 settings and text over the saved ones, tracking off.
@@ -1778,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;
@@ -1919,52 +2006,59 @@ image; `null` means the product genuinely has no photograph, so that is the
 moment to render a placeholder. The list model carries no gallery at all, so a
 card gets the cover or `null`.
 
-## WhatsApp prefill messages
+## WhatsApp
 
-The storefront's WhatsApp launcher hands the shopper to WhatsApp with a message
-already written, and the thank-you page offers the same handoff for an order.
-The template belongs to the merchant — the dashboard authors and previews it
-within the platform's limits — while the page resolves it:
-
-The merchant writes the widget's texts once, in the store's primary language.
-Read the widget with `localWhatsAppWidget(config)`: on a page in another
-language its texts (labels, welcome, prefills) are null, so the theme shows its
-own words in the shopper's language; the agent's name and the settings stay.
+The WhatsApp button App owns the store's WhatsApp: its number, its texts,
+which pages show the floating launcher, how it looks. Your theme owns only
+how it is drawn. Every link a theme draws to WhatsApp — the launcher, a
+footer or menu link, a contact card, the thank-you and tracking buttons —
+comes from one function, `whatsAppContact(config, page, words)`, and none is
+written by hand:
 
 ~~~ts
-import {
-  buildWhatsAppHref,
-  localWhatsAppWidget,
-  resolvePrefillText,
-} from "@wocart/storefront";
-
-const widget = localWhatsAppWidget(config);
-if (!widget) return;
-
-const text = resolvePrefillText({
-  template: widget.prefillProduct ?? "Hello {store}, about {product}: {url}",
-  storeName: config.name,
-  productName: product.name, // falls back to the store name when absent
-  url: Astro.url.href,       // ad-click parameters (`utm_*`, `fbclid`) stripped
-  orderNumber: null,         // resolves to nothing when absent
-});
-
-const href = buildWhatsAppHref(widget.href, text);
-~~~
-
-Three rules come with it, and a theme must not re-implement them:
-
-- the resolved message is capped at `MAX_RESOLVED_PREFILL_LENGTH` characters and
-  cut at a word boundary, because browsers and WhatsApp both truncate silently
-  past a point;
-- `{url}` never carries ad-click parameters;
-- the encoded `text=` is appended to the base href, preserving a query string
-  the href already carries.
-
-`PREFILL_TOKENS` is the token vocabulary the dashboard offers (`product`, `url`,
-`order`, `store`); an unknown placeholder is left verbatim so a template typo is
-visible rather than silently swallowed. The cap and the token list are the
-same ones the dashboard enforces.
+import { showsWidgetOn, whatsAppContact } from "@wocart/storefront";
+
+const whatsapp = whatsAppContact(
+  config,
+  { kind: "product", url: canonical, product: product.name },
+  {
+    launcher: null, // the launcher shows its icon alone unless the merchant names it
+    caption: t("whatsapp.caption"),
+    welcome: t("whatsapp.welcome"),
+    cta: t("whatsapp.cta"),
+    orderButton: t("whatsapp.order"),
+    messages: { general: t("whatsapp.message"), product: t("whatsapp.messageProduct"), order: t("whatsapp.messageOrder") },
+  },
+);
+const launcherShown = whatsapp !== null && showsWidgetOn(whatsapp.surfaces, store.pathname);
+// whatsapp.href, whatsapp.ctaLabel, whatsapp.welcomeMessage, whatsapp.agentName …
+~~~
+
+It answers `null` when the store has no WhatsApp (the App is off, or has no
+usable number). Otherwise every text is resolved for this page:
+
+- **The merchant's text, else your words.** `/store/config` serves each of
+  the App's texts in the page's language, or null where the merchant wrote
+  none in it — never another language's. A null reads your `words`, which
+  your theme has in every language it speaks. `caption`, `welcome` and
+  `launcher` may be null in your words too: the panel then shows nothing
+  there.
+- **The page's message.** `page.kind` is `product` (a product or landing
+  page, with `product` its name), `order` (the thank-you or tracking page,
+  with `order` its number) or `general`. The merchant's template for that
+  kind is used, else their general one, else yours for that kind.
+- **The agent** is the merchant's, else the store's name.
+
+The message follows three rules no theme re-implements: it is capped at
+`MAX_RESOLVED_PREFILL_LENGTH` characters, cut at a word boundary, because
+browsers and WhatsApp both truncate silently past a point; `{url}` never
+carries ad-click parameters (`utm_*`, `fbclid`); and the encoded `text=` keeps
+a query string the number's link already carries.
+
+`PREFILL_TOKENS` is the token vocabulary the dashboard offers (`product`,
+`url`, `order`, `store`); an unknown placeholder is left verbatim so a
+template typo is visible rather than silently swallowed. The cap and the
+token list are the same ones the dashboard enforces.
 
 ## The sitemap
 
@@ -2021,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