@brainerce/mcp-server 2.7.0 → 2.9.0

package/dist/index.mjs

@@ -403,6 +403,234 @@ function PayPalPaymentForm({ clientId, orderId, checkoutId }: { clientId: string
 }
 \`\`\``;
 }
+function getCheckoutCustomFieldsSection() {
+  return `## Checkout Custom Fields (Optional Step Between Shipping & Payment)
+
+Some stores configure **custom fields** at checkout \u2014 e.g., gift wrapping, floor number for delivery, installation date, custom engraving. Each field can add a **surcharge** to the order total. The server filters by visibility (always / shipping-only / pickup-only / cart-products) and calculates surcharges automatically.
+
+### When to Build This
+
+Check capabilities first:
+\`\`\`typescript
+const caps = await fetch(\`/api/vc/\${connectionId}/capabilities\`).then(r => r.json());
+if (caps.features.hasCheckoutCustomFields) {
+  // Build the step described below
+}
+\`\`\`
+
+If \`hasCheckoutCustomFields\` is true, you MUST build this step or customers will be charged surcharges they never saw.
+
+### Where to Place It
+
+After \`selectShippingMethod()\` (or pickup confirmation), BEFORE \`createPaymentIntent()\`. Pseudocode:
+
+\`\`\`
+address \u2192 shipping/pickup \u2192 custom-fields (NEW) \u2192 payment
+\`\`\`
+
+If the loaded fields array is empty for this checkout (visibility filters can hide all fields), **skip the step entirely** \u2014 go straight to payment with no UI flicker.
+
+### Loading Field Definitions
+
+\`\`\`typescript
+import type { CheckoutCustomFieldDefinition } from 'brainerce';
+
+const fields = await client.getCheckoutCustomFields(checkoutId);
+if (fields.length === 0) {
+  setStep('payment');  // Nothing to collect
+  return;
+}
+\`\`\`
+
+Each \`CheckoutCustomFieldDefinition\` has:
+- \`key\` \u2014 the form field name to use in your state
+- \`name\` \u2014 display label
+- \`description\` \u2014 helper text (render below the input)
+- \`type\` \u2014 \`'TEXT' | 'TEXTAREA' | 'NUMBER' | 'BOOLEAN' | 'SELECT' | 'DATE'\`
+- \`required\` \u2014 boolean
+- \`minLength\` / \`maxLength\` \u2014 for TEXT/TEXTAREA
+- \`minValue\` / \`maxValue\` \u2014 for NUMBER
+- \`options\` \u2014 \`Array<{value, label}>\` for SELECT
+- \`pricing\` \u2014 never render this; the server uses it to compute surcharges
+
+### Rendering All 6 Field Types
+
+\`\`\`typescript
+function CustomFieldsStep({ fields, values, onChange, onApply, loading }: {
+  fields: CheckoutCustomFieldDefinition[];
+  values: Record<string, unknown>;
+  onChange: (key: string, value: unknown) => void;
+  onApply: () => void;
+  loading?: boolean;
+}) {
+  return (
+    <div className="space-y-4">
+      {fields.map((field) => {
+        const value = values[field.key] ?? '';
+        const label = (
+          <label className="block text-sm font-medium">
+            {field.name}{field.required && <span className="text-red-500"> *</span>}
+          </label>
+        );
+        const help = field.description && (
+          <p className="text-xs text-gray-500 mt-1">{field.description}</p>
+        );
+
+        switch (field.type) {
+          case 'TEXT':
+            return (
+              <div key={field.key}>
+                {label}
+                <input
+                  type="text"
+                  value={value as string}
+                  onChange={(e) => onChange(field.key, e.target.value)}
+                  required={field.required}
+                  minLength={field.minLength ?? undefined}
+                  maxLength={field.maxLength ?? undefined}
+                  className="w-full border rounded px-3 py-2"
+                />
+                {help}
+              </div>
+            );
+          case 'TEXTAREA':
+            return (
+              <div key={field.key}>
+                {label}
+                <textarea
+                  value={value as string}
+                  onChange={(e) => onChange(field.key, e.target.value)}
+                  required={field.required}
+                  minLength={field.minLength ?? undefined}
+                  maxLength={field.maxLength ?? undefined}
+                  rows={3}
+                  className="w-full border rounded px-3 py-2"
+                />
+                {help}
+              </div>
+            );
+          case 'NUMBER':
+            return (
+              <div key={field.key}>
+                {label}
+                <input
+                  type="number"
+                  value={value as number}
+                  onChange={(e) => onChange(field.key, e.target.valueAsNumber)}
+                  required={field.required}
+                  min={field.minValue ?? undefined}
+                  max={field.maxValue ?? undefined}
+                  className="w-full border rounded px-3 py-2"
+                />
+                {help}
+              </div>
+            );
+          case 'BOOLEAN':
+            return (
+              <div key={field.key} className="flex items-start gap-2">
+                <input
+                  type="checkbox"
+                  checked={value === true}
+                  onChange={(e) => onChange(field.key, e.target.checked)}
+                  className="mt-1"
+                />
+                <div>{label}{help}</div>
+              </div>
+            );
+          case 'SELECT':
+            return (
+              <div key={field.key}>
+                {label}
+                <select
+                  value={value as string}
+                  onChange={(e) => onChange(field.key, e.target.value)}
+                  required={field.required}
+                  className="w-full border rounded px-3 py-2"
+                >
+                  <option value="">\u2014 Select \u2014</option>
+                  {field.options?.map((opt) => (
+                    <option key={opt.value} value={opt.value}>{opt.label}</option>
+                  ))}
+                </select>
+                {help}
+              </div>
+            );
+          case 'DATE':
+            return (
+              <div key={field.key}>
+                {label}
+                <input
+                  type="date"
+                  value={value as string}
+                  onChange={(e) => onChange(field.key, e.target.value)}
+                  required={field.required}
+                  className="w-full border rounded px-3 py-2"
+                />
+                {help}
+              </div>
+            );
+          default:
+            return null;
+        }
+      })}
+
+      <button
+        type="button"
+        onClick={onApply}
+        disabled={loading}
+        className="w-full bg-black text-white py-3 rounded"
+      >
+        {loading ? 'Updating\u2026' : 'Continue to Payment'}
+      </button>
+    </div>
+  );
+}
+\`\`\`
+
+### Submitting Values & Recalculating Surcharges
+
+\`\`\`typescript
+async function applyCustomFields() {
+  setLoading(true);
+  try {
+    // Server validates required + min/max + coerces types + recalculates totals
+    const updated = await client.setCheckoutCustomFields(checkoutId, customFieldValues);
+    setCheckout(updated);  // updated.surchargeAmount and updated.appliedSurcharges are now fresh
+    setStep('payment');
+  } catch (err) {
+    setError(err instanceof Error ? err.message : 'Failed to save selections');
+  } finally {
+    setLoading(false);
+  }
+}
+\`\`\`
+
+### Order Summary \u2014 Show the Surcharges
+
+**Critical:** if you don't render \`appliedSurcharges\`, customers will see a higher total with no explanation. Add this to your order summary above the total row:
+
+\`\`\`typescript
+{checkout.appliedSurcharges?.length > 0 && (
+  <>
+    {checkout.appliedSurcharges.map((s) => (
+      <div key={s.key} className="flex justify-between text-sm text-gray-600">
+        <span>{s.name}</span>
+        <span>{formatPrice(s.amount, { currency })}</span>
+      </div>
+    ))}
+  </>
+)}
+\`\`\`
+
+\`checkout.surchargeAmount\` is a string (use \`parseFloat()\`); \`checkout.totalAmount\` already includes it.
+
+### Notes
+
+- The server filters fields by \`visibility\` (\`always\` / \`shipping\` / \`pickup\` / \`products\`) \u2014 your client just renders what \`getCheckoutCustomFields()\` returns.
+- The server validates \`required\`, \`minLength\`/\`maxLength\`, \`minValue\`/\`maxValue\`, and SELECT options. Don't rely on client validation alone \u2014 surface server errors with a toast.
+- If \`getCheckoutCustomFields()\` returns 0 fields, skip the step entirely. Don't render an empty UI.
+`;
+}
 function getPaymentProvidersSection() {
   return `## Payment Provider Detection (DO THIS FIRST on checkout page!)
 
@@ -1252,6 +1480,10 @@ ${getCheckoutFlowSection(currency)}
 
 ---
 
+${getCheckoutCustomFieldsSection()}
+
+---
+
 ${getPaymentProvidersSection()}
 
 ---
@@ -1310,6 +1542,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getCartSection(cur);
     case "checkout":
       return getCheckoutFlowSection(cur);
+    case "checkout-custom-fields":
+      return getCheckoutCustomFieldsSection();
     case "payment":
       return getPaymentProvidersSection();
     case "auth":
@@ -1338,7 +1572,7 @@ function getSectionByTopic(topic, connectionId, currency) {
         storeType: "E-commerce store"
       });
     default:
-      return `Unknown topic: "${topic}". Available topics: setup, products, cart, checkout, payment, auth, order-confirmation, inventory, discounts, recommendations, tax, critical-rules, type-reference, admin, all`;
+      return `Unknown topic: "${topic}". Available topics: setup, products, cart, checkout, checkout-custom-fields, payment, auth, order-confirmation, inventory, discounts, recommendations, tax, critical-rules, type-reference, admin, all`;
   }
 }
 
@@ -1351,6 +1585,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "products",
     "cart",
     "checkout",
+    "checkout-custom-fields",
     "payment",
     "auth",
     "order-confirmation",
@@ -3372,6 +3607,7 @@ import type {
   ShippingDestinations,
   PickupLocation,
   CheckoutBumpsResponse,
+  CheckoutCustomFieldDefinition,
 } from 'brainerce';
 import { formatPrice } from 'brainerce';
 import { getClient } from '@/lib/brainerce';
@@ -3381,6 +3617,7 @@ import { ShippingStep } from '@/components/checkout/shipping-step';
 import { PaymentStep } from '@/components/checkout/payment-step';
 import { DeliveryMethodStep } from '@/components/checkout/delivery-method-step';
 import { PickupStep } from '@/components/checkout/pickup-step';
+import { CustomFieldsStep } from '@/components/checkout/custom-fields-step';
 import { TaxDisplay } from '@/components/checkout/tax-display';
 import { OrderBumpCard } from '@/components/checkout/order-bump-card';
 import { CouponInput } from '@/components/cart/coupon-input';
@@ -3389,7 +3626,7 @@ import { LoadingSpinner } from '@/components/shared/loading-spinner';
 import { useTranslations } from '@/lib/translations';
 import { cn } from '@/lib/utils';
 
-type CheckoutStep = 'method' | 'address' | 'shipping' | 'pickup' | 'payment';
+type CheckoutStep = 'method' | 'address' | 'shipping' | 'pickup' | 'custom-fields' | 'payment';
 
 function CheckoutContent() {
   const searchParams = useSearchParams();
@@ -3422,6 +3659,9 @@ function CheckoutContent() {
   const [orderBumps, setOrderBumps] = useState<CheckoutBumpsResponse | null>(null);
   const [addedBumpIds, setAddedBumpIds] = useState<Set<string>>(new Set());
   const [bumpLoading, setBumpLoading] = useState<string | null>(null);
+  const [customFields, setCustomFields] = useState<CheckoutCustomFieldDefinition[]>([]);
+  const [customFieldValues, setCustomFieldValues] = useState<Record<string, unknown>>({});
+  const [customFieldsLoading, setCustomFieldsLoading] = useState(false);
 
   // Check for returning from canceled payment
   const canceled = searchParams.get('canceled') === 'true';
@@ -3473,6 +3713,23 @@ function CheckoutContent() {
           const existing = await client.getCheckout(existingCheckoutId);
           setCheckout(existing);
 
+          // Preload custom field definitions and any existing values so the
+          // step indicator and "change options" affordance work on resume.
+          client
+            .getCheckoutCustomFields(existing.id)
+            .then((fields) => {
+              setCustomFields(fields);
+              const existingValues = (
+                existing as unknown as {
+                  customFieldValues?: Record<string, unknown> | null;
+                }
+              ).customFieldValues;
+              if (existingValues) setCustomFieldValues(existingValues);
+            })
+            .catch(() => {
+              setCustomFields([]);
+            });
+
           // Determine step based on checkout state
           const allDigital = existing.lineItems.every(
             (i) => (i.product as unknown as { isDownloadable?: boolean }).isDownloadable
@@ -3643,6 +3900,21 @@ function CheckoutContent() {
     }
   }
 
+  // After shipping/pickup is set, decide whether to show the custom-fields step
+  // or jump straight to payment. Returns the next step.
+  async function loadCustomFieldsOrSkip(checkoutId: string): Promise<CheckoutStep> {
+    try {
+      const fields = await getClient().getCheckoutCustomFields(checkoutId);
+      setCustomFields(fields);
+      return fields.length > 0 ? 'custom-fields' : 'payment';
+    } catch {
+      // If the endpoint isn't available or fails, fall through to payment
+      // rather than blocking the customer.
+      setCustomFields([]);
+      return 'payment';
+    }
+  }
+
   // Handle shipping method selection
   async function handleShippingSelect(rateId: string) {
     if (!checkout) return;
@@ -3655,7 +3927,7 @@ function CheckoutContent() {
 
       const updated = await client.selectShippingMethod(checkout.id, rateId);
       setCheckout(updated);
-      setStep('payment');
+      setStep(await loadCustomFieldsOrSkip(updated.id));
     } catch (err) {
       const message = err instanceof Error ? err.message : t('failedToSelectShipping');
       setError(message);
@@ -3664,6 +3936,23 @@ function CheckoutContent() {
     }
   }
 
+  // Submit custom fields
+  async function handleCustomFieldsApply() {
+    if (!checkout) return;
+    try {
+      setCustomFieldsLoading(true);
+      setError(null);
+      const updated = await getClient().setCheckoutCustomFields(checkout.id, customFieldValues);
+      setCheckout(updated);
+      setStep('payment');
+    } catch (err) {
+      const message = err instanceof Error ? err.message : t('customFieldsFailed');
+      setError(message);
+    } finally {
+      setCustomFieldsLoading(false);
+    }
+  }
+
   // Handle delivery method selection
   async function handleDeliveryTypeSelect(method: 'shipping' | 'pickup') {
     if (!checkout) return;
@@ -3709,7 +3998,7 @@ function CheckoutContent() {
         phone: customerInfo.phone,
       });
       setCheckout(updated);
-      setStep('payment');
+      setStep(await loadCustomFieldsOrSkip(updated.id));
     } catch (err) {
       const message = err instanceof Error ? err.message : t('failedToSelectPickup');
       setError(message);
@@ -3771,9 +4060,15 @@ function CheckoutContent() {
     );
   }
 
+  const customFieldsStep =
+    customFields.length > 0
+      ? [{ key: 'custom-fields' as CheckoutStep, label: t('stepCustomFields') }]
+      : [];
+
   const steps: { key: CheckoutStep; label: string }[] = isAllDigital
     ? [
         { key: 'address', label: t('stepContactInfo') },
+        ...customFieldsStep,
         { key: 'payment', label: t('stepPayment') },
       ]
     : pickupLocations.length > 0
@@ -3781,17 +4076,20 @@ function CheckoutContent() {
         ? [
             { key: 'method', label: t('stepMethod') },
             { key: 'pickup', label: t('stepPickup') },
+            ...customFieldsStep,
             { key: 'payment', label: t('stepPayment') },
           ]
         : [
             { key: 'method', label: t('stepMethod') },
             { key: 'address', label: t('stepAddress') },
             { key: 'shipping', label: t('stepShipping') },
+            ...customFieldsStep,
             { key: 'payment', label: t('stepPayment') },
           ]
       : [
           { key: 'address', label: t('stepAddress') },
           { key: 'shipping', label: t('stepShipping') },
+          ...customFieldsStep,
           { key: 'payment', label: t('stepPayment') },
         ];
 
@@ -3990,19 +4288,54 @@ function CheckoutContent() {
             </div>
           )}
 
+          {/* Custom Fields (optional, between shipping/pickup and payment) */}
+          {step === 'custom-fields' && checkout && (
+            <div>
+              <div className="mb-4 flex items-center justify-between">
+                <h2 className="text-foreground text-lg font-semibold">{t('customFieldsTitle')}</h2>
+                <button
+                  type="button"
+                  onClick={() => setStep(deliveryType === 'pickup' ? 'pickup' : 'shipping')}
+                  className="text-primary text-sm hover:underline"
+                >
+                  {deliveryType === 'pickup' ? t('changePickup') : t('changeShipping')}
+                </button>
+              </div>
+              <CustomFieldsStep
+                fields={customFields}
+                values={customFieldValues}
+                onChange={(key, value) =>
+                  setCustomFieldValues((prev) => ({ ...prev, [key]: value }))
+                }
+                onApply={handleCustomFieldsApply}
+                loading={customFieldsLoading}
+              />
+            </div>
+          )}
+
           {/* Payment */}
           {step === 'payment' && checkout && (
             <div>
               <div className="mb-4 flex items-center justify-between">
                 <h2 className="text-foreground text-lg font-semibold">{t('payment')}</h2>
-                {!isAllDigital && (
+                {customFields.length > 0 ? (
                   <button
                     type="button"
-                    onClick={() => setStep(deliveryType === 'pickup' ? 'pickup' : 'shipping')}
+                    onClick={() => setStep('custom-fields')}
                     className="text-primary text-sm hover:underline"
                   >
-                    {deliveryType === 'pickup' ? t('changePickup') : t('changeShipping')}
+                    {t('changeOptions')}
                   </button>
+                ) : (
+                  !isAllDigital && (
+                    <button
+                      type="button"
+                      onClick={() => setStep(deliveryType === 'pickup' ? 'pickup' : 'shipping')}
+                      className="text-primary text-sm hover:underline"
+                    >
+                      {deliveryType === 'pickup' ? t('changePickup') : t('changeShipping')}
+                    </button>
+                  )
                 )}
               </div>
 
@@ -4189,6 +4522,20 @@ function CheckoutContent() {
                   taxBreakdown={checkout.taxBreakdown}
                 />
 
+                {/* Custom field surcharges (one line per applied surcharge) */}
+                {checkout.appliedSurcharges && checkout.appliedSurcharges.length > 0 && (
+                  <>
+                    {checkout.appliedSurcharges.map((s) => (
+                      <div key={s.key} className="flex items-center justify-between">
+                        <span className="text-muted-foreground">{s.name}</span>
+                        <span className="text-foreground">
+                          {formatPrice(Number(s.amount), { currency }) as string}
+                        </span>
+                      </div>
+                    ))}
+                  </>
+                )}
+
                 <div className="border-border mt-2 border-t pt-2">
                   <div className="flex items-center justify-between">
                     <span className="text-foreground font-semibold">{tc('total')}</span>
@@ -11244,8 +11591,11 @@ async function fetchStoreInfo(connectionId, baseUrl = KNOWN_API_URLS.production)
   } catch {
     throw new Error(`Invalid response from ${baseUrl}`);
   }
+  const storeName = json.storeName || json.name || "My Store";
+  const displayName = json.channelName || storeName;
   return {
-    name: json.name || json.storeName || "My Store",
+    name: displayName,
+    storeName,
     currency: json.currency || "USD",
     language: json.language || "en",
     ...json.i18n ? { i18n: json.i18n } : {}
@@ -11286,7 +11636,7 @@ function getCandidateApiUrls() {
 
 // src/tools/get-store-info.ts
 var GET_STORE_INFO_NAME = "get-store-info";
-var GET_STORE_INFO_DESCRIPTION = "Fetch live store information from the Brainerce API using a connection ID. Returns the store name, currency, and language. Use this to personalize the store being built.";
+var GET_STORE_INFO_DESCRIPTION = "Fetch live store information from the Brainerce API using a connection ID. Returns the channel display name (what the user sees in their dashboard), parent store name, currency, and language. Use this to personalize the store being built \u2014 prefer the channel name for user-facing text since a single Brainerce store can have multiple sales channels.";
 var GET_STORE_INFO_SCHEMA = {
   connectionId: z5.string().describe("Vibe-coded connection ID (starts with vc_)")
 };
@@ -11299,7 +11649,10 @@ async function handleGetStoreInfo(args) {
           type: "text",
           text: JSON.stringify(
             {
+              // `name` is the channel display name (from the dashboard sales-channel card);
+              // falls back to storeName when a channel doesn't have its own name.
               name: resolved.info.name,
+              storeName: resolved.info.storeName,
               currency: resolved.info.currency,
               language: resolved.info.language,
               connectionId: args.connectionId,
@@ -11393,7 +11746,8 @@ var GET_STORE_CAPABILITIES_SCHEMA = {
 };
 function formatCapabilities(caps) {
   const lines = [];
-  lines.push(`## Store: ${caps.store.name} (${caps.store.currency})`);
+  const channelSuffix = caps.store.channelName && caps.store.channelName !== caps.store.name ? ` \u2014 Channel: "${caps.store.channelName}"` : "";
+  lines.push(`## Store: ${caps.store.name} (${caps.store.currency})${channelSuffix}`);
   lines.push(`Language: ${caps.store.language}`);
   if (caps.store.i18n?.enabled) {
     lines.push(
@@ -11426,6 +11780,9 @@ function formatCapabilities(caps) {
     caps.features.hasDownloadableProducts ? "\u2705 Downloadable products available" : "\u274C No downloadable products"
   );
   lines.push(caps.features.hasCoupons ? "\u2705 Coupons available" : "\u274C No coupons");
+  lines.push(
+    caps.features.hasCheckoutCustomFields ? "\u2705 Checkout custom fields configured (surcharges may apply)" : "\u274C No checkout custom fields"
+  );
   lines.push("");
   lines.push("## Connection Settings");
   lines.push(
@@ -11471,6 +11828,11 @@ function formatCapabilities(caps) {
   if (caps.features.hasCoupons) {
     suggestions.push('Add a coupon input to the cart. Use get-code-example("coupon-input").');
   }
+  if (caps.features.hasCheckoutCustomFields) {
+    suggestions.push(
+      `Checkout custom fields are configured. Build a step between shipping/pickup and payment using getCheckoutCustomFields() + setCheckoutCustomFields(). Render checkout.appliedSurcharges in the order summary so customers see what they're paying for. Use get-code-example("checkout-custom-fields").`
+    );
+  }
   if (caps.connection.requireEmailVerification) {
     suggestions.push(
       'Email verification is required \u2014 ALWAYS build the verify-email page. Use get-code-example("verify-email").'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainerce/mcp-server",
-  "version": "2.7.0",
+  "version": "2.9.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"