@brainerce/mcp-server 2.1.1 → 2.4.0

package/dist/bin/http.js

@@ -314,6 +314,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} />;
   }
@@ -432,11 +446,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
@@ -3157,7 +3172,12 @@ export default function CartPage() {
             <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} />
+                <CartBundleOfferCard
+                  key={offer.id}
+                  offer={offer}
+                  cartId={cart.id}
+                  onAdd={refreshCart}
+                />
               ))}
             </div>
           )}
@@ -7654,8 +7674,9 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
       })
       .catch(() => null);
 
-    // B) Load + init SDK as early as possible
+    // B) Load + init SDK as early as possible (skip for sandbox)
     providerPromise.then((providerSdk) => {
+      if (providerSdk?.renderType === 'sandbox') return;
       if (providerSdk?.renderType === 'sdk-widget' && providerSdk.scriptUrl) {
         currentSdk = providerSdk;
         loadScript(providerSdk);
@@ -7682,6 +7703,9 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
       const sdk = resolveClientSdk(intent, providerSdk);
       currentSdk = sdk;
 
+      // Sandbox mode \u2014 no SDK to load, UI handles it
+      if (sdk.renderType === 'sandbox') return;
+
       if (sdk.renderType === 'redirect') {
         window.location.href = intent.clientSecret;
         return;
@@ -7776,6 +7800,48 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
 
   const sdk = resolveClientSdk(paymentIntent, preloadedSdk);
 
+  if (sdk.renderType === 'sandbox') {
+    const handleCompleteSandbox = async () => {
+      setLoading(true);
+      try {
+        const client = getClient();
+        await client.completeGuestCheckout(checkoutId);
+        window.location.href = \`/order-confirmation?checkout_id=\${checkoutId}\`;
+      } catch (err) {
+        setError(err instanceof Error ? err.message : t('paymentError'));
+        setLoading(false);
+      }
+    };
+
+    return (
+      <div className={cn('py-8 text-center', className)}>
+        <div className="mx-auto max-w-md rounded-lg border border-amber-200 bg-amber-50 p-6">
+          <svg
+            className="mx-auto mb-3 h-10 w-10 text-amber-500"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={1.5}
+              d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4.5c-.77-.833-2.694-.833-3.464 0L3.34 16.5c-.77.833.192 2.5 1.732 2.5z"
+            />
+          </svg>
+          <h3 className="text-foreground mb-1 text-lg font-semibold">{t('sandboxTitle')}</h3>
+          <p className="text-muted-foreground mb-4 text-sm">{t('sandboxDescription')}</p>
+          <button
+            onClick={handleCompleteSandbox}
+            className="inline-flex items-center rounded-md bg-amber-500 px-6 py-2.5 text-sm font-medium text-white transition-colors hover:bg-amber-600"
+          >
+            {t('completeTestOrder')}
+          </button>
+        </div>
+      </div>
+    );
+  }
+
   if (sdk.renderType === 'sdk-widget') {
     const containerId =
       sdk.containerId || \`\${paymentIntent.provider || 'payment'}-payment-container\`;
@@ -9933,18 +9999,18 @@ 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;
+  cartId: string;
   onAdd: () => void;
   className?: string;
 }
 
-export function CartBundleOfferCard({ offer, onAdd, className }: CartBundleOfferCardProps) {
+export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBundleOfferCardProps) {
   const { storeInfo } = useStoreInfo();
   const t = useTranslations('cart');
   const currency = storeInfo?.currency || 'USD';
@@ -9968,12 +10034,9 @@ export function CartBundleOfferCard({ offer, onAdd, className }: CartBundleOffer
     if (adding) return;
     try {
       setAdding(true);
+      const { getClient } = await import('@/lib/brainerce');
       const client = getClient();
-      await client.smartAddToCart({
-        productId: product.id,
-        variantId: offer.bundleVariantId || undefined,
-        quantity: 1,
-      });
+      await client.addBundleToCart(cartId, offer.id);
       onAdd();
     } catch (err) {
       console.error('Failed to add bundle item:', err);
@@ -10485,7 +10548,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
@@ -10727,6 +10791,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)`
   );
@@ -10766,6 +10833,11 @@ 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").'
@@ -10919,6 +10991,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) {

package/dist/bin/stdio.js

@@ -312,6 +312,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} />;
   }
@@ -430,11 +444,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
@@ -3155,7 +3170,12 @@ export default function CartPage() {
             <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} />
+                <CartBundleOfferCard
+                  key={offer.id}
+                  offer={offer}
+                  cartId={cart.id}
+                  onAdd={refreshCart}
+                />
               ))}
             </div>
           )}
