@brainerce/mcp-server 3.5.1 → 3.7.0

package/dist/index.mjs

@@ -916,6 +916,175 @@ function ProductPage({ product, storeInfo }: { product: Product; storeInfo: Stor
 }
 \`\`\`
 
+### Variant Attribute Selector with Swatches (color + size **mix**)
+
+The simple text-button picker above works, but loses the merchant-configured
+**swatch metadata**. A single product often mixes one attribute that should
+render as **color swatches** (e.g. \`Color\`) and another that should render
+as **text buttons** (e.g. \`Size\`). The product response includes everything
+you need:
+
+- \`product.productAttributeOptions[]\` \u2014 the swatch definitions: \`attribute.name\`,
+  \`attribute.displayType\` (the \`AttributeDisplayType\` enum: \`DEFAULT\` | \`COLOR_SWATCH\` | \`IMAGE_SWATCH\` | \`MIXED_SWATCH\`),
+  \`attributeOption.name\`, \`swatchColor\` (hex), \`swatchColor2\` (hex \u2014 used for dual-color swatches
+  like Black & White), \`swatchImageUrl\` (for fabric / pattern thumbnails).
+  \`MIXED_SWATCH\` means each option in the group can independently pick image OR color
+  (the merchant decides per option). Treat any unrecognized value as \`DEFAULT\`.
+- \`variant.attributes\` \u2014 the selected value per attribute on each variant.
+
+Use \`getProductSwatches(product)\` to get a render-ready, grouped structure:
+
+\`\`\`typescript
+import { getProductSwatches } from 'brainerce';
+
+const groups = getProductSwatches(product);
+// [
+//   { attributeName: 'color', displayType: 'COLOR_SWATCH', options: [
+//     { name: 'Full Color',    swatchColor: '#1D9435', swatchColor2: null,       swatchImageUrl: null },
+//     { name: 'Black & White', swatchColor: '#000000', swatchColor2: '#FFFFFF',  swatchImageUrl: null },
+//   ]},
+//   { attributeName: 'size', displayType: 'DEFAULT', options: [
+//     { name: '16" \xD7 20"' }, { name: '24" \xD7 32"' }, { name: '36" \xD7 48"' },
+//   ]},
+// ]
+\`\`\`
+
+Render one branch per \`displayType\`. The same loop handles all-swatch, all-text,
+and the mix case:
+
+\`\`\`typescript
+function VariantPicker({
+  product,
+  selections,
+  onSelect,
+}: {
+  product: Product;
+  selections: Record<string, string>;          // { color: 'Full Color', size: '24" \xD7 32"' }
+  onSelect: (attrName: string, value: string) => void;
+}) {
+  const groups = getProductSwatches(product);
+  if (groups.length === 0) return null;
+
+  return (
+    <div className="space-y-4">
+      {groups.map((group) => (
+        <div key={group.attributeName}>
+          <label className="block mb-2 text-sm font-medium">
+            {group.attributeName}: <span className="text-gray-500">{selections[group.attributeName] ?? ''}</span>
+          </label>
+          <div className="flex flex-wrap gap-2">
+            {group.options.map((opt) => {
+              const isSelected = selections[group.attributeName] === opt.name;
+
+              // COLOR_SWATCH \u2014 round button; dual-color uses a 50/50 gradient.
+              if (group.displayType === 'COLOR_SWATCH' && opt.swatchColor) {
+                const bg = opt.swatchColor2
+                  ? \`linear-gradient(135deg, \${opt.swatchColor} 50%, \${opt.swatchColor2} 50%)\`
+                  : opt.swatchColor;
+                return (
+                  <button
+                    key={opt.name}
+                    type="button"
+                    title={opt.name}
+                    aria-pressed={isSelected}
+                    onClick={() => onSelect(group.attributeName, opt.name)}
+                    className={\`h-9 w-9 rounded-full border-2 \${isSelected ? 'border-black ring-2 ring-black/30' : 'border-gray-300 hover:border-black'}\`}
+                    style={{ background: bg }}
+                  />
+                );
+              }
+
+              // IMAGE_SWATCH \u2014 square thumbnail (fabric/pattern preview).
+              if (group.displayType === 'IMAGE_SWATCH' && opt.swatchImageUrl) {
+                return (
+                  <button
+                    key={opt.name}
+                    type="button"
+                    aria-pressed={isSelected}
+                    onClick={() => onSelect(group.attributeName, opt.name)}
+                    className={\`h-10 w-10 overflow-hidden rounded border-2 \${isSelected ? 'border-black' : 'border-gray-300'}\`}
+                  >
+                    <img src={opt.swatchImageUrl} alt={opt.name} className="h-full w-full object-cover" />
+                  </button>
+                );
+              }
+
+              // MIXED_SWATCH \u2014 each option is independently image OR color (image wins if present).
+              if (group.displayType === 'MIXED_SWATCH') {
+                if (opt.swatchImageUrl) {
+                  return (
+                    <button
+                      key={opt.name}
+                      type="button"
+                      aria-pressed={isSelected}
+                      onClick={() => onSelect(group.attributeName, opt.name)}
+                      className={\`h-10 w-10 overflow-hidden rounded border-2 \${isSelected ? 'border-black' : 'border-gray-300'}\`}
+                    >
+                      <img src={opt.swatchImageUrl} alt={opt.name} className="h-full w-full object-cover" />
+                    </button>
+                  );
+                }
+                if (opt.swatchColor) {
+                  const bg = opt.swatchColor2
+                    ? \`linear-gradient(135deg, \${opt.swatchColor} 50%, \${opt.swatchColor2} 50%)\`
+                    : opt.swatchColor;
+                  return (
+                    <button
+                      key={opt.name}
+                      type="button"
+                      title={opt.name}
+                      aria-pressed={isSelected}
+                      onClick={() => onSelect(group.attributeName, opt.name)}
+                      className={\`h-9 w-9 rounded-full border-2 \${isSelected ? 'border-black ring-2 ring-black/30' : 'border-gray-300 hover:border-black'}\`}
+                      style={{ background: bg }}
+                    />
+                  );
+                }
+                // option has neither image nor color \u2192 fall through to text button below.
+              }
+
+              // DEFAULT (or any swatch type missing its data) \u2014 plain text button.
+              return (
+                <button
+                  key={opt.name}
+                  type="button"
+                  aria-pressed={isSelected}
+                  onClick={() => onSelect(group.attributeName, opt.name)}
+                  className={\`rounded border px-3 py-1.5 text-sm \${isSelected ? 'bg-black text-white border-black' : 'border-gray-300 hover:border-black'}\`}
+                >
+                  {opt.name}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+\`\`\`
+
+Wire it up in the product page: keep \`selections\` in state, find the matching
+variant after each pick, and update price / image / stock from it.
+
+\`\`\`typescript
+const [selections, setSelections] = useState<Record<string, string>>({});
+
+const matchedVariant = useMemo(() => (
+  product.variants?.find((v) =>
+    Object.entries(selections).every(([k, val]) => v.attributes?.[k] === val)
+  ) ?? null
+), [product.variants, selections]);
+
+// Greying-out unavailable combinations: for each candidate value, run
+// the same find() and check \`inventory.canPurchase\`. Disable the button
+// if no purchasable variant exists under that selection.
+\`\`\`
+
+**i18n:** \`getProductSwatches\` returns translated \`attributeName\` and
+\`option.name\` automatically when \`client.setLocale()\` is active. No
+client-side overlay needed. Swatch colors are language-agnostic.
+
 ### Description Rendering (handles HTML vs text)
 
 \`\`\`typescript
@@ -1547,6 +1716,65 @@ The merchant can hide a group entirely for one variant by setting \`maxOverride:
 
 Allergens (informational chips), scheduled availability windows, nested combos (depth \u2264 3 via \`nestedByModifierId\`), and downsell modifiers (negative \`priceDelta\`) are all built on the same data model. See INTEGRATION-OPTIONAL.md "Restaurant / build-your-own products" for those flows.`;
 }
