@wocart/storefront 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,57 @@ follows [semantic versioning](https://semver.org/): breaking changes ship only
 in a new major version, and an export is marked `@deprecated` for at least one
 minor release before a major removes it.
 
+## 1.2.0 — 2026-10-15
+
+### Added
+
+- **`createStorefrontRoutes`** (`@wocart/storefront/astro`): the eight
+  same-origin API routes every storefront needs — OTP send and verify, cart
+  validation, abandoned-checkout tracking and conversion, communes, and
+  reviews (list and submit) — ready to export, so a theme's route file is one
+  line. Every POST refuses cross-origin requests, the OTP and abandoned
+  routes forward the shopper's address, and input is bounded before it is
+  sent. The theme passes only the request's own client.
+- **`runFormAction`** (`@wocart/storefront/astro`) runs an action posted from
+  a form and stores its result for the page that POST renders.
+- `orders.otp.send` and `orders.otp.verify` take the shopper's forwarded
+  headers as a last argument. The server limits sends and attempts per
+  shopper; without them every shopper of a store shared the theme worker's
+  one limit.
+
+### Changed
+
+- **A proxy route's failure status follows the server's category** when
+  `errorStatus` is unset: 400 for validation, 422 for a business refusal, 429
+  when the server named a wait, 504 for a timeout, and 502 for anything the
+  shopper cannot fix (and for a failure that carries no `domainError`, as
+  before). An explicit `errorStatus` still wins.
+- A client function that throws answers 502 with
+  `code: "PROXY_UPSTREAM_FAILED"` and a generic message; the exception's own
+  text no longer reaches the browser.
+- `placeOrderInput` refusals name their field without a sentence. The Arabic
+  messages it carried reached French and English stores as-is; the theme
+  answers each field with its own copy.
+- `placeOrderInput` and `executePlaceOrder` accept a `pricePerUnit` of 0. The
+  price is display-only, and a product the merchant prices at 0 was not
+  orderable from its product page.
+
+### Deprecated
+
+- `resolveActionRedirectDecision`: use `runFormAction` and call `next()`. It
+  now always answers `{ kind: "next" }`. Its 303 back to the form on an
+  error lost the result in Astro 7 — the shopper returned to the form with no
+  message — so an errored post now renders in place. Its `referer` and
+  `pathname` inputs are unused.
+
+### Fixed
+
+- A server error's `context` can no longer overwrite the result's own
+  `success`, `error`, `code` or `domainError` fields.
+- A `*_NOT_FOUND` answer from `products.get`, `pages.get`, `pages.landing`,
+  `pageData.get` or `orders.tracking` is absence, not a failure: it no longer
+  reaches `onError` as a degraded read.
+
 ## 1.1.0 — 2026-10-14
 
 ### Fixed

package/README.md

@@ -69,7 +69,7 @@ if (result.success) {
 | --- | --- | --- |
 | `@wocart/storefront` | browser and server | read-model types and schemas, reference data (58 wilayas, 1,551 communes), money and image helpers, the basket and OTP state machines, language routing, Meta pixel payloads |
 | `@wocart/storefront/server` | server only | `createStoreClient`, `StoreClient`, `ClientResult`, `StorefrontError` — the API key lives here |
-| `@wocart/storefront/astro` | server only | `createProxyEndpoint`, `placeOrderInput`, `executePlaceOrder`, `collectForwardedHeaders`, `resolveActionRedirectDecision` |
+| `@wocart/storefront/astro` | server only | `createStorefrontRoutes`, `createProxyEndpoint`, `placeOrderInput`, `executePlaceOrder`, `collectForwardedHeaders`, `runFormAction` |
 
 Browser code never receives the key. It calls your own same-origin routes
 (for example `src/pages/api/cart.ts`), which call the SDK on the server:

package/USAGE.md

@@ -915,6 +915,12 @@ verify returns a verified status with otpToken on success. Failure context can
 include attemptsRemaining and a terminal state. Use it for the countdown,
 retry, and lockout UI.
 
+The server limits sends and attempts per shopper. Both calls take the
+shopper's forwarded headers as their last argument
+(`send(phone, collectForwardedHeaders(request))`); without them every shopper
+of the store shares the one limit of the theme's worker. The `otpSend` and
+`otpVerify` routes of `createStorefrontRoutes` pass them for you.
+
 ### Using the SDK's OtpMachine
 
 The SDK exports `createOtpMachine` to manage the complete interactive WhatsApp
@@ -1017,6 +1023,8 @@ wrapper while the SDK owns reusable validation and execution logic.
 placeOrderInput is the shared form schema. It:
 
 - whitelists supported fields and strips unknown fields;
+- names the failing field on a refusal, with no shopper-facing sentence — the
+  theme answers each field with its own copy in the store's language;
 - coerces form number strings;
 - turns empty optional values into undefined;
 - canonicalizes phone input;
@@ -1046,7 +1054,7 @@ export const server = {
 
       if (!result.success) {
         throw new ActionError({
-          code: "BAD_REQUEST",
+          code: result.errorKind === "shape" ? "BAD_REQUEST" : "UNPROCESSABLE_CONTENT",
           message: result.error,
         });
       }
@@ -1076,71 +1084,113 @@ order request:
 Use it when the server route is the trusted boundary that forwards the order.
 Do not let arbitrary browser code choose identity headers.
 
-### Redirect behavior
+### Running the action from middleware
 
-The middleware helper resolveActionRedirectDecision handles the form POST
-flow:
+runFormAction runs an action posted from an HTML form and stores its result
+for the page that POST renders:
 
-- form actions execute and serialize their result;
-- form errors redirect to the referer, or the current pathname, with status
-  303;
-- successful form actions return next so the result cookie survives;
-- non-form and JSON requests continue without a redirect.
+~~~ts
+// src/middleware.ts
+import { defineMiddleware } from "astro:middleware";
+import { getActionContext } from "astro:actions";
+import { runFormAction } from "@wocart/storefront/astro";
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  const { action, setActionResult, serializeActionResult } = getActionContext(context);
+  await runFormAction({
+    action: action && {
+      calledFrom: action.calledFrom,
+      name: action.name,
+      handler: action.handler,
+    },
+    setActionResult,
+    serializeActionResult,
+  });
+  return next();
+});
+~~~
 
-The common mistake is redirecting successful actions too early. Let success
-continue through next, then redirect from the successful page/action flow to
-the thank-you experience.
+The page reads the result with `Astro.getActionResult()`: on success it
+redirects to the thank-you page, and on a refusal it renders the form again
+with the error in place.
+
+Never redirect from the middleware, on success or on error. Astro 7 keeps an
+action result for the response being rendered only, so a redirect arrives at
+the next page with no result: the thank-you redirect never fires, and a
+refused order shows no message. resolveActionRedirectDecision, the earlier
+name, is deprecated and now always answers next.
 
 ## Browser-facing proxy routes
 
-Browser code should call a same-origin theme route. That route uses
-createProxyEndpoint to call the SDK with the server-only API key.
+Browser code calls same-origin theme routes, which call the platform with the
+server-only API key. The key never reaches the browser.
 
-This keeps the key out of the browser and centralizes CSRF checks, input
-validation, parameter parsing, attribution forwarding, and error shape.
+### The storefront routes, ready to export
 
-### Cart validation route
+createStorefrontRoutes returns the eight routes every storefront needs. Bind
+them once to the request's own client:
 
 ~~~ts
-import { z } from "zod";
-import { createProxyEndpoint } from "@wocart/storefront/astro";
-
-import { BasketLineInputSchema, MAX_BASKET_LINES } from "@wocart/storefront";
+// src/theme/api-routes.ts
+import type { APIContext } from "astro";
+import { createStorefrontRoutes } from "@wocart/storefront/astro";
 
-const cartInputSchema = z.object({
-  items: z.array(BasketLineInputSchema).min(1).max(MAX_BASKET_LINES),
-});
-
-export const POST = createProxyEndpoint({
-  method: "POST",
-  client: (input) => store.cart.validate(input.items),
-  inputSchema: cartInputSchema,
-  successBody: (data) => ({ success: true, data }),
+export const routes = createStorefrontRoutes<APIContext>({
+  client: (context) => context.locals.store.client,
 });
 ~~~
 
-The browser can now call the theme's own route. It never calls the server
-directly and never needs the API key.
-
-### Order route with attribution
+Each route file then exports one of them:
 
 ~~~ts
-export const POST = createProxyEndpoint({
-  method: "POST",
-  client: (input, headers) => store.orders.create(input, headers),
-  forwardAttribution: true,
-  successStatus: 201,
-  errorStatus: 422,
-});
+// src/pages/api/otp/send.ts
+import { routes } from "@/theme/api-routes";
+export const POST = routes.otpSend;
 ~~~
 
-### GET route with a numeric path parameter
+| Route | Method | Browser sends | Answers |
+| --- | --- | --- | --- |
+| `otpSend` | POST | `{ phone }` | `{ data: OtpSendResult }` |
+| `otpVerify` | POST | `{ phone, requestId, code }` | `{ data: OtpVerifyResult }` |
+| `cartValidate` | POST | `{ items }` | `{ success: true, data: CartValidation }` |
+| `abandonedUpsert` | POST | `AbandonedCheckoutInput` | 204 |
+| `abandonedConvert` | POST | `{ sessionId, orderId, orderNumber }` | 204 |
+| `communes` | GET | path param `wilayaId` | `{ data: Commune[] }` |
+| `reviewsList` | GET | path param `productId`, query `limit` (1–50, default 20) and `offset` | `{ data: Review[], total }` |
+| `reviewSubmit` | POST | `ReviewInput` | 201 `{ success: true, data: { id } }` |
+
+What every route gets right:
+
+- every POST refuses a cross-origin request with 403;
+- the OTP routes and abandoned tracking forward the shopper's address and
+  user agent, so the server limits and attributes per shopper;
+- input is bounded before it is sent, and a malformed body is a 400 that never
+  reaches the server;
+- a refusal answers with the status the server's category implies — 400 for
+  validation, 422 for a business refusal, 429 when the server named a wait —
+  and carries the server's `code` and context (`windowSeconds`,
+  `attemptsRemaining`, `terminal`), which is what the browser branches on;
+- a failure the shopper cannot fix (a wrong store key, a server fault, a
+  dropped connection) is a 502, and a timeout a 504.
+
+The client resolver runs once per request. Return the request's own client,
+never one kept across requests.
+
+### A custom route
+
+createProxyEndpoint is the factory behind those routes, for a route of the
+theme's own. Its client function returns a result (`{ success, data }` or a
+failure), so wrap a read that returns a plain value:
 
 ~~~ts
+import { z } from "zod";
+import { createProxyEndpoint } from "@wocart/storefront/astro";
+
 export const GET = createProxyEndpoint({
   method: "GET",
-  client: (input) => store.geo.communes(input.wilayaId),
-  pathParams: { wilayaId: "number" },
+  pathParams: { slug: "string" },
+  inputSchema: z.object({ slug: z.string().min(1).max(200) }),
+  client: async ({ slug }) => ({ success: true, data: await store.products.get(slug) }),
 });
 ~~~
 
@@ -1153,12 +1203,18 @@ Proxy configuration supports:
 - numeric or string path parameter parsing;
 - CSRF protection, enabled by default for POST and disabled by default for GET;
 - attribution forwarding;
-- custom success and error status codes;
-- custom successBody;
-- noContent responses.
+- a custom success status, successBody and noContent;
+- errorStatus, which overrides the status derived from the failure. Leave it
+  unset unless the browser contract needs one fixed status.
+
+A thrown client function answers 502 with `code: "PROXY_UPSTREAM_FAILED"`
+and a generic message: an exception's own text never reaches the browser.
+
+Orders do not go through a proxy route: they go through the placeOrder action
+(see above), which validates the form and forwards attribution itself.
 
-Use same-origin proxy routes for browser operations. Do not solve a proxy
-problem by moving the API key into public environment variables.
+Do not solve a proxy problem by moving the API key into public environment
+variables.
 
 ## Money, images, and presentation utilities
 

package/dist/actions.d.ts

@@ -17,10 +17,11 @@
  *     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);
