@base44/app-plugin-commerce 0.6.8 → 0.6.10

package/base44/entities/commerce.ProductReview.jsonc

@@ -24,7 +24,7 @@
     },
     "review": {
       "type": "string",
-      "description": "Review content"
+      "description": "Review text. May be empty for a stars-only review (submit-review requires text or a rating, not both)."
     },
     "rating": {
       "type": "integer",
@@ -38,7 +38,7 @@
       "description": "Derived: reviewer purchased the product. Set by commerce/storefront-catalog submit-review."
     }
   },
-  "required": ["product_id", "review"],
+  "required": ["product_id"],
   "rls": {
     "read": { "user_condition": { "role": "admin" } },
     "create": { "user_condition": { "role": "admin" } },

package/base44/functions/commerce/storefront-catalog/entry.ts

@@ -396,12 +396,16 @@ async function submitReview(sr: any, p: any, user: any): Promise<any> {
   const review = String(p.review ?? "").trim();
   const rating = p.rating == null ? null : Math.floor(Number(p.rating));
 
-  if (!review) {
-    throw new HttpError(400, "review is required.", "review_incomplete");
-  }
   if (rating != null && (rating < 0 || rating > 5)) {
     throw new HttpError(400, "Rating must be between 0 and 5.", "invalid_rating");
   }
+  // Text or stars — either alone is a valid review. Requiring text rejected
+  // every stars-only submission from a form that treats the write-up as
+  // optional, with a 400 the customer can't act on. Rating 0 is "unrated"
+  // (the aggregates ignore it), so it can't stand in for the missing text.
+  if (!review && !(rating != null && rating >= 1)) {
+    throw new HttpError(400, "A review needs text or a star rating.", "review_incomplete");
+  }
 
   const verified = await hasPurchased(sr, reviewerEmail, product.id);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/skills/commerce/SKILL.md

@@ -118,7 +118,7 @@ batch (above).
 | Topic | Open when | Size |
 |---|---|---|
 | [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 6K |
-| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 36K |
+| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 37K |
 | [`install/03-data.md`](./install/03-data.md) | seeding catalog, shipping rates/zones, payments; re-callable per slice | 11K |
 | [`docs/entities.md`](./docs/entities.md) | any direct entity read/write ("which entity holds X") | 11K |
 | [`references/catalog-rendering.md`](./references/catalog-rendering.md) | field shapes each catalog call returns, variant edge cases | 16K |

package/skills/commerce/docs/api-storefront.md

@@ -114,14 +114,14 @@ This is the **only** way a storefront can enumerate ribbons (the entity is admin
 No payload. Returns `{ "attributes": [ { ...attribute, "terms": [ ...values ] } ] }` — each attribute (`id, name, code, order`) with its values (`id, attribute_id, name, order, count`), both sorted by `order`; for filter UIs. Filter with `list-products` `attribute_id` (id or attribute **name**) + `attribute_term` (the value name); `code` is the stable key for a URL.
 
 ### `submit-review`
-**Payload:** `{ product_id, email?, reviewer?, review, rating? }` — `email` is required for guests (`400 email_required`); a signed-in caller's session email always wins.
+**Payload:** `{ product_id, email?, reviewer?, review?, rating? }` — at least one of `review` (text) or `rating` (1–5); `email` is required for guests (`400 email_required`); a signed-in caller's session email always wins.
 
 > A React storefront reaches this call as `submitReview` (and the paginated list as `getProductReviews`) on the client from `@/commerce/storefront`'s `useStorefront()`, with the list itself already riding along on the product; policies and moderation are [`../references/reviews.md`](../references/reviews.md). Read on for the raw contract.
 
-**Public by default: anyone can review with an email address — no login.** A guest passes `email`; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only, defaulting to the account's `full_name` then the email's local part. `rating` is optional (0–5). `verified` is derived from the email's order history. Status is `hold` unless `products.auto_approve_reviews` — the one server-side switch, so a hardcoded "awaiting approval" message is wrong when it is on. Stricter policies (login-gated, verified buyers only, rating required) are the storefront's own gate around this call — the server accepts any valid email: [`../references/reviews.md`](../references/reviews.md).
+**Public by default: anyone can review with an email address — no login.** A guest passes `email`; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only, defaulting to the account's `full_name` then the email's local part. **Text or stars — either alone is valid**: `rating` is 0–5 (0 = unrated, so a stars-only submission needs 1–5); `review_incomplete` fires only when both are missing. `verified` is derived from the email's order history. Status is `hold` unless `products.auto_approve_reviews` — the one server-side switch, so a hardcoded "awaiting approval" message is wrong when it is on. Stricter policies (login-gated, verified buyers only, rating required) are the storefront's own gate around this call — the server accepts any valid email: [`../references/reviews.md`](../references/reviews.md).
 
 **Response:** `{ "review_id", "status": "hold"|"approved", "verified": true }`
-**Errors:** `404 not_found`, `400 email_required|review_incomplete|invalid_rating`.
+**Errors:** `404 not_found`, `400 email_required|review_incomplete` (neither text nor stars)`|invalid_rating`.
 
 ---
 

package/skills/commerce/install/02-storefront.md

@@ -116,7 +116,7 @@ import { useProductList, useCategories, useStoreInfo, useFormatMoney, productPri
 
 ⚑ **Render paging whenever `hasNext` is true** — `{list.hasNext && <button type="button" onClick={list.next} disabled={list.busy}>…</button>}` (append mode: `list.loadMore`); a page that renders nothing for paging ships a catalog silently capped at `per_page`. Drive filters from `useCategories()`/`useRibbons()` data via `setParams`, never from hardcoded names — a renamed ribbon must not strand a dead button.
 
-A card can render `name`, `productImages(row)[0]`, `productPrice(row, { formatMoney }).label` (already "From €19.99" when the product sells variants — there is no product `type` flag, and `product.price` alone is a rolled-up from-price), `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count`, `productRibbons(row)`, `productSpecs(row)`. ⚑ **Images and ribbons are objects, either may be empty** — render your placeholder, never a broken `<img>` or a raw object. Field matrix: [`../references/catalog-rendering.md`](../references/catalog-rendering.md). That list is an inventory, not a card design and not an order to render in. An even grid of identical cards, each carrying the same name/price/stars trio, is where a generated store lands by default and almost never where this catalog belongs: give the grid a rhythm (a hero piece spanning two columns, an editorial break between rows, a denser tile for a large catalog), and lead each card with the one or two fields *these* products are judged on — carat weight, focal length, edition size, ABV — read off `productSpecs(row)`, not the fields every store shows.
+A card can render `name`, `productImages(row)[0]`, `productPrice(row, { formatMoney }).label` (already "From €19.99" when the product sells variants — there is no product `type` flag, and `product.price` alone is a rolled-up from-price), `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count`, `productRibbons(row)`, `productSpecs(row)`. ⚑ **Images and ribbons are objects, either may be empty** — render your placeholder, never a broken `<img>` or a raw object. Field matrix: [`../references/catalog-rendering.md`](../references/catalog-rendering.md). That list is an inventory, not a card design and not an order to render in. An even grid of identical cards, each carrying the same name/price/stars trio, is where a generated store lands by default and almost never where this catalog belongs: give the grid a rhythm (a hero piece spanning two columns, an editorial break between rows, a denser tile for a large catalog), and lead each card with the one or two fields *these* products are judged on — carat weight, focal length, ABV — read off `productSpecs(row)`.
 
 ⚑ **Ribbons belong in both views** — grid and product page. They are the merchant's own merchandising ("Limited", "Last pieces"), and each links to its filtered listing (`/collection?ribbon_id=<id>`). `productRibbons(row)` hands you `{id, name}` **objects** — render `r.name`, key the link on `r.id`; the entry itself in JSX is React's "Objects are not valid as a React child". Never render a bare "Ribbons:" label with nothing after it. ⚑ **A ribbon link inside a card that is itself a link nests `<a>` in `<a>`** — invalid, React warns. In the grid use plain labels, or link the image and title rather than the whole card; keep ribbon links on the product page.
 
@@ -156,9 +156,13 @@ Build your layout from — all optional, **not one component style**:
 - **Variant selector** — `variantAxes(view, p.pick)`, one entry per axis:
 
   ```jsx
+  const SWATCH = { Ivory: "#F2EDE4", "Obsidian Black": "#101014" };   // this catalog's colour names → CSS
   {variantAxes(view, p.pick).map((axis) => (
     <fieldset key={axis.key}>{/* label from axis.name / axis.selectedOption */}
-      {axis.options.map((o) => (
+      {axis.options.map((o) => /colou?r/i.test(axis.name) ? (
+        <button key={o.value} disabled={o.disabled} aria-pressed={o.selected} onClick={o.pick}
+                className="swatch" style={{ background: SWATCH[o.value] }} title={o.value} aria-label={o.value} />
+      ) : (
         <button key={o.value} disabled={o.disabled} aria-pressed={o.selected} onClick={o.pick}>
           {o.value}{/* o.outOfStock → mark visibly */}
         </button>
@@ -167,7 +171,7 @@ Build your layout from — all optional, **not one component style**:
   ))}
   ```
 
-  ⚑ **One control per axis, never a list of variations**, and ⚑ **an unbuyable option renders `disabled`, never hidden** (`outOfStock` stays visible, just marked). `view.missingAxes` names what's unpicked. **Render each axis by what it is — pick the control per attribute**: a colour axis as colour circles with the name as a hint (a swatch alone leaves "Ivory" vs "Sand" unguessable), size chips with a size guide, a select for a long list — a specialty control where it genuinely fits, not on every axis; yet every axis as the identical chip row is a generated-page tell. Any control keeps the contract: disabled, out-of-stock marked, selection visible.
+  ⚑ **One control per axis, never a list of variations**, and ⚑ **an unbuyable option renders `disabled`, never hidden** (`outOfStock` stays visible, just marked). `view.missingAxes` names what's unpicked. ⚑ **Pick the control per attribute, as the branch above does**: a colour axis as colour circles (the name stays reachable — `title`, `aria-label`, and the axis label showing `selectedOption`), size chips beside a size guide, a select for a long list; a specialty control where it genuinely fits, not on every axis — but every axis as the same bare chip row is the flattest page this kit produces. Any control keeps the contract: disabled, out-of-stock marked, selection visible.
 - **Buy box** — one button, and **you supply its four words**:
 
   ```jsx
@@ -190,7 +194,15 @@ Build your layout from — all optional, **not one component style**:
 
   ⚑ **Never `.map()` the whole list into one grey label/value table** — that is the single most reliable tell of a generated product page. Design the two or three rows that carry *this* catalog's meaning as what they are (a weight set in the display face, a composition as bars, a provenance beside its place); let the rest fall through to the plain row, and don't feel obliged to keep them in one block — a spec can sit under the gallery, beside the price, or inside the description. Branch on `s.key` too where one particular modifier deserves its own treatment regardless of type. ⚑ **Look a spec up with `findSpec(rows, "care")`** (ignores case, spaces, `_`, `-`): meta keys are free text (`care`, `Care`, `Care Instructions`), so `rows.find(s => s.label === "Care")` silently never matches and renders the fallback forever. `[]` means no section at all.
 - **Breadcrumbs** — from `categories` (`/collection?category_id=${c.id}`); skip on a flat catalog. Ribbons (`productRibbons(product)`) are labels, not breadcrumbs.
-- **Reviews, only if the store wants them** — no review UI is a complete outcome (then no star ratings on cards either: an average of nothing is `0`). `p.reviews` arrives with the product as `{ items, page, per_page, has_next }`; submitting is `submitReview` off `useStorefront()`. ⚑ **The form renders for every visitor by default** (guests supply an email; hide the field when signed in) — login-gate it only when the store asks. ⚑ Derive the confirmation from the response's `status` (`"approved"` vs `"hold"`) — a hardcoded "awaiting approval" lies to every store that auto-approves — and refresh the list after, or the review doesn't appear. Field codes, policies and moderation: [`../references/reviews.md`](../references/reviews.md).
+- **Reviews, only if the store wants them** — no review UI is a complete outcome (then no star ratings on cards either: an average of nothing is `0`). ⚑ **Both shapes are exact — invented names fail silently** (a 400 naming a field you *did* fill in; blank authors):
+
+  ```jsx
+  p.reviews                                     // { items, page, per_page, has_next }
+  p.reviews.items[0]                            // { id, reviewer, review, rating, verified, created_date }
+  await submitReview({ product_id, review, rating, reviewer, email })   // NOT content/reviewer_name/reviewer_email
+  ```
+
+  Text or stars — either alone submits. ⚑ **The form renders for every visitor by default** (guests supply an email; hide it when signed in) — login-gate it only when the store asks. ⚑ Derive the confirmation from the response's `status` (`"approved"` vs `"hold"`) — a hardcoded "awaiting approval" lies to every auto-approving store — and refresh the list after, or the review doesn't appear. Codes, policies, moderation: [`../references/reviews.md`](../references/reviews.md).
 - **Title** — give each page type its own `<title>` and description; a store whose every page shares one static title is invisible to search. Nothing here emits structured data either — if the store wants rich results, emit your own `Product`/`Offer` JSON-LD from `product` and `view.display` (price, currency, availability).
 
 ## Cart / bag
@@ -251,7 +263,7 @@ import { CheckoutProvider, useCheckoutContext, AddressFields, ShippingMethodPick
 
 ⚑ Rules: render each picker's `hint` and every branch; a single shipping or payment option still *shows* what it is — never a picker of one, never "nothing selected". ⚑ Picks are instant: both pickers reflect a click immediately (shipping optimistically), and `mustChoose` stays true after a choice — the radios keep rendering, still changeable; never disable options while `syncing`/`choosing` (the hint covers it). Render `addressError` on the address fields. ⚑ Payment methods, currency and countries come from `useStoreInfo()`/`useCountries()` only — `cart.payment_gateways` is always `undefined`, and a default store offers `offline` only, so never hardcode a card option.
 
-⚑ **A disabled place-order button must say why** — the silent disabled button is the most common checkout dead end. `blockers` is an array of codes; write one line per code, in the store's voice, anchored near the field that fixes it: `empty_cart` (bag is empty) · `billing_incomplete` (required address fields — `missingBillingFields` names them) · `shipping_address_incomplete` (the separate delivery address) · `shipping_address_required` (no address to price yet) · `shipping_method_required` (choose a delivery option) · `shipping_not_available` (this address can't be delivered to) · `payment_method_required` (choose how to pay) · `cart_loading` / `shipping_recalculating` (transient — a quiet "one moment", not an error).
+⚑ **A disabled place-order button must say why** — the silent disabled button is the most common checkout dead end. `blockers` is an array of codes; write one line per code, in the store's voice, anchored near the field that fixes it: `empty_cart` · `billing_incomplete` (required address fields — `missingBillingFields` names them) · `shipping_address_incomplete` (the separate delivery address) · `shipping_address_required` (no address to price yet) · `shipping_method_required` (choose a delivery option) · `shipping_not_available` (can't deliver there) · `payment_method_required` · `cart_loading` / `shipping_recalculating` (transient — a quiet "one moment", not an error).
 
 The pickers' `hint.code` works the same way (`missing_address`, `none_available`, `syncing` for shipping; `none_available` for payment): write those words once, and prefer `hint.serverMessage` when it is set — the backend's explanation is more specific than anything you can write.
 
@@ -304,7 +316,7 @@ function CheckoutForm() {
 
 **`<AddressFields>` is the one shipped component — use it, never hand-roll the address form.** It owns what hand-rolled forms get wrong: the state/province field appears with the right options once a country is picked (shipping rates and taxes match on country *plus* state, so a form without it mis-prices US/CA/AU orders with no error anywhere), every field keeps its `autoComplete` token (what makes browser autofill work), required marks arm on first blur, and the server's "we don't ship there" lands on the country field. `which="shipping"` renders null until `shipToDifferent` is on — the deliver-elsewhere checkbox itself is yours, wired to `c.shipToDifferent` / `c.setShipToDifferent`.
 
-It ships **no CSS** bar a `max-width:100%` cap on the selects (an unstyled checkout must not scroll sideways): every element carries `data-part` (`address-fields`, `field`, `label`, `control`, `required`, `error`) plus `data-key` (the field) and `data-span` (1 or 2 — the field's natural width in a two-column grid), so style it in your `index.css` via `[data-part]` selectors or pass `className`/`classes={{ field, label, control, error }}`. ⚑ **`data-part` sits on the element, not a wrapper** — `select[data-part="control"]`, never `[data-part="control"] input`: the descendant form matches nothing and ships the form unstyled. Props: `includeCompany` (default false), `includePhone` (default true), `omit={["…"]}`, `labels={{ postcode: "ZIP code" }}` (over `addressFieldSpec`'s plain-convention defaults), `selectPlaceholder`, and two escape hatches — `inputRender` swaps the control only (spread the handed `dom` props onto your input), `fieldRender` replaces the whole labeled block. `c.missingBillingFields` stays the live list of what is still missing, if you want your own per-field marks.
+It ships **no CSS** bar a `max-width:100%` cap on the selects (an unstyled checkout must not scroll sideways): every element carries `data-part` (`address-fields`, `field`, `label`, `control`, `required`, `error`) plus `data-key` (the field) and `data-span` (1 or 2 — the field's natural width in a two-column grid), so style it in your `index.css` via `[data-part]` selectors or pass `className`/`classes={{ field, label, control, error }}`. ⚑ **`data-part` sits on the element, not a wrapper** — `select[data-part="control"]`, never `[data-part="control"] input`: the descendant form matches nothing and ships the form unstyled. Props: `includeCompany` (false), `includePhone` (true), `omit={["…"]}`, `labels={{ postcode: "ZIP code" }}`, `selectPlaceholder`, and two escape hatches — `inputRender` swaps the control only (spread the handed `dom` props onto your input), `fieldRender` replaces the whole labeled block. `c.missingBillingFields` stays the live list of what is missing, for your own per-field marks.
 
 ⚑ **The `stage === "submitted"` guard goes above the empty-cart branch** — placing an order clears the cart before the browser navigates, and without the guard the page flashes an empty bag over a just-placed order.
 

package/skills/commerce/references/reviews.md

@@ -17,7 +17,7 @@ Reviews are **part of the happy path**, not an extra: the backend always shipped
 Both live on the storefront client in `@/commerce/utils` — in React, `useStorefront()` is that client:
 
 - **`getProductReviews(slugOrRef, { page, per_page })`** → `{ items, page, per_page, has_next, average_rating, rating_count }`. The same reviews `get-product` returns — page or refresh the list without re-fetching the page; `useProduct(slug, { reviewsPerPage })` sizes the first one.
-- **`submitReview({ product_id, review, rating?, reviewer?, email? })`** → `{ review_id, status, verified }`. `review` is the body text and is required; `rating` is optional, **0–5**; `reviewer` is the display name. It **rejects** with `email_required` | `review_incomplete` | `invalid_rating` | `not_found` — catch it, read `storefrontErrorCode(e)`, and land each code on its own field, so a failed submit says what to fix instead of resolving into nothing. After an approved submission, refresh the list yourself so the review actually appears.
+- **`submitReview({ product_id, review?, rating?, reviewer?, email? })`** → `{ review_id, status, verified }`. **Text or stars — at least one**: `review` is the body text, `rating` is **1–5 stars** (0 counts as unrated); stars-only and text-only are both valid, only both missing rejects. `reviewer` is the display name. ⚑ **These are the API's names, not the entity's columns** — a form built on `content`/`reviewer_name`/`reviewer_email` is submitting nothing; those three are accepted as aliases, but the reviews you render back are always `{ id, reviewer, review, rating, verified, created_date }`, so an author read off `reviewer_name` renders blank. It **rejects** with `email_required` | `review_incomplete` (neither text nor stars) | `invalid_rating` | `not_found` — catch it, read `storefrontErrorCode(e)`, and land each code on its own field, so a failed submit says what to fix instead of resolving into nothing. After an approved submission, refresh the list yourself so the review actually appears.
 
 ## What ships
 
@@ -36,7 +36,7 @@ Which visitors may submit is a gate **you** render, in your own words — and **
 | **Login-gated** | a signed-in visitor only | one conditional around the same form: render it when your app has a user, otherwise your "sign in to review" line |
 | **Verified buyers** | someone whose own orders include a `processing`/`completed` order for this product | check `storefront-account` `my-orders` for the product, gate on the result |
 
-Policies are **UI-side by design**: the server accepts any valid email, so a stricter rule is exactly this gate — and a policy that must hold against handcrafted API calls too belongs in a backend function of your own wrapping `submit-review`. Either way: hide the email field for a signed-in visitor (the session's email wins server-side), and make the stars mandatory by validating before you call. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.
+Policies are **UI-side by design**: the server accepts any valid email, so a stricter rule is exactly this gate — and a policy that must hold against handcrafted API calls too belongs in a backend function of your own wrapping `submit-review`. Either way: hide the email field for a signed-in visitor (the session's email wins server-side). The server needs only one of text/stars — if your form makes either (or both) mandatory, validate before you call, so the customer meets your words rather than a raw 400. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.
 
 ## Auto-approval and moderation
 

package/src/commerce/admin/pages/products/Reviews.jsx

@@ -137,7 +137,10 @@ export default function Reviews() {
         label: "Review",
         render: (row) => (
           <div className="max-w-md">
-            <p className="line-clamp-2 text-sm">{row.review}</p>
+            {/* A rating-only review is valid — say so, or the row reads as blank. */}
+            {row.review
+              ? <p className="line-clamp-2 text-sm">{row.review}</p>
+              : <p className="text-sm italic text-muted-foreground">Rating only — no text</p>}
             {row.verified && <span className="text-xs text-green-700">✓ Verified owner</span>}
           </div>
         ),

package/src/commerce/utils/storefront.js

@@ -24,6 +24,15 @@
  *   payload) returns an action's payload as-is.
  */
 
+/** First of `keys` holding a non-empty string on `obj` ("" when none does). */
+function firstFilled(obj, keys) {
+  for (const k of keys) {
+    const v = obj?.[k];
+    if (typeof v === "string" && v.trim()) return v.trim();
+  }
+  return "";
+}
+
 /** The stable error code a failed storefront call carries, if any. */
 export function storefrontErrorCode(e) {
   return e?.response?.data?.code ?? e?.data?.code ?? e?.code ?? null;
@@ -111,7 +120,18 @@ export function createStorefront(base44, { storageKey = "cart_token", storage }
     /**
      * Submit a review. `email` is required for a guest and ignored for a
      * signed-in caller (the session's email always wins, so nobody can
-     * review as someone else). `rating` is optional, 0–5.
+     * review as someone else). At least one of `review` (the text) or
+     * `rating` (1–5 stars) is required — a stars-only submission is valid,
+     * and so is text-only; with neither this **throws synchronously**, naming
+     * the keys it did receive, instead of letting the server answer about a
+     * field the customer filled in.
+     *
+     * The payload is `{ product_id, review, rating, reviewer, email }` — the
+     * API's names, which are **not** the ProductReview entity's columns.
+     * Common near-misses (`content`, `text`, `body`, `comment`;
+     * `reviewer_name`, `name`; `reviewer_email`) are accepted as aliases, so a
+     * form written against the entity still submits. The reviews you render
+     * back always use the API's names: `{ reviewer, review, rating, verified }`.
      *
      * Resolves to `{ review_id, status, verified }` — **`status` is
      * `"approved"` or `"hold"` depending on the store's `auto_approve_reviews`
@@ -119,7 +139,28 @@ export function createStorefront(base44, { storageKey = "cart_token", storage }
      * moderation. Rejects with `email_required` | `review_incomplete` |
      * `invalid_rating` | `not_found`.
      */
-    submitReview({ product_id, review, rating, reviewer, email } = {}) {
+    submitReview(payload = {}) {
+      const { product_id, rating } = payload;
+      // Accept the names a review form naturally reaches for. The payload keys
+      // are NOT the entity's columns, and a plain destructure dropped every
+      // mismatch on the floor: a form posting `content`/`reviewer_name`/
+      // `reviewer_email` sent no text at all and got back "review is required"
+      // — naming a field the customer had filled in. Canonical names win when
+      // both are present; anything still unrecognized throws below rather than
+      // vanishing.
+      const review = firstFilled(payload, ["review", "content", "text", "body", "comment"]);
+      const reviewer = firstFilled(payload, ["reviewer", "reviewer_name", "name", "author"]);
+      const email = firstFilled(payload, ["email", "reviewer_email"]);
+      const rated = rating != null && Number(rating) >= 1;
+      if (!review && !rated) {
+        // Fail here, not after a round trip: the server can only report the
+        // field it didn't receive, which is never the one that is wrong.
+        throw new Error(
+          `submitReview needs \`review\` text or a \`rating\` of 1-5. Received: ${
+            Object.keys(payload).join(", ") || "nothing"
+          }. The payload is { product_id, review, rating, reviewer, email } — not the entity's column names.`,
+        );
+      }
       return inv("commerce/storefront-catalog", {
         action: "submit-review",
         product_id,