brainerce 1.0.1 → 1.0.2

package/README.md

@@ -123,15 +123,11 @@ const { data: products } = await client.getProducts();
 
 > **AI Agents / Vibe-Coders:** Read this section carefully! These are common misunderstandings.
 
-### 1. Guest Checkout - Don't Use createCheckout with Local Cart!
+### 1. Guest Checkout - Use `startGuestCheckout()` for Guests
 
-**This is the #1 cause of "Cart not found" errors!**
+**For guest users, use `startGuestCheckout()` which creates a checkout from the session cart:**
 
 ```typescript
-// ❌ WRONG - Local cart ID "__local__" doesn't exist on server!
-const cart = await client.smartGetCart(); // Returns { id: "__local__", ... }
-const checkout = await client.createCheckout({ cartId: cart.id }); // 💥 ERROR: Cart not found
-
 // ✅ CORRECT - Use startGuestCheckout() for guest users
 const result = await client.startGuestCheckout();
 if (result.tracked) {
@@ -145,7 +141,7 @@ const order = await client.submitGuestOrder();
 
 **Rule of thumb:**
 
-- Guest user + Local cart → `startGuestCheckout()` or `submitGuestOrder()`
+- Guest user + Session cart → `startGuestCheckout()` or `submitGuestOrder()`
 - Logged-in user + Server cart → `createCheckout({ cartId })`
 
 ### 2. ⛔ NEVER Create Local Interfaces - Use SDK Types!
@@ -381,13 +377,7 @@ const total = subtotal - discount;
 - 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
-  );
-  ```
+- `getCartTotals()` works with all carts — guests now use server-side session carts with full pricing fields.
 
 ### 15. SearchSuggestions - Products Have `price`, Not `basePrice`
 