+ *         // A refusal renders on the form, in place (see middleware.ts).
+ *         throw new ActionError({
+ *           code: result.errorKind === "shape" ? "BAD_REQUEST" : "UNPROCESSABLE_CONTENT",
+ *           message: result.error,
+ *         });
  *       }
  *       return result.data;
  *     },

package/dist/actions.js

@@ -17,10 +17,11 @@
  *     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);
+ *         // A refusal renders on the form, in place (see middleware.ts).
+ *         throw new ActionError({
+ *           code: result.errorKind === "shape" ? "BAD_REQUEST" : "UNPROCESSABLE_CONTENT",
+ *           message: result.error,
+ *         });
  *       }
  *       return result.data;
  *     },
@@ -92,7 +93,9 @@ export const placeOrderInput = z.object({
     // 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()),
+    // Display-only — the server prices every order from the catalog — so a
+    // product the merchant prices at 0 is as orderable as any other.
+    pricePerUnit: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.coerce.number().nonnegative().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()),
@@ -101,10 +104,12 @@ export const placeOrderInput = 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}$/, "رقم الهاتف غير صحيح")),
+    // No custom messages: a failure names its field, and the theme answers it
+    // with its own copy in the store's language.
+    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, "يرجى اختيار البلدية"),
+    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(),
@@ -176,7 +181,7 @@ export function collectForwardedHeaders(request) {
 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)) {
+        (!input.productId || !input.productName || input.pricePerUnit === undefined)) {
         return {
             success: false,
             error: "An order needs either a basket or a product.",

package/dist/astro.d.ts

@@ -1,6 +1,8 @@
 export { createProxyEndpoint } from "./endpoints/proxy.js";
 export type { ProxyClientFn, ProxyEndpointConfig, AstroAPIContext, AstroAPIRoute, } from "./endpoints/proxy.js";
+export { createStorefrontRoutes, REVIEWS_PAGE_DEFAULT, REVIEWS_PAGE_MAX, } from "./endpoints/storefront-routes.js";
+export type { StorefrontApiRoute, StorefrontRoutes, StorefrontRoutesOptions, } from "./endpoints/storefront-routes.js";
 export { placeOrderInput, executePlaceOrder, collectForwardedHeaders, } from "./actions.js";
 export type { PlaceOrderInput, PlaceOrderResult } from "./actions.js";
-export { resolveActionRedirectDecision } from "./middleware.js";
+export { runFormAction, resolveActionRedirectDecision } from "./middleware.js";
 export type { PrgDecision, ActionMiddlewareDeps, ActionDescriptor } from "./middleware.js";

package/dist/astro.js

@@ -1,3 +1,4 @@
 export { createProxyEndpoint } from "./endpoints/proxy.js";
+export { createStorefrontRoutes, REVIEWS_PAGE_DEFAULT, REVIEWS_PAGE_MAX, } from "./endpoints/storefront-routes.js";
 export { placeOrderInput, executePlaceOrder, collectForwardedHeaders, } from "./actions.js";
-export { resolveActionRedirectDecision } from "./middleware.js";
+export { runFormAction, resolveActionRedirectDecision } from "./middleware.js";

package/dist/client/core.d.ts

@@ -70,6 +70,14 @@ export declare const DEFAULT_READ_TIMEOUT_MS = 10000;
  * @returns Core infrastructure for namespace implementations
  */
 export declare function createClientCore(config: ClientConfig): ClientCore;
+/**
+ * The server's own answer that a looked-up record does not exist
+ * (`PRODUCT_NOT_FOUND`, `STORE_PAGE_NOT_FOUND`, …). A lookup returns `null` for
+ * it without reporting a failure: a stale link is not an outage. A 404 that
+ * does not carry the server's code — a wrong `serverUrl`, a route the platform
+ * does not have — is not absence, and is still reported.
+ */
+export declare function isNotFoundAnswer(error: unknown): boolean;
 /**
  * Report a read that a namespace swallowed.
  *

package/dist/client/core.js

@@ -430,11 +430,11 @@ export function createClientCore(config) {
             if (!response.ok) {
                 const failure = serverFailure(response.status, read.ok ? read.value : undefined, operation, false);
                 return {
+                    ...failure.flatContext,
                     success: false,
                     error: failure.message,
                     ...(failure.code !== undefined ? { code: failure.code } : {}),
                     domainError: failure.domainError,
-                    ...failure.flatContext,
                 };
             }
             if (!read.ok || !isRecord(read.value)) {
@@ -488,11 +488,11 @@ export function createClientCore(config) {
             if (!response.ok) {
                 const failure = serverFailure(response.status, read.ok ? read.value : undefined, operation, false);
                 return {
+                    ...failure.flatContext,
                     success: false,
                     error: failure.message,
                     ...(failure.code !== undefined ? { code: failure.code } : {}),
                     domainError: failure.domainError,
-                    ...failure.flatContext,
                 };
             }
             if (!read.ok || !isRecord(read.value)) {
@@ -526,6 +526,16 @@ export function createClientCore(config) {
         patch,
     };
 }
+/**
+ * The server's own answer that a looked-up record does not exist
+ * (`PRODUCT_NOT_FOUND`, `STORE_PAGE_NOT_FOUND`, …). A lookup returns `null` for
+ * it without reporting a failure: a stale link is not an outage. A 404 that
+ * does not carry the server's code — a wrong `serverUrl`, a route the platform
+ * does not have — is not absence, and is still reported.
+ */
+export function isNotFoundAnswer(error) {
+    return isStorefrontError(error) && /_NOT_FOUND$/.test(error.domainError.code);
+}
 /**
  * Report a read that a namespace swallowed.
  *

package/dist/client/orders.d.ts

@@ -34,14 +34,17 @@ export interface OtpNamespace {
      * Send a WhatsApp verification code. On "unavailable" the server returns
      * a signed bypassToken — checkout proceeds unverified (fail-open).
      * Rate-limit errors carry `code: "OTP_RATE_LIMITED"` and `windowSeconds`.
+     * `forwardedHeaders` carries the shopper's address: the server's send and
+     * verify limits count per shopper, and without it every shopper of the
+     * store shares the one limit of this worker.
      */
-    send(phone: string): Promise<ClientResult<OtpSendResult>>;
+    send(phone: string, forwardedHeaders?: Record<string, string>): Promise<ClientResult<OtpSendResult>>;
     /**
      * Verify the code the customer typed. Wrong-but-retryable codes return
      * `code`/`attemptsRemaining`/`terminal` on the error result; a success
      * returns the signed `otpToken` that travels with the order.
      */
-    verify(phone: string, requestId: string, code: string): Promise<ClientResult<OtpVerifyResult>>;
+    verify(phone: string, requestId: string, code: string, forwardedHeaders?: Record<string, string>): Promise<ClientResult<OtpVerifyResult>>;
 }
 export interface OrdersNamespace {
     /**

package/dist/client/orders.js

@@ -13,7 +13,7 @@
  */
 import { CreatedOrderSchema, IdResponseSchema, OrderTrackingSchema, OtpSendResultSchema, OtpVerifyResultSchema, } from "../schemas.js";
 import { STOREFRONT_OPERATIONS } from "../domain.js";
-import { reportDegradedRead } from "./core.js";
+import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
 /**
  * Create orders namespace
  */
@@ -34,7 +34,8 @@ export function createOrdersNamespace(core) {
                 return tracking ?? null;
             }
             catch (error) {
-                reportDegradedRead(core.config, error, "orders.tracking");
+                if (!isNotFoundAnswer(error))
+                    reportDegradedRead(core.config, error, "orders.tracking");
                 return null;
             }
         },
@@ -60,16 +61,21 @@ export function createOrdersNamespace(core) {
             },
         },
         otp: {
-            async send(phone) {
+            async send(phone, forwardedHeaders) {
                 // core.post flattens the server's `context` (windowSeconds) and
                 // `code` into the error result — exactly what the OTP step reads.
                 return core.post("/store/otp/send", { phone }, {
+                    ...(forwardedHeaders ? { headers: forwardedHeaders } : {}),
                     schema: OtpSendResultSchema,
                     operation: STOREFRONT_OPERATIONS.ordersOtpSend,
                 });
             },
-            async verify(phone, requestId, code) {
-                return core.post("/store/otp/verify", { phone, requestId, code }, { schema: OtpVerifyResultSchema, operation: STOREFRONT_OPERATIONS.ordersOtpVerify });
+            async verify(phone, requestId, code, forwardedHeaders) {
+                return core.post("/store/otp/verify", { phone, requestId, code }, {
+                    ...(forwardedHeaders ? { headers: forwardedHeaders } : {}),
+                    schema: OtpVerifyResultSchema,
+                    operation: STOREFRONT_OPERATIONS.ordersOtpVerify,
+                });
             },
         },
     };

package/dist/client/page-data.js

@@ -16,7 +16,7 @@
  */
 import { PageDocumentPayloadSchema } from "../schemas.js";
 import { STOREFRONT_OPERATIONS } from "../domain.js";
-import { reportDegradedRead } from "./core.js";
+import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
 /**
  * Create the page-data namespace.
  */
@@ -28,7 +28,8 @@ export function createPageDataNamespace(core) {
                 return document ?? null;
             }
             catch (error) {
-                reportDegradedRead(core.config, error, "pageData.get");
+                if (!isNotFoundAnswer(error))
+                    reportDegradedRead(core.config, error, "pageData.get");
                 return null;
             }
         },

