@brainerce/mcp-server 3.12.0 → 3.12.2

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
 
@@ -1771,7 +1805,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)
@@ -3261,6 +3295,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";
@@ -3287,6 +3400,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getInventorySection();
     case "discounts":
       return getDiscountsSection();
+    case "loyalty":
+      return getLoyaltySection();
     case "recommendations":
       return getRecommendationsSection();
     case "reviews":
@@ -3320,6 +3435,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",
@@ -3450,6 +3568,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "order-confirmation",
     "inventory",
     "discounts",
+    "loyalty",
     "recommendations",
     "reviews",
     "product-customization-fields",
@@ -3602,11 +3721,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 +3826,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 +3926,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 +4163,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;
 
@@ -4775,6 +4906,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,
@@ -4787,7 +4955,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") {
@@ -4821,6 +4990,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.'
@@ -5083,7 +5253,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:
@@ -6259,6 +6437,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(
@@ -6304,6 +6485,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").`