omni-sync-sdk 0.8.0 → 0.8.2

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,60 @@ 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 customer info (REQUIRED - email is needed for order!)
+await omni.setCheckoutCustomer(checkout.id, {
+  email: 'customer@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+});
+
+// 6. Set shipping address
+await omni.setShippingAddress(checkout.id, {
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  city: 'New York',
+  postalCode: '10001',
+  country: 'US',
+});
+
+// 7. Get shipping rates and select one
+const rates = await omni.getShippingRates(checkout.id);
+await omni.selectShippingMethod(checkout.id, rates[0].id);
+
+// 8. 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 +167,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 +415,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:
@@ -1789,9 +1938,190 @@ 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 customer info (REQUIRED - even for logged-in customers!)
+        await omni.setCheckoutCustomer(checkoutId, {
+          email: email, // Get from form or customer profile
+          firstName: shippingAddress.firstName,
+          lastName: shippingAddress.lastName,
+        });
+
+        // 2. Set shipping address
+        await omni.setShippingAddress(checkoutId, shippingAddress);
+
+        // 3. Get and select shipping rate
+        const rates = await omni.getShippingRates(checkoutId);
+        if (rates.length > 0) {
+          await omni.selectShippingMethod(checkoutId, selectedRate || rates[0].id);
+        }
+
+        // 4. 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';
@@ -1957,9 +2287,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';

package/dist/index.d.mts

@@ -76,6 +76,7 @@ interface Product {
     costPrice?: number | null;
     status: 'active' | 'draft' | 'archived';
     type: 'SIMPLE' | 'VARIABLE';
+    isDownloadable?: boolean;
     images?: ProductImage[];
     inventory?: InventoryInfo | null;
     variants?: ProductVariant[];
@@ -110,6 +111,7 @@ interface ProductQueryParams {
     search?: string;
     status?: 'active' | 'draft' | 'archived';
     type?: 'SIMPLE' | 'VARIABLE';
+    isDownloadable?: boolean;
     sortBy?: 'name' | 'createdAt' | 'updatedAt' | 'basePrice';
     sortOrder?: 'asc' | 'desc';
 }
@@ -157,6 +159,7 @@ interface CreateProductDto {
     costPrice?: number;
     status?: 'active' | 'draft';
     type?: 'SIMPLE' | 'VARIABLE';
+    isDownloadable?: boolean;
     categories?: string[];
     tags?: string[];
     images?: ProductImage[];
@@ -169,6 +172,7 @@ interface UpdateProductDto {
     salePrice?: number | null;
     costPrice?: number | null;
     status?: 'active' | 'draft' | 'archived';
+    isDownloadable?: boolean;
     categories?: string[];
     tags?: string[];
     images?: ProductImage[];

package/dist/index.d.ts

@@ -76,6 +76,7 @@ interface Product {
     costPrice?: number | null;
     status: 'active' | 'draft' | 'archived';
     type: 'SIMPLE' | 'VARIABLE';
+    isDownloadable?: boolean;
     images?: ProductImage[];
     inventory?: InventoryInfo | null;
     variants?: ProductVariant[];
@@ -110,6 +111,7 @@ interface ProductQueryParams {
     search?: string;
     status?: 'active' | 'draft' | 'archived';
     type?: 'SIMPLE' | 'VARIABLE';
+    isDownloadable?: boolean;
     sortBy?: 'name' | 'createdAt' | 'updatedAt' | 'basePrice';
     sortOrder?: 'asc' | 'desc';
 }
@@ -157,6 +159,7 @@ interface CreateProductDto {
     costPrice?: number;
     status?: 'active' | 'draft';
     type?: 'SIMPLE' | 'VARIABLE';
+    isDownloadable?: boolean;
     categories?: string[];
     tags?: string[];
     images?: ProductImage[];
@@ -169,6 +172,7 @@ interface UpdateProductDto {
     salePrice?: number | null;
     costPrice?: number | null;
     status?: 'active' | 'draft' | 'archived';
+    isDownloadable?: boolean;
     categories?: string[];
     tags?: string[];
     images?: ProductImage[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omni-sync-sdk",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Official SDK for building e-commerce storefronts with OmniSync Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",