@brainerce/mcp-server 3.11.1 → 3.12.1

package/dist/index.js

@@ -744,17 +744,19 @@ function getPaymentProvidersSection() {
   return `## Payment Provider Detection (DO THIS FIRST on checkout page!)
 
 \`\`\`typescript
-const { hasPayments, providers } = await client.getPaymentProviders();
+const { hasPayments, providers, defaultProvider } = await client.getPaymentProviders();
 if (!hasPayments) {
   // Show error: "Payment is not configured for this store"
   return;
 }
-const stripeProvider = providers.find(p => p.provider === 'stripe');
-const growProvider = providers.find(p => p.provider === 'grow');
-const paypalProvider = providers.find(p => p.provider === 'paypal');
+// Primary vs additive (Shopify-parity): render wallets as express buttons ABOVE the card form.
+const expressMethods = providers.filter(p => p.isAdditive);           // e.g. PayPal (WALLET)
+const primary = defaultProvider && !defaultProvider.isAdditive ? defaultProvider : undefined;
 \`\`\`
 
-Each provider has: \`id\`, \`provider\` (flexible string \u2014 \`'stripe'\`, \`'grow'\`, \`'paypal'\`, \`'cardcom'\`, \`'morning'\`, \`'takbull'\`, \`'sandbox'\`, and future providers), \`name\`, \`publicKey\`, \`stripeAccountId\` (Stripe only), \`supportedMethods\`, \`testMode\`, \`isDefault\`.
+Each provider has: \`id\`, \`provider\` (flexible string \u2014 \`'stripe'\`, \`'grow'\`, \`'paypal'\`, \`'cardcom'\`, \`'morning'\`, \`'takbull'\`, \`'sandbox'\`, and future providers), \`name\`, \`publicKey\`, \`stripeAccountId\` (Stripe only), \`supportedMethods\`, \`testMode\`, \`isDefault\`, plus the taxonomy fields \`methodType\` (\`'CREDIT_CARD'\` = the single primary card processor that settles the order; \`'WALLET'\`/other = additive), \`isAdditive\`, and \`presentation\` (\`'card_form'\` | \`'express_button'\` | \u2026).
+
+**Primary vs. additive:** there is one primary card processor (the \`defaultProvider\`, \`isAdditive: false\`) plus any additive methods (\`isAdditive: true\`, e.g. PayPal). Render additive methods as accelerated-checkout **express buttons above** the card form \u2014 they sit alongside the primary, never replace it. Create the intent with the tapped provider's \`id\`. (Exception: a wallet-only store has no card processor, so its wallet becomes the \`defaultProvider\` and stands alone.)
 
 The payment intent returned from \`createPaymentIntent()\` includes a \`clientSdk\` object whose \`renderType\` tells you exactly how to render \u2014 **branch on THAT, not on the provider name**:
 
@@ -1142,11 +1144,22 @@ client-side overlay needed. Swatch colors are language-agnostic.
 function ProductDescription({ product }: { product: Product }) {
   const content = getDescriptionContent(product);
   if (!content) return null;
-  if ('html' in content) return <div dangerouslySetInnerHTML={{ __html: content.html }} />;
+  // Descriptions are merchant HTML and may contain <video> + host-locked
+  // YouTube/Vimeo <iframe> embeds. NEVER render unsanitized \u2014 sanitize and
+  // allowlist video/source + iframe (restricted to youtube/vimeo hosts).
+  if ('html' in content) {
+    return <div dangerouslySetInnerHTML={{ __html: sanitizeProductHtml(content.html) }} />;
+  }
   return <p>{content.text}</p>;
 }
 \`\`\`
 
+**Sanitize descriptions.** \`sanitizeProductHtml\` is the host-locked sanitizer the
+\`create-brainerce-store\` scaffold ships at \`src/lib/sanitize-html.ts\`. If you roll
+your own, allow \`video\`/\`source\` and \`iframe\` **restricted** to \`www.youtube.com\`,
+\`www.youtube-nocookie.com\`, \`player.vimeo.com\` (never arbitrary iframes), and add
+those hosts to your CSP \`frame-src\` or embeds render blank.
+
 ### Metafields (Custom Product Fields) \u2014 display on product detail!
 
 **IMPORTANT: Render metafield values based on \`mf.type\`!** Don't just display \`mf.value\` as text for all types.
@@ -1229,7 +1242,28 @@ const { url } = await client.uploadCustomizationFile(file);
 // Then use the URL in metadata: metadata: { logo: url }
 \`\`\`
 
-**Customization field properties:** \`key\`, \`name\` (display label), \`type\`, \`required\`, \`minLength\`, \`maxLength\`, \`minValue\`, \`maxValue\`, \`enumValues\`, \`defaultValue\`, \`position\`
+**Customization field properties:** \`key\`, \`name\` (display label), \`type\`, \`required\`, \`minLength\`, \`maxLength\`, \`minValue\`, \`maxValue\`, \`enumValues\` (array of \`{label, value, swatchColor?, swatchImageUrl?}\`), \`defaultValue\`, \`position\`
+
+**SELECT / MULTI_SELECT \u2014 use \`option.value\` to submit, \`option.label\` to display:**
+
+\`\`\`typescript
+for (const option of field.enumValues ?? []) {
+  // option.value \u2192 what to submit in metadata
+  // option.label \u2192 what to show the customer
+  // option.swatchColor \u2192 optional hex color for color swatches
+}
+\`\`\`
+
+**Display customizations in cart / checkout \u2014 no extra API call needed:**
+
+CartItem and CheckoutLineItem both include a \`customizations\` object alongside \`metadata\`. Use \`customizations\` for display \u2014 it contains resolved labels, not raw keys.
+
+\`\`\`typescript
+// Works for CartItem, CheckoutLineItem, and OrderItem \u2014 same shape
+const lines = Object.values(item.customizations ?? {})
+  .map(c => \`\${c.label}: \${Array.isArray(c.value) ? c.value.join(', ') : c.value}\`);
+// e.g. ["Frame color: Gold", "Add-ons: Gift wrap"]
+\`\`\`
 
 ### Downloadable / Digital Products
 
@@ -2560,8 +2594,9 @@ await admin.createTaxRate({ name: 'VAT (Food)', rate: 0, country: 'GB', taxClass
 await admin.mergeTaxClasses(food.id, standardClassId);
 \`\`\`
 
-Storefront (public, no apiKey \u2014 \`storeId\` mode): \`getStoreTaxClasses()\` lists
-the store's classes (storefront-safe fields only) for a transparency badge.
+Storefront (public, no apiKey \u2014 \`storeId\` mode OR vibe-coded mode \`vc_*\`, gated
+on the \`products:read\` scope every connection already has): \`getStoreTaxClasses()\`
+lists the store's classes (storefront-safe fields only) for a transparency badge.
 
 For a buyer-facing tax preview on PDP / PLP / cart, \`estimateTax({ country,
 subtotal })\` returns the tax portion at the Standard rate for the buyer's
@@ -2583,8 +2618,10 @@ A region binds countries \u2192 currency + tax-display mode + enabled payment
 providers. Manage them via the SDK (scopes \`regions:read\` / \`regions:write\`).
 \`detectRegion\` is a pure client-side helper to map a buyer's country to a
 region; pass the resolved \`regionId\` to \`createCheckout\` to associate the
-checkout with a region (recorded for reporting + provider scoping; currency
-follows the cart until FX price conversion lands).
+checkout with a region (recorded for reporting + provider scoping). FX-at-checkout:
+presentment-enabled regions (Stripe today) charge in the region currency and the
+checkout response carries a \`presentment\` overlay with the charged amounts;
+otherwise the checkout is charged in the store base currency.
 
 \`\`\`typescript
 const eu = await admin.createRegion({
@@ -2597,9 +2634,12 @@ const { data: regions } = await admin.getRegions();
 const region = admin.detectRegion('DE', regions); // \u2192 eu, else default, else null
 \`\`\`
 
-Storefront (public, no apiKey \u2014 \`storeId\` mode): \`getStoreRegions()\` lists
-active regions, \`getStoreRegion(id)\` returns one region + its payment providers.
-Pair with \`detectRegion\` to pick the buyer's region for currency display.
+Storefront (public, no apiKey \u2014 \`storeId\` mode OR vibe-coded mode \`vc_*\`, gated
+on the \`products:read\` scope every connection already has): \`getStoreRegions()\`
+lists active regions, \`getStoreRegion(id)\` returns one region + its payment
+providers. \`getAutoRegion(country)\` and \`estimateTax({ country, subtotal })\` work
+in both modes too. Pair with \`detectRegion\` to pick the buyer's region for
+currency display.
 
 \`\`\`typescript
 const store = new BrainerceClient({ storeId: 'store_123' });
@@ -3223,6 +3263,76 @@ Rules:
   count updates when the bot adds items.
 `;
 }
