@wocart/storefront 1.0.0 → 1.2.0

package/dist/endpoints/storefront-routes.js

@@ -0,0 +1,133 @@
+/**
+ * The storefront's same-origin API routes, ready to export.
+ *
+ * Every theme needs the same eight routes between the shopper's browser and
+ * the platform: OTP send and verify, cart validation, abandoned-checkout
+ * tracking and its conversion, communes, and reviews (list and submit). What
+ * each one must get right is decided here once — the cross-origin check on
+ * every POST, the shopper's address forwarded wherever the server counts or
+ * attributes per shopper, the input bounds, and the response shape the
+ * browser reads — so a theme's route file is one line:
+ *
+ * ```ts
+ * // src/pages/api/otp/send.ts
+ * import { routes } from "@/theme/api-routes";
+ * export const POST = routes.otpSend;
+ * ```
+ *
+ * The theme decides only which client serves the request — its own,
+ * per-request client, so the language and the request lifetime are the
+ * page's. A failure answers with the status the server's category implies
+ * (see `createProxyEndpoint`), and the server's diagnostic fields ride along.
+ */
+import { z } from "zod";
+import { AbandonedCheckoutInputSchema, BasketLineInputSchema, MAX_BASKET_LINES, WilayaIdSchema, } from "../domain.js";
+import { createProxyEndpoint, } from "./proxy.js";
+export const REVIEWS_PAGE_DEFAULT = 20;
+export const REVIEWS_PAGE_MAX = 50;
+const otpSendInput = z.object({ phone: z.string().min(1).max(32) });
+const otpVerifyInput = z.object({
+    phone: z.string().min(1).max(32),
+    requestId: z.string().min(1).max(200),
+    code: z.string().min(1).max(16),
+});
+const cartValidateInput = z.object({
+    items: z.array(BasketLineInputSchema).min(1).max(MAX_BASKET_LINES),
+});
+const abandonedConvertInput = z.object({
+    sessionId: z.string().uuid(),
+    orderId: z.string().min(1).max(200),
+    orderNumber: z.string().min(1).max(100),
+});
+const communesInput = z.object({ wilayaId: WilayaIdSchema });
+const reviewsListInput = z.object({
+    productId: z.string().min(1).max(200),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .catch(REVIEWS_PAGE_DEFAULT)
+        .transform((n) => Math.min(n, REVIEWS_PAGE_MAX)),
+    offset: z.coerce.number().int().min(0).catch(0),
+});
+/**
+ * The shape of a review, bounded so the body stays small. The rules — the
+ * order-number format, the rating range, the body's length — are the
+ * server's, and its refusal carries the code the form answers by.
+ */
+const reviewSubmitInput = z.object({
+    orderNumber: z.string().min(1).max(64),
+    productId: z.string().min(1).max(200),
+    rating: z.number(),
+    title: z.string().max(500).optional(),
+    body: z.string().max(5000),
+});
+export function createStorefrontRoutes(options) {
+    const route = (config) => async (context) => {
+        const { call, ...endpoint } = config;
+        return createProxyEndpoint({
+            ...endpoint,
+            client: (input, headers) => call(options.client(context), input, headers),
+        })(context);
+    };
+    return {
+        otpSend: route({
+            method: "POST",
+            inputSchema: otpSendInput,
+            forwardAttribution: true,
+            call: (client, { phone }, headers) => client.orders.otp.send(phone, headers),
+        }),
+        otpVerify: route({
+            method: "POST",
+            inputSchema: otpVerifyInput,
+            forwardAttribution: true,
+            call: (client, { phone, requestId, code }, headers) => client.orders.otp.verify(phone, requestId, code, headers),
+        }),
+        cartValidate: route({
+            method: "POST",
+            inputSchema: cartValidateInput,
+            successBody: (data) => ({ success: true, data }),
+            call: (client, { items }) => client.cart.validate(items),
+        }),
+        abandonedUpsert: route({
+            method: "POST",
+            inputSchema: AbandonedCheckoutInputSchema,
+            forwardAttribution: true,
+            noContent: true,
+            call: (client, input, headers) => client.orders.abandoned.upsert(input, headers),
+        }),
+        abandonedConvert: route({
+            method: "POST",
+            inputSchema: abandonedConvertInput,
+            noContent: true,
+            call: (client, { sessionId, orderId, orderNumber }) => client.orders.abandoned.convert(sessionId, orderId, orderNumber),
+        }),
+        communes: route({
+            method: "GET",
+            pathParams: { wilayaId: "number" },
+            inputSchema: communesInput,
+            call: async (client, { wilayaId }) => ({
+                success: true,
+                data: await client.geo.communes(wilayaId),
+            }),
+        }),
+        reviewsList: route({
+            method: "GET",
+            pathParams: { productId: "string" },
+            queryParams: ["limit", "offset"],
+            inputSchema: reviewsListInput,
+            successBody: ({ rows, total }) => ({ data: rows, total }),
+            call: async (client, { productId, limit, offset }) => ({
+                success: true,
+                data: await client.products.reviews.list(productId, { limit, offset }),
+            }),
+        }),
+        reviewSubmit: route({
+            method: "POST",
+            inputSchema: reviewSubmitInput,
+            successStatus: 201,
+            successBody: (data) => ({ success: true, data }),
+            call: (client, { title, ...review }) => client.products.reviews.submit(title === undefined ? review : { ...review, title }),
+        }),
+    };
+}

package/dist/middleware.d.ts

