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

brainerce 1.37.3 → 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

@@ -3361,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)).

package/dist/index.d.mts CHANGED Viewed

@@ -5306,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;
@@ -5491,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

@@ -5306,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;
@@ -5491,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.3",
+  "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",