@grainql/analytics-web 2.7.1 → 2.9.0

package/dist/index.js

@@ -44,6 +44,7 @@ const cookies_1 = require("./cookies");
 const activity_1 = require("./activity");
 const heartbeat_1 = require("./heartbeat");
 const page_tracking_1 = require("./page-tracking");
+const id_manager_1 = require("./id-manager");
 const attribution_1 = require("./attribution");
 Object.defineProperty(exports, "categorizeReferrer", { enumerable: true, get: function () { return attribution_1.categorizeReferrer; } });
 Object.defineProperty(exports, "parseUTMParameters", { enumerable: true, get: function () { return attribution_1.parseUTMParameters; } });
@@ -59,13 +60,13 @@ class GrainAnalytics {
         this.flushTimer = null;
         this.isDestroyed = false;
         this.globalUserId = null;
-        this.persistentAnonymousUserId = null;
+        this.persistentAnonymousUserId = null; // Deprecated: use idManager instead
         // Remote Config properties
         this.configCache = null;
         this.configRefreshTimer = null;
         this.configChangeListeners = [];
         this.configFetchPromise = null;
-        this.cookiesEnabled = false;
+        this.cookiesEnabled = false; // Deprecated: cookies no longer used for IDs
         // Automatic Tracking properties
         this.activityDetector = null;
         this.heartbeatManager = null;
@@ -79,6 +80,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',
@@ -93,38 +97,37 @@ class GrainAnalytics {
             configCacheKey: 'grain_config',
             configRefreshInterval: 300000, // 5 minutes
             enableConfigCache: true,
-            // Privacy defaults
-            consentMode: 'opt-out',
+            // Privacy defaults (v2.0)
+            consentMode: 'cookieless', // Default: privacy-first, no permanent tracking
             waitForConsent: false,
-            enableCookies: false,
-            anonymizeIP: false,
             disableAutoProperties: false,
             // Automatic Tracking defaults
             enableHeartbeat: true,
             heartbeatActiveInterval: 120000, // 2 minutes
             heartbeatInactiveInterval: 300000, // 5 minutes
             enableAutoPageView: true,
-            stripQueryParams: true,
+            stripQueryParams: true, // Privacy-first: strip by default
+            stripHash: false,
             // Heatmap Tracking defaults
             enableHeatmapTracking: true,
             ...config,
             tenantId: config.tenantId,
         };
-        // Initialize consent manager
+        // Initialize consent manager (v2.0)
         this.consentManager = new consent_1.ConsentManager(this.config.tenantId, this.config.consentMode);
-        // Check if cookies are enabled
-        if (this.config.enableCookies) {
-            this.cookiesEnabled = (0, cookies_1.areCookiesEnabled)();
-            if (!this.cookiesEnabled && this.config.debug) {
-                console.warn('[Grain Analytics] Cookies are not available, falling back to localStorage');
-            }
-        }
+        // Initialize ID manager (v2.0)
+        const idMode = this.consentManager.getIdMode();
+        this.idManager = new id_manager_1.IdManager({
+            mode: idMode,
+            tenantId: this.config.tenantId,
+            useLocalStorage: true, // For permanent IDs when consented
+        });
         // Set global userId if provided in config
         if (config.userId) {
             this.globalUserId = config.userId;
         }
         this.validateConfig();
-        this.initializePersistentAnonymousUserId();
+        // Deprecated: initializePersistentAnonymousUserId() - now handled by IdManager
         this.setupBeforeUnload();
         this.startFlushTimer();
         this.initializeConfigCache();
@@ -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();
@@ -140,8 +145,11 @@ class GrainAnalytics {
                 this.initializeHeatmapTracking();
             }
         }
