@grainql/analytics-web 2.7.1 → 2.8.0

package/dist/index.js

@@ -79,6 +79,9 @@ class GrainAnalytics {
         // Session tracking
         this.sessionStartTime = Date.now();
         this.sessionEventCount = 0;
+        // Debug mode properties
+        this.debugAgent = null;
+        this.isDebugMode = false;
         this.config = {
             apiUrl: 'https://api.grainql.com',
             authStrategy: 'NONE',
@@ -132,6 +135,8 @@ class GrainAnalytics {
         this.ephemeralSessionId = this.generateUUID();
         // Initialize automatic tracking (browser only)
         if (typeof window !== 'undefined') {
+            // Check for debug mode before initializing tracking
+            this.checkAndInitializeDebugMode();
             this.initializeAutomaticTracking();
             // Track session start
             this.trackSessionStart();
@@ -760,6 +765,8 @@ class GrainAnalytics {
                         debug: this.config.debug,
                         enableMutationObserver: true,
                         mutationDebounceDelay: 500,
+                        tenantId: this.config.tenantId,
+                        apiUrl: this.config.apiUrl,
                     });
                     this.log('Interaction tracking initialized');
                 }
@@ -1818,6 +1825,93 @@ class GrainAnalytics {
     offConsentChange(listener) {
         this.consentManager.removeListener(listener);
     }
+    /**
+     * Check for debug mode parameters and initialize debug agent if valid
+     */
+    checkAndInitializeDebugMode() {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            const urlParams = new URLSearchParams(window.location.search);
+            const isDebug = urlParams.get('grain_debug') === '1';
+            const sessionId = urlParams.get('grain_session');
+            if (!isDebug || !sessionId) {
+                return;
+            }
+            this.log('Debug mode detected, verifying session:', sessionId);
+            // Verify session with API
+            this.verifyDebugSession(sessionId, window.location.hostname)
+                .then((valid) => {
+                if (valid) {
+                    this.log('Debug session verified, initializing debug agent');
+                    this.isDebugMode = true;
+                    this.initializeDebugAgent(sessionId);
+                }
+                else {
+                    this.log('Debug session verification failed');
+                }
+            })
+                .catch((error) => {
+                this.log('Failed to verify debug session:', error);
+            });
+        }
+        catch (error) {
+            this.log('Error checking debug mode:', error);
+        }
+    }
+    /**
+     * Verify debug session with API
+     */
+    async verifyDebugSession(sessionId, domain) {
+        try {
+            const url = `${this.config.apiUrl}/v1/tenant/${encodeURIComponent(this.config.tenantId)}/debug-sessions/verify`;
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    sessionId,
+                    domain,
+                }),
+            });
+            if (!response.ok) {
+                return false;
+            }
+            const result = await response.json();
+            return result.valid === true;
+        }
+        catch (error) {
+            this.log('Debug session verification error:', error);
+            return false;
+        }
+    }
+    /**
+     * Initialize debug agent
+     */
+    initializeDebugAgent(sessionId) {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            this.log('Loading debug agent module');
+            Promise.resolve().then(() => __importStar(require('./debug-agent'))).then(({ DebugAgent }) => {
+                try {
+                    this.debugAgent = new DebugAgent(this, sessionId, this.config.tenantId, this.config.apiUrl, {
+                        debug: this.config.debug,
+                    });
+                    this.log('Debug agent initialized');
+                }
+                catch (error) {
+                    this.log('Failed to initialize debug agent:', error);
+                }
+            }).catch((error) => {
+                this.log('Failed to load debug agent module:', error);
+            });
+        }
+        catch (error) {
+            this.log('Error initializing debug agent:', error);
+        }
+    }
     /**
      * Destroy the client and clean up resources
      */
@@ -1857,6 +1951,11 @@ class GrainAnalytics {
             this.heatmapTrackingManager.destroy();
             this.heatmapTrackingManager = null;
         }
