omni-sync-sdk 0.21.0 → 0.21.2

package/README.md

@@ -121,7 +121,32 @@ const { data: products } = await omni.getProducts();
 
 > **AI Agents / Vibe-Coders:** Read this section carefully! These are common misunderstandings.
 
-### 1. All Types Are Exported - Don't Create Local Interfaces!
+### 1. Guest Checkout - Don't Use createCheckout with Local Cart!
+
+**This is the #1 cause of "Cart not found" errors!**
+
+```typescript
+// ❌ WRONG - Local cart ID "__local__" doesn't exist on server!
+const cart = await omni.smartGetCart(); // Returns { id: "__local__", ... }
+const checkout = await omni.createCheckout({ cartId: cart.id }); // 💥 ERROR: Cart not found
+
+// ✅ CORRECT - Use startGuestCheckout() for guest users
+const result = await omni.startGuestCheckout();
+if (result.tracked) {
+  const checkout = await omni.getCheckout(result.checkoutId);
+  // Continue with payment flow...
+}
+
+// ✅ ALTERNATIVE - Use submitGuestOrder() for simple checkout without payment UI
+const order = await omni.submitGuestOrder();
+```
+
+**Rule of thumb:**
+
+- Guest user + Local cart → `startGuestCheckout()` or `submitGuestOrder()`
+- Logged-in user + Server cart → `createCheckout({ cartId })`
+
+### 2. All Types Are Exported - Don't Create Local Interfaces!
 
 ```typescript
 // ❌ WRONG - Don't create these locally
@@ -147,19 +172,32 @@ formatPrice(amount, 'USD');
 formatPrice(amount, { currency: 'USD' });
 ```
 
-### 3. Order Fields - Use Correct Names
+### 3. Cart/Checkout vs Order - Different Item Structures!
+
+**IMPORTANT:** Cart and Checkout items have NESTED product data. Order items are FLAT.
 
 ```typescript
-// ❌ WRONG
-order.total;
-item.product.name;
+// CartItem and CheckoutLineItem - NESTED product
+cart.items.forEach((item) => {
+  console.log(item.product.name); // ✅ Correct for Cart/Checkout
+  console.log(item.product.sku);
+  console.log(item.product.images);
+});
 
-// ✅ CORRECT
-order.totalAmount; // or order.total (alias)
-item.name; // flat, not nested
-item.image; // flat, not nested
+// OrderItem - FLAT structure
+order.items.forEach((item) => {
+  console.log(item.name); // ✅ Correct for Orders
+  console.log(item.sku);
+  console.log(item.image); // singular, not images
+});
 ```
 
+| Type               | Access Name         | Access Image          |
+| ------------------ | ------------------- | --------------------- |
+| `CartItem`         | `item.product.name` | `item.product.images` |
+| `CheckoutLineItem` | `item.product.name` | `item.product.images` |
+| `OrderItem`        | `item.name`         | `item.image`          |
+
 ### 4. Payment Status is 'succeeded', not 'completed'
 
 ```typescript
@@ -206,16 +244,186 @@ const color = variant.attributes?.['Color']; // string
 const size = variant.attributes?.['Size']; // string
 ```
 