package/dist/client/pages.js

@@ -14,7 +14,7 @@
 import { LandingPageSchema, StorePagePublicSchema } from "../schemas.js";
 import { STOREFRONT_OPERATIONS } from "../domain.js";
 import { localizedPath } from "./paths.js";
-import { reportDegradedRead } from "./core.js";
+import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
 /**
  * Create pages namespace
  */
@@ -26,7 +26,8 @@ export function createPagesNamespace(core) {
                 return page ?? null;
             }
             catch (error) {
-                reportDegradedRead(core.config, error, "pages.get");
+                if (!isNotFoundAnswer(error))
+                    reportDegradedRead(core.config, error, "pages.get");
                 return null;
             }
         },
@@ -36,7 +37,8 @@ export function createPagesNamespace(core) {
                 return landingPage ?? null;
             }
             catch (error) {
-                reportDegradedRead(core.config, error, "pages.landing");
+                if (!isNotFoundAnswer(error))
+                    reportDegradedRead(core.config, error, "pages.landing");
                 return null;
             }
         },

package/dist/client/products.js

@@ -15,7 +15,7 @@ import { z } from "zod";
 import { IdResponseSchema, ProductListSchema, ProductSchema, ReviewListEnvelopeSchema } from "../schemas.js";
 import { STOREFRONT_OPERATIONS } from "../domain.js";
 import { localizedPath } from "./paths.js";