@@ -7652,8 +7672,9 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
       })
       .catch(() => null);
 
-    // B) Load + init SDK as early as possible
+    // B) Load + init SDK as early as possible (skip for sandbox)
     providerPromise.then((providerSdk) => {
+      if (providerSdk?.renderType === 'sandbox') return;
       if (providerSdk?.renderType === 'sdk-widget' && providerSdk.scriptUrl) {
         currentSdk = providerSdk;
         loadScript(providerSdk);
@@ -7680,6 +7701,9 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
       const sdk = resolveClientSdk(intent, providerSdk);
       currentSdk = sdk;
 
+      // Sandbox mode \u2014 no SDK to load, UI handles it
+      if (sdk.renderType === 'sandbox') return;
+
       if (sdk.renderType === 'redirect') {
         window.location.href = intent.clientSecret;
         return;
@@ -7774,6 +7798,48 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
 
   const sdk = resolveClientSdk(paymentIntent, preloadedSdk);
 
+  if (sdk.renderType === 'sandbox') {
+    const handleCompleteSandbox = async () => {
+      setLoading(true);
+      try {
+        const client = getClient();
+        await client.completeGuestCheckout(checkoutId);
+        window.location.href = \`/order-confirmation?checkout_id=\${checkoutId}\`;
+      } catch (err) {
+        setError(err instanceof Error ? err.message : t('paymentError'));
+        setLoading(false);
+      }
+    };
+
+    return (
+      <div className={cn('py-8 text-center', className)}>
+        <div className="mx-auto max-w-md rounded-lg border border-amber-200 bg-amber-50 p-6">
+          <svg
+            className="mx-auto mb-3 h-10 w-10 text-amber-500"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={1.5}
+              d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4.5c-.77-.833-2.694-.833-3.464 0L3.34 16.5c-.77.833.192 2.5 1.732 2.5z"
+            />
+          </svg>
+          <h3 className="text-foreground mb-1 text-lg font-semibold">{t('sandboxTitle')}</h3>
+          <p className="text-muted-foreground mb-4 text-sm">{t('sandboxDescription')}</p>
+          <button
+            onClick={handleCompleteSandbox}
+            className="inline-flex items-center rounded-md bg-amber-500 px-6 py-2.5 text-sm font-medium text-white transition-colors hover:bg-amber-600"
+          >
+            {t('completeTestOrder')}
+          </button>
+        </div>
+      </div>
+    );
+  }
+
   if (sdk.renderType === 'sdk-widget') {
     const containerId =
       sdk.containerId || \`\${paymentIntent.provider || 'payment'}-payment-container\`;
@@ -9931,18 +9997,18 @@ 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;
+  cartId: string;
   onAdd: () => void;
   className?: string;
 }
 
-export function CartBundleOfferCard({ offer, onAdd, className }: CartBundleOfferCardProps) {
+export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBundleOfferCardProps) {
   const { storeInfo } = useStoreInfo();
   const t = useTranslations('cart');
   const currency = storeInfo?.currency || 'USD';
@@ -9966,12 +10032,9 @@ export function CartBundleOfferCard({ offer, onAdd, className }: CartBundleOffer
     if (adding) return;
     try {
       setAdding(true);
+      const { getClient } = await import('@/lib/brainerce');
       const client = getClient();
-      await client.smartAddToCart({
-        productId: product.id,
-        variantId: offer.bundleVariantId || undefined,
-        quantity: 1,
-      });
+      await client.addBundleToCart(cartId, offer.id);
       onAdd();
     } catch (err) {
       console.error('Failed to add bundle item:', err);
@@ -10483,7 +10546,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
@@ -10725,6 +10789,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)`
   );
@@ -10764,6 +10831,11 @@ 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").'
@@ -10917,6 +10989,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) {

package/dist/index.d.mts

@@ -50,6 +50,7 @@ interface StoreCapabilities {
         ordersWriteEnabled: boolean;
         guestCheckoutTracking: boolean;
         requireEmailVerification: boolean;
+        sandboxPaymentsEnabled: boolean;
         reservationStrategy: string;
         reservationTimeout: number;
         lowStockWarning: boolean;

package/dist/index.d.ts

@@ -50,6 +50,7 @@ interface StoreCapabilities {
         ordersWriteEnabled: boolean;
         guestCheckoutTracking: boolean;
         requireEmailVerification: boolean;
+        sandboxPaymentsEnabled: boolean;
         reservationStrategy: string;
         reservationTimeout: number;
         lowStockWarning: boolean;

package/dist/index.js

@@ -329,6 +329,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 +461,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
@@ -3172,7 +3187,12 @@ export default function CartPage() {
             <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} />
+                <CartBundleOfferCard
+                  key={offer.id}
+                  offer={offer}
+                  cartId={cart.id}
+                  onAdd={refreshCart}
+                />
               ))}
             </div>
           )}
@@ -7669,8 +7689,9 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
       })
       .catch(() => null);
 
-    // B) Load + init SDK as early as possible
+    // B) Load + init SDK as early as possible (skip for sandbox)
     providerPromise.then((providerSdk) => {
+      if (providerSdk?.renderType === 'sandbox') return;
       if (providerSdk?.renderType === 'sdk-widget' && providerSdk.scriptUrl) {
         currentSdk = providerSdk;
         loadScript(providerSdk);
@@ -7697,6 +7718,9 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
       const sdk = resolveClientSdk(intent, providerSdk);
       currentSdk = sdk;
 
+      // Sandbox mode \u2014 no SDK to load, UI handles it
+      if (sdk.renderType === 'sandbox') return;
+
       if (sdk.renderType === 'redirect') {
         window.location.href = intent.clientSecret;
         return;
@@ -7791,6 +7815,48 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
 
   const sdk = resolveClientSdk(paymentIntent, preloadedSdk);
 
+  if (sdk.renderType === 'sandbox') {
+    const handleCompleteSandbox = async () => {
+      setLoading(true);
+      try {
+        const client = getClient();
+        await client.completeGuestCheckout(checkoutId);
+        window.location.href = \`/order-confirmation?checkout_id=\${checkoutId}\`;
+      } catch (err) {
+        setError(err instanceof Error ? err.message : t('paymentError'));
+        setLoading(false);
+      }
+    };
+
+    return (
+      <div className={cn('py-8 text-center', className)}>
+        <div className="mx-auto max-w-md rounded-lg border border-amber-200 bg-amber-50 p-6">
+          <svg
+            className="mx-auto mb-3 h-10 w-10 text-amber-500"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={1.5}
+              d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4.5c-.77-.833-2.694-.833-3.464 0L3.34 16.5c-.77.833.192 2.5 1.732 2.5z"
+            />
+          </svg>
+          <h3 className="text-foreground mb-1 text-lg font-semibold">{t('sandboxTitle')}</h3>
+          <p className="text-muted-foreground mb-4 text-sm">{t('sandboxDescription')}</p>
+          <button
+            onClick={handleCompleteSandbox}
+            className="inline-flex items-center rounded-md bg-amber-500 px-6 py-2.5 text-sm font-medium text-white transition-colors hover:bg-amber-600"
+          >
+            {t('completeTestOrder')}
+          </button>
+        </div>
+      </div>
+    );
+  }
+
   if (sdk.renderType === 'sdk-widget') {
     const containerId =
       sdk.containerId || \`\${paymentIntent.provider || 'payment'}-payment-container\`;
@@ -9948,18 +10014,18 @@ 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;
+  cartId: string;
   onAdd: () => void;
   className?: string;
 }
 
-export function CartBundleOfferCard({ offer, onAdd, className }: CartBundleOfferCardProps) {
+export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBundleOfferCardProps) {
   const { storeInfo } = useStoreInfo();
   const t = useTranslations('cart');
   const currency = storeInfo?.currency || 'USD';
@@ -9983,12 +10049,9 @@ export function CartBundleOfferCard({ offer, onAdd, className }: CartBundleOffer
     if (adding) return;
     try {
       setAdding(true);
+      const { getClient } = await import('@/lib/brainerce');
       const client = getClient();
-      await client.smartAddToCart({
-        productId: product.id,
-        variantId: offer.bundleVariantId || undefined,
-        quantity: 1,
-      });
+      await client.addBundleToCart(cartId, offer.id);
       onAdd();
     } catch (err) {
       console.error('Failed to add bundle item:', err);
@@ -10500,7 +10563,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
@@ -10742,6 +10806,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)`
   );
@@ -10781,6 +10848,11 @@ 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").'
@@ -10934,6 +11006,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) {

package/dist/index.mjs

@@ -284,6 +284,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} />;
   }
@@ -402,11 +416,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
@@ -3127,7 +3142,12 @@ export default function CartPage() {
             <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} />
+                <CartBundleOfferCard
+                  key={offer.id}
+                  offer={offer}
+                  cartId={cart.id}
+                  onAdd={refreshCart}
+                />
               ))}
             </div>
           )}
