@wocart/storefront 0.0.0-stage → 1.1.0

package/dist/middleware.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Middleware engine — the POST/Redirect/GET pattern for Astro Actions,
+ * framework-free.
+ *
+ * `astro:middleware` and `astro:actions` are virtual modules that only
+ * exist inside an Astro project, so this file computes the DECISION and each
+ * theme's middleware executes it:
+ *
+ * ```ts
+ * // src/middleware.ts
+ * import { defineMiddleware } from "astro:middleware";
+ * import { getActionContext } from "astro:actions";
+ * import { resolveActionRedirectDecision } from "@wocart/storefront/astro";
+ *
+ * export const onRequest = defineMiddleware(async (context, next) => {
+ *   const { action, setActionResult, serializeActionResult } =
+ *     getActionContext(context);
+ *   const decision = await resolveActionRedirectDecision({
+ *     action: action && {
+ *       calledFrom: action.calledFrom,
+ *       name: action.name,
+ *       handler: action.handler,
+ *     },
+ *     setActionResult,
+ *     serializeActionResult,
+ *     referer: context.request.headers.get("Referer"),
+ *     pathname: context.url.pathname,
+ *   });
+ *   if (decision.kind === "redirect") {
+ *     return context.redirect(decision.location, decision.status);
+ *   }
+ *   return next();
+ * });
+ * ```
+ *
+ * The pattern (Astro docs):
+ * - On ERROR  → store the result cookie + 303 redirect back to the form page
+ *               → the page re-renders, getActionResult() returns the error,
+ *               field errors are displayed to the user.
+ * - On SUCCESS → store the result cookie + let next() render the page from
+ *               the same POST → getActionResult() returns the success data,
+ *               the page issues Astro.redirect('/thank-you?...') which the
+ *               browser follows.
+ *
+ * On success the caller MUST call next(), not context.redirect(): a redirect
+ * drops the setActionResult cookie, getActionResult() sees undefined on the
+ * next page, and the thank-you redirect never fires. That invariant is what
+ * the "next on success" decision encodes — the tests pin it.
+ */
+/**
+ * The slice of an action result the decision reads: whether it errored.
+ * Astro's own `SafeResult` is assignable to this.
+ */
+export interface ActionHandlerResult {
+    error?: unknown;
+    data?: unknown;
+}
+export interface ActionDescriptor<TResult extends ActionHandlerResult = ActionHandlerResult> {
+    /** Astro sets this to "form" for HTML form submissions, "json" otherwise. */
+    calledFrom: string;
+    name: string;
+    handler: () => Promise<TResult>;
+}
+/**
+ * `TSerialized` is the framework's result-cookie token, opaque to this SDK:
+ * Astro 5 used a string, Astro 7 an object (`SerializedActionResult`). The
+ * generics thread whatever `getActionContext()` hands the theme straight
+ * through, so no theme ever casts.
+ */
+export interface ActionMiddlewareDeps<TResult extends ActionHandlerResult = ActionHandlerResult, TSerialized = string> {
+    action?: ActionDescriptor<TResult>;
+    /** Stores the serialized action result cookie (Astro's setActionResult). */
+    setActionResult: (name: string, serialized: TSerialized) => void;
+    /** Serializes an ActionResult into the cookie value (Astro's serializeActionResult). */
+    serializeActionResult: (result: TResult) => TSerialized;
+    /** The Referer request header, if the shopper's browser sent one. */
+    referer?: string | null;
+    /** Path of the page the form posted to — the fallback redirect target. */
+    pathname: string;
+}
+export type PrgDecision = 
+/** Redirect back to the form page (error path) — 303 See Other. */
+{
+    kind: "redirect";
+    location: string;
+    status: 303;
+}
+/** Render the page from this POST (success / not an action / JSON action). */
+ | {
+    kind: "next";
+};
+/**
+ * Decide what the middleware should do for this request.
+ *
+ * Runs the action handler exactly when it was called from a form, stores the
+ * serialized result cookie either way, and redirects back to the form page
+ * on error (Referer first, the posted path as fallback). Success falls
+ * through to "next" — never a redirect — so the result cookie survives.
+ */
+export declare function resolveActionRedirectDecision<TResult extends ActionHandlerResult, TSerialized>(deps: ActionMiddlewareDeps<TResult, TSerialized>): Promise<PrgDecision>;

