@brainerce/mcp-server 3.12.0 → 3.12.1

package/dist/bin/http.js

@@ -721,17 +721,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**:
 
@@ -1119,11 +1121,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.
@@ -1206,7 +1219,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
 
@@ -3238,6 +3272,44 @@ 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";
@@ -3297,6 +3369,9 @@ function getSectionByTopic(topic, connectionId, currency) {
     case "analytics":
     case "traffic-analytics":
       return getStorefrontAnalyticsSection(cid);
+    case "shipping-app":
+    case "shippo":
+      return getShippingAppSection();
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -3579,11 +3654,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;
@@ -3677,6 +3759,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;
 }
@@ -3776,6 +3859,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 {
@@ -4012,7 +4096,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;
 
@@ -5060,7 +5147,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:

package/dist/bin/stdio.js

@@ -718,17 +718,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**:
 
@@ -1116,11 +1118,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.
@@ -1203,7 +1216,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
 
@@ -3235,6 +3269,44 @@ 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";
@@ -3294,6 +3366,9 @@ function getSectionByTopic(topic, connectionId, currency) {
     case "analytics":
     case "traffic-analytics":
       return getStorefrontAnalyticsSection(cid);
+    case "shipping-app":
+    case "shippo":
+      return getShippingAppSection();
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -3576,11 +3651,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;
@@ -3674,6 +3756,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;
 }
@@ -3773,6 +3856,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 {
@@ -4009,7 +4093,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;
 
@@ -5057,7 +5144,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:

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
 
@@ -3261,6 +3295,44 @@ 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";
@@ -3320,6 +3392,9 @@ function getSectionByTopic(topic, connectionId, currency) {
     case "analytics":
     case "traffic-analytics":
       return getStorefrontAnalyticsSection(cid);
+    case "shipping-app":
+    case "shippo":
+      return getShippingAppSection();
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -3602,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;
@@ -3700,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;
 }
@@ -3799,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 {
@@ -4035,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;
 
@@ -5083,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:

package/dist/index.mjs

@@ -712,17 +712,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**:
 
@@ -1110,11 +1112,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.
@@ -1197,7 +1210,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
 
@@ -3229,6 +3263,44 @@ 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";
@@ -3288,6 +3360,9 @@ function getSectionByTopic(topic, connectionId, currency) {
     case "analytics":
     case "traffic-analytics":
       return getStorefrontAnalyticsSection(cid);
+    case "shipping-app":
+    case "shippo":
+      return getShippingAppSection();
     case "all":
       return [
         "# Brainerce SDK \u2014 full topic dump",
@@ -3570,11 +3645,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;
@@ -3668,6 +3750,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;
 }
@@ -3767,6 +3850,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 {
@@ -4003,7 +4087,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;
 
@@ -5051,7 +5138,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:

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@brainerce/mcp-server",
-  "version": "3.12.0",
+  "version": "3.12.1",
+  "packageManager": "pnpm@9.0.0",
   "description": "Framework-agnostic domain knowledge API for Brainerce. Provides SDK docs, types, business flows, critical rules, and store capabilities to AI tools like Lovable, Cursor, Bolt, v0, and Claude Code. Does NOT provide framework-specific boilerplate — clients build in whatever framework fits.",
   "bin": {
     "brainerce-mcp": "dist/bin/stdio.js"