@wocart/storefront 0.0.0-stage → 1.1.0

package/dist/client/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Store Client Factory — the SDK's front door.
+ *
+ * One server-side call builds the whole read/write surface a theme needs, over one
+ * shared core: config, products, categories, pages, shipping, geo, cart,
+ * orders. The core is internal — consumers see only namespaces.
+ *
+ * One core means one connection story for every namespace: every read is
+ * bounded by the client's `readTimeoutMs`, each call makes its own request
+ * (none waits on another's pending one), and the opt-in caches (config,
+ * categories, communes) keep finished results per client instance.
+ * A theme server render typically builds one client per request.
+ *
+ * ```ts
+ * import { createStoreClient } from "@wocart/storefront/server";
+ *
+ * const store = createStoreClient({
+ *   serverUrl: env.COD_SERVER_URL,
+ *   apiKey: env.STORE_API_KEY,
+ * });
+ *
+ * const [config, products] = await Promise.all([
+ *   store.config.get(),
+ *   store.products.list({ featured: true, limit: 8 }),
+ * ]);
+ * ```
+ */
+import type { StoreScope } from "../domain.js";
+export declare function createStoreClient(config: StoreScope): {
+    config: import("./config.js").ConfigNamespace;
+    products: import("./products.js").ProductsNamespace;
+    categories: import("./categories.js").CategoriesNamespace;
+    pages: import("./pages.js").PagesNamespace;
+    pageData: import("./page-data.js").PageDataNamespace;
+    shipping: import("./shipping.js").ShippingNamespace;
+    geo: import("./geo.js").GeoNamespace;
+    cart: import("./cart.js").CartNamespace;
+    orders: import("./orders.js").OrdersNamespace;
+};
+export type StoreClient = ReturnType<typeof createStoreClient>;

package/dist/client/index.js

@@ -0,0 +1,81 @@
+/**
+ * Store Client Factory — the SDK's front door.
+ *
+ * One server-side call builds the whole read/write surface a theme needs, over one
+ * shared core: config, products, categories, pages, shipping, geo, cart,
+ * orders. The core is internal — consumers see only namespaces.
+ *
+ * One core means one connection story for every namespace: every read is
+ * bounded by the client's `readTimeoutMs`, each call makes its own request
+ * (none waits on another's pending one), and the opt-in caches (config,
+ * categories, communes) keep finished results per client instance.
+ * A theme server render typically builds one client per request.
+ *
+ * ```ts
+ * import { createStoreClient } from "@wocart/storefront/server";
+ *
+ * const store = createStoreClient({
+ *   serverUrl: env.COD_SERVER_URL,
+ *   apiKey: env.STORE_API_KEY,
+ * });
+ *
+ * const [config, products] = await Promise.all([
+ *   store.config.get(),
+ *   store.products.list({ featured: true, limit: 8 }),
+ * ]);
+ * ```
+ */
+import { createClientCore } from "./core.js";
+import { StorefrontError } from "./errors.js";
+import { createConfigNamespace } from "./config.js";
+import { createProductsNamespace } from "./products.js";
+import { createCategoriesNamespace } from "./categories.js";
+import { createPagesNamespace } from "./pages.js";
+import { createPageDataNamespace } from "./page-data.js";
+import { createShippingNamespace } from "./shipping.js";
+import { createGeoNamespace } from "./geo.js";
+import { createCartNamespace } from "./cart.js";
+import { createOrdersNamespace } from "./orders.js";
+export function createStoreClient(config) {
+    assertUsableScope(config);
+    const core = createClientCore(config);
+    return {
+        config: createConfigNamespace(core),
+        products: createProductsNamespace(core),
+        categories: createCategoriesNamespace(core),
+        pages: createPagesNamespace(core),
+        pageData: createPageDataNamespace(core),
+        shipping: createShippingNamespace(core),
+        geo: createGeoNamespace(core),
+        cart: createCartNamespace(core),
+        orders: createOrdersNamespace(core),
+    };
+}
+/**
+ * One place where an unusable configuration becomes a loud setup error.
+ *
+ * An empty `serverUrl` or `apiKey` (the shape a missing environment variable
+ * takes after a cast) would otherwise send unauthenticated requests and turn
+ * every read into an empty store — a silent failure that looks like "no
+ * products". Reads keep their never-throw contract *after* construction; this
+ * throws only at setup, where the caller can still fix the variable.
+ */
+function assertUsableScope(config) {
+    const required = [
+        ["serverUrl", "COD_SERVER_URL", config?.serverUrl],
+        ["apiKey", "STORE_API_KEY", config?.apiKey],
+    ];
+    for (const [field, envName, value] of required) {
+        if (typeof value === "string" && value.trim() !== "")
+            continue;
+        throw new StorefrontError({
+            category: "authentication",
+            code: "MISSING_CONFIGURATION",
+            message: `createStoreClient: \`${field}\` is empty — set ${envName} before building ` +
+                `the client. Without it every read would return an empty store instead of failing.`,
+            retryable: false,
+            operation: "client.create",
+            sideEffect: "not_started",
+        });
+    }
+}