package/dist/middleware.js

@@ -0,0 +1,72 @@
+/**
+ * Middleware engine — the POST/Redirect/GET pattern for Astro Actions,
+ * framework-free.
+ *
+ * `astro:middleware` and `astro:actions` are virtual modules that only
+ * exist inside an Astro project, so this file computes the DECISION and each
+ * theme's middleware executes it:
+ *
+ * ```ts
+ * // src/middleware.ts
+ * import { defineMiddleware } from "astro:middleware";
+ * import { getActionContext } from "astro:actions";
+ * import { resolveActionRedirectDecision } from "@wocart/storefront/astro";
+ *
+ * export const onRequest = defineMiddleware(async (context, next) => {
+ *   const { action, setActionResult, serializeActionResult } =
+ *     getActionContext(context);
+ *   const decision = await resolveActionRedirectDecision({
+ *     action: action && {
+ *       calledFrom: action.calledFrom,
+ *       name: action.name,
+ *       handler: action.handler,
+ *     },
+ *     setActionResult,
+ *     serializeActionResult,
+ *     referer: context.request.headers.get("Referer"),
+ *     pathname: context.url.pathname,
+ *   });
+ *   if (decision.kind === "redirect") {
+ *     return context.redirect(decision.location, decision.status);
+ *   }
+ *   return next();
+ * });
+ * ```
+ *
+ * The pattern (Astro docs):
+ * - On ERROR  → store the result cookie + 303 redirect back to the form page
+ *               → the page re-renders, getActionResult() returns the error,
+ *               field errors are displayed to the user.
+ * - On SUCCESS → store the result cookie + let next() render the page from
+ *               the same POST → getActionResult() returns the success data,
+ *               the page issues Astro.redirect('/thank-you?...') which the
+ *               browser follows.
+ *
+ * On success the caller MUST call next(), not context.redirect(): a redirect
+ * drops the setActionResult cookie, getActionResult() sees undefined on the
+ * next page, and the thank-you redirect never fires. That invariant is what
+ * the "next on success" decision encodes — the tests pin it.
+ */
+/**
+ * Decide what the middleware should do for this request.
+ *
+ * Runs the action handler exactly when it was called from a form, stores the
+ * serialized result cookie either way, and redirects back to the form page
+ * on error (Referer first, the posted path as fallback). Success falls
+ * through to "next" — never a redirect — so the result cookie survives.
+ */
+export async function resolveActionRedirectDecision(deps) {
+    const { action, setActionResult, serializeActionResult, referer, pathname } = deps;
+    if (action?.calledFrom === "form") {
+        const result = await action.handler();
+        setActionResult(action.name, serializeActionResult(result));
+        if (result.error) {
+            // Redirect back to the form page so getActionResult() can surface
+            // field errors.
+            return { kind: "redirect", location: referer ?? pathname, status: 303 };
+        }
+        // Success: let next() render the page; the page will redirect to
+        // /thank-you. Calling a redirect here would drop the result cookie.
+    }
+    return { kind: "next" };
+}

package/dist/offer-view.d.ts

@@ -0,0 +1,10 @@
+import type { Offer } from "./types.js";
+export interface OfferTierView {
+    isFreeShipping: boolean;
+    savePct: number;
+    savingsAmount: number;
+    price: number;
+    comparePrice: number | null;
+}
+export type OfferTierInput = Pick<Offer, "discountType" | "triggerQuantity" | "rewardQuantity">;
+export declare function getOfferTierView(offer: OfferTierInput, basePrice: number, comparePrice: number | null): OfferTierView;

package/dist/offer-view.js

