@brainerce/mcp-server 3.12.2 → 3.12.3

package/dist/bin/http.js

@@ -3324,11 +3324,18 @@ Points are earned automatically by the platform when an order is paid \u2014 the
 \`\`\`typescript
 // requires client.setCustomerToken(auth.token)
 const status = await client.getLoyaltyStatus();
-// { enrolled, pointsBalance, lifetimeEarned, program: { pointsName, currencyRatio, status } | null }
+// {
+//   enrolled, pointsBalance, lifetimeEarned,
+//   program: { pointsName, currencyRatio, status } | null,
+//   tier: { id, name, level, pointsMultiplier } | null,
+//   nextTier: { id, name, level, pointsMultiplier, qualificationType, qualificationThreshold } | null,
+//   progressToNextTier, pointsToNextTier,
+// }
 \`\`\`
 
 - \`program === null\` \u2192 the store has no loyalty program; hide the loyalty UI.
 - \`program.status !== 'ACTIVE'\` \u2192 program paused/draft; hide the loyalty UI.
+- \`tier\`/\`nextTier\` are \`null\` when the store hasn't configured tiers, or the customer hasn't qualified for one yet.
 
 ## Enroll (only if auto-enroll is off)
 
@@ -3336,19 +3343,30 @@ 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
+\`\`\`
 `;
 }
 function getSectionByTopic(topic, connectionId, currency) {
@@ -4884,6 +4902,18 @@ interface TaxEstimateResponse {
 // full shipping address. The country comes from your edge runtime
 // (CF-IPCountry / request.geo.country / etc.), NOT the request IP.`;
 var LOYALTY_TYPES = `// ---- Loyalty & Rewards (storefront mode only) ----
+interface LoyaltyTierSummary {
+  id: string;
+  name: string;
+  level: number;              // ordering; higher = better tier
+  pointsMultiplier: number;
+}
+
+interface LoyaltyNextTierSummary extends LoyaltyTierSummary {
+  qualificationType: 'SPEND' | 'POINTS';
+  qualificationThreshold: number;
+}
+
 interface LoyaltyStatus {
   enrolled: boolean;
   pointsBalance: number;      // redeemable points (pending earns excluded)
@@ -4893,6 +4923,10 @@ 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;
 }
 
 interface LoyaltyReward {
@@ -4900,16 +4934,19 @@ interface LoyaltyReward {
   name: string;
   description: string | null;
   pointsCost: number;
-  discountValue: number;      // fixed amount off, store currency
+  type: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
+  discountValue: number;      // currency amount (FIXED_DISCOUNT) or 0-100 percent (PERCENT_DISCOUNT)
   minOrderAmount: number | null;
   maxUsesPerUser: number;
   isActive: boolean;
+  minTierLevel: number | null; // minimum tier level required, or null for no restriction
   createdAt: string;
   updatedAt: string;
 }
 
 interface RedeemRewardResult {
   couponCode: string;         // one-time coupon to apply at checkout
+  discountType: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
   discountValue: number;
   pointsSpent: number;
   pointsBalance: number;      // remaining balance after redemption
@@ -4919,6 +4956,7 @@ 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 }>
 `;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
@@ -6464,7 +6502,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/bin/stdio.js

@@ -3321,11 +3321,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 +3340,30 @@ 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
+\`\`\`
 `;
 }
 function getSectionByTopic(topic, connectionId, currency) {
@@ -4881,6 +4899,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 +4920,10 @@ 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;
 }
 
 interface LoyaltyReward {
@@ -4897,16 +4931,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 +4953,7 @@ 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 }>
 `;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
@@ -6461,7 +6499,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.js

@@ -3347,11 +3347,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 +3366,30 @@ 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
+\`\`\`
 `;
 }
 function getSectionByTopic(topic, connectionId, currency) {
@@ -4907,6 +4925,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 +4946,10 @@ 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;
 }
 
 interface LoyaltyReward {
@@ -4923,16 +4957,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 +4979,7 @@ 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 }>
 `;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
@@ -6487,7 +6525,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.mjs

@@ -3315,11 +3315,18 @@ Points are earned automatically by the platform when an order is paid \u2014 the
 \`\`\`typescript
 // requires client.setCustomerToken(auth.token)
 const status = await client.getLoyaltyStatus();
-// { enrolled, pointsBalance, lifetimeEarned, program: { pointsName, currencyRatio, status } | null }
+// {
+//   enrolled, pointsBalance, lifetimeEarned,
+//   program: { pointsName, currencyRatio, status } | null,
+//   tier: { id, name, level, pointsMultiplier } | null,
+//   nextTier: { id, name, level, pointsMultiplier, qualificationType, qualificationThreshold } | null,
+//   progressToNextTier, pointsToNextTier,
+// }
 \`\`\`
 
 - \`program === null\` \u2192 the store has no loyalty program; hide the loyalty UI.
 - \`program.status !== 'ACTIVE'\` \u2192 program paused/draft; hide the loyalty UI.
+- \`tier\`/\`nextTier\` are \`null\` when the store hasn't configured tiers, or the customer hasn't qualified for one yet.
 
 ## Enroll (only if auto-enroll is off)
 
@@ -3327,19 +3334,30 @@ 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
+\`\`\`
 `;
 }
 function getSectionByTopic(topic, connectionId, currency) {
@@ -4875,6 +4893,18 @@ interface TaxEstimateResponse {
 // full shipping address. The country comes from your edge runtime
 // (CF-IPCountry / request.geo.country / etc.), NOT the request IP.`;
 var LOYALTY_TYPES = `// ---- Loyalty & Rewards (storefront mode only) ----
+interface LoyaltyTierSummary {
+  id: string;
+  name: string;
+  level: number;              // ordering; higher = better tier
+  pointsMultiplier: number;
+}
+
+interface LoyaltyNextTierSummary extends LoyaltyTierSummary {
+  qualificationType: 'SPEND' | 'POINTS';
+  qualificationThreshold: number;
+}
+
 interface LoyaltyStatus {
   enrolled: boolean;
   pointsBalance: number;      // redeemable points (pending earns excluded)
@@ -4884,6 +4914,10 @@ 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;
 }
 
 interface LoyaltyReward {
@@ -4891,16 +4925,19 @@ interface LoyaltyReward {
   name: string;
   description: string | null;
   pointsCost: number;
-  discountValue: number;      // fixed amount off, store currency
+  type: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
+  discountValue: number;      // currency amount (FIXED_DISCOUNT) or 0-100 percent (PERCENT_DISCOUNT)
   minOrderAmount: number | null;
   maxUsesPerUser: number;
   isActive: boolean;
+  minTierLevel: number | null; // minimum tier level required, or null for no restriction
   createdAt: string;
   updatedAt: string;
 }
 
 interface RedeemRewardResult {
   couponCode: string;         // one-time coupon to apply at checkout
+  discountType: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
   discountValue: number;
   pointsSpent: number;
   pointsBalance: number;      // remaining balance after redemption
@@ -4910,6 +4947,7 @@ 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 }>
 `;
 var TYPES_BY_DOMAIN = {
   products: PRODUCTS_TYPES,
@@ -6455,7 +6493,7 @@ function formatCapabilities(caps) {
   }
   if (caps.features.hasLoyaltyProgram) {
     suggestions.push(
-      "A loyalty program is active. In a storefront-mode client (new BrainerceClient({ storeId })), show the logged-in customer their points balance and redeemable rewards, and let them redeem for a coupon at checkout. Use getLoyaltyStatus(), getAvailableRewards(), and redeemLoyaltyReward(id). Note: loyalty is NOT available in vibe-coded mode."
+      "A loyalty program is active. In a storefront-mode client (new BrainerceClient({ storeId })), show the logged-in customer their points balance, tier progress, and redeemable rewards, and let them redeem for a coupon at checkout. Use getLoyaltyStatus() (includes tier/nextTier/progressToNextTier), getAvailableRewards(), redeemLoyaltyReward(id), and optionally reportSocialShare(). Note: loyalty is NOT available in vibe-coded mode."
     );
   }
   if (caps.features.hasCheckoutCustomFields) {

package/package.json

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