brainerce 1.0.1 → 1.0.2

package/dist/index.d.mts

@@ -3362,9 +3362,15 @@ declare class BrainerceClient {
     private readonly timeout;
     private customerToken;
     private customerCartId;
+    private sessionCartId;
+    private sessionToken;
+    private _sessionCartPromise;
+    private _migrationDone;
+    /** localStorage key for session cart reference (sessionToken + cartId) */
+    private readonly SESSION_CART_KEY;
     /**
      * 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.
      */
     private readonly VIRTUAL_LOCAL_CART_ID;
     /**
@@ -4585,6 +4591,64 @@ declare class BrainerceClient {
      * ```
      */
     isCustomerLoggedIn(): boolean;
+    /**
+     * Hydrate session cart state from localStorage on construction.
+     * @internal
+     */
+    private hydrateSessionCart;
+    /**
+     * Persist session cart reference to localStorage.
+     * @internal
+     */
+    private saveSessionCart;
+    /**
+     * Clear session cart reference from localStorage and memory.
+     * @internal
+     */
+    private clearSessionCart;
+    /**
+     * Update the cached item count in the session reference.
+     * @internal
+     */
+    private updateSessionCartItemCount;
+    /**
+     * 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
+     */
+    private emptyCart;
+    /**
+     * Create a server-side cart via API. Never falls back to localStorage.
+     * @internal
+     */
+    private createServerCart;
+    /**
+     * 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
+     */
+    private getOrCreateSessionCart;
+    /** @internal */
+    private _getOrCreateSessionCartImpl;
+    /**
+     * Migrate legacy localStorage cart to server session cart.
+     * Called once, on first smart method call if migration is needed.
+     * @internal
+     */
+    private migrateLocalCartToSession;
+    /**
+     * 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
+     */
+    private mergeSessionCartOnLogin;
+    /**
+     * 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(): number;
     /**
      * Get or create a server cart for the logged-in customer
      * Caches the cart ID for subsequent calls
@@ -4597,10 +4661,10 @@ declare class BrainerceClient {
      */
     private fetchCustomerCart;
     /**
-     * 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
@@ -4608,14 +4672,20 @@ declare class BrainerceClient {
      * await client.smartAddToCart({
      *   productId: 'prod_123',
      *   quantity: 2,
-     *   name: 'Cool Product', // Optional: for localStorage display
-     *   price: '29.99',
      * });
      * ```
      */
-    smartAddToCart(item: Omit<LocalCartItem, 'addedAt'>): Promise<Cart | LocalCart>;
+    smartAddToCart(item: {
+        productId: string;
+        variantId?: string;
+        quantity: number;
+    }): Promise<Cart>;
     /**
-     * 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
@@ -4623,7 +4693,7 @@ declare class BrainerceClient {
      * console.log('Items:', cart.items.length);
      * ```
      */
-    smartGetCart(): Promise<Cart | LocalCart>;
+    smartGetCart(): Promise<Cart>;
     /**
      * Smart update cart item quantity
      *
@@ -4633,7 +4703,7 @@ declare class BrainerceClient {
      * await client.smartUpdateCartItem('prod_123', 0); // Remove item
      * ```
      */
-    smartUpdateCartItem(productId: string, quantity: number, variantId?: string): Promise<Cart | LocalCart>;
+    smartUpdateCartItem(productId: string, quantity: number, variantId?: string): Promise<Cart>;
     /**
      * Smart remove from cart
      *
@@ -4643,17 +4713,15 @@ declare class BrainerceClient {
      * await client.smartRemoveFromCart('prod_456', 'variant_789');
      * ```
      */
-    smartRemoveFromCart(productId: string, variantId?: string): Promise<Cart | LocalCart>;
+    smartRemoveFromCart(productId: string, variantId?: string): Promise<Cart>;
     /**
-     * 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
@@ -4661,7 +4729,7 @@ declare class BrainerceClient {
      * 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);
      * ```
@@ -4670,15 +4738,15 @@ declare class BrainerceClient {
     /**
      * 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 });
      * ```
      */
@@ -4694,7 +4762,6 @@ declare class BrainerceClient {
      * // After payment success
      * if (paymentStatus === 'succeeded') {
      *   client.onCheckoutComplete();
-     *   client.clearLocalCart(); // Also clear localStorage for guests
      * }
      * ```
      */
@@ -5016,14 +5083,8 @@ declare class BrainerceClient {
      */
     private isLocalStorageAvailable;
     /**
-     * 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(): LocalCart;
     /**
@@ -5041,89 +5102,44 @@ declare class BrainerceClient {
      */
     private localCartToCart;
     /**
-     * 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: Omit<LocalCartItem, 'addedAt'>): LocalCart;
     /**
-     * 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: string, quantity: number, variantId?: string): LocalCart;
     /**
-     * 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: string, variantId?: string): LocalCart;
     /**
-     * Clear all items from local cart
-     *
-     * @example
-     * ```typescript
-     * client.clearLocalCart();
-     * ```
+     * @deprecated Use `onCheckoutComplete()` instead. Guest carts are now stored on the server.
      */
     clearLocalCart(): LocalCart;
     /**
-     * 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: LocalCart['customer']): LocalCart;
     /**
-     * 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: LocalCart['shippingAddress']): LocalCart;
     /**
-     * Set billing address on local cart
+     * @deprecated Address is now set via `updateGuestCheckoutAddress()` after `startGuestCheckout()`.
+     * Still used by `submitGuestOrder()` for backward compatibility.
      */
     setLocalCartBillingAddress(address: LocalCart['billingAddress']): LocalCart;
     /**
-     * Set coupon code on local cart
+     * @deprecated Coupons are now applied via `applyCoupon()` on the server cart.
      */
     setLocalCartCoupon(couponCode: string | undefined): LocalCart;
     /**
-     * Get total items count in local cart
+     * @deprecated Use `getSmartCartItemCount()` instead.
      */
     getLocalCartItemCount(): number;
     /**
@@ -5222,16 +5238,8 @@ declare class BrainerceClient {
      */
     private clearActiveCheckoutStorage;
     /**
+     * @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: number[]): void;
     /**

package/dist/index.d.ts

@@ -3362,9 +3362,15 @@ declare class BrainerceClient {
     private readonly timeout;
     private customerToken;
     private customerCartId;
+    private sessionCartId;
+    private sessionToken;
+    private _sessionCartPromise;
+    private _migrationDone;
+    /** localStorage key for session cart reference (sessionToken + cartId) */
+    private readonly SESSION_CART_KEY;
     /**
      * 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.
      */
     private readonly VIRTUAL_LOCAL_CART_ID;
     /**
@@ -4585,6 +4591,64 @@ declare class BrainerceClient {
      * ```
      */
     isCustomerLoggedIn(): boolean;
+    /**
+     * Hydrate session cart state from localStorage on construction.
+     * @internal
+     */
+    private hydrateSessionCart;
+    /**
+     * Persist session cart reference to localStorage.
+     * @internal
+     */
+    private saveSessionCart;
+    /**
+     * Clear session cart reference from localStorage and memory.
+     * @internal
+     */
+    private clearSessionCart;
+    /**
+     * Update the cached item count in the session reference.
+     * @internal
+     */
+    private updateSessionCartItemCount;
+    /**
+     * 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
+     */
+    private emptyCart;
+    /**
+     * Create a server-side cart via API. Never falls back to localStorage.
+     * @internal
+     */
+    private createServerCart;
+    /**
+     * 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
+     */
+    private getOrCreateSessionCart;
+    /** @internal */
+    private _getOrCreateSessionCartImpl;
+    /**
+     * Migrate legacy localStorage cart to server session cart.
+     * Called once, on first smart method call if migration is needed.
+     * @internal
+     */
+    private migrateLocalCartToSession;
+    /**
+     * 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
+     */
+    private mergeSessionCartOnLogin;
+    /**
+     * 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(): number;
     /**
      * Get or create a server cart for the logged-in customer
      * Caches the cart ID for subsequent calls
@@ -4597,10 +4661,10 @@ declare class BrainerceClient {
      */
     private fetchCustomerCart;
     /**
-     * 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
@@ -4608,14 +4672,20 @@ declare class BrainerceClient {
      * await client.smartAddToCart({
      *   productId: 'prod_123',
      *   quantity: 2,
-     *   name: 'Cool Product', // Optional: for localStorage display
-     *   price: '29.99',
      * });
      * ```
      */
-    smartAddToCart(item: Omit<LocalCartItem, 'addedAt'>): Promise<Cart | LocalCart>;
+    smartAddToCart(item: {
+        productId: string;
+        variantId?: string;
+        quantity: number;
+    }): Promise<Cart>;
     /**
-     * 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
@@ -4623,7 +4693,7 @@ declare class BrainerceClient {
      * console.log('Items:', cart.items.length);
      * ```
      */
-    smartGetCart(): Promise<Cart | LocalCart>;
+    smartGetCart(): Promise<Cart>;
     /**
      * Smart update cart item quantity
      *
@@ -4633,7 +4703,7 @@ declare class BrainerceClient {
      * await client.smartUpdateCartItem('prod_123', 0); // Remove item
      * ```
      */
-    smartUpdateCartItem(productId: string, quantity: number, variantId?: string): Promise<Cart | LocalCart>;
+    smartUpdateCartItem(productId: string, quantity: number, variantId?: string): Promise<Cart>;
     /**
      * Smart remove from cart
      *
@@ -4643,17 +4713,15 @@ declare class BrainerceClient {
      * await client.smartRemoveFromCart('prod_456', 'variant_789');
      * ```
      */
-    smartRemoveFromCart(productId: string, variantId?: string): Promise<Cart | LocalCart>;
+    smartRemoveFromCart(productId: string, variantId?: string): Promise<Cart>;
     /**
-     * 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
@@ -4661,7 +4729,7 @@ declare class BrainerceClient {
      * 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);
      * ```
@@ -4670,15 +4738,15 @@ declare class BrainerceClient {
     /**
      * 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 });
      * ```
      */
@@ -4694,7 +4762,6 @@ declare class BrainerceClient {
      * // After payment success
      * if (paymentStatus === 'succeeded') {
      *   client.onCheckoutComplete();
-     *   client.clearLocalCart(); // Also clear localStorage for guests
      * }
      * ```
      */
@@ -5016,14 +5083,8 @@ declare class BrainerceClient {
      */
     private isLocalStorageAvailable;
     /**
-     * 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(): LocalCart;
     /**
@@ -5041,89 +5102,44 @@ declare class BrainerceClient {
      */
     private localCartToCart;
     /**
-     * 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: Omit<LocalCartItem, 'addedAt'>): LocalCart;
     /**
-     * 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: string, quantity: number, variantId?: string): LocalCart;
     /**
-     * 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: string, variantId?: string): LocalCart;
     /**
-     * Clear all items from local cart
-     *
-     * @example
-     * ```typescript
-     * client.clearLocalCart();
-     * ```
+     * @deprecated Use `onCheckoutComplete()` instead. Guest carts are now stored on the server.
      */
     clearLocalCart(): LocalCart;
     /**
-     * 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: LocalCart['customer']): LocalCart;
     /**
-     * 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: LocalCart['shippingAddress']): LocalCart;
     /**
-     * Set billing address on local cart
+     * @deprecated Address is now set via `updateGuestCheckoutAddress()` after `startGuestCheckout()`.
+     * Still used by `submitGuestOrder()` for backward compatibility.
      */
     setLocalCartBillingAddress(address: LocalCart['billingAddress']): LocalCart;
     /**
-     * Set coupon code on local cart
+     * @deprecated Coupons are now applied via `applyCoupon()` on the server cart.
      */
     setLocalCartCoupon(couponCode: string | undefined): LocalCart;
     /**
-     * Get total items count in local cart
+     * @deprecated Use `getSmartCartItemCount()` instead.
      */
     getLocalCartItemCount(): number;
     /**
@@ -5222,16 +5238,8 @@ declare class BrainerceClient {
      */
     private clearActiveCheckoutStorage;
     /**
+     * @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: number[]): void;
     /**