@grainql/analytics-web 2.0.0 → 2.1.0

package/dist/index.js

@@ -6,9 +6,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GrainAnalytics = void 0;
 exports.createGrainAnalytics = createGrainAnalytics;
+const consent_1 = require("./consent");
+const cookies_1 = require("./cookies");
+const activity_1 = require("./activity");
+const heartbeat_1 = require("./heartbeat");
+const page_tracking_1 = require("./page-tracking");
 class GrainAnalytics {
     constructor(config) {
         this.eventQueue = [];
+        this.waitingForConsentQueue = [];
         this.flushTimer = null;
         this.isDestroyed = false;
         this.globalUserId = null;
@@ -18,6 +24,13 @@ class GrainAnalytics {
         this.configRefreshTimer = null;
         this.configChangeListeners = [];
         this.configFetchPromise = null;
+        this.cookiesEnabled = false;
+        // Automatic Tracking properties
+        this.activityDetector = null;
+        this.heartbeatManager = null;
+        this.pageTrackingManager = null;
+        this.ephemeralSessionId = null;
+        this.eventCountSinceLastHeartbeat = 0;
         this.config = {
             apiUrl: 'https://api.grainql.com',
             authStrategy: 'NONE',
@@ -32,9 +45,30 @@ class GrainAnalytics {
             configCacheKey: 'grain_config',
             configRefreshInterval: 300000, // 5 minutes
             enableConfigCache: true,
+            // Privacy defaults
+            consentMode: 'opt-out',
+            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,
             ...config,
             tenantId: config.tenantId,
         };
+        // Initialize consent manager
+        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');
+            }
+        }
         // Set global userId if provided in config
         if (config.userId) {
             this.globalUserId = config.userId;
@@ -44,6 +78,18 @@ class GrainAnalytics {
         this.setupBeforeUnload();
         this.startFlushTimer();
         this.initializeConfigCache();
+        // Initialize ephemeral session ID (memory-only, not persisted)
+        this.ephemeralSessionId = this.generateUUID();
+        // Initialize automatic tracking (browser only)
+        if (typeof window !== 'undefined') {
+            this.initializeAutomaticTracking();
+        }
+        // Set up consent change listener to flush waiting events and handle consent upgrade
+        this.consentManager.addListener((state) => {
+            if (state.granted) {
+                this.handleConsentGranted();
+            }
+        });
     }
     validateConfig() {
         if (!this.config.tenantId) {
@@ -77,22 +123,38 @@ class GrainAnalytics {
         return this.generateUUID();
     }
     /**
-     * Initialize persistent anonymous user ID from localStorage or create new one
+     * Initialize persistent anonymous user ID from cookies or localStorage
+     * Priority: Cookie → localStorage → generate new
      */
     initializePersistentAnonymousUserId() {
         if (typeof window === 'undefined')
             return;
         const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
+        const cookieName = '_grain_uid';
         try {
+            // Try to load from cookie first if enabled
+            if (this.cookiesEnabled) {
+                const cookieValue = (0, cookies_1.getCookie)(cookieName);
+                if (cookieValue) {
+                    this.persistentAnonymousUserId = cookieValue;
+                    this.log('Loaded persistent anonymous user ID from cookie:', this.persistentAnonymousUserId);
+                    return;
+                }
+            }
+            // Fallback to localStorage
             const stored = localStorage.getItem(storageKey);
             if (stored) {
                 this.persistentAnonymousUserId = stored;
-                this.log('Loaded persistent anonymous user ID:', this.persistentAnonymousUserId);
+                this.log('Loaded persistent anonymous user ID from localStorage:', this.persistentAnonymousUserId);
+                // Migrate to cookie if enabled
+                if (this.cookiesEnabled) {
+                    this.savePersistentAnonymousUserId(stored);
+                }
             }
             else {
                 // Generate new UUIDv4 anonymous user ID
                 this.persistentAnonymousUserId = this.generateAnonymousUserId();
-                localStorage.setItem(storageKey, this.persistentAnonymousUserId);
+                this.savePersistentAnonymousUserId(this.persistentAnonymousUserId);
                 this.log('Generated new persistent anonymous user ID:', this.persistentAnonymousUserId);
             }
         }
@@ -102,10 +164,36 @@ class GrainAnalytics {
             this.persistentAnonymousUserId = this.generateAnonymousUserId();
         }
     }
+    /**
+     * Save persistent anonymous user ID to cookie and/or localStorage
+     */
+    savePersistentAnonymousUserId(userId) {
+        if (typeof window === 'undefined')
+            return;
+        const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
+        const cookieName = '_grain_uid';
+        try {
+            // Save to cookie if enabled
+            if (this.cookiesEnabled) {
+                const cookieOptions = {
+                    maxAge: 365 * 24 * 60 * 60, // 365 days
+                    sameSite: 'lax',
+                    secure: window.location.protocol === 'https:',
+                    ...this.config.cookieOptions,
+                };
+                (0, cookies_1.setCookie)(cookieName, userId, cookieOptions);
+            }
+            // Always save to localStorage as fallback
+            localStorage.setItem(storageKey, userId);
+        }
+        catch (error) {
+            this.log('Failed to save persistent anonymous user ID:', error);
+        }
+    }
     /**
      * Get the effective user ID (global userId or persistent anonymous ID)
      */
-    getEffectiveUserId() {
+    getEffectiveUserIdInternal() {
         if (this.globalUserId) {
             return this.globalUserId;
         }
@@ -253,7 +341,7 @@ class GrainAnalytics {
     formatEvent(event) {
         return {
             eventName: event.eventName,
-            userId: event.userId || this.getEffectiveUserId(),
+            userId: event.userId || this.getEffectiveUserIdInternal(),
             properties: event.properties || {},
         };
     }
@@ -433,6 +521,120 @@ class GrainAnalytics {
             }
         });
     }
+    /**
+     * Initialize automatic tracking (heartbeat and page views)
+     */
+    initializeAutomaticTracking() {
+        if (this.config.enableHeartbeat) {
+            try {
+                this.activityDetector = new activity_1.ActivityDetector();
+                this.heartbeatManager = new heartbeat_1.HeartbeatManager(this, this.activityDetector, {
+                    activeInterval: this.config.heartbeatActiveInterval,
+                    inactiveInterval: this.config.heartbeatInactiveInterval,
+                    debug: this.config.debug,
+                });
+                this.log('Heartbeat tracking initialized');
+            }
+            catch (error) {
+                this.log('Failed to initialize heartbeat tracking:', error);
+            }
+        }
+        if (this.config.enableAutoPageView) {
+            try {
+                this.pageTrackingManager = new page_tracking_1.PageTrackingManager(this, {
+                    stripQueryParams: this.config.stripQueryParams,
+                    debug: this.config.debug,
+                });
+                this.log('Auto page view tracking initialized');
+            }
+            catch (error) {
+                this.log('Failed to initialize page view tracking:', error);
+            }
+        }
+    }
+    /**
+     * Handle consent granted - upgrade ephemeral session to persistent user
+     */
+    handleConsentGranted() {
+        this.flushWaitingForConsentQueue();
+        // Track consent granted event with mapping
+        if (this.ephemeralSessionId) {
+            this.trackSystemEvent('_grain_consent_granted', {
+                previous_session_id: this.ephemeralSessionId,
+                new_user_id: this.getEffectiveUserId(),
+                timestamp: Date.now(),
+            });
+        }
+    }
+    /**
+     * Track system events that bypass consent checks (for necessary/functional tracking)
+     */
+    trackSystemEvent(eventName, properties) {
+        if (this.isDestroyed)
+            return;
+        const hasConsent = this.consentManager.hasConsent('analytics');
+        // Create event with appropriate user ID
+        const event = {
+            eventName,
+            userId: hasConsent ? this.getEffectiveUserId() : this.getEphemeralSessionId(),
+            properties: {
+                ...properties,
+                _minimal: !hasConsent, // Flag to indicate minimal tracking
+                _consent_status: hasConsent ? 'granted' : 'pending',
+            },
+        };
+        // Bypass consent check for necessary system events
+        this.eventQueue.push(event);
+        this.eventCountSinceLastHeartbeat++;
+        this.log(`Queued system event: ${eventName}`, properties);
+        // Consider flushing
+        if (this.eventQueue.length >= this.config.batchSize) {
+            this.flush().catch((error) => {
+                const formattedError = this.formatError(error, 'flush system event');
+                this.logError(formattedError);
+            });
+        }
+    }
+    /**
+     * Get ephemeral session ID (memory-only, not persisted)
+     */
+    getEphemeralSessionId() {
+        if (!this.ephemeralSessionId) {
+            this.ephemeralSessionId = this.generateUUID();
+        }
+        return this.ephemeralSessionId;
+    }
+    /**
+     * Get the current page path from page tracker
+     */
+    getCurrentPage() {
+        return this.pageTrackingManager?.getCurrentPage() || null;
+    }
+    /**
+     * Get event count since last heartbeat
+     */
+    getEventCountSinceLastHeartbeat() {
+        return this.eventCountSinceLastHeartbeat;
+    }
+    /**
+     * Reset event count since last heartbeat
+     */
+    resetEventCountSinceLastHeartbeat() {
+        this.eventCountSinceLastHeartbeat = 0;
+    }
+    /**
+     * Get the effective user ID (public method)
+     */
+    getEffectiveUserId() {
+        return this.getEffectiveUserIdInternal();
+    }
+    /**
+     * Get the session ID (ephemeral or persistent based on consent)
+     */
+    getSessionId() {
+        const hasConsent = this.consentManager.hasConsent('analytics');
+        return hasConsent ? this.getEffectiveUserId() : this.getEphemeralSessionId();
+    }
     async track(eventOrName, propertiesOrOptions, options) {
         try {
             if (this.isDestroyed) {
@@ -454,8 +656,30 @@ class GrainAnalytics {
                 event = eventOrName;
                 opts = propertiesOrOptions || {};
             }
+            // Filter properties if whitelist is enabled
+            if (this.config.allowedProperties && event.properties) {
+                const filtered = {};
+                for (const key of this.config.allowedProperties) {
+                    if (key in event.properties) {
+                        filtered[key] = event.properties[key];
+                    }
+                }
+                event.properties = filtered;
+            }
             const formattedEvent = this.formatEvent(event);
+            // Check consent before tracking
+            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;
+            }
             this.eventQueue.push(formattedEvent);
+            this.eventCountSinceLastHeartbeat++;
             this.log(`Queued event: ${event.eventName}`, event.properties);
             // Check if we should flush immediately
             if (opts.flush || this.eventQueue.length >= this.config.batchSize) {
@@ -467,6 +691,22 @@ class GrainAnalytics {
             this.logError(formattedError);
         }
     }
+    /**
+     * Flush events that were waiting for consent
+     */
+    flushWaitingForConsentQueue() {
+        if (this.waitingForConsentQueue.length === 0)
+            return;
+        this.log(`Flushing ${this.waitingForConsentQueue.length} events waiting for consent`);
+        // Move waiting events to main queue
+        this.eventQueue.push(...this.waitingForConsentQueue);
+        this.waitingForConsentQueue = [];
+        // Flush immediately
+        this.flush().catch((error) => {
+            const formattedError = this.formatError(error, 'flush waiting for consent queue');
+            this.logError(formattedError);
+        });
+    }
     /**
      * Identify a user (sets userId for subsequent events)
      */
@@ -513,7 +753,7 @@ class GrainAnalytics {
      * Get current effective user ID (global userId or persistent anonymous ID)
      */
     getEffectiveUserIdPublic() {
-        return this.getEffectiveUserId();
+        return this.getEffectiveUserIdInternal();
     }
     /**
      * Login with auth token or userId on the fly
@@ -563,7 +803,7 @@ class GrainAnalytics {
                 this.log(`Login: Setting auth strategy to ${options.authStrategy}`);
                 this.config.authStrategy = options.authStrategy;
             }
-            this.log(`Login successful. Effective user ID: ${this.getEffectiveUserId()}`);
+            this.log(`Login successful. Effective user ID: ${this.getEffectiveUserIdInternal()}`);
         }
         catch (error) {
             const formattedError = this.formatError(error, 'login');
@@ -608,7 +848,7 @@ class GrainAnalytics {
                     }
                 }
             }
-            this.log(`Logout successful. Effective user ID: ${this.getEffectiveUserId()}`);
+            this.log(`Logout successful. Effective user ID: ${this.getEffectiveUserIdInternal()}`);
         }
         catch (error) {
             const formattedError = this.formatError(error, 'logout');
@@ -626,7 +866,7 @@ class GrainAnalytics {
                 this.logError(formattedError);
                 return;
             }
-            const userId = options?.userId || this.getEffectiveUserId();
+            const userId = options?.userId || this.getEffectiveUserIdInternal();
             // Validate property count (max 4 properties)
             const propertyKeys = Object.keys(properties);
             if (propertyKeys.length > 4) {
@@ -906,7 +1146,7 @@ class GrainAnalytics {
                 this.logError(formattedError);
                 return null;
             }
-            const userId = options.userId || this.getEffectiveUserId();
+            const userId = options.userId || this.getEffectiveUserIdInternal();
             const immediateKeys = options.immediateKeys || [];
             const properties = options.properties || {};
             const request = {
@@ -1108,7 +1348,7 @@ class GrainAnalytics {
     async preloadConfig(immediateKeys = [], properties) {
         try {
             // Use effective userId (will be generated if not set)
-            const effectiveUserId = this.getEffectiveUserId();
+            const effectiveUserId = this.getEffectiveUserIdInternal();
             this.log(`Preloading config for user: ${effectiveUserId}`);
             const response = await this.fetchConfig({ immediateKeys, properties });
             if (response) {
@@ -1130,6 +1370,63 @@ class GrainAnalytics {
         }
         return chunks;
     }
+    // Privacy & Consent Methods
+    /**
+     * Grant consent for tracking
+     * @param categories - Optional array of consent categories (e.g., ['analytics', 'functional'])
+     */
+    grantConsent(categories) {
+        try {
+            this.consentManager.grantConsent(categories);
+            this.log('Consent granted', categories);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'grantConsent');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Revoke consent for tracking (opt-out)
+     * @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 = [];
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'revokeConsent');
+            this.logError(formattedError);
+        }
+    }
+    /**
+     * Get current consent state
+     */
+    getConsentState() {
+        return this.consentManager.getConsentState();
+    }
+    /**
+     * Check if user has granted consent
+     * @param category - Optional category to check (if not provided, checks general consent)
+     */
+    hasConsent(category) {
+        return this.consentManager.hasConsent(category);
+    }
+    /**
+     * Add listener for consent state changes
+     */
+    onConsentChange(listener) {
+        this.consentManager.addListener(listener);
+    }
+    /**
+     * Remove consent change listener
+     */
+    offConsentChange(listener) {
+        this.consentManager.removeListener(listener);
+    }
     /**
      * Destroy the client and clean up resources
      */
@@ -1143,6 +1440,19 @@ class GrainAnalytics {
         this.stopConfigRefreshTimer();
         // Clear config change listeners
         this.configChangeListeners = [];
+        // Destroy automatic tracking managers
+        if (this.heartbeatManager) {
+            this.heartbeatManager.destroy();
+            this.heartbeatManager = null;
+        }
+        if (this.pageTrackingManager) {
+            this.pageTrackingManager.destroy();
+            this.pageTrackingManager = null;
+        }
+        if (this.activityDetector) {
+            this.activityDetector.destroy();
+            this.activityDetector = null;
+        }
         // Send any remaining events (in chunks if necessary)
         if (this.eventQueue.length > 0) {
             const eventsToSend = [...this.eventQueue];