@wocart/storefront 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,86 @@ 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
+
+- **A read never waits on another read's pending request.** The client used to
+  merge an identical read with one already in flight, and its opt-in caches
+  held the pending request itself. A client kept across requests (one per
+  isolate) could therefore make a request wait on a read another request had
+  started; on Cloudflare Workers that read never settles once the request
+  that started it is cancelled (a shopper leaving mid-load, a navigation
+  interrupted by a click), and every later request for the same URL hung.
+  Each call now makes its own request, and the caches keep finished values
+  only.
+
+### Added
+
+- **`readTimeoutMs`** on `createStoreClient` bounds every read, retries
+  included: 10 000 ms by default, `0` for no limit. A read that runs out of
+  time degrades like any failed read and reports `REQUEST_TIMEOUT` to
+  `onError`, so a server that stops answering costs a page seconds instead of
+  holding it open. Writes keep no default limit: a write cut off by a timer
+  may already have happened.
+
+### Changed
+
+- Parallel identical reads are no longer coalesced into one request. A page
+  that asks for the same data from several places should ask once and share
+  the result within its render.
+
 ## 1.0.0 — 2026-10-13
 
 The first public release.

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:
@@ -115,6 +115,7 @@ import { createBasketStore, formatMoney } from "@wocart/storefront";
 | `locale` | no | read merchant text in a published store language (`"fr"`); one client per language |
 | `theme` | no | your theme's key (`defineTheme({ key })`), to receive the merchant's edits to your theme's text |
 | `onError` | no | observability hook for degraded reads |
+| `readTimeoutMs` | no | how long one read may take, retries included, before it degrades (default 10 000; `0` for no limit) |
 
 A storefront deployed by Wocart receives its origin and key as the
 `COD_SERVER_URL` and `STORE_API_KEY` environment variables. The SDK reads no

package/USAGE.md

@@ -162,9 +162,11 @@ const [config, featuredProducts] = await Promise.all([
 ]);
 ~~~
 
-Parallel identical GET requests made through the same client are coalesced.
-That makes it safe for independent page loaders to ask for the same
-configuration without manually coordinating them.
+Every call makes its own request; a call never waits on another call's
+pending request, even an identical one. Within one render, ask once and share
+the result (`Promise.all`, or a per-request memo) when several parts of a page
+need the same data. A client never holds pending work across calls, so one
+kept for several requests cannot leave a request waiting on another's read.
 
 ### Available imports
 
@@ -438,10 +440,13 @@ conversion event.
 
 ### Caching and retries
 
-- GET requests are fresh by default.
-- Parallel identical GET requests are deduplicated per client instance.
-- config.get(), categories.list(), and geo.communes() use the client
-  lifetime cache after a successful response.
+- GET requests are fresh by default, and each call makes its own request.
+- config.get(), categories.list(), and geo.communes() keep their finished
+  result for the client's lifetime; a call made while the first is still
+  pending makes its own request rather than waiting on it.
+- Every read is bounded by `readTimeoutMs` (10 seconds by default), retries
+  included; a read that runs out of time degrades and reports
+  `REQUEST_TIMEOUT` to `onError`. Writes have no default limit.
 - null results and failures are not cached, so a temporary failure can recover
   on the next call.
 - GET network failures use two short exponential backoff retries.
@@ -910,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
@@ -1012,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;
@@ -1041,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,
         });
       }
@@ -1071,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) }),
 });
 ~~~
 
@@ -1148,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

@@ -17,8 +17,8 @@ export type ClientConfig = StoreScope;
 /**
  * Options every request accepts.
  *
- * `signal` cancels the request — an aborted call never retries, never coalesces
- * with another caller's request, and returns a REQUEST_ABORTED DomainError
+ * `signal` cancels the request — an aborted call never retries, is never
+ * cached, and returns a REQUEST_ABORTED DomainError
  * (a read throws instead). `timeoutMs` bounds the whole operation, retries
  * included, and reads as REQUEST_TIMEOUT. `operation` names the call in the
  * error it produces; namespaces pass a stable label (`orders.otp.send`) so logs
@@ -61,6 +61,8 @@ export interface ClientCore {
     post: <TInput, TOutput>(path: string, body: TInput, opts?: PostOptions<TOutput>) => Promise<ClientResult<TOutput>>;
     patch: <TInput, TOutput>(path: string, body: TInput, optsOrSchema?: z.Schema<TOutput> | PatchOptions<TOutput>) => Promise<ClientResult<TOutput>>;
 }
+/** How long a read may take, retries included, unless the client sets another limit. */
+export declare const DEFAULT_READ_TIMEOUT_MS = 10000;
 /**
  * Create client core infrastructure
  *
@@ -68,6 +70,14 @@ export interface ClientCore {
  * @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.
  *