@@ -7624,8 +7644,9 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
       })
       .catch(() => null);
 
-    // B) Load + init SDK as early as possible
+    // B) Load + init SDK as early as possible (skip for sandbox)
     providerPromise.then((providerSdk) => {
+      if (providerSdk?.renderType === 'sandbox') return;
       if (providerSdk?.renderType === 'sdk-widget' && providerSdk.scriptUrl) {
         currentSdk = providerSdk;
         loadScript(providerSdk);
@@ -7652,6 +7673,9 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
       const sdk = resolveClientSdk(intent, providerSdk);
       currentSdk = sdk;
 
+      // Sandbox mode \u2014 no SDK to load, UI handles it
+      if (sdk.renderType === 'sandbox') return;
+
       if (sdk.renderType === 'redirect') {
         window.location.href = intent.clientSecret;
         return;
@@ -7746,6 +7770,48 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
 
   const sdk = resolveClientSdk(paymentIntent, preloadedSdk);
 
+  if (sdk.renderType === 'sandbox') {
+    const handleCompleteSandbox = async () => {
+      setLoading(true);
+      try {
+        const client = getClient();
+        await client.completeGuestCheckout(checkoutId);
+        window.location.href = \`/order-confirmation?checkout_id=\${checkoutId}\`;
+      } catch (err) {
+        setError(err instanceof Error ? err.message : t('paymentError'));
+        setLoading(false);
+      }
+    };
+
+    return (
+      <div className={cn('py-8 text-center', className)}>
+        <div className="mx-auto max-w-md rounded-lg border border-amber-200 bg-amber-50 p-6">
+          <svg
+            className="mx-auto mb-3 h-10 w-10 text-amber-500"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={1.5}
+              d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4.5c-.77-.833-2.694-.833-3.464 0L3.34 16.5c-.77.833.192 2.5 1.732 2.5z"
+            />
+          </svg>
+          <h3 className="text-foreground mb-1 text-lg font-semibold">{t('sandboxTitle')}</h3>
+          <p className="text-muted-foreground mb-4 text-sm">{t('sandboxDescription')}</p>
+          <button
+            onClick={handleCompleteSandbox}
+            className="inline-flex items-center rounded-md bg-amber-500 px-6 py-2.5 text-sm font-medium text-white transition-colors hover:bg-amber-600"
+          >
+            {t('completeTestOrder')}
+          </button>
+        </div>
+      </div>
+    );
+  }
+
   if (sdk.renderType === 'sdk-widget') {
     const containerId =
       sdk.containerId || \`\${paymentIntent.provider || 'payment'}-payment-container\`;
@@ -9903,18 +9969,18 @@ 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;
+  cartId: string;
   onAdd: () => void;
   className?: string;
 }
 
-export function CartBundleOfferCard({ offer, onAdd, className }: CartBundleOfferCardProps) {
+export function CartBundleOfferCard({ offer, cartId, onAdd, className }: CartBundleOfferCardProps) {
   const { storeInfo } = useStoreInfo();
   const t = useTranslations('cart');
   const currency = storeInfo?.currency || 'USD';
@@ -9938,12 +10004,9 @@ export function CartBundleOfferCard({ offer, onAdd, className }: CartBundleOffer
     if (adding) return;
     try {
       setAdding(true);
+      const { getClient } = await import('@/lib/brainerce');
       const client = getClient();
-      await client.smartAddToCart({
-        productId: product.id,
-        variantId: offer.bundleVariantId || undefined,
-        quantity: 1,
-      });
+      await client.addBundleToCart(cartId, offer.id);
       onAdd();
     } catch (err) {
       console.error('Failed to add bundle item:', err);
@@ -10455,7 +10518,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
@@ -10697,6 +10761,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)`
   );
@@ -10736,6 +10803,11 @@ 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").'
@@ -10889,6 +10961,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainerce/mcp-server",
-  "version": "2.1.1",
+  "version": "2.4.0",
   "description": "MCP server for AI-powered Brainerce store building. Provides SDK docs, types, and code examples to AI tools like Lovable, Cursor, and Claude Code.",
   "bin": {
     "brainerce-mcp": "dist/bin/stdio.js"