@@ -1,21 +1,20 @@
 /**
- * Middleware engine — the POST/Redirect/GET pattern for Astro Actions,
- * framework-free.
+ * Middleware engine for Astro Actions called from an HTML form, 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:
+ * `astro:middleware` and `astro:actions` are virtual modules that only exist
+ * inside an Astro project, so this file runs the action and each theme's
+ * middleware wires it:
  *
  * ```ts
  * // src/middleware.ts
  * import { defineMiddleware } from "astro:middleware";
  * import { getActionContext } from "astro:actions";
- * import { resolveActionRedirectDecision } from "@wocart/storefront/astro";
+ * import { runFormAction } from "@wocart/storefront/astro";
  *
  * export const onRequest = defineMiddleware(async (context, next) => {
  *   const { action, setActionResult, serializeActionResult } =
  *     getActionContext(context);
- *   const decision = await resolveActionRedirectDecision({
+ *   await runFormAction({
  *     action: action && {
  *       calledFrom: action.calledFrom,
  *       name: action.name,
@@ -23,29 +22,21 @@
  *     },
  *     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.
+ * The page then renders from the same POST and reads the result with
+ * `getActionResult()`:
+ * - on SUCCESS it issues `Astro.redirect('/thank-you?…')`, which the browser
+ *   follows;
+ * - on ERROR it renders the form again with the error in place.
  *
- * 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.
+ * Neither path may redirect from the middleware. Astro 7 holds an action
+ * result for the response being rendered only — a redirect arrives at the next
+ * page with no result, the thank-you redirect never fires and a refused order
+ * shows no message.
  */
 /**
  * The slice of an action result the decision reads: whether it errored.
@@ -73,28 +64,31 @@ export interface ActionMiddlewareDeps<TResult extends ActionHandlerResult = Acti
     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. */
+    /** @deprecated Unused since 1.2.0: nothing redirects. */
     referer?: string | null;
-    /** Path of the page the form posted to — the fallback redirect target. */
-    pathname: string;
+    /** @deprecated Unused since 1.2.0: nothing redirects. */
+    pathname?: string;
 }
 export type PrgDecision = 
-/** Redirect back to the form page (error path) — 303 See Other. */
+/** Never produced since 1.2.0 — kept so existing `decision.kind` checks compile. */
 {
     kind: "redirect";
     location: string;
     status: 303;
 }
-/** Render the page from this POST (success / not an action / JSON action). */
+/** Render the page from this POST. */
  | {
     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.
+ * Run an action called from an HTML form and store its result for the page
+ * this POST renders. Resolves to that result, or `undefined` when the request
+ * is not a form-called action (a JSON call or a plain request is Astro's).
+ */
+export declare function runFormAction<TResult extends ActionHandlerResult, TSerialized>(deps: Pick<ActionMiddlewareDeps<TResult, TSerialized>, "action" | "setActionResult" | "serializeActionResult">): Promise<TResult | undefined>;
+/**
+ * @deprecated Use `runFormAction` and call `next()`. Runs the action the same
+ * way and always answers `{ kind: "next" }`: an errored post renders in place,
+ * because a redirect drops the result (see the note at the top of this file).
  */
 export declare function resolveActionRedirectDecision<TResult extends ActionHandlerResult, TSerialized>(deps: ActionMiddlewareDeps<TResult, TSerialized>): Promise<PrgDecision>;

package/dist/middleware.js

@@ -1,21 +1,20 @@
 /**
- * Middleware engine — the POST/Redirect/GET pattern for Astro Actions,
- * framework-free.
+ * Middleware engine for Astro Actions called from an HTML form, 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:
+ * `astro:middleware` and `astro:actions` are virtual modules that only exist
+ * inside an Astro project, so this file runs the action and each theme's
+ * middleware wires it:
  *
  * ```ts
  * // src/middleware.ts
  * import { defineMiddleware } from "astro:middleware";
  * import { getActionContext } from "astro:actions";
- * import { resolveActionRedirectDecision } from "@wocart/storefront/astro";
+ * import { runFormAction } from "@wocart/storefront/astro";
  *
  * export const onRequest = defineMiddleware(async (context, next) => {
  *   const { action, setActionResult, serializeActionResult } =
  *     getActionContext(context);
- *   const decision = await resolveActionRedirectDecision({
+ *   await runFormAction({
  *     action: action && {
  *       calledFrom: action.calledFrom,
  *       name: action.name,
@@ -23,50 +22,41 @@
  *     },
  *     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.
+ * The page then renders from the same POST and reads the result with
+ * `getActionResult()`:
+ * - on SUCCESS it issues `Astro.redirect('/thank-you?…')`, which the browser
+ *   follows;
+ * - on ERROR it renders the form again with the error in place.
  *
- * 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.
+ * Neither path may redirect from the middleware. Astro 7 holds an action
+ * result for the response being rendered only — a redirect arrives at the next
+ * page with no result, the thank-you redirect never fires and a refused order
+ * shows no message.
  */
 /**
- * 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.
+ * Run an action called from an HTML form and store its result for the page
+ * this POST renders. Resolves to that result, or `undefined` when the request
+ * is not a form-called action (a JSON call or a plain request is Astro's).
+ */
+export async function runFormAction(deps) {
+    const { action, setActionResult, serializeActionResult } = deps;
+    if (action?.calledFrom !== "form")
+        return undefined;
+    const result = await action.handler();
+    setActionResult(action.name, serializeActionResult(result));
+    return result;
+}
+/**
+ * @deprecated Use `runFormAction` and call `next()`. Runs the action the same
+ * way and always answers `{ kind: "next" }`: an errored post renders in place,
+ * because a redirect drops the result (see the note at the top of this file).
  */
 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.
-    }
+    await runFormAction(deps);
     return { kind: "next" };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/storefront",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",