brainerce 1.6.0 → 1.9.0

package/AI_BUILDER_PROMPT.md

@@ -559,6 +559,54 @@ const suggestions = await client.getSearchSuggestions('blue', 5);
 
 ---
 
+## Product Recommendations (Cross-Sells, Upsells, Related)
+
+Stores can configure product relations. Use these to boost sales with smart product suggestions:
+
+| Type | Where to Show | Purpose |
+|------|--------------|---------|
+| **Cross-sells** | Cart page | Complementary products ("You might also need") |
+| **Upsells** | Product page | Premium alternatives ("Upgrade your choice") |
+| **Related** | Bottom of product page | Similar products |
+
+```typescript
+import type { ProductRecommendationsResponse, CartRecommendationsResponse } from 'brainerce';
+
+// Product page — recommendations come EMBEDDED in the product response (no extra API call needed)
+const product = await client.getProductBySlug('some-slug');
+const recs = (product as any).recommendations as ProductRecommendationsResponse | undefined;
+// recs?.upsells — premium alternatives (show on product page)
+// recs?.related — similar products (show at bottom of product page)
+// recs?.crossSells — complementary products (typically used on cart page)
+
+// Each recommendation has: id, name, slug, basePrice, salePrice, images[], type, inventory
+
+// Cart page — cross-sell suggestions for cart items (separate call, since cart has no embedded recs)
+const cart = await client.smartGetCart();
+const cartRecs: CartRecommendationsResponse = await client.getCartRecommendations(cart.id, 4);
+// cartRecs.recommendations — deduplicated cross-sells (excludes items already in cart)
+
+// Render recommendation cards on product page
+{recs?.upsells && recs.upsells.length > 0 && (
+  <section>
+    <h2>Upgrade Your Choice</h2>
+    <div className="grid grid-cols-2 sm:grid-cols-4 gap-4">
+      {recs.upsells.map(item => (
+        <a key={item.id} href={`/products/${item.slug}`}>
+          <img src={item.images?.[0]?.url} alt={item.name} />
+          <p>{item.name}</p>
+          <p>{formatPrice(item.salePrice || item.basePrice)}</p>
+        </a>
+      ))}
+    </div>
+  </section>
+)}
+```
+
+> **Note:** Recommendations return empty arrays when no relations are configured — the UI just renders nothing. Always build the sections. The `getProductRecommendations()` SDK method still works as a fallback for older storefronts.
+
+---
+
 ## Product Custom Fields (Metafields)
 
 Products may have custom fields defined by the store owner (e.g., "Material", "Care Instructions", "Warranty").
@@ -727,8 +775,8 @@ if (params.get('oauth_success') === 'true') {
 
 - [ ] **Home** (`/`) - Featured products grid
 - [ ] **Products** (`/products`) - Product list with infinite scroll
-- [ ] **Product Detail** (`/products/[slug]`) - Use `getProductBySlug(slug)`
-- [ ] **Cart** (`/cart`) - Show items, quantities, totals, **coupon code input**, discount display
+- [ ] **Product Detail** (`/products/[slug]`) - Use `getProductBySlug(slug)`. Show **upsells** + **related products** from `product.recommendations` (embedded in response)
+- [ ] **Cart** (`/cart`) - Show items, quantities, totals, **coupon code input**, discount display, **cross-sell recommendations** via `getCartRecommendations()`
 - [ ] **Checkout** (`/checkout`) - Address → Shipping → Payment. **Show discount in order summary!**
 - [ ] **Success** (`/checkout/success`) - **Must call `completeGuestCheckout()`!**
 - [ ] **Login** (`/login`) - Email/password + social buttons, handle `requiresVerification`
@@ -751,6 +799,7 @@ Some features may not be configured yet, but the store owner can enable them at
 - **Product Discount Badges** → `getProductDiscountBadge(id)` returns `null` — renders nothing.
 - **Cart Nudges** → `cart.nudges` is `[]` — renders nothing.
 - **Coupon Input** → Always show in cart. Works even with no coupons configured.
+- **Product Recommendations** → Upsells + related on product page (from `product.recommendations`), cross-sells on cart page (`getCartRecommendations()`). Returns empty arrays when none configured.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.6.0",
+  "version": "1.9.0",
   "description": "Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",