brainerce 1.42.0 → 1.43.0

package/README.md

@@ -46,7 +46,7 @@ Every Brainerce storefront must include **all mandatory features** below. Featur
 | Forgot / reset password                                 | `client.forgotPassword()`, `client.resetPassword()`                                                           | ✅          |
 | OAuth sign-in buttons + callback handler                | `client.getAvailableOAuthProviders()`                                                                         | ✅          |
 | Account area (profile + order history)                  | `client.getMyProfile()`, `client.getMyOrders()`                                                               | ✅          |
-| Loyalty & rewards (points balance + redeem)             | `client.getLoyaltyStatus()`, `client.getAvailableRewards()`, `client.redeemLoyaltyReward(id)`                 | conditional |
+| Loyalty & rewards (points balance + tiers + redeem)     | `client.getLoyaltyStatus()`, `client.getAvailableRewards()`, `client.redeemLoyaltyReward(id)`, `client.reportSocialShare()` | conditional |
 | Global header: cart count + search autocomplete         | `client.getCart()`, `client.getSearchSuggestions(query)`                                                      | ✅          |
 | Discount banners + product badges                       | `client.getDiscountBanners()`, `client.getProductDiscountBadge(productId)`                                    | ✅          |
 | Product reviews on PDP + JSON-LD aggregateRating        | `client.listProductReviews(id)`, `client.submitProductReview(id, …)`                                          | ✅          |
@@ -2920,23 +2920,35 @@ customers check their points balance, enroll, and redeem rewards for one-time
 coupons that apply at checkout.
 
 ```typescript
-// Current status — points balance + program display config.
-// `program` is null if the store has no loyalty program.
+// Current status — points balance + program display config + tier progress.
+// `program`/`tier`/`nextTier` are null if the store has no loyalty program
+// (or no tiers configured / the customer hasn't reached one yet).
 const status = await client.getLoyaltyStatus();
 if (status.enrolled) {
   console.log(`${status.pointsBalance} ${status.program?.pointsName}`);
+  if (status.nextTier) {
+    console.log(`${status.pointsToNextTier} to reach ${status.nextTier.name}`);
+  }
 }
 
-// Enroll (idempotent) — only if the program is ACTIVE.
+// Enroll (idempotent) — only if the program is ACTIVE. May grant a one-time
+// "join the program" bonus if the store has one configured.
 await client.enrollInLoyalty();
 
-// Rewards the customer can redeem, cheapest first.
+// Rewards the customer can redeem, cheapest first (already filtered to ones
+// their current tier qualifies for).
 const rewards = await client.getAvailableRewards();
 
 // Redeem → spends points, returns a one-time coupon code to apply to the cart.
-const { couponCode, discountValue, pointsBalance } =
+// `discountType` tells you how to interpret `discountValue` (currency amount
+// for FIXED_DISCOUNT, 0-100 percent for PERCENT_DISCOUNT).
+const { couponCode, discountType, discountValue, pointsBalance } =
   await client.redeemLoyaltyReward(rewards[0].id);
 await client.applyCoupon(cartId, couponCode);
+
+// Self-reported social share — grants the SOCIAL_SHARE bonus if configured
+// (once per customer).
+await client.reportSocialShare('instagram');
 ```
 
 #### Auth Response Type

package/dist/index.d.mts

@@ -248,6 +248,21 @@ interface CustomerProfile {
     createdAt: string;
     updatedAt: string;
 }
