@base44/app-plugin-commerce 0.6.10 → 0.6.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.6.10",
+  "version": "0.6.12",
   "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

@@ -194,7 +194,7 @@ 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`). ⚑ **Both shapes are exact — invented names fail silently** (a 400 naming a field you *did* fill in; blank authors):
+- **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** — entity-style names (`content`, `reviewer_name`) throw on submit and render blank in the list:
 
   ```jsx
   p.reviews                                     // { items, page, per_page, has_next }

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. ⚑ **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.
+- **`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, rows back as `{ id, reviewer, review, rating, verified, created_date }`. Not the entity's columns: a near-miss (`content`, `reviewer_name`, `reviewer_email`, …) throws client-side rather than being aliased, since the same wrong names would render the list blank too. 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,13 +24,32 @@
  *   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 "";
+/**
+ * Near-miss payload keys, rejected rather than aliased: the same names come
+ * back on the review rows, so a store that posts `content` reads
+ * `reviewer_name` too — aliasing the submit would leave every author blank
+ * with nothing failing to say why.
+ */
+const REVIEW_FIELD_FIXES = {
+  content: "review",
+  text: "review",
+  body: "review",
+  comment: "review",
+  reviewer_name: "reviewer",
+  name: "reviewer",
+  author: "reviewer",
+  reviewer_email: "email",
+};
+
+const REVIEW_SIGNATURE = "submitReview({ product_id, review, rating, reviewer, email })";
+
+/** 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) throw new Error(`${REVIEW_SIGNATURE} — got: ${wrong.join(", ")}`);
 }
 
 /** The stable error code a failed storefront call carries, if any. */
@@ -126,12 +145,10 @@ export function createStorefront(base44, { storageKey = "cart_token", storage }
      * 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 }`.
+     * **One set of names, both directions** — `{ product_id, review, rating,
+     * reviewer, email }` in, `{ id, reviewer, review, rating, verified,
+     * created_date }` back. Not the entity's columns: a near-miss (`content`,
+     * `reviewer_name`, `reviewer_email`, …) throws rather than being aliased.
      *
      * Resolves to `{ review_id, status, verified }` — **`status` is
      * `"approved"` or `"hold"` depending on the store's `auto_approve_reviews`
@@ -140,26 +157,15 @@ export function createStorefront(base44, { storageKey = "cart_token", storage }
      * `invalid_rating` | `not_found`.
      */
     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 { 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 (!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.`,
-        );
+      if (!String(review ?? "").trim() && !rated) {
+        throw new Error(`${REVIEW_SIGNATURE} — needs review text or a rating of 1-5`);
       }
       return inv("commerce/storefront-catalog", {
         action: "submit-review",