@base44/app-plugin-commerce 0.6.9 → 0.6.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "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/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.
 
@@ -194,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()` — text or stars, either alone submits. ⚑ **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
@@ -255,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.
 
@@ -308,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 }`. **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. 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.
+- **`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. ⚑ **One set of names, both directions** — the payload above, and rows back as `{ id, reviewer, review, rating, verified, created_date }`. They are the API's names, **not** the ProductReview entity's columns: a near-miss (`content`, `text`, `body`, `comment`; `reviewer_name`, `name`, `author`; `reviewer_email`) throws client-side naming the field it should be, rather than being aliased — a store that posts `content` reads `reviewer_name` back too, so a submit patched into working would still render every author 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
 

package/src/commerce/utils/storefront.js

@@ -24,6 +24,42 @@
  *   payload) returns an action's payload as-is.
  */
 
+/**
+ * Review payload keys a form reaches for instead of the API's, and what each
+ * one should be. These are **rejected by name, never aliased**: a review is
+ * submitted with these keys and rendered back with the API's, so a store that
+ * posts `content` also reads `reviewer_name` off the response and shows every
+ * author as "Anonymous". Accepting the alias would fix the submit and leave the
+ * list broken — with nothing failing anywhere to say so. One set of names,
+ * enforced at the first call that gets them wrong.
+ */
+const REVIEW_FIELD_FIXES = {
+  content: "review",
+  text: "review",
+  body: "review",
+  comment: "review",
+  reviewer_name: "reviewer",
+  name: "reviewer",
+  author: "reviewer",
+  reviewer_email: "email",
+};
+
+const REVIEW_SHAPES =
+  "The payload is { product_id, review, rating, reviewer, email }, and reviews come " +
+  "back as { id, reviewer, review, rating, verified, created_date } — the same names " +
+  "on both sides, and not the ProductReview entity's columns.";
+
+/** Throw when a payload uses a near-miss name and leaves the real field empty. */
+function assertReviewFieldNames(payload) {
+  const wrong = Object.keys(payload).filter((k) => {
+    const canonical = REVIEW_FIELD_FIXES[k];
+    return canonical && !String(payload[canonical] ?? "").trim();
+  });
+  if (!wrong.length) return;
+  const fixes = wrong.map((k) => `\`${k}\` should be \`${REVIEW_FIELD_FIXES[k]}\``).join(", ");
+  throw new Error(`submitReview: ${fixes}. ${REVIEW_SHAPES}`);
+}
+
 /** 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;
@@ -113,7 +149,19 @@ export function createStorefront(base44, { storageKey = "cart_token", storage }
      * signed-in caller (the session's email always wins, so nobody can
      * 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; only both missing rejects (`review_incomplete`).
+     * 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.
+     *
+     * **One set of names, both directions.** The payload is `{ product_id,
+     * review, rating, reviewer, email }` and a review comes back as `{ id,
+     * reviewer, review, rating, verified, created_date }` — not the
+     * ProductReview entity's columns. A near-miss (`content`, `text`, `body`,
+     * `comment`; `reviewer_name`, `name`, `author`; `reviewer_email`) throws
+     * naming the field it should be, and is deliberately **not** aliased: a
+     * store that posts `content` reads `reviewer_name` back too, so accepting
+     * the alias would fix the submit and leave every author rendering blank,
+     * with nothing failing to say why.
      *
      * Resolves to `{ review_id, status, verified }` — **`status` is
      * `"approved"` or `"hold"` depending on the store's `auto_approve_reviews`
@@ -121,7 +169,21 @@ 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, review, rating, reviewer, email } = payload;
+      // A wrong field name used to vanish in the destructure: the text never
+      // left the browser and the server answered "review is required" about a
+      // field the customer had filled in. Name the mistake instead, here,
+      // where the fix also applies to the list the store renders back.
+      assertReviewFieldNames(payload);
+      const rated = rating != null && Number(rating) >= 1;
+      if (!String(review ?? "").trim() && !rated) {
+        throw new Error(
+          `submitReview needs \`review\` text or a \`rating\` of 1-5. Received: ${
+            Object.keys(payload).join(", ") || "nothing"
+          }. ${REVIEW_SHAPES}`,
+        );
+      }
       return inv("commerce/storefront-catalog", {
         action: "submit-review",
         product_id,