package/dist/client/orders.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Orders Namespace - Checkout, Tracking, Abandonment, OTP
+ *
+ * Deep module: hides five endpoints and their differing wire contracts
+ * ({data} envelopes, a top-level {success, id}, fire-and-forget PATCH,
+ * OTP context flattening) behind one small surface.
+ *
+ * Failure contracts:
+ * - create/abandoned/otp return errors as results (never throw) — the
+ *   checkout form must stay on screen and render the reason.
+ * - tracking resolves to null on any failure — firing no conversion event
+ *   is recoverable; reporting it to the wrong ad account is not.
+ */
+import { type ClientCore, type ClientResult } from "./core.js";
+import type { AbandonedCheckoutInput } from "../domain.js";
+import type { CreateOrderInput, CreatedOrder, OrderTracking, OtpSendResult, OtpVerifyResult } from "../types.js";
+export interface AbandonedNamespace {
+    /**
+     * Upsert an abandoned-checkout record — fire-and-forget. `forwardedHeaders`
+     * carries the shopper's User-Agent / forwarding headers so attribution
+     * reflects the visitor, not this worker.
+     */
+    upsert(body: AbandonedCheckoutInput, forwardedHeaders?: Record<string, string>): Promise<ClientResult<{
+        id: string;
+    }>>;
+    /**
+     * Mark an abandoned session as converted after a successful order.
+     * The server treats this as fire-and-forget (always 200).
+     */
+    convert(sessionId: string, orderId: string, orderNumber: string): Promise<ClientResult<null>>;
+}
+export interface OtpNamespace {
+    /**
+     * Send a WhatsApp verification code. On "unavailable" the server returns
+     * a signed bypassToken — checkout proceeds unverified (fail-open).
+     * Rate-limit errors carry `code: "OTP_RATE_LIMITED"` and `windowSeconds`.
+     */
+    send(phone: string): Promise<ClientResult<OtpSendResult>>;
+    /**
+     * Verify the code the customer typed. Wrong-but-retryable codes return
+     * `code`/`attemptsRemaining`/`terminal` on the error result; a success
+     * returns the signed `otpToken` that travels with the order.
+     */
+    verify(phone: string, requestId: string, code: string): Promise<ClientResult<OtpVerifyResult>>;
+}
+export interface OrdersNamespace {
+    /**
+     * Submit an order. The server re-prices every line from the catalog —
+     * `pricePerUnit` arriving from the browser is display-only. Attribution
+     * headers (forwarded from the proxy) ride along here, not on the body.
+     * The body is the SDK's `CreateOrderInput`; `PlaceOrderInput` (the form
+     * whitelist) is assignable to it, so an action can pass its parsed input
+     * straight through.
+     */
+    create(body: CreateOrderInput, forwardedHeaders?: Record<string, string>): Promise<ClientResult<CreatedOrder>>;
+    /**
+     * The order's tracking destination (which Meta pixel, which browser
+     * event). Resolves to `null` on any failure or an empty orderId —
+     * the thank-you page fires no conversion at all in that case.
+     */
+    tracking(orderId: string): Promise<OrderTracking | null>;
+    abandoned: AbandonedNamespace;
+    otp: OtpNamespace;
+}
+/**
+ * Create orders namespace
+ */
+export declare function createOrdersNamespace(core: ClientCore): OrdersNamespace;

package/dist/client/orders.js

