npm - brainerce - Versions diffs - 1.37.2 → 1.38.0 - Mend

brainerce 1.37.2 → 1.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -2050,8 +2050,11 @@ const checkout = await client.createCheckout({
 ```
 > The region is recorded on the checkout and used for payment-provider scoping.
-> Currency continues to follow the cart until FX price conversion lands, so
-> passing a `regionId` does not re-price the cart.
+> **FX-at-checkout:** when the region currency differs from the store base and its
+> provider can settle it (presentment-enabled — Stripe today), the buyer is charged
+> in the region currency and the checkout response carries a `presentment` overlay
+> (`presentment.total` / `presentment.currency` = what's charged). Otherwise the
+> checkout is charged in the store base currency.
 #### Region display pricing (`getProducts({ regionId })`)
@@ -3358,6 +3361,51 @@ console.log(store.language); // 'en', 'he', etc.
 ---
+### Traffic Analytics (built-in, no GA4 needed)
+Brainerce has a **native cookieless analytics pipeline** — visits, visitors, countries, sources, devices, conversion funnel — visible in the merchant dashboard under **Dashboard → Traffic**. You don't need GA4, Meta Pixel, or any third-party script.
+**Option A — Script tag (recommended, zero JS):**
+Add one line to your root layout `<head>`:
+```html
+<!-- Vibe-coded (salesChannelId) mode -->
+<script defer src="https://api.brainerce.com/t.js" data-channel="vc_abc123"></script>
+<!-- storeId mode -->
+<script defer src="https://api.brainerce.com/t.js" data-store-id="your_store_id"></script>
+```
+The pixel auto-tracks pageviews on load and on every SPA route change, de-dupes consecutive identical paths, and measures active dwell time. Scaffolds from `create-brainerce-store ≥ 1.50` include it automatically.
+**Option B — SDK method (JS import, same endpoint):**
+```typescript
+// Basic pageview — call this on route changes if you're not using t.js
+client.trackEvent({ eventType: 'pageview', path: '/products/shoes' });
+// With UTM attribution (from URL params)
+const params = new URLSearchParams(window.location.search);
+client.trackEvent({
+  path: window.location.pathname,
+  utmSource:   params.get('utm_source')   ?? undefined,
+  utmMedium:   params.get('utm_medium')   ?? undefined,
+  utmCampaign: params.get('utm_campaign') ?? undefined,
+  screenWidth: window.innerWidth,
+  lang: navigator.language,
+});
+// Engagement dwell time (send on route change or pagehide)
+client.trackEvent({ eventType: 'engagement', path: '/products/shoes', engagedMs: 12000 });
+```
+> `trackEvent()` is fire-and-forget — errors are silently swallowed so a failed beacon never breaks your storefront. Available in `salesChannelId` and `storeId` modes.
+**Privacy:** cookieless, no PII stored. The visitor IP is resolved to a country server-side and then discarded. No cookie-consent banner required under GDPR/ePrivacy.
+---
 ## Admin API Reference
 > ⛔ **Server-side only.** The `apiKey` (`brainerce_*`) is a privileged secret — NEVER put it in browser code, client bundles, or any code that ships to the user's machine. It belongs in an environment variable on your server. For building the customer-facing storefront, use `salesChannelId` instead (see [Quick Start](#quick-start)).
@@ -3638,8 +3686,10 @@ const { region: resolved } = await store.getAutoRegion('DE'); // server-side, on
 > **Multi-region checkout:** pass a `regionId` to `createCheckout` to associate the
 > checkout with a region (for reporting + payment-provider scoping). The region
-> must belong to the store. Currency still follows the cart until FX price
-> conversion lands. See the Checkout section.
+> must belong to the store. **FX-at-checkout:** presentment-enabled regions
+> (Stripe today) charge in the region currency and return a `presentment` overlay;
+> otherwise the checkout is charged in the store base currency. See the Checkout
+> section.
 ### Price Lists (per-region pricing)

package/dist/index.d.mts CHANGED Viewed

@@ -2507,8 +2507,11 @@ interface Checkout {
     currency: string;
     /**
      * Region this checkout is associated with (multi-region commerce), or null.
-     * Recorded for reporting + provider scoping; currency follows the cart until
-     * FX price conversion lands.
+     * Recorded for reporting + provider scoping. FX-at-checkout: when the region
+     * currency differs from the store base and its provider can settle it
+     * (presentment-enabled — Stripe today), the buyer is charged in the region
+     * currency and the `presentment` overlay below carries the charged amounts;
+     * otherwise the checkout is charged in the store base currency.
      */
     regionId?: string | null;
     /** Subtotal as string - use parseFloat() */
@@ -2560,6 +2563,41 @@ interface Checkout {
      * @see ReservationInfo
      */
     reservation?: ReservationInfo;
+    /**
+     * FX-at-checkout presentment overlay. Present ONLY when the checkout's region
+     * uses a different currency from the store base AND that region charges in its
+     * own currency (presentment). These are the amounts the buyer will actually be
+     * CHARGED, in `presentment.currency` — `presentment.total` equals the payment
+     * intent amount to the cent. Render these (not the base `total`/`currency`
+     * above) when present. Absent = the checkout is charged in the store base
+     * currency (the fields above are authoritative).
+     *
+     * @example
+     * const c = await client.getCheckout(id);
+     * const shown = c.presentment
+     *   ? formatPrice(c.presentment.total, { currency: c.presentment.currency })
+     *   : formatPrice(c.total, { currency: c.currency });
+     */
+    presentment?: {
+        /** ISO-4217 currency the buyer is charged in (e.g. "EUR"). */
+        currency: string;
+        /** Subtotal in the presentment currency as string - use parseFloat(). */
+        subtotal: string;
+        /** Discount amount in the presentment currency as string. */
+        discountAmount: string;
+        /** Shipping cost in the presentment currency as string. */
+        shippingAmount: string;
+        /** Tax amount in the presentment currency as string. */
+        taxAmount: string;
+        /** Surcharge amount in the presentment currency as string. */
+        surchargeAmount: string;
+        /** Grand total in the presentment currency — equals the charged amount. */
+        total: string;
+        /** Base→presentment rate applied (buffer included), as string. */
+        fxChargingRate: string;
+        /** FX buffer percent applied to the mid-market rate, as string (or null). */
+        fxBufferPercent: string | null;
+    };
 }
 /**
  * Options for creating a checkout from a cart.
@@ -5268,6 +5306,30 @@ interface BlogPostListResponse {
         totalPages: number;
     };
 }
+/**
+ * Payload for `client.trackEvent()` — the programmatic counterpart to the
+ * `t.js` script-tag pixel. Every field is optional; the server degrades
+ * gracefully on missing values. Deliberately collects no PII: `path` is
+ * pathname-only, `referrer` is reduced to a hostname server-side, and the
+ * visitor IP is resolved to a country then discarded.
+ */
+interface TrackEventPayload {
+    /** `'pageview'` (default) or `'engagement'` (active dwell-time report). */
+    eventType?: 'pageview' | 'engagement';
+    /** `window.location.pathname` — no query string (intentional, avoids PII). */
+    path?: string;
+    /** `document.referrer` — full URL, reduced to hostname server-side. */
+    referrer?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    /** Viewport width in px — used for mobile/tablet/desktop classification. */
+    screenWidth?: number;
+    /** `navigator.language` — coarse locale hint for future breakdowns. */
+    lang?: string;
+    /** Active dwell time in ms. Only meaningful for `eventType: 'engagement'`. Max 1 800 000 (30 min). */
+    engagedMs?: number;
+}
 interface BrainerceApiError {
     statusCode: number;
     message: string;
@@ -5453,6 +5515,39 @@ declare class BrainerceClient {
      *   `'ltr'` for everything else (including unknown locales).
      */
     getStoreDirection(locale?: string | null): 'ltr' | 'rtl';
+    /**
+     * Send a storefront analytics beacon (pageview or engagement).
+     *
+     * This is the programmatic counterpart to the `t.js` script-tag pixel —
+     * use it when you prefer a JS import over a `<script>` tag, or when you
+     * need to fire events the auto-tracker doesn't cover.
+     *
+     * **If you're already loading `t.js`, you do NOT need this** — the pixel
+     * handles pageviews and SPA route changes automatically.
+     *
+     * The call is fire-and-forget: errors are swallowed so a failed beacon
+     * never breaks your storefront. Available in `salesChannelId` and `storeId`
+     * modes; silently skipped in admin mode (server-to-server beacons are
+     * meaningless without a real browser session).
+     *
+     * @example
+     * ```typescript
+     * // Basic pageview (equivalent to what t.js sends automatically)
+     * client.trackEvent({ eventType: 'pageview', path: '/products/shoes' });
+     *
+     * // With UTM attribution
+     * client.trackEvent({
+     *   path: '/products/shoes',
+     *   utmSource: 'newsletter',
+     *   utmMedium: 'email',
+     *   utmCampaign: 'summer-sale',
+     * });
+     *
+     * // Engagement (active dwell time in ms — send on route change or pagehide)
+     * client.trackEvent({ eventType: 'engagement', path: '/products/shoes', engagedMs: 12000 });
+     * ```
+     */
+    trackEvent(payload?: TrackEventPayload): Promise<void>;
     /**
      * Get a list of products with pagination and filtering
      * Works in vibe-coded, storefront (public), and admin mode

package/dist/index.d.ts CHANGED Viewed

@@ -2507,8 +2507,11 @@ interface Checkout {
     currency: string;
     /**
      * Region this checkout is associated with (multi-region commerce), or null.
-     * Recorded for reporting + provider scoping; currency follows the cart until
-     * FX price conversion lands.
+     * Recorded for reporting + provider scoping. FX-at-checkout: when the region
+     * currency differs from the store base and its provider can settle it
+     * (presentment-enabled — Stripe today), the buyer is charged in the region
+     * currency and the `presentment` overlay below carries the charged amounts;
+     * otherwise the checkout is charged in the store base currency.
      */
     regionId?: string | null;
     /** Subtotal as string - use parseFloat() */
@@ -2560,6 +2563,41 @@ interface Checkout {
      * @see ReservationInfo
      */
     reservation?: ReservationInfo;
+    /**
+     * FX-at-checkout presentment overlay. Present ONLY when the checkout's region
+     * uses a different currency from the store base AND that region charges in its
+     * own currency (presentment). These are the amounts the buyer will actually be
+     * CHARGED, in `presentment.currency` — `presentment.total` equals the payment
+     * intent amount to the cent. Render these (not the base `total`/`currency`
+     * above) when present. Absent = the checkout is charged in the store base
+     * currency (the fields above are authoritative).
+     *
+     * @example
+     * const c = await client.getCheckout(id);
+     * const shown = c.presentment
+     *   ? formatPrice(c.presentment.total, { currency: c.presentment.currency })
+     *   : formatPrice(c.total, { currency: c.currency });
+     */
+    presentment?: {
+        /** ISO-4217 currency the buyer is charged in (e.g. "EUR"). */
+        currency: string;
+        /** Subtotal in the presentment currency as string - use parseFloat(). */
+        subtotal: string;
+        /** Discount amount in the presentment currency as string. */
+        discountAmount: string;
+        /** Shipping cost in the presentment currency as string. */
+        shippingAmount: string;
+        /** Tax amount in the presentment currency as string. */
+        taxAmount: string;
+        /** Surcharge amount in the presentment currency as string. */
+        surchargeAmount: string;
+        /** Grand total in the presentment currency — equals the charged amount. */
+        total: string;
+        /** Base→presentment rate applied (buffer included), as string. */
+        fxChargingRate: string;
+        /** FX buffer percent applied to the mid-market rate, as string (or null). */
+        fxBufferPercent: string | null;
+    };
 }
 /**
  * Options for creating a checkout from a cart.
@@ -5268,6 +5306,30 @@ interface BlogPostListResponse {
         totalPages: number;
     };
 }
+/**
+ * Payload for `client.trackEvent()` — the programmatic counterpart to the
+ * `t.js` script-tag pixel. Every field is optional; the server degrades
+ * gracefully on missing values. Deliberately collects no PII: `path` is
+ * pathname-only, `referrer` is reduced to a hostname server-side, and the
+ * visitor IP is resolved to a country then discarded.
+ */
+interface TrackEventPayload {
+    /** `'pageview'` (default) or `'engagement'` (active dwell-time report). */
+    eventType?: 'pageview' | 'engagement';
+    /** `window.location.pathname` — no query string (intentional, avoids PII). */
+    path?: string;
+    /** `document.referrer` — full URL, reduced to hostname server-side. */
+    referrer?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    /** Viewport width in px — used for mobile/tablet/desktop classification. */
+    screenWidth?: number;
+    /** `navigator.language` — coarse locale hint for future breakdowns. */
+    lang?: string;
+    /** Active dwell time in ms. Only meaningful for `eventType: 'engagement'`. Max 1 800 000 (30 min). */
+    engagedMs?: number;
+}
 interface BrainerceApiError {
     statusCode: number;
     message: string;
@@ -5453,6 +5515,39 @@ declare class BrainerceClient {
      *   `'ltr'` for everything else (including unknown locales).
      */
     getStoreDirection(locale?: string | null): 'ltr' | 'rtl';
+    /**
+     * Send a storefront analytics beacon (pageview or engagement).
+     *
+     * This is the programmatic counterpart to the `t.js` script-tag pixel —
+     * use it when you prefer a JS import over a `<script>` tag, or when you
+     * need to fire events the auto-tracker doesn't cover.
+     *
+     * **If you're already loading `t.js`, you do NOT need this** — the pixel
+     * handles pageviews and SPA route changes automatically.
+     *
+     * The call is fire-and-forget: errors are swallowed so a failed beacon
+     * never breaks your storefront. Available in `salesChannelId` and `storeId`
+     * modes; silently skipped in admin mode (server-to-server beacons are
+     * meaningless without a real browser session).
+     *
+     * @example
+     * ```typescript
+     * // Basic pageview (equivalent to what t.js sends automatically)
+     * client.trackEvent({ eventType: 'pageview', path: '/products/shoes' });
+     *
+     * // With UTM attribution
+     * client.trackEvent({
+     *   path: '/products/shoes',
+     *   utmSource: 'newsletter',
+     *   utmMedium: 'email',
+     *   utmCampaign: 'summer-sale',
+     * });
+     *
+     * // Engagement (active dwell time in ms — send on route change or pagehide)
+     * client.trackEvent({ eventType: 'engagement', path: '/products/shoes', engagedMs: 12000 });
+     * ```
+     */
+    trackEvent(payload?: TrackEventPayload): Promise<void>;
     /**
      * Get a list of products with pagination and filtering
      * Works in vibe-coded, storefront (public), and admin mode

package/dist/index.js CHANGED Viewed

@@ -1072,6 +1072,49 @@ var BrainerceClient = class {
   getStoreDirection(locale) {
     return getDirectionForLocale(locale ?? this.locale);
   }
+  // -------------------- Analytics --------------------
+  /**
+   * Send a storefront analytics beacon (pageview or engagement).
+   *
+   * This is the programmatic counterpart to the `t.js` script-tag pixel —
+   * use it when you prefer a JS import over a `<script>` tag, or when you
+   * need to fire events the auto-tracker doesn't cover.
+   *
+   * **If you're already loading `t.js`, you do NOT need this** — the pixel
+   * handles pageviews and SPA route changes automatically.
+   *
+   * The call is fire-and-forget: errors are swallowed so a failed beacon
+   * never breaks your storefront. Available in `salesChannelId` and `storeId`
+   * modes; silently skipped in admin mode (server-to-server beacons are
+   * meaningless without a real browser session).
+   *
+   * @example
+   * ```typescript
+   * // Basic pageview (equivalent to what t.js sends automatically)
+   * client.trackEvent({ eventType: 'pageview', path: '/products/shoes' });
+   *
+   * // With UTM attribution
+   * client.trackEvent({
+   *   path: '/products/shoes',
+   *   utmSource: 'newsletter',
+   *   utmMedium: 'email',
+   *   utmCampaign: 'summer-sale',
+   * });
+   *
+   * // Engagement (active dwell time in ms — send on route change or pagehide)
+   * client.trackEvent({ eventType: 'engagement', path: '/products/shoes', engagedMs: 12000 });
+   * ```
+   */
+  async trackEvent(payload = {}) {
+    try {
+      if (this.isVibeCodedMode()) {
+        await this.vibeCodedRequest("POST", "/events", payload);
+      } else if (this.isStorefrontMode()) {
+        await this.storefrontRequest("POST", "/events", payload);
+      }
+    } catch {
+    }
+  }
   // -------------------- Products --------------------
   /**
    * Get a list of products with pagination and filtering

package/dist/index.mjs CHANGED Viewed

@@ -1002,6 +1002,49 @@ var BrainerceClient = class {
   getStoreDirection(locale) {
     return getDirectionForLocale(locale ?? this.locale);
   }
+  // -------------------- Analytics --------------------
+  /**
+   * Send a storefront analytics beacon (pageview or engagement).
+   *
+   * This is the programmatic counterpart to the `t.js` script-tag pixel —
+   * use it when you prefer a JS import over a `<script>` tag, or when you
+   * need to fire events the auto-tracker doesn't cover.
+   *
+   * **If you're already loading `t.js`, you do NOT need this** — the pixel
+   * handles pageviews and SPA route changes automatically.
+   *
+   * The call is fire-and-forget: errors are swallowed so a failed beacon
+   * never breaks your storefront. Available in `salesChannelId` and `storeId`
+   * modes; silently skipped in admin mode (server-to-server beacons are
+   * meaningless without a real browser session).
+   *
+   * @example
+   * ```typescript
+   * // Basic pageview (equivalent to what t.js sends automatically)
+   * client.trackEvent({ eventType: 'pageview', path: '/products/shoes' });
+   *
+   * // With UTM attribution
+   * client.trackEvent({
+   *   path: '/products/shoes',
+   *   utmSource: 'newsletter',
+   *   utmMedium: 'email',
+   *   utmCampaign: 'summer-sale',
+   * });
+   *
+   * // Engagement (active dwell time in ms — send on route change or pagehide)
+   * client.trackEvent({ eventType: 'engagement', path: '/products/shoes', engagedMs: 12000 });
+   * ```
+   */
+  async trackEvent(payload = {}) {
+    try {
+      if (this.isVibeCodedMode()) {
+        await this.vibeCodedRequest("POST", "/events", payload);
+      } else if (this.isStorefrontMode()) {
+        await this.storefrontRequest("POST", "/events", payload);
+      }
+    } catch {
+    }
+  }
   // -------------------- Products --------------------
   /**
    * Get a list of products with pagination and filtering

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.37.2",
+  "version": "1.38.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",