@brainerce/mcp-server 3.12.2 → 3.12.4

package/dist/index.mjs

@@ -211,7 +211,7 @@ async function startCheckout() {
 2. Customer optionally applies coupon on cart page \u2192 \`applyCoupon(cartId, code)\`
 3. Detect payment providers \u2192 \`getPaymentProviders()\`
 4. Start checkout session (\`startGuestCheckout()\` or \`createCheckout()\`)
-5. Set shipping address (includes required email) \u2192 \`setShippingAddress()\`
+5. Set shipping address (includes required email) \u2192 \`setShippingAddress()\` \u2014 also pass \`notes\` from the **"Order notes" textarea that every checkout page should include by default** (optional field, max 2000 chars; lands on the order for the merchant)
 6. Select shipping method \u2192 \`selectShippingMethod()\`
 6b. (Optional) Set checkout custom fields \u2192 \`setCheckoutCustomFields()\` \u2014 surcharges auto-calculated
 7. Create payment intent \u2192 \`createPaymentIntent()\` \u2192 returns \`{ clientSecret, provider }\`
@@ -233,6 +233,8 @@ function CheckoutPage() {
   const [checkout, setCheckout] = useState<Checkout | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState(true);
+  // Optional "Order notes" textarea \u2014 render it on the checkout page by default
+  const [orderNotes, setOrderNotes] = useState('');
 
   useEffect(() => { startCheckout(); }, []);
 
@@ -267,6 +269,7 @@ function CheckoutPage() {
         postalCode: cart.shippingAddress.postalCode,
         country: cart.shippingAddress.country,
         phone: cart.shippingAddress.phone,
+        notes: orderNotes || undefined,  // from the "Order notes" textarea \u2014 include one by default
       });
       setCheckout(checkoutData);
 
@@ -2117,6 +2120,7 @@ A useful order card includes ALL of the following when the data is present. Each
 | **Tracking** | \`order.trackingNumber\`, \`order.trackingUrl\`, \`order.carrier\`, \`order.shippedAt\`, \`order.deliveredAt\` | Link out to \`trackingUrl\` when set. |
 | **Payment** | \`order.paymentMethod\`, \`order.financialStatus\` | Badge \`financialStatus\` (paid / pending / refunded / partially_refunded). |
 | Downloads | \`order.hasDownloads\` \u2192 \`client.getOrderDownloads(id)\` | Separate call; returns \`OrderDownloadLink[]\`. |
+| **Order note** | \`order.notes\` | The shopper's own checkout note, echoed back read-only. Render when present ("Your order note"). |
 | Financial summary | \`order.subtotal\`, \`order.appliedDiscounts\`, \`order.couponCode\` + \`couponDiscount\`, \`order.shippingAmount\`, \`order.taxAmount\`, \`order.totalAmount\` | Breakdown rows + final total. In VAT-inclusive mode \`taxAmount\` is 0 \u2014 read \`order.taxBreakdown.totalTax\` and label "Tax (incl.)". |
 
 #### Rendering \`order.items[i].customizations\` by type
@@ -2142,7 +2146,6 @@ The storefront scaffolded by \`create-brainerce-store\` already implements this.
 These fields are NOT returned to buyers by \`/customers/me/orders\`. If you see them in older examples, ignore them \u2014 they are for merchant/admin views only.
 
 - \`order.accountId\`, \`order.storeId\`, \`order.customerId\` (already known on the request)
-- \`order.notes\` (internal merchant notes)
 - \`order.customFieldValues\` (order-level checkout fields \u2014 merchant concept; buyers see \`items[i].customizations\`)
 - \`order.appliedSurcharges\`, \`order.surchargeAmount\`, \`order.appliedRuleIds\`, \`order.downloadMeta\`, \`order.pickupLocationData\``;
 }
