brainerce 1.39.0 → 1.42.0

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.36.1";
+var SDK_VERSION = "1.42.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -583,6 +583,7 @@ var BrainerceClient = class {
       }
     }
     this.proxyMode = options.proxyMode || false;
+    this.analyticsBaseUrl = this.resolveAnalyticsBaseUrl(options.analyticsBaseUrl, resolvedBase);
     this.onAuthError = options.onAuthError;
     this.hydrateSessionCart();
     this.detectRecoverCartFromUrl();
@@ -1036,12 +1037,46 @@ var BrainerceClient = class {
    * ```
    */
   async trackEvent(payload = {}) {
+    if (this.isVibeCodedMode() && this.connectionId) {
+      this.sendAnalyticsBeacon(`/api/vc/${encodePathSegment(this.connectionId)}/events`, payload);
+    } else if (this.isStorefrontMode() && this.storeId) {
+      this.sendAnalyticsBeacon(`/api/stores/${encodePathSegment(this.storeId)}/events`, payload);
+    }
+  }
+  /**
+   * Resolve the base URL for analytics beacons. Analytics must go DIRECTLY to the
+   * Brainerce API (never through a same-origin BFF proxy) so the visitor's real IP —
+   * hence country — reaches the backend. Explicit `analyticsBaseUrl` wins; otherwise
+   * use the direct API when `baseUrl` is a same-origin proxy, else the (already-direct)
+   * `baseUrl` (which may be a custom / self-hosted Brainerce API).
+   */
+  resolveAnalyticsBaseUrl(explicit, resolvedBase) {
+    if (explicit) return explicit.replace(/\/$/, "");
+    const sameOriginProxy = this.proxyMode || typeof window !== "undefined" && !!window.location?.origin && resolvedBase.startsWith(window.location.origin);
+    return sameOriginProxy ? DEFAULT_BASE_URL : resolvedBase;
+  }
+  /**
+   * Fire-and-forget analytics beacon sent directly to `analyticsBaseUrl`. Uses
+   * `keepalive` so it survives page unload (engagement events fired on pagehide),
+   * omits credentials (cookieless), and never throws.
+   */
+  sendAnalyticsBeacon(eventsPath, payload) {
     try {
-      if (this.isVibeCodedMode()) {
-        await this.vibeCodedRequest("POST", "/events", payload);
-      } else if (this.isStorefrontMode()) {
-        await this.storefrontRequest("POST", "/events", payload);
-      }
+      const headers = {
+        "Content-Type": "application/json",
+        "X-SDK-Version": SDK_VERSION,
+        "ngrok-skip-browser-warning": "true"
+      };
+      if (this.origin) headers["Origin"] = this.origin;
+      void fetch(`${this.analyticsBaseUrl}${eventsPath}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        keepalive: true,
+        credentials: "omit",
+        mode: "cors"
+      }).catch(() => {
+      });
     } catch {
     }
   }
@@ -5159,6 +5194,14 @@ var BrainerceClient = class {
    *
    * @returns Payment providers config with hasPayments flag and provider list
    *
+   * Each provider carries a `methodType` (Shopify-parity taxonomy) and a derived
+   * `isAdditive` / `presentation`. There is at most ONE primary card processor
+   * (`methodType: 'CREDIT_CARD'`, the `defaultProvider`) that settles the order;
+   * additive methods (`isAdditive: true`, e.g. PayPal as a `'WALLET'`) are shown
+   * *alongside* it as accelerated-checkout express buttons — they never replace
+   * the card form. A wallet-only store is the one exception: with no card
+   * processor installed, the wallet becomes the `defaultProvider` and stands alone.
+   *
    * @example
    * ```typescript
    * const { providers, hasPayments, defaultProvider } = await client.getPaymentProviders();
@@ -5168,27 +5211,21 @@ var BrainerceClient = class {
    *   return;
    * }
    *
-   * // Find specific providers
-   * const stripeProvider = providers.find(p => p.provider === 'stripe');
-   * const paypalProvider = providers.find(p => p.provider === 'paypal');
-   *
-   * // Initialize Stripe if available (with Connect account support)
-   * if (stripeProvider) {
-   *   const stripe = await loadStripe(stripeProvider.publicKey, {
-   *     stripeAccount: stripeProvider.stripeAccountId, // For Stripe Connect
-   *   });
-   *   // Show Stripe payment form
-   * }
-   *
-   * // Initialize PayPal if available
-   * if (paypalProvider) {
-   *   // Load PayPal SDK with paypalProvider.publicKey as client-id
-   *   // Show PayPal buttons
+   * // Render additive methods (wallets) as express buttons ABOVE the card form.
+   * const expressMethods = providers.filter(p => p.isAdditive); // e.g. PayPal
+   * for (const m of expressMethods) {
+   *   // m.presentation === 'express_button' — render an express/accelerated button
+   *   // and call createPaymentIntent({ providerId: m.id }) when the buyer taps it.
    * }
    *
-   * // Or use the default provider for a simpler single-provider flow
-   * if (defaultProvider) {
-   *   console.log(`Using default: ${defaultProvider.name} (${defaultProvider.provider})`);
+   * // Render the primary card processor (the settling default) as the main form.
+   * if (defaultProvider && !defaultProvider.isAdditive) {
+   *   if (defaultProvider.provider === 'stripe') {
+   *     const stripe = await loadStripe(defaultProvider.publicKey, {
+   *       stripeAccount: defaultProvider.stripeAccountId, // For Stripe Connect
+   *     });
+   *     // Show the Stripe card form
+   *   }
    * }
    * ```
    */
@@ -6208,6 +6245,102 @@ var BrainerceClient = class {
       400
     );
   }