+        // Destroy debug agent
+        if (this.debugAgent) {
+            this.debugAgent.destroy();
+            this.debugAgent = null;
+        }
         // Send any remaining events (in chunks if necessary)
         if (this.eventQueue.length > 0) {
             const eventsToSend = [...this.eventQueue];

package/dist/index.mjs

@@ -38,6 +38,9 @@ export class GrainAnalytics {
         // Session tracking
         this.sessionStartTime = Date.now();
         this.sessionEventCount = 0;
+        // Debug mode properties
+        this.debugAgent = null;
+        this.isDebugMode = false;
         this.config = {
             apiUrl: 'https://api.grainql.com',
             authStrategy: 'NONE',
@@ -91,6 +94,8 @@ export class GrainAnalytics {
         this.ephemeralSessionId = this.generateUUID();
         // Initialize automatic tracking (browser only)
         if (typeof window !== 'undefined') {
+            // Check for debug mode before initializing tracking
+            this.checkAndInitializeDebugMode();
             this.initializeAutomaticTracking();
             // Track session start
             this.trackSessionStart();
@@ -719,6 +724,8 @@ export class GrainAnalytics {
                         debug: this.config.debug,
                         enableMutationObserver: true,
                         mutationDebounceDelay: 500,
+                        tenantId: this.config.tenantId,
+                        apiUrl: this.config.apiUrl,
                     });
                     this.log('Interaction tracking initialized');
                 }
@@ -1777,6 +1784,93 @@ export class GrainAnalytics {
     offConsentChange(listener) {
         this.consentManager.removeListener(listener);
     }
+    /**
+     * Check for debug mode parameters and initialize debug agent if valid
+     */
+    checkAndInitializeDebugMode() {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            const urlParams = new URLSearchParams(window.location.search);
+            const isDebug = urlParams.get('grain_debug') === '1';
+            const sessionId = urlParams.get('grain_session');
+            if (!isDebug || !sessionId) {
+                return;
+            }
+            this.log('Debug mode detected, verifying session:', sessionId);
+            // Verify session with API
+            this.verifyDebugSession(sessionId, window.location.hostname)
+                .then((valid) => {
+                if (valid) {
+                    this.log('Debug session verified, initializing debug agent');
+                    this.isDebugMode = true;
+                    this.initializeDebugAgent(sessionId);
+                }
+                else {
+                    this.log('Debug session verification failed');
+                }
+            })
+                .catch((error) => {
+                this.log('Failed to verify debug session:', error);
+            });
+        }
+        catch (error) {
+            this.log('Error checking debug mode:', error);
+        }
+    }
+    /**
+     * Verify debug session with API
+     */
+    async verifyDebugSession(sessionId, domain) {
+        try {
+            const url = `${this.config.apiUrl}/v1/tenant/${encodeURIComponent(this.config.tenantId)}/debug-sessions/verify`;
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    sessionId,
+                    domain,
+                }),
+            });
+            if (!response.ok) {
+                return false;
+            }
+            const result = await response.json();
+            return result.valid === true;
+        }
+        catch (error) {
+            this.log('Debug session verification error:', error);
+            return false;
+        }
+    }
+    /**
+     * Initialize debug agent
+     */
+    initializeDebugAgent(sessionId) {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            this.log('Loading debug agent module');
+            import('./debug-agent').then(({ DebugAgent }) => {
+                try {
+                    this.debugAgent = new DebugAgent(this, sessionId, this.config.tenantId, this.config.apiUrl, {
+                        debug: this.config.debug,
+                    });
+                    this.log('Debug agent initialized');
+                }
+                catch (error) {
+                    this.log('Failed to initialize debug agent:', error);
+                }
+            }).catch((error) => {
+                this.log('Failed to load debug agent module:', error);
+            });
+        }
+        catch (error) {
+            this.log('Error initializing debug agent:', error);
+        }
+    }
     /**
      * Destroy the client and clean up resources
      */
@@ -1816,6 +1910,11 @@ export class GrainAnalytics {
             this.heatmapTrackingManager.destroy();
             this.heatmapTrackingManager = null;
         }
