@wocart/storefront 0.0.0-stage → 1.0.0

package/dist/data/wilayas.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Algeria's 58 wilayas — static reference data, also served through
+ * `geo.wilayas()`.
+ */
+import type { Wilaya } from "../types.js";
+export declare const WILAYAS: Wilaya[];

package/dist/data/wilayas.js

@@ -0,0 +1,64 @@
+/**
+ * Algeria's 58 wilayas — static reference data, also served through
+ * `geo.wilayas()`.
+ */
+export const WILAYAS = [
+    { id: 1, name: "Adrar", nameAr: "أدرار" },
+    { id: 2, name: "Chlef", nameAr: "الشلف" },
+    { id: 3, name: "Laghouat", nameAr: "الأغواط" },
+    { id: 4, name: "Oum El Bouaghi", nameAr: "أم البواقي" },
+    { id: 5, name: "Batna", nameAr: "باتنة" },
+    { id: 6, name: "Béjaïa", nameAr: "بجاية" },
+    { id: 7, name: "Biskra", nameAr: "بسكرة" },
+    { id: 8, name: "Béchar", nameAr: "بشار" },
+    { id: 9, name: "Blida", nameAr: "البليدة" },
+    { id: 10, name: "Bouira", nameAr: "البويرة" },
+    { id: 11, name: "Tamanrasset", nameAr: "تمنراست" },
+    { id: 12, name: "Tébessa", nameAr: "تبسة" },
+    { id: 13, name: "Tlemcen", nameAr: "تلمسان" },
+    { id: 14, name: "Tiaret", nameAr: "تيارت" },
+    { id: 15, name: "Tizi Ouzou", nameAr: "تيزي وزو" },
+    { id: 16, name: "Alger", nameAr: "الجزائر" },
+    { id: 17, name: "Djelfa", nameAr: "الجلفة" },
+    { id: 18, name: "Jijel", nameAr: "جيجل" },
+    { id: 19, name: "Sétif", nameAr: "سطيف" },
+    { id: 20, name: "Saïda", nameAr: "سعيدة" },
+    { id: 21, name: "Skikda", nameAr: "سكيكدة" },
+    { id: 22, name: "Sidi Bel Abbès", nameAr: "سيدي بلعباس" },
+    { id: 23, name: "Annaba", nameAr: "عنابة" },
+    { id: 24, name: "Guelma", nameAr: "قالمة" },
+    { id: 25, name: "Constantine", nameAr: "قسنطينة" },
+    { id: 26, name: "Médéa", nameAr: "المدية" },
+    { id: 27, name: "Mostaganem", nameAr: "مستغانم" },
+    { id: 28, name: "M'Sila", nameAr: "المسيلة" },
+    { id: 29, name: "Mascara", nameAr: "معسكر" },
+    { id: 30, name: "Ouargla", nameAr: "ورقلة" },
+    { id: 31, name: "Oran", nameAr: "وهران" },
+    { id: 32, name: "El Bayadh", nameAr: "البيض" },
+    { id: 33, name: "Illizi", nameAr: "إليزي" },
+    { id: 34, name: "Bordj Bou Arréridj", nameAr: "برج بوعريريج" },
+    { id: 35, name: "Boumerdès", nameAr: "بومرداس" },
+    { id: 36, name: "El Tarf", nameAr: "الطارف" },
+    { id: 37, name: "Tindouf", nameAr: "تندوف" },
+    { id: 38, name: "Tissemsilt", nameAr: "تيسمسيلت" },
+    { id: 39, name: "El Oued", nameAr: "الوادي" },
+    { id: 40, name: "Khenchela", nameAr: "خنشلة" },
+    { id: 41, name: "Souk Ahras", nameAr: "سوق أهراس" },
+    { id: 42, name: "Tipaza", nameAr: "تيبازة" },
+    { id: 43, name: "Mila", nameAr: "ميلة" },
+    { id: 44, name: "Aïn Defla", nameAr: "عين الدفلى" },
+    { id: 45, name: "Naâma", nameAr: "النعامة" },
+    { id: 46, name: "Aïn Témouchent", nameAr: "عين تموشنت" },
+    { id: 47, name: "Ghardaïa", nameAr: "غرداية" },
+    { id: 48, name: "Relizane", nameAr: "غليزان" },
+    { id: 49, name: "Timimoun", nameAr: "تيميمون" },
+    { id: 50, name: "Bordj Badji Mokhtar", nameAr: "برج باجي مختار" },
+    { id: 51, name: "Ouled Djellal", nameAr: "أولاد جلال" },
+    { id: 52, name: "Béni Abbès", nameAr: "بني عباس" },
+    { id: 53, name: "In Salah", nameAr: "عين صالح" },
+    { id: 54, name: "In Guezzam", nameAr: "عين قزام" },
+    { id: 55, name: "Touggourt", nameAr: "تقرت" },
+    { id: 56, name: "Djanet", nameAr: "جانت" },
+    { id: 57, name: "El M'Ghair", nameAr: "المغير" },
+    { id: 58, name: "El Meniaa", nameAr: "المنيعة" },
+];

