@wocart/storefront 0.0.0-stage → 1.0.0

package/dist/basket.js

@@ -0,0 +1,258 @@
+/**
+ * Browser-side shopping cart / basket engine.
+ *
+ * Deep module: concentrates state, persistence, event notification,
+ * cross-tab synchronization, duplicate merging, and bounds enforcement behind
+ * a minimal, testable interface.
+ *
+ * The basket is intent, not trusted money. It lives in the client environment
+ * (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";
+/** Default key used in browser storage, versioned to prevent schema drift crashes. */
+export const DEFAULT_BASKET_STORAGE_KEY = "cod_cart_v1";
+/**
+ * Create a memory storage adapter (ideal for node, tests, and SSR).
+ */
+export function createMemoryStorageAdapter() {
+    const store = new Map();
+    return {
+        getItem: (key) => store.get(key) ?? null,
+        setItem: (key, value) => {
+            store.set(key, value);
+        },
+        removeItem: (key) => {
+            store.delete(key);
+        },
+        isAvailable: () => true,
+    };
+}
+/**
+ * Create a safe browser localStorage adapter with storage event subscription.
+ */
+export function createLocalStorageAdapter(storageKey = DEFAULT_BASKET_STORAGE_KEY) {
+    function checkAvailable() {
+        if (typeof window === "undefined" || typeof localStorage === "undefined")
+            return false;
+        try {
+            const probe = "__cod_probe__";
+            localStorage.setItem(probe, "1");
+            localStorage.removeItem(probe);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return {
+        getItem: (key) => {
+            try {
+                return localStorage.getItem(key);
+            }
+            catch {
+                return null;
+            }
+        },
+        setItem: (key, value) => {
+            try {
+                localStorage.setItem(key, value);
+            }
+            catch {
+                // Quota exceeded or private browsing: fail silently, memory state continues
+            }
+        },
+        removeItem: (key) => {
+            try {
+                localStorage.removeItem(key);
+            }
+            catch {
+                // Fail silently
+            }
+        },
+        isAvailable: checkAvailable,
+        subscribe: (onExternalChange) => {
+            if (typeof window === "undefined")
+                return () => { };
+            const onStorage = (event) => {
+                if (event.key === storageKey) {
+                    onExternalChange();
+                }
+            };
+            window.addEventListener("storage", onStorage);
+            return () => {
+                window.removeEventListener("storage", onStorage);
+            };
+        },
+    };
+}
+function sanitizeLine(raw, maxQuantity) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const line = raw;
+    const productId = typeof line.productId === "string" ? line.productId.trim() : "";
+    const productName = typeof line.productName === "string" ? line.productName : "";
+    if (!productId || !productName)
+        return null;
+    const quantity = Number(line.quantity);
+    if (!Number.isInteger(quantity) || quantity < 1)
+        return null;
+    const unitPrice = Number(line.unitPrice);
+    return {
+        productId,
+        productName,
+        variantId: typeof line.variantId === "string" && line.variantId ? line.variantId : null,
+        variantLabel: typeof line.variantLabel === "string" && line.variantLabel ? line.variantLabel : null,
+        quantity: Math.min(quantity, 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,
+    };
+}
+function normalizeLines(lines, maxLines, maxQuantity) {
+    const merged = new Map();
+    for (const line of lines) {
+        const key = basketLineKey(line.productId, line.variantId);
+        const existing = merged.get(key);
+        if (existing) {
+            existing.quantity = Math.min(existing.quantity + line.quantity, maxQuantity);
+            existing.variantLabel ??= line.variantLabel;
+            existing.image ??= line.image;
+            existing.href ??= line.href;
+        }
+        else {
+            merged.set(key, { ...line });
+        }
+    }
+    return [...merged.values()].slice(0, maxLines);
+}
+/**
+ * The server-facing projection of basket lines — the ONE place a browser
+ * basket turns into `items[]` for POST /store/cart/validate or an order.
+ *
+ * Pure and store-free so a caller holding a line snapshot (a theme's
+ * debounced validator, a checkout draft) projects it without re-deriving the
+ * wire shape; `BasketStore.toOrderItems()` delegates here, and the order
+ * action's schema is what finally accepts or rejects it.
+ */
+export function toOrderItems(lines) {
+    return lines.map((line) => ({
+        productId: line.productId,
+        productName: line.productName,
+        variantId: line.variantId ?? undefined,
+        variantLabel: line.variantLabel ?? undefined,
+        quantity: line.quantity,
+        pricePerUnit: line.unitPrice,
+    }));
+}
+/**
+ * Create a deep Basket Store.
+ */
+export function createBasketStore(options = {}) {
+    const storageKey = options.storageKey ?? DEFAULT_BASKET_STORAGE_KEY;
+    const maxLines = options.maxLines ?? MAX_BASKET_LINES;
+    const maxLineQuantity = options.maxLineQuantity ?? MAX_BASKET_LINE_QUANTITY;
+    const storage = options.storage ??
+        (typeof window !== "undefined"
+            ? createLocalStorageAdapter(storageKey)
+            : createMemoryStorageAdapter());
+    const listeners = new Set();
+    function readFromStorage() {
+        try {
+            const raw = storage.getItem(storageKey);
+            if (!raw)
+                return [];
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed))
+                return [];
+            return normalizeLines(parsed
+                .map((item) => sanitizeLine(item, maxLineQuantity))
+                .filter((line) => line !== null), maxLines, maxLineQuantity);
+        }
+        catch {
+            return [];
+        }
+    }
+    let state = readFromStorage();
+    function commit(next) {
+        state = normalizeLines(next, maxLines, maxLineQuantity);
+        try {
+            storage.setItem(storageKey, JSON.stringify(state));
+        }
+        catch {
+            // Ignored: memory state continues
+        }
+        for (const listener of listeners) {
+            try {
+                listener(state);
+            }
+            catch {
+                // Listener exception must not break store
+            }
+        }
+        return state;
+    }
+    // Cross-tab synchronization
+    if (storage.subscribe) {
+        storage.subscribe(() => {
+            state = readFromStorage();
+            for (const listener of listeners) {
+                try {
+                    listener(state);
+                }
+                catch { }
+            }
+        });
+    }
+    return {
+        getLines() {
+            return state;
+        },
+        getCount() {
+            return state.reduce((total, line) => total + line.quantity, 0);
+        },
+        getSubtotal() {
+            return state.reduce((total, line) => total + line.unitPrice * line.quantity, 0);
+        },
+        addLine(line) {
+            const key = basketLineKey(line.productId, line.variantId);
+            const isExisting = state.some((l) => basketLineKey(l.productId, l.variantId) === key);
+            // Refuse adding a new line when already at cap
+            if (state.length >= maxLines && !isExisting) {
+                return state;
+            }
+            return commit([...state, line]);
+        },
+        setQuantity(key, quantity) {
+            if (!Number.isInteger(quantity) || quantity < 1) {
+                return this.removeLine(key);
+            }
+            const capped = Math.min(quantity, maxLineQuantity);
+            return commit(state.map((line) => basketLineKey(line.productId, line.variantId) === key
+                ? { ...line, quantity: capped }
+                : line));
+        },
+        removeLine(key) {
+            return commit(state.filter((line) => basketLineKey(line.productId, line.variantId) !== key));
+        },
+        clear() {
+            try {
+                storage.removeItem(storageKey);
+            }
+            catch { }
+            return commit([]);
+        },
+        toOrderItems() {
+            return toOrderItems(state);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        isPersistent() {
+            return storage.isAvailable();
+        },
+    };
+}

package/dist/client/cart.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Cart Namespace - Server-side Basket Validation
+ *
+ * Deep module: hides the wire shape and the read-only semantics of
+ * POST /store/cart/validate behind one call. The shopper's basket lives in
+ * the browser; every line here is re-priced and re-checked against the live
+ * catalog — the client's own price is display-only.
+ *
+ * Failure contract: returns the error as a
+ * result (never throws). The upstream is read-only — nothing is written and
+ * no stock is reserved — so a failure is safe to swallow: the cart drawer
+ * keeps its optimistic view and checkout re-validates everything anyway.
+ */
+import type { ClientCore, ClientResult } from "./core.js";
+import type { CartValidation } from "../types.js";
+import type { BasketLineInput } from "../domain.js";
+export interface CartNamespace {
+    /**
+     * Re-price and re-check a basket against the live catalog.
+     * `items` are the browser's basket lines (productId, quantity, and the
+     * optional variant fields); pricing from their side is never trusted, and
+     * each line's product name and variant label come back from the catalog in
+     * the client's language.
+     */
+    validate(items: readonly BasketLineInput[]): Promise<ClientResult<CartValidation>>;
+}
+/**
+ * Create cart namespace
+ */
+export declare function createCartNamespace(core: ClientCore): CartNamespace;

package/dist/client/cart.js

@@ -0,0 +1,26 @@
+/**
+ * Cart Namespace - Server-side Basket Validation
+ *
+ * Deep module: hides the wire shape and the read-only semantics of
+ * POST /store/cart/validate behind one call. The shopper's basket lives in
+ * the browser; every line here is re-priced and re-checked against the live
+ * catalog — the client's own price is display-only.
+ *
+ * Failure contract: returns the error as a
+ * result (never throws). The upstream is read-only — nothing is written and
+ * no stock is reserved — so a failure is safe to swallow: the cart drawer
+ * keeps its optimistic view and checkout re-validates everything anyway.
+ */
+import { CartValidationSchema } from "../schemas.js";
+import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { localizedPath } from "./paths.js";
+/**
+ * Create cart namespace
+ */
+export function createCartNamespace(core) {
+    return {
+        async validate(items) {
+            return core.post(localizedPath(core.config, "/store/cart/validate"), { items }, { schema: CartValidationSchema, operation: STOREFRONT_OPERATIONS.cartValidate });
+        },
+    };
+}

package/dist/client/categories.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Categories Namespace - Store Category Tree
+ *
+ * Deep module: hides URL construction, caching, transport, and response
+ * validation behind one call. Categories are read-mostly, so successful
+ * lists are cached for the process lifetime; failures are never cached (the
+ * next call retries).
+ *
+ * Failure contract: resolves to `[]`
+ * on any failure — never throws. Pass `onError` to the client to see what a
+ * degraded read actually was.
+ */
+import { type ClientCore } from "./core.js";
+import type { Category } from "../types.js";
+export interface CategoriesNamespace {
+    /**
+     * List store categories, ordered by position (cached after first success).
+     * Resolves to `[]` when the list cannot be fetched.
+     */
+    list(): Promise<Category[]>;
+}
+/**
+ * Create categories namespace
+ */
+export declare function createCategoriesNamespace(core: ClientCore): CategoriesNamespace;

package/dist/client/categories.js

@@ -0,0 +1,37 @@
+/**
+ * Categories Namespace - Store Category Tree
+ *
+ * Deep module: hides URL construction, caching, transport, and response
+ * validation behind one call. Categories are read-mostly, so successful
+ * lists are cached for the process lifetime; failures are never cached (the
+ * next call retries).
+ *
+ * Failure contract: resolves to `[]`
+ * on any failure — never throws. Pass `onError` to the client to see what a
+ * degraded read actually was.
+ */
+import { z } from "zod";
+import { CategorySchema } from "../schemas.js";
+import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { localizedPath } from "./paths.js";
+import { reportDegradedRead } from "./core.js";
+/**
+ * Create categories namespace
+ */
+export function createCategoriesNamespace(core) {
+    return {
+        async list() {
+            try {
+                const categories = await core.get(localizedPath(core.config, "/store/categories"), z.array(CategorySchema), {
+                    cache: true,
+                    operation: STOREFRONT_OPERATIONS.categoriesList,
+                });
+                return categories ?? [];
+            }
+            catch (error) {
+                reportDegradedRead(core.config, error, "categories.list");
+                return [];
+            }
+        },
+    };
+}

package/dist/client/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Config Namespace - Store Configuration
+ *
+ * Deep module: hides caching, retry, transport, and response validation
+ * behind one call.
+ *
+ * Failure contract: resolves to `null`
+ * on any failure (HTTP error, network error, absent data, a response that no
+ * longer matches the store-config contract) — never throws. Themes fall back
+ * to their defaults (`(await store.config.get()) ?? DEFAULTS`). Pass `onError` to the
+ * client to see what a `null` actually was.
+ *
+ * Successful results are cached for the process lifetime (config is
+ * read-mostly); failures and null results are never cached, so a transient
+ * outage recovers on the next request.
+ */
+import { type ClientCore } from "./core.js";
+import type { StoreConfig } from "../types.js";
+export interface ConfigNamespace {
+    /**
+     * Get store configuration (cached after first success).
+     * Resolves to `null` when the config cannot be fetched.
+     */
+    get(): Promise<StoreConfig | null>;
+}
+/**
+ * Create config namespace
+ */
+export declare function createConfigNamespace(core: ClientCore): ConfigNamespace;

package/dist/client/config.js

@@ -0,0 +1,41 @@
+/**
+ * Config Namespace - Store Configuration
+ *
+ * Deep module: hides caching, retry, transport, and response validation
+ * behind one call.
+ *
+ * Failure contract: resolves to `null`
+ * on any failure (HTTP error, network error, absent data, a response that no
+ * longer matches the store-config contract) — never throws. Themes fall back
+ * to their defaults (`(await store.config.get()) ?? DEFAULTS`). Pass `onError` to the
+ * client to see what a `null` actually was.
+ *
+ * Successful results are cached for the process lifetime (config is
+ * read-mostly); failures and null results are never cached, so a transient
+ * outage recovers on the next request.
+ */
+import { StoreConfigSchema } from "../schemas.js";
+import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { localizedPath } from "./paths.js";
+import { reportDegradedRead } from "./core.js";
+/**
+ * Create config namespace
+ */
+export function createConfigNamespace(core) {
+    return {
+        async get() {
+            try {
+                const path = localizedPath(core.config, "/store/config", { theme: core.config.theme });
+                const config = await core.get(path, StoreConfigSchema.nullable(), {
+                    cache: true,
+                    operation: STOREFRONT_OPERATIONS.configGet,
+                });
+                return config ?? null;
+            }
+            catch (error) {
+                reportDegradedRead(core.config, error, "config.get");
+                return null;
+            }
+        },
+    };
+}

package/dist/client/core.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Deep API Client - Core Infrastructure
+ *
+ * Hides: caching, request deduplication, retry logic, validation,
+ * header management, cancellation, and URL construction.
+ *
+ * Deep module principle: Maximum leverage for namespace implementations.
+ * One infrastructure layer serves all API methods.
+ */
+import type { z } from "zod";
+import type { ClientResult, StoreScope } from "../domain.js";
+export type { ClientResult } from "../domain.js";
+/**
+ * Client configuration
+ */
+export type ClientConfig = StoreScope;
+/**
+ * Options every request accepts.
+ *
+ * `signal` cancels the request — an aborted call never retries, never coalesces
+ * with another caller's request, and returns a REQUEST_ABORTED DomainError
+ * (a read throws instead). `timeoutMs` bounds the whole operation, retries
+ * included, and reads as REQUEST_TIMEOUT. `operation` names the call in the
+ * error it produces; namespaces pass a stable label (`orders.otp.send`) so logs
+ * never carry shopper-supplied ids from the URL.
+ */
+export interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    operation?: string;
+}
+/**
+ * Options for GET requests
+ */
+export interface GetOptions extends RequestOptions {
+    envelope?: boolean;
+    cache?: boolean;
+}
+/**
+ * Options for POST requests
+ */
+export interface PostOptions<TOutput> extends RequestOptions {
+    schema?: z.Schema<TOutput>;
+    headers?: Record<string, string>;
+    topLevelData?: boolean;
+}
+/**
+ * Options for PATCH requests
+ */
+export interface PatchOptions<TOutput> extends RequestOptions {
+    schema?: z.Schema<TOutput>;
+    headers?: Record<string, string>;
+}
+/**
+ * Client core infrastructure
+ * Exposed only to namespace implementations, not to end users
+ */
+export interface ClientCore {
+    config: ClientConfig;
+    get: <T>(path: string, schema?: z.Schema<T>, opts?: GetOptions) => Promise<T>;
+    post: <TInput, TOutput>(path: string, body: TInput, opts?: PostOptions<TOutput>) => Promise<ClientResult<TOutput>>;
+    patch: <TInput, TOutput>(path: string, body: TInput, optsOrSchema?: z.Schema<TOutput> | PatchOptions<TOutput>) => Promise<ClientResult<TOutput>>;
+}
+/**
+ * Create client core infrastructure
+ *
+ * @param config - Client configuration
+ * @returns Core infrastructure for namespace implementations
+ */
+export declare function createClientCore(config: ClientConfig): ClientCore;
+/**
+ * Report a read that a namespace swallowed.
+ *
+ * Namespaces degrade instead of throwing — that is their contract — so this
+ * is the operator's only signal that a call did not complete. A failure the
+ * core produced already carries its DomainError; anything else (a bug inside
+ * a namespace, a storage exception) is normalised to the same shape, so a
+ * consumer's handler branches on one contract. A throwing hook never turns a
+ * degraded read into a thrown one.
+ */
+export declare function reportDegradedRead(config: StoreScope | undefined, error: unknown, operation: string): void;
+/**
+ * Clear the request cache
+ * Useful for testing or forcing fresh data
+ */
+export declare function clearCache(): void;