brainerce 1.0.1 → 1.0.2

package/AI_BUILDER_PROMPT.md

@@ -135,19 +135,16 @@ import { getCartTotals } from 'brainerce';
 const totals = getCartTotals(cart);
 // { subtotal: 59.98, discount: 10, shipping: 0, total: 49.98 }
 
-// ⚠️ LocalCart vs Cart - KEY DIFFERENCES:
-// Server Cart has: id, itemCount, subtotal, discountAmount
-// Guest LocalCart has NONE of these! Only: items, couponCode, customer
-// To check type: if ('id' in cart) { /* server Cart */ } else { /* LocalCart */ }
-// Item count for both: cart.items.length
+// All smart* methods return a server Cart (even for guests via session carts)
+// Cart has: id, itemCount, subtotal, discountAmount, items, couponCode
 ```
 
 ### 🏷️ Coupon Code (Add to Cart Page!)
 
 ```typescript
-// Apply coupon - only works on server Cart (has 'id' field)
-// Server cart is created after startGuestCheckout() or for logged-in users
-const updatedCart = await client.applyCoupon(cartId, 'SAVE20');
+// Apply coupon to cart
+const cart = await client.smartGetCart();
+const updatedCart = await client.applyCoupon(cart.id, 'SAVE20');
 console.log(updatedCart.discountAmount); // "10.00" (string)
 console.log(updatedCart.couponCode); // "SAVE20"
 
@@ -682,7 +679,7 @@ waitResult.orderNumber               waitResult.status.orderNumber (nested in Pa
 variant.attributes.map(...)          Object.entries(variant.attributes || {}) (it's an object!)
 categorySuggestion.slug              // ❌ doesn't exist! Only: id, name, productCount
 order.status === 'COMPLETED'         order.status === 'delivered' (OrderStatus is lowercase!)
-getCartTotals(localCart)             // ❌ LocalCart has no subtotal! Calculate manually
+getCartTotals(cart)                  // ✅ Works — all carts are server carts now
 result.checkoutId (guest checkout)   // ⚠️ Check result.tracked first! It's a union type
 ```
 
@@ -690,27 +687,10 @@ result.checkoutId (guest checkout)   // ⚠️ Check result.tracked first! It's
 
 - **OrderItem** (from orders): Flat structure — `item.price`, `item.name`, `item.image`
 - **CartItem / CheckoutLineItem**: Nested structure — `item.unitPrice`, `item.product.name`, `item.product.images`
-- **`getCartTotals()`** only works with **server Cart** (has `subtotal`/`discountAmount`). For **LocalCart**, calculate manually:
-  ```typescript
-  const subtotal = cart.items.reduce(
-    (sum, item) => sum + parseFloat(item.price || '0') * item.quantity,
-    0
-  );
-  ```
+- **`getCartTotals()`** works on all carts — guests now use server-side session carts with full `subtotal`/`discountAmount` fields.
 - **`GuestCheckoutStartResponse`** is a union type — always check `result.tracked` before accessing `result.checkoutId`
 - **`WaitForOrderResult`** has `result.status.orderNumber`, NOT `result.orderNumber`. But `completeGuestCheckout()` returns `GuestOrderResponse` which DOES have `result.orderNumber` directly.
-- **⚠️ HYDRATION: Never use `useState(client.getLocalCart())`** in Next.js — causes hydration mismatch! Server has no localStorage (empty cart) but client does (real cart). Always start with empty state and load in `useEffect`:
-
-  ```typescript
-  // ❌ WRONG — hydration mismatch!
-  const [cart, setCart] = useState(client.getLocalCart());
-
-  // ✅ CORRECT — load after hydration
-  const [cart, setCart] = useState<LocalCart>({ items: [], updatedAt: '' });
-  useEffect(() => {
-    setCart(client.getLocalCart());
-  }, []);
-  ```
+- **Cart state**: Use `useState<Cart | null>(null)` and load with `smartGetCart()` in `useEffect` — all carts are server-side now, no hydration mismatch issues.
 
 ---