brainerce 1.56.0 → 1.57.0

package/README.md

@@ -2457,6 +2457,10 @@ const checkout = await client.setCheckoutCustomer(checkoutId, {
   notes: 'Please leave the package at the door', // Optional order note (max 2000 chars)
   // analyticsClientId / analyticsSessionId: auto-attached if you called
   // loadGoogleAnalytics() — no need to pass these yourself.
+  // trafficReferrerHost / trafficUtm*: auto-attached from the SDK's own
+  // traffic-attribution capture (external referrer + utm, 30-day window) so
+  // the dashboard can report "orders from ChatGPT / Google / …". Nothing to
+  // wire up; pass explicitly only to override.
 });
 ```
 
@@ -4094,6 +4098,15 @@ const cart = await client.createCart();
 await client.addToCart(cart.id, { productId: 'prod_abc', quantity: 1 });
 ```
 
+### Traffic attribution (automatic, zero-config)
+
+The SDK also records where each visit came from — the external referrer host
+and any `utm_source`/`utm_medium`/`utm_campaign` — as a **last non-direct
+touch** (`brainerce_attr` in localStorage, 30-day window). The captured values
+are auto-attached to `setCheckoutCustomer()` / `setShippingAddress()` and end
+up on the order, powering the dashboard's "orders from ChatGPT / Google / …"
+reporting. Nothing to configure; a value you pass explicitly always wins.
+
 What this does:
 
 - Idempotently injects `gtag.js` and initializes `dataLayer` (skips injection if you're already loading `gtag.js` yourself — safe to call either way).

package/dist/index.d.mts

@@ -3294,6 +3294,16 @@ interface SetCheckoutCustomerDto {
      */
     analyticsClientId?: string;
     analyticsSessionId?: string;
+    /**
+     * Traffic attribution (last non-direct touch) — auto-attached by the SDK
+     * from its `brainerce_attr` capture (external referrer host + utm params,
+     * 30-day window). Lets the dashboard report "orders from ChatGPT/Google/…".
+     * Pass explicitly to override; omit to use the captured values.
+     */
+    trafficReferrerHost?: string;
+    trafficUtmSource?: string;
+    trafficUtmMedium?: string;
+    trafficUtmCampaign?: string;
 }
 /**
  * Shipping address with customer email (required for checkout).
@@ -3327,6 +3337,16 @@ interface SetShippingAddressDto {
      */
     analyticsClientId?: string;
     analyticsSessionId?: string;
+    /**
+     * Traffic attribution (last non-direct touch) — auto-attached by the SDK
+     * from its `brainerce_attr` capture (external referrer host + utm params,
+     * 30-day window). Lets the dashboard report "orders from ChatGPT/Google/…".
+     * Pass explicitly to override; omit to use the captured values.
+     */
+    trafficReferrerHost?: string;
+    trafficUtmSource?: string;
+    trafficUtmMedium?: string;
+    trafficUtmCampaign?: string;
     /**
      * The `placeId` of the autocomplete suggestion the shopper picked (from
      * `addressAutocomplete()`). Send it whenever the address came from the
@@ -6847,6 +6867,26 @@ declare class BrainerceClient {
      * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
      * called, or if it hasn't resolved any ids by the time this is awaited.
      */
+    /** localStorage key holding the last non-direct-touch attribution blob. */
+    private readonly TRAFFIC_ATTR_KEY;
+    /** Attribution older than this is stale and never forwarded (classic 30-day window). */
+    private static readonly TRAFFIC_ATTR_MAX_AGE_MS;
+    /**
+     * Record the visit's traffic origin — LAST NON-DIRECT TOUCH semantics: an
+     * external referrer or any utm_source overwrites the stored blob; a direct
+     * or internal navigation keeps the previous touch. Runs once per client
+     * construction (i.e. per page load in browser storefronts) and must never
+     * throw — attribution is telemetry, the storefront always wins.
+     */
+    private captureTrafficAttribution;
+    /** The stored attribution as request-body fields, or null when absent/stale. */
+    private getTrafficAttribution;
+    /**
+     * Merge the stored traffic attribution onto a request body — only for
+     * fields the caller didn't set explicitly (explicit values always win),
+     * mirroring `withAnalyticsStitchIds`. No-op outside the browser.
+     */
+    private withTrafficAttribution;
     private withAnalyticsStitchIds;
     /**
      * Drop the fields `getAddressDetails()` returns that no address endpoint

package/dist/index.d.ts

@@ -3294,6 +3294,16 @@ interface SetCheckoutCustomerDto {
      */
     analyticsClientId?: string;
     analyticsSessionId?: string;
+    /**
+     * Traffic attribution (last non-direct touch) — auto-attached by the SDK
+     * from its `brainerce_attr` capture (external referrer host + utm params,
+     * 30-day window). Lets the dashboard report "orders from ChatGPT/Google/…".
+     * Pass explicitly to override; omit to use the captured values.
+     */
+    trafficReferrerHost?: string;
+    trafficUtmSource?: string;
+    trafficUtmMedium?: string;
+    trafficUtmCampaign?: string;
 }
 /**
  * Shipping address with customer email (required for checkout).
@@ -3327,6 +3337,16 @@ interface SetShippingAddressDto {
      */
     analyticsClientId?: string;
     analyticsSessionId?: string;