+  // -------------------- Loyalty --------------------
+  // Storefront-mode only (storeId + customerToken). The backend exposes loyalty
+  // solely under /api/stores/:storeId/loyalty — there is no vibe-coded route, so
+  // these do NOT branch on isVibeCodedMode() (that would 404 silently).
+  /**
+   * Get the logged-in customer's loyalty status: enrollment, points balance,
+   * lifetime earned, and the program's display config (requires customerToken).
+   * Only available in storefront mode. `program` is null when the store has no
+   * loyalty program.
+   *
+   * @example
+   * ```typescript
+   * client.setCustomerToken(auth.token);
+   * const status = await client.getLoyaltyStatus();
+   * if (status.enrolled) console.log(`${status.pointsBalance} ${status.program?.pointsName}`);
+   * ```
+   */
+  async getLoyaltyStatus() {
+    if (!this.customerToken && !this.proxyMode) {
+      throw new BrainerceError(
+        "Customer token required. Call setCustomerToken() after login.",
+        401
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", "/loyalty/me");
+    }
+    throw new BrainerceError("getLoyaltyStatus is only available in storefront mode", 400);
+  }
+  /**
+   * Enroll the logged-in customer in the store's loyalty program (requires
+   * customerToken). Idempotent — returns the same status shape as
+   * getLoyaltyStatus(). Only available in storefront mode.
+   *
+   * @example
+   * ```typescript
+   * const status = await client.enrollInLoyalty();
+   * ```
+   */
+  async enrollInLoyalty() {
+    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/enroll");
+    }
+    throw new BrainerceError("enrollInLoyalty is only available in storefront mode", 400);
+  }
+  /**
+   * List the rewards the customer can redeem points for (active rewards, cheapest
+   * first). Requires customerToken. Only available in storefront mode.
+   *
+   * @example
+   * ```typescript
+   * client.setCustomerToken(auth.token);
+   * const rewards = await client.getAvailableRewards();
+   * ```
+   */
+  async getAvailableRewards() {
+    if (!this.customerToken && !this.proxyMode) {
+      throw new BrainerceError(
+        "Customer token required. Call setCustomerToken() after login.",
+        401
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", "/loyalty/rewards/available");
+    }
+    throw new BrainerceError("getAvailableRewards is only available in storefront mode", 400);
+  }
+  /**
+   * Redeem a reward: spends the customer's points and mints a one-time coupon
+   * that applies at checkout (requires customerToken). Only available in
+   * storefront mode.
+   *
+   * @example
+   * ```typescript
+   * const { couponCode, pointsBalance } = await client.redeemLoyaltyReward('rw_123');
+   * // apply couponCode to the cart at checkout
+   * ```
+   */
+  async redeemLoyaltyReward(rewardId) {
+    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/redeem", { rewardId });
+    }
+    throw new BrainerceError("redeemLoyaltyReward 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.39.0",
+  "version": "1.42.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",