@wocart/storefront 0.0.0-stage → 1.0.0

package/dist/abandoned-checkout.d.ts

@@ -0,0 +1,22 @@
+import type { AbandonedCheckoutInput } from "./domain.js";
+export type AbandonedCheckoutSnapshot = Omit<AbandonedCheckoutInput, "sessionId" | "fbc" | "fbp">;
+export interface AbandonedCheckoutStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export interface AbandonedCheckoutPorts {
+    readonly storage: AbandonedCheckoutStorage;
+    readonly createId: () => string;
+    readonly schedule: (callback: () => void, delayMs: number) => unknown;
+    readonly cancel: (handle: unknown) => void;
+    readonly readCookie: (name: string) => string | undefined;
+    readonly send: (payload: AbandonedCheckoutInput) => Promise<void>;
+    readonly beacon: (payload: AbandonedCheckoutInput) => void;
+}
+export interface AbandonedCheckoutTracker {
+    schedule(snapshot: AbandonedCheckoutSnapshot): void;
+    update(snapshot: AbandonedCheckoutSnapshot): void;
+    captureOnExit(snapshot: AbandonedCheckoutSnapshot): void;
+    isCapturable(snapshot: AbandonedCheckoutSnapshot): boolean;
+}
+export declare function createAbandonedCheckoutTracker(ports: AbandonedCheckoutPorts): AbandonedCheckoutTracker;

package/dist/abandoned-checkout.js

