omni-sync-sdk 0.19.4 → 0.20.0

package/dist/index.d.mts

@@ -1778,9 +1778,36 @@ interface Checkout {
      */
     reservation?: ReservationInfo;
 }
+/**
+ * Options for creating a checkout from a cart.
+ *
+ * Supports **partial checkout** (AliExpress-style): pass `selectedItemIds` to
+ * checkout only specific items. After payment, only selected items are removed
+ * from the cart - remaining items stay for future purchases.
+ */
 interface CreateCheckoutDto {
+    /** The cart ID to create checkout from */
     cartId: string;
+    /** Optional customer ID to associate with checkout */
     customerId?: string;
+    /**
+     * **Partial checkout**: Only include these cart item IDs in the checkout.
+     * If omitted, all cart items are included (full cart checkout).
+     *
+     * After successful payment:
+     * - Selected items are removed from the cart
+     * - Unselected items remain in the cart (cart stays ACTIVE)
+     *
+     * @example
+     * ```typescript
+     * // Checkout only items 1 and 3, leave item 2 in cart
+     * const checkout = await omni.createCheckout({
+     *   cartId: 'cart_123',
+     *   selectedItemIds: ['item_1', 'item_3'],
+     * });
+     * ```
+     */
+    selectedItemIds?: string[];
 }
 interface SetCheckoutCustomerDto {
     email: string;
@@ -4215,14 +4242,41 @@ declare class OmniSyncClient {
      * ```
      */
     onLogout(): void;
+    /**
+     * Clear cart cache after successful checkout
+     *
+     * Call this after a successful order to ensure the next smartGetCart()
+     * creates a fresh cart instead of returning the converted one.
+     *
+     * @example
+     * ```typescript
+     * // After payment success
+     * if (paymentStatus === 'succeeded') {
+     *   omni.onCheckoutComplete();
+     *   omni.clearLocalCart(); // Also clear localStorage for guests
+     * }
+     * ```
+     */
+    onCheckoutComplete(): void;
     /**
      * Create a checkout from a cart
      * Starts the checkout process and returns checkout with available options
      *
+     * **Partial Checkout (AliExpress-style):**
+     * Pass `selectedItemIds` to checkout only specific items from the cart.
+     * After payment, only the selected items are removed from the cart -
+     * remaining items stay in the cart for future purchases.
+     *
      * @example
      * ```typescript
+     * // Full cart checkout (default)
      * const checkout = await omni.createCheckout({ cartId: 'cart_123' });
-     * console.log('Checkout created:', checkout.id);
+     *
+     * // Partial checkout - only buy selected items
+     * const checkout = await omni.createCheckout({
+     *   cartId: 'cart_123',
+     *   selectedItemIds: ['item_1', 'item_3'], // Only these items will be purchased
+     * });
      * ```
      */
     createCheckout(data: CreateCheckoutDto): Promise<Checkout>;

package/dist/index.d.ts

@@ -1778,9 +1778,36 @@ interface Checkout {
      */
     reservation?: ReservationInfo;
 }
+/**
+ * Options for creating a checkout from a cart.
+ *
+ * Supports **partial checkout** (AliExpress-style): pass `selectedItemIds` to
+ * checkout only specific items. After payment, only selected items are removed
+ * from the cart - remaining items stay for future purchases.
+ */
 interface CreateCheckoutDto {
+    /** The cart ID to create checkout from */
     cartId: string;
+    /** Optional customer ID to associate with checkout */
     customerId?: string;
+    /**
+     * **Partial checkout**: Only include these cart item IDs in the checkout.
+     * If omitted, all cart items are included (full cart checkout).
+     *
+     * After successful payment:
+     * - Selected items are removed from the cart
+     * - Unselected items remain in the cart (cart stays ACTIVE)
+     *
+     * @example
+     * ```typescript
+     * // Checkout only items 1 and 3, leave item 2 in cart
+     * const checkout = await omni.createCheckout({
+     *   cartId: 'cart_123',
+     *   selectedItemIds: ['item_1', 'item_3'],
+     * });
+     * ```
+     */
+    selectedItemIds?: string[];
 }
 interface SetCheckoutCustomerDto {
     email: string;
@@ -4215,14 +4242,41 @@ declare class OmniSyncClient {
      * ```
      */
     onLogout(): void;
+    /**
+     * Clear cart cache after successful checkout
+     *
+     * Call this after a successful order to ensure the next smartGetCart()
+     * creates a fresh cart instead of returning the converted one.
+     *
+     * @example
+     * ```typescript
+     * // After payment success
+     * if (paymentStatus === 'succeeded') {
+     *   omni.onCheckoutComplete();
+     *   omni.clearLocalCart(); // Also clear localStorage for guests
+     * }
+     * ```
+     */
+    onCheckoutComplete(): void;
     /**
      * Create a checkout from a cart
      * Starts the checkout process and returns checkout with available options
      *
+     * **Partial Checkout (AliExpress-style):**
+     * Pass `selectedItemIds` to checkout only specific items from the cart.
+     * After payment, only the selected items are removed from the cart -
+     * remaining items stay in the cart for future purchases.
+     *
      * @example
      * ```typescript
+     * // Full cart checkout (default)
      * const checkout = await omni.createCheckout({ cartId: 'cart_123' });
-     * console.log('Checkout created:', checkout.id);
+     *
+     * // Partial checkout - only buy selected items
+     * const checkout = await omni.createCheckout({
+     *   cartId: 'cart_123',
+     *   selectedItemIds: ['item_1', 'item_3'], // Only these items will be purchased
+     * });
      * ```
      */
     createCheckout(data: CreateCheckoutDto): Promise<Checkout>;

package/dist/index.js

@@ -1981,7 +1981,11 @@ var OmniSyncClient = class {
   async getOrCreateCustomerCart() {
     if (this.customerCartId) {
       try {
-        return await this.getCart(this.customerCartId);
+        const existingCart = await this.getCart(this.customerCartId);
+        if (existingCart.status === "ACTIVE") {
+          return existingCart;
+        }
+        this.customerCartId = null;
       } catch {
         this.customerCartId = null;
       }
@@ -2144,15 +2148,44 @@ var OmniSyncClient = class {
   onLogout() {
     this.customerCartId = null;
   }
+  /**
+   * Clear cart cache after successful checkout
+   *
+   * Call this after a successful order to ensure the next smartGetCart()
+   * creates a fresh cart instead of returning the converted one.
+   *
+   * @example
+   * ```typescript
+   * // After payment success
+   * if (paymentStatus === 'succeeded') {
+   *   omni.onCheckoutComplete();
+   *   omni.clearLocalCart(); // Also clear localStorage for guests
+   * }
+   * ```
+   */
+  onCheckoutComplete() {
+    this.customerCartId = null;
+  }
   // -------------------- Checkout --------------------
   /**
    * Create a checkout from a cart
    * Starts the checkout process and returns checkout with available options
    *
+   * **Partial Checkout (AliExpress-style):**
+   * Pass `selectedItemIds` to checkout only specific items from the cart.
+   * After payment, only the selected items are removed from the cart -
+   * remaining items stay in the cart for future purchases.
+   *
    * @example
    * ```typescript
+   * // Full cart checkout (default)
    * const checkout = await omni.createCheckout({ cartId: 'cart_123' });
-   * console.log('Checkout created:', checkout.id);
+   *
+   * // Partial checkout - only buy selected items
+   * const checkout = await omni.createCheckout({
+   *   cartId: 'cart_123',
+   *   selectedItemIds: ['item_1', 'item_3'], // Only these items will be purchased
+   * });
    * ```
    */
   async createCheckout(data) {

package/dist/index.mjs

@@ -1944,7 +1944,11 @@ var OmniSyncClient = class {
   async getOrCreateCustomerCart() {
     if (this.customerCartId) {
       try {
-        return await this.getCart(this.customerCartId);
+        const existingCart = await this.getCart(this.customerCartId);
+        if (existingCart.status === "ACTIVE") {
+          return existingCart;
+        }
+        this.customerCartId = null;
       } catch {
         this.customerCartId = null;
       }
@@ -2107,15 +2111,44 @@ var OmniSyncClient = class {
   onLogout() {
     this.customerCartId = null;
   }
+  /**
+   * Clear cart cache after successful checkout
+   *
+   * Call this after a successful order to ensure the next smartGetCart()
+   * creates a fresh cart instead of returning the converted one.
+   *
+   * @example
+   * ```typescript
+   * // After payment success
+   * if (paymentStatus === 'succeeded') {
+   *   omni.onCheckoutComplete();
+   *   omni.clearLocalCart(); // Also clear localStorage for guests
+   * }
+   * ```
+   */
+  onCheckoutComplete() {
+    this.customerCartId = null;
+  }
   // -------------------- Checkout --------------------
   /**
    * Create a checkout from a cart
    * Starts the checkout process and returns checkout with available options
    *
+   * **Partial Checkout (AliExpress-style):**
+   * Pass `selectedItemIds` to checkout only specific items from the cart.
+   * After payment, only the selected items are removed from the cart -
+   * remaining items stay in the cart for future purchases.
+   *
    * @example
    * ```typescript
+   * // Full cart checkout (default)
    * const checkout = await omni.createCheckout({ cartId: 'cart_123' });
-   * console.log('Checkout created:', checkout.id);
+   *
+   * // Partial checkout - only buy selected items
+   * const checkout = await omni.createCheckout({
+   *   cartId: 'cart_123',
+   *   selectedItemIds: ['item_1', 'item_3'], // Only these items will be purchased
+   * });
    * ```
    */
   async createCheckout(data) {

package/package.json

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