+/** The membership tier a customer currently holds, or is progressing toward. */
+interface LoyaltyTierSummary {
+    id: string;
+    name: string;
+    /** Ordering; higher = better tier. */
+    level: number;
+    /** Points-earning multiplier this tier grants (e.g. 1.5 = 50% more points per order). */
+    pointsMultiplier: number;
+}
+/** The next tier up, including what it takes to qualify. */
+interface LoyaltyNextTierSummary extends LoyaltyTierSummary {
+    qualificationType: 'SPEND' | 'POINTS';
+    /** Threshold in store currency (SPEND) or points (POINTS). */
+    qualificationThreshold: number;
+}
 /** A store's loyalty program status for a logged-in customer. */
 interface LoyaltyStatus {
     /** Whether the customer has a membership in the program. */
@@ -264,21 +279,32 @@ interface LoyaltyStatus {
         currencyRatio: number;
         status: 'DRAFT' | 'ACTIVE' | 'PAUSED';
     } | null;
-}
-/** A reward a customer can redeem points for (fixed-amount discount coupon). */
+    /** The customer's current tier, or null if untiered / no tiers configured. */
+    tier: LoyaltyTierSummary | null;
+    /** The next tier up, or null if already at the top tier (or no tiers configured). */
+    nextTier: LoyaltyNextTierSummary | null;
+    /** 0..1 progress toward nextTier; 1 if no nextTier and a tier is held. */
+    progressToNextTier: number;
+    /** Remaining spend/points needed to reach nextTier, or null if there's no nextTier. */
+    pointsToNextTier: number | null;
+}
+/** A reward a customer can redeem points for. */
 interface LoyaltyReward {
     id: string;
     name: string;
     description: string | null;
     /** Points required to redeem this reward. */
     pointsCost: number;
-    /** Fixed discount amount the minted coupon is worth, in store currency. */
+    /** FIXED_DISCOUNT: discountValue is a store-currency amount off. PERCENT_DISCOUNT: discountValue is a 0-100 percent off. */
+    type: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
     discountValue: number;
     /** Minimum order amount for the coupon to apply, or null. */
     minOrderAmount: number | null;
     /** How many times a single customer may redeem this reward. */
     maxUsesPerUser: number;
     isActive: boolean;
+    /** Minimum tier level required to redeem this reward, or null for no restriction. */
+    minTierLevel: number | null;
     createdAt: string;
     updatedAt: string;
 }
