@wocart/storefront 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,64 @@ 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.7.0 — 2026-10-17
+
+### Added
+
+- **Page types and their URLs.** `STOREFRONT_PAGE_PATHS` is the platform's
+  table of public paths (`home`, `catalog`, `category`, `product`, `page`,
+  `landing`, `checkout`, `thankYou`); `storefrontPath(type, params)` builds
+  one (encoded; a missing parameter throws) and `matchStorefrontPath(pathname)`
+  recognises one, exactly. Types `StorefrontPageType`, `StorefrontPathParams`,
+  `StorefrontPageMatch`.
+- **Navigation menus.** `store.menus.get(handle)` reads a menu as a shopper
+  sees it: labels in the client's language, every `href` resolved by the
+  server, items leading nowhere public already left out; `null` for an
+  unknown handle, which is not reported to `onError`. Types `StoreMenu`,
+  `StoreMenuItem`, schemas `StoreMenuSchema`, `StoreMenuItemSchema`.
+- `StoreConfig.themeSettings`: the merchant's values for the requesting
+  theme's settings, as saved — resolve them with `resolveThemeSettings` from
+  `@wocart/theme` 1.1. Optional: absent from a server that predates them.
+
+### Deprecated
+
+- `STOREFRONT_ROUTES` lists six of the paths, without the home and the
+  catalog; use `STOREFRONT_PAGE_PATHS` and `matchStorefrontPath`.
+
+## 1.6.0 — 2026-10-17
+
+### Added
+
+- **Reviews with photos and a voice note.** `products.reviews.eligibility()`
+  proves a purchase with the order number and the phone it was placed with,
+  and answers the products the order may review and what may be attached,
+  with an upload grant. `products.reviews.upload()` sends one file as it is
+  (a stream passes through unbuffered). `submit()` takes `phone`, `grant` and
+  `uploads`, and answers `visibility` (`published` or `after_review`).
+- `Review` carries `verified` and `media` (photos with a thumbnail, the voice
+  note with its length); reviews from older servers read as unverified with
+  no media.
+- Storefront routes `reviewEligibility` and `reviewUpload` (PUT, the file as
+  the body); `reviewSubmit` forwards the new fields. Every PUT refuses a
+  cross-origin request too.
+- **`@wocart/storefront/review-media`**, a browser-only entry point:
+  `prepareReviewPhoto` (1600 px, re-encoded, EXIF removed before it leaves
+  the device), `createVoiceRecorder` (speech at ~32 kb/s, stops at the
+  store's limit), `canRecordVoice`, `pickVoiceMimeType`, `photoTargetSize`.
+- Types `ReviewMedia`, `ReviewEligibility`, `ReviewEligibilityInput`,
+  `ReviewableProduct`, `ReviewUpload`, `ReviewUploadInput`,
+  `ReviewSubmitResult`, and their schemas.
+
+### Deprecated
+
+- **`submit()` without `phone`**: still accepted for a text review of a
+  delivered order; a later major requires the phone.
+
+- **`deletedAt`** on a product is optional and always `null` when present: a
+  removed product is deleted on the server and never served, so the field says
+  nothing. The server keeps sending `null` for releases that require it; a
+  later major release removes it. Nothing in a theme should read it.
+
 ## 1.5.0 — 2026-10-15
 
 ### Added

package/USAGE.md

@@ -90,34 +90,55 @@ allowlists, delivery availability, stock, discounts, final totals, OTP
 acceptance, or tracking eligibility. Those rules are platform data or platform
 decisions. The theme presents them and gives the shopper a clear next action.
 
-## The storefront route contract
+## Page types and their URLs
 
-A storefront's public paths are a platform contract, not a theme preference.
-Three parts of the platform meet on them: the theme renders the pages, the server writes the
-URL Meta is told about (`/lp/:slug` for a sale attributed to a landing page,
-`/thank-you` otherwise), and the dashboard prints them as the store's public
-links. These six patterns are frozen — restyle anything else, but change one of
-these only as a platform change:
+A URL *means* something to the platform — a product, a category, a store
+page — and that meaning is a **page type**. Each page type lives at one
+public path. The paths are a platform contract, not a theme preference: the
+platform builds them without running your theme (the dashboard prints a page's
+public link, the server names the landing page in the URL Meta is told about,
+the AI tools hand out landing-page links), so a theme that moved one would
+break those links.
 
-| Route | Renders |
-| --- | --- |
-| `/products/:handle` | product detail (public handle, never an internal id) |
-| `/category/:slug` | a category listing |
-| `/pages/:slug` | a legal or CMS page |
-| `/lp/:slug` | a landing page |
-| `/checkout` | the checkout |
-| `/thank-you` | order confirmation |
-
-The root (`/`) and the catalog index (`/products`) carry no parameter and are
-the two further surfaces a theme implements.
-
-The contract is exported, so a theme can read it instead of repeating it:
-`STOREFRONT_ROUTES` is the table above, and `showsWidgetOn(surfaces, pathname)`
-is the platform's half of "which surface is this page" — the merchant's
-per-surface switches then mean the same thing as the dashboard's preview. The
-gate never prefix-matches: `/productsomething`, `/checkout-success` and
-`/thank-you-again` are no surface at all, never a widget on a page the merchant
-switched off.
+| Page type | Path | Renders | Your theme |
+| --- | --- | --- | --- |
+| `home` | `/` | the home page | required |
+| `catalog` | `/products` | every product | required |
+| `category` | `/category/:slug` | one category's products | required when the store has categories |
+| `product` | `/products/:handle` | one product (its public handle, never an id) | required |
+| `page` | `/pages/:slug` | a legal or merchant page | required — checkout consent links to the store's legal pages |
+| `landing` | `/lp/:slug` | a landing page | required when the store runs landing pages |
+| `checkout` | `/checkout` | the cart's checkout | required when the store turns the cart on |
+| `thankYou` | `/thank-you` | the order confirmation | required |
+
+How a theme implements them, in Astro's own terms:
+
+- **Render each page type at its path with a file route**:
+  `src/pages/products/[handle].astro`, `src/pages/lp/[slug].astro` … The
+  parameter's name in your file is yours; the path is the platform's.
+- **Build every link with `storefrontPath`**, never a hand-written string:
+  `storefrontPath("product", { handle: product.handle })` → `/products/robe`,
+  `storefrontPath("checkout")` → `/checkout`. Parameters are encoded for you;
+  a missing one throws, so a link to nowhere fails loudly. Add the language
+  prefix with `localizeHref(storefrontPath(…), locale, routing)`.
+- **Recognise a page with `matchStorefrontPath(pathname)`** →
+  `{ type: "product", params: { handle: "robe" } }`, or `null` for any other
+  path. It matches exactly — `/productsomething`, `/products/a/b` and
+  `/checkout-success` are nothing — and ignores the query, fragment and a
+  trailing slash. Pass the path without its language prefix.
+- **Answer a missing resource with a real 404** (`return Astro.rewrite("/404")`),
+  never a redirect to the home page: a redirect turns a dead link into a
+  "soft 404" for search engines and ad reviews.
+- **Every other route is yours.** `/about`, `/offers/summer`, a store
+  locator — add them as Astro file routes; nothing in the contract restricts
+  them. Avoid the platform's paths above and `/api/*` (your same-origin
+  endpoints, see "Storefront API routes").
+
+`showsWidgetOn(surfaces, pathname)` is the platform's half of "should the
+WhatsApp widget show here": the merchant switches surfaces on; the page type
+says which surface a pathname is. `STOREFRONT_PAGE_PATHS` is the table above
+as data. `STOREFRONT_ROUTES` is deprecated: it lists six of the paths, without
+the home and the catalog.
 
 ## The five rules to remember
 
