omni-sync-sdk 0.4.1 → 0.6.1

package/README.md

@@ -31,14 +31,75 @@ const omni = new OmniSyncClient({
 // Fetch products
 const { data: products } = await omni.getProducts();
 
-// Create a cart
-const cart = await omni.createCart();
+// ===== GUEST CHECKOUT (Recommended for most sites) =====
+// Cart stored locally - NO API calls until checkout!
 
-// Add item to cart
-await omni.addToCart(cart.id, {
+// Add to local cart (stored in localStorage)
+omni.addToLocalCart({
   productId: products[0].id,
   quantity: 1,
+  name: products[0].name,
+  price: String(products[0].basePrice),
+});
+
+// Set customer info
+omni.setLocalCartCustomer({ email: 'customer@example.com' });
+omni.setLocalCartShippingAddress({
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  city: 'New York',
+  postalCode: '10001',
+  country: 'US',
 });
+
+// Submit order (single API call!)
+const order = await omni.submitGuestOrder();
+console.log('Order created:', order.orderId);
+```
+
+---
+
+## Two Ways to Handle Cart
+
+### Option 1: Local Cart (Guest Users) - RECOMMENDED
+
+For guest users, the cart is stored in **localStorage** - exactly like Amazon, Shopify, and other major platforms do. This means:
+
+- ✅ No API calls when browsing/adding to cart
+- ✅ Cart persists across page refreshes
+- ✅ Single API call at checkout
+- ✅ No server load for window shoppers
+
+```typescript
+// Add product to local cart
+omni.addToLocalCart({ productId: 'prod_123', quantity: 2 });
+
+// View cart
+const cart = omni.getLocalCart();
+console.log('Items:', cart.items.length);
+
+// Update quantity
+omni.updateLocalCartItem('prod_123', 5);
+
+// Remove item
+omni.removeFromLocalCart('prod_123');
+
+// At checkout - submit everything in ONE API call
+const order = await omni.submitGuestOrder();
+```
+
+### Option 2: Server Cart (Registered Users)
+
+For logged-in customers, use server-side cart:
+
+- ✅ Cart syncs across devices
+- ✅ Abandoned cart recovery
+- ✅ Customer history tracking
+
+```typescript
+const cart = await omni.createCart();
+await omni.addToCart(cart.id, { productId: 'prod_123', quantity: 2 });
 ```
 
 ---
@@ -56,18 +117,28 @@ export const omni = new OmniSyncClient({
   connectionId: 'vc_YOUR_CONNECTION_ID', // Your Connection ID from OmniSync
 });
 
-// ----- Cart Helpers -----
+// ----- Guest Cart Helpers (localStorage) -----
+
+export function getCartItemCount(): number {
+  return omni.getLocalCartItemCount();
+}
+
+export function getCart() {
+  return omni.getLocalCart();
+}
 
-export function getCartId(): string | null {
+// ----- For Registered Users (server cart) -----
+
+export function getServerCartId(): string | null {
   if (typeof window === 'undefined') return null;
   return localStorage.getItem('cartId');
 }
 
-export function setCartId(id: string): void {
+export function setServerCartId(id: string): void {
   localStorage.setItem('cartId', id);
 }
 
-export function clearCartId(): void {
+export function clearServerCartId(): void {
   localStorage.removeItem('cartId');
 }
 
@@ -180,13 +251,236 @@ interface InventoryInfo {
 
 ---
 
-### Cart
+### Local Cart (Guest Users) - RECOMMENDED
+
+The local cart stores everything in **localStorage** until checkout. This is the recommended approach for most storefronts.
+
+#### Add to Local Cart
+
+```typescript
+// Add item with product info (for display)
+omni.addToLocalCart({
+  productId: 'prod_123',
+  variantId: 'var_456', // Optional: for products with variants
+  quantity: 2,
+  name: 'Cool T-Shirt', // Optional: for cart display
+  price: '29.99', // Optional: for cart display
+  image: 'https://...', // Optional: for cart display
+});
+```
+
+#### Get Local Cart
+
+```typescript
+const cart = omni.getLocalCart();
+
+console.log(cart.items); // Array of cart items
+console.log(cart.customer); // Customer info (if set)
+console.log(cart.shippingAddress); // Shipping address (if set)
+console.log(cart.couponCode); // Applied coupon (if any)
+```
+
+#### Update Item Quantity
+
+```typescript
+// Set quantity to 5
+omni.updateLocalCartItem('prod_123', 5);
+
+// For variant products
+omni.updateLocalCartItem('prod_123', 3, 'var_456');
+
+// Set to 0 to remove
+omni.updateLocalCartItem('prod_123', 0);
+```
+
+#### Remove Item
+
+```typescript
+omni.removeFromLocalCart('prod_123');
+omni.removeFromLocalCart('prod_123', 'var_456'); // With variant
+```
+
+#### Clear Cart
+
+```typescript
+omni.clearLocalCart();
+```
+
+#### Set Customer Info
+
+```typescript
+omni.setLocalCartCustomer({
+  email: 'customer@example.com', // Required
+  firstName: 'John', // Optional
+  lastName: 'Doe', // Optional
+  phone: '+1234567890', // Optional
+});
+```
+
+#### Set Shipping Address
+
+```typescript
+omni.setLocalCartShippingAddress({
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  line2: 'Apt 4B', // Optional
+  city: 'New York',
+  region: 'NY', // Optional: State/Province
+  postalCode: '10001',
+  country: 'US',
+  phone: '+1234567890', // Optional
+});
+```
+
+#### Set Billing Address (Optional)
+
+```typescript
+omni.setLocalCartBillingAddress({
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '456 Business Ave',
+  city: 'New York',
+  postalCode: '10002',
+  country: 'US',
+});
+```
+
+#### Apply Coupon
+
+```typescript
+omni.setLocalCartCoupon('SAVE20');
+
+// Remove coupon
+omni.setLocalCartCoupon(undefined);
+```
+
+#### Get Cart Item Count
+
+```typescript
+const count = omni.getLocalCartItemCount();
+console.log(`${count} items in cart`);
+```
+
+#### Local Cart Type Definition
+
+```typescript
+interface LocalCart {
+  items: LocalCartItem[];
+  couponCode?: string;
+  customer?: {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+  };
+  shippingAddress?: {
+    firstName: string;
+    lastName: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    region?: string;
+    postalCode: string;
+    country: string;
+    phone?: string;
+  };
+  billingAddress?: {
+    /* same as shipping */
+  };
+  notes?: string;
+  updatedAt: string;
+}
+
+interface LocalCartItem {
+  productId: string;
+  variantId?: string;
+  quantity: number;
+  name?: string;
+  sku?: string;
+  price?: string;
+  image?: string;
+  addedAt: string;
+}
+```
+
+---
+
+### Guest Checkout (Submit Order)
+
+Submit the local cart as an order with a **single API call**:
+
+```typescript
+// Make sure cart has items, customer email, and shipping address
+const order = await omni.submitGuestOrder();
+
+console.log(order.orderId); // 'order_abc123...'
+console.log(order.orderNumber); // 'ORD-12345'
+console.log(order.status); // 'pending'
+console.log(order.total); // 59.98
+console.log(order.message); // 'Order created successfully'
+
+// Cart is automatically cleared after successful order
+```
+
+#### Keep Cart After Order
+
+```typescript
+// If you want to keep the cart data (e.g., for order review page)
+const order = await omni.submitGuestOrder({ clearCartOnSuccess: false });
+```
+
+#### Create Order with Custom Data
+
+If you manage cart state yourself instead of using local cart:
+
+```typescript
+const order = await omni.createGuestOrder({
+  items: [
+    { productId: 'prod_123', quantity: 2 },
+    { productId: 'prod_456', variantId: 'var_789', quantity: 1 },
+  ],
+  customer: {
+    email: 'customer@example.com',
+    firstName: 'John',
+    lastName: 'Doe',
+  },
+  shippingAddress: {
+    firstName: 'John',
+    lastName: 'Doe',
+    line1: '123 Main St',
+    city: 'New York',
+    postalCode: '10001',
+    country: 'US',
+  },
+  couponCode: 'SAVE20', // Optional
+  notes: 'Please gift wrap', // Optional
+});
+```
+
+#### Guest Order Response Type
+
+```typescript
+interface GuestOrderResponse {
+  orderId: string;
+  orderNumber: string;
+  status: string;
+  total: number;
+  message: string;
+}
+```
+
+---
+
+### Server Cart (Registered Users)
+
+For logged-in customers who want cart sync across devices.
 
 #### Create Cart
 
 ```typescript
 const cart = await omni.createCart();
-setCartId(cart.id); // Save to localStorage
+setServerCartId(cart.id); // Save to localStorage
 ```
 
 #### Get Cart
@@ -615,12 +909,12 @@ export default function ProductsPage() {
 }
 ```
 
-### Product Detail with Add to Cart
+### Product Detail with Add to Cart (Local Cart)
 
 ```typescript
 'use client';
 import { useEffect, useState } from 'react';
-import { omni, getCartId, setCartId } from '@/lib/omni-sync';
+import { omni } from '@/lib/omni-sync';
 import type { Product } from 'omni-sync-sdk';
 
 export default function ProductPage({ params }: { params: { id: string } }) {
@@ -628,7 +922,6 @@ export default function ProductPage({ params }: { params: { id: string } }) {
   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() {
@@ -645,30 +938,25 @@ export default function ProductPage({ params }: { params: { id: string } }) {
     load();
   }, [params.id]);
 
-  const handleAddToCart = async () => {
+  const handleAddToCart = () => {
     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);
-    }
+    // Get variant if selected
+    const variant = selectedVariant
+      ? product.variants?.find(v => v.id === selectedVariant)
+      : null;
+
+    // Add to local cart (NO API call!)
+    omni.addToLocalCart({
+      productId: product.id,
+      variantId: selectedVariant || undefined,
+      quantity,
+      name: variant?.name || product.name,
+      price: String(variant?.price || product.salePrice || product.basePrice),
+      image: product.images?.[0]?.url,
+    });
+
+    alert('Added to cart!');
   };
 
   if (loading) return <div>Loading...</div>;
@@ -749,63 +1037,33 @@ export default function ProductPage({ params }: { params: { id: string } }) {
 }
 ```
 
-### Cart Page
+### Cart Page (Local Cart)
 
 ```typescript
 'use client';
-import { useEffect, useState } from 'react';
-import { omni, getCartId } from '@/lib/omni-sync';
-import type { Cart } from 'omni-sync-sdk';
+import { useState } from 'react';
+import { omni } from '@/lib/omni-sync';
+import type { LocalCart } 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 [cart, setCart] = useState<LocalCart>(omni.getLocalCart());
 
-  const loadCart = async () => {
-    const cartId = getCartId();
-    if (!cartId) {
-      setLoading(false);
-      return;
-    }
-    try {
-      const c = await omni.getCart(cartId);
-      setCart(c);
-    } finally {
-      setLoading(false);
-    }
+  const updateQuantity = (productId: string, quantity: number, variantId?: string) => {
+    const updated = omni.updateLocalCartItem(productId, quantity, variantId);
+    setCart(updated);
   };
 
-  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 = (productId: string, variantId?: string) => {
+    const updated = omni.removeFromLocalCart(productId, variantId);
+    setCart(updated);
   };
 
-  const removeItem = async (itemId: string) => {
-    if (!cart) return;
-    setUpdating(itemId);
-    try {
-      await omni.removeCartItem(cart.id, itemId);
-      await loadCart();
-    } finally {
-      setUpdating(null);
-    }
-  };
+  // Calculate subtotal from local cart
+  const subtotal = cart.items.reduce((sum, item) => {
+    return sum + (parseFloat(item.price || '0') * item.quantity);
+  }, 0);
 
-  if (loading) return <div>Loading cart...</div>;
-  if (!cart || cart.items.length === 0) {
+  if (cart.items.length === 0) {
     return (
       <div className="text-center py-12">
         <h1 className="text-2xl font-bold">Your cart is empty</h1>
@@ -819,42 +1077,38 @@ export default function CartPage() {
       <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">
+        <div key={`${item.productId}-${item.variantId || ''}`} className="flex items-center gap-4 py-4 border-b">
           <img
-            src={item.product.images?.[0]?.url || '/placeholder.jpg'}
-            alt={item.product.name}
+            src={item.image || '/placeholder.jpg'}
+            alt={item.name || 'Product'}
             className="w-20 h-20 object-cover"
           />
           <div className="flex-1">
-            <h3 className="font-medium">{item.product.name}</h3>
-            {item.variant && <p className="text-sm text-gray-500">{item.variant.name}</p>}
-            <p className="font-bold">${item.unitPrice}</p>
+            <h3 className="font-medium">{item.name || 'Product'}</h3>
+            <p className="font-bold">${item.price}</p>
           </div>
           <div className="flex items-center gap-2">
             <button
-              onClick={() => updateQuantity(item.id, item.quantity - 1)}
-              disabled={updating === item.id}
+              onClick={() => updateQuantity(item.productId, item.quantity - 1, item.variantId)}
               className="w-8 h-8 border rounded"
             >-</button>
             <span className="w-8 text-center">{item.quantity}</span>
             <button
-              onClick={() => updateQuantity(item.id, item.quantity + 1)}
-              disabled={updating === item.id}
+              onClick={() => updateQuantity(item.productId, item.quantity + 1, item.variantId)}
               className="w-8 h-8 border rounded"
             >+</button>
           </div>
           <button
-            onClick={() => removeItem(item.id)}
-            disabled={updating === item.id}
+            onClick={() => removeItem(item.productId, item.variantId)}
             className="text-red-600"
           >Remove</button>
         </div>
       ))}
 
       <div className="mt-6 text-right">
-        <p className="text-xl">Subtotal: <strong>${cart.subtotal}</strong></p>
-        {cart.discountAmount && Number(cart.discountAmount) > 0 && (
-          <p className="text-green-600">Discount: -${cart.discountAmount}</p>
+        <p className="text-xl">Subtotal: <strong>${subtotal.toFixed(2)}</strong></p>
+        {cart.couponCode && (
+          <p className="text-green-600">Coupon applied: {cart.couponCode}</p>
         )}
         <a
           href="/checkout"
@@ -868,12 +1122,182 @@ export default function CartPage() {
 }
 ```
 
-### Multi-Step Checkout
+### Guest Checkout (Single API Call)
+
+This is the recommended checkout for guest users. All cart data is in localStorage, and we submit it in one API call.
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { omni } from '@/lib/omni-sync';
+import type { LocalCart, GuestOrderResponse } from 'omni-sync-sdk';
+
+type Step = 'info' | 'review' | 'complete';
+
+export default function CheckoutPage() {
+  const [cart, setCart] = useState<LocalCart>(omni.getLocalCart());
+  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(cart.customer?.email || '');
+  const [firstName, setFirstName] = useState(cart.customer?.firstName || '');
+  const [lastName, setLastName] = useState(cart.customer?.lastName || '');
+  const [address, setAddress] = useState(cart.shippingAddress?.line1 || '');
+  const [city, setCity] = useState(cart.shippingAddress?.city || '');
+  const [postalCode, setPostalCode] = useState(cart.shippingAddress?.postalCode || '');
+  const [country, setCountry] = useState(cart.shippingAddress?.country || 'US');
+
+  // Calculate subtotal
+  const subtotal = cart.items.reduce((sum, item) => {
+    return sum + (parseFloat(item.price || '0') * item.quantity);
+  }, 0);
+
+  // Redirect if cart is empty
+  useEffect(() => {
+    if (cart.items.length === 0 && step !== 'complete') {
+      window.location.href = '/cart';
+    }
+  }, [cart.items.length, step]);
+
+  const handleInfoSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    // Save to local cart
+    omni.setLocalCartCustomer({ email, firstName, lastName });
+    omni.setLocalCartShippingAddress({
+      firstName,
+      lastName,
+      line1: address,
+      city,
+      postalCode,
+      country,
+    });
+
+    setStep('review');
+  };
+
+  const handlePlaceOrder = async () => {
+    setSubmitting(true);
+    setError('');
+
+    try {
+      // Single API call to create order!
+      const result = await omni.submitGuestOrder();
+      setOrder(result);
+      setStep('complete');
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to place order');
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  if (step === 'complete' && order) {
+    return (
+      <div className="text-center py-12">
+        <h1 className="text-3xl font-bold text-green-600">Order Complete!</h1>
+        <p className="mt-4">Order Number: <strong>{order.orderNumber}</strong></p>
+        <p className="mt-2">Total: <strong>${order.total.toFixed(2)}</strong></p>
+        <p className="mt-4 text-gray-600">A confirmation email will be sent to {email}</p>
+        <a href="/" className="mt-6 inline-block text-blue-600">Continue Shopping</a>
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-2xl mx-auto">
+      <h1 className="text-2xl font-bold mb-6">Checkout</h1>
+
+      {error && (
+        <div className="bg-red-100 text-red-600 p-3 rounded mb-4">{error}</div>
+      )}
+
+      {step === 'info' && (
+        <form onSubmit={handleInfoSubmit} className="space-y-4">
+          <h2 className="text-lg font-bold">Contact Information</h2>
+          <input
+            type="email"
+            placeholder="Email"
+            value={email}
+            onChange={e => setEmail(e.target.value)}
+            required
+            className="w-full border p-2 rounded"
+          />
+
+          <h2 className="text-lg font-bold mt-6">Shipping Address</h2>
+          <div className="grid grid-cols-2 gap-4">
+            <input placeholder="First Name" value={firstName} onChange={e => setFirstName(e.target.value)} required className="border p-2 rounded" />
+            <input placeholder="Last Name" value={lastName} onChange={e => setLastName(e.target.value)} required className="border p-2 rounded" />
+          </div>
+          <input placeholder="Address" value={address} onChange={e => setAddress(e.target.value)} required className="w-full border p-2 rounded" />
+          <div className="grid grid-cols-2 gap-4">
+            <input placeholder="City" value={city} onChange={e => setCity(e.target.value)} required className="border p-2 rounded" />
+            <input placeholder="Postal Code" value={postalCode} onChange={e => setPostalCode(e.target.value)} required className="border p-2 rounded" />
+          </div>
+          <select value={country} onChange={e => setCountry(e.target.value)} className="w-full border p-2 rounded">
+            <option value="US">United States</option>
+            <option value="IL">Israel</option>
+            <option value="GB">United Kingdom</option>
+          </select>
+
+          <button type="submit" className="w-full bg-black text-white py-3 rounded">
+            Review Order
+          </button>
+        </form>
+      )}
+
+      {step === 'review' && (
+        <div className="space-y-6">
+          {/* Order Summary */}
+          <div className="border p-4 rounded">
+            <h3 className="font-bold mb-4">Order Summary</h3>
+            {cart.items.map((item) => (
+              <div key={`${item.productId}-${item.variantId || ''}`} className="flex justify-between py-2">
+                <span>{item.name} x {item.quantity}</span>
+                <span>${(parseFloat(item.price || '0') * item.quantity).toFixed(2)}</span>
+              </div>
+            ))}
+            <hr className="my-2" />
+            <div className="flex justify-between font-bold">
+              <span>Total</span>
+              <span>${subtotal.toFixed(2)}</span>
+            </div>
+          </div>
+
+          {/* Shipping Info */}
+          <div className="border p-4 rounded">
+            <h3 className="font-bold mb-2">Shipping To</h3>
+            <p>{firstName} {lastName}</p>
+            <p>{address}</p>
+            <p>{city}, {postalCode}, {country}</p>
+            <button onClick={() => setStep('info')} className="text-blue-600 text-sm mt-2">Edit</button>
+          </div>
+
+          <button
+            onClick={handlePlaceOrder}
+            disabled={submitting}
+            className="w-full bg-green-600 text-white py-3 rounded text-lg"
+          >
+            {submitting ? 'Processing...' : 'Place Order'}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Multi-Step Checkout (Server Cart - For Registered Users)
+
+For logged-in users with server-side cart:
 
 ```typescript
 'use client';
 import { useEffect, useState } from 'react';
-import { omni, getCartId, clearCartId } from '@/lib/omni-sync';
+import { omni, getServerCartId } from '@/lib/omni-sync';
 import type { Checkout, ShippingRate } from 'omni-sync-sdk';
 
 type Step = 'customer' | 'shipping' | 'payment' | 'complete';
@@ -896,7 +1320,7 @@ export default function CheckoutPage() {
 
   useEffect(() => {
     async function initCheckout() {
-      const cartId = getCartId();
+      const cartId = getServerCartId();
       if (!cartId) {
         window.location.href = '/cart';
         return;
@@ -948,7 +1372,6 @@ export default function CheckoutPage() {
     setSubmitting(true);
     try {
       const { orderId } = await omni.completeCheckout(checkout.id);
-      clearCartId();
       setStep('complete');
     } catch (err) {
       alert('Failed to complete order');
@@ -1202,12 +1625,12 @@ export default function AccountPage() {
 }
 ```
 
-### Header Component with Cart Count
+### Header Component with Cart Count (Local Cart)
 
 ```typescript
 'use client';
-import { useEffect, useState } from 'react';
-import { omni, getCartId, isLoggedIn } from '@/lib/omni-sync';
+import { useState, useEffect } from 'react';
+import { omni, isLoggedIn } from '@/lib/omni-sync';
 
 export function Header() {
   const [cartCount, setCartCount] = useState(0);
@@ -1215,17 +1638,8 @@ export function Header() {
 
   useEffect(() => {
     setLoggedIn(isLoggedIn());
-
-    async function loadCart() {
-      const cartId = getCartId();
-      if (cartId) {
-        try {
-          const cart = await omni.getCart(cartId);
-          setCartCount(cart.itemCount);
-        } catch {}
-      }
-    }
-    loadCart();
+    // Get cart count from local storage (NO API call!)
+    setCartCount(omni.getLocalCartItemCount());
   }, []);
 
   return (
@@ -1340,7 +1754,13 @@ import type {
   ProductQueryParams,
   PaginatedResponse,
 
-  // Cart
+  // Local Cart (Guest Users)
+  LocalCart,
+  LocalCartItem,
+  CreateGuestOrderDto,
+  GuestOrderResponse,
+
+  // Server Cart (Registered Users)
   Cart,
   CartItem,
   AddToCartDto,