@wocart/storefront 1.21.0 → 1.23.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ 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
+as what it put in, one canonical address per page, and product descriptions
+read the same for legacy rows.
+
+### Added
+
+- `addedLines(before, after)`: what an add put in the basket — each line that
+  grew, by what it grew — for an `AddToCart` event that reports the add, not
+  the whole basket; empty when the basket had no room.
+- `canonicalUrl(origin, { pathname, locale, routing }, search)`: a page's
+  canonical address — its path in its language, keeping only the listing page
+  (`?page=2`), never an order, a search, a coupon or an ad's click id.
+
+### Fixed
+
+- `productMeta` reads an empty `descriptionPlain` as no plain text: a legacy
+  text row is then described by its own text, as before plain text existed.
+
 ## 1.21.0 — 2026-10-24
 
 ### Added

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". |
 
@@ -716,12 +717,23 @@ script:
 
 ~~~astro
 ---
-import { jsonLd, productMeta, productStructuredData } from "@wocart/storefront";
+import { canonicalUrl, jsonLd, productMeta, productStructuredData } from "@wocart/storefront";
 const meta = productMeta(product);
+const canonical = canonicalUrl(Astro.url.origin, store, Astro.url.search);
 ---
 <title>{meta.title} | {store.config.name}</title>
 {meta.description && <meta name="description" content={meta.description} />}
-<script type="application/ld+json" set:html={jsonLd(productStructuredData(product, { url: Astro.url.href, storeName: store.config.name }))} />
+<script type="application/ld+json" set:html={jsonLd(productStructuredData(product, { url: canonical, storeName: store.config.name }))} />
+~~~
+
+Every page's `<link rel="canonical">` is `canonicalUrl(origin, { pathname,
+locale, routing }, search)`: the page's path in its language, keeping only the
+listing page it shows (`?page=2`). An order, a search, a coupon or an ad's
+click id (`fbclid`, `utm_*`) in the address is the same page to a search
+engine; a canonical that kept them would split one page into many.
+
+~~~ts
+const canonical = canonicalUrl(Astro.url.origin, store, Astro.url.search);
 ~~~
 
 ### Product lists
@@ -1190,6 +1202,17 @@ basket.addSelections(
 );
 ~~~
 
+What an add put in the basket is `addedLines(before, after)`: each line that
+grew, by what it grew. Report that as the `AddToCart` event — never the whole
+basket — and read an empty answer as a basket with no room left.
+
+~~~ts
+const before = basket.getLines();
+const added = addedLines(before, basket.addSelections(line, selections));
+if (added.length === 0) showBasketFull();
+else tracker.track("AddToCart", buildMetaAddToCartPayload(added));
+~~~
+
 ### Single-product order versus basket order
 
 An order is either:
@@ -1236,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/basket.d.ts

@@ -95,3 +95,17 @@ export declare function toOrderItems(lines: readonly BasketLine[]): BasketLineIn
  * Create a deep Basket Store.
  */
 export declare function createBasketStore(options?: BasketStoreOptions): BasketStore;
+/**
+ * What an add put in the basket: each line of `after` whose quantity grew
+ * since `before`, with the quantity it grew by — what an `AddToCart` event
+ * reports, never the whole basket. Empty when nothing went in, as when the
+ * basket was full.
+ *
+ * ```ts
+ * const before = basket.getLines();
+ * const added = addedLines(before, basket.addSelections(line, selections));
+ * if (added.length === 0) showBasketFull();
+ * else tracker.track("AddToCart", buildMetaAddToCartPayload(added));
+ * ```
+ */
+export declare function addedLines(before: readonly BasketLine[], after: readonly BasketLine[]): BasketLine[];

package/dist/basket.js

@@ -277,3 +277,23 @@ export function createBasketStore(options = {}) {
         },
     };
 }
+/**
+ * What an add put in the basket: each line of `after` whose quantity grew
+ * since `before`, with the quantity it grew by — what an `AddToCart` event
+ * reports, never the whole basket. Empty when nothing went in, as when the
+ * basket was full.
+ *
+ * ```ts
+ * const before = basket.getLines();
+ * const added = addedLines(before, basket.addSelections(line, selections));
+ * if (added.length === 0) showBasketFull();
+ * else tracker.track("AddToCart", buildMetaAddToCartPayload(added));
+ * ```
+ */
+export function addedLines(before, after) {
+    const had = new Map(before.map((line) => [basketLineKey(line.productId, line.variantId), line.quantity]));
+    return after.flatMap((line) => {
+        const grew = line.quantity - (had.get(basketLineKey(line.productId, line.variantId)) ?? 0);
+        return grew > 0 ? [{ ...line, quantity: grew }] : [];
+    });
+}

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

@@ -22,9 +22,11 @@ export { servedLanguage } from "./locales.js";
 export { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "./locale-routing.js";
 export type { LocalePath, LocaleRouting } from "./locale-routing.js";
 export type { StorefrontPageMatch, StorefrontPageType, StorefrontPathParams, StorefrontRoute } from "./routes.js";
-export { createBasketStore, createMemoryStorageAdapter, createLocalStorageAdapter, DEFAULT_BASKET_STORAGE_KEY, toOrderItems, } from "./basket.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 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";
@@ -35,8 +37,8 @@ export { createQuoter } from "./quote.js";
 export type { Quoter, QuoterOptions, QuoteResult } from "./quote.js";
 export { isOrderNumber, ORDER_NUMBER_PATTERN } from "./order-number.js";
 export { DEFAULT_COLLECTION_HANDLES, PRODUCT_SORTS, SHOPPER_ORDER_JOURNEY, SHOPPER_ORDER_STAGES } from "./catalog.js";
-export { SEO_TEXT_LIMITS, jsonLd, productMeta, productStructuredData } from "./seo.js";
-export type { PageMeta, ProductStructuredDataOptions } from "./seo.js";
+export { SEO_TEXT_LIMITS, canonicalUrl, jsonLd, productMeta, productStructuredData } from "./seo.js";
+export type { CanonicalPage, PageMeta, ProductStructuredDataOptions } from "./seo.js";
 export { REVIEW_REFUSAL_CODES, REVIEW_TEXT_LIMITS } from "./reviews.js";
 export type { ReviewRefusalCode } from "./reviews.js";
 export type { CommuneTuple } from "./data/communes.js";

package/dist/index.js

@@ -16,8 +16,9 @@ export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, trunc
 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";
-export { createBasketStore, createMemoryStorageAdapter, createLocalStorageAdapter, DEFAULT_BASKET_STORAGE_KEY, toOrderItems, } from "./basket.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";
@@ -26,7 +27,7 @@ export { readCartQuote, readCouponOutcome, readShippingRates } from "./answer-re
 export { createQuoter } from "./quote.js";
 export { isOrderNumber, ORDER_NUMBER_PATTERN } from "./order-number.js";
 export { DEFAULT_COLLECTION_HANDLES, PRODUCT_SORTS, SHOPPER_ORDER_JOURNEY, SHOPPER_ORDER_STAGES } from "./catalog.js";
-export { SEO_TEXT_LIMITS, jsonLd, productMeta, productStructuredData } from "./seo.js";
+export { SEO_TEXT_LIMITS, canonicalUrl, jsonLd, productMeta, productStructuredData } from "./seo.js";
 export { REVIEW_REFUSAL_CODES, REVIEW_TEXT_LIMITS } from "./reviews.js";
 export { normalizeAlgerianPhone, toLocalAlgerianMobile } from "./phone.js";
 export * from "./types.js";

package/dist/seo.d.ts

@@ -1,3 +1,9 @@
+/**
+ * What a product page tells search engines and shared links: its title and
+ * description, and its structured data — decided once, so every theme ranks
+ * the same products the same way.
+ */
+import { type LocaleRouting } from "./locale-routing.js";
 import type { Product, ProductList } from "./types.js";
 /** The lengths a search-engine title and description may have: about what a search result shows. */
 export declare const SEO_TEXT_LIMITS: {
@@ -44,4 +50,19 @@ export declare function productStructuredData(product: Product, options: Product
  * ```
  */
 export declare function jsonLd(value: unknown): string;
