@wocart/storefront 1.22.0 → 2.0.0

package/CHANGELOG.md

@@ -5,6 +5,68 @@ 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.0.0 — 2026-10-30
+
+A store's images can live on any media host. The server answers every image
+as a `MediaImage` and the store's config says how its images are delivered;
+the image helpers take that delivery instead of a media domain. Requires a
+store server that answers this shape.
+
+### Changed (breaking)
+
+- Every image is a `MediaImage`, `{ key, url, width, height }`: a product
+  image (`ProductImageSchema`) and a landing image carry `key` and `url`
+  (`src`, `srcSm`, `srcMd`, `srcLg` are gone); a category has `image` (was
+  `imageUrl`); `StoreConfig` has `logo` (was `logoUrl`) and `ogImage` as
+  images.
+- `StoreConfig.media` (`MediaDelivery`, `{ kind, origin }`): where every key is
+  served from, and how it is resized — `imagekit`, `cloudflare`, or `direct`.
+- `mediaUrl(key, delivery)`, `mediaImageUrl(url, params, delivery)`,
+  `mediaImageSrcset(url, widths, { delivery })` and `pictureOf(image,
+  delivery)` take the store's delivery (was a media domain). `mediaImageUrl`
+  builds ImageKit's `?tr=` or Cloudflare's `/cdn-cgi/image/`, and answers
+  `null` for a `direct` delivery.
+- `productImageSource` reads `url`.
+
+### Removed
+
+- `optimizeImage`, `generateSrcSet`, `IMAGE_SIZES`, `getCardImage`,
+  `getGalleryImage`, `getThumbnailImage`, `getHeroImage`, `getCategoryImage`,
+  `getLogoImage`, `createImageHelpers` and their types: each took a media
+  domain, which no longer exists. Use `mediaImageUrl` and `mediaImageSrcset`
+  with the size a page shows. They are removed without a deprecating minor
+  because no media domain is left for them to take.
+
+### Added
+
+- `isMediaKey`, `MediaImage`, `MediaDelivery`, `MediaDeliveryKind`,
+  `MediaImageSchema` and `MediaDeliverySchema`.
+
+### Changed
+
+- The README is short and points to the documentation at docs.wocart.store.
+
+## 1.23.0 — 2026-10-25
+
+One checkout, one order: a double click, a refreshed submission or a retry
+after a dropped connection no longer places the order twice. And an order
+records the language it was placed in.
+
+### Added
+
+- `bindCheckoutKey(form)`: puts a `checkoutKey` on every submission a checkout
+  form makes, through its `formdata` event. The key stays the same while the
+  shopper changes nothing and is drawn anew once they change any field; it is
+  drawn at the first submission, never rendered into a cached page. Returns a
+  function that unbinds it.
+- `placeOrderInput` and `CreateOrderInput` take `checkoutKey`, a UUID. The same
+  key again answers with the order it already placed, exactly as the first
+  time; for another phone it fails with `CHECKOUT_KEY_IN_USE`. Without a key,
+  every order is placed as before.
+- `orders.create` sends the client's `locale`: the order records the
+  language the shopper checked out in (the primary when the store does not
+  publish it), and the customer's messages are written in it.
+
 ## 1.22.0 — 2026-10-24
 
 What moving Theme-00 onto the SDK showed every theme needs: an add reported

package/README.md

