@wocart/storefront 2.2.0 → 3.1.0

package/dist/types.d.ts

@@ -64,38 +64,16 @@ export interface StorefrontLanguage {
     /** `<html dir>` for this language. */
     direction: "rtl" | "ltr";
 }
+/**
+ * The storefront's view of the store, in one language — `config.get()`.
+ * Every merchant text is in `locale`; a field holds exactly what a theme
+ * reads, nothing the server keeps to itself.
+ */
 export interface StoreConfig {
     id: string;
     name: string;
     domain: string | null;
     logo: MediaImage | null;
-    themeId: string;
-    /**
-     * @deprecated A store's colors and font are its theme's settings: declare
-     * them in `defineTheme({ settings })` and read `themeSettings`. This is the
-     * value saved before that, no longer editable; removed in 2.0.
-     */
-    primaryColor: string;
-    /**
-     * @deprecated A store's colors and font are its theme's settings: declare
-     * them in `defineTheme({ settings })` and read `themeSettings`. This is the
-     * value saved before that, no longer editable; removed in 2.0.
-     */
-    accentColor: string;
-    /**
-     * @deprecated A store's colors and font are its theme's settings: declare
-     * them in `defineTheme({ settings })` and read `themeSettings`. This is the
-     * value saved before that, no longer editable; removed in 2.0.
-     */
-    bgColor: string;
-    /**
-     * @deprecated A store's colors and font are its theme's settings: declare
-     * them in `defineTheme({ settings })` and read `themeSettings`. This is the
-     * value saved before that, no longer editable; removed in 2.0.
-     */
-    fontFamily: string;
-    /** @deprecated Always null; removed in 2.0. */
-    fontUrl: string | null;
     /** The store's primary language: a BCP 47 code such as `ar`. */
     lang: string;
     /**
@@ -105,23 +83,8 @@ export interface StoreConfig {
     locale: string;
     /** The published languages, primary first (always includes `lang`). */
     locales: StorefrontLanguage[];
-    /**
-     * The store's edits to this theme's text, one map per published language:
-     * `{ ar: { heroTitle: "…" } }`. Sent only to a client created with `theme`.
-     * A theme merges `contentOverrides[locale]` over its own pack for that
-     * language — never another language's map.
-     */
-    contentOverrides: Record<string, Record<string, string>>;
-    /**
-     * The merchant's values for this theme's settings, by setting key, exactly
-     * as saved — `{}` when there are none or the client was created without
-     * `theme`, absent from a server that predates theme settings. Read them
-     * against the theme's declaration with `resolveThemeSettings` from
-     * `@wocart/theme` (which takes either): a value the theme no longer accepts
-     * falls back to its default there.
-     */
-    themeSettings?: Record<string, unknown> | undefined;
     currency: string;
+    /** In `locale`: "دج" in Arabic reads "DA" in French. */
     currencySymbol: string;
     metaTitle: string | null;
     metaDescription: string | null;
@@ -129,47 +92,55 @@ export interface StoreConfig {
     ogImage: MediaImage | null;
     /** Where every image key is served from, and how it is resized: pass it to `mediaUrl`, `mediaImageUrl` and `pictureOf`. */
     media: MediaDelivery;
-    /**
-     * @deprecated Always null. An announcement is a theme's own content: declare
-     * it as a theme setting and read `themeSettings`. Removed in 2.0.
-     */
-    announcementBar: string | null;
     reviewsEnabled: boolean;
     /** When true the storefront renders the cart alongside the direct order form. */
     cartEnabled: boolean;
     /** Subtotal (DZD) at or above which delivery is free. null = no threshold. */
     freeShippingThreshold: number | null;
-    cartShippingMode: "highest" | "default_profile";
-    otpEnabled: boolean;
-    /** Cloudflare Turnstile — true only when a store_turnstile_config row exists AND is enabled. */
-    turnstileEnabled: boolean;
-    /** Public widget site key; null when Turnstile is disabled. The secret never leaves the server. */
-    turnstileSiteKey: string | null;
-    status: "active" | "inactive";
-    createdAt: string;
-    updatedAt: string;
+    /**
+     * The store's edits to this theme's text, one map per published language:
+     * `{ ar: { heroTitle: "…" } }`. Sent only to a client created with `theme`.
+     * A theme merges `contentOverrides[locale]` over its own pack for that
+     * language — never another language's map.
+     */
+    contentOverrides: Record<string, Record<string, string>>;
+    /**
+     * The merchant's values for this theme's settings, by setting key, exactly
+     * as saved — `{}` when there are none or the client was created without
+     * `theme`. Read them against the theme's declaration with
+     * `resolveThemeSettings` from `@wocart/theme`: a value the theme no longer
+     * accepts falls back to its default there.
+     */
+    themeSettings: Record<string, unknown>;
     checkoutForm: CheckoutFormPolicy;
+    /** The WhatsApp button, or null when the store has none. Read it through `whatsAppContact`. */
+    whatsapp: StoreWhatsAppWidget | null;
     pixelId: string | null;
     conversionEvent: "Purchase" | "Purchase_Confirmed" | "Purchase_Delivered" | "Lead";
     /**
-     * Published pages that opt into the footer, titled in the store's own
-     * language, ordered for display. The checkout consent line resolves Terms/
-     * Refund from here by `kind` — never a hardcoded slug, since a merchant may
-     * rename any page's slug freely.
+     * Published pages that opt into the footer, titled in `locale`, ordered for
+     * display. The checkout consent line resolves Terms/Refund from here by
+     * `kind` — never a hardcoded slug, since a merchant may rename any page's
+     * slug freely.
      */
     pages: StorePageLink[];
-    /**
-     * The public subset of the store's legal profile. Null until the merchant
-     * saves one from the dashboard (Settings → Store Pages) — RC/NIF are never
-     * exposed here, only inside the legal documents themselves.
-     */
-    legalContact: StoreLegalContact | null;
-    /** The WhatsApp contact widget, already resolved, or null when disabled. */
-    whatsapp: StoreWhatsAppWidget | null;
+    /** How a shopper reaches the store, besides WhatsApp: each null until the merchant writes it. */
+    contact: StoreContact;
+    otpEnabled: boolean;
+    /** Cloudflare Turnstile — true only when the store switched it on. */
+    turnstileEnabled: boolean;
+    /** Public widget site key; null when Turnstile is off. The secret never leaves the server. */
+    turnstileSiteKey: string | null;
 }
 /** The merchant's per-surface switches for the WhatsApp contact widget. */
 export type WidgetSurfaces = StoreWhatsAppWidget["surfaces"];
+/**
+ * The WhatsApp button App, as the server serves it: each text in the page's
+ * language, or null where the merchant wrote none in it — the theme's words
+ * then. A theme reads it through `whatsAppContact`, never field by field.
+ */
 export interface StoreWhatsAppWidget {
+    /** The chat link to the store's number, without a message. */
     href: string;
     agentName: string | null;
     caption: string | null;
@@ -203,11 +174,11 @@ export interface StorePageLink {
     title: string;
     position: number;
 }
-export interface StoreLegalContact {
-    contactEmail: string | null;
-    contactPhone: string | null;
-    deliveryMinDays: number;
-    deliveryMaxDays: number;
+/** How a shopper reaches the store — `StoreConfig.contact`. */
+export interface StoreContact {
+    phone: string | null;
+    email: string | null;
+    address: string | null;
 }
 /** A resolved store page — GET /store/pages/{slug}. */
 export interface StorePagePublic {
@@ -227,10 +198,10 @@ export interface StoreCollection {
     /** In the client's language when the store translated it, else the primary. */
     title: string;
     description: string | null;
-    /** How many products a shopper sees in it; absent from a server that predates it. */
-    productCount?: number | null | undefined;
-    /** Its first listed product's first photo, until a merchant can pick one; absent from a server that predates it. */
-    image?: ProductImage | null | undefined;
+    /** How many products a shopper sees in it. */
+    productCount: number;
+    /** Its first listed product's first photo, until a merchant can pick one; null while it lists none with one. */
+    image: ProductImage | null;
 }
 /** A navigation menu — GET /store/menus/{handle}. */
 export interface StoreMenu {
@@ -247,7 +218,7 @@ export interface StoreMenuItem {
      * it through `localizeHref` — or the absolute URL the merchant entered.
      */
     href: string;
-    /** The page type it opens (`home`, `catalog`, `category`, `product`, `page`, `landing`), or `url`. */
+    /** What it opens: a page type (`home`, `catalog`, `search`, `trackOrder`, `contact`, `category`, `collection`, `product`, `page`, `landing`), or `url`. */
     type: string;
     children: StoreMenuItem[];
 }
@@ -298,8 +269,8 @@ export interface LandingPage {
     };
     /**
      * 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), or null when it has none or the client names no theme: the
+     * theme then renders its `landing` default.
      */
     document: PageDocumentPayload | null;
 }
@@ -324,12 +295,12 @@ export interface CartValidationLine {
     unitPrice: number;
     /** What the line costs, offers and the coupon applied. */
     lineTotal: number;
-    /** The offer applied to the line; null or absent when none. */
-    offerId?: string | null | undefined;
-    /** That offer's name, in the shopper's language; null or absent when none. */
-    offerName?: string | null | undefined;
-    /** The line's share of the coupon's discount, already out of `lineTotal`; null or absent without one. */
-    discount?: number | null | undefined;
+    /** The offer applied to the line; null when none. */
+    offerId: string | null;
+    /** That offer's name, in the shopper's language; null when none. */
+    offerName: string | null;
+    /** The line's share of the coupon's discount, already out of `lineTotal`; 0 without one. */
+    discount: number;
     /** Units still available; null when the product is not stock-tracked. */
     maxQuantity: number | null;
     /**
@@ -338,17 +309,16 @@ export interface CartValidationLine {
      */
     blocker: "missing" | "unlisted" | "out_of_stock" | null;
 }
-/** A satisfied Buy-X-Get-Y reward, appended server-side at order time. */
 /** A gift the basket earns, as the order will give it: free, beside the lines. */
 export interface CartReward {
     offerId: string;
-    /** The offer's name, in the shopper's language; absent from an older server. */
-    offerName?: string | null | undefined;
+    /** The offer's name, in the shopper's language. */
+    offerName: string | null;
     productId: string | null;
     productName: string | null;
-    /** The variant given and its label; null for a product without variants, absent from an older server. */
-    variantId?: string | null | undefined;
-    variantLabel?: string | null | undefined;
+    /** The variant given and its label; null for a product without variants. */
+    variantId: string | null;
+    variantLabel: string | null;
     quantity: number;
 }
 /** The catalog's truth about a basket, right now. Read-only — nothing is written. */
@@ -362,6 +332,8 @@ export interface CartValidation {
         threshold: number | null;
         qualified: boolean;
         remaining: number;
+        /** Why delivery is free: an offer, the coupon or the store's amount; null when it is not. */
+        by: "offer" | "coupon" | "threshold" | null;
     };
     /**
      * Present when `validate` was given a destination: what the order would
@@ -371,8 +343,8 @@ export interface CartValidation {
      * deliver there, and an order to it is refused.
      */
     delivery?: CartDeliveryQuote | undefined;
-    /** What the code the quote was asked with did; null without one, absent from a server that predates coupons. */
-    coupon?: CouponOutcome | null | undefined;
+    /** What the code the quote was asked with did; null without one. */
+    coupon: CouponOutcome | null;
 }
 /**
  * Why a code does not apply. Open: a server may name a reason this SDK has not
@@ -413,8 +385,8 @@ export interface CreatedOrder {
     deliveryFee: number;
     /** price + deliveryFee, offers and the coupon applied. */
     total: number;
-    /** What the coupon took off; null or absent without one. */
-    couponDiscount?: number | null | undefined;
+    /** What the coupon took off; 0 without one. */
+    couponDiscount: number;
 }
 /** One basket line in a create-order body. */
 export interface CreateOrderItemInput {
@@ -573,7 +545,7 @@ export interface Review {
     createdAt: string;
     /** Rests on an order that reached its customer: show it as a verified purchase. */
     verified: boolean;
-    /** Photos first, then the voice note. Empty from servers before 1.6. */
+    /** Photos first, then the voice note. */
     media: ReviewMedia[];
 }
 /** One product of the shopper's order, as `products.reviews.eligibility()` answers it. */
@@ -613,8 +585,7 @@ export interface ReviewUpload {
 /** What a submitted review answers: published now, or after the store checks it. */
 export interface ReviewSubmitResult {
     id: string;
-    /** Absent from servers before 1.6. */
-    visibility?: "published" | "after_review" | undefined;
+    visibility: "published" | "after_review";
 }
 /**
  * Filters `products.list()` accepts — named so a theme can type its own
@@ -631,11 +602,9 @@ export interface ProductListFilters {
     collection?: string;
     /** Only products priced below their compare-at price. */
     onSale?: boolean;
-    /** @deprecated Use `collection: "featured"`. */
-    featured?: boolean;
     /**
      * The order. Absent: the listing's own — a collection's, a search's best
-     * match first, else newest. A server that predates sorting ignores it.
+     * match first, else newest.
      */
     sort?: ProductSort;
     /** Server-side cap; the server clamps anything larger. */
@@ -650,8 +619,8 @@ export interface ProductPage {
     items: ProductList[];
     /** True when another page follows this one. */
     hasNext: boolean;
-    /** How many products the whole listing holds, across its pages; null from a server that predates counts. */
-    total: number | null;
+    /** How many products the whole listing holds, across its pages. */
+    total: number;
 }
 /** `products.reviews.list()` paging — named for the same reason. */
 export interface ReviewListPagination {
@@ -665,12 +634,8 @@ export interface ReviewListPagination {
  */
 export interface ReviewInput {
     orderNumber: string;
-    /**
-     * The phone the order was placed with. Without it (the 1.5 shape) a review
-     * is text only and still needs a delivered order.
-     * @deprecated Omitting it is deprecated; a later major requires it.
-     */
-    phone?: string;
+    /** The phone the order was placed with. */
+    phone: string;
     productId: string;
     /** 1–5, the server validates the range. */
     rating: number;

package/dist/unavailable-store.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The store a page renders when its config cannot be read.
+ *
+ * Every theme needs one, and each used to write its own — with whatever
+ * fields the config had when it was written. It is the SDK's, so it always has
+ * the config's shape, and it decides once what a store we cannot read offers:
+ * nothing to buy. The cart, the checkout, the code by SMS, reviews and the
+ * WhatsApp button are off, so the page can never look like a working
+ * checkout; the theme renders its own words in its layout around it.
+ */
+import type { StoreConfig } from "./types.js";
+export interface UnavailableStoreOptions {
+    /** The store's server, as the theme's client is given it: a store that serves its own files serves them from its `/media`. */
+    serverUrl: string;
+    /** The page's language. Default: the platform's default language. */
+    locale?: string;
+}
+/**
+ * The config of a store that cannot be read, in `locale`, its only language —
+ * pass it as `resolveStoreRequest`'s `fallback`. Its `id` is empty: no store
+ * has that id, so a theme tells it from a real config by `config.id`.
+ */
+export declare function unavailableStoreConfig({ serverUrl, locale }: UnavailableStoreOptions): StoreConfig;

package/dist/unavailable-store.js

@@ -0,0 +1,58 @@
+/** The platform's default store language: a new store speaks it until the merchant picks another. */
+const DEFAULT_LOCALE = "ar";
+/**
+ * A language described by the runtime's own data: the platform's list of
+ * languages lives on the server, and an unreadable store has none to send.
+ */
+function describedLanguage(code) {
+    const locale = new Intl.Locale(code);
+    const info = locale.getTextInfo?.() ?? locale.textInfo;
+    const name = new Intl.DisplayNames([code], { type: "language" }).of(code) ?? code;
+    return {
+        code,
+        nativeName: name.charAt(0).toLocaleUpperCase(code) + name.slice(1),
+        direction: info?.direction === "rtl" ? "rtl" : "ltr",
+    };
+}
+/**
+ * The config of a store that cannot be read, in `locale`, its only language —
+ * pass it as `resolveStoreRequest`'s `fallback`. Its `id` is empty: no store
+ * has that id, so a theme tells it from a real config by `config.id`.
+ */
+export function unavailableStoreConfig({ serverUrl, locale = DEFAULT_LOCALE }) {
+    return {
+        id: "",
+        name: "",
+        domain: null,
+        logo: null,
+        lang: locale,
+        locale,
+        locales: [describedLanguage(locale)],
+        currency: "DZD",
+        currencySymbol: "DZD",
+        metaTitle: null,
+        metaDescription: null,
+        ogImage: null,
+        media: { kind: "direct", origin: `${serverUrl.replace(/\/+$/, "")}/media` },
+        reviewsEnabled: false,
+        cartEnabled: false,
+        freeShippingThreshold: null,
+        contentOverrides: {},
+        themeSettings: {},
+        checkoutForm: {
+            address: "hidden",
+            notes: "hidden",
+            email: "hidden",
+            deliveryOptions: { home: false, stopDesk: false },
+            customFields: [],
+        },
+        whatsapp: null,
+        pixelId: null,
+        conversionEvent: "Purchase",
+        pages: [],
+        contact: { phone: null, email: null, address: null },
+        otpEnabled: false,
+        turnstileEnabled: false,
+        turnstileSiteKey: null,
+    };
+}

package/dist/variant-picker.d.ts

@@ -10,8 +10,12 @@
  * or not made with the other choices.
  */
 import type { ProductVariant } from "./types.js";
-/** What the picker reads of a variant — a page may hand it a lighter copy than `ProductVariant`. */
-export type PickerVariant = Pick<ProductVariant, "variations" | "active" | "inventory" | "position" | "isDefault">;
+/**
+ * What the picker reads of a variant — a page may hand it a lighter copy than
+ * `ProductVariant`. A product's variants are its active ones, in the
+ * merchant's order: the picker takes them as they come.
+ */
+export type PickerVariant = Pick<ProductVariant, "variations" | "inventory" | "isDefault">;
 /** Option name → chosen value, as a product's `variantOptions` name them. */
 export type OptionSelection = Readonly<Record<string, string>>;
 export type OptionState = "available" | "sold_out" | "unavailable";

package/dist/variant-picker.js

@@ -1,20 +1,17 @@
-const live = (variant) => variant.active;
-const sellable = (product, variant) => live(variant) && (!product.trackInventory || variant.inventory > 0);
-const byPosition = (a, b) => a.position - b.position;
+const sellable = (product, variant) => !product.trackInventory || variant.inventory > 0;
 /** The variant whose every option has the value `selection` gives it, or null. */
 export function variantFor(variants, selection) {
-    return variants.find((variant) => live(variant) && Object.entries(variant.variations).every(([option, value]) => selection[option] === value)) ?? null;
+    return variants.find((variant) => Object.entries(variant.variations).every(([option, value]) => selection[option] === value)) ?? null;
 }
 /**
  * The variant a product page opens on: the merchant's default when it can be
  * sold, else the first that can, else the default (or first) shown sold out.
  */
 export function initialVariant(product) {
-    const ordered = product.variants.filter(live).sort(byPosition);
-    const preferred = ordered.find((variant) => variant.isDefault) ?? ordered[0] ?? null;
+    const preferred = product.variants.find((variant) => variant.isDefault) ?? product.variants[0] ?? null;
     if (preferred && sellable(product, preferred))
         return preferred;
-    return ordered.find((variant) => sellable(product, variant)) ?? preferred;
+    return product.variants.find((variant) => sellable(product, variant)) ?? preferred;
 }
 /**
  * The shopper picks `value` for `option`. The variant they mean is the one
@@ -24,8 +21,8 @@ export function initialVariant(product) {
  */
 export function pickOption(product, selection, option, value) {
     const kept = (variant) => Object.entries(selection).filter(([name, chosen]) => variant.variations[name] === chosen).length;
-    const candidates = product.variants.filter((variant) => live(variant) && variant.variations[option] === value);
-    const best = candidates.sort((a, b) => kept(b) - kept(a) || Number(sellable(product, b)) - Number(sellable(product, a)) || byPosition(a, b))[0];
+    const candidates = product.variants.filter((variant) => variant.variations[option] === value);
+    const best = candidates.sort((a, b) => kept(b) - kept(a) || Number(sellable(product, b)) - Number(sellable(product, a)))[0];
     return best ? { variant: best, selection: { ...best.variations } } : { variant: null, selection };
 }
 /**

package/dist/whatsapp.d.ts

@@ -6,7 +6,9 @@
  * 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:
+ * `whatsAppContact` is the one way a theme reads the store's WhatsApp: it
+ * picks the page's template, falls back to the theme's words, and applies
+ * three rules no theme re-invents:
  *
  * 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.
@@ -55,9 +57,60 @@ export declare function resolvePrefillText({ template, storeName, productName, u
 /** 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.
+ * A theme's own words for the WhatsApp button, in the page's language: what
+ * each text reads when the merchant left it empty. A theme has them in every
+ * language it speaks; the store's texts come translated or not at all. The
+ * panel's three optional texts take null when the theme shows nothing there.
  */
-export declare function localWhatsAppWidget(config: Pick<StoreConfig, "whatsapp" | "lang" | "locale">): StoreWhatsAppWidget | null;
+export interface WhatsAppWords {
+    /** The floating launcher's text; null: the launcher shows its icon alone. */
+    launcher: string | null;
+    /** The line under the agent's name; null: none. */
+    caption: string | null;
+    /** The panel's greeting; null: none, and a launcher may open the chat straight away. */
+    welcome: string | null;
+    /** The button that opens WhatsApp from the panel, and any other WhatsApp link's text. */
+    cta: string;
+    /** The button on an order's confirmation or tracking page. */
+    orderButton: string;
+    /** The message each kind of page starts the chat with; each may carry `{store}`, `{product}`, `{url}` and `{order}`. */
+    messages: Record<WhatsAppPage["kind"], string>;
+}
+/** What a page is about, for the message the chat starts with. */
+export interface WhatsAppPage {
+    /** A product or landing page names its product; an order's confirmation or tracking page its order. */
+    kind: "general" | "product" | "order";
+    /** The page's address, for `{url}`; its ad-click parameters are dropped. */
+    url: string;
+    product?: string | null | undefined;
+    order?: string | null | undefined;
+}
+/** The store's WhatsApp on one page, every text resolved — `whatsAppContact`. */
+export interface WhatsAppContact {
+    /** The chat link, with this page's message in it. */
+    href: string;
+    launcherLabel: string | null;
+    caption: string | null;
+    welcomeMessage: string | null;
+    ctaLabel: string;
+    orderButtonLabel: string;
+    /** Who the shopper writes to: the merchant's agent, else the store. */
+    agentName: string;
+    avatarUrl: string | null;
+    accent: StoreWhatsAppWidget["accent"];
+    position: StoreWhatsAppWidget["position"];
+    attention: boolean;
+    /** The pages the floating launcher shows on (`showsWidgetOn`); a link elsewhere on the page does not depend on it. */
+    surfaces: StoreWhatsAppWidget["surfaces"];
+}
+/**
+ * The store's WhatsApp for one page, or null when it has none: every link a
+ * theme draws to it — the launcher, a footer or menu link, a contact card,
+ * the order confirmation's button — comes from here, so each carries the
+ * page's message and every text is in the page's language.
+ *
+ * Each text is the merchant's when they wrote one, else the theme's `words`.
+ * The message is the page's own template (a product's, an order's), else the
+ * merchant's general one, else the theme's for that kind of page.
+ */
+export declare function whatsAppContact(config: Pick<StoreConfig, "whatsapp" | "name">, page: WhatsAppPage, words: WhatsAppWords): WhatsAppContact | null;

package/dist/whatsapp.js

@@ -69,17 +69,35 @@ 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.
+ * The store's WhatsApp for one page, or null when it has none: every link a
+ * theme draws to it — the launcher, a footer or menu link, a contact card,
+ * the order confirmation's button — comes from here, so each carries the
+ * page's message and every text is in the page's language.
+ *
+ * Each text is the merchant's when they wrote one, else the theme's `words`.
+ * The message is the page's own template (a product's, an order's), else the
+ * merchant's general one, else the theme's for that kind of page.
  */
-export function localWhatsAppWidget(config) {
+export function whatsAppContact(config, page, words) {
     const widget = config.whatsapp;
-    if (!widget || config.locale === config.lang)
-        return widget;
-    return { ...widget, ...Object.fromEntries(WIDGET_TEXTS.map((key) => [key, null])) };
+    if (!widget)
+        return null;
+    const own = page.kind === "product" ? widget.prefillProduct : page.kind === "order" ? widget.prefillThankYou : null;
+    const template = own ?? widget.prefillGeneral ?? words.messages[page.kind];
+    const message = resolvePrefillText({ template, storeName: config.name, productName: page.product ?? null, url: page.url, orderNumber: page.order ?? null });
+    return {
+        href: buildWhatsAppHref(widget.href, message),
+        launcherLabel: widget.launcherLabel ?? words.launcher,
+        caption: widget.caption ?? words.caption,
+        welcomeMessage: widget.welcomeMessage ?? words.welcome,
+        ctaLabel: widget.ctaLabel ?? words.cta,
+        orderButtonLabel: widget.thankYouButtonLabel ?? words.orderButton,
+        agentName: widget.agentName ?? config.name,
+        avatarUrl: widget.avatarUrl,
+        accent: widget.accent,
+        position: widget.position,
+        attention: widget.attention,
+        surfaces: widget.surfaces,
+    };
 }

package/package.json

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