@@ -0,0 +1,13 @@
+export function getOfferTierView(offer, basePrice, comparePrice) {
+    const isFreeShipping = offer.discountType === "free_shipping";
+    const quantityTotal = offer.triggerQuantity + offer.rewardQuantity;
+    return {
+        isFreeShipping,
+        savePct: isFreeShipping || quantityTotal <= 0
+            ? 0
+            : Math.round((offer.rewardQuantity / quantityTotal) * 100),
+        savingsAmount: isFreeShipping ? 0 : offer.rewardQuantity * basePrice,
+        price: basePrice * offer.triggerQuantity,
+        comparePrice: comparePrice === null ? null : comparePrice * offer.triggerQuantity,
+    };
+}

package/dist/otp.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Browser-side checkout WhatsApp OTP state machine.
+ *
+ * Deep module: concentrates send/verify flows, cooldown countdowns,
+ * attempt counting, terminal expiry handling, fail-open bypass management,
+ * and state notifications behind a simple, predictable interface.
+ *
+ * Can run in pure memory (tests / node) or drive browser UI via subscription.
+ */
+import type { ClientResult } from "./domain.js";
+import type { OtpSendResult, OtpVerifyResult } from "./types.js";
+import type { z } from "zod";
+/**
+ * Visual / operational step of the OTP process.
+ */
+export type OtpStatus = "idle" | "sending" | "code_sent" | "verifying" | "verified" | "bypassed" | "error";
+/**
+ * Snapshot of OTP state machine at any instant.
+ */
+export interface OtpState {
+    readonly status: OtpStatus;
+    readonly phone: string;
+    readonly normalizedPhone: string | null;
+    readonly requestId: string | null;
+    readonly otpToken: string | null;
+    readonly bypassToken: string | null;
+    readonly error: string | null;
+    readonly errorCode: string | null;
+    readonly cooldownRemaining: number;
+    readonly attemptsRemaining: number | null;
+    readonly isTerminal: boolean;
+}
+export type OtpStateListener = (state: OtpState) => void;
+export interface OtpFailureContext {
+    readonly windowSeconds?: number;
+    readonly attemptsRemaining?: number;
+    readonly terminal?: boolean;
+}
+export type OtpTransportResult<T> = ClientResult<T> & OtpFailureContext;
+export interface OtpTransport {
+    send(phone: string): Promise<OtpTransportResult<OtpSendResult>>;
+    verify(phone: string, requestId: string, code: string): Promise<OtpTransportResult<OtpVerifyResult>>;
+}
+export declare function createOtpTransport(options: {
+    send: OtpTransport["send"];
+    verify: OtpTransport["verify"];
+}): OtpTransport;
+export interface OtpResponseOptions<T> {
+    schema: z.Schema<T>;
+    operation: string;
+    fallbackError: string;
+}
+export declare function otpTransportFailure<T>(error: unknown, operation: string, fallbackError: string): OtpTransportResult<T>;
+export declare function mapOtpResponse<T>(response: Response, options: OtpResponseOptions<T>): Promise<OtpTransportResult<T>>;
+export interface OtpMachineOptions {
+    transport: OtpTransport;
+    initialPhone?: string;
+    onStateChange?: OtpStateListener;
+    timerIntervalMs?: number;
+}
+export interface OtpMachine {
+    /** Get current snapshot of the machine. */
+    getState(): OtpState;
+    /** Set or change phone number. Resets verification if phone changed. */
+    setPhone(phone: string): void;
+    /** Request / send an OTP code via WhatsApp. */
+    send(): Promise<boolean>;
+    /** Verify a 6-digit code. */
+    verify(code: string): Promise<boolean>;
+    /** Reset to idle state. */
+    reset(): void;
+    /** Subscribe to state changes. Returns unsubscribe callback. */
+    subscribe(listener: OtpStateListener): () => void;
+    /** Dispose internal timers. */
+    dispose(): void;
+}
+/**
+ * Create an OtpMachine.
+ */
+export declare function createOtpMachine(options: OtpMachineOptions): OtpMachine;

package/dist/otp.js

