@grainql/analytics-web 2.5.4 → 2.6.0

package/dist/esm/types/heatmap-tracking.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Type definitions for Heatmap Tracking
+ */
+export interface HeatmapClickData {
+    pageUrl: string;
+    xpath: string;
+    viewportX: number;
+    viewportY: number;
+    pageX: number;
+    pageY: number;
+    elementTag: string;
+    elementText?: string;
+    timestamp: number;
+}
+export interface HeatmapScrollData {
+    pageUrl: string;
+    viewportSection: number;
+    scrollDepthPx: number;
+    durationMs: number;
+    entryTimestamp: number;
+    exitTimestamp: number;
+    pageHeight: number;
+    viewportHeight: number;
+}
+export interface HeatmapTrackingOptions {
+    scrollDebounceDelay: number;
+    batchDelay: number;
+    maxBatchSize: number;
+    debug?: boolean;
+}
+export interface HeatmapScrollState {
+    viewportSection: number;
+    entryTime: number;
+    scrollDepthPx: number;
+}
+export interface HeatmapTrackingState {
+    currentScrollState: HeatmapScrollState | null;
+    pendingClicks: HeatmapClickData[];
+    pendingScrolls: HeatmapScrollData[];
+}
+//# sourceMappingURL=heatmap-tracking.d.ts.map

package/dist/esm/types/heatmap-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heatmap-tracking.d.ts","sourceRoot":"","sources":["../../../src/types/heatmap-tracking.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,kBAAkB,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC9C,aAAa,EAAE,gBAAgB,EAAE,CAAC;IAClC,cAAc,EAAE,iBAAiB,EAAE,CAAC;CACrC"}

package/dist/esm/types/heatmap-tracking.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for Heatmap Tracking
+ */
+export {};
+//# sourceMappingURL=heatmap-tracking.js.map

package/dist/esm/types/heatmap-tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heatmap-tracking.js","sourceRoot":"","sources":["../../../src/types/heatmap-tracking.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/heartbeat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/E,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC,kBAAkB,IAAI,MAAM,CAAC;IAC7B,qBAAqB,IAAI,MAAM,CAAC;IAChC,YAAY,IAAI,MAAM,CAAC;IACvB,cAAc,IAAI,MAAM,GAAG,IAAI,CAAC;IAChC,+BAA+B,IAAI,MAAM,CAAC;IAC1C,iCAAiC,IAAI,IAAI,CAAC;CAC3C;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,wBAAwB,CAAS;gBAGvC,OAAO,EAAE,gBAAgB,EACzB,gBAAgB,EAAE,gBAAgB,EAClC,MAAM,EAAE,eAAe;IAezB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAyB7B;;OAEG;IACH,OAAO,CAAC,aAAa;IA2CrB;;OAEG;IACH,OAAO,IAAI,IAAI;CAchB"}
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/E,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC,kBAAkB,IAAI,MAAM,CAAC;IAC7B,qBAAqB,IAAI,MAAM,CAAC;IAChC,YAAY,IAAI,MAAM,CAAC;IACvB,cAAc,IAAI,MAAM,GAAG,IAAI,CAAC;IAChC,+BAA+B,IAAI,MAAM,CAAC;IAC1C,iCAAiC,IAAI,IAAI,CAAC;CAC3C;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,wBAAwB,CAAS;gBAGvC,OAAO,EAAE,gBAAgB,EACzB,gBAAgB,EAAE,gBAAgB,EAClC,MAAM,EAAE,eAAe;IAezB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAyB7B;;OAEG;IACH,OAAO,CAAC,aAAa;IAuCrB;;OAEG;IACH,OAAO,IAAI,IAAI;CAUhB"}

package/dist/heartbeat.js