@@ -1,20 +1,13 @@
 # @wocart/storefront
 
 The storefront SDK for [Wocart](https://github.com/bighadj22/codflow), the
-cash-on-delivery commerce platform for Algeria. It gives a storefront theme
-typed, validated access to a store's catalog, delivery prices, basket,
-checkout, OTP and order tracking — and keeps prices, rules and secrets on the
-server.
+cash-on-delivery commerce platform for Algeria. It gives a storefront typed,
+validated access to a store's catalog, delivery prices, basket, checkout, OTP,
+order tracking and images — and keeps prices, rules and secrets on the server.
 
-- **Typed and validated.** Every server response is parsed against a schema
-  before your code sees it.
-- **Predictable failures.** Reads never throw: they resolve to `null`, `[]` or
-  `{}` and report through `onError`. Writes return a result whose failure always
-  carries a structured `DomainError`.
-- **Browser-safe by construction.** The root entry exports no client and no
-  secret; the store API key lives behind `@wocart/storefront/server`.
-- **Framework-neutral core, Astro adapters.** Proxy routes, form actions and
-  the POST/Redirect/GET middleware decision for Astro, with no Astro import.
+**Documentation: [docs.wocart.store/sdk/storefront](https://docs.wocart.store/sdk/storefront)**
+— also in [French](https://docs.wocart.store/fr/sdk/storefront) and
+[Arabic](https://docs.wocart.store/ar/sdk/storefront).
 
 ## Install
 
@@ -22,123 +15,35 @@ server.
 npm install @wocart/storefront zod
 ```
 
-`zod` (4.x) is a peer dependency: the SDK's schemas are part of its API — you
-can validate with them, and you pass your own schemas to `createProxyEndpoint` —
-so your app and the SDK share one copy. npm 7 and later install it
-automatically. ESM only. Runs in browsers, Cloudflare Workers, Node and Astro server
-runtimes; tooling needs Node 22.12 or newer.
+`zod` 4 is a peer dependency. ESM only; Node 22.12 or newer for tooling.
 
 ## Quick start
 
 ```ts
 import { createStoreClient } from "@wocart/storefront/server";
+import { mediaImageUrl } from "@wocart/storefront";
 
-// Server-side only: a page frontmatter, endpoint, action or middleware.
-const store = createStoreClient({
-  serverUrl: env.COD_SERVER_URL, // your store's API origin
-  apiKey: env.STORE_API_KEY,     // server-only secret
-  onError: (error) => console.warn(error.operation, error.code, error.requestId),
-});
+const store = createStoreClient({ serverUrl: env.COD_SERVER_URL, apiKey: env.STORE_API_KEY });
 
-// Reads: typed, validated, safe to render straight away.
-const [config, products] = await Promise.all([
-  store.config.get(),                                // StoreConfig | null
-  store.products.list({ featured: true, limit: 8 }), // ProductList[]
-]);
-const product = await store.products.get("blue-t-shirt"); // Product | null
-
-// Writes: a discriminated result, never a thrown HTTP error.
-const result = await store.orders.create({
-  customerName: "أمين",
-  phone: "0555123456",
-  wilayaId: 16,
-  communeId: "c-16-001",
-  items: [{ productId: "p-1", productName: "Blue T-Shirt", quantity: 1 }],
-});
-
-if (result.success) {
-  console.log(result.data.orderNumber, result.data.total);
-} else {
-  console.error(result.domainError.category, result.domainError.message);
-}
-```
-
-## Entry points
-
-| 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 — 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
-(for example `src/pages/api/cart.ts`), which call the SDK on the server:
-
-```ts
-// In the browser: no client, no key.
-import { createBasketStore, formatMoney } from "@wocart/storefront";
+const config = await store.config.get();
+const product = await store.products.get("blue-t-shirt");
+const photo = product?.images[0];
+const src = photo && config ? mediaImageUrl(photo.url, { width: 480, fit: "cover", format: "auto" }, config.media) ?? photo.url : null;
 ```
 
-## What the client covers
-
-| Namespace | Use it for |
-| --- | --- |
-| `config` | store identity, branding, languages, checkout policy, feature flags |
-| `products` | catalog lists, product detail, reviews |
-| `categories` | catalog navigation |
-| `pages` | legal and CMS pages, landing pages |
-| `pageData` | the store's saved page document for a surface (render it with [`@wocart/theme`](https://www.npmjs.com/package/@wocart/theme)) |
-| `shipping` | home and stop-desk delivery prices per wilaya |
-| `geo` | wilayas and communes |
-| `cart` | server re-pricing and validation of a browser basket |
-| `orders` | order creation, OTP, abandoned checkout, conversion tracking |
-
-## How errors work
+Reads never throw: they resolve to `null`, `[]` or `{}` and report through
+`onError`. Writes return `{ success, data }` or a structured `domainError`.
 
-- **Reads** resolve to the empty value (`null`, `[]`, `{}`) so a page still
-  renders, and report the cause to `onError` as a `DomainError` with
-  `category`, `code`, `retryable`, `sideEffect`, `operation` and `requestId`.
-- **Writes** return `ClientResult<T>`: `{ success: true, data }` or
-  `{ success: false, error, domainError }`. Branch on
-  `result.domainError.category` — `validation`, `authentication`, `business`,
-  `system`, `transport` — instead of status codes.
-- **Setup errors are loud.** An empty `serverUrl` or `apiKey` throws
-  `MISSING_CONFIGURATION` when the client is created, instead of quietly
-  turning every read into an empty store.
-
-## Configuration
+## Entry points
 
-| Option | Required | Notes |
+| Import | Runs in | Holds |
 | --- | --- | --- |
-| `serverUrl` | yes | your store's API origin |
-| `apiKey` | yes | the store API key, sent as `X-Store-API-Key`; server-only |
-| `locale` | no | read merchant text in a published store language (`"fr"`); one client per language |
-| `theme` | no | your theme's key (`defineTheme({ key })`), to receive the merchant's edits to your theme's text |
-| `onError` | no | observability hook for degraded reads |
-| `readTimeoutMs` | no | how long one read may take, retries included, before it degrades (default 10 000; `0` for no limit) |
-
-A storefront deployed by Wocart receives its origin and key as the
-`COD_SERVER_URL` and `STORE_API_KEY` environment variables. The SDK reads no
-environment variables itself; pass the values in. In Astro, declare the key as
-a server secret (`envField.string({ context: "server", access: "secret" })`)
-and never expose it as a public variable.
-
-## Documentation
-
-- [USAGE.md](./USAGE.md) — the full guide: every namespace and the UI decisions
-  it implies, checkout and OTP, Astro actions and proxy routes, languages,
-  images, and a definition of done for a new theme.
-- [CHANGELOG.md](./CHANGELOG.md) — what changed in each release.
-
-## Compatibility
+| `@wocart/storefront` | browser and server | types and schemas, reference data, money and image helpers, basket and OTP state |
+| `@wocart/storefront/server` | server only | `createStoreClient` — the store API key lives here — preview and revalidation checks |
+| `@wocart/storefront/astro` | server only | proxy routes, form actions, `placeOrderInput` |
 
-- Follows [semantic versioning](https://semver.org/). Breaking changes ship
-  only in a new major version and are listed in the changelog.
-- Response schemas ignore fields they do not know, so a newer server never
-  breaks an older SDK; a response missing a required field degrades the read
-  and reports it.
-- Astro 7 is verified. The Astro adapters are structural and import nothing
-  from Astro.
+[USAGE.md](./USAGE.md) ships with the package for offline reading;
+[CHANGELOG.md](./CHANGELOG.md) lists every release.
 
 ## License
 

package/USAGE.md

@@ -214,10 +214,11 @@ server directly.
 
 | Export | Use it for |
 | --- | --- |
-| `formatMoney`, `optimizeImage`, `generateSrcSet` | Money text and image URLs |
-| `mediaImageUrl` | The Cloudflare resizing URL of a media-domain image, served by the media domain itself (any storefront host); `null` for any other image — the builder behind every image helper and `@wocart/theme/image-service` |
-| `mediaUrl(key, mediaDomain)` | The public URL of a stored media key — what a theme's `image` field holds (`{ key: "products/…" }`): `mediaUrl(image.key, MEDIA_DOMAIN)`; `null` with no media domain or a key that cannot name an object. The key is the identity; the URL is derived at render |
-| `createImageHelpers(mediaDomain)`, `getCardImage`, `getGalleryImage`, `getThumbnailImage`, `getHeroImage`, `getCategoryImage`, `getLogoImage` | The bound image toolkit (`IMAGE_SIZES` holds the presets) |
+| `formatMoney` | Money text |
+| `mediaImageUrl(url, params, config.media)` | A store image at the size and format a page shows it, from the store's delivery (ImageKit `?tr=` or Cloudflare `/cdn-cgi/image/`); `null` for an image the delivery does not serve, or a `direct` delivery — the builder behind `@wocart/theme/image-service` |
+| `mediaImageSrcset(url, widths, { delivery })` | The same image at several widths, for `srcset` |
+| `mediaUrl(key, config.media)`, `isMediaKey` | The URL of a Media Key — what a theme's `image` field holds (`{ key: "products/…" }`); `null` without a delivery or for a value that is not a key |
+| `pictureOf(image, config.media)` | A picked image ready for an `<img>`: URL, alt, size, focal point |
 | `WILAYAS`, `ALGERIA_COMMUNES`, `communesForWilaya` | Reference data: 58 wilayas, 1,551 communes, one wilaya's rows |
 | `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 |
@@ -236,6 +237,7 @@ server directly.
 | `basketLineKey`, `toOrderItems`, `MAX_BASKET_LINES`, `MAX_BASKET_LINE_QUANTITY` | Basket identity, the wire projection, and the caps the server re-checks |
 | `createOtpMachine` | The OTP step's state machine |
 | `createOtpTransport`, `mapOtpResponse`, `otpTransportFailure` | Route-agnostic OTP result mapping; the theme supplies its same-origin route functions |
+| `bindCheckoutKey` | One checkout attempt, one order: the key a checkout form's submissions carry |
 | `createAbandonedCheckoutTracker` | Port-injected session, capture eligibility, debounce, update, cookie, fetch, and exit-beacon policy |
 | `STOREFRONT_OPERATIONS` | The exact operation labels used by namespace calls |
 | `STOREFRONT_RETRY_POLICIES` | Which operations retry, by exact operation label |
@@ -260,7 +262,7 @@ not add a local product-view or offer-price module around them.
 | --- | --- | --- |
 | `serverUrl` | yes | Your store's API origin. No default: a wrong origin must be a visible mistake, not a silent one. |
 | `apiKey` | yes | The store's API key. Sent as `X-Store-API-Key` on every request. **Server-only.** |
-| `locale` | no | The language to read merchant text in — see "Store languages". |
+| `locale` | no | The language to read merchant text in, and the one an order is recorded in — see "Store languages". |
 | `theme` | no | Your theme's key, to receive the merchant's edits to your theme's text — see "Store languages". |
 | `onError` | no | Observability hook for degraded reads — see "When a read degrades: onError". |
 
@@ -289,7 +291,6 @@ storefront deployed by Wocart receives these:
 | --- | --- | --- |
 | `COD_SERVER_URL` | server variable | the store's API origin, e.g. `https://api.your-store.com` |
 | `STORE_API_KEY` | server secret | the store API key |
-| `MEDIA_DOMAIN` | server variable (optional) | media domain for `createImageHelpers(mediaDomain)`; unset → image URLs pass through unchanged |
 
 Never put `STORE_API_KEY` in a browser-exposed variable (no `PUBLIC_*`, no
 `import.meta.env` in client code, no HTML attribute). In Astro, declare it in
@@ -517,11 +518,13 @@ const currencySymbol = config?.currencySymbol ?? "دج";
 StoreConfig contains the current store identity and presentation fields,
 including:
 
-- name, domain, logoUrl and themeId (the colors, fontFamily and fontUrl
+- 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;
+  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;
@@ -1258,6 +1261,32 @@ CreatedOrder contains the order ID, customer-facing order number, product
 price, delivery fee, and total, all in whole DZD — and `couponDiscount`, what
 the order's coupon took off.
 
+### One checkout, one order
+
+A shopper who double-clicks, refreshes the thank-you page's POST, or retries
+after a dropped connection sends the same checkout again. Give the order its
+`checkoutKey` and the server places it once: the same key again answers with
+the order it already placed, exactly as the first time — no second order, no
+second stock deduction, no second notification. For another phone the key
+fails with `CHECKOUT_KEY_IN_USE`; without a key, every call places an order.
+
+In the browser, bind the key to the checkout form once:
+
+~~~ts
+import { bindCheckoutKey } from "@wocart/storefront";
+
+bindCheckoutKey(document.querySelector("form.order-form")!);
+~~~
+
+It adds `checkoutKey` to every submission the form makes, through the form's
+`formdata` event, so a native submit and a `new FormData(form)` both carry it.
+The key stays the same while the shopper changes nothing and is drawn anew
+once they change any field, so a different order is never answered with the
+one already placed. It is drawn at the first submission, never rendered into
+the page: a storefront page is cached and served to every shopper.
+`placeOrderInput` passes the key through; the function `bindCheckoutKey`
+returns unbinds it.
+
 ### Coupons
 
 A coupon is a code the shopper types. It applies after offers, only to the
@@ -1800,53 +1829,46 @@ price presentation does not drift between cards, product pages, and checkout.
 
 ### Images
 
+Every image the store's server answers is a `MediaImage` — `{ key, url,
+width, height }` — and the store's config carries `media`, its
+`MediaDelivery`: the origin every key is served from and how that origin
+resizes (`imagekit`, `cloudflare`, or `direct` for files served as stored).
+Pass `config.media` to the image helpers; one theme then works on every host a
+store can use.
+
 ~~~ts
-import {
-  generateSrcSet,
-  getCardImage,
-  optimizeImage,
-} from "@wocart/storefront";
+import { mediaImageUrl } from "@wocart/storefront";
 
-const mediaDomain = env.MEDIA_DOMAIN;
-const originalImage = product.images[0]?.src ?? "";
-const cardImage = getCardImage(originalImage, mediaDomain);
-const src = optimizeImage(originalImage, {
-  width: 480,
-  height: 480,
-  quality: 82,
-  format: "auto",
-  fit: "cover",
-}, mediaDomain);
-const srcSet = generateSrcSet(originalImage, 480, 480, mediaDomain);
+const photo = product.images[0];
+const card = photo ? mediaImageUrl(photo.url, { width: 480, height: 480, fit: "cover", format: "auto", quality: 82 }, config.media) ?? photo.url : null;
 ~~~
 
-The image utility accepts the original media URL and can target a media
-domain. Use it to produce appropriately sized URLs rather than downloading
-original assets into every card.
+`mediaImageUrl` answers `null` for an image its delivery does not serve and
+for a `direct` delivery, which does not resize: show the original then.
 
 For an image whose width changes with the screen, give the browser widths and
 let `sizes` choose — a phone then downloads a phone-sized file.
-`mediaImageSrcset(src, widths, { mediaDomain, ratio, quality })` gives one
-size per width with width descriptors, cropped to `ratio` (height ÷ width)
-when given; null off the media domain:
+`mediaImageSrcset(src, widths, { delivery, ratio, quality })` gives one size
+per width with width descriptors, cropped to `ratio` (height ÷ width) when
+given and never enlarged past the original otherwise:
 
 ~~~astro
 <img
-  src={mediaImageUrl(src, { width: 720, format: "auto" }, mediaDomain) ?? src}
-  srcset={mediaImageSrcset(src, [360, 540, 720, 1080], { mediaDomain, ratio: 1.25 }) ?? undefined}
+  src={mediaImageUrl(src, { width: 720, fit: "scale-down", format: "auto" }, config.media) ?? src}
+  srcset={mediaImageSrcset(src, [360, 540, 720, 1080], { delivery: config.media, ratio: 1.25 }) ?? undefined}
   sizes="(min-width: 1024px) 25vw, 50vw"
   alt="" loading="lazy" />
 ~~~
 
-A photo a merchant picks for a section is stored as a media key with its alt
-text, size and focal point. `pictureOf(image, mediaDomain)` turns it into what
+A photo a merchant picks for a section is stored as a Media Key with its alt
+text, size and focal point. `pictureOf(image, config.media)` turns it into what
 an `<img>` needs — `src`, `alt` (empty when none was written), `width`,
 `height` and `position`, the focal point as CSS `object-position` — or null
 when none is picked:
 
 ~~~astro
 ---
-const picture = pictureOf(props.image, mediaDomain);
+const picture = pictureOf(props.image, config.media);
 ---
 {picture && <img src={picture.src} alt={picture.alt} width={picture.width} height={picture.height} style={{ objectPosition: picture.position }} />}
 ~~~
@@ -1859,10 +1881,10 @@ thumbnail. `productImageSource` answers which image represents the product, so
 a cart drawer, a checkout summary and a product card cannot disagree:
 
 ~~~ts
-import { getThumbnailImage, productImageSource } from "@wocart/storefront";
+import { mediaImageUrl, productImageSource } from "@wocart/storefront";
 
 const src = productImageSource(product); // Product | ProductList
-const thumbnail = src ? getThumbnailImage(src) : null;
+const thumbnail = src ? mediaImageUrl(src, { width: 160, height: 160, fit: "cover", format: "auto" }, config.media) ?? src : null;
 ~~~
 
 It prefers the merchant's cover and falls back to the first usable gallery
@@ -1870,40 +1892,6 @@ 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`.
 
-Available semantic helpers include:
-
-- getCardImage;
-- getGalleryImage;
-- getThumbnailImage;
-- getHeroImage;
-- getCategoryImage;
-- getLogoImage.
-
-The helper chooses the appropriate image role. The theme still owns layout,
-aspect ratio, alt text, lazy loading, placeholders, and art direction.
-
-#### Bind the media domain once
-
-Do not thread the media domain through every call site — a missed argument
-silently ships an unoptimized image. Bind it once and use the URL-only helper
-set:
-
-~~~ts
-import { createImageHelpers } from "@wocart/storefront";
-
-const images = createImageHelpers(env.MEDIA_DOMAIN);
-
-const thumbnail = images.getThumbnailImage(product.images[0].src);
-const preview = images.getCardImage(product.images[0].src);
-const srcSet = images.generateSrcSet(product.images[0].src, 480, 480);
-~~~
-
-The returned toolkit exposes the same helpers plus `optimizeImage`,
-`generateSrcSet`, and `IMAGE_SIZES`. With no domain bound, every helper returns
-the original URL unchanged, so a store without a media domain needs no branch —
-and `optimizeImage` / `generateSrcSet` still take a per-call domain that
-overrides the bound one.
-
 ## WhatsApp prefill messages
 
 The storefront's WhatsApp launcher hands the shopper to WhatsApp with a message

package/dist/abandoned-checkout.d.ts

@@ -1,4 +1,5 @@
 import type { AbandonedCheckoutInput } from "./domain.js";
+import { type UuidSource } from "./utils/uuid.js";
 export type AbandonedCheckoutSnapshot = Omit<AbandonedCheckoutInput, "sessionId" | "fbc" | "fbp">;
 export interface AbandonedCheckoutStorage {
     getItem(key: string): string | null;
@@ -29,9 +30,7 @@ export declare function createAbandonedCheckoutTracker(ports: AbandonedCheckoutP
 /** What the browser wiring uses of the page; the page's own globals by default. */
 export interface AbandonedCheckoutHost {
     readonly sessionStorage?: Pick<Storage, "getItem" | "setItem" | "removeItem">;
-    readonly crypto?: Pick<Crypto, "getRandomValues"> & {
-        randomUUID?: () => string;
-    };
+    readonly crypto?: UuidSource;
     readonly document?: {
         readonly cookie: string;
     };

package/dist/abandoned-checkout.js

@@ -1,4 +1,5 @@
 import { toLocalAlgerianMobile } from "./phone.js";
+import { uuidV4 } from "./utils/uuid.js";
 /**
  * Where the browser keeps the checkout's id for the tab (`sessionStorage`):
  * every capture of one checkout updates one record, and the thank-you page
@@ -110,7 +111,7 @@ export function createBrowserAbandonedCheckoutTracker(options, host = globalThis
             getItem: (key) => host.sessionStorage?.getItem(key) ?? null,
             setItem: (key, value) => host.sessionStorage?.setItem(key, value),
         },
-        createId: () => uuid(host),
+        createId: () => uuidV4(host.crypto ?? globalThis.crypto),
         schedule: (callback, delayMs) => host.setTimeout(callback, delayMs),
         cancel: (handle) => host.clearTimeout(handle),
         readCookie: (name) => cookieValue(host.document?.cookie ?? "", name),
@@ -154,14 +155,3 @@ function cookieValue(cookies, name) {
     }
     return undefined;
 }
-/** A version 4 UUID: the platform's `randomUUID`, else one drawn from `getRandomValues`. */
-function uuid(host) {
-    const crypto = host.crypto ?? globalThis.crypto;
-    if (typeof crypto.randomUUID === "function")
-        return crypto.randomUUID();
-    const bytes = crypto.getRandomValues(new Uint8Array(16));
-    bytes[6] = (bytes[6] & 0x0f) | 0x40;
-    bytes[8] = (bytes[8] & 0x3f) | 0x80;
-    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}

package/dist/actions.d.ts

@@ -86,6 +86,7 @@ export declare const placeOrderInput: z.ZodObject<{
     }, z.core.$strip>>>, unknown>;
     landingPageSlug: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
     couponCode: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    checkoutKey: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
 }, z.core.$strip>;
 export type PlaceOrderInput = z.infer<typeof placeOrderInput>;
 /**

package/dist/actions.js

@@ -153,6 +153,9 @@ export const placeOrderInput = z.object({
     // The code the shopper typed; an empty box sends none. Whether it applies
     // is the server's to say — a refusal comes back as `couponRefusal`.
     couponCode: z.preprocess((v) => (typeof v === "string" && v.trim() === "") || v == null ? undefined : v, z.string().max(64).optional()),
+    // The checkout attempt's key (`bindCheckoutKey`): the same key again is
+    // answered with the order it placed, never a second one.
+    checkoutKey: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().uuid().optional()),
 });
 /**
  * Collect the shopper's attribution headers so the server records the

package/dist/checkout-key.d.ts

@@ -0,0 +1,25 @@
+/**
+ * One checkout attempt, one order. The server places the order a checkout key
+ * arrives with once: the same key again answers with that order, never a
+ * second one, a second stock deduction or a second notification.
+ *
+ * `bindCheckoutKey` puts a key on every submission a checkout form makes. It
+ * stays the same while the shopper changes nothing — a double click, a
+ * refreshed or retried submission carries it — and is drawn anew once they
+ * change anything, so a different order is never answered with the one
+ * already placed.
+ *
+ * The key is drawn in the browser at the first submission, never rendered: a
+ * storefront page is cached and served to every shopper.
+ */
+import { type UuidSource } from "./utils/uuid.js";
+/** What the binding uses of the form: its events. */
+export type CheckoutKeyForm = Pick<EventTarget, "addEventListener" | "removeEventListener">;
+/**
+ * Bind a checkout key to the form; the function returned unbinds it. The key
+ * is added through the form's `formdata` event, so it reaches a native submit
+ * and a `new FormData(form)` alike, whatever order the theme's own submit
+ * handlers run in. A browser without that event sends no key and places its
+ * orders as before.
+ */
+export declare function bindCheckoutKey(form: CheckoutKeyForm, crypto?: UuidSource): () => void;

package/dist/checkout-key.js

@@ -0,0 +1,42 @@
+/**
+ * One checkout attempt, one order. The server places the order a checkout key
+ * arrives with once: the same key again answers with that order, never a
+ * second one, a second stock deduction or a second notification.
+ *
+ * `bindCheckoutKey` puts a key on every submission a checkout form makes. It
+ * stays the same while the shopper changes nothing — a double click, a
+ * refreshed or retried submission carries it — and is drawn anew once they
+ * change anything, so a different order is never answered with the one
+ * already placed.
+ *
+ * The key is drawn in the browser at the first submission, never rendered: a
+ * storefront page is cached and served to every shopper.
+ */
+import { uuidV4 } from "./utils/uuid.js";
+const FIELD = "checkoutKey";
+const CHANGES = ["input", "change", "reset"];
+/**
+ * Bind a checkout key to the form; the function returned unbinds it. The key
+ * is added through the form's `formdata` event, so it reaches a native submit
+ * and a `new FormData(form)` alike, whatever order the theme's own submit
+ * handlers run in. A browser without that event sends no key and places its
+ * orders as before.
+ */
+export function bindCheckoutKey(form, crypto = globalThis.crypto) {
+    let key = null;
+    const stamp = (event) => {
+        key ??= uuidV4(crypto);
+        event.formData.set(FIELD, key);
+    };
+    const forget = () => {
+        key = null;
+    };
+    form.addEventListener("formdata", stamp);
+    for (const type of CHANGES)
+        form.addEventListener(type, forget);
+    return () => {
+        form.removeEventListener("formdata", stamp);
+        for (const type of CHANGES)
+            form.removeEventListener(type, forget);
+    };
+}

package/dist/client/orders.js

@@ -14,13 +14,14 @@
 import { CreatedOrderSchema, IdResponseSchema, OrderTrackingSchema, OtpSendResultSchema, ShopperOrderStatusSchema, OtpVerifyResultSchema, } from "../schemas.js";
 import { STOREFRONT_OPERATIONS } from "../operations.js";
 import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
+import { localizedPath } from "./paths.js";
 /**
  * Create orders namespace
  */
 export function createOrdersNamespace(core) {
     return {
         async create(body, forwardedHeaders) {
-            return core.post("/store/orders", body, {
+            return core.post(localizedPath(core.config, "/store/orders"), body, {
                 ...(forwardedHeaders ? { headers: forwardedHeaders } : {}),
                 schema: CreatedOrderSchema,
                 operation: STOREFRONT_OPERATIONS.ordersCreate,

package/dist/client/paths.d.ts

@@ -1,8 +1,8 @@
 /**
- * Request paths for reads that carry merchant text. Each one names the
- * client's language (`StoreScope.locale`), so the server serves it
- * with its translations — and caches keyed by path keep one entry per
- * language.
+ * Request paths that name the client's language (`StoreScope.locale`): reads
+ * that carry merchant text, so the server serves them with their
+ * translations (caches keyed by path keep one entry per language), and an
+ * order, which records the language it was placed in.
  */
 import type { StoreScope } from "../domain.js";
 export declare function localizedPath(scope: Pick<StoreScope, "locale">, path: string, params?: Readonly<Record<string, string | undefined>>): string;

package/dist/index.d.ts

@@ -11,8 +11,8 @@
  */
 export { formatMoney } from "./utils/money.js";
 export type { MoneyFormatOptions } from "./utils/money.js";
-export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, mediaImageUrl, mediaImageSrcset, mediaUrl, pictureOf, } from "./utils/image.js";
-export type { ImageHelpers, ImageResizeOptions, MediaImageParams, MediaImageSrcsetOptions, PickedImage, Picture } from "./utils/image.js";
+export { isMediaKey, mediaImageSrcset, mediaImageUrl, mediaUrl, pictureOf } from "./utils/image.js";
+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";
@@ -25,6 +25,8 @@ export type { StorefrontPageMatch, StorefrontPageType, StorefrontPathParams, Sto
 export { addedLines, createBasketStore, createMemoryStorageAdapter, createLocalStorageAdapter, DEFAULT_BASKET_STORAGE_KEY, toOrderItems, } from "./basket.js";
 export { MAX_BASKET_LINES, MAX_BASKET_LINE_QUANTITY, basketLineKey } from "./basket-line.js";
 export type { BasketStore, BasketStorageAdapter, BasketStoreOptions, BasketListener, BasketSelectionLine, } from "./basket.js";
+export { bindCheckoutKey } from "./checkout-key.js";
+export type { CheckoutKeyForm } from "./checkout-key.js";
 export { createOtpMachine, createOtpTransport, mapOtpResponse, otpTransportFailure, } from "./otp.js";
 export type { OtpMachine, OtpMachineOptions, OtpFailureContext, OtpResponseOptions, OtpState, OtpStatus, OtpTransport, OtpTransportResult, OtpStateListener, } from "./otp.js";
 export { WILAYAS } from "./data/wilayas.js";