+function getStorefrontAnalyticsSection(connectionId) {
+  return `## Storefront Traffic Analytics (visits, countries, sources)
+
+Brainerce can track cookieless storefront traffic \u2014 how many people visit the
+store, from which countries, and from which traffic sources \u2014 and surface it in
+the merchant dashboard alongside sales (so the merchant gets a REAL conversion
+rate: visits \u2192 orders).
+
+Add ONE line to the storefront's root layout (\`<head>\` or end of \`<body>\`):
+
+\`\`\`html
+<script defer src="https://api.brainerce.com/t.js" data-channel="${connectionId}"></script>
+\`\`\`
+
+That's it \u2014 the pixel auto-sends a pageview beacon on load and on SPA route
+changes. Stores scaffolded with \`create-brainerce-store\` already include it.
+
+Privacy: the pixel is cookieless and stores NO personal data \u2014 no cookie, no
+cross-site/cross-day tracking, and the visitor IP is resolved to a country
+server-side then discarded. No cookie-consent banner is required for it under
+GDPR/ePrivacy.
+
+CSP: if the storefront sets a Content-Security-Policy, allow the script + beacon:
+- \`script-src\` \u2026 \`https://api.brainerce.com\`
+- \`connect-src\` \u2026 \`https://api.brainerce.com\`
+
+The merchant can toggle tracking per sales channel in the dashboard. The data
+shows up under Dashboard \u2192 Analytics (visits over time, by country, by source,
+by device) and can also be asked of the AI assistant ("how many visits did I get
+this month and from where?").
+`;
+}
+function getShippingAppSection() {
+  return `## App Store Shipping (Shippo)
+
+Merchants install Shippo from the Brainerce App Store. After connecting their own Shippo account
+(OAuth), live carrier rates appear automatically at checkout alongside any manually configured
+zone rates. **Billing goes directly to the merchant's Shippo account \u2014 Brainerce never charges.**
+
+### Checkout \u2014 live carrier rates
+
+No SDK changes needed. Once Shippo is installed and configured, the existing
+\`getShippingRates()\` call returns both manual zone rates and live Shippo quotes:
+
+\`\`\`typescript
+const { rates } = await client.setShippingAddress(checkoutId, { ... });
+// rates may include:
+// { id: 'shippo:rate_8f123abc', name: 'USPS Priority Mail', price: '8.50', currency: 'USD', source: 'carrier' }
+\`\`\`
+
+Rates prefixed \`shippo:\` are live Shippo quotes. Pass the full \`id\` as \`shippingRateId\`
+when calling \`selectShippingMethod()\`.
+
+### Admin \u2014 purchase a shipping label
+
+After the order is placed, the merchant purchases a label by passing the Shippo rate object_id:
+
+\`\`\`typescript
+const label = await admin.createShippingLabel(orderId, {
+  shippoRateObjectId: 'rate_8f123456789abcdef',
+});
+console.log(label.labelUrl);       // PDF ready to print
+console.log(label.trackingNumber); // auto-populated on the order
+\`\`\`
+
+The \`trackingNumber\` is stored on the \`Order\` and returned in \`getMyOrders()\`
+so customers can track their shipment automatically.
+
+**SDK mode:** \`createShippingLabel()\` requires \`apiKey\` (admin mode only).`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -3279,6 +3389,12 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getBlogSection();
     case "storefront-bot":
       return getStorefrontBotSection(cid);
+    case "analytics":
+    case "traffic-analytics":
+      return getStorefrontAnalyticsSection(cid);
+    case "shipping-app":
+    case "shippo":
+      return getShippingAppSection();
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -3347,6 +3463,10 @@ function getSectionByTopic(topic, connectionId, currency) {
         "",
         "---",
         "",
+        getStorefrontAnalyticsSection(cid),
+        "",
+        "---",
+        "",
         getProductCustomizationFieldsSection(),
         "",
         "---",
@@ -3416,6 +3536,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "inquiries",
     "content",
     "storefront-bot",
+    "analytics",
     "all"
   ]).describe("The SDK documentation topic to retrieve"),
   salesChannelId: import_zod.z.string().optional().describe("Sales channel ID (starts with vc_). Used to personalize setup code."),
