@wocart/storefront 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ 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.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
+
+- **`products.page(filters)`** returns one page of products and whether another
+  follows (`{ items, hasNext }`). It asks the server for one row more than the
+  page, so the answer is exact without a count query. A page is 24 by default
+  and at most 99 (one below the server's 100-row cap). A failed read is an empty
+  final page, as `list` degrades. Themes stop re-deriving paging from `list`.
+- `ProductPage` type.
+- **`rewardUnitPrice`** on an offer: what one gift unit is worth at list price
+  (the gift variant's price, or the gift product's). `getOfferTierView` states
+  the saving at that value and the share of the list value it is. Without it,
+  the product's own price stands in, as before.
+
 ## 1.4.0 — 2026-10-15
 
 ### Added

package/USAGE.md

@@ -624,19 +624,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
 
@@ -1179,11 +1224,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/products.d.ts

@@ -12,7 +12,11 @@
  * half-shaped product into a theme.
  */
 import { type ClientCore, type ClientResult } from "./core.js";
-import type { Product, ProductList, 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. */
+export declare const PRODUCT_PAGE_MAX = 99;
 export interface ProductsNamespace {
     /**
      * Get a single product by its public URL handle
@@ -26,6 +30,12 @@ export interface ProductsNamespace {
      * @returns Array of products
      */
     list(filters?: ProductListFilters): Promise<ProductList[]>;
+    /**
+     * One page of products, and whether another page follows. The server is
+     * asked for one row more than the page, so the answer is exact without a
+     * count query. A failed read is an empty final page, as `list` degrades.
+     */
+    page(filters?: ProductListFilters): Promise<ProductPage>;
     /**
      * Reviews sub-namespace
      */
@@ -41,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`.
+         */
+        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<{
-            id: string;
-        }>>;
+        submit(data: ReviewInput): Promise<ClientResult<ReviewSubmitResult>>;
     };
 }
 /**

package/dist/client/products.js

@@ -12,14 +12,33 @@
  * 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";
+/** Page size when a caller names none — the storefront's default grid. */
+export const PRODUCT_PAGE_DEFAULT = 24;
+/** One below the server's 100-row cap, so the extra row that proves a next page fits. */
+export const PRODUCT_PAGE_MAX = 99;
 /**
  * Create products namespace
  */
 export function createProductsNamespace(core) {
+    const list = async (filters) => {
+        try {
+            const products = await core.get(localizedPath(core.config, "/store/products", {
+                categoryId: filters?.categoryId || undefined,
+                featured: filters?.featured ? "true" : undefined,
+                limit: filters?.limit === undefined ? undefined : String(filters.limit),
+                offset: filters?.offset ? String(filters.offset) : undefined,
+            }), z.array(ProductListSchema), { operation: STOREFRONT_OPERATIONS.productsList });
+            return products ?? [];
+        }
+        catch (error) {
+            reportDegradedRead(core.config, error, "products.list");
+            return [];
+        }
+    };
     return {
         async get(handle) {
             try {
@@ -32,20 +51,11 @@ export function createProductsNamespace(core) {
                 return null;
             }
         },
-        async list(filters) {
-            try {
-                const products = await core.get(localizedPath(core.config, "/store/products", {
-                    categoryId: filters?.categoryId || undefined,
-                    featured: filters?.featured ? "true" : undefined,
-                    limit: filters?.limit === undefined ? undefined : String(filters.limit),
-                    offset: filters?.offset ? String(filters.offset) : undefined,
-                }), z.array(ProductListSchema), { operation: STOREFRONT_OPERATIONS.productsList });
-                return products ?? [];
-            }
-            catch (error) {
-                reportDegradedRead(core.config, error, "products.list");
-                return [];
-            }
+        list,
+        async page(filters) {
+            const size = Math.min(Math.max(1, filters?.limit ?? PRODUCT_PAGE_DEFAULT), PRODUCT_PAGE_MAX);
+            const rows = await list({ ...filters, limit: size + 1 });
+            return { items: rows.slice(0, size), hasNext: rows.length > size };
         },
         reviews: {
             async list(productId, pagination) {
@@ -71,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,6 +349,8 @@ 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 shippingRates: "shipping.rates";
@@ -392,6 +394,8 @@ export declare const STOREFRONT_RETRY_POLICIES: {
     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,6 +202,8 @@ 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",
     shippingRates: "shipping.rates",
@@ -244,6 +246,8 @@ export const STOREFRONT_RETRY_POLICIES = {
     [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) */

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, successBody, noContent = false, } = config;
+    const { method, client, inputSchema, queryParams = [], pathParams = {}, csrfProtection = method !== "GET", readInput, forwardAttribution = false, successStatus = 200, errorStatus, successBody, noContent = false, } = config;
     return async (context) => {
         const { request, params } = context;
         // CSRF Protection: reject cross-origin requests
@@ -41,7 +41,10 @@ export function createProxyEndpoint(config) {
         // Parse input based on method
         let input;
         try {
-            if (method === "GET") {
+            if (readInput) {
+                input = readInput(request);
+            }
+            else if (method === "GET") {
                 input = parseGetInput(request, params, queryParams, pathParams);
             }
             else {

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

@@ -1,9 +1,10 @@
 /**
  * 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
+ * Every theme needs the same 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, find the order, send a
+ * photo or voice note, 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
@@ -47,7 +48,15 @@ export interface StorefrontRoutes<C extends AstroAPIContext> {
     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 } }`. */
+    /** POST `{ orderNumber, phone, turnstileToken? }` → `{ data: ReviewEligibility }`. */
+    readonly reviewEligibility: StorefrontApiRoute<C>;
+    /**
+     * PUT one file as the body, the grant in `X-Review-Grant` (and a voice
+     * note's length in `X-Media-Duration-Ms`) → 201 `{ data: ReviewUpload }`.
+     * The file streams on to the server unbuffered.
+     */
+    readonly reviewUpload: StorefrontApiRoute<C>;
+    /** POST a `ReviewInput` → 201 `{ success: true, data: { id, visibility } }`. */
     readonly reviewSubmit: StorefrontApiRoute<C>;
 }
 export declare const REVIEWS_PAGE_DEFAULT = 20;

package/dist/endpoints/storefront-routes.js

@@ -1,9 +1,10 @@
 /**
  * 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
+ * Every theme needs the same 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, find the order, send a
+ * photo or voice note, 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
@@ -65,11 +66,40 @@ const reviewsListInput = z.object({
  */
 const reviewSubmitInput = z.object({
     orderNumber: z.string().min(1).max(64),
+    phone: z.string().min(1).max(32).optional(),
     productId: z.string().min(1).max(200),
     rating: z.number(),
     title: z.string().max(500).optional(),
     body: z.string().max(5000),
+    grant: z.string().min(1).max(2048).optional(),
+    uploads: z.array(z.string().min(1).max(64)).max(8).optional(),
 });
+const reviewEligibilityInput = z.object({
+    orderNumber: z.string().min(1).max(64),
+    phone: z.string().min(1).max(32),
+    turnstileToken: z.string().min(1).max(2048).optional(),
+});
+/** The file itself stays a stream; only the headers around it are checked here. */
+const reviewUploadInput = z.object({
+    body: z.custom((value) => value instanceof ReadableStream, "No file was sent"),
+    grant: z.string().min(1).max(2048),
+    contentLength: z.number().int().positive().optional(),
+    durationMs: z.number().int().positive().max(600_000).optional(),
+});
+function readUpload(request) {
+    const length = Number(request.headers.get("Content-Length"));
+    const duration = Number(request.headers.get("X-Media-Duration-Ms"));
+    return {
+        body: request.body,
+        grant: request.headers.get("X-Review-Grant") ?? "",
+        ...(Number.isInteger(length) && length > 0 ? { contentLength: length } : {}),
+        ...(Number.isInteger(duration) && duration > 0 ? { durationMs: duration } : {}),
+    };
+}
+/** Drops the keys a form left undefined: the client's input type is exact. */
+function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
 export function createStorefrontRoutes(options) {
     const route = (config) => async (context) => {
         const { call, ...endpoint } = config;
@@ -130,12 +160,24 @@ export function createStorefrontRoutes(options) {
                 data: await client.products.reviews.list(productId, { limit, offset }),
             }),
         }),
+        reviewEligibility: route({
+            method: "POST",
+            inputSchema: reviewEligibilityInput,
+            call: (client, input) => client.products.reviews.eligibility(defined(input)),
+        }),
+        reviewUpload: route({
+            method: "PUT",
+            readInput: readUpload,
+            inputSchema: reviewUploadInput,
+            successStatus: 201,
+            call: (client, input) => client.products.reviews.upload(defined(input)),
+        }),
         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 }),