@@ -286,7 +312,9 @@ interface LoyaltyReward {
 interface RedeemRewardResult {
     /** The minted one-time coupon code to apply at checkout. */
     couponCode: string;
-    /** Fixed discount amount the coupon is worth. */
+    /** Matches the redeemed reward's `type` — tells you how to interpret discountValue. */
+    discountType: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
+    /** Currency amount (FIXED_DISCOUNT) or percent 0-100 (PERCENT_DISCOUNT) the coupon is worth. */
     discountValue: number;
     /** Points spent on this redemption. */
     pointsSpent: number;
@@ -8662,6 +8690,21 @@ declare class BrainerceClient {
      * ```
      */
     redeemLoyaltyReward(rewardId: string): Promise<RedeemRewardResult>;
+    /**
+     * Report a social share, granting the SOCIAL_SHARE earning-rule bonus if the
+     * store has one configured (requires customerToken). Self-reported — no
+     * share-tracking infra — and capped at once per customer per program. Only
+     * available in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * await client.reportSocialShare('instagram');
+     * ```
+     */
+    reportSocialShare(platform?: string): Promise<{
+        awarded: boolean;
+        points: number;
+    }>;
     /**
      * Get the current customer's orders (requires customerToken)
      * Works in vibe-coded and storefront modes

package/dist/index.d.ts

@@ -248,6 +248,21 @@ interface CustomerProfile {
     createdAt: string;
     updatedAt: string;
 }
+/** The membership tier a customer currently holds, or is progressing toward. */
+interface LoyaltyTierSummary {
+    id: string;
+    name: string;
+    /** Ordering; higher = better tier. */
+    level: number;
+    /** Points-earning multiplier this tier grants (e.g. 1.5 = 50% more points per order). */
+    pointsMultiplier: number;
+}
+/** The next tier up, including what it takes to qualify. */
+interface LoyaltyNextTierSummary extends LoyaltyTierSummary {
+    qualificationType: 'SPEND' | 'POINTS';
+    /** Threshold in store currency (SPEND) or points (POINTS). */
+    qualificationThreshold: number;
+}
 /** A store's loyalty program status for a logged-in customer. */
 interface LoyaltyStatus {
     /** Whether the customer has a membership in the program. */
@@ -264,21 +279,32 @@ interface LoyaltyStatus {
         currencyRatio: number;
         status: 'DRAFT' | 'ACTIVE' | 'PAUSED';
     } | null;
-}
-/** A reward a customer can redeem points for (fixed-amount discount coupon). */
+    /** The customer's current tier, or null if untiered / no tiers configured. */
+    tier: LoyaltyTierSummary | null;
+    /** The next tier up, or null if already at the top tier (or no tiers configured). */
+    nextTier: LoyaltyNextTierSummary | null;
+    /** 0..1 progress toward nextTier; 1 if no nextTier and a tier is held. */
+    progressToNextTier: number;
+    /** Remaining spend/points needed to reach nextTier, or null if there's no nextTier. */
+    pointsToNextTier: number | null;
+}
+/** A reward a customer can redeem points for. */
 interface LoyaltyReward {
     id: string;
     name: string;
     description: string | null;
     /** Points required to redeem this reward. */
     pointsCost: number;
-    /** Fixed discount amount the minted coupon is worth, in store currency. */
+    /** FIXED_DISCOUNT: discountValue is a store-currency amount off. PERCENT_DISCOUNT: discountValue is a 0-100 percent off. */
+    type: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
     discountValue: number;
     /** Minimum order amount for the coupon to apply, or null. */
     minOrderAmount: number | null;
     /** How many times a single customer may redeem this reward. */
     maxUsesPerUser: number;
     isActive: boolean;
+    /** Minimum tier level required to redeem this reward, or null for no restriction. */
+    minTierLevel: number | null;
     createdAt: string;
     updatedAt: string;
 }
@@ -286,7 +312,9 @@ interface LoyaltyReward {
 interface RedeemRewardResult {
     /** The minted one-time coupon code to apply at checkout. */
     couponCode: string;
-    /** Fixed discount amount the coupon is worth. */
+    /** Matches the redeemed reward's `type` — tells you how to interpret discountValue. */
+    discountType: 'FIXED_DISCOUNT' | 'PERCENT_DISCOUNT';
+    /** Currency amount (FIXED_DISCOUNT) or percent 0-100 (PERCENT_DISCOUNT) the coupon is worth. */
     discountValue: number;
     /** Points spent on this redemption. */
     pointsSpent: number;
@@ -8662,6 +8690,21 @@ declare class BrainerceClient {
      * ```
      */
     redeemLoyaltyReward(rewardId: string): Promise<RedeemRewardResult>;
+    /**
+     * Report a social share, granting the SOCIAL_SHARE earning-rule bonus if the
+     * store has one configured (requires customerToken). Self-reported — no
+     * share-tracking infra — and capped at once per customer per program. Only
+     * available in storefront mode.
+     *
+     * @example
+     * ```typescript
+     * await client.reportSocialShare('instagram');
+     * ```
+     */
+    reportSocialShare(platform?: string): Promise<{
+        awarded: boolean;
+        points: number;
+    }>;
     /**
      * Get the current customer's orders (requires customerToken)
      * Works in vibe-coded and storefront modes

package/dist/index.js

@@ -6411,6 +6411,33 @@ var BrainerceClient = class {
     }
     throw new BrainerceError("redeemLoyaltyReward is only available in storefront mode", 400);
   }
+  /**
+   * Report a social share, granting the SOCIAL_SHARE earning-rule bonus if the
+   * store has one configured (requires customerToken). Self-reported — no
+   * share-tracking infra — and capped at once per customer per program. Only
+   * available in storefront mode.
+   *
+   * @example
+   * ```typescript
+   * await client.reportSocialShare('instagram');
+   * ```
+   */
+  async reportSocialShare(platform) {
+    if (!this.customerToken && !this.proxyMode) {
+      throw new BrainerceError(
+        "Customer token required. Call setCustomerToken() after login.",
+        401
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "POST",
+        "/loyalty/social-share",
+        platform ? { platform } : {}
+      );
+    }
+    throw new BrainerceError("reportSocialShare is only available in storefront mode", 400);
+  }
   /**
    * Get the current customer's orders (requires customerToken)
    * Works in vibe-coded and storefront modes

package/dist/index.mjs

@@ -6341,6 +6341,33 @@ var BrainerceClient = class {
     }
     throw new BrainerceError("redeemLoyaltyReward is only available in storefront mode", 400);
   }
+  /**
+   * Report a social share, granting the SOCIAL_SHARE earning-rule bonus if the
+   * store has one configured (requires customerToken). Self-reported — no
+   * share-tracking infra — and capped at once per customer per program. Only
+   * available in storefront mode.
+   *
+   * @example
+   * ```typescript
+   * await client.reportSocialShare('instagram');
+   * ```
+   */
+  async reportSocialShare(platform) {
+    if (!this.customerToken && !this.proxyMode) {
+      throw new BrainerceError(
+        "Customer token required. Call setCustomerToken() after login.",
+        401
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "POST",
+        "/loyalty/social-share",
+        platform ? { platform } : {}
+      );
+    }
+    throw new BrainerceError("reportSocialShare is only available in storefront mode", 400);
+  }
   /**
    * Get the current customer's orders (requires customerToken)
    * Works in vibe-coded and storefront modes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.42.0",
+  "version": "1.43.0",
   "description": "Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",