-import { reportDegradedRead } from "./core.js";
+import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
 /**
  * Create products namespace
  */
@@ -27,7 +27,8 @@ export function createProductsNamespace(core) {
                 return product ?? null;
             }
             catch (error) {
-                reportDegradedRead(core.config, error, "products.get");
+                if (!isNotFoundAnswer(error))
+                    reportDegradedRead(core.config, error, "products.get");
                 return null;
             }
         },

package/dist/endpoints/proxy.d.ts

@@ -69,9 +69,11 @@ export interface ProxyEndpointConfig<TInput, TOutput> {
      */
     successStatus?: number;
     /**
-     * Status code for upstream failures (default: 502).
-     * Typical choices: 502 for cart/abandoned/otp-send, 422 for otp-verify,
-     * 400 for submit-review.
+     * Status code for every upstream failure. Leave it unset: the status then
+     * follows the failure's `domainError` — 400 for a validation refusal, 422 for
+     * a business refusal, 429 when the server named a wait, 504 for a timeout and
+     * 502 for anything the shopper cannot fix (a bad store key, a server fault,
+     * a dropped connection, or a failure that carries no `domainError`).
      */
     errorStatus?: number;
     /**

package/dist/endpoints/proxy.js

@@ -31,7 +31,7 @@ import { collectForwardedHeaders } from "../actions.js";
  * ```
  */
 export function createProxyEndpoint(config) {
-    const { method, client, inputSchema, queryParams = [], pathParams = {}, csrfProtection = method === "POST", forwardAttribution = false, successStatus = 200, errorStatus = 502, successBody, noContent = false, } = config;
+    const { method, client, inputSchema, queryParams = [], pathParams = {}, csrfProtection = method === "POST", forwardAttribution = false, successStatus = 200, errorStatus, successBody, noContent = false, } = config;
     return async (context) => {
         const { request, params } = context;
         // CSRF Protection: reject cross-origin requests
@@ -68,8 +68,8 @@ export function createProxyEndpoint(config) {
         try {
             result = await client(input, headers);
         }
-        catch (error) {
-            return jsonResponse({ error: error instanceof Error ? error.message : "Upstream request failed" }, errorStatus);
+        catch {
+            return jsonResponse({ error: "The request could not be completed", code: "PROXY_UPSTREAM_FAILED" }, errorStatus ?? 502);
         }
         // Handle client errors — forward every diagnostic field the client
         // attached (code, windowSeconds, attemptsRemaining, terminal, ...)
@@ -78,7 +78,7 @@ export function createProxyEndpoint(config) {
             const extra = { ...result };
             delete extra.success;
             delete extra.error;
-            return jsonResponse({ error: result.error, ...extra }, errorStatus);
+            return jsonResponse({ error: result.error, ...extra }, errorStatus ?? failureStatus(result.domainError));
         }
         // Return success response
         if (noContent) {
@@ -88,6 +88,23 @@ export function createProxyEndpoint(config) {
         return jsonResponse(body, successStatus);
     };
 }
+/**
+ * The status a failure answers the browser with. The server's category decides:
+ * a refusal the shopper can act on stays a 4xx, and everything else is the
+ * gateway's failure, never the shopper's.
+ */
+function failureStatus(domainError) {
+    if (typeof domainError !== "object" || domainError === null)
+        return 502;
+    const { category, code, retryAfterSeconds } = domainError;
+    if (category === "validation")
+        return 400;
+    if (category === "business")
+        return typeof retryAfterSeconds === "number" ? 429 : 422;
+    if (category === "transport" && code === "REQUEST_TIMEOUT")
+        return 504;
+    return 502;
+}
 /**
  * Parse GET request input from query params and path params
  */

package/dist/endpoints/storefront-routes.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 type { StoreClient } from "../client/index.js";
+import { type AstroAPIContext } from "./proxy.js";
+export interface StorefrontRoutesOptions<C extends AstroAPIContext> {
+    /** The store client that serves this request — the request's own, never a shared one. */
+    client: (context: C) => StoreClient;
+}
+export type StorefrontApiRoute<C extends AstroAPIContext> = (context: C) => Promise<Response>;
+export interface StorefrontRoutes<C extends AstroAPIContext> {
+    /** POST `{ phone }` → `{ data: OtpSendResult }`. */
+    readonly otpSend: StorefrontApiRoute<C>;
+    /** POST `{ phone, requestId, code }` → `{ data: OtpVerifyResult }`. */
+    readonly otpVerify: StorefrontApiRoute<C>;
+    /** POST `{ items }` → `{ success: true, data: CartValidation }`. */
+    readonly cartValidate: StorefrontApiRoute<C>;
+    /** POST an `AbandonedCheckoutInput` → 204. */
+    readonly abandonedUpsert: StorefrontApiRoute<C>;
+    /** POST `{ sessionId, orderId, orderNumber }` → 204. */
+    readonly abandonedConvert: StorefrontApiRoute<C>;
+    /** GET, path param `wilayaId` → `{ data: Commune[] }`. */
+    readonly communes: StorefrontApiRoute<C>;
+    /** GET, path param `productId`, query `limit`/`offset` → `{ data: Review[], total }`. */
+    readonly reviewsList: StorefrontApiRoute<C>;
+    /** POST a `ReviewInput` → 201 `{ success: true, data: { id } }`. */
+    readonly reviewSubmit: StorefrontApiRoute<C>;
+}
+export declare const REVIEWS_PAGE_DEFAULT = 20;
+export declare const REVIEWS_PAGE_MAX = 50;
+export declare function createStorefrontRoutes<C extends AstroAPIContext = AstroAPIContext>(options: StorefrontRoutesOptions<C>): StorefrontRoutes<C>;

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.1.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",