+            call: (client, review) => client.products.reviews.submit(defined(review)),
         }),
     };
 }

package/dist/offer-view.d.ts

@@ -6,5 +6,5 @@ export interface OfferTierView {
     price: number;
     comparePrice: number | null;
 }
-export type OfferTierInput = Pick<Offer, "discountType" | "triggerQuantity" | "rewardQuantity">;
+export type OfferTierInput = Pick<Offer, "discountType" | "triggerQuantity" | "rewardQuantity" | "rewardUnitPrice">;
 export declare function getOfferTierView(offer: OfferTierInput, basePrice: number, comparePrice: number | null): OfferTierView;

package/dist/offer-view.js

@@ -1,13 +1,17 @@
 export function getOfferTierView(offer, basePrice, comparePrice) {
     const isFreeShipping = offer.discountType === "free_shipping";
-    const quantityTotal = offer.triggerQuantity + offer.rewardQuantity;
+    // A gift that is another product (or a variant priced apart) is worth its own
+    // price; without one, the product's price stands in for it.
+    const giftPrice = offer.rewardUnitPrice ?? basePrice;
+    const savingsAmount = isFreeShipping ? 0 : offer.rewardQuantity * giftPrice;
+    const price = basePrice * offer.triggerQuantity;
+    // The share of what the shopper would have paid for everything, gifts included.
+    const listValue = price + savingsAmount;
     return {
         isFreeShipping,
-        savePct: isFreeShipping || quantityTotal <= 0
-            ? 0
-            : Math.round((offer.rewardQuantity / quantityTotal) * 100),
-        savingsAmount: isFreeShipping ? 0 : offer.rewardQuantity * basePrice,
-        price: basePrice * offer.triggerQuantity,
+        savePct: isFreeShipping || listValue <= 0 ? 0 : Math.round((savingsAmount / listValue) * 100),
+        savingsAmount,
+        price,
         comparePrice: comparePrice === null ? null : comparePrice * offer.triggerQuantity,
     };
 }

