@brainerce/mcp-server 3.5.0 → 3.6.0

package/dist/index.js

@@ -119,7 +119,7 @@ npm install brainerce
 import { BrainerceClient } from 'brainerce';
 
 export const client = new BrainerceClient({
-  connectionId: '${connectionId}',
+  salesChannelId: '${connectionId}',
 });
 
 // Cart helpers \u2014 save cart ID to localStorage
@@ -221,7 +221,7 @@ async function startCheckout() {
 ### Full Checkout Flow (Multi-Provider)
 
 1. Customer fills cart
-2. Customer optionally applies coupon (cart page)
+2. Customer optionally applies coupon on cart page \u2192 \`applyCoupon(cartId, code)\`
 3. Detect payment providers \u2192 \`getPaymentProviders()\`
 4. Start checkout session (\`startGuestCheckout()\` or \`createCheckout()\`)
 5. Set shipping address (includes required email) \u2192 \`setShippingAddress()\`
@@ -239,7 +239,7 @@ import { Elements, PaymentElement, useStripe, useElements } from '@stripe/react-
 
 function CheckoutPage() {
   const [paymentData, setPaymentData] = useState<{
-    clientSecret: string; provider: string; checkoutId: string;
+    clientSecret: string; provider: string; checkoutId: string; clientSdk?: { renderType: string };
   } | null>(null);
   const [stripePromise, setStripePromise] = useState<ReturnType<typeof loadStripe> | null>(null);
   const [paypalClientId, setPaypalClientId] = useState<string | null>(null);
@@ -301,7 +301,7 @@ function CheckoutPage() {
         // saveCard: customerOptedIn,  // optional opt-in
       });
 
-      setPaymentData({ clientSecret: paymentIntent.clientSecret, provider: paymentIntent.provider, checkoutId });
+      setPaymentData({ clientSecret: paymentIntent.clientSecret, provider: paymentIntent.provider, checkoutId, clientSdk: paymentIntent.clientSdk });
 
       // Step 5: Initialize the correct payment provider
       if (paymentIntent.provider === 'stripe' && stripeProvider) {
@@ -911,6 +911,10 @@ function ProductPage({ product, storeInfo }: { product: Product; storeInfo: Stor
     ? getVariantPrice(selectedVariant, product.basePrice).toString()
     : product.salePrice || product.basePrice;
 
+  // \u2705 For catalog cards: use pre-computed priceMin/priceMax instead of iterating variants
+  // product.priceMin / product.priceMax are always set for VARIABLE products with explicit variant prices.
+  // product.priceVaries is true when the range should be shown as "\u20AA49 \u2013 \u20AA199".
+
   // Build attribute buttons (size, color, etc.)
   const allOptions = product.variants?.map(v => getVariantOptions(v)) || [];
   const attrNames = [...new Set(allOptions.flatMap(opts => opts.map(o => o.name)))];
@@ -1125,6 +1129,7 @@ const total = cart.total;
 
 ### Coupons
 
+**On the cart page** (before checkout is created):
 \`\`\`typescript
 // Apply coupon \u2014 returns updated Cart with discountAmount
 const updatedCart = await client.applyCoupon(cartId, 'SAVE20');
@@ -1132,13 +1137,24 @@ console.log(updatedCart.discountAmount); // "10.00"
 console.log(updatedCart.couponCode);     // "SAVE20"
 
 // Remove coupon
-const updatedCart = await client.removeCoupon(cartId);
+await client.removeCoupon(cartId);
 
 // Calculate totals including discount
 const totals = getCartTotals(cart); // { subtotal, discount, shipping, total }
 \`\`\`
 
-Add a coupon code input on the cart page. Coupons only work on server \`Cart\` (has \`id\` field). Checkout inherits the coupon \u2014 show \`checkout.discountAmount\` and \`checkout.couponCode\` in checkout order summary.
+**On the checkout page** (after checkout session exists \u2014 ALWAYS use this when checkoutId is available):
+\`\`\`typescript
+// Applies to cart AND updates checkout totals in one call
+const checkout = await client.applyCheckoutCoupon(checkoutId, 'SAVE20');
+console.log(checkout.discountAmount); // "10.00"
+console.log(checkout.total);          // correctly updated total
+
+// Remove coupon from checkout
+await client.removeCheckoutCoupon(checkoutId);
+\`\`\`
+
+> \u26A0\uFE0F **Critical:** if a checkout session already exists, ALWAYS use \`applyCheckoutCoupon(checkoutId, code)\`. Using \`applyCoupon(cartId, code)\` after checkout creation does NOT update the checkout total \u2014 payment will charge the original amount. Show \`checkout.discountAmount\` and \`checkout.couponCode\` in the order summary.
 
 ### \u26A0\uFE0F Checkout Order Summary \u2014 Use checkout.lineItems, NOT cart.items!
 
@@ -1563,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
 
@@ -1958,7 +2021,7 @@ subsequent SDK call sends the \`Accept-Language\` header automatically:
 \`\`\`typescript
 import { BrainerceClient } from 'brainerce';
 
-const client = new BrainerceClient({ connectionId: 'vc_...' });
+const client = new BrainerceClient({ salesChannelId: 'vc_...' });
 client.setLocale('he'); // done \u2014 all calls are now in Hebrew
 \`\`\`
 
@@ -2509,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":
@@ -2581,6 +2646,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getProductReviewsSection(),
+        "",
+        "---",
+        "",
         getDiscountsSection(),
         "",
         "---",
@@ -2632,6 +2701,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inventory",
     "discounts",
     "recommendations",
+    "reviews",
     "product-customization-fields",
     "tax",
     "critical-rules",
@@ -2675,6 +2745,9 @@ interface Product {
   basePrice: string;   // Use parseFloat() for calculations
   salePrice?: string | null;
   costPrice?: string | null;
+  priceMin?: string | null;  // Lowest variant price (VARIABLE products). Use for catalog/JSON-LD range display.
+  priceMax?: string | null;  // Highest variant price (VARIABLE products).
+  priceVaries?: boolean;     // true when variant prices differ \u2014 show "\u20AA49 \u2013 \u20AA199" range.
   status: string;
   type: 'SIMPLE' | 'VARIABLE';
   isDownloadable?: boolean;
@@ -3245,9 +3318,9 @@ var HELPERS_TYPES = `// ---- Helper Functions (import from 'brainerce') ----
 // Price helpers
 function formatPrice(priceString: string | number | undefined | null, options?: { currency?: string; locale?: string; }): string;
 function getProductPrice(product: Pick<Product, 'basePrice' | 'salePrice'>): number;
-function getProductPriceInfo(product: Pick<Product, 'basePrice' | 'salePrice'>): {
+function getProductPriceInfo(product: Pick<Product, 'basePrice' | 'salePrice' | 'discount' | 'priceMin' | 'priceVaries'>): {
   price: number; originalPrice: number; isOnSale: boolean; discountAmount: number; discountPercent: number;
-};
+}; // Falls back to priceMin when basePrice=0 (VARIABLE products)
 function getVariantPrice(variant: Pick<ProductVariant, 'price' | 'salePrice'>, productBasePrice: string): number;
 
 // Cart helpers
@@ -3360,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.
@@ -3603,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) {
@@ -3633,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.'
@@ -3749,7 +3855,7 @@ function selectVariant(product: Product, selections: Record<string, string>) {
 import { client } from './brainerce';
 
 // 1. Submit the address + email. Email is REQUIRED on the DTO.
-const { shippingRates } = await client.setShippingAddress(checkoutId, {
+const { checkout, rates } = await client.setShippingAddress(checkoutId, {
   email,
   firstName,
   lastName,
@@ -3760,10 +3866,11 @@ const { shippingRates } = await client.setShippingAddress(checkoutId, {
   postalCode,
   country,
 });
+// rates = available shipping rates; checkout = updated checkout object
 
 // 2. Let the customer pick one of the returned rates.
-const chosen = shippingRates[0]; // user selection
-await client.setShippingMethod(checkoutId, chosen.id);
+const chosen = rates[0]; // user selection
+await client.selectShippingMethod(checkoutId, chosen.id);
 
 // 3. Re-fetch the checkout to get updated totals (tax may change after address).
 const checkout = await client.getCheckout(checkoutId);
@@ -3817,21 +3924,21 @@ if (providers.length === 0) {
 }
 
 const active = providers[0];`,
-  "checkout-stripe-confirm": `// Stripe confirm flow. Requires @stripe/stripe-js and @stripe/react-stripe-js
-// (or the vanilla Stripe.js browser SDK).
+  "checkout-stripe-confirm": `// Stripe confirm flow. Requires @stripe/stripe-js.
 import { loadStripe } from '@stripe/stripe-js';
 import { client } from './brainerce';
 
 const stripe = await loadStripe(stripePublicKey);
 if (!stripe) throw new Error('Stripe failed to load');
 
-// The SDK returns a clientSecret via the provider's config after setPaymentMethod.
-const { clientSecret } = await client.setPaymentMethod(checkoutId, {
-  providerId: stripeProvider.id,
+// Create a payment intent \u2014 returns clientSecret for Stripe Elements.
+const intent = await client.createPaymentIntent(checkoutId, {
+  successUrl: \`\${window.location.origin}/order-confirmation?checkoutId=\${checkoutId}\`,
+  cancelUrl: \`\${window.location.origin}/checkout?error=cancelled\`,
 });
 
-// Use Stripe Elements to collect the card, then confirm:
-const result = await stripe.confirmCardPayment(clientSecret, {
+// Use Stripe Elements to confirm:
+const result = await stripe.confirmCardPayment(intent.clientSecret, {
   payment_method: { card: cardElement },
 });
 
@@ -3840,21 +3947,21 @@ if (result.error) {
   return;
 }
 
-// Success \u2014 redirect to your confirmation page with checkoutId in the URL.
+// Success \u2014 redirect to confirmation page.
 // The confirmation page runs handlePaymentSuccess + waitForOrder.
 window.location.assign(\`/order-confirmation?checkoutId=\${checkoutId}\`);`,
   "checkout-paypal-confirm": `// PayPal confirm flow. Use the PayPal JS SDK (render a PayPal button component).
 import { client } from './brainerce';
 
-// When the PayPal button's onApprove fires with the PayPal order ID:
-async function onPayPalApprove(paypalOrderId: string) {
-  await client.setPaymentMethod(checkoutId, {
-    providerId: paypalProvider.id,
-    providerData: { paypalOrderId },
-  });
+// Create a payment intent first \u2014 for PayPal this returns the PayPal order ID.
+const intent = await client.createPaymentIntent(checkoutId, {
+  successUrl: \`\${window.location.origin}/order-confirmation?checkoutId=\${checkoutId}\`,
+  cancelUrl: \`\${window.location.origin}/checkout?error=cancelled\`,
+});
 
-  // PayPal confirmation \u2014 the SDK captures the order server-side.
-  // After this resolves, redirect to confirmation.
+// Render a PayPal button using intent.clientSdk (provider SDK config).
+// When the PayPal button's onApprove fires, redirect to confirmation:
+function onPayPalApprove() {
   window.location.assign(\`/order-confirmation?checkoutId=\${checkoutId}\`);
 }`,
   "checkout-sandbox-confirm": `// Sandbox payment \u2014 store has sandboxPaymentsEnabled=true. No real charge.
@@ -3897,7 +4004,7 @@ async function registerAndMaybeVerify(input: {
   firstName: string;
   lastName: string;
 }) {
-  const result = await client.register(input);
+  const result = await client.registerCustomer(input);
   if (result.requiresVerification) {
     // Route the user to your verify-email UI. Do NOT treat them as logged in.
     return { state: 'needs-verification' as const };
@@ -3918,7 +4025,7 @@ async function resendCode() {
 import { client } from './brainerce';
 
 async function login(email: string, password: string) {
-  const result = await client.login({ email, password });
+  const result = await client.loginCustomer(email, password);
   if (result.requiresVerification) {
     return { state: 'needs-verification' as const };
   }
@@ -3953,25 +4060,37 @@ async function submitReset(token: string, newPassword: string) {
   "oauth-redirect-and-callback": `// OAuth sign-in. Redirect flow, NOT popup.
 import { client } from './brainerce';
 
-// On your login / register UI:
-const providers = await client.getAvailableOAuthProviders();
-// Render one button per provider. On click, redirect the browser:
-for (const p of providers) {
-  // button.onclick = () => window.location.assign(p.authorizationUrl)
+// Step 1: Get available provider names (strings: 'GOOGLE', 'FACEBOOK', 'GITHUB')
+const { providers } = await client.getAvailableOAuthProviders();
+
+// Step 2: For each provider, fetch the authorization URL, then redirect.
+// Call this when the user clicks a provider button:
+async function redirectToOAuth(provider: string) {
+  const { authorizationUrl } = await client.getOAuthAuthorizeUrl(provider, {
+    redirectUrl: \`\${window.location.origin}/auth/callback\`,
+  });
+  window.location.href = authorizationUrl; // full-page redirect, NOT a popup
 }
 
-// On your OAuth callback route (SERVER-SIDE / BFF):
-// 1. Read token + oauth_success (or oauth_error) from query params.
-// 2. If oauth_error: redirect to login with the error message.
-// 3. If oauth_success: exchange the token for a session cookie (your BFF),
-//    then redirect the browser to /account or wherever.
-// Do NOT allow the token to land in browser history as a query param.`,
+// Step 3: On your /auth/callback route, read token from URL params:
+const params = new URLSearchParams(window.location.search);
+const oauthError = params.get('oauth_error');
+const token = params.get('token');
+if (oauthError) {
+  window.location.href = '/login?error=' + encodeURIComponent(oauthError);
+} else if (token) {
+  client.setCustomerToken(token);
+  window.location.href = '/account';
+}`,
   "coupon-apply-and-remove": `// Coupon input. Build the UI even if no coupons exist today \u2014 it auto-hides.
+// IMPORTANT: use applyCheckoutCoupon when a checkoutId is available (checkout page).
+// Using applyCoupon after checkout creation does NOT update the checkout total.
 import { client } from './brainerce';
 
-async function applyCoupon(code: string) {
+// On cart page (no checkout session yet)
+async function applyCouponToCart(cartId: string, code: string) {
   try {
-    const cart = await client.applyCoupon(code);
+    const cart = await client.applyCoupon(cartId, code);
     return { ok: true, cart };
   } catch (err) {
     // Invalid / expired / minimum not met. Surface the specific error.
@@ -3979,17 +4098,30 @@ async function applyCoupon(code: string) {
   }
 }
 
-async function removeCoupon() {
-  const cart = await client.removeCoupon();
-  return cart;
+async function removeCouponFromCart(cartId: string) {
+  return client.removeCoupon(cartId);
+}
+
+// On checkout page (checkout session already exists \u2014 always prefer this)
+async function applyCouponToCheckout(checkoutId: string, code: string) {
+  try {
+    const checkout = await client.applyCheckoutCoupon(checkoutId, code);
+    return { ok: true, checkout }; // checkout.total is already updated
+  } catch (err) {
+    return { ok: false, error: (err as Error).message };
+  }
+}
+
+async function removeCouponFromCheckout(checkoutId: string) {
+  return client.removeCheckoutCoupon(checkoutId);
 }`,
   "reservation-countdown": `// Reservation countdown. Use the SDK's expiry timestamp \u2014 do NOT invent
 // your own timer state.
 import { client } from './brainerce';
 
-function getRemainingMs(cart: { reservationExpiresAt?: string | null }): number {
-  if (!cart.reservationExpiresAt) return 0;
-  const expiry = new Date(cart.reservationExpiresAt).getTime();
+function getRemainingMs(cart: { reservation?: { expiresAt?: string } }): number {
+  if (!cart.reservation?.expiresAt) return 0;
+  const expiry = new Date(cart.reservation.expiresAt).getTime();
   return Math.max(0, expiry - Date.now());
 }
 
@@ -4016,8 +4148,8 @@ function onSearchChange(query: string, onResults: (items: unknown[]) => void) {
     return;
   }
   searchTimer = setTimeout(async () => {
-    const results = await client.searchProducts(query);
-    onResults(results);
+    const { products } = await client.getSearchSuggestions(query);
+    onResults(products);
   }, 300);
 }`,
   "i18n-set-locale": `// i18n \u2014 only if get-store-capabilities reports i18n.enabled.
@@ -4374,19 +4506,13 @@ import { client } from './brainerce-client';
 
 interface CheckoutOptions {
   cartId: string;
-  shippingAddress: object;
-  shippingMethodId: string;
-  paymentProviderId: string;
 }
 
 async function createCheckoutSafe(opts: CheckoutOptions) {
   try {
-    return await client.createCheckout({
-      cartId: opts.cartId,
-      shippingAddress: opts.shippingAddress,
-      shippingMethodId: opts.shippingMethodId,
-      paymentProviderId: opts.paymentProviderId,
-    });
+    // createCheckout only takes cartId (+ optional customerId, selectedItemIds).
+    // Shipping address, shipping method, and payment are set via separate calls.
+    return await client.createCheckout({ cartId: opts.cartId });
   } catch (err: unknown) {
     if (!isApiError(err, 'PRICE_DRIFT')) throw err;
 
@@ -4516,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) {
@@ -5061,21 +5274,21 @@ var FLOWS = {
 1. **Collect address + email.** Build a form that captures customer email, billing address, shipping address (with \`line1\`, \`line2\`, \`city\`, \`region\`, \`postalCode\`, \`country\`). \`email\` is REQUIRED on \`SetShippingAddressDto\`.
 2. **Submit the address to get shipping rates.**
    \`\`\`ts
-   const { shippingRates } = await client.setShippingAddress(checkoutId, {
+   const { checkout, rates } = await client.setShippingAddress(checkoutId, {
      email,
      firstName,
      lastName,
      line1, line2, city, region, postalCode, country,
    });
    \`\`\`
-   The response includes the available shipping rates for that address + the store's zones.
+   \`rates\` = available shipping rates for that address + the store's zones. \`checkout\` = updated checkout object.
 3. **Let the customer pick a rate**, then persist the selection:
    \`\`\`ts
-   await client.setShippingMethod(checkoutId, rateId);
+   await client.selectShippingMethod(checkoutId, rateId);
    \`\`\`
-4. **Fetch payment providers for this checkout:**
+4. **Fetch payment providers:**
    \`\`\`ts
-   const providers = await client.getPaymentProviders(checkoutId);
+   const providers = await client.getPaymentProviders();
    \`\`\`
    The response tells you which providers are configured (Stripe, Grow, PayPal, Sandbox) and how to render each. Each provider has a \`renderType\` telling you whether to show a Stripe Elements form, a redirect button, a PayPal button, or a sandbox "complete test order" button.
 5. **Confirm payment using the provider's recommended flow.** For Stripe: Stripe Elements \u2192 \`stripe.confirmCardPayment\` using the clientSecret returned by the SDK. For sandbox payments: call \`completeGuestCheckout(checkoutId)\` directly. For PayPal/Grow: follow the redirect and handle the return on your confirmation page.
@@ -5091,28 +5304,28 @@ Never bypass these steps. Never call \`submitGuestOrder\` / \`createOrder\` \u20
   "auth-register": {
     title: "Registration",
     body: `1. **Collect** email, password, first name, last name. Enforce strong passwords client-side: 8+ chars, upper, lower, number, special.
-2. **Call register:**
+2. **Call registerCustomer:**
    \`\`\`ts
-   const result = await client.register({ email, password, firstName, lastName });
+   const result = await client.registerCustomer({ email, password, firstName, lastName });
    \`\`\`
 3. **Branch on \`result.requiresVerification\`:**
-   - If \`true\`: route the user to your verify-email UI. Do NOT treat them as logged in yet.
-   - If \`false\`: the user is logged in. Store the token via your BFF session and route to the account area.
+   - If \`true\`: store the token temporarily (e.g. sessionStorage), route the user to your verify-email UI. Do NOT treat them as logged in yet.
+   - If \`false\`: call \`client.setCustomerToken(result.token)\` and route to the account area.
 4. **On the verify-email step:** collect a 6-digit code and call \`client.verifyEmail(code)\`. Offer a "resend code" button wired to \`client.resendVerificationEmail()\`.
-5. **After verifyEmail resolves:** the user is now logged in. Persist the session via your BFF and route to the account area.
+5. **After verifyEmail resolves:** call \`client.setCustomerToken(result.token)\` \u2014 the user is now logged in \u2014 then route to the account area.
 
 Build the verify-email step EVEN IF the store currently has verification disabled. It auto-hides; store owners enable it later.`
   },
   "auth-login": {
     title: "Login",
     body: `1. **Collect** email + password.
-2. **Call login:**
+2. **Call loginCustomer:**
    \`\`\`ts
-   const result = await client.login({ email, password });
+   const result = await client.loginCustomer(email, password);
    \`\`\`
 3. **Branch on \`result.requiresVerification\`:**
    - If \`true\`: route to verify-email. The user must complete verification before accessing account features.
-   - If \`false\`: persist the session via your BFF and route to the previous page (or account area).
+   - If \`false\`: call \`client.setCustomerToken(result.token)\` and route to the previous page (or account area).
 4. **Offer OAuth buttons** from \`client.getAvailableOAuthProviders()\`. Render a placeholder region even when no providers are returned \u2014 the region auto-hides today and shows buttons the moment a provider is enabled in the dashboard.
 5. **On error**, render the specific message (invalid credentials, rate limited, account disabled) \u2014 never swallow.`
   },
@@ -5137,15 +5350,24 @@ Build both steps EVEN IF the store has no email provider configured today \u2014
   },
   oauth: {
     title: "OAuth sign-in",
-    body: `1. **Render available providers:**
+    body: `1. **Get available provider names:**
    \`\`\`ts
-   const providers = await client.getAvailableOAuthProviders();
+   const { providers } = await client.getAvailableOAuthProviders();
+   // providers = ['GOOGLE', 'FACEBOOK', 'GITHUB'] (strings, not objects with authorizationUrl)
+   \`\`\`
+2. **For each provider, fetch the authorization URL:**
+   \`\`\`ts
+   const { authorizationUrl } = await client.getOAuthAuthorizeUrl(provider, {
+     redirectUrl: \`\${window.location.origin}/auth/callback\`,
+   });
+   window.location.href = authorizationUrl; // full-page redirect, NOT a popup
    \`\`\`
-   Each provider has \`{ provider: 'GOOGLE' | 'FACEBOOK' | 'GITHUB', authorizationUrl }\`.
-2. **Build a button for each** that redirects the browser to \`authorizationUrl\`. Do NOT open a popup; the full-page redirect is required.
-3. **On the provider's side** the user authenticates, and the provider redirects back to your OAuth callback URL with \`token\` + \`oauth_success\` (or \`oauth_error\`) query params.
-4. **The callback handler MUST run server-side (BFF).** Extract the token from the query params, exchange it for a session cookie via your BFF, then redirect the browser to the account area. Never let the token land in browser history as a query param or localStorage.
-5. **On \`oauth_error\`:** redirect to login with an error message.
+3. **On the callback page** the URL contains \`token\` + \`oauth_success\` (or \`oauth_error\`) query params. Extract and apply the token:
+   \`\`\`ts
+   const token = new URLSearchParams(location.search).get('token');
+   if (token) client.setCustomerToken(token); // then redirect to account
+   \`\`\`
+4. **On \`oauth_error\`:** redirect to login with an error message.
 
 Build the OAuth button region AND the callback handler even when no providers are configured. They auto-hide.`
   },
@@ -5167,7 +5389,7 @@ Build the OAuth button region AND the callback handler even when no providers ar
 
 - **Cart ID persistence:** the SDK stores the cart ID across reloads. You do not need to write cart-to-localStorage code yourself.
 - **Reads:** \`client.getCart()\` returns the current cart. Call it on mount in your cart UI and on any page that shows a cart count (header).
-- **Writes:** use \`client.addToCart\`, \`client.updateCartItem\`, \`client.removeCartItem\`, \`client.applyCoupon\`, \`client.removeCoupon\`. After each mutation the SDK returns the updated cart.
+- **Writes:** use \`client.addToCart\`, \`client.updateCartItem\`, \`client.removeCartItem\`, \`client.applyCoupon\`, \`client.removeCoupon\`. After each mutation the SDK returns the updated cart. On the **checkout page** use \`client.applyCheckoutCoupon(checkoutId, code)\` / \`client.removeCheckoutCoupon(checkoutId)\` \u2014 these update checkout totals atomically. Never use \`applyCoupon\` after a checkout session exists.
 - **Totals:** call \`getCartTotals(cart)\` \u2014 do NOT read \`cart.total\`. The helper understands taxes, shipping, and discounts.
 - **\`smartGetCart()\`** returns \`CartWithIncludes\` (extends \`Cart\`). All carts are server-side. Pass \`{ include: ['recommendations', 'upgrades', 'bundles'] }\` to fetch extras in one request.
 - **NEVER mutate cart state outside SDK helpers.** Any hand-rolled cart update risks desync with the reservation timer and the checkout flow.`
@@ -5299,7 +5521,7 @@ var FEATURES = [
     id: "browse-products",
     title: "Browse, filter, and search products",
     description: "Users can list products with pagination, apply category / price / attribute / custom-field filters, sort by name / price / newest, and run a search with autocomplete. Custom-field filters surface metafield definitions whose filterable=true (SELECT, MULTI_SELECT, BOOLEAN). Must handle empty states and loading states.",
-    sdk: "client.getProducts({ page, limit, filters, sort, metafields }), client.getPublicMetafieldDefinitions(), client.searchProducts(query)",
+    sdk: "client.getProducts({ page, limit, filters, sort, metafields }), client.getPublicMetafieldDefinitions(), client.getSearchSuggestions(query)",
     mandatory: "mandatory"
   },
   {
@@ -5309,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",
@@ -5329,7 +5558,7 @@ var FEATURES = [
     id: "cart-coupons",
     title: "Apply and remove coupon codes",
     description: "Users can enter a coupon code, see it applied to the cart, see the discount amount, and remove it. Build the UI even if no coupons are configured today \u2014 it auto-hides.",
-    sdk: "client.applyCoupon(code), client.removeCoupon()",
+    sdk: "client.applyCoupon(cartId, code), client.removeCoupon(cartId) \u2014 on cart page. client.applyCheckoutCoupon(checkoutId, code), client.removeCheckoutCoupon(checkoutId) \u2014 on checkout page (use when checkoutId exists)",
     mandatory: "mandatory",
     capabilityFlag: "hasCoupons",
     whenDisabledNote: "Store has no coupons configured today. Build the UI anyway \u2014 it auto-hides until the store owner creates a coupon."
@@ -5346,7 +5575,7 @@ var FEATURES = [
     id: "checkout",
     title: "Complete a full checkout end-to-end",
     description: "Users can enter their address, pick a shipping rate, pick a payment provider, pay, and land on a confirmation page showing the real order. Displays checkout.lineItems (not cart.items) on the summary.",
-    sdk: "client.setShippingAddress, client.setShippingMethod, client.getPaymentProviders, provider-specific confirm, client.handlePaymentSuccess, client.waitForOrder",
+    sdk: "client.setShippingAddress (returns { checkout, rates }), client.selectShippingMethod, client.getPaymentProviders(), provider-specific confirm, client.handlePaymentSuccess, client.waitForOrder",
     flowRef: "checkout",
     mandatory: "mandatory"
   },
@@ -5362,7 +5591,7 @@ var FEATURES = [
     id: "register",
     title: "Register a new account with email verification",
     description: 'Users can create an account (email, password, first + last name). Handles the requiresVerification branch by routing to an email-verification step. Verification step collects a 6-digit code and has a "resend code" action.',
-    sdk: "client.register({email, password, firstName, lastName}), client.verifyEmail(code), client.resendVerificationEmail()",
+    sdk: "client.registerCustomer({email, password, firstName, lastName}), client.verifyEmail(code), client.resendVerificationEmail()",
     flowRef: "auth-register",
     mandatory: "mandatory",
     capabilityFlag: "oauth",
@@ -5372,7 +5601,7 @@ var FEATURES = [
     id: "login",
     title: "Log in with email / password and handle verification branch",
     description: "Users can log in. The login form handles the requiresVerification branch by routing to the verify-email step. Specific errors render (bad credentials, rate limited, disabled account).",
-    sdk: "client.login({email, password})",
+    sdk: "client.loginCustomer(email, password)",
     flowRef: "auth-login",
     mandatory: "mandatory"
   },
@@ -5405,14 +5634,14 @@ var FEATURES = [
     id: "header",
     title: "Global header with cart count and search",
     description: "A header visible across the experience with the store logo, navigation, a cart icon with live item count, a search input with autocomplete (debounced ~300ms, 2-char minimum), and a login / account action. Below the header, discount banners render when active.",
-    sdk: "client.getCart() for the count, client.searchProducts(query) for autocomplete",
+    sdk: "client.getCart() for the count, client.getSearchSuggestions(query) for autocomplete",
     mandatory: "mandatory"
   },
   {
     id: "discount-banners",
     title: "Show active discount banners and badges",
     description: "Active discount rules render as banners (below the header) and as badges on product cards / detail pages. Build the UI even if the store has no active discounts today \u2014 it auto-hides.",
-    sdk: "client.getDiscountBanners(), getProductDiscountBadge(product)",
+    sdk: "client.getDiscountBanners(), client.getProductDiscountBadge(productId)",
     mandatory: "mandatory",
     capabilityFlag: "hasDiscountRules",
     whenDisabledNote: "Store has no discount rules active. Build the banner and badge components anyway \u2014 they auto-hide."