@grainql/analytics-web 2.4.0 → 2.5.3

package/dist/esm/interaction-tracking.js

@@ -0,0 +1,288 @@
+/**
+ * Interaction Tracking Manager for Grain Analytics
+ * Automatically attaches click and focus listeners to detected interactive elements
+ */
+export class InteractionTrackingManager {
+    constructor(tracker, interactions, config = {}) {
+        this.isDestroyed = false;
+        this.attachedListeners = new Map();
+        this.xpathCache = 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') {
+            // Attach listeners after DOM is ready
+            if (document.readyState === 'loading') {
+                document.addEventListener('DOMContentLoaded', () => this.attachAllListeners());
+            }
+            else {
+                // DOM already loaded
+                setTimeout(() => this.attachAllListeners(), 0);
+            }
+            // Setup mutation observer for dynamic content
+            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;
+        }
+        // Check if we already attached listeners to this element for this interaction
+        if (this.attachedListeners.has(element)) {
+            this.log('Listeners already attached for element:', element);
+            return;
+        }
+        const handlers = [];
+        // Click handler
+        const clickHandler = (event) => this.handleInteractionClick(interaction, event);
+        element.addEventListener('click', clickHandler, { passive: true });
+        handlers.push({ event: 'click', handler: clickHandler });
+        // Focus handler (for form inputs)
+        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;
+        // Check if this is a navigation link (has href attribute)
+        const isNavigationLink = element instanceof HTMLAnchorElement && element.href;
+        const eventProperties = {
+            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 || undefined,
+            element_class: element.className || undefined,
+            ...(isNavigationLink && { href: element.href }),
+            timestamp: Date.now(),
+        };
+        // If it's a navigation link, flush immediately to ensure event is sent before navigation
+        if (isNavigationLink) {
+            // Use flush option to send immediately - handle promise if returned
+            const result = this.tracker.track(interaction.eventName, eventProperties, { flush: true });
+            if (result instanceof Promise) {
+                result.catch((error) => {
+                    // Log error but don't block navigation
+                    this.log('Failed to track navigation click:', error);
+                });
+            }
+        }
+        else {
+            this.tracker.track(interaction.eventName, eventProperties);
+        }
+        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 || undefined,
+            element_class: element.className || undefined,
+            timestamp: Date.now(),
+        });
+        this.log('Tracked focus interaction:', interaction.eventName);
+    }
+    /**
+     * Find element by XPath selector
+     */
+    findElementByXPath(xpath) {
+        // Check cache first
+        if (this.xpathCache.has(xpath)) {
+            const cached = this.xpathCache.get(xpath);
+            // Verify element is still in DOM
+            if (cached && document.contains(cached)) {
+                return cached;
+            }
+            // Clear invalid cache entry
+            this.xpathCache.delete(xpath);
+        }
+        try {
+            // Strip the xpath= prefix if present (from Stagehand selectors)
+            let cleanXpath = xpath;
+            if (xpath.startsWith('xpath=')) {
+                cleanXpath = xpath.substring(6); // Remove 'xpath=' prefix
+            }
+            const result = document.evaluate(cleanXpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+            const element = result.singleNodeValue;
+            // Cache the result (use original xpath as key)
+            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) => {
+            // Debounce the re-attachment
+            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;
+        // Clear XPath cache on mutations
+        this.xpathCache.clear();
+        // Check if any of our tracked elements were removed
+        const removedElements = new Set();
+        for (const mutation of mutations) {
+            mutation.removedNodes.forEach((node) => {
+                if (node instanceof Element) {
+                    removedElements.add(node);
+                    // Also check for child elements we were tracking
+                    this.attachedListeners.forEach((handlers, element) => {
+                        if (node.contains(element)) {
+                            removedElements.add(element);
+                        }
+                    });
+                }
+            });
+        }
+        // Clean up removed elements
+        removedElements.forEach((element) => {
+            this.detachListeners(element);
+        });
+        // Try to re-attach listeners for any interactions that might now be available
+        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');
+        // Detach all existing listeners
+        this.attachedListeners.forEach((handlers, element) => {
+            this.detachListeners(element);
+        });
+        // Clear cache
+        this.xpathCache.clear();
+        // Update configuration
+        this.interactions = interactions;
+        // Reattach listeners
+        this.attachAllListeners();
+    }
+    /**
+     * Cleanup and destroy
+     */
+    destroy() {
+        if (this.isDestroyed)
+            return;
+        this.log('Destroying interaction tracking manager');
+        this.isDestroyed = true;
+        // Clear debounce timer
+        if (this.mutationDebounceTimer !== null) {
+            clearTimeout(this.mutationDebounceTimer);
+            this.mutationDebounceTimer = null;
+        }
+        // Disconnect mutation observer
+        if (this.mutationObserver) {
+            this.mutationObserver.disconnect();
+            this.mutationObserver = null;
+        }
+        // Detach all listeners
+        this.attachedListeners.forEach((handlers, element) => {
+            this.detachListeners(element);
+        });
+        // Clear caches
+        this.attachedListeners.clear();
+        this.xpathCache.clear();
+    }
+}
+//# sourceMappingURL=interaction-tracking.js.map

package/dist/esm/interaction-tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-tracking.js","sourceRoot":"","sources":["../../src/interaction-tracking.ts"],"names":[],"mappings":"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"}

package/dist/esm/section-tracking.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Section Tracking Manager for Grain Analytics
+ * Intelligent scroll tracking with viewport metrics, visible sections, and engagement analysis
+ */
+import type { SectionConfig, SectionTrackingOptions } from './types/auto-tracking';
+export interface SectionTracker {
+    trackSystemEvent(eventName: string, properties: Record<string, unknown>): void;
+    hasConsent(category: 'analytics' | 'marketing' | 'functional'): boolean;
+    log(...args: unknown[]): void;
+}
+export declare class SectionTrackingManager {
+    private tracker;
+    private sections;
+    private options;
+    private isDestroyed;
+    private sectionStates;
+    private intersectionObserver;
+    private xpathCache;
+    private lastScrollPosition;
+    private lastScrollTime;
+    private scrollVelocity;
+    private scrollDebounceTimer;
+    private pendingEvents;
+    private batchTimer;
+    private sectionTimers;
+    private readonly SPLIT_DURATION;
+    constructor(tracker: SectionTracker, sections: SectionConfig[], options?: Partial<SectionTrackingOptions>);
+    /**
+     * Initialize section tracking
+     */
+    private initialize;
+    /**
+     * Setup IntersectionObserver for section visibility
+     */
+    private setupIntersectionObserver;
+    /**
+     * Setup scroll listener for velocity calculation
+     */
+    private setupScrollListener;
+    /**
+     * Initialize sections and start observing
+     */
+    private initializeSections;
+    /**
+     * Handle intersection observer entry
+     */
+    private handleIntersection;
+    /**
+     * Handle section entry (became visible)
+     */
+    private handleSectionEntry;
+    /**
+     * Start periodic tracking for a section (sends events every 3 seconds)
+     */
+    private startPeriodicTracking;
+    /**
+     * Stop periodic tracking for a section
+     */
+    private stopPeriodicTracking;
+    /**
+     * Handle section exit (became invisible)
+     */
+    private handleSectionExit;
+    /**
+     * Update scroll velocity
+     */
+    private updateScrollVelocity;
+    /**
+     * Calculate current scroll depth as percentage
+     */
+    private calculateScrollDepth;
+    /**
+     * Determine if section view should be tracked (sanitization)
+     */
+    private shouldTrackSection;
+    /**
+     * Queue section view for batching
+     */
+    private queueSectionView;
+    /**
+     * Flush pending section view events
+     */
+    private flushPendingEvents;
+    /**
+     * Find element by XPath selector
+     */
+    private findElementByXPath;
+    /**
+     * Log debug messages
+     */
+    private log;
+    /**
+     * Update sections configuration
+     */
+    updateSections(sections: SectionConfig[]): void;
+    /**
+     * Cleanup and destroy
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=section-tracking.d.ts.map

package/dist/esm/section-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-tracking.d.ts","sourceRoot":"","sources":["../../src/section-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAmB,sBAAsB,EAAwB,MAAM,uBAAuB,CAAC;AAE1H,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/E,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;AAWD,qBAAa,sBAAsB;IACjC,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,WAAW,CAAS;IAG5B,OAAO,CAAC,aAAa,CAAgD;IACrE,OAAO,CAAC,oBAAoB,CAAqC;IACjE,OAAO,CAAC,UAAU,CAA0C;IAG5D,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,mBAAmB,CAAuB;IAGlD,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,UAAU,CAAuB;IAGzC,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;gBAGrC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,aAAa,EAAE,EACzB,OAAO,GAAE,OAAO,CAAC,sBAAsB,CAAM;IAgB/C;;OAEG;IACH,OAAO,CAAC,UAAU;IAelB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAqBjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAkB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA8B1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA2D7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAQ5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAuCzB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA+B1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAuC1B;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,IAAI;IAsB/C;;OAEG;IACH,OAAO,IAAI,IAAI;CAsChB"}