@brainerce/mcp-server 3.6.0 → 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
@@ -1550,17 +1719,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.
@@ -1589,9 +1769,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() {
@@ -2687,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 {
@@ -3421,11 +3600,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:
@@ -3728,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",
@@ -3797,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';
 
@@ -4611,21 +4916,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>
@@ -4658,42 +4967,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>
   );
@@ -5501,9 +5851,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"
   },
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainerce/mcp-server",
-  "version": "3.6.0",
+  "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"