@@ -96,9 +96,6 @@ class HeartbeatManager {
         // Track the heartbeat event
         this.tracker.trackSystemEvent('_grain_heartbeat', properties);
         this.lastHeartbeatTime = now;
-        if (this.config.debug) {
-            console.log('[Heartbeat] Sent heartbeat:', properties);
-        }
     }
     /**
      * Destroy the heartbeat manager
@@ -111,9 +108,6 @@ class HeartbeatManager {
             this.heartbeatTimer = null;
         }
         this.isDestroyed = true;
-        if (this.config.debug) {
-            console.log('[Heartbeat] Destroyed');
-        }
     }
 }
 exports.HeartbeatManager = HeartbeatManager;

package/dist/heatmap-tracking.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Heatmap Tracking Manager for Grain Analytics
+ * Tracks click interactions and scroll depth across all pages
+ */
+import type { HeatmapTrackingOptions } from './types/heatmap-tracking';
+export interface SendEventOptions {
+    flush?: boolean;
+}
+export interface HeatmapTracker {
+    trackSystemEvent(eventName: string, properties?: Record<string, unknown>, options?: SendEventOptions): void | Promise<void>;
+    hasConsent(category: 'analytics' | 'marketing' | 'functional'): boolean;
+    log(...args: unknown[]): void;
+}
+export declare class HeatmapTrackingManager {
+    private tracker;
+    private options;
+    private isDestroyed;
+    private currentScrollState;
+    private pendingClicks;
+    private pendingScrolls;
+    private scrollDebounceTimer;
+    private batchTimer;
+    private scrollTrackingTimer;
+    private periodicScrollTimer;
+    private lastScrollPosition;
+    private lastScrollTime;
+    private readonly SPLIT_DURATION;
+    constructor(tracker: HeatmapTracker, options?: Partial<HeatmapTrackingOptions>);
+    /**
+     * Initialize heatmap tracking
+     */
+    private initialize;
+    /**
+     * Setup click event tracking
+     */
+    private setupClickTracking;
+    /**
+     * Setup scroll event tracking
+     */
+    private setupScrollTracking;
+    /**
+     * Start periodic scroll state tracking
+     */
+    private startScrollTracking;
+    /**
+     * Start periodic scroll tracking (sends events every 3 seconds)
+     */
+    private startPeriodicScrollTracking;
+    /**
+     * Setup page unload handler to beacon remaining data
+     */
+    private setupUnloadHandler;
+    /**
+     * Handle click event
+     */
+    private handleClick;
+    /**
+     * Handle scroll event
+     */
+    private handleScroll;
+    /**
+     * Update current scroll state
+     */
+    private updateScrollState;
+    /**
+     * Generate XPath for an element
+     */
+    private generateXPath;
+    /**
+     * Consider flushing batched events
+     */
+    private considerBatchFlush;
+    /**
+     * Flush pending events
+     */
+    private flushPendingEvents;
+    /**
+     * Flush pending events with beacon (for page unload)
+     */
+    private flushPendingEventsWithBeacon;
+    /**
+     * Log debug message
+     */
+    private log;
+    /**
+     * Destroy the tracking manager
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=heatmap-tracking.d.ts.map

package/dist/heatmap-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heatmap-tracking.d.ts","sourceRoot":"","sources":["../src/heatmap-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAGV,sBAAsB,EAEvB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5H,UAAU,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;IACxE,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC/B;AASD,qBAAa,sBAAsB;IACjC,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,WAAW,CAAS;IAG5B,OAAO,CAAC,kBAAkB,CAAmC;IAC7D,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,cAAc,CAA2B;IAGjD,OAAO,CAAC,mBAAmB,CAAuB;IAClD,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,mBAAmB,CAAuB;IAClD,OAAO,CAAC,mBAAmB,CAAuB;IAGlD,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;gBAGrC,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,OAAO,CAAC,sBAAsB,CAAM;IAe/C;;OAEG;IACH,OAAO,CAAC,UAAU;IAkBlB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAgB3B;;OAEG;IACH,OAAO,CAAC,2BAA2B;IA8CnC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;OAEG;IACH,OAAO,CAAC,WAAW;IAwDnB;;OAEG;IACH,OAAO,CAAC,YAAY;IAKpB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAiDzB;;OAEG;IACH,OAAO,CAAC,aAAa;IAiCrB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAqD1B;;OAEG;IACH,OAAO,CAAC,4BAA4B;IA6CpC;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,OAAO,IAAI,IAAI;CA2BhB"}

package/dist/heatmap-tracking.js

@@ -0,0 +1,465 @@
+"use strict";
+/**
+ * Heatmap Tracking Manager for Grain Analytics
+ * Tracks click interactions and scroll depth across all pages
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeatmapTrackingManager = void 0;
+const DEFAULT_OPTIONS = {
+    scrollDebounceDelay: 100,
+    batchDelay: 2000,
+    maxBatchSize: 20,
+    debug: false,
+};
+class HeatmapTrackingManager {
+    constructor(tracker, options = {}) {
+        this.isDestroyed = false;
+        // Tracking state
+        this.currentScrollState = null;
+        this.pendingClicks = [];
+        this.pendingScrolls = [];
+        // Timers
+        this.scrollDebounceTimer = null;
+        this.batchTimer = null;
+        this.scrollTrackingTimer = null;
+        this.periodicScrollTimer = null;
+        // Scroll tracking
+        this.lastScrollPosition = 0;
+        this.lastScrollTime = Date.now();
+        this.SPLIT_DURATION = 3000; // 3 seconds - same as section tracking
+        this.tracker = tracker;
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+        if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+            // Initialize after DOM is ready
+            if (document.readyState === 'loading') {
+                document.addEventListener('DOMContentLoaded', () => this.initialize());
+            }
+            else {
+                setTimeout(() => this.initialize(), 0);
+            }
+        }
+    }
+    /**
+     * Initialize heatmap tracking
+     */
+    initialize() {
+        if (this.isDestroyed)
+            return;
+        this.log('Initializing heatmap tracking');
+        // Setup click tracking
+        this.setupClickTracking();
+        // Setup scroll tracking
+        this.setupScrollTracking();
+        // Start periodic scroll state tracking
+        this.startScrollTracking();
+        // Setup page unload handler for beaconing
+        this.setupUnloadHandler();
+    }
+    /**
+     * Setup click event tracking
+     */
+    setupClickTracking() {
+        if (typeof document === 'undefined')
+            return;
+        const clickHandler = (event) => {
+            if (this.isDestroyed)
+                return;
+            if (!this.tracker.hasConsent('analytics'))
+                return;
+            this.handleClick(event);
+        };
+        document.addEventListener('click', clickHandler, { passive: true, capture: true });
+    }
+    /**
+     * Setup scroll event tracking
+     */
+    setupScrollTracking() {
+        if (typeof window === 'undefined')
+            return;
+        const scrollHandler = () => {
+            if (this.scrollDebounceTimer !== null) {
+                clearTimeout(this.scrollDebounceTimer);
+            }
+            this.scrollDebounceTimer = window.setTimeout(() => {
+                this.handleScroll();
+                this.scrollDebounceTimer = null;
+            }, this.options.scrollDebounceDelay);
+        };
+        window.addEventListener('scroll', scrollHandler, { passive: true });
+    }
+    /**
+     * Start periodic scroll state tracking
+     */
+    startScrollTracking() {
+        if (typeof window === 'undefined')
+            return;
+        // Track initial scroll position
+        this.updateScrollState();
+        // Update scroll state every 500ms (for detecting section changes)
+        this.scrollTrackingTimer = window.setInterval(() => {
+            if (this.isDestroyed)
+                return;
+            this.updateScrollState();
+        }, 500);
+        // Start periodic 3-second scroll duration tracking
+        this.startPeriodicScrollTracking();
+    }
+    /**
+     * Start periodic scroll tracking (sends events every 3 seconds)
+     */
+    startPeriodicScrollTracking() {
+        if (typeof window === 'undefined')
+            return;
+        this.periodicScrollTimer = window.setInterval(() => {
+            if (this.isDestroyed || !this.currentScrollState)
+                return;
+            if (!this.tracker.hasConsent('analytics'))
+                return;
+            const currentTime = Date.now();
+            const duration = currentTime - this.currentScrollState.entryTime;
+            // Only send if meaningful duration (> 1 second)
+            if (duration > 1000) {
+                const scrollY = window.scrollY || window.pageYOffset;
+                const viewportHeight = window.innerHeight;
+                const pageHeight = document.documentElement.scrollHeight;
+                const scrollData = {
+                    pageUrl: window.location.href,
+                    viewportSection: this.currentScrollState.viewportSection,
+                    scrollDepthPx: scrollY,
+                    durationMs: duration,
+                    entryTimestamp: this.currentScrollState.entryTime,
+                    exitTimestamp: currentTime,
+                    pageHeight,
+                    viewportHeight,
+                };
+                // Send immediately using beacon to ensure delivery
+                this.tracker.trackSystemEvent('_grain_heatmap_scroll', {
+                    page_url: scrollData.pageUrl,
+                    viewport_section: scrollData.viewportSection,
+                    scroll_depth_px: scrollData.scrollDepthPx,
+                    duration_ms: scrollData.durationMs,
+                    entry_timestamp: scrollData.entryTimestamp,
+                    exit_timestamp: scrollData.exitTimestamp,
+                    page_height: scrollData.pageHeight,
+                    viewport_height: scrollData.viewportHeight,
+                    is_split: true, // Flag to indicate periodic tracking, not final exit
+                }, { flush: true });
+                // Reset entry time for next period
+                this.currentScrollState.entryTime = currentTime;
+            }
+        }, this.SPLIT_DURATION);
+    }
+    /**
+     * Setup page unload handler to beacon remaining data
+     */
+    setupUnloadHandler() {
+        if (typeof window === 'undefined')
+            return;
+        const unloadHandler = () => {
+            // Finalize current scroll state
+            if (this.currentScrollState) {
+                const currentTime = Date.now();
+                const duration = currentTime - this.currentScrollState.entryTime;
+                if (duration > 100) {
+                    const scrollData = {
+                        pageUrl: window.location.href,
+                        viewportSection: this.currentScrollState.viewportSection,
+                        scrollDepthPx: this.currentScrollState.scrollDepthPx,
+                        durationMs: duration,
+                        entryTimestamp: this.currentScrollState.entryTime,
+                        exitTimestamp: currentTime,
+                        pageHeight: document.documentElement.scrollHeight,
+                        viewportHeight: window.innerHeight,
+                    };
+                    this.pendingScrolls.push(scrollData);
+                }
+            }
+            // Flush all pending events with beacon
+            this.flushPendingEventsWithBeacon();
+        };
+        // Use both events for better compatibility
+        window.addEventListener('beforeunload', unloadHandler);
+        window.addEventListener('pagehide', unloadHandler);
+    }
+    /**
+     * Handle click event
+     */
+    handleClick(event) {
+        if (!this.tracker.hasConsent('analytics'))
+            return;
+        const element = event.target;
+        if (!element)
+            return;
+        const pageUrl = window.location.href;
+        const xpath = this.generateXPath(element);
+        // Get viewport coordinates
+        const viewportX = Math.round(event.clientX);
+        const viewportY = Math.round(event.clientY);
+        // Get page coordinates (including scroll offset)
+        const pageX = Math.round(event.pageX);
+        const pageY = Math.round(event.pageY);
+        const elementTag = element.tagName?.toLowerCase() || 'unknown';
+        const elementText = element.textContent?.trim().substring(0, 100);
+        const clickData = {
+            pageUrl,
+            xpath,
+            viewportX,
+            viewportY,
+            pageX,
+            pageY,
+            elementTag,
+            elementText: elementText || undefined,
+            timestamp: Date.now(),
+        };
+        // Check if this is a navigation link
+        const isNavigationLink = element instanceof HTMLAnchorElement && element.href;
+        // Send immediately with beacon for navigation links to ensure delivery
+        if (isNavigationLink) {
+            this.tracker.trackSystemEvent('_grain_heatmap_click', {
+                page_url: clickData.pageUrl,
+                xpath: clickData.xpath,
+                viewport_x: clickData.viewportX,
+                viewport_y: clickData.viewportY,
+                page_x: clickData.pageX,
+                page_y: clickData.pageY,
+                element_tag: clickData.elementTag,
+                element_text: clickData.elementText,
+                timestamp: clickData.timestamp,
+            }, { flush: true });
+        }
+        else {
+            this.pendingClicks.push(clickData);
+            // Check if we should flush
+            this.considerBatchFlush();
+        }
+    }
+    /**
+     * Handle scroll event
+     */
+    handleScroll() {
+        if (!this.tracker.hasConsent('analytics'))
+            return;
+        this.updateScrollState();
+    }
+    /**
+     * Update current scroll state
+     */
+    updateScrollState() {
+        if (typeof window === 'undefined')
+            return;
+        if (!this.tracker.hasConsent('analytics'))
+            return;
+        const currentTime = Date.now();
+        const scrollY = window.scrollY || window.pageYOffset;
+        const viewportHeight = window.innerHeight;
+        const pageHeight = document.documentElement.scrollHeight;
+        // Calculate which viewport section we're in
+        const viewportSection = Math.floor(scrollY / viewportHeight);
+        // If we're in a new section, record the previous one
+        if (this.currentScrollState && this.currentScrollState.viewportSection !== viewportSection) {
+            const duration = currentTime - this.currentScrollState.entryTime;
+            // Only record if duration is meaningful (> 100ms)
+            if (duration > 100) {
+                const scrollData = {
+                    pageUrl: window.location.href,
+                    viewportSection: this.currentScrollState.viewportSection,
+                    scrollDepthPx: this.currentScrollState.scrollDepthPx,
+                    durationMs: duration,
+                    entryTimestamp: this.currentScrollState.entryTime,
+                    exitTimestamp: currentTime,
+                    pageHeight,
+                    viewportHeight,
+                };
+                this.pendingScrolls.push(scrollData);
+            }
+        }
+        // Update current state
+        if (!this.currentScrollState || this.currentScrollState.viewportSection !== viewportSection) {
+            this.currentScrollState = {
+                viewportSection,
+                entryTime: currentTime,
+                scrollDepthPx: scrollY,
+            };
+        }
+        this.lastScrollPosition = scrollY;
+        this.lastScrollTime = currentTime;
+        // Check if we should flush
+        this.considerBatchFlush();
+    }
+    /**
+     * Generate XPath for an element
+     */
+    generateXPath(element) {
+        if (!element)
+            return '';
+        // If element has an ID, use that for simpler XPath
+        if (element.id) {
+            return `//*[@id="${element.id}"]`;
+        }
+        const paths = [];
+        let currentElement = element;
+        while (currentElement && currentElement.nodeType === Node.ELEMENT_NODE) {
+            let index = 0;
+            let sibling = currentElement;
+            // Count preceding siblings of the same tag
+            while (sibling) {
+                sibling = sibling.previousElementSibling;
+                if (sibling && sibling.nodeName === currentElement.nodeName) {
+                    index++;
+                }
+            }
+            const tagName = currentElement.nodeName.toLowerCase();
+            const pathIndex = index > 0 ? `[${index + 1}]` : '';
+            paths.unshift(`${tagName}${pathIndex}`);
+            currentElement = currentElement.parentElement;
+        }
+        return paths.length ? `/${paths.join('/')}` : '';
+    }
+    /**
+     * Consider flushing batched events
+     */
+    considerBatchFlush() {
+        const totalEvents = this.pendingClicks.length + this.pendingScrolls.length;
+        // Flush if we've hit the batch size
+        if (totalEvents >= this.options.maxBatchSize) {
+            this.flushPendingEvents();
+            return;
+        }
+        // Otherwise, schedule a batch flush
+        if (this.batchTimer === null && totalEvents > 0) {
+            this.batchTimer = window.setTimeout(() => {
+                this.flushPendingEvents();
+                this.batchTimer = null;
+            }, this.options.batchDelay);
+        }
+    }
+    /**
+     * Flush pending events
+     */
+    flushPendingEvents() {
+        if (this.isDestroyed)
+            return;
+        if (!this.tracker.hasConsent('analytics')) {
+            // Clear pending events if consent is revoked
+            this.pendingClicks = [];
+            this.pendingScrolls = [];
+            return;
+        }
+        // Send click events
+        if (this.pendingClicks.length > 0) {
+            for (const clickData of this.pendingClicks) {
+                this.tracker.trackSystemEvent('_grain_heatmap_click', {
+                    page_url: clickData.pageUrl,
+                    xpath: clickData.xpath,
+                    viewport_x: clickData.viewportX,
+                    viewport_y: clickData.viewportY,
+                    page_x: clickData.pageX,
+                    page_y: clickData.pageY,
+                    element_tag: clickData.elementTag,
+                    element_text: clickData.elementText,
+                    timestamp: clickData.timestamp,
+                });
+            }
+            this.pendingClicks = [];
+        }
+        // Send scroll events
+        if (this.pendingScrolls.length > 0) {
+            for (const scrollData of this.pendingScrolls) {
+                this.tracker.trackSystemEvent('_grain_heatmap_scroll', {
+                    page_url: scrollData.pageUrl,
+                    viewport_section: scrollData.viewportSection,
+                    scroll_depth_px: scrollData.scrollDepthPx,
+                    duration_ms: scrollData.durationMs,
+                    entry_timestamp: scrollData.entryTimestamp,
+                    exit_timestamp: scrollData.exitTimestamp,
+                    page_height: scrollData.pageHeight,
+                    viewport_height: scrollData.viewportHeight,
+                });
+            }
+            this.pendingScrolls = [];
+        }
+        // Clear batch timer
+        if (this.batchTimer !== null) {
+            clearTimeout(this.batchTimer);
+            this.batchTimer = null;
+        }
+    }
+    /**
+     * Flush pending events with beacon (for page unload)
+     */
+    flushPendingEventsWithBeacon() {
+        if (!this.tracker.hasConsent('analytics')) {
+            this.pendingClicks = [];
+            this.pendingScrolls = [];
+            return;
+        }
+        // Send click events with beacon
+        if (this.pendingClicks.length > 0) {
+            for (const clickData of this.pendingClicks) {
+                this.tracker.trackSystemEvent('_grain_heatmap_click', {
+                    page_url: clickData.pageUrl,
+                    xpath: clickData.xpath,
+                    viewport_x: clickData.viewportX,
+                    viewport_y: clickData.viewportY,
+                    page_x: clickData.pageX,
+                    page_y: clickData.pageY,
+                    element_tag: clickData.elementTag,
+                    element_text: clickData.elementText,
+                    timestamp: clickData.timestamp,
+                }, { flush: true });
+            }
+            this.pendingClicks = [];
+        }
+        // Send scroll events with beacon
+        if (this.pendingScrolls.length > 0) {
+            for (const scrollData of this.pendingScrolls) {
+                this.tracker.trackSystemEvent('_grain_heatmap_scroll', {
+                    page_url: scrollData.pageUrl,
+                    viewport_section: scrollData.viewportSection,
+                    scroll_depth_px: scrollData.scrollDepthPx,
+                    duration_ms: scrollData.durationMs,
+                    entry_timestamp: scrollData.entryTimestamp,
+                    exit_timestamp: scrollData.exitTimestamp,
+                    page_height: scrollData.pageHeight,
+                    viewport_height: scrollData.viewportHeight,
+                }, { flush: true });
+            }
+            this.pendingScrolls = [];
+        }
+    }
+    /**
+     * Log debug message
+     */
+    log(...args) {
+        if (this.options.debug) {
+            this.tracker.log('[Heatmap Tracking]', ...args);
+        }
+    }
+    /**
+     * Destroy the tracking manager
+     */
+    destroy() {
+        this.isDestroyed = true;
+        // Clear timers
+        if (this.scrollDebounceTimer !== null) {
+            clearTimeout(this.scrollDebounceTimer);
+            this.scrollDebounceTimer = null;
+        }
+        if (this.batchTimer !== null) {
+            clearTimeout(this.batchTimer);
+            this.batchTimer = null;
+        }
+        if (this.scrollTrackingTimer !== null) {
+            clearInterval(this.scrollTrackingTimer);
+            this.scrollTrackingTimer = null;
+        }
+        if (this.periodicScrollTimer !== null) {
+            clearInterval(this.periodicScrollTimer);
+            this.periodicScrollTimer = null;
+        }
+        // Flush any remaining events
+        this.flushPendingEvents();
+    }
+}
+exports.HeatmapTrackingManager = HeatmapTrackingManager;
+//# sourceMappingURL=heatmap-tracking.js.map

package/dist/index.d.ts

@@ -56,6 +56,7 @@ export interface GrainConfig {
     heartbeatInactiveInterval?: number;
     enableAutoPageView?: boolean;
     stripQueryParams?: boolean;
+    enableHeatmapTracking?: boolean;
 }
 export interface SendEventOptions {
     flush?: boolean;
@@ -237,6 +238,7 @@ export declare class GrainAnalytics implements HeartbeatTracker, PageTracker {
     private eventCountSinceLastHeartbeat;
     private interactionTrackingManager;
     private sectionTrackingManager;
+    private heatmapTrackingManager;
     private sessionStartTime;
     private sessionEventCount;
     constructor(config: GrainConfig);
@@ -311,6 +313,10 @@ export declare class GrainAnalytics implements HeartbeatTracker, PageTracker {
      * Initialize automatic tracking (heartbeat and page views)
      */
     private initializeAutomaticTracking;
+    /**
+     * Initialize heatmap tracking
+     */
+    private initializeHeatmapTracking;
     /**
      * Initialize auto-tracking (interactions and sections)
      */