@wocart/storefront 1.17.0 → 1.19.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ 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.19.0 — 2026-10-21
+
+What a theme's browser code takes from the package brings no Zod. Validation
+stays where data enters — a shopper's request at a route, the platform's answer
+in the client — on the server; the browser reads what those checked.
+
+### Added
+
+- `isWilayaId(value)`: whether a value is a wilaya id, the range
+  `WilayaIdSchema` checks on the server, read from the same `WILAYAS` — for the
+  browser, which checks a selected wilaya without a schema.
+- `readShippingRates(value)` and `readCouponOutcome(value)`: the delivery rates
+  a page carries and a quote's coupon outcome, read in the browser. Each accepts
+  exactly what `ShippingRatesSchema` / `CouponOutcomeSchema` accept and returns
+  what they would, without Zod — a page cached apart from its scripts can still
+  hold another version's shape. A property test holds each to its schema.
+- `mapOtpResponse` takes no `schema` for an answer of the SDK's own
+  `otpSend` / `otpVerify` routes, whose client already checked it on the
+  server. An answer with no `data` object is still a `MALFORMED_RESPONSE`
+  failure. Passing a schema works as before.
+
+### Changed
+
+- The basket's limits and line identity (`MAX_BASKET_LINES`,
+  `MAX_BASKET_LINE_QUANTITY`, `basketLineKey`) and the operation tables
+  (`STOREFRONT_OPERATIONS`, `STOREFRONT_RETRY_POLICIES`) moved out of the
+  module that builds the schemas. The exports are the same; a browser bundle
+  that uses the basket or names an operation no longer carries Zod.
+- A test bundles every browser-facing export through the package entry the
+  way a theme's Vite build does and fails, naming the export, if Zod appears.
+
+## 1.18.0 — 2026-10-21
+
+The basket carries the offer a shopper chose for a line, so a quantity tier
+that two offers share is priced as the shopper picked it.
+
+### Added
+
+- `BasketLine.offerId` (optional): the offer chosen for the line. `addLine`
+  keeps it; a plain add to the line keeps the chosen offer, and a later explicit
+  choice replaces it. A stored offer survives a reload; a value that is not a
+  string is dropped.
+- `toOrderItems` and `BasketStore.toOrderItems()` send `offerId` with the line,
+  so checkout and cart validation receive the choice. A line that chose no offer
+  sends none.
+
 ## 1.17.0 — 2026-10-18
 
 ### Added

package/USAGE.md

@@ -218,6 +218,8 @@ server directly.
 | `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) |
 | `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 |
 | `normalizeAlgerianPhone`, `toLocalAlgerianMobile` | The one Algerian phone rule (accept/format) |
 | `resolvePrefillText`, `buildWhatsAppHref`, `stripTrackingParams`, `truncateAtWordBoundary`, `PREFILL_TOKENS`, `MAX_RESOLVED_PREFILL_LENGTH` | WhatsApp prefill text and the `wa.me` link |
 | `storefrontPath`, `matchStorefrontPath`, `STOREFRONT_PAGE_PATHS` | The page types and their public paths: build a link, recognise a page |
@@ -314,6 +316,20 @@ Browser code reaches the platform only through same-origin routes you own
 browser-safe by construction: it exports no client factory and no function that
 carries the key, which the package's own contract test asserts.
 
+**Validation runs where data enters, on the server.** The SDK checks a
+shopper's request at its routes and the platform's answer in its client, with
+the schemas this package exports. What its routes and server islands hand the
+browser has passed those checks, so browser code reads it by its type and never
+imports a schema: a schema in a browser script ships Zod — about 27 KB
+compressed — to every shopper's page. The browser-facing values (the basket,
+the variant picker, the OTP machine, tracking, routes, phones, wilayas) are
+free of schemas, and a test bundles them the way a theme's build does to keep
+them so. A page can be cached apart from its scripts, so where the browser
+reads a value another version may have shaped, it uses a reader —
+`readShippingRates`, `readCouponOutcome` — that accepts exactly what the
+schema accepts, held to it by a property test, and Zod stays on the server. A theme with an endpoint of its own still validates it — on the
+server, where the request arrives.
+
 ### The namespaces
 
 | Namespace | Use it for | Important result shapes |
@@ -964,6 +980,10 @@ const communes = await store.geo.communes(wilayaId); // server rows, cached
 // zero-network rows for the checkout's locality field:
 import { communesForWilaya } from "@wocart/storefront";
 const rows = communesForWilaya(wilayaId); // Commune[] — [] if unknown
+
+// a selected wilaya, checked in the browser before its communes are asked for:
+import { isWilayaId } from "@wocart/storefront";
+if (isWilayaId(Number(select.value))) loadCommunes(Number(select.value));
 ~~~
 
 Wilayas are local and do not use the network. `geo.communes()` reads the
@@ -1182,12 +1202,12 @@ The SDK exports `createOtpMachine` to manage the complete interactive WhatsApp
 verification lifecycle without managing timers and attempts manually. It talks
 to your own same-origin OTP routes through a transport; `mapOtpResponse` turns
 each route's response into the SDK's typed result, and `otpTransportFailure`
