brainerce 1.0.0

package/README.md

@@ -0,0 +1,4409 @@
+# brainerce
+
+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.
+
+## Installation
+
+```bash
+npm install brainerce
+# or
+pnpm add brainerce
+# or
+yarn add brainerce
+```
+
+---
+
+## Quick Reference - Helper Functions
+
+The SDK exports these utility functions for common UI tasks:
+
+| Function                                       | Purpose                                | Example                                                |
+| ---------------------------------------------- | -------------------------------------- | ------------------------------------------------------ |
+| `formatPrice(amount, { currency?, locale? })`  | Format prices for display              | `formatPrice("99.99", { currency: 'USD' })` → `$99.99` |
+| `getPriceDisplay(amount, currency?, locale?)`  | Alias for `formatPrice`                | Same as above                                          |
+| `getDescriptionContent(product)`               | Get product description (HTML or text) | `getDescriptionContent(product)`                       |
+| `isHtmlDescription(product)`                   | Check if description is HTML           | `isHtmlDescription(product)` → `true/false`            |
+| `getStockStatus(inventory)`                    | Get human-readable stock status        | `getStockStatus(inventory)` → `"In Stock"`             |
+| `getProductPrice(product)`                     | Get effective price (handles sales)    | `getProductPrice(product)` → `29.99`                   |
+| `getProductPriceInfo(product)`                 | Get price + sale info + discount %     | `{ price, isOnSale, discountPercent }`                 |
+| `getVariantPrice(variant, basePrice)`          | Get variant price with fallback        | `getVariantPrice(variant, '29.99')` → `34.99`          |
+| `getCartTotals(cart, shippingPrice?)`          | Calculate cart subtotal/discount/total | `{ subtotal, discount, shipping, total }`              |
+| `getCartItemName(item)`                        | Get name from nested cart item         | `getCartItemName(item)` → `"Blue T-Shirt"`             |
+| `getCartItemImage(item)`                       | Get image URL from cart item           | `getCartItemImage(item)` → `"https://..."`             |
+| `getVariantOptions(variant)`                   | Get variant attributes as array        | `[{ name: "Color", value: "Red" }]`                    |
+| `isCouponApplicableToProduct(coupon, product)` | Check if coupon applies                | `isCouponApplicableToProduct(coupon, product)`         |
+
+```typescript
+import {
+  formatPrice,
+  getDescriptionContent,
+  getStockStatus,
+  getProductPrice,
+  getProductPriceInfo,
+  getCartTotals,
+  getCartItemName,
+  getCartItemImage,
+} from 'brainerce';
+
+// Format price for display
+const priceText = formatPrice(product.basePrice, { currency: 'USD' }); // "$99.99"
+
+// Get product description (handles HTML vs plain text)
+const description = getDescriptionContent(product);
+
+// Get stock status text
+const stockText = getStockStatus(product.inventory); // "In Stock", "Low Stock", "Out of Stock"
+
+// Get effective price (handles sale prices automatically)
+const price = getProductPrice(product); // Returns number: 29.99
+
+// Get full price info including sale status
+const priceInfo = getProductPriceInfo(product);
+// { price: 19.99, originalPrice: 29.99, isOnSale: true, discountPercent: 33 }
+
+// Calculate cart totals
+const totals = getCartTotals(cart, shippingRate?.price);
+// { subtotal: 59.98, discount: 10, shipping: 5.99, total: 55.97 }
+
+// Access cart item details (handles nested structure)
+const itemName = getCartItemName(cartItem); // "Blue T-Shirt - Large"
+const itemImage = getCartItemImage(cartItem); // "https://..."
+```
+
+> **⚠️ DO NOT CREATE YOUR OWN UTILITY FILES!** All helper functions above are exported from `brainerce`. Never create `utils/format.ts`, `lib/helpers.ts`, or similar files - use the SDK exports directly.
+
+---
+
+## ⚠️ CRITICAL: Payment Integration Required!
+
+**Your store will NOT work without payment integration.** The store owner has already configured payment providers (Stripe/PayPal) - you just need to implement the payment page.
+
+```typescript
+// On your checkout/payment page, ALWAYS call this first:
+const { hasPayments, providers } = await omni.getPaymentProviders();
+
+if (!hasPayments) {
+  // Show error - payment is not configured
+  return <div>Payment not configured for this store</div>;
+}
+
+// Show payment forms for available providers
+const stripeProvider = providers.find(p => p.provider === 'stripe');
+const paypalProvider = providers.find(p => p.provider === 'paypal');
+```
+
+**See the [Payment Integration](#payment-integration-vibe-coded-sites) section for complete implementation examples.**
+
+---
+
+## Quick Start
+
+### For Vibe-Coded Sites (Recommended)
+
+```typescript
+import { BrainerceClient } from 'brainerce';
+
+// Initialize with your Connection ID
+const omni = new BrainerceClient({
+  connectionId: 'vc_YOUR_CONNECTION_ID',
+});
+
+// Fetch products
+const { data: products } = await omni.getProducts();
+```
+
+---
+
+## Common Mistakes to Avoid
+
+> **AI Agents / Vibe-Coders:** Read this section carefully! These are common misunderstandings.
+
+### 1. Guest Checkout - Don't Use createCheckout with Local Cart!
+
+**This is the #1 cause of "Cart not found" errors!**
+
+```typescript
+// ❌ WRONG - Local cart ID "__local__" doesn't exist on server!
+const cart = await omni.smartGetCart(); // Returns { id: "__local__", ... }
+const checkout = await omni.createCheckout({ cartId: cart.id }); // 💥 ERROR: Cart not found
+
+// ✅ CORRECT - Use startGuestCheckout() for guest users
+const result = await omni.startGuestCheckout();
+if (result.tracked) {
+  const checkout = await omni.getCheckout(result.checkoutId);
+  // Continue with payment flow...
+}
+
+// ✅ ALTERNATIVE - Use submitGuestOrder() for simple checkout without payment UI
+const order = await omni.submitGuestOrder();
+```
+
+**Rule of thumb:**
+
+- Guest user + Local cart → `startGuestCheckout()` or `submitGuestOrder()`
+- Logged-in user + Server cart → `createCheckout({ cartId })`
+
+### 2. ⛔ NEVER Create Local Interfaces - Use SDK Types!
+
+**This causes type errors and runtime bugs!**
+
+```typescript
+// ❌ WRONG - Don't create your own interfaces!
+interface CartItem {
+  id: string;
+  name: string; // WRONG - it's item.product.name!
+  price: number; // WRONG - prices are strings!
+}
+
+// ❌ WRONG - Don't use 'as unknown as' casting!
+const item = result as unknown as MyLocalType;
+
+// ✅ CORRECT - Import ALL types from SDK
+import type {
+  Product,
+  ProductVariant,
+  Cart,
+  CartItem,
+  Checkout,
+  CheckoutLineItem,
+  Order,
+  OrderItem,
+  CustomerProfile,
+  CustomerAddress,
+  ShippingRate,
+  PaymentProvider,
+  PaymentIntent,
+  PaymentStatus,
+  SearchSuggestions,
+  ProductSuggestion,
+  CategorySuggestion,
+  OAuthAuthorizeResponse,
+  CustomerOAuthProvider,
+} from 'brainerce';
+```
+
+**⚠️ SDK Type Facts - Trust These!**
+
+| What                     | Correct                       | Wrong                 |
+| ------------------------ | ----------------------------- | --------------------- |
+| Prices                   | `string` (use `parseFloat()`) | `number`              |
+| Cart item name           | `item.product.name`           | `item.name`           |
+| Order item name          | `item.name`                   | `item.product.name`   |
+| Cart item image          | `item.product.images[0]`      | `item.image`          |
+| Order item image         | `item.image`                  | `item.product.images` |
+| Address state/province   | `region`                      | `state` or `province` |
+| OAuth redirect URL       | `authorizationUrl`            | `url`                 |
+| OAuth providers response | `{ providers: [...] }`        | `[...]` directly      |
+
+**If you think a type is "wrong", YOU are wrong. Read the SDK types!**
+
+### 3. formatPrice Expects Options Object
+
+```typescript
+// ❌ WRONG
+formatPrice(amount, 'USD');
+
+// ✅ CORRECT
+formatPrice(amount, { currency: 'USD' });
+```
+
+### 4. Cart/Checkout vs Order - Different Item Structures!
+
+**IMPORTANT:** Cart and Checkout items have NESTED product data. Order items are FLAT.
+
+```typescript
+// CartItem and CheckoutLineItem - NESTED product
+cart.items.forEach((item) => {
+  console.log(item.product.name); // ✅ Correct for Cart/Checkout
+  console.log(item.product.sku);
+  console.log(item.product.images);
+});
+
+// OrderItem - FLAT structure
+order.items.forEach((item) => {
+  console.log(item.name); // ✅ Correct for Orders
+  console.log(item.sku);
+  console.log(item.image); // singular, not images
+});
+```
+
+| Type               | Access Name         | Access Image          |
+| ------------------ | ------------------- | --------------------- |
+| `CartItem`         | `item.product.name` | `item.product.images` |
+| `CheckoutLineItem` | `item.product.name` | `item.product.images` |
+| `OrderItem`        | `item.name`         | `item.image`          |
+
+### 5. Payment Status is 'succeeded', not 'completed'
+
+```typescript
+// ❌ WRONG
+if (status.status === 'completed')
+
+// ✅ CORRECT
+if (status.status === 'succeeded')
+```
+
+### 6. ProductSuggestion vs Product - Different Types
+
+`getSearchSuggestions()` returns `ProductSuggestion[]`, NOT `Product[]`.
+This is intentional - suggestions are lightweight for autocomplete.
+
+```typescript
+// ProductSuggestion has:
+{
+  (id, name, slug, image, basePrice, salePrice, type);
+}
+
+// Product has many more fields
+```
+
+### 7. All Prices Are Strings - Use parseFloat()
+
+```typescript
+// ❌ WRONG - assuming number
+const total = item.price * quantity;
+
+// ✅ CORRECT - parse first
+const total = parseFloat(item.price) * quantity;
+
+// Or use SDK helper
+import { formatPrice } from 'brainerce';
+const display = formatPrice(item.price, { currency: 'USD' });
+```
+
+### 8. Variant Attributes Are `Record<string, string>`
+
+```typescript
+// Accessing variant attributes:
+const color = variant.attributes?.['Color']; // string
+const size = variant.attributes?.['Size']; // string
+```
+
+### 9. Address Uses `region`, NOT `state`
+
+```typescript
+// ❌ WRONG
+const address = {
+  state: 'NY', // This field doesn't exist!
+};
+
+// ✅ CORRECT
+const address: SetShippingAddressDto = {
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  city: 'New York',
+  region: 'NY', // Use 'region' for state/province
+  postalCode: '10001',
+  country: 'US',
+};
+```
+
+### 10. OAuth - Use `authorizationUrl`, NOT `url`
+
+```typescript
+// ❌ WRONG
+const response = await omni.getOAuthAuthorizeUrl('GOOGLE', { redirectUrl });
+window.location.href = response.url; // 'url' doesn't exist!
+
+// ✅ CORRECT
+const response = await omni.getOAuthAuthorizeUrl('GOOGLE', { redirectUrl });
+window.location.href = response.authorizationUrl; // Correct property name
+```
+
+### 11. OAuth Provider Type is Exported
+
+```typescript
+// ❌ WRONG - creating your own type
+type Provider = 'google' | 'facebook'; // lowercase won't work!
+
+// ✅ CORRECT - import from SDK
+import { CustomerOAuthProvider } from 'brainerce';
+// CustomerOAuthProvider = 'GOOGLE' | 'FACEBOOK' | 'GITHUB'  (UPPERCASE)
+
+const provider: CustomerOAuthProvider = 'GOOGLE';
+await omni.getOAuthAuthorizeUrl(provider, { redirectUrl });
+```
+
+### 12. getAvailableOAuthProviders Returns Object, Not Array
+
+```typescript
+// ❌ WRONG - expecting array directly
+const providers = await omni.getAvailableOAuthProviders();
+providers.forEach(p => ...);  // Error! providers is not an array
+
+// ✅ CORRECT - access the providers property
+const response = await omni.getAvailableOAuthProviders();
+response.providers.forEach(p => ...);  // response.providers is the array
+```
+
+### 13. SDK Uses `null`, Not `undefined`
+
+Optional fields in SDK types use `null`, not `undefined`:
+
+```typescript
+// SDK types use:
+slug: string | null;
+salePrice: string | null;
+
+// So when checking:
+if (product.slug !== null) {
+  // ✅ Check for null
+  // ...
+}
+```
+
+### 14. Cart Has No `total` Field - Use `getCartTotals()` Helper
+
+```typescript
+// ❌ WRONG - these fields don't exist on Cart
+const total = cart.total; // ← 'total' doesn't exist!
+const discount = cart.discount; // ← 'discount' doesn't exist! It's 'discountAmount'
+
+// ✅ CORRECT - use the helper function (RECOMMENDED)
+import { getCartTotals } from 'brainerce';
+const totals = getCartTotals(cart, shippingPrice);
+// Returns: { subtotal: 59.98, discount: 10, shipping: 5.99, total: 55.97 }
+
+// ✅ CORRECT - or calculate manually
+const subtotal = parseFloat(cart.subtotal);
+const discount = parseFloat(cart.discountAmount); // ← Note: 'discountAmount', NOT 'discount'
+const total = subtotal - discount;
+```
+
+**Important Notes:**
+
+- Cart field is `discountAmount`, NOT `discount`
+- Cart has NO `total` field - use `getCartTotals()` or calculate
+- Checkout DOES have a `total` field, but Cart does not
+- `getCartTotals()` only works with **server Cart** (which has `subtotal` and `discountAmount` fields). It does **NOT** work with **LocalCart** (guest cart from localStorage). For LocalCart, calculate totals manually:
+  ```typescript
+  const subtotal = cart.items.reduce(
+    (sum, item) => sum + parseFloat(item.price || '0') * item.quantity,
+    0
+  );
+  ```
+
+### 15. SearchSuggestions - Products Have `price`, Not `basePrice`
+
+```typescript
+// In SearchSuggestions, ProductSuggestion has:
+// - price: effective price (sale price if on sale, otherwise base price)
+// - basePrice: original price
+// - salePrice: sale price if on sale
+
+// ✅ Use 'price' for display (it's already the correct price)
+suggestions.products.map(p => (
+  <div>{p.name} - {formatPrice(p.price, { currency })}</div>
+));
+```
+
+### 16. Forgetting to Clear Cart After Payment
+
+**This causes "ghost items" in the cart after successful payment!**
+
+```typescript
+// ❌ WRONG - Cart items remain after payment!
+// In your success page:
+export default function SuccessPage() {
+  return <div>Thank you for your order!</div>;
+  // User goes back to shop → still sees purchased items in cart!
+}
+
+// ✅ CORRECT - Call completeGuestCheckout() on success page
+export default function SuccessPage() {
+  const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
+
+  useEffect(() => {
+    if (checkoutId) {
+      // Send order to server AND clear cart
+      omni.completeGuestCheckout(checkoutId);
+    }
+  }, []);
+
+  return <div>Thank you for your order!</div>;
+}
+```
+
+**Why is this needed?**
+
+- `completeGuestCheckout()` sends the order to the server AND clears the local cart
+- Without it, the order is never created on the server (payment goes through but no order!)
+- For partial checkout (AliExpress-style), only the purchased items are removed
+- **WARNING:** Do NOT use `handlePaymentSuccess()` - it only clears localStorage and does NOT create the order
+
+---
+
+## Checkout: Guest vs Logged-In Customer
+
+> **⚠️ CRITICAL:** There are TWO different checkout flows. Using the wrong one will cause errors!
+
+| Customer Type | Cart Type                 | With Payment (Stripe)  | Without Payment UI   |
+| ------------- | ------------------------- | ---------------------- | -------------------- |
+| **Guest**     | Local Cart (localStorage) | `startGuestCheckout()` | `submitGuestOrder()` |
+| **Logged In** | Server Cart               | `createCheckout()`     | `completeCheckout()` |
+
+### ❌ COMMON MISTAKE - Don't Do This!
+
+```typescript
+// ❌ WRONG - This will FAIL with "Cart not found" error!
+const cart = omni.getLocalCart(); // Returns cart with id: "__local__"
+const checkout = await omni.createCheckout({ cartId: cart.id }); // ERROR!
+
+// The "__local__" ID is virtual - it doesn't exist on the server!
+```
+
+### ✅ Correct Flow for Guest Checkout with Payment
+
+```typescript
+// ✅ CORRECT - Use startGuestCheckout() for guests with local cart
+const result = await omni.startGuestCheckout();
+
+if (result.tracked) {
+  // Now you have a REAL checkout on the server
+  const checkout = await omni.getCheckout(result.checkoutId);
+
+  // Continue with shipping, payment, etc.
+  await omni.setShippingAddress(result.checkoutId, { ... });
+  const intent = await omni.createPaymentIntent(result.checkoutId);
+  // ... Stripe payment ...
+}
+```
+
+### Decision Flow
+
+```typescript
+// ALWAYS check this at checkout!
+if (isLoggedIn()) {
+  // ✅ Logged-in customer → Server Cart + Checkout flow
+  // Orders will be linked to their account
+  const order = await completeServerCheckout();
+} else {
+  // ✅ Guest → Local Cart + submitGuestOrder
+  // Orders are standalone (not linked to any account)
+  const order = await omni.submitGuestOrder();
+}
+```
+
+### Guest Checkout (for visitors without account)
+
+```typescript
+// Cart stored locally - NO API calls until checkout!
+
+// Add to local cart (stored in localStorage)
+omni.addToLocalCart({
+  productId: products[0].id,
+  quantity: 1,
+  name: products[0].name,
+  price: String(products[0].basePrice),
+});
+
+// Set customer info
+omni.setLocalCartCustomer({ email: 'customer@example.com' });
+omni.setLocalCartShippingAddress({
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  city: 'New York',
+  postalCode: '10001',
+  country: 'US',
+});
+
+// Submit order (single API call!)
+const order = await omni.submitGuestOrder();
+console.log('Order created:', order.orderId);
+```
+
+### Logged-In Customer Checkout (orders linked to account)
+
+```typescript
+// 1. Make sure customer token is set (after login)
+omni.setCustomerToken(authResponse.token);
+
+// 2. Create server cart (auto-linked to customer!)
+const cart = await omni.createCart();
+localStorage.setItem('cartId', cart.id);
+
+// 3. Add items to server cart
+await omni.addToCart(cart.id, {
+  productId: products[0].id,
+  quantity: 1,
+});
+
+// 4. Create checkout from cart
+const checkout = await omni.createCheckout({ cartId: cart.id });
+
+// 5. Set customer info (REQUIRED - email is needed for order!)
+await omni.setCheckoutCustomer(checkout.id, {
+  email: 'customer@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+});
+
+// 6. Set shipping address
+await omni.setShippingAddress(checkout.id, {
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  city: 'New York',
+  postalCode: '10001',
+  country: 'US',
+});
+
+// 7. Get shipping rates and select one
+const rates = await omni.getShippingRates(checkout.id);
+await omni.selectShippingMethod(checkout.id, rates[0].id);
+
+// 8. Complete checkout - order is linked to customer!
+const { orderId } = await omni.completeCheckout(checkout.id);
+console.log('Order created:', orderId);
+
+// Customer can now see this order in omni.getMyOrders()
+```
+
+> **WARNING:** Do NOT use `submitGuestOrder()` for logged-in customers! Their orders won't be linked to their account and won't appear in their order history.
+
+---
+
+## Two Ways to Handle Cart
+
+### Option 1: Local Cart (Guest Users)
+
+For guest users, the cart is stored in **localStorage** - exactly like Amazon, Shopify, and other major platforms do. This means:
+
+- ✅ No API calls when browsing/adding to cart
+- ✅ Cart persists across page refreshes
+- ✅ Single API call at checkout
+- ✅ No server load for window shoppers
+
+```typescript
+// Add product to local cart
+omni.addToLocalCart({ productId: 'prod_123', quantity: 2 });
+
+// View cart
+const cart = omni.getLocalCart();
+console.log('Items:', cart.items.length);
+
+// Update quantity
+omni.updateLocalCartItem('prod_123', 5);
+
+// Remove item
+omni.removeFromLocalCart('prod_123');
+
+// At checkout - submit everything in ONE API call
+const order = await omni.submitGuestOrder();
+```
+
+### Option 2: Server Cart (Logged-In Customers)
+
+For logged-in customers, **you MUST use server-side cart** to link orders to their account:
+
+- ✅ Cart syncs across devices
+- ✅ Abandoned cart recovery
+- ✅ Orders linked to customer account
+- ✅ Customer can see orders in "My Orders"
+
+```typescript
+// 1. Set customer token (after login)
+omni.setCustomerToken(token);
+
+// 2. Create cart (auto-linked to customer)
+const cart = await omni.createCart();
+localStorage.setItem('cartId', cart.id);
+
+// 3. Add items
+await omni.addToCart(cart.id, { productId: 'prod_123', quantity: 2 });
+
+// 4. At checkout - create checkout and complete
+const checkout = await omni.createCheckout({ cartId: cart.id });
+// ... set shipping address, select shipping method ...
+const { orderId } = await omni.completeCheckout(checkout.id);
+```
+
+> **⚠️ CRITICAL:** If you use `submitGuestOrder()` for a logged-in customer, their order will NOT be linked to their account!
+
+---
+
+## Complete Store Setup
+
+### Step 1: Create the Brainerce Client
+
+Create a file `lib/brainerce.ts`:
+
+```typescript
+import { BrainerceClient } from 'brainerce';
+
+export const omni = new BrainerceClient({
+  connectionId: 'vc_YOUR_CONNECTION_ID', // Your Connection ID from Brainerce
+});
+
+// ----- Guest Cart Helpers (localStorage) -----
+
+export function getCartItemCount(): number {
+  return omni.getLocalCartItemCount();
+}
+
+export function getCart() {
+  return omni.getLocalCart();
+}
+
+// ----- For Registered Users (server cart) -----
+
+export function getServerCartId(): string | null {
+  if (typeof window === 'undefined') return null;
+  return localStorage.getItem('cartId');
+}
+
+export function setServerCartId(id: string): void {
+  localStorage.setItem('cartId', id);
+}
+
+export function clearServerCartId(): void {
+  localStorage.removeItem('cartId');
+}
+
+// ----- Customer Token Helpers -----
+
+export function setCustomerToken(token: string | null): void {
+  if (token) {
+    localStorage.setItem('customerToken', token);
+    omni.setCustomerToken(token);
+  } else {
+    localStorage.removeItem('customerToken');
+    omni.clearCustomerToken();
+  }
+}
+
+export function restoreCustomerToken(): string | null {
+  const token = localStorage.getItem('customerToken');
+  if (token) omni.setCustomerToken(token);
+  return token;
+}
+
+export function isLoggedIn(): boolean {
+  return !!localStorage.getItem('customerToken');
+}
+```
+
+---
+
+## Important: Cart & Checkout Data Structures
+
+### Nested Product/Variant Structure
+
+Cart and Checkout items use a **nested structure** for product and variant data. This is a common pattern that prevents data duplication and ensures consistency.
+
+**Common Mistake:**
+
+```typescript
+// WRONG - product name is NOT at top level
+const name = item.name; // undefined!
+const sku = item.sku; // undefined!
+```
+
+**Correct Access Pattern:**
+
+```typescript
+// CORRECT - access via nested objects
+const name = item.product.name;
+const sku = item.product.sku;
+const variantName = item.variant?.name;
+const variantSku = item.variant?.sku;
+```
+
+### Field Mapping Reference
+
+| What You Want  | CartItem                  | CheckoutLineItem          |
+| -------------- | ------------------------- | ------------------------- |
+| Product Name   | `item.product.name`       | `item.product.name`       |
+| Product SKU    | `item.product.sku`        | `item.product.sku`        |
+| Product ID     | `item.productId`          | `item.productId`          |
+| Product Images | `item.product.images`     | `item.product.images`     |
+| Variant Name   | `item.variant?.name`      | `item.variant?.name`      |
+| Variant SKU    | `item.variant?.sku`       | `item.variant?.sku`       |
+| Variant ID     | `item.variantId`          | `item.variantId`          |
+| Unit Price     | `item.unitPrice` (string) | `item.unitPrice` (string) |
+| Quantity       | `item.quantity`           | `item.quantity`           |
+
+### Price Fields Are Strings
+
+All monetary values in Cart and Checkout are returned as **strings** (e.g., `"29.99"`) to preserve decimal precision across different systems. Use `parseFloat()` or the `formatPrice()` helper:
+
+```typescript
+// Monetary fields that are strings:
+// - CartItem: unitPrice, discountAmount
+// - Cart: subtotal, discountAmount
+// - CheckoutLineItem: unitPrice, discountAmount
+// - Checkout: subtotal, discountAmount, shippingAmount, taxAmount, total
+// - ShippingRate: price
+
+import { formatPrice } from 'brainerce';
+
+// Option 1: Using formatPrice helper (recommended)
+const cart = await omni.getCart(cartId);
+const total = formatPrice(cart.subtotal); // "$59.98"
+const totalNum = formatPrice(cart.subtotal, { asNumber: true }); // 59.98
+
+// Option 2: Manual parseFloat
+const subtotal = parseFloat(cart.subtotal);
+const discount = parseFloat(cart.discountAmount);
+const total = subtotal - discount;
+
+// Line item total
+cart.items.forEach((item) => {
+  const lineTotal = parseFloat(item.unitPrice) * item.quantity;
+  console.log(`${item.product.name}: $${lineTotal.toFixed(2)}`);
+});
+```
+
+### Complete Cart Item Display Example
+
+```typescript
+import type { CartItem } from 'brainerce';
+import { formatPrice } from 'brainerce';
+
+function CartItemRow({ item }: { item: CartItem }) {
+  // Access nested product data
+  const productName = item.product.name;
+  const productSku = item.product.sku;
+  const productImage = item.product.images?.[0]?.url;
+
+  // Access nested variant data (if exists)
+  const variantName = item.variant?.name;
+  const displayName = variantName ? `${productName} - ${variantName}` : productName;
+
+  // Format price using helper
+  const unitPrice = formatPrice(item.unitPrice);
+  const lineTotal = formatPrice(item.unitPrice, { asNumber: true }) * item.quantity;
+
+  return (
+    <div className="flex items-center gap-4">
+      <img src={productImage} alt={displayName} className="w-16 h-16 object-cover" />
+      <div className="flex-1">
+        <h3 className="font-medium">{displayName}</h3>
+        <p className="text-sm text-gray-500">SKU: {item.variant?.sku || productSku}</p>
+      </div>
+      <span className="text-gray-600">Qty: {item.quantity}</span>
+      <span className="font-medium">${lineTotal.toFixed(2)}</span>
+    </div>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### Products
+
+#### Get Products (with pagination)
+
+```typescript
+import { omni } from '@/lib/brainerce';
+import type { Product, PaginatedResponse } from 'brainerce';
+
+const response: PaginatedResponse<Product> = await omni.getProducts({
+  page: 1,
+  limit: 12,
+  search: 'shirt', // Optional: search by name
+  status: 'active', // Optional: 'active' | 'draft' | 'archived'
+  type: 'SIMPLE', // Optional: 'SIMPLE' | 'VARIABLE'
+  sortBy: 'createdAt', // Optional: 'name' | 'createdAt' | 'updatedAt' | 'basePrice'
+  sortOrder: 'desc', // Optional: 'asc' | 'desc'
+});
+
+console.log(response.data); // Product[]
+console.log(response.meta.total); // Total number of products
+console.log(response.meta.totalPages); // Total pages
+```
+
+#### Get Single Product
+
+```typescript
+const product: Product = await omni.getProduct('product_id');
+
+console.log(product.name);
+console.log(product.basePrice);
+console.log(product.salePrice); // null if no sale
+console.log(product.images); // ProductImage[]
+console.log(product.variants); // ProductVariant[] (for VARIABLE products)
+console.log(product.inventory); // { total, reserved, available }
+```
+
+#### Search Suggestions (Autocomplete)
+
+Get search suggestions for building autocomplete/search-as-you-type UI:
+
+```typescript
+import type { SearchSuggestions } from 'brainerce';
+
+// Basic autocomplete
+const suggestions: SearchSuggestions = await omni.getSearchSuggestions('shirt');
+
+console.log(suggestions.products);
+// [{ id, name, image, basePrice, salePrice, type }]
+
+console.log(suggestions.categories);
+// [{ id, name, productCount }]
+
+// With custom limit (default: 5, max: 10)
+const suggestions = await omni.getSearchSuggestions('dress', 3);
+```
+
+**Search covers:** name, sku, description, categories, tags, and brands.
+
+**Example: Search Input with Suggestions**
+
+```typescript
+function SearchInput() {
+  const [query, setQuery] = useState('');
+  const [suggestions, setSuggestions] = useState<SearchSuggestions | null>(null);
+
+  // Debounce search requests
+  useEffect(() => {
+    if (query.length < 2) {
+      setSuggestions(null);
+      return;
+    }
+
+    const timer = setTimeout(async () => {
+      const results = await omni.getSearchSuggestions(query, 5);
+      setSuggestions(results);
+    }, 300);
+
+    return () => clearTimeout(timer);
+  }, [query]);
+
+  return (
+    <div>
+      <input
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        placeholder="Search products..."
+      />
+      {suggestions && (
+        <div className="suggestions">
+          {suggestions.products.map((product) => (
+            <a key={product.id} href={`/products/${product.slug}`}>
+              <img src={product.image || '/placeholder.png'} alt={product.name} />
+              <span>{product.name}</span>
+              <span>${product.basePrice}</span>
+            </a>
+          ))}
+          {suggestions.categories.map((category) => (
+            <a key={category.id} href={`/category/${category.id}`}>
+              {category.name} ({category.productCount} products)
+            </a>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+#### Product Type Definition
+
+```typescript
+interface Product {
+  id: string;
+  name: string;
+  description?: string | null;
+  descriptionFormat?: 'text' | 'html' | 'markdown'; // Format of description content
+  sku: string;
+  basePrice: number;
+  salePrice?: number | null;
+  status: 'active' | 'draft' | 'archived';
+  type: 'SIMPLE' | 'VARIABLE';
+  images?: ProductImage[];
+  inventory?: InventoryInfo | null;
+  variants?: ProductVariant[];
+  categories?: string[];
+  tags?: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface ProductImage {
+  url: string;
+  position?: number;
+  isMain?: boolean;
+}
+
+interface ProductVariant {
+  id: string;
+  sku?: string | null;
+  name?: string | null;
+  price?: number | null;
+  salePrice?: number | null;
+  attributes?: Record<string, string>;
+  inventory?: InventoryInfo | null;
+}
+
+interface InventoryInfo {
+  total: number;
+  reserved: number;
+  available: number;
+  trackingMode?: 'TRACKED' | 'UNLIMITED' | 'DISABLED';
+  inStock: boolean; // Pre-calculated - use this for display!
+  canPurchase: boolean; // Pre-calculated - use this for add-to-cart
+}
+```
+
+#### Product Metafields (Custom Fields)
+
+Products can have custom fields (metafields) defined by the store owner, such as "Material", "Care Instructions", or "Warranty".
+
+```typescript
+import {
+  getProductMetafield,
+  getProductMetafieldValue,
+  getProductMetafieldsByType,
+} from 'brainerce';
+
+const product = await omni.getProductBySlug('blue-shirt');
+
+// Access all metafields
+product.metafields?.forEach((field) => {
+  console.log(`${field.definitionName}: ${field.value}`);
+});
+
+// Get a specific metafield by key
+const material = getProductMetafieldValue(product, 'material'); // auto-parsed (string | number | boolean | null)
+const careField = getProductMetafield(product, 'care_instructions'); // full ProductMetafield object
+
+// Filter metafields by type
+const textFields = getProductMetafieldsByType(product, 'TEXT');
+
+// Fetch metafield definitions (schema) to build dynamic UI
+const { definitions } = await omni.getPublicMetafieldDefinitions();
+definitions.forEach((def) => {
+  console.log(`${def.name} (${def.key}): ${def.type}, required: ${def.required}`);
+});
+```
+
+> **Note:** `metafields` may be empty if the store hasn't defined custom fields. Always use optional chaining (`product.metafields?.forEach`).
+
+#### Displaying Price Range for Variable Products
+
+For products with `type: 'VARIABLE'` and multiple variants with different prices, display a **price range** instead of a single price:
+
+```typescript
+// Helper function to get price range from variants
+function getPriceRange(product: Product): { min: number; max: number } | null {
+  if (product.type !== 'VARIABLE' || !product.variants?.length) {
+    return null;
+  }
+
+  const prices = product.variants
+    .map(v => v.price ?? product.basePrice)
+    .filter((p): p is number => p !== null);
+
+  if (prices.length === 0) return null;
+
+  const min = Math.min(...prices);
+  const max = Math.max(...prices);
+
+  // Return null if all variants have the same price
+  return min !== max ? { min, max } : null;
+}
+
+// Usage in component
+function ProductPrice({ product }: { product: Product }) {
+  const priceRange = getPriceRange(product);
+
+  if (priceRange) {
+    // Variable product with different variant prices - show range
+    return <span>${priceRange.min} - ${priceRange.max}</span>;
+  }
+
+  // Simple product or all variants same price - show single price
+  return product.salePrice ? (
+    <>
+      <span className="text-red-600">${product.salePrice}</span>
+      <span className="line-through text-gray-400 ml-2">${product.basePrice}</span>
+    </>
+  ) : (
+    <span>${product.basePrice}</span>
+  );
+}
+```
+
+**When to show price range:**
+
+- Product `type` is `'VARIABLE'`
+- Has 2+ variants with **different** prices
+- Example: T-shirt sizes S/M/L at $29, XL/XXL at $34 → Display "$29 - $34"
+
+**When to show single price:**
+
+- Product `type` is `'SIMPLE'`
+- Variable product where all variants have the same price
+
+#### Rendering Product Descriptions
+
+> **CRITICAL**: Product descriptions from Shopify/WooCommerce contain HTML tags. If you render them as plain text, users will see raw `<p>`, `<ul>`, `<li>` tags instead of formatted content!
+
+Use the SDK helper functions to handle this automatically:
+
+```tsx
+import { isHtmlDescription, getDescriptionContent } from 'brainerce';
+
+// Option 1: Using isHtmlDescription helper (recommended)
+function ProductDescription({ product }: { product: Product }) {
+  if (!product.description) return null;
+
+  if (isHtmlDescription(product)) {
+    // HTML from Shopify/WooCommerce - MUST use dangerouslySetInnerHTML
+    return <div dangerouslySetInnerHTML={{ __html: product.description }} />;
+  }
+
+  // Plain text - render normally
+  return <p>{product.description}</p>;
+}
+
+// Option 2: Using getDescriptionContent helper
+function ProductDescription({ product }: { product: Product }) {
+  const content = getDescriptionContent(product);
+  if (!content) return null;
+
+  if ('html' in content) {
+    return <div dangerouslySetInnerHTML={{ __html: content.html }} />;
+  }
+
+  return <p>{content.text}</p>;
+}
+```
+
+| Source Platform | descriptionFormat | Rendering                     |
+| --------------- | ----------------- | ----------------------------- |
+| Shopify         | `'html'`          | Use `dangerouslySetInnerHTML` |
+| WooCommerce     | `'html'`          | Use `dangerouslySetInnerHTML` |
+| TikTok          | `'text'`          | Render as plain text          |
+| Manual entry    | `'text'`          | Render as plain text          |
+
+**Common Mistake** - DO NOT do this:
+
+```tsx
+// WRONG - HTML will show as raw tags like <p>Hello</p>
+<p>{product.description}</p>
+```
+
+---
+
+### Local Cart (Guest Users) - RECOMMENDED
+
+The local cart stores everything in **localStorage** until checkout. This is the recommended approach for most storefronts.
+
+#### Add to Local Cart
+
+```typescript
+// Add item with product info (for display)
+omni.addToLocalCart({
+  productId: 'prod_123',
+  variantId: 'var_456', // Optional: for products with variants
+  quantity: 2,
+  name: 'Cool T-Shirt', // Optional: for cart display
+  price: '29.99', // Optional: for cart display
+  image: 'https://...', // Optional: for cart display
+});
+```
+
+#### Get Local Cart
+
+```typescript
+const cart = omni.getLocalCart();
+
+console.log(cart.items); // Array of cart items
+console.log(cart.customer); // Customer info (if set)
+console.log(cart.shippingAddress); // Shipping address (if set)
+console.log(cart.couponCode); // Applied coupon (if any)
+```
+
+#### Update Item Quantity
+
+```typescript
+// Set quantity to 5
+omni.updateLocalCartItem('prod_123', 5);
+
+// For variant products
+omni.updateLocalCartItem('prod_123', 3, 'var_456');
+
+// Set to 0 to remove
+omni.updateLocalCartItem('prod_123', 0);
+```
+
+#### Remove Item
+
+```typescript
+omni.removeFromLocalCart('prod_123');
+omni.removeFromLocalCart('prod_123', 'var_456'); // With variant
+```
+
+#### Clear Cart
+
+```typescript
+omni.clearLocalCart();
+```
+
+#### Set Customer Info
+
+```typescript
+omni.setLocalCartCustomer({
+  email: 'customer@example.com', // Required
+  firstName: 'John', // Optional
+  lastName: 'Doe', // Optional
+  phone: '+1234567890', // Optional
+});
+```
+
+#### Set Shipping Address
+
+```typescript
+omni.setLocalCartShippingAddress({
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  line2: 'Apt 4B', // Optional
+  city: 'New York',
+  region: 'NY', // Optional: State/Province
+  postalCode: '10001',
+  country: 'US',
+  phone: '+1234567890', // Optional
+});
+```
+
+#### Set Billing Address (Optional)
+
+```typescript
+omni.setLocalCartBillingAddress({
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '456 Business Ave',
+  city: 'New York',
+  postalCode: '10002',
+  country: 'US',
+});
+```
+
+#### Apply Coupon
+
+```typescript
+omni.setLocalCartCoupon('SAVE20');
+
+// Remove coupon
+omni.setLocalCartCoupon(undefined);
+```
+
+#### Get Cart Item Count
+
+```typescript
+const count = omni.getLocalCartItemCount();
+console.log(`${count} items in cart`);
+```
+
+#### Local Cart Type Definition
+
+```typescript
+interface LocalCart {
+  items: LocalCartItem[];
+  couponCode?: string;
+  customer?: {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+  };
+  shippingAddress?: {
+    firstName: string;
+    lastName: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    region?: string;
+    postalCode: string;
+    country: string;
+    phone?: string;
+  };
+  billingAddress?: {
+    /* same as shipping */
+  };
+  notes?: string;
+  updatedAt: string;
+}
+
+interface LocalCartItem {
+  productId: string;
+  variantId?: string;
+  quantity: number;
+  name?: string;
+  sku?: string;
+  price?: string;
+  image?: string;
+  addedAt: string;
+}
+```
+
+---
+
+### Guest Checkout (Submit Order)
+
+Submit the local cart as an order with a **single API call**:
+
+```typescript
+// Make sure cart has items, customer email, and shipping address
+const order = await omni.submitGuestOrder();
+
+console.log(order.orderId); // 'order_abc123...'
+console.log(order.orderNumber); // 'ORD-12345'
+console.log(order.status); // 'pending'
+console.log(order.total); // 59.98
+console.log(order.message); // 'Order created successfully'
+
+// Cart is automatically cleared after successful order
+```
+
+> **🔄 Automatic Tracking:** If "Track Guest Checkouts" is enabled in your connection settings (Brainerce Admin), `submitGuestOrder()` will automatically create a tracked checkout session before placing the order. This allows you to see abandoned carts and checkout sessions in your admin dashboard - **no code changes needed!**
+
+#### Keep Cart After Order
+
+```typescript
+// If you want to keep the cart data (e.g., for order review page)
+const order = await omni.submitGuestOrder({ clearCartOnSuccess: false });
+```
+
+#### Create Order with Custom Data
+
+If you manage cart state yourself instead of using local cart:
+
+```typescript
+const order = await omni.createGuestOrder({
+  items: [
+    { productId: 'prod_123', quantity: 2 },
+    { productId: 'prod_456', variantId: 'var_789', quantity: 1 },
+  ],
+  customer: {
+    email: 'customer@example.com',
+    firstName: 'John',
+    lastName: 'Doe',
+  },
+  shippingAddress: {
+    firstName: 'John',
+    lastName: 'Doe',
+    line1: '123 Main St',
+    city: 'New York',
+    postalCode: '10001',
+    country: 'US',
+  },
+  couponCode: 'SAVE20', // Optional
+  notes: 'Please gift wrap', // Optional
+});
+```
+
+#### Guest Order Response Type
+
+```typescript
+interface GuestOrderResponse {
+  orderId: string;
+  orderNumber: string;
+  status: string;
+  total: number;
+  message: string;
+}
+```
+
+---
+
+### Tracked Guest Checkout (Automatic)
+
+> **Note:** As of SDK v0.7.1, `submitGuestOrder()` automatically handles tracking. You don't need to use these methods unless you want explicit control over the checkout flow.
+
+When **"Track Guest Checkouts"** is enabled in your connection settings, checkout sessions are automatically created on the server, allowing:
+
+- Visibility of checkout sessions in admin dashboard
+- Abandoned cart tracking
+- Future: abandoned cart recovery emails
+
+#### How to Enable
+
+1. Go to Brainerce Admin → Integrations → Vibe-Coded Sites
+2. Click on your connection → Settings
+3. Enable "Track Guest Checkouts"
+4. Save - that's it! No code changes needed.
+
+#### Advanced: Manual Tracking Control
+
+If you need explicit control over the tracking flow (e.g., to track checkout steps before the user places an order):
+
+```typescript
+// 1. Start tracked checkout (sends cart items to server)
+const checkout = await omni.startGuestCheckout();
+
+if (checkout.tracked) {
+  // 2. Update with shipping address
+  await omni.updateGuestCheckoutAddress(checkout.checkoutId, {
+    shippingAddress: {
+      firstName: 'John',
+      lastName: 'Doe',
+      line1: '123 Main St',
+      city: 'New York',
+      postalCode: '10001',
+      country: 'US',
+    },
+  });
+
+  // 3. Complete the checkout
+  const order = await omni.completeGuestCheckout(checkout.checkoutId);
+  console.log('Order created:', order.orderId);
+} else {
+  // Fallback to regular guest checkout
+  const order = await omni.submitGuestOrder();
+}
+```
+
+#### Response Types
+
+```typescript
+type GuestCheckoutStartResponse =
+  | {
+      tracked: true;
+      checkoutId: string;
+      cartId: string;
+      message: string;
+    }
+  | {
+      tracked: false;
+      message: string;
+    };
+```
+
+---
+
+### Server Cart (Registered Users)
+
+For logged-in customers who want cart sync across devices.
+
+#### Create Cart
+
+```typescript
+const cart = await omni.createCart();
+setServerCartId(cart.id); // Save to localStorage
+```
+
+#### Get Cart
+
+```typescript
+const cartId = getCartId();
+if (cartId) {
+  const cart = await omni.getCart(cartId);
+  console.log(cart.items); // CartItem[]
+  console.log(cart.itemCount); // Total items
+  console.log(cart.subtotal); // Subtotal amount
+}
+```
+
+#### Add to Cart
+
+```typescript
+const cart = await omni.addToCart(cartId, {
+  productId: 'product_id',
+  variantId: 'variant_id', // Optional: for VARIABLE products
+  quantity: 2,
+  notes: 'Gift wrap please', // Optional
+});
+```
+
+#### Update Cart Item
+
+```typescript
+const cart = await omni.updateCartItem(cartId, itemId, {
+  quantity: 3,
+});
+```
+
+#### Remove Cart Item
+
+```typescript
+const cart = await omni.removeCartItem(cartId, itemId);
+```
+
+#### Apply Coupon
+
+```typescript
+const cart = await omni.applyCoupon(cartId, 'SAVE20');
+console.log(cart.discountAmount); // Discount applied
+console.log(cart.couponCode); // 'SAVE20'
+```
+
+#### Remove Coupon
+
+```typescript
+const cart = await omni.removeCoupon(cartId);
+```
+
+#### Cart Type Definition
+
+```typescript
+interface Cart {
+  id: string;
+  sessionToken?: string | null;
+  customerId?: string | null;
+  status: 'ACTIVE' | 'MERGED' | 'CONVERTED' | 'ABANDONED';
+  currency: string;
+  subtotal: string;
+  discountAmount: string;
+  couponCode?: string | null;
+  items: CartItem[];
+  itemCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface CartItem {
+  id: string;
+  productId: string;
+  variantId?: string | null;
+  quantity: number;
+  unitPrice: string;
+  discountAmount: string;
+  notes?: string | null;
+  product: {
+    id: string;
+    name: string;
+    sku: string;
+    images?: unknown[];
+  };
+  variant?: {
+    id: string;
+    name?: string | null;
+    sku?: string | null;
+  } | null;
+}
+```
+
+---
+
+### Checkout
+
+#### Create Checkout from Cart
+
+```typescript
+const checkout = await omni.createCheckout({
+  cartId: cartId,
+});
+```
+
+#### Partial Checkout (AliExpress-style)
+
+Allow customers to select which items to checkout from their cart. Only selected items are purchased - remaining items stay in the cart for later.
+
+```typescript
+// 1. In your cart page, track selected items
+const [selectedItems, setSelectedItems] = useState<Set<string>>(new Set());
+
+// 2. Create checkout with only selected items
+const checkout = await omni.createCheckout({
+  cartId: cart.id,
+  selectedItemIds: Array.from(selectedItems), // Only these items go to checkout
+});
+
+// 3. Before checkout, check stock ONLY for selected items
+const stockCheck = await omni.checkCartStock(cart, Array.from(selectedItems));
+if (!stockCheck.allAvailable) {
+  // Handle out-of-stock items
+}
+
+// After successful payment:
+// - Selected items are REMOVED from cart
+// - Unselected items REMAIN in cart (cart stays ACTIVE)
+// - Customer can continue shopping and checkout remaining items later
+```
+
+#### Set Customer Information
+
+```typescript
+const checkout = await omni.setCheckoutCustomer(checkoutId, {
+  email: 'customer@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  phone: '+1234567890', // Optional
+});
+```
+
+#### Set Shipping Address
+
+```typescript
+const { checkout, rates } = await omni.setShippingAddress(checkoutId, {
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  line2: 'Apt 4B', // Optional
+  city: 'New York',
+  region: 'NY', // State/Province
+  postalCode: '10001',
+  country: 'US',
+  phone: '+1234567890', // Optional
+});
+
+// rates contains available shipping options
+console.log(rates); // ShippingRate[]
+```
+
+#### Select Shipping Method
+
+```typescript
+const checkout = await omni.selectShippingMethod(checkoutId, rates[0].id);
+```
+
+#### Set Billing Address
+
+```typescript
+// Same as shipping
+const checkout = await omni.setBillingAddress(checkoutId, {
+  ...shippingAddress,
+  sameAsShipping: true, // Optional shortcut
+});
+```
+
+#### Complete Checkout
+
+```typescript
+const { orderId } = await omni.completeCheckout(checkoutId);
+clearCartId(); // Clear cart from localStorage
+console.log('Order created:', orderId);
+```
+
+#### Checkout Type Definition
+
+```typescript
+interface Checkout {
+  id: string;
+  status: CheckoutStatus;
+  email?: string | null;
+  shippingAddress?: CheckoutAddress | null;
+  billingAddress?: CheckoutAddress | null;
+  shippingMethod?: ShippingRate | null;
+  currency: string;
+  subtotal: string;
+  discountAmount: string;
+  shippingAmount: string;
+  taxAmount: string;
+  total: string;
+  couponCode?: string | null;
+  items: CheckoutLineItem[];
+  itemCount: number;
+  availableShippingRates?: ShippingRate[];
+}
+
+type CheckoutStatus = 'PENDING' | 'SHIPPING_SET' | 'PAYMENT_PENDING' | 'COMPLETED' | 'FAILED';
+
+interface ShippingRate {
+  id: string;
+  name: string;
+  description?: string | null;
+  price: string;
+  currency: string;
+  estimatedDays?: number | null;
+}
+```
+
+#### Shipping Rates: Complete Flow
+
+The shipping flow involves setting an address and then selecting from available rates:
+
+```typescript
+// Step 1: Set shipping address - this returns available rates
+const { checkout, rates } = await omni.setShippingAddress(checkoutId, {
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  city: 'New York',
+  region: 'NY',
+  postalCode: '10001',
+  country: 'US',
+});
+
+// Step 2: Handle empty rates (edge case)
+if (rates.length === 0) {
+  // No shipping options available for this address
+  // This can happen when:
+  // - Store doesn't ship to this address/country
+  // - All shipping methods have restrictions that exclude this address
+  // - Shipping rates haven't been configured in the store
+
+  return (
+    <div className="bg-yellow-50 p-4 rounded">
+      <p className="font-medium">No shipping options available</p>
+      <p className="text-sm text-gray-600">
+        We currently cannot ship to this address. Please try a different address or contact us for
+        assistance.
+      </p>
+    </div>
+  );
+}
+
+// Step 3: Display available rates to customer
+<div className="space-y-2">
+  <h3 className="font-medium">Select Shipping Method</h3>
+  {rates.map((rate) => (
+    <label key={rate.id} className="flex items-center gap-3 p-3 border rounded cursor-pointer">
+      <input
+        type="radio"
+        name="shipping"
+        value={rate.id}
+        checked={selectedRateId === rate.id}
+        onChange={() => setSelectedRateId(rate.id)}
+      />
+      <div className="flex-1">
+        <span className="font-medium">{rate.name}</span>
+        {rate.description && <p className="text-sm text-gray-500">{rate.description}</p>}
+        {rate.estimatedDays && (
+          <p className="text-sm text-gray-500">Estimated delivery: {rate.estimatedDays} business days</p>
+        )}
+      </div>
+      <span className="font-medium">${parseFloat(rate.price).toFixed(2)}</span>
+    </label>
+  ))}
+</div>;
+
+// Step 4: Select the shipping method
+await omni.selectShippingMethod(checkoutId, selectedRateId);
+```
+
+**Handling Empty Shipping Rates:**
+
+When no shipping rates are available, you have several options:
+
+```typescript
+// Option 1: Show helpful message
+if (rates.length === 0) {
+  return <NoShippingAvailable address={shippingAddress} />;
+}
+
+// Option 2: Allow customer to contact store
+if (rates.length === 0) {
+  return (
+    <div>
+      <p>Shipping not available to your location.</p>
+      <a href="/contact">Request a shipping quote</a>
+    </div>
+  );
+}
+
+// Option 3: Validate before proceeding
+function canProceedToPayment(checkout: Checkout, rates: ShippingRate[]): boolean {
+  if (rates.length === 0) return false;
+  if (!checkout.shippingRateId) return false;
+  if (!checkout.email) return false;
+  return true;
+}
+```
+
+---
+
+### Payment Integration (Vibe-Coded Sites)
+
+For vibe-coded sites, the SDK provides payment integration with Stripe and PayPal. The store owner configures their payment provider(s) in the admin, and your site uses these methods to process payments.
+
+#### ⚠️ Important: Getting a Valid Checkout ID
+
+Before creating a payment intent, you need a checkout ID. How you get it depends on the customer type:
+
+```typescript
+// For GUEST users (local cart in localStorage):
+const result = await omni.startGuestCheckout();
+const checkoutId = result.checkoutId;
+
+// For LOGGED-IN users (server cart):
+const checkout = await omni.createCheckout({ cartId: serverCartId });
+const checkoutId = checkout.id;
+
+// Then continue with shipping and payment...
+```
+
+#### Get All Payment Providers (Recommended)
+
+Use this method to get ALL enabled payment providers and build dynamic UI:
+
+```typescript
+const { hasPayments, providers, defaultProvider } = await omni.getPaymentProviders();
+
+// Returns:
+// {
+//   hasPayments: true,
+//   providers: [
+//     {
+//       id: 'provider_xxx',
+//       provider: 'stripe',
+//       name: 'Stripe',
+//       publicKey: 'pk_live_xxx...',
+//       supportedMethods: ['card', 'ideal'],
+//       testMode: false,
+//       isDefault: true
+//     },
+//     {
+//       id: 'provider_yyy',
+//       provider: 'paypal',
+//       name: 'PayPal',
+//       publicKey: 'client_id_xxx...',
+//       supportedMethods: ['paypal'],
+//       testMode: false,
+//       isDefault: false
+//     }
+//   ],
+//   defaultProvider: { ... }  // The default provider (first one)
+// }
+
+// Build dynamic UI based on available providers
+if (!hasPayments) {
+  return <div>Payment not configured for this store</div>;
+}
+
+const stripeProvider = providers.find(p => p.provider === 'stripe');
+const paypalProvider = providers.find(p => p.provider === 'paypal');
+
+// Show Stripe payment form if available
+if (stripeProvider) {
+  const stripe = await loadStripe(stripeProvider.publicKey);
+  // ... show Stripe Elements
+}
+
+// Show PayPal buttons if available
+if (paypalProvider) {
+  // ... show PayPal buttons with paypalProvider.publicKey as client-id
+}
+```
+
+#### Get Payment Configuration (Single Provider)
+
+If you only need the default provider, use this simpler method:
+
+```typescript
+const config = await omni.getPaymentConfig();
+
+// Returns:
+// {
+//   provider: 'stripe' | 'paypal',
+//   publicKey: 'pk_live_xxx...',  // Stripe publishable key or PayPal client ID
+//   supportedMethods: ['card', 'ideal', 'bancontact'],
+//   testMode: false
+// }
+```
+
+#### Create Payment Intent
+
+After the customer fills in shipping details, create a payment intent:
+
+```typescript
+const intent = await omni.createPaymentIntent(checkout.id);
+
+// Returns:
+// {
+//   id: 'pi_xxx...',
+//   clientSecret: 'pi_xxx_secret_xxx',  // Used by Stripe.js/PayPal SDK
+//   amount: 9999,  // In cents
+//   currency: 'USD',
+//   status: 'requires_payment_method'
+// }
+```
+
+#### Confirm Payment with Stripe.js
+
+Use the client secret with Stripe.js to collect payment:
+
+```typescript
+// Initialize Stripe.js with the public key from getPaymentConfig()
+const stripe = await loadStripe(config.publicKey);
+
+// Create Elements and Payment Element
+const elements = stripe.elements({ clientSecret: intent.clientSecret });
+const paymentElement = elements.create('payment');
+paymentElement.mount('#payment-element');
+
+// When customer submits payment
+const { error } = await stripe.confirmPayment({
+  elements,
+  confirmParams: {
+    return_url: `${window.location.origin}/checkout/success?checkout_id=${checkout.id}`,
+  },
+});
+
+if (error) {
+  console.error('Payment failed:', error.message);
+}
+```
+
+#### After Payment: Success Page Pattern (Recommended)
+
+**Important:** Orders are created asynchronously via webhook after Stripe confirms payment.
+This typically takes 1-5 seconds, but can vary. Follow these best practices:
+
+**Option 1: Optimistic Success Page (Recommended - Used by Amazon, Shopify, AliExpress)**
+
+Show success immediately without waiting for orderId. This is the industry standard:
+
+```typescript
+// In your payment form, after stripe.confirmPayment() succeeds:
+const { error } = await stripe.confirmPayment({
+  elements,
+  confirmParams: {
+    return_url: `${window.location.origin}/checkout/success?checkout_id=${checkout.id}`,
+  },
+});
+
+// On /checkout/success page - show confirmation IMMEDIATELY:
+export default function CheckoutSuccessPage() {
+  const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
+
+  return (
+    <div className="text-center py-12">
+      <h1 className="text-2xl font-bold text-green-600">Payment Received!</h1>
+      <p className="mt-4">Your order is being processed.</p>
+      <p className="mt-2 text-gray-600">
+        Confirmation #{checkoutId?.slice(-8).toUpperCase()}
+      </p>
+      <p className="mt-4">A confirmation email will be sent shortly.</p>
+      <a href="/orders" className="mt-6 inline-block text-blue-600">
+        View Your Orders →
+      </a>
+    </div>
+  );
+}
+```
+
+**Option 2: Wait for Order (For SPAs that need orderId)**
+
+Use `waitForOrder()` to poll in the background with exponential backoff:
+
+```typescript
+// After payment succeeds, wait for order creation (max 30 seconds)
+const result = await omni.waitForOrder(checkout.id, {
+  maxWaitMs: 30000, // 30 seconds max
+  onPollAttempt: (attempt, status) => {
+    console.log(`Checking order status... (attempt ${attempt})`);
+  },
+  onOrderReady: (status) => {
+    // Called immediately when order is created
+    console.log('Order ready:', status.orderNumber);
+  },
+});
+
+if (result.success) {
+  // Order was created within timeout
+  window.location.href = `/orders/${result.status.orderId}`;
+} else {
+  // Order not created yet - show optimistic success anyway
+  // The email will be sent when order is ready
+  showSuccessMessage('Payment received! Order confirmation coming soon.');
+}
+```
+
+**Option 3: Simple Status Check (Single poll)**
+
+For simple use cases where you just want to check once:
+
+```typescript
+const status = await omni.getPaymentStatus(checkout.id);
+
+// Returns:
+// {
+//   checkoutId: 'checkout_xxx',
+//   status: 'succeeded' | 'pending' | 'failed' | 'canceled',
+//   orderId: 'order_xxx',      // Only if order was created
+//   orderNumber: 'ORD-123',    // Only if order was created
+//   error: 'Payment declined'  // Only if payment failed
+// }
+
+if (status.status === 'succeeded' && status.orderId) {
+  window.location.href = `/order-confirmation/${status.orderId}`;
+} else if (status.status === 'succeeded') {
+  // Payment succeeded but order not created yet
+  showMessage('Payment received, processing your order...');
+} else if (status.status === 'failed') {
+  showError(status.error || 'Payment failed');
+}
+```
+
+> **Why Optimistic Success?** Stripe webhooks typically arrive within 1-5 seconds,
+> but network issues can cause delays. Major e-commerce platforms (Amazon, Shopify)
+> show success immediately and send order details via email. This provides better UX
+> than making customers wait on a loading screen.
+
+#### Complete Checkout with Payment Example
+
+> **Note:** This example assumes you already have a `checkout_id`. See below for how to create one.
+
+**How to get a checkout_id:**
+
+```typescript
+// For GUEST users (local cart):
+const result = await omni.startGuestCheckout();
+const checkoutId = result.checkoutId; // Use this!
+
+// For LOGGED-IN users (server cart):
+const checkout = await omni.createCheckout({ cartId: cart.id });
+const checkoutId = checkout.id; // Use this!
+```
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { loadStripe, Stripe, StripeElements } from '@stripe/stripe-js';
+import { Elements, PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js';
+import { omni } from '@/lib/brainerce';
+import type { Checkout, PaymentConfig, PaymentIntent } from 'brainerce';
+
+export default function CheckoutPaymentPage() {
+  const [checkout, setCheckout] = useState<Checkout | null>(null);
+  const [paymentConfig, setPaymentConfig] = useState<PaymentConfig | null>(null);
+  const [paymentIntent, setPaymentIntent] = useState<PaymentIntent | null>(null);
+  const [stripePromise, setStripePromise] = useState<Promise<Stripe | null> | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    async function initPayment() {
+      try {
+        // Get checkout_id from URL (set by previous step)
+        const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
+        if (!checkoutId) throw new Error('No checkout ID');
+
+        // Get payment configuration
+        const config = await omni.getPaymentConfig();
+        setPaymentConfig(config);
+
+        // Initialize Stripe
+        if (config.provider === 'stripe') {
+          setStripePromise(loadStripe(config.publicKey));
+        }
+
+        // Create payment intent
+        const intent = await omni.createPaymentIntent(checkoutId);
+        setPaymentIntent(intent);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to initialize payment');
+      } finally {
+        setLoading(false);
+      }
+    }
+    initPayment();
+  }, []);
+
+  if (loading) return <div>Loading payment...</div>;
+  if (error) return <div className="text-red-600">{error}</div>;
+  if (!paymentConfig || !paymentIntent || !stripePromise) return null;
+
+  return (
+    <div className="max-w-lg mx-auto p-6">
+      <h1 className="text-2xl font-bold mb-6">Payment</h1>
+
+      <Elements stripe={stripePromise} options={{ clientSecret: paymentIntent.clientSecret }}>
+        <PaymentForm checkoutId={paymentIntent.id} />
+      </Elements>
+    </div>
+  );
+}
+
+function PaymentForm({ checkoutId }: { checkoutId: string }) {
+  const stripe = useStripe();
+  const elements = useElements();
+  const [processing, setProcessing] = useState(false);
+  const [error, setError] = useState('');
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!stripe || !elements) return;
+
+    setProcessing(true);
+    setError('');
+
+    const { error } = await stripe.confirmPayment({
+      elements,
+      confirmParams: {
+        return_url: `${window.location.origin}/checkout/success?checkout_id=${checkoutId}`,
+      },
+    });
+
+    if (error) {
+      setError(error.message || 'Payment failed');
+      setProcessing(false);
+    }
+    // If successful, Stripe redirects to return_url
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <PaymentElement />
+
+      {error && <div className="text-red-600 mt-4">{error}</div>}
+
+      <button
+        type="submit"
+        disabled={!stripe || processing}
+        className="w-full mt-6 bg-green-600 text-white py-3 rounded disabled:opacity-50"
+      >
+        {processing ? 'Processing...' : 'Pay Now'}
+      </button>
+    </form>
+  );
+}
+```
+
+#### Complete Order After Payment: `completeGuestCheckout()`
+
+**CRITICAL:** After payment succeeds, you MUST call `completeGuestCheckout()` to create the order on the server and clear the cart.
+
+> **WARNING:** Do NOT use `handlePaymentSuccess()` - it only clears the local cart (localStorage)
+> and does NOT send the order to the server. Your customer will pay but no order will be created!
+
+```typescript
+// On your /checkout/success page:
+export default function CheckoutSuccessPage() {
+  const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
+
+  useEffect(() => {
+    if (checkoutId) {
+      // IMPORTANT: This sends the order to the server AND clears the cart
+      // completeGuestCheckout() returns GuestOrderResponse (has .orderNumber directly)
+      // This is different from waitForOrder() which returns WaitForOrderResult
+      // (access orderNumber via .status.orderNumber instead)
+      omni.completeGuestCheckout(checkoutId).then(result => {
+        console.log('Order created:', result.orderNumber);
+      }).catch(() => {
+        // Order may already exist (e.g., page refresh) - safe to ignore
+      });
+    }
+  }, []);
+
+  return (
+    <div className="text-center py-12">
+      <h1 className="text-2xl font-bold text-green-600">Payment Received!</h1>
+      {/* ... rest of success page */}
+    </div>
+  );
+}
+```
+
+**How it works:**
+| User Type | Cart Type | Behavior |
+|-----------|-----------|----------|
+| Guest (partial checkout) | Local cart | Creates order + removes only purchased items |
+| Guest (full checkout) | Local cart | Creates order + clears entire cart |
+| Logged-in | Server cart | Creates order + clears cart via SDK state |
+
+**Why is this needed?**
+
+- `completeGuestCheckout()` sends `POST /checkout/:id/complete` which creates the order on the server
+- Without it, payment goes through Stripe but no order is created in the system
+- The server also links the order to the customer (by email) so it appears in their order history
+- For partial checkout (AliExpress-style), only the purchased items are removed
+
+---
+
+### Customer Authentication
+
+#### Register Customer
+
+```typescript
+const auth = await omni.registerCustomer({
+  email: 'customer@example.com',
+  password: 'securepassword123',
+  firstName: 'John',
+  lastName: 'Doe',
+});
+
+// Check if email verification is required
+if (auth.requiresVerification) {
+  localStorage.setItem('verificationToken', auth.token);
+  window.location.href = '/verify-email';
+} else {
+  setCustomerToken(auth.token);
+  // Redirect back to store, not /account
+  window.location.href = '/';
+}
+```
+
+#### Login Customer
+
+```typescript
+const auth = await omni.loginCustomer('customer@example.com', 'password123');
+setCustomerToken(auth.token);
+
+// Best practice: redirect back to previous page or home
+const returnUrl = localStorage.getItem('returnUrl') || '/';
+localStorage.removeItem('returnUrl');
+window.location.href = returnUrl;
+```
+
+> **Best Practice:** Before showing login page, save the current URL with `localStorage.setItem('returnUrl', window.location.pathname)`. After login, redirect back to that URL. This is how Amazon, Shopify, and most e-commerce sites work.
+
+#### Logout Customer
+
+```typescript
+setCustomerToken(null);
+window.location.href = '/'; // Return to store home
+```
+
+#### Get Customer Profile
+
+```typescript
+restoreCustomerToken(); // Restore from localStorage
+const profile = await omni.getMyProfile();
+
+console.log(profile.firstName);
+console.log(profile.email);
+console.log(profile.addresses);
+```
+
+#### Get Customer Orders
+
+```typescript
+const { data: orders, meta } = await omni.getMyOrders({
+  page: 1,
+  limit: 10,
+});
+```
+
+#### Auth Response Type
+
+```typescript
+interface CustomerAuthResponse {
+  customer: {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    emailVerified: boolean;
+  };
+  token: string;
+  expiresAt: string;
+  requiresVerification?: boolean; // true if email verification is required
+}
+```
+
+---
+
+### Email Verification
+
+If the store has **email verification enabled**, customers must verify their email after registration before they can fully use their account.
+
+#### Registration with Email Verification
+
+When `requiresVerification` is true in the registration response, the customer needs to verify their email:
+
+```typescript
+const auth = await omni.registerCustomer({
+  email: 'customer@example.com',
+  password: 'securepassword123',
+  firstName: 'John',
+});
+
+if (auth.requiresVerification) {
+  // Save token for verification step
+  localStorage.setItem('verificationToken', auth.token);
+  // Redirect to verification page
+  window.location.href = '/verify-email';
+} else {
+  // No verification needed - redirect back to store
+  setCustomerToken(auth.token);
+  window.location.href = '/';
+}
+```
+
+#### Verify Email with Code
+
+After the customer receives the 6-digit code via email:
+
+```typescript
+// Get the token saved from registration
+const token = localStorage.getItem('verificationToken');
+
+// Verify email - pass the token directly (no need to call setCustomerToken first!)
+const result = await omni.verifyEmail(code, token);
+
+if (result.verified) {
+  // Email verified! Now set the token for normal use
+  setCustomerToken(token);
+  localStorage.removeItem('verificationToken');
+  // Redirect back to store (or returnUrl if saved)
+  const returnUrl = localStorage.getItem('returnUrl') || '/';
+  localStorage.removeItem('returnUrl');
+  window.location.href = returnUrl;
+}
+```
+
+#### Resend Verification Email
+
+If the customer didn't receive the email or the code expired:
+
+```typescript
+const token = localStorage.getItem('verificationToken');
+await omni.resendVerificationEmail(token);
+// Show success message - new code sent
+```
+
+> **Note:** Resend is rate-limited to 3 requests per hour.
+
+#### Complete Email Verification Page Example
+
+```typescript
+'use client';
+import { useState } from 'react';
+import { omni, setCustomerToken } from '@/lib/brainerce';
+import { toast } from 'sonner';
+
+export default function VerifyEmailPage() {
+  const [code, setCode] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  const handleVerify = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+
+    try {
+      const token = localStorage.getItem('verificationToken');
+      if (!token) {
+        toast.error('No verification token found. Please register again.');
+        return;
+      }
+
+      const result = await omni.verifyEmail(code, token);
+
+      if (result.verified) {
+        toast.success('Email verified!');
+        setCustomerToken(token);
+        localStorage.removeItem('verificationToken');
+        // Redirect back to store
+        const returnUrl = localStorage.getItem('returnUrl') || '/';
+        localStorage.removeItem('returnUrl');
+        window.location.href = returnUrl;
+      }
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : 'Verification failed');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleResend = async () => {
+    try {
+      const token = localStorage.getItem('verificationToken');
+      if (!token) {
+        toast.error('No verification token found');
+        return;
+      }
+      await omni.resendVerificationEmail(token);
+      toast.success('Verification code sent!');
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : 'Failed to resend');
+    }
+  };
+
+  return (
+    <div className="max-w-md mx-auto mt-12">
+      <h1 className="text-2xl font-bold mb-4">Verify Your Email</h1>
+      <p className="text-gray-600 mb-6">
+        We sent a 6-digit code to your email. Enter it below to verify your account.
+      </p>
+
+      <form onSubmit={handleVerify} className="space-y-4">
+        <input
+          type="text"
+          placeholder="Enter 6-digit code"
+          value={code}
+          onChange={(e) => setCode(e.target.value)}
+          maxLength={6}
+          className="w-full border p-3 rounded text-center text-2xl tracking-widest"
+          required
+        />
+        <button
+          type="submit"
+          disabled={loading || code.length !== 6}
+          className="w-full bg-black text-white py-3 rounded disabled:opacity-50"
+        >
+          {loading ? 'Verifying...' : 'Verify Email'}
+        </button>
+      </form>
+
+      <button onClick={handleResend} className="mt-4 text-blue-600 text-sm">
+        Didn't receive the code? Resend
+      </button>
+    </div>
+  );
+}
+```
+
+---
+
+### Social Login (OAuth)
+
+Allow customers to sign in with Google, Facebook, or GitHub. The store owner configures which providers are available in their Brainerce admin panel.
+
+#### Check Available Providers
+
+```typescript
+// Returns only the providers the store owner has enabled
+const { providers } = await omni.getAvailableOAuthProviders();
+// providers = ['GOOGLE', 'FACEBOOK'] - varies by store configuration
+```
+
+#### OAuth Login Flow
+
+**Step 1: User clicks "Sign in with Google"**
+
+```typescript
+// Save cart ID before redirect (user will leave your site!)
+const cartId = localStorage.getItem('cartId');
+if (cartId) sessionStorage.setItem('pendingCartId', cartId);
+
+// Get authorization URL
+const { authorizationUrl, state } = await omni.getOAuthAuthorizeUrl('GOOGLE', {
+  redirectUrl: window.location.origin + '/auth/callback', // Where Google sends them back
+});
+
+// Save state for verification (CSRF protection)
+sessionStorage.setItem('oauthState', state);
+
+// Redirect to Google
+window.location.href = authorizationUrl;
+```
+
+**Step 2: Create callback page (`/auth/callback`)**
+
+```typescript
+// pages/auth/callback.tsx or app/auth/callback/page.tsx
+'use client';
+import { useEffect, useState } from 'react';
+import { useSearchParams } from 'next/navigation';
+import { omni, setCustomerToken } from '@/lib/brainerce';
+
+export default function AuthCallback() {
+  const searchParams = useSearchParams();
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function handleCallback() {
+      const code = searchParams.get('code');
+      const state = searchParams.get('state');
+      const errorParam = searchParams.get('error');
+
+      // Check for OAuth errors (user cancelled, etc.)
+      if (errorParam) {
+        window.location.href = '/login?error=cancelled';
+        return;
+      }
+
+      if (!code || !state) {
+        setError('Missing OAuth parameters');
+        return;
+      }
+
+      // Verify state matches (CSRF protection)
+      const savedState = sessionStorage.getItem('oauthState');
+      if (state !== savedState) {
+        setError('Invalid state - please try again');
+        return;
+      }
+
+      try {
+        // Exchange code for customer token
+        const { customer, token, isNewCustomer } = await omni.handleOAuthCallback(
+          'GOOGLE',
+          code,
+          state
+        );
+
+        // Save the customer token
+        setCustomerToken(token);
+        sessionStorage.removeItem('oauthState');
+
+        // Link any pending cart to the now-logged-in customer
+        const pendingCartId = sessionStorage.getItem('pendingCartId');
+        if (pendingCartId) {
+          try {
+            await omni.linkCart(pendingCartId);
+          } catch {
+            // Cart may have expired - that's ok
+          }
+          sessionStorage.removeItem('pendingCartId');
+        }
+
+        // Redirect to return URL or home
+        const returnUrl = localStorage.getItem('returnUrl') || '/';
+        localStorage.removeItem('returnUrl');
+        window.location.href = returnUrl;
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Login failed');
+      }
+    }
+
+    handleCallback();
+  }, [searchParams]);
+
+  if (error) {
+    return (
+      <div className="max-w-md mx-auto mt-12 text-center">
+        <h1 className="text-xl font-bold text-red-600">Login Failed</h1>
+        <p className="mt-2 text-gray-600">{error}</p>
+        <a href="/login" className="mt-4 inline-block text-blue-600">
+          Try again
+        </a>
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-md mx-auto mt-12 text-center">
+      <div className="animate-spin h-8 w-8 border-4 border-blue-600 border-t-transparent rounded-full mx-auto"></div>
+      <p className="mt-4 text-gray-600">Completing login...</p>
+    </div>
+  );
+}
+```
+
+#### Login Page with Social Buttons
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { omni, setCustomerToken } from '@/lib/brainerce';
+
+export default function LoginPage() {
+  const [providers, setProviders] = useState<string[]>([]);
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+
+  // Load available OAuth providers
+  useEffect(() => {
+    omni.getAvailableOAuthProviders()
+      .then(({ providers }) => setProviders(providers))
+      .catch(() => {}); // OAuth not configured - that's ok
+  }, []);
+
+  // Social login handler
+  const handleSocialLogin = async (provider: string) => {
+    try {
+      // Save cart ID before redirect
+      const cartId = localStorage.getItem('cartId');
+      if (cartId) sessionStorage.setItem('pendingCartId', cartId);
+
+      const { authorizationUrl, state } = await omni.getOAuthAuthorizeUrl(
+        provider as 'GOOGLE' | 'FACEBOOK' | 'GITHUB',
+        { redirectUrl: window.location.origin + '/auth/callback' }
+      );
+
+      sessionStorage.setItem('oauthState', state);
+      window.location.href = authorizationUrl;
+    } catch (err) {
+      setError('Failed to start login');
+    }
+  };
+
+  // Regular email/password login
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    setError('');
+    try {
+      const auth = await omni.loginCustomer(email, password);
+      setCustomerToken(auth.token);
+      const returnUrl = localStorage.getItem('returnUrl') || '/';
+      localStorage.removeItem('returnUrl');
+      window.location.href = returnUrl;
+    } catch (err) {
+      setError('Invalid email or password');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="max-w-md mx-auto mt-12">
+      <h1 className="text-2xl font-bold mb-6">Login</h1>
+
+      {/* Social Login Buttons */}
+      {providers.length > 0 && (
+        <div className="space-y-3 mb-6">
+          {providers.includes('GOOGLE') && (
+            <button
+              onClick={() => handleSocialLogin('GOOGLE')}
+              className="w-full flex items-center justify-center gap-2 border py-3 rounded hover:bg-gray-50"
+            >
+              <GoogleIcon />
+              Continue with Google
+            </button>
+          )}
+          {providers.includes('FACEBOOK') && (
+            <button
+              onClick={() => handleSocialLogin('FACEBOOK')}
+              className="w-full flex items-center justify-center gap-2 bg-[#1877F2] text-white py-3 rounded"
+            >
+              <FacebookIcon />
+              Continue with Facebook
+            </button>
+          )}
+          {providers.includes('GITHUB') && (
+            <button
+              onClick={() => handleSocialLogin('GITHUB')}
+              className="w-full flex items-center justify-center gap-2 bg-[#24292F] text-white py-3 rounded"
+            >
+              <GithubIcon />
+              Continue with GitHub
+            </button>
+          )}
+          <div className="relative my-4">
+            <div className="absolute inset-0 flex items-center">
+              <div className="w-full border-t" />
+            </div>
+            <div className="relative flex justify-center text-sm">
+              <span className="px-2 bg-white text-gray-500">or</span>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Email/Password Form */}
+      {error && <div className="bg-red-100 text-red-600 p-3 rounded mb-4">{error}</div>}
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <input
+          type="email"
+          placeholder="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          required
+          className="w-full border p-2 rounded"
+        />
+        <input
+          type="password"
+          placeholder="Password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          required
+          className="w-full border p-2 rounded"
+        />
+        <button
+          type="submit"
+          disabled={loading}
+          className="w-full bg-black text-white py-3 rounded"
+        >
+          {loading ? 'Logging in...' : 'Login'}
+        </button>
+      </form>
+
+      <p className="mt-4 text-center">
+        Don't have an account? <a href="/register" className="text-blue-600">Register</a>
+      </p>
+    </div>
+  );
+}
+
+// Simple SVG icons (or use lucide-react)
+const GoogleIcon = () => (
+  <svg className="w-5 h-5" viewBox="0 0 24 24">
+    <path fill="#4285F4" d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"/>
+    <path fill="#34A853" d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"/>
+    <path fill="#FBBC05" d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"/>
+    <path fill="#EA4335" d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"/>
+  </svg>
+);
+
+const FacebookIcon = () => (
+  <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+    <path d="M24 12.073c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.99 4.388 10.954 10.125 11.854v-8.385H7.078v-3.47h3.047V9.43c0-3.007 1.792-4.669 4.533-4.669 1.312 0 2.686.235 2.686.235v2.953H15.83c-1.491 0-1.956.925-1.956 1.874v2.25h3.328l-.532 3.47h-2.796v8.385C19.612 23.027 24 18.062 24 12.073z"/>
+  </svg>
+);
+
+const GithubIcon = () => (
+  <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+    <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/>
+  </svg>
+);
+```
+
+#### Account Linking (Add Social Account to Existing User)
+
+Logged-in customers can link additional social accounts to their profile:
+
+```typescript
+// Get currently linked accounts
+const connections = await omni.getOAuthConnections();
+// [{ provider: 'GOOGLE', email: 'user@gmail.com', linkedAt: '...' }]
+
+// Link a new provider (redirects to OAuth flow)
+const { authorizationUrl } = await omni.linkOAuthProvider('GITHUB');
+window.location.href = authorizationUrl;
+
+// Unlink a provider
+await omni.unlinkOAuthProvider('GOOGLE');
+```
+
+#### Cart Linking After OAuth Login
+
+When a customer logs in via OAuth, their guest cart should be linked to their account:
+
+```typescript
+// omni.linkCart() associates a guest cart with the logged-in customer
+await omni.linkCart(cartId);
+```
+
+This is automatically handled in the callback example above.
+
+#### OAuth Method Reference
+
+| Method                                       | Description                                  |
+| -------------------------------------------- | -------------------------------------------- |
+| `getAvailableOAuthProviders()`               | Get list of enabled providers for this store |
+| `getOAuthAuthorizeUrl(provider, options?)`   | Get URL to redirect user to OAuth provider   |
+| `handleOAuthCallback(provider, code, state)` | Exchange OAuth code for customer token       |
+| `linkOAuthProvider(provider)`                | Link social account to current customer      |
+| `unlinkOAuthProvider(provider)`              | Remove linked social account                 |
+| `getOAuthConnections()`                      | Get list of linked social accounts           |
+| `linkCart(cartId)`                           | Link guest cart to logged-in customer        |
+
+---
+
+### Customer Addresses
+
+#### Get Addresses
+
+```typescript
+const addresses = await omni.getMyAddresses();
+```
+
+#### Add Address
+
+```typescript
+const address = await omni.addMyAddress({
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  city: 'New York',
+  region: 'NY',
+  postalCode: '10001',
+  country: 'US',
+  isDefault: true,
+});
+```
+
+#### Update Address
+
+```typescript
+const updated = await omni.updateMyAddress(addressId, {
+  line1: '456 New Street',
+});
+```
+
+#### Delete Address
+
+```typescript
+await omni.deleteMyAddress(addressId);
+```
+
+---
+
+### Store Info
+
+```typescript
+const store = await omni.getStoreInfo();
+
+console.log(store.name); // Store name
+console.log(store.currency); // 'USD', 'ILS', etc.
+console.log(store.language); // 'en', 'he', etc.
+```
+
+---
+
+## Admin API Reference
+
+The Admin API requires an API key (`apiKey`) and provides full access to store configuration and management features.
+
+```typescript
+// Initialize in Admin mode
+const omni = new BrainerceClient({
+  apiKey: process.env.OMNI_API_KEY, // 'omni_*' prefix
+});
+```
+
+### Taxonomy Management
+
+```typescript
+// Categories
+const categories = await omni.listCategories({ page: 1, limit: 20 });
+const category = await omni.getCategory('cat_id');
+const newCategory = await omni.createCategory({ name: 'Electronics', slug: 'electronics' });
+await omni.updateCategory('cat_id', { name: 'Updated Name' });
+await omni.deleteCategory('cat_id');
+
+// Brands
+const brands = await omni.listBrands();
+const brand = await omni.createBrand({ name: 'Nike', slug: 'nike' });
+
+// Tags
+const tags = await omni.listTags();
+const tag = await omni.createTag({ name: 'Sale', slug: 'sale' });
+
+// Attributes (for variant options)
+const attributes = await omni.listAttributes();
+const attribute = await omni.createAttribute({ name: 'Color', slug: 'color' });
+const options = await omni.getAttributeOptions('attr_id');
+await omni.createAttributeOption('attr_id', { value: 'Red', slug: 'red' });
+```
+
+### Shipping Configuration
+
+```typescript
+// Shipping Zones
+const zones = await omni.listShippingZones();
+const zone = await omni.createShippingZone({
+  name: 'US Domestic',
+  countries: ['US'],
+});
+
+// Shipping Rates
+const rates = await omni.getZoneShippingRates('zone_id');
+await omni.createZoneShippingRate('zone_id', {
+  name: 'Standard Shipping',
+  type: 'flat',
+  price: 5.99,
+  estimatedDays: '3-5',
+});
+```
+
+### Tax Configuration
+
+```typescript
+const rates = await omni.getTaxRates();
+await omni.createTaxRate({
+  name: 'CA Sales Tax',
+  rate: 7.25,
+  country: 'US',
+  region: 'CA',
+});
+```
+
+### Metafield Definitions
+
+```typescript
+// Define custom fields
+const definitions = await omni.getMetafieldDefinitions();
+await omni.createMetafieldDefinition({
+  name: 'Care Instructions',
+  key: 'care_instructions',
+  type: 'multi_line_text',
+});
+
+// Set values on products
+await omni.setProductMetafield('prod_id', 'def_id', {
+  value: 'Machine wash cold',
+});
+```
+
+### Store Team Management
+
+Each store has its own team with roles (`OWNER`, `MANAGER`, `STAFF`, `VIEWER`) and granular permissions.
+
+```typescript
+// List team members + pending invitations for a store
+const { members, invitations } = await omni.getStoreTeam('store_id');
+
+// Invite a new member
+const invitation = await omni.inviteStoreMember('store_id', {
+  email: 'newmember@example.com',
+  role: 'MANAGER', // 'MANAGER' | 'STAFF' | 'VIEWER'
+});
+
+// Update member role or set custom permissions
+await omni.updateStoreMember('store_id', 'member_id', { role: 'STAFF' });
+await omni.updateStoreMember('store_id', 'member_id', {
+  permissions: ['VIEW_PRODUCTS', 'VIEW_ORDERS', 'FULFILL_ORDERS'], // overrides role defaults
+});
+
+// Remove a member
+await omni.removeStoreMember('store_id', 'member_id');
+
+// Manage invitations
+await omni.resendStoreInvitation('store_id', 'inv_id');
+await omni.revokeStoreInvitation('store_id', 'inv_id');
+
+// Get all stores accessible to the current user (owned + shared)
+const stores = await omni.getMyStores();
+// [{ id, name, role: 'OWNER', context: 'owner' }, { id, name, role: 'MANAGER', context: 'member' }]
+
+// Get user's permissions for a specific store
+const { role, permissions } = await omni.getMyStorePermissions('store_id');
+```
+
+> **Note:** The previous account-level team methods (`getTeamMembers`, `inviteTeamMember`, etc.) are deprecated. Use the store-level methods above instead.
+
+### Email Settings & Templates
+
+```typescript
+// Get/update settings
+const settings = await omni.getEmailSettings();
+await omni.updateEmailSettings({
+  emailsEnabled: true,
+  defaultFromName: 'My Store',
+  eventSettings: {
+    ORDER_CONFIRMATION: { enabled: true, sendToCustomer: true },
+  },
+});
+
+// Manage templates
+const templates = await omni.getEmailTemplates();
+await omni.createEmailTemplate({
+  name: 'Order Confirmation',
+  eventType: 'ORDER_CONFIRMATION',
+  subject: 'Your order #{{orderNumber}}',
+  htmlContent: '<h1>Thank you!</h1>...',
+});
+
+// Preview template
+const preview = await omni.previewEmailTemplate('template_id', {
+  variables: { orderNumber: '1001' },
+});
+```
+
+### Sync Conflict Resolution
+
+```typescript
+// Product sync conflicts
+const conflicts = await omni.getSyncConflicts();
+await omni.resolveSyncConflict('conflict_id', 'MERGE'); // or 'CREATE_NEW'
+
+// Metafield conflicts
+const metafieldConflicts = await omni.getMetafieldConflicts();
+await omni.resolveMetafieldConflict('conflict_id', {
+  resolution: 'USE_INCOMING', // 'KEEP_EXISTING' | 'USE_INCOMING' | 'MERGE'
+});
+await omni.ignoreMetafieldConflict('conflict_id');
+```
+
+### OAuth Provider Configuration
+
+```typescript
+// Configure social login for customers
+const providers = await omni.getOAuthProviders();
+await omni.configureOAuthProvider({
+  provider: 'GOOGLE',
+  clientId: 'your-google-client-id',
+  clientSecret: 'your-google-client-secret',
+  isEnabled: true,
+});
+await omni.updateOAuthProvider('GOOGLE', { isEnabled: false });
+await omni.deleteOAuthProvider('GOOGLE');
+```
+
+---
+
+## Complete Page Examples
+
+### Home Page
+
+```typescript
+'use client';
+import { useEffect, useState } from 'react';
+import { omni } from '@/lib/brainerce';
+import type { Product } from 'brainerce';
+
+export default function HomePage() {
+  const [products, setProducts] = useState<Product[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function loadProducts() {
+      try {
+        const { data } = await omni.getProducts({ limit: 8 });
+        setProducts(data);
+      } catch (err) {
+        setError('Failed to load products');
+      } finally {
+        setLoading(false);
+      }
+    }
+    loadProducts();
+  }, []);
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>{error}</div>;
+
+  return (
+    <div className="grid grid-cols-2 md:grid-cols-4 gap-6">
+      {products.map((product) => (
+        <a key={product.id} href={`/products/${product.slug}`} className="group">
+          <img
+            src={product.images?.[0]?.url || '/placeholder.jpg'}
+            alt={product.name}
+            className="w-full aspect-square object-cover"
+          />
+          <h3 className="mt-2 font-medium">{product.name}</h3>
+          <p className="text-lg">
+            {product.salePrice ? (
+              <>
+                <span className="text-red-600">${product.salePrice}</span>
+                <span className="line-through text-gray-400 ml-2">${product.basePrice}</span>
+              </>
+            ) : (
+              <span>${product.basePrice}</span>
+            )}
+          </p>
+        </a>
+      ))}
+    </div>
+  );
+}
+```
+
+### Products List with Pagination
+
+```typescript
+'use client';
+import { useEffect, useState } from 'react';
+import { omni } from '@/lib/brainerce';
+import type { Product, PaginatedResponse } from 'brainerce';
+
+export default function ProductsPage() {
+  const [data, setData] = useState<PaginatedResponse<Product> | null>(null);
+  const [page, setPage] = useState(1);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    async function load() {
+      setLoading(true);
+      try {
+        const result = await omni.getProducts({ page, limit: 12 });
+        setData(result);
+      } finally {
+        setLoading(false);
+      }
+    }
+    load();
+  }, [page]);
+
+  if (loading) return <div>Loading...</div>;
+  if (!data) return <div>No products found</div>;
+
+  return (
+    <div>
+      <div className="grid grid-cols-3 gap-6">
+        {data.data.map((product) => (
+          <a key={product.id} href={`/products/${product.slug}`}>
+            <img src={product.images?.[0]?.url} alt={product.name} />
+            <h3>{product.name}</h3>
+            <p>${product.salePrice || product.basePrice}</p>
+          </a>
+        ))}
+      </div>
+
+      {/* Pagination */}
+      <div className="flex gap-2 mt-8">
+        <button onClick={() => setPage(p => Math.max(1, p - 1))} disabled={page === 1}>
+          Previous
+        </button>
+        <span>Page {data.meta.page} of {data.meta.totalPages}</span>
+        <button onClick={() => setPage(p => p + 1)} disabled={page >= data.meta.totalPages}>
+          Next
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Product Detail with Add to Cart (Local Cart)
+
+```typescript
+'use client';
+import { useEffect, useState } from 'react';
+import { omni } from '@/lib/brainerce';
+import { isHtmlDescription, getVariantPrice, getVariantOptions, formatPrice } from 'brainerce';
+import type { Product, ProductVariant, StoreInfo } from 'brainerce';
+
+// Route: /products/[slug]/page.tsx - uses URL-friendly slug instead of ID
+export default function ProductPage({ params }: { params: { slug: string } }) {
+  const [product, setProduct] = useState<Product | null>(null);
+  const [selectedVariant, setSelectedVariant] = useState<ProductVariant | null>(null);
+  const [storeInfo, setStoreInfo] = useState<StoreInfo | null>(null);
+  const [quantity, setQuantity] = useState(1);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    async function load() {
+      try {
+        const [p, info] = await Promise.all([
+          omni.getProductBySlug(params.slug),
+          omni.getStoreInfo(),
+        ]);
+        setProduct(p);
+        setStoreInfo(info);
+        // Auto-select first variant for VARIABLE products
+        if (p.type === 'VARIABLE' && p.variants && p.variants.length > 0) {
+          setSelectedVariant(p.variants[0]);
+        }
+      } finally {
+        setLoading(false);
+      }
+    }
+    load();
+  }, [params.slug]);
+
+  // Get the image to display (variant image takes priority)
+  const getDisplayImage = () => {
+    // Use variant-specific image if available
+    if (selectedVariant?.image) {
+      const img = selectedVariant.image;
+      return typeof img === 'string' ? img : img.url;
+    }
+    // Fall back to product's main image
+    return product?.images?.[0]?.url || '/placeholder.jpg';
+  };
+
+  // Get the price to display (variant price takes priority)
+  const getDisplayPrice = () => {
+    if (!product) return '0';
+    if (selectedVariant) {
+      return getVariantPrice(selectedVariant, product.basePrice).toString();
+    }
+    return product.salePrice || product.basePrice;
+  };
+
+  const handleAddToCart = () => {
+    if (!product) return;
+
+    // Add to local cart (NO API call!)
+    omni.addToLocalCart({
+      productId: product.id,
+      variantId: selectedVariant?.id,
+      quantity,
+      name: selectedVariant?.name
+        ? `${product.name} - ${selectedVariant.name}`
+        : product.name,
+      price: getDisplayPrice(),
+      image: getDisplayImage(),
+    });
+
+    alert('Added to cart!');
+  };
+
+  if (loading) return <div>Loading...</div>;
+  if (!product) return <div>Product not found</div>;
+
+  return (
+    <div className="grid grid-cols-2 gap-8">
+      {/* Images - updates when variant changes */}
+      <div>
+        <img
+          src={getDisplayImage()}
+          alt={product.name}
+          className="w-full"
+        />
+      </div>
+
+      {/* Details */}
+      <div>
+        <h1 className="text-3xl font-bold">{product.name}</h1>
+        {/* Price updates based on selected variant */}
+        <p className="text-2xl mt-4">
+          {formatPrice(getDisplayPrice(), { currency: storeInfo?.currency || 'USD' })}
+        </p>
+
+        {/* IMPORTANT: Use isHtmlDescription() to render HTML descriptions correctly */}
+        {product.description && (
+          isHtmlDescription(product) ? (
+            <div className="mt-4 text-gray-600" dangerouslySetInnerHTML={{ __html: product.description }} />
+          ) : (
+            <p className="mt-4 text-gray-600">{product.description}</p>
+          )
+        )}
+
+        {/* Variant Selection - shows attribute-based buttons */}
+        {product.type === 'VARIABLE' && product.variants && product.variants.length > 0 && (
+          <div className="mt-6">
+            {/* Extract unique attribute names from all variants */}
+            {(() => {
+              const allOptions = product.variants.map(v => getVariantOptions(v));
+              const attributeNames = [...new Set(allOptions.flatMap(opts => opts.map(o => o.name)))];
+
+              return attributeNames.map(attrName => {
+                const uniqueValues = [...new Set(
+                  allOptions.flatMap(opts => opts.filter(o => o.name === attrName).map(o => o.value))
+                )];
+                const currentValue = getVariantOptions(selectedVariant).find(o => o.name === attrName)?.value;
+
+                return (
+                  <div key={attrName} className="mb-4">
+                    <label className="block font-medium mb-2">
+                      {attrName}: {currentValue}
+                    </label>
+                    <div className="flex gap-2">
+                      {uniqueValues.map(value => (
+                        <button
+                          key={value}
+                          onClick={() => {
+                            // Find variant matching the selected attribute value
+                            const match = product.variants?.find(v => {
+                              const opts = getVariantOptions(v);
+                              return opts.some(o => o.name === attrName && o.value === value);
+                            });
+                            if (match) setSelectedVariant(match);
+                          }}
+                          className={`px-4 py-2 border rounded ${
+                            currentValue === value
+                              ? 'bg-black text-white border-black'
+                              : 'bg-white text-black border-gray-300 hover:border-black'
+                          }`}
+                        >
+                          {value}
+                        </button>
+                      ))}
+                    </div>
+                  </div>
+                );
+              });
+            })()}
+          </div>
+        )}
+
+        {/* Quantity */}
+        <div className="mt-4">
+          <label className="block font-medium mb-2">Quantity</label>
+          <input
+            type="number"
+            min="1"
+            value={quantity}
+            onChange={(e) => setQuantity(Number(e.target.value))}
+            className="border rounded p-2 w-20"
+          />
+        </div>
+
+        {/* Add to Cart Button */}
+        <button
+          onClick={handleAddToCart}
+          disabled={adding}
+          className="mt-6 w-full bg-black text-white py-3 rounded disabled:opacity-50"
+        >
+          {adding ? 'Adding...' : 'Add to Cart'}
+        </button>
+
+        {/* Stock Status - use inStock which handles UNLIMITED variants */}
+        {product.inventory && (
+          <p className="mt-4 text-sm">
+            {product.inventory.inStock
+              ? (product.inventory.trackingMode === 'UNLIMITED'
+                  ? 'In Stock'
+                  : `${product.inventory.available} in stock`)
+              : 'Out of stock'}
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### Cart Page (Local Cart)
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { omni } from '@/lib/brainerce';
+import type { LocalCart } from 'brainerce';
+
+export default function CartPage() {
+  // ⚠️ Do NOT use useState(omni.getLocalCart()) — causes hydration mismatch!
+  // Server has no localStorage (empty cart) but client does (cart with items).
+  const [cart, setCart] = useState<LocalCart>({ items: [], updatedAt: '' });
+
+  useEffect(() => {
+    setCart(omni.getLocalCart());
+  }, []);
+
+  const updateQuantity = (productId: string, quantity: number, variantId?: string) => {
+    const updated = omni.updateLocalCartItem(productId, quantity, variantId);
+    setCart(updated);
+  };
+
+  const removeItem = (productId: string, variantId?: string) => {
+    const updated = omni.removeFromLocalCart(productId, variantId);
+    setCart(updated);
+  };
+
+  // Calculate subtotal from local cart
+  const subtotal = cart.items.reduce((sum, item) => {
+    return sum + (parseFloat(item.price || '0') * item.quantity);
+  }, 0);
+
+  if (cart.items.length === 0) {
+    return (
+      <div className="text-center py-12">
+        <h1 className="text-2xl font-bold">Your cart is empty</h1>
+        <a href="/products" className="text-blue-600 mt-4 inline-block">Continue Shopping</a>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      <h1 className="text-2xl font-bold mb-6">Shopping Cart</h1>
+
+      {cart.items.map((item) => (
+        <div key={`${item.productId}-${item.variantId || ''}`} className="flex items-center gap-4 py-4 border-b">
+          <img
+            src={item.image || '/placeholder.jpg'}
+            alt={item.name || 'Product'}
+            className="w-20 h-20 object-cover"
+          />
+          <div className="flex-1">
+            <h3 className="font-medium">{item.name || 'Product'}</h3>
+            <p className="font-bold">${item.price}</p>
+          </div>
+          <div className="flex items-center gap-2">
+            <button
+              onClick={() => updateQuantity(item.productId, item.quantity - 1, item.variantId)}
+              className="w-8 h-8 border rounded"
+            >-</button>
+            <span className="w-8 text-center">{item.quantity}</span>
+            <button
+              onClick={() => updateQuantity(item.productId, item.quantity + 1, item.variantId)}
+              className="w-8 h-8 border rounded"
+            >+</button>
+          </div>
+          <button
+            onClick={() => removeItem(item.productId, item.variantId)}
+            className="text-red-600"
+          >Remove</button>
+        </div>
+      ))}
+
+      <div className="mt-6 text-right">
+        <p className="text-xl">Subtotal: <strong>${subtotal.toFixed(2)}</strong></p>
+        {cart.couponCode && (
+          <p className="text-green-600">Coupon applied: {cart.couponCode}</p>
+        )}
+        <a
+          href="/checkout"
+          className="mt-4 inline-block bg-black text-white px-8 py-3 rounded"
+        >
+          Proceed to Checkout
+        </a>
+      </div>
+    </div>
+  );
+}
+```
+
+### Universal Checkout (Handles Both Guest & Logged-In)
+
+> **RECOMMENDED:** Use this pattern to properly handle both guest and logged-in customers in a single checkout page.
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { omni, isLoggedIn, getServerCartId, setServerCartId, restoreCustomerToken } from '@/lib/brainerce';
+
+export default function CheckoutPage() {
+  const [loading, setLoading] = useState(true);
+  const [submitting, setSubmitting] = useState(false);
+  const [customerLoggedIn, setCustomerLoggedIn] = useState(false);
+
+  // Form state
+  const [email, setEmail] = useState('');
+  const [shippingAddress, setShippingAddress] = useState({
+    firstName: '', lastName: '', line1: '', city: '', postalCode: '', country: 'US'
+  });
+
+  // Server checkout state (for logged-in customers)
+  const [checkoutId, setCheckoutId] = useState<string | null>(null);
+  const [shippingRates, setShippingRates] = useState<any[]>([]);
+  const [selectedRate, setSelectedRate] = useState<string | null>(null);
+
+  useEffect(() => {
+    restoreCustomerToken();
+    const loggedIn = isLoggedIn();
+    setCustomerLoggedIn(loggedIn);
+
+    async function initCheckout() {
+      if (loggedIn) {
+        // Logged-in customer: Create server cart + checkout
+        let cartId = getServerCartId();
+
+        if (!cartId) {
+          // Create new cart (auto-linked to customer)
+          const cart = await omni.createCart();
+          cartId = cart.id;
+          setServerCartId(cartId);
+
+          // Migrate local cart items to server cart
+          const localCart = omni.getLocalCart();
+          for (const item of localCart.items) {
+            await omni.addToCart(cartId, {
+              productId: item.productId,
+              variantId: item.variantId,
+              quantity: item.quantity,
+            });
+          }
+          omni.clearLocalCart(); // Clear local cart after migration
+        }
+
+        // Create checkout from server cart
+        const checkout = await omni.createCheckout({ cartId });
+        setCheckoutId(checkout.id);
+
+        // Pre-fill from customer profile if available
+        try {
+          const profile = await omni.getMyOrders({ limit: 1 }); // Just to check auth works
+        } catch (e) {
+          console.log('Could not fetch profile');
+        }
+      }
+      setLoading(false);
+    }
+
+    initCheckout();
+  }, []);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setSubmitting(true);
+
+    try {
+      if (customerLoggedIn && checkoutId) {
+        // ===== LOGGED-IN CUSTOMER: Server Checkout =====
+
+        // 1. Set customer info (REQUIRED - even for logged-in customers!)
+        await omni.setCheckoutCustomer(checkoutId, {
+          email: email, // Get from form or customer profile
+          firstName: shippingAddress.firstName,
+          lastName: shippingAddress.lastName,
+        });
+
+        // 2. Set shipping address
+        await omni.setShippingAddress(checkoutId, shippingAddress);
+
+        // 3. Get and select shipping rate
+        const rates = await omni.getShippingRates(checkoutId);
+        if (rates.length > 0) {
+          await omni.selectShippingMethod(checkoutId, selectedRate || rates[0].id);
+        }
+
+        // 4. Complete checkout - ORDER IS LINKED TO CUSTOMER!
+        const { orderId } = await omni.completeCheckout(checkoutId);
+
+        // Clear cart ID
+        localStorage.removeItem('cartId');
+
+        // Redirect to success page
+        window.location.href = `/order-success?orderId=${orderId}`;
+
+      } else {
+        // ===== GUEST: Local Cart + submitGuestOrder =====
+
+        // Set customer and shipping info on local cart
+        omni.setLocalCartCustomer({ email });
+        omni.setLocalCartShippingAddress(shippingAddress);
+
+        // Submit guest order (single API call)
+        const order = await omni.submitGuestOrder();
+
+        // Redirect to success page
+        window.location.href = `/order-success?orderId=${order.orderId}`;
+      }
+    } catch (error) {
+      console.error('Checkout failed:', error);
+      alert('Checkout failed. Please try again.');
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  if (loading) return <div>Loading checkout...</div>;
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* Show email field only for guests */}
+      {!customerLoggedIn && (
+        <input
+          type="email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          placeholder="Email"
+          required
+        />
+      )}
+
+      {/* Shipping address fields */}
+      <input value={shippingAddress.firstName} onChange={(e) => setShippingAddress({...shippingAddress, firstName: e.target.value})} placeholder="First Name" required />
+      <input value={shippingAddress.lastName} onChange={(e) => setShippingAddress({...shippingAddress, lastName: e.target.value})} placeholder="Last Name" required />
+      <input value={shippingAddress.line1} onChange={(e) => setShippingAddress({...shippingAddress, line1: e.target.value})} placeholder="Address" required />
+      <input value={shippingAddress.city} onChange={(e) => setShippingAddress({...shippingAddress, city: e.target.value})} placeholder="City" required />
+      <input value={shippingAddress.postalCode} onChange={(e) => setShippingAddress({...shippingAddress, postalCode: e.target.value})} placeholder="Postal Code" required />
+
+      {/* Shipping rates (for logged-in customers) */}
+      {customerLoggedIn && shippingRates.length > 0 && (
+        <select value={selectedRate || ''} onChange={(e) => setSelectedRate(e.target.value)}>
+          {shippingRates.map((rate) => (
+            <option key={rate.id} value={rate.id}>
+              {rate.name} - ${rate.price}
+            </option>
+          ))}
+        </select>
+      )}
+
+      <button type="submit" disabled={submitting}>
+        {submitting ? 'Processing...' : 'Place Order'}
+      </button>
+
+      {customerLoggedIn && (
+        <p className="text-sm text-green-600">
+          ✓ Logged in - Order will be saved to your account
+        </p>
+      )}
+    </form>
+  );
+}
+```
+
+> **Key Points:**
+>
+> - `isLoggedIn()` determines which flow to use
+> - Logged-in customers use `createCart()` → `createCheckout()` → `completeCheckout()`
+> - Guests use local cart + `submitGuestOrder()`
+> - Local cart items are migrated to server cart when customer logs in
+
+---
+
+### Guest Checkout (Single API Call)
+
+This checkout is for **guest users only**. All cart data is in localStorage, and we submit it in one API call.
+
+> **⚠️ WARNING:** Do NOT use this for logged-in customers! Use the Universal Checkout pattern above instead.
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { omni } from '@/lib/brainerce';
+import type { LocalCart, GuestOrderResponse } from 'brainerce';
+
+type Step = 'info' | 'review' | 'complete';
+
+export default function CheckoutPage() {
+  // ⚠️ Do NOT use useState(omni.getLocalCart()) — causes hydration mismatch!
+  const [cart, setCart] = useState<LocalCart>({ items: [], updatedAt: '' });
+  const [step, setStep] = useState<Step>('info');
+  const [order, setOrder] = useState<GuestOrderResponse | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState('');
+
+  // Form state
+  const [email, setEmail] = useState('');
+  const [firstName, setFirstName] = useState('');
+  const [lastName, setLastName] = useState('');
+  const [address, setAddress] = useState('');
+  const [city, setCity] = useState('');
+  const [postalCode, setPostalCode] = useState('');
+  const [country, setCountry] = useState('US');
+
+  // Load cart from localStorage after hydration
+  useEffect(() => {
+    const localCart = omni.getLocalCart();
+    setCart(localCart);
+    if (localCart.customer?.email) setEmail(localCart.customer.email);
+    if (localCart.customer?.firstName) setFirstName(localCart.customer.firstName);
+    if (localCart.customer?.lastName) setLastName(localCart.customer.lastName);
+    if (localCart.shippingAddress?.line1) setAddress(localCart.shippingAddress.line1);
+    if (localCart.shippingAddress?.city) setCity(localCart.shippingAddress.city);
+    if (localCart.shippingAddress?.postalCode) setPostalCode(localCart.shippingAddress.postalCode);
+    if (localCart.shippingAddress?.country) setCountry(localCart.shippingAddress.country);
+  }, []);
+
+  // Calculate subtotal
+  const subtotal = cart.items.reduce((sum, item) => {
+    return sum + (parseFloat(item.price || '0') * item.quantity);
+  }, 0);
+
+  // Redirect if cart is empty
+  useEffect(() => {
+    if (cart.items.length === 0 && step !== 'complete') {
+      window.location.href = '/cart';
+    }
+  }, [cart.items.length, step]);
+
+  const handleInfoSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    // Save to local cart
+    omni.setLocalCartCustomer({ email, firstName, lastName });
+    omni.setLocalCartShippingAddress({
+      firstName,
+      lastName,
+      line1: address,
+      city,
+      postalCode,
+      country,
+    });
+
+    setStep('review');
+  };
+
+  const handlePlaceOrder = async () => {
+    setSubmitting(true);
+    setError('');
+
+    try {
+      // Single API call to create order!
+      const result = await omni.submitGuestOrder();
+      setOrder(result);
+      setStep('complete');
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to place order');
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  if (step === 'complete' && order) {
+    return (
+      <div className="text-center py-12">
+        <h1 className="text-3xl font-bold text-green-600">Order Complete!</h1>
+        <p className="mt-4">Order Number: <strong>{order.orderNumber}</strong></p>
+        <p className="mt-2">Total: <strong>${order.total.toFixed(2)}</strong></p>
+        <p className="mt-4 text-gray-600">A confirmation email will be sent to {email}</p>
+        <a href="/" className="mt-6 inline-block text-blue-600">Continue Shopping</a>
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-2xl mx-auto">
+      <h1 className="text-2xl font-bold mb-6">Checkout</h1>
+
+      {error && (
+        <div className="bg-red-100 text-red-600 p-3 rounded mb-4">{error}</div>
+      )}
+
+      {step === 'info' && (
+        <form onSubmit={handleInfoSubmit} className="space-y-4">
+          <h2 className="text-lg font-bold">Contact Information</h2>
+          <input
+            type="email"
+            placeholder="Email"
+            value={email}
+            onChange={e => setEmail(e.target.value)}
+            required
+            className="w-full border p-2 rounded"
+          />
+
+          <h2 className="text-lg font-bold mt-6">Shipping Address</h2>
+          <div className="grid grid-cols-2 gap-4">
+            <input placeholder="First Name" value={firstName} onChange={e => setFirstName(e.target.value)} required className="border p-2 rounded" />
+            <input placeholder="Last Name" value={lastName} onChange={e => setLastName(e.target.value)} required className="border p-2 rounded" />
+          </div>
+          <input placeholder="Address" value={address} onChange={e => setAddress(e.target.value)} required className="w-full border p-2 rounded" />
+          <div className="grid grid-cols-2 gap-4">
+            <input placeholder="City" value={city} onChange={e => setCity(e.target.value)} required className="border p-2 rounded" />
+            <input placeholder="Postal Code" value={postalCode} onChange={e => setPostalCode(e.target.value)} required className="border p-2 rounded" />
+          </div>
+          <select value={country} onChange={e => setCountry(e.target.value)} className="w-full border p-2 rounded">
+            <option value="US">United States</option>
+            <option value="IL">Israel</option>
+            <option value="GB">United Kingdom</option>
+          </select>
+
+          <button type="submit" className="w-full bg-black text-white py-3 rounded">
+            Review Order
+          </button>
+        </form>
+      )}
+
+      {step === 'review' && (
+        <div className="space-y-6">
+          {/* Order Summary */}
+          <div className="border p-4 rounded">
+            <h3 className="font-bold mb-4">Order Summary</h3>
+            {cart.items.map((item) => (
+              <div key={`${item.productId}-${item.variantId || ''}`} className="flex justify-between py-2">
+                <span>{item.name} x {item.quantity}</span>
+                <span>${(parseFloat(item.price || '0') * item.quantity).toFixed(2)}</span>
+              </div>
+            ))}
+            <hr className="my-2" />
+            <div className="flex justify-between font-bold">
+              <span>Total</span>
+              <span>${subtotal.toFixed(2)}</span>
+            </div>
+          </div>
+
+          {/* Shipping Info */}
+          <div className="border p-4 rounded">
+            <h3 className="font-bold mb-2">Shipping To</h3>
+            <p>{firstName} {lastName}</p>
+            <p>{address}</p>
+            <p>{city}, {postalCode}, {country}</p>
+            <button onClick={() => setStep('info')} className="text-blue-600 text-sm mt-2">Edit</button>
+          </div>
+
+          <button
+            onClick={handlePlaceOrder}
+            disabled={submitting}
+            className="w-full bg-green-600 text-white py-3 rounded text-lg"
+          >
+            {submitting ? 'Processing...' : 'Place Order'}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Multi-Step Checkout (Server Cart - For Logged-In Customers Only)
+
+> **IMPORTANT:** This checkout pattern is ONLY for logged-in customers. For a checkout page that handles both guests and logged-in customers, see the "Universal Checkout" example above.
+
+For logged-in users with server-side cart - orders will be linked to their account:
+
+```typescript
+'use client';
+import { useEffect, useState } from 'react';
+import { omni, getServerCartId } from '@/lib/brainerce';
+import type { Checkout, ShippingRate } from 'brainerce';
+
+type Step = 'customer' | 'shipping' | 'payment' | 'complete';
+
+export default function CheckoutPage() {
+  const [checkout, setCheckout] = useState<Checkout | null>(null);
+  const [step, setStep] = useState<Step>('customer');
+  const [shippingRates, setShippingRates] = useState<ShippingRate[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [submitting, setSubmitting] = useState(false);
+
+  // Form state
+  const [email, setEmail] = useState('');
+  const [firstName, setFirstName] = useState('');
+  const [lastName, setLastName] = useState('');
+  const [address, setAddress] = useState('');
+  const [city, setCity] = useState('');
+  const [postalCode, setPostalCode] = useState('');
+  const [country, setCountry] = useState('US');
+
+  useEffect(() => {
+    async function initCheckout() {
+      const cartId = getServerCartId();
+      if (!cartId) {
+        window.location.href = '/cart';
+        return;
+      }
+      try {
+        const c = await omni.createCheckout({ cartId });
+        setCheckout(c);
+      } finally {
+        setLoading(false);
+      }
+    }
+    initCheckout();
+  }, []);
+
+  const handleCustomerSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!checkout) return;
+    setSubmitting(true);
+    try {
+      await omni.setCheckoutCustomer(checkout.id, { email, firstName, lastName });
+      setStep('shipping');
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleShippingSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!checkout) return;
+    setSubmitting(true);
+    try {
+      const { rates } = await omni.setShippingAddress(checkout.id, {
+        firstName, lastName,
+        line1: address,
+        city, postalCode, country,
+      });
+      setShippingRates(rates);
+      if (rates.length > 0) {
+        await omni.selectShippingMethod(checkout.id, rates[0].id);
+      }
+      setStep('payment');
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleCompleteOrder = async () => {
+    if (!checkout) return;
+    setSubmitting(true);
+    try {
+      const { orderId } = await omni.completeCheckout(checkout.id);
+      setStep('complete');
+    } catch (err) {
+      alert('Failed to complete order');
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  if (loading) return <div>Loading checkout...</div>;
+  if (!checkout) return <div>Failed to create checkout</div>;
+
+  if (step === 'complete') {
+    return (
+      <div className="text-center py-12">
+        <h1 className="text-3xl font-bold text-green-600">Order Complete!</h1>
+        <p className="mt-4">Thank you for your purchase.</p>
+        <a href="/" className="mt-6 inline-block text-blue-600">Continue Shopping</a>
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-2xl mx-auto">
+      <h1 className="text-2xl font-bold mb-6">Checkout</h1>
+
+      {step === 'customer' && (
+        <form onSubmit={handleCustomerSubmit} className="space-y-4">
+          <input type="email" placeholder="Email" value={email} onChange={e => setEmail(e.target.value)} required className="w-full border p-2 rounded" />
+          <div className="grid grid-cols-2 gap-4">
+            <input placeholder="First Name" value={firstName} onChange={e => setFirstName(e.target.value)} required className="border p-2 rounded" />
+            <input placeholder="Last Name" value={lastName} onChange={e => setLastName(e.target.value)} required className="border p-2 rounded" />
+          </div>
+          <button type="submit" disabled={submitting} className="w-full bg-black text-white py-3 rounded">
+            {submitting ? 'Saving...' : 'Continue to Shipping'}
+          </button>
+        </form>
+      )}
+
+      {step === 'shipping' && (
+        <form onSubmit={handleShippingSubmit} className="space-y-4">
+          <input placeholder="Address" value={address} onChange={e => setAddress(e.target.value)} required className="w-full border p-2 rounded" />
+          <div className="grid grid-cols-2 gap-4">
+            <input placeholder="City" value={city} onChange={e => setCity(e.target.value)} required className="border p-2 rounded" />
+            <input placeholder="Postal Code" value={postalCode} onChange={e => setPostalCode(e.target.value)} required className="border p-2 rounded" />
+          </div>
+          <select value={country} onChange={e => setCountry(e.target.value)} className="w-full border p-2 rounded">
+            <option value="US">United States</option>
+            <option value="IL">Israel</option>
+            <option value="GB">United Kingdom</option>
+          </select>
+          <button type="submit" disabled={submitting} className="w-full bg-black text-white py-3 rounded">
+            {submitting ? 'Calculating Shipping...' : 'Continue to Payment'}
+          </button>
+        </form>
+      )}
+
+      {step === 'payment' && (
+        <div className="space-y-6">
+          <div className="border p-4 rounded">
+            <h3 className="font-bold mb-2">Order Summary</h3>
+            <p>Subtotal: ${checkout.subtotal}</p>
+            <p>Shipping: ${checkout.shippingAmount}</p>
+            <p className="text-xl font-bold mt-2">Total: ${checkout.total}</p>
+          </div>
+          <button onClick={handleCompleteOrder} disabled={submitting} className="w-full bg-green-600 text-white py-3 rounded text-lg">
+            {submitting ? 'Processing...' : 'Complete Order'}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Login Page
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { omni, setCustomerToken } from '@/lib/brainerce';
+
+export default function LoginPage() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [error, setError] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  // Save the page user came from (for redirect after login)
+  useEffect(() => {
+    const referrer = document.referrer;
+    if (referrer && !referrer.includes('/login') && !referrer.includes('/register')) {
+      const url = new URL(referrer);
+      localStorage.setItem('returnUrl', url.pathname);
+    }
+  }, []);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    setError('');
+    try {
+      const auth = await omni.loginCustomer(email, password);
+      setCustomerToken(auth.token);
+
+      // Redirect back to previous page or home (like Amazon/Shopify do)
+      const returnUrl = localStorage.getItem('returnUrl') || '/';
+      localStorage.removeItem('returnUrl');
+      window.location.href = returnUrl;
+    } catch (err) {
+      setError('Invalid email or password');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="max-w-md mx-auto mt-12">
+      <h1 className="text-2xl font-bold mb-6">Login</h1>
+      {error && <div className="bg-red-100 text-red-600 p-3 rounded mb-4">{error}</div>}
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <input type="email" placeholder="Email" value={email} onChange={e => setEmail(e.target.value)} required className="w-full border p-2 rounded" />
+        <input type="password" placeholder="Password" value={password} onChange={e => setPassword(e.target.value)} required className="w-full border p-2 rounded" />
+        <button type="submit" disabled={loading} className="w-full bg-black text-white py-3 rounded">
+          {loading ? 'Logging in...' : 'Login'}
+        </button>
+      </form>
+      <p className="mt-4 text-center">
+        Don't have an account? <a href="/register" className="text-blue-600">Register</a>
+      </p>
+    </div>
+  );
+}
+```
+
+### Register Page
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { omni, setCustomerToken } from '@/lib/brainerce';
+
+export default function RegisterPage() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [firstName, setFirstName] = useState('');
+  const [lastName, setLastName] = useState('');
+  const [error, setError] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  // Save the page user came from (for redirect after registration)
+  useEffect(() => {
+    const referrer = document.referrer;
+    if (referrer && !referrer.includes('/login') && !referrer.includes('/register')) {
+      const url = new URL(referrer);
+      localStorage.setItem('returnUrl', url.pathname);
+    }
+  }, []);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    setError('');
+    try {
+      const auth = await omni.registerCustomer({ email, password, firstName, lastName });
+
+      // Check if email verification is required
+      if (auth.requiresVerification) {
+        // Save token for verification step
+        localStorage.setItem('verificationToken', auth.token);
+        window.location.href = '/verify-email';
+      } else {
+        // No verification needed - redirect back to store (like Amazon/Shopify)
+        setCustomerToken(auth.token);
+        const returnUrl = localStorage.getItem('returnUrl') || '/';
+        localStorage.removeItem('returnUrl');
+        window.location.href = returnUrl;
+      }
+    } catch (err) {
+      setError('Registration failed. Email may already be in use.');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="max-w-md mx-auto mt-12">
+      <h1 className="text-2xl font-bold mb-6">Create Account</h1>
+      {error && <div className="bg-red-100 text-red-600 p-3 rounded mb-4">{error}</div>}
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <div className="grid grid-cols-2 gap-4">
+          <input placeholder="First Name" value={firstName} onChange={e => setFirstName(e.target.value)} required className="border p-2 rounded" />
+          <input placeholder="Last Name" value={lastName} onChange={e => setLastName(e.target.value)} required className="border p-2 rounded" />
+        </div>
+        <input type="email" placeholder="Email" value={email} onChange={e => setEmail(e.target.value)} required className="w-full border p-2 rounded" />
+        <input type="password" placeholder="Password (min 8 characters)" value={password} onChange={e => setPassword(e.target.value)} required minLength={8} className="w-full border p-2 rounded" />
+        <button type="submit" disabled={loading} className="w-full bg-black text-white py-3 rounded">
+          {loading ? 'Creating Account...' : 'Create Account'}
+        </button>
+      </form>
+      <p className="mt-4 text-center">
+        Already have an account? <a href="/login" className="text-blue-600">Login</a>
+      </p>
+    </div>
+  );
+}
+```
+
+### Account Page
+
+```typescript
+'use client';
+import { useEffect, useState } from 'react';
+import { omni, restoreCustomerToken, setCustomerToken, isLoggedIn } from '@/lib/brainerce';
+import type { CustomerProfile, Order } from 'brainerce';
+
+export default function AccountPage() {
+  const [profile, setProfile] = useState<CustomerProfile | null>(null);
+  const [orders, setOrders] = useState<Order[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    restoreCustomerToken();
+    if (!isLoggedIn()) {
+      window.location.href = '/login';
+      return;
+    }
+
+    async function load() {
+      try {
+        const [p, o] = await Promise.all([
+          omni.getMyProfile(),
+          omni.getMyOrders({ limit: 10 }),
+        ]);
+        setProfile(p);
+        setOrders(o.data);
+      } finally {
+        setLoading(false);
+      }
+    }
+    load();
+  }, []);
+
+  const handleLogout = () => {
+    setCustomerToken(null);
+    window.location.href = '/';
+  };
+
+  if (loading) return <div>Loading...</div>;
+  if (!profile) return <div>Please log in</div>;
+
+  return (
+    <div>
+      <div className="flex justify-between items-center mb-8">
+        <h1 className="text-2xl font-bold">My Account</h1>
+        <button onClick={handleLogout} className="text-red-600">Logout</button>
+      </div>
+
+      <div className="grid md:grid-cols-2 gap-8">
+        <div className="border rounded p-6">
+          <h2 className="text-xl font-bold mb-4">Profile</h2>
+          <p><strong>Name:</strong> {profile.firstName} {profile.lastName}</p>
+          <p><strong>Email:</strong> {profile.email}</p>
+        </div>
+
+        <div className="border rounded p-6">
+          <h2 className="text-xl font-bold mb-4">Recent Orders</h2>
+          {orders.length === 0 ? (
+            <p className="text-gray-500">No orders yet</p>
+          ) : (
+            <div className="space-y-4">
+              {orders.map((order) => (
+                <div key={order.id} className="border-b pb-4">
+                  <span className="font-medium">#{order.id.slice(-8)}</span>
+                  <span className="ml-2 text-sm">{order.status}</span>
+                  <p className="font-bold">${order.totalAmount}</p>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Header Component with Cart Count (Local Cart)
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { omni, isLoggedIn } from '@/lib/brainerce';
+
+export function Header() {
+  const [cartCount, setCartCount] = useState(0);
+  const [loggedIn, setLoggedIn] = useState(false);
+
+  useEffect(() => {
+    setLoggedIn(isLoggedIn());
+    // Get cart count from local storage (NO API call!)
+    setCartCount(omni.getLocalCartItemCount());
+  }, []);
+
+  return (
+    <header className="flex justify-between items-center p-4 border-b">
+      <a href="/" className="text-xl font-bold">Store Name</a>
+      <nav className="flex gap-6 items-center">
+        <a href="/products">Shop</a>
+        <a href="/cart" className="relative">
+          Cart
+          {cartCount > 0 && (
+            <span className="absolute -top-2 -right-2 bg-red-600 text-white text-xs w-5 h-5 rounded-full flex items-center justify-center">
+              {cartCount}
+            </span>
+          )}
+        </a>
+        {loggedIn ? (
+          <a href="/account">Account</a>
+        ) : (
+          <a href="/login">Login</a>
+        )}
+      </nav>
+    </header>
+  );
+}
+```
+
+---
+
+## Error Handling
+
+```typescript
+import { BrainerceClient, BrainerceError } from 'brainerce';
+
+try {
+  const product = await omni.getProduct('invalid_id');
+} catch (error) {
+  if (error instanceof BrainerceError) {
+    console.error(`API Error: ${error.message}`);
+    console.error(`Status Code: ${error.statusCode}`);
+    console.error(`Details:`, error.details);
+  }
+}
+```
+
+---
+
+## Webhooks
+
+Receive real-time updates when products, orders, or inventory change.
+
+### Setup Webhook Endpoint
+
+```typescript
+// api/webhooks/brainerce/route.ts (Next.js App Router)
+import { verifyWebhook, createWebhookHandler } from 'brainerce';
+
+const handler = createWebhookHandler({
+  'product.updated': async (event) => {
+    console.log('Product updated:', event.entityId);
+    // Invalidate cache, update UI, etc.
+  },
+  'inventory.updated': async (event) => {
+    console.log('Stock changed:', event.data);
+  },
+  'order.created': async (event) => {
+    console.log('New order from:', event.platform);
+  },
+});
+
+export async function POST(req: Request) {
+  const signature = req.headers.get('x-omni-signature');
+  const body = await req.json();
+
+  // Verify signature
+  if (!verifyWebhook(body, signature, process.env.OMNI_SYNC_WEBHOOK_SECRET!)) {
+    return new Response('Invalid signature', { status: 401 });
+  }
+
+  // Process event
+  await handler(body);
+
+  return new Response('OK');
+}
+```
+
+### Webhook Events
+
+| Event                | Description                     |
+| -------------------- | ------------------------------- |
+| `product.created`    | New product created             |
+| `product.updated`    | Product details changed         |
+| `product.deleted`    | Product removed                 |
+| `inventory.updated`  | Stock levels changed            |
+| `order.created`      | New order received              |
+| `order.updated`      | Order status changed            |
+| `cart.abandoned`     | Cart abandoned (no activity)    |
+| `checkout.completed` | Checkout completed successfully |
+
+---
+
+## TypeScript Support
+
+All types are exported for full TypeScript support:
+
+```typescript
+import type {
+  // Products
+  Product,
+  ProductImage,
+  ProductVariant,
+  InventoryInfo,
+  ProductQueryParams,
+  PaginatedResponse,
+
+  // Local Cart (Guest Users)
+  LocalCart,
+  LocalCartItem,
+  CreateGuestOrderDto,
+  GuestOrderResponse,
+
+  // Server Cart (Registered Users)
+  Cart,
+  CartItem,
+  AddToCartDto,
+
+  // Checkout
+  Checkout,
+  CheckoutStatus,
+  ShippingRate,
+  SetShippingAddressDto,
+
+  // Customer
+  Customer,
+  CustomerProfile,
+  CustomerAddress,
+  CustomerAuthResponse,
+
+  // Orders
+  Order,
+  OrderStatus,
+  OrderItem,
+
+  // Webhooks
+  WebhookEvent,
+  WebhookEventType,
+
+  // Errors
+  BrainerceError,
+} from 'brainerce';
+```
+
+---
+
+## Environment Variables
+
+```env
+# Required for vibe-coded sites
+NEXT_PUBLIC_OMNI_CONNECTION_ID=vc_your_connection_id
+
+# Optional: Override API URL (default: https://api.brainerce.com)
+NEXT_PUBLIC_OMNI_API_URL=https://api.brainerce.com
+
+# For webhooks (server-side only)
+OMNI_SYNC_WEBHOOK_SECRET=your_webhook_secret
+```
+
+---
+
+## Required Pages Checklist
+
+When building a store, implement these pages:
+
+- [ ] **Home** (`/`) - Product grid
+- [ ] **Products** (`/products`) - Product list with pagination
+- [ ] **Product Detail** (`/products/[slug]`) - Single product with Add to Cart (use `getProductBySlug(slug)`)
+- [ ] **Cart** (`/cart`) - Cart items, update quantity, remove
+- [ ] **Checkout** (`/checkout`) - Multi-step checkout flow
+- [ ] **⚠️ Payment** (`/checkout/payment`) - **REQUIRED!** Use `getPaymentProviders()` to show Stripe/PayPal forms
+- [ ] **Login** (`/login`) - Customer login + social login buttons (Google/Facebook/GitHub if available)
+- [ ] **Register** (`/register`) - Customer registration + social signup buttons
+- [ ] **Auth Callback** (`/auth/callback`) - Handle OAuth redirects from Google/Facebook/GitHub
+- [ ] **Verify Email** (`/verify-email`) - Email verification with 6-digit code (if store requires it)
+- [ ] **Account** (`/account`) - Profile and order history
+
+### ⚠️ Payment Page is REQUIRED
+
+Without a payment page, customers cannot complete orders! See [Payment Integration](#payment-integration-vibe-coded-sites) for implementation.
+
+---
+
+## Error Handling & Toast Notifications
+
+For a polished user experience, use toast notifications to show success/error messages. We recommend [Sonner](https://sonner.emilkowal.ski/) - a lightweight toast library.
+
+### Setup Toast Notifications
+
+```bash
+npm install sonner
+```
+
+Add the Toaster component to your app layout:
+
+```tsx
+// app/layout.tsx or App.tsx
+import { Toaster } from 'sonner';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Toaster
+          position="top-right"
+          richColors
+          closeButton
+          toastOptions={{
+            duration: 4000,
+          }}
+        />
+      </body>
+    </html>
+  );
+}
+```
+
+### Handling SDK Errors
+
+The SDK throws `BrainerceError` with helpful messages. Wrap SDK calls in try/catch:
+
+```tsx
+import { toast } from 'sonner';
+import { BrainerceError } from 'brainerce';
+
+// Add to cart with toast feedback
+const handleAddToCart = async (productId: string, quantity: number) => {
+  try {
+    omni.addToLocalCart({ productId, quantity });
+    toast.success('Added to cart!');
+  } catch (error) {
+    if (error instanceof BrainerceError) {
+      toast.error(error.message);
+    } else {
+      toast.error('Something went wrong');
+    }
+  }
+};
+
+// Checkout with toast feedback
+const handleCheckout = async () => {
+  try {
+    const order = await omni.submitGuestOrder();
+    toast.success(`Order placed! Order #${order.orderNumber}`);
+    // Navigate to success page
+  } catch (error) {
+    if (error instanceof BrainerceError) {
+      // Show specific error message from SDK
+      toast.error(error.message);
+    } else {
+      toast.error('Failed to place order. Please try again.');
+    }
+  }
+};
+```
+
+### Common Error Messages
+
+| Error                          | When it occurs                     |
+| ------------------------------ | ---------------------------------- |
+| `Cart is empty`                | Trying to checkout with empty cart |
+| `Customer email is required`   | Missing email at checkout          |
+| `Shipping address is required` | Missing shipping address           |
+| `Product not found`            | Invalid product ID                 |
+| `Insufficient inventory`       | Not enough stock                   |
+| `Invalid quantity`             | Quantity < 1 or > available        |
+
+### Custom Hook for SDK Operations (Optional)
+
+Create a reusable hook for SDK operations with automatic toast handling:
+
+```tsx
+// hooks/useOmniAction.ts
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { BrainerceError } from 'brainerce';
+
+export function useOmniAction<T>() {
+  const [isLoading, setIsLoading] = useState(false);
+
+  const execute = async (
+    action: () => Promise<T>,
+    options?: {
+      successMessage?: string;
+      errorMessage?: string;
+      onSuccess?: (result: T) => void;
+    }
+  ): Promise<T | null> => {
+    setIsLoading(true);
+    try {
+      const result = await action();
+      if (options?.successMessage) {
+        toast.success(options.successMessage);
+      }
+      options?.onSuccess?.(result);
+      return result;
+    } catch (error) {
+      const message =
+        error instanceof BrainerceError
+          ? error.message
+          : options?.errorMessage || 'Something went wrong';
+      toast.error(message);
+      return null;
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  return { execute, isLoading };
+}
+
+// Usage:
+const { execute, isLoading } = useOmniAction();
+
+const handlePlaceOrder = () => {
+  execute(() => omni.submitGuestOrder(), {
+    successMessage: 'Order placed successfully!',
+    onSuccess: (order) => navigate(`/order/${order.orderId}`),
+  });
+};
+```
+
+---
+
+## Important Rules
+
+### DO:
+
+- Install `brainerce` and use it for ALL data
+- Import types from the SDK
+- Handle loading states and errors
+- **Use toast notifications (Sonner) for user feedback on actions**
+- Persist cart ID in localStorage
+- Persist customer token after login
+- **Use `isHtmlDescription(product)` helper and render HTML with `dangerouslySetInnerHTML` when it returns true**
+- **Wrap SDK calls in try/catch and show error toasts**
+
+### DON'T:
+
+- Create mock/hardcoded product data
+- Use localStorage for products
+- Skip implementing required pages
+- Write `const products = [...]` - use the API!
+- Use `@apply group` in CSS - Tailwind doesn't allow 'group' in @apply. Use `className="group"` on the element instead
+- **Render `product.description` as plain text without using `isHtmlDescription()` - HTML will show as raw tags like `<p>`, `<ul>`, `<li>`!**
+
+---
+
+## License
+
+MIT