@brainerce/mcp-server 3.5.1 → 3.7.0

package/dist/index.js

@@ -948,6 +948,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
@@ -1579,6 +1748,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
 
@@ -2525,6 +2753,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":
@@ -2597,6 +2827,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getProductReviewsSection(),
+        "",
+        "---",
+        "",
         getDiscountsSection(),
         "",
         "---",
@@ -2648,6 +2882,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inventory",
     "discounts",
     "recommendations",
+    "reviews",
     "product-customization-fields",
     "tax",
     "critical-rules",
@@ -2665,9 +2900,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 {
@@ -3379,6 +3612,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.
@@ -3622,6 +3891,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) {
@@ -3652,6 +3922,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.'
@@ -3673,6 +3944,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",
@@ -3742,28 +4014,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';
 
@@ -4555,6 +4947,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) {
@@ -5357,6 +5881,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",