@@ -196,7 +217,8 @@ server directly.
 | `WILAYAS`, `ALGERIA_COMMUNES`, `communesForWilaya` | Reference data: 58 wilayas, 1,551 communes, one wilaya's rows |
 | `normalizeAlgerianPhone`, `toLocalAlgerianMobile` | The one Algerian phone rule (accept/format) |
 | `resolvePrefillText`, `buildWhatsAppHref`, `stripTrackingParams`, `truncateAtWordBoundary`, `PREFILL_TOKENS`, `MAX_RESOLVED_PREFILL_LENGTH` | WhatsApp prefill text and the `wa.me` link |
-| `showsWidgetOn`, `STOREFRONT_ROUTES` | Which surface a pathname is (the frozen route contract) |
+| `storefrontPath`, `matchStorefrontPath`, `STOREFRONT_PAGE_PATHS` | The page types and their public paths: build a link, recognise a page |
+| `showsWidgetOn`, `STOREFRONT_ROUTES` | Which widget surface a pathname is (`STOREFRONT_ROUTES` deprecated) |
 | `productImageSource` | Which photo represents a product (cover → gallery fallback) |
 | `getProductView`, `getProductListView` | Pure price, discount, default-variant, and stock values for detail and list projections |
 | `getOfferTierView` | Pure offer-tier price, compare-price, savings, and free-shipping projection; display-only, never order authority |
