@grainql/analytics-web 2.4.0 → 2.5.0

package/dist/index.global.dev.js

@@ -1,10 +1,13 @@
-/* Grain Analytics Web SDK v2.4.0 | MIT License | Development Build */
+/* Grain Analytics Web SDK v2.5.0 | MIT License | Development Build */
 "use strict";
 var Grain = (() => {
   var __defProp = Object.defineProperty;
   var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
   var __getOwnPropNames = Object.getOwnPropertyNames;
   var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __esm = (fn, res) => function __init() {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  };
   var __export = (target, all) => {
     for (var name in all)
       __defProp(target, name, { get: all[name], enumerable: true });
@@ -19,6 +22,622 @@ var Grain = (() => {
   };
   var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+  // src/interaction-tracking.ts
+  var interaction_tracking_exports = {};
+  __export(interaction_tracking_exports, {
+    InteractionTrackingManager: () => InteractionTrackingManager
+  });
+  var InteractionTrackingManager;
+  var init_interaction_tracking = __esm({
+    "src/interaction-tracking.ts"() {
+      "use strict";
+      InteractionTrackingManager = class {
+        constructor(tracker, interactions, config = {}) {
+          this.isDestroyed = false;
+          this.attachedListeners = /* @__PURE__ */ new Map();
+          this.xpathCache = /* @__PURE__ */ new Map();
+          this.mutationObserver = null;
+          this.mutationDebounceTimer = null;
+          this.tracker = tracker;
+          this.interactions = interactions;
+          this.config = {
+            debug: config.debug ?? false,
+            enableMutationObserver: config.enableMutationObserver ?? true,
+            mutationDebounceDelay: config.mutationDebounceDelay ?? 500
+          };
+          if (typeof window !== "undefined" && typeof document !== "undefined") {
+            if (document.readyState === "loading") {
+              document.addEventListener("DOMContentLoaded", () => this.attachAllListeners());
+            } else {
+              setTimeout(() => this.attachAllListeners(), 0);
+            }
+            if (this.config.enableMutationObserver) {
+              this.setupMutationObserver();
+            }
+          }
+        }
+        /**
+         * Attach listeners to all configured interactions
+         */
+        attachAllListeners() {
+          if (this.isDestroyed)
+            return;
+          this.log("Attaching interaction listeners for", this.interactions.length, "interactions");
+          for (const interaction of this.interactions) {
+            this.attachInteractionListener(interaction);
+          }
+        }
+        /**
+         * Attach listener to a specific interaction
+         */
+        attachInteractionListener(interaction) {
+          if (this.isDestroyed)
+            return;
+          const element = this.findElementByXPath(interaction.selector);
+          if (!element) {
+            this.log("Element not found for interaction:", interaction.eventName, "selector:", interaction.selector);
+            return;
+          }
+          if (this.attachedListeners.has(element)) {
+            this.log("Listeners already attached for element:", element);
+            return;
+          }
+          const handlers = [];
+          const clickHandler = (event) => this.handleInteractionClick(interaction, event);
+          element.addEventListener("click", clickHandler, { passive: true });
+          handlers.push({ event: "click", handler: clickHandler });
+          if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) {
+            const focusHandler = (event) => this.handleInteractionFocus(interaction, event);
+            element.addEventListener("focus", focusHandler, { passive: true });
+            handlers.push({ event: "focus", handler: focusHandler });
+          }
+          this.attachedListeners.set(element, handlers);
+          this.log("Attached listeners to element for:", interaction.eventName);
+        }
+        /**
+         * Handle click event on interaction
+         */
+        handleInteractionClick(interaction, event) {
+          if (this.isDestroyed)
+            return;
+          if (!this.tracker.hasConsent("analytics"))
+            return;
+          const element = event.target;
+          this.tracker.track(interaction.eventName, {
+            interaction_type: "click",
+            interaction_label: interaction.label,
+            interaction_description: interaction.description,
+            interaction_priority: interaction.priority,
+            element_tag: element.tagName?.toLowerCase(),
+            element_text: element.textContent?.trim().substring(0, 100),
+            element_id: element.id || void 0,
+            element_class: element.className || void 0,
+            timestamp: Date.now()
+          });
+          this.log("Tracked click interaction:", interaction.eventName);
+        }
+        /**
+         * Handle focus event on interaction (for form fields)
+         */
+        handleInteractionFocus(interaction, event) {
+          if (this.isDestroyed)
+            return;
+          if (!this.tracker.hasConsent("analytics"))
+            return;
+          const element = event.target;
+          this.tracker.track(interaction.eventName, {
+            interaction_type: "focus",
+            interaction_label: interaction.label,
+            interaction_description: interaction.description,
+            interaction_priority: interaction.priority,
+            element_tag: element.tagName?.toLowerCase(),
+            element_id: element.id || void 0,
+            element_class: element.className || void 0,
+            timestamp: Date.now()
+          });
+          this.log("Tracked focus interaction:", interaction.eventName);
+        }
+        /**
+         * Find element by XPath selector
+         */
+        findElementByXPath(xpath) {
+          if (this.xpathCache.has(xpath)) {
+            const cached = this.xpathCache.get(xpath);
+            if (cached && document.contains(cached)) {
+              return cached;
+            }
+            this.xpathCache.delete(xpath);
+          }
+          try {
+            const result = document.evaluate(
+              xpath,
+              document,
+              null,
+              XPathResult.FIRST_ORDERED_NODE_TYPE,
+              null
+            );
+            const element = result.singleNodeValue;
+            if (element) {
+              this.xpathCache.set(xpath, element);
+            }
+            return element;
+          } catch (error) {
+            this.log("Error evaluating XPath:", xpath, error);
+            return null;
+          }
+        }
+        /**
+         * Setup mutation observer to handle dynamic content
+         */
+        setupMutationObserver() {
+          if (typeof MutationObserver === "undefined") {
+            this.log("MutationObserver not supported");
+            return;
+          }
+          this.mutationObserver = new MutationObserver((mutations) => {
+            if (this.mutationDebounceTimer !== null) {
+              clearTimeout(this.mutationDebounceTimer);
+            }
+            this.mutationDebounceTimer = window.setTimeout(() => {
+              this.handleMutations(mutations);
+              this.mutationDebounceTimer = null;
+            }, this.config.mutationDebounceDelay);
+          });
+          this.mutationObserver.observe(document.body, {
+            childList: true,
+            subtree: true
+          });
+          this.log("Mutation observer setup");
+        }
+        /**
+         * Handle DOM mutations
+         */
+        handleMutations(mutations) {
+          if (this.isDestroyed)
+            return;
+          this.xpathCache.clear();
+          const removedElements = /* @__PURE__ */ new Set();
+          for (const mutation of mutations) {
+            mutation.removedNodes.forEach((node) => {
+              if (node instanceof Element) {
+                removedElements.add(node);
+                this.attachedListeners.forEach((handlers, element) => {
+                  if (node.contains(element)) {
+                    removedElements.add(element);
+                  }
+                });
+              }
+            });
+          }
+          removedElements.forEach((element) => {
+            this.detachListeners(element);
+          });
+          this.attachAllListeners();
+        }
+        /**
+         * Detach listeners from an element
+         */
+        detachListeners(element) {
+          const handlers = this.attachedListeners.get(element);
+          if (!handlers)
+            return;
+          handlers.forEach(({ event, handler }) => {
+            element.removeEventListener(event, handler);
+          });
+          this.attachedListeners.delete(element);
+          this.log("Detached listeners from element");
+        }
+        /**
+         * Log debug messages
+         */
+        log(...args) {
+          if (this.config.debug) {
+            console.log("[InteractionTracking]", ...args);
+          }
+        }
+        /**
+         * Update interactions configuration
+         */
+        updateInteractions(interactions) {
+          if (this.isDestroyed)
+            return;
+          this.log("Updating interactions configuration");
+          this.attachedListeners.forEach((handlers, element) => {
+            this.detachListeners(element);
+          });
+          this.xpathCache.clear();
+          this.interactions = interactions;
+          this.attachAllListeners();
+        }
+        /**
+         * Cleanup and destroy
+         */
+        destroy() {
+          if (this.isDestroyed)
+            return;
+          this.log("Destroying interaction tracking manager");
+          this.isDestroyed = true;
+          if (this.mutationDebounceTimer !== null) {
+            clearTimeout(this.mutationDebounceTimer);
+            this.mutationDebounceTimer = null;
+          }
+          if (this.mutationObserver) {
+            this.mutationObserver.disconnect();
+            this.mutationObserver = null;
+          }
+          this.attachedListeners.forEach((handlers, element) => {
+            this.detachListeners(element);
+          });
+          this.attachedListeners.clear();
+          this.xpathCache.clear();
+        }
+      };
+    }
+  });
+
+  // src/section-tracking.ts
+  var section_tracking_exports = {};
+  __export(section_tracking_exports, {
+    SectionTrackingManager: () => SectionTrackingManager
+  });
+  var DEFAULT_OPTIONS, SectionTrackingManager;
+  var init_section_tracking = __esm({
+    "src/section-tracking.ts"() {
+      "use strict";
+      DEFAULT_OPTIONS = {
+        minDwellTime: 1e3,
+        // 1 second minimum
+        scrollVelocityThreshold: 500,
+        // 500px/s
+        intersectionThreshold: 0.1,
+        // 10% visible
+        debounceDelay: 100,
+        batchDelay: 2e3,
+        // 2 seconds
+        debug: false
+      };
+      SectionTrackingManager = class {
+        constructor(tracker, sections, options = {}) {
+          this.isDestroyed = false;
+          // Tracking state
+          this.sectionStates = /* @__PURE__ */ new Map();
+          this.intersectionObserver = null;
+          this.xpathCache = /* @__PURE__ */ new Map();
+          // Scroll tracking
+          this.lastScrollPosition = 0;
+          this.lastScrollTime = Date.now();
+          this.scrollVelocity = 0;
+          this.scrollDebounceTimer = null;
+          // Event batching
+          this.pendingEvents = [];
+          this.batchTimer = null;
+          this.tracker = tracker;
+          this.sections = sections;
+          this.options = { ...DEFAULT_OPTIONS, ...options };
+          if (typeof window !== "undefined" && typeof document !== "undefined") {
+            if (document.readyState === "loading") {
+              document.addEventListener("DOMContentLoaded", () => this.initialize());
+            } else {
+              setTimeout(() => this.initialize(), 0);
+            }
+          }
+        }
+        /**
+         * Initialize section tracking
+         */
+        initialize() {
+          if (this.isDestroyed)
+            return;
+          this.log("Initializing section tracking for", this.sections.length, "sections");
+          this.setupIntersectionObserver();
+          this.setupScrollListener();
+          this.initializeSections();
+        }
+        /**
+         * Setup IntersectionObserver for section visibility
+         */
+        setupIntersectionObserver() {
+          if (typeof IntersectionObserver === "undefined") {
+            this.log("IntersectionObserver not supported");
+            return;
+          }
+          this.intersectionObserver = new IntersectionObserver(
+            (entries) => {
+              entries.forEach((entry) => {
+                this.handleIntersection(entry);
+              });
+            },
+            {
+              threshold: [0, 0.1, 0.25, 0.5, 0.75, 1],
+              rootMargin: "0px"
+            }
+          );
+          this.log("IntersectionObserver created");
+        }
+        /**
+         * Setup scroll listener for velocity calculation
+         */
+        setupScrollListener() {
+          if (typeof window === "undefined")
+            return;
+          const scrollHandler = () => {
+            if (this.scrollDebounceTimer !== null) {
+              clearTimeout(this.scrollDebounceTimer);
+            }
+            this.scrollDebounceTimer = window.setTimeout(() => {
+              this.updateScrollVelocity();
+              this.scrollDebounceTimer = null;
+            }, this.options.debounceDelay);
+          };
+          window.addEventListener("scroll", scrollHandler, { passive: true });
+          this.log("Scroll listener attached");
+        }
+        /**
+         * Initialize sections and start observing
+         */
+        initializeSections() {
+          for (const section of this.sections) {
+            const element = this.findElementByXPath(section.selector);
+            if (!element) {
+              this.log("Section element not found:", section.sectionName, "selector:", section.selector);
+              continue;
+            }
+            const state = {
+              element,
+              config: section,
+              entryTime: null,
+              exitTime: null,
+              isVisible: false,
+              lastScrollPosition: window.scrollY,
+              lastScrollTime: Date.now(),
+              entryScrollSpeed: 0,
+              exitScrollSpeed: 0,
+              maxVisibleArea: 0
+            };
+            this.sectionStates.set(section.sectionName, state);
+            if (this.intersectionObserver) {
+              this.intersectionObserver.observe(element);
+            }
+            this.log("Section initialized and observed:", section.sectionName);
+          }
+        }
+        /**
+         * Handle intersection observer entry
+         */
+        handleIntersection(entry) {
+          if (this.isDestroyed)
+            return;
+          const state = Array.from(this.sectionStates.values()).find(
+            (s) => s.element === entry.target
+          );
+          if (!state)
+            return;
+          const isVisible = entry.isIntersecting && entry.intersectionRatio >= this.options.intersectionThreshold;
+          const visibleArea = entry.intersectionRatio;
+          if (visibleArea > state.maxVisibleArea) {
+            state.maxVisibleArea = visibleArea;
+          }
+          if (isVisible && !state.isVisible) {
+            this.handleSectionEntry(state);
+          } else if (!isVisible && state.isVisible) {
+            this.handleSectionExit(state);
+          }
+          state.isVisible = isVisible;
+        }
+        /**
+         * Handle section entry (became visible)
+         */
+        handleSectionEntry(state) {
+          this.log("Section entered view:", state.config.sectionName);
+          state.entryTime = Date.now();
+          state.entryScrollSpeed = this.scrollVelocity;
+          state.lastScrollPosition = window.scrollY;
+          state.lastScrollTime = Date.now();
+          state.maxVisibleArea = 0;
+        }
+        /**
+         * Handle section exit (became invisible)
+         */
+        handleSectionExit(state) {
+          this.log("Section exited view:", state.config.sectionName);
+          if (state.entryTime === null)
+            return;
+          state.exitTime = Date.now();
+          state.exitScrollSpeed = this.scrollVelocity;
+          const duration = state.exitTime - state.entryTime;
+          const viewData = {
+            sectionName: state.config.sectionName,
+            sectionType: state.config.sectionType,
+            entryTime: state.entryTime,
+            exitTime: state.exitTime,
+            duration,
+            viewportWidth: window.innerWidth,
+            viewportHeight: window.innerHeight,
+            scrollDepth: this.calculateScrollDepth(),
+            visibleAreaPercentage: Math.round(state.maxVisibleArea * 100),
+            scrollSpeedAtEntry: state.entryScrollSpeed,
+            scrollSpeedAtExit: state.exitScrollSpeed
+          };
+          if (this.shouldTrackSection(viewData)) {
+            this.queueSectionView(viewData);
+          } else {
+            this.log("Section view filtered out:", state.config.sectionName, "duration:", duration);
+          }
+          state.entryTime = null;
+        }
+        /**
+         * Update scroll velocity
+         */
+        updateScrollVelocity() {
+          const now = Date.now();
+          const currentPosition = window.scrollY;
+          const timeDelta = now - this.lastScrollTime;
+          const positionDelta = Math.abs(currentPosition - this.lastScrollPosition);
+          if (timeDelta > 0) {
+            this.scrollVelocity = positionDelta / timeDelta * 1e3;
+          }
+          this.lastScrollPosition = currentPosition;
+          this.lastScrollTime = now;
+        }
+        /**
+         * Calculate current scroll depth as percentage
+         */
+        calculateScrollDepth() {
+          if (typeof window === "undefined" || typeof document === "undefined")
+            return 0;
+          const windowHeight = window.innerHeight;
+          const documentHeight = Math.max(
+            document.body.scrollHeight,
+            document.body.offsetHeight,
+            document.documentElement.clientHeight,
+            document.documentElement.scrollHeight,
+            document.documentElement.offsetHeight
+          );
+          const scrollTop = window.scrollY;
+          const scrollableHeight = documentHeight - windowHeight;
+          if (scrollableHeight <= 0)
+            return 100;
+          return Math.round(scrollTop / scrollableHeight * 100);
+        }
+        /**
+         * Determine if section view should be tracked (sanitization)
+         */
+        shouldTrackSection(viewData) {
+          if (viewData.duration < this.options.minDwellTime) {
+            return false;
+          }
+          const avgScrollSpeed = (viewData.scrollSpeedAtEntry + viewData.scrollSpeedAtExit) / 2;
+          if (avgScrollSpeed > this.options.scrollVelocityThreshold * 2) {
+            return false;
+          }
+          if (viewData.visibleAreaPercentage < 10) {
+            return false;
+          }
+          return true;
+        }
+        /**
+         * Queue section view for batching
+         */
+        queueSectionView(viewData) {
+          this.pendingEvents.push(viewData);
+          this.log("Queued section view:", viewData.sectionName, "duration:", viewData.duration);
+          if (this.batchTimer === null) {
+            this.batchTimer = window.setTimeout(() => {
+              this.flushPendingEvents();
+            }, this.options.batchDelay);
+          }
+        }
+        /**
+         * Flush pending section view events
+         */
+        flushPendingEvents() {
+          if (this.isDestroyed || this.pendingEvents.length === 0)
+            return;
+          if (!this.tracker.hasConsent("analytics")) {
+            this.pendingEvents = [];
+            return;
+          }
+          this.log("Flushing", this.pendingEvents.length, "section view events");
+          for (const viewData of this.pendingEvents) {
+            this.tracker.trackSystemEvent("_grain_section_view", {
+              section_name: viewData.sectionName,
+              section_type: viewData.sectionType,
+              duration_ms: viewData.duration,
+              viewport_width: viewData.viewportWidth,
+              viewport_height: viewData.viewportHeight,
+              scroll_depth_percent: viewData.scrollDepth,
+              visible_area_percent: viewData.visibleAreaPercentage,
+              scroll_speed_entry: Math.round(viewData.scrollSpeedAtEntry || 0),
+              scroll_speed_exit: Math.round(viewData.scrollSpeedAtExit || 0),
+              entry_timestamp: viewData.entryTime,
+              exit_timestamp: viewData.exitTime
+            });
+          }
+          this.pendingEvents = [];
+          this.batchTimer = null;
+        }
+        /**
+         * Find element by XPath selector
+         */
+        findElementByXPath(xpath) {
+          if (this.xpathCache.has(xpath)) {
+            const cached = this.xpathCache.get(xpath);
+            if (cached && document.contains(cached)) {
+              return cached;
+            }
+            this.xpathCache.delete(xpath);
+          }
+          try {
+            const result = document.evaluate(
+              xpath,
+              document,
+              null,
+              XPathResult.FIRST_ORDERED_NODE_TYPE,
+              null
+            );
+            const element = result.singleNodeValue;
+            if (element) {
+              this.xpathCache.set(xpath, element);
+            }
+            return element;
+          } catch (error) {
+            this.log("Error evaluating XPath:", xpath, error);
+            return null;
+          }
+        }
+        /**
+         * Log debug messages
+         */
+        log(...args) {
+          if (this.options.debug) {
+            console.log("[SectionTracking]", ...args);
+          }
+        }
+        /**
+         * Update sections configuration
+         */
+        updateSections(sections) {
+          if (this.isDestroyed)
+            return;
+          this.log("Updating sections configuration");
+          if (this.intersectionObserver) {
+            this.intersectionObserver.disconnect();
+          }
+          this.sectionStates.clear();
+          this.xpathCache.clear();
+          this.sections = sections;
+          this.setupIntersectionObserver();
+          this.initializeSections();
+        }
+        /**
+         * Cleanup and destroy
+         */
+        destroy() {
+          if (this.isDestroyed)
+            return;
+          this.log("Destroying section tracking manager");
+          this.isDestroyed = true;
+          this.flushPendingEvents();
+          if (this.scrollDebounceTimer !== null) {
+            clearTimeout(this.scrollDebounceTimer);
+            this.scrollDebounceTimer = null;
+          }
+          if (this.batchTimer !== null) {
+            clearTimeout(this.batchTimer);
+            this.batchTimer = null;
+          }
+          if (this.intersectionObserver) {
+            this.intersectionObserver.disconnect();
+            this.intersectionObserver = null;
+          }
+          this.sectionStates.clear();
+          this.xpathCache.clear();
+          this.pendingEvents = [];
+        }
+      };
+    }
+  });
+
   // src/index.ts
   var src_exports = {};
   __export(src_exports, {
@@ -3878,6 +4497,9 @@ var Grain = (() => {
       this.pageTrackingManager = null;
       this.ephemeralSessionId = null;
       this.eventCountSinceLastHeartbeat = 0;
+      // Auto-tracking properties
+      this.interactionTrackingManager = null;
+      this.sectionTrackingManager = null;
       // Session tracking
       this.sessionStartTime = Date.now();
       this.sessionEventCount = 0;
@@ -4396,6 +5018,86 @@ var Grain = (() => {
           this.log("Failed to initialize page view tracking:", error);
         }
       }
+      this.initializeAutoTracking();
+    }
+    /**
+     * Initialize auto-tracking (interactions and sections)
+     */
+    async initializeAutoTracking() {
+      try {
+        const userId = this.globalUserId || this.persistentAnonymousUserId || this.generateUUID();
+        const currentUrl = typeof window !== "undefined" ? window.location.href : "";
+        const request = {
+          userId,
+          immediateKeys: [],
+          properties: {},
+          currentUrl
+          // Add current URL to request
+        };
+        const headers = await this.getAuthHeaders();
+        const url = `${this.config.apiUrl}/v1/client/${encodeURIComponent(this.config.tenantId)}/config/configurations`;
+        const response = await fetch(url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(request)
+        });
+        if (response.ok) {
+          const configResponse = await response.json();
+          if (configResponse.autoTrackingConfig) {
+            this.setupAutoTrackingManagers(configResponse.autoTrackingConfig);
+          }
+        }
+      } catch (error) {
+        this.log("Failed to initialize auto-tracking:", error);
+      }
+    }
+    /**
+     * Setup auto-tracking managers
+     */
+    setupAutoTrackingManagers(config) {
+      Promise.resolve().then(() => (init_interaction_tracking(), interaction_tracking_exports)).then(({ InteractionTrackingManager: InteractionTrackingManager2 }) => {
+        try {
+          if (config.interactions && config.interactions.length > 0) {
+            this.interactionTrackingManager = new InteractionTrackingManager2(
+              this,
+              config.interactions,
+              {
+                debug: this.config.debug,
+                enableMutationObserver: true,
+                mutationDebounceDelay: 500
+              }
+            );
+            this.log("Interaction tracking initialized with", config.interactions.length, "interactions");
+          }
+        } catch (error) {
+          this.log("Failed to initialize interaction tracking:", error);
+        }
+      }).catch((error) => {
+        this.log("Failed to load interaction tracking module:", error);
+      });
+      Promise.resolve().then(() => (init_section_tracking(), section_tracking_exports)).then(({ SectionTrackingManager: SectionTrackingManager2 }) => {
+        try {
+          if (config.sections && config.sections.length > 0) {
+            this.sectionTrackingManager = new SectionTrackingManager2(
+              this,
+              config.sections,
+              {
+                minDwellTime: 1e3,
+                scrollVelocityThreshold: 500,
+                intersectionThreshold: 0.1,
+                debounceDelay: 100,
+                batchDelay: 2e3,
+                debug: this.config.debug
+              }
+            );
+            this.log("Section tracking initialized with", config.sections.length, "sections");
+          }
+        } catch (error) {
+          this.log("Failed to initialize section tracking:", error);
+        }
+      }).catch((error) => {
+        this.log("Failed to load section tracking module:", error);
+      });
     }
     /**
      * Track session start event
@@ -5355,6 +6057,14 @@ var Grain = (() => {
         this.activityDetector.destroy();
         this.activityDetector = null;
       }
+      if (this.interactionTrackingManager) {
+        this.interactionTrackingManager.destroy();
+        this.interactionTrackingManager = null;
+      }
+      if (this.sectionTrackingManager) {
+        this.sectionTrackingManager.destroy();
+        this.sectionTrackingManager = null;
+      }
       if (this.eventQueue.length > 0) {
         const eventsToSend = [...this.eventQueue];
         this.eventQueue = [];