brainerce 1.10.3 → 1.11.0

package/README.md

@@ -4,7 +4,7 @@ Official SDK for building e-commerce storefronts with **Brainerce Platform**.
 
 This SDK provides a complete solution for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts to connect to Brainerce's unified commerce API.
 
-> **🤖 AI Agents / Vibe Coders:** See [AI_BUILDER_PROMPT.md](./AI_BUILDER_PROMPT.md) for a concise, copy-paste-ready prompt optimized for AI code generation. It contains the essential rules and complete code examples to build a working store.
+> **AI Agents / Vibe Coders:** Use the MCP server for AI-powered store building: `npx @brainerce/mcp-server`. It provides docs, code templates, and live store capabilities to any AI tool (Cursor, Lovable, Claude Code).
 
 ## Installation
 
@@ -1058,7 +1058,7 @@ interface Product {
   sku: string;
   basePrice: number;
   salePrice?: number | null;
-  status: 'active' | 'draft' | 'archived';
+  status: 'active' | 'draft';
   type: 'SIMPLE' | 'VARIABLE';
   images?: ProductImage[];
   inventory?: InventoryInfo | null;

package/dist/index.d.mts

@@ -73,6 +73,22 @@ interface BrainerceClientOptions {
         statusCode: number;
         path?: string;
     }) => void;
+    /**
+     * Origin header to send with requests.
+     * Browsers add this automatically, but Node.js environments (SSR, scripts, npx)
+     * do not. When running server-side, the SDK will auto-derive it from `baseUrl`
+     * if not explicitly provided.
+     *
+     * @example
+     * ```typescript
+     * // Explicit origin for server-side usage
+     * const client = new BrainerceClient({
+     *   connectionId: 'vc_abc123...',
+     *   origin: 'https://mysite.com',
+     * });
+     * ```
+     */
+    origin?: string;
     /**
      * Enable proxy mode for BFF (Backend-for-Frontend) pattern.
      * When true, the SDK skips client-side customer token checks and does not
@@ -167,7 +183,7 @@ interface Product {
     salePrice?: string | null;
     /** Cost price as string. Use parseFloat() for calculations. */
     costPrice?: string | null;
-    /** Product status (active, draft, archived). Always returned by backend. */
+    /** Product status (active, draft). Always returned by backend. */
     status: string;
     type: 'SIMPLE' | 'VARIABLE';
     /** Whether product is downloadable/digital. */