@@ -0,0 +1,295 @@
+/**
+ * Browser-side checkout WhatsApp OTP state machine.
+ *
+ * Deep module: concentrates send/verify flows, cooldown countdowns,
+ * attempt counting, terminal expiry handling, fail-open bypass management,
+ * and state notifications behind a simple, predictable interface.
+ *
+ * Can run in pure memory (tests / node) or drive browser UI via subscription.
+ */
+import { toLocalAlgerianMobile } from "./phone.js";
+export function createOtpTransport(options) {
+    return { send: options.send, verify: options.verify };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isDomainError(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.category === "string" &&
+        typeof value.code === "string" &&
+        typeof value.message === "string" &&
+        typeof value.retryable === "boolean" &&
+        typeof value.operation === "string" &&
+        typeof value.sideEffect === "string");
+}
+function fallbackDomainError(operation, code, message) {
+    return {
+        category: "unknown",
+        code,
+        message,
+        retryable: false,
+        operation,
+        sideEffect: "unknown",
+    };
+}
+function mapFailure(body, options, fallbackCode) {
+    const error = typeof body.error === "string" ? body.error : options.fallbackError;
+    const domainError = isDomainError(body.domainError)
+        ? body.domainError
+        : fallbackDomainError(options.operation, typeof body.code === "string" ? body.code : fallbackCode, error);
+    return {
+        success: false,
+        error,
+        ...(typeof body.code === "string" ? { code: body.code } : {}),
+        ...(typeof body.windowSeconds === "number" ? { windowSeconds: body.windowSeconds } : {}),
+        ...(typeof body.attemptsRemaining === "number"
+            ? { attemptsRemaining: body.attemptsRemaining }
+            : {}),
+        ...(typeof body.terminal === "boolean" ? { terminal: body.terminal } : {}),
+        domainError,
+    };
+}
+export function otpTransportFailure(error, operation, fallbackError) {
+    const message = error instanceof Error ? error.message : fallbackError;
+    return {
+        success: false,
+        error: message,
+        domainError: fallbackDomainError(operation, "NETWORK_ERROR", message),
+    };
+}
+export async function mapOtpResponse(response, options) {
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        return {
+            success: false,
+            error: options.fallbackError,
+            domainError: fallbackDomainError(options.operation, "MALFORMED_RESPONSE", options.fallbackError),
+        };
+    }
+    if (!isRecord(body)) {
+        return mapFailure({}, options, "MALFORMED_RESPONSE");
+    }
+    if (!response.ok) {
+        return mapFailure(body, options, `HTTP_${response.status}`);
+    }
+    const parsed = options.schema.safeParse(body.data);
+    if (!parsed.success) {
+        return mapFailure(body, options, "SCHEMA_VALIDATION_FAILED");
+    }
+    return { success: true, data: parsed.data };
+}
+/**
+ * Create an OtpMachine.
+ */
+export function createOtpMachine(options) {
+    const { transport, timerIntervalMs = 1000 } = options;
+    const listeners = new Set();
+    if (options.onStateChange)
+        listeners.add(options.onStateChange);
+    let state = {
+        status: "idle",
+        phone: options.initialPhone ?? "",
+        normalizedPhone: options.initialPhone ? toLocalAlgerianMobile(options.initialPhone) : null,
+        requestId: null,
+        otpToken: null,
+        bypassToken: null,
+        error: null,
+        errorCode: null,
+        cooldownRemaining: 0,
+        attemptsRemaining: null,
+        isTerminal: false,
+    };
+    let timer = null;
+    function updateState(next) {
+        state = { ...state, ...next };
+        for (const listener of listeners) {
+            try {
+                listener(state);
+            }
+            catch { }
+        }
+    }
+    function startCooldown(seconds) {
+        if (timer)
+            clearInterval(timer);
+        let remaining = seconds;
+        updateState({ cooldownRemaining: remaining });
+        timer = setInterval(() => {
+            remaining -= 1;
+            if (remaining <= 0) {
+                if (timer)
+                    clearInterval(timer);
+                timer = null;
+                updateState({ cooldownRemaining: 0 });
+            }
+            else {
+                updateState({ cooldownRemaining: remaining });
+            }
+        }, timerIntervalMs);
+    }
+    function stopCooldown() {
+        if (timer) {
+            clearInterval(timer);
+            timer = null;
+        }
+        updateState({ cooldownRemaining: 0 });
+    }
+    return {
+        getState() {
+            return state;
+        },
+        setPhone(rawPhone) {
+            const normalized = toLocalAlgerianMobile(rawPhone);
+            if (state.phone === rawPhone && state.normalizedPhone === normalized)
+                return;
+            stopCooldown();
+            updateState({
+                status: "idle",
+                phone: rawPhone,
+                normalizedPhone: normalized,
+                requestId: null,
+                otpToken: null,
+                bypassToken: null,
+                error: null,
+                errorCode: null,
+                attemptsRemaining: null,
+                isTerminal: false,
+            });
+        },
+        async send() {
+            if (state.cooldownRemaining > 0 || state.status === "sending" || state.status === "verifying") {
+                return false;
+            }
+            const phoneToSend = state.normalizedPhone ?? state.phone.trim();
+            if (!phoneToSend) {
+                updateState({ status: "error", error: "Phone number is required" });
+                return false;
+            }
+            updateState({ status: "sending", error: null, errorCode: null });
+            try {
+                const res = await transport.send(phoneToSend);
+                if (!res.success) {
+                    const cooldown = res.windowSeconds ?? 60;
+                    startCooldown(cooldown);
+                    updateState({
+                        status: "error",
+                        error: res.error,
+                        errorCode: res.domainError.code,
+                    });
+                    return false;
+                }
+                if (res.data.status === "unavailable") {
+                    stopCooldown();
+                    updateState({
+                        status: "bypassed",
+                        bypassToken: res.data.bypassToken,
+                        error: null,
+                        errorCode: null,
+                    });
+                    return true;
+                }
+                startCooldown(60);
+                updateState({
+                    status: "code_sent",
+                    requestId: res.data.requestId,
+                    error: null,
+                    errorCode: null,
+                    attemptsRemaining: null,
+                    isTerminal: false,
+                });
+                return true;
+            }
+            catch (err) {
+                updateState({
+                    status: "error",
+                    error: err instanceof Error ? err.message : "Failed to send verification code",
+                    errorCode: "NETWORK_ERROR",
+                });
+                return false;
+            }
+        },
+        async verify(code) {
+            const cleanCode = code.replace(/\D/g, "");
+            if (cleanCode.length !== 6) {
+                updateState({
+                    error: "Verification code must be 6 digits",
+                    errorCode: "INVALID_FORMAT",
+                });
+                return false;
+            }
+            if (!state.requestId) {
+                updateState({
+                    status: "error",
+                    error: "No active verification request. Please request a new code.",
+                    errorCode: "NO_REQUEST",
+                });
+                return false;
+            }
+            if (state.status === "verifying")
+                return false;
+            const phoneToVerify = state.normalizedPhone ?? state.phone.trim();
+            updateState({ status: "verifying", error: null, errorCode: null });
+            try {
+                const res = await transport.verify(phoneToVerify, state.requestId, cleanCode);
+                if (!res.success) {
+                    const isTerminal = res.terminal === true;
+                    updateState({
+                        status: isTerminal ? "error" : "code_sent",
+                        error: res.error,
+                        errorCode: res.domainError.code,
+                        attemptsRemaining: res.attemptsRemaining ?? null,
+                        isTerminal,
+                        requestId: isTerminal ? null : state.requestId,
+                    });
+                    return false;
+                }
+                stopCooldown();
+                updateState({
+                    status: "verified",
+                    otpToken: res.data.otpToken,
+                    error: null,
+                    errorCode: null,
+                    attemptsRemaining: null,
+                    isTerminal: false,
+                });
+                return true;
+            }
+            catch (err) {
+                updateState({
+                    status: "code_sent",
+                    error: err instanceof Error ? err.message : "Verification failed",
+                    errorCode: "NETWORK_ERROR",
+                });
+                return false;
+            }
+        },
+        reset() {
+            stopCooldown();
+            updateState({
+                status: "idle",
+                requestId: null,
+                otpToken: null,
+                bypassToken: null,
+                error: null,
+                errorCode: null,
+                attemptsRemaining: null,
+                isTerminal: false,
+            });
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        dispose() {
+            stopCooldown();
+            listeners.clear();
+        },
+    };
+}

package/dist/phone.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeAlgerianPhone(raw: string): string | null;
+export declare function toLocalAlgerianMobile(raw: string): string | null;

package/dist/phone.js

@@ -0,0 +1,34 @@
+const ALGERIAN_COUNTRY_CODE = "213";
+const ALGERIAN_MOBILE_PREFIX = /^[567]/;
+function clean(raw) {
+    return raw.replace(/[\s\-().]/g, "");
+}
+export function normalizeAlgerianPhone(raw) {
+    if (typeof raw !== "string")
+        return null;
+    let phone = clean(raw.trim());
+    if (phone.length < 6 || phone.length > 20)
+        return null;
+    if (phone.startsWith("00")) {
+        phone = `+${phone.slice(2)}`;
+    }
+    if (phone.startsWith("+")) {
+        return /^\+\d{7,15}$/.test(phone) ? phone : null;
+    }
+    if (phone.startsWith(ALGERIAN_COUNTRY_CODE)) {
+        const rest = phone.slice(ALGERIAN_COUNTRY_CODE.length);
+        return ALGERIAN_MOBILE_PREFIX.test(rest) ? `+${phone}` : null;
+    }
+    const local = phone.startsWith("0") ? phone.slice(1) : phone;
+    if (local.length === 9 && ALGERIAN_MOBILE_PREFIX.test(local)) {
+        return `+${ALGERIAN_COUNTRY_CODE}${local}`;
+    }
+    return null;
+}
+export function toLocalAlgerianMobile(raw) {
+    const e164 = normalizeAlgerianPhone(raw);
+    if (!e164 || !e164.startsWith("+213"))
+        return null;
+    const local = e164.slice(4);
+    return /^[567]\d{8}$/.test(local) ? `0${local}` : null;
+}

package/dist/product-view.d.ts

@@ -0,0 +1,12 @@
+import type { ProductDetail, ProductList, ProductVariant } from "./types.js";
+export interface ProductView {
+    readonly defaultVariant: ProductVariant | null;
+    readonly basePrice: number;
+    readonly comparePrice: number | null;
+    readonly hasDiscount: boolean;
+    readonly discountPct: number;
+    readonly isOutOfStock: boolean;
+    readonly isLowStock: boolean;
+}
+export declare function getProductView(product: ProductDetail): ProductView;
+export declare function getProductListView(product: ProductList): ProductView;

package/dist/product-view.js

@@ -0,0 +1,42 @@
+function discountOf(basePrice, comparePrice) {
+    if (comparePrice == null || comparePrice <= basePrice) {
+        return { hasDiscount: false, discountPct: 0 };
+    }
+    return {
+        hasDiscount: true,
+        discountPct: Math.round((1 - basePrice / comparePrice) * 100),
+    };
+}
+function stockOf(product) {
+    if (!product.trackInventory) {
+        return { isOutOfStock: false, isLowStock: false };
+    }
+    return {
+        isOutOfStock: product.inventory === 0,
+        isLowStock: product.inventory > 0 && product.inventory <= product.lowStockThreshold,
+    };
+}
+export function getProductView(product) {
+    const defaultVariant = product.hasVariants
+        ? (product.variants.find((variant) => variant.isDefault) ?? product.variants[0] ?? null)
+        : null;
+    const basePrice = defaultVariant?.price ?? product.price;
+    const comparePrice = defaultVariant?.compareAtPrice ?? product.compareAtPrice ?? null;
+    return {
+        defaultVariant,
+        basePrice,
+        comparePrice,
+        ...discountOf(basePrice, comparePrice),
+        ...stockOf(product),
+    };
+}
+export function getProductListView(product) {
+    const comparePrice = product.compareAtPrice ?? null;
+    return {
+        defaultVariant: null,
+        basePrice: product.price,
+        comparePrice,
+        ...discountOf(product.price, comparePrice),
+        ...stockOf(product),
+    };
+}