@@ -2190,7 +2193,22 @@ function OrderConfirmation() {
 
 **Common mistake:** Don't just check URL params and show success immediately!
 You MUST call \`waitForOrder(checkoutId)\` to verify the order was created.
-Also call \`handlePaymentSuccess(checkoutId)\` to clear purchased items from the cart.`;
+Also call \`handlePaymentSuccess(checkoutId)\` to clear purchased items from the cart.
+
+### Optional: render full order details on the confirmation page
+
+Want a richer thank-you page (items, shipping address, totals, the shopper's
+order note)? After \`waitForOrder\` succeeds, fetch the full buyer-safe order \u2014
+works for guests too (possession of the checkout id is the credential):
+
+\`\`\`typescript
+const order = await client.getOrderByCheckout(checkoutId);
+// order.items, order.shippingAddress, order.notes, order.subtotal,
+// order.shippingAmount, order.taxAmount / order.taxBreakdown, order.totalAmount
+\`\`\`
+
+Render whatever subset fits your design \u2014 same field shapes as the buyer
+order-history view (see "Buyer order view" section).`;
 }
 function getI18nSection() {
   return `## Internationalization (i18n)
@@ -2520,6 +2538,8 @@ dashboard or the admin SDK).
 
 \`\`\`typescript
 // Publish to a specific vibe-coded site (admin mode):
+await admin.publishProductToSalesChannel('prod_id', 'vc_conn_id');
+await admin.publishCouponToSalesChannel('coupon_id', 'vc_conn_id');
 await admin.publishCategoryToVibeCodedSite('cat_id', 'conn_id');
 await admin.publishTagToVibeCodedSite('tag_id', 'conn_id');
 await admin.publishBrandToVibeCodedSite('brand_id', 'conn_id');
@@ -3315,11 +3335,18 @@ Points are earned automatically by the platform when an order is paid \u2014 the
 \`\`\`typescript
 // requires client.setCustomerToken(auth.token)
 const status = await client.getLoyaltyStatus();
-// { enrolled, pointsBalance, lifetimeEarned, program: { pointsName, currencyRatio, status } | null }
+// {
+//   enrolled, pointsBalance, lifetimeEarned,
+//   program: { pointsName, currencyRatio, status } | null,
+//   tier: { id, name, level, pointsMultiplier } | null,
+//   nextTier: { id, name, level, pointsMultiplier, qualificationType, qualificationThreshold } | null,
+//   progressToNextTier, pointsToNextTier,
+// }
 \`\`\`
 
 - \`program === null\` \u2192 the store has no loyalty program; hide the loyalty UI.
 - \`program.status !== 'ACTIVE'\` \u2192 program paused/draft; hide the loyalty UI.
+- \`tier\`/\`nextTier\` are \`null\` when the store hasn't configured tiers, or the customer hasn't qualified for one yet.
 
 ## Enroll (only if auto-enroll is off)
 
@@ -3327,19 +3354,67 @@ const status = await client.getLoyaltyStatus();
 await client.enrollInLoyalty(); // same status shape; no-op if already enrolled
 \`\`\`
 
+May grant a one-time "joined the program" bonus if configured \u2014 distinct from any account-signup bonus (granted automatically on registration, not by this call).
+
 ## Rewards & redemption
 
 \`\`\`typescript
 const rewards = await client.getAvailableRewards();
-// [{ id, name, description, pointsCost, discountValue, minOrderAmount, maxUsesPerUser, isActive }]
+// [{ id, name, description, pointsCost, type, discountValue, minOrderAmount, maxUsesPerUser, minTierLevel, isActive }]
+// Already filtered to rewards the customer's current tier qualifies for.
 
-const { couponCode, discountValue, pointsBalance } = await client.redeemLoyaltyReward(rewardId);
+const { couponCode, discountType, 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.
+- \`reward.type\` is \`'FIXED_DISCOUNT'\` (currency amount) or \`'PERCENT_DISCOUNT'\` (0-100 percent) \u2014 the redeem result's \`discountType\` matches.
+- \`redeemLoyaltyReward\` mints a one-time coupon (\`usageLimit: 1\`). Apply it with the normal \`applyCoupon\` flow.
+- Throws if the customer has insufficient points, or their tier is below \`reward.minTierLevel\`. If minting fails, points are refunded automatically.
 - Disable a reward's redeem button when \`pointsBalance < reward.pointsCost\`.
+
+## Social share (optional)
+
+\`\`\`typescript
+await client.reportSocialShare('instagram'); // platform optional, self-reported, once per customer
+\`\`\`
+
+## Referrals (when the store enables them)
+
+\`getLoyaltyStatus()\` also returns \`referralCode\` (the member's share code, null when referrals are disabled or the customer isn't enrolled) and \`referralWelcomeCoupon\` (the still-unused welcome coupon this customer got for signing up via a referral link).
+
+\`\`\`typescript
+// 1. Referrer: build a share link around their code.
+const { referralCode } = await client.getLoyaltyStatus();
+const shareUrl = \`https://your-store.com/?ref=\${referralCode}\`;
+
+// 2. Landing page: PUBLIC lookup \u2014 no customerToken needed.
+const info = await client.getReferralInfo(refFromQuery);
+// { valid, referrerFirstName, reward: { name, type, value, minOrderAmount } | null }
+if (info.valid) {
+  // "Jane sent you a gift: 10% off your first order"
+}
+
+// 3. Registration: pass the code \u2014 invalid codes never fail registration
+// (validated asynchronously server-side with fraud checks).
+await client.registerCustomer({ email, password, referralCode: refFromQuery });
+
+// 4. Show the referee their welcome coupon after login:
+const { referralWelcomeCoupon } = await client.getLoyaltyStatus();
+if (referralWelcomeCoupon) {
+  await client.applyCoupon(cartId, referralWelcomeCoupon.code);
+}
+\`\`\`
+
+The referrer earns a points bonus after the referee's first qualifying order (held through the program's pending window, like order points). Everything server-side \u2014 no storefront earn calls.
+
+## Birthday gifts (when the store enables them)
+
+No dedicated calls \u2014 collect \`birthMonth\`/\`birthDay\` (1-12 / 1-31, **no year**, must be sent together) via \`updateMyProfile()\` and the platform emails a one-time gift coupon ahead of the customer's birthday.
+
+\`\`\`typescript
+await client.updateMyProfile({ birthMonth: 4, birthDay: 17 });
+\`\`\`
 `;
 }
 function getSectionByTopic(topic, connectionId, currency) {
@@ -3864,6 +3939,7 @@ interface Checkout {
   appliedSurcharges?: Array<{ key: string; name: string; value: unknown; amount: string }> | null;
   customFieldValues?: Record<string, unknown> | null;
   couponCode?: string | null;
+  notes?: string | null;  // Order-level shopper note \u2014 copied onto the order at completion
   lineItems: CheckoutLineItem[];  // Use THIS for order summary, NOT cart.items!
   itemCount: number;
   availableShippingRates?: ShippingRate[];
@@ -3932,6 +4008,7 @@ interface SetShippingAddressDto {
   postalCode: string;
   country: string;
   phone?: string;
+  notes?: string;     // Order notes textarea \u2014 include one on checkout by default! Max 2000 chars, lands on the order
 }
 
 interface CreateCheckoutDto {
@@ -4875,6 +4952,18 @@ interface TaxEstimateResponse {
 // 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 LoyaltyTierSummary {
+  id: string;
+  name: string;
+  level: number;              // ordering; higher = better tier
+  pointsMultiplier: number;
+}
+
+interface LoyaltyNextTierSummary extends LoyaltyTierSummary {
+  qualificationType: 'SPEND' | 'POINTS';
+  qualificationThreshold: number;
+}
+
 interface LoyaltyStatus {
   enrolled: boolean;
   pointsBalance: number;      // redeemable points (pending earns excluded)
@@ -4884,6 +4973,28 @@ interface LoyaltyStatus {
     currencyRatio: number;    // points needed to redeem 1 unit of store currency
     status: 'DRAFT' | 'ACTIVE' | 'PAUSED';
   } | null;                   // null when the store has no loyalty program
+  tier: LoyaltyTierSummary | null;         // null if untiered / no tiers configured
+  nextTier: LoyaltyNextTierSummary | null; // null if at the top tier already
+  progressToNextTier: number; // 0..1
+  pointsToNextTier: number | null;
+  referralCode?: string | null;            // member's share code; null when referrals disabled / not enrolled
+  referralWelcomeCoupon?: {                // unused welcome coupon from signing up via a referral link
+    code: string;
+    type: string;                          // 'PERCENTAGE' | 'FIXED_AMOUNT'
+    value: number;
+  } | null;
+}
+
+// Public referral-link lookup \u2014 NO customerToken needed (safe pre-signup)
+interface ReferralInfo {
+  valid: boolean;                          // false for unknown/disabled codes
+  referrerFirstName: string | null;        // for "Jane sent you a gift" copy \u2014 no other PII
+  reward: {
+    name: string;
+    type: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
+    value: number;
+    minOrderAmount: number | null;
+  } | null;
 }
 
 interface LoyaltyReward {
@@ -4891,16 +5002,19 @@ interface LoyaltyReward {
   name: string;
   description: string | null;
   pointsCost: number;
-  discountValue: number;      // fixed amount off, store currency
+  type: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
+  discountValue: number;      // currency amount (FIXED_DISCOUNT) or 0-100 percent (PERCENT_DISCOUNT)
   minOrderAmount: number | null;
   maxUsesPerUser: number;
   isActive: boolean;
+  minTierLevel: number | null; // minimum tier level required, or null for no restriction
   createdAt: string;
   updatedAt: string;
 }
 
 interface RedeemRewardResult {
   couponCode: string;         // one-time coupon to apply at checkout
+  discountType: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
   discountValue: number;
   pointsSpent: number;
   pointsBalance: number;      // remaining balance after redemption
@@ -4910,6 +5024,10 @@ interface RedeemRewardResult {
 // client.enrollInLoyalty(): Promise<LoyaltyStatus>
 // client.getAvailableRewards(): Promise<LoyaltyReward[]>
 // client.redeemLoyaltyReward(rewardId: string): Promise<RedeemRewardResult>
+// client.reportSocialShare(platform?: string): Promise<{ awarded: boolean; points: number }>
+// client.getReferralInfo(code: string): Promise<ReferralInfo>   // PUBLIC \u2014 no customerToken
+// Referral signup: client.registerCustomer({ ..., referralCode })
+// Birthday gift data: client.updateMyProfile({ birthMonth, birthDay })  // 1-12 / 1-31, no year, both together
 `;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
@@ -6408,6 +6526,14 @@ function formatCapabilities(caps) {
   lines.push(
     caps.features.hasLoyaltyProgram ? "\u2705 Loyalty program active (points & rewards \u2014 storefront-mode only)" : "\u274C No loyalty program"
   );
+  if (caps.features.hasLoyaltyProgram) {
+    lines.push(
+      caps.features.hasReferralProgram ? "\u2705 Referral program enabled (share codes + welcome reward \u2014 storefront-mode only)" : "\u274C Referral program not enabled"
+    );
+    lines.push(
+      caps.features.hasBirthdayRewards ? "\u2705 Birthday gifts enabled (set birthMonth/birthDay via updateMyProfile)" : "\u274C Birthday gifts not enabled"
+    );
+  }
   lines.push("");
   lines.push("## Connection Settings");
   lines.push(
@@ -6455,7 +6581,7 @@ function formatCapabilities(caps) {
   }
   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."
+      "A loyalty program is active. In a storefront-mode client (new BrainerceClient({ storeId })), show the logged-in customer their points balance, tier progress, and redeemable rewards, and let them redeem for a coupon at checkout. Use getLoyaltyStatus() (includes tier/nextTier/progressToNextTier), getAvailableRewards(), redeemLoyaltyReward(id), and optionally reportSocialShare(). Note: loyalty is NOT available in vibe-coded mode."
     );
   }
   if (caps.features.hasCheckoutCustomFields) {

package/package.json

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