@base44/app-plugin-commerce 0.6.10 → 0.6.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.6.10",
+  "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/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, 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,13 +24,40 @@
  *   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 "";
+/**
+ * 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. */
@@ -126,12 +153,15 @@ 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.** 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`
@@ -140,25 +170,18 @@ 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.
+      if (!String(review ?? "").trim() && !rated) {
         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.`,
+          }. ${REVIEW_SHAPES}`,
         );
       }
       return inv("commerce/storefront-catalog", {