omni-sync-sdk 0.20.3 → 0.21.1

package/README.md

@@ -147,19 +147,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,6 +219,118 @@ 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>
+));
+```
+
 ---
 
 ## Checkout: Guest vs Logged-In Customer

package/dist/index.d.mts

@@ -1692,15 +1692,27 @@ interface ShippingRate {
  * **Note:** Order is created automatically via webhook when payment succeeds.
  * No need to call `completeCheckout()` - it happens automatically.
  *
+ * **IMPORTANT: Order Summary Display**
+ * Always use `checkout.lineItems` for displaying the Order Summary during checkout!
+ * This is especially important for **partial checkout** (AliExpress-style) where the user
+ * selects only some items from their cart. The `lineItems` array contains ONLY the items
+ * being purchased in this checkout, NOT the entire cart.
+ *
  * **IMPORTANT: Price fields are strings**
  * All monetary fields (subtotal, discountAmount, shippingAmount, taxAmount, total)
  * are strings to preserve decimal precision. Use parseFloat() for calculations.
  *
  * @example
  * ```typescript
- * // Display checkout summary
+ * // Display checkout summary - use checkout.lineItems, NOT localCart!
  * const checkout = await omni.getCheckout(checkoutId);
  *
+ * // Order Summary - ALWAYS use checkout.lineItems
+ * checkout.lineItems.forEach(item => {
+ *   console.log(item.product.name, item.quantity, item.unitPrice);
+ * });
+ *
+ * // Totals
  * const subtotal = parseFloat(checkout.subtotal);
  * const discount = parseFloat(checkout.discountAmount);
  * const shipping = parseFloat(checkout.shippingAmount);