+        // Destroy debug agent
+        if (this.debugAgent) {
+            this.debugAgent.destroy();
+            this.debugAgent = null;
+        }
         // Send any remaining events (in chunks if necessary)
         if (this.eventQueue.length > 0) {
             const eventsToSend = [...this.eventQueue];

package/dist/interaction-tracking.d.ts

@@ -15,6 +15,8 @@ export interface InteractionTrackingConfig {
     debug?: boolean;
     enableMutationObserver?: boolean;
     mutationDebounceDelay?: number;
+    tenantId?: string;
+    apiUrl?: string;
 }
 export declare class InteractionTrackingManager {
     private tracker;
@@ -26,6 +28,10 @@ export declare class InteractionTrackingManager {
     private mutationObserver;
     private mutationDebounceTimer;
     constructor(tracker: InteractionTracker, interactions: InteractionConfig[], config?: InteractionTrackingConfig);
+    /**
+     * Fetch trackers from API and merge with existing interactions
+     */
+    private fetchAndMergeTrackers;
     /**
      * Attach listeners to all configured interactions
      */

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

@@ -1 +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;AAG/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;IAiCjC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAiC9B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAkB9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAyC1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0B7B;;OAEG;IACH,OAAO,CAAC,eAAe;IA+BvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAWvB;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,kBAAkB,CAAC,YAAY,EAAE,iBAAiB,EAAE,GAAG,IAAI;IAoB3D;;OAEG;IACH,OAAO,IAAI,IAAI;CA4BhB"}
+{"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;AAG/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;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;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;IAmCxC;;OAEG;YACW,qBAAqB;IA6CnC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAiCjC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAiC9B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAkB9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAyC1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0B7B;;OAEG;IACH,OAAO,CAAC,eAAe;IA+BvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAWvB;;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

@@ -19,15 +19,25 @@ class InteractionTrackingManager {
             debug: config.debug ?? false,
             enableMutationObserver: config.enableMutationObserver ?? true,
             mutationDebounceDelay: config.mutationDebounceDelay ?? 500,
+            tenantId: config.tenantId,
+            apiUrl: config.apiUrl,
         };
         if (typeof window !== 'undefined' && typeof document !== 'undefined') {
-            // Attach listeners after DOM is ready
-            if (document.readyState === 'loading') {
-                document.addEventListener('DOMContentLoaded', () => this.attachAllListeners());
+            // Fetch and merge trackers if configured
+            if (this.config.tenantId && this.config.apiUrl) {
+                this.fetchAndMergeTrackers().then(() => {
+                    this.attachAllListeners();
+                });
             }
             else {
-                // DOM already loaded
-                setTimeout(() => this.attachAllListeners(), 0);
+                // 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) {
@@ -35,6 +45,46 @@ class InteractionTrackingManager {
             }
         }
     }
+    /**
+     * Fetch trackers from API and merge with existing interactions
+     */
+    async fetchAndMergeTrackers() {
+        if (!this.config.tenantId || !this.config.apiUrl)
+            return;
+        try {
+            const currentUrl = typeof window !== 'undefined' ? window.location.href : '';
+            const url = `${this.config.apiUrl}/v1/client/${encodeURIComponent(this.config.tenantId)}/trackers?url=${encodeURIComponent(currentUrl)}`;
+            this.log('Fetching trackers from:', url);
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+            });
+            if (!response.ok) {
+                this.log('Failed to fetch trackers:', response.status);
+                return;
+            }
+            const result = await response.json();
+            if (result.trackers && Array.isArray(result.trackers)) {
+                this.log('Fetched', result.trackers.length, 'trackers');
+                // Convert trackers to InteractionConfig format
+                const trackerInteractions = result.trackers.map((tracker) => ({
+                    eventName: tracker.eventName,
+                    selector: tracker.selector,
+                    priority: 5, // High priority for manually created trackers
+                    label: tracker.eventName,
+                    description: `Tracker: ${tracker.eventName}`,
+                }));
+                // Merge with existing interactions (trackers take precedence)
+                this.interactions = [...trackerInteractions, ...this.interactions];
+                this.log('Merged trackers, total interactions:', this.interactions.length);
+            }
+        }
+        catch (error) {
+            this.log('Error fetching trackers:', error);
+        }
+    }
     /**
      * Attach listeners to all configured interactions
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grainql/analytics-web",
-  "version": "2.7.1",
+  "version": "2.8.0",
   "description": "Lightweight TypeScript SDK for sending analytics events and managing remote configurations via Grain's REST API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",