@wocart/storefront 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.
 
+## 2.2.0 — 2026-11-01
+
+### Added
+
+- `localWhatsAppWidget(config)`: the WhatsApp widget as a page in
+  `config.locale` shows it. Its texts are written once, in the store's
+  primary language; on a page in another language they are null, so a theme
+  shows its own words in the shopper's language instead of the merchant's in
+  another one. The agent's name and every setting stay.
+
+### Fixed
+
+- `formatMoney` writes the currency symbol after the amount in every
+  language, as Algerian prices are written (`5 000 DA`, `5,000 DA`,
+  `5.000 دج`), joined by a no-break space so the two never wrap apart. French
+  and English put it before the amount (`DA 5 000`). Without a symbol it is
+  the amount alone, with no stray space.
+
+## 2.1.0 — 2026-10-31
+
+### Added
+
+- `LandingPage.document`: the page's own composition for the client's
+  `theme`, or null — a landing page and its document in one request. Null
+  from a server that predates it, and a malformed document reads as null.
+- `pages.landing(slug, { preview: true })` answers a draft page too and
+  counts no visit, for an editor's preview.
+- `countdownTarget`, `countdownEnd` and `timeLeft`: an offer countdown's end
+  — every midnight, or a day the merchant names, at its end or at a time —
+  in Algiers time, the same in the server's render and the browser.
+
+### Fixed
+
+- `pages.landing` sends the client's language, like every read that carries
+  merchant text: the page's product reaches a shopper in their language.
+
 ## 2.0.0 — 2026-10-30
 
 A store's images can live on any media host. The server answers every image

package/USAGE.md

@@ -223,7 +223,7 @@ 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) |
-| `resolvePrefillText`, `buildWhatsAppHref`, `stripTrackingParams`, `truncateAtWordBoundary`, `PREFILL_TOKENS`, `MAX_RESOLVED_PREFILL_LENGTH` | WhatsApp prefill text and the `wa.me` link |
+| `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 |
 | `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) |
 | `productImageSource` | Which photo represents a product (cover → gallery fallback) |
@@ -998,7 +998,19 @@ const landing = await store.pages.landing("summer-sale");
 
 A landing page can contain its own name, SEO metadata, image gap, images,
 product, publishedAt, and tracking information. The product may be null.
-Draft, archived, or unknown landing pages resolve to null.
+Draft, archived, or unknown landing pages resolve to null. Its product
+arrives in the client's language.
+
+A client created with `theme` also receives the page's own composition,
+`landing.document` (the page document `lp:<id>`), or null when it has none:
+render it with `@wocart/theme` against the theme's `landing` surface, which
+gives every landing page its starting document. An editor's preview reads a
+draft page too, and counts no visit, with `{ preview: true }` — never on a
+shopper's page:
+
+~~~ts
+const landing = await store.pages.landing(slug, { preview: true });
+~~~
 
 Landing tracking is already resolved by the server:
 