package/dist/domain.d.ts

@@ -0,0 +1,332 @@
+import { z } from "zod";
+/**
+ * The scope of one Store Client. A client is never a cross-store client: its
+ * API key selects exactly one store and its caches live inside that client.
+ * This type is exported from the browser-safe barrel for type reuse only; the
+ * API key must still be supplied and retained by server-side code.
+ */
+export interface StoreScope {
+    readonly serverUrl: string;
+    readonly apiKey: string;
+    /**
+     * The key of the theme this client renders (`defineTheme({ key })` in
+     * `@wocart/theme`). The store's edits to that theme's text arrive as
+     * `StoreConfig.contentOverrides`; without it there are none, because edits
+     * belong to the theme that declares their keys. The server owns the key
+     * format and refuses a malformed one.
+     */
+    readonly theme?: string;
+    /**
+     * The language this client reads merchant text in (BCP 47, e.g. `fr`) —
+     * Shopify Hydrogen's per-request i18n. The server serves it when the store
+     * publishes it and the primary otherwise; `StoreConfig.locale` says which.
+     * Untranslated fields fall back to the primary one by one. Create one client
+     * per language: each keeps its own caches. Omit it for the primary.
+     */
+    readonly locale?: string;
+    /**
+     * Opt-in degradation hook. Reads resolve to `null`/`[]`/`{}` when a call
+     * cannot be completed — that is the theme-facing contract and it does not
+     * change. But "the network is down" and "the server's response no longer
+     * matches the SDK's schemas" must not look identical to the operator, and
+     * a degraded read is the one failure a theme never sees. Every swallowed
+     * failure is reported here, carrying the same `DomainError` a mutation
+     * returns (`code`, `operation`, `requestId`, `retryable`). Never called on
+     * success.
+     */
+    onError?: (error: DomainError) => void;
+}
+/** 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.
+ *
+ * The server validates the same 1..58 range; deriving the ceiling from
+ * `WILAYAS` keeps the route's early rejection and the platform's accepted
+ * 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.
+ */
+export declare const BasketLineSchema: z.ZodObject<{
+    productId: z.ZodString;
+    productName: z.ZodString;
+    variantId: z.ZodNullable<z.ZodString>;
+    variantLabel: z.ZodNullable<z.ZodString>;
+    quantity: z.ZodNumber;
+    unitPrice: z.ZodNumber;
+    href: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type BasketLine = z.infer<typeof BasketLineSchema>;
+/**
+ * The server-facing projection of a basket line. UI-only fields are omitted,
+ * and `pricePerUnit` remains display-only even when present.
+ */
+export declare const BasketLineInputSchema: z.ZodObject<{
+    productId: z.ZodString;
+    productName: z.ZodString;
+    variantId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    variantLabel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    quantity: z.ZodNumber;
+    pricePerUnit: z.ZodOptional<z.ZodNumber>;
+    offerId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type BasketLineInput = z.infer<typeof BasketLineInputSchema>;
+/**
+ * A canonical browser basket. Empty is valid for a persisted cart, but every
+ * line must be unique by product + variant. Order submission requires at
+ * least one line and is governed by the Checkout Draft invariant below.
+ */
+export declare const BasketSchema: z.ZodObject<{
+    lines: z.ZodArray<z.ZodObject<{
+        productId: z.ZodString;
+        productName: z.ZodString;
+        variantId: z.ZodNullable<z.ZodString>;
+        variantLabel: z.ZodNullable<z.ZodString>;
+        quantity: z.ZodNumber;
+        unitPrice: z.ZodNumber;
+        href: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Basket = z.infer<typeof BasketSchema>;
+/**
+ * The basket-line projection used by abandoned-checkout tracking.
+ *
+ * Variant fields are optional and nullable: a product-page payload has no
+ * variant at all and omits the key (the tracker strips it with `?? undefined`),
+ * while a checkout-page payload can carry a selected variant — the proxy
+ * accepts both, so the schema must too.
+ */
+export declare const AbandonedBasketLineSchema: z.ZodObject<{
+    productId: z.ZodString;
+    productName: z.ZodString;
+    variantId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    variantLabel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    quantity: z.ZodNumber;
+    unitPrice: z.ZodNumber;
+}, z.core.$strip>;
+export type AbandonedBasketLine = z.infer<typeof AbandonedBasketLineSchema>;
+/**
+ * Runtime schema for the optional abandoned-checkout signal — the body
+ * `orders.abandoned.upsert()` accepts.
+ *
+ * This is the contract, not a convenience: a theme's abandoned-checkout route
+ * validates its body with THIS schema rather than a hand-copied twin. Bounds
+ * match the server's, with two deliberate client-side differences:
+ *
+ * - `communeId` is capped at 200 (the server has no bound; a commune id is
+ *   `c-01-001`, so nothing legitimate is refused and the proxy body stays
+ *   bounded).
+ * - `variantId`/`variantLabel` accept an explicit `null` as well as omission;
+ *   the server's top-level fields take omission only, and the tracker strips
+ *   nulls, so nothing a browser sends reaches that difference.
+ */
+export declare const AbandonedCheckoutInputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    customerName: z.ZodString;
+    phone: z.ZodString;
+    wilayaId: z.ZodOptional<z.ZodNumber>;
+    communeId: z.ZodOptional<z.ZodString>;
+    wilayaName: z.ZodOptional<z.ZodString>;
+    communeName: z.ZodOptional<z.ZodString>;
+    productId: z.ZodOptional<z.ZodString>;
+    productName: z.ZodOptional<z.ZodString>;
+    variantId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    variantLabel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    price: z.ZodOptional<z.ZodNumber>;
+    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        productId: z.ZodString;
+        productName: z.ZodString;
+        variantId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        variantLabel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        quantity: z.ZodNumber;
+        unitPrice: z.ZodNumber;
+    }, z.core.$strip>>>;
+    deliveryType: z.ZodOptional<z.ZodEnum<{
+        home: "home";
+        stop_desk: "stop_desk";
+    }>>;
+    fbc: z.ZodOptional<z.ZodString>;
+    fbp: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Exact public input for the optional abandoned-checkout signal.
+ *
+ * `variantId`/`variantLabel` follow the same omit-or-null rule as each
+ * `items[]` line: absent — not null — is the common wire shape.
+ */
+export type AbandonedCheckoutInput = z.infer<typeof AbandonedCheckoutInputSchema>;
+/** Shopper's selected delivery mode and destination. Policy decides whether address is required. */
+export declare const DeliverySelectionSchema: z.ZodObject<{
+    wilayaId: z.ZodNumber;
+    communeId: z.ZodString;
+    deliveryType: z.ZodEnum<{
+        home: "home";
+        stop_desk: "stop_desk";
+    }>;
+    address: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type DeliverySelection = z.infer<typeof DeliverySelectionSchema>;
+/** A shopper answer keyed by the server-minted checkout-field id. */
+export interface CheckoutFieldAnswer {
+    readonly id: string;
+    readonly value: string;
+}
+export interface CheckoutAttribution {
+    readonly fbc: string | null;
+    readonly fbp: string | null;
+    readonly landingPageSlug: string | null;
+}
+/**
+ * Mutable checkout intent before the server accepts an order.
+ *
+ * Invariant: `mode: "single"` has exactly one line; `mode: "basket"` has
+ * one or more lines. This is intentionally a domain contract, not a second
+ * copy of merchant checkout-policy validation: the server remains the owner
+ * of required fields, legal pages, prices, stock and delivery rules.
+ */
+export interface CheckoutDraft {
+    readonly mode: "single" | "basket";
+    readonly lines: readonly BasketLineInput[];
+    readonly customerName: string;
+    readonly phone: string;
+    readonly delivery: DeliverySelection;
+    readonly address?: string | null;
+    readonly email?: string | null;
+    readonly notes?: string | null;
+    readonly customFieldResponses: readonly CheckoutFieldAnswer[];
+    readonly otpProof: OtpProof | null;
+    readonly attribution: CheckoutAttribution;
+}
+/** Proof that the checkout phone was verified or that the provider failed open. */
+export declare const OtpProofSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"verified">;
+    phone: z.ZodString;
+    token: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"bypass">;
+    phone: z.ZodString;
+    token: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type OtpProof = z.infer<typeof OtpProofSchema>;
+/** A server-accepted purchase. Totals are authoritative only after acceptance. */
+export declare const OrderSchema: z.ZodObject<{
+    orderId: z.ZodString;
+    orderNumber: z.ZodString;
+    price: z.ZodNumber;
+    deliveryFee: z.ZodNumber;
+    total: z.ZodNumber;
+}, z.core.$strip>;
+export type Order = z.infer<typeof OrderSchema>;
+/** Server-owned decision for the thank-you page's conversion event. */
+export declare const TrackingDecisionSchema: z.ZodObject<{
+    pixelId: z.ZodNullable<z.ZodString>;
+    event: z.ZodNullable<z.ZodEnum<{
+        Lead: "Lead";
+        Purchase: "Purchase";
+    }>>;
+}, z.core.$strip>;
+export type TrackingDecision = z.infer<typeof TrackingDecisionSchema>;
+export type DomainErrorCategory = "validation" | "authentication" | "business" | "system" | "transport" | "unknown";
+export type SideEffectOutcome = "not_started" | "rejected" | "committed" | "unknown";
+export interface DomainFieldIssue {
+    readonly field: string;
+    readonly code: string;
+    readonly message: string;
+}
+/**
+ * The error shape every SDK failure normalizes to. Keeping
+ * category, retry safety, and side-effect outcome together prevents a generic
+ * retry from duplicating orders, OTP requests, reviews, or abandonment writes.
+ */
+export interface DomainError {
+    readonly category: DomainErrorCategory;
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly operation: string;
+    readonly sideEffect: SideEffectOutcome;
+    readonly fieldIssues?: readonly DomainFieldIssue[];
+    readonly retryAfterSeconds?: number;
+    /**
+     * Correlation id the server logged this failure under (`context.requestId`).
+     * The only diagnostic a theme may safely surface — it never carries customer
+     * data, and it is how a support request is traced back to one server log line.
+     */
+    readonly requestId?: string;
+}
+export type ClientResult<T> = {
+    readonly success: true;
+    readonly data: T;
+} | {
+    readonly success: false;
+    readonly error: string;
+    readonly code?: string;
+    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 pagesGet: "pages.get";
+    readonly pagesLanding: "pages.landing";
+    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 "products.get": "safe-read";
+    readonly "products.list": "safe-read";
+    readonly "products.reviews.list": "safe-read";
+    readonly "products.reviews.submit": "never";
+    readonly "shipping.rate": "safe-read";
+    readonly "shipping.rates": "safe-read";
+};

package/dist/domain.js

@@ -0,0 +1,214 @@
+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;
+/**
+ * A wilaya id, bounded by the reference dataset itself rather than a literal.
+ *
+ * The server validates the same 1..58 range; deriving the ceiling from
+ * `WILAYAS` keeps the route's early rejection and the platform's accepted
+ * 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.
+ */
+export const BasketLineSchema = z.object({
+    productId: z.string().min(1).max(200),
+    productName: z.string().min(1).max(200),
+    variantId: z.string().min(1).max(200).nullable(),
+    variantLabel: z.string().max(200).nullable(),
+    quantity: z.number().int().min(1).max(MAX_BASKET_LINE_QUANTITY),
+    unitPrice: z.number().finite().nonnegative(),
+    href: z.string().min(1).optional(),
+    image: z.string().min(1).optional(),
+});
+/**
+ * The server-facing projection of a basket line. UI-only fields are omitted,
+ * and `pricePerUnit` remains display-only even when present.
+ */
+export const BasketLineInputSchema = z.object({
+    productId: z.string().min(1).max(200),
+    productName: z.string().min(1).max(200),
+    variantId: z.string().min(1).max(200).nullable().optional(),
+    variantLabel: z.string().max(200).nullable().optional(),
+    quantity: z.number().int().min(1).max(MAX_BASKET_LINE_QUANTITY),
+    pricePerUnit: z.number().finite().nonnegative().optional(),
+    offerId: z.string().min(1).max(200).optional(),
+});
+/**
+ * A canonical browser basket. Empty is valid for a persisted cart, but every
+ * line must be unique by product + variant. Order submission requires at
+ * least one line and is governed by the Checkout Draft invariant below.
+ */
+export const BasketSchema = z
+    .object({
+    lines: z.array(BasketLineSchema).max(MAX_BASKET_LINES),
+})
+    .superRefine((basket, context) => {
+    const seen = new Set();
+    basket.lines.forEach((line, index) => {
+        const key = basketLineKey(line.productId, line.variantId);
+        if (seen.has(key)) {
+            context.addIssue({
+                code: "custom",
+                path: ["lines", index],
+                message: "Basket lines must be unique by product and variant.",
+            });
+        }
+        seen.add(key);
+    });
+});
+/**
+ * The basket-line projection used by abandoned-checkout tracking.
+ *
+ * Variant fields are optional and nullable: a product-page payload has no
+ * variant at all and omits the key (the tracker strips it with `?? undefined`),
+ * while a checkout-page payload can carry a selected variant — the proxy
+ * accepts both, so the schema must too.
+ */
+export const AbandonedBasketLineSchema = z.object({
+    productId: z.string().min(1).max(200),
+    productName: z.string().min(1).max(200),
+    variantId: z.string().max(200).nullish(),
+    variantLabel: z.string().max(200).nullish(),
+    quantity: z.number().int().min(1).max(MAX_BASKET_LINE_QUANTITY),
+    unitPrice: z.number().nonnegative(),
+});
+/**
+ * Runtime schema for the optional abandoned-checkout signal — the body
+ * `orders.abandoned.upsert()` accepts.
+ *
+ * This is the contract, not a convenience: a theme's abandoned-checkout route
+ * validates its body with THIS schema rather than a hand-copied twin. Bounds
+ * match the server's, with two deliberate client-side differences:
+ *
+ * - `communeId` is capped at 200 (the server has no bound; a commune id is
+ *   `c-01-001`, so nothing legitimate is refused and the proxy body stays
+ *   bounded).
+ * - `variantId`/`variantLabel` accept an explicit `null` as well as omission;
+ *   the server's top-level fields take omission only, and the tracker strips
+ *   nulls, so nothing a browser sends reaches that difference.
+ */
+export const AbandonedCheckoutInputSchema = z.object({
+    sessionId: z.string().uuid(),
+    customerName: z.string().min(2).max(100),
+    phone: z
+        .string()
+        .min(9)
+        .max(20)
+        .regex(/^[0-9+\s-]+$/),
+    wilayaId: WilayaIdSchema.optional(),
+    communeId: z.string().max(200).optional(),
+    wilayaName: z.string().max(100).optional(),
+    communeName: z.string().max(100).optional(),
+    productId: z.string().max(200).optional(),
+    productName: z.string().max(200).optional(),
+    variantId: z.string().max(200).nullish(),
+    variantLabel: z.string().max(200).nullish(),
+    price: z.number().positive().optional(),
+    /** The whole basket, when the shopper walked away from a cart checkout. */
+    items: z
+        .array(AbandonedBasketLineSchema)
+        .min(1)
+        .max(MAX_BASKET_LINES)
+        .optional(),
+    deliveryType: z.enum(["home", "stop_desk"]).optional(),
+    fbc: z.string().max(500).optional(),
+    fbp: z.string().max(500).optional(),
+});
+/** Shopper's selected delivery mode and destination. Policy decides whether address is required. */
+export const DeliverySelectionSchema = z.object({
+    wilayaId: z.number().int().min(1).max(58),
+    communeId: z.string().min(1),
+    deliveryType: z.enum(["home", "stop_desk"]),
+    address: z.string().max(300).nullable().optional(),
+});
+/** Proof that the checkout phone was verified or that the provider failed open. */
+export const OtpProofSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("verified"),
+        phone: z.string().min(1),
+        token: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal("bypass"),
+        phone: z.string().min(1),
+        token: z.string().min(1),
+        reason: z.string().min(1),
+    }),
+]);
+/** A server-accepted purchase. Totals are authoritative only after acceptance. */
+export const OrderSchema = z.object({
+    orderId: z.string().min(1),
+    orderNumber: z.string().min(1),
+    price: z.number().finite().nonnegative(),
+    deliveryFee: z.number().finite().nonnegative(),
+    total: z.number().finite().nonnegative(),
+});
+/** Server-owned decision for the thank-you page's conversion event. */
+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",
+    pagesGet: "pages.get",
+    pagesLanding: "pages.landing",
+    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.productsGet]: "safe-read",
+    [STOREFRONT_OPERATIONS.productsList]: "safe-read",
+    [STOREFRONT_OPERATIONS.productsReviewsList]: "safe-read",
+    [STOREFRONT_OPERATIONS.productsReviewsSubmit]: "never",
+    [STOREFRONT_OPERATIONS.shippingRate]: "safe-read",
+    [STOREFRONT_OPERATIONS.shippingRates]: "safe-read",
+};