omni-sync-sdk 0.7.11 → 0.8.1

package/README.md

@@ -30,8 +30,37 @@ const omni = new OmniSyncClient({
 
 // Fetch products
 const { data: products } = await omni.getProducts();
+```
+
+---
+
+## Checkout: Guest vs Logged-In Customer
+
+> **IMPORTANT:** There are TWO different checkout flows. You MUST use the correct one based on whether the customer is logged in or not.
 
-// ===== GUEST CHECKOUT (Recommended for most sites) =====
+| Customer Type | Cart Type | Checkout Method | Orders Linked to Account? |
+|---------------|-----------|-----------------|---------------------------|
+| **Guest** | Local Cart (localStorage) | `submitGuestOrder()` | No |
+| **Logged In** | Server Cart | `completeCheckout()` | Yes |
+
+### Decision Flow
+
+```typescript
+// ALWAYS check this at checkout!
+if (isLoggedIn()) {
+  // ✅ Logged-in customer → Server Cart + Checkout flow
+  // Orders will be linked to their account
+  const order = await completeServerCheckout();
+} else {
+  // ✅ Guest → Local Cart + submitGuestOrder
+  // Orders are standalone (not linked to any account)
+  const order = await omni.submitGuestOrder();
+}
+```
+
+### Guest Checkout (for visitors without account)
+
+```typescript
 // Cart stored locally - NO API calls until checkout!
 
 // Add to local cart (stored in localStorage)
@@ -58,11 +87,53 @@ const order = await omni.submitGuestOrder();
 console.log('Order created:', order.orderId);
 ```
 
+### Logged-In Customer Checkout (orders linked to account)
+
+```typescript
+// 1. Make sure customer token is set (after login)
+omni.setCustomerToken(authResponse.token);
+
+// 2. Create server cart (auto-linked to customer!)
+const cart = await omni.createCart();
+localStorage.setItem('cartId', cart.id);
+
+// 3. Add items to server cart
+await omni.addToCart(cart.id, {
+  productId: products[0].id,
+  quantity: 1,
+});
+
+// 4. Create checkout from cart
+const checkout = await omni.createCheckout({ cartId: cart.id });
+
+// 5. Set shipping address
+await omni.setShippingAddress(checkout.id, {
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  city: 'New York',
+  postalCode: '10001',
+  country: 'US',
+});
+
+// 6. Get shipping rates and select one
+const rates = await omni.getShippingRates(checkout.id);
+await omni.selectShippingMethod(checkout.id, rates[0].id);
+
+// 7. Complete checkout - order is linked to customer!
+const { orderId } = await omni.completeCheckout(checkout.id);
+console.log('Order created:', orderId);
+
+// Customer can now see this order in omni.getMyOrders()
+```
+
+> **WARNING:** Do NOT use `submitGuestOrder()` for logged-in customers! Their orders won't be linked to their account and won't appear in their order history.
+
 ---
 
 ## Two Ways to Handle Cart
 
-### Option 1: Local Cart (Guest Users) - RECOMMENDED
+### Option 1: Local Cart (Guest Users)
 
 For guest users, the cart is stored in **localStorage** - exactly like Amazon, Shopify, and other major platforms do. This means:
 
@@ -89,19 +160,34 @@ omni.removeFromLocalCart('prod_123');
 const order = await omni.submitGuestOrder();
 ```
 
-### Option 2: Server Cart (Registered Users)
+### Option 2: Server Cart (Logged-In Customers)
 
-For logged-in customers, use server-side cart:
+For logged-in customers, **you MUST use server-side cart** to link orders to their account:
 
 - ✅ Cart syncs across devices
 - ✅ Abandoned cart recovery
-- ✅ Customer history tracking
+- ✅ Orders linked to customer account
+- ✅ Customer can see orders in "My Orders"
 
 ```typescript
+// 1. Set customer token (after login)
+omni.setCustomerToken(token);
+
+// 2. Create cart (auto-linked to customer)
 const cart = await omni.createCart();
+localStorage.setItem('cartId', cart.id);
+
+// 3. Add items
 await omni.addToCart(cart.id, { productId: 'prod_123', quantity: 2 });
+
+// 4. At checkout - create checkout and complete
+const checkout = await omni.createCheckout({ cartId: cart.id });
+// ... set shipping address, select shipping method ...
+const { orderId } = await omni.completeCheckout(checkout.id);
 ```
 
+> **⚠️ CRITICAL:** If you use `submitGuestOrder()` for a logged-in customer, their order will NOT be linked to their account!
+
 ---
 
 ## Complete Store Setup
@@ -322,6 +408,62 @@ interface InventoryInfo {
 }
 ```
 
+#### Displaying Price Range for Variable Products
+
+For products with `type: 'VARIABLE'` and multiple variants with different prices, display a **price range** instead of a single price:
+
+```typescript
+// Helper function to get price range from variants
+function getPriceRange(product: Product): { min: number; max: number } | null {
+  if (product.type !== 'VARIABLE' || !product.variants?.length) {
+    return null;
+  }
+
+  const prices = product.variants
+    .map(v => v.price ?? product.basePrice)
+    .filter((p): p is number => p !== null);
+
+  if (prices.length === 0) return null;
+
+  const min = Math.min(...prices);
+  const max = Math.max(...prices);
+
+  // Return null if all variants have the same price
+  return min !== max ? { min, max } : null;
+}
+
+// Usage in component
+function ProductPrice({ product }: { product: Product }) {
+  const priceRange = getPriceRange(product);
+
+  if (priceRange) {
+    // Variable product with different variant prices - show range
+    return <span>${priceRange.min} - ${priceRange.max}</span>;
+  }
+
+  // Simple product or all variants same price - show single price
+  return product.salePrice ? (
+    <>
+      <span className="text-red-600">${product.salePrice}</span>
+      <span className="line-through text-gray-400 ml-2">${product.basePrice}</span>
+    </>
+  ) : (
+    <span>${product.basePrice}</span>
+  );
+}
+```
+
+**When to show price range:**
+
+- Product `type` is `'VARIABLE'`
+- Has 2+ variants with **different** prices
+- Example: T-shirt sizes S/M/L at $29, XL/XXL at $34 → Display "$29 - $34"
+
+**When to show single price:**
+
+- Product `type` is `'SIMPLE'`
+- Variable product where all variants have the same price
+
 #### Rendering Product Descriptions
 
 **IMPORTANT**: Product descriptions may contain HTML (from Shopify/WooCommerce) or plain text. Always check `descriptionFormat` before rendering:
@@ -1076,6 +1218,335 @@ export default function VerifyEmailPage() {
 
 ---
 
+### Social Login (OAuth)
+
+Allow customers to sign in with Google, Facebook, or GitHub. The store owner configures which providers are available in their OmniSync admin panel.
+
+#### Check Available Providers
+
+```typescript
+// Returns only the providers the store owner has enabled
+const { providers } = await omni.getAvailableOAuthProviders();
+// providers = ['GOOGLE', 'FACEBOOK'] - varies by store configuration
+```
+
+#### OAuth Login Flow
+
+**Step 1: User clicks "Sign in with Google"**
+
+```typescript
+// Save cart ID before redirect (user will leave your site!)
+const cartId = localStorage.getItem('cartId');
+if (cartId) sessionStorage.setItem('pendingCartId', cartId);
+
+// Get authorization URL
+const { authorizationUrl, state } = await omni.getOAuthAuthorizeUrl('GOOGLE', {
+  redirectUrl: window.location.origin + '/auth/callback', // Where Google sends them back
+});
+
+// Save state for verification (CSRF protection)
+sessionStorage.setItem('oauthState', state);
+
+// Redirect to Google
+window.location.href = authorizationUrl;
+```
+
+**Step 2: Create callback page (`/auth/callback`)**
+
+```typescript
+// pages/auth/callback.tsx or app/auth/callback/page.tsx
+'use client';
+import { useEffect, useState } from 'react';
+import { useSearchParams } from 'next/navigation';
+import { omni, setCustomerToken } from '@/lib/omni-sync';
+
+export default function AuthCallback() {
+  const searchParams = useSearchParams();
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function handleCallback() {
+      const code = searchParams.get('code');
+      const state = searchParams.get('state');
+      const errorParam = searchParams.get('error');
+
+      // Check for OAuth errors (user cancelled, etc.)
+      if (errorParam) {
+        window.location.href = '/login?error=cancelled';
+        return;
+      }
+
+      if (!code || !state) {
+        setError('Missing OAuth parameters');
+        return;
+      }
+
+      // Verify state matches (CSRF protection)
+      const savedState = sessionStorage.getItem('oauthState');
+      if (state !== savedState) {
+        setError('Invalid state - please try again');
+        return;
+      }
+
+      try {
+        // Exchange code for customer token
+        const { customer, token, isNewCustomer } = await omni.handleOAuthCallback(
+          'GOOGLE',
+          code,
+          state
+        );
+
+        // Save the customer token
+        setCustomerToken(token);
+        sessionStorage.removeItem('oauthState');
+
+        // Link any pending cart to the now-logged-in customer
+        const pendingCartId = sessionStorage.getItem('pendingCartId');
+        if (pendingCartId) {
+          try {
+            await omni.linkCart(pendingCartId);
+          } catch {
+            // Cart may have expired - that's ok
+          }
+          sessionStorage.removeItem('pendingCartId');
+        }
+
+        // Redirect to return URL or home
+        const returnUrl = localStorage.getItem('returnUrl') || '/';
+        localStorage.removeItem('returnUrl');
+        window.location.href = returnUrl;
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Login failed');
+      }
+    }
+
+    handleCallback();
+  }, [searchParams]);
+
+  if (error) {
+    return (
+      <div className="max-w-md mx-auto mt-12 text-center">
+        <h1 className="text-xl font-bold text-red-600">Login Failed</h1>
+        <p className="mt-2 text-gray-600">{error}</p>
+        <a href="/login" className="mt-4 inline-block text-blue-600">
+          Try again
+        </a>
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-md mx-auto mt-12 text-center">
+      <div className="animate-spin h-8 w-8 border-4 border-blue-600 border-t-transparent rounded-full mx-auto"></div>
+      <p className="mt-4 text-gray-600">Completing login...</p>
+    </div>
+  );
+}
+```
+
+#### Login Page with Social Buttons
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { omni, setCustomerToken } from '@/lib/omni-sync';
+
+export default function LoginPage() {
+  const [providers, setProviders] = useState<string[]>([]);
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+
+  // Load available OAuth providers
+  useEffect(() => {
+    omni.getAvailableOAuthProviders()
+      .then(({ providers }) => setProviders(providers))
+      .catch(() => {}); // OAuth not configured - that's ok
+  }, []);
+
+  // Social login handler
+  const handleSocialLogin = async (provider: string) => {
+    try {
+      // Save cart ID before redirect
+      const cartId = localStorage.getItem('cartId');
+      if (cartId) sessionStorage.setItem('pendingCartId', cartId);
+
+      const { authorizationUrl, state } = await omni.getOAuthAuthorizeUrl(
+        provider as 'GOOGLE' | 'FACEBOOK' | 'GITHUB',
+        { redirectUrl: window.location.origin + '/auth/callback' }
+      );
+
+      sessionStorage.setItem('oauthState', state);
+      window.location.href = authorizationUrl;
+    } catch (err) {
+      setError('Failed to start login');
+    }
+  };
+
+  // Regular email/password login
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    setError('');
+    try {
+      const auth = await omni.loginCustomer(email, password);
+      setCustomerToken(auth.token);
+      const returnUrl = localStorage.getItem('returnUrl') || '/';
+      localStorage.removeItem('returnUrl');
+      window.location.href = returnUrl;
+    } catch (err) {
+      setError('Invalid email or password');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="max-w-md mx-auto mt-12">
+      <h1 className="text-2xl font-bold mb-6">Login</h1>
+
+      {/* Social Login Buttons */}
+      {providers.length > 0 && (
+        <div className="space-y-3 mb-6">
+          {providers.includes('GOOGLE') && (
+            <button
+              onClick={() => handleSocialLogin('GOOGLE')}
+              className="w-full flex items-center justify-center gap-2 border py-3 rounded hover:bg-gray-50"
+            >
+              <GoogleIcon />
+              Continue with Google
+            </button>
+          )}
+          {providers.includes('FACEBOOK') && (
+            <button
+              onClick={() => handleSocialLogin('FACEBOOK')}
+              className="w-full flex items-center justify-center gap-2 bg-[#1877F2] text-white py-3 rounded"
+            >
+              <FacebookIcon />
+              Continue with Facebook
+            </button>
+          )}
+          {providers.includes('GITHUB') && (
+            <button
+              onClick={() => handleSocialLogin('GITHUB')}
+              className="w-full flex items-center justify-center gap-2 bg-[#24292F] text-white py-3 rounded"
+            >
+              <GithubIcon />
+              Continue with GitHub
+            </button>
+          )}
+          <div className="relative my-4">
+            <div className="absolute inset-0 flex items-center">
+              <div className="w-full border-t" />
+            </div>
+            <div className="relative flex justify-center text-sm">
+              <span className="px-2 bg-white text-gray-500">or</span>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Email/Password Form */}
+      {error && <div className="bg-red-100 text-red-600 p-3 rounded mb-4">{error}</div>}
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <input
+          type="email"
+          placeholder="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          required
+          className="w-full border p-2 rounded"
+        />
+        <input
+          type="password"
+          placeholder="Password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          required
+          className="w-full border p-2 rounded"
+        />
+        <button
+          type="submit"
+          disabled={loading}
+          className="w-full bg-black text-white py-3 rounded"
+        >
+          {loading ? 'Logging in...' : 'Login'}
+        </button>
+      </form>
+
+      <p className="mt-4 text-center">
+        Don't have an account? <a href="/register" className="text-blue-600">Register</a>
+      </p>
+    </div>
+  );
+}
+
+// Simple SVG icons (or use lucide-react)
+const GoogleIcon = () => (
+  <svg className="w-5 h-5" viewBox="0 0 24 24">
+    <path fill="#4285F4" d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"/>
+    <path fill="#34A853" d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"/>
+    <path fill="#FBBC05" d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"/>
+    <path fill="#EA4335" d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"/>
+  </svg>
+);
+
+const FacebookIcon = () => (
+  <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+    <path d="M24 12.073c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.99 4.388 10.954 10.125 11.854v-8.385H7.078v-3.47h3.047V9.43c0-3.007 1.792-4.669 4.533-4.669 1.312 0 2.686.235 2.686.235v2.953H15.83c-1.491 0-1.956.925-1.956 1.874v2.25h3.328l-.532 3.47h-2.796v8.385C19.612 23.027 24 18.062 24 12.073z"/>
+  </svg>
+);
+
+const GithubIcon = () => (
+  <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+    <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/>
+  </svg>
+);
+```
+
+#### Account Linking (Add Social Account to Existing User)
+
+Logged-in customers can link additional social accounts to their profile:
+
+```typescript
+// Get currently linked accounts
+const connections = await omni.getOAuthConnections();
+// [{ provider: 'GOOGLE', email: 'user@gmail.com', linkedAt: '...' }]
+
+// Link a new provider (redirects to OAuth flow)
+const { authorizationUrl } = await omni.linkOAuthProvider('GITHUB');
+window.location.href = authorizationUrl;
+
+// Unlink a provider
+await omni.unlinkOAuthProvider('GOOGLE');
+```
+
+#### Cart Linking After OAuth Login
+
+When a customer logs in via OAuth, their guest cart should be linked to their account:
+
+```typescript
+// omni.linkCart() associates a guest cart with the logged-in customer
+await omni.linkCart(cartId);
+```
+
+This is automatically handled in the callback example above.
+
+#### OAuth Method Reference
+
+| Method                                       | Description                                  |
+| -------------------------------------------- | -------------------------------------------- |
+| `getAvailableOAuthProviders()`               | Get list of enabled providers for this store |
+| `getOAuthAuthorizeUrl(provider, options?)`   | Get URL to redirect user to OAuth provider   |
+| `handleOAuthCallback(provider, code, state)` | Exchange OAuth code for customer token       |
+| `linkOAuthProvider(provider)`                | Link social account to current customer      |
+| `unlinkOAuthProvider(provider)`              | Remove linked social account                 |
+| `getOAuthConnections()`                      | Get list of linked social accounts           |
+| `linkCart(cartId)`                           | Link guest cart to logged-in customer        |
+
+---
+
 ### Customer Addresses
 
 #### Get Addresses
@@ -1460,9 +1931,183 @@ export default function CartPage() {
 }
 ```
 
+### Universal Checkout (Handles Both Guest & Logged-In)
+
+> **RECOMMENDED:** Use this pattern to properly handle both guest and logged-in customers in a single checkout page.
+
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+import { omni, isLoggedIn, getServerCartId, setServerCartId, restoreCustomerToken } from '@/lib/omni-sync';
+
+export default function CheckoutPage() {
+  const [loading, setLoading] = useState(true);
+  const [submitting, setSubmitting] = useState(false);
+  const [customerLoggedIn, setCustomerLoggedIn] = useState(false);
+
+  // Form state
+  const [email, setEmail] = useState('');
+  const [shippingAddress, setShippingAddress] = useState({
+    firstName: '', lastName: '', line1: '', city: '', postalCode: '', country: 'US'
+  });
+
+  // Server checkout state (for logged-in customers)
+  const [checkoutId, setCheckoutId] = useState<string | null>(null);
+  const [shippingRates, setShippingRates] = useState<any[]>([]);
+  const [selectedRate, setSelectedRate] = useState<string | null>(null);
+
+  useEffect(() => {
+    restoreCustomerToken();
+    const loggedIn = isLoggedIn();
+    setCustomerLoggedIn(loggedIn);
+
+    async function initCheckout() {
+      if (loggedIn) {
+        // Logged-in customer: Create server cart + checkout
+        let cartId = getServerCartId();
+
+        if (!cartId) {
+          // Create new cart (auto-linked to customer)
+          const cart = await omni.createCart();
+          cartId = cart.id;
+          setServerCartId(cartId);
+
+          // Migrate local cart items to server cart
+          const localCart = omni.getLocalCart();
+          for (const item of localCart.items) {
+            await omni.addToCart(cartId, {
+              productId: item.productId,
+              variantId: item.variantId,
+              quantity: item.quantity,
+            });
+          }
+          omni.clearLocalCart(); // Clear local cart after migration
+        }
+
+        // Create checkout from server cart
+        const checkout = await omni.createCheckout({ cartId });
+        setCheckoutId(checkout.id);
+
+        // Pre-fill from customer profile if available
+        try {
+          const profile = await omni.getMyOrders({ limit: 1 }); // Just to check auth works
+        } catch (e) {
+          console.log('Could not fetch profile');
+        }
+      }
+      setLoading(false);
+    }
+
+    initCheckout();
+  }, []);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setSubmitting(true);
+
+    try {
+      if (customerLoggedIn && checkoutId) {
+        // ===== LOGGED-IN CUSTOMER: Server Checkout =====
+
+        // 1. Set shipping address
+        await omni.setShippingAddress(checkoutId, shippingAddress);
+
+        // 2. Get and select shipping rate
+        const rates = await omni.getShippingRates(checkoutId);
+        if (rates.length > 0) {
+          await omni.selectShippingMethod(checkoutId, selectedRate || rates[0].id);
+        }
+
+        // 3. Complete checkout - ORDER IS LINKED TO CUSTOMER!
+        const { orderId } = await omni.completeCheckout(checkoutId);
+
+        // Clear cart ID
+        localStorage.removeItem('cartId');
+
+        // Redirect to success page
+        window.location.href = `/order-success?orderId=${orderId}`;
+
+      } else {
+        // ===== GUEST: Local Cart + submitGuestOrder =====
+
+        // Set customer and shipping info on local cart
+        omni.setLocalCartCustomer({ email });
+        omni.setLocalCartShippingAddress(shippingAddress);
+
+        // Submit guest order (single API call)
+        const order = await omni.submitGuestOrder();
+
+        // Redirect to success page
+        window.location.href = `/order-success?orderId=${order.orderId}`;
+      }
+    } catch (error) {
+      console.error('Checkout failed:', error);
+      alert('Checkout failed. Please try again.');
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  if (loading) return <div>Loading checkout...</div>;
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* Show email field only for guests */}
+      {!customerLoggedIn && (
+        <input
+          type="email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          placeholder="Email"
+          required
+        />
+      )}
+
+      {/* Shipping address fields */}
+      <input value={shippingAddress.firstName} onChange={(e) => setShippingAddress({...shippingAddress, firstName: e.target.value})} placeholder="First Name" required />
+      <input value={shippingAddress.lastName} onChange={(e) => setShippingAddress({...shippingAddress, lastName: e.target.value})} placeholder="Last Name" required />
+      <input value={shippingAddress.line1} onChange={(e) => setShippingAddress({...shippingAddress, line1: e.target.value})} placeholder="Address" required />
+      <input value={shippingAddress.city} onChange={(e) => setShippingAddress({...shippingAddress, city: e.target.value})} placeholder="City" required />
+      <input value={shippingAddress.postalCode} onChange={(e) => setShippingAddress({...shippingAddress, postalCode: e.target.value})} placeholder="Postal Code" required />
+
+      {/* Shipping rates (for logged-in customers) */}
+      {customerLoggedIn && shippingRates.length > 0 && (
+        <select value={selectedRate || ''} onChange={(e) => setSelectedRate(e.target.value)}>
+          {shippingRates.map((rate) => (
+            <option key={rate.id} value={rate.id}>
+              {rate.name} - ${rate.price}
+            </option>
+          ))}
+        </select>
+      )}
+
+      <button type="submit" disabled={submitting}>
+        {submitting ? 'Processing...' : 'Place Order'}
+      </button>
+
+      {customerLoggedIn && (
+        <p className="text-sm text-green-600">
+          ✓ Logged in - Order will be saved to your account
+        </p>
+      )}
+    </form>
+  );
+}
+```
+
+> **Key Points:**
+> - `isLoggedIn()` determines which flow to use
+> - Logged-in customers use `createCart()` → `createCheckout()` → `completeCheckout()`
+> - Guests use local cart + `submitGuestOrder()`
+> - Local cart items are migrated to server cart when customer logs in
+
+---
+
 ### Guest Checkout (Single API Call)
 
-This is the recommended checkout for guest users. All cart data is in localStorage, and we submit it in one API call.
+This checkout is for **guest users only**. All cart data is in localStorage, and we submit it in one API call.
+
+> **⚠️ WARNING:** Do NOT use this for logged-in customers! Use the Universal Checkout pattern above instead.
 
 ```typescript
 'use client';
@@ -1628,9 +2273,11 @@ export default function CheckoutPage() {
 }
 ```
 
-### Multi-Step Checkout (Server Cart - For Registered Users)
+### Multi-Step Checkout (Server Cart - For Logged-In Customers Only)
+
+> **IMPORTANT:** This checkout pattern is ONLY for logged-in customers. For a checkout page that handles both guests and logged-in customers, see the "Universal Checkout" example above.
 
-For logged-in users with server-side cart:
+For logged-in users with server-side cart - orders will be linked to their account:
 
 ```typescript
 'use client';
@@ -2188,8 +2835,9 @@ When building a store, implement these pages:
 - [ ] **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
+- [ ] **Login** (`/login`) - Customer login + social login buttons (Google/Facebook/GitHub if available)
+- [ ] **Register** (`/register`) - Customer registration + social signup buttons
+- [ ] **Auth Callback** (`/auth/callback`) - Handle OAuth redirects from Google/Facebook/GitHub
 - [ ] **Verify Email** (`/verify-email`) - Email verification with 6-digit code (if store requires it)
 - [ ] **Account** (`/account`) - Profile and order history