@base44/app-plugin-commerce 0.6.11 → 0.6.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.6.11",
+  "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. ⚑ **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.
+- **`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

@@ -25,13 +25,10 @@
  */
 
 /**
- * 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.
+ * 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",
@@ -44,10 +41,7 @@ const REVIEW_FIELD_FIXES = {
   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.";
+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) {
@@ -55,9 +49,7 @@ function assertReviewFieldNames(payload) {
     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}`);
+  if (wrong.length) throw new Error(`${REVIEW_SIGNATURE} — got: ${wrong.join(", ")}`);
 }
 
 /** The stable error code a failed storefront call carries, if any. */
@@ -153,15 +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.
      *
-     * **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.
+     * **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`
@@ -178,11 +165,7 @@ export function createStorefront(base44, { storageKey = "cart_token", storage }
       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}`,
-        );
+        throw new Error(`${REVIEW_SIGNATURE} — needs review text or a rating of 1-5`);
       }
       return inv("commerce/storefront-catalog", {
         action: "submit-review",