+function getProductReviewsSection() {
+  return `## Product Reviews (\u2605 ratings + JSON-LD for SEO)
+
+**Purchaser-only.** Only authenticated customers who purchased the product can submit. Each customer writes one review per product and can edit/delete it. Reviews publish immediately \u2014 no PENDING queue.
+
+\`\`\`typescript
+// PDP \u2014 list visible reviews (public)
+const { data } = await getClient().listProductReviews(productId, { page: 1, limit: 20 });
+
+// Decide which UI to render for the current customer
+getClient().setCustomerToken(authToken); // after login
+const { eligible, reason, myReview } = await getClient().getMyProductReview(productId);
+
+if (!eligible) {
+  // reason: 'no_eligible_order' | 'reviews_disabled' | 'product_not_found'
+  // \u2192 "only customers who purchased this product can leave a review"
+} else if (myReview) {
+  // \u2192 edit form prefilled with myReview.rating + myReview.body
+} else {
+  // \u2192 submit form (rating + body only \u2014 name/email come from customer profile)
+}
+
+await getClient().submitProductReview(productId, { rating: 5, body: 'Loved it!' });
+await getClient().updateMyProductReview(productId, { rating: 4, body: 'Updated.' });
+await getClient().deleteMyProductReview(productId); // can submit a new one after
+\`\`\`
+
+Each \`Product\` carries denormalized rollups: \`product.avgRating\`, \`product.reviewCount\`. Use these on PLP cards.
+
+### JSON-LD (mandatory for SEO stars in Google)
+
+Emit \`aggregateRating\` ONLY when \`product.reviewCount > 0\`:
+
+\`\`\`typescript
+const productJsonLd = {
+  '@context': 'https://schema.org',
+  '@type': 'Product',
+  name: product.name,
+  // \u2026existing fields
+  ...(product.reviewCount > 0 && {
+    aggregateRating: {
+      '@type': 'AggregateRating',
+      ratingValue: product.avgRating,
+      reviewCount: product.reviewCount,
+      bestRating: 5,
+      worstRating: 1,
+    },
+  }),
+};
+\`\`\`
+
+### Rules
+- Rating must be an integer 1-5 (DB constraint).
+- Customer must be logged in AND have purchased the product (\`SHIPPED+\` for physical, \`PAID+\` for downloadable).
+- One review per (productId, customerId). Duplicate submit \u2192 409 \u2014 use updateMyProductReview instead.
+- Submit throttled 3 / 60s / IP; edit/delete 5 / 60s / IP.
+- \`verifiedPurchase\` is always true for customer-submitted reviews.
+- Stores with \`reviewsEnabled = false\` return 403 on storefront endpoints.`;
+}
 function getInventorySection() {
   return `## Inventory, Stock Display & Reservation Countdown
 
@@ -2493,6 +2721,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getDiscountsSection();
     case "recommendations":
       return getRecommendationsSection();
+    case "reviews":
+      return getProductReviewsSection();
     case "product-customization-fields":
       return getProductCustomizationFieldsSection();
     case "modifier-groups":
@@ -2565,6 +2795,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getProductReviewsSection(),
+        "",
+        "---",
+        "",
         getDiscountsSection(),
         "",
         "---",
@@ -2616,6 +2850,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inventory",
     "discounts",
     "recommendations",
+    "reviews",
     "product-customization-fields",
     "tax",
     "critical-rules",
@@ -2633,9 +2868,7 @@ var GET_SDK_DOCS_SCHEMA = {
 async function handleGetSdkDocs(args) {
   const id = args.salesChannelId ?? args.connectionId;
   if (!args.salesChannelId && args.connectionId) {
-    console.warn(
-      "get-sdk-docs: `connectionId` is deprecated \u2014 use `salesChannelId` instead"
-    );
+    console.warn("get-sdk-docs: `connectionId` is deprecated \u2014 use `salesChannelId` instead");
   }
   const content = getSectionByTopic(args.topic, id, args.currency);
   return {
@@ -3347,6 +3580,42 @@ interface CartBundleOffer {
   totalOriginalPrice: string;
   totalDiscountedPrice: string;
 }`;
+var REVIEWS_TYPES = `// ---- Product Reviews ----
+
+interface ProductReview {
+  id: string;
+  productId: string;
+  authorName: string;                // max 100 chars
+  rating: number;                    // integer 1-5
+  body: string | null;               // plain text, max 5000 chars
+  verifiedPurchase: boolean;         // derived server-side from DELIVERED orders
+  hiddenAt?: string | null;          // ISO datetime; admin responses only \u2014 null = visible
+  createdAt: string;                 // ISO datetime
+}
+
+interface ProductReviewAdmin extends ProductReview {
+  customerId: string | null;
+  authorEmail: string | null;
+  orderId: string | null;
+  updatedAt: string;
+}
+
+interface WriteProductReviewInput {
+  rating: number;                    // 1-5
+  body?: string;                     // optional, max 5000 chars
+}
+
+interface MyProductReview {
+  eligible: boolean;
+  // Machine-readable reason when not eligible. null when eligible=true.
+  reason: 'no_eligible_order' | 'reviews_disabled' | 'product_not_found' | null;
+  myReview: ProductReview | null;
+}
+
+// Each Product carries denormalized review stats:
+//   product.avgRating: number       // 0 when reviewCount is 0
+//   product.reviewCount: number     // count of visible (hiddenAt IS NULL) reviews
+`;
 var INQUIRIES_TYPES = `// ---- Contact Inquiries & Forms ----
 
 // Two shapes \u2014 legacy and flexible. The two may be mixed; \`fields\` wins on key collision.
@@ -3590,6 +3859,7 @@ var TYPES_BY_DOMAIN = {
   payments: PAYMENTS_TYPES,
   helpers: HELPERS_TYPES,
   inquiries: INQUIRIES_TYPES,
+  reviews: REVIEWS_TYPES,
   "modifier-groups": MODIFIER_GROUPS_TYPES
 };
 function getTypesByDomain(domain) {
@@ -3620,6 +3890,7 @@ var GET_TYPE_DEFINITIONS_SCHEMA = {
     "payments",
     "helpers",
     "inquiries",
+    "reviews",
     "all"
   ]).describe(
     'The domain of types to retrieve. Use "helpers" for helper function signatures and common types like StoreInfo, PaginatedResponse.'
@@ -3641,6 +3912,7 @@ var GET_CODE_EXAMPLE_SCHEMA = {
     "sdk-init",
     "cart-read-and-mutate",
     "variant-selection",
+    "variant-selector-swatches",
     "checkout-address-and-shipping",
     "checkout-payment-providers",
     "checkout-stripe-confirm",
@@ -3710,28 +3982,148 @@ for (const item of cart.items) {
   const unitPrice = parseFloat(item.unitPrice); // prices are strings!
 }`,
   "variant-selection": `// Variant selection with live stock + price updates.
+// Variants expose attributes as a flat object: { color: 'Red', size: 'M' }.
+// NOT 'options' \u2014 that field does not exist on ProductVariant.
 import { getVariantPrice, getStockStatus, getVariantOptions } from 'brainerce';
 import type { Product, ProductVariant } from 'brainerce';
 
 function selectVariant(product: Product, selections: Record<string, string>) {
-  // selections = { Size: 'M', Color: 'Red' }
-  const variant = product.variants.find((v) =>
-    v.options.every((o) => selections[o.name] === o.value)
+  // selections = { size: 'M', color: 'Red' }  (keys match variant.attributes keys)
+  const variant = product.variants?.find((v) =>
+    Object.entries(selections).every(([k, val]) => v.attributes?.[k] === val)
   );
   if (!variant) return null;
 
-  const price = getVariantPrice(product, variant); // handles compare-at, currency
-  const stock = getStockStatus(variant); // 'IN_STOCK' | 'LOW_STOCK' | 'OUT_OF_STOCK'
-  const canPurchase = stock !== 'OUT_OF_STOCK';
+  const price = getVariantPrice(variant, product.basePrice); // string, fallback-aware
+  const stock = getStockStatus(variant.inventory); // 'in-stock' | 'low-stock' | 'out-of-stock' | 'unavailable'
+  const canPurchase = variant.inventory?.canPurchase !== false;
 
   // Switch the main product image to the variant's image if it has one
-  const image = variant.image ?? product.images[0];
+  const image = variant.image ?? product.images?.[0];
 
   return { variant, price, stock, canPurchase, image };
 }
 
-// Build the option picker from getVariantOptions(product) \u2014 returns
-// [{ name: 'Size', values: ['S','M','L'] }, ...]`,
+// Build the option picker by iterating product.variants and grouping
+// variant.attributes into { color: ['Red', 'Blue'], size: ['S','M','L'] }.
+// For each variant you can also call getVariantOptions(variant) which returns
+// the same key/value pairs as an array with translated names when setLocale() is active.
+// For swatch metadata (color hex, dual-color, image), use the
+// 'variant-selector-swatches' operation instead.`,
+  "variant-selector-swatches": `// Variant picker that mixes color swatches and text buttons in one product.
+// Uses product.productAttributeOptions[] \u2014 the merchant-configured swatch
+// metadata. displayType is the AttributeDisplayType Prisma enum, one of:
+//   'DEFAULT'       \u2014 plain text button
+//   'COLOR_SWATCH'  \u2014 swatchColor (+ optional swatchColor2 dual-color gradient)
+//   'IMAGE_SWATCH'  \u2014 swatchImageUrl thumbnail
+//   'MIXED_SWATCH'  \u2014 per-option hybrid: image if swatchImageUrl is set,
+//                     otherwise fall back to swatchColor
+// getProductSwatches() groups options by attribute name so you can render each
+// attribute with its own displayType \u2014 a single product can have Color as
+// swatches AND Size as text buttons.
+import { getProductSwatches } from 'brainerce';
+import type { Product } from 'brainerce';
+
+function VariantPicker({
+  product,
+  selections,
+  onSelect,
+}: {
+  product: Product;
+  selections: Record<string, string>;
+  onSelect: (attrName: string, value: string) => void;
+}) {
+  const groups = getProductSwatches(product);
+  // groups: [{ attributeName, displayType, options: [{ name, swatchColor, swatchColor2, swatchImageUrl }] }]
+
+  return (
+    <>
+      {groups.map((group) => (
+        <div key={group.attributeName}>
+          <label>{group.attributeName}: {selections[group.attributeName] ?? ''}</label>
+          <div style={{ display: 'flex', gap: 8 }}>
+            {group.options.map((opt) => {
+              const selected = selections[group.attributeName] === opt.name;
+              const onClick = () => onSelect(group.attributeName, opt.name);
+
+              // COLOR_SWATCH: round button. swatchColor2 = dual-color gradient.
+              if (group.displayType === 'COLOR_SWATCH' && opt.swatchColor) {
+                const bg = opt.swatchColor2
+                  ? \`linear-gradient(135deg, \${opt.swatchColor} 50%, \${opt.swatchColor2} 50%)\`
+                  : opt.swatchColor;
+                return (
+                  <button
+                    key={opt.name}
+                    type="button"
+                    title={opt.name}
+                    aria-pressed={selected}
+                    onClick={onClick}
+                    style={{
+                      width: 36,
+                      height: 36,
+                      borderRadius: '50%',
+                      background: bg,
+                      outline: selected ? '2px solid black' : 'none',
+                    }}
+                  />
+                );
+              }
+
+              // IMAGE_SWATCH: square thumbnail.
+              if (group.displayType === 'IMAGE_SWATCH' && opt.swatchImageUrl) {
+                return (
+                  <button key={opt.name} type="button" onClick={onClick} aria-pressed={selected}>
+                    <img src={opt.swatchImageUrl} alt={opt.name} width={40} height={40} />
+                  </button>
+                );
+              }
+
+              // MIXED_SWATCH: per-option hybrid (image wins if present).
+              if (group.displayType === 'MIXED_SWATCH') {
+                if (opt.swatchImageUrl) {
+                  return (
+                    <button key={opt.name} type="button" onClick={onClick} aria-pressed={selected}>
+                      <img src={opt.swatchImageUrl} alt={opt.name} width={40} height={40} />
+                    </button>
+                  );
+                }
+                if (opt.swatchColor) {
+                  const bg = opt.swatchColor2
+                    ? \`linear-gradient(135deg, \${opt.swatchColor} 50%, \${opt.swatchColor2} 50%)\`
+                    : opt.swatchColor;
+                  return (
+                    <button
+                      key={opt.name}
+                      type="button"
+                      title={opt.name}
+                      aria-pressed={selected}
+                      onClick={onClick}
+                      style={{ width: 36, height: 36, borderRadius: '50%', background: bg }}
+                    />
+                  );
+                }
+              }
+
+              // DEFAULT (or any swatch type missing its data): text button.
+              return (
+                <button key={opt.name} type="button" onClick={onClick} aria-pressed={selected}>
+                  {opt.name}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      ))}
+    </>
+  );
+}
+
+// After the user picks a value, find the matching ProductVariant:
+//   product.variants?.find((v) =>
+//     Object.entries(selections).every(([k, val]) => v.attributes?.[k] === val)
+//   )
+// Then read variant.price, variant.image, variant.inventory.canPurchase
+// to update the rest of the PDP.`,
   "checkout-address-and-shipping": `// Step 1-3 of the checkout flow. Never reorder or skip.
 import { client } from './brainerce';
 
@@ -4523,6 +4915,138 @@ function renderCartItem(item: CartItem): string {
 // multiply unitPrice \xD7 quantity directly.
 function lineTotal(item: CartItem): number {
   return item.unitPrice * item.quantity;
+}`,
+  "product-reviews": `// Purchaser-only reviews. Customer must be logged in AND have purchased
+// the product. The component switches between sign-in CTA / not-eligible /
+// submit form / edit form based on getMyProductReview().
+import { getClient, getServerClient } from '@/lib/brainerce';
+import { checkAuthStatus } from '@/lib/auth';
+import type { Product, ProductReview, MyProductReview } from 'brainerce';
+
+// Server component \u2014 fetches existing reviews + emits JSON-LD aggregateRating.
+export async function ProductReviewsSection({ product }: { product: Product }) {
+  const { data } = await getServerClient().listProductReviews(product.id, { page: 1, limit: 20 });
+
+  return (
+    <section>
+      <h2>Reviews ({product.reviewCount ?? 0})</h2>
+      {data.length === 0 && <p>No reviews yet.</p>}
+      {data.map((r) => (
+        <article key={r.id}>
+          <strong>{r.authorName}</strong>
+          {r.verifiedPurchase && <span> \xB7 Verified purchase</span>}
+          <div>{'\u2605'.repeat(r.rating)}{'\u2606'.repeat(5 - r.rating)}</div>
+          {r.body && <p>{r.body}</p>}
+        </article>
+      ))}
+      <ReviewForm productId={product.id} />
+    </section>
+  );
+}
+
+// JSON-LD \u2014 emit aggregateRating only when there is data
+function productJsonLd(product: Product, url: string) {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Product',
+    name: product.name,
+    image: product.images?.[0]?.url,
+    url,
+    sku: product.sku ?? product.id,
+    ...(product.reviewCount && product.reviewCount > 0 && {
+      aggregateRating: {
+        '@type': 'AggregateRating',
+        ratingValue: product.avgRating,
+        reviewCount: product.reviewCount,
+        bestRating: 5,
+        worstRating: 1,
+      },
+    }),
+  };
+}
+
+// Client-side form
+'use client';
+import { useEffect, useState } from 'react';
+
+type Stage =
+  | { kind: 'loading' }
+  | { kind: 'signed_out' }
+  | { kind: 'not_eligible'; reason: MyProductReview['reason'] }
+  | { kind: 'submit' }
+  | { kind: 'edit'; review: ProductReview };
+
+function ReviewForm({ productId }: { productId: string }) {
+  const [stage, setStage] = useState<Stage>({ kind: 'loading' });
+  const [rating, setRating] = useState(5);
+  const [body, setBody] = useState('');
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    (async () => {
+      const auth = await checkAuthStatus();
+      if (!auth.isLoggedIn) return setStage({ kind: 'signed_out' });
+      const me = await getClient().getMyProductReview(productId);
+      if (!me.eligible) return setStage({ kind: 'not_eligible', reason: me.reason });
+      if (me.myReview) {
+        setRating(me.myReview.rating);
+        setBody(me.myReview.body ?? '');
+        return setStage({ kind: 'edit', review: me.myReview });
+      }
+      setStage({ kind: 'submit' });
+    })();
+  }, [productId]);
+
+  if (stage.kind === 'loading') return <p>Loading\u2026</p>;
+  if (stage.kind === 'signed_out')
+    return <p><a href="/account/login">Sign in</a> to leave a review.</p>;
+  if (stage.kind === 'not_eligible')
+    return <p>Only customers who purchased this product can leave a review.</p>;
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    const client = getClient();
+    const input = { rating, body: body || undefined };
+    try {
+      if (stage.kind === 'edit') {
+        await client.updateMyProductReview(productId, input);
+      } else {
+        await client.submitProductReview(productId, input);
+      }
+      window.location.reload();
+    } catch (err: any) {
+      if (err?.status === 403) setError('Only customers who purchased this product can leave a review.');
+      else if (err?.status === 409) setError('You already reviewed this product.');
+      else if (err?.status === 429) setError('Too many submissions. Please wait a moment.');
+      else setError('Could not save your review. Please try again.');
+    }
+  }
+
+  async function remove() {
+    if (!confirm('Delete your review?')) return;
+    await getClient().deleteMyProductReview(productId);
+    window.location.reload();
+  }
+
+  return (
+    <form onSubmit={submit}>
+      <h3>{stage.kind === 'edit' ? 'Edit your review' : 'Write a review'}</h3>
+      <div>
+        {[1,2,3,4,5].map(n => (
+          <button type="button" key={n} onClick={() => setRating(n)}>
+            {n <= rating ? '\u2605' : '\u2606'}
+          </button>
+        ))}
+      </div>
+      <textarea value={body} onChange={(e) => setBody(e.target.value)} maxLength={5000} />
+      <button type="submit">{stage.kind === 'edit' ? 'Save changes' : 'Submit review'}</button>
+      {stage.kind === 'edit' && (
+        <button type="button" onClick={remove}>Delete review</button>
+      )}
+      {error && <p role="alert">{error}</p>}
+    </form>
+  );
 }`
 };
 async function handleGetCodeExample(args) {
@@ -5325,6 +5849,13 @@ var FEATURES = [
     sdk: "client.getProductBySlug(slug). Helpers: getProductPriceInfo, getVariantPrice, getStockStatus, getVariantOptions, getProductSwatches, getDescriptionContent, getProductMetafieldValue.",
     mandatory: "mandatory"
   },
+  {
+    id: "product-reviews",
+    title: "Display + collect product reviews (purchaser-only) with stars + JSON-LD",
+    description: 'On the PDP show a Reviews section: list of customer reviews with star rating, author name (from customer profile), verified-purchase badge, body, and date \u2014 public, no login needed. Below the list, a form that adapts to the current customer: signed-in + purchased + no review yet \u2192 submit form (rating 1-5 + optional body, no name/email \u2014 those are derived from the customer profile); signed-in + purchased + already has review \u2192 edit form prefilled with rating/body plus a delete button; signed-in but did NOT purchase \u2192 "only customers who purchased this product can leave a review"; not signed in \u2192 sign-in CTA. Eligibility: physical products require an order in SHIPPED+; downloadable products additionally accept PAID/PROCESSING. On PLP cards show \u2605 avgRating and (reviewCount). Emit Product JSON-LD with aggregateRating ONLY when product.reviewCount > 0 \u2014 this is what unlocks the star rich snippet in Google. Reviews publish immediately; merchants moderate (hide/show) from the admin surface. Rate-limited 3 submits / 60s / IP.',
+    sdk: "client.listProductReviews(productId) for the public list; client.getMyProductReview(productId) for the form-state decision; client.submitProductReview / updateMyProductReview / deleteMyProductReview for the three customer actions. All four customer methods require setCustomerToken(...) after login. Product.avgRating + Product.reviewCount are denormalized rollups returned on every product fetch.",
+    mandatory: "mandatory"
+  },
   {
     id: "product-customization-fields",
     title: "Render buyer-input customization fields on the product page",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainerce/mcp-server",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "description": "Framework-agnostic domain knowledge API for Brainerce. Provides SDK docs, types, business flows, critical rules, and store capabilities to AI tools like Lovable, Cursor, Bolt, v0, and Claude Code. Does NOT provide framework-specific boilerplate — clients build in whatever framework fits.",
   "bin": {
     "brainerce-mcp": "dist/bin/stdio.js"