-covers a request that never completed:
+covers a request that never completed. The routes are the SDK's own
+(`createStorefrontRoutes`), whose client checked the answer on the server, so
+`mapOtpResponse` takes no schema here; pass one only for an endpoint of your own:
 
 ~~~ts
 import {
-  OtpSendResultSchema,
-  OtpVerifyResultSchema,
   STOREFRONT_OPERATIONS,
   createOtpMachine,
   createOtpTransport,
@@ -1195,14 +1215,14 @@ import {
   otpTransportFailure,
 } from "@wocart/storefront";
 
-async function post(path, body, schema, operation) {
+async function post(path, body, operation) {
   try {
     const response = await fetch(path, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(body),
     });
-    return await mapOtpResponse(response, { schema, operation, fallbackError: "Please try again" });
+    return await mapOtpResponse(response, { operation, fallbackError: "Please try again" });
   } catch (error) {
     return otpTransportFailure(error, operation, "Please try again");
   }
@@ -1211,9 +1231,9 @@ async function post(path, body, schema, operation) {
 const otp = createOtpMachine({
   transport: createOtpTransport({
     send: (phone) =>
-      post("/api/otp/send", { phone }, OtpSendResultSchema, STOREFRONT_OPERATIONS.ordersOtpSend),
+      post("/api/otp/send", { phone }, STOREFRONT_OPERATIONS.ordersOtpSend),
     verify: (phone, requestId, code) =>
-      post("/api/otp/verify", { phone, requestId, code }, OtpVerifyResultSchema, STOREFRONT_OPERATIONS.ordersOtpVerify),
+      post("/api/otp/verify", { phone, requestId, code }, STOREFRONT_OPERATIONS.ordersOtpVerify),
   }),
   initialPhone: "0551234567",
 });

package/dist/answer-readers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Readers for what this package's server parts hand the browser: the delivery
+ * rates a page carries and the coupon outcome of a cart quote.
+ *
+ * The server built both with `ShippingRatesSchema` / `CouponOutcomeSchema`, so
+ * the browser need not run those schemas. A page can still be cached apart
+ * from its scripts, so a value of another version's shape is possible; these
+ * accept exactly what the schemas accept and return what they would — extra
+ * keys left out — without bringing Zod into a shopper's page. A property test
+ * holds each reader to its schema.
+ */
+import type { CouponOutcome, ShippingRates } from "./types.js";
+/** The delivery rates of a value (`ShippingRates`), or null when it is not a rate table. */
+export declare function readShippingRates(value: unknown): ShippingRates | null;
+/** What a coupon did in a quote (`CouponOutcome`), or null when the value is not one. */
+export declare function readCouponOutcome(value: unknown): CouponOutcome | null;

package/dist/answer-readers.js

@@ -0,0 +1,41 @@
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+/** The delivery rates of a value (`ShippingRates`), or null when it is not a rate table. */
+export function readShippingRates(value) {
+    if (!isObject(value))
+        return null;
+    const rates = {};
+    for (const [wilaya, entry] of Object.entries(value)) {
+        if (wilaya === "__proto__")
+            continue;
+        if (!isObject(entry) || !isFiniteNumber(entry.home) || !isFiniteNumber(entry.stopDesk))
+            return null;
+        rates[wilaya] = { home: entry.home, stopDesk: entry.stopDesk };
+    }
+    return rates;
+}
+/** What a coupon did in a quote (`CouponOutcome`), or null when the value is not one. */
+export function readCouponOutcome(value) {
+    if (!isObject(value) || typeof value.code !== "string")
+        return null;
+    const { code } = value;
+    if (value.applied === true) {
+        if (!isFiniteNumber(value.discount) || typeof value.freeShipping !== "boolean")
+            return null;
+        return { code, applied: true, discount: value.discount, freeShipping: value.freeShipping };
+    }
+    if (value.applied !== false || typeof value.reason !== "string")
+        return null;
+    const { reason, shortBy, startsAt } = value;
+    if (shortBy !== undefined && !isFiniteNumber(shortBy))
+        return null;
+    if (startsAt !== undefined && typeof startsAt !== "string")
+        return null;
+    return {
+        code,
+        applied: false,
+        reason,
+        ...(shortBy === undefined ? {} : { shortBy }),
+        ...(startsAt === undefined ? {} : { startsAt }),
+    };
+}

package/dist/basket-line.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A basket line's identity and the server's limits for one basket: what the
+ * browser's basket needs to keep itself well-formed. Plain values and no
+ * schema — this module runs in every shopper's browser that holds a basket,
+ * and the schemas that check a basket on the server (`domain.ts`) read the
+ * same limits from here.
+ */
+/** The server's hard limits for one canonical browser basket. */
+export declare const MAX_BASKET_LINES: 20;
+export declare const MAX_BASKET_LINE_QUANTITY: 100;
+/**
+ * Product + variant is the identity of a basket line. A null variant is a
+ * real identity, not the same thing as any selected variant.
+ */
+export declare function basketLineKey(productId: string, variantId: string | null): string;

package/dist/basket-line.js

@@ -0,0 +1,17 @@
+/**
+ * A basket line's identity and the server's limits for one basket: what the
+ * browser's basket needs to keep itself well-formed. Plain values and no
+ * schema — this module runs in every shopper's browser that holds a basket,
+ * and the schemas that check a basket on the server (`domain.ts`) read the
+ * same limits from here.
+ */
+/** The server's hard limits for one canonical browser basket. */
+export const MAX_BASKET_LINES = 20;
+export const MAX_BASKET_LINE_QUANTITY = 100;
+/**
+ * Product + variant is the identity of a basket line. A null variant is a
+ * real identity, not the same thing as any selected variant.
+ */
+export function basketLineKey(productId, variantId) {
+    return `${productId}\u0000${variantId ?? ""}`;
+}

package/dist/basket.d.ts

@@ -9,7 +9,7 @@
  * (or memory fake in server/tests). The server always validates and re-prices
  * every line at checkout.
  */
-import { type BasketLine, type BasketLineInput } from "./domain.js";
+import type { BasketLine, BasketLineInput } from "./domain.js";
 /** Default key used in browser storage, versioned to prevent schema drift crashes. */
 export declare const DEFAULT_BASKET_STORAGE_KEY = "cod_cart_v1";
 /**

package/dist/basket.js

@@ -9,7 +9,7 @@
  * (or memory fake in server/tests). The server always validates and re-prices
  * every line at checkout.
  */
-import { MAX_BASKET_LINES, MAX_BASKET_LINE_QUANTITY, basketLineKey, } from "./domain.js";
+import { MAX_BASKET_LINES, MAX_BASKET_LINE_QUANTITY, basketLineKey } from "./basket-line.js";
 /** Default key used in browser storage, versioned to prevent schema drift crashes. */
 export const DEFAULT_BASKET_STORAGE_KEY = "cod_cart_v1";
 /**
@@ -107,6 +107,7 @@ function sanitizeLine(raw, maxQuantity) {
         unitPrice: Number.isFinite(unitPrice) && unitPrice >= 0 ? unitPrice : 0,
         href: typeof line.href === "string" ? line.href : undefined,
         image: typeof line.image === "string" ? line.image : undefined,
+        offerId: typeof line.offerId === "string" && line.offerId ? line.offerId : undefined,
     };
 }
 function normalizeLines(lines, maxLines, maxQuantity) {
@@ -119,6 +120,8 @@ function normalizeLines(lines, maxLines, maxQuantity) {
             existing.variantLabel ??= line.variantLabel;
             existing.image ??= line.image;
             existing.href ??= line.href;
+            // The newest explicit choice of offer wins; a plain add keeps the one chosen.
+            existing.offerId = line.offerId ?? existing.offerId;
         }
         else {
             merged.set(key, { ...line });
@@ -143,6 +146,7 @@ export function toOrderItems(lines) {
         variantLabel: line.variantLabel ?? undefined,
         quantity: line.quantity,
         pricePerUnit: line.unitPrice,
+        ...(line.offerId !== undefined ? { offerId: line.offerId } : {}),
     }));
 }
 /**

package/dist/client/cart.js

@@ -12,7 +12,7 @@
  * keeps its optimistic view and checkout re-validates everything anyway.
  */
 import { CartValidationSchema } from "../schemas.js";
-import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { STOREFRONT_OPERATIONS } from "../operations.js";
 import { localizedPath } from "./paths.js";
 /**
  * Create cart namespace

package/dist/client/categories.js

@@ -12,7 +12,7 @@
  */
 import { z } from "zod";
 import { CategorySchema } from "../schemas.js";
-import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { STOREFRONT_OPERATIONS } from "../operations.js";
 import { localizedPath } from "./paths.js";
 import { reportDegradedRead } from "./core.js";
 /**

package/dist/client/collections.js

@@ -10,7 +10,7 @@
  * failed read — the page answers a real 404.
  */
 import { StoreCollectionSchema } from "../schemas.js";
-import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { STOREFRONT_OPERATIONS } from "../operations.js";
 import { localizedPath } from "./paths.js";
 import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
 export function createCollectionsNamespace(core) {

package/dist/client/config.js

@@ -15,7 +15,7 @@
  * outage recovers on the next request.
  */
 import { StoreConfigSchema } from "../schemas.js";
-import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { STOREFRONT_OPERATIONS } from "../operations.js";
 import { localizedPath } from "./paths.js";
 import { reportDegradedRead } from "./core.js";
 /**

package/dist/client/geo.js

@@ -14,7 +14,7 @@
  */
 import { z } from "zod";
 import { CommuneSchema } from "../schemas.js";
-import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { STOREFRONT_OPERATIONS } from "../operations.js";
 import { reportDegradedRead } from "./core.js";
 import { WILAYAS } from "../data/wilayas.js";
 /**

package/dist/client/menus.js

@@ -11,7 +11,7 @@
  * read — the theme renders its own fallback navigation.
  */
 import { StoreMenuSchema } from "../schemas.js";
-import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { STOREFRONT_OPERATIONS } from "../operations.js";
 import { localizedPath } from "./paths.js";
 import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
 export function createMenusNamespace(core) {

package/dist/client/orders.js

@@ -12,7 +12,7 @@
  *   is recoverable; reporting it to the wrong ad account is not.
  */
 import { CreatedOrderSchema, IdResponseSchema, OrderTrackingSchema, OtpSendResultSchema, OtpVerifyResultSchema, } from "../schemas.js";
-import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { STOREFRONT_OPERATIONS } from "../operations.js";
 import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
 /**
  * Create orders namespace

package/dist/client/page-data.js

@@ -17,7 +17,7 @@
  * the next render, subject only to the theme's route cache).
  */
 import { PageDocumentPayloadSchema } from "../schemas.js";
-import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { STOREFRONT_OPERATIONS } from "../operations.js";
 import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
 /**
  * Create the page-data namespace.

package/dist/client/pages.js

@@ -12,7 +12,7 @@
  *   redirects to the store home instead of a dead end.
  */
 import { LandingPageSchema, StorePagePublicSchema } from "../schemas.js";
-import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { STOREFRONT_OPERATIONS } from "../operations.js";
 import { localizedPath } from "./paths.js";
 import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
 /**

package/dist/client/products.js

@@ -13,7 +13,7 @@
  */
 import { z } from "zod";
 import { ProductListSchema, ProductSchema, ReviewEligibilitySchema, ReviewListEnvelopeSchema, ReviewSubmitResultSchema, ReviewUploadSchema } from "../schemas.js";
-import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { STOREFRONT_OPERATIONS } from "../operations.js";
 import { localizedPath } from "./paths.js";
 import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
 /** Page size when a caller names none — the storefront's default grid. */

package/dist/client/shipping.js

@@ -13,7 +13,7 @@
  * treated as unsupported.
  */
 import { ShippingRatesSchema } from "../schemas.js";
-import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { STOREFRONT_OPERATIONS } from "../operations.js";
 import { reportDegradedRead } from "./core.js";
 /**
  * Create shipping namespace

package/dist/domain.d.ts

@@ -46,9 +46,6 @@ export interface StoreScope {
      */
     readonly readTimeoutMs?: number;
 }
-/** The server's hard limits for one canonical browser basket. */
-export declare const MAX_BASKET_LINES: 20;
-export declare const MAX_BASKET_LINE_QUANTITY: 100;
 /**
  * A wilaya id, bounded by the reference dataset itself rather than a literal.
  *
@@ -57,11 +54,6 @@ export declare const MAX_BASKET_LINE_QUANTITY: 100;
  * range in step.
  */
 export declare const WilayaIdSchema: z.ZodNumber;
-/**
- * Product + variant is the identity of a basket line. A null variant is a
- * real identity, not the same thing as any selected variant.
- */
-export declare function basketLineKey(productId: string, variantId: string | null): string;
 /**
  * A browser-owned basket line. `unitPrice` is an optimistic display value;
  * the server re-prices every line during validation and order creation.
@@ -75,6 +67,7 @@ export declare const BasketLineSchema: z.ZodObject<{
     unitPrice: z.ZodNumber;
     href: z.ZodOptional<z.ZodString>;
     image: z.ZodOptional<z.ZodString>;
+    offerId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type BasketLine = z.infer<typeof BasketLineSchema>;
 /**
@@ -106,6 +99,7 @@ export declare const BasketSchema: z.ZodObject<{
         unitPrice: z.ZodNumber;
         href: z.ZodOptional<z.ZodString>;
         image: z.ZodOptional<z.ZodString>;
+        offerId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Basket = z.infer<typeof BasketSchema>;
@@ -345,65 +339,3 @@ export type ClientResult<T> = {
     readonly domainError: DomainError;
     readonly [key: string]: unknown;
 };
-export type RetryPolicy = "safe-read" | "never";
-export declare const STOREFRONT_OPERATIONS: {
-    readonly configGet: "config.get";
-    readonly categoriesList: "categories.list";
-    readonly productsGet: "products.get";
-    readonly productsList: "products.list";
-    readonly productsReviewsList: "products.reviews.list";
-    readonly productsReviewsSubmit: "products.reviews.submit";
-    readonly productsReviewsEligibility: "products.reviews.eligibility";
-    readonly productsReviewsUpload: "products.reviews.upload";
-    readonly pagesGet: "pages.get";
-    readonly pagesLanding: "pages.landing";
-    readonly menusGet: "menus.get";
-    readonly collectionsGet: "collections.get";
-    readonly shippingRates: "shipping.rates";
-    readonly shippingRate: "shipping.rate";
-    readonly geoCommunes: "geo.communes";
-    readonly cartValidate: "cart.validate";
-    readonly pageDataGet: "pageData.get";
-    readonly ordersCreate: "orders.create";
-    readonly ordersTracking: "orders.tracking";
-    readonly ordersAbandonedUpsert: "orders.abandoned.upsert";
-    readonly ordersAbandonedConvert: "orders.abandoned.convert";
-    readonly ordersOtpSend: "orders.otp.send";
-    readonly ordersOtpVerify: "orders.otp.verify";
-};
-export type StorefrontOperation = (typeof STOREFRONT_OPERATIONS)[keyof typeof STOREFRONT_OPERATIONS];
-/**
- * The retry policy per operation, as a contract a caller can read.
- *
- * The transport enforces it by kind: every `safe-read` goes through the
- * caching/deduplicating GET path, which repeats a transport or 5xx failure,
- * while every `never` goes through the POST/PATCH path, which returns a result
- * and never retries (a replayed write is how a shopper ends up with two
- * orders). A test asserts this table covers every public operation and agrees
- * with that classification, so a new operation cannot ship unclassified.
- */
-export declare const STOREFRONT_RETRY_POLICIES: {
-    readonly "cart.validate": "safe-read";
-    readonly "categories.list": "safe-read";
-    readonly "config.get": "safe-read";
-    readonly "geo.communes": "safe-read";
-    readonly "orders.abandoned.convert": "never";
-    readonly "orders.abandoned.upsert": "never";
-    readonly "orders.create": "never";
-    readonly "orders.otp.send": "never";
-    readonly "orders.otp.verify": "never";
-    readonly "orders.tracking": "safe-read";
-    readonly "pageData.get": "safe-read";
-    readonly "pages.get": "safe-read";
-    readonly "pages.landing": "safe-read";
-    readonly "menus.get": "safe-read";
-    readonly "collections.get": "safe-read";
-    readonly "products.get": "safe-read";
-    readonly "products.list": "safe-read";
-    readonly "products.reviews.list": "safe-read";
-    readonly "products.reviews.submit": "never";
-    readonly "products.reviews.eligibility": "never";
-    readonly "products.reviews.upload": "never";
-    readonly "shipping.rate": "safe-read";
-    readonly "shipping.rates": "safe-read";
-};

package/dist/domain.js

@@ -1,8 +1,6 @@
 import { z } from "zod";
 import { WILAYAS } from "./data/wilayas.js";
-/** The server's hard limits for one canonical browser basket. */
-export const MAX_BASKET_LINES = 20;
-export const MAX_BASKET_LINE_QUANTITY = 100;
+import { MAX_BASKET_LINES, MAX_BASKET_LINE_QUANTITY, basketLineKey } from "./basket-line.js";
 /**
  * A wilaya id, bounded by the reference dataset itself rather than a literal.
  *
@@ -11,13 +9,6 @@ export const MAX_BASKET_LINE_QUANTITY = 100;
  * range in step.
  */
 export const WilayaIdSchema = z.number().int().min(1).max(WILAYAS.length);
-/**
- * Product + variant is the identity of a basket line. A null variant is a
- * real identity, not the same thing as any selected variant.
- */
-export function basketLineKey(productId, variantId) {
-    return `${productId}\u0000${variantId ?? ""}`;
-}
 /**
  * A browser-owned basket line. `unitPrice` is an optimistic display value;
  * the server re-prices every line during validation and order creation.
@@ -31,6 +22,11 @@ export const BasketLineSchema = z.object({
     unitPrice: z.number().finite().nonnegative(),
     href: z.string().min(1).optional(),
     image: z.string().min(1).optional(),
+    /**
+     * The offer the shopper chose for this line, when they picked a tier. The
+     * server still applies it only if it holds for the quantity.
+     */
+    offerId: z.string().min(1).max(200).optional(),
 });
 /**
  * The server-facing projection of a basket line. UI-only fields are omitted,
@@ -196,63 +192,3 @@ export const TrackingDecisionSchema = z.object({
     pixelId: z.string().nullable(),
     event: z.enum(["Purchase", "Lead"]).nullable(),
 });
-export const STOREFRONT_OPERATIONS = {
-    configGet: "config.get",
-    categoriesList: "categories.list",
-    productsGet: "products.get",
-    productsList: "products.list",
-    productsReviewsList: "products.reviews.list",
-    productsReviewsSubmit: "products.reviews.submit",
-    productsReviewsEligibility: "products.reviews.eligibility",
-    productsReviewsUpload: "products.reviews.upload",
-    pagesGet: "pages.get",
-    pagesLanding: "pages.landing",
-    menusGet: "menus.get",
-    collectionsGet: "collections.get",
-    shippingRates: "shipping.rates",
-    shippingRate: "shipping.rate",
-    geoCommunes: "geo.communes",
-    cartValidate: "cart.validate",
-    pageDataGet: "pageData.get",
-    ordersCreate: "orders.create",
-    ordersTracking: "orders.tracking",
-    ordersAbandonedUpsert: "orders.abandoned.upsert",
-    ordersAbandonedConvert: "orders.abandoned.convert",
-    ordersOtpSend: "orders.otp.send",
-    ordersOtpVerify: "orders.otp.verify",
-};
-/**
- * The retry policy per operation, as a contract a caller can read.
- *
- * The transport enforces it by kind: every `safe-read` goes through the
- * caching/deduplicating GET path, which repeats a transport or 5xx failure,
- * while every `never` goes through the POST/PATCH path, which returns a result
- * and never retries (a replayed write is how a shopper ends up with two
- * orders). A test asserts this table covers every public operation and agrees
- * with that classification, so a new operation cannot ship unclassified.
- */
-export const STOREFRONT_RETRY_POLICIES = {
-    [STOREFRONT_OPERATIONS.cartValidate]: "safe-read",
-    [STOREFRONT_OPERATIONS.categoriesList]: "safe-read",
-    [STOREFRONT_OPERATIONS.configGet]: "safe-read",
-    [STOREFRONT_OPERATIONS.geoCommunes]: "safe-read",
-    [STOREFRONT_OPERATIONS.ordersAbandonedConvert]: "never",
-    [STOREFRONT_OPERATIONS.ordersAbandonedUpsert]: "never",
-    [STOREFRONT_OPERATIONS.ordersCreate]: "never",
-    [STOREFRONT_OPERATIONS.ordersOtpSend]: "never",
-    [STOREFRONT_OPERATIONS.ordersOtpVerify]: "never",
-    [STOREFRONT_OPERATIONS.ordersTracking]: "safe-read",
-    [STOREFRONT_OPERATIONS.pageDataGet]: "safe-read",
-    [STOREFRONT_OPERATIONS.pagesGet]: "safe-read",
-    [STOREFRONT_OPERATIONS.pagesLanding]: "safe-read",
-    [STOREFRONT_OPERATIONS.menusGet]: "safe-read",
-    [STOREFRONT_OPERATIONS.collectionsGet]: "safe-read",
-    [STOREFRONT_OPERATIONS.productsGet]: "safe-read",
-    [STOREFRONT_OPERATIONS.productsList]: "safe-read",
-    [STOREFRONT_OPERATIONS.productsReviewsList]: "safe-read",
-    [STOREFRONT_OPERATIONS.productsReviewsSubmit]: "never",
-    [STOREFRONT_OPERATIONS.productsReviewsEligibility]: "never",
-    [STOREFRONT_OPERATIONS.productsReviewsUpload]: "never",
-    [STOREFRONT_OPERATIONS.shippingRate]: "safe-read",
-    [STOREFRONT_OPERATIONS.shippingRates]: "safe-read",
-};

package/dist/endpoints/storefront-routes.js

@@ -22,7 +22,8 @@
  * (see `createProxyEndpoint`), and the server's diagnostic fields ride along.
  */
 import { z } from "zod";
-import { AbandonedCheckoutInputSchema, BasketLineInputSchema, DeliveryDestinationSchema, ProductQuoteInputSchema, MAX_BASKET_LINES, WilayaIdSchema, } from "../domain.js";
+import { AbandonedCheckoutInputSchema, BasketLineInputSchema, DeliveryDestinationSchema, ProductQuoteInputSchema, WilayaIdSchema, } from "../domain.js";
+import { MAX_BASKET_LINES } from "../basket-line.js";
 import { createProxyEndpoint, } from "./proxy.js";
 export const REVIEWS_PAGE_DEFAULT = 20;
 export const REVIEWS_PAGE_MAX = 50;

package/dist/index.d.ts

@@ -23,16 +23,20 @@ export { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "
 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 { MAX_BASKET_LINES, MAX_BASKET_LINE_QUANTITY, basketLineKey } from "./basket-line.js";
 export type { BasketStore, BasketStorageAdapter, BasketStoreOptions, BasketListener, } from "./basket.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";
 export { ALGERIA_COMMUNES, communesForWilaya } from "./data/communes.js";
+export { isWilayaId } from "./wilaya-id.js";
+export { readCouponOutcome, readShippingRates } from "./answer-readers.js";
 export type { CommuneTuple } from "./data/communes.js";
 export { normalizeAlgerianPhone, toLocalAlgerianMobile } from "./phone.js";
 export * from "./types.js";
 export * from "./schemas.js";
 export * from "./domain.js";
+export * from "./operations.js";
 export * from "./product-view.js";
 export { getOfferTierView, getQuantityTierViews } from "./offer-view.js";
 export { COUPON_NOT_APPLICABLE, COUPON_URL_PARAM, couponFromUrl, couponRefusalOf } from "./coupon.js";

package/dist/index.js

@@ -17,13 +17,17 @@ export { STOREFRONT_PAGE_PATHS, STOREFRONT_ROUTES, matchStorefrontPath, showsWid
 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 { MAX_BASKET_LINES, MAX_BASKET_LINE_QUANTITY, basketLineKey } from "./basket-line.js";
 export { createOtpMachine, createOtpTransport, mapOtpResponse, otpTransportFailure, } from "./otp.js";
 export { WILAYAS } from "./data/wilayas.js";
 export { ALGERIA_COMMUNES, communesForWilaya } from "./data/communes.js";
+export { isWilayaId } from "./wilaya-id.js";
+export { readCouponOutcome, readShippingRates } from "./answer-readers.js";
 export { normalizeAlgerianPhone, toLocalAlgerianMobile } from "./phone.js";
 export * from "./types.js";
 export * from "./schemas.js";
 export * from "./domain.js";
+export * from "./operations.js";
 export * from "./product-view.js";
 export { getOfferTierView, getQuantityTierViews } from "./offer-view.js";
 export { COUPON_NOT_APPLICABLE, COUPON_URL_PARAM, couponFromUrl, couponRefusalOf } from "./coupon.js";

package/dist/operations.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The platform operations a storefront calls, and the retry policy each one
+ * keeps. Plain values and no schema: browser code reads the operation names
+ * too — an OTP route's failure names the operation it was — so this module
+ * stays free of anything that would bring a validator into a shopper's page.
+ */
+export type RetryPolicy = "safe-read" | "never";
+export declare const STOREFRONT_OPERATIONS: {
+    readonly configGet: "config.get";
+    readonly categoriesList: "categories.list";
+    readonly productsGet: "products.get";
+    readonly productsList: "products.list";
+    readonly productsReviewsList: "products.reviews.list";
+    readonly productsReviewsSubmit: "products.reviews.submit";
+    readonly productsReviewsEligibility: "products.reviews.eligibility";
+    readonly productsReviewsUpload: "products.reviews.upload";
+    readonly pagesGet: "pages.get";
+    readonly pagesLanding: "pages.landing";
+    readonly menusGet: "menus.get";
+    readonly collectionsGet: "collections.get";
+    readonly shippingRates: "shipping.rates";
+    readonly shippingRate: "shipping.rate";
+    readonly geoCommunes: "geo.communes";
+    readonly cartValidate: "cart.validate";
+    readonly pageDataGet: "pageData.get";
+    readonly ordersCreate: "orders.create";
+    readonly ordersTracking: "orders.tracking";
+    readonly ordersAbandonedUpsert: "orders.abandoned.upsert";
+    readonly ordersAbandonedConvert: "orders.abandoned.convert";
+    readonly ordersOtpSend: "orders.otp.send";
+    readonly ordersOtpVerify: "orders.otp.verify";
+};
+export type StorefrontOperation = (typeof STOREFRONT_OPERATIONS)[keyof typeof STOREFRONT_OPERATIONS];
+/**
+ * The retry policy per operation, as a contract a caller can read.
+ *
+ * The transport enforces it by kind: every `safe-read` goes through the
+ * caching/deduplicating GET path, which repeats a transport or 5xx failure,
+ * while every `never` goes through the POST/PATCH path, which returns a result
+ * and never retries (a replayed write is how a shopper ends up with two
+ * orders). A test asserts this table covers every public operation and agrees
+ * with that classification, so a new operation cannot ship unclassified.
+ */
+export declare const STOREFRONT_RETRY_POLICIES: {
+    readonly "cart.validate": "safe-read";
+    readonly "categories.list": "safe-read";
+    readonly "config.get": "safe-read";
+    readonly "geo.communes": "safe-read";
+    readonly "orders.abandoned.convert": "never";
+    readonly "orders.abandoned.upsert": "never";
+    readonly "orders.create": "never";
+    readonly "orders.otp.send": "never";
+    readonly "orders.otp.verify": "never";
+    readonly "orders.tracking": "safe-read";
+    readonly "pageData.get": "safe-read";
+    readonly "pages.get": "safe-read";
+    readonly "pages.landing": "safe-read";
+    readonly "menus.get": "safe-read";
+    readonly "collections.get": "safe-read";
+    readonly "products.get": "safe-read";
+    readonly "products.list": "safe-read";
+    readonly "products.reviews.list": "safe-read";
+    readonly "products.reviews.submit": "never";
+    readonly "products.reviews.eligibility": "never";
+    readonly "products.reviews.upload": "never";
+    readonly "shipping.rate": "safe-read";
+    readonly "shipping.rates": "safe-read";
+};

package/dist/operations.js

@@ -0,0 +1,66 @@
+/**
+ * The platform operations a storefront calls, and the retry policy each one
+ * keeps. Plain values and no schema: browser code reads the operation names
+ * too — an OTP route's failure names the operation it was — so this module
+ * stays free of anything that would bring a validator into a shopper's page.
+ */
+export const STOREFRONT_OPERATIONS = {
+    configGet: "config.get",
+    categoriesList: "categories.list",
+    productsGet: "products.get",
+    productsList: "products.list",
+    productsReviewsList: "products.reviews.list",
+    productsReviewsSubmit: "products.reviews.submit",
+    productsReviewsEligibility: "products.reviews.eligibility",
+    productsReviewsUpload: "products.reviews.upload",
+    pagesGet: "pages.get",
+    pagesLanding: "pages.landing",
+    menusGet: "menus.get",
+    collectionsGet: "collections.get",
+    shippingRates: "shipping.rates",
+    shippingRate: "shipping.rate",
+    geoCommunes: "geo.communes",
+    cartValidate: "cart.validate",
+    pageDataGet: "pageData.get",
+    ordersCreate: "orders.create",
+    ordersTracking: "orders.tracking",
+    ordersAbandonedUpsert: "orders.abandoned.upsert",
+    ordersAbandonedConvert: "orders.abandoned.convert",
+    ordersOtpSend: "orders.otp.send",
+    ordersOtpVerify: "orders.otp.verify",
+};
+/**
+ * The retry policy per operation, as a contract a caller can read.
+ *
+ * The transport enforces it by kind: every `safe-read` goes through the
+ * caching/deduplicating GET path, which repeats a transport or 5xx failure,
+ * while every `never` goes through the POST/PATCH path, which returns a result
+ * and never retries (a replayed write is how a shopper ends up with two
+ * orders). A test asserts this table covers every public operation and agrees
+ * with that classification, so a new operation cannot ship unclassified.
+ */
+export const STOREFRONT_RETRY_POLICIES = {
+    [STOREFRONT_OPERATIONS.cartValidate]: "safe-read",
+    [STOREFRONT_OPERATIONS.categoriesList]: "safe-read",
+    [STOREFRONT_OPERATIONS.configGet]: "safe-read",
+    [STOREFRONT_OPERATIONS.geoCommunes]: "safe-read",
+    [STOREFRONT_OPERATIONS.ordersAbandonedConvert]: "never",
+    [STOREFRONT_OPERATIONS.ordersAbandonedUpsert]: "never",
+    [STOREFRONT_OPERATIONS.ordersCreate]: "never",
+    [STOREFRONT_OPERATIONS.ordersOtpSend]: "never",
+    [STOREFRONT_OPERATIONS.ordersOtpVerify]: "never",
+    [STOREFRONT_OPERATIONS.ordersTracking]: "safe-read",
+    [STOREFRONT_OPERATIONS.pageDataGet]: "safe-read",
+    [STOREFRONT_OPERATIONS.pagesGet]: "safe-read",
+    [STOREFRONT_OPERATIONS.pagesLanding]: "safe-read",
+    [STOREFRONT_OPERATIONS.menusGet]: "safe-read",
+    [STOREFRONT_OPERATIONS.collectionsGet]: "safe-read",
+    [STOREFRONT_OPERATIONS.productsGet]: "safe-read",
+    [STOREFRONT_OPERATIONS.productsList]: "safe-read",
+    [STOREFRONT_OPERATIONS.productsReviewsList]: "safe-read",
+    [STOREFRONT_OPERATIONS.productsReviewsSubmit]: "never",
+    [STOREFRONT_OPERATIONS.productsReviewsEligibility]: "never",
+    [STOREFRONT_OPERATIONS.productsReviewsUpload]: "never",
+    [STOREFRONT_OPERATIONS.shippingRate]: "safe-read",
+    [STOREFRONT_OPERATIONS.shippingRates]: "safe-read",
+};

package/dist/otp.d.ts

@@ -46,7 +46,14 @@ export declare function createOtpTransport(options: {
     verify: OtpTransport["verify"];
 }): OtpTransport;
 export interface OtpResponseOptions<T> {
-    schema: z.Schema<T>;
+    /**
+     * Checks the answer's `data`. Leave it out to read an answer of this
+     * package's own `otpSend` / `otpVerify` routes: their client already checked
+     * it on the server with `OtpSendResultSchema` / `OtpVerifyResultSchema`, and
+     * a schema here would only ship Zod to every shopper's browser. Pass one for
+     * an endpoint of your own.
+     */
+    schema?: z.Schema<T>;
     operation: string;
     fallbackError: string;
 }

package/dist/otp.js

@@ -77,6 +77,9 @@ export async function mapOtpResponse(response, options) {
     if (!response.ok) {
         return mapFailure(body, options, `HTTP_${response.status}`);
     }
+    if (options.schema === undefined) {
+        return isRecord(body.data) ? { success: true, data: body.data } : mapFailure(body, options, "MALFORMED_RESPONSE");
+    }
     const parsed = options.schema.safeParse(body.data);
     if (!parsed.success) {
         return mapFailure(body, options, "SCHEMA_VALIDATION_FAILED");

package/dist/wilaya-id.d.ts

@@ -0,0 +1 @@
+export declare function isWilayaId(value: unknown): value is number;

package/dist/wilaya-id.js

@@ -0,0 +1,10 @@
+/**
+ * Whether a value is a wilaya id: an integer from 1 to the number of wilayas
+ * in the reference dataset. It is the range `WilayaIdSchema` checks on the
+ * server, read from the same `WILAYAS`, so the two cannot disagree — for the
+ * browser, which checks a selected wilaya before asking for its communes.
+ */
+import { WILAYAS } from "./data/wilayas.js";
+export function isWilayaId(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= WILAYAS.length;
+}

package/package.json

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