@brainerce/mcp-server 3.5.1 → 3.6.0

package/dist/bin/http.js

@@ -1555,6 +1555,53 @@ 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)
+
+Reviews publish immediately on submit. Merchants hide individual reviews via the admin surface \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 submit form
+await client.submitProductReview(productId, {
+  authorName, authorEmail, rating: 5, body,
+});
+\`\`\`
+
+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).
+- 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.
+- Stores with \`reviewsEnabled = false\` return 403 on storefront endpoints.`;
+}
 function getInventorySection() {
   return `## Inventory, Stock Display & Reservation Countdown
 
@@ -2501,6 +2548,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":
@@ -2573,6 +2622,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getProductReviewsSection(),
+        "",
+        "---",
+        "",
         getDiscountsSection(),
         "",
         "---",
@@ -2624,6 +2677,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inventory",
     "discounts",
     "recommendations",
+    "reviews",
     "product-customization-fields",
     "tax",
     "critical-rules",
@@ -3355,6 +3409,37 @@ 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 SubmitProductReviewInput {
+  authorName: string;
+  authorEmail?: string;              // recommended \u2014 used for guest dedupe + verified-purchase derivation
+  rating: number;                    // 1-5
+  body?: string;                     // optional
+}
+
+// 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.
@@ -3598,6 +3683,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) {
@@ -3628,6 +3714,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.'
@@ -4531,6 +4618,93 @@ function renderCartItem(item: CartItem): string {
 // multiply unitPrice \xD7 quantity directly.
 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';
+
+export async function ProductReviewsSection({ product }: { product: Product }) {
+  const { data } = await client.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.map((r) => (
+        <article key={r.id}>
+          <strong>{r.authorName}</strong>
+          {r.verifiedPurchase && <span> \xB7 Verified</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 { useState } from 'react';
+
+function ReviewForm({ productId }: { productId: string }) {
+  const [rating, setRating] = useState(5);
+  const [body, setBody] = useState('');
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [error, setError] = useState<string | null>(null);
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    try {
+      await client.submitProductReview(productId, {
+        authorName: name,
+        authorEmail: email,
+        rating,
+        body: body || undefined,
+      });
+      window.location.reload();
+    } catch (err: any) {
+      if (err?.status === 409) setError("You've 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.');
+    }
+  }
+
+  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>
+      {error && <p role="alert">{error}</p>}
+    </form>
+  );
 }`
 };
 async function handleGetCodeExample(args) {
@@ -5333,6 +5507,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 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.",
+    mandatory: "mandatory"
+  },
   {
     id: "product-customization-fields",
     title: "Render buyer-input customization fields on the product page",

package/dist/bin/stdio.js

@@ -1553,6 +1553,53 @@ 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)
+
+Reviews publish immediately on submit. Merchants hide individual reviews via the admin surface \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 submit form
+await client.submitProductReview(productId, {
+  authorName, authorEmail, rating: 5, body,
+});
+\`\`\`
+
+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).
+- 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.
+- Stores with \`reviewsEnabled = false\` return 403 on storefront endpoints.`;
+}
 function getInventorySection() {
   return `## Inventory, Stock Display & Reservation Countdown
 
@@ -2499,6 +2546,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":
@@ -2571,6 +2620,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getProductReviewsSection(),
+        "",
+        "---",
+        "",
         getDiscountsSection(),
         "",
         "---",
@@ -2622,6 +2675,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inventory",
     "discounts",
     "recommendations",
+    "reviews",
     "product-customization-fields",
     "tax",
     "critical-rules",
@@ -3353,6 +3407,37 @@ 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 SubmitProductReviewInput {
+  authorName: string;
+  authorEmail?: string;              // recommended \u2014 used for guest dedupe + verified-purchase derivation
+  rating: number;                    // 1-5
+  body?: string;                     // optional
+}
+
+// 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.
@@ -3596,6 +3681,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) {
@@ -3626,6 +3712,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.'
@@ -4529,6 +4616,93 @@ function renderCartItem(item: CartItem): string {
 // multiply unitPrice \xD7 quantity directly.
 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';
+
+export async function ProductReviewsSection({ product }: { product: Product }) {
+  const { data } = await client.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.map((r) => (
+        <article key={r.id}>
+          <strong>{r.authorName}</strong>
+          {r.verifiedPurchase && <span> \xB7 Verified</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 { useState } from 'react';
+
+function ReviewForm({ productId }: { productId: string }) {
+  const [rating, setRating] = useState(5);
+  const [body, setBody] = useState('');
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [error, setError] = useState<string | null>(null);
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    try {
+      await client.submitProductReview(productId, {
+        authorName: name,
+        authorEmail: email,
+        rating,
+        body: body || undefined,
+      });
+      window.location.reload();
+    } catch (err: any) {
+      if (err?.status === 409) setError("You've 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.');
+    }
+  }
+
+  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>
+      {error && <p role="alert">{error}</p>}
+    </form>
+  );
 }`
 };
 async function handleGetCodeExample(args) {
@@ -5331,6 +5505,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 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.",
+    mandatory: "mandatory"
+  },
   {
     id: "product-customization-fields",
     title: "Render buyer-input customization fields on the product page",

package/dist/index.js

@@ -1579,6 +1579,53 @@ 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)
+
+Reviews publish immediately on submit. Merchants hide individual reviews via the admin surface \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 submit form
+await client.submitProductReview(productId, {
+  authorName, authorEmail, rating: 5, body,
+});
+\`\`\`
+
+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).
+- 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.
+- Stores with \`reviewsEnabled = false\` return 403 on storefront endpoints.`;
+}
 function getInventorySection() {
   return `## Inventory, Stock Display & Reservation Countdown
 
@@ -2525,6 +2572,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 +2646,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getProductReviewsSection(),
+        "",
+        "---",
+        "",
         getDiscountsSection(),
         "",
         "---",
@@ -2648,6 +2701,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inventory",
     "discounts",
     "recommendations",
+    "reviews",
     "product-customization-fields",
     "tax",
     "critical-rules",
@@ -3379,6 +3433,37 @@ 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 SubmitProductReviewInput {
+  authorName: string;
+  authorEmail?: string;              // recommended \u2014 used for guest dedupe + verified-purchase derivation
+  rating: number;                    // 1-5
+  body?: string;                     // optional
+}
+
+// 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 +3707,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 +3738,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.'
@@ -4555,6 +4642,93 @@ function renderCartItem(item: CartItem): string {
 // multiply unitPrice \xD7 quantity directly.
 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';
+
+export async function ProductReviewsSection({ product }: { product: Product }) {
+  const { data } = await client.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.map((r) => (
+        <article key={r.id}>
+          <strong>{r.authorName}</strong>
+          {r.verifiedPurchase && <span> \xB7 Verified</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 { useState } from 'react';
+
+function ReviewForm({ productId }: { productId: string }) {
+  const [rating, setRating] = useState(5);
+  const [body, setBody] = useState('');
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [error, setError] = useState<string | null>(null);
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    try {
+      await client.submitProductReview(productId, {
+        authorName: name,
+        authorEmail: email,
+        rating,
+        body: body || undefined,
+      });
+      window.location.reload();
+    } catch (err: any) {
+      if (err?.status === 409) setError("You've 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.');
+    }
+  }
+
+  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>
+      {error && <p role="alert">{error}</p>}
+    </form>
+  );
 }`
 };
 async function handleGetCodeExample(args) {
@@ -5357,6 +5531,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 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.",
+    mandatory: "mandatory"
+  },
   {
     id: "product-customization-fields",
     title: "Render buyer-input customization fields on the product page",

package/dist/index.mjs

@@ -1547,6 +1547,53 @@ 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)
+
+Reviews publish immediately on submit. Merchants hide individual reviews via the admin surface \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 submit form
+await client.submitProductReview(productId, {
+  authorName, authorEmail, rating: 5, body,
+});
+\`\`\`
+
+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).
+- 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.
+- Stores with \`reviewsEnabled = false\` return 403 on storefront endpoints.`;
+}
 function getInventorySection() {
   return `## Inventory, Stock Display & Reservation Countdown
 
@@ -2493,6 +2540,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 +2614,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getProductReviewsSection(),
+        "",
+        "---",
+        "",
         getDiscountsSection(),
         "",
         "---",
@@ -2616,6 +2669,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inventory",
     "discounts",
     "recommendations",
+    "reviews",
     "product-customization-fields",
     "tax",
     "critical-rules",
@@ -3347,6 +3401,37 @@ 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 SubmitProductReviewInput {
+  authorName: string;
+  authorEmail?: string;              // recommended \u2014 used for guest dedupe + verified-purchase derivation
+  rating: number;                    // 1-5
+  body?: string;                     // optional
+}
+
+// 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 +3675,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 +3706,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.'
@@ -4523,6 +4610,93 @@ function renderCartItem(item: CartItem): string {
 // multiply unitPrice \xD7 quantity directly.
 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';
+
+export async function ProductReviewsSection({ product }: { product: Product }) {
+  const { data } = await client.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.map((r) => (
+        <article key={r.id}>
+          <strong>{r.authorName}</strong>
+          {r.verifiedPurchase && <span> \xB7 Verified</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 { useState } from 'react';
+
+function ReviewForm({ productId }: { productId: string }) {
+  const [rating, setRating] = useState(5);
+  const [body, setBody] = useState('');
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [error, setError] = useState<string | null>(null);
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    try {
+      await client.submitProductReview(productId, {
+        authorName: name,
+        authorEmail: email,
+        rating,
+        body: body || undefined,
+      });
+      window.location.reload();
+    } catch (err: any) {
+      if (err?.status === 409) setError("You've 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.');
+    }
+  }
+
+  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>
+      {error && <p role="alert">{error}</p>}
+    </form>
+  );
 }`
 };
 async function handleGetCodeExample(args) {
@@ -5325,6 +5499,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 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.",
+    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.6.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"