@brainerce/mcp-server 3.12.2 → 3.12.4

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');
@@ -3321,11 +3341,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)
 
@@ -3333,19 +3360,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) {
@@ -3870,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[];
@@ -3938,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 {
@@ -4881,6 +4958,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)
@@ -4890,6 +4979,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 {
@@ -4897,16 +5008,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
@@ -4916,6 +5030,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,
@@ -6414,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(
@@ -6461,7 +6587,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/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');
@@ -3347,11 +3367,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)
 
@@ -3359,19 +3386,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) {
@@ -3896,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[];
@@ -3964,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 {
@@ -4907,6 +4984,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)
@@ -4916,6 +5005,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 {
@@ -4923,16 +5034,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
@@ -4942,6 +5056,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,
@@ -6440,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(
@@ -6487,7 +6613,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) {