@@ -0,0 +1,89 @@
+import { toLocalAlgerianMobile } from "./phone.js";
+const SESSION_KEY = "cod_session_id";
+const DEBOUNCE_MS = 3000;
+export function createAbandonedCheckoutTracker(ports) {
+    let sessionId = readSessionId(ports);
+    let timer = null;
+    let hasSentInitial = false;
+    const payloadFor = (snapshot) => {
+        const fbc = readCookie(ports, "_fbc");
+        const fbp = readCookie(ports, "_fbp");
+        return {
+            ...snapshot,
+            sessionId,
+            ...(fbc === undefined ? {} : { fbc }),
+            ...(fbp === undefined ? {} : { fbp }),
+        };
+    };
+    const send = (snapshot) => {
+        try {
+            if (!isCapturable(snapshot))
+                return;
+            const payload = payloadFor(snapshot);
+            void Promise.resolve(ports.send(payload)).then(() => {
+                hasSentInitial = true;
+            }, () => undefined);
+        }
+        catch {
+            return;
+        }
+    };
+    const isCapturable = (snapshot) => snapshot.customerName.trim().length >= 2 &&
+        toLocalAlgerianMobile(snapshot.phone) !== null;
+    return {
+        schedule(snapshot) {
+            try {
+                if (timer !== null)
+                    ports.cancel(timer);
+                timer = ports.schedule(() => {
+                    timer = null;
+                    send(snapshot);
+                }, DEBOUNCE_MS);
+            }
+            catch {
+                timer = null;
+            }
+        },
+        update(snapshot) {
+            try {
+                if (hasSentInitial)
+                    send(snapshot);
+            }
+            catch {
+                return;
+            }
+        },
+        captureOnExit(snapshot) {
+            try {
+                if (!isCapturable(snapshot))
+                    return;
+                ports.beacon(payloadFor(snapshot));
+            }
+            catch {
+                return;
+            }
+        },
+        isCapturable,
+    };
+}
+function readCookie(ports, name) {
+    try {
+        return ports.readCookie(name);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readSessionId(ports) {
+    try {
+        const existing = ports.storage.getItem(SESSION_KEY);
+        if (existing)
+            return existing;
+        const created = ports.createId();
+        ports.storage.setItem(SESSION_KEY, created);
+        return created;
+    }
+    catch {
+        return ports.createId();
+    }
+}

package/dist/actions.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Storefront Actions — the placeOrder action's engine, framework-free.
+ *
+ * Astro's `defineAction`/`ActionError` live in `astro:actions`, a virtual
+ * module that only exists inside an Astro project — so the engine moves here
+ * and each theme keeps a thin wrapper:
+ *
+ * ```ts
+ * // src/actions/index.ts
+ * import { ActionError, defineAction } from "astro:actions";
+ * import { executePlaceOrder, placeOrderInput } from "@wocart/storefront/astro";
+ *
+ * export const server = {
+ *   placeOrder: defineAction({
+ *     accept: "form",
+ *     input: placeOrderInput,
+ *     handler: async (input, context) => {
+ *       const result = await executePlaceOrder(input, context.request, client);
+ *       if (!result.success) {
+ *         if (result.errorKind === "shape") {
+ *           throw new ActionError({ code: "BAD_REQUEST", message: result.error });
+ *         }
+ *         throw new Error(result.error);
+ *       }
+ *       return result.data;
+ *     },
+ *   }),
+ * };
+ * ```
+ *
+ * Everything decision-bearing — the input whitelist, the basket-or-product
+ * rule, attribution forwarding, the exact wire body — lives here, tested
+ * without Astro.
+ */
+import { z } from "zod";
+import type { StoreClient } from "./client/index.js";
+import type { DomainError } from "./domain.js";
+import type { CreatedOrder } from "./types.js";
+/**
+ * The order form's input whitelist.
+ *
+ * zod STRIPS every key this schema does not name, which is why a field the
+ * storefront renders but this schema forgets silently never reaches
+ * the server. Form parsing needs a plain object schema
+ * (no .superRefine), so the basket-or-product rule lives in
+ * executePlaceOrder — failing there turns a bare 400 into a field error the
+ * form can actually render.
+ */
+export declare const placeOrderInput: z.ZodObject<{
+    productId: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    productName: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    variantId: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    variantLabel: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    pricePerUnit: z.ZodPreprocess<z.ZodOptional<z.ZodCoercedNumber<unknown>>, unknown>;
+    quantity: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offerId: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    variantSelections: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        variantId: z.ZodString;
+        variantLabel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>, unknown>;
+    customerName: z.ZodString;
+    phone: z.ZodPreprocess<z.ZodString, unknown>;
+    wilayaId: z.ZodCoercedNumber<unknown>;
+    communeId: z.ZodString;
+    address: z.ZodOptional<z.ZodString>;
+    deliveryType: z.ZodDefault<z.ZodEnum<{
+        home: "home";
+        stop_desk: "stop_desk";
+    }>>;
+    notes: z.ZodOptional<z.ZodString>;
+    email: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    customFieldResponses: z.ZodPreprocess<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnknown>]>>, unknown>;
+    fbc: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    fbp: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    otpToken: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    turnstileToken: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    items: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        productId: z.ZodString;
+        productName: z.ZodString;
+        variantId: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+        variantLabel: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+        quantity: z.ZodCoercedNumber<unknown>;
+        pricePerUnit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        offerId: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    }, z.core.$strip>>>, unknown>;
+    landingPageSlug: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+}, z.core.$strip>;
+export type PlaceOrderInput = z.infer<typeof placeOrderInput>;
+/**
+ * Collect the shopper's attribution headers so the server records the
+ * visitor, not the theme's worker: User-Agent verbatim, the client IP from
+ * Cloudflare's CF-Connecting-IP (falling back to the first X-Forwarded-For
+ * entry), and the Referer when present.
+ */
+export declare function collectForwardedHeaders(request: Request): Record<string, string>;
+export type PlaceOrderResult = {
+    success: true;
+    data: CreatedOrder;
+} | {
+    success: false;
+    error: string;
+    errorKind: "shape";
+} | {
+    success: false;
+    error: string;
+    errorKind: "upstream";
+    domainError: DomainError;
+};
+/**
+ * Execute the placeOrder action's handler body: enforce the
+ * basket-or-product rule, forward attribution headers, and submit the order.
+ *
+ * The parsed `input` IS the wire body: placeOrderInput is a whitelist whose
+ * keys match the server's create-order body 1:1, so a second hand-written
+ * field list would be one more thing to drift.
+ */
+export declare function executePlaceOrder(input: PlaceOrderInput, request: Request, client: StoreClient): Promise<PlaceOrderResult>;

