@grainql/analytics-web 2.0.0 → 2.1.0

package/dist/index.mjs

@@ -2,9 +2,15 @@
  * Grain Analytics Web SDK
  * A lightweight, dependency-free TypeScript SDK for sending analytics events to Grain's REST API
  */
+import { ConsentManager } from './consent';
+import { setCookie, getCookie, areCookiesEnabled } from './cookies';
+import { ActivityDetector } from './activity';
+import { HeartbeatManager } from './heartbeat';
+import { PageTrackingManager } from './page-tracking';
 export class GrainAnalytics {
     constructor(config) {
         this.eventQueue = [];
+        this.waitingForConsentQueue = [];
         this.flushTimer = null;
         this.isDestroyed = false;
         this.globalUserId = null;
@@ -14,6 +20,13 @@ export 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',
@@ -28,9 +41,30 @@ export 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 ConsentManager(this.config.tenantId, this.config.consentMode);
+        // Check if cookies are enabled
+        if (this.config.enableCookies) {
+            this.cookiesEnabled = 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;
@@ -40,6 +74,18 @@ export 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) {
@@ -73,22 +119,38 @@ export 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 = 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);
             }
         }
@@ -98,10 +160,36 @@ export 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,
+                };
+                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;
         }
@@ -249,7 +337,7 @@ export class GrainAnalytics {
     formatEvent(event) {
         return {
             eventName: event.eventName,
-            userId: event.userId || this.getEffectiveUserId(),
+            userId: event.userId || this.getEffectiveUserIdInternal(),
             properties: event.properties || {},
         };
     }
@@ -429,6 +517,120 @@ export class GrainAnalytics {
             }
         });
     }
+    /**
+     * Initialize automatic tracking (heartbeat and page views)
+     */
+    initializeAutomaticTracking() {
+        if (this.config.enableHeartbeat) {
+            try {
+                this.activityDetector = new ActivityDetector();
+                this.heartbeatManager = new 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 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) {
@@ -450,8 +652,30 @@ export 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) {
@@ -463,6 +687,22 @@ export 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)
      */
@@ -509,7 +749,7 @@ export 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
@@ -559,7 +799,7 @@ export 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');
@@ -604,7 +844,7 @@ export 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');
@@ -622,7 +862,7 @@ export 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) {
@@ -902,7 +1142,7 @@ export 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 = {
@@ -1104,7 +1344,7 @@ export 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) {
@@ -1126,6 +1366,63 @@ export 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
      */
@@ -1139,6 +1436,19 @@ export 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];

package/dist/page-tracking.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Page Tracking for Grain Analytics
+ * Automatically tracks page views with consent-aware behavior
+ */
+export interface PageTrackingConfig {
+    stripQueryParams: boolean;
+    debug?: boolean;
+}
+export interface PageTracker {
+    trackSystemEvent(eventName: string, properties: Record<string, unknown>): void;
+    hasConsent(category?: string): boolean;
+    getEffectiveUserId(): string;
+    getEphemeralSessionId(): string;
+}
+export declare class PageTrackingManager {
+    private config;
+    private tracker;
+    private isDestroyed;
+    private currentPath;
+    private originalPushState;
+    private originalReplaceState;
+    constructor(tracker: PageTracker, config: PageTrackingConfig);
+    /**
+     * Setup History API listeners (pushState, replaceState, popstate)
+     */
+    private setupHistoryListeners;
+    /**
+     * Setup hash change listener
+     */
+    private setupHashChangeListener;
+    /**
+     * Handle popstate event (back/forward navigation)
+     */
+    private handlePopState;
+    /**
+     * Handle hash change event
+     */
+    private handleHashChange;
+    /**
+     * Track the current page
+     */
+    private trackCurrentPage;
+    /**
+     * Extract path from URL, optionally stripping query parameters
+     */
+    private extractPath;
+    /**
+     * Get the current page path
+     */
+    getCurrentPage(): string | null;
+    /**
+     * Manually track a page view (for custom navigation)
+     */
+    trackPage(page: string, properties?: Record<string, unknown>): void;
+    /**
+     * Destroy the page tracker
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=page-tracking.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"page-tracking.d.ts","sourceRoot":"","sources":["../src/page-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/E,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC,kBAAkB,IAAI,MAAM,CAAC;IAC7B,qBAAqB,IAAI,MAAM,CAAC;CACjC;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,oBAAoB,CAA4C;gBAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB;IAY5D;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAqB7B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAK/B;;OAEG;IACH,OAAO,CAAC,cAAc,CAGpB;IAEF;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAGtB;IAEF;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAmCxB;;OAEG;IACH,OAAO,CAAC,WAAW;IAmBnB;;OAEG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAgCnE;;OAEG;IACH,OAAO,IAAI,IAAI;CAyBhB"}

package/dist/react/activity.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Activity Detection for Grain Analytics
+ * Tracks user activity (mouse, keyboard, touch, scroll) to determine if user is active
+ */
+export declare class ActivityDetector {
+    private lastActivityTime;
+    private activityThreshold;
+    private listeners;
+    private boundActivityHandler;
+    private isDestroyed;
+    private readonly activityEvents;
+    constructor();
+    /**
+     * Setup event listeners for activity detection
+     */
+    private setupListeners;
+    /**
+     * Handle activity event
+     */
+    private handleActivity;
+    /**
+     * Debounce function to limit how often activity handler is called
+     */
+    private debounce;
+    /**
+     * Check if user is currently active
+     * @param threshold Time in ms to consider user inactive (default: 30s)
+     */
+    isActive(threshold?: number): boolean;
+    /**
+     * Get time since last activity in milliseconds
+     */
+    getTimeSinceLastActivity(): number;
+    /**
+     * Get last activity timestamp
+     */
+    getLastActivityTime(): number;
+    /**
+     * Set activity threshold
+     */
+    setActivityThreshold(threshold: number): void;
+    /**
+     * Add listener for activity changes
+     */
+    addListener(listener: () => void): void;
+    /**
+     * Remove listener
+     */
+    removeListener(listener: () => void): void;
+    /**
+     * Notify all listeners
+     */
+    private notifyListeners;
+    /**
+     * Cleanup and remove listeners
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=activity.d.ts.map

package/dist/react/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../src/activity.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,iBAAiB,CAAiB;IAC1C,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,oBAAoB,CAAa;IACzC,OAAO,CAAC,WAAW,CAAS;IAG5B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAOpB;;IAQX;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAMtB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAehB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO;IAMrC;;OAEG;IACH,wBAAwB,IAAI,MAAM;IAIlC;;OAEG;IACH,mBAAmB,IAAI,MAAM;IAI7B;;OAEG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI7C;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAIvC;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAO1C;;OAEG;IACH,OAAO,CAAC,eAAe;IAUvB;;OAEG;IACH,OAAO,IAAI,IAAI;CAYhB"}