@@ -642,7 +658,7 @@ interface ProductQueryParams {
     page?: number;
     limit?: number;
     search?: string;
-    status?: 'active' | 'draft' | 'archived';
+    status?: 'active' | 'draft';
     /** Filter by category IDs (comma-separated or array) */
     categories?: string | string[];
     /** Filter by brand IDs (comma-separated or array) */
@@ -750,7 +766,7 @@ interface UpdateProductDto {
     basePrice?: number;
     salePrice?: number | null;
     costPrice?: number | null;
-    status?: 'active' | 'draft' | 'archived';
+    status?: 'active' | 'draft';
     isDownloadable?: boolean;
     categories?: string[];
     tags?: string[];
@@ -3541,6 +3557,7 @@ declare class BrainerceClient {
      * This is needed because Stripe redirects lose in-memory state.
      */
     private readonly ACTIVE_CHECKOUT_KEY;
+    private readonly origin?;
     private readonly proxyMode;
     private readonly onAuthError?;
     constructor(options: BrainerceClientOptions);

package/dist/index.d.ts

@@ -73,6 +73,22 @@ interface BrainerceClientOptions {
         statusCode: number;
         path?: string;
     }) => void;
+    /**
+     * Origin header to send with requests.
+     * Browsers add this automatically, but Node.js environments (SSR, scripts, npx)
+     * do not. When running server-side, the SDK will auto-derive it from `baseUrl`
+     * if not explicitly provided.
+     *
+     * @example
+     * ```typescript
+     * // Explicit origin for server-side usage
+     * const client = new BrainerceClient({
+     *   connectionId: 'vc_abc123...',
+     *   origin: 'https://mysite.com',
+     * });
+     * ```
+     */
+    origin?: string;
     /**
      * Enable proxy mode for BFF (Backend-for-Frontend) pattern.
      * When true, the SDK skips client-side customer token checks and does not
@@ -167,7 +183,7 @@ interface Product {
     salePrice?: string | null;
     /** Cost price as string. Use parseFloat() for calculations. */
     costPrice?: string | null;
-    /** Product status (active, draft, archived). Always returned by backend. */
+    /** Product status (active, draft). Always returned by backend. */
     status: string;
     type: 'SIMPLE' | 'VARIABLE';
     /** Whether product is downloadable/digital. */
@@ -642,7 +658,7 @@ interface ProductQueryParams {
     page?: number;
     limit?: number;
     search?: string;
-    status?: 'active' | 'draft' | 'archived';
+    status?: 'active' | 'draft';
     /** Filter by category IDs (comma-separated or array) */
     categories?: string | string[];
     /** Filter by brand IDs (comma-separated or array) */
@@ -750,7 +766,7 @@ interface UpdateProductDto {
     basePrice?: number;
     salePrice?: number | null;
     costPrice?: number | null;
-    status?: 'active' | 'draft' | 'archived';
+    status?: 'active' | 'draft';
     isDownloadable?: boolean;
     categories?: string[];
     tags?: string[];
@@ -3541,6 +3557,7 @@ declare class BrainerceClient {
      * This is needed because Stripe redirects lose in-memory state.
      */
     private readonly ACTIVE_CHECKOUT_KEY;
+    private readonly origin?;
     private readonly proxyMode;
     private readonly onAuthError?;
     constructor(options: BrainerceClientOptions);

package/dist/index.js

@@ -223,6 +223,15 @@ var BrainerceClient = class {
     }
     this.baseUrl = resolvedBase;
     this.timeout = options.timeout || DEFAULT_TIMEOUT;
+    if (options.origin) {
+      this.origin = options.origin;
+    } else if (typeof window === "undefined") {
+      try {
+        const parsed = new URL(resolvedBase);
+        this.origin = parsed.origin;
+      } catch {
+      }
+    }
     this.proxyMode = options.proxyMode || false;
     this.onAuthError = options.onAuthError;
     this.hydrateSessionCart();
@@ -327,14 +336,18 @@ var BrainerceClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
+      const headers = {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        "X-SDK-Version": "1.11.0",
+        "ngrok-skip-browser-warning": "true"
+      };
+      if (this.origin) {
+        headers["Origin"] = this.origin;
+      }
       const response = await fetch(url.toString(), {
         method,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json",
-          "X-SDK-Version": "0.3.0",
-          "ngrok-skip-browser-warning": "true"
-        },
+        headers,
         body: body ? JSON.stringify(body) : void 0,
         signal: controller.signal
       });
@@ -384,9 +397,12 @@ var BrainerceClient = class {
     try {
       const headers = {
         "Content-Type": "application/json",
-        "X-SDK-Version": "0.3.0",
+        "X-SDK-Version": "1.11.0",
         "ngrok-skip-browser-warning": "true"
       };
+      if (this.origin) {
+        headers["Origin"] = this.origin;
+      }
       if (this.proxyMode && method !== "GET") {
         headers["X-Requested-With"] = "brainerce";
       }
@@ -452,9 +468,12 @@ var BrainerceClient = class {
     try {
       const headers = {
         "Content-Type": "application/json",
-        "X-SDK-Version": "0.3.0",
+        "X-SDK-Version": "1.11.0",
         "ngrok-skip-browser-warning": "true"
       };
+      if (this.origin) {
+        headers["Origin"] = this.origin;
+      }
       if (this.customerToken) {
         headers["Authorization"] = `Bearer ${this.customerToken}`;
       }

package/dist/index.mjs

@@ -165,6 +165,15 @@ var BrainerceClient = class {
     }
     this.baseUrl = resolvedBase;
     this.timeout = options.timeout || DEFAULT_TIMEOUT;
+    if (options.origin) {
+      this.origin = options.origin;
+    } else if (typeof window === "undefined") {
+      try {
+        const parsed = new URL(resolvedBase);
+        this.origin = parsed.origin;
+      } catch {
+      }
+    }
     this.proxyMode = options.proxyMode || false;
     this.onAuthError = options.onAuthError;
     this.hydrateSessionCart();
@@ -269,14 +278,18 @@ var BrainerceClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
+      const headers = {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        "X-SDK-Version": "1.11.0",
+        "ngrok-skip-browser-warning": "true"
+      };
+      if (this.origin) {
+        headers["Origin"] = this.origin;
+      }
       const response = await fetch(url.toString(), {
         method,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json",
-          "X-SDK-Version": "0.3.0",
-          "ngrok-skip-browser-warning": "true"
-        },
+        headers,
         body: body ? JSON.stringify(body) : void 0,
         signal: controller.signal
       });
@@ -326,9 +339,12 @@ var BrainerceClient = class {
     try {
       const headers = {
         "Content-Type": "application/json",
-        "X-SDK-Version": "0.3.0",
+        "X-SDK-Version": "1.11.0",
         "ngrok-skip-browser-warning": "true"
       };
+      if (this.origin) {
+        headers["Origin"] = this.origin;
+      }
       if (this.proxyMode && method !== "GET") {
         headers["X-Requested-With"] = "brainerce";
       }
@@ -394,9 +410,12 @@ var BrainerceClient = class {
     try {
       const headers = {
         "Content-Type": "application/json",
-        "X-SDK-Version": "0.3.0",
+        "X-SDK-Version": "1.11.0",
         "ngrok-skip-browser-warning": "true"
       };
+      if (this.origin) {
+        headers["Origin"] = this.origin;
+      }
       if (this.customerToken) {
         headers["Authorization"] = `Bearer ${this.customerToken}`;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.10.3",
+  "version": "1.11.0",
   "description": "Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -14,8 +14,7 @@
   },
   "files": [
     "dist",
-    "README.md",
-    "AI_BUILDER_PROMPT.md"
+    "README.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",

package/AI_BUILDER_PROMPT.md

@@ -1,843 +0,0 @@
-# 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**