package/dist/actions.js

@@ -0,0 +1,196 @@
+/**
+ * Storefront Actions — the placeOrder action's engine, framework-free.
+ *
+ * Astro's `defineAction`/`ActionError` live in `astro:actions`, a virtual
+ * module that only exists inside an Astro project — so the engine moves here
+ * and each theme keeps a thin wrapper:
+ *
+ * ```ts
+ * // src/actions/index.ts
+ * import { ActionError, defineAction } from "astro:actions";
+ * import { executePlaceOrder, placeOrderInput } from "@wocart/storefront/astro";
+ *
+ * export const server = {
+ *   placeOrder: defineAction({
+ *     accept: "form",
+ *     input: placeOrderInput,
+ *     handler: async (input, context) => {
+ *       const result = await executePlaceOrder(input, context.request, client);
+ *       if (!result.success) {
+ *         if (result.errorKind === "shape") {
+ *           throw new ActionError({ code: "BAD_REQUEST", message: result.error });
+ *         }
+ *         throw new Error(result.error);
+ *       }
+ *       return result.data;
+ *     },
+ *   }),
+ * };
+ * ```
+ *
+ * Everything decision-bearing — the input whitelist, the basket-or-product
+ * rule, attribution forwarding, the exact wire body — lives here, tested
+ * without Astro.
+ */
+import { z } from "zod";
+import { toLocalAlgerianMobile } from "./phone.js";
+function parseOptionalArrayInput(value) {
+    if (!value || value === "[]")
+        return undefined;
+    if (Array.isArray(value))
+        return value.length > 0 ? value : undefined;
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) && parsed.length > 0 ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseVariantSelectionsInput(value) {
+    if (!value || value === "[]")
+        return undefined;
+    if (Array.isArray(value))
+        return value.length > 0 ? value : undefined;
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+const optionalVariantId = z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().min(1).max(200).optional());
+const optionalVariantLabel = z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().max(100).optional());
+const cartItemInput = z.object({
+    productId: z.string().min(1).max(200),
+    productName: z.string().min(1).max(200),
+    variantId: optionalVariantId,
+    variantLabel: optionalVariantLabel,
+    quantity: z.coerce.number().int().min(1).max(100),
+    pricePerUnit: z.coerce.number().nonnegative().optional(),
+    offerId: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().optional()),
+});
+/**
+ * The order form's input whitelist.
+ *
+ * zod STRIPS every key this schema does not name, which is why a field the
+ * storefront renders but this schema forgets silently never reaches
+ * the server. Form parsing needs a plain object schema
+ * (no .superRefine), so the basket-or-product rule lives in
+ * executePlaceOrder — failing there turns a bare 400 into a field error the
+ * form can actually render.
+ */
+export const placeOrderInput = z.object({
+    // Optional because a basket order has no single representative product;
+    // executePlaceOrder requires them whenever `items` is absent.
+    productId: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().min(1).max(200).optional()),
+    productName: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().min(1).max(200).optional()),
+    // Forms always submit all hidden inputs — empty string must become undefined
+    variantId: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().min(1).optional()),
+    variantLabel: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().max(100).optional()),
+    pricePerUnit: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.coerce.number().positive().optional()),
+    quantity: z.coerce.number().int().min(1).max(100).default(1),
+    // Explicit offer tier selected by the user
+    offerId: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().optional()),
+    // Per-unit variant selections — JSON string from hidden form input
+    variantSelections: z.preprocess(parseVariantSelectionsInput, z.array(z.object({
+        variantId: z.string().min(1),
+        variantLabel: z.string().optional(),
+    })).optional()),
+    customerName: z.string().min(2, "الاسم مطلوب").max(100),
+    phone: z.preprocess((v) => (typeof v === "string" ? toLocalAlgerianMobile(v) ?? v : v), z.string().regex(/^0[567]\d{8}$/, "رقم الهاتف غير صحيح")),
+    wilayaId: z.coerce.number().int().min(1).max(58),
+    communeId: z.string().min(1, "يرجى اختيار البلدية"),
+    address: z.string().max(300).optional(),
+    deliveryType: z.enum(["home", "stop_desk"]).default("home"),
+    notes: z.string().max(500).optional(),
+    // Checkout Form Policy fields. This schema is a whitelist — anything not
+    // named here is stripped before the order reaches the server — so both
+    // keys must exist even though whether they are asked for, and whether
+    // they may be empty, is the merchant's policy and the server's ruling.
+    // Validated permissively on purpose: a stricter rule here would reject
+    // with this worker's message instead of the store-language one the server
+    // returns, and would be a second definition of the same rule.
+    email: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().max(254).optional()),
+    // One JSON field rather than one input per custom field, precisely
+    // because of this whitelist: a merchant adding a field must never require
+    // a theme deploy.
+    customFieldResponses: z.preprocess((v) => {
+        if (!v || v === "[]")
+            return undefined;
+        if (Array.isArray(v))
+            return v.length > 0 ? v : undefined;
+        if (typeof v !== "string" || v.length > 4000)
+            return undefined;
+        return v;
+    }, z.union([z.string().max(4000), z.array(z.unknown())]).optional()),
+    fbc: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().optional()),
+    fbp: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().optional()),
+    // WhatsApp OTP verification proof — set after the OTP step verifies.
+    // Absent when the store has verification disabled (schema stays additive).
+    otpToken: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().min(10).max(1024).optional()),
+    // Cloudflare Turnstile proof — auto-injected by the widget's hidden input
+    // when the store enables bot protection. Absent when disabled (additive).
+    // Tokens are single-use, max 2048 chars, and expire after 300 seconds.
+    turnstileToken: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().min(1).max(2048).optional()),
+    // Cart basket. Present only when checkout started from the drawer; an
+    // empty or malformed value falls through to the flat single-product
+    // fields above, so the direct order form is untouched by this.
+    items: z.preprocess(parseOptionalArrayInput, z.array(cartItemInput).min(1).max(20).optional()),
+    // Landing page attribution — best-effort: unknown/draft slug leaves
+    // the order unattributed, never blocked (platform extension, LP feature).
+    landingPageSlug: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().min(1).max(60).optional()),
+});
+/**
+ * Collect the shopper's attribution headers so the server records the
+ * visitor, not the theme's worker: User-Agent verbatim, the client IP from
+ * Cloudflare's CF-Connecting-IP (falling back to the first X-Forwarded-For
+ * entry), and the Referer when present.
+ */
+export function collectForwardedHeaders(request) {
+    const forwardedHeaders = {};
+    const userAgent = request.headers.get("User-Agent");
+    if (userAgent)
+        forwardedHeaders["User-Agent"] = userAgent;
+    const clientIp = request.headers.get("CF-Connecting-IP") ??
+        request.headers.get("X-Forwarded-For")?.split(",")[0]?.trim();
+    if (clientIp)
+        forwardedHeaders["X-Forwarded-For"] = clientIp;
+    const referer = request.headers.get("Referer");
+    if (referer)
+        forwardedHeaders["Referer"] = referer;
+    return forwardedHeaders;
+}
+/**
+ * Execute the placeOrder action's handler body: enforce the
+ * basket-or-product rule, forward attribution headers, and submit the order.
+ *
+ * The parsed `input` IS the wire body: placeOrderInput is a whitelist whose
+ * keys match the server's create-order body 1:1, so a second hand-written
+ * field list would be one more thing to drift.
+ */
+export async function executePlaceOrder(input, request, client) {
+    // An order is either a basket or a single product, never neither.
+    if (!input.items?.length &&
+        (!input.productId || !input.productName || !input.pricePerUnit)) {
+        return {
+            success: false,
+            error: "An order needs either a basket or a product.",
+            errorKind: "shape",
+        };
+    }
+    const result = await client.orders.create(input, collectForwardedHeaders(request));
+    if (!result.success) {
+        return {
+            success: false,
+            error: result.error,
+            errorKind: "upstream",
+            domainError: result.domainError,
+        };
+    }
+    return { success: true, data: result.data };
+}

