@brainerce/mcp-server 2.0.1 → 2.1.0

package/dist/bin/stdio.js

@@ -730,27 +730,103 @@ const nudges: CartNudge[] = await client.getCartNudges(cartId);
 Display: banners in header, badges on product cards (strikethrough + discounted price), nudges below cart totals, applied discounts as line items in order summary.`;
 }
 function getRecommendationsSection() {
-  return `## Product Recommendations (Cross-Sells & Upsells)
+  return `## Product Recommendations & Upsell Features
 
-Recommendations come **embedded in the product response** \u2014 no extra API call needed for product pages.
+### Relation Types
+- **Cross-sell**: Complementary products ("Bought a phone? Add a case") \u2014 shown on product page + cart
+- **Upsell**: Premium alternatives ("Upgrade to Pro for $20 more") \u2014 shown on product page + cart upgrade banner
+- **Related**: Similar products ("Other shirts in this collection") \u2014 shown on product page
+
+### Product Page Recommendations
+Recommendations come **embedded in the product response** \u2014 no extra API call needed.
 
 \`\`\`typescript
-import type { ProductRecommendation, ProductRecommendationsResponse, CartRecommendationsResponse } from 'brainerce';
+import type { ProductRecommendation, ProductRecommendationsResponse } from 'brainerce';
 
-// Product page \u2014 recommendations are embedded in the product response
 const product = await client.getProductBySlug('some-slug');
 const recs = (product as any).recommendations as ProductRecommendationsResponse | undefined;
-// recs?.upsells \u2014 premium alternatives (show on product page)
-// recs?.related \u2014 similar products (show at bottom of product page)
-// recs?.crossSells \u2014 complementary products (typically used on cart page)
 
-// Cart page \u2014 cross-sell suggestions for cart items (separate call)
-const cartRecs: CartRecommendationsResponse = await client.getCartRecommendations(cartId, 4);
+// recs?.crossSells \u2014 complementary products \u2192 "Frequently Bought Together" section
+// recs?.upsells \u2014 premium alternatives \u2192 "Upgrade Your Choice" section
+// recs?.related \u2014 similar products \u2192 "Similar Products" section
+\`\`\`
+
+### Cart Page Features
+
+**Cross-sell recommendations** (existing products the customer might also want):
+\`\`\`typescript
+import type { CartRecommendationsResponse } from 'brainerce';
+const cartRecs = await client.getCartRecommendations(cartId, 4);
 // cartRecs.recommendations \u2014 deduplicated cross-sells (excludes items already in cart)
 \`\`\`
 
-ProductRecommendation: \`id\`, \`name\`, \`slug\`, \`basePrice\`, \`salePrice\`, \`images\`, \`type\`, \`inventory\`, \`relationType\`.
-Display upsells + related on product pages, cross-sells on cart page.`;
+**Cart upgrade banner** (upsell relations with small price delta \u2014 "Upgrade to X for +$Y"):
+\`\`\`typescript
+import type { CartUpgradesResponse } from 'brainerce';
+const { upgrades } = await client.getCartUpgrades(cartId);
+// upgrades is a Record<sourceProductId, { targetProduct, priceDelta, deltaPercent }>
+// Show inline banner per cart item if upgrade exists
+\`\`\`
+
+**Bundle offers** (discounted complementary products configured by the store owner):
+\`\`\`typescript
+import type { CartBundlesResponse } from 'brainerce';
+const { bundles } = await client.getCartBundles(cartId);
+// bundles[].bundleProduct \u2014 the product to offer
+// bundles[].originalPrice / bundles[].discountedPrice \u2014 prices
+// bundles[].discountType ('PERCENTAGE' | 'FIXED_AMOUNT') + discountValue
+\`\`\`
+
+**Free shipping progress bar** (configured threshold in channel settings):
+\`\`\`typescript
+const { storeInfo } = useStoreInfo(); // from store provider
+const threshold = storeInfo?.upsell?.freeShippingThreshold;
+const subtotal = parseFloat(cart.subtotal);
+const remaining = threshold ? threshold - subtotal : 0;
+const qualified = threshold ? subtotal >= threshold : false;
+// Show progress bar: remaining > 0 ? "You're $X away from free shipping!" : "You've got free shipping!"
+\`\`\`
+
+### Checkout Features
+
+**Order bumps** (one-click add-ons at checkout):
+\`\`\`typescript
+import type { CheckoutBumpsResponse } from 'brainerce';
+const { bumps } = await client.getCheckoutBumps(checkoutId);
+// bumps[].bumpProduct \u2014 product to offer
+// bumps[].originalPrice / discountedPrice \u2014 with optional discount
+// bumps[].title / description \u2014 display text
+
+// Add a bump to cart:
+await client.addOrderBump(cartId, bumpId);
+// Remove a bump:
+await client.removeOrderBump(cartId, bumpId);
+// Detect already-added bumps: check cart.items for metadata?.isOrderBump === true
+\`\`\`
+
+### Feature Flags (per-channel)
+All upsell features are controlled by \`storeInfo.upsell.*\`:
+- \`freeShippingBarEnabled\` \u2014 free shipping progress bar in cart
+- \`frequentlyBoughtTogetherEnabled\` \u2014 cross-sell section on product page
+- \`cartUpgradeBannerEnabled\` \u2014 upgrade banner per cart item
+- \`cartBundleEnabled\` \u2014 bundle offers in cart
+- \`checkoutOrderBumpEnabled\` \u2014 order bumps at checkout
+- \`freeShippingThreshold\` \u2014 threshold amount for free shipping bar
+
+Always check the flag before rendering: \`if (storeInfo?.upsell?.featureName !== false)\`
+
+### Components Reference
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| FrequentlyBoughtTogether | products/ | Cross-sells with "Add all to cart" on product page |
+| RecommendationSection | products/ | Grid of upsells or related products on product page |
+| CartRecommendationSection | products/ | Cross-sell grid at bottom of cart page |
+| FreeShippingBar | cart/ | Progress bar toward free shipping threshold |
+| CartUpgradeBanner | cart/ | Inline "Upgrade to X for +$Y" per cart item |
+| CartBundleOfferCard | cart/ | Discounted bundle offer card in cart |
+| OrderBumpCard | checkout/ | Checkbox add-on card in checkout sidebar |
+
+ProductRecommendation: \`id\`, \`name\`, \`slug\`, \`basePrice\`, \`salePrice\`, \`images\`, \`type\`, \`inventory\`, \`relationType\`.`;
 }
 function getInventorySection() {
   return `## Inventory, Stock Display & Reservation Countdown
@@ -2923,13 +2999,17 @@ export default async function ProductDetailPage({ params }: Props) {
 
 import { useEffect, useState } from 'react';
 import Link from 'next/link';
-import type { CartRecommendationsResponse } from 'brainerce';
+import type { CartRecommendationsResponse, CartUpgradesResponse, CartBundlesResponse } from 'brainerce';
 import { getClient } from '@/lib/brainerce';
 import { useCart } from '@/providers/store-provider';
+import { useStoreInfo } from '@/providers/store-provider';
 import { CartItem } from '@/components/cart/cart-item';
+import { CartUpgradeBanner } from '@/components/cart/cart-upgrade-banner';
+import { CartBundleOfferCard } from '@/components/cart/cart-bundle-offer';
 import { CartSummary } from '@/components/cart/cart-summary';
 import { CouponInput } from '@/components/cart/coupon-input';
 import { CartNudges } from '@/components/cart/cart-nudges';
+import { FreeShippingBar } from '@/components/cart/free-shipping-bar';
 import { ReservationCountdown } from '@/components/cart/reservation-countdown';
 import { CartRecommendationSection } from '@/components/products/recommendation-section';
 import { LoadingSpinner } from '@/components/shared/loading-spinner';
@@ -2937,9 +3017,12 @@ import { useTranslations } from '@/lib/translations';
 
 export default function CartPage() {
   const { cart, cartLoading, refreshCart, itemCount } = useCart();
+  const { storeInfo } = useStoreInfo();
   const t = useTranslations('cart');
   const tc = useTranslations('common');
   const [cartRecs, setCartRecs] = useState<CartRecommendationsResponse | null>(null);
+  const [upgrades, setUpgrades] = useState<CartUpgradesResponse | null>(null);
+  const [bundles, setBundles] = useState<CartBundlesResponse | null>(null);
 
   // Load cross-sell recommendations when cart changes
   useEffect(() => {
@@ -2954,6 +3037,32 @@ export default function CartPage() {
       .catch(() => {});
   }, [cart?.id, cart?.items.length]);
 
+  // Load upgrade suggestions when cart changes
+  useEffect(() => {
+    if (!cart?.id || cart.items.length === 0 || storeInfo?.upsell?.cartUpgradeBannerEnabled === false) {
+      setUpgrades(null);
+      return;
+    }
+    const client = getClient();
+    client
+      .getCartUpgrades(cart.id)
+      .then(setUpgrades)
+      .catch(() => {});
+  }, [cart?.id, cart?.items.length, storeInfo?.upsell?.cartUpgradeBannerEnabled]);
+
+  // Load bundle offers when cart changes
+  useEffect(() => {
+    if (!cart?.id || cart.items.length === 0 || storeInfo?.upsell?.cartBundleEnabled === false) {
+      setBundles(null);
+      return;
+    }
+    const client = getClient();
+    client
+      .getCartBundles(cart.id)
+      .then(setBundles)
+      .catch(() => {});
+  }, [cart?.id, cart?.items.length, storeInfo?.upsell?.cartBundleEnabled]);
+
   if (cartLoading) {
     return (
       <div className="flex min-h-[60vh] items-center justify-center">
@@ -3013,10 +3122,30 @@ export default function CartPage() {
           {/* Cart items */}
           <div>
             {cart.items.map((item) => (
-              <CartItem key={item.id} item={item} onUpdate={refreshCart} />
+              <div key={item.id}>
+                <CartItem item={item} onUpdate={refreshCart} />
+                {upgrades?.upgrades?.[item.productId] && (
+                  <CartUpgradeBanner
+                    suggestion={upgrades.upgrades[item.productId]}
+                    cartItem={item}
+                    onUpgrade={refreshCart}
+                    className="mb-2 ms-24"
+                  />
+                )}
+              </div>
             ))}
           </div>
 
+          {/* Bundle offers */}
+          {bundles?.bundles && bundles.bundles.length > 0 && (
+            <div className="mt-6 space-y-3">
+              <h3 className="text-foreground text-sm font-semibold">{t('bundleOffers')}</h3>
+              {bundles.bundles.map((offer) => (
+                <CartBundleOfferCard key={offer.id} offer={offer} onAdd={refreshCart} />
+              ))}
+            </div>
+          )}
+
           {/* Coupon input */}
           <div className="border-border mt-6 border-t pt-4">
             <CouponInput cart={cart} onUpdate={refreshCart} />
@@ -3026,6 +3155,7 @@ export default function CartPage() {
         {/* Summary sidebar */}
         <div className="lg:col-span-1">
           <div className="bg-muted/50 border-border sticky top-24 rounded-lg border p-6">
+            <FreeShippingBar className="mb-4" />
             <CartSummary />
 
             <Link
@@ -3069,6 +3199,7 @@ import type {
   SetShippingAddressDto,
   ShippingDestinations,
   PickupLocation,
+  CheckoutBumpsResponse,
 } from 'brainerce';
 import { formatPrice } from 'brainerce';
 import { getClient } from '@/lib/brainerce';
@@ -3079,6 +3210,7 @@ import { PaymentStep } from '@/components/checkout/payment-step';
 import { DeliveryMethodStep } from '@/components/checkout/delivery-method-step';
 import { PickupStep } from '@/components/checkout/pickup-step';
 import { TaxDisplay } from '@/components/checkout/tax-display';
+import { OrderBumpCard } from '@/components/checkout/order-bump-card';
 import { CouponInput } from '@/components/cart/coupon-input';
 import { ReservationCountdown } from '@/components/cart/reservation-countdown';
 import { LoadingSpinner } from '@/components/shared/loading-spinner';
@@ -3115,6 +3247,9 @@ function CheckoutContent() {
     phone?: string;
   } | null>(null);
   const [hasSavedAddress, setHasSavedAddress] = useState(false);
+  const [orderBumps, setOrderBumps] = useState<CheckoutBumpsResponse | null>(null);
+  const [addedBumpIds, setAddedBumpIds] = useState<Set<string>>(new Set());
+  const [bumpLoading, setBumpLoading] = useState<string | null>(null);
 
   // Check for returning from canceled payment
   const canceled = searchParams.get('canceled') === 'true';
@@ -3217,9 +3352,59 @@ function CheckoutContent() {
     };
 
     initCheckout();
-    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [cart?.id, existingCheckoutId]);
 
+  // Load order bumps when checkout is available
+  useEffect(() => {
+    if (!checkout?.id || storeInfo?.upsell?.checkoutOrderBumpEnabled === false) {
+      setOrderBumps(null);
+      return;
+    }
+    const client = getClient();
+    client
+      .getCheckoutBumps(checkout.id)
+      .then((data) => {
+        setOrderBumps(data);
+        // Detect already-added bumps from cart
+        if (cart?.items) {
+          const existingBumpIds = new Set<string>();
+          for (const item of cart.items) {
+            const meta = item.metadata as Record<string, unknown> | undefined;
+            if (meta?.isOrderBump && meta?.orderBumpId) {
+              existingBumpIds.add(meta.orderBumpId as string);
+            }
+          }
+          setAddedBumpIds(existingBumpIds);
+        }
+      })
+      .catch(() => {});
+  }, [checkout?.id, storeInfo?.upsell?.checkoutOrderBumpEnabled]);
+
+  // Handle bump toggle
+  async function handleBumpToggle(bumpId: string, add: boolean) {
+    if (!cart?.id || bumpLoading) return;
+    try {
+      setBumpLoading(bumpId);
+      const client = getClient();
+      if (add) {
+        await client.addOrderBump(cart.id, bumpId);
+        setAddedBumpIds((prev) => new Set([...prev, bumpId]));
+      } else {
+        await client.removeOrderBump(cart.id, bumpId);
+        setAddedBumpIds((prev) => {
+          const next = new Set(prev);
+          next.delete(bumpId);
+          return next;
+        });
+      }
+      await refreshCart();
+    } catch (err) {
+      console.error('Failed to toggle order bump:', err);
+    } finally {
+      setBumpLoading(null);
+    }
+  }
+
   // Handle shipping address submission
   async function handleAddressSubmit(
     address: SetShippingAddressDto,
@@ -3722,6 +3907,24 @@ function CheckoutContent() {
               )
             )}
 
+            {/* Order bumps */}
+            {orderBumps?.bumps && orderBumps.bumps.length > 0 && (
+              <div className="border-border space-y-2 border-t pt-4">
+                <p className="text-foreground text-xs font-semibold uppercase tracking-wide">
+                  {t('addToYourOrder')}
+                </p>
+                {orderBumps.bumps.map((bump) => (
+                  <OrderBumpCard
+                    key={bump.id}
+                    bump={bump}
+                    isAdded={addedBumpIds.has(bump.id)}
+                    onToggle={handleBumpToggle}
+                    loading={bumpLoading === bump.id}
+                  />
+                ))}
+              </div>
+            )}
+
             {/* Coupon input \u2014 show from shipping/pickup step onwards (or immediately if digital) */}
             {cart &&
               (isAllDigital || step === 'shipping' || step === 'pickup' || step === 'payment') && (
@@ -9193,6 +9396,680 @@ export function LoadingSpinner({ size = 'md', className }: LoadingSpinnerProps)
     </div>
   );
 }
+`,
+  "src/components/products/recommendation-section.tsx": `'use client';
+
+import { useEffect, useState } from 'react';
+import Link from 'next/link';
+import Image from 'next/image';
+import type { ProductRecommendation } from 'brainerce';
+import { PriceDisplay } from '@/components/shared/price-display';
+import { cn } from '@/lib/utils';
+
+interface RecommendationCardProps {
+  item: ProductRecommendation;
+  className?: string;
+}
+
+function RecommendationCard({ item, className }: RecommendationCardProps) {
+  const firstImage = item.images?.[0];
+  const imageUrl = typeof firstImage === 'string' ? firstImage : firstImage?.url || null;
+  const slug = item.slug || item.id;
+  const basePrice = parseFloat(item.basePrice);
+  const salePrice = item.salePrice ? parseFloat(item.salePrice) : undefined;
+  const isOnSale = salePrice != null && salePrice < basePrice;
+
+  return (
+    <Link
+      href={\`/products/\${slug}\`}
+      className={cn(
+        'border-border bg-background group block overflow-hidden rounded-lg border transition-shadow hover:shadow-md',
+        className
+      )}
+    >
+      <div className="bg-muted relative aspect-square overflow-hidden">
+        {imageUrl ? (
+          <Image
+            src={imageUrl}
+            alt={item.name}
+            fill
+            sizes="(max-width: 640px) 50vw, (max-width: 1024px) 33vw, 20vw"
+            className="object-cover transition-transform duration-300 group-hover:scale-105"
+          />
+        ) : (
+          <div className="text-muted-foreground absolute inset-0 flex items-center justify-center">
+            <svg className="h-10 w-10" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={1.5}
+                d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z"
+              />
+            </svg>
+          </div>
+        )}
+      </div>
+      <div className="space-y-1.5 p-3">
+        <h3 className="text-foreground group-hover:text-primary line-clamp-2 text-sm font-medium transition-colors">
+          {item.name}
+        </h3>
+        <PriceDisplay price={basePrice} salePrice={isOnSale ? salePrice : undefined} size="sm" />
+      </div>
+    </Link>
+  );
+}
+
+interface RecommendationSectionProps {
+  title: string;
+  items: ProductRecommendation[];
+  className?: string;
+}
+
+export function RecommendationSection({ title, items, className }: RecommendationSectionProps) {
+  if (items.length === 0) return null;
+
+  return (
+    <div className={cn('', className)}>
+      <h2 className="text-foreground mb-4 text-xl font-semibold">{title}</h2>
+      <div className="grid grid-cols-2 gap-3 sm:grid-cols-3 lg:grid-cols-4">
+        {items.map((item) => (
+          <RecommendationCard key={item.id} item={item} />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+interface CartRecommendationSectionProps {
+  title: string;
+  items: ProductRecommendation[];
+  className?: string;
+}
+
+export function CartRecommendationSection({
+  title,
+  items,
+  className,
+}: CartRecommendationSectionProps) {
+  if (items.length === 0) return null;
+
+  return (
+    <div className={cn('', className)}>
+      <h2 className="text-foreground mb-4 text-lg font-semibold">{title}</h2>
+      <div className="grid grid-cols-2 gap-3 sm:grid-cols-4">
+        {items.map((item) => (
+          <RecommendationCard key={item.id} item={item} />
+        ))}
+      </div>
+    </div>
+  );
+}
+`,
+  "src/components/products/frequently-bought-together.tsx": `'use client';
+
+import { useState } from 'react';
+import Image from 'next/image';
+import type { Product, ProductRecommendation } from 'brainerce';
+import { formatPrice } from 'brainerce';
+import { useCart } from '@/providers/store-provider';
+import { useStoreInfo } from '@/providers/store-provider';
+import { useTranslations } from '@/lib/translations';
+import { cn } from '@/lib/utils';
+
+interface FrequentlyBoughtTogetherProps {
+  items: ProductRecommendation[];
+  currentProduct: Product;
+  className?: string;
+}
+
+function getEffectivePrice(item: { basePrice: string; salePrice?: string | null }): number {
+  const sale = item.salePrice ? parseFloat(item.salePrice) : null;
+  const base = parseFloat(item.basePrice);
+  return sale != null && sale < base ? sale : base;
+}
+
+function ProductThumb({
+  name,
+  imageUrl,
+  price,
+  currency,
+  checked,
+  onToggle,
+  disabled,
+}: {
+  name: string;
+  imageUrl: string | null;
+  price: number;
+  currency: string;
+  checked: boolean;
+  onToggle?: () => void;
+  disabled?: boolean;
+}) {
+  return (
+    <label
+      className={cn(
+        'border-border bg-background relative flex cursor-pointer flex-col items-center rounded-lg border p-3 transition-all',
+        checked ? 'ring-primary ring-2' : 'opacity-60',
+        disabled && 'pointer-events-none'
+      )}
+    >
+      {onToggle && (
+        <input
+          type="checkbox"
+          checked={checked}
+          onChange={onToggle}
+          className="absolute start-2 top-2 h-4 w-4 rounded"
+        />
+      )}
+      <div className="bg-muted relative mb-2 h-20 w-20 overflow-hidden rounded">
+        {imageUrl ? (
+          <Image src={imageUrl} alt={name} fill sizes="80px" className="object-cover" />
+        ) : (
+          <div className="flex h-full w-full items-center justify-center">
+            <svg className="text-muted-foreground h-8 w-8" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z" />
+            </svg>
+          </div>
+        )}
+      </div>
+      <span className="text-foreground line-clamp-2 text-center text-xs font-medium">{name}</span>
+      <span className="text-muted-foreground mt-1 text-xs">
+        {formatPrice(price, { currency }) as string}
+      </span>
+    </label>
+  );
+}
+
+export function FrequentlyBoughtTogether({
+  items,
+  currentProduct,
+  className,
+}: FrequentlyBoughtTogetherProps) {
+  const { storeInfo } = useStoreInfo();
+  const { refreshCart } = useCart();
+  const t = useTranslations('productDetail');
+
+  // Only show up to 3 cross-sells
+  const crossSells = items.slice(0, 3);
+
+  const [selected, setSelected] = useState<Set<string>>(() => new Set(crossSells.map((i) => i.id)));
+  const [adding, setAdding] = useState(false);
+
+  if (!storeInfo?.upsell?.frequentlyBoughtTogetherEnabled) return null;
+  if (crossSells.length === 0) return null;
+
+  const currency = storeInfo.currency || 'USD';
+
+  const currentPrice = getEffectivePrice(currentProduct);
+  const currentImage = currentProduct.images?.[0];
+  const currentImageUrl = currentImage
+    ? typeof currentImage === 'string'
+      ? currentImage
+      : currentImage.url
+    : null;
+
+  const totalPrice = crossSells
+    .filter((item) => selected.has(item.id))
+    .reduce((sum, item) => sum + getEffectivePrice(item), currentPrice);
+
+  const toggleItem = (id: string) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) {
+        next.delete(id);
+      } else {
+        next.add(id);
+      }
+      return next;
+    });
+  };
+
+  async function handleAddAll() {
+    if (adding || selected.size === 0) return;
+    try {
+      setAdding(true);
+      const { getClient } = await import('@/lib/brainerce');
+      const client = getClient();
+      const selectedItems = crossSells.filter((item) => selected.has(item.id));
+      for (const item of selectedItems) {
+        await client.smartAddToCart({ productId: item.id, quantity: 1 });
+      }
+      await refreshCart();
+    } catch (err) {
+      console.error('Failed to add items to cart:', err);
+    } finally {
+      setAdding(false);
+    }
+  }
+
+  return (
+    <div className={cn('border-border rounded-lg border p-6', className)}>
+      <h2 className="text-foreground mb-4 text-xl font-semibold">{t('frequentlyBoughtTogether')}</h2>
+
+      <div className="flex flex-wrap items-center gap-3">
+        {/* Current product (always included, no checkbox) */}
+        <ProductThumb
+          name={currentProduct.name}
+          imageUrl={currentImageUrl}
+          price={currentPrice}
+          currency={currency}
+          checked={true}
+          disabled
+        />
+
+        {crossSells.map((item) => {
+          const img = item.images?.[0];
+          const imgUrl = img ? (typeof img === 'string' ? img : img.url) : null;
+          return (
+            <div key={item.id} className="flex items-center gap-3">
+              <span className="text-muted-foreground text-lg font-light">+</span>
+              <ProductThumb
+                name={item.name}
+                imageUrl={imgUrl}
+                price={getEffectivePrice(item)}
+                currency={currency}
+                checked={selected.has(item.id)}
+                onToggle={() => toggleItem(item.id)}
+              />
+            </div>
+          );
+        })}
+      </div>
+
+      {/* Total + Add button */}
+      <div className="mt-4 flex flex-wrap items-center gap-4">
+        <span className="text-foreground text-lg font-semibold">
+          {t('totalPrice', { price: formatPrice(totalPrice, { currency }) as string })}
+        </span>
+        <button
+          onClick={handleAddAll}
+          disabled={adding || selected.size === 0}
+          className={cn(
+            'bg-primary text-primary-foreground rounded px-5 py-2.5 text-sm font-medium transition-opacity hover:opacity-90',
+            'disabled:cursor-not-allowed disabled:opacity-50'
+          )}
+        >
+          {adding ? t('addingAll') : t('addSelectedToCart')}
+        </button>
+      </div>
+    </div>
+  );
+}
+`,
+  "src/components/cart/free-shipping-bar.tsx": `'use client';
+
+import { formatPrice } from 'brainerce';
+import { useStoreInfo, useCart } from '@/providers/store-provider';
+import { useTranslations } from '@/lib/translations';
+import { cn } from '@/lib/utils';
+
+interface FreeShippingBarProps {
+  className?: string;
+}
+
+export function FreeShippingBar({ className }: FreeShippingBarProps) {
+  const t = useTranslations('cart');
+  const { storeInfo } = useStoreInfo();
+  const { totals } = useCart();
+
+  const upsell = storeInfo?.upsell;
+  const threshold = upsell?.freeShippingThreshold;
+  const enabled = upsell?.freeShippingBarEnabled !== false;
+
+  // Don't render if disabled or no threshold configured
+  if (!enabled || !threshold || threshold <= 0) return null;
+
+  const subtotal = totals.subtotal;
+  const remaining = Math.max(0, threshold - subtotal);
+  const progress = Math.min(100, (subtotal / threshold) * 100);
+  const qualified = remaining <= 0;
+  const currency = storeInfo?.currency || 'USD';
+
+  // Don't show if already qualified
+  if (qualified) {
+    return (
+      <div className={cn('rounded-lg border border-green-200 bg-green-50 p-3', className)}>
+        <div className="flex items-center gap-2 text-sm font-medium text-green-700">
+          <svg className="h-4 w-4 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M5 13l4 4L19 7"
+            />
+          </svg>
+          {t('freeShippingQualified')}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn('rounded-lg border border-amber-200 bg-amber-50 p-3', className)}>
+      <p className="mb-2 text-sm text-amber-800">
+        {t('freeShippingRemaining', {
+          amount: formatPrice(remaining, { currency }) as string,
+        })}
+      </p>
+      <div className="h-2 w-full overflow-hidden rounded-full bg-amber-200">
+        <div
+          className="h-full rounded-full bg-amber-500 transition-all duration-500 ease-out"
+          style={{ width: \`\${progress}%\` }}
+        />
+      </div>
+    </div>
+  );
+}
+`,
+  "src/components/cart/cart-upgrade-banner.tsx": `'use client';
+
+import { useState, useEffect } from 'react';
+import Image from 'next/image';
+import type { CartUpgradeSuggestion, CartItem as CartItemType } from 'brainerce';
+import { formatPrice } from 'brainerce';
+import { getClient } from '@/lib/brainerce';
+import { useStoreInfo } from '@/providers/store-provider';
+import { useTranslations } from '@/lib/translations';
+import { cn } from '@/lib/utils';
+
+interface CartUpgradeBannerProps {
+  suggestion: CartUpgradeSuggestion;
+  cartItem: CartItemType;
+  onUpgrade: () => void;
+  className?: string;
+}
+
+export function CartUpgradeBanner({
+  suggestion,
+  cartItem,
+  onUpgrade,
+  className,
+}: CartUpgradeBannerProps) {
+  const { storeInfo } = useStoreInfo();
+  const t = useTranslations('cart');
+  const currency = storeInfo?.currency || 'USD';
+  const [upgrading, setUpgrading] = useState(false);
+  const [dismissed, setDismissed] = useState(false);
+
+  const storageKey = \`dismissed_upgrade_\${suggestion.sourceProductId}\`;
+
+  useEffect(() => {
+    try {
+      if (sessionStorage.getItem(storageKey)) {
+        setDismissed(true);
+      }
+    } catch {}
+  }, [storageKey]);
+
+  if (dismissed) return null;
+
+  const target = suggestion.targetProduct;
+  const firstImage = target.images?.[0];
+  const imageUrl = firstImage ? (typeof firstImage === 'string' ? firstImage : firstImage.url) : null;
+  const formattedDelta = formatPrice(parseFloat(suggestion.priceDelta), { currency }) as string;
+
+  function handleDismiss() {
+    try {
+      sessionStorage.setItem(storageKey, '1');
+    } catch {}
+    setDismissed(true);
+  }
+
+  async function handleUpgrade() {
+    if (upgrading) return;
+    try {
+      setUpgrading(true);
+      const client = getClient();
+      await client.smartRemoveFromCart(cartItem.productId, cartItem.variantId || undefined);
+      await client.smartAddToCart({ productId: target.id, quantity: cartItem.quantity });
+      onUpgrade();
+    } catch (err) {
+      console.error('Failed to upgrade cart item:', err);
+    } finally {
+      setUpgrading(false);
+    }
+  }
+
+  return (
+    <div
+      className={cn(
+        'bg-primary/5 border-primary/20 relative flex items-center gap-3 rounded-lg border px-4 py-3',
+        className
+      )}
+    >
+      {/* Dismiss button */}
+      <button
+        type="button"
+        onClick={handleDismiss}
+        className="text-muted-foreground hover:text-foreground absolute end-2 top-2 text-xs"
+        aria-label={t('dismissUpgrade')}
+      >
+        <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+          <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+        </svg>
+      </button>
+
+      {/* Product image */}
+      <div className="bg-muted relative h-12 w-12 flex-shrink-0 overflow-hidden rounded">
+        {imageUrl ? (
+          <Image src={imageUrl} alt={target.name} fill sizes="48px" className="object-cover" />
+        ) : (
+          <div className="text-muted-foreground flex h-full w-full items-center justify-center">
+            <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z" />
+            </svg>
+          </div>
+        )}
+      </div>
+
+      {/* Text */}
+      <div className="min-w-0 flex-1">
+        <p className="text-foreground text-sm font-medium">
+          {t('upgradeFor', { name: target.name, amount: formattedDelta })}
+        </p>
+      </div>
+
+      {/* Upgrade button */}
+      <button
+        type="button"
+        onClick={handleUpgrade}
+        disabled={upgrading}
+        className={cn(
+          'bg-primary text-primary-foreground flex-shrink-0 rounded px-3 py-1.5 text-xs font-medium transition-opacity hover:opacity-90',
+          'disabled:cursor-not-allowed disabled:opacity-50'
+        )}
+      >
+        {upgrading ? t('upgrading') : t('upgrade')}
+      </button>
+    </div>
+  );
+}
+`,
+  "src/components/cart/cart-bundle-offer.tsx": `'use client';
+
+import { useState } from 'react';
+import Image from 'next/image';
+import type { CartBundleOffer as CartBundleOfferType } from 'brainerce';
+import { formatPrice } from 'brainerce';
+import { getClient } from '@/lib/brainerce';
+import { useStoreInfo } from '@/providers/store-provider';
+import { useTranslations } from '@/lib/translations';
+import { cn } from '@/lib/utils';
+
+interface CartBundleOfferCardProps {
+  offer: CartBundleOfferType;
+  onAdd: () => void;
+  className?: string;
+}
+
+export function CartBundleOfferCard({ offer, onAdd, className }: CartBundleOfferCardProps) {
+  const { storeInfo } = useStoreInfo();
+  const t = useTranslations('cart');
+  const currency = storeInfo?.currency || 'USD';
+  const [adding, setAdding] = useState(false);
+
+  const product = offer.bundleProduct;
+  const firstImage = product.images?.[0];
+  const imageUrl = firstImage ? (typeof firstImage === 'string' ? firstImage : firstImage.url) : null;
+  const originalPrice = parseFloat(offer.originalPrice);
+  const discountedPrice = parseFloat(offer.discountedPrice);
+  const discountLabel =
+    offer.discountType === 'PERCENTAGE'
+      ? \`\${offer.discountValue}%\`
+      : formatPrice(parseFloat(offer.discountValue), { currency }) as string;
+
+  async function handleAdd() {
+    if (adding) return;
+    try {
+      setAdding(true);
+      const client = getClient();
+      await client.smartAddToCart({
+        productId: product.id,
+        variantId: offer.bundleVariantId || undefined,
+        quantity: 1,
+      });
+      onAdd();
+    } catch (err) {
+      console.error('Failed to add bundle item:', err);
+    } finally {
+      setAdding(false);
+    }
+  }
+
+  return (
+    <div
+      className={cn(
+        'bg-background border-border flex items-center gap-4 rounded-lg border p-4',
+        className
+      )}
+    >
+      {/* Product image */}
+      <div className="bg-muted relative h-16 w-16 flex-shrink-0 overflow-hidden rounded">
+        {imageUrl ? (
+          <Image src={imageUrl} alt={product.name} fill sizes="64px" className="object-cover" />
+        ) : (
+          <div className="text-muted-foreground flex h-full w-full items-center justify-center">
+            <svg className="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z" />
+            </svg>
+          </div>
+        )}
+      </div>
+
+      {/* Details */}
+      <div className="min-w-0 flex-1">
+        <p className="text-foreground text-sm font-medium">{offer.name}</p>
+        {offer.description && (
+          <p className="text-muted-foreground mt-0.5 text-xs">{offer.description}</p>
+        )}
+        <div className="mt-1 flex items-center gap-2">
+          <span className="text-muted-foreground text-sm line-through">
+            {formatPrice(originalPrice, { currency }) as string}
+          </span>
+          <span className="text-foreground text-sm font-semibold">
+            {formatPrice(discountedPrice, { currency }) as string}
+          </span>
+          <span className="bg-destructive/10 text-destructive rounded px-1.5 py-0.5 text-xs font-medium">
+            -{discountLabel}
+          </span>
+        </div>
+      </div>
+
+      {/* Add button */}
+      <button
+        type="button"
+        onClick={handleAdd}
+        disabled={adding}
+        className={cn(
+          'bg-primary text-primary-foreground flex-shrink-0 rounded px-4 py-2 text-xs font-medium transition-opacity hover:opacity-90',
+          'disabled:cursor-not-allowed disabled:opacity-50'
+        )}
+      >
+        {adding ? t('addingBundle') : t('addBundleItem')}
+      </button>
+    </div>
+  );
+}
+`,
+  "src/components/checkout/order-bump-card.tsx": `'use client';
+
+import Image from 'next/image';
+import type { OrderBump } from 'brainerce';
+import { formatPrice } from 'brainerce';
+import { useStoreInfo } from '@/providers/store-provider';
+import { useTranslations } from '@/lib/translations';
+import { cn } from '@/lib/utils';
+
+interface OrderBumpCardProps {
+  bump: OrderBump;
+  isAdded: boolean;
+  onToggle: (bumpId: string, add: boolean) => void;
+  loading: boolean;
+  className?: string;
+}
+
+export function OrderBumpCard({ bump, isAdded, onToggle, loading, className }: OrderBumpCardProps) {
+  const { storeInfo } = useStoreInfo();
+  const t = useTranslations('checkout');
+  const currency = storeInfo?.currency || 'USD';
+
+  const product = bump.bumpProduct;
+  const firstImage = product.images?.[0];
+  const imageUrl = firstImage ? (typeof firstImage === 'string' ? firstImage : firstImage.url) : null;
+  const originalPrice = parseFloat(bump.originalPrice);
+  const hasDiscount = bump.discountedPrice != null;
+  const discountedPrice = hasDiscount ? parseFloat(bump.discountedPrice!) : null;
+
+  return (
+    <label
+      className={cn(
+        'border-border hover:border-primary/50 flex cursor-pointer items-start gap-3 rounded-lg border p-3 transition-colors',
+        isAdded && 'border-primary bg-primary/5',
+        loading && 'pointer-events-none opacity-60',
+        className
+      )}
+    >
+      <input
+        type="checkbox"
+        checked={isAdded}
+        onChange={() => onToggle(bump.id, !isAdded)}
+        disabled={loading}
+        className="mt-1 h-4 w-4 shrink-0 rounded"
+      />
+
+      {/* Image */}
+      {imageUrl && (
+        <div className="bg-muted relative h-10 w-10 shrink-0 overflow-hidden rounded">
+          <Image src={imageUrl} alt={product.name} fill sizes="40px" className="object-cover" />
+        </div>
+      )}
+
+      {/* Content */}
+      <div className="min-w-0 flex-1">
+        <p className="text-foreground text-sm font-medium">{bump.title}</p>
+        {bump.description && (
+          <p className="text-muted-foreground mt-0.5 text-xs">{bump.description}</p>
+        )}
+        <div className="mt-1 flex items-center gap-2">
+          {hasDiscount ? (
+            <>
+              <span className="text-muted-foreground text-xs line-through">
+                {formatPrice(originalPrice, { currency }) as string}
+              </span>
+              <span className="text-foreground text-sm font-semibold">
+                {formatPrice(discountedPrice!, { currency }) as string}
+              </span>
+            </>
+          ) : (
+            <span className="text-foreground text-sm font-semibold">
+              {formatPrice(originalPrice, { currency }) as string}
+            </span>
+          )}
+        </div>
+      </div>
+    </label>
+  );
+}
 `,
   "src/hooks/use-search.ts": `'use client';