@grainql/analytics-web 2.4.0 → 2.5.3

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;
@@ -490,9 +526,12 @@ class GrainAnalytics {
         try {
             const headers = await this.getAuthHeaders();
             const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/multi`;
-            const body = JSON.stringify({ events });
-            // Try beacon API first (more reliable for page unload)
-            if (typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
+            // Send events array directly (not wrapped in object) to match API expectation
+            const body = JSON.stringify(events);
+            // Beacon API doesn't support custom headers, so only use it for unauthenticated requests
+            const needsAuth = this.config.authStrategy !== 'NONE';
+            // Try beacon API first (more reliable for page unload, but only if no auth needed)
+            if (!needsAuth && typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
                 const blob = new Blob([body], { type: 'application/json' });
                 const success = navigator.sendBeacon(url, blob);
                 if (success) {
@@ -500,7 +539,7 @@ class GrainAnalytics {
                     return;
                 }
             }
-            // Fallback to fetch with keepalive
+            // Use fetch with keepalive (supports headers and works during page unload)
             await fetch(url, {
                 method: 'POST',
                 headers,
@@ -598,6 +637,103 @@ 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 {
+            this.log('Initializing auto-tracking...');
+            // 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`;
+            this.log('Fetching auto-tracking config from:', url);
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(request),
+            });
+            if (!response.ok) {
+                this.log('Failed to fetch auto-tracking config:', response.status, response.statusText);
+                return;
+            }
+            const configResponse = await response.json();
+            this.log('Received config response:', configResponse);
+            if (configResponse.autoTrackingConfig) {
+                this.log('Auto-tracking config found:', configResponse.autoTrackingConfig);
+                this.setupAutoTrackingManagers(configResponse.autoTrackingConfig);
+            }
+            else {
+                this.log('No auto-tracking config in response');
+            }
+        }
+        catch (error) {
+            this.log('Failed to initialize auto-tracking:', error);
+            // Fail silently - auto-tracking is optional
+        }
+    }
+    /**
+     * Setup auto-tracking managers
+     */
+    setupAutoTrackingManagers(config) {
+        this.log('Setting up auto-tracking managers...', config);
+        // Lazy load the managers to avoid bundling them if not needed
+        if (config.interactions && config.interactions.length > 0) {
+            this.log('Loading interaction tracking module for', config.interactions.length, 'interactions');
+            Promise.resolve().then(() => __importStar(require('./interaction-tracking'))).then(({ InteractionTrackingManager }) => {
+                try {
+                    this.interactionTrackingManager = new InteractionTrackingManager(this, config.interactions, {
+                        debug: this.config.debug,
+                        enableMutationObserver: true,
+                        mutationDebounceDelay: 500,
+                    });
+                    this.log('✅ Interaction tracking initialized successfully 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);
+            });
+        }
+        else {
+            this.log('No interactions configured for auto-tracking');
+        }
+        if (config.sections && config.sections.length > 0) {
+            this.log('Loading section tracking module for', config.sections.length, 'sections');
+            Promise.resolve().then(() => __importStar(require('./section-tracking'))).then(({ SectionTrackingManager }) => {
+                try {
+                    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 successfully 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);
+            });
+        }
+        else {
+            this.log('No sections configured for auto-tracking');
+        }
     }
     /**
      * Track session start event
@@ -1644,6 +1780,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;
@@ -482,9 +485,12 @@ export class GrainAnalytics {
         try {
             const headers = await this.getAuthHeaders();
             const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/multi`;
-            const body = JSON.stringify({ events });
-            // Try beacon API first (more reliable for page unload)
-            if (typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
+            // Send events array directly (not wrapped in object) to match API expectation
+            const body = JSON.stringify(events);
+            // Beacon API doesn't support custom headers, so only use it for unauthenticated requests
+            const needsAuth = this.config.authStrategy !== 'NONE';
+            // Try beacon API first (more reliable for page unload, but only if no auth needed)
+            if (!needsAuth && typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
                 const blob = new Blob([body], { type: 'application/json' });
                 const success = navigator.sendBeacon(url, blob);
                 if (success) {
@@ -492,7 +498,7 @@ export class GrainAnalytics {
                     return;
                 }
             }
-            // Fallback to fetch with keepalive
+            // Use fetch with keepalive (supports headers and works during page unload)
             await fetch(url, {
                 method: 'POST',
                 headers,
@@ -590,6 +596,103 @@ 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 {
+            this.log('Initializing auto-tracking...');
+            // 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`;
+            this.log('Fetching auto-tracking config from:', url);
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(request),
+            });
+            if (!response.ok) {
+                this.log('Failed to fetch auto-tracking config:', response.status, response.statusText);
+                return;
+            }
+            const configResponse = await response.json();
+            this.log('Received config response:', configResponse);
+            if (configResponse.autoTrackingConfig) {
+                this.log('Auto-tracking config found:', configResponse.autoTrackingConfig);
+                this.setupAutoTrackingManagers(configResponse.autoTrackingConfig);
+            }
+            else {
+                this.log('No auto-tracking config in response');
+            }
+        }
+        catch (error) {
+            this.log('Failed to initialize auto-tracking:', error);
+            // Fail silently - auto-tracking is optional
+        }
+    }
+    /**
+     * Setup auto-tracking managers
+     */
+    setupAutoTrackingManagers(config) {
+        this.log('Setting up auto-tracking managers...', config);
+        // Lazy load the managers to avoid bundling them if not needed
+        if (config.interactions && config.interactions.length > 0) {
+            this.log('Loading interaction tracking module for', config.interactions.length, 'interactions');
+            import('./interaction-tracking').then(({ InteractionTrackingManager }) => {
+                try {
+                    this.interactionTrackingManager = new InteractionTrackingManager(this, config.interactions, {
+                        debug: this.config.debug,
+                        enableMutationObserver: true,
+                        mutationDebounceDelay: 500,
+                    });
+                    this.log('✅ Interaction tracking initialized successfully 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);
+            });
+        }
+        else {
+            this.log('No interactions configured for auto-tracking');
+        }
+        if (config.sections && config.sections.length > 0) {
+            this.log('Loading section tracking module for', config.sections.length, 'sections');
+            import('./section-tracking').then(({ SectionTrackingManager }) => {
+                try {
+                    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 successfully 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);
+            });
+        }
+        else {
+            this.log('No sections configured for auto-tracking');
+        }
     }
     /**
      * Track session start event
@@ -1636,6 +1739,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,74 @@
+/**
+ * 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 SendEventOptions {
+    flush?: boolean;
+}
+export interface InteractionTracker {
+    track(eventName: string, properties?: Record<string, unknown>, options?: SendEventOptions): 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,gBAAgB;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,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;IACjH,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;IAuC9B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAoB9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAyC1B;;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"}