omni-sync-sdk 0.22.1 → 0.22.3

package/AI_BUILDER_PROMPT.md

@@ -1,548 +1,563 @@
-# OmniSync Store Builder
-
-Build a **{store_type}** store called "{store_name}" | Style: **{style}** | Currency: **{currency}**
-
----
-
-## ⛔ STOP! Read These 3 Rules First (Breaking = Store Won't Work)
-
-### Rule 1: Guest vs Logged-In = Different Checkout Methods!
-
-```typescript
-// ❌ THIS WILL FAIL - "Cart not found" error!
-const cart = await omni.smartGetCart(); // Guest cart has id: "__local__"
-await omni.createCheckout({ cartId: cart.id }); // 💥 "__local__" doesn't exist on server!
-
-// ✅ CORRECT - Check user type first!
-if (omni.isCustomerLoggedIn()) {
-  // Logged-in user → server cart exists
-  const checkout = await omni.createCheckout({ cartId: cart.id });
-  const checkoutId = checkout.id;
-} else {
-  // Guest user → use startGuestCheckout()
-  const result = await omni.startGuestCheckout();
-  const checkoutId = result.checkoutId;
-}
-```
-
-| User Type     | Cart Location | Checkout Method              | Get Checkout ID     |
-| ------------- | ------------- | ---------------------------- | ------------------- |
-| **Guest**     | localStorage  | `startGuestCheckout()`       | `result.checkoutId` |
-| **Logged-in** | Server        | `createCheckout({ cartId })` | `checkout.id`       |
-
-### Rule 2: Complete Checkout & Clear Cart After Payment!
-
-```typescript
-// On /checkout/success page - MUST DO THIS!
-export default function CheckoutSuccessPage() {
-  const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
-
-  useEffect(() => {
-    if (checkoutId) {
-      // ⚠️ CRITICAL: This sends the order to the server AND clears the cart!
-      // handlePaymentSuccess() only clears the local cart - it does NOT create the order!
-      omni.completeGuestCheckout(checkoutId);
-    }
-  }, []);
-
-  return <div>Thank you for your order!</div>;
-}
-```
-
-> **WARNING:** Do NOT use `handlePaymentSuccess()` to complete an order. It only clears
-> the local cart (localStorage) and does NOT communicate with the server.
-> Always use `completeGuestCheckout()` after payment succeeds.
-
-### Rule 3: Never Hardcode Products!
-
-```typescript
-// ❌ FORBIDDEN - Store will show fake data!
-const products = [{ id: '1', name: 'T-Shirt', price: 29.99 }];
-
-// ✅ CORRECT - Fetch from API
-const { data: products } = await omni.getProducts();
-```
-
----
-
-## Quick Setup
-
-```bash
-npm install omni-sync-sdk
-```
-
-```typescript
-// lib/omni-sync.ts
-import { OmniSyncClient } from 'omni-sync-sdk';
-
-export const omni = new OmniSyncClient({
-  connectionId: '{connection_id}',
-  baseUrl: '{api_url}',
-});
-
-// Restore customer session on page load
-export function initOmniSync() {
-  if (typeof window === 'undefined') return;
-  const token = localStorage.getItem('customerToken');
-  if (token) omni.setCustomerToken(token);
-}
-
-// Save/clear customer token
-export function setCustomerToken(token: string | null) {
-  if (token) {
-    localStorage.setItem('customerToken', token);
-    omni.setCustomerToken(token);
-  } else {
-    localStorage.removeItem('customerToken');
-    omni.clearCustomerToken();
-  }
-}
-```
-
----
-
-## Cart (Works for Both Guest & Logged-in)
-
-```typescript
-// Get or create cart - handles both guest (localStorage) and logged-in (server) automatically
-const cart = await omni.smartGetCart();
-
-// Add to cart
-await omni.smartAddToCart({
-  productId: 'prod_xxx',
-  variantId: 'var_xxx', // optional, for products with variants
-  quantity: 1,
-});
-
-// Update quantity (by productId, not itemId!)
-await omni.smartUpdateCartItem('prod_xxx', 2); // productId, quantity
-await omni.smartUpdateCartItem('prod_xxx', 3, 'var_xxx'); // with variant
-
-// Remove item (by productId, not itemId!)
-await omni.smartRemoveFromCart('prod_xxx');
-await omni.smartRemoveFromCart('prod_xxx', 'var_xxx'); // with variant
-
-// Get cart totals (cart doesn't have .total field!)
-import { getCartTotals } from 'omni-sync-sdk';
-const totals = getCartTotals(cart);
-// { subtotal: 59.98, discount: 10, shipping: 0, total: 49.98 }
-
-// ⚠️ LocalCart vs Cart - KEY DIFFERENCES:
-// Server Cart has: id, itemCount, subtotal, discountAmount
-// Guest LocalCart has NONE of these! Only: items, couponCode, customer
-// To check type: if ('id' in cart) { /* server Cart */ } else { /* LocalCart */ }
-// Item count for both: cart.items.length
-```
-
----
-
-## 🛒 Partial Checkout (AliExpress Style) - REQUIRED!
-
-Cart page MUST have checkboxes so users can select which items to buy:
-
-```typescript
-// Cart page - track selected items
-const [selectedIndices, setSelectedIndices] = useState<number[]>(
-  cart.items.map((_, i) => i) // All selected by default
-);
-
-const toggleItem = (index: number) => {
-  setSelectedIndices(prev =>
-    prev.includes(index)
-      ? prev.filter(i => i !== index)
-      : [...prev, index]
-  );
-};
-
-const toggleAll = () => {
-  if (selectedIndices.length === cart.items.length) {
-    setSelectedIndices([]); // Deselect all
-  } else {
-    setSelectedIndices(cart.items.map((_, i) => i)); // Select all
-  }
-};
-
-// In your cart UI:
-<div>
-  <label>
-    <input
-      type="checkbox"
-      checked={selectedIndices.length === cart.items.length}
-      onChange={toggleAll}
-    />
-    Select All
-  </label>
-</div>
-
-{cart.items.map((item, index) => (
-  <div key={index}>
-    <input
-      type="checkbox"
-      checked={selectedIndices.includes(index)}
-      onChange={() => toggleItem(index)}
-    />
-    {/* ... item details ... */}
-  </div>
-))}
-
-// On checkout button - pass selected items!
-const handleCheckout = async () => {
-  if (selectedIndices.length === 0) {
-    alert('Please select items to checkout');
-    return;
-  }
-
-  const result = await omni.startGuestCheckout({ selectedIndices });
-  // Only selected items go to checkout, others stay in cart!
-};
-```
-
-**Why this matters:**
-
-- Users can buy some items now, leave others for later
-- After payment, `completeGuestCheckout()` sends the order and only removes purchased items
-- Remaining items stay in cart for future purchase
-
-**⚠️ Order Summary on Checkout Page - Use checkout.lineItems!**
-
-```typescript
-// ❌ WRONG - Shows ALL cart items (even unselected ones!)
-<div className="order-summary">
-  {cart.items.map(item => (
-    <div>{item.product.name} - ${item.price}</div>
-  ))}
-</div>
-
-// ✅ CORRECT - Shows only items being purchased in this checkout
-<div className="order-summary">
-  {checkout.lineItems.map(item => (
-    <div>{item.product.name} - ${item.price}</div>
-  ))}
-</div>
-```
-
-The `checkout` object's `lineItems` array contains ONLY the items selected for this checkout!
-
----
-
-## Complete Checkout Flow
-
-### Step 1: Start Checkout (Different for Guest vs Logged-in!)
-
-```typescript
-async function startCheckout() {
-  const cart = await omni.smartGetCart();
-
-  if (cart.items.length === 0) {
-    alert('Cart is empty');
-    return;
-  }
-
-  let checkoutId: string;
-
-  if (omni.isCustomerLoggedIn()) {
-    // Logged-in: create checkout from server cart
-    const checkout = await omni.createCheckout({ cartId: cart.id });
-    checkoutId = checkout.id;
-  } else {
-    // Guest: use startGuestCheckout (syncs local cart to server)
-    const result = await omni.startGuestCheckout();
-    if (!result.tracked || !result.checkoutId) {
-      throw new Error('Failed to create checkout');
-    }
-    checkoutId = result.checkoutId;
-  }
-
-  // Save for payment page
-  localStorage.setItem('checkoutId', checkoutId);
-
-  // Navigate to checkout
-  window.location.href = '/checkout';
-}
-```
-
-### Step 2: Shipping Address
-
-```typescript
-const checkoutId = localStorage.getItem('checkoutId')!;
-
-// Set shipping address (email is required!)
-const { checkout, rates } = await omni.setShippingAddress(checkoutId, {
-  email: 'customer@example.com',
-  firstName: 'John',
-  lastName: 'Doe',
-  line1: '123 Main St',
-  city: 'New York',
-  region: 'NY', // ⚠️ Use 'region', NOT 'state'!
-  postalCode: '10001',
-  country: 'US',
-});
-
-// Show available shipping rates
-rates.forEach((rate) => {
-  console.log(`${rate.name}: $${rate.price}`);
-});
-```
-
-### Step 3: Select Shipping Method
-
-```typescript
-await omni.selectShippingMethod(checkoutId, selectedRateId);
-```
-
-### Step 4: Payment with Stripe
-
-```typescript
-// Install: npm install @stripe/stripe-js @stripe/react-stripe-js
-
-// 1. Check if payment is configured
-const { hasPayments, providers } = await omni.getPaymentProviders();
-if (!hasPayments) {
-  return <div>Payment not configured for this store</div>;
-}
-
-// 2. Get Stripe config
-const stripeProvider = providers.find(p => p.provider === 'stripe');
-if (!stripeProvider) {
-  return <div>Stripe not configured</div>;
-}
-
-// 3. Create payment intent
-const intent = await omni.createPaymentIntent(checkoutId);
-
-// 4. Initialize Stripe
-import { loadStripe } from '@stripe/stripe-js';
-const stripe = await loadStripe(stripeProvider.publicKey, {
-  stripeAccount: stripeProvider.stripeAccountId,
-});
-
-// 5. Confirm payment (in your payment form)
-const { error } = await stripe.confirmPayment({
-  elements,
-  confirmParams: {
-    return_url: `${window.location.origin}/checkout/success?checkout_id=${checkoutId}`,
-  },
-});
-
-if (error) {
-  setError(error.message);
-}
-// If no error, Stripe redirects to success page
-```
-
-### Step 5: Success Page (Complete Order & Clear Cart!)
-
-```typescript
-// /checkout/success/page.tsx
-'use client';
-import { useEffect, useState } from 'react';
-import { omni } from '@/lib/omni-sync';
-
-export default function CheckoutSuccessPage() {
-  const [orderNumber, setOrderNumber] = useState<string>();
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
-
-    if (checkoutId) {
-      // ⚠️ CRITICAL: Complete the order on the server AND clear the cart!
-      // Do NOT use handlePaymentSuccess() - it only clears localStorage!
-      omni.completeGuestCheckout(checkoutId).then(result => {
-        setOrderNumber(result.orderNumber);
-        setLoading(false);
-      }).catch(() => {
-        // Order may already be completed (e.g., page refresh) - check status
-        omni.getPaymentStatus(checkoutId).then(status => {
-          if (status.orderNumber) {
-            setOrderNumber(status.orderNumber);
-          }
-          setLoading(false);
-        });
-      });
-    }
-  }, []);
-
-  return (
-    <div className="text-center py-12">
-      <h1 className="text-2xl font-bold text-green-600">Thank you for your order!</h1>
-      {loading && <p className="mt-2">Processing your order...</p>}
-      {orderNumber && <p className="mt-2">Order #{orderNumber}</p>}
-      <p className="mt-4">A confirmation email will be sent shortly.</p>
-    </div>
-  );
-}
-```
-
----
-
-## Partial Checkout (AliExpress Style)
-
-Allow customers to buy only some items from their cart:
-
-```typescript
-// Start checkout with only selected items (by index)
-const result = await omni.startGuestCheckout({
-  selectedIndices: [0, 2], // Buy items at index 0 and 2 only
-});
-
-// After payment, completeGuestCheckout() sends the order AND removes only those items!
-// Other items stay in cart.
-```
-
----
-
-## Products API
-
-```typescript
-// List products with pagination
-const { data: products, meta } = await omni.getProducts({
-  page: 1,
-  limit: 20,
-  search: 'blue shirt', // Searches name, description, SKU, categories, tags
-});
-// meta = { page: 1, limit: 20, total: 150, totalPages: 8 }
-
-// Get single product by slug (for product detail page)
-const product = await omni.getProductBySlug('blue-cotton-shirt');
-
-// Search suggestions (for autocomplete)
-const suggestions = await omni.getSearchSuggestions('blue', 5);
-// { products: [...], categories: [...] }
-```
-
----
-
-## Product Custom Fields (Metafields)
-
-Products may have custom fields defined by the store owner (e.g., "Material", "Care Instructions", "Warranty").
-
-```typescript
-import { getProductMetafield, getProductMetafieldValue } from 'omni-sync-sdk';
-
-// Access metafields on a product
-const product = await omni.getProductBySlug('blue-shirt');
-
-// Get all custom fields
-product.metafields?.forEach((field) => {
-  console.log(`${field.definitionName}: ${field.value}`);
-});
-
-// Get specific field by key
-const material = getProductMetafieldValue(product, 'material');
-const careInstructions = getProductMetafield(product, 'care_instructions');
-
-// Get available metafield definitions (schema)
-const { definitions } = await omni.getPublicMetafieldDefinitions();
-// Use definitions to build dynamic UI (filters, forms, etc.)
-```
-
-> **Tip:** `metafields` may be empty if the store hasn't defined custom fields. Always use optional chaining.
-
----
-
-## Customer Authentication
-
-```typescript
-// Register
-const { customer, token } = await omni.registerCustomer({
-  email: 'john@example.com',
-  password: 'securepass123',
-  firstName: 'John',
-  lastName: 'Doe',
-});
-setCustomerToken(token);
-
-// Login
-const { customer, token } = await omni.loginCustomer('john@example.com', 'password');
-setCustomerToken(token);
-
-// Logout
-setCustomerToken(null);
-
-// Get profile (requires token)
-const profile = await omni.getMyProfile();
-
-// Get order history
-const { data: orders, meta } = await omni.getMyOrders({ page: 1, limit: 10 });
-```
-
----
-
-## OAuth / Social Login
-
-```typescript
-// Get available providers for this store
-const { providers } = await omni.getAvailableOAuthProviders();
-// providers = ['GOOGLE', 'FACEBOOK', 'GITHUB']
-
-// Redirect to OAuth provider
-const { authorizationUrl } = await omni.getOAuthAuthorizeUrl('GOOGLE', {
-  redirectUrl: `${window.location.origin}/auth/callback`,
-});
-window.location.href = authorizationUrl;
-
-// Handle callback (on /auth/callback page)
-const code = new URLSearchParams(window.location.search).get('code');
-const state = new URLSearchParams(window.location.search).get('state');
-const { customer, token } = await omni.handleOAuthCallback('GOOGLE', code!, state!);
-setCustomerToken(token);
-```
-
----
-
-## Required Pages Checklist
-
-- [ ] **Home** (`/`) - Featured products grid
-- [ ] **Products** (`/products`) - Product list with infinite scroll
-- [ ] **Product Detail** (`/products/[slug]`) - Use `getProductBySlug(slug)`
-- [ ] **Cart** (`/cart`) - Show items, quantities, totals
-- [ ] **Checkout** (`/checkout`) - Address → Shipping → Payment
-- [ ] **Success** (`/checkout/success`) - **Must call `completeGuestCheckout()`!**
-- [ ] **Login** (`/login`) - Email/password + social buttons
-- [ ] **Register** (`/register`) - Registration form
-- [ ] **Account** (`/account`) - Profile + order history
-- [ ] **Header** - Logo, nav, cart icon with count, search
-
----
-
-## Common Type Gotchas
-
-```typescript
-// ❌ WRONG                          // ✅ CORRECT
-address.state                        address.region
-cart.total                           getCartTotals(cart).total
-cart.discount                        cart.discountAmount
-item.name (in cart)                  item.product.name
-response.url (OAuth)                 response.authorizationUrl
-providers.forEach (OAuth)            response.providers.forEach
-status === 'completed'               status === 'succeeded'
-product.metafields.name              product.metafields[0].definitionName
-product.metafields.key               product.metafields[0].definitionKey
-orderItem.unitPrice                  orderItem.price (OrderItem is FLAT, not nested!)
-cartItem.price                       cartItem.unitPrice (Cart/Checkout items use unitPrice)
-waitResult.orderNumber               waitResult.status.orderNumber (nested in PaymentStatus)
-variant.attributes.map(...)          Object.entries(variant.attributes || {}) (it's an object!)
-categorySuggestion.slug              // ❌ doesn't exist! Only: id, name, productCount
-order.status === 'COMPLETED'         order.status === 'delivered' (OrderStatus is lowercase!)
-getCartTotals(localCart)             // ❌ LocalCart has no subtotal! Calculate manually
-result.checkoutId (guest checkout)   // ⚠️ Check result.tracked first! It's a union type
-```
-
-**Key distinctions:**
-
-- **OrderItem** (from orders): Flat structure — `item.price`, `item.name`, `item.image`
-- **CartItem / CheckoutLineItem**: Nested structure — `item.unitPrice`, `item.product.name`, `item.product.images`
-- **`getCartTotals()`** only works with **server Cart** (has `subtotal`/`discountAmount`). For **LocalCart**, calculate manually:
-  ```typescript
-  const subtotal = cart.items.reduce((sum, item) => sum + parseFloat(item.price || '0') * item.quantity, 0);
-  ```
-- **`GuestCheckoutStartResponse`** is a union type — always check `result.tracked` before accessing `result.checkoutId`
-- **`WaitForOrderResult`** has `result.status.orderNumber`, NOT `result.orderNumber`. But `completeGuestCheckout()` returns `GuestOrderResponse` which DOES have `result.orderNumber` directly.
-
----
-
-## Full SDK Documentation
-
-For complete API reference and working code examples:
-**https://brainerce.com/docs/sdk**
+# OmniSync Store Builder
+
+Build a **{store_type}** store called "{store_name}" | Style: **{style}** | Currency: **{currency}**
+
+---
+
+## ⛔ STOP! Read These 3 Rules First (Breaking = Store Won't Work)
+
+### Rule 1: Guest vs Logged-In = Different Checkout Methods!
+
+```typescript
+// ❌ THIS WILL FAIL - "Cart not found" error!
+const cart = await omni.smartGetCart(); // Guest cart has id: "__local__"
+await omni.createCheckout({ cartId: cart.id }); // 💥 "__local__" doesn't exist on server!
+
+// ✅ CORRECT - Check user type first!
+if (omni.isCustomerLoggedIn()) {
+  // Logged-in user → server cart exists
+  const checkout = await omni.createCheckout({ cartId: cart.id });
+  const checkoutId = checkout.id;
+} else {
+  // Guest user → use startGuestCheckout()
+  const result = await omni.startGuestCheckout();
+  const checkoutId = result.checkoutId;
+}
+```
+
+| User Type     | Cart Location | Checkout Method              | Get Checkout ID     |
+| ------------- | ------------- | ---------------------------- | ------------------- |
+| **Guest**     | localStorage  | `startGuestCheckout()`       | `result.checkoutId` |
+| **Logged-in** | Server        | `createCheckout({ cartId })` | `checkout.id`       |
+
+### Rule 2: Complete Checkout & Clear Cart After Payment!
+
+```typescript
+// On /checkout/success page - MUST DO THIS!
+export default function CheckoutSuccessPage() {
+  const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
+
+  useEffect(() => {
+    if (checkoutId) {
+      // ⚠️ CRITICAL: This sends the order to the server AND clears the cart!
+      // handlePaymentSuccess() only clears the local cart - it does NOT create the order!
+      omni.completeGuestCheckout(checkoutId);
+    }
+  }, []);
+
+  return <div>Thank you for your order!</div>;
+}
+```
+
+> **WARNING:** Do NOT use `handlePaymentSuccess()` to complete an order. It only clears
+> the local cart (localStorage) and does NOT communicate with the server.
+> Always use `completeGuestCheckout()` after payment succeeds.
+
+### Rule 3: Never Hardcode Products!
+
+```typescript
+// ❌ FORBIDDEN - Store will show fake data!
+const products = [{ id: '1', name: 'T-Shirt', price: 29.99 }];
+
+// ✅ CORRECT - Fetch from API
+const { data: products } = await omni.getProducts();
+```
+
+---
+
+## Quick Setup
+
+```bash
+npm install omni-sync-sdk
+```
+
+```typescript
+// lib/omni-sync.ts
+import { OmniSyncClient } from 'omni-sync-sdk';
+
+export const omni = new OmniSyncClient({
+  connectionId: '{connection_id}',
+  baseUrl: '{api_url}',
+});
+
+// Restore customer session on page load
+export function initOmniSync() {
+  if (typeof window === 'undefined') return;
+  const token = localStorage.getItem('customerToken');
+  if (token) omni.setCustomerToken(token);
+}
+
+// Save/clear customer token
+export function setCustomerToken(token: string | null) {
+  if (token) {
+    localStorage.setItem('customerToken', token);
+    omni.setCustomerToken(token);
+  } else {
+    localStorage.removeItem('customerToken');
+    omni.clearCustomerToken();
+  }
+}
+```
+
+---
+
+## Cart (Works for Both Guest & Logged-in)
+
+```typescript
+// Get or create cart - handles both guest (localStorage) and logged-in (server) automatically
+const cart = await omni.smartGetCart();
+
+// Add to cart
+await omni.smartAddToCart({
+  productId: 'prod_xxx',
+  variantId: 'var_xxx', // optional, for products with variants
+  quantity: 1,
+});
+
+// Update quantity (by productId, not itemId!)
+await omni.smartUpdateCartItem('prod_xxx', 2); // productId, quantity
+await omni.smartUpdateCartItem('prod_xxx', 3, 'var_xxx'); // with variant
+
+// Remove item (by productId, not itemId!)
+await omni.smartRemoveFromCart('prod_xxx');
+await omni.smartRemoveFromCart('prod_xxx', 'var_xxx'); // with variant
+
+// Get cart totals (cart doesn't have .total field!)
+import { getCartTotals } from 'omni-sync-sdk';
+const totals = getCartTotals(cart);
+// { subtotal: 59.98, discount: 10, shipping: 0, total: 49.98 }
+
+// ⚠️ LocalCart vs Cart - KEY DIFFERENCES:
+// Server Cart has: id, itemCount, subtotal, discountAmount
+// Guest LocalCart has NONE of these! Only: items, couponCode, customer
+// To check type: if ('id' in cart) { /* server Cart */ } else { /* LocalCart */ }
+// Item count for both: cart.items.length
+```
+
+---
+
+## 🛒 Partial Checkout (AliExpress Style) - REQUIRED!
+
+Cart page MUST have checkboxes so users can select which items to buy:
+
+```typescript
+// Cart page - track selected items
+const [selectedIndices, setSelectedIndices] = useState<number[]>(
+  cart.items.map((_, i) => i) // All selected by default
+);
+
+const toggleItem = (index: number) => {
+  setSelectedIndices(prev =>
+    prev.includes(index)
+      ? prev.filter(i => i !== index)
+      : [...prev, index]
+  );
+};
+
+const toggleAll = () => {
+  if (selectedIndices.length === cart.items.length) {
+    setSelectedIndices([]); // Deselect all
+  } else {
+    setSelectedIndices(cart.items.map((_, i) => i)); // Select all
+  }
+};
+
+// In your cart UI:
+<div>
+  <label>
+    <input
+      type="checkbox"
+      checked={selectedIndices.length === cart.items.length}
+      onChange={toggleAll}
+    />
+    Select All
+  </label>
+</div>
+
+{cart.items.map((item, index) => (
+  <div key={index}>
+    <input
+      type="checkbox"
+      checked={selectedIndices.includes(index)}
+      onChange={() => toggleItem(index)}
+    />
+    {/* ... item details ... */}
+  </div>
+))}
+
+// On checkout button - pass selected items!
+const handleCheckout = async () => {
+  if (selectedIndices.length === 0) {
+    alert('Please select items to checkout');
+    return;
+  }
+
+  const result = await omni.startGuestCheckout({ selectedIndices });
+  // Only selected items go to checkout, others stay in cart!
+};
+```
+
+**Why this matters:**
+
+- Users can buy some items now, leave others for later
+- After payment, `completeGuestCheckout()` sends the order and only removes purchased items
+- Remaining items stay in cart for future purchase
+
+**⚠️ Order Summary on Checkout Page - Use checkout.lineItems!**
+
+```typescript
+// ❌ WRONG - Shows ALL cart items (even unselected ones!)
+<div className="order-summary">
+  {cart.items.map(item => (
+    <div>{item.product.name} - ${item.price}</div>
+  ))}
+</div>
+
+// ✅ CORRECT - Shows only items being purchased in this checkout
+<div className="order-summary">
+  {checkout.lineItems.map(item => (
+    <div>{item.product.name} - ${item.price}</div>
+  ))}
+</div>
+```
+
+The `checkout` object's `lineItems` array contains ONLY the items selected for this checkout!
+
+---
+
+## Complete Checkout Flow
+
+### Step 1: Start Checkout (Different for Guest vs Logged-in!)
+
+```typescript
+async function startCheckout() {
+  const cart = await omni.smartGetCart();
+
+  if (cart.items.length === 0) {
+    alert('Cart is empty');
+    return;
+  }
+
+  let checkoutId: string;
+
+  if (omni.isCustomerLoggedIn()) {
+    // Logged-in: create checkout from server cart
+    const checkout = await omni.createCheckout({ cartId: cart.id });
+    checkoutId = checkout.id;
+  } else {
+    // Guest: use startGuestCheckout (syncs local cart to server)
+    const result = await omni.startGuestCheckout();
+    if (!result.tracked || !result.checkoutId) {
+      throw new Error('Failed to create checkout');
+    }
+    checkoutId = result.checkoutId;
+  }
+
+  // Save for payment page
+  localStorage.setItem('checkoutId', checkoutId);
+
+  // Navigate to checkout
+  window.location.href = '/checkout';
+}
+```
+
+### Step 2: Shipping Address
+
+```typescript
+const checkoutId = localStorage.getItem('checkoutId')!;
+
+// Set shipping address (email is required!)
+const { checkout, rates } = await omni.setShippingAddress(checkoutId, {
+  email: 'customer@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  city: 'New York',
+  region: 'NY', // ⚠️ Use 'region', NOT 'state'!
+  postalCode: '10001',
+  country: 'US',
+});
+
+// Show available shipping rates
+rates.forEach((rate) => {
+  console.log(`${rate.name}: $${rate.price}`);
+});
+```
+
+### Step 3: Select Shipping Method
+
+```typescript
+await omni.selectShippingMethod(checkoutId, selectedRateId);
+```
+
+### Step 4: Payment with Stripe
+
+```typescript
+// Install: npm install @stripe/stripe-js @stripe/react-stripe-js
+
+// 1. Check if payment is configured
+const { hasPayments, providers } = await omni.getPaymentProviders();
+if (!hasPayments) {
+  return <div>Payment not configured for this store</div>;
+}
+
+// 2. Get Stripe config
+const stripeProvider = providers.find(p => p.provider === 'stripe');
+if (!stripeProvider) {
+  return <div>Stripe not configured</div>;
+}
+
+// 3. Create payment intent
+const intent = await omni.createPaymentIntent(checkoutId);
+
+// 4. Initialize Stripe
+import { loadStripe } from '@stripe/stripe-js';
+const stripe = await loadStripe(stripeProvider.publicKey, {
+  stripeAccount: stripeProvider.stripeAccountId,
+});
+
+// 5. Confirm payment (in your payment form)
+const { error } = await stripe.confirmPayment({
+  elements,
+  confirmParams: {
+    return_url: `${window.location.origin}/checkout/success?checkout_id=${checkoutId}`,
+  },
+});
+
+if (error) {
+  setError(error.message);
+}
+// If no error, Stripe redirects to success page
+```
+
+### Step 5: Success Page (Complete Order & Clear Cart!)
+
+```typescript
+// /checkout/success/page.tsx
+'use client';
+import { useEffect, useState } from 'react';
+import { omni } from '@/lib/omni-sync';
+
+export default function CheckoutSuccessPage() {
+  const [orderNumber, setOrderNumber] = useState<string>();
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
+
+    if (checkoutId) {
+      // ⚠️ CRITICAL: Complete the order on the server AND clear the cart!
+      // Do NOT use handlePaymentSuccess() - it only clears localStorage!
+      omni.completeGuestCheckout(checkoutId).then(result => {
+        setOrderNumber(result.orderNumber);
+        setLoading(false);
+      }).catch(() => {
+        // Order may already be completed (e.g., page refresh) - check status
+        omni.getPaymentStatus(checkoutId).then(status => {
+          if (status.orderNumber) {
+            setOrderNumber(status.orderNumber);
+          }
+          setLoading(false);
+        });
+      });
+    }
+  }, []);
+
+  return (
+    <div className="text-center py-12">
+      <h1 className="text-2xl font-bold text-green-600">Thank you for your order!</h1>
+      {loading && <p className="mt-2">Processing your order...</p>}
+      {orderNumber && <p className="mt-2">Order #{orderNumber}</p>}
+      <p className="mt-4">A confirmation email will be sent shortly.</p>
+    </div>
+  );
+}
+```
+
+---
+
+## Partial Checkout (AliExpress Style)
+
+Allow customers to buy only some items from their cart:
+
+```typescript
+// Start checkout with only selected items (by index)
+const result = await omni.startGuestCheckout({
+  selectedIndices: [0, 2], // Buy items at index 0 and 2 only
+});
+
+// After payment, completeGuestCheckout() sends the order AND removes only those items!
+// Other items stay in cart.
+```
+
+---
+
+## Products API
+
+```typescript
+// List products with pagination
+const { data: products, meta } = await omni.getProducts({
+  page: 1,
+  limit: 20,
+  search: 'blue shirt', // Searches name, description, SKU, categories, tags
+});
+// meta = { page: 1, limit: 20, total: 150, totalPages: 8 }
+
+// Get single product by slug (for product detail page)
+const product = await omni.getProductBySlug('blue-cotton-shirt');
+
+// Search suggestions (for autocomplete)
+const suggestions = await omni.getSearchSuggestions('blue', 5);
+// { products: [...], categories: [...] }
+```
+
+---
+
+## Product Custom Fields (Metafields)
+
+Products may have custom fields defined by the store owner (e.g., "Material", "Care Instructions", "Warranty").
+
+```typescript
+import { getProductMetafield, getProductMetafieldValue } from 'omni-sync-sdk';
+
+// Access metafields on a product
+const product = await omni.getProductBySlug('blue-shirt');
+
+// Get all custom fields
+product.metafields?.forEach((field) => {
+  console.log(`${field.definitionName}: ${field.value}`);
+});
+
+// Get specific field by key
+const material = getProductMetafieldValue(product, 'material');
+const careInstructions = getProductMetafield(product, 'care_instructions');
+
+// Get available metafield definitions (schema)
+const { definitions } = await omni.getPublicMetafieldDefinitions();
+// Use definitions to build dynamic UI (filters, forms, etc.)
+```
+
+> **Tip:** `metafields` may be empty if the store hasn't defined custom fields. Always use optional chaining.
+
+---
+
+## Customer Authentication
+
+```typescript
+// Register
+const { customer, token } = await omni.registerCustomer({
+  email: 'john@example.com',
+  password: 'securepass123',
+  firstName: 'John',
+  lastName: 'Doe',
+});
+setCustomerToken(token);
+
+// Login
+const { customer, token } = await omni.loginCustomer('john@example.com', 'password');
+setCustomerToken(token);
+
+// Logout
+setCustomerToken(null);
+
+// Get profile (requires token)
+const profile = await omni.getMyProfile();
+
+// Get order history
+const { data: orders, meta } = await omni.getMyOrders({ page: 1, limit: 10 });
+```
+
+---
+
+## OAuth / Social Login
+
+```typescript
+// Get available providers for this store
+const { providers } = await omni.getAvailableOAuthProviders();
+// providers = ['GOOGLE', 'FACEBOOK', 'GITHUB']
+
+// Redirect to OAuth provider
+const { authorizationUrl } = await omni.getOAuthAuthorizeUrl('GOOGLE', {
+  redirectUrl: `${window.location.origin}/auth/callback`,
+});
+window.location.href = authorizationUrl;
+
+// Handle callback (on /auth/callback page)
+const code = new URLSearchParams(window.location.search).get('code');
+const state = new URLSearchParams(window.location.search).get('state');
+const { customer, token } = await omni.handleOAuthCallback('GOOGLE', code!, state!);
+setCustomerToken(token);
+```
+
+---
+
+## Required Pages Checklist
+
+- [ ] **Home** (`/`) - Featured products grid
+- [ ] **Products** (`/products`) - Product list with infinite scroll
+- [ ] **Product Detail** (`/products/[slug]`) - Use `getProductBySlug(slug)`
+- [ ] **Cart** (`/cart`) - Show items, quantities, totals
+- [ ] **Checkout** (`/checkout`) - Address → Shipping → Payment
+- [ ] **Success** (`/checkout/success`) - **Must call `completeGuestCheckout()`!**
+- [ ] **Login** (`/login`) - Email/password + social buttons
+- [ ] **Register** (`/register`) - Registration form
+- [ ] **Account** (`/account`) - Profile + order history
+- [ ] **Header** - Logo, nav, cart icon with count, search
+
+---
+
+## Common Type Gotchas
+
+```typescript
+// ❌ WRONG                          // ✅ CORRECT
+address.state                        address.region
+cart.total                           getCartTotals(cart).total
+cart.discount                        cart.discountAmount
+item.name (in cart)                  item.product.name
+response.url (OAuth)                 response.authorizationUrl
+providers.forEach (OAuth)            response.providers.forEach
+status === 'completed'               status === 'succeeded'
+product.metafields.name              product.metafields[0].definitionName
+product.metafields.key               product.metafields[0].definitionKey
+orderItem.unitPrice                  orderItem.price (OrderItem is FLAT, not nested!)
+cartItem.price                       cartItem.unitPrice (Cart/Checkout items use unitPrice)
+waitResult.orderNumber               waitResult.status.orderNumber (nested in PaymentStatus)
+variant.attributes.map(...)          Object.entries(variant.attributes || {}) (it's an object!)
+categorySuggestion.slug              // ❌ doesn't exist! Only: id, name, productCount
+order.status === 'COMPLETED'         order.status === 'delivered' (OrderStatus is lowercase!)
+getCartTotals(localCart)             // ❌ LocalCart has no subtotal! Calculate manually
+result.checkoutId (guest checkout)   // ⚠️ Check result.tracked first! It's a union type
+```
+
+**Key distinctions:**
+
+- **OrderItem** (from orders): Flat structure — `item.price`, `item.name`, `item.image`
+- **CartItem / CheckoutLineItem**: Nested structure — `item.unitPrice`, `item.product.name`, `item.product.images`
+- **`getCartTotals()`** only works with **server Cart** (has `subtotal`/`discountAmount`). For **LocalCart**, calculate manually:
+  ```typescript
+  const subtotal = cart.items.reduce(
+    (sum, item) => sum + parseFloat(item.price || '0') * item.quantity,
+    0
+  );
+  ```
+- **`GuestCheckoutStartResponse`** is a union type — always check `result.tracked` before accessing `result.checkoutId`
+- **`WaitForOrderResult`** has `result.status.orderNumber`, NOT `result.orderNumber`. But `completeGuestCheckout()` returns `GuestOrderResponse` which DOES have `result.orderNumber` directly.
+- **⚠️ HYDRATION: Never use `useState(omni.getLocalCart())`** in Next.js — causes hydration mismatch! Server has no localStorage (empty cart) but client does (real cart). Always start with empty state and load in `useEffect`:
+
+  ```typescript
+  // ❌ WRONG — hydration mismatch!
+  const [cart, setCart] = useState(omni.getLocalCart());
+
+  // ✅ CORRECT — load after hydration
+  const [cart, setCart] = useState<LocalCart>({ items: [], updatedAt: '' });
+  useEffect(() => {
+    setCart(omni.getLocalCart());
+  }, []);
+  ```
+
+---
+
+## Full SDK Documentation
+
+For complete API reference and working code examples:
+**https://brainerce.com/docs/sdk**