@@ -432,91 +422,61 @@ export default function SuccessPage() {
 
 **Why is this needed?**
 
-- `completeGuestCheckout()` sends the order to the server AND clears the local cart
+- `completeGuestCheckout()` sends the order to the server AND clears the session 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
+- After successful checkout, also call `client.onCheckoutComplete()` to clear the session cart reference
 
 ---
 
 ## Checkout: Guest vs Logged-In Customer
 
-> **⚠️ CRITICAL:** There are TWO different checkout flows. Using the wrong one will cause errors!
+Both guests and logged-in customers now use the same `smart*` cart methods. The SDK handles server-side session carts for guests automatically.
 
-| Customer Type | Cart Type                 | With Payment (Stripe)  | Without Payment UI   |
-| ------------- | ------------------------- | ---------------------- | -------------------- |
-| **Guest**     | Local Cart (localStorage) | `startGuestCheckout()` | `submitGuestOrder()` |
-| **Logged In** | Server Cart               | `createCheckout()`     | `completeCheckout()` |
+| Customer Type | Cart Method | Checkout |
+| ------------- | ----------- | -------- |
+| **Guest**     | `smartAddToCart()` (session cart) | `startGuestCheckout()` → `createCheckout()` |
+| **Logged In** | `smartAddToCart()` (server cart) | `createCheckout()` → `completeCheckout()` |
 
-### ❌ COMMON MISTAKE - Don't Do This!
+### Cart Usage (Same for Both)
 
 ```typescript
-// ❌ WRONG - This will FAIL with "Cart not found" error!
-const cart = client.getLocalCart(); // Returns cart with id: "__local__"
-const checkout = await client.createCheckout({ cartId: cart.id }); // ERROR!
-
-// The "__local__" ID is virtual - it doesn't exist on the server!
-```
+// Add to cart — works for both guests and logged-in users
+await client.smartAddToCart({ productId: 'prod_123', quantity: 2 });
 
-### ✅ Correct Flow for Guest Checkout with Payment
+// Get cart
+const cart = await client.smartGetCart();
 
-```typescript
-// ✅ CORRECT - Use startGuestCheckout() for guests with local cart
-const result = await client.startGuestCheckout();
+// Update quantity
+await client.smartUpdateCartItem('prod_123', 5);
 
-if (result.tracked) {
-  // Now you have a REAL checkout on the server
-  const checkout = await client.getCheckout(result.checkoutId);
+// Remove item
+await client.smartRemoveFromCart('prod_123');
 
-  // Continue with shipping, payment, etc.
-  await client.setShippingAddress(result.checkoutId, { ... });
-  const intent = await client.createPaymentIntent(result.checkoutId);
-  // ... Stripe payment ...
-}
+// Get totals (works for all carts)
+import { getCartTotals } from 'brainerce';
+const totals = getCartTotals(cart); // { subtotal, discount, shipping, total }
 ```
 
-### Decision Flow
+### On Login — Merge Guest Cart
 
 ```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 client.submitGuestOrder();
-}
+// After setting customer token
+client.setCustomerToken(token);
+await client.syncCartOnLogin(); // Merges session cart into customer cart
 ```
 
-### Guest Checkout (for visitors without account)
+### Guest Checkout
 
 ```typescript
-// Cart stored locally - NO API calls until checkout!
-
-// Add to local cart (stored in localStorage)
-client.addToLocalCart({
-  productId: products[0].id,
-  quantity: 1,
-  name: products[0].name,
-  price: String(products[0].basePrice),
-});
-
-// Set customer info
-client.setLocalCartCustomer({ email: 'customer@example.com' });
-client.setLocalCartShippingAddress({
-  firstName: 'John',
-  lastName: 'Doe',
-  line1: '123 Main St',
-  city: 'New York',
-  postalCode: '10001',
-  country: 'US',
-});
+// Guest checkout creates a checkout from the session cart
+const result = await client.startGuestCheckout();
 
-// Submit order (single API call!)
-const order = await client.submitGuestOrder();
-console.log('Order created:', order.orderId);
+if (result.tracked) {
+  const checkout = await client.getCheckout(result.checkoutId);
+  await client.setShippingAddress(result.checkoutId, shippingAddress);
+  // ... continue with shipping rates, payment, etc.
+}
 ```
 
 ### Logged-In Customer Checkout (orders linked to account)
@@ -525,27 +485,24 @@ console.log('Order created:', order.orderId);
 // 1. Make sure customer token is set (after login)
 client.setCustomerToken(authResponse.token);
 
-// 2. Create server cart (auto-linked to customer!)
-const cart = await client.createCart();
-localStorage.setItem('cartId', cart.id);
-
-// 3. Add items to server cart
-await client.addToCart(cart.id, {
+// 2. Add items to cart (smart methods handle server cart automatically)
+await client.smartAddToCart({
   productId: products[0].id,
   quantity: 1,
 });
 
-// 4. Create checkout from cart
+// 3. Get cart and create checkout
+const cart = await client.smartGetCart();
 const checkout = await client.createCheckout({ cartId: cart.id });
 
-// 5. Set customer info (REQUIRED - email is needed for order!)
+// 4. Set customer info (REQUIRED - email is needed for order!)
 await client.setCheckoutCustomer(checkout.id, {
   email: 'customer@example.com',
   firstName: 'John',
   lastName: 'Doe',
 });
 
-// 6. Set shipping address
+// 5. Set shipping address
 await client.setShippingAddress(checkout.id, {
   firstName: 'John',
   lastName: 'Doe',
@@ -555,11 +512,11 @@ await client.setShippingAddress(checkout.id, {
   country: 'US',
 });
 
-// 7. Get shipping rates and select one
+// 6. Get shipping rates and select one
 const rates = await client.getShippingRates(checkout.id);
 await client.selectShippingMethod(checkout.id, rates[0].id);
 
-// 8. Complete checkout - order is linked to customer!
+// 7. Complete checkout - order is linked to customer!
 const { orderId } = await client.completeCheckout(checkout.id);
 console.log('Order created:', orderId);
 
@@ -570,62 +527,53 @@ console.log('Order created:', orderId);
 
 ---
 
-## Two Ways to Handle Cart
-
-### Option 1: Local Cart (Guest Users)
+## Cart (Unified for All Users)
 
-For guest users, the cart is stored in **localStorage** - exactly like Amazon, Shopify, and other major platforms do. This means:
+The SDK uses **server-side carts for all users**. Guests get automatic session carts; logged-in customers get server carts linked to their account.
 
-- ✅ No API calls when browsing/adding to cart
-- ✅ Cart persists across page refreshes
-- ✅ Single API call at checkout
-- ✅ No server load for window shoppers
+- ✅ Cart persists across page refreshes (via session token in localStorage)
+- ✅ Server-side pricing, discounts, and totals
+- ✅ Automatic migration from guest → customer cart on login
+- ✅ Same API for both guests and logged-in users
 
 ```typescript
-// Add product to local cart
-client.addToLocalCart({ productId: 'prod_123', quantity: 2 });
+// Add to cart (guest or logged-in — same code!)
+await client.smartAddToCart({ productId: 'prod_123', quantity: 2 });
 
-// View cart
-const cart = client.getLocalCart();
+// Get cart
+const cart = await client.smartGetCart();
 console.log('Items:', cart.items.length);
+console.log('Total:', getCartTotals(cart).total);
 
 // Update quantity
-client.updateLocalCartItem('prod_123', 5);
+await client.smartUpdateCartItem('prod_123', 5);
 
 // Remove item
-client.removeFromLocalCart('prod_123');
-
-// At checkout - submit everything in ONE API call
-const order = await client.submitGuestOrder();
+await client.smartRemoveFromCart('prod_123');
 ```
 
-### 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"
+### After Login — Sync Cart
 
 ```typescript
-// 1. Set customer token (after login)
 client.setCustomerToken(token);
+const mergedCart = await client.syncCartOnLogin();
+// Guest session cart items are merged into the customer's server cart
+```
 
-// 2. Create cart (auto-linked to customer)
-const cart = await client.createCart();
-localStorage.setItem('cartId', cart.id);
-
-// 3. Add items
-await client.addToCart(cart.id, { productId: 'prod_123', quantity: 2 });
+### After Checkout — Clear Cart
 
-// 4. At checkout - create checkout and complete
-const checkout = await client.createCheckout({ cartId: cart.id });
-// ... set shipping address, select shipping method ...
-const { orderId } = await client.completeCheckout(checkout.id);
+```typescript
+client.onCheckoutComplete();
+// Clears session cart reference so next visit starts fresh
 ```
 
-> **⚠️ CRITICAL:** If you use `submitGuestOrder()` for a logged-in customer, their order will NOT be linked to their account!
+### After Logout — Preserve Guest Cart
+
+```typescript
+client.clearCustomerToken();
+client.onLogout();
+// Session cart is preserved — guest can continue browsing
+```
 
 ---
 
@@ -642,29 +590,14 @@ export const client = new BrainerceClient({
   connectionId: 'vc_YOUR_CONNECTION_ID', // Your Connection ID from Brainerce
 });
 
-// ----- Guest Cart Helpers (localStorage) -----
-
-export function getCartItemCount(): number {
-  return client.getLocalCartItemCount();
-}
-
-export function getCart() {
-  return client.getLocalCart();
-}
-
-// ----- For Registered Users (server cart) -----
-
-export function getServerCartId(): string | null {
-  if (typeof window === 'undefined') return null;
-  return localStorage.getItem('cartId');
-}
+// ----- Cart Helpers -----
 
-export function setServerCartId(id: string): void {
-  localStorage.setItem('cartId', id);
+export async function getCart() {
+  return client.smartGetCart();
 }
 
-export function clearServerCartId(): void {
-  localStorage.removeItem('cartId');
+export function getCartItemCount(): number {
+  return client.getSmartCartItemCount();
 }
 
 // ----- Customer Token Helpers -----
@@ -1096,164 +1029,86 @@ function ProductDescription({ product }: { product: Product }) {
 
 ---
 
-### Local Cart (Guest Users) - RECOMMENDED
+### Cart Operations (All Users)
 
-The local cart stores everything in **localStorage** until checkout. This is the recommended approach for most storefronts.
+The `smart*` methods work for both guests and logged-in users. Guests use server-side session carts; logged-in users use server carts linked to their account.
 
-#### Add to Local Cart
+#### Add to Cart
 
 ```typescript
-// Add item with product info (for display)
-client.addToLocalCart({
+await client.smartAddToCart({
   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
+#### Get Cart
 
 ```typescript
-const cart = client.getLocalCart();
+const cart = await client.smartGetCart();
 
-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)
+console.log(cart.items);        // Array of CartItem
+console.log(cart.itemCount);    // Total item count
+console.log(cart.couponCode);   // Applied coupon (if any)
 ```
 
 #### Update Item Quantity
 
 ```typescript
 // Set quantity to 5
-client.updateLocalCartItem('prod_123', 5);
+await client.smartUpdateCartItem('prod_123', 5);
 
 // For variant products
-client.updateLocalCartItem('prod_123', 3, 'var_456');
+await client.smartUpdateCartItem('prod_123', 3, 'var_456');
 
 // Set to 0 to remove
-client.updateLocalCartItem('prod_123', 0);
+await client.smartUpdateCartItem('prod_123', 0);
 ```
 
 #### Remove Item
 
 ```typescript
-client.removeFromLocalCart('prod_123');
-client.removeFromLocalCart('prod_123', 'var_456'); // With variant
-```
-
-#### Clear Cart
-
-```typescript
-client.clearLocalCart();
+await client.smartRemoveFromCart('prod_123');
+await client.smartRemoveFromCart('prod_123', 'var_456'); // With variant
 ```
 
-#### Set Customer Info
+#### Get Cart Item Count (No API Call)
 
 ```typescript
-client.setLocalCartCustomer({
-  email: 'customer@example.com', // Required
-  firstName: 'John', // Optional
-  lastName: 'Doe', // Optional
-  phone: '+1234567890', // Optional
-});
-```
-
-#### Set Shipping Address
-
-```typescript
-client.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
-client.setLocalCartBillingAddress({
-  firstName: 'John',
-  lastName: 'Doe',
-  line1: '456 Business Ave',
-  city: 'New York',
-  postalCode: '10002',
-  country: 'US',
-});
+// Returns cached count from session reference — instant, no API call
+const count = client.getSmartCartItemCount();
+console.log(`${count} items in cart`);
+// For accurate count, use: (await client.smartGetCart()).itemCount
 ```
 
 #### Apply Coupon
 
 ```typescript
-client.setLocalCartCoupon('SAVE20');
+const cart = await client.smartGetCart();
+const updated = await client.applyCoupon(cart.id, 'SAVE20');
+console.log(updated.discountAmount); // "10.00"
+console.log(updated.couponCode);     // "SAVE20"
 
 // Remove coupon
-client.setLocalCartCoupon(undefined);
-```
-
-#### Get Cart Item Count
-
-```typescript
-const count = client.getLocalCartItemCount();
-console.log(`${count} items in cart`);
+await client.removeCoupon(cart.id);
 ```
 
-#### Local Cart Type Definition
+#### Cart Totals
 
 ```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;
-}
+import { getCartTotals } from 'brainerce';
 
-interface LocalCartItem {
-  productId: string;
-  variantId?: string;
-  quantity: number;
-  name?: string;
-  sku?: string;
-  price?: string;
-  image?: string;
-  addedAt: string;
-}
+const cart = await client.smartGetCart();
+const totals = getCartTotals(cart);
+// { subtotal: 59.98, discount: 10, shipping: 5.99, total: 55.97 }
 ```
 
 ---
 
 ### Guest Checkout (Submit Order)
 
-Submit the local cart as an order with a **single API call**:
+> **Note:** `startGuestCheckout()` is the preferred method for guest checkout — it creates a full checkout session from the session cart. `submitGuestOrder()` still works as a simpler alternative for basic orders.
 
 ```typescript
 // Make sure cart has items, customer email, and shipping address
@@ -1279,7 +1134,7 @@ const order = await client.submitGuestOrder({ clearCartOnSuccess: false });
 
 #### Create Order with Custom Data
 
-If you manage cart state yourself instead of using local cart:
+If you manage cart state yourself instead of using the smart cart methods:
 
 ```typescript
 const order = await client.createGuestOrder({
@@ -1384,15 +1239,14 @@ type GuestCheckoutStartResponse =
 
 ---
 
-### Server Cart (Registered Users)
+### Server Cart (Low-Level API)
 
-For logged-in customers who want cart sync across devices.
+These low-level methods are available for advanced use cases. For most storefronts, use the `smart*` methods above instead.
 
 #### Create Cart
 
 ```typescript
 const cart = await client.createCart();
-setServerCartId(cart.id); // Save to localStorage
 ```
 
 #### Get Cart
@@ -1715,12 +1569,13 @@ For vibe-coded sites, the SDK provides payment integration with Stripe and PayPa
 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):
+// For GUEST users (session cart):
 const result = await client.startGuestCheckout();
 const checkoutId = result.checkoutId;
 
 // For LOGGED-IN users (server cart):
-const checkout = await client.createCheckout({ cartId: serverCartId });
+const cart = await client.smartGetCart();
+const checkout = await client.createCheckout({ cartId: cart.id });
 const checkoutId = checkout.id;
 
 // Then continue with shipping and payment...
@@ -1941,11 +1796,12 @@ if (status.status === 'succeeded' && status.orderId) {
 **How to get a checkout_id:**
 
 ```typescript
-// For GUEST users (local cart):
+// For GUEST users (session cart):
 const result = await client.startGuestCheckout();
 const checkoutId = result.checkoutId; // Use this!
 
 // For LOGGED-IN users (server cart):
+const cart = await client.smartGetCart();
 const checkout = await client.createCheckout({ cartId: cart.id });
 const checkoutId = checkout.id; // Use this!
 ```
@@ -2058,7 +1914,7 @@ function PaymentForm({ checkoutId }: { checkoutId: string }) {
 
 **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)
+> **WARNING:** Do NOT use `handlePaymentSuccess()` - it only clears cart state locally
 > and does NOT send the order to the server. Your customer will pay but no order will be created!
 
 ```typescript
@@ -2092,8 +1948,8 @@ export default function CheckoutSuccessPage() {
 **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 |
+| Guest (partial checkout) | Session cart | Creates order + removes only purchased items |
+| Guest (full checkout) | Session cart | Creates order + clears entire cart |
 | Logged-in | Server cart | Creates order + clears cart via SDK state |
 
 **Why is this needed?**
@@ -2452,10 +2308,7 @@ export default function LoginPage() {
   // 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);
-
+      // Session cart is preserved automatically via localStorage session token
       const { authorizationUrl, state } = await client.getOAuthAuthorizeUrl(
         provider as 'GOOGLE' | 'FACEBOOK' | 'GITHUB',
         { redirectUrl: window.location.origin + '/auth/callback' }
@@ -2979,7 +2832,7 @@ export default function ProductsPage() {
 }
 ```
 
-### Product Detail with Add to Cart (Local Cart)
+### Product Detail with Add to Cart
 
 ```typescript
 'use client';
@@ -3036,19 +2889,14 @@ export default function ProductPage({ params }: { params: { slug: string } }) {
     return product.salePrice || product.basePrice;
   };
 
-  const handleAddToCart = () => {
+  const handleAddToCart = async () => {
     if (!product) return;
 
-    // Add to local cart (NO API call!)
-    client.addToLocalCart({
+    // Add to cart (works for both guests and logged-in users)
+    await client.smartAddToCart({
       productId: product.id,
       variantId: selectedVariant?.id,
       quantity,
-      name: selectedVariant?.name
-        ? `${product.name} - ${selectedVariant.name}`
-        : product.name,
-      price: getDisplayPrice(),
-      image: getDisplayImage(),
     });
 
     alert('Added to cart!');
@@ -3170,39 +3018,35 @@ export default function ProductPage({ params }: { params: { slug: string } }) {
 }
 ```
 
-### Cart Page (Local Cart)
+### Cart Page
 
 ```typescript
 'use client';
 import { useState, useEffect } from 'react';
 import { client } from '@/lib/brainerce';
-import type { LocalCart } from 'brainerce';
+import { getCartTotals, formatPrice } from 'brainerce';
+import type { Cart } from 'brainerce';
 
 export default function CartPage() {
-  // ⚠️ Do NOT use useState(client.getLocalCart()) — causes hydration mismatch!
-  // Server has no localStorage (empty cart) but client does (cart with items).
-  const [cart, setCart] = useState<LocalCart>({ items: [], updatedAt: '' });
+  const [cart, setCart] = useState<Cart | null>(null);
+  const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    setCart(client.getLocalCart());
+    client.smartGetCart().then(setCart).finally(() => setLoading(false));
   }, []);
 
-  const updateQuantity = (productId: string, quantity: number, variantId?: string) => {
-    const updated = client.updateLocalCartItem(productId, quantity, variantId);
+  const updateQuantity = async (productId: string, quantity: number, variantId?: string) => {
+    const updated = await client.smartUpdateCartItem(productId, quantity, variantId);
     setCart(updated);
   };
 
-  const removeItem = (productId: string, variantId?: string) => {
-    const updated = client.removeFromLocalCart(productId, variantId);
+  const removeItem = async (productId: string, variantId?: string) => {
+    const updated = await client.smartRemoveFromCart(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) {
+  if (loading) return <div>Loading cart...</div>;
+  if (!cart || cart.items.length === 0) {
     return (
       <div className="text-center py-12">
         <h1 className="text-2xl font-bold">Your cart is empty</h1>
@@ -3211,43 +3055,46 @@ export default function CartPage() {
     );
   }
 
+  const totals = getCartTotals(cart);
+
   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">
+        <div key={item.id} className="flex items-center gap-4 py-4 border-b">
           <img
-            src={item.image || '/placeholder.jpg'}
-            alt={item.name || 'Product'}
+            src={item.product.images?.[0] || '/placeholder.jpg'}
+            alt={item.product.name}
             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>
+            <h3 className="font-medium">{item.product.name}</h3>
+            {item.variant && <p className="text-sm text-gray-500">{item.variant.name}</p>}
+            <p className="font-bold">${item.unitPrice}</p>
           </div>
           <div className="flex items-center gap-2">
             <button
-              onClick={() => updateQuantity(item.productId, item.quantity - 1, item.variantId)}
+              onClick={() => updateQuantity(item.productId, item.quantity - 1, item.variantId ?? undefined)}
               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)}
+              onClick={() => updateQuantity(item.productId, item.quantity + 1, item.variantId ?? undefined)}
               className="w-8 h-8 border rounded"
             >+</button>
           </div>
           <button
-            onClick={() => removeItem(item.productId, item.variantId)}
+            onClick={() => removeItem(item.productId, item.variantId ?? undefined)}
             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>
+        <p className="text-xl">Subtotal: <strong>${totals.subtotal.toFixed(2)}</strong></p>
+        {totals.discount > 0 && (
+          <p className="text-green-600">Discount: -${totals.discount.toFixed(2)}</p>
         )}
         <a
           href="/checkout"
@@ -3261,19 +3108,23 @@ export default function CartPage() {
 }
 ```
 
-### Universal Checkout (Handles Both Guest & Logged-In)
+### Checkout Page
 
-> **RECOMMENDED:** Use this pattern to properly handle both guest and logged-in customers in a single checkout page.
+> **RECOMMENDED:** Use this unified pattern — the `smart*` methods handle both guest and logged-in users.
 
 ```typescript
 'use client';
 import { useState, useEffect } from 'react';
-import { client, isLoggedIn, getServerCartId, setServerCartId, restoreCustomerToken } from '@/lib/brainerce';
+import { client, isLoggedIn, restoreCustomerToken } from '@/lib/brainerce';
+import type { Checkout, ShippingRate } from 'brainerce';
 
 export default function CheckoutPage() {
   const [loading, setLoading] = useState(true);
   const [submitting, setSubmitting] = useState(false);
-  const [customerLoggedIn, setCustomerLoggedIn] = useState(false);
+  const [checkout, setCheckout] = useState<Checkout | null>(null);
+  const [shippingRates, setShippingRates] = useState<ShippingRate[]>([]);
+  const [selectedRate, setSelectedRate] = useState<string | null>(null);
+  const customerLoggedIn = isLoggedIn();
 
   // Form state
   const [email, setEmail] = useState('');
@@ -3281,49 +3132,26 @@ export default function CheckoutPage() {
     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 client.createCart();
-          cartId = cart.id;
-          setServerCartId(cartId);
-
-          // Migrate local cart items to server cart
-          const localCart = client.getLocalCart();
-          for (const item of localCart.items) {
-            await client.addToCart(cartId, {
-              productId: item.productId,
-              variantId: item.variantId,
-              quantity: item.quantity,
-            });
+      try {
+        // startGuestCheckout() creates checkout from session cart (for guests)
+        // For logged-in users, create checkout from their server cart
+        if (customerLoggedIn) {
+          const cart = await client.smartGetCart();
+          const co = await client.createCheckout({ cartId: cart.id });
+          setCheckout(co);
+        } else {
+          const result = await client.startGuestCheckout();
+          if (result.tracked) {
+            const co = await client.getCheckout(result.checkoutId);
+            setCheckout(co);
           }
-          client.clearLocalCart(); // Clear local cart after migration
-        }
-
-        // Create checkout from server cart
-        const checkout = await client.createCheckout({ cartId });
-        setCheckoutId(checkout.id);
-
-        // Pre-fill from customer profile if available
-        try {
-          const profile = await client.getMyOrders({ limit: 1 }); // Just to check auth works
-        } catch (e) {
-          console.log('Could not fetch profile');
         }
+      } catch (err) {
+        console.error('Failed to initialize checkout:', err);
       }
       setLoading(false);
     }
@@ -3333,50 +3161,33 @@ export default function CheckoutPage() {
 
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
+    if (!checkout) return;
     setSubmitting(true);
 
     try {
-      if (customerLoggedIn && checkoutId) {
-        // ===== LOGGED-IN CUSTOMER: Server Checkout =====
-
-        // 1. Set customer info (REQUIRED - even for logged-in customers!)
-        await client.setCheckoutCustomer(checkoutId, {
-          email: email, // Get from form or customer profile
-          firstName: shippingAddress.firstName,
-          lastName: shippingAddress.lastName,
-        });
-
-        // 2. Set shipping address
-        await client.setShippingAddress(checkoutId, shippingAddress);
-
-        // 3. Get and select shipping rate
-        const rates = await client.getShippingRates(checkoutId);
-        if (rates.length > 0) {
-          await client.selectShippingMethod(checkoutId, selectedRate || rates[0].id);
-        }
-
-        // 4. Complete checkout - ORDER IS LINKED TO CUSTOMER!
-        const { orderId } = await client.completeCheckout(checkoutId);
-
-        // Clear cart ID
-        localStorage.removeItem('cartId');
+      // 1. Set customer info
+      await client.setCheckoutCustomer(checkout.id, {
+        email,
+        firstName: shippingAddress.firstName,
+        lastName: shippingAddress.lastName,
+      });
 
-        // Redirect to success page
-        window.location.href = `/order-success?orderId=${orderId}`;
+      // 2. Set shipping address
+      await client.setShippingAddress(checkout.id, shippingAddress);
 
-      } else {
-        // ===== GUEST: Local Cart + submitGuestOrder =====
+      // 3. Get and select shipping rate
+      const rates = await client.getShippingRates(checkout.id);
+      if (rates.length > 0) {
+        await client.selectShippingMethod(checkout.id, selectedRate || rates[0].id);
+      }
 
-        // Set customer and shipping info on local cart
-        client.setLocalCartCustomer({ email });
-        client.setLocalCartShippingAddress(shippingAddress);
+      // 4. Complete checkout
+      const { orderId } = await client.completeCheckout(checkout.id);
 
-        // Submit guest order (single API call)
-        const order = await client.submitGuestOrder();
+      // 5. Clean up
+      client.onCheckoutComplete();
 
-        // Redirect to success page
-        window.location.href = `/order-success?orderId=${order.orderId}`;
-      }
+      window.location.href = `/order-success?orderId=${orderId}`;
     } catch (error) {
       console.error('Checkout failed:', error);
       alert('Checkout failed. Please try again.');
@@ -3389,31 +3200,19 @@ export default function CheckoutPage() {
 
   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
-        />
+        <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 && (
+      {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>
+            <option key={rate.id} value={rate.id}>{rate.name} - ${rate.price}</option>
           ))}
         </select>
       )}
@@ -3421,12 +3220,6 @@ export default function CheckoutPage() {
       <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>
   );
 }
@@ -3434,207 +3227,21 @@ export default function CheckoutPage() {
 
 > **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 { client } from '@/lib/brainerce';
-import type { LocalCart, GuestOrderResponse } from 'brainerce';
-
-type Step = 'info' | 'review' | 'complete';
-
-export default function CheckoutPage() {
-  // ⚠️ Do NOT use useState(client.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 = client.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
-    client.setLocalCartCustomer({ email, firstName, lastName });
-    client.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 client.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>
-  );
-}
-```
+> - Both guests and logged-in users go through `createCheckout()` → `completeCheckout()`
+> - Guest session cart is created automatically by `smart*` methods
+> - Call `client.onCheckoutComplete()` after successful payment to clear the session cart
+> - Call `client.syncCartOnLogin()` when a user logs in to merge their guest cart
 
 ### 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.
+> **IMPORTANT:** This checkout pattern is ONLY for logged-in customers. For a checkout page that handles both guests and logged-in customers, see the "Checkout Page" 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 { client, getServerCartId } from '@/lib/brainerce';
+import { client } from '@/lib/brainerce';
 import type { Checkout, ShippingRate } from 'brainerce';
 
 type Step = 'customer' | 'shipping' | 'payment' | 'complete';
@@ -3657,13 +3264,13 @@ export default function CheckoutPage() {
 
   useEffect(() => {
     async function initCheckout() {
-      const cartId = getServerCartId();
-      if (!cartId) {
-        window.location.href = '/cart';
-        return;
-      }
       try {
-        const c = await client.createCheckout({ cartId });
+        const cart = await client.smartGetCart();
+        if (!cart || cart.items.length === 0) {
+          window.location.href = '/cart';
+          return;
+        }
+        const c = await client.createCheckout({ cartId: cart.id });
         setCheckout(c);
       } finally {
         setLoading(false);
@@ -3995,7 +3602,7 @@ export default function AccountPage() {
 }
 ```
 
-### Header Component with Cart Count (Local Cart)
+### Header Component with Cart Count
 
 ```typescript
 'use client';
@@ -4008,8 +3615,8 @@ export function Header() {
 
   useEffect(() => {
     setLoggedIn(isLoggedIn());
-    // Get cart count from local storage (NO API call!)
-    setCartCount(client.getLocalCartItemCount());
+    // Get cart count from session reference (no API call!)
+    setCartCount(client.getSmartCartItemCount());
   }, []);
 
   return (
@@ -4124,16 +3731,12 @@ import type {
   ProductQueryParams,
   PaginatedResponse,
 
-  // Local Cart (Guest Users)
-  LocalCart,
-  LocalCartItem,
-  CreateGuestOrderDto,
-  GuestOrderResponse,
-
-  // Server Cart (Registered Users)
+  // Cart (All Users)
   Cart,
   CartItem,
   AddToCartDto,
+  CreateGuestOrderDto,
+  GuestOrderResponse,
 
   // Checkout
   Checkout,
@@ -4246,7 +3849,7 @@ import { BrainerceError } from 'brainerce';
 // Add to cart with toast feedback
 const handleAddToCart = async (productId: string, quantity: number) => {
   try {
-    client.addToLocalCart({ productId, quantity });
+    await client.smartAddToCart({ productId, quantity });
     toast.success('Added to cart!');
   } catch (error) {
     if (error instanceof BrainerceError) {