@@ -0,0 +1,76 @@
+/**
+ * Orders Namespace - Checkout, Tracking, Abandonment, OTP
+ *
+ * Deep module: hides five endpoints and their differing wire contracts
+ * ({data} envelopes, a top-level {success, id}, fire-and-forget PATCH,
+ * OTP context flattening) behind one small surface.
+ *
+ * Failure contracts:
+ * - create/abandoned/otp return errors as results (never throw) — the
+ *   checkout form must stay on screen and render the reason.
+ * - tracking resolves to null on any failure — firing no conversion event
+ *   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 { reportDegradedRead } from "./core.js";
+/**
+ * Create orders namespace
+ */
+export function createOrdersNamespace(core) {
+    return {
+        async create(body, forwardedHeaders) {
+            return core.post("/store/orders", body, {
+                ...(forwardedHeaders ? { headers: forwardedHeaders } : {}),
+                schema: CreatedOrderSchema,
+                operation: STOREFRONT_OPERATIONS.ordersCreate,
+            });
+        },
+        async tracking(orderId) {
+            if (!orderId)
+                return null;
+            try {
+                const tracking = await core.get(`/store/orders/${encodeURIComponent(orderId)}/tracking`, OrderTrackingSchema.nullable(), { operation: STOREFRONT_OPERATIONS.ordersTracking });
+                return tracking ?? null;
+            }
+            catch (error) {
+                reportDegradedRead(core.config, error, "orders.tracking");
+                return null;
+            }
+        },
+        abandoned: {
+            async upsert(body, forwardedHeaders) {
+                // The server answers `{ success, id }` — the payload sits at the
+                // top level, not inside `data`.
+                const result = await core.post("/store/abandoned", body, {
+                    ...(forwardedHeaders ? { headers: forwardedHeaders } : {}),
+                    schema: IdResponseSchema,
+                    topLevelData: true,
+                    operation: STOREFRONT_OPERATIONS.ordersAbandonedUpsert,
+                });
+                if (!result.success)
+                    return result;
+                return { success: true, data: { id: result.data.id } };
+            },
+            async convert(sessionId, orderId, orderNumber) {
+                const result = await core.patch(`/store/abandoned/${encodeURIComponent(sessionId)}/convert`, { orderId, orderNumber }, { operation: STOREFRONT_OPERATIONS.ordersAbandonedConvert });
+                if (!result.success)
+                    return result;
+                return { success: true, data: null };
+            },
+        },
+        otp: {
+            async send(phone) {
+                // core.post flattens the server's `context` (windowSeconds) and
+                // `code` into the error result — exactly what the OTP step reads.
+                return core.post("/store/otp/send", { phone }, {
+                    schema: OtpSendResultSchema,
+                    operation: STOREFRONT_OPERATIONS.ordersOtpSend,
+                });
+            },
+            async verify(phone, requestId, code) {
+                return core.post("/store/otp/verify", { phone, requestId, code }, { schema: OtpVerifyResultSchema, operation: STOREFRONT_OPERATIONS.ordersOtpVerify });
+            },
+        },
+    };
+}

