@brainerce/mcp-server 2.3.0 → 2.6.0

package/dist/index.js

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -17,14 +15,6 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -197,7 +187,7 @@ import {
   getVariantPrice, getVariantOptions, getStockStatus,
   getCartItemName, getCartItemImage,
   getDescriptionContent, isHtmlDescription,
-  getProductMetafieldValue,
+  getProductMetafieldValue, getProductCustomizationFields,
 } from 'brainerce';
 \`\`\``;
 }
@@ -239,6 +229,7 @@ async function startCheckout() {
 4. Start checkout session (\`startGuestCheckout()\` or \`createCheckout()\`)
 5. Set shipping address (includes required email) \u2192 \`setShippingAddress()\`
 6. Select shipping method \u2192 \`selectShippingMethod()\`
+6b. (Optional) Set checkout custom fields \u2192 \`setCheckoutCustomFields()\` \u2014 surcharges auto-calculated
 7. Create payment intent \u2192 \`createPaymentIntent()\` \u2192 returns \`{ clientSecret, provider }\`
 8. Branch on \`provider\`: \`'stripe'\` \u2192 Stripe Elements, \`'grow'\` \u2192 iframe, \`'paypal'\` \u2192 PayPal Buttons
 9. **Order is created AUTOMATICALLY after payment succeeds (via webhook) \u2014 for ALL providers!**
@@ -329,6 +320,20 @@ function CheckoutPage() {
   if (!paymentData) return <div>Unable to initialize payment</div>;
 
   // Render payment UI based on provider
+  if (paymentData.provider === 'sandbox') {
+    return (
+      <div className="text-center p-6 bg-amber-50 border border-amber-200 rounded-lg">
+        <h3 className="font-semibold mb-2">Test Mode</h3>
+        <p className="text-sm text-gray-600 mb-4">No real payment will be charged.</p>
+        <button onClick={async () => {
+          await client.completeGuestCheckout(checkoutId);
+          window.location.href = \\\`/order-confirmation?checkout_id=\\\${checkoutId}\\\`;
+        }} className="bg-amber-500 text-white px-6 py-2 rounded">
+          Complete Test Order
+        </button>
+      </div>
+    );
+  }
   if (paymentData.provider === 'grow') {
     return <GrowPaymentForm paymentUrl={paymentData.clientSecret} checkoutId={paymentData.checkoutId} />;
   }
@@ -447,11 +452,12 @@ const growProvider = providers.find(p => p.provider === 'grow');
 const paypalProvider = providers.find(p => p.provider === 'paypal');
 \`\`\`
 
-Each provider has: \`id\`, \`provider\` ('stripe'|'grow'|'paypal'), \`name\`, \`publicKey\`, \`stripeAccountId\` (Stripe only), \`supportedMethods\`, \`testMode\`, \`isDefault\`.
+Each provider has: \`id\`, \`provider\` ('stripe'|'grow'|'paypal'|'sandbox'), \`name\`, \`publicKey\`, \`stripeAccountId\` (Stripe only), \`supportedMethods\`, \`testMode\`, \`isDefault\`.
 
 - **Stripe:** \`npm install @stripe/stripe-js @stripe/react-stripe-js\` \u2014 \`loadStripe(publicKey, { stripeAccount })\`
 - **Grow:** No SDK \u2014 uses iframe with payment URL. Supports credit cards, Bit, Apple Pay, Google Pay.
-- **PayPal:** \`npm install @paypal/react-paypal-js\` \u2014 \`PayPalScriptProvider\` + \`PayPalButtons\``;
+- **PayPal:** \`npm install @paypal/react-paypal-js\` \u2014 \`PayPalScriptProvider\` + \`PayPalButtons\`
+- **Sandbox:** No SDK needed \u2014 when \`sandboxPaymentsEnabled\` is true, \`getPaymentProviders()\` includes a sandbox provider with \`renderType: 'sandbox'\`. Show a "Complete Test Order" button. Call \`completeGuestCheckout(checkoutId)\` to finalize. Orders are marked \`isTestOrder: true\`.`;
 }
 function getProductsSection(_currency) {
   return `## Products & Variants
@@ -606,6 +612,35 @@ const material = getProductMetafieldValue(product, 'material');
 
 **Metafield fields:** \`definitionName\` (display label), \`definitionKey\` (lookup key), \`value\`, \`type\` (IMAGE, GALLERY, URL, COLOR, BOOLEAN, DATE, DATETIME, TEXT, TEXTAREA, NUMBER, DIMENSION, WEIGHT, JSON)
 
+### Product Customization Fields (Customer Input)
+
+Some products allow customers to provide input at purchase time (e.g., text on a cake, upload a logo). Check \`product.customizationFields\` and render input fields accordingly.
+
+\`\`\`typescript
+import { getProductCustomizationFields } from 'brainerce';
+import type { ProductCustomizationField } from 'brainerce';
+
+const fields = getProductCustomizationFields(product);
+
+// Render input for each field based on field.type:
+// TEXT/TEXTAREA \u2192 text input, NUMBER \u2192 number input, BOOLEAN \u2192 checkbox,
+// COLOR \u2192 color picker, DATE \u2192 date picker, IMAGE \u2192 file upload, etc.
+// Check field.required, field.minLength, field.maxLength, field.enumValues for validation.
+
+// Pass customer values in metadata when adding to cart:
+await client.addToCart(cartId, {
+  productId: product.id,
+  quantity: 1,
+  metadata: { cake_text: 'Happy Birthday!' },
+});
+
+// For IMAGE fields, upload first:
+const { url } = await client.uploadCustomizationFile(file);
+// Then use the URL in metadata: metadata: { logo: url }
+\`\`\`
+
+**Customization field properties:** \`key\`, \`name\` (display label), \`type\`, \`required\`, \`minLength\`, \`maxLength\`, \`minValue\`, \`maxValue\`, \`enumValues\`, \`defaultValue\`, \`position\`
+
 ### Downloadable / Digital Products
 
 Products with \`isDownloadable: true\` are digital products. Show a digital badge instead of stock badge, list included files, and note that download links appear after purchase.
@@ -792,9 +827,14 @@ 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
+// bundles[].requiresVariantSelection \u2014 true if customer must pick a variant
+// bundles[].lockedVariant \u2014 set if admin pre-selected a specific variant
+// bundles[].bundleProduct.variants \u2014 available variants (only when requiresVariantSelection)
 
 // Add a bundle to cart (applies the discount automatically):
 await client.addBundleToCart(cartId, bundleOfferId);
+// For products with variants \u2014 pass the selected variantId:
+await client.addBundleToCart(cartId, bundleOfferId, selectedVariantId);
 // Remove a bundle from cart:
 await client.removeBundleFromCart(cartId, bundleOfferId);
 // Detect already-added bundles: check cart.items for metadata?.isBundleItem === true
@@ -819,9 +859,14 @@ 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
+// bumps[].requiresVariantSelection \u2014 true if customer must pick a variant
+// bumps[].lockedVariant \u2014 set if admin pre-selected a specific variant
+// bumps[].bumpProduct.variants \u2014 available variants (only when requiresVariantSelection)
 
 // Add a bump to cart:
 await client.addOrderBump(cartId, bumpId);
+// For products with variants \u2014 pass the selected variantId:
+await client.addOrderBump(cartId, bumpId, selectedVariantId);
 // Remove a bump:
 await client.removeOrderBump(cartId, bumpId);
 // Detect already-added bumps: check cart.items for metadata?.isOrderBump === true
@@ -846,10 +891,11 @@ Always check the flag before rendering: \`if (storeInfo?.upsell?.featureName !==
 | 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 |
+| CartBundleOfferCard | cart/ | Discounted bundle offer card in cart (with inline variant selector for variable products) |
+| OrderBumpCard | checkout/ | Checkbox add-on card in checkout sidebar (with inline variant selector for variable products) |
 
-ProductRecommendation: \`id\`, \`name\`, \`slug\`, \`basePrice\`, \`salePrice\`, \`images\`, \`type\`, \`inventory\`, \`relationType\`.`;
+ProductRecommendation: \`id\`, \`name\`, \`slug\`, \`basePrice\`, \`salePrice\`, \`images\`, \`type\`, \`inventory\`, \`relationType\`, \`variants?\` (when variant selection needed).
+OrderBump/CartBundleOffer: includes \`requiresVariantSelection\` (boolean) and \`lockedVariant?\` (\`{ id, name, attributes }\`).`;
 }
 function getInventorySection() {
   return `## Inventory, Stock Display & Reservation Countdown
@@ -1989,6 +2035,15 @@ export function getClient(): BrainerceClient {
   }
   return clientInstance;
 }
+<% if (i18nEnabled) { %>
+
+/** Initialize client with a specific locale for translated content */
+export function initClientWithLocale(locale: string): BrainerceClient {
+  const client = getClient();
+  client.setLocale(locale);
+  return client;
+}
+<% } %>
 
 // Cart ID helpers (not a security token \u2014 safe in localStorage)
 const CART_ID_KEY = 'brainerce_cart_id';
@@ -2187,6 +2242,10 @@ import type { StoreInfo, Cart, CustomerProfile } from 'brainerce';
 import { getCartTotals } from 'brainerce';
 import { getClient, initClient, setStoredCartId } from '@/lib/brainerce';
 import { checkAuthStatus, proxyLogout } from '@/lib/auth';
+<% if (i18nEnabled) { %>
+import { MessagesContext } from '@/lib/translations';
+import { getMessages, defaultLocale } from '@/i18n';
+<% } %>
 
 // ---- Store Info Context ----
 interface StoreInfoContextValue {
@@ -2246,7 +2305,11 @@ export function useCart() {
 }
 
 // ---- Provider Component ----
+<% if (i18nEnabled) { %>
+export function StoreProvider({ children, locale }: { children: React.ReactNode; locale?: string }) {
+<% } else { %>
 export function StoreProvider({ children }: { children: React.ReactNode }) {
+<% } %>
   const [storeInfo, setStoreInfo] = useState<StoreInfo | null>(null);
   const [storeLoading, setStoreLoading] = useState(true);
   const [isLoggedIn, setIsLoggedIn] = useState(false);
@@ -2254,6 +2317,9 @@ export function StoreProvider({ children }: { children: React.ReactNode }) {
   const [authLoading, setAuthLoading] = useState(true);
   const [cart, setCart] = useState<Cart | null>(null);
   const [cartLoading, setCartLoading] = useState(true);
+<% if (i18nEnabled) { %>
+  const [messages, setMessages] = useState<Record<string, Record<string, string>>>({});
+<% } %>
 
   // Check auth status via httpOnly cookie (server-side validation)
   const refreshAuth = useCallback(async () => {
@@ -2272,6 +2338,16 @@ export function StoreProvider({ children }: { children: React.ReactNode }) {
   // Initialize client, check auth, and fetch store info
   useEffect(() => {
     const client = initClient();
+<% if (i18nEnabled) { %>
+
+    // Set locale on SDK client for translated product content
+    if (locale) {
+      client.setLocale(locale);
+    }
+
+    // Load UI message strings for current locale
+    getMessages(locale || defaultLocale).then(setMessages);
+<% } %>
 
     // Optimistic check: if brainerce_logged_in cookie exists, assume logged in
     // while we validate the actual token server-side
@@ -2288,7 +2364,11 @@ export function StoreProvider({ children }: { children: React.ReactNode }) {
       .then(setStoreInfo)
       .catch(console.error)
       .finally(() => setStoreLoading(false));
+<% if (i18nEnabled) { %>
+  }, [refreshAuth, locale]);
+<% } else { %>
   }, [refreshAuth]);
+<% } %>
 
   // Cart management
   const refreshCart = useCallback(async () => {
@@ -2341,6 +2421,21 @@ export function StoreProvider({ children }: { children: React.ReactNode }) {
 
   const totals = cart ? getCartTotals(cart) : { subtotal: 0, discount: 0, shipping: 0, total: 0 };
 
+<% if (i18nEnabled) { %>
+  return (
+    <MessagesContext.Provider value={messages}>
+      <StoreInfoContext.Provider value={{ storeInfo, loading: storeLoading }}>
+        <AuthContext.Provider value={{ isLoggedIn, authLoading, customer, login, logout }}>
+          <CartContext.Provider
+            value={{ cart, cartLoading, refreshCart, itemCount, totals }}
+          >
+            {children}
+          </CartContext.Provider>
+        </AuthContext.Provider>
+      </StoreInfoContext.Provider>
+    </MessagesContext.Provider>
+  );
+<% } else { %>
   return (
     <StoreInfoContext.Provider value={{ storeInfo, loading: storeLoading }}>
       <AuthContext.Provider value={{ isLoggedIn, authLoading, customer, login, logout }}>
@@ -2352,6 +2447,7 @@ export function StoreProvider({ children }: { children: React.ReactNode }) {
       </AuthContext.Provider>
     </StoreInfoContext.Provider>
   );
+<% } %>
 }
 `,
   "src/app/page.tsx": `'use client';
@@ -2453,7 +2549,81 @@ export default function HomePage() {
   );
 }
 `,
-  "src/app/layout.tsx.ejs": `import type { Metadata } from 'next';
+  "src/app/layout.tsx.ejs": `<% if (i18nEnabled) { %>
+import type { Metadata } from 'next';
+<%- fontImport %>
+import { StoreProvider } from '@/providers/store-provider';
+import { Header } from '@/components/layout/header';
+import { Footer } from '@/components/layout/footer';
+import { getDirection, supportedLocales } from '@/i18n';
+import '../globals.css';
+
+<%- fontVariable %>
+
+const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://example.com';
+
+export const metadata: Metadata = {
+  metadataBase: new URL(baseUrl),
+  title: {
+    default: 'My Store',
+    template: \`%s | My Store\`,
+  },
+  description: 'My Store',
+  alternates: {
+    canonical: '/',
+  },
+  openGraph: {
+    siteName: 'My Store',
+    type: 'website',
+  },
+  robots: {
+    index: true,
+    follow: true,
+  },
+};
+
+const organizationJsonLd = {
+  '@context': 'https://schema.org',
+  '@type': 'Organization',
+  name: 'My Store',
+  url: baseUrl,
+};
+
+export function generateStaticParams() {
+  return supportedLocales.map((locale) => ({ locale }));
+}
+
+export default function RootLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode;
+  params: { locale: string };
+}) {
+  const dir = getDirection(params.locale);
+
+  return (
+    <html lang={params.locale} dir={dir}>
+      <head>
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(organizationJsonLd) }}
+        />
+      </head>
+      <body className={font.className}>
+        <StoreProvider locale={params.locale}>
+          <div className="min-h-screen flex flex-col">
+            <Header />
+            <main className="flex-1">{children}</main>
+            <Footer />
+          </div>
+        </StoreProvider>
+      </body>
+    </html>
+  );
+}
+<% } else { %>
+import type { Metadata } from 'next';
 <%- fontImport %>
 import { StoreProvider } from '@/providers/store-provider';
 import { Header } from '@/components/layout/header';
@@ -2517,6 +2687,7 @@ export default function RootLayout({
     </html>
   );
 }
+<% } %>
 `,
   "src/app/products/page.tsx": `'use client';
 
@@ -3417,13 +3588,13 @@ function CheckoutContent() {
   }, [checkout?.id, storeInfo?.upsell?.checkoutOrderBumpEnabled]);
 
   // Handle bump toggle
-  async function handleBumpToggle(bumpId: string, add: boolean) {
+  async function handleBumpToggle(bumpId: string, add: boolean, variantId?: string) {
     if (!cart?.id || bumpLoading) return;
     try {
       setBumpLoading(bumpId);
       const client = getClient();
       if (add) {
-        await client.addOrderBump(cart.id, bumpId);
+        await client.addOrderBump(cart.id, bumpId, variantId);
         setAddedBumpIds((prev) => new Set([...prev, bumpId]));
       } else {
         await client.removeOrderBump(cart.id, bumpId);
@@ -4121,6 +4292,23 @@ function OrderConfirmationContent() {
         client.handlePaymentSuccess(checkoutId!);
         await refreshCart();
 
+        // For redirect-based payment providers (e.g. CardCom), the customer
+        // returns with provider params in the URL (lowprofilecode, etc.).
+        // Send these to the backend for server-side verification via the
+        // provider's API (e.g. GetLpResult) \u2014 never trust URL params alone.
+        const lowProfileCode =
+          searchParams.get('lowprofilecode') || searchParams.get('LowProfileCode');
+        if (lowProfileCode) {
+          try {
+            await client.confirmSdkPayment(checkoutId!, {
+              paymentIntentId: lowProfileCode,
+            });
+          } catch (err) {
+            console.warn('Redirect payment confirmation failed:', err);
+            // Don't block \u2014 webhook may still process the payment
+          }
+        }
+
         const orderResult = await client.waitForOrder(checkoutId!, {
           maxWaitMs: 30000,
         });
@@ -5637,7 +5825,62 @@ export async function POST(request: NextRequest) {
   return response;
 }
 `,
-  "src/middleware.ts": `import { NextRequest, NextResponse } from 'next/server';
+  "src/middleware.ts.ejs": `<% if (i18nEnabled) { %>
+import { NextRequest, NextResponse } from 'next/server';
+
+const TOKEN_COOKIE = 'brainerce_customer_token';
+const PROTECTED_PATHS = ['/account'];
+const supportedLocales = <%- supportedLocales %>;
+const defaultLocale = '<%= defaultLocale %>';
+
+function getLocaleFromPath(pathname: string): string | null {
+  const segment = pathname.split('/')[1];
+  return supportedLocales.includes(segment) ? segment : null;
+}
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // Skip static files and API routes
+  if (
+    pathname.startsWith('/api/') ||
+    pathname.startsWith('/_next/') ||
+    pathname.includes('.')
+  ) {
+    return NextResponse.next();
+  }
+
+  const pathnameLocale = getLocaleFromPath(pathname);
+
+  // Redirect to default locale if no locale prefix
+  if (!pathnameLocale) {
+    const url = request.nextUrl.clone();
+    url.pathname = \`/\${defaultLocale}\${pathname}\`;
+    return NextResponse.redirect(url);
+  }
+
+  // Auth protection (with locale prefix)
+  const pathWithoutLocale = pathname.replace(\`/\${pathnameLocale}\`, '') || '/';
+  const isProtected = PROTECTED_PATHS.some((p) => pathWithoutLocale.startsWith(p));
+  if (isProtected) {
+    const token = request.cookies.get(TOKEN_COOKIE);
+    if (!token?.value) {
+      const loginUrl = new URL(\`/\${pathnameLocale}/login\`, request.url);
+      return NextResponse.redirect(loginUrl);
+    }
+  }
+
+  // Set locale header for server components
+  const response = NextResponse.next();
+  response.headers.set('x-locale', pathnameLocale);
+  return response;
+}
+
+export const config = {
+  matcher: ['/((?!_next|api|.*\\\\..*).*)'],
+};
+<% } else { %>
+import { NextRequest, NextResponse } from 'next/server';
 
 const TOKEN_COOKIE = 'brainerce_customer_token';
 
@@ -5662,6 +5905,7 @@ export function middleware(request: NextRequest) {
 export const config = {
   matcher: ['/account/:path*'],
 };
+<% } %>
 `,
   "src/components/products/product-card.tsx": `'use client';
 
@@ -7523,7 +7767,9 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
     initialized.current = true;
 
     const client = getClient();
-    const successUrl = \`\${window.location.origin}/order-confirmation?checkout_id=\${checkoutId}\`;
+    const iframeSuccessUrl = \`\${window.location.origin}/payment-complete?checkout_id=\${checkoutId}\`;
+    const iframeFailedUrl = \`\${window.location.origin}/payment-complete?checkout_id=\${checkoutId}&failed=true\`;
+    const redirectSuccessUrl = \`\${window.location.origin}/order-confirmation?checkout_id=\${checkoutId}\`;
     const cancelUrl = \`\${window.location.origin}/checkout?checkout_id=\${checkoutId}&canceled=true\`;
 
     let sdkInitDone = false;
@@ -7684,8 +7930,19 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
     });
 
     // C) Create payment intent (starts wallet timer)
-    const intentPromise = client
-      .createPaymentIntent(checkoutId, { successUrl, cancelUrl })
+    // Wait for provider info so we can choose the right success URL:
+    // iframe providers redirect inside the iframe to /payment-complete (postMessage),
+    // redirect providers go straight to /order-confirmation.
+    const intentPromise = providerPromise
+      .then((providerSdk) => {
+        const isIframe = providerSdk?.renderType === 'iframe';
+        const successUrl = isIframe ? iframeSuccessUrl : redirectSuccessUrl;
+        const failedUrl = isIframe ? iframeFailedUrl : cancelUrl;
+        return client.createPaymentIntent(checkoutId, {
+          successUrl,
+          cancelUrl: failedUrl,
+        });
+      })
       .then((intent) => {
         setPaymentIntent(intent);
         return intent;
@@ -7710,6 +7967,36 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
         window.location.href = intent.clientSecret;
         return;
       }
+
+      // Iframe mode: listen for postMessage from the /payment-complete callback
+      // page that loads inside the iframe after the provider redirects on completion.
+      if (sdk.renderType === 'iframe') {
+        const handleMessage = (event: MessageEvent) => {
+          if (event.origin !== window.location.origin) return;
+          if (event.data?.type !== 'brainerce:payment-complete') return;
+
+          const params = event.data.data as Record<string, string> | undefined;
+          if (params?.failed === 'true') {
+            setError(t('paymentError'));
+            return;
+          }
+
+          // Map provider-specific params to normalized format for
+          // server-side verification (e.g. CardCom lowprofilecode \u2192 paymentIntentId)
+          const lowProfileCode = params?.lowprofilecode || params?.LowProfileCode;
+          const normalized: Record<string, unknown> = { ...params };
+          if (lowProfileCode) {
+            normalized.paymentIntentId = lowProfileCode;
+          }
+
+          // Trigger server-side verification + order creation
+          handleSuccess(normalized);
+        };
+        window.addEventListener('message', handleMessage);
+        cleanups.push(() => window.removeEventListener('message', handleMessage));
+        return;
+      }
+
       if (sdk.renderType !== 'sdk-widget' || !sdk.globalName) return;
 
       // Store for retryRender from onError callback
@@ -7860,15 +8147,45 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
 
   if (sdk.renderType === 'iframe') {
     return (
-      <div className={cn('py-4', className)}>
-        <iframe
-          src={paymentIntent.clientSecret}
-          className="w-full border-0"
-          style={{ minHeight: '500px' }}
-          title={t('payment')}
-          allow="payment"
-        />
-      </div>
+      <>
+        {/* Modal overlay */}
+        <div className="fixed inset-0 z-50 flex items-start justify-center overflow-y-auto bg-black/50 py-6 backdrop-blur-sm">
+          <div className="relative mx-4 w-full max-w-md rounded-2xl bg-white shadow-2xl">
+            {/* Close button */}
+            <button
+              onClick={() => {
+                window.location.href = \`/checkout?checkout_id=\${checkoutId}&canceled=true\`;
+              }}
+              className="absolute end-3 top-3 z-10 flex h-8 w-8 items-center justify-center rounded-full bg-white/80 text-gray-500 shadow-sm transition-colors hover:bg-gray-100 hover:text-gray-700"
+              aria-label="Close"
+            >
+              <svg
+                width="14"
+                height="14"
+                viewBox="0 0 14 14"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+              >
+                <path d="M1 1l12 12M13 1L1 13" />
+              </svg>
+            </button>
+            <iframe
+              src={paymentIntent.clientSecret}
+              className="w-full rounded-2xl border-0"
+              style={{ height: '80vh' }}
+              title={t('payment')}
+              allow="payment"
+            />
+          </div>
+        </div>
+        {/* Placeholder so the checkout layout doesn't collapse */}
+        <div className={cn('flex flex-col items-center justify-center py-12', className)}>
+          <LoadingSpinner size="lg" />
+          <p className="text-muted-foreground mt-4 text-sm">{t('preparingPayment')}</p>
+        </div>
+      </>
     );
   }
 
@@ -9995,10 +10312,10 @@ export function CartUpgradeBanner({
 `,
   "src/components/cart/cart-bundle-offer.tsx": `'use client';
 
-import { useState } from 'react';
+import { useState, useMemo } from 'react';
 import Image from 'next/image';
 import type { CartBundleOffer as CartBundleOfferType } from 'brainerce';
-import { formatPrice } from 'brainerce';
+import { formatPrice, getVariantOptions } from 'brainerce';
 import { useStoreInfo } from '@/providers/store-provider';
 import { useTranslations } from '@/lib/translations';
 import { cn } from '@/lib/utils';
@@ -10015,28 +10332,114 @@ export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBun
   const t = useTranslations('cart');
   const currency = storeInfo?.currency || 'USD';
   const [adding, setAdding] = useState(false);
+  const [selectedVariantId, setSelectedVariantId] = useState<string | null>(null);
 
   const product = offer.bundleProduct;
+  const variants = product.variants;
+  const requiresSelection = offer.requiresVariantSelection && variants && variants.length > 0;
+
+  // Build attribute groups from variants
+  const attributeGroups = useMemo(() => {
+    if (!requiresSelection || !variants) return [];
+    const groups = new Map<string, Set<string>>();
+    for (const v of variants) {
+      const opts = getVariantOptions(v as any);
+      for (const opt of opts) {
+        if (!groups.has(opt.name)) groups.set(opt.name, new Set());
+        groups.get(opt.name)!.add(opt.value);
+      }
+    }
+    return Array.from(groups.entries()).map(([name, values]) => ({
+      name,
+      values: Array.from(values),
+    }));
+  }, [requiresSelection, variants]);
+
+  const [selectedAttrs, setSelectedAttrs] = useState<Record<string, string>>({});
+
+  const selectedVariant = useMemo(() => {
+    if (!requiresSelection || !variants) return null;
+    return (
+      variants.find((v) => {
+        const opts = getVariantOptions(v as any);
+        return attributeGroups.every((group) => {
+          const opt = opts.find((o) => o.name === group.name);
+          return opt && selectedAttrs[group.name] === opt.value;
+        });
+      }) ?? null
+    );
+  }, [requiresSelection, variants, selectedAttrs, attributeGroups]);
+
+  const effectiveVariantId = selectedVariant?.id ?? selectedVariantId;
+
+  function handleAttrSelect(attrName: string, value: string) {
+    const next = { ...selectedAttrs, [attrName]: value };
+    setSelectedAttrs(next);
+    if (variants) {
+      const match = variants.find((v) => {
+        const opts = getVariantOptions(v as any);
+        return attributeGroups.every((group) => {
+          const opt = opts.find((o) => o.name === group.name);
+          return opt && next[group.name] === opt.value;
+        });
+      });
+      setSelectedVariantId(match?.id ?? null);
+    }
+  }
+
+  // Compute display prices
+  const { displayOriginal, displayDiscounted, discountLabel } = useMemo(() => {
+    let effectivePrice: number;
+    if (selectedVariant) {
+      const vSale = selectedVariant.salePrice ? parseFloat(selectedVariant.salePrice) : null;
+      const vPrice = selectedVariant.price ? parseFloat(selectedVariant.price) : null;
+      effectivePrice = vSale ?? vPrice ?? parseFloat(offer.originalPrice);
+    } else {
+      effectivePrice = parseFloat(offer.originalPrice);
+    }
+
+    let discounted: number;
+    if (offer.discountType === 'PERCENTAGE') {
+      discounted = effectivePrice * (1 - parseFloat(offer.discountValue) / 100);
+    } else {
+      discounted = Math.max(0, effectivePrice - parseFloat(offer.discountValue));
+    }
+
+    const label =
+      offer.discountType === 'PERCENTAGE'
+        ? \`\${offer.discountValue}%\`
+        : (formatPrice(parseFloat(offer.discountValue), { currency }) as string);
+
+    return { displayOriginal: effectivePrice, displayDiscounted: discounted, discountLabel: label };
+  }, [selectedVariant, offer.originalPrice, offer.discountType, offer.discountValue, currency]);
+
+  const isOos =
+    selectedVariant?.inventory?.trackingMode !== 'NOT_TRACKED' &&
+    selectedVariant?.inventory?.available != null &&
+    selectedVariant.inventory.available <= 0;
+
+  const lockedLabel =
+    offer.lockedVariant?.name ??
+    (offer.lockedVariant?.attributes
+      ? Object.values(offer.lockedVariant.attributes).join(' / ')
+      : null);
+
   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);
+
+  const canAdd = !requiresSelection || !!effectiveVariantId;
 
   async function handleAdd() {
-    if (adding) return;
+    if (adding || !canAdd || isOos) return;
     try {
       setAdding(true);
       const { getClient } = await import('@/lib/brainerce');
       const client = getClient();
-      await client.addBundleToCart(cartId, offer.id);
+      await client.addBundleToCart(cartId, offer.id, effectiveVariantId ?? undefined);
       onAdd();
     } catch (err) {
       console.error('Failed to add bundle item:', err);
@@ -10046,70 +10449,121 @@ export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBun
   }
 
   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>
+    <div className={cn('bg-background border-border rounded-lg border p-4', className)}>
+      <div className="flex items-center gap-4">
+        {/* 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>
+        {/* 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>
+          )}
+          {lockedLabel && <p className="text-muted-foreground mt-0.5 text-xs">{lockedLabel}</p>}
+          <div className="mt-1 flex items-center gap-2">
+            <span className="text-muted-foreground text-sm line-through">
+              {formatPrice(displayOriginal, { currency }) as string}
+            </span>
+            <span className="text-foreground text-sm font-semibold">
+              {formatPrice(displayDiscounted, { 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 || !canAdd || isOos}
+          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')
+            : requiresSelection && !canAdd
+              ? t('selectOptions') || 'Select options'
+              : t('addBundleItem')}
+        </button>
       </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>
+      {/* Compact variant selector */}
+      {requiresSelection && (
+        <div className="mt-3 space-y-1.5 ps-20">
+          {attributeGroups.map((group) => (
+            <div key={group.name} className="flex flex-wrap items-center gap-1.5">
+              <span className="text-muted-foreground text-xs">{group.name}:</span>
+              {group.values.map((value) => {
+                const isSelected = selectedAttrs[group.name] === value;
+                const variantForValue = variants?.find((v) => {
+                  const opts = getVariantOptions(v as any);
+                  const matchesValue = opts.some((o) => o.name === group.name && o.value === value);
+                  if (!matchesValue) return false;
+                  return Object.entries(selectedAttrs).every(([k, sv]) => {
+                    if (k === group.name) return true;
+                    return opts.some((o) => o.name === k && o.value === sv);
+                  });
+                });
+                const isVariantOos =
+                  variantForValue?.inventory?.trackingMode !== 'NOT_TRACKED' &&
+                  variantForValue?.inventory?.available != null &&
+                  variantForValue.inventory.available <= 0;
+
+                return (
+                  <button
+                    key={value}
+                    type="button"
+                    onClick={() => handleAttrSelect(group.name, value)}
+                    disabled={isVariantOos}
+                    className={cn(
+                      'rounded-full border px-2.5 py-0.5 text-xs transition-colors',
+                      isSelected
+                        ? 'border-primary bg-primary text-primary-foreground'
+                        : 'border-border text-foreground hover:border-primary/50',
+                      isVariantOos && 'cursor-not-allowed line-through opacity-40'
+                    )}
+                  >
+                    {value}
+                  </button>
+                );
+              })}
+            </div>
+          ))}
+          {isOos && effectiveVariantId && (
+            <p className="text-destructive text-xs">{t('outOfStock') || 'Out of stock'}</p>
+          )}
+        </div>
+      )}
     </div>
   );
 }
 `,
   "src/components/checkout/order-bump-card.tsx": `'use client';
 
+import { useState, useMemo } from 'react';
 import Image from 'next/image';
-import type { OrderBump } from 'brainerce';
-import { formatPrice } from 'brainerce';
+import type { OrderBump, RecommendationVariant } from 'brainerce';
+import { formatPrice, getVariantOptions } from 'brainerce';
 import { useStoreInfo } from '@/providers/store-provider';
 import { useTranslations } from '@/lib/translations';
 import { cn } from '@/lib/utils';
@@ -10117,7 +10571,7 @@ import { cn } from '@/lib/utils';
 interface OrderBumpCardProps {
   bump: OrderBump;
   isAdded: boolean;
-  onToggle: (bumpId: string, add: boolean) => void;
+  onToggle: (bumpId: string, add: boolean, variantId?: string) => void;
   loading: boolean;
   className?: string;
 }
@@ -10126,66 +10580,225 @@ export function OrderBumpCard({ bump, isAdded, onToggle, loading, className }: O
   const { storeInfo } = useStoreInfo();
   const t = useTranslations('checkout');
   const currency = storeInfo?.currency || 'USD';
+  const [selectedVariantId, setSelectedVariantId] = useState<string | null>(null);
 
   const product = bump.bumpProduct;
+  const variants = product.variants;
+  const requiresSelection = bump.requiresVariantSelection && variants && variants.length > 0;
+
+  // Build attribute groups from variants for pill selector
+  const attributeGroups = useMemo(() => {
+    if (!requiresSelection || !variants) return [];
+    const groups = new Map<string, Set<string>>();
+    for (const v of variants) {
+      const opts = getVariantOptions(v as any);
+      for (const opt of opts) {
+        if (!groups.has(opt.name)) groups.set(opt.name, new Set());
+        groups.get(opt.name)!.add(opt.value);
+      }
+    }
+    return Array.from(groups.entries()).map(([name, values]) => ({
+      name,
+      values: Array.from(values),
+    }));
+  }, [requiresSelection, variants]);
+
+  // Track selected attributes
+  const [selectedAttrs, setSelectedAttrs] = useState<Record<string, string>>({});
+
+  // Find matching variant based on selected attributes
+  const selectedVariant = useMemo(() => {
+    if (!requiresSelection || !variants) return null;
+    return (
+      variants.find((v) => {
+        const opts = getVariantOptions(v as any);
+        return attributeGroups.every((group) => {
+          const opt = opts.find((o) => o.name === group.name);
+          return opt && selectedAttrs[group.name] === opt.value;
+        });
+      }) ?? null
+    );
+  }, [requiresSelection, variants, selectedAttrs, attributeGroups]);
+
+  // Update selectedVariantId when variant match changes
+  const effectiveVariantId = selectedVariant?.id ?? selectedVariantId;
+
+  function handleAttrSelect(attrName: string, value: string) {
+    const next = { ...selectedAttrs, [attrName]: value };
+    setSelectedAttrs(next);
+    // Find matching variant with new selection
+    if (variants) {
+      const match = variants.find((v) => {
+        const opts = getVariantOptions(v as any);
+        return attributeGroups.every((group) => {
+          const opt = opts.find((o) => o.name === group.name);
+          return opt && next[group.name] === opt.value;
+        });
+      });
+      setSelectedVariantId(match?.id ?? null);
+    }
+  }
+
+  // Compute display price
+  const { displayOriginal, displayDiscounted } = useMemo(() => {
+    let effectivePrice: number;
+    if (selectedVariant) {
+      const vSale = selectedVariant.salePrice ? parseFloat(selectedVariant.salePrice) : null;
+      const vPrice = selectedVariant.price ? parseFloat(selectedVariant.price) : null;
+      effectivePrice = vSale ?? vPrice ?? parseFloat(bump.originalPrice);
+    } else {
+      effectivePrice = parseFloat(bump.originalPrice);
+    }
+
+    let discounted: number | null = null;
+    if (bump.discountType && bump.discountValue) {
+      const dv = parseFloat(bump.discountValue);
+      if (bump.discountType === 'PERCENTAGE') {
+        discounted = effectivePrice * (1 - dv / 100);
+      } else {
+        discounted = Math.max(0, effectivePrice - dv);
+      }
+    }
+
+    return { displayOriginal: effectivePrice, displayDiscounted: discounted };
+  }, [selectedVariant, bump.originalPrice, bump.discountType, bump.discountValue]);
+
+  // Check if selected variant is out of stock
+  const isOos =
+    selectedVariant?.inventory?.trackingMode !== 'NOT_TRACKED' &&
+    selectedVariant?.inventory?.available != null &&
+    selectedVariant.inventory.available <= 0;
+
+  // Locked variant label
+  const lockedLabel =
+    bump.lockedVariant?.name ??
+    (bump.lockedVariant?.attributes
+      ? Object.values(bump.lockedVariant.attributes).join(' / ')
+      : null);
+
   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;
+
+  const canToggle = !requiresSelection || !!effectiveVariantId;
 
   return (
-    <label
+    <div
       className={cn(
-        'border-border hover:border-primary/50 flex cursor-pointer items-start gap-3 rounded-lg border p-3 transition-colors',
+        'border-border hover:border-primary/50 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>
-      )}
+      <label className="flex cursor-pointer items-start gap-3">
+        <input
+          type="checkbox"
+          checked={isAdded}
+          onChange={() => {
+            if (canToggle) {
+              onToggle(bump.id, !isAdded, effectiveVariantId ?? undefined);
+            }
+          }}
+          disabled={loading || !canToggle || isOos}
+          className="mt-1 h-4 w-4 shrink-0 rounded"
+        />
 
-      {/* 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>
+        {/* 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>
         )}
-        <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>
+
+        {/* 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>
+          )}
+
+          {/* Locked variant label */}
+          {lockedLabel && <p className="text-muted-foreground mt-0.5 text-xs">{lockedLabel}</p>}
+
+          {/* Price */}
+          <div className="mt-1 flex items-center gap-2">
+            {displayDiscounted != null ? (
+              <>
+                <span className="text-muted-foreground text-xs line-through">
+                  {formatPrice(displayOriginal, { currency }) as string}
+                </span>
+                <span className="text-foreground text-sm font-semibold">
+                  {formatPrice(displayDiscounted, { currency }) as string}
+                </span>
+              </>
+            ) : (
               <span className="text-foreground text-sm font-semibold">
-                {formatPrice(discountedPrice!, { currency }) as string}
+                {formatPrice(displayOriginal, { currency }) as string}
               </span>
-            </>
-          ) : (
-            <span className="text-foreground text-sm font-semibold">
-              {formatPrice(originalPrice, { currency }) as string}
-            </span>
+            )}
+            {requiresSelection && !effectiveVariantId && (
+              <span className="text-muted-foreground text-xs">
+                {t('selectOptions') || 'Select options'}
+              </span>
+            )}
+          </div>
+        </div>
+      </label>
+
+      {/* Compact variant selector */}
+      {requiresSelection && !isAdded && (
+        <div className="ms-7 mt-2 space-y-1.5">
+          {attributeGroups.map((group) => (
+            <div key={group.name} className="flex flex-wrap items-center gap-1.5">
+              <span className="text-muted-foreground text-xs">{group.name}:</span>
+              {group.values.map((value) => {
+                const isSelected = selectedAttrs[group.name] === value;
+                // Check if this value leads to any available variant
+                const variantForValue = variants?.find((v) => {
+                  const opts = getVariantOptions(v as any);
+                  const matchesValue = opts.some((o) => o.name === group.name && o.value === value);
+                  if (!matchesValue) return false;
+                  // Check other selected attrs
+                  return Object.entries(selectedAttrs).every(([k, sv]) => {
+                    if (k === group.name) return true;
+                    return opts.some((o) => o.name === k && o.value === sv);
+                  });
+                });
+                const isVariantOos =
+                  variantForValue?.inventory?.trackingMode !== 'NOT_TRACKED' &&
+                  variantForValue?.inventory?.available != null &&
+                  variantForValue.inventory.available <= 0;
+
+                return (
+                  <button
+                    key={value}
+                    type="button"
+                    onClick={() => handleAttrSelect(group.name, value)}
+                    disabled={isVariantOos}
+                    className={cn(
+                      'rounded-full border px-2.5 py-0.5 text-xs transition-colors',
+                      isSelected
+                        ? 'border-primary bg-primary text-primary-foreground'
+                        : 'border-border text-foreground hover:border-primary/50',
+                      isVariantOos && 'cursor-not-allowed line-through opacity-40'
+                    )}
+                  >
+                    {value}
+                  </button>
+                );
+              })}
+            </div>
+          ))}
+          {isOos && effectiveVariantId && (
+            <p className="text-destructive text-xs">{t('outOfStock') || 'Out of stock'}</p>
           )}
         </div>
-      </div>
-    </label>
+      )}
+    </div>
   );
 }
 `,
@@ -10548,7 +11161,8 @@ var DETAILED = `# Required Pages \u2014 Detailed Guide
 - Step 1: Customer info (email, name)
 - Step 2: Shipping address form
 - Step 3: Shipping method selection (from rates returned by \`setShippingAddress()\`)
-- Step 4: Payment (auto-detects Stripe/Grow/PayPal via \`getPaymentProviders()\`)
+- Step 4: Payment (auto-detects Stripe/Grow/PayPal/Sandbox via \`getPaymentProviders()\`)
+- If \`sandboxPaymentsEnabled\` is on, a sandbox provider with \`renderType: 'sandbox'\` is included \u2014 show a "Complete Test Order" button instead of real payment UI. Call \`completeGuestCheckout(checkoutId)\` to finalize.
 - Order summary sidebar showing \`checkout.lineItems\` (NOT cart.items!)
 - Tax display after address entry
 - Reservation countdown
@@ -10628,46 +11242,39 @@ async function handleGetRequiredPages(args) {
 var import_zod5 = require("zod");
 
 // src/utils/fetch-store-info.ts
-var import_https = __toESM(require("https"));
-var import_http = __toESM(require("http"));
 async function fetchStoreInfo(connectionId, baseUrl = "https://api.brainerce.com") {
   const url = `${baseUrl}/api/vc/${connectionId}/info`;
-  return new Promise((resolve, reject) => {
-    const client = url.startsWith("https") ? import_https.default : import_http.default;
-    const req = client.get(url, { timeout: 1e4 }, (res) => {
-      let data = "";
-      res.on("data", (chunk) => {
-        data += chunk;
-      });
-      res.on("end", () => {
-        if (res.statusCode && res.statusCode >= 400) {
-          if (res.statusCode === 404) {
-            reject(new Error(`Connection ID "${connectionId}" not found. Check your dashboard.`));
-          } else {
-            reject(new Error(`API returned status ${res.statusCode}`));
-          }
-          return;
-        }
-        try {
-          const json = JSON.parse(data);
-          resolve({
-            name: json.name || json.storeName || "My Store",
-            currency: json.currency || "USD",
-            language: json.language || "en"
-          });
-        } catch {
-          reject(new Error("Invalid response from API"));
-        }
-      });
-    });
-    req.on("error", (err) => {
-      reject(new Error(`Failed to connect to Brainerce API: ${err.message}`));
-    });
-    req.on("timeout", () => {
-      req.destroy();
-      reject(new Error("Request timed out"));
-    });
-  });
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 1e4);
+  let res;
+  try {
+    res = await fetch(url, { signal: controller.signal });
+  } catch (err) {
+    if (err.name === "AbortError") {
+      throw new Error("Request timed out");
+    }
+    throw new Error(`Failed to connect to Brainerce API: ${err.message}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+  if (res.status === 404) {
+    throw new Error(`Connection ID "${connectionId}" not found. Check your dashboard.`);
+  }
+  if (!res.ok) {
+    throw new Error(`API returned status ${res.status}`);
+  }
+  let json;
+  try {
+    json = await res.json();
+  } catch {
+    throw new Error("Invalid response from API");
+  }
+  return {
+    name: json.name || json.storeName || "My Store",
+    currency: json.currency || "USD",
+    language: json.language || "en",
+    ...json.i18n ? { i18n: json.i18n } : {}
+  };
 }
 
 // src/tools/get-store-info.ts
@@ -10678,7 +11285,11 @@ var GET_STORE_INFO_SCHEMA = {
 };
 async function handleGetStoreInfo(args) {
   try {
-    const info = await fetchStoreInfo(args.connectionId);
+    const baseUrl = (process.env.BRAINERCE_API_URL || "https://api.brainerce.com").replace(
+      /\/$/,
+      ""
+    );
+    const info = await fetchStoreInfo(args.connectionId, baseUrl);
     return {
       content: [
         {
@@ -10709,41 +11320,32 @@ async function handleGetStoreInfo(args) {
 var import_zod6 = require("zod");
 
 // src/utils/fetch-store-capabilities.ts
-var import_https2 = __toESM(require("https"));
-var import_http2 = __toESM(require("http"));
 async function fetchStoreCapabilities(connectionId, baseUrl = "https://api.brainerce.com") {
   const url = `${baseUrl}/api/vc/${connectionId}/capabilities`;
-  return new Promise((resolve, reject) => {
-    const client = url.startsWith("https") ? import_https2.default : import_http2.default;
-    const req = client.get(url, { timeout: 1e4 }, (res) => {
-      let data = "";
-      res.on("data", (chunk) => {
-        data += chunk;
-      });
-      res.on("end", () => {
-        if (res.statusCode && res.statusCode >= 400) {
-          if (res.statusCode === 404) {
-            reject(new Error(`Connection ID "${connectionId}" not found. Check your dashboard.`));
-          } else {
-            reject(new Error(`API returned status ${res.statusCode}`));
-          }
-          return;
-        }
-        try {
-          resolve(JSON.parse(data));
-        } catch {
-          reject(new Error("Invalid response from API"));
-        }
-      });
-    });
-    req.on("error", (err) => {
-      reject(new Error(`Failed to connect to Brainerce API: ${err.message}`));
-    });
-    req.on("timeout", () => {
-      req.destroy();
-      reject(new Error("Request timed out"));
-    });
-  });
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 1e4);
+  let res;
+  try {
+    res = await fetch(url, { signal: controller.signal });
+  } catch (err) {
+    if (err.name === "AbortError") {
+      throw new Error("Request timed out");
+    }
+    throw new Error(`Failed to connect to Brainerce API: ${err.message}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+  if (res.status === 404) {
+    throw new Error(`Connection ID "${connectionId}" not found. Check your dashboard.`);
+  }
+  if (!res.ok) {
+    throw new Error(`API returned status ${res.status}`);
+  }
+  try {
+    return await res.json();
+  } catch {
+    throw new Error("Invalid response from API");
+  }
 }
 
 // src/tools/get-store-capabilities.ts
@@ -10756,6 +11358,11 @@ function formatCapabilities(caps) {
   const lines = [];
   lines.push(`## Store: ${caps.store.name} (${caps.store.currency})`);
   lines.push(`Language: ${caps.store.language}`);
+  if (caps.store.i18n?.enabled) {
+    lines.push(
+      `Multi-language: ENABLED \u2014 locales: ${caps.store.i18n.supportedLocales.join(", ")} (default: ${caps.store.i18n.defaultLocale})`
+    );
+  }
   lines.push("");
   lines.push("## Configured Features");
   if (caps.features.paymentProviders.length > 0) {
@@ -10790,6 +11397,9 @@ function formatCapabilities(caps) {
   lines.push(
     `- Email verification: ${caps.connection.requireEmailVerification ? "required" : "not required"}`
   );
+  lines.push(
+    `- Sandbox payments: ${caps.connection.sandboxPaymentsEnabled ? "enabled (test orders without real payment)" : "disabled"}`
+  );
   lines.push(
     `- Inventory reservation: ${caps.connection.reservationStrategy} (${caps.connection.reservationTimeout} min timeout)`
   );
@@ -10829,11 +11439,21 @@ function formatCapabilities(caps) {
       'Email verification is required \u2014 ALWAYS build the verify-email page. Use get-code-example("verify-email").'
     );
   }
+  if (caps.connection.sandboxPaymentsEnabled) {
+    suggestions.push(
+      `Sandbox payments are enabled \u2014 the PaymentStep component shows a "Complete Test Order" button when renderType is 'sandbox'. No real charges. Test orders are marked isTestOrder: true.`
+    );
+  }
   if (caps.connection.reservationStrategy !== "ON_PAYMENT") {
     suggestions.push(
       'Inventory reservation is active \u2014 show a countdown timer. Use get-code-example("reservation-countdown").'
     );
   }
+  if (caps.store.i18n?.enabled && caps.store.i18n.supportedLocales.length > 1) {
+    suggestions.push(
+      `Multi-language is enabled (${caps.store.i18n.supportedLocales.join(", ")}). Use client.setLocale(locale) before fetching content. Consider locale-prefixed routes (/he/products, /en/products) and a language switcher in the header.`
+    );
+  }
   if (suggestions.length === 0) {
     suggestions.push(
       "Start by building the required pages. Use get-required-pages() for the checklist."
@@ -10844,7 +11464,11 @@ function formatCapabilities(caps) {
 }
 async function handleGetStoreCapabilities(args) {
   try {
-    const caps = await fetchStoreCapabilities(args.connectionId);
+    const baseUrl = (process.env.BRAINERCE_API_URL || "https://api.brainerce.com").replace(
+      /\/$/,
+      ""
+    );
+    const caps = await fetchStoreCapabilities(args.connectionId, baseUrl);
     return {
       content: [{ type: "text", text: formatCapabilities(caps) }]
     };
@@ -10941,6 +11565,20 @@ function formatCapabilitiesSummary(caps) {
   const lines = [];
   lines.push(`## Store: ${caps.store.name}`);
   lines.push(`Currency: ${caps.store.currency} | Language: ${caps.store.language}`);
+  if (caps.store.i18n?.enabled && caps.store.i18n.supportedLocales.length > 1) {
+    lines.push(
+      `Multi-language: ${caps.store.i18n.supportedLocales.join(", ")} (default: ${caps.store.i18n.defaultLocale})`
+    );
+    lines.push("");
+    lines.push("### i18n Implementation");
+    lines.push(
+      "- Call `client.setLocale(locale)` at app init based on URL prefix or user preference"
+    );
+    lines.push("- All getProducts/getCategories/getBrands calls auto-include the locale");
+    lines.push("- Use locale-prefixed routes: `/[locale]/products`, `/[locale]/products/[slug]`");
+    lines.push("- Add a language switcher component in the header");
+    lines.push('- RTL locales (he, ar): set `<html dir="rtl">` \u2014 flexbox reversal is automatic');
+  }
   lines.push("");
   lines.push("### Configured Features");
   if (caps.features.paymentProviders.length > 0) {
@@ -10982,6 +11620,9 @@ function formatCapabilitiesSummary(caps) {
   lines.push(
     `- Guest checkout tracking: ${caps.connection.guestCheckoutTracking ? "enabled" : "disabled"}`
   );
+  lines.push(
+    `- Sandbox payments: ${caps.connection.sandboxPaymentsEnabled ? "ENABLED \u2014 payment step shows test order button (no real charges)" : "disabled"}`
+  );
   return lines.join("\n");
 }
 function buildStoreBundle(options) {
@@ -10991,8 +11632,7 @@ function buildStoreBundle(options) {
     connectionId,
     storeName,
     currency,
-    language: capabilities?.store.language || "en",
-    apiUrl: "https://api.brainerce.com"
+    language: capabilities?.store.language || "en"
   };
   const sections = [];
   sections.push(`# Build: ${storeName} \u2014 ${storeType}${styleDesc}
@@ -11093,9 +11733,13 @@ var BUILD_STORE_SCHEMA = {
   storeStyle: import_zod7.z.string().optional().describe('Design style (e.g., "minimalist", "luxury", "playful", "dark mode")')
 };
 async function handleBuildStore(args) {
+  const baseUrl = (process.env.BRAINERCE_API_URL || "https://api.brainerce.com").replace(
+    /\/$/,
+    ""
+  );
   let capabilities = null;
   try {
-    capabilities = await fetchStoreCapabilities(args.connectionId);
+    capabilities = await fetchStoreCapabilities(args.connectionId, baseUrl);
   } catch {
   }
   const bundle = buildStoreBundle({
@@ -11434,6 +12078,57 @@ ${results.join("\n\n---\n\n")}`
   };
 }
 
+// src/tools/get-integration-guide.ts
+var import_zod10 = require("zod");
+var GET_INTEGRATION_GUIDE_NAME = "get-integration-guide";
+var GET_INTEGRATION_GUIDE_DESCRIPTION = 'Get the Brainerce integration guide for connecting any website to Brainerce. Returns step-by-step instructions with full API endpoints, request/response examples, and code snippets. Use "core" for the main guide (products, cart, checkout, payment, orders), "optional" for extra features (accounts, OAuth, promotions), or "rules" for validation, error codes, and edge cases.';
+var GET_INTEGRATION_GUIDE_SCHEMA = {
+  part: import_zod10.z.enum(["core", "optional", "rules"]).describe(
+    'Which part of the integration guide to retrieve. "core" = products, cart, checkout, payment, orders (start here). "optional" = customer accounts, OAuth, discounts, bundles, downloads. "rules" = validation, error codes, edge cases, decision trees, common mistakes.'
+  )
+};
+var GUIDE_URLS = {
+  core: "https://brainerce.com/docs/integration/raw?part=core",
+  optional: "https://brainerce.com/docs/integration/raw?part=optional",
+  rules: "https://brainerce.com/docs/integration/raw?part=rules"
+};
+async function handleGetIntegrationGuide(args) {
+  const url = GUIDE_URLS[args.part];
+  if (!url) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Unknown part: "${args.part}". Available parts: core, optional, rules.`
+        }
+      ]
+    };
+  }
+  try {
+    const response = await fetch(url, {
+      headers: { Accept: "text/plain" },
+      signal: AbortSignal.timeout(15e3)
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    const content = await response.text();
+    return {
+      content: [{ type: "text", text: content }]
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Failed to fetch integration guide (${args.part}): ${message}. You can read it directly at: ${url}`
+        }
+      ]
+    };
+  }
+}
+
 // src/resources/sdk-types.ts
 var SDK_TYPES_URI = "brainerce://sdk/types";
 var SDK_TYPES_NAME = "Brainerce SDK Types";
@@ -11588,15 +12283,15 @@ async function handleProjectTemplate(uri) {
 }
 
 // src/prompts/create-store.ts
-var import_zod10 = require("zod");
+var import_zod11 = require("zod");
 var CREATE_STORE_NAME = "create-store";
 var CREATE_STORE_DESCRIPTION = "Generate a personalized prompt for building a complete Brainerce e-commerce store. Instructs the AI to call build-store for all templates and validate-store when done.";
 var CREATE_STORE_SCHEMA = {
-  connectionId: import_zod10.z.string().describe("Vibe-coded connection ID (starts with vc_)"),
-  storeName: import_zod10.z.string().describe('Name of the store (e.g., "Urban Threads")'),
-  storeType: import_zod10.z.string().describe('Type of store (e.g., "Clothing store", "Electronics shop", "Bakery")'),
-  currency: import_zod10.z.string().optional().default("USD").describe("Store currency code (e.g., USD, ILS, EUR)"),
-  storeStyle: import_zod10.z.string().optional().describe('Design style (e.g., "minimalist", "luxury", "playful", "dark mode")')
+  connectionId: import_zod11.z.string().describe("Vibe-coded connection ID (starts with vc_)"),
+  storeName: import_zod11.z.string().describe('Name of the store (e.g., "Urban Threads")'),
+  storeType: import_zod11.z.string().describe('Type of store (e.g., "Clothing store", "Electronics shop", "Bakery")'),
+  currency: import_zod11.z.string().optional().default("USD").describe("Store currency code (e.g., USD, ILS, EUR)"),
+  storeStyle: import_zod11.z.string().optional().describe('Design style (e.g., "minimalist", "luxury", "playful", "dark mode")')
 };
 function handleCreateStore(args) {
   const styleDesc = args.storeStyle ? ` with a ${args.storeStyle} design style` : "";
@@ -11635,6 +12330,13 @@ DO NOT STOP until all 13 pages + header are implemented:
 13. \`/account\` \u2014 Account dashboard
 14. Header component with cart count + search
 
+## Multi-Language
+If the store has multi-language enabled (check build-store output), implement:
+- Locale-prefixed routes: /[locale]/products instead of /products
+- Call client.setLocale(locale) based on URL prefix
+- Language switcher in header
+- dir="rtl" on <html> for RTL locales (he, ar)
+
 ## Step 3: Validate
 After building all pages, call \`validate-store\` with the list of files you created to verify nothing is missing.
 
@@ -11653,11 +12355,11 @@ After building all pages, call \`validate-store\` with the list of files you cre
 }
 
 // src/prompts/add-feature.ts
-var import_zod11 = require("zod");
+var import_zod12 = require("zod");
 var ADD_FEATURE_NAME = "add-feature";
 var ADD_FEATURE_DESCRIPTION = "Generate a focused prompt for adding a specific feature to an existing Brainerce store. Returns targeted SDK docs, types, and code examples for just that feature.";
 var ADD_FEATURE_SCHEMA = {
-  feature: import_zod11.z.enum([
+  feature: import_zod12.z.enum([
     "products",
     "cart",
     "checkout",
@@ -11670,8 +12372,8 @@ var ADD_FEATURE_SCHEMA = {
     "search",
     "tax"
   ]).describe("The feature to add"),
-  connectionId: import_zod11.z.string().optional().describe("Vibe-coded connection ID (starts with vc_)"),
-  currency: import_zod11.z.string().optional().default("USD").describe("Store currency code")
+  connectionId: import_zod12.z.string().optional().describe("Vibe-coded connection ID (starts with vc_)"),
+  currency: import_zod12.z.string().optional().default("USD").describe("Store currency code")
 };
 var FEATURE_TO_TOPICS = {
   products: { topics: ["products"], domains: ["products"] },
@@ -11786,6 +12488,12 @@ function createServer() {
     GET_PAGE_CODE_SCHEMA,
     handleGetPageCode
   );
+  server.tool(
+    GET_INTEGRATION_GUIDE_NAME,
+    GET_INTEGRATION_GUIDE_DESCRIPTION,
+    GET_INTEGRATION_GUIDE_SCHEMA,
+    handleGetIntegrationGuide
+  );
   server.resource(
     SDK_TYPES_NAME,
     SDK_TYPES_URI,