@@ -1712,11 +1724,6 @@ interface ShippingRate {
  * console.log(`Shipping: $${shipping.toFixed(2)}`);
  * console.log(`Tax: $${tax.toFixed(2)}`);
  * console.log(`Total: $${total.toFixed(2)}`);
- *
- * // Access line items (nested structure)
- * checkout.lineItems.forEach(item => {
- *   console.log(item.product.name, item.quantity);
- * });
  * ```
  *
  * @see CheckoutLineItem for item structure
@@ -3057,6 +3064,11 @@ declare class OmniSyncClient {
      * When a cart has this ID, operations use localStorage instead of server API.
      */
     private readonly VIRTUAL_LOCAL_CART_ID;
+    /**
+     * localStorage key for persisting active checkout across page redirects.
+     * This is needed because Stripe redirects lose in-memory state.
+     */
+    private readonly ACTIVE_CHECKOUT_KEY;
     private readonly onAuthError?;
     constructor(options: OmniSyncClientOptions);
     /**
@@ -4748,6 +4760,11 @@ declare class OmniSyncClient {
      * Pass `selectedIndices` to checkout only specific items from the local cart.
      * Use the index of each item in the cart.items array.
      *
+     * **IMPORTANT - Order Summary Display:**
+     * After calling this function, use `getCheckout(checkoutId)` to get the checkout
+     * and display `checkout.lineItems` in your Order Summary - NOT the local cart items!
+     * The checkout.lineItems contains ONLY the selected items for this checkout.
+     *
      * @param options.selectedIndices - Optional array of item indices for partial checkout
      * @returns Tracking result with checkoutId if enabled
      *
@@ -4760,19 +4777,22 @@ declare class OmniSyncClient {
      * const result = await omni.startGuestCheckout({ selectedIndices: [0, 2] });
      *
      * if (result.tracked) {
-     *   // Store checkoutId for later use
-     *   console.log('Checkout tracked:', result.checkoutId);
+     *   // IMPORTANT: Fetch checkout and use checkout.lineItems for Order Summary!
+     *   const checkout = await omni.getCheckout(result.checkoutId);
+     *
+     *   // Display Order Summary using checkout.lineItems (NOT localCart.items!)
+     *   // checkout.lineItems contains ONLY the selected items
+     *   checkout.lineItems.forEach(item => {
+     *     console.log(item.product.name, item.quantity, item.unitPrice);
+     *   });
      *
      *   // Update checkout with address
-     *   await omni.updateGuestCheckout(result.checkoutId, {
+     *   await omni.updateGuestCheckoutAddress(result.checkoutId, {
      *     shippingAddress: { ... },
      *   });
      *
-     *   // Complete checkout
-     *   const order = await omni.completeGuestCheckout(result.checkoutId);
-     *
-     *   // For partial checkout: remove only purchased items
-     *   omni.removeLocalCartItemsByIndex([0, 2]);
+     *   // After payment success, call handlePaymentSuccess() to clear cart
+     *   omni.handlePaymentSuccess(result.checkoutId);
      * } else {
      *   // Tracking not enabled, use regular submitGuestOrder
      *   const order = await omni.submitGuestOrder();
@@ -4782,6 +4802,21 @@ declare class OmniSyncClient {
     startGuestCheckout(options?: {
         selectedIndices?: number[];
     }): Promise<GuestCheckoutStartResponse>;
+    /**
+     * Save active checkout to localStorage (persists across page redirects)
+     * @internal
+     */
+    private saveActiveCheckout;
+    /**
+     * Load active checkout from localStorage
+     * @internal
+     */
+    private loadActiveCheckout;
+    /**
+     * Clear active checkout from localStorage
+     * @internal
+     */
+    private clearActiveCheckoutStorage;
     /**
      * Remove specific items from local cart by their indices.
      * Use after partial checkout to remove only the purchased items.
@@ -4829,6 +4864,83 @@ declare class OmniSyncClient {
         clearCartOnSuccess?: boolean;
         selectedIndices?: number[];
     }): Promise<GuestOrderResponse>;
+    /**
+     * Get the active guest checkout session info.
+     * Use this to check if there's an active checkout before handling payment success.
+     *
+     * @returns The active checkout info or null if no checkout is active
+     *
+     * @example
+     * ```typescript
+     * const activeCheckout = omni.getActiveGuestCheckout();
+     * if (activeCheckout) {
+     *   console.log('Active checkout:', activeCheckout.checkoutId);
+     *   console.log('Partial checkout:', activeCheckout.selectedIndices?.length);
+     * }
+     * ```
+     */
+    getActiveGuestCheckout(): {
+        checkoutId: string;
+        cartId: string;
+        selectedIndices?: number[];
+    } | null;
+    /**
+     * Handle payment success - automatically clears the cart (both local and server).
+     *
+     * Call this after Stripe payment succeeds (payment_intent.succeeded or confirmPayment success).
+     * This handles ALL checkout scenarios:
+     *
+     * **For guest users (local cart):**
+     * - Full checkout: clears entire localStorage cart
+     * - Partial checkout: removes only the purchased items
+     *
+     * **For logged-in users (server cart):**
+     * - Clears the cached cart ID so next `smartGetCart()` fetches fresh data
+     * - The server cart is already marked as CONVERTED by the webhook
+     *
+     * **IMPORTANT:** Call this from your payment success handler (e.g., after stripe.confirmPayment succeeds,
+     * or on your success page after redirect). This works for both guests AND logged-in users!
+     *
+     * @param checkoutId - Optional checkout ID for validation
+     * @returns Object indicating whether cart was cleared and how
+     *
+     * @example
+     * ```typescript
+     * // After stripe.confirmPayment() succeeds (works for guests AND logged-in users)
+     * const { error, paymentIntent } = await stripe.confirmPayment({
+     *   elements,
+     *   confirmParams: { return_url: '/checkout/success' },
+     *   redirect: 'if_required',
+     * });
+     *
+     * if (!error && paymentIntent?.status === 'succeeded') {
+     *   // Clear the cart automatically - handles all scenarios!
+     *   const result = omni.handlePaymentSuccess(checkoutId);
+     *   console.log('Cart cleared:', result.cleared);
+     *   console.log('User type:', result.userType); // 'guest' or 'customer'
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // On success page (after redirect)
+     * const checkoutId = new URLSearchParams(location.search).get('checkout_id');
+     * if (checkoutId) {
+     *   omni.handlePaymentSuccess(checkoutId);
+     * }
+     * ```
+     */
+    handlePaymentSuccess(checkoutId?: string): {
+        cleared: boolean;
+        mode: 'full' | 'partial' | 'none';
+        userType: 'guest' | 'customer';
+        itemsRemoved?: number;
+    };
+    /**
+     * Clear the active guest checkout tracking without clearing the cart.
+     * Use this if the user abandons checkout or navigates away.
+     */
+    clearActiveGuestCheckout(): void;
     /**
      * Create order from custom data (not from local cart)
      * Use this if you manage cart state yourself

package/dist/index.d.ts

@@ -1692,15 +1692,27 @@ interface ShippingRate {
  * **Note:** Order is created automatically via webhook when payment succeeds.
  * No need to call `completeCheckout()` - it happens automatically.
  *
+ * **IMPORTANT: Order Summary Display**
+ * Always use `checkout.lineItems` for displaying the Order Summary during checkout!
+ * This is especially important for **partial checkout** (AliExpress-style) where the user
+ * selects only some items from their cart. The `lineItems` array contains ONLY the items
+ * being purchased in this checkout, NOT the entire cart.
+ *
  * **IMPORTANT: Price fields are strings**
  * All monetary fields (subtotal, discountAmount, shippingAmount, taxAmount, total)
  * are strings to preserve decimal precision. Use parseFloat() for calculations.
  *
  * @example
  * ```typescript
- * // Display checkout summary
+ * // Display checkout summary - use checkout.lineItems, NOT localCart!
  * const checkout = await omni.getCheckout(checkoutId);
  *
+ * // Order Summary - ALWAYS use checkout.lineItems
+ * checkout.lineItems.forEach(item => {
+ *   console.log(item.product.name, item.quantity, item.unitPrice);
+ * });
+ *
+ * // Totals
  * const subtotal = parseFloat(checkout.subtotal);
  * const discount = parseFloat(checkout.discountAmount);
  * const shipping = parseFloat(checkout.shippingAmount);
@@ -1712,11 +1724,6 @@ interface ShippingRate {
  * console.log(`Shipping: $${shipping.toFixed(2)}`);
  * console.log(`Tax: $${tax.toFixed(2)}`);
  * console.log(`Total: $${total.toFixed(2)}`);
- *
- * // Access line items (nested structure)
- * checkout.lineItems.forEach(item => {
- *   console.log(item.product.name, item.quantity);
- * });
  * ```
  *
  * @see CheckoutLineItem for item structure
@@ -3057,6 +3064,11 @@ declare class OmniSyncClient {
      * When a cart has this ID, operations use localStorage instead of server API.
      */
     private readonly VIRTUAL_LOCAL_CART_ID;
+    /**
+     * localStorage key for persisting active checkout across page redirects.
+     * This is needed because Stripe redirects lose in-memory state.
+     */
+    private readonly ACTIVE_CHECKOUT_KEY;
     private readonly onAuthError?;
     constructor(options: OmniSyncClientOptions);
     /**
@@ -4748,6 +4760,11 @@ declare class OmniSyncClient {
      * Pass `selectedIndices` to checkout only specific items from the local cart.
      * Use the index of each item in the cart.items array.
      *
+     * **IMPORTANT - Order Summary Display:**
+     * After calling this function, use `getCheckout(checkoutId)` to get the checkout
+     * and display `checkout.lineItems` in your Order Summary - NOT the local cart items!
+     * The checkout.lineItems contains ONLY the selected items for this checkout.
+     *
      * @param options.selectedIndices - Optional array of item indices for partial checkout
      * @returns Tracking result with checkoutId if enabled
      *
@@ -4760,19 +4777,22 @@ declare class OmniSyncClient {
      * const result = await omni.startGuestCheckout({ selectedIndices: [0, 2] });
      *
      * if (result.tracked) {
-     *   // Store checkoutId for later use
-     *   console.log('Checkout tracked:', result.checkoutId);
+     *   // IMPORTANT: Fetch checkout and use checkout.lineItems for Order Summary!
+     *   const checkout = await omni.getCheckout(result.checkoutId);
+     *
+     *   // Display Order Summary using checkout.lineItems (NOT localCart.items!)
+     *   // checkout.lineItems contains ONLY the selected items
+     *   checkout.lineItems.forEach(item => {
+     *     console.log(item.product.name, item.quantity, item.unitPrice);
+     *   });
      *
      *   // Update checkout with address
-     *   await omni.updateGuestCheckout(result.checkoutId, {
+     *   await omni.updateGuestCheckoutAddress(result.checkoutId, {
      *     shippingAddress: { ... },
      *   });
      *
-     *   // Complete checkout
-     *   const order = await omni.completeGuestCheckout(result.checkoutId);
-     *
-     *   // For partial checkout: remove only purchased items
-     *   omni.removeLocalCartItemsByIndex([0, 2]);
+     *   // After payment success, call handlePaymentSuccess() to clear cart
+     *   omni.handlePaymentSuccess(result.checkoutId);
      * } else {
      *   // Tracking not enabled, use regular submitGuestOrder
      *   const order = await omni.submitGuestOrder();
@@ -4782,6 +4802,21 @@ declare class OmniSyncClient {
     startGuestCheckout(options?: {
         selectedIndices?: number[];
     }): Promise<GuestCheckoutStartResponse>;
+    /**
+     * Save active checkout to localStorage (persists across page redirects)
+     * @internal
+     */
+    private saveActiveCheckout;
+    /**
+     * Load active checkout from localStorage
+     * @internal
+     */
+    private loadActiveCheckout;
+    /**
+     * Clear active checkout from localStorage
+     * @internal
+     */
+    private clearActiveCheckoutStorage;
     /**
      * Remove specific items from local cart by their indices.
      * Use after partial checkout to remove only the purchased items.
@@ -4829,6 +4864,83 @@ declare class OmniSyncClient {
         clearCartOnSuccess?: boolean;
         selectedIndices?: number[];
     }): Promise<GuestOrderResponse>;
+    /**
+     * Get the active guest checkout session info.
+     * Use this to check if there's an active checkout before handling payment success.
+     *
+     * @returns The active checkout info or null if no checkout is active
+     *
+     * @example
+     * ```typescript
+     * const activeCheckout = omni.getActiveGuestCheckout();
+     * if (activeCheckout) {
+     *   console.log('Active checkout:', activeCheckout.checkoutId);
+     *   console.log('Partial checkout:', activeCheckout.selectedIndices?.length);
+     * }
+     * ```
+     */
+    getActiveGuestCheckout(): {
+        checkoutId: string;
+        cartId: string;
+        selectedIndices?: number[];
+    } | null;
+    /**
+     * Handle payment success - automatically clears the cart (both local and server).
+     *
+     * Call this after Stripe payment succeeds (payment_intent.succeeded or confirmPayment success).
+     * This handles ALL checkout scenarios:
+     *
+     * **For guest users (local cart):**
+     * - Full checkout: clears entire localStorage cart
+     * - Partial checkout: removes only the purchased items
+     *
+     * **For logged-in users (server cart):**
+     * - Clears the cached cart ID so next `smartGetCart()` fetches fresh data
+     * - The server cart is already marked as CONVERTED by the webhook
+     *
+     * **IMPORTANT:** Call this from your payment success handler (e.g., after stripe.confirmPayment succeeds,
+     * or on your success page after redirect). This works for both guests AND logged-in users!
+     *
+     * @param checkoutId - Optional checkout ID for validation
+     * @returns Object indicating whether cart was cleared and how
+     *
+     * @example
+     * ```typescript
+     * // After stripe.confirmPayment() succeeds (works for guests AND logged-in users)
+     * const { error, paymentIntent } = await stripe.confirmPayment({
+     *   elements,
+     *   confirmParams: { return_url: '/checkout/success' },
+     *   redirect: 'if_required',
+     * });
+     *
+     * if (!error && paymentIntent?.status === 'succeeded') {
+     *   // Clear the cart automatically - handles all scenarios!
+     *   const result = omni.handlePaymentSuccess(checkoutId);
+     *   console.log('Cart cleared:', result.cleared);
+     *   console.log('User type:', result.userType); // 'guest' or 'customer'
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // On success page (after redirect)
+     * const checkoutId = new URLSearchParams(location.search).get('checkout_id');
+     * if (checkoutId) {
+     *   omni.handlePaymentSuccess(checkoutId);
+     * }
+     * ```
+     */
+    handlePaymentSuccess(checkoutId?: string): {
+        cleared: boolean;
+        mode: 'full' | 'partial' | 'none';
+        userType: 'guest' | 'customer';
+        itemsRemoved?: number;
+    };
+    /**
+     * Clear the active guest checkout tracking without clearing the cart.
+     * Use this if the user abandons checkout or navigates away.
+     */
+    clearActiveGuestCheckout(): void;
     /**
      * Create order from custom data (not from local cart)
      * Use this if you manage cart state yourself

package/dist/index.js

@@ -54,6 +54,11 @@ var OmniSyncClient = class {
      * When a cart has this ID, operations use localStorage instead of server API.
      */
     this.VIRTUAL_LOCAL_CART_ID = "__local__";
+    /**
+     * localStorage key for persisting active checkout across page redirects.
+     * This is needed because Stripe redirects lose in-memory state.
+     */
+    this.ACTIVE_CHECKOUT_KEY = "omni_active_checkout";
     // -------------------- Local Cart (Client-Side for Guests) --------------------
     // These methods store cart data in localStorage - NO API calls!
     // Use for guest users in vibe-coded sites
@@ -2255,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);
     }
@@ -3069,6 +3080,11 @@ var OmniSyncClient = class {
    * Pass `selectedIndices` to checkout only specific items from the local cart.
    * Use the index of each item in the cart.items array.
    *
+   * **IMPORTANT - Order Summary Display:**
+   * After calling this function, use `getCheckout(checkoutId)` to get the checkout
+   * and display `checkout.lineItems` in your Order Summary - NOT the local cart items!
+   * The checkout.lineItems contains ONLY the selected items for this checkout.
+   *
    * @param options.selectedIndices - Optional array of item indices for partial checkout
    * @returns Tracking result with checkoutId if enabled
    *
@@ -3081,19 +3097,22 @@ var OmniSyncClient = class {
    * const result = await omni.startGuestCheckout({ selectedIndices: [0, 2] });
    *
    * if (result.tracked) {
-   *   // Store checkoutId for later use
-   *   console.log('Checkout tracked:', result.checkoutId);
+   *   // IMPORTANT: Fetch checkout and use checkout.lineItems for Order Summary!
+   *   const checkout = await omni.getCheckout(result.checkoutId);
+   *
+   *   // Display Order Summary using checkout.lineItems (NOT localCart.items!)
+   *   // checkout.lineItems contains ONLY the selected items
+   *   checkout.lineItems.forEach(item => {
+   *     console.log(item.product.name, item.quantity, item.unitPrice);
+   *   });
    *
    *   // Update checkout with address
-   *   await omni.updateGuestCheckout(result.checkoutId, {
+   *   await omni.updateGuestCheckoutAddress(result.checkoutId, {
    *     shippingAddress: { ... },
    *   });
    *
-   *   // Complete checkout
-   *   const order = await omni.completeGuestCheckout(result.checkoutId);
-   *
-   *   // For partial checkout: remove only purchased items
-   *   omni.removeLocalCartItemsByIndex([0, 2]);
+   *   // After payment success, call handlePaymentSuccess() to clear cart
+   *   omni.handlePaymentSuccess(result.checkoutId);
    * } else {
    *   // Tracking not enabled, use regular submitGuestOrder
    *   const order = await omni.submitGuestOrder();
@@ -3121,8 +3140,48 @@ var OmniSyncClient = class {
         customer: cart.customer
       }
     );
+    if (response.tracked && response.checkoutId && response.cartId) {
+      this.saveActiveCheckout({
+        checkoutId: response.checkoutId,
+        cartId: response.cartId,
+        selectedIndices: options?.selectedIndices
+      });
+    }
     return response;
   }
+  /**
+   * Save active checkout to localStorage (persists across page redirects)
+   * @internal
+   */
+  saveActiveCheckout(checkout) {
+    if (typeof window !== "undefined" && window.localStorage) {
+      localStorage.setItem(this.ACTIVE_CHECKOUT_KEY, JSON.stringify(checkout));
+    }
+  }
+  /**
+   * Load active checkout from localStorage
+   * @internal
+   */
+  loadActiveCheckout() {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return null;
+    }
+    try {
+      const data = localStorage.getItem(this.ACTIVE_CHECKOUT_KEY);
+      return data ? JSON.parse(data) : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Clear active checkout from localStorage
+   * @internal
+   */
+  clearActiveCheckoutStorage() {
+    if (typeof window !== "undefined" && window.localStorage) {
+      localStorage.removeItem(this.ACTIVE_CHECKOUT_KEY);
+    }
+  }
   /**
    * Remove specific items from local cart by their indices.
    * Use after partial checkout to remove only the purchased items.
@@ -3213,6 +3272,113 @@ var OmniSyncClient = class {
     }
     return result;
   }
+  /**
+   * Get the active guest checkout session info.
+   * Use this to check if there's an active checkout before handling payment success.
+   *
+   * @returns The active checkout info or null if no checkout is active
+   *
+   * @example
+   * ```typescript
+   * const activeCheckout = omni.getActiveGuestCheckout();
+   * if (activeCheckout) {
+   *   console.log('Active checkout:', activeCheckout.checkoutId);
+   *   console.log('Partial checkout:', activeCheckout.selectedIndices?.length);
+   * }
+   * ```
+   */
+  getActiveGuestCheckout() {
+    return this.loadActiveCheckout();
+  }
+  /**
+   * Handle payment success - automatically clears the cart (both local and server).
+   *
+   * Call this after Stripe payment succeeds (payment_intent.succeeded or confirmPayment success).
+   * This handles ALL checkout scenarios:
+   *
+   * **For guest users (local cart):**
+   * - Full checkout: clears entire localStorage cart
+   * - Partial checkout: removes only the purchased items
+   *
+   * **For logged-in users (server cart):**
+   * - Clears the cached cart ID so next `smartGetCart()` fetches fresh data
+   * - The server cart is already marked as CONVERTED by the webhook
+   *
+   * **IMPORTANT:** Call this from your payment success handler (e.g., after stripe.confirmPayment succeeds,
+   * or on your success page after redirect). This works for both guests AND logged-in users!
+   *
+   * @param checkoutId - Optional checkout ID for validation
+   * @returns Object indicating whether cart was cleared and how
+   *
+   * @example
+   * ```typescript
+   * // After stripe.confirmPayment() succeeds (works for guests AND logged-in users)
+   * const { error, paymentIntent } = await stripe.confirmPayment({
+   *   elements,
+   *   confirmParams: { return_url: '/checkout/success' },
+   *   redirect: 'if_required',
+   * });
+   *
+   * if (!error && paymentIntent?.status === 'succeeded') {
+   *   // Clear the cart automatically - handles all scenarios!
+   *   const result = omni.handlePaymentSuccess(checkoutId);
+   *   console.log('Cart cleared:', result.cleared);
+   *   console.log('User type:', result.userType); // 'guest' or 'customer'
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // On success page (after redirect)
+   * const checkoutId = new URLSearchParams(location.search).get('checkout_id');
+   * if (checkoutId) {
+   *   omni.handlePaymentSuccess(checkoutId);
+   * }
+   * ```
+   */
+  handlePaymentSuccess(checkoutId) {
+    const isLoggedIn = this.isCustomerLoggedIn();
+    if (isLoggedIn) {
+      this.customerCartId = null;
+    }
+    const activeCheckout = this.loadActiveCheckout();
+    if (checkoutId && activeCheckout && activeCheckout.checkoutId !== checkoutId) {
+      console.warn(
+        `handlePaymentSuccess: checkoutId mismatch. Expected ${activeCheckout.checkoutId}, got ${checkoutId}. Proceeding with cleanup.`
+      );
+    }
+    this.clearActiveCheckoutStorage();
+    if (isLoggedIn) {
+      this.clearLocalCart();
+      return {
+        cleared: true,
+        mode: "full",
+        userType: "customer"
+      };
+    }
+    if (activeCheckout?.selectedIndices && activeCheckout.selectedIndices.length > 0) {
+      this.removeLocalCartItemsByIndex(activeCheckout.selectedIndices);
+      return {
+        cleared: true,
+        mode: "partial",
+        userType: "guest",
+        itemsRemoved: activeCheckout.selectedIndices.length
+      };
+    }
+    this.clearLocalCart();
+    return {
+      cleared: true,
+      mode: "full",
+      userType: "guest"
+    };
+  }
+  /**
+   * Clear the active guest checkout tracking without clearing the cart.
+   * Use this if the user abandons checkout or navigates away.
+   */
+  clearActiveGuestCheckout() {
+    this.clearActiveCheckoutStorage();
+  }
   /**
    * Create order from custom data (not from local cart)
    * Use this if you manage cart state yourself

package/dist/index.mjs

@@ -17,6 +17,11 @@ var OmniSyncClient = class {
      * When a cart has this ID, operations use localStorage instead of server API.
      */
     this.VIRTUAL_LOCAL_CART_ID = "__local__";
+    /**
+     * localStorage key for persisting active checkout across page redirects.
+     * This is needed because Stripe redirects lose in-memory state.
+     */
+    this.ACTIVE_CHECKOUT_KEY = "omni_active_checkout";
     // -------------------- Local Cart (Client-Side for Guests) --------------------
     // These methods store cart data in localStorage - NO API calls!
     // Use for guest users in vibe-coded sites
@@ -2218,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);
     }
@@ -3032,6 +3043,11 @@ var OmniSyncClient = class {
    * Pass `selectedIndices` to checkout only specific items from the local cart.
    * Use the index of each item in the cart.items array.
    *
+   * **IMPORTANT - Order Summary Display:**
+   * After calling this function, use `getCheckout(checkoutId)` to get the checkout
+   * and display `checkout.lineItems` in your Order Summary - NOT the local cart items!
+   * The checkout.lineItems contains ONLY the selected items for this checkout.
+   *
    * @param options.selectedIndices - Optional array of item indices for partial checkout
    * @returns Tracking result with checkoutId if enabled
    *
@@ -3044,19 +3060,22 @@ var OmniSyncClient = class {
    * const result = await omni.startGuestCheckout({ selectedIndices: [0, 2] });
    *
    * if (result.tracked) {
-   *   // Store checkoutId for later use
-   *   console.log('Checkout tracked:', result.checkoutId);
+   *   // IMPORTANT: Fetch checkout and use checkout.lineItems for Order Summary!
+   *   const checkout = await omni.getCheckout(result.checkoutId);
+   *
+   *   // Display Order Summary using checkout.lineItems (NOT localCart.items!)
+   *   // checkout.lineItems contains ONLY the selected items
+   *   checkout.lineItems.forEach(item => {
+   *     console.log(item.product.name, item.quantity, item.unitPrice);
+   *   });
    *
    *   // Update checkout with address
-   *   await omni.updateGuestCheckout(result.checkoutId, {
+   *   await omni.updateGuestCheckoutAddress(result.checkoutId, {
    *     shippingAddress: { ... },
    *   });
    *
-   *   // Complete checkout
-   *   const order = await omni.completeGuestCheckout(result.checkoutId);
-   *
-   *   // For partial checkout: remove only purchased items
-   *   omni.removeLocalCartItemsByIndex([0, 2]);
+   *   // After payment success, call handlePaymentSuccess() to clear cart
+   *   omni.handlePaymentSuccess(result.checkoutId);
    * } else {
    *   // Tracking not enabled, use regular submitGuestOrder
    *   const order = await omni.submitGuestOrder();
@@ -3084,8 +3103,48 @@ var OmniSyncClient = class {
         customer: cart.customer
       }
     );
+    if (response.tracked && response.checkoutId && response.cartId) {
+      this.saveActiveCheckout({
+        checkoutId: response.checkoutId,
+        cartId: response.cartId,
+        selectedIndices: options?.selectedIndices
+      });
+    }
     return response;
   }
+  /**
+   * Save active checkout to localStorage (persists across page redirects)
+   * @internal
+   */
+  saveActiveCheckout(checkout) {
+    if (typeof window !== "undefined" && window.localStorage) {
+      localStorage.setItem(this.ACTIVE_CHECKOUT_KEY, JSON.stringify(checkout));
+    }
+  }
+  /**
+   * Load active checkout from localStorage
+   * @internal
+   */
+  loadActiveCheckout() {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return null;
+    }
+    try {
+      const data = localStorage.getItem(this.ACTIVE_CHECKOUT_KEY);
+      return data ? JSON.parse(data) : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Clear active checkout from localStorage
+   * @internal
+   */
+  clearActiveCheckoutStorage() {
+    if (typeof window !== "undefined" && window.localStorage) {
+      localStorage.removeItem(this.ACTIVE_CHECKOUT_KEY);
+    }
+  }
   /**
    * Remove specific items from local cart by their indices.
    * Use after partial checkout to remove only the purchased items.
@@ -3176,6 +3235,113 @@ var OmniSyncClient = class {
     }
     return result;
   }
+  /**
+   * Get the active guest checkout session info.
+   * Use this to check if there's an active checkout before handling payment success.
+   *
+   * @returns The active checkout info or null if no checkout is active
+   *
+   * @example
+   * ```typescript
+   * const activeCheckout = omni.getActiveGuestCheckout();
+   * if (activeCheckout) {
+   *   console.log('Active checkout:', activeCheckout.checkoutId);
+   *   console.log('Partial checkout:', activeCheckout.selectedIndices?.length);
+   * }
+   * ```
+   */
+  getActiveGuestCheckout() {
+    return this.loadActiveCheckout();
+  }
+  /**
+   * Handle payment success - automatically clears the cart (both local and server).
+   *
+   * Call this after Stripe payment succeeds (payment_intent.succeeded or confirmPayment success).
+   * This handles ALL checkout scenarios:
+   *
+   * **For guest users (local cart):**
+   * - Full checkout: clears entire localStorage cart
+   * - Partial checkout: removes only the purchased items
+   *
+   * **For logged-in users (server cart):**
+   * - Clears the cached cart ID so next `smartGetCart()` fetches fresh data
+   * - The server cart is already marked as CONVERTED by the webhook
+   *
+   * **IMPORTANT:** Call this from your payment success handler (e.g., after stripe.confirmPayment succeeds,
+   * or on your success page after redirect). This works for both guests AND logged-in users!
+   *
+   * @param checkoutId - Optional checkout ID for validation
+   * @returns Object indicating whether cart was cleared and how
+   *
+   * @example
+   * ```typescript
+   * // After stripe.confirmPayment() succeeds (works for guests AND logged-in users)
+   * const { error, paymentIntent } = await stripe.confirmPayment({
+   *   elements,
+   *   confirmParams: { return_url: '/checkout/success' },
+   *   redirect: 'if_required',
+   * });
+   *
+   * if (!error && paymentIntent?.status === 'succeeded') {
+   *   // Clear the cart automatically - handles all scenarios!
+   *   const result = omni.handlePaymentSuccess(checkoutId);
+   *   console.log('Cart cleared:', result.cleared);
+   *   console.log('User type:', result.userType); // 'guest' or 'customer'
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // On success page (after redirect)
+   * const checkoutId = new URLSearchParams(location.search).get('checkout_id');
+   * if (checkoutId) {
+   *   omni.handlePaymentSuccess(checkoutId);
+   * }
+   * ```
+   */
+  handlePaymentSuccess(checkoutId) {
+    const isLoggedIn = this.isCustomerLoggedIn();
+    if (isLoggedIn) {
+      this.customerCartId = null;
+    }
+    const activeCheckout = this.loadActiveCheckout();
+    if (checkoutId && activeCheckout && activeCheckout.checkoutId !== checkoutId) {
+      console.warn(
+        `handlePaymentSuccess: checkoutId mismatch. Expected ${activeCheckout.checkoutId}, got ${checkoutId}. Proceeding with cleanup.`
+      );
+    }
+    this.clearActiveCheckoutStorage();
+    if (isLoggedIn) {
+      this.clearLocalCart();
+      return {
+        cleared: true,
+        mode: "full",
+        userType: "customer"
+      };
+    }
+    if (activeCheckout?.selectedIndices && activeCheckout.selectedIndices.length > 0) {
+      this.removeLocalCartItemsByIndex(activeCheckout.selectedIndices);
+      return {
+        cleared: true,
+        mode: "partial",
+        userType: "guest",
+        itemsRemoved: activeCheckout.selectedIndices.length
+      };
+    }
+    this.clearLocalCart();
+    return {
+      cleared: true,
+      mode: "full",
+      userType: "guest"
+    };
+  }
+  /**
+   * Clear the active guest checkout tracking without clearing the cart.
+   * Use this if the user abandons checkout or navigates away.
+   */
+  clearActiveGuestCheckout() {
+    this.clearActiveCheckoutStorage();
+  }
   /**
    * Create order from custom data (not from local cart)
    * Use this if you manage cart state yourself

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omni-sync-sdk",
-  "version": "0.20.3",
+  "version": "0.21.1",
   "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",
@@ -16,14 +16,6 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "lint": "eslint \"src/**/*.ts\"",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "pnpm build"
-  },
   "keywords": [
     "omni-sync",
     "e-commerce",
@@ -72,5 +64,12 @@
     "typescript": {
       "optional": true
     }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}