brainerce 1.0.1 → 1.0.2

package/dist/index.js

@@ -179,9 +179,16 @@ var BrainerceClient = class {
   constructor(options) {
     this.customerToken = null;
     this.customerCartId = null;
+    // Session cart state (server-side guest carts)
+    this.sessionCartId = null;
+    this.sessionToken = null;
+    this._sessionCartPromise = null;
+    this._migrationDone = false;
+    /** localStorage key for session cart reference (sessionToken + cartId) */
+    this.SESSION_CART_KEY = "brainerce_session";
     /**
      * Virtual cart ID used for localStorage carts (guest users not logged in).
-     * When a cart has this ID, operations use localStorage instead of server API.
+     * @deprecated Guest carts now use server-side sessions. Kept for backward compatibility.
      */
     this.VIRTUAL_LOCAL_CART_ID = "__local__";
     /**
@@ -213,6 +220,7 @@ var BrainerceClient = class {
     this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
     this.timeout = options.timeout || DEFAULT_TIMEOUT;
     this.onAuthError = options.onAuthError;
+    this.hydrateSessionCart();
   }
   withGuards(result, type) {
     if (!isDevGuardsEnabled()) return result;
@@ -1911,10 +1919,6 @@ var BrainerceClient = class {
    * ```
    */
   async createCart() {
-    if (this.isVibeCodedMode() && !this.isCustomerLoggedIn()) {
-      const localCart = this.getLocalCart();
-      return this.localCartToCart(localCart);
-    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("POST", "/cart");
     }
@@ -1933,6 +1937,9 @@ var BrainerceClient = class {
    * ```
    */
   async getCartBySession(sessionToken) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", `/cart/session/${sessionToken}`);
+    }
     if (this.storeId && !this.apiKey) {
       return this.storefrontRequest("GET", `/cart/session/${sessionToken}`);
     }
@@ -1958,6 +1965,7 @@ var BrainerceClient = class {
    */
   async getCart(cartId) {
     if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      console.warn('getCart("__local__") is deprecated. Use smartGetCart() instead.');
       return this.withGuards(this.localCartToCart(this.getLocalCart()), "cart");
     }
     if (this.isVibeCodedMode()) {
@@ -1982,38 +1990,14 @@ var BrainerceClient = class {
    */
   async addToCart(cartId, item) {
     if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
-      let productName = "Unknown Product";
-      let productPrice = "0";
-      let productImage;
-      if (item.productInfo) {
-        productName = item.productInfo.name;
-        productPrice = item.productInfo.price;
-        productImage = item.productInfo.image;
-      } else {
-        try {
-          const product = await this.getProduct(item.productId);
-          productName = product.name;
-          productPrice = product.salePrice || product.basePrice;
-          productImage = product.images?.[0]?.url;
-          if (item.variantId && product.variants) {
-            const variant = product.variants.find((v) => v.id === item.variantId);
-            if (variant) {
-              productPrice = variant.salePrice || variant.price || productPrice;
-              if (variant.image) {
-                productImage = typeof variant.image === "string" ? variant.image : variant.image.url;
-              }
-            }
-          }
-        } catch {
-        }
-      }
+      console.warn('addToCart("__local__", ...) is deprecated. Use smartAddToCart() instead.');
       this.addToLocalCart({
         productId: item.productId,
         variantId: item.variantId,
         quantity: item.quantity,
-        name: productName,
-        price: productPrice,
-        image: productImage
+        name: item.productInfo?.name || "Unknown Product",
+        price: item.productInfo?.price || "0",
+        image: item.productInfo?.image
       });
       return this.withGuards(this.localCartToCart(this.getLocalCart()), "cart");
     }
@@ -2044,6 +2028,7 @@ var BrainerceClient = class {
    */
   async updateCartItem(cartId, itemId, data) {
     if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      console.warn('updateCartItem("__local__", ...) is deprecated. Use smartUpdateCartItem() instead.');
       const index = parseInt(itemId.replace("local_", ""), 10);
       const localCart = this.getLocalCart();
       if (index >= 0 && index < localCart.items.length) {
@@ -2079,6 +2064,7 @@ var BrainerceClient = class {
    */
   async removeCartItem(cartId, itemId) {
     if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      console.warn('removeCartItem("__local__", ...) is deprecated. Use smartRemoveFromCart() instead.');
       const index = parseInt(itemId.replace("local_", ""), 10);
       const localCart = this.getLocalCart();
       if (index >= 0 && index < localCart.items.length) {
@@ -2114,6 +2100,7 @@ var BrainerceClient = class {
    */
   async clearCart(cartId) {
     if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      console.warn('clearCart("__local__") is deprecated. Use onCheckoutComplete() or clearLocalCart() directly.');
       this.clearLocalCart();
       return this.withGuards(this.localCartToCart(this.getLocalCart()), "cart");
     }
@@ -2394,6 +2381,230 @@ var BrainerceClient = class {
   isCustomerLoggedIn() {
     return !!this.customerToken;
   }
+  // -------------------- Session Cart Helpers --------------------
+  /**
+   * Hydrate session cart state from localStorage on construction.
+   * @internal
+   */
+  hydrateSessionCart() {
+    if (!this.isLocalStorageAvailable()) return;
+    try {
+      const stored = window.localStorage.getItem(this.SESSION_CART_KEY);
+      if (stored) {
+        const ref = JSON.parse(stored);
+        this.sessionToken = ref.sessionToken;
+        this.sessionCartId = ref.cartId;
+      }
+    } catch {
+    }
+  }
+  /**
+   * Persist session cart reference to localStorage.
+   * @internal
+   */
+  saveSessionCart(ref) {
+    this.sessionToken = ref.sessionToken;
+    this.sessionCartId = ref.cartId;
+    if (!this.isLocalStorageAvailable()) return;
+    window.localStorage.setItem(this.SESSION_CART_KEY, JSON.stringify(ref));
+  }
+  /**
+   * Clear session cart reference from localStorage and memory.
+   * @internal
+   */
+  clearSessionCart() {
+    this.sessionToken = null;
+    this.sessionCartId = null;
+    this._sessionCartPromise = null;
+    if (!this.isLocalStorageAvailable()) return;
+    window.localStorage.removeItem(this.SESSION_CART_KEY);
+  }
+  /**
+   * Update the cached item count in the session reference.
+   * @internal
+   */
+  updateSessionCartItemCount(count) {
+    if (!this.sessionToken || !this.sessionCartId) return;
+    this.saveSessionCart({
+      sessionToken: this.sessionToken,
+      cartId: this.sessionCartId,
+      itemCount: count
+    });
+  }
+  /**
+   * Return a synthetic empty Cart object for display when no server cart exists yet.
+   * Avoids creating a server cart just to show "your cart is empty."
+   * @internal
+   */
+  emptyCart() {
+    return {
+      id: "",
+      sessionToken: null,
+      customerId: null,
+      status: "ACTIVE",
+      currency: "USD",
+      notes: null,
+      subtotal: "0",
+      discountAmount: "0",
+      couponCode: null,
+      items: [],
+      itemCount: 0,
+      expiresAt: null,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /**
+   * Create a server-side cart via API. Never falls back to localStorage.
+   * @internal
+   */
+  async createServerCart() {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("POST", "/cart");
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("POST", "/cart");
+    }
+    return this.adminRequest("POST", "/api/v1/cart");
+  }
+  /**
+   * Get or create a server-side session cart for guest users.
+   * Lazily creates the cart on first call (e.g., first add-to-cart).
+   * Uses promise dedup lock to prevent race conditions on parallel calls.
+   * @internal
+   */
+  async getOrCreateSessionCart() {
+    if (this._sessionCartPromise) return this._sessionCartPromise;
+    this._sessionCartPromise = this._getOrCreateSessionCartImpl();
+    try {
+      return await this._sessionCartPromise;
+    } finally {
+      this._sessionCartPromise = null;
+    }
+  }
+  /** @internal */
+  async _getOrCreateSessionCartImpl() {
+    const migrated = await this.migrateLocalCartToSession();
+    if (migrated) return migrated;
+    if (this.sessionCartId && this.sessionToken) {
+      try {
+        const cart2 = await this.getCart(this.sessionCartId);
+        if (cart2.status === "ACTIVE") {
+          return cart2;
+        }
+        this.clearSessionCart();
+      } catch {
+        this.clearSessionCart();
+      }
+    }
+    if (this.sessionToken) {
+      try {
+        const cart2 = await this.getCartBySession(this.sessionToken);
+        if (cart2 && cart2.status === "ACTIVE") {
+          this.saveSessionCart({
+            sessionToken: this.sessionToken,
+            cartId: cart2.id,
+            itemCount: cart2.itemCount
+          });
+          return cart2;
+        }
+      } catch {
+        this.clearSessionCart();
+      }
+    }
+    const cart = await this.createServerCart();
+    if (cart.sessionToken) {
+      this.saveSessionCart({
+        sessionToken: cart.sessionToken,
+        cartId: cart.id,
+        itemCount: cart.itemCount
+      });
+    }
+    return cart;
+  }
+  /**
+   * Migrate legacy localStorage cart to server session cart.
+   * Called once, on first smart method call if migration is needed.
+   * @internal
+   */
+  async migrateLocalCartToSession() {
+    if (this._migrationDone) return null;
+    this._migrationDone = true;
+    if (this.sessionToken || this.sessionCartId) return null;
+    const localCart = this.getLocalCart();
+    if (localCart.items.length === 0) return null;
+    try {
+      const cart = await this.createServerCart();
+      for (const item of localCart.items) {
+        try {
+          await this.addToCart(cart.id, {
+            productId: item.productId,
+            variantId: item.variantId,
+            quantity: item.quantity
+          });
+        } catch {
+        }
+      }
+      if (cart.sessionToken) {
+        this.saveSessionCart({
+          sessionToken: cart.sessionToken,
+          cartId: cart.id
+        });
+      }
+      this.clearLocalCart();
+      return this.getCart(cart.id);
+    } catch {
+      this._migrationDone = false;
+      return null;
+    }
+  }
+  /**
+   * Merge the guest session cart into the customer's cart on the server.
+   * Tries linkCart first (fast, single call), falls back to mergeCarts endpoint.
+   * @internal
+   */
+  async mergeSessionCartOnLogin() {
+    if (this.sessionCartId) {
+      try {
+        return await this.linkCart(this.sessionCartId);
+      } catch {
+      }
+    }
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("POST", "/cart/merge", {
+        sessionToken: this.sessionToken
+      });
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("POST", "/cart/merge", {
+        sessionToken: this.sessionToken
+      });
+    }
+    return this.adminRequest("POST", "/api/v1/cart/merge", {
+      sessionToken: this.sessionToken
+    });
+  }
+  /**
+   * Get the cart item count without a full cart fetch.
+   * Returns the cached count from localStorage if available, or 0.
+   * For accurate counts, use smartGetCart() and read cart.itemCount.
+   */
+  getSmartCartItemCount() {
+    if (this.isCustomerLoggedIn()) {
+      return 0;
+    }
+    if (!this.isLocalStorageAvailable()) return 0;
+    try {
+      const stored = window.localStorage.getItem(this.SESSION_CART_KEY);
+      if (stored) {
+        const ref = JSON.parse(stored);
+        return ref.itemCount ?? 0;
+      }
+    } catch {
+    }
+    return 0;
+  }
+  // -------------------- Customer Cart --------------------
   /**
    * Get or create a server cart for the logged-in customer
    * Caches the cart ID for subsequent calls
@@ -2446,10 +2657,10 @@ var BrainerceClient = class {
     throw new BrainerceError("fetchCustomerCart requires vibe-coded or storefront mode", 400);
   }
   /**
-   * Smart add to cart - automatically uses localStorage or server based on auth state
+   * Smart add to cart - automatically uses the correct cart based on auth state
    *
-   * - **Guest (not logged in)**: Stores in localStorage
-   * - **Logged in**: Stores on server (database)
+   * - **Logged in**: Uses customer's server cart
+   * - **Guest**: Uses server-side session cart (creates one if needed)
    *
    * @example
    * ```typescript
@@ -2457,25 +2668,35 @@ var BrainerceClient = class {
    * await client.smartAddToCart({
    *   productId: 'prod_123',
    *   quantity: 2,
-   *   name: 'Cool Product', // Optional: for localStorage display
-   *   price: '29.99',
    * });
    * ```
    */
   async smartAddToCart(item) {
     if (this.isCustomerLoggedIn()) {
       const cart = await this.getOrCreateCustomerCart();
-      return this.addToCart(cart.id, {
+      const updated = await this.addToCart(cart.id, {
         productId: item.productId,
         variantId: item.variantId,
         quantity: item.quantity
       });
+      return updated;
     } else {
-      return this.addToLocalCart(item);
+      const cart = await this.getOrCreateSessionCart();
+      const updated = await this.addToCart(cart.id, {
+        productId: item.productId,
+        variantId: item.variantId,
+        quantity: item.quantity
+      });
+      this.updateSessionCartItemCount(updated.items?.length ?? 0);
+      return updated;
     }
   }
   /**
-   * Smart get cart - returns server cart if logged in, localStorage if guest
+   * Smart get cart - returns the current cart (server-side for both guests and logged-in users)
+   *
+   * - **Logged in**: Returns customer's server cart
+   * - **Guest with session**: Returns server-side session cart
+   * - **Guest without session**: Returns empty cart (no server call, cart created lazily on add)
    *
    * @example
    * ```typescript
@@ -2487,7 +2708,10 @@ var BrainerceClient = class {
     if (this.isCustomerLoggedIn()) {
       return this.getOrCreateCustomerCart();
     } else {
-      return this.withGuards(this.getLocalCart(), "cart");
+      if (!this.sessionToken) {
+        return this.emptyCart();
+      }
+      return this.getOrCreateSessionCart();
     }
   }
   /**
@@ -2513,7 +2737,24 @@ var BrainerceClient = class {
       }
       return this.updateCartItem(cart.id, item.id, { quantity });
     } else {
-      return this.updateLocalCartItem(productId, quantity, variantId);
+      if (!this.sessionToken) {
+        return this.emptyCart();
+      }
+      const cart = await this.getOrCreateSessionCart();
+      const item = cart.items.find(
+        (i) => i.productId === productId && i.variantId === (variantId ?? null)
+      );
+      if (!item) {
+        return cart;
+      }
+      let updated;
+      if (quantity <= 0) {
+        updated = await this.removeCartItem(cart.id, item.id);
+      } else {
+        updated = await this.updateCartItem(cart.id, item.id, { quantity });
+      }
+      this.updateSessionCartItemCount(updated.items?.length ?? 0);
+      return updated;
     }
   }
   /**
@@ -2529,15 +2770,13 @@ var BrainerceClient = class {
     return this.smartUpdateCartItem(productId, 0, variantId);
   }
   /**
-   * Sync local cart to server on login
+   * Sync guest cart to customer cart on login
    *
    * Call this AFTER setCustomerToken() when a customer logs in.
    * This will:
-   * 1. Get or create a server cart for the customer
-   * 2. Add all items from localStorage to the server cart (merging with existing)
-   * 3. Clear localStorage
-   *
-   * Items that fail to sync (e.g., out of stock) are silently skipped.
+   * 1. If a server-side session cart exists, merge it into the customer cart (atomic, server-side)
+   * 2. If only a legacy localStorage cart exists, sync items one by one (backward compat)
+   * 3. Clear the session/localStorage after merge
    *
    * @example
    * ```typescript
@@ -2545,7 +2784,7 @@ var BrainerceClient = class {
    * const auth = await client.login(email, password);
    * client.setCustomerToken(auth.token);
    *
-   * // Sync their local cart to server
+   * // Merge their guest cart into customer cart
    * const cart = await client.syncCartOnLogin();
    * console.log('Cart synced, items:', cart.items.length);
    * ```
@@ -2557,6 +2796,14 @@ var BrainerceClient = class {
         401
       );
     }
+    if (this.sessionToken) {
+      try {
+        const merged = await this.mergeSessionCartOnLogin();
+        this.clearSessionCart();
+        return merged;
+      } catch {
+      }
+    }
     const localCart = this.getLocalCart();
     const serverCart = await this.getOrCreateCustomerCart();
     if (localCart.items.length === 0) {
@@ -2578,15 +2825,15 @@ var BrainerceClient = class {
   /**
    * Clear cart state on logout
    *
-   * Call this when a customer logs out to clear the cached cart ID.
-   * The localStorage cart remains available for the next guest session.
+   * Call this when a customer logs out to clear the cached customer cart ID.
+   * The session cart (if any) remains available for the next guest session.
    *
    * @example
    * ```typescript
    * client.clearCustomerToken();
    * client.onLogout();
    *
-   * // Now back to guest mode - cart uses localStorage
+   * // Now back to guest mode - cart uses server-side session
    * await client.smartAddToCart({ productId: 'prod_123', quantity: 1 });
    * ```
    */
@@ -2604,12 +2851,12 @@ var BrainerceClient = class {
    * // After payment success
    * if (paymentStatus === 'succeeded') {
    *   client.onCheckoutComplete();
-   *   client.clearLocalCart(); // Also clear localStorage for guests
    * }
    * ```
    */
   onCheckoutComplete() {
     this.customerCartId = null;
+    this.clearSessionCart();
   }
   // -------------------- Checkout --------------------
   /**
@@ -2636,7 +2883,7 @@ var BrainerceClient = class {
   async createCheckout(data) {
     if (data.cartId === this.VIRTUAL_LOCAL_CART_ID) {
       throw new BrainerceError(
-        "Cannot create checkout from local cart directly. Use startGuestCheckout() for guest checkout with localStorage cart, or sync cart to server first with syncCartOnLogin().",
+        'Cannot create checkout from "__local__" cart. Use startGuestCheckout() or smartAddToCart() to create a server-side cart first.',
         400
       );
     }
@@ -3172,14 +3419,8 @@ var BrainerceClient = class {
     }
   }
   /**
-   * Get local cart from localStorage
-   * Returns empty cart if none exists
-   *
-   * @example
-   * ```typescript
-   * const cart = client.getLocalCart();
-   * console.log('Items in cart:', cart.items.length);
-   * ```
+   * @deprecated Use `smartGetCart()` instead. Guest carts are now stored on the server.
+   * Get local cart from localStorage. Returns empty cart if none exists.
    */
   getLocalCart() {
     if (!this.isLocalStorageAvailable()) {
@@ -3261,18 +3502,8 @@ var BrainerceClient = class {
     };
   }
   /**
-   * Add item to local cart (NO API call)
-   * If item already exists, updates quantity
-   *
-   * @example
-   * ```typescript
-   * client.addToLocalCart({
-   *   productId: 'prod_123',
-   *   quantity: 2,
-   *   name: 'Cool Shirt',
-   *   price: '29.99',
-   * });
-   * ```
+   * @deprecated Use `smartAddToCart()` instead. Guest carts are now stored on the server.
+   * Add item to local cart (NO API call). If item already exists, updates quantity.
    */
   addToLocalCart(item) {
     const cart = this.getLocalCart();
@@ -3294,14 +3525,8 @@ var BrainerceClient = class {
     return cart;
   }
   /**
-   * Update item quantity in local cart
-   * Set quantity to 0 to remove item
-   *
-   * @example
-   * ```typescript
-   * client.updateLocalCartItem('prod_123', 3); // Set quantity to 3
-   * client.updateLocalCartItem('prod_123', 0); // Remove item
-   * ```
+   * @deprecated Use `smartUpdateCartItem()` instead. Guest carts are now stored on the server.
+   * Update item quantity in local cart. Set quantity to 0 to remove item.
    */
   updateLocalCartItem(productId, quantity, variantId) {
     const cart = this.getLocalCart();
@@ -3319,24 +3544,13 @@ var BrainerceClient = class {
     return cart;
   }
   /**
-   * Remove item from local cart
-   *
-   * @example
-   * ```typescript
-   * client.removeFromLocalCart('prod_123');
-   * client.removeFromLocalCart('prod_456', 'variant_789');
-   * ```
+   * @deprecated Use `smartRemoveFromCart()` instead. Guest carts are now stored on the server.
    */
   removeFromLocalCart(productId, variantId) {
     return this.updateLocalCartItem(productId, 0, variantId);
   }
   /**
-   * Clear all items from local cart
-   *
-   * @example
-   * ```typescript
-   * client.clearLocalCart();
-   * ```
+   * @deprecated Use `onCheckoutComplete()` instead. Guest carts are now stored on the server.
    */
   clearLocalCart() {
     const cart = { items: [], updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
@@ -3344,16 +3558,8 @@ var BrainerceClient = class {
     return cart;
   }
   /**
-   * Set customer info on local cart
-   *
-   * @example
-   * ```typescript
-   * client.setLocalCartCustomer({
-   *   email: 'john@example.com',
-   *   firstName: 'John',
-   *   lastName: 'Doe',
-   * });
-   * ```
+   * @deprecated Customer info is now set via checkout address methods.
+   * Still used by `submitGuestOrder()` for backward compatibility.
    */
   setLocalCartCustomer(customer) {
     const cart = this.getLocalCart();
@@ -3362,19 +3568,8 @@ var BrainerceClient = class {
     return cart;
   }
   /**
-   * Set shipping address on local cart
-   *
-   * @example
-   * ```typescript
-   * client.setLocalCartShippingAddress({
-   *   firstName: 'John',
-   *   lastName: 'Doe',
-   *   line1: '123 Main St',
-   *   city: 'Tel Aviv',
-   *   postalCode: '6100000',
-   *   country: 'IL',
-   * });
-   * ```
+   * @deprecated Address is now set via `updateGuestCheckoutAddress()` after `startGuestCheckout()`.
+   * Still used by `submitGuestOrder()` for backward compatibility.
    */
   setLocalCartShippingAddress(address) {
     const cart = this.getLocalCart();
@@ -3383,7 +3578,8 @@ var BrainerceClient = class {
     return cart;
   }
   /**
-   * Set billing address on local cart
+   * @deprecated Address is now set via `updateGuestCheckoutAddress()` after `startGuestCheckout()`.
+   * Still used by `submitGuestOrder()` for backward compatibility.
    */
   setLocalCartBillingAddress(address) {
     const cart = this.getLocalCart();
@@ -3392,7 +3588,7 @@ var BrainerceClient = class {
     return cart;
   }
   /**
-   * Set coupon code on local cart
+   * @deprecated Coupons are now applied via `applyCoupon()` on the server cart.
    */
   setLocalCartCoupon(couponCode) {
     const cart = this.getLocalCart();
@@ -3401,7 +3597,7 @@ var BrainerceClient = class {
     return cart;
   }
   /**
-   * Get total items count in local cart
+   * @deprecated Use `getSmartCartItemCount()` instead.
    */
   getLocalCartItemCount() {
     const cart = this.getLocalCart();
@@ -3431,6 +3627,40 @@ var BrainerceClient = class {
    * ```
    */
   async submitGuestOrder(options) {
+    if (this.sessionToken) {
+      const serverCart = await this.getOrCreateSessionCart();
+      if (!serverCart.items || serverCart.items.length === 0) {
+        throw new BrainerceError("Cart is empty", 400);
+      }
+      const localCart = this.getLocalCart();
+      if (!localCart.customer?.email) {
+        throw new BrainerceError("Customer email is required. Call setLocalCartCustomer() first.", 400);
+      }
+      if (!localCart.shippingAddress) {
+        throw new BrainerceError("Shipping address is required. Call setLocalCartShippingAddress() first.", 400);
+      }
+      const trackingResult = await this.startGuestCheckout();
+      if (!trackingResult.tracked) {
+        throw new BrainerceError("Failed to create checkout from session cart", 500);
+      }
+      await this.updateGuestCheckoutAddress(trackingResult.checkoutId, {
+        shippingAddress: {
+          ...localCart.shippingAddress,
+          email: localCart.customer.email
+        },
+        billingAddress: localCart.billingAddress
+      });
+      const orderResult = await this.completeGuestCheckout(trackingResult.checkoutId, {
+        clearCartOnSuccess: options?.clearCartOnSuccess
+      });
+      return {
+        orderId: orderResult.orderId,
+        orderNumber: orderResult.orderNumber || orderResult.orderId,
+        status: orderResult.status || "pending",
+        total: orderResult.total ?? 0,
+        message: orderResult.message || "Order created successfully"
+      };
+    }
     const cart = this.getLocalCart();
     if (cart.items.length === 0) {
       throw new BrainerceError("Cart is empty", 400);
@@ -3448,7 +3678,6 @@ var BrainerceClient = class {
           shippingAddress: {
             ...cart.shippingAddress,
             email: cart.customer.email
-            // Already validated above
           },
           billingAddress: cart.billingAddress
         });
@@ -3536,6 +3765,34 @@ var BrainerceClient = class {
    * ```
    */
   async startGuestCheckout(options) {
+    if (this.sessionToken) {
+      const serverCart = await this.getOrCreateSessionCart();
+      if (!serverCart.items || serverCart.items.length === 0) {
+        throw new BrainerceError("Cart is empty", 400);
+      }
+      let selectedItemIds;
+      if (options?.selectedIndices?.length) {
+        selectedItemIds = options.selectedIndices.map((i) => serverCart.items[i]?.id).filter((id) => !!id);
+        if (selectedItemIds.length === 0) {
+          throw new BrainerceError("No items selected for checkout", 400);
+        }
+      }
+      const checkout = await this.createCheckout({
+        cartId: serverCart.id,
+        selectedItemIds
+      });
+      this.saveActiveCheckout({
+        checkoutId: checkout.id,
+        cartId: serverCart.id,
+        selectedIndices: options?.selectedIndices
+      });
+      return {
+        tracked: true,
+        checkoutId: checkout.id,
+        cartId: serverCart.id,
+        message: "Checkout created from session cart"
+      };
+    }
     const cart = this.getLocalCart();
     if (cart.items.length === 0) {
       throw new BrainerceError("Cart is empty", 400);
@@ -3599,16 +3856,8 @@ var BrainerceClient = class {
     }
   }
   /**
+   * @deprecated Partial checkout is now handled server-side via `selectedItemIds`.
    * Remove specific items from local cart by their indices.
-   * Use after partial checkout to remove only the purchased items.
-   *
-   * @param indices - Array of item indices to remove
-   *
-   * @example
-   * ```typescript
-   * // After partial checkout success, remove purchased items
-   * client.removeLocalCartItemsByIndex([0, 2]); // Removes items at index 0 and 2
-   * ```
    */
   removeLocalCartItemsByIndex(indices) {
     const cart = this.getLocalCart();
@@ -3685,6 +3934,7 @@ var BrainerceClient = class {
         this.removeLocalCartItemsByIndex(indices);
       } else {
         this.clearLocalCart();
+        this.clearSessionCart();
       }
       this.customerCartId = null;
     }
@@ -3782,6 +4032,7 @@ var BrainerceClient = class {
     }
     if (isLoggedIn) {
       this.clearLocalCart();
+      this.clearSessionCart();
       return {
         cleared: true,
         mode: "full",
@@ -3798,6 +4049,7 @@ var BrainerceClient = class {
       };
     }
     this.clearLocalCart();
+    this.clearSessionCart();
     return {
       cleared: true,
       mode: "full",