@wocart/storefront 1.19.0 → 1.21.0

package/CHANGELOG.md

@@ -5,6 +5,97 @@ 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.21.0 — 2026-10-24
+
+### Added
+
+- **A shopper's track-order page, with no script.** `lookupOrder(input,
+  request, client)` and `orderLookupInput` in `@wocart/storefront/astro`, for
+  an Astro Action a plain form posts: it answers `found` (the order),
+  `invalid-number` (not an order number — the server is not asked),
+  `invalid-phone`, `not-found` (a wrong number or phone, never saying which),
+  `rate-limited` (with the wait) or `failed`, and forwards the shopper's
+  address so the server's limit counts per shopper. The `orderStatus` route
+  takes the same input.
+- **The track-order page is a platform page.** `STOREFRONT_PAGE_PATHS.trackOrder`
+  is `/track-order` — `?order=<number>` fills its number in — so the platform
+  can link a shopper to it like the thank-you page, and every theme renders it
+  at the same place. `showsWidgetOn` treats it as a store page.
+- `SHOPPER_ORDER_JOURNEY`: the stages from `placed` to `delivered`, in order,
+  for a tracking page's progress; `returned` and `cancelled` end an order off
+  it.
+
+### Fixed
+
+- `notFound(Astro)` type-checks against Astro's own global and endpoint
+  context: `NotFoundContext.response.status` is optional, as Astro's
+  `ResponseInit` declares it. Nothing changes at runtime.
+
+## 1.20.0 — 2026-10-24
+
+What every theme used to write itself is now the package's: the order form's
+quote, abandoned-checkout tracking, the review form, the request's store and
+language, the sitemap, search-engine metadata and images sized for the
+screen. Search, sorting, listing totals, a shopper's order status and product
+SEO fields arrive with the server that answers them; on an older server each
+degrades safely.
+
+### Added
+
+- **The order form, from the browser.** `createQuoter({ endpoint })` asks the
+  theme's cart-validate route and answers `fresh` (the quote), `stale` (a newer
+  question was asked meanwhile) or `failed`. `readCartQuote(value)` reads a
+  quote exactly as `CartValidationSchema` does, without Zod.
+- **Coupons.** `couponRefusalTone(reason)` says whether a refusal is a `hint`
+  (the basket does not meet the code yet) or `refused` (the code cannot be
+  used); `COUPON_HINT_REASONS` and `COUPON_REFUSAL_REASONS` list them.
+- **Abandoned checkouts.** `createBrowserAbandonedCheckoutTracker({ endpoint })`
+  wires the tracker to the page — session storage, timers, Meta cookies, a
+  keepalive POST and a beacon on exit. `convertAbandonedCheckout(...)` marks the
+  tab's checkout converted from the thank-you page;
+  `ABANDONED_CHECKOUT_SESSION_KEY` names where its id lives.
+- **Reviews.** `createReviewSession({ routes })` in `@wocart/storefront/review-media`
+  proves the purchase, sends each photo (shrunk) or voice note with its
+  progress and retries, and submits; every refusal comes back as a code from
+  `REVIEW_REFUSAL_CODES`. `REVIEW_TEXT_LIMITS` gives the lengths the server
+  accepts; `isOrderNumber(value)` and `ORDER_NUMBER_PATTERN` the shape of an
+  order number.
+- **The basket.** `basket.addSelections(line, selections)` adds an offer chosen
+  piece by piece — one line per variant, as one change, all or nothing.
+- **Request and preview.** `resolveStoreRequest` and `resolvePreviewStore` in
+  `@wocart/storefront/astro` decide the request's store and language (path
+  prefixes, the asking page's language for endpoints and server islands, the
+  redirects) and the draft's store. `notFound(Astro)` answers a missing
+  resource with the not-found page, never cached.
+- **Sitemap.** `sitemapXml(paths, routing, origin)` and `catalogPaths(client,
+  config)` in `@wocart/storefront/server`.
+- **Images.** `mediaImageSrcset(src, widths, options)` gives width descriptors
+  for `sizes`; `pictureOf(image, mediaDomain)` turns a picked image into its
+  URL, alt, size and focal point.
+- **Search engines.** `productMeta(product)`, `productStructuredData(product,
+  options)` and `jsonLd(value)`; `SEO_TEXT_LIMITS`. Products carry the
+  merchant's `metaTitle` and `metaDescription`, in the client's language.
+- **Catalog.** `products.search(text, filters)`; `sort` on listings
+  (`PRODUCT_SORTS`); `ProductPage.total`; a collection's `productCount` and
+  `image`; `DEFAULT_COLLECTION_HANDLES`; `productTags(product)` reads tags as a
+  list from a listing or a product page.
+- **Order status.** `orders.status({ orderNumber, phone })` and the
+  `orderStatus` storefront route: where a shopper's order is
+  (`SHOPPER_ORDER_STAGES`), its lines, total and tracking number — never its
+  address.
+
+### Changed
+
+- `getProductView(product)` reads the default variant's stock for
+  `isOutOfStock` and `isLowStock` on a product with variants, not the
+  product's total.
+
+### Deprecated
+
+- `ProductSchema.costPrice` and `ProductListSchema.costPrice`: always null —
+  what the merchant paid is never served to a storefront. A later major drops
+  them.
+
 ## 1.19.0 — 2026-10-21
 
 What a theme's browser code takes from the package brings no Zod. Validation

package/USAGE.md

@@ -111,6 +111,7 @@ break those links.
 | `landing` | `/lp/:slug` | a landing page | required when the store runs landing pages |
 | `checkout` | `/checkout` | the cart's checkout | required when the store turns the cart on |
 | `thankYou` | `/thank-you` | the order confirmation | required |
+| `trackOrder` | `/track-order` | where a shopper follows an order by its number and phone; `?order=<number>` fills the number in | required |
 
 How a theme implements them, in Astro's own terms:
 
@@ -693,6 +694,36 @@ The picker reads only `variations`, `active`, `inventory`, `position` and
 `isDefault` of each variant (`PickerVariant`), so a page may hand it a
 lighter copy.
 
+`getProductView(product)` opens on the default variant: its price, and its
+stock for `isOutOfStock` and `isLowStock`, so a product whose first size is
+nearly gone says so even when another size has plenty.
+
+### Search engines and shared links
+
+A product carries the title and description its merchant wrote for search
+engines (`metaTitle`, `metaDescription`, in the client's language; null when
+none was written). `productMeta(product)` gives what a page puts in its
+`<title>` and `<meta name="description">`: what the merchant wrote, else the
+product's name and the start of its description as plain text — never markup
+— within `SEO_TEXT_LIMITS` (60 and 160 characters). Add the store's name to
+the title as the theme's design wants.
+
+`productStructuredData(product, { url, storeName })` gives its schema.org
+`Product` for rich results: photos, SKU, its price and stock as an `Offer`, or
+an `AggregateOffer` when its variants cost different amounts, and its rating
+once reviewed. Write it with `jsonLd(value)`, which escapes what could end the
+script:
+
+~~~astro
+---
+import { jsonLd, productMeta, productStructuredData } from "@wocart/storefront";
+const meta = productMeta(product);
+---
+<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 }))} />
+~~~
+
 ### Product lists
 
 ~~~ts
@@ -725,10 +756,46 @@ const onSale = await store.products.list({ onSale: true, limit: 8 });
 - `featured: true` and `ProductList.storeFeatured` are deprecated: they mean
   the `featured` collection.
 
+A collection's page also has its size and a photo: `collections.get(handle)`
+answers `productCount` (what a shopper sees in it) and `image` (its first
+listed product's first photo, a `ProductImage`), both absent from a server
+that predates them.
+
+**Pages, totals and order.** `products.page(filters)` answers one page,
+whether another follows, and how many products the whole listing holds
+(`total`, null from a server that predates counts) — enough for "page 2 of 5"
+or "36 products":
+
+~~~ts
+const page = await store.products.page({ collection: "best-sellers", sort: "price-ascending", limit: 24, offset: 24 });
+// page.items, page.hasNext, page.total
+~~~
+
+`sort` is one of `PRODUCT_SORTS` — `newest`, `price-ascending`,
+`price-descending` — for a theme's sort control.
+
+`DEFAULT_COLLECTION_HANDLES` names the collections every store starts with,
+the likeliest to hold products first, for a page that needs one and was named
+none. Without one a listing keeps
+its own order: a collection's, a search's best match first, else newest. A
+server that predates sorting ignores it.
+
+**Search.** `products.search(text, filters)` answers a page of the products
+whose name — in the client's language or the catalog's — or tags hold every
+word, with the same filters, sort and paging; names that hold every word come
+first. Blank text finds nothing without asking. Search has its own path, so a
+server that predates it answers an empty page (reported through `onError`),
+never the whole catalog:
+
+~~~ts
+const results = await store.products.search(Astro.url.searchParams.get("q") ?? "", { limit: 24 });
+~~~
+
 Product lists return ProductList objects. ProductList and Product are
 different shapes: a list item is not a detail object and must not be cast to
 Product. ProductList carries list-oriented fields such as coverImage and
 reviewStats, while variantOptions and tags remain their raw serialized form.
+Read tags with `productTags(product)`, which gives a list from either shape.
 
 The limit is optional. An explicit limit of 0 is preserved, so do not replace
 it with a truthiness fallback.
@@ -811,6 +878,41 @@ const { blob, durationMs } = await recorder.stop();
 `canRecordVoice()` says whether to show a record button at all; a shopper can
 also attach an audio file. Send a recording with its `durationMs`.
 
+**The whole flow, from the browser.** `createReviewSession` runs the three
+steps through the theme's own review routes (see the storefront routes
+below): it keeps the proof and the upload grant between them, shrinks a
+photo before sending it, reports an upload's progress, tries again after a
+dropped connection or a server failure (twice, after 2 s then 4 s), and
+answers every refusal as a code for the form to word. It never throws.
+
+~~~ts
+import { createReviewSession } from "@wocart/storefront/review-media";
+import { REVIEW_REFUSAL_CODES, REVIEW_TEXT_LIMITS, isOrderNumber } from "@wocart/storefront";
+
+const session = createReviewSession({
+  routes: { eligibility: "/api/reviews/eligibility", upload: "/api/reviews/upload", submit: "/api/reviews/submit" },
+});
+
+const found = await session.find({ orderNumber, phone });
+if (found.status === "refused") return say(found.code); // null: no answer came
+
+const upload = session.upload(file, { kind: "image", onProgress: (share) => bar.style.inlineSize = `${share * 100}%` });
+remove.onclick = () => upload.cancel();
+const sent = await upload.result; // { status: "sent", uploadId } | refused | cancelled
+
+const submitted = await session.submit({ productId, rating, body, title, uploads: [uploadId] });
+// submitted.status === "submitted": submitted.result.visibility
+~~~
+
+`REVIEW_REFUSAL_CODES` lists every code a step can be refused with — word
+each one, and keep a general sentence for a code a newer server adds. A
+malformed order number is refused before any request, with the server's own
+`VALIDATION_FAILED`; `isOrderNumber(value)` and `ORDER_NUMBER_PATTERN` let a
+form say so as the shopper types. `REVIEW_TEXT_LIMITS` holds the lengths the
+server accepts (`bodyMin`, `bodyMax`, `titleMax`) for the form's hints and
+`maxlength`. `session.reset()` forgets the order and cancels what is still
+sending, when the shopper changes order.
+
 ## Categories, legal pages, and landing pages
 
 ### Categories
@@ -1074,6 +1176,20 @@ The basket persists under `DEFAULT_BASKET_STORAGE_KEY` and holds at most
 `MAX_BASKET_LINES` lines of at most `MAX_BASKET_LINE_QUANTITY` units each —
 the same caps the server re-checks.
 
+An offer chosen piece by piece — three pyjamas in two sizes — goes in with
+`addSelections`: the product's line, then the per-piece choice exactly as an
+order's `variantSelections` carries it. Each variant becomes one line holding
+its pieces, all carrying the offer, in one change (listeners hear once). It
+is all or nothing: when the basket has no room for every new line, nothing is
+added, so an offer is never half in the basket.
+
+~~~ts
+basket.addSelections(
+  { productId, productName, unitPrice, offerId: "three-for-two", href, image },
+  [{ variantId: "6m", variantLabel: "6 mois" }, { variantId: "12m", variantLabel: "12 mois" }, { variantId: "6m", variantLabel: "6 mois" }],
+);
+~~~
+
 ### Single-product order versus basket order
 
 An order is either:
@@ -1157,6 +1273,31 @@ the code's field.
 A shareable link carries a code in the query (`COUPON_URL_PARAM`, `?coupon=RAMADAN10`);
 `couponFromUrl(url)` reads it so the theme can fill the code box.
 
+How a refusal reads is the platform's too: `couponRefusalTone(reason)` is
+`"hint"` when the code is good but this basket does not meet it yet — a phone
+to type, a product under an offer, a minimum not reached, delivery already
+free (`COUPON_HINT_REASONS`) — and `"refused"` when the code itself cannot be
+used, including a reason this release does not know. `COUPON_REFUSAL_REASONS`
+lists every reason the platform names, for a theme to word each one.
+
+**Asking from the browser.** An order form asks again whenever the shopper
+changes something, and only the latest question counts. `createQuoter` posts
+to the theme's cart-validate route and says which answer to show:
+
+~~~ts
+import { createQuoter } from "@wocart/storefront";
+
+const quoter = createQuoter({ endpoint: "/api/cart/validate" });
+const answer = await quoter.quote({ items: basket.toOrderItems() }, { destination, couponCode, phone });
+if (answer.status === "fresh") render(answer.quote); // a CartValidation
+else if (answer.status === "failed") showError();    // the latest question got no usable answer
+// "stale": a newer question was asked meanwhile — keep what is shown
+~~~
+
+`readCartQuote(value)` reads a quote the way the quoter does, for a quote a
+page carries: exactly what `CartValidationSchema` accepts, without a
+validator in the shopper's page.
+
 ### OTP
 
 Use OTP only when config.otpEnabled says the store requires or offers it.
@@ -1263,6 +1404,54 @@ tracking returns pixelId and an event of Purchase or Lead, or null. If it is
 null, fire no conversion event. Do not infer an event from a successful HTTP
 response alone.
 
+**Where an order is, for the shopper.** A shopper has no account: the order's
+number and the phone it was placed with prove it is theirs, as for a review.
+
+~~~ts
+const found = await store.orders.status({ orderNumber, phone }, forwardedHeaders);
+if (found.success) {
+  // found.data.stage: placed, confirmed, preparing, shipped, out_for_delivery,
+  //   delivered, returned (refused at the door) or cancelled — SHOPPER_ORDER_STAGES;
+  //   a progress bar shows SHOPPER_ORDER_JOURNEY, placed to delivered, which
+  //   returned and cancelled leave
+  // found.data.lines, found.data.total, found.data.placedAt
+  // found.data.tracking: { number, carrier } once the carrier has the parcel
+}
+// ORDER_NOT_FOUND: a wrong number or a wrong phone, answered the same.
+// ORDER_LOOKUP_RATE_LIMITED: too many tries for the order or the shopper.
+~~~
+
+It never answers the address, the notes or the merchant's own statuses.
+
+A theme's track-order page needs no script: an Astro Action posted by a plain
+form, with the outcome already worded in the few cases a page shows.
+
+~~~ts
+// src/actions/index.ts
+import { defineAction } from "astro:actions";
+import { lookupOrder, orderLookupInput } from "@wocart/storefront/astro";
+
+export const server = {
+  orderStatus: defineAction({
+    accept: "form",
+    input: orderLookupInput,
+    handler: (input, context) => lookupOrder(input, context.request, context.locals.store.client),
+  }),
+};
+~~~
+
+~~~astro
+---
+// src/pages/track.astro — the page renders from the same POST
+const lookup = Astro.getActionResult(actions.orderStatus)?.data;
+// lookup?.status: "found" (lookup.order), "invalid-number" (the server is not
+// asked), "invalid-phone", "not-found", "rate-limited" (retryAfterSeconds) or "failed"
+---
+<form method="POST" action={actions.orderStatus}>…</form>
+~~~
+
+From the browser, use the storefront routes' `orderStatus`.
+
 ### Meta browser primitives
 
 The payload builders are pure and browser-safe. Use the server-validated value
@@ -1288,6 +1477,26 @@ Use these only when the theme has a real abandoned-checkout flow. Keep the
 normal mutation result handling and never block order creation on optional
 analytics.
 
+In the browser, `createBrowserAbandonedCheckoutTracker` does the capturing:
+the checkout's id for the tab in `sessionStorage`
+(`ABANDONED_CHECKOUT_SESSION_KEY`), a capture after the shopper pauses, the
+Meta cookies, a `keepalive` POST to the theme's route, and a beacon when the
+shopper leaves. Blocked storage or a failed send never touches the order.
+
+~~~ts
+import { convertAbandonedCheckout, createBrowserAbandonedCheckoutTracker } from "@wocart/storefront";
+
+const tracker = createBrowserAbandonedCheckoutTracker({ endpoint: "/api/abandoned" });
+nameInput.addEventListener("input", () => tracker.schedule(snapshot()));
+addEventListener("pagehide", () => tracker.captureOnExit(snapshot()));
+
+// On the thank-you page: the checkout became this order.
+convertAbandonedCheckout({ endpoint: "/api/abandoned/convert", orderId, orderNumber });
+~~~
+
+`createAbandonedCheckoutTracker` is the same policy with every browser
+dependency passed in, for an unusual host.
+
 ## Astro actions and form handling
 
 The SDK cannot import Astro virtual modules, so a theme owns the thin Astro
@@ -1395,6 +1604,60 @@ the next page with no result: the thank-you redirect never fires, and a
 refused order shows no message. resolveActionRedirectDecision, the earlier
 name, is deprecated and now always answers next.
 
+### The request's store and language
+
+`resolveStoreRequest` decides which store a request renders and in which
+language, with the rules every storefront needs: a page takes its language
+from its path (`/fr/products/robe`); the primary's own prefix redirects for
+good to its one address, and a language the store stopped publishing
+redirects for now to the primary page; an endpoint (`/api/…`) or a server
+island takes the language of the page that asked, from its same-origin
+`Referer`, and is never redirected or rewritten. It answers data — the
+request's client, config, language, routing and unprefixed path — and the
+theme builds its own context from it:
+
+~~~ts
+// src/middleware.ts
+import { resolvePreviewStore, resolveStoreRequest, runFormAction } from "@wocart/storefront/astro";
+
+const options = { client: createStore, fallback: FALLBACK_CONFIG }; // the theme's one client factory, and its shell config
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  if (context.url.pathname === THEME_PREVIEW_PATH) {
+    const preview = await readThemePreview(context.request);
+    if (!preview.ok) return new Response(null, { status: preview.status, headers: { "Cache-Control": "no-store" } });
+    context.locals.store = buildContext(await resolvePreviewStore(preview.draft, options));
+    return next();
+  }
+  const request = await resolveStoreRequest({ url: context.url, referer: context.request.headers.get("Referer") }, options);
+  if (request.kind === "redirect") return context.redirect(request.location, request.status);
+  context.locals.store = buildContext(request);
+  // … runFormAction as above …
+  return request.rewrite ? next(request.rewrite) : next();
+});
+~~~
+
+`client(locale?)` makes the request's client, in a language or the
+store's primary; `fallback` is the config rendered when the store cannot be
+read — a shell with the checkout off. `embedded(pathname)` overrides which
+paths serve part of a page. `resolvePreviewStore(draft, options)` is the
+editor's preview: the draft's language when the store serves it, the draft's
+settings and text over the saved ones, tracking off.
+
+### A page whose resource does not exist
+
+A product, category, collection or page that is not there answers the
+theme's not-found page with 404 — and is never cached, or a product published
+a minute later keeps answering "not found":
+
+~~~astro
+---
+import { notFound } from "@wocart/storefront/astro";
+const product = await Astro.locals.store.client.products.get(Astro.params.handle ?? "");
+if (!product) return notFound(Astro);
+---
+~~~
+
 ## Browser-facing proxy routes
 
 Browser code calls same-origin theme routes, which call the platform with the
@@ -1402,8 +1665,8 @@ server-only API key. The key never reaches the browser.
 
 ### The storefront routes, ready to export
 
-createStorefrontRoutes returns the eight routes every storefront needs. Bind
-them once to the request's own client:
+createStorefrontRoutes returns the routes every storefront needs. Bind them
+once to the request's own client:
 
 ~~~ts
 // src/theme/api-routes.ts
@@ -1435,12 +1698,14 @@ export const POST = routes.otpSend;
 | `reviewEligibility` | POST | `{ orderNumber, phone, turnstileToken? }` | `{ data: ReviewEligibility }` |
 | `reviewUpload` | PUT | the file as the body; headers `X-Review-Grant`, `X-Media-Duration-Ms` | 201 `{ data: ReviewUpload }` (streamed on, never buffered) |
 | `reviewSubmit` | POST | `ReviewInput` | 201 `{ success: true, data: { id, visibility } }` |
+| `orderStatus` | POST | `{ orderNumber, phone }` | `{ data: ShopperOrderStatus }` |
 
 What every route gets right:
 
 - every POST and PUT refuses a cross-origin request with 403;
-- the OTP routes and abandoned tracking forward the shopper's address and
-  user agent, so the server limits and attributes per shopper;
+- the OTP routes, abandoned tracking and the order status forward the
+  shopper's address and user agent, so the server limits and attributes per
+  shopper;
 - input is bounded before it is sent, and a malformed body is a 400 that never
   reaches the server;
 - a refusal answers with the status the server's category implies — 400 for
@@ -1537,6 +1802,33 @@ 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.
 
+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:
+
+~~~astro
+<img
+  src={mediaImageUrl(src, { width: 720, format: "auto" }, mediaDomain) ?? src}
+  srcset={mediaImageSrcset(src, [360, 540, 720, 1080], { mediaDomain, 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
+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);
+---
+{picture && <img src={picture.src} alt={picture.alt} width={picture.width} height={picture.height} style={{ objectPosition: picture.position }} />}
+~~~
+
 ### Which photo a product is
 
 `coverImage` is nullable and a merchant who uploads a gallery may never pick
@@ -1628,6 +1920,27 @@ Three rules come with it, and a theme must not re-implement them:
 visible rather than silently swallowed. The cap and the token list are the
 same ones the dashboard enforces.
 
+## The sitemap
+
+`sitemapXml(paths, routing, origin)` writes a multilingual sitemap: one
+`<url>` per page per published language, each naming every language version
+and `x-default`. `catalogPaths(client, config)` lists what it holds — home,
+the catalog, each category, every product (read page by page) and each
+published text page; landing pages stay out, as ad destinations. Both are in
+`@wocart/storefront/server`:
+
+~~~ts
+// src/pages/sitemap.xml.ts
+import { catalogPaths, sitemapXml } from "@wocart/storefront/server";
+
+export const GET: APIRoute = async ({ locals, url }) => {
+  const { client, config, routing } = locals.store;
+  return new Response(sitemapXml(await catalogPaths(client, config), routing, url.origin), {
+    headers: { "Content-Type": "application/xml; charset=utf-8", "Cache-Control": "public, max-age=3600" },
+  });
+};
+~~~
+
 ## Previewing a draft for an editor
 
 A visual editor shows a merchant's unsaved changes on the store's own

package/dist/abandoned-checkout.d.ts

@@ -19,4 +19,49 @@ export interface AbandonedCheckoutTracker {
     captureOnExit(snapshot: AbandonedCheckoutSnapshot): void;
     isCapturable(snapshot: AbandonedCheckoutSnapshot): boolean;
 }
+/**
+ * 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
+ * marks that record converted.
+ */
+export declare const ABANDONED_CHECKOUT_SESSION_KEY = "cod_session_id";
 export declare function createAbandonedCheckoutTracker(ports: AbandonedCheckoutPorts): AbandonedCheckoutTracker;
+/** 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 document?: {
+        readonly cookie: string;
+    };
+    readonly navigator?: {
+        sendBeacon?: (url: string, data: Blob) => boolean;
+    };
+    readonly fetch?: typeof fetch;
+    readonly setTimeout: (callback: () => void, delayMs: number) => unknown;
+    readonly clearTimeout: (handle: never) => void;
+}
+export interface BrowserAbandonedCheckoutOptions {
+    /** The theme's abandoned-checkout route (`createStorefrontRoutes().abandonedUpsert`), e.g. `/api/abandoned`. */
+    endpoint: string;
+}
+/**
+ * `createAbandonedCheckoutTracker` wired to the page: the checkout's id in
+ * `sessionStorage`, timers, the Meta cookies, a `keepalive` POST to the
+ * theme's route, and `sendBeacon` when the shopper leaves. A page that blocks
+ * storage still captures; nothing it does can fail the order.
+ */
+export declare function createBrowserAbandonedCheckoutTracker(options: BrowserAbandonedCheckoutOptions, host?: AbandonedCheckoutHost): AbandonedCheckoutTracker;
+export interface AbandonedCheckoutConversion {
+    /** The theme's conversion route (`createStorefrontRoutes().abandonedConvert`), e.g. `/api/abandoned/convert`. */
+    endpoint: string;
+    orderId: string;
+    orderNumber: string;
+}
+/**
+ * Marks the tab's checkout converted, from the thank-you page: the merchant
+ * no longer sees the order it became as abandoned. The id is used once and
+ * forgotten. Best-effort — it never throws and never holds the page.
+ */
+export declare function convertAbandonedCheckout(conversion: AbandonedCheckoutConversion, host?: Pick<AbandonedCheckoutHost, "sessionStorage" | "fetch">): void;

package/dist/abandoned-checkout.js

@@ -1,5 +1,10 @@
 import { toLocalAlgerianMobile } from "./phone.js";
-const SESSION_KEY = "cod_session_id";
+/**
+ * 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
+ * marks that record converted.
+ */
+export const ABANDONED_CHECKOUT_SESSION_KEY = "cod_session_id";
 const DEBOUNCE_MS = 3000;
 export function createAbandonedCheckoutTracker(ports) {
     let sessionId = readSessionId(ports);
@@ -76,14 +81,87 @@ function readCookie(ports, name) {
 }
 function readSessionId(ports) {
     try {
-        const existing = ports.storage.getItem(SESSION_KEY);
+        const existing = ports.storage.getItem(ABANDONED_CHECKOUT_SESSION_KEY);
         if (existing)
             return existing;
         const created = ports.createId();
-        ports.storage.setItem(SESSION_KEY, created);
+        ports.storage.setItem(ABANDONED_CHECKOUT_SESSION_KEY, created);
         return created;
     }
     catch {
         return ports.createId();
     }
 }
+/**
+ * `createAbandonedCheckoutTracker` wired to the page: the checkout's id in
+ * `sessionStorage`, timers, the Meta cookies, a `keepalive` POST to the
+ * theme's route, and `sendBeacon` when the shopper leaves. A page that blocks
+ * storage still captures; nothing it does can fail the order.
+ */
+export function createBrowserAbandonedCheckoutTracker(options, host = globalThis) {
+    const post = (payload) => (host.fetch ?? globalThis.fetch)(options.endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        keepalive: true,
+    });
+    return createAbandonedCheckoutTracker({
+        storage: {
+            getItem: (key) => host.sessionStorage?.getItem(key) ?? null,
+            setItem: (key, value) => host.sessionStorage?.setItem(key, value),
+        },
+        createId: () => uuid(host),
+        schedule: (callback, delayMs) => host.setTimeout(callback, delayMs),
+        cancel: (handle) => host.clearTimeout(handle),
+        readCookie: (name) => cookieValue(host.document?.cookie ?? "", name),
+        send: async (payload) => {
+            await post(payload);
+        },
+        beacon: (payload) => {
+            const sent = host.navigator?.sendBeacon?.(options.endpoint, new Blob([JSON.stringify(payload)], { type: "application/json" })) ?? false;
+            if (!sent)
+                void post(payload).catch(() => undefined);
+        },
+    });
+}
+/**
+ * Marks the tab's checkout converted, from the thank-you page: the merchant
+ * no longer sees the order it became as abandoned. The id is used once and
+ * forgotten. Best-effort — it never throws and never holds the page.
+ */
+export function convertAbandonedCheckout(conversion, host = globalThis) {
+    try {
+        const sessionId = host.sessionStorage?.getItem(ABANDONED_CHECKOUT_SESSION_KEY);
+        if (!sessionId || !conversion.orderId)
+            return;
+        host.sessionStorage?.removeItem(ABANDONED_CHECKOUT_SESSION_KEY);
+        void (host.fetch ?? globalThis.fetch)(conversion.endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ sessionId, orderId: conversion.orderId, orderNumber: conversion.orderNumber }),
+            keepalive: true,
+        }).catch(() => undefined);
+    }
+    catch {
+        return;
+    }
+}
+function cookieValue(cookies, name) {
+    for (const part of cookies.split(";")) {
+        const separator = part.indexOf("=");
+        if (separator > 0 && part.slice(0, separator).trim() === name)
+            return part.slice(separator + 1).trim() || undefined;
+    }
+    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)}`;
+}