package/dist/review-media.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `@wocart/storefront/review-media` — what a theme's review form does in the
+ * browser before a photo or a voice note is sent, so it arrives small on a
+ * slow mobile connection:
+ *
+ *   prepareReviewPhoto   shrinks a photo to 1600 px at most and re-encodes it
+ *                        (WebP, else JPEG) — a phone photo of several MB
+ *                        becomes a few hundred KB, and its EXIF (the phone's
+ *                        location) is gone before it leaves the device
+ *   createVoiceRecorder  records speech at a low bitrate in what the phone
+ *                        records (WebM/Opus, MP4/AAC on iPhone), and stops by
+ *                        itself at the store's limit
+ *
+ * Browser-only, and kept off the main entry point: a theme that takes no
+ * media pays nothing for it. Each takes its browser dependencies as an
+ * optional last argument, for tests and unusual hosts.
+ */
+export interface PhotoOptions {
+    /** Longest edge in pixels. Default 1600 (what the server keeps). */
+    maxEdge?: number;
+    /** Encoder quality, 0–1. Default 0.82. */
+    quality?: number;
+}
+/** The size a photo is drawn at: its own, or scaled so its longest edge is `maxEdge`. */
+export declare function photoTargetSize(width: number, height: number, maxEdge: number): {
+    width: number;
+    height: number;
+};
+export interface PhotoDeps {
+    createImageBitmap: (image: Blob, options?: ImageBitmapOptions) => Promise<ImageBitmap>;
+    /** A canvas of the given size that can encode itself. */
+    createCanvas: (width: number, height: number) => {
+        getContext(type: "2d"): Pick<CanvasRenderingContext2D, "drawImage"> | null;
+        toBlob(type: string, quality: number): Promise<Blob | null>;
+    };
+}
+/**
+ * A photo ready to send: drawn upright (the camera's orientation applied),
+ * no larger than `maxEdge`, re-encoded as WebP (JPEG where WebP cannot be
+ * written). When the browser cannot do it, the photo is sent as it is — the
+ * server still converts it and drops its EXIF.
+ */
+export declare function prepareReviewPhoto(photo: Blob, options?: PhotoOptions, deps?: PhotoDeps | null): Promise<Blob>;
+/** Formats in the order a recorder is tried: Opus where it can be written, AAC on iPhone. */
+export declare const VOICE_MIME_TYPES: readonly ["audio/webm;codecs=opus", "audio/ogg;codecs=opus", "audio/mp4;codecs=mp4a.40.2", "audio/mp4", "audio/webm"];
+/** The first format this browser can record, or null when it cannot record voice. */
+export declare function pickVoiceMimeType(isTypeSupported: (type: string) => boolean): string | null;
+export interface RecordedVoice {
+    blob: Blob;
+    /** As measured while recording; send it with the upload. */
+    durationMs: number;
+    mimeType: string;
+}
+export interface VoiceRecorderOptions {
+    /** Stops by itself after this many seconds (the store's limit). */
+    maxSeconds: number;
+    /** About every 250 ms while recording, with the time recorded so far. */
+    onTick?: (elapsedMs: number) => void;
+    /** When it stopped by itself at the limit. */
+    onLimit?: (voice: RecordedVoice) => void;
+}
+export interface VoiceRecorder {
+    /** Asks for the microphone and starts. Rejects when it is refused or unavailable. */
+    start(): Promise<void>;
+    /** Stops and gives the recording. */
+    stop(): Promise<RecordedVoice>;
+    /** Stops and throws the recording away. */
+    cancel(): void;
+    readonly state: "idle" | "recording" | "stopped";
+}
+export interface VoiceDeps {
+    getUserMedia: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    MediaRecorder: {
+        new (stream: MediaStream, options?: MediaRecorderOptions): MediaRecorder;
+        isTypeSupported(type: string): boolean;
+    };
+    now: () => number;
+    setInterval: (fn: () => void, ms: number) => unknown;
+    clearInterval: (id: unknown) => void;
+}
+/** Whether this browser can record a voice note at all (hide the record button when not). */
+export declare function canRecordVoice(deps?: VoiceDeps | null): boolean;
+/**
+ * A recorder for one voice note: speech at about 32 kb/s, mono, with the
+ * phone's echo cancellation and noise suppression — 60 s is about 240 KB.
+ */
+export declare function createVoiceRecorder(options: VoiceRecorderOptions, deps?: VoiceDeps | null): VoiceRecorder;