+/** Where a page is, as its canonical address needs it: the route it renders, in its language. */
+export interface CanonicalPage {
+    /** The page's path without its language prefix (`/products/robe`). */
+    pathname: string;
+    locale: string;
+    routing: LocaleRouting;
+}
+/**
+ * A page's canonical address: its path in its language on `origin`, keeping
+ * only the listing page it shows (`?page=2`). An order (`?sort=`), a search,
+ * an ad's click id (`fbclid`, `utm_*`) or a coupon in the address is the same
+ * page to a search engine, and a canonical that kept them would split one
+ * page into many.
+ */
+export declare function canonicalUrl(origin: string, page: CanonicalPage, search?: string | URLSearchParams): string;
 export {};

package/dist/seo.js

@@ -3,6 +3,7 @@
  * description, and its structured data — decided once, so every theme ranks
  * the same products the same way.
  */
+import { localizeHref } from "./locale-routing.js";
 import { getProductView } from "./product-view.js";
 import { initialVariant } from "./variant-picker.js";
 /** The lengths a search-engine title and description may have: about what a search result shows. */
@@ -27,7 +28,8 @@ export function productMeta(product) {
     const written = collapse(product.metaDescription ?? "");
     if (written)
         return { title, description: written };
-    const plain = product.descriptionPlain ?? (product.descriptionFormat === "text" ? product.description : null);
+    // An empty plain text is no plain text: a text row is then read as it is.
+    const plain = product.descriptionPlain || (product.descriptionFormat === "text" ? product.description : null);
     const text = collapse(plain ?? "");
     return { title, description: text ? shorten(text, SEO_TEXT_LIMITS.descriptionMax) : null };
 }
@@ -85,3 +87,17 @@ export function jsonLd(value) {
         .replace(/\u2028/g, "\\u2028")
         .replace(/\u2029/g, "\\u2029");
 }
+/**
+ * A page's canonical address: its path in its language on `origin`, keeping
+ * only the listing page it shows (`?page=2`). An order (`?sort=`), a search,
+ * an ad's click id (`fbclid`, `utm_*`) or a coupon in the address is the same
+ * page to a search engine, and a canonical that kept them would split one
+ * page into many.
+ */
+export function canonicalUrl(origin, page, search = "") {
+    const url = new URL(localizeHref(page.pathname, page.locale, page.routing), origin);
+    const asked = Number(new URLSearchParams(search).get("page"));
+    if (Number.isSafeInteger(asked) && asked > 1)
+        url.searchParams.set("page", String(asked));
+    return url.href;
+}

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.21.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",