@wocart/storefront 1.0.0 → 1.2.0

package/dist/client/core.js

@@ -237,6 +237,14 @@ async function readBody(response) {
         return { ok: false };
     }
 }
+/** How long a read may take, retries included, unless the client sets another limit. */
+export const DEFAULT_READ_TIMEOUT_MS = 10_000;
+/** A positive limit is used as given; `0` means no limit; anything else falls back to the default. */
+function resolveReadTimeout(value) {
+    if (value === 0)
+        return undefined;
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : DEFAULT_READ_TIMEOUT_MS;
+}
 /**
  * Create client core infrastructure
  *
@@ -245,14 +253,17 @@ async function readBody(response) {
  */
 export function createClientCore(config) {
     const { serverUrl, apiKey } = config;
-    const requestCache = new Map();
-    const inflightRequests = new Map();
+    const readTimeoutMs = resolveReadTimeout(config.readTimeoutMs);
+    // Finished values only, never a pending request. A client may outlive the
+    // request that made it (one per isolate); a request that waits on another
+    // request's pending read never settles on Cloudflare Workers once that other
+    // request is cancelled, and every later caller would wait behind it.
+    const valueCache = new Map();
     let observedCacheGeneration = cacheGeneration;
     function resetClearedCaches() {
         if (observedCacheGeneration === cacheGeneration)
             return;
-        requestCache.clear();
-        inflightRequests.clear();
+        valueCache.clear();
         observedCacheGeneration = cacheGeneration;
     }
     /**
@@ -301,107 +312,80 @@ export function createClientCore(config) {
         throw lastError ?? new Error("Network error");
     }
     /**
-     * GET request with in-flight deduplication and opt-in caching.
+     * GET request with opt-in caching.
      *
-     * Default behaviour: every call fetches fresh,
-     * but parallel identical calls coalesce into one request. Pass
-     * `{ cache: true }` for read-mostly data (config, categories, geo).
+     * Every call makes its own request: a call never waits on another call's
+     * pending request, so no caller can be held by work that belongs to someone
+     * else. Pass `{ cache: true }` for read-mostly data (config, categories,
+     * geo): the finished value is kept and later calls reuse it.
      *
      * Rejected and nullish results are never cached — a transient failure
      * or an absent record must not be pinned for the isolate's lifetime.
      *
+     * A read is bounded by the client's `readTimeoutMs` (10 seconds unless the
+     * client sets another), retries included, so a server that stops answering
+     * degrades the read instead of holding the page.
+     *
      * Pass `{ envelope: true }` for endpoints that carry metadata outside
      * `data` (e.g. pagination totals) and need the full response body.
      *
      * A failing read never resolves to a wrong value: it throws a
      * `StorefrontError` carrying the same `DomainError` the mutation path
-     * returns. A cancelled or timed-out read neither retries nor coalesces —
-     * one caller's abort must not cancel another's request, and an abandoned
-     * request must not be pinned in the cache.
+     * returns. A read the caller cancels never retries and is never cached.
      */
     async function get(path, schema, opts) {
         resetClearedCaches();
         const url = buildUrl(path);
         const operation = opts?.operation ?? `GET ${path}`;
-        const request = composeSignal(opts?.signal, opts?.timeoutMs);
-        const shared = request.signal === undefined;
+        const request = composeSignal(opts?.signal, opts?.timeoutMs ?? readTimeoutMs);
+        // A caller-supplied signal opts the read out of retries and the cache: its
+        // abort is the caller's decision, and an abandoned read must not be kept.
+        const callerCancels = opts?.signal !== undefined;
+        const cacheable = opts?.cache === true && !callerCancels;
         try {
-            // Check cache first (only successful results ever live here)
-            if (opts?.cache && shared) {
-                const cached = requestCache.get(url);
-                if (cached) {
-                    return (await cached);
-                }
+            if (cacheable && valueCache.has(url)) {
+                return valueCache.get(url);
             }
-            // Check in-flight requests for deduplication
-            if (shared) {
-                const inflight = inflightRequests.get(url);
-                if (inflight) {
-                    return (await inflight);
-                }
-            }
-            // Create new request
-            const requestPromise = (async () => {
-                try {
-                    const response = await fetchWithRetry(url, {
-                        method: "GET",
-                        headers: buildHeaders(),
-                        ...(request.signal ? { signal: request.signal } : {}),
-                    }, shared ? 2 : 0, request.signal);
-                    if (!response.ok) {
-                        const body = await readBody(response);
-                        throw new StorefrontError(serverFailure(response.status, body.ok ? body.value : undefined, operation, true)
-                            .domainError);
-                    }
+            const value = await (async () => {
+                const response = await fetchWithRetry(url, {
+                    method: "GET",
+                    headers: buildHeaders(),
+                    ...(request.signal ? { signal: request.signal } : {}),
+                }, callerCancels ? 0 : 2, request.signal);
+                if (!response.ok) {
                     const body = await readBody(response);
-                    if (!body.ok) {
-                        throw new StorefrontError(unreadableSuccess("MALFORMED_RESPONSE", MALFORMED_MESSAGE, operation, true));
-                    }
-                    const json = body.value;
-                    if (opts?.envelope) {
-                        if (schema) {
-                            const parsed = schema.safeParse(json);
-                            if (!parsed.success) {
-                                throw new StorefrontError(unreadableSuccess("SCHEMA_VALIDATION_FAILED", SCHEMA_MESSAGE, operation, true));
-                            }
-                            return parsed.data;
-                        }
-                        return json;
-                    }
-                    const data = isRecord(json) ? json.data : undefined;
-                    // Validate with schema if provided
+                    throw new StorefrontError(serverFailure(response.status, body.ok ? body.value : undefined, operation, true)
+                        .domainError);
+                }
+                const body = await readBody(response);
+                if (!body.ok) {
+                    throw new StorefrontError(unreadableSuccess("MALFORMED_RESPONSE", MALFORMED_MESSAGE, operation, true));
+                }
+                const json = body.value;
+                if (opts?.envelope) {
                     if (schema) {
-                        const parsed = schema.safeParse(data);
+                        const parsed = schema.safeParse(json);
                         if (!parsed.success) {
                             throw new StorefrontError(unreadableSuccess("SCHEMA_VALIDATION_FAILED", SCHEMA_MESSAGE, operation, true));
                         }
                         return parsed.data;
                     }
-                    return data;
+                    return json;
                 }
-                finally {
-                    // Remove from inflight after completion
-                    if (shared) {
-                        inflightRequests.delete(url);
+                const data = isRecord(json) ? json.data : undefined;
+                // Validate with schema if provided
+                if (schema) {
+                    const parsed = schema.safeParse(data);
+                    if (!parsed.success) {
+                        throw new StorefrontError(unreadableSuccess("SCHEMA_VALIDATION_FAILED", SCHEMA_MESSAGE, operation, true));
                     }
+                    return parsed.data;
                 }
+                return data;
             })();
-            // Store in-flight so parallel callers coalesce (only when no individual signal)
-            if (shared) {
-                inflightRequests.set(url, requestPromise);
-            }
-            if (opts?.cache && shared) {
-                requestCache.set(url, requestPromise);
-                // A failed or empty lookup must not be pinned: evict so the next
-                // call retries against the server.
-                requestPromise.then((value) => {
-                    if (value == null)
-                        requestCache.delete(url);
-                }, () => {
-                    requestCache.delete(url);
-                });
-            }
-            return await requestPromise;
+            if (cacheable && value != null)
+                valueCache.set(url, value);
+            return value;
         }
         catch (error) {
             if (error instanceof StorefrontError)
@@ -446,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)) {
@@ -504,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)) {
@@ -542,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/index.d.ts

@@ -5,9 +5,10 @@
  * shared core: config, products, categories, pages, shipping, geo, cart,
  * orders. The core is internal — consumers see only namespaces.
  *
- * One core means one connection story for every namespace: identical
- * parallel GETs coalesce into a single upstream request, and the opt-in
- * caches (config, categories, communes) are shared per client instance.
+ * One core means one connection story for every namespace: every read is
+ * bounded by the client's `readTimeoutMs`, each call makes its own request
+ * (none waits on another's pending one), and the opt-in caches (config,
+ * categories, communes) keep finished results per client instance.
  * A theme server render typically builds one client per request.
  *
  * ```ts

package/dist/client/index.js

@@ -5,9 +5,10 @@
  * shared core: config, products, categories, pages, shipping, geo, cart,
  * orders. The core is internal — consumers see only namespaces.
  *
- * One core means one connection story for every namespace: identical
- * parallel GETs coalesce into a single upstream request, and the opt-in
- * caches (config, categories, communes) are shared per client instance.
+ * One core means one connection story for every namespace: every read is
+ * bounded by the client's `readTimeoutMs`, each call makes its own request
+ * (none waits on another's pending one), and the opt-in caches (config,
+ * categories, communes) keep finished results per client instance.
  * A theme server render typically builds one client per request.
  *
  * ```ts

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.d.ts

@@ -12,8 +12,7 @@
  * newer document's instances reach the theme verbatim.
  *
  * Fetched fresh on every call (no process-lifetime cache — a save must reach
- * the next render, subject only to the theme's route cache); identical
- * parallel calls coalesce into one request like every other read.
+ * the next render, subject only to the theme's route cache).
  */
 import { type ClientCore } from "./core.js";
 import type { PageDocumentPayload } from "../types.js";

package/dist/client/page-data.js

@@ -12,12 +12,11 @@
  * newer document's instances reach the theme verbatim.
  *
  * Fetched fresh on every call (no process-lifetime cache — a save must reach
- * the next render, subject only to the theme's route cache); identical
- * parallel calls coalesce into one request like every other read.
+ * the next render, subject only to the theme's route cache).
  */
 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.
  */
@@ -29,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.d.ts

@@ -3,7 +3,7 @@
  *
  * Deep module: hides URL construction, slug encoding, and transport behind
  * two calls. Pages are fetched fresh every request (a merchant edit is live
- * on the next render); parallel identical calls coalesce into one request.
+ * on the next render).
  *
  * Failure contracts:
  * - `get(slug)` → null means "not published" — the theme 404s, never a

package/dist/client/pages.js

@@ -3,7 +3,7 @@
  *
  * Deep module: hides URL construction, slug encoding, and transport behind
  * two calls. Pages are fetched fresh every request (a merchant edit is live
- * on the next render); parallel identical calls coalesce into one request.
+ * on the next render).
  *
  * Failure contracts:
  * - `get(slug)` → null means "not published" — the theme 404s, never a
@@ -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/client/shipping.d.ts

@@ -6,8 +6,7 @@
  * a single wilaya's pair when the caller only needs one.
  *
  * Fetched fresh every request (merchants adjust delivery pricing and expect
- * the next render to show it); parallel identical calls coalesce into one
- * request.
+ * the next render to show it).
  *
  * Failure contract: resolves to `{}` /
  * `null` on any failure — never throws. Absent wilayas have no rule and are

package/dist/client/shipping.js

@@ -6,8 +6,7 @@
  * a single wilaya's pair when the caller only needs one.
  *
  * Fetched fresh every request (merchants adjust delivery pricing and expect
- * the next render to show it); parallel identical calls coalesce into one
- * request.
+ * the next render to show it).
  *
  * Failure contract: resolves to `{}` /
  * `null` on any failure — never throws. Absent wilayas have no rule and are

package/dist/domain.d.ts

@@ -35,6 +35,15 @@ export interface StoreScope {
      * success.
      */
     onError?: (error: DomainError) => void;
+    /**
+     * How long one read may take, retries included, before it gives up: the read
+     * then degrades like any other failed read and `onError` receives a
+     * `REQUEST_TIMEOUT`. A server that stops answering costs a page this long
+     * instead of holding it open. Defaults to 10 000 ms; `0` removes the limit.
+     * Writes have no default limit: a write cut off by a timer may already have
+     * happened, and retrying it could place the same order twice.
+     */
+    readonly readTimeoutMs?: number;
 }
 /** The server's hard limits for one canonical browser basket. */
 export declare const MAX_BASKET_LINES: 20;

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>;