package/dist/review-media.js

@@ -0,0 +1,182 @@
+/**
+ * `@wocart/storefront/review-media` — what a theme's review form does in the
+ * browser before a photo or a voice note is sent, so it arrives small on a
+ * slow mobile connection:
+ *
+ *   prepareReviewPhoto   shrinks a photo to 1600 px at most and re-encodes it
+ *                        (WebP, else JPEG) — a phone photo of several MB
+ *                        becomes a few hundred KB, and its EXIF (the phone's
+ *                        location) is gone before it leaves the device
+ *   createVoiceRecorder  records speech at a low bitrate in what the phone
+ *                        records (WebM/Opus, MP4/AAC on iPhone), and stops by
+ *                        itself at the store's limit
+ *
+ * Browser-only, and kept off the main entry point: a theme that takes no
+ * media pays nothing for it. Each takes its browser dependencies as an
+ * optional last argument, for tests and unusual hosts.
+ */
+/** The size a photo is drawn at: its own, or scaled so its longest edge is `maxEdge`. */
+export function photoTargetSize(width, height, maxEdge) {
+    const longest = Math.max(width, height);
+    if (longest <= maxEdge || longest === 0)
+        return { width, height };
+    const scale = maxEdge / longest;
+    return { width: Math.max(1, Math.round(width * scale)), height: Math.max(1, Math.round(height * scale)) };
+}
+function browserPhotoDeps() {
+    if (typeof createImageBitmap !== "function" || typeof document === "undefined")
+        return null;
+    return {
+        createImageBitmap: (image, options) => createImageBitmap(image, options),
+        createCanvas: (width, height) => {
+            const canvas = document.createElement("canvas");
+            canvas.width = width;
+            canvas.height = height;
+            return {
+                getContext: () => canvas.getContext("2d"),
+                toBlob: (type, quality) => new Promise((resolve) => canvas.toBlob(resolve, type, quality)),
+            };
+        },
+    };
+}
+/**
+ * A photo ready to send: drawn upright (the camera's orientation applied),
+ * no larger than `maxEdge`, re-encoded as WebP (JPEG where WebP cannot be
+ * written). When the browser cannot do it, the photo is sent as it is — the
+ * server still converts it and drops its EXIF.
+ */
+export async function prepareReviewPhoto(photo, options = {}, deps = browserPhotoDeps()) {
+    if (!deps)
+        return photo;
+    const maxEdge = options.maxEdge ?? 1600;
+    const quality = options.quality ?? 0.82;
+    let bitmap;
+    try {
+        bitmap = await deps.createImageBitmap(photo, { imageOrientation: "from-image" });
+    }
+    catch {
+        return photo;
+    }
+    try {
+        const size = photoTargetSize(bitmap.width, bitmap.height, maxEdge);
+        const canvas = deps.createCanvas(size.width, size.height);
+        const context = canvas.getContext("2d");
+        if (!context)
+            return photo;
+        context.drawImage(bitmap, 0, 0, size.width, size.height);
+        for (const type of ["image/webp", "image/jpeg"]) {
+            const blob = await canvas.toBlob(type, quality);
+            if (blob && blob.type === type && blob.size > 0)
+                return blob;
+        }
+        return photo;
+    }
+    catch {
+        return photo;
+    }
+    finally {
+        bitmap.close?.();
+    }
+}
+/** Formats in the order a recorder is tried: Opus where it can be written, AAC on iPhone. */
+export const VOICE_MIME_TYPES = ["audio/webm;codecs=opus", "audio/ogg;codecs=opus", "audio/mp4;codecs=mp4a.40.2", "audio/mp4", "audio/webm"];
+/** The first format this browser can record, or null when it cannot record voice. */
+export function pickVoiceMimeType(isTypeSupported) {
+    return VOICE_MIME_TYPES.find((type) => {
+        try {
+            return isTypeSupported(type);
+        }
+        catch {
+            return false;
+        }
+    }) ?? null;
+}
+function browserVoiceDeps() {
+    if (typeof navigator === "undefined" || !navigator.mediaDevices?.getUserMedia || typeof MediaRecorder === "undefined")
+        return null;
+    return {
+        getUserMedia: (constraints) => navigator.mediaDevices.getUserMedia(constraints),
+        MediaRecorder,
+        now: () => performance.now(),
+        setInterval: (fn, ms) => setInterval(fn, ms),
+        clearInterval: (id) => clearInterval(id),
+    };
+}
+/** Whether this browser can record a voice note at all (hide the record button when not). */
+export function canRecordVoice(deps = browserVoiceDeps()) {
+    return Boolean(deps && pickVoiceMimeType((type) => deps.MediaRecorder.isTypeSupported(type)));
+}
+/**
+ * A recorder for one voice note: speech at about 32 kb/s, mono, with the
+ * phone's echo cancellation and noise suppression — 60 s is about 240 KB.
+ */
+export function createVoiceRecorder(options, deps = browserVoiceDeps()) {
+    let state = "idle";
+    let recorder = null;
+    let stream = null;
+    let chunks = [];
+    let startedAt = 0;
+    let ticker = null;
+    let finished = null;
+    const release = () => {
+        if (ticker !== null)
+            deps?.clearInterval(ticker);
+        ticker = null;
+        stream?.getTracks().forEach((track) => track.stop());
+        stream = null;
+    };
+    return {
+        get state() {
+            return state;
+        },
+        async start() {
+            if (!deps)
+                throw new Error("This browser cannot record voice notes");
+            if (state === "recording")
+                return;
+            const mimeType = pickVoiceMimeType((type) => deps.MediaRecorder.isTypeSupported(type));
+            if (!mimeType)
+                throw new Error("This browser cannot record voice notes");
+            stream = await deps.getUserMedia({ audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true } });
+            chunks = [];
+            recorder = new deps.MediaRecorder(stream, { mimeType, audioBitsPerSecond: 32_000 });
+            const active = recorder;
+            finished = new Promise((resolve) => {
+                active.ondataavailable = (event) => {
+                    if (event.data.size > 0)
+                        chunks.push(event.data);
+                };
+                active.onstop = () => {
+                    const type = (active.mimeType || mimeType).split(";")[0];
+                    resolve({ blob: new Blob(chunks, { type }), durationMs: Math.round(deps.now() - startedAt), mimeType: type });
+                };
+            });
+            startedAt = deps.now();
+            recorder.start(1000);
+            state = "recording";
+            ticker = deps.setInterval(() => {
+                const elapsed = deps.now() - startedAt;
+                options.onTick?.(elapsed);
+                if (elapsed >= options.maxSeconds * 1000 && state === "recording") {
+                    void this.stop().then((voice) => options.onLimit?.(voice));
+                }
+            }, 250);
+        },
+        async stop() {
+            if (state !== "recording" || !recorder || !finished)
+                throw new Error("Not recording");
+            state = "stopped";
+            recorder.stop();
+            const voice = await finished;
+            release();
+            return voice;
+        },
+        cancel() {
+            if (recorder && state === "recording")
+                recorder.stop();
+            state = "stopped";
+            chunks = [];
+            release();
+        },
+    };
+}

