@brainerce/mcp-server 3.6.0 → 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
@@ -1582,17 +1751,28 @@ Allergens (informational chips), scheduled availability windows, nested combos (
 function getProductReviewsSection() {
   return `## Product Reviews (\u2605 ratings + JSON-LD for SEO)
 
-Reviews publish immediately on submit. Merchants hide individual reviews via the admin surface \u2014 no PENDING queue.
+**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
-const { data, meta } = await client.listProductReviews(productId, { page: 1, limit: 20 });
-data.forEach(r => render(r.authorName, r.rating, r.body, r.verifiedPurchase));
+// 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)
+}
 
-// PDP \u2014 submit form
-await client.submitProductReview(productId, {
-  authorName, authorEmail, rating: 5, body,
-});
+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.
@@ -1621,9 +1801,10 @@ const productJsonLd = {
 
 ### Rules
 - Rating must be an integer 1-5 (DB constraint).
-- Duplicate from same email \u2192 409 Conflict.
-- Submit endpoint is throttled to 3 / 60s / IP \u2014 surface a friendly "please wait" on 429.
-- \`verifiedPurchase\` is derived server-side from DELIVERED orders \u2014 DO NOT try to set it.
+- 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() {
@@ -2719,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 {
@@ -3453,11 +3632,16 @@ interface ProductReviewAdmin extends ProductReview {
   updatedAt: string;
 }
 
-interface SubmitProductReviewInput {
-  authorName: string;
-  authorEmail?: string;              // recommended \u2014 used for guest dedupe + verified-purchase derivation
+interface WriteProductReviewInput {
   rating: number;                    // 1-5
-  body?: string;                     // optional
+  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:
@@ -3760,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",
@@ -3829,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';
 
@@ -4643,21 +4948,25 @@ function renderCartItem(item: CartItem): string {
 function lineTotal(item: CartItem): number {
   return item.unitPrice * item.quantity;
 }`,
-  "product-reviews": `// PDP: list visible reviews + submit form + JSON-LD aggregateRating
-import { client } from '@/lib/brainerce';
-import type { Product, ProductReview, SubmitProductReviewInput } from 'brainerce';
-
+  "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 client.listProductReviews(product.id, { page: 1, limit: 20 });
+  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 \u2014 be the first.</p>}
+      {data.length === 0 && <p>No reviews yet.</p>}
       {data.map((r) => (
         <article key={r.id}>
           <strong>{r.authorName}</strong>
-          {r.verifiedPurchase && <span> \xB7 Verified</span>}
+          {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>
@@ -4690,42 +4999,83 @@ function productJsonLd(product: Product, url: string) {
 
 // Client-side form
 'use client';
-import { useState } from 'react';
+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 [name, setName] = useState('');
-  const [email, setEmail] = 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 {
-      await client.submitProductReview(productId, {
-        authorName: name,
-        authorEmail: email,
-        rating,
-        body: body || undefined,
-      });
+      if (stage.kind === 'edit') {
+        await client.updateMyProductReview(productId, input);
+      } else {
+        await client.submitProductReview(productId, input);
+      }
       window.location.reload();
     } catch (err: any) {
-      if (err?.status === 409) setError("You've already reviewed this product.");
+      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 submit review. Please try again.');
+      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}>
-      <input value={name} onChange={(e) => setName(e.target.value)} placeholder="Your name" required maxLength={100} />
-      <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email" />
-      <select value={rating} onChange={(e) => setRating(Number(e.target.value))}>
-        {[5,4,3,2,1].map(n => <option key={n} value={n}>{'\u2605'.repeat(n)}</option>)}
-      </select>
-      <textarea value={body} onChange={(e) => setBody(e.target.value)} maxLength={5000} placeholder="Tell us what you think (optional)" />
-      <button type="submit">Submit review</button>
+      <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>
   );
@@ -5533,9 +5883,9 @@ var FEATURES = [
   },
   {
     id: "product-reviews",
-    title: "Display + collect product reviews with stars + JSON-LD",
-    description: 'On the PDP show a Reviews section: list of customer reviews with star rating, author name, verified-purchase badge, body, and date. Include a submit form (name + email + 1-5 stars + optional body). 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; the merchant moderates from the admin surface. Rate-limited to 3 submits / 60s / IP. Show a friendly "you already reviewed this" message on 409.',
-    sdk: "client.listProductReviews(productId), client.submitProductReview(productId, { authorName, authorEmail, rating, body }). Product.avgRating + Product.reviewCount are denormalized rollups returned on every product fetch.",
+    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"
   },
   {