@brainerce/mcp-server 3.12.2 → 3.12.4

package/dist/bin/http.js

@@ -3,7 +3,6 @@
 
 // src/bin/http.ts
 var import_node_http = require("http");
-var import_node_crypto = require("crypto");
 var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 var import_sse = require("@modelcontextprotocol/sdk/server/sse.js");
 
@@ -220,7 +219,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 }\`
@@ -242,6 +241,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(); }, []);
 
@@ -276,6 +277,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);
 
@@ -2126,6 +2128,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
@@ -2151,7 +2154,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\``;
 }
@@ -2199,7 +2201,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)
@@ -2529,6 +2546,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');
@@ -3324,11 +3343,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)
 
@@ -3336,19 +3362,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) {
@@ -3873,6 +3947,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[];
@@ -3941,6 +4016,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 {
@@ -4884,6 +4960,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)
@@ -4893,6 +4981,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 {
@@ -4900,16 +5010,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
@@ -4919,6 +5032,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,
@@ -6417,6 +6534,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(
@@ -6464,7 +6589,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) {
@@ -7602,69 +7727,29 @@ var SSE_KEEPALIVE_MS = 1e4;
 var SESSION_MAX_AGE_MS = 4 * 60 * 60 * 1e3;
 var NODE_ENV = process.env.NODE_ENV || "development";
 var IS_DEV = NODE_ENV === "development";
-var AUTH_TOKENS = (process.env.MCP_AUTH_TOKENS || "").split(",").map((t) => t.trim()).filter((t) => t.length > 0).map((t) => Buffer.from(t, "utf8"));
-if (AUTH_TOKENS.length === 0 && !IS_DEV) {
-  console.error(
-    "FATAL: MCP_AUTH_TOKENS is not set. The MCP HTTP server must run with at least one Bearer token in non-development environments.\nMint a token (e.g., `mcp_<random>`) via the dashboard and add it (comma-separated) to MCP_AUTH_TOKENS."
-  );
-  process.exit(1);
-}
-if (AUTH_TOKENS.length === 0 && IS_DEV) {
-  console.warn(
-    "WARN: MCP_AUTH_TOKENS is not set. Running in development mode \u2014 any non-empty Bearer token will be accepted."
+if (process.env.MCP_AUTH_TOKENS) {
+  console.info(
+    "NOTE: MCP_AUTH_TOKENS is set but ignored \u2014 the docs MCP server is public by design. The env var can be removed."
   );
 }
 var ALLOWED_ORIGINS = (process.env.MCP_ALLOWED_ORIGINS || "").split(",").map((o) => o.trim()).filter((o) => o.length > 0);
 var LOCALHOST_ORIGIN_RE = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/;
 var RATE_LIMIT_WINDOW_MS = parseInt(process.env.MCP_RATE_LIMIT_WINDOW_MS || "60000", 10);
 var RATE_LIMIT_MAX = parseInt(process.env.MCP_RATE_LIMIT_MAX || "60", 10);
+var RATE_BUCKETS_MAX = parseInt(process.env.MCP_RATE_BUCKETS_MAX || "20000", 10);
 var rateBuckets = /* @__PURE__ */ new Map();
+var MAX_SSE_SESSIONS = parseInt(process.env.MCP_MAX_SSE_SESSIONS || "500", 10);
+var MAX_SSE_SESSIONS_PER_IP = parseInt(process.env.MCP_MAX_SSE_SESSIONS_PER_IP || "5", 10);
 var MAX_BODY_BYTES = parseInt(process.env.MCP_MAX_BODY_BYTES || String(100 * 1024), 10);
-function safeEqual(a, b) {
-  if (a.length !== b.length) {
-    const max = Math.max(a.length, b.length);
-    const ax = Buffer.alloc(max);
-    const bx = Buffer.alloc(max);
-    a.copy(ax);
-    b.copy(bx);
-    (0, import_node_crypto.timingSafeEqual)(ax, bx);
-    return false;
-  }
-  return (0, import_node_crypto.timingSafeEqual)(a, b);
-}
-function authenticate(req, res) {
-  const header = req.headers["authorization"];
-  if (typeof header !== "string" || !header.toLowerCase().startsWith("bearer ")) {
-    writeJson(res, 401, {
-      error: "Missing or malformed Authorization header. Expected: Bearer <token>."
-    });
-    return false;
-  }
-  const presented = header.slice(7).trim();
-  if (presented.length === 0) {
-    writeJson(res, 401, { error: "Empty Bearer token." });
-    return false;
-  }
-  if (AUTH_TOKENS.length === 0 && IS_DEV) {
-    return true;
-  }
-  const presentedBuf = Buffer.from(presented, "utf8");
-  let matched = false;
-  for (const token of AUTH_TOKENS) {
-    if (safeEqual(presentedBuf, token)) {
-      matched = true;
-    }
-  }
-  if (!matched) {
-    writeJson(res, 401, { error: "Invalid Bearer token." });
-    return false;
-  }
-  return true;
-}
 function clientIp(req) {
+  const cf = req.headers["cf-connecting-ip"];
+  if (typeof cf === "string" && cf.length > 0) {
+    return cf.trim();
+  }
   const xff = req.headers["x-forwarded-for"];
   if (typeof xff === "string" && xff.length > 0) {
-    return xff.split(",")[0].trim();
+    const parts = xff.split(",");
+    return parts[parts.length - 1].trim();
   }
   return req.socket.remoteAddress || "unknown";
 }
@@ -7673,6 +7758,9 @@ function rateLimit(req, res) {
   const now = Date.now();
   const bucket = rateBuckets.get(ip);
   if (!bucket || bucket.resetAt <= now) {
+    if (rateBuckets.size >= RATE_BUCKETS_MAX) {
+      rateBuckets.clear();
+    }
     rateBuckets.set(ip, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS });
     return true;
   }
@@ -7796,7 +7884,6 @@ async function main() {
       return;
     }
     if (!rateLimit(req, res)) return;
-    if (!authenticate(req, res)) return;
     if (req.url === "/mcp") {
       try {
         const server = createServer();
@@ -7815,6 +7902,19 @@ async function main() {
       return;
     }
     if (req.url === "/sse" && req.method === "GET") {
+      if (sseSessions.size >= MAX_SSE_SESSIONS) {
+        writeJson(res, 503, { error: "Server at capacity. Try again later." });
+        return;
+      }
+      const ip = clientIp(req);
+      let ownedByIp = 0;
+      for (const session of sseSessions.values()) {
+        if (session.ip === ip) ownedByIp += 1;
+      }
+      if (ownedByIp >= MAX_SSE_SESSIONS_PER_IP) {
+        writeJson(res, 429, { error: "Too many concurrent sessions from this address." });
+        return;
+      }
       try {
         res.setHeader("X-Accel-Buffering", "no");
         res.setHeader("Cache-Control", "no-cache, no-transform");
@@ -7836,7 +7936,8 @@ async function main() {
           transport,
           res,
           keepAliveTimer,
-          createdAt: Date.now()
+          createdAt: Date.now(),
+          ip
         });
         transport.onclose = () => {
           cleanupSession(sessionId);
@@ -7906,20 +8007,23 @@ ${signal} received \u2014 shutting down gracefully...`);
   }
   process.on("SIGTERM", () => shutdown("SIGTERM"));
   process.on("SIGINT", () => shutdown("SIGINT"));
+  httpServer.headersTimeout = 15e3;
+  httpServer.requestTimeout = 6e4;
   httpServer.listen(PORT, () => {
     console.info(`Brainerce MCP server running on http://localhost:${PORT}`);
     console.info(`  Streamable HTTP: http://localhost:${PORT}/mcp`);
     console.info(`  Legacy SSE:      http://localhost:${PORT}/sse`);
     console.info(`  Health check:    http://localhost:${PORT}/health`);
-    console.info(
-      `  Auth tokens:     ${AUTH_TOKENS.length} configured${AUTH_TOKENS.length === 0 && IS_DEV ? " (dev: any non-empty Bearer accepted)" : ""}`
-    );
+    console.info("  Auth:            none (public docs server)");
     console.info(
       `  CORS:            ${ALLOWED_ORIGINS.length} allow-listed origin(s)${IS_DEV ? " + localhost (dev)" : ""}`
     );
     console.info(
       `  Rate limit:      ${RATE_LIMIT_MAX} req / ${Math.round(RATE_LIMIT_WINDOW_MS / 1e3)}s per IP`
     );
+    console.info(
+      `  SSE sessions:    max ${MAX_SSE_SESSIONS} total, ${MAX_SSE_SESSIONS_PER_IP} per IP`
+    );
     console.info(`  Max body:        ${MAX_BODY_BYTES} bytes`);
   });
 }