@wocart/storefront 1.22.0 → 1.23.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ follows [semantic versioning](https://semver.org/): breaking changes ship only
 in a new major version, and an export is marked `@deprecated` for at least one
 minor release before a major removes it.
 
+## 1.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/USAGE.md

@@ -236,6 +236,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 +261,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". |
 
@@ -1258,6 +1259,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

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

@@ -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";

package/dist/index.js

@@ -18,6 +18,7 @@ export { servedLanguage } from "./locales.js";
 export { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "./locale-routing.js";
 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 { bindCheckoutKey } from "./checkout-key.js";
 export { createOtpMachine, createOtpTransport, mapOtpResponse, otpTransportFailure, } from "./otp.js";
 export { WILAYAS } from "./data/wilayas.js";
 export { ALGERIA_COMMUNES, communesForWilaya } from "./data/communes.js";

package/dist/types.d.ts

@@ -475,6 +475,13 @@ export interface CreateOrderInput {
     landingPageSlug?: string | undefined;
     /** The code the shopper typed. An order whose code does not apply is refused whole (`couponRefusalOf`). */
     couponCode?: string | undefined;
+    /**
+     * The checkout attempt's key, a UUID (`bindCheckoutKey`). The same key again
+     * answers with the order it placed, exactly as the first time; for another
+     * phone it fails with `CHECKOUT_KEY_IN_USE`. Without it, every call places
+     * an order.
+     */
+    checkoutKey?: string | undefined;
 }
 /**
  * The order's tracking destination — which Meta pixel it belongs to and

package/dist/utils/uuid.d.ts

@@ -0,0 +1,6 @@
+/** What a UUID is drawn from: the platform's `crypto`, whose `randomUUID` exists only in a secure context. */
+export type UuidSource = Pick<Crypto, "getRandomValues"> & {
+    randomUUID?: () => string;
+};
+/** A version 4 UUID: the platform's `randomUUID`, else one drawn from `getRandomValues`. */
+export declare function uuidV4(crypto: UuidSource): string;

package/dist/utils/uuid.js

@@ -0,0 +1,10 @@
+/** A version 4 UUID: the platform's `randomUUID`, else one drawn from `getRandomValues`. */
+export function uuidV4(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/package.json

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