omni-sync-sdk 0.21.1 → 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
@@ -331,16 +356,74 @@ suggestions.products.map(p => (
 ));
 ```
 
+### 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!
+```
 
-| Customer Type | Cart Type                 | Checkout Method      | Orders Linked to Account? |
-| ------------- | ------------------------- | -------------------- | ------------------------- |
-| **Guest**     | Local Cart (localStorage) | `submitGuestOrder()` | No                        |
-| **Logged In** | Server Cart               | `completeCheckout()` | Yes                       |
+### ✅ Correct Flow for Guest Checkout with Payment
+
+```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
 
@@ -1543,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:
@@ -1753,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';
@@ -1772,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');
 
@@ -1857,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/package.json

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