@@ -3453,7 +3574,7 @@ interface Product {
   priceMin?: string | null;  // Lowest variant price (VARIABLE products) \u2014 same as basePrice for VARIABLE, kept for back-compat and JSON-LD range display.
   priceMax?: string | null;  // Highest variant price (VARIABLE products). Use with priceMin for "\u20AA49 \u2013 \u20AA199" range.
   priceVaries?: boolean;     // true when variant prices differ \u2014 show "\u20AA49 \u2013 \u20AA199" range.
-  // FX DISPLAY overlay (PRD \xA723). Set only when getProducts({ regionId }) was called AND region.currency !== store.currency. basePrice/salePrice above stay in store currency \u2014 these are additive, display-only. The buyer is still charged in store currency at checkout; payment provider handles customer-side FX.
+  // FX DISPLAY overlay (PRD \xA723). Set only when getProducts({ regionId }) was called AND region.currency !== store.currency. basePrice/salePrice above stay in store currency \u2014 these are additive. For presentment-enabled regions (Stripe) the displayPrice uses the same buffered rate the checkout charges (browsed == checkout); for display-only regions it is mid-market and the buyer is charged in store currency at checkout (payment provider handles customer-side FX).
   displayPrice?: string;        // basePrice \xD7 daily FX rate, in displayCurrency.
   displaySalePrice?: string;    // salePrice \xD7 rate (if salePrice present).
   displayPriceMin?: string;     // priceMin \xD7 rate (VARIABLE products).
@@ -3556,11 +3677,18 @@ interface ProductCustomizationField {
   maxLength?: number | null;
   minValue?: number | null;     // NUMBER bounds
   maxValue?: number | null;
-  enumValues?: string[];        // REQUIRED for SELECT / MULTI_SELECT
+  enumValues?: CustomizationFieldOption[];  // REQUIRED for SELECT / MULTI_SELECT
   defaultValue?: string | null;
   position: number;             // Render order
 }
 
+interface CustomizationFieldOption {
+  label: string;          // Display label (e.g., "Rose Gold")
+  value: string;          // Value stored in CartItem.metadata
+  swatchColor?: string | null;      // Optional hex color (e.g., "#B76E79")
+  swatchImageUrl?: string | null;   // Optional swatch image URL
+}
+
 interface ProductQueryParams {
   page?: number;
   limit?: number;
@@ -3654,6 +3782,7 @@ interface CartItem {
     image?: ProductImage | string | null;
   } | null;
   metadata?: Record<string, unknown> | null;  // Buyer-submitted customization values, keyed by ProductCustomizationField.key
+  customizations?: Record<string, { label: string; value: string | string[]; type: string }>;  // Resolved labels \u2014 use this to display "Color: Silver" without extra getProduct() call
   createdAt: string;
   updatedAt: string;
 }
@@ -3707,7 +3836,7 @@ interface Checkout {
   status: CheckoutStatus;
   email?: string | null;
   customerId?: string | null;
-  regionId?: string | null;  // multi-region: recorded for reporting + provider scoping (currency follows the cart until FX lands)
+  regionId?: string | null;  // multi-region: recorded for reporting + provider scoping. FX-at-checkout: presentment-enabled regions (Stripe) charge in the region currency \u2014 see the presentment field below; else charged in store base currency
   shippingAddress?: CheckoutAddress | null;
   billingAddress?: CheckoutAddress | null;
   shippingRateId?: string | null;
@@ -3727,6 +3856,18 @@ interface Checkout {
   itemCount: number;
   availableShippingRates?: ShippingRate[];
   reservation?: ReservationInfo;
+  // FX-at-checkout: present ONLY when the region charges in its own currency (presentment-enabled \u2014 Stripe today). The amounts the buyer is actually CHARGED, in presentment.currency; presentment.total equals the payment intent amount. Render these (not total/currency above) when present. Absent = charged in store base currency. The fields above stay the base reference.
+  presentment?: {
+    currency: string;        // ISO-4217 charged currency, e.g. "EUR"
+    subtotal: string;
+    discountAmount: string;
+    shippingAmount: string;
+    taxAmount: string;
+    surchargeAmount: string;
+    total: string;           // equals the charged amount, to the cent
+    fxChargingRate: string;  // base\u2192presentment rate (buffer included)
+    fxBufferPercent: string | null;
+  };
   createdAt: string;
   updatedAt: string;
 }
@@ -3741,6 +3882,7 @@ interface CheckoutLineItem {
   product: { id: string; name: string; sku: string; images?: ProductImage[]; };
   variant?: { id: string; name?: string | null; sku?: string | null; image?: ProductImage | string | null; } | null;
   metadata?: Record<string, unknown> | null;  // Copied from CartItem.metadata \u2014 buyer customization values
+  customizations?: Record<string, { label: string; value: string | string[]; type: string }>;  // Resolved labels \u2014 same shape as OrderItem.customizations
 }
 
 interface CheckoutAddress {
@@ -3977,7 +4119,10 @@ interface PaymentProviderConfig {
   stripeAccountId?: string;   // Stripe Connect only
   supportedMethods: string[];
   testMode: boolean;
-  isDefault: boolean;
+  isDefault: boolean;         // only a primary (CREDIT_CARD) is ever the default
+  methodType: 'CREDIT_CARD' | 'WALLET' | 'OFFSITE' | 'LOCAL' | 'REDEEMABLE';
+  presentation: 'card_form' | 'express_button' | 'redirect' | 'local_option' | 'redeemable_field';
+  isAdditive: boolean;        // wallet/alt method shown ALONGSIDE the primary (e.g. PayPal)
 }
 type PaymentProvider = PaymentProviderConfig;
 
@@ -4104,10 +4249,22 @@ interface CartAppliedDiscount {
 }
 
 // Recommendation types
+interface RecommendationVariant {
+  id: string; name?: string; price?: string; salePrice?: string;
+  attributes?: Record<string, string>; image?: ProductImage | string; inventory?: InventoryInfo;
+}
 interface ProductRecommendation {
-  id: string; name: string; slug: string; basePrice: string; salePrice?: string;
+  id: string; name: string; slug: string;
+  // For a VARIABLE target, basePrice is the pinned variant's price (when
+  // targetVariantId is set) or the "from {min variant}" range \u2014 never 0.
+  basePrice: string; salePrice?: string;
   images: ProductImage[]; type: 'SIMPLE' | 'VARIABLE'; inventory?: InventoryInfo;
   relationType: string;
+  // Variant context (VARIABLE targets):
+  targetVariantId?: string | null;        // merchant-pinned variant, or null
+  requiresVariantSelection?: boolean;      // true \u2192 customer must pick from variants
+  pinnedVariant?: { id: string; name?: string; attributes?: Record<string, string> } | null;
+  variants?: RecommendationVariant[];      // present when requiresVariantSelection
 }
 interface ProductRecommendationsResponse {
   crossSells: ProductRecommendation[];
@@ -4141,6 +4298,12 @@ interface CartBundleOfferOfferedProduct {
   salePrice: string | null;
   images: Array<{ url: string }>;
   type: string;
+  // Variant context (VARIABLE offered products):
+  variantId?: string | null;               // merchant-pinned variant for this slot
+  requiresVariantSelection?: boolean;       // true \u2192 customer must pick from variants
+  pinnedVariant?: { id: string; name?: string; attributes?: Record<string, string> } | null;
+  variants?: RecommendationVariant[];       // present when requiresVariantSelection
+  // originalPrice = pinned/cheapest variant price for VARIABLE (not a 0 parent base).
   originalPrice: string;
   discountedPrice: string;
 }
@@ -4624,10 +4787,12 @@ interface UpdateRegionDto extends Partial<CreateRegionDto> { isActive?: boolean
 // client.detectRegion(country, regions): Region | null  \u2014 pure, no network.
 //   \u2192 region whose countries includes the code, else the default region, else null.
 // Pass the resolved regionId to createCheckout to associate the checkout with a
-// region (recorded for reporting + provider scoping; currency follows the cart
-// until FX price conversion lands).
+// region (recorded for reporting + provider scoping). FX-at-checkout:
+// presentment-enabled regions (Stripe) charge in the region currency and the
+// response carries a presentment overlay; else charged in store base currency.
 //
-// Storefront (public, no apiKey \u2014 storeId mode):
+// Storefront (public, no apiKey \u2014 storeId mode OR vibe-coded mode, salesChannelId 'vc_*';
+// the vc routes are gated on products:read, which every connection already has):
 interface PublicRegion {
   id: string; name: string; slug: string; currency: string;
   countries: string[]; taxInclusive: boolean; isDefault: boolean;
@@ -4679,7 +4844,8 @@ interface AssignTaxClassDto { productIds?: string[]; variantIds?: string[]; cate
 //                deleteTaxClass(id), setDefaultTaxClass(id), assignTaxClass(id, dto),
 //                mergeTaxClasses(id, targetId)
 //
-// SDK methods (storefront, public \u2014 storeId mode, no apiKey):
+// SDK methods (storefront, public \u2014 storeId mode OR vibe-coded mode 'vc_*', no apiKey;
+// the vc routes are gated on products:read, which every connection already has):
 //   getStoreRegions(), getStoreRegion(id), getAutoRegion(country)
 //   getStoreTaxClasses(), estimateTax({ country?, subtotal })
 //
@@ -5004,7 +5170,15 @@ const checkout = await client.getCheckout(checkoutId);
 import { client } from './brainerce';
 
 const { providers, hasPayments, defaultProvider } = await client.getPaymentProviders();
-// each provider: { id, provider, name, publicKey, supportedMethods, testMode, isDefault, clientSdk? }
+// each provider: { id, provider, name, publicKey, supportedMethods, testMode,
+//                  isDefault, methodType, presentation, isAdditive, clientSdk? }
+//
+// methodType splits providers into ONE primary card processor (CREDIT_CARD, the
+// defaultProvider that settles the order) and additive methods (isAdditive:true,
+// e.g. PayPal as a WALLET). Render additive methods as express buttons ABOVE the
+// card form \u2014 they sit alongside the primary, never replace it. Call
+// createPaymentIntent({ providerId }) with the tapped provider's id. (Wallet-only
+// store: with no card processor, the wallet becomes defaultProvider and stands alone.)
 //
 // After createPaymentIntent, the response carries a clientSdk.renderType that
 // tells your UI how to render the payment step. The 5 possible values: