@grainql/analytics-web 2.4.0 → 2.5.0

package/dist/index.js

@@ -3,6 +3,39 @@
  * Grain Analytics Web SDK
  * A lightweight, dependency-free TypeScript SDK for sending analytics events to Grain's REST API
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GrainAnalytics = exports.getState = exports.getCountryCodeFromTimezone = exports.getCountry = exports.parseUTMParameters = exports.categorizeReferrer = void 0;
 exports.createGrainAnalytics = createGrainAnalytics;
@@ -39,6 +72,9 @@ class GrainAnalytics {
         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;
@@ -598,6 +634,85 @@ class GrainAnalytics {
                 this.log('Failed to initialize page view tracking:', error);
             }
         }
+        // Initialize auto-tracking when config is available
+        this.initializeAutoTracking();
+    }
+    /**
+     * Initialize auto-tracking (interactions and sections)
+     */
+    async initializeAutoTracking() {
+        try {
+            // Fetch remote config to get auto-tracking configuration
+            const userId = this.globalUserId || this.persistentAnonymousUserId || this.generateUUID();
+            const currentUrl = typeof window !== 'undefined' ? window.location.href : '';
+            // Fetch config with currentUrl
+            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);
+            // Fail silently - auto-tracking is optional
+        }
+    }
+    /**
+     * Setup auto-tracking managers
+     */
+    setupAutoTrackingManagers(config) {
+        // Lazy load the managers to avoid bundling them if not needed
+        Promise.resolve().then(() => __importStar(require('./interaction-tracking'))).then(({ InteractionTrackingManager }) => {
+            try {
+                if (config.interactions && config.interactions.length > 0) {
+                    this.interactionTrackingManager = new InteractionTrackingManager(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(() => __importStar(require('./section-tracking'))).then(({ SectionTrackingManager }) => {
+            try {
+                if (config.sections && config.sections.length > 0) {
+                    this.sectionTrackingManager = new SectionTrackingManager(this, config.sections, {
+                        minDwellTime: 1000,
+                        scrollVelocityThreshold: 500,
+                        intersectionThreshold: 0.1,
+                        debounceDelay: 100,
+                        batchDelay: 2000,
+                        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
@@ -1644,6 +1759,15 @@ class GrainAnalytics {
             this.activityDetector.destroy();
             this.activityDetector = null;
         }
+        // Destroy auto-tracking managers
+        if (this.interactionTrackingManager) {
+            this.interactionTrackingManager.destroy();
+            this.interactionTrackingManager = null;
+        }
+        if (this.sectionTrackingManager) {
+            this.sectionTrackingManager.destroy();
+            this.sectionTrackingManager = null;
+        }
         // Send any remaining events (in chunks if necessary)
         if (this.eventQueue.length > 0) {
             const eventsToSend = [...this.eventQueue];

package/dist/index.mjs

@@ -31,6 +31,9 @@ export class GrainAnalytics {
         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;
@@ -590,6 +593,85 @@ export class GrainAnalytics {
                 this.log('Failed to initialize page view tracking:', error);
             }
         }
+        // Initialize auto-tracking when config is available
+        this.initializeAutoTracking();
+    }
+    /**
+     * Initialize auto-tracking (interactions and sections)
+     */
+    async initializeAutoTracking() {
+        try {
+            // Fetch remote config to get auto-tracking configuration
+            const userId = this.globalUserId || this.persistentAnonymousUserId || this.generateUUID();
+            const currentUrl = typeof window !== 'undefined' ? window.location.href : '';
+            // Fetch config with currentUrl
+            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);
+            // Fail silently - auto-tracking is optional
+        }
+    }
+    /**
+     * Setup auto-tracking managers
+     */
+    setupAutoTrackingManagers(config) {
+        // Lazy load the managers to avoid bundling them if not needed
+        import('./interaction-tracking').then(({ InteractionTrackingManager }) => {
+            try {
+                if (config.interactions && config.interactions.length > 0) {
+                    this.interactionTrackingManager = new InteractionTrackingManager(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);
+        });
+        import('./section-tracking').then(({ SectionTrackingManager }) => {
+            try {
+                if (config.sections && config.sections.length > 0) {
+                    this.sectionTrackingManager = new SectionTrackingManager(this, config.sections, {
+                        minDwellTime: 1000,
+                        scrollVelocityThreshold: 500,
+                        intersectionThreshold: 0.1,
+                        debounceDelay: 100,
+                        batchDelay: 2000,
+                        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
@@ -1636,6 +1718,15 @@ export class GrainAnalytics {
             this.activityDetector.destroy();
             this.activityDetector = null;
         }
+        // Destroy auto-tracking managers
+        if (this.interactionTrackingManager) {
+            this.interactionTrackingManager.destroy();
+            this.interactionTrackingManager = null;
+        }
+        if (this.sectionTrackingManager) {
+            this.sectionTrackingManager.destroy();
+            this.sectionTrackingManager = null;
+        }
         // Send any remaining events (in chunks if necessary)
         if (this.eventQueue.length > 0) {
             const eventsToSend = [...this.eventQueue];

package/dist/interaction-tracking.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Interaction Tracking Manager for Grain Analytics
+ * Automatically attaches click and focus listeners to detected interactive elements
+ */
+import type { InteractionConfig } from './types/auto-tracking';
+export interface InteractionTracker {
+    track(eventName: string, properties?: Record<string, unknown>): void | Promise<void>;
+    hasConsent(category: 'analytics' | 'marketing' | 'functional'): boolean;
+    log(...args: unknown[]): void;
+}
+export interface InteractionTrackingConfig {
+    debug?: boolean;
+    enableMutationObserver?: boolean;
+    mutationDebounceDelay?: number;
+}
+export declare class InteractionTrackingManager {
+    private tracker;
+    private interactions;
+    private config;
+    private isDestroyed;
+    private attachedListeners;
+    private xpathCache;
+    private mutationObserver;
+    private mutationDebounceTimer;
+    constructor(tracker: InteractionTracker, interactions: InteractionConfig[], config?: InteractionTrackingConfig);
+    /**
+     * Attach listeners to all configured interactions
+     */
+    private attachAllListeners;
+    /**
+     * Attach listener to a specific interaction
+     */
+    private attachInteractionListener;
+    /**
+     * Handle click event on interaction
+     */
+    private handleInteractionClick;
+    /**
+     * Handle focus event on interaction (for form fields)
+     */
+    private handleInteractionFocus;
+    /**
+     * Find element by XPath selector
+     */
+    private findElementByXPath;
+    /**
+     * Setup mutation observer to handle dynamic content
+     */
+    private setupMutationObserver;
+    /**
+     * Handle DOM mutations
+     */
+    private handleMutations;
+    /**
+     * Detach listeners from an element
+     */
+    private detachListeners;
+    /**
+     * Log debug messages
+     */
+    private log;
+    /**
+     * Update interactions configuration
+     */
+    updateInteractions(interactions: InteractionConfig[]): void;
+    /**
+     * Cleanup and destroy
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=interaction-tracking.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-tracking.d.ts","sourceRoot":"","sources":["../src/interaction-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,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;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,qBAAa,0BAA0B;IACrC,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,iBAAiB,CAA6E;IACtG,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,qBAAqB,CAAuB;gBAGlD,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,iBAAiB,EAAE,EACjC,MAAM,GAAE,yBAA8B;IA0BxC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAkCjC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAqB9B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAoB9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAmC1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0B7B;;OAEG;IACH,OAAO,CAAC,eAAe;IA+BvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAYvB;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,kBAAkB,CAAC,YAAY,EAAE,iBAAiB,EAAE,GAAG,IAAI;IAoB3D;;OAEG;IACH,OAAO,IAAI,IAAI;CA4BhB"}

package/dist/interaction-tracking.js

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * Interaction Tracking Manager for Grain Analytics
+ * Automatically attaches click and focus listeners to detected interactive elements
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InteractionTrackingManager = void 0;
+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;
+        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 || undefined,
+            element_class: element.className || undefined,
+            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 || 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 {
+            const result = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+            const element = result.singleNodeValue;
+            // Cache the result
+            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();
+    }
+}
+exports.InteractionTrackingManager = InteractionTrackingManager;
+//# sourceMappingURL=interaction-tracking.js.map