@tracelog/lib 0.2.2 → 0.4.0

package/README.md

@@ -107,6 +107,12 @@ await tracelog.init({
 
 ## Configuration
 
+**Disabling TraceLog:**
+```typescript
+// Set this flag before initialization to disable TraceLog completely
+window.__traceLogDisabled = true;
+```
+
 **Environment-based settings:**
 - Use `samplingRate: 0.1` to reduce data volume in high-traffic applications
 - Configure `sessionTimeout` to match your application's user session length

package/dist/browser/tracelog.js

@@ -1,5 +1,5 @@
 var y = /* @__PURE__ */ ((r) => (r.Mobile = "mobile", r.Tablet = "tablet", r.Desktop = "desktop", r.Unknown = "unknown", r))(y || {});
-const ee = 15 * 60 * 1e3, Ze = 1e3, et = 1e4, Ue = 250, tt = 24, Ee = 500, ve = 3, rt = 5e3, xe = 1e4, nt = 10, ye = 5, Te = 500, Ie = 120, A = 1, st = 0, it = 1, z = 3e4, G = 864e5, _e = 120, we = 8 * 1024, Ae = 10, be = 10, Y = 255, T = 1e3, K = 100, Me = 3, _ = 2, at = 2e3, k = "data-tl", ot = [
+const ee = 15 * 60 * 1e3, Ze = 1e3, et = 1e4, Ue = 250, tt = 24, Ee = 500, ve = 3, rt = 5e3, xe = 1e4, nt = 10, ye = 5, Te = 500, _e = 120, A = 1, st = 0, it = 1, z = 3e4, G = 864e5, Ie = 120, we = 8 * 1024, Ae = 10, be = 10, Y = 255, T = 1e3, K = 100, Me = 3, I = 2, at = 2e3, k = "data-tl", ot = [
   "button",
   "a",
   'input[type="button"]',
@@ -75,7 +75,7 @@ const ee = 15 * 60 * 1e3, Ze = 1e3, et = 1e4, Ue = 250, tt = 24, Ee = 500, ve =
   excludedUrlPaths: r.excludedUrlPaths ?? [],
   tags: r.tags ?? [],
   ipExcluded: r.ipExcluded ?? !1
-}), I = "tl", dt = (r) => r ? `${I}:${r}:uid` : `${I}:uid`, ht = (r) => r ? `${I}:${r}:queue` : `${I}:queue`, gt = (r) => r ? `${I}:${r}:session` : `${I}:session`, ft = (r) => r ? `${I}:${r}:broadcast` : `${I}:broadcast`, Fe = {
+}), _ = "tl", dt = (r) => r ? `${_}:${r}:uid` : `${_}:uid`, ht = (r) => r ? `${_}:${r}:queue` : `${_}:queue`, gt = (r) => r ? `${_}:${r}:session` : `${_}:session`, ft = (r) => r ? `${_}:${r}:broadcast` : `${_}:broadcast`, Fe = {
   LCP: 4e3,
   FCP: 1800,
   CLS: 0.25,
@@ -224,7 +224,7 @@ const St = () => {
   const e = Math.random() * 16 | 0;
   return (r === "x" ? e : e & 3 | 8).toString(16);
 });
-var w = /* @__PURE__ */ ((r) => (r.Skip = "skip", r.Localhost = "localhost:", r))(w || {}), re = /* @__PURE__ */ ((r) => (r.EVENT = "event", r.QUEUE = "queue", r))(re || {}), d = /* @__PURE__ */ ((r) => (r.PAGE_VIEW = "page_view", r.CLICK = "click", r.SCROLL = "scroll", r.SESSION_START = "session_start", r.SESSION_END = "session_end", r.CUSTOM = "custom", r.WEB_VITALS = "web_vitals", r.ERROR = "error", r))(d || {}), x = /* @__PURE__ */ ((r) => (r.UP = "up", r.DOWN = "down", r))(x || {}), N = /* @__PURE__ */ ((r) => (r.JS_ERROR = "js_error", r.PROMISE_REJECTION = "promise_rejection", r.NETWORK_ERROR = "network_error", r))(N || {}), H = /* @__PURE__ */ ((r) => (r.QA = "qa", r.DEBUG = "debug", r))(H || {}), yt = /* @__PURE__ */ ((r) => (r.AND = "AND", r.OR = "OR", r))(yt || {}), Tt = /* @__PURE__ */ ((r) => (r.URL_MATCHES = "url_matches", r.ELEMENT_MATCHES = "element_matches", r.DEVICE_TYPE = "device_type", r.ELEMENT_TEXT = "element_text", r.ELEMENT_ATTRIBUTE = "element_attribute", r.UTM_SOURCE = "utm_source", r.UTM_MEDIUM = "utm_medium", r.UTM_CAMPAIGN = "utm_campaign", r))(Tt || {}), It = /* @__PURE__ */ ((r) => (r.EQUALS = "equals", r.CONTAINS = "contains", r.STARTS_WITH = "starts_with", r.ENDS_WITH = "ends_with", r.REGEX = "regex", r.GREATER_THAN = "greater_than", r.LESS_THAN = "less_than", r.EXISTS = "exists", r.NOT_EXISTS = "not_exists", r))(It || {});
+var w = /* @__PURE__ */ ((r) => (r.Skip = "skip", r.Localhost = "localhost:", r))(w || {}), re = /* @__PURE__ */ ((r) => (r.EVENT = "event", r.QUEUE = "queue", r))(re || {}), d = /* @__PURE__ */ ((r) => (r.PAGE_VIEW = "page_view", r.CLICK = "click", r.SCROLL = "scroll", r.SESSION_START = "session_start", r.SESSION_END = "session_end", r.CUSTOM = "custom", r.WEB_VITALS = "web_vitals", r.ERROR = "error", r))(d || {}), x = /* @__PURE__ */ ((r) => (r.UP = "up", r.DOWN = "down", r))(x || {}), N = /* @__PURE__ */ ((r) => (r.JS_ERROR = "js_error", r.PROMISE_REJECTION = "promise_rejection", r.NETWORK_ERROR = "network_error", r))(N || {}), H = /* @__PURE__ */ ((r) => (r.QA = "qa", r.DEBUG = "debug", r))(H || {}), yt = /* @__PURE__ */ ((r) => (r.AND = "AND", r.OR = "OR", r))(yt || {}), Tt = /* @__PURE__ */ ((r) => (r.URL_MATCHES = "url_matches", r.ELEMENT_MATCHES = "element_matches", r.DEVICE_TYPE = "device_type", r.ELEMENT_TEXT = "element_text", r.ELEMENT_ATTRIBUTE = "element_attribute", r.UTM_SOURCE = "utm_source", r.UTM_MEDIUM = "utm_medium", r.UTM_CAMPAIGN = "utm_campaign", r))(Tt || {}), _t = /* @__PURE__ */ ((r) => (r.EQUALS = "equals", r.CONTAINS = "contains", r.STARTS_WITH = "starts_with", r.ENDS_WITH = "ends_with", r.REGEX = "regex", r.GREATER_THAN = "greater_than", r.LESS_THAN = "less_than", r.EXISTS = "exists", r.NOT_EXISTS = "not_exists", r))(_t || {});
 class O extends Error {
   constructor(e, t, n) {
     super(e), this.errorCode = t, this.layer = n, this.name = this.constructor.name, Error.captureStackTrace && Error.captureStackTrace(this, this.constructor);
@@ -240,7 +240,7 @@ class M extends O {
     super(e, "APP_CONFIG_INVALID", t);
   }
 }
-class _t extends O {
+class It extends O {
   constructor(e, t = "config") {
     super(e, "SESSION_TIMEOUT_INVALID", t);
   }
@@ -270,7 +270,7 @@ const At = (r) => {
       provided: r.sessionTimeout,
       min: z,
       max: G
-    }), new _t(p.INVALID_SESSION_TIMEOUT, "config");
+    }), new It(p.INVALID_SESSION_TIMEOUT, "config");
   if (r.globalMetadata !== void 0 && (typeof r.globalMetadata != "object" || r.globalMetadata === null))
     throw a.clientError("ConfigValidation", "Global metadata must be an object", {
       provided: r.globalMetadata,
@@ -545,9 +545,9 @@ const At = (r) => {
 } : r.length === 0 ? {
   valid: !1,
   error: "Event name cannot be empty"
-} : r.length > _e ? {
+} : r.length > Ie ? {
   valid: !1,
-  error: `Event name is too long (max ${_e} characters)`
+  error: `Event name is too long (max ${Ie} characters)`
 } : r.includes("<") || r.includes(">") || r.includes("&") ? {
   valid: !1,
   error: "Event name contains invalid characters"
@@ -1492,7 +1492,7 @@ class Yt extends f {
     this.visibilityChangeHandler || this.beforeUnloadHandler || (this.visibilityChangeHandler = () => {
       document.hidden ? this.clearSessionTimeout() : this.get("sessionId") && this.setupSessionTimeout();
     }, this.beforeUnloadHandler = () => {
-      this.eventManager.flushImmediatelySync();
+      this.endSession("page_unload");
     }, document.addEventListener("visibilitychange", this.visibilityChangeHandler), window.addEventListener("beforeunload", this.beforeUnloadHandler));
   }
   cleanupLifecycleListeners() {
@@ -1765,22 +1765,33 @@ class Jt extends f {
   limitWarningLogged = !1;
   minDepthChange = ye;
   minIntervalMs = Te;
-  maxEventsPerSession = Ie;
+  maxEventsPerSession = _e;
   constructor(e) {
     super(), this.eventManager = e;
   }
   startTracking() {
     this.limitWarningLogged = !1, this.applyConfigOverrides(), this.set("scrollEventCount", 0);
-    const e = this.get("config").scrollContainerSelectors, n = (Array.isArray(e) ? e : typeof e == "string" ? [e] : []).map((s) => this.safeQuerySelector(s)).filter((s) => s instanceof HTMLElement);
-    n.length === 0 && n.push(window);
-    for (const s of n)
-      this.setupScrollContainer(s);
+    const e = this.get("config").scrollContainerSelectors, t = Array.isArray(e) ? e : typeof e == "string" ? [e] : [];
+    t.length === 0 ? this.setupScrollContainer(window) : this.trySetupContainers(t, 0);
   }
   stopTracking() {
     for (const e of this.containers)
       this.clearContainerTimer(e), e.element instanceof Window ? window.removeEventListener("scroll", e.listener) : e.element.removeEventListener("scroll", e.listener);
     this.containers.length = 0, this.set("scrollEventCount", 0), this.limitWarningLogged = !1;
   }
+  trySetupContainers(e, t) {
+    const n = e.map((s) => this.safeQuerySelector(s)).filter((s) => s instanceof HTMLElement);
+    if (n.length > 0) {
+      for (const s of n)
+        this.containers.some((o) => o.element === s) || this.setupScrollContainer(s);
+      return;
+    }
+    if (t < 5) {
+      setTimeout(() => this.trySetupContainers(e, t + 1), 200);
+      return;
+    }
+    this.containers.length === 0 && this.setupScrollContainer(window);
+  }
   setupScrollContainer(e) {
     if (e !== window && !this.isElementScrollable(e))
       return;
@@ -1836,7 +1847,7 @@ class Jt extends f {
     }));
   }
   applyConfigOverrides() {
-    this.minDepthChange = ye, this.minIntervalMs = Te, this.maxEventsPerSession = Ie;
+    this.minDepthChange = ye, this.minIntervalMs = Te, this.maxEventsPerSession = _e;
   }
   isWindowScrollable() {
     return document.documentElement.scrollHeight > window.innerHeight;
@@ -2048,7 +2059,7 @@ class tr extends f {
       "largest-contentful-paint",
       (n) => {
         const s = n.getEntries(), i = s[s.length - 1];
-        i && this.sendVital({ type: "LCP", value: Number(i.startTime.toFixed(_)) });
+        i && this.sendVital({ type: "LCP", value: Number(i.startTime.toFixed(I)) });
       },
       { type: "largest-contentful-paint", buffered: !0 },
       !0
@@ -2066,14 +2077,14 @@ class tr extends f {
           const c = typeof o.value == "number" ? o.value : 0;
           e += c;
         }
-        this.sendVital({ type: "CLS", value: Number(e.toFixed(_)) });
+        this.sendVital({ type: "CLS", value: Number(e.toFixed(I)) });
       },
       { type: "layout-shift", buffered: !0 }
     ), this.safeObserve(
       "paint",
       (n) => {
         for (const s of n.getEntries())
-          s.name === "first-contentful-paint" && this.sendVital({ type: "FCP", value: Number(s.startTime.toFixed(_)) });
+          s.name === "first-contentful-paint" && this.sendVital({ type: "FCP", value: Number(s.startTime.toFixed(I)) });
       },
       { type: "paint", buffered: !0 },
       !0
@@ -2086,7 +2097,7 @@ class tr extends f {
           const c = (o.processingEnd ?? 0) - (o.startTime ?? 0);
           s = Math.max(s, c);
         }
-        s > 0 && this.sendVital({ type: "INP", value: Number(s.toFixed(_)) });
+        s > 0 && this.sendVital({ type: "INP", value: Number(s.toFixed(I)) });
       },
       { type: "event", buffered: !0 }
     );
@@ -2094,7 +2105,7 @@ class tr extends f {
   async initWebVitals() {
     try {
       const { onLCP: e, onCLS: t, onFCP: n, onTTFB: s, onINP: i } = await Promise.resolve().then(() => Tr), o = (c) => (l) => {
-        const u = Number(l.value.toFixed(_));
+        const u = Number(l.value.toFixed(I));
         this.sendVital({ type: c, value: u });
       };
       e(o("LCP")), t(o("CLS")), n(o("FCP")), s(o("TTFB")), i(o("INP"));
@@ -2110,7 +2121,7 @@ class tr extends f {
       if (!e)
         return;
       const t = e.responseStart;
-      typeof t == "number" && Number.isFinite(t) && this.sendVital({ type: "TTFB", value: Number(t.toFixed(_)) });
+      typeof t == "number" && Number.isFinite(t) && this.sendVital({ type: "TTFB", value: Number(t.toFixed(I)) });
     } catch (e) {
       a.warn("PerformanceHandler", "Failed to report TTFB", {
         error: e instanceof Error ? e.message : "Unknown error"
@@ -2123,7 +2134,7 @@ class tr extends f {
       (e) => {
         const t = e.getEntries();
         for (const n of t) {
-          const s = Number(n.duration.toFixed(_)), i = Date.now();
+          const s = Number(n.duration.toFixed(I)), i = Date.now();
           i - this.lastLongTaskSentAt >= mt && (this.shouldSendVital("LONG_TASK", s) && this.trackWebVital("LONG_TASK", s), this.lastLongTaskSentAt = i);
         }
       },
@@ -2399,30 +2410,32 @@ let g = null, C = !1, q = !1;
 const sr = async (r) => {
   if (typeof window > "u" || typeof document > "u")
     throw new Error("This library can only be used in a browser environment");
-  if (g) {
-    a.debug("API", "Library already initialized, skipping duplicate initialization");
-    return;
-  }
-  if (C)
-    throw a.warn("API", "Initialization already in progress"), new Error("Initialization already in progress");
-  C = !0;
-  try {
-    a.info("API", "Initializing TraceLog", { projectId: r.id });
-    const e = Lt(r), t = new nr();
+  if (!window.__traceLogDisabled) {
+    if (g) {
+      a.debug("API", "Library already initialized, skipping duplicate initialization");
+      return;
+    }
+    if (C)
+      throw a.warn("API", "Initialization already in progress"), new Error("Initialization already in progress");
+    C = !0;
     try {
-      await t.init(e), g = t, a.info("API", "TraceLog initialized successfully", { projectId: e.id });
-    } catch (n) {
+      a.info("API", "Initializing TraceLog", { projectId: r.id });
+      const e = Lt(r), t = new nr();
       try {
-        await t.destroy(!0);
-      } catch (s) {
-        a.warn("API", "Failed to cleanup partially initialized app", { cleanupError: s });
+        await t.init(e), g = t, a.info("API", "TraceLog initialized successfully", { projectId: e.id });
+      } catch (n) {
+        try {
+          await t.destroy(!0);
+        } catch (s) {
+          a.warn("API", "Failed to cleanup partially initialized app", { cleanupError: s });
+        }
+        throw n;
       }
-      throw n;
+    } catch (e) {
+      throw g = null, a.error("API", "Initialization failed", { error: e }), e;
+    } finally {
+      C = !1;
     }
-  } catch (e) {
-    throw g = null, a.error("API", "Initialization failed", { error: e }), e;
-  } finally {
-    C = !1;
   }
 }, ir = (r, e) => {
   if (!g)
@@ -2453,10 +2466,10 @@ const sr = async (r) => {
   } finally {
     q = !1;
   }
-}, Ir = {
+}, _r = {
   WEB_VITALS_THRESHOLDS: Fe
   // Business thresholds for performance analysis
-}, _r = {
+}, Ir = {
   PII_PATTERNS: ze
   // Patterns for sensitive data protection
 }, wr = {
@@ -2741,7 +2754,7 @@ export {
   Cr as ANALYTICS_QUERY_LIMITS,
   Pr as ANOMALY_DETECTION,
   Mr as CONTENT_ANALYTICS,
-  _r as DATA_PROTECTION,
+  Ir as DATA_PROTECTION,
   br as DEVICE_ANALYTICS,
   y as DeviceType,
   wr as ENGAGEMENT_THRESHOLDS,
@@ -2749,13 +2762,13 @@ export {
   d as EventType,
   Rr as INSIGHT_THRESHOLDS,
   H as Mode,
-  Ir as PERFORMANCE_CONFIG,
+  _r as PERFORMANCE_CONFIG,
   Nr as SEGMENTATION_ANALYTICS,
   Ar as SESSION_ANALYTICS,
   Or as SPECIAL_PAGE_URLS,
   x as ScrollDirection,
   Lr as TEMPORAL_ANALYSIS,
-  It as TagConditionOperator,
+  _t as TagConditionOperator,
   Tt as TagConditionType,
   yt as TagLogicalOperator,
   Dr as tracelog

package/dist/cjs/api.d.ts

@@ -28,14 +28,14 @@ export declare const event: (name: string, metadata?: Record<string, MetadataTyp
  * @param event - Event name to listen to
  * @param callback - Function to call when event is emitted
  * @example
- * // Listen for real-time events
- * tracelog.on('realtime', (data) => {
- *   console.log('Event tracked:', data.type, data.data);
+ * // Listen for tracked events
+ * tracelog.on('event', (data) => {
+ *   console.log('Event tracked:', data.type);
  * });
  *
- * // Listen for sent events
- * tracelog.on('sent', (data) => {
- *   console.log('Events sent:', data.eventCount);
+ * // Listen for event queues being sent
+ * tracelog.on('queue', (data) => {
+ *   console.log('Events sent:', data.events.length);
  * });
  */
 export declare const on: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
@@ -45,7 +45,7 @@ export declare const on: <K extends keyof EmitterMap>(event: K, callback: Emitte
  * @param callback - The same function reference that was used in on()
  * @example
  * // Remove a specific listener
- * tracelog.off('realtime', myCallback);
+ * tracelog.off('event', myCallback);
  */
 export declare const off: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
 /**

package/dist/cjs/api.js

@@ -21,6 +21,10 @@ const init = async (appConfig) => {
     if (typeof window === 'undefined' || typeof document === 'undefined') {
         throw new Error('This library can only be used in a browser environment');
     }
+    // Check if TraceLog is disabled
+    if (window.__traceLogDisabled) {
+        return;
+    }
     // Already initialized - safe to return
     if (app) {
         utils_1.debugLog.debug('API', 'Library already initialized, skipping duplicate initialization');
@@ -92,14 +96,14 @@ exports.event = event;
  * @param event - Event name to listen to
  * @param callback - Function to call when event is emitted
  * @example
- * // Listen for real-time events
- * tracelog.on('realtime', (data) => {
- *   console.log('Event tracked:', data.type, data.data);
+ * // Listen for tracked events
+ * tracelog.on('event', (data) => {
+ *   console.log('Event tracked:', data.type);
  * });
  *
- * // Listen for sent events
- * tracelog.on('sent', (data) => {
- *   console.log('Events sent:', data.eventCount);
+ * // Listen for event queues being sent
+ * tracelog.on('queue', (data) => {
+ *   console.log('Events sent:', data.events.length);
  * });
  */
 const on = (event, callback) => {
@@ -115,7 +119,7 @@ exports.on = on;
  * @param callback - The same function reference that was used in on()
  * @example
  * // Remove a specific listener
- * tracelog.off('realtime', myCallback);
+ * tracelog.off('event', myCallback);
  */
 const off = (event, callback) => {
     if (!app) {

package/dist/cjs/app.types.d.ts

@@ -1,2 +1,2 @@
 export { Mode, EventType, DeviceType, ScrollDirection, ErrorType, TagConditionOperator, TagLogicalOperator, TagConditionType, } from './types';
-export type { ScrollData, ClickData, CustomEventData, MetadataType, WebVitalsData, ErrorData, PageViewData, UTM, EventData, AppConfig, ApiConfig, ExtendedEventsQueueDto, TagConfig, BaseEventsQueueDto, WebVitalType, SessionEndReason, } from './types';
+export type { ScrollData, ClickData, CustomEventData, MetadataType, WebVitalsData, ErrorData, PageViewData, UTM, EventLocation, EventData, AppConfig, ApiConfig, ExtendedEventsQueueDto, TagConfig, BaseEventsQueueDto, WebVitalType, SessionEndReason, } from './types';

package/dist/cjs/handlers/scroll.handler.d.ts

@@ -10,6 +10,7 @@ export declare class ScrollHandler extends StateManager {
     constructor(eventManager: EventManager);
     startTracking(): void;
     stopTracking(): void;
+    private trySetupContainers;
     private setupScrollContainer;
     private processScrollEvent;
     private shouldEmitScrollEvent;

package/dist/cjs/handlers/scroll.handler.js

@@ -21,14 +21,11 @@ class ScrollHandler extends state_manager_1.StateManager {
         this.set('scrollEventCount', 0);
         const raw = this.get('config').scrollContainerSelectors;
         const selectors = Array.isArray(raw) ? raw : typeof raw === 'string' ? [raw] : [];
-        const elements = selectors
-            .map((sel) => this.safeQuerySelector(sel))
-            .filter((element) => element instanceof HTMLElement);
-        if (elements.length === 0) {
-            elements.push(window);
+        if (selectors.length === 0) {
+            this.setupScrollContainer(window);
         }
-        for (const element of elements) {
-            this.setupScrollContainer(element);
+        else {
+            this.trySetupContainers(selectors, 0);
         }
     }
     stopTracking() {
@@ -45,6 +42,27 @@ class ScrollHandler extends state_manager_1.StateManager {
         this.set('scrollEventCount', 0);
         this.limitWarningLogged = false;
     }
+    trySetupContainers(selectors, attempt) {
+        const elements = selectors
+            .map((sel) => this.safeQuerySelector(sel))
+            .filter((element) => element instanceof HTMLElement);
+        if (elements.length > 0) {
+            for (const element of elements) {
+                const isAlreadyTracking = this.containers.some((c) => c.element === element);
+                if (!isAlreadyTracking) {
+                    this.setupScrollContainer(element);
+                }
+            }
+            return;
+        }
+        if (attempt < 5) {
+            setTimeout(() => this.trySetupContainers(selectors, attempt + 1), 200);
+            return;
+        }
+        if (this.containers.length === 0) {
+            this.setupScrollContainer(window);
+        }
+    }
     setupScrollContainer(element) {
         // Skip setup for non-scrollable elements
         if (element !== window && !this.isElementScrollable(element)) {

package/dist/cjs/managers/session.manager.js

@@ -250,7 +250,7 @@ class SessionManager extends state_manager_1.StateManager {
             }
         };
         this.beforeUnloadHandler = () => {
-            this.eventManager.flushImmediatelySync();
+            this.endSession('page_unload');
         };
         // Handle tab visibility changes
         document.addEventListener('visibilitychange', this.visibilityChangeHandler);

package/dist/cjs/types/event.types.d.ts

@@ -75,6 +75,10 @@ export interface PageViewData {
     search?: string;
     hash?: string;
 }
+export interface EventLocation {
+    country: string;
+    country_code: string;
+}
 export interface VitalSample {
     type: WebVitalType;
     value: number;
@@ -94,6 +98,7 @@ export interface EventData {
     session_end_reason?: SessionEndReason;
     error_data?: ErrorData;
     utm?: UTM;
+    location?: EventLocation;
     tags?: string[] | {
         id: string;
         key: string;

package/dist/cjs/types/window.types.d.ts

@@ -1,6 +1,11 @@
 import { TraceLogTestBridge } from './test-bridge.types';
 declare global {
     interface Window {
+        /**
+         * Flag to disable TraceLog initialization
+         * Set to true to prevent the library from running
+         */
+        __traceLogDisabled?: boolean;
         /**
          * Testing bridge for E2E tests
          * Only available when NODE_ENV=dev

package/dist/esm/api.d.ts

@@ -28,14 +28,14 @@ export declare const event: (name: string, metadata?: Record<string, MetadataTyp
  * @param event - Event name to listen to
  * @param callback - Function to call when event is emitted
  * @example
- * // Listen for real-time events
- * tracelog.on('realtime', (data) => {
- *   console.log('Event tracked:', data.type, data.data);
+ * // Listen for tracked events
+ * tracelog.on('event', (data) => {
+ *   console.log('Event tracked:', data.type);
  * });
  *
- * // Listen for sent events
- * tracelog.on('sent', (data) => {
- *   console.log('Events sent:', data.eventCount);
+ * // Listen for event queues being sent
+ * tracelog.on('queue', (data) => {
+ *   console.log('Events sent:', data.events.length);
  * });
  */
 export declare const on: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
@@ -45,7 +45,7 @@ export declare const on: <K extends keyof EmitterMap>(event: K, callback: Emitte
  * @param callback - The same function reference that was used in on()
  * @example
  * // Remove a specific listener
- * tracelog.off('realtime', myCallback);
+ * tracelog.off('event', myCallback);
  */
 export declare const off: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
 /**

package/dist/esm/api.js

@@ -18,6 +18,10 @@ export const init = async (appConfig) => {
     if (typeof window === 'undefined' || typeof document === 'undefined') {
         throw new Error('This library can only be used in a browser environment');
     }
+    // Check if TraceLog is disabled
+    if (window.__traceLogDisabled) {
+        return;
+    }
     // Already initialized - safe to return
     if (app) {
         debugLog.debug('API', 'Library already initialized, skipping duplicate initialization');
@@ -87,14 +91,14 @@ export const event = (name, metadata) => {
  * @param event - Event name to listen to
  * @param callback - Function to call when event is emitted
  * @example
- * // Listen for real-time events
- * tracelog.on('realtime', (data) => {
- *   console.log('Event tracked:', data.type, data.data);
+ * // Listen for tracked events
+ * tracelog.on('event', (data) => {
+ *   console.log('Event tracked:', data.type);
  * });
  *
- * // Listen for sent events
- * tracelog.on('sent', (data) => {
- *   console.log('Events sent:', data.eventCount);
+ * // Listen for event queues being sent
+ * tracelog.on('queue', (data) => {
+ *   console.log('Events sent:', data.events.length);
  * });
  */
 export const on = (event, callback) => {
@@ -109,7 +113,7 @@ export const on = (event, callback) => {
  * @param callback - The same function reference that was used in on()
  * @example
  * // Remove a specific listener
- * tracelog.off('realtime', myCallback);
+ * tracelog.off('event', myCallback);
  */
 export const off = (event, callback) => {
     if (!app) {

package/dist/esm/app.types.d.ts

@@ -1,2 +1,2 @@
 export { Mode, EventType, DeviceType, ScrollDirection, ErrorType, TagConditionOperator, TagLogicalOperator, TagConditionType, } from './types';
-export type { ScrollData, ClickData, CustomEventData, MetadataType, WebVitalsData, ErrorData, PageViewData, UTM, EventData, AppConfig, ApiConfig, ExtendedEventsQueueDto, TagConfig, BaseEventsQueueDto, WebVitalType, SessionEndReason, } from './types';
+export type { ScrollData, ClickData, CustomEventData, MetadataType, WebVitalsData, ErrorData, PageViewData, UTM, EventLocation, EventData, AppConfig, ApiConfig, ExtendedEventsQueueDto, TagConfig, BaseEventsQueueDto, WebVitalType, SessionEndReason, } from './types';

package/dist/esm/handlers/scroll.handler.d.ts

@@ -10,6 +10,7 @@ export declare class ScrollHandler extends StateManager {
     constructor(eventManager: EventManager);
     startTracking(): void;
     stopTracking(): void;
+    private trySetupContainers;
     private setupScrollContainer;
     private processScrollEvent;
     private shouldEmitScrollEvent;

package/dist/esm/handlers/scroll.handler.js

@@ -18,14 +18,11 @@ export class ScrollHandler extends StateManager {
         this.set('scrollEventCount', 0);
         const raw = this.get('config').scrollContainerSelectors;
         const selectors = Array.isArray(raw) ? raw : typeof raw === 'string' ? [raw] : [];
-        const elements = selectors
-            .map((sel) => this.safeQuerySelector(sel))
-            .filter((element) => element instanceof HTMLElement);
-        if (elements.length === 0) {
-            elements.push(window);
+        if (selectors.length === 0) {
+            this.setupScrollContainer(window);
         }
-        for (const element of elements) {
-            this.setupScrollContainer(element);
+        else {
+            this.trySetupContainers(selectors, 0);
         }
     }
     stopTracking() {
@@ -42,6 +39,27 @@ export class ScrollHandler extends StateManager {
         this.set('scrollEventCount', 0);
         this.limitWarningLogged = false;
     }
+    trySetupContainers(selectors, attempt) {
+        const elements = selectors
+            .map((sel) => this.safeQuerySelector(sel))
+            .filter((element) => element instanceof HTMLElement);
+        if (elements.length > 0) {
+            for (const element of elements) {
+                const isAlreadyTracking = this.containers.some((c) => c.element === element);
+                if (!isAlreadyTracking) {
+                    this.setupScrollContainer(element);
+                }
+            }
+            return;
+        }
+        if (attempt < 5) {
+            setTimeout(() => this.trySetupContainers(selectors, attempt + 1), 200);
+            return;
+        }
+        if (this.containers.length === 0) {
+            this.setupScrollContainer(window);
+        }
+    }
     setupScrollContainer(element) {
         // Skip setup for non-scrollable elements
         if (element !== window && !this.isElementScrollable(element)) {

package/dist/esm/managers/session.manager.js

@@ -247,7 +247,7 @@ export class SessionManager extends StateManager {
             }
         };
         this.beforeUnloadHandler = () => {
-            this.eventManager.flushImmediatelySync();
+            this.endSession('page_unload');
         };
         // Handle tab visibility changes
         document.addEventListener('visibilitychange', this.visibilityChangeHandler);

package/dist/esm/types/event.types.d.ts

@@ -75,6 +75,10 @@ export interface PageViewData {
     search?: string;
     hash?: string;
 }
+export interface EventLocation {
+    country: string;
+    country_code: string;
+}
 export interface VitalSample {
     type: WebVitalType;
     value: number;
@@ -94,6 +98,7 @@ export interface EventData {
     session_end_reason?: SessionEndReason;
     error_data?: ErrorData;
     utm?: UTM;
+    location?: EventLocation;
     tags?: string[] | {
         id: string;
         key: string;

package/dist/esm/types/window.types.d.ts

@@ -1,6 +1,11 @@
 import { TraceLogTestBridge } from './test-bridge.types';
 declare global {
     interface Window {
+        /**
+         * Flag to disable TraceLog initialization
+         * Set to true to prevent the library from running
+         */
+        __traceLogDisabled?: boolean;
         /**
          * Testing bridge for E2E tests
          * Only available when NODE_ENV=dev

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tracelog/lib",
   "description": "JavaScript library for web analytics and real-time event tracking",
   "license": "MIT",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "main": "./dist/cjs/public-api.js",
   "module": "./dist/esm/public-api.js",
   "types": "./dist/esm/public-api.d.ts",