omni-sync-sdk 0.20.2 → 0.21.0

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);
     /**
@@ -4185,6 +4197,11 @@ declare class OmniSyncClient {
      * @internal
      */
     private getOrCreateCustomerCart;
+    /**
+     * Fetch the customer's existing cart from server
+     * @internal
+     */
+    private fetchCustomerCart;
     /**
      * Smart add to cart - automatically uses localStorage or server based on auth state
      *
@@ -4743,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
      *
@@ -4755,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();
@@ -4777,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.
@@ -4824,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);
     /**
@@ -4185,6 +4197,11 @@ declare class OmniSyncClient {
      * @internal
      */
     private getOrCreateCustomerCart;
+    /**
+     * Fetch the customer's existing cart from server
+     * @internal
+     */
+    private fetchCustomerCart;
     /**
      * Smart add to cart - automatically uses localStorage or server based on auth state
      *
@@ -4743,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
      *
@@ -4755,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();
@@ -4777,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.
@@ -4824,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
@@ -2032,6 +2037,14 @@ var OmniSyncClient = class {
         this.customerCartId = null;
       }
     }
+    try {
+      const cart2 = await this.fetchCustomerCart();
+      if (cart2.status === "ACTIVE") {
+        this.customerCartId = cart2.id;
+        return cart2;
+      }
+    } catch {
+    }
     const cart = await this.createCart();
     this.customerCartId = cart.id;
     if (this.customerToken) {
@@ -2042,6 +2055,22 @@ var OmniSyncClient = class {
     }
     return cart;
   }
+  /**
+   * Fetch the customer's existing cart from server
+   * @internal
+   */
+  async fetchCustomerCart() {
+    if (!this.customerToken) {
+      throw new OmniSyncError("Customer token required", 401);
+    }
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", "/customers/me/cart");
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", "/customers/me/cart");
+    }
+    throw new OmniSyncError("fetchCustomerCart requires vibe-coded or storefront mode", 400);
+  }
   /**
    * Smart add to cart - automatically uses localStorage or server based on auth state
    *
@@ -3045,6 +3074,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
    *
@@ -3057,19 +3091,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();
@@ -3097,8 +3134,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.
@@ -3189,6 +3266,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
@@ -1995,6 +2000,14 @@ var OmniSyncClient = class {
         this.customerCartId = null;
       }
     }
+    try {
+      const cart2 = await this.fetchCustomerCart();
+      if (cart2.status === "ACTIVE") {
+        this.customerCartId = cart2.id;
+        return cart2;
+      }
+    } catch {
+    }
     const cart = await this.createCart();
     this.customerCartId = cart.id;
     if (this.customerToken) {
@@ -2005,6 +2018,22 @@ var OmniSyncClient = class {
     }
     return cart;
   }
+  /**
+   * Fetch the customer's existing cart from server
+   * @internal
+   */
+  async fetchCustomerCart() {
+    if (!this.customerToken) {
+      throw new OmniSyncError("Customer token required", 401);
+    }
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", "/customers/me/cart");
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", "/customers/me/cart");
+    }
+    throw new OmniSyncError("fetchCustomerCart requires vibe-coded or storefront mode", 400);
+  }
   /**
    * Smart add to cart - automatically uses localStorage or server based on auth state
    *
@@ -3008,6 +3037,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
    *
@@ -3020,19 +3054,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();
@@ -3060,8 +3097,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.
@@ -3152,6 +3229,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.2",
+  "version": "0.21.0",
   "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"
   }
-}
+}