+### 8. Address Uses `region`, NOT `state`
+
+```typescript
+// ❌ WRONG
+const address = {
+  state: 'NY', // This field doesn't exist!
+};
+
+// ✅ CORRECT
+const address: SetShippingAddressDto = {
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  city: 'New York',
+  region: 'NY', // Use 'region' for state/province
+  postalCode: '10001',
+  country: 'US',
+};
+```
+
+### 9. OAuth - Use `authorizationUrl`, NOT `url`
+
+```typescript
+// ❌ WRONG
+const response = await omni.getOAuthAuthorizeUrl('GOOGLE', { redirectUrl });
+window.location.href = response.url; // 'url' doesn't exist!
+
+// ✅ CORRECT
+const response = await omni.getOAuthAuthorizeUrl('GOOGLE', { redirectUrl });
+window.location.href = response.authorizationUrl; // Correct property name
+```
+
+### 10. OAuth Provider Type is Exported
+
+```typescript
+// ❌ WRONG - creating your own type
+type Provider = 'google' | 'facebook'; // lowercase won't work!
+
+// ✅ CORRECT - import from SDK
+import { CustomerOAuthProvider } from 'omni-sync-sdk';
+// CustomerOAuthProvider = 'GOOGLE' | 'FACEBOOK' | 'GITHUB'  (UPPERCASE)
+
+const provider: CustomerOAuthProvider = 'GOOGLE';
+await omni.getOAuthAuthorizeUrl(provider, { redirectUrl });
+```
+
+### 11. getAvailableOAuthProviders Returns Object, Not Array
+
+```typescript
+// ❌ WRONG - expecting array directly
+const providers = await omni.getAvailableOAuthProviders();
+providers.forEach(p => ...);  // Error! providers is not an array
+
+// ✅ CORRECT - access the providers property
+const response = await omni.getAvailableOAuthProviders();
+response.providers.forEach(p => ...);  // response.providers is the array
+```
+
+### 12. SDK Uses `null`, Not `undefined`
+
+Optional fields in SDK types use `null`, not `undefined`:
+
+```typescript
+// SDK types use:
+slug: string | null;
+salePrice: string | null;
+
+// So when checking:
+if (product.slug !== null) {
+  // ✅ Check for null
+  // ...
+}
+```
+
+### 13. Cart Has No `total` Field - Use `getCartTotals()` Helper
+
+```typescript
+// ❌ WRONG - these fields don't exist on Cart
+const total = cart.total; // ← 'total' doesn't exist!
+const discount = cart.discount; // ← 'discount' doesn't exist! It's 'discountAmount'
+
+// ✅ CORRECT - use the helper function (RECOMMENDED)
+import { getCartTotals } from 'omni-sync-sdk';
+const totals = getCartTotals(cart, shippingPrice);
+// Returns: { subtotal: 59.98, discount: 10, shipping: 5.99, total: 55.97 }
+
+// ✅ CORRECT - or calculate manually
+const subtotal = parseFloat(cart.subtotal);
+const discount = parseFloat(cart.discountAmount); // ← Note: 'discountAmount', NOT 'discount'
+const total = subtotal - discount;
+```
+
+**Important Notes:**
+
+- Cart field is `discountAmount`, NOT `discount`
+- Cart has NO `total` field - use `getCartTotals()` or calculate
+- Checkout DOES have a `total` field, but Cart does not
+
+### 14. SearchSuggestions - Products Have `price`, Not `basePrice`
+
+```typescript
+// In SearchSuggestions, ProductSuggestion has:
+// - price: effective price (sale price if on sale, otherwise base price)
+// - basePrice: original price
+// - salePrice: sale price if on sale
+
+// ✅ Use 'price' for display (it's already the correct price)
+suggestions.products.map(p => (
+  <div>{p.name} - {formatPrice(p.price, { currency })}</div>
+));
+```
+
+### 15. Forgetting to Clear Cart After Payment
+
+**This causes "ghost items" in the cart after successful payment!**
+
+```typescript
+// ❌ WRONG - Cart items remain after payment!
+// In your success page:
+export default function SuccessPage() {
+  return <div>Thank you for your order!</div>;
+  // User goes back to shop → still sees purchased items in cart!
+}
+
+// ✅ CORRECT - Call handlePaymentSuccess() on success page
+export default function SuccessPage() {
+  const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
+
+  useEffect(() => {
+    // Clear cart items that were purchased
+    omni.handlePaymentSuccess(checkoutId);
+  }, []);
+
+  return <div>Thank you for your order!</div>;
+}
+```
+
+**Why is this needed?**
+
+- Guest users: Local cart persists in localStorage across page refreshes and Stripe redirects
+- Without cleanup, purchased items remain visible in cart
+- `handlePaymentSuccess()` handles both full and partial checkout cleanup
+
 ---
 
 ## 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.
+> **⚠️ CRITICAL:** There are TWO different checkout flows. Using the wrong one will cause errors!
+
+| Customer Type | Cart Type                 | With Payment (Stripe)  | Without Payment UI   |
+| ------------- | ------------------------- | ---------------------- | -------------------- |
+| **Guest**     | Local Cart (localStorage) | `startGuestCheckout()` | `submitGuestOrder()` |
+| **Logged In** | Server Cart               | `createCheckout()`     | `completeCheckout()` |
+
+### ❌ COMMON MISTAKE - Don't Do This!
+
+```typescript
+// ❌ WRONG - This will FAIL with "Cart not found" error!
+const cart = omni.getLocalCart(); // Returns cart with id: "__local__"
+const checkout = await omni.createCheckout({ cartId: cart.id }); // ERROR!
+
+// The "__local__" ID is virtual - it doesn't exist on the server!
+```
+
+### ✅ Correct Flow for Guest Checkout with Payment
 
-| Customer Type | Cart Type                 | Checkout Method      | Orders Linked to Account? |
-| ------------- | ------------------------- | -------------------- | ------------------------- |
-| **Guest**     | Local Cart (localStorage) | `submitGuestOrder()` | No                        |
-| **Logged In** | Server Cart               | `completeCheckout()` | Yes                       |
+```typescript
+// ✅ CORRECT - Use startGuestCheckout() for guests with local cart
+const result = await omni.startGuestCheckout();
+
+if (result.tracked) {
+  // Now you have a REAL checkout on the server
+  const checkout = await omni.getCheckout(result.checkoutId);
+
+  // Continue with shipping, payment, etc.
+  await omni.setShippingAddress(result.checkoutId, { ... });
+  const intent = await omni.createPaymentIntent(result.checkoutId);
+  // ... Stripe payment ...
+}
+```
 
 ### Decision Flow
 
