@wocart/storefront 0.0.0-stage → 1.0.0

package/dist/client/core.js

@@ -0,0 +1,582 @@
+/**
+ * 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 { StorefrontError, isStorefrontError } from "./errors.js";
+/**
+ * Result type for mutations (POST/PATCH).
+ *
+ * `domainError` is **always present on a failure the SDK produced** — every
+ * transport, HTTP, schema and abort path sets it, so a consumer branches on
+ * `result.domainError.category` without an optional-chain. It is declared as
+ * a required field on purpose: a new failure path that forgets it does not
+ * compile.
+ *
+ * `error` stays as the human-readable message (`domainError.message`), `code`
+ * stays an open string because the server's error codes are open (`HTTP_<status>`
+ * for gateway failures, the server's own code otherwise — a closed union would
+ * reject codes this SDK has not seen yet), and the index signature carries the
+ * server's flattened `context` (OTP's `windowSeconds`/`attemptsRemaining`/
+ * `terminal`, field issues) so a proxy can forward it without re-declaring each
+ * key. Read models do not come back as a `ClientResult` — reads degrade to
+ * `null`/`[]`/`{}` instead (see USAGE.md, "Failure and result contracts").
+ */
+let cacheGeneration = 0;
+const ABORT_MESSAGE = "The request was cancelled";
+const TIMEOUT_MESSAGE = "The request timed out";
+const MALFORMED_MESSAGE = "The server response could not be read";
+const SCHEMA_MESSAGE = "Schema validation failed";
+/**
+ * The server's own error categories, translated to SDK categories. This is the
+ * wire vocabulary of the platform's ERROR_CATEGORIES, not a second copy of it:
+ * the server always wins when it names a category, and the status-code mapping
+ * below only covers failures that arrive without one (gateways, proxies).
+ */
+const WIRE_CATEGORIES = {
+    VALIDATION: "validation",
+    AUTHENTICATION: "authentication",
+    BUSINESS_LOGIC: "business",
+    SYSTEM: "system",
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(source, key) {
+    if (!isRecord(source))
+        return undefined;
+    const value = source[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function readNumber(source, key) {
+    if (!isRecord(source))
+        return undefined;
+    const value = source[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function categorizeFailure(status, wireCategory) {
+    if (typeof wireCategory === "string" && WIRE_CATEGORIES[wireCategory]) {
+        return WIRE_CATEGORIES[wireCategory];
+    }
+    if (status === 401 || status === 403)
+        return "authentication";
+    if (status === 400 || status === 422)
+        return "validation";
+    if (status === 404 || status === 409 || status === 429)
+        return "business";
+    if (status !== undefined && status >= 500)
+        return "system";
+    return "unknown";
+}
+/**
+ * What the platform actually did. A 2xx means it accepted the command, a 4xx is
+ * a clean refusal, and everything else — 5xx, dropped connections, timeouts —
+ * leaves the outcome unproven. Only a proven outcome may be replayed.
+ */
+function determineSideEffectOutcome(status) {
+    if (status === undefined)
+        return "unknown";
+    if (status >= 200 && status < 300)
+        return "committed";
+    if (status >= 400 && status < 500)
+        return "rejected";
+    return "unknown";
+}
+/**
+ * A write is replayable only when the server refused it *and* said when to come
+ * back: retrying a dropped connection is how a shopper ends up with two orders.
+ * Reads are safe to repeat unless the request itself was rejected.
+ */
+function isReplayable(status, readOnly) {
+    if (readOnly)
+        return status === 429 || status >= 500;
+    return status === 429;
+}
+/** Field-level errors from the server's Zod failures (`context.fields`). */
+function readFieldIssues(context) {
+    if (!isRecord(context) || !Array.isArray(context.fields))
+        return undefined;
+    const issues = context.fields.flatMap((entry) => {
+        if (!isRecord(entry))
+            return [];
+        return [
+            {
+                field: typeof entry.path === "string" ? entry.path : "",
+                code: typeof entry.code === "string" ? entry.code : "INVALID",
+                message: typeof entry.message === "string" ? entry.message : "Invalid value",
+            },
+        ];
+    });
+    return issues.length > 0 ? issues : undefined;
+}
+function composeSignal(signal, timeoutMs) {
+    if (!signal && timeoutMs === undefined) {
+        return { signal: undefined, aborted: () => false, timedOut: () => false, cleanup: () => { } };
+    }
+    if (timeoutMs === undefined) {
+        return { signal, aborted: () => signal.aborted, timedOut: () => false, cleanup: () => { } };
+    }
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    const forward = () => controller.abort();
+    if (signal) {
+        if (signal.aborted)
+            forward();
+        else
+            signal.addEventListener("abort", forward, { once: true });
+    }
+    return {
+        signal: controller.signal,
+        aborted: () => signal?.aborted === true,
+        timedOut: () => timedOut,
+        cleanup: () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", forward);
+        },
+    };
+}
+function abortedError(operation) {
+    return {
+        category: "transport",
+        code: "REQUEST_ABORTED",
+        message: ABORT_MESSAGE,
+        retryable: false,
+        operation,
+        sideEffect: "not_started",
+    };
+}
+/**
+ * A failure that happened before the server answered — or after it stopped
+ * answering. `readOnly` marks reads: only a read may be replayed on one of
+ * these, because a write's outcome is unproven and replaying it is how a
+ * shopper ends up with two orders.
+ */
+function transportFailure(cause, signal, operation, readOnly) {
+    const sideEffect = readOnly ? "not_started" : "unknown";
+    if (signal.timedOut()) {
+        return {
+            category: "transport",
+            code: "REQUEST_TIMEOUT",
+            message: TIMEOUT_MESSAGE,
+            retryable: readOnly,
+            operation,
+            sideEffect,
+        };
+    }
+    if (signal.aborted()) {
+        return { ...abortedError(operation), sideEffect };
+    }
+    return {
+        category: "transport",
+        code: "NETWORK_ERROR",
+        message: cause instanceof Error ? cause.message : "Network error",
+        retryable: readOnly,
+        operation,
+        sideEffect,
+    };
+}
+/**
+ * A 2xx response the SDK could not read or validate. The server already
+ * committed the command — only the answer went missing — so a write must not be
+ * replayed on the strength of it.
+ */
+function unreadableSuccess(code, message, operation, readOnly) {
+    return {
+        category: "system",
+        code,
+        message,
+        retryable: readOnly,
+        operation,
+        sideEffect: readOnly ? "not_started" : "committed",
+    };
+}
+/**
+ * A failure the server reported itself: its message, its code, its category, and
+ * every diagnostic it chose to publish in `context`.
+ */
+function serverFailure(status, body, operation, readOnly) {
+    const context = isRecord(body) ? body.context : undefined;
+    const message = readString(body, "error") ??
+        readString(body, "message") ??
+        (status !== undefined ? `HTTP ${status}` : "Request failed");
+    const code = readString(body, "code");
+    const retryAfterSeconds = readNumber(context, "windowSeconds") ?? readNumber(body, "retryAfterSeconds");
+    const fieldIssues = readFieldIssues(context);
+    const requestId = readString(context, "requestId");
+    const domainError = {
+        category: categorizeFailure(status, isRecord(body) ? body.category : undefined),
+        code: code ?? (status !== undefined ? `HTTP_${status}` : "HTTP_ERROR"),
+        message,
+        retryable: isReplayable(status, readOnly),
+        operation,
+        sideEffect: determineSideEffectOutcome(status),
+        ...(fieldIssues !== undefined ? { fieldIssues } : {}),
+        ...(requestId !== undefined ? { requestId } : {}),
+        ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
+    };
+    return {
+        message,
+        code,
+        flatContext: isRecord(context) ? context : undefined,
+        domainError,
+    };
+}
+async function readBody(response) {
+    try {
+        return { ok: true, value: await response.json() };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * Create client core infrastructure
+ *
+ * @param config - Client configuration
+ * @returns Core infrastructure for namespace implementations
+ */
+export function createClientCore(config) {
+    const { serverUrl, apiKey } = config;
+    const requestCache = new Map();
+    const inflightRequests = new Map();
+    let observedCacheGeneration = cacheGeneration;
+    function resetClearedCaches() {
+        if (observedCacheGeneration === cacheGeneration)
+            return;
+        requestCache.clear();
+        inflightRequests.clear();
+        observedCacheGeneration = cacheGeneration;
+    }
+    /**
+     * Build full URL from path
+     */
+    function buildUrl(path) {
+        const base = serverUrl.replace(/\/$/, "");
+        const cleanPath = path.startsWith("/") ? path : `/${path}`;
+        return `${base}${cleanPath}`;
+    }
+    /**
+     * Build request headers
+     */
+    function buildHeaders(customHeaders) {
+        return {
+            "X-Store-API-Key": apiKey,
+            "Content-Type": "application/json",
+            ...customHeaders,
+        };
+    }
+    /**
+     * Execute fetch with retry logic.
+     *
+     * Retries are for reads only — callers pass `retries: 0` for anything that
+     * writes. An aborted signal is never retried and never worth waiting on.
+     */
+    async function fetchWithRetry(url, options, retries, signal) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            if (signal?.aborted) {
+                throw new Error(ABORT_MESSAGE);
+            }
+            try {
+                return await fetch(url, options);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error("Network error");
+                if (signal?.aborted || attempt === retries) {
+                    break;
+                }
+                // Exponential backoff: 100ms, 200ms
+                const delay = 100 * Math.pow(2, attempt);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+        throw lastError ?? new Error("Network error");
+    }
+    /**
+     * GET request with in-flight deduplication and opt-in caching.
+     *
+     * Default behaviour: every call fetches fresh,
+     * but parallel identical calls coalesce into one request. Pass
+     * `{ cache: true }` for read-mostly data (config, categories, geo).
+     *
+     * Rejected and nullish results are never cached — a transient failure
+     * or an absent record must not be pinned for the isolate's lifetime.
+     *
+     * Pass `{ envelope: true }` for endpoints that carry metadata outside
+     * `data` (e.g. pagination totals) and need the full response body.
+     *
+     * A failing read never resolves to a wrong value: it throws a
+     * `StorefrontError` carrying the same `DomainError` the mutation path
+     * returns. A cancelled or timed-out read neither retries nor coalesces —
+     * one caller's abort must not cancel another's request, and an abandoned
+     * request must not be pinned in the cache.
+     */
+    async function get(path, schema, opts) {
+        resetClearedCaches();
+        const url = buildUrl(path);
+        const operation = opts?.operation ?? `GET ${path}`;
+        const request = composeSignal(opts?.signal, opts?.timeoutMs);
+        const shared = request.signal === undefined;
+        try {
+            // Check cache first (only successful results ever live here)
+            if (opts?.cache && shared) {
+                const cached = requestCache.get(url);
+                if (cached) {
+                    return (await cached);
+                }
+            }
+            // Check in-flight requests for deduplication
+            if (shared) {
+                const inflight = inflightRequests.get(url);
+                if (inflight) {
+                    return (await inflight);
+                }
+            }
+            // Create new request
+            const requestPromise = (async () => {
+                try {
+                    const response = await fetchWithRetry(url, {
+                        method: "GET",
+                        headers: buildHeaders(),
+                        ...(request.signal ? { signal: request.signal } : {}),
+                    }, shared ? 2 : 0, request.signal);
+                    if (!response.ok) {
+                        const body = await readBody(response);
+                        throw new StorefrontError(serverFailure(response.status, body.ok ? body.value : undefined, operation, true)
+                            .domainError);
+                    }
+                    const body = await readBody(response);
+                    if (!body.ok) {
+                        throw new StorefrontError(unreadableSuccess("MALFORMED_RESPONSE", MALFORMED_MESSAGE, operation, true));
+                    }
+                    const json = body.value;
+                    if (opts?.envelope) {
+                        if (schema) {
+                            const parsed = schema.safeParse(json);
+                            if (!parsed.success) {
+                                throw new StorefrontError(unreadableSuccess("SCHEMA_VALIDATION_FAILED", SCHEMA_MESSAGE, operation, true));
+                            }
+                            return parsed.data;
+                        }
+                        return json;
+                    }
+                    const data = isRecord(json) ? json.data : undefined;
+                    // Validate with schema if provided
+                    if (schema) {
+                        const parsed = schema.safeParse(data);
+                        if (!parsed.success) {
+                            throw new StorefrontError(unreadableSuccess("SCHEMA_VALIDATION_FAILED", SCHEMA_MESSAGE, operation, true));
+                        }
+                        return parsed.data;
+                    }
+                    return data;
+                }
+                finally {
+                    // Remove from inflight after completion
+                    if (shared) {
+                        inflightRequests.delete(url);
+                    }
+                }
+            })();
+            // Store in-flight so parallel callers coalesce (only when no individual signal)
+            if (shared) {
+                inflightRequests.set(url, requestPromise);
+            }
+            if (opts?.cache && shared) {
+                requestCache.set(url, requestPromise);
+                // A failed or empty lookup must not be pinned: evict so the next
+                // call retries against the server.
+                requestPromise.then((value) => {
+                    if (value == null)
+                        requestCache.delete(url);
+                }, () => {
+                    requestCache.delete(url);
+                });
+            }
+            return await requestPromise;
+        }
+        catch (error) {
+            if (error instanceof StorefrontError)
+                throw error;
+            throw new StorefrontError(transportFailure(error, request, operation, true));
+        }
+        finally {
+            request.cleanup();
+        }
+    }
+    /**
+     * POST request with error handling.
+     *
+     * By default the `{ data: ... }` envelope is unwrapped and `data`
+     * returned. Pass `topLevelData: true` for endpoints whose payload sits at
+     * the top level (e.g. `POST /store/abandoned` → `{ success, id }`).
+     *
+     * On failure the error result carries `code`, every field of the server's
+     * `context` object (`windowSeconds`, `attemptsRemaining`, `terminal`)
+     * flattened into the result — the checkout UI reads these — and the whole
+     * failure again as `domainError`, the serializable contract a caller may
+     * branch on. A POST never throws: an aborted or dropped request leaves the
+     * outcome `unknown`, never a retry of a possible duplicate.
+     */
+    async function post(path, body, opts) {
+        const url = buildUrl(path);
+        const operation = opts?.operation ?? `POST ${path}`;
+        const request = composeSignal(opts?.signal, opts?.timeoutMs);
+        if (request.aborted()) {
+            request.cleanup();
+            const domainError = abortedError(operation);
+            return { success: false, error: domainError.message, domainError };
+        }
+        try {
+            const response = await fetchWithRetry(url, {
+                method: "POST",
+                headers: buildHeaders(opts?.headers),
+                body: JSON.stringify(body),
+                ...(request.signal ? { signal: request.signal } : {}),
+            }, 0, request.signal);
+            const read = await readBody(response);
+            if (!response.ok) {
+                const failure = serverFailure(response.status, read.ok ? read.value : undefined, operation, false);
+                return {
+                    success: false,
+                    error: failure.message,
+                    ...(failure.code !== undefined ? { code: failure.code } : {}),
+                    domainError: failure.domainError,
+                    ...failure.flatContext,
+                };
+            }
+            if (!read.ok || !isRecord(read.value)) {
+                const domainError = unreadableSuccess("MALFORMED_RESPONSE", MALFORMED_MESSAGE, operation, false);
+                return { success: false, error: domainError.message, domainError };
+            }
+            const payload = read.value;
+            const data = opts?.topLevelData ? payload : payload.data;
+            // Validate with schema if provided
+            if (opts?.schema) {
+                const parsed = opts.schema.safeParse(data);
+                if (!parsed.success) {
+                    const domainError = unreadableSuccess("SCHEMA_VALIDATION_FAILED", SCHEMA_MESSAGE, operation, false);
+                    return { success: false, error: domainError.message, domainError };
+                }
+                return { success: true, data: parsed.data };
+            }
+            return { success: true, data: data };
+        }
+        catch (error) {
+            const domainError = transportFailure(error, request, operation, false);
+            return { success: false, error: domainError.message, domainError };
+        }
+        finally {
+            request.cleanup();
+        }
+    }
+    /**
+     * PATCH request with error handling
+     */
+    async function patch(path, body, optsOrSchema) {
+        const url = buildUrl(path);
+        const opts = optsOrSchema && "safeParse" in optsOrSchema
+            ? { schema: optsOrSchema }
+            : (optsOrSchema ?? {});
+        const operation = opts.operation ?? `PATCH ${path}`;
+        const request = composeSignal(opts.signal, opts.timeoutMs);
+        if (request.aborted()) {
+            request.cleanup();
+            const domainError = abortedError(operation);
+            return { success: false, error: domainError.message, domainError };
+        }
+        try {
+            const response = await fetchWithRetry(url, {
+                method: "PATCH",
+                headers: buildHeaders(opts.headers),
+                body: JSON.stringify(body),
+                ...(request.signal ? { signal: request.signal } : {}),
+            }, 0, request.signal);
+            const read = await readBody(response);
+            if (!response.ok) {
+                const failure = serverFailure(response.status, read.ok ? read.value : undefined, operation, false);
+                return {
+                    success: false,
+                    error: failure.message,
+                    ...(failure.code !== undefined ? { code: failure.code } : {}),
+                    domainError: failure.domainError,
+                    ...failure.flatContext,
+                };
+            }
+            if (!read.ok || !isRecord(read.value)) {
+                const domainError = unreadableSuccess("MALFORMED_RESPONSE", MALFORMED_MESSAGE, operation, false);
+                return { success: false, error: domainError.message, domainError };
+            }
+            const data = read.value.data;
+            // Validate with schema if provided
+            if (opts.schema) {
+                const parsed = opts.schema.safeParse(data);
+                if (!parsed.success) {
+                    const domainError = unreadableSuccess("SCHEMA_VALIDATION_FAILED", SCHEMA_MESSAGE, operation, false);
+                    return { success: false, error: domainError.message, domainError };
+                }
+                return { success: true, data: parsed.data };
+            }
+            return { success: true, data: data };
+        }
+        catch (error) {
+            const domainError = transportFailure(error, request, operation, false);
+            return { success: false, error: domainError.message, domainError };
+        }
+        finally {
+            request.cleanup();
+        }
+    }
+    return {
+        config,
+        get,
+        post,
+        patch,
+    };
+}
+/**
+ * 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 function reportDegradedRead(config, error, operation) {
+    const onError = config?.onError;
+    if (!onError)
+        return;
+    const domainError = isStorefrontError(error)
+        ? error.domainError
+        : {
+            category: "transport",
+            code: "NETWORK_ERROR",
+            message: error instanceof Error ? error.message : "Network error",
+            retryable: true,
+            operation,
+            sideEffect: "not_started",
+        };
+    try {
+        onError(domainError);
+    }
+    catch {
+        // Observability must never escalate a degraded read.
+    }
+}
+/**
+ * Clear the request cache
+ * Useful for testing or forcing fresh data
+ */
+export function clearCache() {
+    cacheGeneration += 1;
+}

package/dist/client/errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * SDK error type for read failures.
+ *
+ * Reads resolve their "absent" outcomes (null, [], {}) through the namespaces;
+ * everything else is a real failure and arrives as one of these. It stays an
+ * `Error` so existing `catch`/`instanceof Error` call sites keep working, and it
+ * carries a plain, serializable `DomainError` so a caller can branch on
+ * category, code, retryability and side-effect outcome instead of a string.
+ */
+import type { DomainError } from "../domain.js";
+export declare class StorefrontError extends Error {
+    readonly domainError: DomainError;
+    constructor(domainError: DomainError);
+}
+/**
+ * Recognises a StorefrontError across a realm boundary (worker, iframe, Astro
+ * action), where `instanceof` fails but the serialized shape survives.
+ */
+export declare function isStorefrontError(value: unknown): value is StorefrontError;

package/dist/client/errors.js

@@ -0,0 +1,31 @@
+/**
+ * SDK error type for read failures.
+ *
+ * Reads resolve their "absent" outcomes (null, [], {}) through the namespaces;
+ * everything else is a real failure and arrives as one of these. It stays an
+ * `Error` so existing `catch`/`instanceof Error` call sites keep working, and it
+ * carries a plain, serializable `DomainError` so a caller can branch on
+ * category, code, retryability and side-effect outcome instead of a string.
+ */
+export class StorefrontError extends Error {
+    domainError;
+    constructor(domainError) {
+        super(domainError.message);
+        this.name = "StorefrontError";
+        this.domainError = domainError;
+    }
+}
+/**
+ * Recognises a StorefrontError across a realm boundary (worker, iframe, Astro
+ * action), where `instanceof` fails but the serialized shape survives.
+ */
+export function isStorefrontError(value) {
+    if (value instanceof StorefrontError)
+        return true;
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return (candidate.name === "StorefrontError" &&
+        typeof candidate.domainError === "object" &&
+        candidate.domainError !== null);
+}

package/dist/client/geo.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Geo Namespace - Wilayas & Communes
+ *
+ * Deep module: hides where the wilaya dataset lives and the communes lookup
+ * behind two calls.
+ *
+ * `wilayas()` resolves the bundled static dataset — Algeria's 58 wilayas
+ * are stable reference data, so no network round-trip. It stays async so the
+ * data can move server-side without touching call sites.
+ *
+ * `communes()` reads the server and is cached per wilaya (reference data);
+ * failures resolve to `[]` — never throw. Wilaya IDs are 1–58; anything
+ * else is a 400 upstream, surfaced as `[]` (no communes to show).
+ */
+import { type ClientCore } from "./core.js";
+import type { Commune, Wilaya } from "../types.js";
+export interface GeoNamespace {
+    /**
+     * Algeria's 58 wilayas, with Arabic names for RTL checkout forms.
+     */
+    wilayas(): Promise<Wilaya[]>;
+    /**
+     * Communes for one wilaya (1–58), cached. Resolves to `[]` on failure
+     * or an unknown wilaya.
+     */
+    communes(wilayaId: number | string): Promise<Commune[]>;
+}
+/**
+ * Create geo namespace
+ */
+export declare function createGeoNamespace(core: ClientCore): GeoNamespace;