@brainerce/mcp-server 2.7.0 → 2.8.0

package/dist/bin/stdio.js

@@ -409,6 +409,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!)
 
@@ -1258,6 +1486,10 @@ ${getCheckoutFlowSection(currency)}
 
 ---
 
+${getCheckoutCustomFieldsSection()}
+
+---
+
 ${getPaymentProvidersSection()}
 
 ---
@@ -1316,6 +1548,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":
@@ -1344,7 +1578,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`;
   }
 }
 
@@ -1357,6 +1591,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "products",
     "cart",
     "checkout",
+    "checkout-custom-fields",
     "payment",
     "auth",
     "order-confirmation",
@@ -3378,6 +3613,7 @@ import type {
   ShippingDestinations,
   PickupLocation,
   CheckoutBumpsResponse,
+  CheckoutCustomFieldDefinition,
 } from 'brainerce';
 import { formatPrice } from 'brainerce';
 import { getClient } from '@/lib/brainerce';
@@ -3387,6 +3623,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';
@@ -3395,7 +3632,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();
@@ -3428,6 +3665,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';
@@ -3479,6 +3719,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
@@ -3649,6 +3906,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;
@@ -3661,7 +3933,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);
@@ -3670,6 +3942,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;
@@ -3715,7 +4004,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);
@@ -3777,9 +4066,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
@@ -3787,17 +4082,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') },
         ];
 
@@ -3996,19 +4294,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>
 
@@ -4195,6 +4528,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>
@@ -11250,8 +11597,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 } : {}
@@ -11292,7 +11642,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: import_zod5.z.string().describe("Vibe-coded connection ID (starts with vc_)")
 };
@@ -11305,7 +11655,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,
@@ -11399,7 +11752,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(
@@ -11432,6 +11786,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(
@@ -11477,6 +11834,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/dist/index.d.mts

@@ -33,7 +33,14 @@ declare const AVAILABLE_DOMAINS: string[];
 declare const PROJECT_TEMPLATE = "# Next.js Brainerce Store \u2014 Project Structure\n\n```\nmy-store/\n\u251C\u2500\u2500 package.json                    # Dependencies: brainerce, next, react, tailwindcss\n\u251C\u2500\u2500 next.config.js\n\u251C\u2500\u2500 tailwind.config.ts\n\u251C\u2500\u2500 tsconfig.json\n\u251C\u2500\u2500 lib/\n\u2502   \u2514\u2500\u2500 brainerce.ts               # SDK client setup, cart helpers, auth helpers\n\u251C\u2500\u2500 app/\n\u2502   \u251C\u2500\u2500 layout.tsx                  # Root layout with StoreProvider\n\u2502   \u251C\u2500\u2500 page.tsx                    # Home: hero, featured products, categories\n\u2502   \u251C\u2500\u2500 products/\n\u2502   \u2502   \u251C\u2500\u2500 page.tsx               # Product listing with infinite scroll\n\u2502   \u2502   \u2514\u2500\u2500 [slug]/\n\u2502   \u2502       \u2514\u2500\u2500 page.tsx           # Product detail: images, variants, add to cart\n\u2502   \u251C\u2500\u2500 cart/\n\u2502   \u2502   \u2514\u2500\u2500 page.tsx               # Cart: items with checkboxes, coupon, totals\n\u2502   \u251C\u2500\u2500 checkout/\n\u2502   \u2502   \u2514\u2500\u2500 page.tsx               # Checkout: address \u2192 shipping \u2192 payment\n\u2502   \u251C\u2500\u2500 order-confirmation/\n\u2502   \u2502   \u2514\u2500\u2500 page.tsx               # Order confirmation: waitForOrder() + handlePaymentSuccess()\n\u2502   \u251C\u2500\u2500 login/\n\u2502   \u2502   \u2514\u2500\u2500 page.tsx               # Login: email/password + OAuth buttons\n\u2502   \u251C\u2500\u2500 register/\n\u2502   \u2502   \u2514\u2500\u2500 page.tsx               # Register: form + OAuth buttons\n\u2502   \u251C\u2500\u2500 verify-email/\n\u2502   \u2502   \u2514\u2500\u2500 page.tsx               # Email verification: 6-digit code + resend\n\u2502   \u251C\u2500\u2500 auth/\n\u2502   \u2502   \u2514\u2500\u2500 callback/\n\u2502   \u2502       \u2514\u2500\u2500 page.tsx           # OAuth callback: extract token from URL params\n\u2502   \u2514\u2500\u2500 account/\n\u2502       \u2514\u2500\u2500 page.tsx               # Account: profile + order history (protected)\n\u251C\u2500\u2500 components/\n\u2502   \u251C\u2500\u2500 Header.tsx                  # Logo, nav, cart icon, search autocomplete\n\u2502   \u251C\u2500\u2500 ProductCard.tsx             # Product card with image, price, stock badge\n\u2502   \u251C\u2500\u2500 StockBadge.tsx              # \"Only X left!\" low stock indicator\n\u2502   \u251C\u2500\u2500 ReservationCountdown.tsx    # Timer for reserved items\n\u2502   \u251C\u2500\u2500 StripePaymentForm.tsx       # Stripe Elements payment form\n\u2502   \u251C\u2500\u2500 GrowPaymentForm.tsx         # Grow iframe payment form\n\u2502   \u2514\u2500\u2500 PayPalPaymentForm.tsx       # PayPal Buttons payment form\n\u2514\u2500\u2500 public/\n    \u2514\u2500\u2500 placeholder.jpg             # Fallback product image\n```\n\n## Key Dependencies\n\n```json\n{\n  \"dependencies\": {\n    \"brainerce\": \"latest\",\n    \"next\": \"^15\",\n    \"react\": \"^19\",\n    \"react-dom\": \"^19\",\n    \"@stripe/stripe-js\": \"latest\",\n    \"@stripe/react-stripe-js\": \"latest\",\n    \"@paypal/react-paypal-js\": \"latest\"\n  },\n  \"devDependencies\": {\n    \"tailwindcss\": \"^4\",\n    \"typescript\": \"^5\",\n    \"@types/react\": \"latest\",\n    \"@types/node\": \"latest\"\n  }\n}\n```\n\n## File Descriptions\n\n| File | Purpose |\n|------|---------|\n| `lib/brainerce.ts` | SDK client init, cart ID helpers, customer token helpers |\n| `app/page.tsx` | Homepage with hero section and featured products grid |\n| `app/products/page.tsx` | Product listing with infinite scroll (50/page), filters, search |\n| `app/products/[slug]/page.tsx` | Product detail with variant switching, description, metafields |\n| `app/cart/page.tsx` | Cart with checkboxes for partial checkout, coupon input, reservation timer |\n| `app/checkout/page.tsx` | Multi-step: address \u2192 shipping rates \u2192 payment (Stripe/Grow/PayPal) |\n| `app/order-confirmation/page.tsx` | Polls waitForOrder(), shows order number, clears cart |\n| `app/login/page.tsx` | Email/password login + OAuth buttons, handles requiresVerification |\n| `app/register/page.tsx` | Registration form + OAuth, handles requiresVerification |\n| `app/verify-email/page.tsx` | 6-digit verification code input with resend button |\n| `app/auth/callback/page.tsx` | Extracts OAuth token from URL params, stores in localStorage |\n| `app/account/page.tsx` | Protected page: getMyProfile() + getMyOrders() |\n| `components/Header.tsx` | Site header with nav, cart count badge, search autocomplete |\n\n## Content Security Policy (CSP)\n\nPayment SDKs load iframes and scripts from external domains. Add these CSP headers in `next.config.js`:\n\n```js\n// next.config.js\nmodule.exports = {\n  async headers() {\n    return [{\n      source: '/(.*)',\n      headers: [{\n        key: 'Content-Security-Policy',\n        value: [\n          \"default-src 'self'\",\n          \"script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.meshulam.co.il https://meshulam.co.il https://*.meshulam.co.il https://grow.link https://*.grow.link https://*.grow.security https://js.stripe.com https://pay.google.com\",\n          \"style-src 'self' 'unsafe-inline'\",\n          \"img-src 'self' data: blob: https:\",\n          \"font-src 'self' data:\",\n          \"frame-src 'self' https://*.meshulam.co.il https://grow.link https://*.grow.link https://*.grow.security https://*.creditguard.co.il https://js.stripe.com https://hooks.stripe.com https://pay.google.com\",\n          \"connect-src 'self' https://*.meshulam.co.il https://grow.link https://*.grow.link https://*.grow.security https://google.com https://pay.google.com https://*.stripe.com https://*.creditguard.co.il\",\n          \"worker-src 'self' blob:\",\n        ].join('; '),\n      }],\n    }];\n  },\n};\n```\n\n**Required domains by provider:**\n- **Grow**: `*.meshulam.co.il`, `grow.link`, `*.grow.link`, `*.grow.security`, `*.creditguard.co.il`\n- **Stripe**: `js.stripe.com`, `hooks.stripe.com`, `*.stripe.com`\n- **Google Pay**: `pay.google.com`, `google.com`\n";
 
 interface StoreInfo {
+    /**
+     * Display name — prefers the per-connection channel name (what the user
+     * sees in their Brainerce dashboard sales-channel card), falling back to
+     * the parent store name.
+     */
     name: string;
+    /** Parent store name (the account-level store). */
+    storeName: string;
     currency: string;
     language: string;
     i18n?: {
@@ -46,7 +53,10 @@ declare function fetchStoreInfo(connectionId: string, baseUrl?: string): Promise
 
 interface StoreCapabilities {
     store: {
+        /** Parent store name (account-level). */
         name: string;
+        /** Per-connection channel display name (what the user sees in the dashboard). */
+        channelName?: string;
         currency: string;
         language: string;
         i18n?: {
@@ -79,6 +89,7 @@ interface StoreCapabilities {
         hasDiscountRules: boolean;
         hasDownloadableProducts: boolean;
         hasCoupons: boolean;
+        hasCheckoutCustomFields: boolean;
     };
 }
 declare function fetchStoreCapabilities(connectionId: string, baseUrl?: string): Promise<StoreCapabilities>;

package/dist/index.d.ts

@@ -33,7 +33,14 @@ declare const AVAILABLE_DOMAINS: string[];
 declare const PROJECT_TEMPLATE = "# Next.js Brainerce Store \u2014 Project Structure\n\n```\nmy-store/\n\u251C\u2500\u2500 package.json                    # Dependencies: brainerce, next, react, tailwindcss\n\u251C\u2500\u2500 next.config.js\n\u251C\u2500\u2500 tailwind.config.ts\n\u251C\u2500\u2500 tsconfig.json\n\u251C\u2500\u2500 lib/\n\u2502   \u2514\u2500\u2500 brainerce.ts               # SDK client setup, cart helpers, auth helpers\n\u251C\u2500\u2500 app/\n\u2502   \u251C\u2500\u2500 layout.tsx                  # Root layout with StoreProvider\n\u2502   \u251C\u2500\u2500 page.tsx                    # Home: hero, featured products, categories\n\u2502   \u251C\u2500\u2500 products/\n\u2502   \u2502   \u251C\u2500\u2500 page.tsx               # Product listing with infinite scroll\n\u2502   \u2502   \u2514\u2500\u2500 [slug]/\n\u2502   \u2502       \u2514\u2500\u2500 page.tsx           # Product detail: images, variants, add to cart\n\u2502   \u251C\u2500\u2500 cart/\n\u2502   \u2502   \u2514\u2500\u2500 page.tsx               # Cart: items with checkboxes, coupon, totals\n\u2502   \u251C\u2500\u2500 checkout/\n\u2502   \u2502   \u2514\u2500\u2500 page.tsx               # Checkout: address \u2192 shipping \u2192 payment\n\u2502   \u251C\u2500\u2500 order-confirmation/\n\u2502   \u2502   \u2514\u2500\u2500 page.tsx               # Order confirmation: waitForOrder() + handlePaymentSuccess()\n\u2502   \u251C\u2500\u2500 login/\n\u2502   \u2502   \u2514\u2500\u2500 page.tsx               # Login: email/password + OAuth buttons\n\u2502   \u251C\u2500\u2500 register/\n\u2502   \u2502   \u2514\u2500\u2500 page.tsx               # Register: form + OAuth buttons\n\u2502   \u251C\u2500\u2500 verify-email/\n\u2502   \u2502   \u2514\u2500\u2500 page.tsx               # Email verification: 6-digit code + resend\n\u2502   \u251C\u2500\u2500 auth/\n\u2502   \u2502   \u2514\u2500\u2500 callback/\n\u2502   \u2502       \u2514\u2500\u2500 page.tsx           # OAuth callback: extract token from URL params\n\u2502   \u2514\u2500\u2500 account/\n\u2502       \u2514\u2500\u2500 page.tsx               # Account: profile + order history (protected)\n\u251C\u2500\u2500 components/\n\u2502   \u251C\u2500\u2500 Header.tsx                  # Logo, nav, cart icon, search autocomplete\n\u2502   \u251C\u2500\u2500 ProductCard.tsx             # Product card with image, price, stock badge\n\u2502   \u251C\u2500\u2500 StockBadge.tsx              # \"Only X left!\" low stock indicator\n\u2502   \u251C\u2500\u2500 ReservationCountdown.tsx    # Timer for reserved items\n\u2502   \u251C\u2500\u2500 StripePaymentForm.tsx       # Stripe Elements payment form\n\u2502   \u251C\u2500\u2500 GrowPaymentForm.tsx         # Grow iframe payment form\n\u2502   \u2514\u2500\u2500 PayPalPaymentForm.tsx       # PayPal Buttons payment form\n\u2514\u2500\u2500 public/\n    \u2514\u2500\u2500 placeholder.jpg             # Fallback product image\n```\n\n## Key Dependencies\n\n```json\n{\n  \"dependencies\": {\n    \"brainerce\": \"latest\",\n    \"next\": \"^15\",\n    \"react\": \"^19\",\n    \"react-dom\": \"^19\",\n    \"@stripe/stripe-js\": \"latest\",\n    \"@stripe/react-stripe-js\": \"latest\",\n    \"@paypal/react-paypal-js\": \"latest\"\n  },\n  \"devDependencies\": {\n    \"tailwindcss\": \"^4\",\n    \"typescript\": \"^5\",\n    \"@types/react\": \"latest\",\n    \"@types/node\": \"latest\"\n  }\n}\n```\n\n## File Descriptions\n\n| File | Purpose |\n|------|---------|\n| `lib/brainerce.ts` | SDK client init, cart ID helpers, customer token helpers |\n| `app/page.tsx` | Homepage with hero section and featured products grid |\n| `app/products/page.tsx` | Product listing with infinite scroll (50/page), filters, search |\n| `app/products/[slug]/page.tsx` | Product detail with variant switching, description, metafields |\n| `app/cart/page.tsx` | Cart with checkboxes for partial checkout, coupon input, reservation timer |\n| `app/checkout/page.tsx` | Multi-step: address \u2192 shipping rates \u2192 payment (Stripe/Grow/PayPal) |\n| `app/order-confirmation/page.tsx` | Polls waitForOrder(), shows order number, clears cart |\n| `app/login/page.tsx` | Email/password login + OAuth buttons, handles requiresVerification |\n| `app/register/page.tsx` | Registration form + OAuth, handles requiresVerification |\n| `app/verify-email/page.tsx` | 6-digit verification code input with resend button |\n| `app/auth/callback/page.tsx` | Extracts OAuth token from URL params, stores in localStorage |\n| `app/account/page.tsx` | Protected page: getMyProfile() + getMyOrders() |\n| `components/Header.tsx` | Site header with nav, cart count badge, search autocomplete |\n\n## Content Security Policy (CSP)\n\nPayment SDKs load iframes and scripts from external domains. Add these CSP headers in `next.config.js`:\n\n```js\n// next.config.js\nmodule.exports = {\n  async headers() {\n    return [{\n      source: '/(.*)',\n      headers: [{\n        key: 'Content-Security-Policy',\n        value: [\n          \"default-src 'self'\",\n          \"script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.meshulam.co.il https://meshulam.co.il https://*.meshulam.co.il https://grow.link https://*.grow.link https://*.grow.security https://js.stripe.com https://pay.google.com\",\n          \"style-src 'self' 'unsafe-inline'\",\n          \"img-src 'self' data: blob: https:\",\n          \"font-src 'self' data:\",\n          \"frame-src 'self' https://*.meshulam.co.il https://grow.link https://*.grow.link https://*.grow.security https://*.creditguard.co.il https://js.stripe.com https://hooks.stripe.com https://pay.google.com\",\n          \"connect-src 'self' https://*.meshulam.co.il https://grow.link https://*.grow.link https://*.grow.security https://google.com https://pay.google.com https://*.stripe.com https://*.creditguard.co.il\",\n          \"worker-src 'self' blob:\",\n        ].join('; '),\n      }],\n    }];\n  },\n};\n```\n\n**Required domains by provider:**\n- **Grow**: `*.meshulam.co.il`, `grow.link`, `*.grow.link`, `*.grow.security`, `*.creditguard.co.il`\n- **Stripe**: `js.stripe.com`, `hooks.stripe.com`, `*.stripe.com`\n- **Google Pay**: `pay.google.com`, `google.com`\n";
 
 interface StoreInfo {
+    /**
+     * Display name — prefers the per-connection channel name (what the user
+     * sees in their Brainerce dashboard sales-channel card), falling back to
+     * the parent store name.
+     */
     name: string;
+    /** Parent store name (the account-level store). */
+    storeName: string;
     currency: string;
     language: string;
     i18n?: {
@@ -46,7 +53,10 @@ declare function fetchStoreInfo(connectionId: string, baseUrl?: string): Promise
 
 interface StoreCapabilities {
     store: {
+        /** Parent store name (account-level). */
         name: string;
+        /** Per-connection channel display name (what the user sees in the dashboard). */
+        channelName?: string;
         currency: string;
         language: string;
         i18n?: {
@@ -79,6 +89,7 @@ interface StoreCapabilities {
         hasDiscountRules: boolean;
         hasDownloadableProducts: boolean;
         hasCoupons: boolean;
+        hasCheckoutCustomFields: boolean;
     };
 }
 declare function fetchStoreCapabilities(connectionId: string, baseUrl?: string): Promise<StoreCapabilities>;