brainerce 1.7.0 → 1.10.0

package/AI_BUILDER_PROMPT.md

@@ -1,842 +1,843 @@
-# Brainerce Store Builder
-
-Build a **{store_type}** store called "{store_name}" | Style: **{style}** | Currency: **{currency}**
-
----
-
-## ⛔ STOP! Read These 3 Rules First (Breaking = Store Won't Work)
-
-### Rule 1: Guest vs Logged-In = Different Checkout Methods!
-
-```typescript
-// ❌ THIS WILL FAIL - "Cart not found" error!
-const cart = await client.smartGetCart(); // Guest cart has id: "__local__"
-await client.createCheckout({ cartId: cart.id }); // 💥 "__local__" doesn't exist on server!
-
-// ✅ CORRECT - Check user type first!
-if (client.isCustomerLoggedIn()) {
-  // Logged-in user → server cart exists
-  const checkout = await client.createCheckout({ cartId: cart.id });
-  const checkoutId = checkout.id;
-} else {
-  // Guest user → use startGuestCheckout()
-  const result = await client.startGuestCheckout();
-  const checkoutId = result.checkoutId;
-}
-```
-
-| User Type     | Cart Location | Checkout Method              | Get Checkout ID     |
-| ------------- | ------------- | ---------------------------- | ------------------- |
-| **Guest**     | localStorage  | `startGuestCheckout()`       | `result.checkoutId` |
-| **Logged-in** | Server        | `createCheckout({ cartId })` | `checkout.id`       |
-
-### Rule 2: Complete Checkout & Clear Cart After Payment!
-
-```typescript
-// On /checkout/success page - MUST DO THIS!
-export default function CheckoutSuccessPage() {
-  const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
-
-  useEffect(() => {
-    if (checkoutId) {
-      // ⚠️ CRITICAL: This sends the order to the server AND clears the cart!
-      // handlePaymentSuccess() only clears the local cart - it does NOT create the order!
-      client.completeGuestCheckout(checkoutId);
-    }
-  }, []);
-
-  return <div>Thank you for your order!</div>;
-}
-```
-
-> **WARNING:** Do NOT use `handlePaymentSuccess()` to complete an order. It only clears
-> the local cart (localStorage) and does NOT communicate with the server.
-> Always use `completeGuestCheckout()` after payment succeeds.
-
-### Rule 3: Never Hardcode Products!
-
-```typescript
-// ❌ FORBIDDEN - Store will show fake data!
-const products = [{ id: '1', name: 'T-Shirt', price: 29.99 }];
-
-// ✅ CORRECT - Fetch from API
-const { data: products } = await client.getProducts();
-```
-
----
-
-## Quick Setup
-
-```bash
-npm install brainerce
-```
-
-```typescript
-// lib/brainerce.ts
-import { BrainerceClient } from 'brainerce';
-
-export const client = new BrainerceClient({
-  connectionId: '{connection_id}',
-  baseUrl: '{api_url}',
-});
-
-// Restore customer session on page load
-export function initBrainerce() {
-  if (typeof window === 'undefined') return;
-  const token = localStorage.getItem('customerToken');
-  if (token) client.setCustomerToken(token);
-}
-
-// Save/clear customer token
-export function setCustomerToken(token: string | null) {
-  if (token) {
-    localStorage.setItem('customerToken', token);
-    client.setCustomerToken(token);
-  } else {
-    localStorage.removeItem('customerToken');
-    client.clearCustomerToken();
-  }
-}
-```
-
----
-
-## Cart (Works for Both Guest & Logged-in)
-
-```typescript
-// Get or create cart - handles both guest (localStorage) and logged-in (server) automatically
-const cart = await client.smartGetCart();
-
-// Add to cart - ALWAYS pass name, price, image for guest cart display!
-await client.smartAddToCart({
-  productId: product.id,
-  variantId: selectedVariant?.id,
-  quantity: 1,
-  // IMPORTANT: Pass product info for guest cart display
-  name: selectedVariant?.name ? `${product.name} - ${selectedVariant.name}` : product.name,
-  price: getVariantPrice(selectedVariant, product.basePrice),
-  image: selectedVariant?.image
-    ? typeof selectedVariant.image === 'string'
-      ? selectedVariant.image
-      : selectedVariant.image.url
-    : product.images?.[0]?.url,
-});
-
-// Update quantity (by productId, not itemId!)
-await client.smartUpdateCartItem('prod_xxx', 2); // productId, quantity
-await client.smartUpdateCartItem('prod_xxx', 3, 'var_xxx'); // with variant
-
-// Remove item (by productId, not itemId!)
-await client.smartRemoveFromCart('prod_xxx');
-await client.smartRemoveFromCart('prod_xxx', 'var_xxx'); // with variant
-
-// Get cart totals (cart doesn't have .total field!)
-import { getCartTotals } from 'brainerce';
-const totals = getCartTotals(cart);
-// { subtotal: 59.98, discount: 10, shipping: 0, total: 49.98 }
-
-// All smart* methods return a server Cart (even for guests via session carts)
-// Cart has: id, itemCount, subtotal, discountAmount, items, couponCode
-```
-
-### 🏷️ Coupon Code (Add to Cart Page!)
-
-```typescript
-// Apply coupon to cart
-const cart = await client.smartGetCart();
-const updatedCart = await client.applyCoupon(cart.id, 'SAVE20');
-console.log(updatedCart.discountAmount); // "10.00" (string)
-console.log(updatedCart.couponCode); // "SAVE20"
-
-// Remove coupon
-const updatedCart = await client.removeCoupon(cartId);
-
-// Calculate totals including discount
-import { getCartTotals } from 'brainerce';
-const totals = getCartTotals(cart); // { subtotal, discount, shipping, total }
-```
-
-**Cart page coupon UI:**
-
-```typescript
-// State
-const [couponCode, setCouponCode] = useState('');
-const [couponError, setCouponError] = useState('');
-const [isApplying, setIsApplying] = useState(false);
-
-// Apply handler
-async function handleApplyCoupon() {
-  if (!couponCode.trim() || !('id' in cart)) return;
-  setIsApplying(true);
-  setCouponError('');
-  try {
-    const updatedCart = await client.applyCoupon(cart.id, couponCode.trim());
-    setCart(updatedCart);
-    setCouponCode('');
-  } catch (err: any) {
-    setCouponError(err.message || 'Invalid coupon code');
-  } finally {
-    setIsApplying(false);
-  }
-}
-
-// Remove handler
-async function handleRemoveCoupon() {
-  if (!('id' in cart)) return;
-  const updatedCart = await client.removeCoupon(cart.id);
-  setCart(updatedCart);
-}
-
-// UI - place in cart order summary
-{('id' in cart) && (
-  <div>
-    {cart.couponCode ? (
-      <div className="flex items-center justify-between bg-green-50 p-2 rounded">
-        <span className="text-green-700 text-sm">🏷️ {cart.couponCode}</span>
-        <button onClick={handleRemoveCoupon} className="text-red-500 text-sm">✕</button>
-      </div>
-    ) : (
-      <div className="flex gap-2">
-        <input value={couponCode} onChange={(e) => setCouponCode(e.target.value)}
-          placeholder="Coupon code" className="flex-1 border rounded px-3 py-2 text-sm" />
-        <button onClick={handleApplyCoupon} disabled={isApplying}
-          className="px-4 py-2 bg-gray-800 text-white rounded text-sm">
-          {isApplying ? '...' : 'Apply'}
-        </button>
-      </div>
-    )}
-    {couponError && <p className="text-red-500 text-xs mt-1">{couponError}</p>}
-  </div>
-)}
-
-// Order summary - show discount line
-{('id' in cart) && parseFloat(cart.discountAmount) > 0 && (
-  <div className="text-green-600">Discount: -{formatPrice(cart.discountAmount)}</div>
-)}
-```
-
-**Checkout order summary - coupon carries over from cart:**
-
-```typescript
-// Checkout already includes coupon from cart
-<div>Subtotal: {formatPrice(checkout.subtotal)}</div>
-{parseFloat(checkout.discountAmount) > 0 && (
-  <div className="text-green-600">
-    Discount ({checkout.couponCode}): -{formatPrice(checkout.discountAmount)}
-  </div>
-)}
-<div>Shipping: {formatPrice(selectedRate?.price || '0')}</div>
-<div className="font-bold">Total: {formatPrice(checkout.total)}</div>
-```
-
----
-
-## 🛒 Partial Checkout (AliExpress Style) - REQUIRED!
-
-Cart page MUST have checkboxes so users can select which items to buy:
-
-```typescript
-// Cart page - track selected items
-const [selectedIndices, setSelectedIndices] = useState<number[]>(
-  cart.items.map((_, i) => i) // All selected by default
-);
-
-const toggleItem = (index: number) => {
-  setSelectedIndices(prev =>
-    prev.includes(index)
-      ? prev.filter(i => i !== index)
-      : [...prev, index]
-  );
-};
-
-const toggleAll = () => {
-  if (selectedIndices.length === cart.items.length) {
-    setSelectedIndices([]); // Deselect all
-  } else {
-    setSelectedIndices(cart.items.map((_, i) => i)); // Select all
-  }
-};
-
-// In your cart UI:
-<div>
-  <label>
-    <input
-      type="checkbox"
-      checked={selectedIndices.length === cart.items.length}
-      onChange={toggleAll}
-    />
-    Select All
-  </label>
-</div>
-
-{cart.items.map((item, index) => (
-  <div key={index}>
-    <input
-      type="checkbox"
-      checked={selectedIndices.includes(index)}
-      onChange={() => toggleItem(index)}
-    />
-    {/* ... item details ... */}
-  </div>
-))}
-
-// On checkout button - pass selected items!
-const handleCheckout = async () => {
-  if (selectedIndices.length === 0) {
-    alert('Please select items to checkout');
-    return;
-  }
-
-  const result = await client.startGuestCheckout({ selectedIndices });
-  // Only selected items go to checkout, others stay in cart!
-};
-```
-
-**Why this matters:**
-
-- Users can buy some items now, leave others for later
-- After payment, `completeGuestCheckout()` sends the order and only removes purchased items
-- Remaining items stay in cart for future purchase
-
-**⚠️ Order Summary on Checkout Page - Use checkout.lineItems!**
-
-```typescript
-// ❌ WRONG - Shows ALL cart items (even unselected ones!)
-<div className="order-summary">
-  {cart.items.map(item => (
-    <div>{item.product.name} - ${item.price}</div>
-  ))}
-</div>
-
-// ✅ CORRECT - Shows only items being purchased in this checkout
-<div className="order-summary">
-  {checkout.lineItems.map(item => (
-    <div>{item.product.name} - ${item.price}</div>
-  ))}
-</div>
-```
-
-The `checkout` object's `lineItems` array contains ONLY the items selected for this checkout!
-
----
-
-## Shipping Destinations (Country/Region Dropdowns)
-
-Before showing a checkout form, fetch where the store ships to and render `<select>` dropdowns instead of free-text inputs:
-
-```typescript
-import type { ShippingDestinations } from 'brainerce';
-
-// Fetch on page load (no checkout needed)
-const destinations: ShippingDestinations = await client.getShippingDestinations();
-// {
-//   worldwide: boolean,         // true if store ships everywhere
-//   countries: [{ code: 'US', name: 'United States' }, ...],
-//   regions: { 'US': [{ code: 'CA', name: 'California' }, ...] }
-// }
-
-// Country <select>
-<select value={country} onChange={(e) => setCountry(e.target.value)}>
-  <option value="">Select country</option>
-  {destinations.countries.map((c) => (
-    <option key={c.code} value={c.code}>{c.name}</option>
-  ))}
-</select>
-
-// Region <select> — only show when regions exist for selected country
-{destinations.regions[country]?.length > 0 ? (
-  <select value={region} onChange={(e) => setRegion(e.target.value)}>
-    <option value="">Select region</option>
-    {destinations.regions[country].map((r) => (
-      <option key={r.code} value={r.code}>{r.name}</option>
-    ))}
-  </select>
-) : (
-  <input type="text" value={region} onChange={(e) => setRegion(e.target.value)} />
-)}
-```
-
-> **Note:** `regions` is an object keyed by country code. If a country has no region restrictions, it won't appear in `regions` — use a free-text input as fallback.
-
----
-
-## Complete Checkout Flow
-
-### Step 1: Start Checkout (Different for Guest vs Logged-in!)
-
-```typescript
-async function startCheckout() {
-  const cart = await client.smartGetCart();
-
-  if (cart.items.length === 0) {
-    alert('Cart is empty');
-    return;
-  }
-
-  let checkoutId: string;
-
-  if (client.isCustomerLoggedIn()) {
-    // Logged-in: create checkout from server cart
-    const checkout = await client.createCheckout({ cartId: cart.id });
-    checkoutId = checkout.id;
-  } else {
-    // Guest: use startGuestCheckout (syncs local cart to server)
-    const result = await client.startGuestCheckout();
-    if (!result.tracked || !result.checkoutId) {
-      throw new Error('Failed to create checkout');
-    }
-    checkoutId = result.checkoutId;
-  }
-
-  // Save for payment page
-  localStorage.setItem('checkoutId', checkoutId);
-
-  // Navigate to checkout
-  window.location.href = '/checkout';
-}
-```
-
-### Step 2: Shipping Address
-
-```typescript
-const checkoutId = localStorage.getItem('checkoutId')!;
-
-// Set shipping address (email is required!)
-const { checkout, rates } = await client.setShippingAddress(checkoutId, {
-  email: 'customer@example.com',
-  firstName: 'John',
-  lastName: 'Doe',
-  line1: '123 Main St',
-  city: 'New York',
-  region: 'NY', // ⚠️ Use 'region', NOT 'state'!
-  postalCode: '10001',
-  country: 'US',
-});
-
-// Show available shipping rates
-rates.forEach((rate) => {
-  console.log(`${rate.name}: $${rate.price}`);
-});
-```
-
-### Step 3: Select Shipping Method
-
-```typescript
-await client.selectShippingMethod(checkoutId, selectedRateId);
-```
-
-### Step 4: Payment (Multi-Provider)
-
-```typescript
-// 1. Check if payment is configured
-const { hasPayments, providers } = await client.getPaymentProviders();
-if (!hasPayments) {
-  return <div>Payment not configured for this store</div>;
-}
-
-// 2. Create payment intent — returns provider type!
-const intent = await client.createPaymentIntent(checkoutId, {
-  successUrl: `${window.location.origin}/checkout/success?checkout_id=${checkoutId}`,
-  cancelUrl: `${window.location.origin}/checkout?error=cancelled`,
-});
-
-// 3. Branch by provider
-if (intent.provider === 'grow') {
-  // Grow: clientSecret is a payment URL — show in iframe
-  // <iframe src={intent.clientSecret} style={{ width: '100%', minHeight: '600px', border: 'none' }} allow="payment" />
-  // Supports credit cards, Bit, Apple Pay, Google Pay, bank transfers
-  // Add fallback: <a href={intent.clientSecret} target="_blank">Open payment in new tab</a>
-  // Order created automatically via webhook!
-} else {
-  // Stripe: install @stripe/stripe-js @stripe/react-stripe-js
-  import { loadStripe } from '@stripe/stripe-js';
-  const stripeProvider = providers.find(p => p.provider === 'stripe');
-  const stripe = await loadStripe(stripeProvider.publicKey, {
-    stripeAccount: stripeProvider.stripeAccountId,
-  });
-
-  // Confirm payment (in your payment form)
-  const { error } = await stripe.confirmPayment({
-    elements,
-    confirmParams: {
-      return_url: `${window.location.origin}/checkout/success?checkout_id=${checkoutId}`,
-    },
-  });
-
-  if (error) {
-    setError(error.message);
-  }
-  // If no error, Stripe redirects to success page
-}
-```
-
-### Step 5: Success Page (Complete Order & Clear Cart!)
-
-```typescript
-// /checkout/success/page.tsx
-'use client';
-import { useEffect, useState } from 'react';
-import { client } from '@/lib/brainerce';
-
-export default function CheckoutSuccessPage() {
-  const [orderNumber, setOrderNumber] = useState<string>();
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    // Break out of iframe if redirected here from Grow payment page
-    if (window.top !== window.self) {
-      window.top!.location.href = window.location.href;
-      return;
-    }
-
-    const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
-
-    if (checkoutId) {
-      // ⚠️ CRITICAL: Complete the order on the server AND clear the cart!
-      // Do NOT use handlePaymentSuccess() - it only clears localStorage!
-      client.completeGuestCheckout(checkoutId).then(result => {
-        setOrderNumber(result.orderNumber);
-        setLoading(false);
-      }).catch(() => {
-        // Order may already be completed (e.g., page refresh) - check status
-        client.getPaymentStatus(checkoutId).then(status => {
-          if (status.orderNumber) {
-            setOrderNumber(status.orderNumber);
-          }
-          setLoading(false);
-        });
-      });
-    }
-  }, []);
-
-  return (
-    <div className="text-center py-12">
-      <h1 className="text-2xl font-bold text-green-600">Thank you for your order!</h1>
-      {loading && <p className="mt-2">Processing your order...</p>}
-      {orderNumber && <p className="mt-2">Order #{orderNumber}</p>}
-      <p className="mt-4">A confirmation email will be sent shortly.</p>
-    </div>
-  );
-}
-```
-
----
-
-## Partial Checkout (AliExpress Style)
-
-Allow customers to buy only some items from their cart:
-
-```typescript
-// Start checkout with only selected items (by index)
-const result = await client.startGuestCheckout({
-  selectedIndices: [0, 2], // Buy items at index 0 and 2 only
-});
-
-// After payment, completeGuestCheckout() sends the order AND removes only those items!
-// Other items stay in cart.
-```
-
----
-
-## Products API
-
-```typescript
-// List products with pagination
-const { data: products, meta } = await client.getProducts({
-  page: 1,
-  limit: 20,
-  search: 'blue shirt', // Searches name, description, SKU, categories, tags
-});
-// meta = { page: 1, limit: 20, total: 150, totalPages: 8 }
-
-// Get single product by slug (for product detail page)
-const product = await client.getProductBySlug('blue-cotton-shirt');
-
-// Search suggestions (for autocomplete)
-const suggestions = await client.getSearchSuggestions('blue', 5);
-// { products: [...], categories: [...] }
-```
-
----
-
-## Product Recommendations (Cross-Sells, Upsells, Related)
-
-Stores can configure product relations. Use these to boost sales with smart product suggestions:
-
-| Type | Where to Show | Purpose |
-|------|--------------|---------|
-| **Cross-sells** | Cart page | Complementary products ("You might also need") |
-| **Upsells** | Product page | Premium alternatives ("Upgrade your choice") |
-| **Related** | Bottom of product page | Similar products |
-
-```typescript
-import type { ProductRecommendationsResponse, CartRecommendationsResponse } from 'brainerce';
-
-// Product page — get upsells + related products
-const recs: ProductRecommendationsResponse = await client.getProductRecommendations(product.id);
-// recs.upsells — premium alternatives (show on product page)
-// recs.related — similar products (show at bottom of product page)
-// recs.crossSells — complementary products (typically used on cart page)
-
-// Each recommendation has: id, name, slug, basePrice, salePrice, images, type, inventory
-
-// Cart page — cross-sell suggestions for cart items
-const cart = await client.smartGetCart();
-const cartRecs: CartRecommendationsResponse = await client.getCartRecommendations(cart.id, 4);
-// cartRecs.recommendations — deduplicated cross-sells (excludes items already in cart)
-
-// Render recommendation cards
-{recs.upsells.length > 0 && (
-  <section>
-    <h2>Upgrade Your Choice</h2>
-    <div className="grid grid-cols-2 sm:grid-cols-4 gap-4">
-      {recs.upsells.map(item => (
-        <a key={item.id} href={`/products/${item.slug}`}>
-          <img src={item.images?.[0]?.url} alt={item.name} />
-          <p>{item.name}</p>
-          <p>{formatPrice(item.salePrice || item.basePrice)}</p>
-        </a>
-      ))}
-    </div>
-  </section>
-)}
-```
-
-> **Note:** These methods return empty arrays when no relations are configured — the UI just renders nothing. Always build the sections.
-
----
-
-## Product Custom Fields (Metafields)
-
-Products may have custom fields defined by the store owner (e.g., "Material", "Care Instructions", "Warranty").
-
-**Important:** Each metafield has a `type` field. When rendering, you **must** check `field.type` and render accordingly:
-
-| Type                               | Rendering                                               |
-| ---------------------------------- | ------------------------------------------------------- |
-| `IMAGE`                            | `<img>` thumbnail (value is URL)                        |
-| `GALLERY`                          | Row of `<img>` thumbnails (value is JSON array of URLs) |
-| `URL`                              | `<a>` clickable link                                    |
-| `COLOR`                            | Color swatch + hex value                                |
-| `BOOLEAN`                          | "Yes" / "No"                                            |
-| `DATE`                             | `new Date(value).toLocaleDateString()`                  |
-| `DATETIME`                         | `new Date(value).toLocaleString()`                      |
-| `TEXT`, `TEXTAREA`, `NUMBER`, etc. | Plain text                                              |
-
-```typescript
-import { getProductMetafield, getProductMetafieldValue } from 'brainerce';
-import type { ProductMetafield } from 'brainerce';
-
-// Access metafields on a product
-const product = await client.getProductBySlug('blue-shirt');
-
-// ⚠️ MUST render based on type! Don't just show field.value as text for all types.
-function MetafieldValue({ field }: { field: ProductMetafield }) {
-  switch (field.type) {
-    case 'IMAGE':
-      return field.value ? <img src={field.value} alt={field.definitionName} className="h-16 w-16 rounded object-cover" /> : <>-</>;
-    case 'GALLERY': {
-      let urls: string[] = [];
-      try { urls = JSON.parse(field.value); } catch { urls = field.value ? [field.value] : []; }
-      return <div className="flex gap-2">{urls.map((url, i) => <img key={i} src={url} className="h-16 w-16 rounded object-cover" />)}</div>;
-    }
-    case 'URL':
-      return field.value ? <a href={field.value} target="_blank" rel="noopener noreferrer">{field.value}</a> : <>-</>;
-    case 'COLOR':
-      return <span><span className="inline-block h-4 w-4 rounded-full border" style={{ backgroundColor: field.value }} /> {field.value}</span>;
-    case 'BOOLEAN':
-      return <>{field.value === 'true' ? 'Yes' : 'No'}</>;
-    case 'DATE':
-      return <>{field.value ? new Date(field.value).toLocaleDateString() : '-'}</>;
-    case 'DATETIME':
-      return <>{field.value ? new Date(field.value).toLocaleString() : '-'}</>;
-    default:
-      return <>{field.value || '-'}</>;
-  }
-}
-
-// Display in spec table
-{product.metafields?.map(mf => (
-  <tr key={mf.id}>
-    <td>{mf.definitionName}</td>
-    <td><MetafieldValue field={mf} /></td>
-  </tr>
-))}
-
-// Get specific field by key
-const material = getProductMetafieldValue(product, 'material');
-const careInstructions = getProductMetafield(product, 'care_instructions');
-
-// Get available metafield definitions (schema)
-const { definitions } = await client.getPublicMetafieldDefinitions();
-// Use definitions to build dynamic UI (filters, forms, etc.)
-```
-
-> **Tip:** `metafields` may be empty if the store hasn't defined custom fields. Always use optional chaining.
-
----
-
-## Customer Authentication
-
-```typescript
-// Register
-const auth = await client.registerCustomer({
-  email: 'john@example.com',
-  password: 'securepass123',
-  firstName: 'John',
-  lastName: 'Doe',
-});
-
-if (auth.requiresVerification) {
-  // Store token for verification step
-  localStorage.setItem('verificationToken', auth.token);
-  localStorage.setItem('verificationEmail', 'john@example.com');
-  window.location.href = '/verify-email';
-} else {
-  client.setCustomerToken(auth.token);
-  localStorage.setItem('customerToken', auth.token);
-}
-
-// Login
-const auth = await client.loginCustomer('john@example.com', 'password');
-
-if (auth.requiresVerification) {
-  localStorage.setItem('verificationToken', auth.token);
-  localStorage.setItem('verificationEmail', 'john@example.com');
-  window.location.href = '/verify-email';
-} else {
-  client.setCustomerToken(auth.token);
-  localStorage.setItem('customerToken', auth.token);
-}
-
-// Verify email (on /verify-email page)
-const result = await client.verifyEmail(code, token);
-if (result.verified) {
-  client.setCustomerToken(token);
-  localStorage.setItem('customerToken', token);
-  localStorage.removeItem('verificationToken');
-  localStorage.removeItem('verificationEmail');
-  window.location.href = '/account';
-}
-
-// Resend verification code
-await client.resendVerificationEmail(token);
-
-// Forgot password (on /forgot-password page)
-await client.forgotPassword(email);
-// Always succeeds (prevents email enumeration)
-
-// Reset password (on /reset-password page — user arrives via email link)
-const token = new URLSearchParams(window.location.search).get('token');
-await client.resetPassword(token!, newPassword);
-// On success: redirect to /login
-
-// Logout
-client.setCustomerToken(null);
-localStorage.removeItem('customerToken');
-
-// Get profile (requires token)
-const profile = await client.getMyProfile();
-
-// Get order history
-const { data: orders, meta } = await client.getMyOrders({ page: 1, limit: 10 });
-```
-
----
-
-## OAuth / Social Login
-
-```typescript
-// Get available providers for this store
-const { providers } = await client.getAvailableOAuthProviders();
-// providers = ['GOOGLE', 'FACEBOOK', 'GITHUB']
-
-// Redirect to OAuth provider
-const { authorizationUrl } = await client.getOAuthAuthorizeUrl('GOOGLE', {
-  redirectUrl: `${window.location.origin}/auth/callback`,
-});
-window.location.href = authorizationUrl;
-
-// Handle callback (on /auth/callback page — backend redirects here with params)
-const params = new URLSearchParams(window.location.search);
-if (params.get('oauth_success') === 'true') {
-  const token = params.get('token');
-  client.setCustomerToken(token!);
-  // Also available: customer_id, customer_email, is_new
-} else if (params.get('oauth_error')) {
-  // Show error to user
-}
-```
-
----
-
-## Required Pages Checklist
-
-- [ ] **Home** (`/`) - Featured products grid
-- [ ] **Products** (`/products`) - Product list with infinite scroll
-- [ ] **Product Detail** (`/products/[slug]`) - Use `getProductBySlug(slug)`. Show **upsells** + **related products** via `getProductRecommendations()`
-- [ ] **Cart** (`/cart`) - Show items, quantities, totals, **coupon code input**, discount display, **cross-sell recommendations** via `getCartRecommendations()`
-- [ ] **Checkout** (`/checkout`) - Address → Shipping → Payment. **Show discount in order summary!**
-- [ ] **Success** (`/checkout/success`) - **Must call `completeGuestCheckout()`!**
-- [ ] **Login** (`/login`) - Email/password + social buttons, handle `requiresVerification`
-- [ ] **Register** (`/register`) - Registration form, handle `requiresVerification`
-- [ ] **Verify Email** (`/verify-email`) - 6-digit code input + resend button. **ALWAYS create this page** even if verification is currently disabled — the store owner can enable it at any time
-- [ ] **Forgot Password** (`/forgot-password`) - Email input, shows success message
-- [ ] **Reset Password** (`/reset-password`) - Token from URL + new password form
-- [ ] **OAuth Callback** (`/auth/callback`) - Handle OAuth redirect with token from URL params
-- [ ] **Account** (`/account`) - Profile + order history
-- [ ] **Header** - Logo, nav, cart icon with count, search
-
-### ALWAYS Build These (Even If Currently Disabled)
-
-Some features may not be configured yet, but the store owner can enable them at any time. **Always create the UI** — SDK methods return empty/null when not configured:
-
-- **Email Verification** → `/verify-email` page. `requiresVerification` is checked in login/register flows.
-- **OAuth Buttons** → Social login buttons on Login & Register + `/auth/callback` page. `getAvailableOAuthProviders()` returns `[]` when none configured — buttons just don't render.
-- **Password Reset** → `/forgot-password` + `/reset-password` pages. `forgotPassword()` silently succeeds when no account exists.
-- **Discount Banners** → `getDiscountBanners()` returns `[]` when no rules — component renders nothing.
-- **Product Discount Badges** → `getProductDiscountBadge(id)` returns `null` — renders nothing.
-- **Cart Nudges** → `cart.nudges` is `[]` — renders nothing.
-- **Coupon Input** → Always show in cart. Works even with no coupons configured.
-- **Product Recommendations** → Upsells + related on product page, cross-sells on cart page. `getProductRecommendations()` / `getCartRecommendations()` return empty arrays when none configured.
-
----
-
-## Common Type Gotchas
-
-```typescript
-// ❌ WRONG                          // ✅ CORRECT
-address.state                        address.region
-cart.total                           getCartTotals(cart).total
-cart.discount                        cart.discountAmount
-item.name (in cart)                  item.product.name
-response.url (OAuth)                 response.authorizationUrl
-providers.forEach (OAuth)            response.providers.forEach
-status === 'completed'               status === 'succeeded'
-product.metafields.name              product.metafields[0].definitionName
-product.metafields.key               product.metafields[0].definitionKey
-orderItem.unitPrice                  orderItem.price (OrderItem is FLAT, not nested!)
-cartItem.price                       cartItem.unitPrice (Cart/Checkout items use unitPrice)
-waitResult.orderNumber               waitResult.status.orderNumber (nested in PaymentStatus)
-variant.attributes.map(...)          Object.entries(variant.attributes || {}) (it's an object!)
-categorySuggestion.slug              // ❌ doesn't exist! Only: id, name, productCount
-order.status === 'COMPLETED'         order.status === 'delivered' (OrderStatus is lowercase!)
-getCartTotals(cart)                  // ✅ Works — all carts are server carts now
-result.checkoutId (guest checkout)   // ⚠️ Check result.tracked first! It's a union type
-```
-
-**Key distinctions:**
-
-- **OrderItem** (from orders): Flat structure — `item.price`, `item.name`, `item.image`
-- **CartItem / CheckoutLineItem**: Nested structure — `item.unitPrice`, `item.product.name`, `item.product.images`
-- **`getCartTotals()`** works on all carts — guests now use server-side session carts with full `subtotal`/`discountAmount` fields.
-- **`GuestCheckoutStartResponse`** is a union type — always check `result.tracked` before accessing `result.checkoutId`
-- **`WaitForOrderResult`** has `result.status.orderNumber`, NOT `result.orderNumber`. But `completeGuestCheckout()` returns `GuestOrderResponse` which DOES have `result.orderNumber` directly.
-- **Cart state**: Use `useState<Cart | null>(null)` and load with `smartGetCart()` in `useEffect` — all carts are server-side now, no hydration mismatch issues.
-
----
-
-## Full SDK Documentation
-
-For complete API reference and working code examples:
-**https://brainerce.com/docs/sdk**
+# Brainerce Store Builder
+
+Build a **{store_type}** store called "{store_name}" | Style: **{style}** | Currency: **{currency}**
+
+---
+
+## ⛔ STOP! Read These 3 Rules First (Breaking = Store Won't Work)
+
+### Rule 1: Guest vs Logged-In = Different Checkout Methods!
+
+```typescript
+// ❌ THIS WILL FAIL - "Cart not found" error!
+const cart = await client.smartGetCart(); // Guest cart has id: "__local__"
+await client.createCheckout({ cartId: cart.id }); // 💥 "__local__" doesn't exist on server!
+
+// ✅ CORRECT - Check user type first!
+if (client.isCustomerLoggedIn()) {
+  // Logged-in user → server cart exists
+  const checkout = await client.createCheckout({ cartId: cart.id });
+  const checkoutId = checkout.id;
+} else {
+  // Guest user → use startGuestCheckout()
+  const result = await client.startGuestCheckout();
+  const checkoutId = result.checkoutId;
+}
+```
+
+| User Type     | Cart Location | Checkout Method              | Get Checkout ID     |
+| ------------- | ------------- | ---------------------------- | ------------------- |
+| **Guest**     | localStorage  | `startGuestCheckout()`       | `result.checkoutId` |
+| **Logged-in** | Server        | `createCheckout({ cartId })` | `checkout.id`       |
+
+### Rule 2: Complete Checkout & Clear Cart After Payment!
+
+```typescript
+// On /checkout/success page - MUST DO THIS!
+export default function CheckoutSuccessPage() {
+  const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
+
+  useEffect(() => {
+    if (checkoutId) {
+      // ⚠️ CRITICAL: This sends the order to the server AND clears the cart!
+      // handlePaymentSuccess() only clears the local cart - it does NOT create the order!
+      client.completeGuestCheckout(checkoutId);
+    }
+  }, []);
+
+  return <div>Thank you for your order!</div>;
+}
+```
+
+> **WARNING:** Do NOT use `handlePaymentSuccess()` to complete an order. It only clears
+> the local cart (localStorage) and does NOT communicate with the server.
+> Always use `completeGuestCheckout()` after payment succeeds.
+
+### Rule 3: Never Hardcode Products!
+
+```typescript
+// ❌ FORBIDDEN - Store will show fake data!
+const products = [{ id: '1', name: 'T-Shirt', price: 29.99 }];
+
+// ✅ CORRECT - Fetch from API
+const { data: products } = await client.getProducts();
+```
+
+---
+
+## Quick Setup
+
+```bash
+npm install brainerce
+```
+
+```typescript
+// lib/brainerce.ts
+import { BrainerceClient } from 'brainerce';
+
+export const client = new BrainerceClient({
+  connectionId: '{connection_id}',
+  baseUrl: '{api_url}',
+});
+
+// Restore customer session on page load
+export function initBrainerce() {
+  if (typeof window === 'undefined') return;
+  const token = localStorage.getItem('customerToken');
+  if (token) client.setCustomerToken(token);
+}
+
+// Save/clear customer token
+export function setCustomerToken(token: string | null) {
+  if (token) {
+    localStorage.setItem('customerToken', token);
+    client.setCustomerToken(token);
+  } else {
+    localStorage.removeItem('customerToken');
+    client.clearCustomerToken();
+  }
+}
+```
+
+---
+
+## Cart (Works for Both Guest & Logged-in)
+
+```typescript
+// Get or create cart - handles both guest (localStorage) and logged-in (server) automatically
+const cart = await client.smartGetCart();
+
+// Add to cart - ALWAYS pass name, price, image for guest cart display!
+await client.smartAddToCart({
+  productId: product.id,
+  variantId: selectedVariant?.id,
+  quantity: 1,
+  // IMPORTANT: Pass product info for guest cart display
+  name: selectedVariant?.name ? `${product.name} - ${selectedVariant.name}` : product.name,
+  price: getVariantPrice(selectedVariant, product.basePrice),
+  image: selectedVariant?.image
+    ? typeof selectedVariant.image === 'string'
+      ? selectedVariant.image
+      : selectedVariant.image.url
+    : product.images?.[0]?.url,
+});
+
+// Update quantity (by productId, not itemId!)
+await client.smartUpdateCartItem('prod_xxx', 2); // productId, quantity
+await client.smartUpdateCartItem('prod_xxx', 3, 'var_xxx'); // with variant
+
+// Remove item (by productId, not itemId!)
+await client.smartRemoveFromCart('prod_xxx');
+await client.smartRemoveFromCart('prod_xxx', 'var_xxx'); // with variant
+
+// Get cart totals (cart doesn't have .total field!)
+import { getCartTotals } from 'brainerce';
+const totals = getCartTotals(cart);
+// { subtotal: 59.98, discount: 10, shipping: 0, total: 49.98 }
+
+// All smart* methods return a server Cart (even for guests via session carts)
+// Cart has: id, itemCount, subtotal, discountAmount, items, couponCode
+```
+
+### 🏷️ Coupon Code (Add to Cart Page!)
+
+```typescript
+// Apply coupon to cart
+const cart = await client.smartGetCart();
+const updatedCart = await client.applyCoupon(cart.id, 'SAVE20');
+console.log(updatedCart.discountAmount); // "10.00" (string)
+console.log(updatedCart.couponCode); // "SAVE20"
+
+// Remove coupon
+const updatedCart = await client.removeCoupon(cartId);
+
+// Calculate totals including discount
+import { getCartTotals } from 'brainerce';
+const totals = getCartTotals(cart); // { subtotal, discount, shipping, total }
+```
+
+**Cart page coupon UI:**
+
+```typescript
+// State
+const [couponCode, setCouponCode] = useState('');
+const [couponError, setCouponError] = useState('');
+const [isApplying, setIsApplying] = useState(false);
+
+// Apply handler
+async function handleApplyCoupon() {
+  if (!couponCode.trim() || !('id' in cart)) return;
+  setIsApplying(true);
+  setCouponError('');
+  try {
+    const updatedCart = await client.applyCoupon(cart.id, couponCode.trim());
+    setCart(updatedCart);
+    setCouponCode('');
+  } catch (err: any) {
+    setCouponError(err.message || 'Invalid coupon code');
+  } finally {
+    setIsApplying(false);
+  }
+}
+
+// Remove handler
+async function handleRemoveCoupon() {
+  if (!('id' in cart)) return;
+  const updatedCart = await client.removeCoupon(cart.id);
+  setCart(updatedCart);
+}
+
+// UI - place in cart order summary
+{('id' in cart) && (
+  <div>
+    {cart.couponCode ? (
+      <div className="flex items-center justify-between bg-green-50 p-2 rounded">
+        <span className="text-green-700 text-sm">🏷️ {cart.couponCode}</span>
+        <button onClick={handleRemoveCoupon} className="text-red-500 text-sm">✕</button>
+      </div>
+    ) : (
+      <div className="flex gap-2">
+        <input value={couponCode} onChange={(e) => setCouponCode(e.target.value)}
+          placeholder="Coupon code" className="flex-1 border rounded px-3 py-2 text-sm" />
+        <button onClick={handleApplyCoupon} disabled={isApplying}
+          className="px-4 py-2 bg-gray-800 text-white rounded text-sm">
+          {isApplying ? '...' : 'Apply'}
+        </button>
+      </div>
+    )}
+    {couponError && <p className="text-red-500 text-xs mt-1">{couponError}</p>}
+  </div>
+)}
+
+// Order summary - show discount line
+{('id' in cart) && parseFloat(cart.discountAmount) > 0 && (
+  <div className="text-green-600">Discount: -{formatPrice(cart.discountAmount)}</div>
+)}
+```
+
+**Checkout order summary - coupon carries over from cart:**
+
+```typescript
+// Checkout already includes coupon from cart
+<div>Subtotal: {formatPrice(checkout.subtotal)}</div>
+{parseFloat(checkout.discountAmount) > 0 && (
+  <div className="text-green-600">
+    Discount ({checkout.couponCode}): -{formatPrice(checkout.discountAmount)}
+  </div>
+)}
+<div>Shipping: {formatPrice(selectedRate?.price || '0')}</div>
+<div className="font-bold">Total: {formatPrice(checkout.total)}</div>
+```
+
+---
+
+## 🛒 Partial Checkout (AliExpress Style) - REQUIRED!
+
+Cart page MUST have checkboxes so users can select which items to buy:
+
+```typescript
+// Cart page - track selected items
+const [selectedIndices, setSelectedIndices] = useState<number[]>(
+  cart.items.map((_, i) => i) // All selected by default
+);
+
+const toggleItem = (index: number) => {
+  setSelectedIndices(prev =>
+    prev.includes(index)
+      ? prev.filter(i => i !== index)
+      : [...prev, index]
+  );
+};
+
+const toggleAll = () => {
+  if (selectedIndices.length === cart.items.length) {
+    setSelectedIndices([]); // Deselect all
+  } else {
+    setSelectedIndices(cart.items.map((_, i) => i)); // Select all
+  }
+};
+
+// In your cart UI:
+<div>
+  <label>
+    <input
+      type="checkbox"
+      checked={selectedIndices.length === cart.items.length}
+      onChange={toggleAll}
+    />
+    Select All
+  </label>
+</div>
+
+{cart.items.map((item, index) => (
+  <div key={index}>
+    <input
+      type="checkbox"
+      checked={selectedIndices.includes(index)}
+      onChange={() => toggleItem(index)}
+    />
+    {/* ... item details ... */}
+  </div>
+))}
+
+// On checkout button - pass selected items!
+const handleCheckout = async () => {
+  if (selectedIndices.length === 0) {
+    alert('Please select items to checkout');
+    return;
+  }
+
+  const result = await client.startGuestCheckout({ selectedIndices });
+  // Only selected items go to checkout, others stay in cart!
+};
+```
+
+**Why this matters:**
+
+- Users can buy some items now, leave others for later
+- After payment, `completeGuestCheckout()` sends the order and only removes purchased items
+- Remaining items stay in cart for future purchase
+
+**⚠️ Order Summary on Checkout Page - Use checkout.lineItems!**
+
+```typescript
+// ❌ WRONG - Shows ALL cart items (even unselected ones!)
+<div className="order-summary">
+  {cart.items.map(item => (
+    <div>{item.product.name} - ${item.price}</div>
+  ))}
+</div>
+
+// ✅ CORRECT - Shows only items being purchased in this checkout
+<div className="order-summary">
+  {checkout.lineItems.map(item => (
+    <div>{item.product.name} - ${item.price}</div>
+  ))}
+</div>
+```
+
+The `checkout` object's `lineItems` array contains ONLY the items selected for this checkout!
+
+---
+
+## Shipping Destinations (Country/Region Dropdowns)
+
+Before showing a checkout form, fetch where the store ships to and render `<select>` dropdowns instead of free-text inputs:
+
+```typescript
+import type { ShippingDestinations } from 'brainerce';
+
+// Fetch on page load (no checkout needed)
+const destinations: ShippingDestinations = await client.getShippingDestinations();
+// {
+//   worldwide: boolean,         // true if store ships everywhere
+//   countries: [{ code: 'US', name: 'United States' }, ...],
+//   regions: { 'US': [{ code: 'CA', name: 'California' }, ...] }
+// }
+
+// Country <select>
+<select value={country} onChange={(e) => setCountry(e.target.value)}>
+  <option value="">Select country</option>
+  {destinations.countries.map((c) => (
+    <option key={c.code} value={c.code}>{c.name}</option>
+  ))}
+</select>
+
+// Region <select> — only show when regions exist for selected country
+{destinations.regions[country]?.length > 0 ? (
+  <select value={region} onChange={(e) => setRegion(e.target.value)}>
+    <option value="">Select region</option>
+    {destinations.regions[country].map((r) => (
+      <option key={r.code} value={r.code}>{r.name}</option>
+    ))}
+  </select>
+) : (
+  <input type="text" value={region} onChange={(e) => setRegion(e.target.value)} />
+)}
+```
+
+> **Note:** `regions` is an object keyed by country code. If a country has no region restrictions, it won't appear in `regions` — use a free-text input as fallback.
+
+---
+
+## Complete Checkout Flow
+
+### Step 1: Start Checkout (Different for Guest vs Logged-in!)
+
+```typescript
+async function startCheckout() {
+  const cart = await client.smartGetCart();
+
+  if (cart.items.length === 0) {
+    alert('Cart is empty');
+    return;
+  }
+
+  let checkoutId: string;
+
+  if (client.isCustomerLoggedIn()) {
+    // Logged-in: create checkout from server cart
+    const checkout = await client.createCheckout({ cartId: cart.id });
+    checkoutId = checkout.id;
+  } else {
+    // Guest: use startGuestCheckout (syncs local cart to server)
+    const result = await client.startGuestCheckout();
+    if (!result.tracked || !result.checkoutId) {
+      throw new Error('Failed to create checkout');
+    }
+    checkoutId = result.checkoutId;
+  }
+
+  // Save for payment page
+  localStorage.setItem('checkoutId', checkoutId);
+
+  // Navigate to checkout
+  window.location.href = '/checkout';
+}
+```
+
+### Step 2: Shipping Address
+
+```typescript
+const checkoutId = localStorage.getItem('checkoutId')!;
+
+// Set shipping address (email is required!)
+const { checkout, rates } = await client.setShippingAddress(checkoutId, {
+  email: 'customer@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  city: 'New York',
+  region: 'NY', // ⚠️ Use 'region', NOT 'state'!
+  postalCode: '10001',
+  country: 'US',
+});
+
+// Show available shipping rates
+rates.forEach((rate) => {
+  console.log(`${rate.name}: $${rate.price}`);
+});
+```
+
+### Step 3: Select Shipping Method
+
+```typescript
+await client.selectShippingMethod(checkoutId, selectedRateId);
+```
+
+### Step 4: Payment (Multi-Provider)
+
+```typescript
+// 1. Check if payment is configured
+const { hasPayments, providers } = await client.getPaymentProviders();
+if (!hasPayments) {
+  return <div>Payment not configured for this store</div>;
+}
+
+// 2. Create payment intent — returns provider type!
+const intent = await client.createPaymentIntent(checkoutId, {
+  successUrl: `${window.location.origin}/checkout/success?checkout_id=${checkoutId}`,
+  cancelUrl: `${window.location.origin}/checkout?error=cancelled`,
+});
+
+// 3. Branch by provider
+if (intent.provider === 'grow') {
+  // Grow: clientSecret is a payment URL — show in iframe
+  // <iframe src={intent.clientSecret} style={{ width: '100%', minHeight: '600px', border: 'none' }} allow="payment" />
+  // Supports credit cards, Bit, Apple Pay, Google Pay, bank transfers
+  // Add fallback: <a href={intent.clientSecret} target="_blank">Open payment in new tab</a>
+  // Order created automatically via webhook!
+} else {
+  // Stripe: install @stripe/stripe-js @stripe/react-stripe-js
+  import { loadStripe } from '@stripe/stripe-js';
+  const stripeProvider = providers.find(p => p.provider === 'stripe');
+  const stripe = await loadStripe(stripeProvider.publicKey, {
+    stripeAccount: stripeProvider.stripeAccountId,
+  });
+
+  // Confirm payment (in your payment form)
+  const { error } = await stripe.confirmPayment({
+    elements,
+    confirmParams: {
+      return_url: `${window.location.origin}/checkout/success?checkout_id=${checkoutId}`,
+    },
+  });
+
+  if (error) {
+    setError(error.message);
+  }
+  // If no error, Stripe redirects to success page
+}
+```
+
+### Step 5: Success Page (Complete Order & Clear Cart!)
+
+```typescript
+// /checkout/success/page.tsx
+'use client';
+import { useEffect, useState } from 'react';
+import { client } from '@/lib/brainerce';
+
+export default function CheckoutSuccessPage() {
+  const [orderNumber, setOrderNumber] = useState<string>();
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    // Break out of iframe if redirected here from Grow payment page
+    if (window.top !== window.self) {
+      window.top!.location.href = window.location.href;
+      return;
+    }
+
+    const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
+
+    if (checkoutId) {
+      // ⚠️ CRITICAL: Complete the order on the server AND clear the cart!
+      // Do NOT use handlePaymentSuccess() - it only clears localStorage!
+      client.completeGuestCheckout(checkoutId).then(result => {
+        setOrderNumber(result.orderNumber);
+        setLoading(false);
+      }).catch(() => {
+        // Order may already be completed (e.g., page refresh) - check status
+        client.getPaymentStatus(checkoutId).then(status => {
+          if (status.orderNumber) {
+            setOrderNumber(status.orderNumber);
+          }
+          setLoading(false);
+        });
+      });
+    }
+  }, []);
+
+  return (
+    <div className="text-center py-12">
+      <h1 className="text-2xl font-bold text-green-600">Thank you for your order!</h1>
+      {loading && <p className="mt-2">Processing your order...</p>}
+      {orderNumber && <p className="mt-2">Order #{orderNumber}</p>}
+      <p className="mt-4">A confirmation email will be sent shortly.</p>
+    </div>
+  );
+}
+```
+
+---
+
+## Partial Checkout (AliExpress Style)
+
+Allow customers to buy only some items from their cart:
+
+```typescript
+// Start checkout with only selected items (by index)
+const result = await client.startGuestCheckout({
+  selectedIndices: [0, 2], // Buy items at index 0 and 2 only
+});
+
+// After payment, completeGuestCheckout() sends the order AND removes only those items!
+// Other items stay in cart.
+```
+
+---
+
+## Products API
+
+```typescript
+// List products with pagination
+const { data: products, meta } = await client.getProducts({
+  page: 1,
+  limit: 20,
+  search: 'blue shirt', // Searches name, description, SKU, categories, tags
+});
+// meta = { page: 1, limit: 20, total: 150, totalPages: 8 }
+
+// Get single product by slug (for product detail page)
+const product = await client.getProductBySlug('blue-cotton-shirt');
+
+// Search suggestions (for autocomplete)
+const suggestions = await client.getSearchSuggestions('blue', 5);
+// { products: [...], categories: [...] }
+```
+
+---
+
+## Product Recommendations (Cross-Sells, Upsells, Related)
+
+Stores can configure product relations. Use these to boost sales with smart product suggestions:
+
+| Type            | Where to Show          | Purpose                                        |
+| --------------- | ---------------------- | ---------------------------------------------- |
+| **Cross-sells** | Cart page              | Complementary products ("You might also need") |
+| **Upsells**     | Product page           | Premium alternatives ("Upgrade your choice")   |
+| **Related**     | Bottom of product page | Similar products                               |
+
+```typescript
+import type { ProductRecommendationsResponse, CartRecommendationsResponse } from 'brainerce';
+
+// Product page — recommendations come EMBEDDED in the product response (no extra API call needed)
+const product = await client.getProductBySlug('some-slug');
+const recs = (product as any).recommendations as ProductRecommendationsResponse | undefined;
+// recs?.upsells — premium alternatives (show on product page)
+// recs?.related — similar products (show at bottom of product page)
+// recs?.crossSells — complementary products (typically used on cart page)
+
+// Each recommendation has: id, name, slug, basePrice, salePrice, images[], type, inventory
+
+// Cart page — cross-sell suggestions for cart items (separate call, since cart has no embedded recs)
+const cart = await client.smartGetCart();
+const cartRecs: CartRecommendationsResponse = await client.getCartRecommendations(cart.id, 4);
+// cartRecs.recommendations — deduplicated cross-sells (excludes items already in cart)
+
+// Render recommendation cards on product page
+{recs?.upsells && recs.upsells.length > 0 && (
+  <section>
+    <h2>Upgrade Your Choice</h2>
+    <div className="grid grid-cols-2 sm:grid-cols-4 gap-4">
+      {recs.upsells.map(item => (
+        <a key={item.id} href={`/products/${item.slug}`}>
+          <img src={item.images?.[0]?.url} alt={item.name} />
+          <p>{item.name}</p>
+          <p>{formatPrice(item.salePrice || item.basePrice)}</p>
+        </a>
+      ))}
+    </div>
+  </section>
+)}
+```
+
+> **Note:** Recommendations return empty arrays when no relations are configured — the UI just renders nothing. Always build the sections. The `getProductRecommendations()` SDK method still works as a fallback for older storefronts.
+
+---
+
+## Product Custom Fields (Metafields)
+
+Products may have custom fields defined by the store owner (e.g., "Material", "Care Instructions", "Warranty").
+
+**Important:** Each metafield has a `type` field. When rendering, you **must** check `field.type` and render accordingly:
+
+| Type                               | Rendering                                               |
+| ---------------------------------- | ------------------------------------------------------- |
+| `IMAGE`                            | `<img>` thumbnail (value is URL)                        |
+| `GALLERY`                          | Row of `<img>` thumbnails (value is JSON array of URLs) |
+| `URL`                              | `<a>` clickable link                                    |
+| `COLOR`                            | Color swatch + hex value                                |
+| `BOOLEAN`                          | "Yes" / "No"                                            |
+| `DATE`                             | `new Date(value).toLocaleDateString()`                  |
+| `DATETIME`                         | `new Date(value).toLocaleString()`                      |
+| `TEXT`, `TEXTAREA`, `NUMBER`, etc. | Plain text                                              |
+
+```typescript
+import { getProductMetafield, getProductMetafieldValue } from 'brainerce';
+import type { ProductMetafield } from 'brainerce';
+
+// Access metafields on a product
+const product = await client.getProductBySlug('blue-shirt');
+
+// ⚠️ MUST render based on type! Don't just show field.value as text for all types.
+function MetafieldValue({ field }: { field: ProductMetafield }) {
+  switch (field.type) {
+    case 'IMAGE':
+      return field.value ? <img src={field.value} alt={field.definitionName} className="h-16 w-16 rounded object-cover" /> : <>-</>;
+    case 'GALLERY': {
+      let urls: string[] = [];
+      try { urls = JSON.parse(field.value); } catch { urls = field.value ? [field.value] : []; }
+      return <div className="flex gap-2">{urls.map((url, i) => <img key={i} src={url} className="h-16 w-16 rounded object-cover" />)}</div>;
+    }
+    case 'URL':
+      return field.value ? <a href={field.value} target="_blank" rel="noopener noreferrer">{field.value}</a> : <>-</>;
+    case 'COLOR':
+      return <span><span className="inline-block h-4 w-4 rounded-full border" style={{ backgroundColor: field.value }} /> {field.value}</span>;
+    case 'BOOLEAN':
+      return <>{field.value === 'true' ? 'Yes' : 'No'}</>;
+    case 'DATE':
+      return <>{field.value ? new Date(field.value).toLocaleDateString() : '-'}</>;
+    case 'DATETIME':
+      return <>{field.value ? new Date(field.value).toLocaleString() : '-'}</>;
+    default:
+      return <>{field.value || '-'}</>;
+  }
+}
+
+// Display in spec table
+{product.metafields?.map(mf => (
+  <tr key={mf.id}>
+    <td>{mf.definitionName}</td>
+    <td><MetafieldValue field={mf} /></td>
+  </tr>
+))}
+
+// Get specific field by key
+const material = getProductMetafieldValue(product, 'material');
+const careInstructions = getProductMetafield(product, 'care_instructions');
+
+// Get available metafield definitions (schema)
+const { definitions } = await client.getPublicMetafieldDefinitions();
+// Use definitions to build dynamic UI (filters, forms, etc.)
+```
+
+> **Tip:** `metafields` may be empty if the store hasn't defined custom fields. Always use optional chaining.
+
+---
+
+## Customer Authentication
+
+```typescript
+// Register
+const auth = await client.registerCustomer({
+  email: 'john@example.com',
+  password: 'securepass123',
+  firstName: 'John',
+  lastName: 'Doe',
+});
+
+if (auth.requiresVerification) {
+  // Store token for verification step
+  localStorage.setItem('verificationToken', auth.token);
+  localStorage.setItem('verificationEmail', 'john@example.com');
+  window.location.href = '/verify-email';
+} else {
+  client.setCustomerToken(auth.token);
+  localStorage.setItem('customerToken', auth.token);
+}
+
+// Login
+const auth = await client.loginCustomer('john@example.com', 'password');
+
+if (auth.requiresVerification) {
+  localStorage.setItem('verificationToken', auth.token);
+  localStorage.setItem('verificationEmail', 'john@example.com');
+  window.location.href = '/verify-email';
+} else {
+  client.setCustomerToken(auth.token);
+  localStorage.setItem('customerToken', auth.token);
+}
+
+// Verify email (on /verify-email page)
+const result = await client.verifyEmail(code, token);
+if (result.verified) {
+  client.setCustomerToken(token);
+  localStorage.setItem('customerToken', token);
+  localStorage.removeItem('verificationToken');
+  localStorage.removeItem('verificationEmail');
+  window.location.href = '/account';
+}
+
+// Resend verification code
+await client.resendVerificationEmail(token);
+
+// Forgot password (on /forgot-password page)
+await client.forgotPassword(email);
+// Always succeeds (prevents email enumeration)
+
+// Reset password (on /reset-password page — user arrives via email link)
+const token = new URLSearchParams(window.location.search).get('token');
+await client.resetPassword(token!, newPassword);
+// On success: redirect to /login
+
+// Logout
+client.setCustomerToken(null);
+localStorage.removeItem('customerToken');
+
+// Get profile (requires token)
+const profile = await client.getMyProfile();
+
+// Get order history
+const { data: orders, meta } = await client.getMyOrders({ page: 1, limit: 10 });
+```
+
+---
+
+## OAuth / Social Login
+
+```typescript
+// Get available providers for this store
+const { providers } = await client.getAvailableOAuthProviders();
+// providers = ['GOOGLE', 'FACEBOOK', 'GITHUB']
+
+// Redirect to OAuth provider
+const { authorizationUrl } = await client.getOAuthAuthorizeUrl('GOOGLE', {
+  redirectUrl: `${window.location.origin}/auth/callback`,
+});
+window.location.href = authorizationUrl;
+
+// Handle callback (on /auth/callback page — backend redirects here with params)
+const params = new URLSearchParams(window.location.search);
+if (params.get('oauth_success') === 'true') {
+  const token = params.get('token');
+  client.setCustomerToken(token!);
+  // Also available: customer_id, customer_email, is_new
+} else if (params.get('oauth_error')) {
+  // Show error to user
+}
+```
+
+---
+
+## Required Pages Checklist
+
+- [ ] **Home** (`/`) - Featured products grid
+- [ ] **Products** (`/products`) - Product list with infinite scroll
+- [ ] **Product Detail** (`/products/[slug]`) - Use `getProductBySlug(slug)`. Show **upsells** + **related products** from `product.recommendations` (embedded in response)
+- [ ] **Cart** (`/cart`) - Show items, quantities, totals, **coupon code input**, discount display, **cross-sell recommendations** via `getCartRecommendations()`
+- [ ] **Checkout** (`/checkout`) - Address → Shipping → Payment. **Show discount in order summary!**
+- [ ] **Success** (`/checkout/success`) - **Must call `completeGuestCheckout()`!**
+- [ ] **Login** (`/login`) - Email/password + social buttons, handle `requiresVerification`
+- [ ] **Register** (`/register`) - Registration form, handle `requiresVerification`
+- [ ] **Verify Email** (`/verify-email`) - 6-digit code input + resend button. **ALWAYS create this page** even if verification is currently disabled — the store owner can enable it at any time
+- [ ] **Forgot Password** (`/forgot-password`) - Email input, shows success message
+- [ ] **Reset Password** (`/reset-password`) - Token from URL + new password form
+- [ ] **OAuth Callback** (`/auth/callback`) - Handle OAuth redirect with token from URL params
+- [ ] **Account** (`/account`) - Profile + order history
+- [ ] **Header** - Logo, nav, cart icon with count, search
+
+### ALWAYS Build These (Even If Currently Disabled)
+
+Some features may not be configured yet, but the store owner can enable them at any time. **Always create the UI** — SDK methods return empty/null when not configured:
+
+- **Email Verification** → `/verify-email` page. `requiresVerification` is checked in login/register flows.
+- **OAuth Buttons** → Social login buttons on Login & Register + `/auth/callback` page. `getAvailableOAuthProviders()` returns `[]` when none configured — buttons just don't render.
+- **Password Reset** → `/forgot-password` + `/reset-password` pages. `forgotPassword()` silently succeeds when no account exists.
+- **Discount Banners** → `getDiscountBanners()` returns `[]` when no rules — component renders nothing.
+- **Product Discount Badges** → `getProductDiscountBadge(id)` returns `null` — renders nothing.
+- **Cart Nudges** → `cart.nudges` is `[]` — renders nothing.
+- **Coupon Input** → Always show in cart. Works even with no coupons configured.
+- **Product Recommendations** → Upsells + related on product page (from `product.recommendations`), cross-sells on cart page (`getCartRecommendations()`). Returns empty arrays when none configured.
+
+---
+
+## Common Type Gotchas
+
+```typescript
+// ❌ WRONG                          // ✅ CORRECT
+address.state                        address.region
+cart.total                           getCartTotals(cart).total
+cart.discount                        cart.discountAmount
+item.name (in cart)                  item.product.name
+response.url (OAuth)                 response.authorizationUrl
+providers.forEach (OAuth)            response.providers.forEach
+status === 'completed'               status === 'succeeded'
+product.metafields.name              product.metafields[0].definitionName
+product.metafields.key               product.metafields[0].definitionKey
+orderItem.unitPrice                  orderItem.price (OrderItem is FLAT, not nested!)
+cartItem.price                       cartItem.unitPrice (Cart/Checkout items use unitPrice)
+waitResult.orderNumber               waitResult.status.orderNumber (nested in PaymentStatus)
+variant.attributes.map(...)          Object.entries(variant.attributes || {}) (it's an object!)
+categorySuggestion.slug              // ❌ doesn't exist! Only: id, name, productCount
+order.status === 'COMPLETED'         order.status === 'delivered' (OrderStatus is lowercase!)
+getCartTotals(cart)                  // ✅ Works — all carts are server carts now
+result.checkoutId (guest checkout)   // ⚠️ Check result.tracked first! It's a union type
+```
+
+**Key distinctions:**
+
+- **OrderItem** (from orders): Flat structure — `item.price`, `item.name`, `item.image`
+- **CartItem / CheckoutLineItem**: Nested structure — `item.unitPrice`, `item.product.name`, `item.product.images`
+- **`getCartTotals()`** works on all carts — guests now use server-side session carts with full `subtotal`/`discountAmount` fields.
+- **`GuestCheckoutStartResponse`** is a union type — always check `result.tracked` before accessing `result.checkoutId`
+- **`WaitForOrderResult`** has `result.status.orderNumber`, NOT `result.orderNumber`. But `completeGuestCheckout()` returns `GuestOrderResponse` which DOES have `result.orderNumber` directly.
+- **Cart state**: Use `useState<Cart | null>(null)` and load with `smartGetCart()` in `useEffect` — all carts are server-side now, no hydration mismatch issues.
+
+---
+
+## Full SDK Documentation
+
+For complete API reference and working code examples:
+**https://brainerce.com/docs/sdk**