@brainerce/mcp-server 3.12.1 → 3.12.3

package/dist/bin/http.js

@@ -1782,7 +1782,7 @@ The merchant can hide a group entirely for one variant by setting \`maxOverride:
 
 ### Restaurant features (advanced)
 
-Allergens (informational chips), scheduled availability windows, nested combos (depth \u2264 3 via \`nestedByModifierId\`), and downsell modifiers (negative \`priceDelta\`) are all built on the same data model. See INTEGRATION-OPTIONAL.md "Restaurant / build-your-own products" for those flows.`;
+Scheduled availability windows, nested combos (depth \u2264 3 via \`nestedByModifierId\`), and downsell modifiers (negative \`priceDelta\`) are all built on the same data model. See INTEGRATION-OPTIONAL.md "Restaurant / build-your-own products" for those flows.`;
 }
 function getProductReviewsSection() {
   return `## Product Reviews (\u2605 ratings + JSON-LD for SEO)
@@ -3310,6 +3310,65 @@ so customers can track their shipment automatically.
 
 **SDK mode:** \`createShippingLabel()\` requires \`apiKey\` (admin mode only).`;
 }
+function getLoyaltySection() {
+  return `# Loyalty & Rewards
+
+Logged-in customers earn points on paid orders and redeem them for a one-time discount coupon at checkout.
+
+> **Storefront mode only.** These methods work only with \`new BrainerceClient({ storeId })\` + a logged-in \`customerToken\`. There is **no vibe-coded route** \u2014 in \`salesChannelId: 'vc_*'\` mode they throw. Skip loyalty if you connect vibe-coded.
+
+Points are earned automatically by the platform when an order is paid \u2014 there is no earn call from the storefront. Your job is to **show** balance/rewards and to **redeem**.
+
+## Status
+
+\`\`\`typescript
+// requires client.setCustomerToken(auth.token)
+const status = await client.getLoyaltyStatus();
+// {
+//   enrolled, pointsBalance, lifetimeEarned,
+//   program: { pointsName, currencyRatio, status } | null,
+//   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)
+
+\`\`\`typescript
+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, type, discountValue, minOrderAmount, maxUsesPerUser, minTierLevel, isActive }]
+// Already filtered to rewards the customer's current tier qualifies for.
+
+const { couponCode, discountType, discountValue, pointsBalance } =
+  await client.redeemLoyaltyReward(rewardId);
+await client.applyCoupon(cartId, couponCode); // applies via the normal coupon engine
+\`\`\`
+
+- \`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
+\`\`\`
+`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -3336,6 +3395,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getInventorySection();
     case "discounts":
       return getDiscountsSection();
+    case "loyalty":
+      return getLoyaltySection();
     case "recommendations":
       return getRecommendationsSection();
     case "reviews":
@@ -3502,6 +3563,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "order-confirmation",
     "inventory",
     "discounts",
+    "loyalty",
     "recommendations",
     "reviews",
     "product-customization-fields",
@@ -4839,6 +4901,63 @@ interface TaxEstimateResponse {
 // Non-binding by design: the authoritative tax runs at checkout against the
 // full shipping address. The country comes from your edge runtime
 // (CF-IPCountry / request.geo.country / etc.), NOT the request IP.`;
+var LOYALTY_TYPES = `// ---- Loyalty & Rewards (storefront mode only) ----
+interface 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)
+  lifetimeEarned: number;
+  program: {
+    pointsName: string;       // e.g. "points", "coins"
+    currencyRatio: number;    // points needed to redeem 1 unit of store currency
+    status: 'DRAFT' | 'ACTIVE' | 'PAUSED';
+  } | null;                   // null when the store has no loyalty program
+  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;
+}
+
+interface LoyaltyReward {
+  id: string;
+  name: string;
+  description: string | null;
+  pointsCost: number;
+  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
+}
+
+// client.getLoyaltyStatus(): Promise<LoyaltyStatus>
+// client.enrollInLoyalty(): Promise<LoyaltyStatus>
+// client.getAvailableRewards(): Promise<LoyaltyReward[]>
+// client.redeemLoyaltyReward(rewardId: string): Promise<RedeemRewardResult>
+// client.reportSocialShare(platform?: string): Promise<{ awarded: boolean; points: number }>
+`;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
   cart: CART_TYPES,
@@ -4851,7 +4970,8 @@ var TYPES_BY_DOMAIN = {
   reviews: REVIEWS_TYPES,
   "modifier-groups": MODIFIER_GROUPS_TYPES,
   content: CONTENT_TYPES,
-  regions: REGIONS_TYPES
+  regions: REGIONS_TYPES,
+  loyalty: LOYALTY_TYPES
 };
 function getTypesByDomain(domain) {
   if (domain === "all") {
@@ -4885,6 +5005,7 @@ var GET_TYPE_DEFINITIONS_SCHEMA = {
     "modifier-groups",
     "content",
     "regions",
+    "loyalty",
     "all"
   ]).describe(
     'The domain of types to retrieve. Use "helpers" for helper function signatures and common types like StoreInfo, PaginatedResponse. Use "content" for FAQ / Footer / Header / Announcement / RichText / Page. Use "regions" for Region / TaxClass admin types.'
@@ -6331,6 +6452,9 @@ function formatCapabilities(caps) {
   lines.push(
     caps.features.hasCheckoutCustomFields ? "\u2705 Checkout custom fields configured (surcharges may apply)" : "\u274C No checkout custom fields"
   );
+  lines.push(
+    caps.features.hasLoyaltyProgram ? "\u2705 Loyalty program active (points & rewards \u2014 storefront-mode only)" : "\u274C No loyalty program"
+  );
   lines.push("");
   lines.push("## Connection Settings");
   lines.push(
@@ -6376,6 +6500,11 @@ function formatCapabilities(caps) {
   if (caps.features.hasCoupons) {
     suggestions.push('Add a coupon input to the cart. Use get-code-example("coupon-input").');
   }
+  if (caps.features.hasLoyaltyProgram) {
+    suggestions.push(
+      "A loyalty program is active. In a storefront-mode client (new BrainerceClient({ storeId })), show the logged-in customer their points balance, 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) {
     suggestions.push(
       `Checkout custom fields are configured. Build a step between shipping/pickup and payment using getCheckoutCustomFields() + setCheckoutCustomFields(). Render checkout.appliedSurcharges in the order summary so customers see what they're paying for. Use get-code-example("checkout-custom-fields").`

package/dist/bin/stdio.js

@@ -1779,7 +1779,7 @@ The merchant can hide a group entirely for one variant by setting \`maxOverride:
 
 ### Restaurant features (advanced)
 
-Allergens (informational chips), scheduled availability windows, nested combos (depth \u2264 3 via \`nestedByModifierId\`), and downsell modifiers (negative \`priceDelta\`) are all built on the same data model. See INTEGRATION-OPTIONAL.md "Restaurant / build-your-own products" for those flows.`;
+Scheduled availability windows, nested combos (depth \u2264 3 via \`nestedByModifierId\`), and downsell modifiers (negative \`priceDelta\`) are all built on the same data model. See INTEGRATION-OPTIONAL.md "Restaurant / build-your-own products" for those flows.`;
 }
 function getProductReviewsSection() {
   return `## Product Reviews (\u2605 ratings + JSON-LD for SEO)
@@ -3307,6 +3307,65 @@ so customers can track their shipment automatically.
 
 **SDK mode:** \`createShippingLabel()\` requires \`apiKey\` (admin mode only).`;
 }
+function getLoyaltySection() {
+  return `# Loyalty & Rewards
+
+Logged-in customers earn points on paid orders and redeem them for a one-time discount coupon at checkout.
+
+> **Storefront mode only.** These methods work only with \`new BrainerceClient({ storeId })\` + a logged-in \`customerToken\`. There is **no vibe-coded route** \u2014 in \`salesChannelId: 'vc_*'\` mode they throw. Skip loyalty if you connect vibe-coded.
+
+Points are earned automatically by the platform when an order is paid \u2014 there is no earn call from the storefront. Your job is to **show** balance/rewards and to **redeem**.
+
+## Status
+
+\`\`\`typescript
+// requires client.setCustomerToken(auth.token)
+const status = await client.getLoyaltyStatus();
+// {
+//   enrolled, pointsBalance, lifetimeEarned,
+//   program: { pointsName, currencyRatio, status } | null,
+//   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)
+
+\`\`\`typescript
+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, type, discountValue, minOrderAmount, maxUsesPerUser, minTierLevel, isActive }]
+// Already filtered to rewards the customer's current tier qualifies for.
+
+const { couponCode, discountType, discountValue, pointsBalance } =
+  await client.redeemLoyaltyReward(rewardId);
+await client.applyCoupon(cartId, couponCode); // applies via the normal coupon engine
+\`\`\`
+
+- \`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
+\`\`\`
+`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -3333,6 +3392,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getInventorySection();
     case "discounts":
       return getDiscountsSection();
+    case "loyalty":
+      return getLoyaltySection();
     case "recommendations":
       return getRecommendationsSection();
     case "reviews":
@@ -3499,6 +3560,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "order-confirmation",
     "inventory",
     "discounts",
+    "loyalty",
     "recommendations",
     "reviews",
     "product-customization-fields",
@@ -4836,6 +4898,63 @@ interface TaxEstimateResponse {
 // Non-binding by design: the authoritative tax runs at checkout against the
 // full shipping address. The country comes from your edge runtime
 // (CF-IPCountry / request.geo.country / etc.), NOT the request IP.`;
+var LOYALTY_TYPES = `// ---- Loyalty & Rewards (storefront mode only) ----
+interface 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)
+  lifetimeEarned: number;
+  program: {
+    pointsName: string;       // e.g. "points", "coins"
+    currencyRatio: number;    // points needed to redeem 1 unit of store currency
+    status: 'DRAFT' | 'ACTIVE' | 'PAUSED';
+  } | null;                   // null when the store has no loyalty program
+  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;
+}
+
+interface LoyaltyReward {
+  id: string;
+  name: string;
+  description: string | null;
+  pointsCost: number;
+  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
+}
+
+// client.getLoyaltyStatus(): Promise<LoyaltyStatus>
+// client.enrollInLoyalty(): Promise<LoyaltyStatus>
+// client.getAvailableRewards(): Promise<LoyaltyReward[]>
+// client.redeemLoyaltyReward(rewardId: string): Promise<RedeemRewardResult>
+// client.reportSocialShare(platform?: string): Promise<{ awarded: boolean; points: number }>
+`;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
   cart: CART_TYPES,
@@ -4848,7 +4967,8 @@ var TYPES_BY_DOMAIN = {
   reviews: REVIEWS_TYPES,
   "modifier-groups": MODIFIER_GROUPS_TYPES,
   content: CONTENT_TYPES,
-  regions: REGIONS_TYPES
+  regions: REGIONS_TYPES,
+  loyalty: LOYALTY_TYPES
 };
 function getTypesByDomain(domain) {
   if (domain === "all") {
@@ -4882,6 +5002,7 @@ var GET_TYPE_DEFINITIONS_SCHEMA = {
     "modifier-groups",
     "content",
     "regions",
+    "loyalty",
     "all"
   ]).describe(
     'The domain of types to retrieve. Use "helpers" for helper function signatures and common types like StoreInfo, PaginatedResponse. Use "content" for FAQ / Footer / Header / Announcement / RichText / Page. Use "regions" for Region / TaxClass admin types.'
@@ -6328,6 +6449,9 @@ function formatCapabilities(caps) {
   lines.push(
     caps.features.hasCheckoutCustomFields ? "\u2705 Checkout custom fields configured (surcharges may apply)" : "\u274C No checkout custom fields"
   );
+  lines.push(
+    caps.features.hasLoyaltyProgram ? "\u2705 Loyalty program active (points & rewards \u2014 storefront-mode only)" : "\u274C No loyalty program"
+  );
   lines.push("");
   lines.push("## Connection Settings");
   lines.push(
@@ -6373,6 +6497,11 @@ function formatCapabilities(caps) {
   if (caps.features.hasCoupons) {
     suggestions.push('Add a coupon input to the cart. Use get-code-example("coupon-input").');
   }
+  if (caps.features.hasLoyaltyProgram) {
+    suggestions.push(
+      "A loyalty program is active. In a storefront-mode client (new BrainerceClient({ storeId })), show the logged-in customer their points balance, 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) {
     suggestions.push(
       `Checkout custom fields are configured. Build a step between shipping/pickup and payment using getCheckoutCustomFields() + setCheckoutCustomFields(). Render checkout.appliedSurcharges in the order summary so customers see what they're paying for. Use get-code-example("checkout-custom-fields").`

package/dist/index.d.mts

@@ -75,6 +75,8 @@ interface StoreCapabilities {
         hasCheckoutCustomFields: boolean;
         /** True when at least one PUBLISHED Content row exists for the store. */
         hasContent?: boolean;
+        /** True when the store has an ACTIVE loyalty program. Storefront-mode only. */
+        hasLoyaltyProgram?: boolean;
     };
 }
 declare function fetchStoreCapabilities(connectionId: string, baseUrl?: string): Promise<StoreCapabilities>;

package/dist/index.d.ts

@@ -75,6 +75,8 @@ interface StoreCapabilities {
         hasCheckoutCustomFields: boolean;
         /** True when at least one PUBLISHED Content row exists for the store. */
         hasContent?: boolean;
+        /** True when the store has an ACTIVE loyalty program. Storefront-mode only. */
+        hasLoyaltyProgram?: boolean;
     };
 }
 declare function fetchStoreCapabilities(connectionId: string, baseUrl?: string): Promise<StoreCapabilities>;

package/dist/index.js

@@ -1805,7 +1805,7 @@ The merchant can hide a group entirely for one variant by setting \`maxOverride:
 
 ### Restaurant features (advanced)
 
-Allergens (informational chips), scheduled availability windows, nested combos (depth \u2264 3 via \`nestedByModifierId\`), and downsell modifiers (negative \`priceDelta\`) are all built on the same data model. See INTEGRATION-OPTIONAL.md "Restaurant / build-your-own products" for those flows.`;
+Scheduled availability windows, nested combos (depth \u2264 3 via \`nestedByModifierId\`), and downsell modifiers (negative \`priceDelta\`) are all built on the same data model. See INTEGRATION-OPTIONAL.md "Restaurant / build-your-own products" for those flows.`;
 }
 function getProductReviewsSection() {
   return `## Product Reviews (\u2605 ratings + JSON-LD for SEO)
@@ -3333,6 +3333,65 @@ so customers can track their shipment automatically.
 
 **SDK mode:** \`createShippingLabel()\` requires \`apiKey\` (admin mode only).`;
 }
+function getLoyaltySection() {
+  return `# Loyalty & Rewards
+
+Logged-in customers earn points on paid orders and redeem them for a one-time discount coupon at checkout.
+
+> **Storefront mode only.** These methods work only with \`new BrainerceClient({ storeId })\` + a logged-in \`customerToken\`. There is **no vibe-coded route** \u2014 in \`salesChannelId: 'vc_*'\` mode they throw. Skip loyalty if you connect vibe-coded.
+
+Points are earned automatically by the platform when an order is paid \u2014 there is no earn call from the storefront. Your job is to **show** balance/rewards and to **redeem**.
+
+## Status
+
+\`\`\`typescript
+// requires client.setCustomerToken(auth.token)
+const status = await client.getLoyaltyStatus();
+// {
+//   enrolled, pointsBalance, lifetimeEarned,
+//   program: { pointsName, currencyRatio, status } | null,
+//   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)
+
+\`\`\`typescript
+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, type, discountValue, minOrderAmount, maxUsesPerUser, minTierLevel, isActive }]
+// Already filtered to rewards the customer's current tier qualifies for.
+
+const { couponCode, discountType, discountValue, pointsBalance } =
+  await client.redeemLoyaltyReward(rewardId);
+await client.applyCoupon(cartId, couponCode); // applies via the normal coupon engine
+\`\`\`
+
+- \`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
+\`\`\`
+`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -3359,6 +3418,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getInventorySection();
     case "discounts":
       return getDiscountsSection();
+    case "loyalty":
+      return getLoyaltySection();
     case "recommendations":
       return getRecommendationsSection();
     case "reviews":
@@ -3525,6 +3586,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "order-confirmation",
     "inventory",
     "discounts",
+    "loyalty",
     "recommendations",
     "reviews",
     "product-customization-fields",
@@ -4862,6 +4924,63 @@ interface TaxEstimateResponse {
 // Non-binding by design: the authoritative tax runs at checkout against the
 // full shipping address. The country comes from your edge runtime
 // (CF-IPCountry / request.geo.country / etc.), NOT the request IP.`;
+var LOYALTY_TYPES = `// ---- Loyalty & Rewards (storefront mode only) ----
+interface 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)
+  lifetimeEarned: number;
+  program: {
+    pointsName: string;       // e.g. "points", "coins"
+    currencyRatio: number;    // points needed to redeem 1 unit of store currency
+    status: 'DRAFT' | 'ACTIVE' | 'PAUSED';
+  } | null;                   // null when the store has no loyalty program
+  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;
+}
+
+interface LoyaltyReward {
+  id: string;
+  name: string;
+  description: string | null;
+  pointsCost: number;
+  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
+}
+
+// client.getLoyaltyStatus(): Promise<LoyaltyStatus>
+// client.enrollInLoyalty(): Promise<LoyaltyStatus>
+// client.getAvailableRewards(): Promise<LoyaltyReward[]>
+// client.redeemLoyaltyReward(rewardId: string): Promise<RedeemRewardResult>
+// client.reportSocialShare(platform?: string): Promise<{ awarded: boolean; points: number }>
+`;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
   cart: CART_TYPES,
@@ -4874,7 +4993,8 @@ var TYPES_BY_DOMAIN = {
   reviews: REVIEWS_TYPES,
   "modifier-groups": MODIFIER_GROUPS_TYPES,
   content: CONTENT_TYPES,
-  regions: REGIONS_TYPES
+  regions: REGIONS_TYPES,
+  loyalty: LOYALTY_TYPES
 };
 function getTypesByDomain(domain) {
   if (domain === "all") {
@@ -4908,6 +5028,7 @@ var GET_TYPE_DEFINITIONS_SCHEMA = {
     "modifier-groups",
     "content",
     "regions",
+    "loyalty",
     "all"
   ]).describe(
     'The domain of types to retrieve. Use "helpers" for helper function signatures and common types like StoreInfo, PaginatedResponse. Use "content" for FAQ / Footer / Header / Announcement / RichText / Page. Use "regions" for Region / TaxClass admin types.'
@@ -6354,6 +6475,9 @@ function formatCapabilities(caps) {
   lines.push(
     caps.features.hasCheckoutCustomFields ? "\u2705 Checkout custom fields configured (surcharges may apply)" : "\u274C No checkout custom fields"
   );
+  lines.push(
+    caps.features.hasLoyaltyProgram ? "\u2705 Loyalty program active (points & rewards \u2014 storefront-mode only)" : "\u274C No loyalty program"
+  );
   lines.push("");
   lines.push("## Connection Settings");
   lines.push(
@@ -6399,6 +6523,11 @@ function formatCapabilities(caps) {
   if (caps.features.hasCoupons) {
     suggestions.push('Add a coupon input to the cart. Use get-code-example("coupon-input").');
   }
+  if (caps.features.hasLoyaltyProgram) {
+    suggestions.push(
+      "A loyalty program is active. In a storefront-mode client (new BrainerceClient({ storeId })), show the logged-in customer their points balance, 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) {
     suggestions.push(
       `Checkout custom fields are configured. Build a step between shipping/pickup and payment using getCheckoutCustomFields() + setCheckoutCustomFields(). Render checkout.appliedSurcharges in the order summary so customers see what they're paying for. Use get-code-example("checkout-custom-fields").`

package/dist/index.mjs

@@ -1773,7 +1773,7 @@ The merchant can hide a group entirely for one variant by setting \`maxOverride:
 
 ### Restaurant features (advanced)
 
-Allergens (informational chips), scheduled availability windows, nested combos (depth \u2264 3 via \`nestedByModifierId\`), and downsell modifiers (negative \`priceDelta\`) are all built on the same data model. See INTEGRATION-OPTIONAL.md "Restaurant / build-your-own products" for those flows.`;
+Scheduled availability windows, nested combos (depth \u2264 3 via \`nestedByModifierId\`), and downsell modifiers (negative \`priceDelta\`) are all built on the same data model. See INTEGRATION-OPTIONAL.md "Restaurant / build-your-own products" for those flows.`;
 }
 function getProductReviewsSection() {
   return `## Product Reviews (\u2605 ratings + JSON-LD for SEO)
@@ -3301,6 +3301,65 @@ so customers can track their shipment automatically.
 
 **SDK mode:** \`createShippingLabel()\` requires \`apiKey\` (admin mode only).`;
 }
+function getLoyaltySection() {
+  return `# Loyalty & Rewards
+
+Logged-in customers earn points on paid orders and redeem them for a one-time discount coupon at checkout.
+
+> **Storefront mode only.** These methods work only with \`new BrainerceClient({ storeId })\` + a logged-in \`customerToken\`. There is **no vibe-coded route** \u2014 in \`salesChannelId: 'vc_*'\` mode they throw. Skip loyalty if you connect vibe-coded.
+
+Points are earned automatically by the platform when an order is paid \u2014 there is no earn call from the storefront. Your job is to **show** balance/rewards and to **redeem**.
+
+## Status
+
+\`\`\`typescript
+// requires client.setCustomerToken(auth.token)
+const status = await client.getLoyaltyStatus();
+// {
+//   enrolled, pointsBalance, lifetimeEarned,
+//   program: { pointsName, currencyRatio, status } | null,
+//   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)
+
+\`\`\`typescript
+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, type, discountValue, minOrderAmount, maxUsesPerUser, minTierLevel, isActive }]
+// Already filtered to rewards the customer's current tier qualifies for.
+
+const { couponCode, discountType, discountValue, pointsBalance } =
+  await client.redeemLoyaltyReward(rewardId);
+await client.applyCoupon(cartId, couponCode); // applies via the normal coupon engine
+\`\`\`
+
+- \`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
+\`\`\`
+`;
+}
 function getSectionByTopic(topic, connectionId, currency) {
   const cid = connectionId || "vc_YOUR_CONNECTION_ID";
   const cur = currency || "USD";
@@ -3327,6 +3386,8 @@ function getSectionByTopic(topic, connectionId, currency) {
       return getInventorySection();
     case "discounts":
       return getDiscountsSection();
+    case "loyalty":
+      return getLoyaltySection();
     case "recommendations":
       return getRecommendationsSection();
     case "reviews":
@@ -3493,6 +3554,7 @@ var GET_SDK_DOCS_SCHEMA = {
     "order-confirmation",
     "inventory",
     "discounts",
+    "loyalty",
     "recommendations",
     "reviews",
     "product-customization-fields",
@@ -4830,6 +4892,63 @@ interface TaxEstimateResponse {
 // Non-binding by design: the authoritative tax runs at checkout against the
 // full shipping address. The country comes from your edge runtime
 // (CF-IPCountry / request.geo.country / etc.), NOT the request IP.`;
+var LOYALTY_TYPES = `// ---- Loyalty & Rewards (storefront mode only) ----
+interface 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)
+  lifetimeEarned: number;
+  program: {
+    pointsName: string;       // e.g. "points", "coins"
+    currencyRatio: number;    // points needed to redeem 1 unit of store currency
+    status: 'DRAFT' | 'ACTIVE' | 'PAUSED';
+  } | null;                   // null when the store has no loyalty program
+  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;
+}
+
+interface LoyaltyReward {
+  id: string;
+  name: string;
+  description: string | null;
+  pointsCost: number;
+  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
+}
+
+// client.getLoyaltyStatus(): Promise<LoyaltyStatus>
+// client.enrollInLoyalty(): Promise<LoyaltyStatus>
+// client.getAvailableRewards(): Promise<LoyaltyReward[]>
+// client.redeemLoyaltyReward(rewardId: string): Promise<RedeemRewardResult>
+// client.reportSocialShare(platform?: string): Promise<{ awarded: boolean; points: number }>
+`;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
   cart: CART_TYPES,
@@ -4842,7 +4961,8 @@ var TYPES_BY_DOMAIN = {
   reviews: REVIEWS_TYPES,
   "modifier-groups": MODIFIER_GROUPS_TYPES,
   content: CONTENT_TYPES,
-  regions: REGIONS_TYPES
+  regions: REGIONS_TYPES,
+  loyalty: LOYALTY_TYPES
 };
 function getTypesByDomain(domain) {
   if (domain === "all") {
@@ -4876,6 +4996,7 @@ var GET_TYPE_DEFINITIONS_SCHEMA = {
     "modifier-groups",
     "content",
     "regions",
+    "loyalty",
     "all"
   ]).describe(
     'The domain of types to retrieve. Use "helpers" for helper function signatures and common types like StoreInfo, PaginatedResponse. Use "content" for FAQ / Footer / Header / Announcement / RichText / Page. Use "regions" for Region / TaxClass admin types.'
@@ -6322,6 +6443,9 @@ function formatCapabilities(caps) {
   lines.push(
     caps.features.hasCheckoutCustomFields ? "\u2705 Checkout custom fields configured (surcharges may apply)" : "\u274C No checkout custom fields"
   );
+  lines.push(
+    caps.features.hasLoyaltyProgram ? "\u2705 Loyalty program active (points & rewards \u2014 storefront-mode only)" : "\u274C No loyalty program"
+  );
   lines.push("");
   lines.push("## Connection Settings");
   lines.push(
@@ -6367,6 +6491,11 @@ function formatCapabilities(caps) {
   if (caps.features.hasCoupons) {
     suggestions.push('Add a coupon input to the cart. Use get-code-example("coupon-input").');
   }
+  if (caps.features.hasLoyaltyProgram) {
+    suggestions.push(
+      "A loyalty program is active. In a storefront-mode client (new BrainerceClient({ storeId })), show the logged-in customer their points balance, 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) {
     suggestions.push(
       `Checkout custom fields are configured. Build a step between shipping/pickup and payment using getCheckoutCustomFields() + setCheckoutCustomFields(). Render checkout.appliedSurcharges in the order summary so customers see what they're paying for. Use get-code-example("checkout-custom-fields").`

package/package.json

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