@@ -1010,6 +1022,21 @@ if (landing?.tracking.pixelId) {
 
 Do not invent tracking events from a landing-page slug.
 
+### An offer's countdown
+
+~~~ts
+import { countdownEnd, countdownTarget, timeLeft } from "@wocart/storefront";
+
+const ends = countdownTarget(settings.mode, settings.endsOn, settings.endsAt); // "midnight", "2026-11-30", "2026-11-30T18:30"
+const end = countdownEnd(ends);           // null: ended, or no real moment — show nothing
+const left = end === null ? null : timeLeft(end);
+~~~
+
+A countdown ends every day at midnight, or on a day the merchant names, at
+its end or at the time they give, in Algiers time. The server writes the time
+left; the browser keeps it running with the same functions. A countdown that
+has ended shows nothing, never zeros.
+
 ### The saved page document (theme composition)
 
 ~~~ts
@@ -1899,21 +1926,30 @@ 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.
+
 ~~~ts
 import {
   buildWhatsAppHref,
+  localWhatsAppWidget,
   resolvePrefillText,
 } from "@wocart/storefront";
 
+const widget = localWhatsAppWidget(config);
+if (!widget) return;
+
 const text = resolvePrefillText({
-  template: config.whatsapp.prefillProduct ?? "Hello {store}, about {product}: {url}",
+  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(config.whatsapp.href, text);
+const href = buildWhatsAppHref(widget.href, text);
 ~~~
 
 Three rules come with it, and a theme must not re-implement them:

package/dist/client/pages.d.ts

@@ -9,7 +9,8 @@
  * - `get(slug)` → null means "not published" — the theme 404s, never a
  *   soft 200 with empty content.
  * - `landing(slug)` → null means draft/archived/unknown — the theme
- *   redirects to the store home instead of a dead end.
+ *   redirects to the store home instead of a dead end. `{ preview: true }`
+ *   also answers a draft page and counts no visit: an editor's preview.
  */
 import { type ClientCore } from "./core.js";
 import type { LandingPage, StorePagePublic } from "../types.js";
@@ -22,10 +23,15 @@ export interface PagesNamespace {
     get(slug: string): Promise<StorePagePublic | null>;
     /**
      * Get a published landing page by its public slug: the ordered image
-     * stack, spacing settings, and the linked product in full store-product
-     * shape. Resolves to `null` for draft/archived/unknown slugs or failure.
+     * stack, spacing settings, the linked product in full store-product
+     * shape, and the page's own document for the client's `theme`. Resolves to
+     * `null` for draft/archived/unknown slugs or failure. With
+     * `{ preview: true }` a draft page answers too and no visit is counted —
+     * for an editor's preview only, never a shopper's page.
      */
-    landing(slug: string): Promise<LandingPage | null>;
+    landing(slug: string, options?: {
+        preview?: boolean;
+    }): Promise<LandingPage | null>;
 }
 /**
  * Create pages namespace

package/dist/client/pages.js

@@ -9,7 +9,8 @@
  * - `get(slug)` → null means "not published" — the theme 404s, never a
  *   soft 200 with empty content.
  * - `landing(slug)` → null means draft/archived/unknown — the theme
- *   redirects to the store home instead of a dead end.
+ *   redirects to the store home instead of a dead end. `{ preview: true }`
+ *   also answers a draft page and counts no visit: an editor's preview.
  */
 import { LandingPageSchema, StorePagePublicSchema } from "../schemas.js";
 import { STOREFRONT_OPERATIONS } from "../operations.js";
@@ -31,9 +32,12 @@ export function createPagesNamespace(core) {
                 return null;
             }
         },
-        async landing(slug) {
+        async landing(slug, options = {}) {
             try {
-                const landingPage = await core.get(`/store/landing-pages/${encodeURIComponent(slug)}`, LandingPageSchema.nullable(), { operation: STOREFRONT_OPERATIONS.pagesLanding });
+                const landingPage = await core.get(localizedPath(core.config, `/store/landing-pages/${encodeURIComponent(slug)}`, {
+                    theme: core.config.theme,
+                    preview: options.preview === true ? "1" : undefined,
+                }), LandingPageSchema.nullable(), { operation: STOREFRONT_OPERATIONS.pagesLanding });
                 return landingPage ?? null;
             }
             catch (error) {

package/dist/countdown.d.ts

@@ -0,0 +1,28 @@
+/**
+ * An offer countdown's end, as the store sets it: every day at midnight, or
+ * a day the merchant names — at its end or at the time they give — in
+ * Algiers time (UTC+1 all year). An end already past, or a day or time that
+ * does not exist, is no countdown at all: a shopper never sees zeros. Runs
+ * the same on the server, which writes the time left, and in the browser,
+ * which keeps it running.
+ */
+/** What a countdown counts to: `midnight`, a day (`YYYY-MM-DD`) or a day at a time (`YYYY-MM-DDTHH:MM`). */
+export type CountdownEnd = "midnight" | string;
+/** The time left, in whole units. */
+export interface TimeLeft {
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+}
+/**
+ * What a countdown's settings count to: `mode` `midnight` or `date`, the
+ * day the merchant typed (`YYYY-MM-DD`) and, optionally, the time
+ * (`HH:MM`). Undefined when they count to nothing — no day for `date`, or
+ * any other mode.
+ */
+export declare function countdownTarget(mode: string | undefined, endsOn: string | undefined, endsAt: string | undefined): CountdownEnd | undefined;
+/** When a countdown ends, as an instant (ms since the epoch); null when it has ended or names no real moment. */
+export declare function countdownEnd(ends: CountdownEnd | undefined, now?: number): number | null;
+/** The time left until `end`, in whole days, hours, minutes and seconds; zero once it has passed. */
+export declare function timeLeft(end: number, now?: number): TimeLeft;

package/dist/countdown.js

@@ -0,0 +1,55 @@
+/**
+ * An offer countdown's end, as the store sets it: every day at midnight, or
+ * a day the merchant names — at its end or at the time they give — in
+ * Algiers time (UTC+1 all year). An end already past, or a day or time that
+ * does not exist, is no countdown at all: a shopper never sees zeros. Runs
+ * the same on the server, which writes the time left, and in the browser,
+ * which keeps it running.
+ */
+const ALGERIA_OFFSET_MS = 60 * 60 * 1000;
+const MOMENT = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2}))?$/;
+const TIME = /^(\d{1,2}):(\d{2})$/;
+/**
+ * What a countdown's settings count to: `mode` `midnight` or `date`, the
+ * day the merchant typed (`YYYY-MM-DD`) and, optionally, the time
+ * (`HH:MM`). Undefined when they count to nothing — no day for `date`, or
+ * any other mode.
+ */
+export function countdownTarget(mode, endsOn, endsAt) {
+    if (mode === "midnight")
+        return "midnight";
+    const day = endsOn?.trim() ?? "";
+    if (mode !== "date" || day === "")
+        return undefined;
+    const time = TIME.exec(endsAt?.trim() ?? "");
+    return time ? `${day}T${time[1].padStart(2, "0")}:${time[2]}` : day;
+}
+/** When a countdown ends, as an instant (ms since the epoch); null when it has ended or names no real moment. */
+export function countdownEnd(ends, now = Date.now()) {
+    if (ends === undefined || ends === "")
+        return null;
+    if (ends === "midnight") {
+        const local = new Date(now + ALGERIA_OFFSET_MS);
+        return Date.UTC(local.getUTCFullYear(), local.getUTCMonth(), local.getUTCDate() + 1) - ALGERIA_OFFSET_MS;
+    }
+    const match = MOMENT.exec(ends.trim());
+    if (!match)
+        return null;
+    const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+    const check = new Date(Date.UTC(year, month - 1, day));
+    if (check.getUTCMonth() !== month - 1 || check.getUTCDate() !== day)
+        return null;
+    let end = Date.UTC(year, month - 1, day + 1) - ALGERIA_OFFSET_MS;
+    if (match[4] !== undefined) {
+        const [hours, minutes] = [Number(match[4]), Number(match[5])];
+        if (hours > 23 || minutes > 59)
+            return null;
+        end = Date.UTC(year, month - 1, day, hours, minutes) - ALGERIA_OFFSET_MS;
+    }
+    return end > now ? end : null;
+}
+/** The time left until `end`, in whole days, hours, minutes and seconds; zero once it has passed. */
+export function timeLeft(end, now = Date.now()) {
+    const total = Math.max(0, Math.floor((end - now) / 1000));
+    return { days: Math.floor(total / 86400), hours: Math.floor((total % 86400) / 3600), minutes: Math.floor((total % 3600) / 60), seconds: total % 60 };
+}

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { isMediaKey, mediaImageSrcset, mediaImageUrl, mediaUrl, pictureOf } from
 export type { MediaDelivery, MediaDeliveryKind, MediaImage, MediaImageParams, MediaImageSrcsetOptions, PickedImage, Picture } from "./utils/image.js";
 export { productImageSource } from "./utils/product-image.js";
 export type { ProductImageSourceInput } from "./utils/product-image.js";
-export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, } from "./whatsapp.js";
+export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, localWhatsAppWidget, } from "./whatsapp.js";
 export type { PrefillToken, ResolvePrefillParams } from "./whatsapp.js";
 export { STOREFRONT_PAGE_PATHS, STOREFRONT_ROUTES, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";
 export { servedLanguage } from "./locales.js";
@@ -49,6 +49,8 @@ export * from "./domain.js";
 export * from "./operations.js";
 export * from "./product-view.js";
 export { getOfferTierView, getQuantityTierViews } from "./offer-view.js";
+export { countdownEnd, countdownTarget, timeLeft } from "./countdown.js";
+export type { CountdownEnd, TimeLeft } from "./countdown.js";
 export { COUPON_HINT_REASONS, COUPON_NOT_APPLICABLE, COUPON_REFUSAL_REASONS, COUPON_URL_PARAM, couponFromUrl, couponRefusalOf, couponRefusalTone, } from "./coupon.js";
 export { initialVariant, optionStates, pickOption, variantFor } from "./variant-picker.js";
 export type { OptionSelection, OptionState, PickerVariant } from "./variant-picker.js";

package/dist/index.js

@@ -12,7 +12,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, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, } from "./whatsapp.js";
+export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, localWhatsAppWidget, } from "./whatsapp.js";
 export { STOREFRONT_PAGE_PATHS, STOREFRONT_ROUTES, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";
 export { servedLanguage } from "./locales.js";
 export { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "./locale-routing.js";
@@ -36,6 +36,7 @@ export * from "./domain.js";
 export * from "./operations.js";
 export * from "./product-view.js";
 export { getOfferTierView, getQuantityTierViews } from "./offer-view.js";
+export { countdownEnd, countdownTarget, timeLeft } from "./countdown.js";
 export { COUPON_HINT_REASONS, COUPON_NOT_APPLICABLE, COUPON_REFUSAL_REASONS, COUPON_URL_PARAM, couponFromUrl, couponRefusalOf, couponRefusalTone, } from "./coupon.js";
 export { initialVariant, optionStates, pickOption, variantFor } from "./variant-picker.js";
 export { ABANDONED_CHECKOUT_SESSION_KEY, convertAbandonedCheckout, createAbandonedCheckoutTracker, createBrowserAbandonedCheckoutTracker, } from "./abandoned-checkout.js";

package/dist/schemas.d.ts

@@ -746,6 +746,11 @@ export declare const LandingPageSchema: z.ZodObject<{
             rewardUnitPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    document: z.ZodDefault<z.ZodCatch<z.ZodNullable<z.ZodObject<{
+        version: z.ZodNumber;
+        surface: z.ZodString;
+        sections: z.ZodArray<z.ZodUnknown>;
+    }, z.core.$loose>>>>;
     tracking: z.ZodObject<{
         pixelId: z.ZodNullable<z.ZodString>;
         conversionEvent: z.ZodEnum<{

package/dist/schemas.js

@@ -341,6 +341,7 @@ export const LandingPageSchema = z.object({
     publishedAt: z.string().nullable(),
     images: z.array(LandingPageImageSchema),
     product: ProductSchema.nullable(),
+    document: PageDocumentPayloadSchema.nullable().catch(null).default(null),
     tracking: z.object({
         pixelId: z.string().nullable(),
         conversionEvent: z.enum([

package/dist/types.d.ts

@@ -296,6 +296,12 @@ export interface LandingPage {
         pixelId: string | null;
         conversionEvent: "Lead" | "Purchase" | "Purchase_Confirmed" | "Purchase_Delivered";
     };
+    /**
+     * The page's own composition for the client's `theme` (its `lp:<id>`
+     * document), or null when it has none, the client names no theme, or the
+     * server predates it: the theme then renders its `landing` default.
+     */
+    document: PageDocumentPayload | null;
 }
 export interface Wilaya {
     id: number;

package/dist/utils/money.d.ts

@@ -2,7 +2,7 @@
  * Deep Money Formatter
  *
  * One formatter for every price a storefront shows.
- * Handles locale-aware formatting, RTL symbol positioning, and Arabic-Indic digits.
+ * Handles locale-aware formatting and Arabic-Indic digits; the symbol follows the amount.
  *
  * Design principle: ONE function that handles all cases. Callers curry if needed.
  */
@@ -26,14 +26,14 @@ export interface MoneyFormatOptions {
  * // Arabic: 5,000 دج (with Arabic-Indic digits)
  * formatMoney(5000, { symbol: 'دج', locale: 'ar-DZ' })
  *
- * // French: DA 5 000,00
- * formatMoney(5000, { symbol: 'DA', locale: 'fr-FR' })
+ * // French: 5 000,00 DA
+ * formatMoney(5000, { symbol: 'DA', locale: 'fr-FR', decimals: 2 })
  *
- * // English: DA 5,000.00
+ * // English: 5,000 DA
  * formatMoney(5000, { symbol: 'DA', locale: 'en-US' })
- *
- * // No decimals: 5,000 دج
- * formatMoney(5000, { symbol: 'دج', locale: 'ar-DZ', decimals: 0 })
  * ```
+ *
+ * The symbol follows the amount in every language, as Algerian prices are
+ * written, joined by a no-break space so the two never wrap apart.
  */
 export declare function formatMoney(amount: number, options: MoneyFormatOptions): string;

package/dist/utils/money.js

@@ -2,7 +2,7 @@
  * Deep Money Formatter
  *
  * One formatter for every price a storefront shows.
- * Handles locale-aware formatting, RTL symbol positioning, and Arabic-Indic digits.
+ * Handles locale-aware formatting and Arabic-Indic digits; the symbol follows the amount.
  *
  * Design principle: ONE function that handles all cases. Callers curry if needed.
  */
@@ -18,15 +18,15 @@
  * // Arabic: 5,000 دج (with Arabic-Indic digits)
  * formatMoney(5000, { symbol: 'دج', locale: 'ar-DZ' })
  *
- * // French: DA 5 000,00
- * formatMoney(5000, { symbol: 'DA', locale: 'fr-FR' })
+ * // French: 5 000,00 DA
+ * formatMoney(5000, { symbol: 'DA', locale: 'fr-FR', decimals: 2 })
  *
- * // English: DA 5,000.00
+ * // English: 5,000 DA
  * formatMoney(5000, { symbol: 'DA', locale: 'en-US' })
- *
- * // No decimals: 5,000 دج
- * formatMoney(5000, { symbol: 'دج', locale: 'ar-DZ', decimals: 0 })
  * ```
+ *
+ * The symbol follows the amount in every language, as Algerian prices are
+ * written, joined by a no-break space so the two never wrap apart.
  */
 export function formatMoney(amount, options) {
     const { symbol, locale, decimals = 0 } = options;
@@ -35,9 +35,5 @@ export function formatMoney(amount, options) {
         minimumFractionDigits: decimals,
         maximumFractionDigits: decimals,
     });
-    // RTL-aware symbol positioning
-    // Arabic: suffix (5,000.00 دج)
-    // French/English: prefix (DA 5,000.00)
-    const isRTL = locale.startsWith("ar");
-    return isRTL ? `${formatted} ${symbol}` : `${symbol} ${formatted}`;
+    return symbol ? `${formatted}\u00A0${symbol}` : formatted;
 }

package/dist/whatsapp.d.ts

@@ -16,6 +16,7 @@
  * 3. **The encoded text is appended the same way everywhere**, so a base href
  *    that already carries a query string keeps it.
  */
+import type { StoreConfig, StoreWhatsAppWidget } from "./types.js";
 /**
  * The hard cap on a resolved prefill message, in characters.
  *
@@ -53,3 +54,10 @@ export interface ResolvePrefillParams {
 export declare function resolvePrefillText({ template, storeName, productName, url, orderNumber, }: ResolvePrefillParams): string;
 /** Appends the resolved message to a `wa.me` href, encoded and query-safe. */
 export declare function buildWhatsAppHref(baseHref: string, text: string): string;
+/**
+ * The WhatsApp widget as a page in `config.locale` shows it. The merchant
+ * writes its texts once, in the store's primary language (`config.lang`), so
+ * a page in another language gets them as null and shows the theme's own
+ * words in its language instead; the agent's name and every setting stay.
+ */
+export declare function localWhatsAppWidget(config: Pick<StoreConfig, "whatsapp" | "lang" | "locale">): StoreWhatsAppWidget | null;

package/dist/whatsapp.js

@@ -1,21 +1,3 @@
-/**
- * WhatsApp prefill messages — the storefront's message rule.
- *
- * A storefront's WhatsApp launcher hands the shopper to WhatsApp with the
- * message already written. The template belongs to the merchant (the dashboard
- * authors it within the limits below), and the page
- * resolves it: `{store}`, `{product}`, `{url}`, `{order}`.
- *
- * Three rules live here so no theme re-invents them:
- *
- * 1. **Ad-click parameters are stripped from `{url}`.** A shopper arriving from
- *    a paid ad should not hand the merchant's WhatsApp a `fbclid`-laden link.
- * 2. **The resolved message is capped at `MAX_RESOLVED_PREFILL_LENGTH`, cut at
- *    a word boundary.** Browsers and WhatsApp both truncate silently past a
- *    point; a cut mid-word reads as a broken store.
- * 3. **The encoded text is appended the same way everywhere**, so a base href
- *    that already carries a query string keeps it.
- */
 /**
  * The hard cap on a resolved prefill message, in characters.
  *
@@ -87,3 +69,17 @@ export function buildWhatsAppHref(baseHref, text) {
     const separator = baseHref.includes("?") ? "&" : "?";
     return `${baseHref}${separator}text=${encodeURIComponent(text)}`;
 }
+/** The widget's texts the merchant writes once, in the store's primary language. */
+const WIDGET_TEXTS = ["caption", "welcomeMessage", "launcherLabel", "ctaLabel", "prefillGeneral", "prefillProduct", "thankYouButtonLabel", "prefillThankYou"];
+/**
+ * The WhatsApp widget as a page in `config.locale` shows it. The merchant
+ * writes its texts once, in the store's primary language (`config.lang`), so
+ * a page in another language gets them as null and shows the theme's own
+ * words in its language instead; the agent's name and every setting stay.
+ */
+export function localWhatsAppWidget(config) {
+    const widget = config.whatsapp;
+    if (!widget || config.locale === config.lang)
+        return widget;
+    return { ...widget, ...Object.fromEntries(WIDGET_TEXTS.map((key) => [key, null])) };
+}

package/package.json

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