@@ -1418,6 +1626,22 @@ function canProceedToPayment(checkout: Checkout, rates: ShippingRate[]): boolean
 
 For vibe-coded sites, the SDK provides payment integration with Stripe and PayPal. The store owner configures their payment provider(s) in the admin, and your site uses these methods to process payments.
 
+#### ⚠️ Important: Getting a Valid Checkout ID
+
+Before creating a payment intent, you need a checkout ID. How you get it depends on the customer type:
+
+```typescript
+// For GUEST users (local cart in localStorage):
+const result = await omni.startGuestCheckout();
+const checkoutId = result.checkoutId;
+
+// For LOGGED-IN users (server cart):
+const checkout = await omni.createCheckout({ cartId: serverCartId });
+const checkoutId = checkout.id;
+
+// Then continue with shipping and payment...
+```
+
 #### Get All Payment Providers (Recommended)
 
 Use this method to get ALL enabled payment providers and build dynamic UI:
@@ -1628,6 +1852,20 @@ if (status.status === 'succeeded' && status.orderId) {
 
 #### Complete Checkout with Payment Example
 
+> **Note:** This example assumes you already have a `checkout_id`. See below for how to create one.
+
+**How to get a checkout_id:**
+
+```typescript
+// For GUEST users (local cart):
+const result = await omni.startGuestCheckout();
+const checkoutId = result.checkoutId; // Use this!
+
+// For LOGGED-IN users (server cart):
+const checkout = await omni.createCheckout({ cartId: cart.id });
+const checkoutId = checkout.id; // Use this!
+```
+
 ```typescript
 'use client';
 import { useState, useEffect } from 'react';
@@ -1647,7 +1885,7 @@ export default function CheckoutPaymentPage() {
   useEffect(() => {
     async function initPayment() {
       try {
-        // Assume checkout is already created and shipping is set
+        // Get checkout_id from URL (set by previous step)
         const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
         if (!checkoutId) throw new Error('No checkout ID');
 
@@ -1732,6 +1970,48 @@ function PaymentForm({ checkoutId }: { checkoutId: string }) {
 }
 ```
 
+#### Cart Cleanup After Payment: `handlePaymentSuccess()`
+
+**CRITICAL:** After payment succeeds, you MUST call `handlePaymentSuccess()` to clear the cart. This ensures:
+
+- Guest users: Local cart items are removed (full or partial based on what was purchased)
+- Logged-in users: Server cart is cleared
+
+```typescript
+// On your /checkout/success page:
+export default function CheckoutSuccessPage() {
+  const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
+
+  useEffect(() => {
+    // IMPORTANT: Call this to clear the cart after successful payment
+    const result = omni.handlePaymentSuccess(checkoutId);
+
+    console.log('Cart cleanup:', result);
+    // { cleared: true, mode: 'full' | 'partial', userType: 'guest' | 'customer' }
+  }, []);
+
+  return (
+    <div className="text-center py-12">
+      <h1 className="text-2xl font-bold text-green-600">Payment Received!</h1>
+      {/* ... rest of success page */}
+    </div>
+  );
+}
+```
+
+**How it works:**
+| User Type | Cart Type | Behavior |
+|-----------|-----------|----------|
+| Guest (partial checkout) | Local cart | Only removes purchased items |
+| Guest (full checkout) | Local cart | Clears entire cart |
+| Logged-in | Server cart | Clears cart via SDK state |
+
+**Why is this needed?**
+
+- After Stripe redirects back to your success page, the cart is still in localStorage/memory
+- Without calling `handlePaymentSuccess()`, users will see their "purchased" items still in cart
+- For partial checkout (AliExpress-style), only the purchased items are removed
+
 ---
 
 ### Customer Authentication

package/dist/index.js

@@ -2260,6 +2260,12 @@ var OmniSyncClient = class {
    * ```
    */
   async createCheckout(data) {
+    if (data.cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      throw new OmniSyncError(
+        "Cannot create checkout from local cart directly. Use startGuestCheckout() for guest checkout with localStorage cart, or sync cart to server first with syncCartOnLogin().",
+        400
+      );
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("POST", "/checkout", data);
     }

package/dist/index.mjs

@@ -2223,6 +2223,12 @@ var OmniSyncClient = class {
    * ```
    */
   async createCheckout(data) {
+    if (data.cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      throw new OmniSyncError(
+        "Cannot create checkout from local cart directly. Use startGuestCheckout() for guest checkout with localStorage cart, or sync cart to server first with syncCartOnLogin().",
+        400
+      );
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("POST", "/checkout", data);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omni-sync-sdk",
-  "version": "0.21.0",
+  "version": "0.21.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",