package/dist/client/page-data.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Page Data Namespace — the store's saved composition document.
+ *
+ * Deep module: hides URL construction and transport behind one call. The
+ * document belongs to the store (one per surface — "home" today) and is
+ * written by the platform's editor; this namespace is the theme's read side.
+ *
+ * Transport semantics (NOT the document contract): the payload is validated
+ * as `{ version, surface, sections }` and returns `null` for "no saved
+ * document" or any failure — never throws. What the sections MEAN is the
+ * theme SDK's `parsePageData`'s job; `sections` stays `unknown[]` here so a
+ * newer document's instances reach the theme verbatim.
+ *
+ * Fetched fresh on every call (no process-lifetime cache — a save must reach
+ * the next render, subject only to the theme's route cache).
+ */
+import { type ClientCore } from "./core.js";
+import type { PageDocumentPayload } from "../types.js";
+export interface PageDataNamespace {
+    /**
+     * Get the store's saved page document for one surface (e.g. "home").
+     * Resolves to `null` when the store has never saved one or when the read
+     * fails — the theme then renders its shipped default document.
+     */
+    get(surface: string): Promise<PageDocumentPayload | null>;
+}
+/**
+ * Create the page-data namespace.
+ */
+export declare function createPageDataNamespace(core: ClientCore): PageDataNamespace;

package/dist/client/page-data.js

@@ -0,0 +1,36 @@
+/**
+ * Page Data Namespace — the store's saved composition document.
+ *
+ * Deep module: hides URL construction and transport behind one call. The
+ * document belongs to the store (one per surface — "home" today) and is
+ * written by the platform's editor; this namespace is the theme's read side.
+ *
+ * Transport semantics (NOT the document contract): the payload is validated
+ * as `{ version, surface, sections }` and returns `null` for "no saved
+ * document" or any failure — never throws. What the sections MEAN is the
+ * theme SDK's `parsePageData`'s job; `sections` stays `unknown[]` here so a
+ * newer document's instances reach the theme verbatim.
+ *
+ * Fetched fresh on every call (no process-lifetime cache — a save must reach
+ * the next render, subject only to the theme's route cache).
+ */
+import { PageDocumentPayloadSchema } from "../schemas.js";
+import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { reportDegradedRead } from "./core.js";
+/**
+ * Create the page-data namespace.
+ */
+export function createPageDataNamespace(core) {
+    return {
+        async get(surface) {
+            try {
+                const document = await core.get(`/store/page-documents/${encodeURIComponent(surface)}`, PageDocumentPayloadSchema.nullable(), { operation: STOREFRONT_OPERATIONS.pageDataGet });
+                return document ?? null;
+            }
+            catch (error) {
+                reportDegradedRead(core.config, error, "pageData.get");
+                return null;
+            }
+        },
+    };
+}

package/dist/client/pages.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pages Namespace - Store Pages & Landing Pages
+ *
+ * Deep module: hides URL construction, slug encoding, and transport behind
+ * two calls. Pages are fetched fresh every request (a merchant edit is live
+ * on the next render).
+ *
+ * Failure contracts:
+ * - `get(slug)` → null means "not published" — the theme 404s, never a
+ *   soft 200 with empty content.
+ * - `landing(slug)` → null means draft/archived/unknown — the theme
+ *   redirects to the store home instead of a dead end.
+ */
+import { type ClientCore } from "./core.js";
+import type { LandingPage, StorePagePublic } from "../types.js";
+export interface PagesNamespace {
+    /**
+     * Get a published store page (Terms/Privacy/Refund/Shipping/custom),
+     * resolved to the store's own language server-side.
+     * Resolves to `null` for draft/unknown slugs or fetch failure.
+     */
+    get(slug: string): Promise<StorePagePublic | null>;
+    /**
+     * Get a published landing page by its public slug: the ordered image
+     * stack, spacing settings, and the linked product in full store-product
+     * shape. Resolves to `null` for draft/archived/unknown slugs or failure.
+     */
+    landing(slug: string): Promise<LandingPage | null>;
+}
+/**
+ * Create pages namespace
+ */
+export declare function createPagesNamespace(core: ClientCore): PagesNamespace;

package/dist/client/pages.js

@@ -0,0 +1,44 @@
+/**
+ * Pages Namespace - Store Pages & Landing Pages
+ *
+ * Deep module: hides URL construction, slug encoding, and transport behind
+ * two calls. Pages are fetched fresh every request (a merchant edit is live
+ * on the next render).
+ *
+ * Failure contracts:
+ * - `get(slug)` → null means "not published" — the theme 404s, never a
+ *   soft 200 with empty content.
+ * - `landing(slug)` → null means draft/archived/unknown — the theme
+ *   redirects to the store home instead of a dead end.
+ */
+import { LandingPageSchema, StorePagePublicSchema } from "../schemas.js";
+import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { localizedPath } from "./paths.js";
+import { reportDegradedRead } from "./core.js";
+/**
+ * Create pages namespace
+ */
+export function createPagesNamespace(core) {
+    return {
+        async get(slug) {
+            try {
+                const page = await core.get(localizedPath(core.config, `/store/pages/${encodeURIComponent(slug)}`), StorePagePublicSchema.nullable(), { operation: STOREFRONT_OPERATIONS.pagesGet });
+                return page ?? null;
+            }
+            catch (error) {
+                reportDegradedRead(core.config, error, "pages.get");
+                return null;
+            }
+        },
+        async landing(slug) {
+            try {
+                const landingPage = await core.get(`/store/landing-pages/${encodeURIComponent(slug)}`, LandingPageSchema.nullable(), { operation: STOREFRONT_OPERATIONS.pagesLanding });
+                return landingPage ?? null;
+            }
+            catch (error) {
+                reportDegradedRead(core.config, error, "pages.landing");
+                return null;
+            }
+        },
+    };
+}

package/dist/client/paths.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Request paths for reads that carry merchant text. Each one names the
+ * client's language (`StoreScope.locale`), so the server serves it
+ * with its translations — and caches keyed by path keep one entry per
+ * language.
+ */
+import type { StoreScope } from "../domain.js";
+export declare function localizedPath(scope: Pick<StoreScope, "locale">, path: string, params?: Readonly<Record<string, string | undefined>>): string;

package/dist/client/paths.js

@@ -0,0 +1,10 @@
+export function localizedPath(scope, path, params = {}) {
+    const search = new URLSearchParams();
+    for (const [name, value] of Object.entries(params))
+        if (value !== undefined)
+            search.set(name, value);
+    if (scope.locale !== undefined)
+        search.set("locale", scope.locale);
+    const query = search.toString();
+    return query === "" ? path : `${path}?${query}`;
+}

package/dist/client/products.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Products Namespace - Product Catalog & Reviews
+ *
+ * Deep module: Hides ID vs handle resolution, pagination, filter construction,
+ * response validation, and review submission complexity. Callers get a clean
+ * namespace interface.
+ *
+ * Every read validates the server's payload against the published catalog
+ * schemas before it is handed out: a catalog response that no longer matches
+ * the contract degrades to `null`/`[]` like any other failed read (and is
+ * reported through the client's `onError`), instead of leaking a
+ * half-shaped product into a theme.
+ */
+import { type ClientCore, type ClientResult } from "./core.js";
+import type { Product, ProductList, ProductListFilters, Review, ReviewInput, ReviewListPagination } from "../types.js";
+export interface ProductsNamespace {
+    /**
+     * Get a single product by its public URL handle
+     * @param handle - URL handle
+     * @returns Product or null if not found
+     */
+    get(handle: string): Promise<Product | null>;
+    /**
+     * List products with optional filters
+     * @param filters - Optional category, featured flag, limit and offset
+     * @returns Array of products
+     */
+    list(filters?: ProductListFilters): Promise<ProductList[]>;
+    /**
+     * Reviews sub-namespace
+     */
+    reviews: {
+        /**
+         * List reviews for a product
+         * @param productId - Product ID
+         * @param pagination - Optional limit and offset
+         * @returns Reviews with total count
+         */
+        list(productId: string, pagination?: ReviewListPagination): Promise<{
+            rows: Review[];
+            total: number;
+        }>;
+        /**
+         * Submit a product review
+         * @param data - Review data
+         * @returns Result with review ID or error
+         */
+        submit(data: ReviewInput): Promise<ClientResult<{
+            id: string;
+        }>>;
+    };
+}
+/**
+ * Create products namespace
+ */
+export declare function createProductsNamespace(core: ClientCore): ProductsNamespace;

package/dist/client/products.js

@@ -0,0 +1,78 @@
+/**
+ * Products Namespace - Product Catalog & Reviews
+ *
+ * Deep module: Hides ID vs handle resolution, pagination, filter construction,
+ * response validation, and review submission complexity. Callers get a clean
+ * namespace interface.
+ *
+ * Every read validates the server's payload against the published catalog
+ * schemas before it is handed out: a catalog response that no longer matches
+ * the contract degrades to `null`/`[]` like any other failed read (and is
+ * reported through the client's `onError`), instead of leaking a
+ * half-shaped product into a theme.
+ */
+import { z } from "zod";
+import { IdResponseSchema, ProductListSchema, ProductSchema, ReviewListEnvelopeSchema } from "../schemas.js";
+import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { localizedPath } from "./paths.js";
+import { reportDegradedRead } from "./core.js";
+/**
+ * Create products namespace
+ */
+export function createProductsNamespace(core) {
+    return {
+        async get(handle) {
+            try {
+                const product = await core.get(localizedPath(core.config, `/store/products/${encodeURIComponent(handle)}`), ProductSchema.nullable(), { operation: STOREFRONT_OPERATIONS.productsGet });
+                return product ?? null;
+            }
+            catch (error) {
+                reportDegradedRead(core.config, error, "products.get");
+                return null;
+            }
+        },
+        async list(filters) {
+            try {
+                const products = await core.get(localizedPath(core.config, "/store/products", {
+                    categoryId: filters?.categoryId || undefined,
+                    featured: filters?.featured ? "true" : undefined,
+                    limit: filters?.limit === undefined ? undefined : String(filters.limit),
+                    offset: filters?.offset ? String(filters.offset) : undefined,
+                }), z.array(ProductListSchema), { operation: STOREFRONT_OPERATIONS.productsList });
+                return products ?? [];
+            }
+            catch (error) {
+                reportDegradedRead(core.config, error, "products.list");
+                return [];
+            }
+        },
+        reviews: {
+            async list(productId, pagination) {
+                try {
+                    const params = new URLSearchParams({
+                        productId,
+                        limit: String(pagination?.limit ?? 20),
+                        offset: String(pagination?.offset ?? 0),
+                    });
+                    // The server returns { data: Review[], total } — total lives
+                    // outside `data`, so read the full envelope.
+                    const envelope = await core.get(`/store/reviews?${params}`, ReviewListEnvelopeSchema, {
+                        envelope: true,
+                        operation: STOREFRONT_OPERATIONS.productsReviewsList,
+                    });
+                    return {
+                        rows: envelope?.data ?? [],
+                        total: envelope?.total ?? 0,
+                    };
+                }
+                catch (error) {
+                    reportDegradedRead(core.config, error, "products.reviews.list");
+                    return { rows: [], total: 0 };
+                }
+            },
+            async submit(data) {
+                return core.post("/store/reviews", data, { schema: IdResponseSchema, operation: STOREFRONT_OPERATIONS.productsReviewsSubmit });
+            },
+        },
+    };
+}

package/dist/client/shipping.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shipping Namespace - Delivery Pricing
+ *
+ * Deep module: hides URL construction and the per-wilaya lookup behind two
+ * calls. The server always returns the full per-wilaya map; `rate()` extracts
+ * a single wilaya's pair when the caller only needs one.
+ *
+ * Fetched fresh every request (merchants adjust delivery pricing and expect
+ * the next render to show it).
+ *
+ * Failure contract: resolves to `{}` /
+ * `null` on any failure — never throws. Absent wilayas have no rule and are
+ * treated as unsupported.
+ */
+import { type ClientCore } from "./core.js";
+import type { ShippingRates, WilayaRates } from "../types.js";
+export interface ShippingNamespace {
+    /**
+     * All per-wilaya shipping rates, keyed by wilaya ID (as string).
+     * Resolves to `{}` when the rates cannot be fetched.
+     */
+    rates(): Promise<ShippingRates>;
+    /**
+     * The rate pair for one wilaya.
+     * Resolves to `null` when that wilaya has no rule or fetch fails.
+     *
+     * Takes the same `number | string` as `geo.communes()`: a form control
+     * hands over a string, a typed row hands over a number, and neither caller
+     * should have to remember which of the two this one wants.
+     */
+    rate(wilayaId: number | string): Promise<WilayaRates | null>;
+}
+/**
+ * Create shipping namespace
+ */
+export declare function createShippingNamespace(core: ClientCore): ShippingNamespace;

package/dist/client/shipping.js

@@ -0,0 +1,47 @@
+/**
+ * Shipping Namespace - Delivery Pricing
+ *
+ * Deep module: hides URL construction and the per-wilaya lookup behind two
+ * calls. The server always returns the full per-wilaya map; `rate()` extracts
+ * a single wilaya's pair when the caller only needs one.
+ *
+ * Fetched fresh every request (merchants adjust delivery pricing and expect
+ * the next render to show it).
+ *
+ * Failure contract: resolves to `{}` /
+ * `null` on any failure — never throws. Absent wilayas have no rule and are
+ * treated as unsupported.
+ */
+import { ShippingRatesSchema } from "../schemas.js";
+import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { reportDegradedRead } from "./core.js";
+/**
+ * Create shipping namespace
+ */
+export function createShippingNamespace(core) {
+    return {
+        async rates() {
+            try {
+                return ((await core.get("/store/shipping-rates", ShippingRatesSchema.nullable(), {
+                    operation: STOREFRONT_OPERATIONS.shippingRates,
+                })) ?? {});
+            }
+            catch (error) {
+                reportDegradedRead(core.config, error, "shipping.rates");
+                return {};
+            }
+        },
+        async rate(wilayaId) {
+            try {
+                const rates = (await core.get("/store/shipping-rates", ShippingRatesSchema.nullable(), {
+                    operation: STOREFRONT_OPERATIONS.shippingRate,
+                })) ?? {};
+                return rates[String(wilayaId)] ?? null;
+            }
+            catch (error) {
+                reportDegradedRead(core.config, error, "shipping.rate");
+                return null;
+            }
+        },
+    };
+}