+    /**
+     * Traffic attribution (last non-direct touch) — auto-attached by the SDK
+     * from its `brainerce_attr` capture (external referrer host + utm params,
+     * 30-day window). Lets the dashboard report "orders from ChatGPT/Google/…".
+     * Pass explicitly to override; omit to use the captured values.
+     */
+    trafficReferrerHost?: string;
+    trafficUtmSource?: string;
+    trafficUtmMedium?: string;
+    trafficUtmCampaign?: string;
     /**
      * The `placeId` of the autocomplete suggestion the shopper picked (from
      * `addressAutocomplete()`). Send it whenever the address came from the
@@ -6847,6 +6867,26 @@ declare class BrainerceClient {
      * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
      * called, or if it hasn't resolved any ids by the time this is awaited.
      */
+    /** localStorage key holding the last non-direct-touch attribution blob. */
+    private readonly TRAFFIC_ATTR_KEY;
+    /** Attribution older than this is stale and never forwarded (classic 30-day window). */
+    private static readonly TRAFFIC_ATTR_MAX_AGE_MS;
+    /**
+     * Record the visit's traffic origin — LAST NON-DIRECT TOUCH semantics: an
+     * external referrer or any utm_source overwrites the stored blob; a direct
+     * or internal navigation keeps the previous touch. Runs once per client
+     * construction (i.e. per page load in browser storefronts) and must never
+     * throw — attribution is telemetry, the storefront always wins.
+     */
+    private captureTrafficAttribution;
+    /** The stored attribution as request-body fields, or null when absent/stale. */
+    private getTrafficAttribution;
+    /**
+     * Merge the stored traffic attribution onto a request body — only for
+     * fields the caller didn't set explicitly (explicit values always win),
+     * mirroring `withAnalyticsStitchIds`. No-op outside the browser.
+     */
+    private withTrafficAttribution;
     private withAnalyticsStitchIds;
     /**
      * Drop the fields `getAddressDetails()` returns that no address endpoint

package/dist/index.js

@@ -299,6 +299,14 @@ var _BrainerceClient = class _BrainerceClient {
      * This is needed because Stripe redirects lose in-memory state.
      */
     this.ACTIVE_CHECKOUT_KEY = "brainerce_active_checkout";
+    /**
+     * Merge the resolved GA4 stitch ids onto a request body — only for fields
+     * the caller didn't already set explicitly (explicit values always win).
+     * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
+     * called, or if it hasn't resolved any ids by the time this is awaited.
+     */
+    /** localStorage key holding the last non-direct-touch attribution blob. */
+    this.TRAFFIC_ATTR_KEY = "brainerce_attr";
     // -------------------- Contact Forms (schema) --------------------
     /**
      * List active contact forms configured for the store.
@@ -704,6 +712,7 @@ var _BrainerceClient = class _BrainerceClient {
     this.onCartReset = options.onCartReset;
     this.hydrateSessionCart();
     this.detectRecoverCartFromUrl();
+    this.captureTrafficAttribution();
   }
   // -------------------- Locale --------------------
   /**
@@ -1526,11 +1535,82 @@ var _BrainerceClient = class _BrainerceClient {
     }
   }
   /**
-   * Merge the resolved GA4 stitch ids onto a request body — only for fields
-   * the caller didn't already set explicitly (explicit values always win).
-   * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
-   * called, or if it hasn't resolved any ids by the time this is awaited.
+   * Record the visit's traffic origin — LAST NON-DIRECT TOUCH semantics: an
+   * external referrer or any utm_source overwrites the stored blob; a direct
+   * or internal navigation keeps the previous touch. Runs once per client
+   * construction (i.e. per page load in browser storefronts) and must never
+   * throw — attribution is telemetry, the storefront always wins.
+   */
+  captureTrafficAttribution() {
+    try {
+      if (typeof window === "undefined" || !window.localStorage) return;
+      const params = new URLSearchParams(window.location.search);
+      const utmSource = params.get("utm_source") || void 0;
+      const utmMedium = params.get("utm_medium") || void 0;
+      const utmCampaign = params.get("utm_campaign") || void 0;
+      let referrerHost;
+      if (document.referrer) {
+        try {
+          const ref = new URL(document.referrer);
+          if (ref.hostname && ref.hostname !== window.location.hostname) {
+            referrerHost = ref.hostname.toLowerCase().replace(/^www\./, "");
+          }
+        } catch {
+        }
+      }
+      if (!referrerHost && !utmSource) return;
+      window.localStorage.setItem(
+        this.TRAFFIC_ATTR_KEY,
+        JSON.stringify({ referrerHost, utmSource, utmMedium, utmCampaign, at: Date.now() })
+      );
+    } catch {
+    }
+  }
+  /** The stored attribution as request-body fields, or null when absent/stale. */
+  getTrafficAttribution() {
+    try {
+      if (typeof window === "undefined" || !window.localStorage) return null;
+      const raw = window.localStorage.getItem(this.TRAFFIC_ATTR_KEY);
+      if (!raw) return null;
+      const blob = JSON.parse(raw);
+      if (!blob || typeof blob !== "object") return null;
+      if (typeof blob.at !== "number" || Date.now() - blob.at > _BrainerceClient.TRAFFIC_ATTR_MAX_AGE_MS) {
+        return null;
+      }
+      const out = {};
+      if (typeof blob.referrerHost === "string" && blob.referrerHost) {
+        out.trafficReferrerHost = blob.referrerHost.slice(0, 253);
+      }
+      if (typeof blob.utmSource === "string" && blob.utmSource) {
+        out.trafficUtmSource = blob.utmSource.slice(0, 150);
+      }
+      if (typeof blob.utmMedium === "string" && blob.utmMedium) {
+        out.trafficUtmMedium = blob.utmMedium.slice(0, 150);
+      }
+      if (typeof blob.utmCampaign === "string" && blob.utmCampaign) {
+        out.trafficUtmCampaign = blob.utmCampaign.slice(0, 150);
+      }
+      return Object.keys(out).length > 0 ? out : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Merge the stored traffic attribution onto a request body — only for
+   * fields the caller didn't set explicitly (explicit values always win),
+   * mirroring `withAnalyticsStitchIds`. No-op outside the browser.
    */
+  withTrafficAttribution(dto) {
+    const attr = this.getTrafficAttribution();
+    if (!attr) return dto;
+    return {
+      ...dto ?? {},
+      trafficReferrerHost: dto?.trafficReferrerHost ?? attr.trafficReferrerHost,
+      trafficUtmSource: dto?.trafficUtmSource ?? attr.trafficUtmSource,
+      trafficUtmMedium: dto?.trafficUtmMedium ?? attr.trafficUtmMedium,
+      trafficUtmCampaign: dto?.trafficUtmCampaign ?? attr.trafficUtmCampaign
+    };
+  }
   async withAnalyticsStitchIds(dto) {
     if (!this._ga4StitchPromise) return dto;
     try {
@@ -5387,7 +5467,7 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setCheckoutCustomer(checkoutId, data) {
-    const body = await this.withAnalyticsStitchIds(data);
+    const body = this.withTrafficAttribution(await this.withAnalyticsStitchIds(data));
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -5489,7 +5569,9 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setShippingAddress(checkoutId, address) {
-    const body = await this.withAnalyticsStitchIds(this.stripResolvedOnlyAddressFields(address));
+    const body = this.withTrafficAttribution(
+      await this.withAnalyticsStitchIds(this.stripResolvedOnlyAddressFields(address))
+    );
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -9716,6 +9798,8 @@ _BrainerceClient.RESOLVED_ONLY_ADDRESS_FIELDS = [
   "lng",
   "formattedAddress"
 ];
+/** Attribution older than this is stale and never forwarded (classic 30-day window). */
+_BrainerceClient.TRAFFIC_ATTR_MAX_AGE_MS = 30 * 24 * 3600 * 1e3;
 var BrainerceClient = _BrainerceClient;
 var BrainerceError = class extends Error {
   constructor(message, statusCode, details) {

package/dist/index.mjs

@@ -212,6 +212,14 @@ var _BrainerceClient = class _BrainerceClient {
      * This is needed because Stripe redirects lose in-memory state.
      */
     this.ACTIVE_CHECKOUT_KEY = "brainerce_active_checkout";
+    /**
+     * Merge the resolved GA4 stitch ids onto a request body — only for fields
+     * the caller didn't already set explicitly (explicit values always win).
+     * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
+     * called, or if it hasn't resolved any ids by the time this is awaited.
+     */
+    /** localStorage key holding the last non-direct-touch attribution blob. */
+    this.TRAFFIC_ATTR_KEY = "brainerce_attr";
     // -------------------- Contact Forms (schema) --------------------
     /**
      * List active contact forms configured for the store.
@@ -617,6 +625,7 @@ var _BrainerceClient = class _BrainerceClient {
     this.onCartReset = options.onCartReset;
     this.hydrateSessionCart();
     this.detectRecoverCartFromUrl();
+    this.captureTrafficAttribution();
   }
   // -------------------- Locale --------------------
   /**
@@ -1439,11 +1448,82 @@ var _BrainerceClient = class _BrainerceClient {
     }
   }
   /**
-   * Merge the resolved GA4 stitch ids onto a request body — only for fields
-   * the caller didn't already set explicitly (explicit values always win).
-   * No-op (returns `dto` unchanged) if `loadGoogleAnalytics()` was never
-   * called, or if it hasn't resolved any ids by the time this is awaited.
+   * Record the visit's traffic origin — LAST NON-DIRECT TOUCH semantics: an
+   * external referrer or any utm_source overwrites the stored blob; a direct
+   * or internal navigation keeps the previous touch. Runs once per client
+   * construction (i.e. per page load in browser storefronts) and must never
+   * throw — attribution is telemetry, the storefront always wins.
+   */
+  captureTrafficAttribution() {
+    try {
+      if (typeof window === "undefined" || !window.localStorage) return;
+      const params = new URLSearchParams(window.location.search);
+      const utmSource = params.get("utm_source") || void 0;
+      const utmMedium = params.get("utm_medium") || void 0;
+      const utmCampaign = params.get("utm_campaign") || void 0;
+      let referrerHost;
+      if (document.referrer) {
+        try {
+          const ref = new URL(document.referrer);
+          if (ref.hostname && ref.hostname !== window.location.hostname) {
+            referrerHost = ref.hostname.toLowerCase().replace(/^www\./, "");
+          }
+        } catch {
+        }
+      }
+      if (!referrerHost && !utmSource) return;
+      window.localStorage.setItem(
+        this.TRAFFIC_ATTR_KEY,
+        JSON.stringify({ referrerHost, utmSource, utmMedium, utmCampaign, at: Date.now() })
+      );
+    } catch {
+    }
+  }
+  /** The stored attribution as request-body fields, or null when absent/stale. */
+  getTrafficAttribution() {
+    try {
+      if (typeof window === "undefined" || !window.localStorage) return null;
+      const raw = window.localStorage.getItem(this.TRAFFIC_ATTR_KEY);
+      if (!raw) return null;
+      const blob = JSON.parse(raw);
+      if (!blob || typeof blob !== "object") return null;
+      if (typeof blob.at !== "number" || Date.now() - blob.at > _BrainerceClient.TRAFFIC_ATTR_MAX_AGE_MS) {
+        return null;
+      }
+      const out = {};
+      if (typeof blob.referrerHost === "string" && blob.referrerHost) {
+        out.trafficReferrerHost = blob.referrerHost.slice(0, 253);
+      }
+      if (typeof blob.utmSource === "string" && blob.utmSource) {
+        out.trafficUtmSource = blob.utmSource.slice(0, 150);
+      }
+      if (typeof blob.utmMedium === "string" && blob.utmMedium) {
+        out.trafficUtmMedium = blob.utmMedium.slice(0, 150);
+      }
+      if (typeof blob.utmCampaign === "string" && blob.utmCampaign) {
+        out.trafficUtmCampaign = blob.utmCampaign.slice(0, 150);
+      }
+      return Object.keys(out).length > 0 ? out : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Merge the stored traffic attribution onto a request body — only for
+   * fields the caller didn't set explicitly (explicit values always win),
+   * mirroring `withAnalyticsStitchIds`. No-op outside the browser.
    */
+  withTrafficAttribution(dto) {
+    const attr = this.getTrafficAttribution();
+    if (!attr) return dto;
+    return {
+      ...dto ?? {},
+      trafficReferrerHost: dto?.trafficReferrerHost ?? attr.trafficReferrerHost,
+      trafficUtmSource: dto?.trafficUtmSource ?? attr.trafficUtmSource,
+      trafficUtmMedium: dto?.trafficUtmMedium ?? attr.trafficUtmMedium,
+      trafficUtmCampaign: dto?.trafficUtmCampaign ?? attr.trafficUtmCampaign
+    };
+  }
   async withAnalyticsStitchIds(dto) {
     if (!this._ga4StitchPromise) return dto;
     try {
@@ -5300,7 +5380,7 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setCheckoutCustomer(checkoutId, data) {
-    const body = await this.withAnalyticsStitchIds(data);
+    const body = this.withTrafficAttribution(await this.withAnalyticsStitchIds(data));
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -5402,7 +5482,9 @@ var _BrainerceClient = class _BrainerceClient {
    * ```
    */
   async setShippingAddress(checkoutId, address) {
-    const body = await this.withAnalyticsStitchIds(this.stripResolvedOnlyAddressFields(address));
+    const body = this.withTrafficAttribution(
+      await this.withAnalyticsStitchIds(this.stripResolvedOnlyAddressFields(address))
+    );
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest(
         "PATCH",
@@ -9629,6 +9711,8 @@ _BrainerceClient.RESOLVED_ONLY_ADDRESS_FIELDS = [
   "lng",
   "formattedAddress"
 ];
+/** Attribution older than this is stale and never forwarded (classic 30-day window). */
+_BrainerceClient.TRAFFIC_ATTR_MAX_AGE_MS = 30 * 24 * 3600 * 1e3;
 var BrainerceClient = _BrainerceClient;
 var BrainerceError = class extends Error {
   constructor(message, statusCode, details) {

package/package.json

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