package/dist/astro.d.ts

@@ -0,0 +1,6 @@
+export { createProxyEndpoint } from "./endpoints/proxy.js";
+export type { ProxyClientFn, ProxyEndpointConfig, AstroAPIContext, AstroAPIRoute, } from "./endpoints/proxy.js";
+export { placeOrderInput, executePlaceOrder, collectForwardedHeaders, } from "./actions.js";
+export type { PlaceOrderInput, PlaceOrderResult } from "./actions.js";
+export { resolveActionRedirectDecision } from "./middleware.js";
+export type { PrgDecision, ActionMiddlewareDeps, ActionDescriptor } from "./middleware.js";

package/dist/astro.js

@@ -0,0 +1,3 @@
+export { createProxyEndpoint } from "./endpoints/proxy.js";
+export { placeOrderInput, executePlaceOrder, collectForwardedHeaders, } from "./actions.js";
+export { resolveActionRedirectDecision } from "./middleware.js";

package/dist/basket.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 { type BasketLine, type BasketLineInput } from "./domain.js";
+/** Default key used in browser storage, versioned to prevent schema drift crashes. */
+export declare const DEFAULT_BASKET_STORAGE_KEY = "cod_cart_v1";
+/**
+ * Storage adapter abstraction.
+ *
+ * Allows zero-browser operation (in-memory for unit tests / SSR) and safe
+ * degradation when localStorage is blocked (cookies disabled, private mode).
+ */
+export interface BasketStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    isAvailable(): boolean;
+    subscribe?(onExternalChange: () => void): () => void;
+}
+/**
+ * Options for creating a basket store.
+ */
+export interface BasketStoreOptions {
+    storageKey?: string;
+    storage?: BasketStorageAdapter;
+    maxLines?: number;
+    maxLineQuantity?: number;
+}
+export type BasketListener = (lines: readonly BasketLine[]) => void;
+/**
+ * Basket Store Interface.
+ *
+ * Deep module interface: 9 simple, focused methods that hide all storage
+ * failures, cross-tab events, line reconciliation, and normalization.
+ */
+export interface BasketStore {
+    /** Get current snapshot of lines. */
+    getLines(): readonly BasketLine[];
+    /** Total quantity of items in the basket. */
+    getCount(): number;
+    /** Optimistic display subtotal. Not trusted for money. */
+    getSubtotal(): number;
+    /** Add a line. Merges with existing product+variant, caps quantities. */
+    addLine(line: BasketLine): readonly BasketLine[];
+    /** Update quantity of an existing line. Removes if <= 0. */
+    setQuantity(key: string, quantity: number): readonly BasketLine[];
+    /** Remove a line by its composite key. */
+    removeLine(key: string): readonly BasketLine[];
+    /** Empty the basket. */
+    clear(): readonly BasketLine[];
+    /** Convert lines to server-ready wire items for POST /store/cart/validate or order creation. */
+    toOrderItems(): BasketLineInput[];
+    /** Subscribe to state changes (local and cross-tab). Returns unsubscribe. */
+    subscribe(listener: BasketListener): () => void;
+    /** Check if the underlying storage can persist across reloads. */
+    isPersistent(): boolean;
+}
+/**
+ * Create a memory storage adapter (ideal for node, tests, and SSR).
+ */
+export declare function createMemoryStorageAdapter(): BasketStorageAdapter;
+/**
+ * Create a safe browser localStorage adapter with storage event subscription.
+ */
+export declare function createLocalStorageAdapter(storageKey?: string): BasketStorageAdapter;
+/**
+ * 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 declare function toOrderItems(lines: readonly BasketLine[]): BasketLineInput[];
+/**
+ * Create a deep Basket Store.
+ */
+export declare function createBasketStore(options?: BasketStoreOptions): BasketStore;