omni-sync-sdk 0.2.0 → 0.4.0

package/README.md

@@ -1,191 +1,1430 @@
-# @omni-sync/sdk
-
-SDK for integrating vibe coding stores with Omni-Sync Platform.
-
-## Installation
-
-```bash
-npm install @omni-sync/sdk
-# or
-pnpm add @omni-sync/sdk
-# or
-yarn add @omni-sync/sdk
-```
-
-## Quick Start
-
-```typescript
-import { OmniSyncClient } from '@omni-sync/sdk';
-
-const omni = new OmniSyncClient({
-  apiKey: process.env.OMNI_SYNC_API_KEY!,
-});
-
-// Get products
-const { data: products } = await omni.getProducts();
-
-// Create an order
-const order = await omni.createOrder({
-  items: [
-    { productId: products[0].id, quantity: 2, price: 99.99 }
-  ],
-  customer: { email: 'customer@example.com', name: 'John Doe' },
-  totalAmount: 199.98,
-});
-```
-
-## Products
-
-```typescript
-// List products with pagination
-const { data, meta } = await omni.getProducts({
-  page: 1,
-  limit: 20,
-  status: 'active',
-  search: 'shirt',
-});
-
-// Get single product
-const product = await omni.getProduct('prod_123');
-
-// Create product
-const newProduct = await omni.createProduct({
-  name: 'Blue T-Shirt',
-  sku: 'TSHIRT-BLUE-M',
-  basePrice: 29.99,
-  status: 'active',
-});
-
-// Update product
-const updated = await omni.updateProduct('prod_123', {
-  salePrice: 24.99,
-});
-
-// Delete product
-await omni.deleteProduct('prod_123');
-```
-
-## Orders
-
-```typescript
-// Create order (auto-deducts inventory, syncs to all platforms)
-const order = await omni.createOrder({
-  items: [
-    { productId: 'prod_123', quantity: 1, price: 29.99 },
-    { productId: 'prod_456', quantity: 2, price: 49.99 },
-  ],
-  customer: {
-    email: 'john@example.com',
-    name: 'John Doe',
-    phone: '+1234567890',
-  },
-  totalAmount: 129.97,
-});
-
-// List orders
-const { data: orders } = await omni.getOrders({
-  status: 'pending',
-});
-
-// Update order status
-await omni.updateOrder('order_123', { status: 'shipped' });
-```
-
-## Inventory
-
-```typescript
-// Get current inventory
-const inventory = await omni.getInventory('prod_123');
-console.log(`Available: ${inventory.available}`);
-
-// Update inventory (syncs to all platforms)
-await omni.updateInventory('prod_123', { quantity: 50 });
-```
-
-## Webhooks
-
-Receive real-time updates when products, orders, or inventory change on any connected platform.
-
-### Setup webhook endpoint
-
-```typescript
-// api/webhooks/omni-sync/route.ts (Next.js App Router)
-import { verifyWebhook, createWebhookHandler } from '@omni-sync/sdk';
-
-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 |
-
-## Environment Variables
-
-```env
-OMNI_SYNC_API_KEY=omni_your_api_key_here
-OMNI_SYNC_WEBHOOK_SECRET=your_webhook_secret_here
-```
-
-## Error Handling
-
-```typescript
-import { OmniSyncClient, OmniSyncError } from '@omni-sync/sdk';
-
-try {
-  const product = await omni.getProduct('invalid_id');
-} catch (error) {
-  if (error instanceof OmniSyncError) {
-    console.error(`API Error: ${error.message} (${error.statusCode})`);
-  }
-}
-```
-
-## TypeScript Support
-
-Full TypeScript support with exported types:
-
-```typescript
-import type { 
-  Product, 
-  Order, 
-  CreateProductDto,
-  WebhookEvent 
-} from '@omni-sync/sdk';
-```
-
-## License
-
-MIT
+# omni-sync-sdk
+
+Official SDK for building e-commerce storefronts with **OmniSync Platform**.
+
+This SDK provides a complete solution for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts to connect to OmniSync's unified commerce API.
+
+## Installation
+
+```bash
+npm install omni-sync-sdk
+# or
+pnpm add omni-sync-sdk
+# or
+yarn add omni-sync-sdk
+```
+
+---
+
+## Quick Start
+
+### For Vibe-Coded Sites (Recommended)
+
+```typescript
+import { OmniSyncClient } from 'omni-sync-sdk';
+
+// Initialize with your Connection ID
+const omni = new OmniSyncClient({
+  connectionId: 'vc_YOUR_CONNECTION_ID',
+});
+
+// Fetch products
+const { data: products } = await omni.getProducts();
+
+// Create a cart
+const cart = await omni.createCart();
+
+// Add item to cart
+await omni.addToCart(cart.id, {
+  productId: products[0].id,
+  quantity: 1,
+});
+```
+
+---
+
+## Complete Store Setup
+
+### Step 1: Create the OmniSync Client
+
+Create a file `lib/omni-sync.ts`:
+
+```typescript
+import { OmniSyncClient } from 'omni-sync-sdk';
+
+export const omni = new OmniSyncClient({
+  connectionId: 'vc_YOUR_CONNECTION_ID', // Your Connection ID from OmniSync
+});
+
+// ----- Cart Helpers -----
+
+export function getCartId(): string | null {
+  if (typeof window === 'undefined') return null;
+  return localStorage.getItem('cartId');
+}
+
+export function setCartId(id: string): void {
+  localStorage.setItem('cartId', id);
+}
+
+export function clearCartId(): 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');
+}
+```
+
+---
+
+## API Reference
+
+### Products
+
+#### Get Products (with pagination)
+
+```typescript
+import { omni } from '@/lib/omni-sync';
+import type { Product, PaginatedResponse } from 'omni-sync-sdk';
+
+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 }
+```
+
+#### Product Type Definition
+
+```typescript
+interface Product {
+  id: string;
+  name: string;
+  description?: string | null;
+  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;
+}
+```
+
+---
+
+### Cart
+
+#### Create Cart
+
+```typescript
+const cart = await omni.createCart();
+setCartId(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,
+});
+```
+
+#### 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;
+}
+```
+
+---
+
+### Customer Authentication
+
+#### Register Customer
+
+```typescript
+const auth = await omni.registerCustomer({
+  email: 'customer@example.com',
+  password: 'securepassword123',
+  firstName: 'John',
+  lastName: 'Doe',
+});
+
+setCustomerToken(auth.token);
+console.log('Registered:', auth.customer.email);
+```
+
+#### Login Customer
+
+```typescript
+const auth = await omni.loginCustomer('customer@example.com', 'password123');
+setCustomerToken(auth.token);
+```
+
+#### Logout Customer
+
+```typescript
+setCustomerToken(null);
+```
+
+#### 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;
+}
+```
+
+---
+
+### 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.
+```
+
+---
+
+## Complete Page Examples
+
+### Home Page
+
+```typescript
+'use client';
+import { useEffect, useState } from 'react';
+import { omni } from '@/lib/omni-sync';
+import type { Product } from 'omni-sync-sdk';
+
+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.id}`} 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/omni-sync';
+import type { Product, PaginatedResponse } from 'omni-sync-sdk';
+
+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.id}`}>
+            <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
+
+```typescript
+'use client';
+import { useEffect, useState } from 'react';
+import { omni, getCartId, setCartId } from '@/lib/omni-sync';
+import type { Product } from 'omni-sync-sdk';
+
+export default function ProductPage({ params }: { params: { id: string } }) {
+  const [product, setProduct] = useState<Product | null>(null);
+  const [selectedVariant, setSelectedVariant] = useState<string | null>(null);
+  const [quantity, setQuantity] = useState(1);
+  const [loading, setLoading] = useState(true);
+  const [adding, setAdding] = useState(false);
+
+  useEffect(() => {
+    async function load() {
+      try {
+        const p = await omni.getProduct(params.id);
+        setProduct(p);
+        if (p.variants && p.variants.length > 0) {
+          setSelectedVariant(p.variants[0].id);
+        }
+      } finally {
+        setLoading(false);
+      }
+    }
+    load();
+  }, [params.id]);
+
+  const handleAddToCart = async () => {
+    if (!product) return;
+    setAdding(true);
+    try {
+      let cartId = getCartId();
+
+      if (!cartId) {
+        const cart = await omni.createCart();
+        cartId = cart.id;
+        setCartId(cartId);
+      }
+
+      await omni.addToCart(cartId, {
+        productId: product.id,
+        variantId: selectedVariant || undefined,
+        quantity,
+      });
+
+      alert('Added to cart!');
+    } catch (err) {
+      alert('Failed to add to cart');
+    } finally {
+      setAdding(false);
+    }
+  };
+
+  if (loading) return <div>Loading...</div>;
+  if (!product) return <div>Product not found</div>;
+
+  return (
+    <div className="grid grid-cols-2 gap-8">
+      {/* Images */}
+      <div>
+        <img
+          src={product.images?.[0]?.url || '/placeholder.jpg'}
+          alt={product.name}
+          className="w-full"
+        />
+      </div>
+
+      {/* Details */}
+      <div>
+        <h1 className="text-3xl font-bold">{product.name}</h1>
+        <p className="text-2xl mt-4">
+          ${product.salePrice || product.basePrice}
+        </p>
+
+        {product.description && (
+          <p className="mt-4 text-gray-600">{product.description}</p>
+        )}
+
+        {/* Variant Selection */}
+        {product.variants && product.variants.length > 0 && (
+          <div className="mt-6">
+            <label className="block font-medium mb-2">Select Option</label>
+            <select
+              value={selectedVariant || ''}
+              onChange={(e) => setSelectedVariant(e.target.value)}
+              className="border rounded p-2 w-full"
+            >
+              {product.variants.map((v) => (
+                <option key={v.id} value={v.id}>
+                  {v.name || v.sku} - ${v.price || product.basePrice}
+                </option>
+              ))}
+            </select>
+          </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 */}
+        {product.inventory && (
+          <p className="mt-4 text-sm">
+            {product.inventory.available > 0
+              ? `${product.inventory.available} in stock`
+              : 'Out of stock'}
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### Cart Page
+
+```typescript
+'use client';
+import { useEffect, useState } from 'react';
+import { omni, getCartId } from '@/lib/omni-sync';
+import type { Cart } from 'omni-sync-sdk';
+
+export default function CartPage() {
+  const [cart, setCart] = useState<Cart | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [updating, setUpdating] = useState<string | null>(null);
+
+  const loadCart = async () => {
+    const cartId = getCartId();
+    if (!cartId) {
+      setLoading(false);
+      return;
+    }
+    try {
+      const c = await omni.getCart(cartId);
+      setCart(c);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => { loadCart(); }, []);
+
+  const updateQuantity = async (itemId: string, quantity: number) => {
+    if (!cart) return;
+    setUpdating(itemId);
+    try {
+      if (quantity <= 0) {
+        await omni.removeCartItem(cart.id, itemId);
+      } else {
+        await omni.updateCartItem(cart.id, itemId, { quantity });
+      }
+      await loadCart();
+    } finally {
+      setUpdating(null);
+    }
+  };
+
+  const removeItem = async (itemId: string) => {
+    if (!cart) return;
+    setUpdating(itemId);
+    try {
+      await omni.removeCartItem(cart.id, itemId);
+      await loadCart();
+    } finally {
+      setUpdating(null);
+    }
+  };
+
+  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>
+        <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.id} className="flex items-center gap-4 py-4 border-b">
+          <img
+            src={item.product.images?.[0]?.url || '/placeholder.jpg'}
+            alt={item.product.name}
+            className="w-20 h-20 object-cover"
+          />
+          <div className="flex-1">
+            <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.id, item.quantity - 1)}
+              disabled={updating === item.id}
+              className="w-8 h-8 border rounded"
+            >-</button>
+            <span className="w-8 text-center">{item.quantity}</span>
+            <button
+              onClick={() => updateQuantity(item.id, item.quantity + 1)}
+              disabled={updating === item.id}
+              className="w-8 h-8 border rounded"
+            >+</button>
+          </div>
+          <button
+            onClick={() => removeItem(item.id)}
+            disabled={updating === item.id}
+            className="text-red-600"
+          >Remove</button>
+        </div>
+      ))}
+
+      <div className="mt-6 text-right">
+        <p className="text-xl">Subtotal: <strong>${cart.subtotal}</strong></p>
+        {cart.discountAmount && Number(cart.discountAmount) > 0 && (
+          <p className="text-green-600">Discount: -${cart.discountAmount}</p>
+        )}
+        <a
+          href="/checkout"
+          className="mt-4 inline-block bg-black text-white px-8 py-3 rounded"
+        >
+          Proceed to Checkout
+        </a>
+      </div>
+    </div>
+  );
+}
+```
+
+### Multi-Step Checkout
+
+```typescript
+'use client';
+import { useEffect, useState } from 'react';
+import { omni, getCartId, clearCartId } from '@/lib/omni-sync';
+import type { Checkout, ShippingRate } from 'omni-sync-sdk';
+
+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 = getCartId();
+      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);
+      clearCartId();
+      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 } from 'react';
+import { omni, setCustomerToken } from '@/lib/omni-sync';
+
+export default function LoginPage() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [error, setError] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    setError('');
+    try {
+      const auth = await omni.loginCustomer(email, password);
+      setCustomerToken(auth.token);
+      window.location.href = '/account';
+    } 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 } from 'react';
+import { omni, setCustomerToken } from '@/lib/omni-sync';
+
+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);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    setError('');
+    try {
+      const auth = await omni.registerCustomer({ email, password, firstName, lastName });
+      setCustomerToken(auth.token);
+      window.location.href = '/account';
+    } 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/omni-sync';
+import type { CustomerProfile, Order } from 'omni-sync-sdk';
+
+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
+
+```typescript
+'use client';
+import { useEffect, useState } from 'react';
+import { omni, getCartId, isLoggedIn } from '@/lib/omni-sync';
+
+export function Header() {
+  const [cartCount, setCartCount] = useState(0);
+  const [loggedIn, setLoggedIn] = useState(false);
+
+  useEffect(() => {
+    setLoggedIn(isLoggedIn());
+
+    async function loadCart() {
+      const cartId = getCartId();
+      if (cartId) {
+        try {
+          const cart = await omni.getCart(cartId);
+          setCartCount(cart.itemCount);
+        } catch {}
+      }
+    }
+    loadCart();
+  }, []);
+
+  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 { OmniSyncClient, OmniSyncError } from 'omni-sync-sdk';
+
+try {
+  const product = await omni.getProduct('invalid_id');
+} catch (error) {
+  if (error instanceof OmniSyncError) {
+    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/omni-sync/route.ts (Next.js App Router)
+import { verifyWebhook, createWebhookHandler } from 'omni-sync-sdk';
+
+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,
+
+  // Cart
+  Cart,
+  CartItem,
+  AddToCartDto,
+
+  // Checkout
+  Checkout,
+  CheckoutStatus,
+  ShippingRate,
+  SetShippingAddressDto,
+
+  // Customer
+  Customer,
+  CustomerProfile,
+  CustomerAddress,
+  CustomerAuthResponse,
+
+  // Orders
+  Order,
+  OrderStatus,
+  OrderItem,
+
+  // Webhooks
+  WebhookEvent,
+  WebhookEventType,
+
+  // Errors
+  OmniSyncError,
+} from 'omni-sync-sdk';
+```
+
+---
+
+## Environment Variables
+
+```env
+# Required for vibe-coded sites
+NEXT_PUBLIC_OMNI_CONNECTION_ID=vc_your_connection_id
+
+# Optional: Override API URL (default: https://api.omni-sync.com)
+NEXT_PUBLIC_OMNI_API_URL=https://api.omni-sync.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/[id]`) - Single product with Add to Cart
+- [ ] **Cart** (`/cart`) - Cart items, update quantity, remove
+- [ ] **Checkout** (`/checkout`) - Multi-step checkout flow
+- [ ] **Login** (`/login`) - Customer login
+- [ ] **Register** (`/register`) - Customer registration
+- [ ] **Account** (`/account`) - Profile and order history
+
+---
+
+## Important Rules
+
+### DO:
+- Install `omni-sync-sdk` and use it for ALL data
+- Import types from the SDK
+- Handle loading states and errors
+- Persist cart ID in localStorage
+- Persist customer token after login
+
+### DON'T:
+- Create mock/hardcoded product data
+- Use localStorage for products
+- Skip implementing required pages
+- Write `const products = [...]` - use the API!
+
+---
+
+## License
+
+MIT