package/dist/schemas.d.ts

@@ -41,6 +41,7 @@ export declare const OfferSchema: z.ZodObject<{
     rewardProductName: z.ZodString;
     rewardVariantId: z.ZodNullable<z.ZodString>;
     rewardVariantLabel: z.ZodNullable<z.ZodString>;
+    rewardUnitPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 export declare const CategorySchema: z.ZodObject<{
     id: z.ZodString;
@@ -88,7 +89,7 @@ export declare const ProductListSchema: z.ZodObject<{
     }>;
     showInStore: z.ZodBoolean;
     storeFeatured: z.ZodBoolean;
-    deletedAt: z.ZodNullable<z.ZodString>;
+    deletedAt: z.ZodOptional<z.ZodNull>;
     publishedAt: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
@@ -141,7 +142,7 @@ export declare const ProductSchema: z.ZodObject<{
     }>;
     showInStore: z.ZodBoolean;
     storeFeatured: z.ZodBoolean;
-    deletedAt: z.ZodNullable<z.ZodString>;
+    deletedAt: z.ZodOptional<z.ZodNull>;
     publishedAt: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
@@ -214,6 +215,7 @@ export declare const ProductSchema: z.ZodObject<{
         rewardProductName: z.ZodString;
         rewardVariantId: z.ZodNullable<z.ZodString>;
         rewardVariantLabel: z.ZodNullable<z.ZodString>;
+        rewardUnitPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const StorePagePublicSchema: z.ZodObject<{
@@ -544,7 +546,7 @@ export declare const LandingPageSchema: z.ZodObject<{
         }>;
         showInStore: z.ZodBoolean;
         storeFeatured: z.ZodBoolean;
-        deletedAt: z.ZodNullable<z.ZodString>;
+        deletedAt: z.ZodOptional<z.ZodNull>;
         publishedAt: z.ZodNullable<z.ZodString>;
         createdAt: z.ZodString;
         updatedAt: z.ZodString;
@@ -617,6 +619,7 @@ export declare const LandingPageSchema: z.ZodObject<{
             rewardProductName: z.ZodString;
             rewardVariantId: z.ZodNullable<z.ZodString>;
             rewardVariantLabel: z.ZodNullable<z.ZodString>;
+            rewardUnitPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     tracking: z.ZodObject<{
@@ -737,6 +740,18 @@ export declare const OtpVerifyResultSchema: z.ZodObject<{
     status: z.ZodLiteral<"verified">;
     otpToken: z.ZodString;
 }, z.core.$strip>;
+export declare const ReviewMediaSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        audio: "audio";
+        image: "image";
+    }>;
+    url: z.ZodString;
+    thumbUrl: z.ZodNullable<z.ZodString>;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
 export declare const ReviewSchema: z.ZodPreprocess<z.ZodObject<{
     id: z.ZodString;
     customerName: z.ZodString;
@@ -744,7 +759,51 @@ export declare const ReviewSchema: z.ZodPreprocess<z.ZodObject<{
     title: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
     body: z.ZodString;
     createdAt: z.ZodString;
+    verified: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    media: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            audio: "audio";
+            image: "image";
+        }>;
+        url: z.ZodString;
+        thumbUrl: z.ZodNullable<z.ZodString>;
+        width: z.ZodNullable<z.ZodNumber>;
+        height: z.ZodNullable<z.ZodNumber>;
+        durationMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>>>;
 }, z.core.$strip>, unknown>;
+export declare const ReviewEligibilitySchema: z.ZodObject<{
+    orderNumber: z.ZodString;
+    customerName: z.ZodString;
+    products: z.ZodArray<z.ZodObject<{
+        productId: z.ZodString;
+        name: z.ZodString;
+        imageSrc: z.ZodNullable<z.ZodString>;
+        reviewed: z.ZodBoolean;
+    }, z.core.$strip>>;
+    media: z.ZodNullable<z.ZodObject<{
+        maxPhotos: z.ZodNumber;
+        voiceMaxSeconds: z.ZodNullable<z.ZodNumber>;
+        grant: z.ZodString;
+        expiresAt: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ReviewUploadSchema: z.ZodObject<{
+    uploadId: z.ZodString;
+    kind: z.ZodEnum<{
+        audio: "audio";
+        image: "image";
+    }>;
+    bytes: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ReviewSubmitResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        after_review: "after_review";
+        published: "published";
+    }>>;
+}, z.core.$strip>;
 /**
  * GET /store/reviews answers `{ success, data: rows, count, total }` — the
  * total lives OUTSIDE `data`, so a caller that reads only `data` loses it.
@@ -757,6 +816,19 @@ export declare const ReviewListEnvelopeSchema: z.ZodObject<{
         title: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
         body: z.ZodString;
         createdAt: z.ZodString;
+        verified: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        media: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                audio: "audio";
+                image: "image";
+            }>;
+            url: z.ZodString;
+            thumbUrl: z.ZodNullable<z.ZodString>;
+            width: z.ZodNullable<z.ZodNumber>;
+            height: z.ZodNullable<z.ZodNumber>;
+            durationMs: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>>>;
     }, z.core.$strip>, unknown>>;
     total: z.ZodNumber;
 }, z.core.$strip>;

package/dist/schemas.js

@@ -38,6 +38,9 @@ export const OfferSchema = z.object({
     rewardProductName: z.string(),
     rewardVariantId: z.string().nullable(),
     rewardVariantLabel: z.string().nullable(),
+    // What one gift unit is worth at list price. Optional: a server that predates
+    // it omits the field, and the product's own price stands in for the gift.
+    rewardUnitPrice: z.number().nullish(),
 });
 const productCategorySchema = z.object({
     id: z.string(),
@@ -80,7 +83,12 @@ const productBaseFields = {
     status: z.enum(["DRAFT", "ACTIVE", "ARCHIVED"]),
     showInStore: z.boolean(),
     storeFeatured: z.boolean(),
-    deletedAt: z.string().datetime().nullable(),
+    /**
+     * @deprecated Always null: the server never serves a removed product. The
+     * server still sends it for older releases; it will stop, and a later major
+     * drops it. Do not read it.
+     */
+    deletedAt: z.null().optional(),
     publishedAt: z.string().datetime().nullable(),
     createdAt: z.string().datetime(),
     updatedAt: z.string().datetime(),
@@ -356,6 +364,15 @@ export const OtpVerifyResultSchema = z.object({
     status: z.literal("verified"),
     otpToken: z.string(),
 });
+export const ReviewMediaSchema = z.object({
+    id: z.string(),
+    kind: z.enum(["image", "audio"]),
+    url: z.string(),
+    thumbUrl: z.string().nullable(),
+    width: z.number().int().nullable(),
+    height: z.number().int().nullable(),
+    durationMs: z.number().int().nullable(),
+});
 export const ReviewSchema = z.preprocess((raw) => {
     if (typeof raw === "object" && raw !== null) {
         const obj = raw;
@@ -372,7 +389,36 @@ export const ReviewSchema = z.preprocess((raw) => {
     title: z.string().nullable().optional().default(null),
     body: z.string(),
     createdAt: z.string(),
+    verified: z.boolean().optional().default(false),
+    media: z.array(ReviewMediaSchema).optional().default([]),
 }));
+export const ReviewEligibilitySchema = z.object({
+    orderNumber: z.string(),
+    customerName: z.string(),
+    products: z.array(z.object({
+        productId: z.string(),
+        name: z.string(),
+        imageSrc: z.string().nullable(),
+        reviewed: z.boolean(),
+    })),
+    media: z
+        .object({
+        maxPhotos: z.number().int().min(0),
+        voiceMaxSeconds: z.number().int().positive().nullable(),
+        grant: z.string().min(1),
+        expiresAt: z.number().int(),
+    })
+        .nullable(),
+});
+export const ReviewUploadSchema = z.object({
+    uploadId: z.string(),
+    kind: z.enum(["image", "audio"]),
+    bytes: z.number().int(),
+});
+export const ReviewSubmitResultSchema = z.object({
+    id: z.string(),
+    visibility: z.enum(["published", "after_review"]).optional(),
+});
 /**
  * GET /store/reviews answers `{ success, data: rows, count, total }` — the
  * total lives OUTSIDE `data`, so a caller that reads only `data` loses it.

package/dist/types.d.ts

@@ -395,6 +395,19 @@ export type OtpVerifyResult = {
     /** Signed, 15-min TTL, bound to the phone. Travels with the order. */
     otpToken: string;
 };
+/** A photo or the voice note of a review. */
+export interface ReviewMedia {
+    id: string;
+    kind: "image" | "audio";
+    /** A photo at 1600 px at most, or the voice note as recorded. */
+    url: string;
+    /** A photo's 480 px version for lists; null for a voice note. */
+    thumbUrl: string | null;
+    width: number | null;
+    height: number | null;
+    /** A voice note's length, when known. */
+    durationMs: number | null;
+}
 export interface Review {
     id: string;
     customerName: string;
@@ -402,6 +415,50 @@ export interface Review {
     title: string | null;
     body: string;
     createdAt: string;
+    /** Rests on an order that reached its customer: show it as a verified purchase. */
+    verified: boolean;
+    /** Photos first, then the voice note. Empty from servers before 1.6. */
+    media: ReviewMedia[];
+}
+/** One product of the shopper's order, as `products.reviews.eligibility()` answers it. */
+export interface ReviewableProduct {
+    productId: string;
+    name: string;
+    imageSrc: string | null;
+    /** Already reviewed from this order: show it, but it cannot be reviewed again. */
+    reviewed: boolean;
+}
+/**
+ * What a shopper's order lets them review, once its number and phone proved
+ * the purchase — and, when the store takes them, what they may attach.
+ */
+export interface ReviewEligibility {
+    orderNumber: string;
+    customerName: string;
+    products: ReviewableProduct[];
+    /** null: text only. */
+    media: {
+        /** 0: no photos. */
+        maxPhotos: number;
+        /** null: no voice note. */
+        voiceMaxSeconds: number | null;
+        /** Send with each upload and with the review. Lasts until `expiresAt`. */
+        grant: string;
+        /** Unix seconds. */
+        expiresAt: number;
+    } | null;
+}
+/** A photo or voice note the server received for a review not yet submitted. */
+export interface ReviewUpload {
+    uploadId: string;
+    kind: "image" | "audio";
+    bytes: number;
+}
+/** What a submitted review answers: published now, or after the store checks it. */
+export interface ReviewSubmitResult {
+    id: string;
+    /** Absent from servers before 1.6. */
+    visibility?: "published" | "after_review" | undefined;
 }
 /**
  * Filters `products.list()` accepts — named so a theme can type its own
@@ -415,21 +472,54 @@ export interface ProductListFilters {
     /** Products to skip — with `limit`, pages through the whole catalog. */
     offset?: number;
 }
+/** One page of products from `products.page()`. */
+export interface ProductPage {
+    items: ProductList[];
+    /** True when another page follows this one. */
+    hasNext: boolean;
+}
 /** `products.reviews.list()` paging — named for the same reason. */
 export interface ReviewListPagination {
     limit?: number;
     offset?: number;
 }
 /**
- * The body `products.reviews.submit()` accepts: the order number is the proof
- * of purchase, and the server owns every other rule (moderation, one-review
- * per order line).
+ * The body `products.reviews.submit()` accepts: the order number and the phone
+ * it was placed with prove the purchase, and the server owns every other rule
+ * (a delivered order, one review per product of it, moderation).
  */
 export interface ReviewInput {
     orderNumber: string;
+    /**
+     * The phone the order was placed with. Without it (the 1.5 shape) a review
+     * is text only and still needs a delivered order.
+     * @deprecated Omitting it is deprecated; a later major requires it.
+     */
+    phone?: string;
     productId: string;
     /** 1–5, the server validates the range. */
     rating: number;
     title?: string;
+    /** At least 10 characters, unless a voice note is attached. */
     body: string;
+    /** The grant from `eligibility()`, when files are attached. */
+    grant?: string;
+    /** `uploadId`s from `upload()`. */
+    uploads?: string[];
+}
+/** What `products.reviews.eligibility()` sends. */
+export interface ReviewEligibilityInput {
+    orderNumber: string;
+    phone: string;
+    /** Required when the store has Turnstile on. */
+    turnstileToken?: string;
+}
+/** What `products.reviews.upload()` sends: one file, as it is. */
+export interface ReviewUploadInput {
+    grant: string;
+    body: Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>;
+    /** Its size, when known: lets the server refuse a file too large before it arrives. */
+    contentLength?: number;
+    /** A voice note's length as the recorder reported it. */
+    durationMs?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/storefront",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",
@@ -41,6 +41,10 @@
       "types": "./dist/astro.d.ts",
       "default": "./dist/astro.js"
     },
+    "./review-media": {
+      "types": "./dist/review-media.d.ts",
+      "default": "./dist/review-media.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [