@tracelog/lib 2.1.0-rc.74.5 → 2.1.1-rc.75.2

package/dist/public-api.d.mts

@@ -688,6 +688,8 @@ interface State {
     hasStartSession: boolean;
     suppressNextScroll: boolean;
     scrollEventCount?: number;
+    sessionReferrer?: string;
+    sessionUtm?: UTM;
 }
 
 /**
@@ -1613,58 +1615,6 @@ declare class EventManager extends StateManager {
      * @internal
      */
     private cleanupExpiredSessionCounts;
-    /**
-     * Returns the referrer if it's external, or 'Direct' if internal/empty.
-     *
-     * **Purpose**: Filter out internal referrers (same domain) to ensure
-     * accurate traffic source attribution. Internal referrers occur when:
-     * - Session expires and user navigates within the same site
-     * - User opens new tab from an internal link
-     * - Page refresh after session timeout
-     *
-     * **Logic**:
-     * - Empty referrer → 'Direct'
-     * - Referrer from same domain or subdomain → 'Direct' (internal navigation)
-     * - External referrer → Returns original referrer
-     *
-     * **Subdomain Detection**:
-     * - `www.example.com` → `example.com` ✓ (internal)
-     * - `blog.example.com` → `example.com` ✓ (internal)
-     * - `example.com` → `www.example.com` ✓ (internal)
-     *
-     * @returns External referrer URL or 'Direct'
-     *
-     * @internal
-     */
-    private getExternalReferrer;
-    /**
-     * Checks if two hostnames belong to the same domain (including subdomains).
-     * Extracts root domain and compares to handle cross-subdomain navigation.
-     *
-     * @example
-     * isSameDomain('www.example.com', 'example.com') // true
-     * isSameDomain('app.example.com', 'www.example.com') // true
-     * isSameDomain('example.co.uk', 'app.example.co.uk') // true
-     *
-     * @param hostname1 - First hostname (e.g., 'www.example.com')
-     * @param hostname2 - Second hostname (e.g., 'app.example.com')
-     * @returns true if same root domain
-     *
-     * @internal
-     */
-    private isSameDomain;
-    /**
-     * Extracts the root (registrable) domain from a hostname.
-     * Handles both standard TLDs (.com, .org) and compound TLDs (.co.uk, .com.br).
-     *
-     * @example
-     * getRootDomain('www.example.com') // 'example.com'
-     * getRootDomain('app.blog.example.com') // 'example.com'
-     * getRootDomain('shop.example.co.uk') // 'example.co.uk'
-     *
-     * @internal
-     */
-    private getRootDomain;
     /**
      * Persists current session event counts to localStorage (debounced).
      *

package/dist/public-api.d.ts

@@ -688,6 +688,8 @@ interface State {
     hasStartSession: boolean;
     suppressNextScroll: boolean;
     scrollEventCount?: number;
+    sessionReferrer?: string;
+    sessionUtm?: UTM;
 }
 
 /**
@@ -1613,58 +1615,6 @@ declare class EventManager extends StateManager {
      * @internal
      */
     private cleanupExpiredSessionCounts;
-    /**
-     * Returns the referrer if it's external, or 'Direct' if internal/empty.
-     *
-     * **Purpose**: Filter out internal referrers (same domain) to ensure
-     * accurate traffic source attribution. Internal referrers occur when:
-     * - Session expires and user navigates within the same site
-     * - User opens new tab from an internal link
-     * - Page refresh after session timeout
-     *
-     * **Logic**:
-     * - Empty referrer → 'Direct'
-     * - Referrer from same domain or subdomain → 'Direct' (internal navigation)
-     * - External referrer → Returns original referrer
-     *
-     * **Subdomain Detection**:
-     * - `www.example.com` → `example.com` ✓ (internal)
-     * - `blog.example.com` → `example.com` ✓ (internal)
-     * - `example.com` → `www.example.com` ✓ (internal)
-     *
-     * @returns External referrer URL or 'Direct'
-     *
-     * @internal
-     */
-    private getExternalReferrer;
-    /**
-     * Checks if two hostnames belong to the same domain (including subdomains).
-     * Extracts root domain and compares to handle cross-subdomain navigation.
-     *
-     * @example
-     * isSameDomain('www.example.com', 'example.com') // true
-     * isSameDomain('app.example.com', 'www.example.com') // true
-     * isSameDomain('example.co.uk', 'app.example.co.uk') // true
-     *
-     * @param hostname1 - First hostname (e.g., 'www.example.com')
-     * @param hostname2 - Second hostname (e.g., 'app.example.com')
-     * @returns true if same root domain
-     *
-     * @internal
-     */
-    private isSameDomain;
-    /**
-     * Extracts the root (registrable) domain from a hostname.
-     * Handles both standard TLDs (.com, .org) and compound TLDs (.co.uk, .com.br).
-     *
-     * @example
-     * getRootDomain('www.example.com') // 'example.com'
-     * getRootDomain('app.blog.example.com') // 'example.com'
-     * getRootDomain('shop.example.co.uk') // 'example.co.uk'
-     *
-     * @internal
-     */
-    private getRootDomain;
     /**
      * Persists current session event counts to localStorage (debounced).
      *

package/dist/public-api.js

@@ -718,7 +718,7 @@ var init_performance_constants = __esm({
 var version;
 var init_package = __esm({
   "package.json"() {
-    version = "2.1.0";
+    version = "2.1.1";
   }
 });
 
@@ -827,6 +827,61 @@ var init_mode_utils = __esm({
   }
 });
 
+// src/utils/browser/referrer.utils.ts
+var COMPOUND_TLDS, getRootDomain, isSameDomain, getExternalReferrer;
+var init_referrer_utils = __esm({
+  "src/utils/browser/referrer.utils.ts"() {
+    init_logging_utils();
+    COMPOUND_TLDS = [
+      "co.uk",
+      "org.uk",
+      "com.au",
+      "net.au",
+      "com.br",
+      "co.nz",
+      "co.jp",
+      "com.mx",
+      "co.in",
+      "com.cn",
+      "co.za"
+    ];
+    getRootDomain = (hostname) => {
+      const parts = hostname.toLowerCase().split(".");
+      if (parts.length <= 2) {
+        return hostname.toLowerCase();
+      }
+      const lastTwo = parts.slice(-2).join(".");
+      if (COMPOUND_TLDS.includes(lastTwo)) {
+        return parts.slice(-3).join(".");
+      }
+      return parts.slice(-2).join(".");
+    };
+    isSameDomain = (hostname1, hostname2) => {
+      if (hostname1 === hostname2) {
+        return true;
+      }
+      return getRootDomain(hostname1) === getRootDomain(hostname2);
+    };
+    getExternalReferrer = () => {
+      const referrer = document.referrer;
+      if (!referrer) {
+        return "Direct";
+      }
+      try {
+        const referrerHostname = new URL(referrer).hostname.toLowerCase();
+        const currentHostname = window.location.hostname.toLowerCase();
+        if (isSameDomain(referrerHostname, currentHostname)) {
+          return "Direct";
+        }
+        return referrer;
+      } catch (error) {
+        log("debug", "Failed to parse referrer URL, using raw value", { error, data: { referrer } });
+        return referrer;
+      }
+    };
+  }
+});
+
 // src/utils/browser/utm-params.utils.ts
 var getUTMParameters;
 var init_utm_params_utils = __esm({
@@ -853,6 +908,7 @@ var init_browser = __esm({
   "src/utils/browser/index.ts"() {
     init_device_detector_utils();
     init_mode_utils();
+    init_referrer_utils();
     init_utm_params_utils();
   }
 });
@@ -3504,7 +3560,6 @@ var init_event_manager = __esm({
         return queue;
       }
       buildEventPayload(data) {
-        const isSessionStart = data.type === "session_start" /* SESSION_START */;
         const currentPageUrl = data.page_url ?? this.get("pageUrl");
         const timestamp = this.timeManager.now();
         const validation = this.timeManager.validateTimestamp(timestamp);
@@ -3513,12 +3568,14 @@ var init_event_manager = __esm({
             data: { type: data.type, error: validation.error }
           });
         }
+        const sessionReferrer = this.get("sessionReferrer");
+        const sessionUtm = this.get("sessionUtm");
         let payload = {
           id: generateEventId(),
           type: data.type,
           page_url: currentPageUrl,
           timestamp,
-          ...isSessionStart && { referrer: this.getExternalReferrer() },
+          ...sessionReferrer && { referrer: sessionReferrer },
           ...data.from_page_url && { from_page_url: data.from_page_url },
           ...data.scroll_data && { scroll_data: data.scroll_data },
           ...data.click_data && { click_data: data.click_data },
@@ -3527,7 +3584,7 @@ var init_event_manager = __esm({
           ...data.error_data && { error_data: data.error_data },
           ...data.viewport_data && { viewport_data: data.viewport_data },
           ...data.page_view && { page_view: data.page_view },
-          ...isSessionStart && getUTMParameters() && { utm: getUTMParameters() }
+          ...sessionUtm && { utm: sessionUtm }
         };
         const collectApiUrls = this.get("collectApiUrls");
         const hasCustomBackend = Boolean(collectApiUrls?.custom);
@@ -3880,102 +3937,6 @@ var init_event_manager = __esm({
           log("warn", "Failed to cleanup expired session counts", { error });
         }
       }
-      /**
-       * Returns the referrer if it's external, or 'Direct' if internal/empty.
-       *
-       * **Purpose**: Filter out internal referrers (same domain) to ensure
-       * accurate traffic source attribution. Internal referrers occur when:
-       * - Session expires and user navigates within the same site
-       * - User opens new tab from an internal link
-       * - Page refresh after session timeout
-       *
-       * **Logic**:
-       * - Empty referrer → 'Direct'
-       * - Referrer from same domain or subdomain → 'Direct' (internal navigation)
-       * - External referrer → Returns original referrer
-       *
-       * **Subdomain Detection**:
-       * - `www.example.com` → `example.com` ✓ (internal)
-       * - `blog.example.com` → `example.com` ✓ (internal)
-       * - `example.com` → `www.example.com` ✓ (internal)
-       *
-       * @returns External referrer URL or 'Direct'
-       *
-       * @internal
-       */
-      getExternalReferrer() {
-        const referrer = document.referrer;
-        if (!referrer) {
-          return "Direct";
-        }
-        try {
-          const referrerHostname = new URL(referrer).hostname.toLowerCase();
-          const currentHostname = window.location.hostname.toLowerCase();
-          if (this.isSameDomain(referrerHostname, currentHostname)) {
-            return "Direct";
-          }
-          return referrer;
-        } catch (error) {
-          log("debug", "Failed to parse referrer URL, using raw value", { error, data: { referrer } });
-          return referrer;
-        }
-      }
-      /**
-       * Checks if two hostnames belong to the same domain (including subdomains).
-       * Extracts root domain and compares to handle cross-subdomain navigation.
-       *
-       * @example
-       * isSameDomain('www.example.com', 'example.com') // true
-       * isSameDomain('app.example.com', 'www.example.com') // true
-       * isSameDomain('example.co.uk', 'app.example.co.uk') // true
-       *
-       * @param hostname1 - First hostname (e.g., 'www.example.com')
-       * @param hostname2 - Second hostname (e.g., 'app.example.com')
-       * @returns true if same root domain
-       *
-       * @internal
-       */
-      isSameDomain(hostname1, hostname2) {
-        if (hostname1 === hostname2) {
-          return true;
-        }
-        return this.getRootDomain(hostname1) === this.getRootDomain(hostname2);
-      }
-      /**
-       * Extracts the root (registrable) domain from a hostname.
-       * Handles both standard TLDs (.com, .org) and compound TLDs (.co.uk, .com.br).
-       *
-       * @example
-       * getRootDomain('www.example.com') // 'example.com'
-       * getRootDomain('app.blog.example.com') // 'example.com'
-       * getRootDomain('shop.example.co.uk') // 'example.co.uk'
-       *
-       * @internal
-       */
-      getRootDomain(hostname) {
-        const parts = hostname.toLowerCase().split(".");
-        if (parts.length <= 2) {
-          return hostname.toLowerCase();
-        }
-        const compoundTlds = [
-          "co.uk",
-          "org.uk",
-          "com.au",
-          "net.au",
-          "com.br",
-          "co.nz",
-          "co.jp",
-          "com.mx",
-          "co.in",
-          "com.cn",
-          "co.za"
-        ];
-        const lastTwo = parts.slice(-2).join(".");
-        if (compoundTlds.includes(lastTwo)) {
-          return parts.slice(-3).join(".");
-        }
-        return parts.slice(-2).join(".");
-      }
       /**
        * Persists current session event counts to localStorage (debounced).
        *
@@ -4152,10 +4113,12 @@ var init_session_manager = __esm({
         }
         return storedSession.id;
       }
-      persistSession(sessionId, lastActivity = Date.now()) {
+      persistSession(sessionId, lastActivity = Date.now(), referrer, utm) {
         this.saveStoredSession({
           id: sessionId,
-          lastActivity
+          lastActivity,
+          ...referrer && { referrer },
+          ...utm && { utm }
         });
       }
       clearStoredSession() {
@@ -4247,17 +4210,31 @@ var init_session_manager = __esm({
         }
         const recoveredSessionId = this.recoverSession();
         const sessionId = recoveredSessionId ?? this.generateSessionId();
+        let sessionReferrer;
+        let sessionUtm;
+        if (recoveredSessionId) {
+          const storedSession = this.loadStoredSession();
+          sessionReferrer = storedSession?.referrer ?? getExternalReferrer();
+          sessionUtm = storedSession?.utm ?? getUTMParameters();
+        } else {
+          sessionReferrer = getExternalReferrer();
+          sessionUtm = getUTMParameters();
+        }
         log("debug", "Session tracking initialized", {
           data: {
             sessionId,
             wasRecovered: !!recoveredSessionId,
-            willEmitSessionStart: true
+            willEmitSessionStart: true,
+            sessionReferrer,
+            hasUtm: !!sessionUtm
           }
         });
         this.isTracking = true;
         try {
           this.set("sessionId", sessionId);
-          this.persistSession(sessionId);
+          this.set("sessionReferrer", sessionReferrer);
+          this.set("sessionUtm", sessionUtm);
+          this.persistSession(sessionId, Date.now(), sessionReferrer, sessionUtm);
           this.initCrossTabSync();
           this.shareSession(sessionId);
           log("debug", "Emitting SESSION_START event", {
@@ -4293,7 +4270,7 @@ var init_session_manager = __esm({
         this.setupSessionTimeout();
         const sessionId = this.get("sessionId");
         if (sessionId) {
-          this.persistSession(sessionId);
+          this.persistSession(sessionId, Date.now(), this.get("sessionReferrer"), this.get("sessionUtm"));
         }
       }
       clearSessionTimeout() {
@@ -4348,6 +4325,8 @@ var init_session_manager = __esm({
         this.clearStoredSession();
         this.set("sessionId", null);
         this.set("hasStartSession", false);
+        this.set("sessionReferrer", void 0);
+        this.set("sessionUtm", void 0);
         this.isTracking = false;
       }
       /**