@brainerce/mcp-server 3.12.3 → 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');
@@ -3367,6 +3386,43 @@ await client.applyCoupon(cartId, couponCode); // applies via the normal coupon e
 \`\`\`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) {
@@ -3891,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[];
@@ -3959,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 {
@@ -4927,6 +4985,24 @@ interface LoyaltyStatus {
   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 {
@@ -4957,6 +5033,9 @@ interface RedeemRewardResult {
 // 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,
@@ -6455,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(
@@ -7640,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";
 }
@@ -7711,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;
   }
@@ -7834,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();
@@ -7853,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");
@@ -7874,7 +7936,8 @@ async function main() {
           transport,
           res,
           keepAliveTimer,
-          createdAt: Date.now()
+          createdAt: Date.now(),
+          ip
         });
         transport.onclose = () => {
           cleanupSession(sessionId);
@@ -7944,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`);
   });
 }

package/dist/bin/stdio.js

@@ -217,7 +217,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 }\`
@@ -239,6 +239,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(); }, []);
 
@@ -273,6 +275,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);
 
@@ -2123,6 +2126,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
@@ -2148,7 +2152,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\``;
 }
@@ -2196,7 +2199,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)
@@ -2526,6 +2544,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');
@@ -3364,6 +3384,43 @@ await client.applyCoupon(cartId, couponCode); // applies via the normal coupon e
 \`\`\`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) {
@@ -3888,6 +3945,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[];
@@ -3956,6 +4014,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 {
@@ -4924,6 +4983,24 @@ interface LoyaltyStatus {
   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 {
@@ -4954,6 +5031,9 @@ interface RedeemRewardResult {
 // 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,
@@ -6452,6 +6532,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(

package/dist/index.d.mts

@@ -77,6 +77,10 @@ interface StoreCapabilities {
         hasContent?: boolean;
         /** True when the store has an ACTIVE loyalty program. Storefront-mode only. */
         hasLoyaltyProgram?: boolean;
+        /** True when the loyalty program has the referral program enabled. Storefront-mode only. */
+        hasReferralProgram?: boolean;
+        /** True when the loyalty program has birthday gifts enabled. */
+        hasBirthdayRewards?: boolean;
     };
 }
 declare function fetchStoreCapabilities(connectionId: string, baseUrl?: string): Promise<StoreCapabilities>;

package/dist/index.d.ts

@@ -77,6 +77,10 @@ interface StoreCapabilities {
         hasContent?: boolean;
         /** True when the store has an ACTIVE loyalty program. Storefront-mode only. */
         hasLoyaltyProgram?: boolean;
+        /** True when the loyalty program has the referral program enabled. Storefront-mode only. */
+        hasReferralProgram?: boolean;
+        /** True when the loyalty program has birthday gifts enabled. */
+        hasBirthdayRewards?: boolean;
     };
 }
 declare function fetchStoreCapabilities(connectionId: string, baseUrl?: string): Promise<StoreCapabilities>;

package/dist/index.js

@@ -243,7 +243,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 }\`
@@ -265,6 +265,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(); }, []);
 
@@ -299,6 +301,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);
 
@@ -2149,6 +2152,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
@@ -2174,7 +2178,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\``;
 }
@@ -2222,7 +2225,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)
@@ -2552,6 +2570,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');
@@ -3390,6 +3410,43 @@ await client.applyCoupon(cartId, couponCode); // applies via the normal coupon e
 \`\`\`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) {
@@ -3914,6 +3971,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[];
@@ -3982,6 +4040,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 {
@@ -4950,6 +5009,24 @@ interface LoyaltyStatus {
   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 {
@@ -4980,6 +5057,9 @@ interface RedeemRewardResult {
 // 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,
@@ -6478,6 +6558,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(

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');
@@ -3358,6 +3378,43 @@ await client.applyCoupon(cartId, couponCode); // applies via the normal coupon e
 \`\`\`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) {
@@ -3882,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[];
@@ -3950,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 {
@@ -4918,6 +4977,24 @@ interface LoyaltyStatus {
   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 {
@@ -4948,6 +5025,9 @@ interface RedeemRewardResult {
 // 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,
@@ -6446,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(

package/package.json

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