@@ -295,6 +317,7 @@ carries the key, which the package's own contract test asserts.
 | products | Product catalog and reviews | Product, ProductList, or empty/null |
 | categories | Catalog navigation | Category array |
 | pages | Legal and CMS pages, landing pages | StorePagePublic, LandingPage, or null |
+| menus | The store's navigation menus | StoreMenu or null |
 | pageData | The store's saved page document | PageDocumentPayload or null |
 | shipping | Delivery prices | ShippingRates or one rate/null |
 | geo | Wilayas and communes | Static wilayas or Commune array |
@@ -474,8 +497,8 @@ StoreConfig contains the current store identity and presentation fields,
 including:
 
 - name, domain, logoUrl, themeId, colors, fontFamily, and fontUrl;
-- lang (the primary language), locales, contentOverrides, currency,
-  currencySymbol, metaTitle, metaDescription, and ogImage;
+- lang (the primary language), locales, contentOverrides, themeSettings,
+  currency, currencySymbol, metaTitle, metaDescription, and ogImage;
 - announcementBar and reviewsEnabled;
 - cartEnabled, freeShippingThreshold, and cartShippingMode;
 - checkoutForm policy;
@@ -483,6 +506,21 @@ including:
 - pixelId and conversionEvent;
 - public page links, legal contact information, and WhatsApp widget settings.
 
+`themeSettings` holds the merchant's values for your theme's settings (the
+ones it declares with `defineTheme({ settings })` in `@wocart/theme`), by
+setting key, exactly as saved. It is sent only to a client created with
+`theme`, is `{}` when the store saved none, and is absent from a server that
+predates theme settings — `resolveThemeSettings` takes either. Never read it raw: resolve it
+against your declaration, which checks every value and falls back to your
+default for one it no longer accepts:
+
+~~~ts
+import { resolveThemeSettings } from "@wocart/theme";
+
+const { values } = resolveThemeSettings(theme, config?.themeSettings, { locales: [locale] });
+const headerMenu = values.headerMenu; // a menu handle, for store.menus.get()
+~~~
+
 The checkout policy is not a suggestion. Use it to decide whether address,
 email, notes, delivery options, and custom fields are required, optional, or
 hidden. The policy includes:
