@brainerce/mcp-server 3.12.0 → 3.12.2

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
 
@@ -1739,7 +1773,7 @@ The merchant can hide a group entirely for one variant by setting \`maxOverride:
 
 ### Restaurant features (advanced)
 
-Allergens (informational chips), scheduled availability windows, nested combos (depth \u2264 3 via \`nestedByModifierId\`), and downsell modifiers (negative \`priceDelta\`) are all built on the same data model. See INTEGRATION-OPTIONAL.md "Restaurant / build-your-own products" for those flows.`;
+Scheduled availability windows, nested combos (depth \u2264 3 via \`nestedByModifierId\`), and downsell modifiers (negative \`priceDelta\`) are all built on the same data model. See INTEGRATION-OPTIONAL.md "Restaurant / build-your-own products" for those flows.`;
 }
 function getProductReviewsSection() {
   return `## Product Reviews (\u2605 ratings + JSON-LD for SEO)
@@ -3229,6 +3263,85 @@ 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 getLoyaltySection() {
+  return `# Loyalty & Rewards
+
+Logged-in customers earn points on paid orders and redeem them for a one-time discount coupon at checkout.
+
+> **Storefront mode only.** These methods work only with \`new BrainerceClient({ storeId })\` + a logged-in \`customerToken\`. There is **no vibe-coded route** \u2014 in \`salesChannelId: 'vc_*'\` mode they throw. Skip loyalty if you connect vibe-coded.
+
+Points are earned automatically by the platform when an order is paid \u2014 there is no earn call from the storefront. Your job is to **show** balance/rewards and to **redeem**.
+
+## Status
+
+\`\`\`typescript
+// requires client.setCustomerToken(auth.token)
+const status = await client.getLoyaltyStatus();
+// { enrolled, pointsBalance, lifetimeEarned, program: { pointsName, currencyRatio, status } | null }
+\`\`\`
+
+- \`program === null\` \u2192 the store has no loyalty program; hide the loyalty UI.
+- \`program.status !== 'ACTIVE'\` \u2192 program paused/draft; hide the loyalty UI.
+
+## Enroll (only if auto-enroll is off)
+
+\`\`\`typescript
+await client.enrollInLoyalty(); // same status shape; no-op if already enrolled
+\`\`\`
+
+## Rewards & redemption
+
+\`\`\`typescript
+const rewards = await client.getAvailableRewards();
+// [{ id, name, description, pointsCost, discountValue, minOrderAmount, maxUsesPerUser, isActive }]
+
+const { couponCode, discountValue, pointsBalance } = await client.redeemLoyaltyReward(rewardId);
+await client.applyCoupon(cartId, couponCode); // applies via the normal coupon engine
+\`\`\`
+
+- \`redeemLoyaltyReward\` mints a one-time fixed-amount coupon (\`usageLimit: 1\`). Apply it with the normal \`applyCoupon\` flow.
+- Throws if the customer has insufficient points. If minting fails, points are refunded automatically.
+- Disable a reward's redeem button when \`pointsBalance < reward.pointsCost\`.
+`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -3255,6 +3368,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getInventorySection();
     case "discounts":
       return getDiscountsSection();
+    case "loyalty":
+      return getLoyaltySection();
     case "recommendations":
       return getRecommendationsSection();
     case "reviews":
@@ -3288,6 +3403,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",
@@ -3418,6 +3536,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "order-confirmation",
     "inventory",
     "discounts",
+    "loyalty",
     "recommendations",
     "reviews",
     "product-customization-fields",
@@ -3570,11 +3689,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 +3794,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 +3894,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 +4131,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;
 
@@ -4743,6 +4874,43 @@ interface TaxEstimateResponse {
 // Non-binding by design: the authoritative tax runs at checkout against the
 // full shipping address. The country comes from your edge runtime
 // (CF-IPCountry / request.geo.country / etc.), NOT the request IP.`;
+var LOYALTY_TYPES = `// ---- Loyalty & Rewards (storefront mode only) ----
+interface LoyaltyStatus {
+  enrolled: boolean;
+  pointsBalance: number;      // redeemable points (pending earns excluded)
+  lifetimeEarned: number;
+  program: {
+    pointsName: string;       // e.g. "points", "coins"
+    currencyRatio: number;    // points needed to redeem 1 unit of store currency
+    status: 'DRAFT' | 'ACTIVE' | 'PAUSED';
+  } | null;                   // null when the store has no loyalty program
+}
+
+interface LoyaltyReward {
+  id: string;
+  name: string;
+  description: string | null;
+  pointsCost: number;
+  discountValue: number;      // fixed amount off, store currency
+  minOrderAmount: number | null;
+  maxUsesPerUser: number;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface RedeemRewardResult {
+  couponCode: string;         // one-time coupon to apply at checkout
+  discountValue: number;
+  pointsSpent: number;
+  pointsBalance: number;      // remaining balance after redemption
+}
+
+// client.getLoyaltyStatus(): Promise<LoyaltyStatus>
+// client.enrollInLoyalty(): Promise<LoyaltyStatus>
+// client.getAvailableRewards(): Promise<LoyaltyReward[]>
+// client.redeemLoyaltyReward(rewardId: string): Promise<RedeemRewardResult>
+`;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
   cart: CART_TYPES,
@@ -4755,7 +4923,8 @@ var TYPES_BY_DOMAIN = {
   reviews: REVIEWS_TYPES,
   "modifier-groups": MODIFIER_GROUPS_TYPES,
   content: CONTENT_TYPES,
-  regions: REGIONS_TYPES
+  regions: REGIONS_TYPES,
+  loyalty: LOYALTY_TYPES
 };
 function getTypesByDomain(domain) {
   if (domain === "all") {
@@ -4789,6 +4958,7 @@ var GET_TYPE_DEFINITIONS_SCHEMA = {
     "modifier-groups",
     "content",
     "regions",
+    "loyalty",
     "all"
   ]).describe(
     'The domain of types to retrieve. Use "helpers" for helper function signatures and common types like StoreInfo, PaginatedResponse. Use "content" for FAQ / Footer / Header / Announcement / RichText / Page. Use "regions" for Region / TaxClass admin types.'
@@ -5051,7 +5221,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:
@@ -6227,6 +6405,9 @@ function formatCapabilities(caps) {
   lines.push(
     caps.features.hasCheckoutCustomFields ? "\u2705 Checkout custom fields configured (surcharges may apply)" : "\u274C No checkout custom fields"
   );
+  lines.push(
+    caps.features.hasLoyaltyProgram ? "\u2705 Loyalty program active (points & rewards \u2014 storefront-mode only)" : "\u274C No loyalty program"
+  );
   lines.push("");
   lines.push("## Connection Settings");
   lines.push(
@@ -6272,6 +6453,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.hasLoyaltyProgram) {
+    suggestions.push(
+      "A loyalty program is active. In a storefront-mode client (new BrainerceClient({ storeId })), show the logged-in customer their points balance and redeemable rewards, and let them redeem for a coupon at checkout. Use getLoyaltyStatus(), getAvailableRewards(), and redeemLoyaltyReward(id). Note: loyalty is NOT available in vibe-coded mode."
+    );
+  }
   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").`

package/package.json

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