-        // Set up consent change listener to flush waiting events and handle consent upgrade
+        // Set up consent change listener to sync IdManager and flush waiting events (v2.0)
         this.consentManager.addListener((state) => {
+            // Sync IdManager with consent state
+            const idMode = this.consentManager.getIdMode();
+            this.idManager.setMode(idMode);
             if (state.granted) {
                 this.handleConsentGranted();
             }
@@ -183,11 +191,14 @@ class GrainAnalytics {
      */
     shouldAllowPersistentStorage() {
         const hasConsent = this.consentManager.hasConsent('analytics');
-        const isOptInMode = this.config.consentMode === 'opt-in';
+        const isCookieless = this.config.consentMode === 'cookieless';
         const userExplicitlyIdentified = !!this.globalUserId;
         const isJWTAuth = this.config.authStrategy === 'JWT';
+        // Never allow persistent storage in cookieless mode
+        if (isCookieless)
+            return false;
         // Allow persistent storage if any of these conditions are met
-        return hasConsent || !isOptInMode || userExplicitlyIdentified || isJWTAuth;
+        return hasConsent || userExplicitlyIdentified || isJWTAuth;
     }
     /**
      * Generate a proper UUIDv4 identifier for anonymous user ID
@@ -281,23 +292,21 @@ class GrainAnalytics {
         }
     }
     /**
-     * Get the effective user ID (global userId or persistent anonymous ID)
+     * Get the effective user ID (v2.0)
      *
-     * GDPR Compliance: In opt-in mode without consent and no explicit user identification,
-     * this should not be called. Use getEphemeralSessionId() instead.
+     * Privacy-first implementation:
+     * - Returns global userId if explicitly set (via identify/login)
+     * - Otherwise uses IdManager to generate:
+     *   - Daily rotating ID (cookieless mode)
+     *   - Permanent ID (with consent)
      */
     getEffectiveUserIdInternal() {
+        // Explicit user identification always takes precedence
         if (this.globalUserId) {
             return this.globalUserId;
         }
-        if (this.persistentAnonymousUserId) {
-            return this.persistentAnonymousUserId;
-        }
-        // Generate a new UUIDv4 identifier as fallback
-        this.persistentAnonymousUserId = this.generateAnonymousUserId();
-        // Try to persist it (will be skipped in opt-in mode without consent)
-        this.savePersistentAnonymousUserId(this.persistentAnonymousUserId);
-        return this.persistentAnonymousUserId;
+        // Use IdManager to generate appropriate ID based on consent
+        return this.idManager.getCurrentUserId();
     }
     log(...args) {
         if (this.config.debug) {
@@ -668,6 +677,7 @@ class GrainAnalytics {
             try {
                 this.pageTrackingManager = new page_tracking_1.PageTrackingManager(this, {
                     stripQueryParams: this.config.stripQueryParams,
+                    stripHash: this.config.stripHash,
                     debug: this.config.debug,
                     tenantId: this.config.tenantId,
                 });
@@ -760,6 +770,8 @@ class GrainAnalytics {
                         debug: this.config.debug,
                         enableMutationObserver: true,
                         mutationDebounceDelay: 500,
+                        tenantId: this.config.tenantId,
+                        apiUrl: this.config.apiUrl,
                     });
                     this.log('Interaction tracking initialized');
                 }
@@ -963,12 +975,13 @@ class GrainAnalytics {
             return;
         const hasConsent = this.consentManager.hasConsent('analytics');
         // Create event with appropriate user ID
+        // v2.0: Always use IdManager which returns daily rotating ID or permanent ID based on consent
         const event = {
             eventName,
-            userId: hasConsent ? this.getEffectiveUserId() : this.getEphemeralSessionId(),
+            userId: this.getEffectiveUserId(), // IdManager handles daily vs permanent based on consent
             properties: {
                 ...properties,
-                _minimal: !hasConsent, // Flag to indicate minimal tracking
+                _minimal: !hasConsent, // Flag to indicate minimal tracking (daily rotating ID)
                 _consent_status: hasConsent ? 'granted' : 'pending',
             },
         };
@@ -1065,17 +1078,22 @@ class GrainAnalytics {
                 event.properties = filtered;
             }
             const formattedEvent = this.formatEvent(event);
-            // Check consent before tracking
+            // Check if we should wait for consent (only if explicitly configured)
             if (this.consentManager.shouldWaitForConsent() && this.config.waitForConsent) {
                 // Queue event until consent is granted
                 this.waitingForConsentQueue.push(formattedEvent);
                 this.log(`Event waiting for consent: ${event.eventName}`, event.properties);
                 return;
             }
-            if (!this.consentManager.hasConsent('analytics')) {
-                this.log(`Event blocked by consent: ${event.eventName}`);
-                return;
-            }
+            // v2.0: GDPR Strict falls back to cookie-less mode (daily rotating IDs)
+            // Events are never blocked - IdManager already provides correct ID (daily or permanent)
+            const hasConsent = this.consentManager.hasConsent('analytics');
+            // Add tracking flags to indicate consent status
+            formattedEvent.properties = {
+                ...formattedEvent.properties,
+                _minimal: !hasConsent, // Flag: true = daily rotating ID, false = permanent ID
+                _consent_status: hasConsent ? 'granted' : 'pending',
+            };
             this.eventQueue.push(formattedEvent);
             this.eventCountSinceLastHeartbeat++;
             this.sessionEventCount++;
@@ -1763,13 +1781,24 @@ class GrainAnalytics {
     }
     // Privacy & Consent Methods
     /**
-     * Grant consent for tracking
+     * Grant consent for tracking (v2.0)
+     * Switches from cookie-less mode to permanent IDs
      * @param categories - Optional array of consent categories (e.g., ['analytics', 'functional'])
      */
     grantConsent(categories) {
         try {
             this.consentManager.grantConsent(categories);
-            this.log('Consent granted', categories);
+            // Sync ID manager with consent state
+            const idMode = this.consentManager.getIdMode();
+            this.idManager.setMode(idMode);
+            this.log('Consent granted, switched to permanent IDs', categories);
+            // Process any queued events waiting for consent
+            if (this.waitingForConsentQueue.length > 0) {
+                this.log(`Processing ${this.waitingForConsentQueue.length} queued events`);
+                this.eventQueue.push(...this.waitingForConsentQueue);
+                this.waitingForConsentQueue = [];
+                this.flush();
+            }
         }
         catch (error) {
             const formattedError = this.formatError(error, 'grantConsent');
@@ -1777,16 +1806,22 @@ class GrainAnalytics {
         }
     }
     /**
-     * Revoke consent for tracking (opt-out)
+     * Revoke consent for tracking (v2.0)
+     * Switches from permanent IDs to cookie-less mode
      * @param categories - Optional array of categories to revoke (if not provided, revokes all)
      */
     revokeConsent(categories) {
         try {
             this.consentManager.revokeConsent(categories);
-            this.log('Consent revoked', categories);
-            // Clear queued events when consent is revoked
-            this.eventQueue = [];
-            this.waitingForConsentQueue = [];
+            // Sync ID manager with consent state
+            const idMode = this.consentManager.getIdMode();
+            this.idManager.setMode(idMode);
+            this.log('Consent revoked, switched to cookie-less mode', categories);
+            // Clear queued events when consent is fully revoked
+            if (!this.consentManager.hasConsent()) {
+                this.eventQueue = [];
+                this.waitingForConsentQueue = [];
+            }
         }
         catch (error) {
             const formattedError = this.formatError(error, 'revokeConsent');
@@ -1818,6 +1853,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 +1979,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];