@@ -624,19 +662,64 @@ const reviews = await store.products.reviews.list(productId, {
 ~~~
 
 The result is { rows: Review[], total: number }. The default page size is 20
-and the default offset is 0. For submitting a review:
+and the default offset is 0. Each review carries `verified` (it rests on an
+order that reached its customer — show a "verified purchase" badge) and
+`media`: its photos (`url` at 1600 px, `thumbUrl` at 480 px for lists, with
+`width`/`height` to reserve the space) and its voice note (`kind: "audio"`,
+with `durationMs`). Show photos as their `thumbUrl` with `loading="lazy"`, and
+a voice note as `<audio preload="none">`, so neither costs anything until the
+shopper opens or plays it.
+
+Writing a review takes three steps, so the shopper never waits on a slow
+connection:
 
 ~~~ts
+// 1. Prove the purchase: the order number and the phone it was placed with.
+const found = await store.products.reviews.eligibility({ orderNumber, phone });
+if (!found.success) {
+  // ORDER_NOT_FOUND (wrong number or phone), REVIEW_ORDER_NOT_DELIVERED,
+  // REVIEW_RATE_LIMITED, REVIEWS_DISABLED
+}
+// found.data.products: what the order may review ({ reviewed } ones only shown).
+// found.data.media: null (text only) or { maxPhotos, voiceMaxSeconds, grant }.
+
+// 2. Send each file the moment it is picked — not on submit.
+const sent = await store.products.reviews.upload({ grant, body: file, contentLength: file.size });
+// sent.data.uploadId
+
+// 3. Submit: answered at once; the files are prepared afterwards.
 const submitted = await store.products.reviews.submit({
-  orderNumber: customerVisibleOrderNumber,
+  orderNumber,
+  phone,
   productId,
   rating: 5,
-  title: "Beautiful",
   body: "Exactly as described.",
+  grant,
+  uploads: [uploadId],
 });
+// submitted.data.visibility: "published" now, or "after_review"
+~~~
+
+orderNumber is the customer-visible order number, not the internal order
+UUID. The body needs 10 characters unless a voice note is attached. One review
+per product of an order (`ORDER_ALREADY_REVIEWED`). A submit without `phone`
+— the 1.5 shape — still works for text only, on a delivered order, and is
+deprecated.
+
+In the browser, `@wocart/storefront/review-media` prepares files before they
+are sent:
+
+~~~ts
+import { canRecordVoice, createVoiceRecorder, prepareReviewPhoto } from "@wocart/storefront/review-media";
+
+const photo = await prepareReviewPhoto(file); // 1600 px, WebP/JPEG, EXIF gone
+const recorder = createVoiceRecorder({ maxSeconds: media.voiceMaxSeconds, onTick, onLimit });
+await recorder.start();
+const { blob, durationMs } = await recorder.stop();
 ~~~
 
-orderNumber is the customer-visible order number, not the internal order UUID.
+`canRecordVoice()` says whether to show a record button at all; a shopper can
+also attach an audio file. Send a recording with its `durationMs`.
 
 ## Categories, legal pages, and landing pages
 
@@ -671,6 +754,36 @@ Do not hardcode the legal navigation list. Use config.pages so the store's
 available public pages determine the links. If a page is null, render the
 theme's not-found or fallback state.
 
+### Navigation menus
+
+A store's menus are store data, like its products: the merchant builds them in
+the dashboard (Navigation) — a handle such as `main-menu`, a title, and up to
+three levels of items, each pointing at a product, a category, a store page, a
+landing page, the home, the catalog, or a URL. Your theme decides *where* a
+menu shows; the merchant decides *what* it holds.
+
+~~~ts
+const menu = await store.menus.get(settings.headerMenu); // "main-menu"
+
+for (const item of menu?.items ?? []) {
+  const href = item.type === "url" ? item.href : localizeHref(item.href, locale, routing);
+  // item.label, item.children (same shape, at most three levels)
+}
+~~~
+
+- Name the menu through a `menu` theme setting rather than a hard-coded
+  handle, so the merchant picks which menu each place shows.
+- Every link is resolved by the server: `href` is a path of the store without
+  a language prefix (pass it through `localizeHref`) or, for `type: "url"`,
+  the address the merchant entered — render it as is.
+- An item whose destination is deleted or not public (a draft page, an
+  inactive product) is already left out, with its children. You never filter.
+- Labels arrive in the client's language when the store translated them.
+- `null` means the store has no menu with that handle, or the read failed:
+  render your own fallback navigation (for example the home and the catalog
+  from `storefrontPath`). A missing menu is not a failure and is not reported
+  to `onError`.
+
 ### Landing pages
 
 ~~~ts
@@ -1179,11 +1292,13 @@ export const POST = routes.otpSend;
 | `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 } }` |
+| `reviewEligibility` | POST | `{ orderNumber, phone, turnstileToken? }` | `{ data: ReviewEligibility }` |
+| `reviewUpload` | PUT | the file as the body; headers `X-Review-Grant`, `X-Media-Duration-Ms` | 201 `{ data: ReviewUpload }` (streamed on, never buffered) |
+| `reviewSubmit` | POST | `ReviewInput` | 201 `{ success: true, data: { id, visibility } }` |
 
 What every route gets right:
 
-- every POST refuses a cross-origin request with 403;
+- every POST and PUT 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

package/dist/client/core.d.ts

@@ -55,10 +55,16 @@ export interface PatchOptions<TOutput> extends RequestOptions {
  * Client core infrastructure
  * Exposed only to namespace implementations, not to end users
  */
+/** What a file upload's body may be. */
+export type UploadBody = Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>;
 export interface ClientCore {
     config: ClientConfig;
     get: <T>(path: string, schema?: z.Schema<T>, opts?: GetOptions) => Promise<T>;
     post: <TInput, TOutput>(path: string, body: TInput, opts?: PostOptions<TOutput>) => Promise<ClientResult<TOutput>>;
+    /** PUT one file as the body (streams pass through unbuffered). */
+    upload: <TOutput>(path: string, body: UploadBody, opts?: PostOptions<TOutput> & {
+        contentLength?: number;
+    }) => 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. */

package/dist/client/core.js

@@ -411,8 +411,22 @@ export function createClientCore(config) {
      * outcome `unknown`, never a retry of a possible duplicate.
      */
     async function post(path, body, opts) {
+        return write("POST", path, { body: JSON.stringify(body) }, opts);
+    }
+    /**
+     * PUT one file as the request body, as it is — a stream passes through
+     * without being buffered. Same result contract as `post`.
+     */
+    async function upload(path, body, opts) {
+        return write("PUT", path, {
+            body,
+            contentType: "application/octet-stream",
+            ...(opts?.contentLength !== undefined ? { contentLength: opts.contentLength } : {}),
+        }, opts);
+    }
+    async function write(method, path, outgoing, opts) {
         const url = buildUrl(path);
-        const operation = opts?.operation ?? `POST ${path}`;
+        const operation = opts?.operation ?? `${method} ${path}`;
         const request = composeSignal(opts?.signal, opts?.timeoutMs);
         if (request.aborted()) {
             request.cleanup();
@@ -421,9 +435,14 @@ export function createClientCore(config) {
         }
         try {
             const response = await fetchWithRetry(url, {
-                method: "POST",
-                headers: buildHeaders(opts?.headers),
-                body: JSON.stringify(body),
+                method,
+                headers: buildHeaders({
+                    ...(outgoing.contentType ? { "Content-Type": outgoing.contentType } : {}),
+                    ...(outgoing.contentLength !== undefined ? { "Content-Length": String(outgoing.contentLength) } : {}),
+                    ...opts?.headers,
+                }),
+                body: outgoing.body,
+                ...(outgoing.body instanceof ReadableStream ? { duplex: "half" } : {}),
                 ...(request.signal ? { signal: request.signal } : {}),
             }, 0, request.signal);
             const read = await readBody(response);
@@ -523,6 +542,7 @@ export function createClientCore(config) {
         config,
         get,
         post,
+        upload,
         patch,
     };
 }

package/dist/client/index.d.ts

@@ -2,7 +2,7 @@
  * Store Client Factory — the SDK's front door.
  *
  * One server-side call builds the whole read/write surface a theme needs, over one
- * shared core: config, products, categories, pages, shipping, geo, cart,
+ * shared core: config, products, categories, pages, menus, shipping, geo, cart,
  * orders. The core is internal — consumers see only namespaces.
  *
  * One core means one connection story for every namespace: every read is
@@ -31,6 +31,7 @@ export declare function createStoreClient(config: StoreScope): {
     products: import("./products.js").ProductsNamespace;
     categories: import("./categories.js").CategoriesNamespace;
     pages: import("./pages.js").PagesNamespace;
+    menus: import("./menus.js").MenusNamespace;
     pageData: import("./page-data.js").PageDataNamespace;
     shipping: import("./shipping.js").ShippingNamespace;
     geo: import("./geo.js").GeoNamespace;

package/dist/client/index.js

@@ -2,7 +2,7 @@
  * Store Client Factory — the SDK's front door.
  *
  * One server-side call builds the whole read/write surface a theme needs, over one
- * shared core: config, products, categories, pages, shipping, geo, cart,
+ * shared core: config, products, categories, pages, menus, shipping, geo, cart,
  * orders. The core is internal — consumers see only namespaces.
  *
  * One core means one connection story for every namespace: every read is
@@ -31,6 +31,7 @@ import { createConfigNamespace } from "./config.js";
 import { createProductsNamespace } from "./products.js";
 import { createCategoriesNamespace } from "./categories.js";
 import { createPagesNamespace } from "./pages.js";
+import { createMenusNamespace } from "./menus.js";
 import { createPageDataNamespace } from "./page-data.js";
 import { createShippingNamespace } from "./shipping.js";
 import { createGeoNamespace } from "./geo.js";
@@ -44,6 +45,7 @@ export function createStoreClient(config) {
         products: createProductsNamespace(core),
         categories: createCategoriesNamespace(core),
         pages: createPagesNamespace(core),
+        menus: createMenusNamespace(core),
         pageData: createPageDataNamespace(core),
         shipping: createShippingNamespace(core),
         geo: createGeoNamespace(core),

package/dist/client/menus.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Menus Namespace - the store's navigation menus
+ *
+ * A menu is store data the merchant edits in the dashboard; a theme names it
+ * by handle (usually through a `menu` theme setting) and renders what comes
+ * back. Every link is resolved by the server: an item's `href` is a path of
+ * the store without a language prefix, or the merchant's URL, and items
+ * leading nowhere public are already left out. Fetched fresh every request.
+ *
+ * Failure contract: `get(handle)` → null means "no such menu" or a failed
+ * read — the theme renders its own fallback navigation.
+ */
+import { type ClientCore } from "./core.js";
+import type { StoreMenu } from "../types.js";
+export interface MenusNamespace {
+    /**
+     * A menu by handle (`main-menu`), labels in the client's language.
+     * Resolves to `null` for an unknown handle or a failed read.
+     */
+    get(handle: string): Promise<StoreMenu | null>;
+}
+export declare function createMenusNamespace(core: ClientCore): MenusNamespace;

package/dist/client/menus.js

@@ -0,0 +1,30 @@
+/**
+ * Menus Namespace - the store's navigation menus
+ *
+ * A menu is store data the merchant edits in the dashboard; a theme names it
+ * by handle (usually through a `menu` theme setting) and renders what comes
+ * back. Every link is resolved by the server: an item's `href` is a path of
+ * the store without a language prefix, or the merchant's URL, and items
+ * leading nowhere public are already left out. Fetched fresh every request.
+ *
+ * Failure contract: `get(handle)` → null means "no such menu" or a failed
+ * read — the theme renders its own fallback navigation.
+ */
+import { StoreMenuSchema } from "../schemas.js";
+import { STOREFRONT_OPERATIONS } from "../domain.js";
+import { localizedPath } from "./paths.js";
+import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
+export function createMenusNamespace(core) {
+    return {
+        async get(handle) {
+            try {
+                return await core.get(localizedPath(core.config, `/store/menus/${encodeURIComponent(handle)}`), StoreMenuSchema, { operation: STOREFRONT_OPERATIONS.menusGet });
+            }
+            catch (error) {
+                if (!isNotFoundAnswer(error))
+                    reportDegradedRead(core.config, error, "menus.get");
+                return null;
+            }
+        },
+    };
+}

package/dist/client/products.d.ts

@@ -12,7 +12,7 @@
  * half-shaped product into a theme.
  */
 import { type ClientCore, type ClientResult } from "./core.js";
-import type { Product, ProductList, ProductPage, ProductListFilters, Review, ReviewInput, ReviewListPagination } from "../types.js";
+import type { Product, ProductList, ProductPage, ProductListFilters, Review, ReviewEligibility, ReviewEligibilityInput, ReviewInput, ReviewListPagination, ReviewSubmitResult, ReviewUpload, ReviewUploadInput } from "../types.js";
 /** Page size when a caller names none — the storefront's default grid. */
 export declare const PRODUCT_PAGE_DEFAULT = 24;
 /** One below the server's 100-row cap, so the extra row that proves a next page fits. */
@@ -51,13 +51,25 @@ export interface ProductsNamespace {
             total: number;
         }>;
         /**
-         * Submit a product review
-         * @param data - Review data
-         * @returns Result with review ID or error
+         * Prove a purchase with the order number and the phone it was placed
+         * with: answers the order's products the shopper may review (a delivered
+         * order, each product once) and, when the store takes them, what may be
+         * attached and the upload grant. A wrong number or phone fails with
+         * `ORDER_NOT_FOUND`; an order on its way with `REVIEW_ORDER_NOT_DELIVERED`.
          */
-        submit(data: ReviewInput): Promise<ClientResult<{
-            id: string;
-        }>>;
+        eligibility(input: ReviewEligibilityInput): Promise<ClientResult<ReviewEligibility>>;
+        /**
+         * Send one photo or voice note, as it is, under the grant — as soon as the
+         * shopper picks it, so submitting waits for nothing. A stream passes
+         * through unbuffered. Its kind is read from its bytes by the server.
+         */
+        upload(input: ReviewUploadInput): Promise<ClientResult<ReviewUpload>>;
+        /**
+         * Submit a review. Answers at once; its files are prepared afterwards,
+         * and `visibility` says whether it is public now or after the store
+         * checks it.
+         */
+        submit(data: ReviewInput): Promise<ClientResult<ReviewSubmitResult>>;
     };
 }
 /**

package/dist/client/products.js

@@ -12,7 +12,7 @@
  * half-shaped product into a theme.
  */
 import { z } from "zod";
-import { IdResponseSchema, ProductListSchema, ProductSchema, ReviewListEnvelopeSchema } from "../schemas.js";
+import { ProductListSchema, ProductSchema, ReviewEligibilitySchema, ReviewListEnvelopeSchema, ReviewSubmitResultSchema, ReviewUploadSchema } from "../schemas.js";
 import { STOREFRONT_OPERATIONS } from "../domain.js";
 import { localizedPath } from "./paths.js";
 import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
@@ -81,8 +81,28 @@ export function createProductsNamespace(core) {
                     return { rows: [], total: 0 };
                 }
             },
+            async eligibility(input) {
+                return core.post("/store/reviews/eligibility", input, {
+                    schema: ReviewEligibilitySchema,
+                    operation: STOREFRONT_OPERATIONS.productsReviewsEligibility,
+                });
+            },
+            async upload(input) {
+                return core.upload("/store/reviews/uploads", input.body, {
+                    schema: ReviewUploadSchema,
+                    operation: STOREFRONT_OPERATIONS.productsReviewsUpload,
+                    headers: {
+                        "X-Review-Grant": input.grant,
+                        ...(input.durationMs ? { "X-Media-Duration-Ms": String(Math.round(input.durationMs)) } : {}),
+                    },
+                    ...(input.contentLength !== undefined ? { contentLength: input.contentLength } : {}),
+                });
+            },
             async submit(data) {
-                return core.post("/store/reviews", data, { schema: IdResponseSchema, operation: STOREFRONT_OPERATIONS.productsReviewsSubmit });
+                return core.post("/store/reviews", data, {
+                    schema: ReviewSubmitResultSchema,
+                    operation: STOREFRONT_OPERATIONS.productsReviewsSubmit,
+                });
             },
         },
     };

package/dist/domain.d.ts

@@ -349,8 +349,11 @@ export declare const STOREFRONT_OPERATIONS: {
     readonly productsList: "products.list";
     readonly productsReviewsList: "products.reviews.list";
     readonly productsReviewsSubmit: "products.reviews.submit";
+    readonly productsReviewsEligibility: "products.reviews.eligibility";
+    readonly productsReviewsUpload: "products.reviews.upload";
     readonly pagesGet: "pages.get";
     readonly pagesLanding: "pages.landing";
+    readonly menusGet: "menus.get";
     readonly shippingRates: "shipping.rates";
     readonly shippingRate: "shipping.rate";
     readonly geoCommunes: "geo.communes";
@@ -388,10 +391,13 @@ export declare const STOREFRONT_RETRY_POLICIES: {
     readonly "pageData.get": "safe-read";
     readonly "pages.get": "safe-read";
     readonly "pages.landing": "safe-read";
+    readonly "menus.get": "safe-read";
     readonly "products.get": "safe-read";
     readonly "products.list": "safe-read";
     readonly "products.reviews.list": "safe-read";
     readonly "products.reviews.submit": "never";
+    readonly "products.reviews.eligibility": "never";
+    readonly "products.reviews.upload": "never";
     readonly "shipping.rate": "safe-read";
     readonly "shipping.rates": "safe-read";
 };

package/dist/domain.js

@@ -202,8 +202,11 @@ export const STOREFRONT_OPERATIONS = {
     productsList: "products.list",
     productsReviewsList: "products.reviews.list",
     productsReviewsSubmit: "products.reviews.submit",
+    productsReviewsEligibility: "products.reviews.eligibility",
+    productsReviewsUpload: "products.reviews.upload",
     pagesGet: "pages.get",
     pagesLanding: "pages.landing",
+    menusGet: "menus.get",
     shippingRates: "shipping.rates",
     shippingRate: "shipping.rate",
     geoCommunes: "geo.communes",
@@ -240,10 +243,13 @@ export const STOREFRONT_RETRY_POLICIES = {
     [STOREFRONT_OPERATIONS.pageDataGet]: "safe-read",
     [STOREFRONT_OPERATIONS.pagesGet]: "safe-read",
     [STOREFRONT_OPERATIONS.pagesLanding]: "safe-read",
+    [STOREFRONT_OPERATIONS.menusGet]: "safe-read",
     [STOREFRONT_OPERATIONS.productsGet]: "safe-read",
     [STOREFRONT_OPERATIONS.productsList]: "safe-read",
     [STOREFRONT_OPERATIONS.productsReviewsList]: "safe-read",
     [STOREFRONT_OPERATIONS.productsReviewsSubmit]: "never",
+    [STOREFRONT_OPERATIONS.productsReviewsEligibility]: "never",
+    [STOREFRONT_OPERATIONS.productsReviewsUpload]: "never",
     [STOREFRONT_OPERATIONS.shippingRate]: "safe-read",
     [STOREFRONT_OPERATIONS.shippingRates]: "safe-read",
 };

package/dist/endpoints/proxy.d.ts

@@ -38,8 +38,14 @@ export type ProxyClientFn<TInput, TOutput> = (data: TInput, headers?: Record<str
  * Configuration for creating a proxy endpoint
  */
 export interface ProxyEndpointConfig<TInput, TOutput> {
-    /** HTTP method: 'GET' or 'POST' */
-    method: "GET" | "POST";
+    /** HTTP method: 'GET', 'POST', or 'PUT' (a raw body, read by `readInput`). */
+    method: "GET" | "POST" | "PUT";
+    /**
+     * Read the input from the request instead of parsing JSON — for a body that
+     * is a file, passed on as a stream. Its result still goes through
+     * `inputSchema`.
+     */
+    readInput?: (request: Request) => unknown;
     /** Client function that calls the server — usually a `StoreClient` method. */
     client: ProxyClientFn<TInput, TOutput>;
     /** Input validation schema (optional for GET without query validation) */