@grainql/analytics-web 1.4.0 → 1.6.1

package/dist/index.mjs

@@ -8,6 +8,12 @@ export class GrainAnalytics {
         this.flushTimer = null;
         this.isDestroyed = false;
         this.globalUserId = null;
+        this.persistentAnonymousUserId = null;
+        // Remote Config properties
+        this.configCache = null;
+        this.configRefreshTimer = null;
+        this.configChangeListeners = [];
+        this.configFetchPromise = null;
         this.config = {
             apiUrl: 'https://api.grainql.com',
             authStrategy: 'NONE',
@@ -17,6 +23,11 @@ export class GrainAnalytics {
             retryDelay: 1000, // 1 second
             maxEventsPerRequest: 160, // Maximum events per API request
             debug: false,
+            // Remote Config defaults
+            defaultConfigurations: {},
+            configCacheKey: 'grain_config',
+            configRefreshInterval: 300000, // 5 minutes
+            enableConfigCache: true,
             ...config,
             tenantId: config.tenantId,
         };
@@ -25,8 +36,10 @@ export class GrainAnalytics {
             this.globalUserId = config.userId;
         }
         this.validateConfig();
+        this.initializePersistentAnonymousUserId();
         this.setupBeforeUnload();
         this.startFlushTimer();
+        this.initializeConfigCache();
     }
     validateConfig() {
         if (!this.config.tenantId) {
@@ -39,6 +52,60 @@ export class GrainAnalytics {
             throw new Error('Grain Analytics: authProvider is required for JWT auth strategy');
         }
     }
+    /**
+     * Generate a UUID v4 string
+     */
+    generateUUID() {
+        if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+            return crypto.randomUUID();
+        }
+        // Fallback for environments without crypto.randomUUID
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+            const r = Math.random() * 16 | 0;
+            const v = c === 'x' ? r : (r & 0x3 | 0x8);
+            return v.toString(16);
+        });
+    }
+    /**
+     * Format UUID for anonymous user ID (remove dashes and prefix with 'temp:')
+     */
+    formatAnonymousUserId(uuid) {
+        return `temp:${uuid.replace(/-/g, '')}`;
+    }
+    /**
+     * Initialize persistent anonymous user ID from localStorage or create new one
+     */
+    initializePersistentAnonymousUserId() {
+        if (typeof window === 'undefined')
+            return;
+        const storageKey = `grain_anonymous_user_id_${this.config.tenantId}`;
+        try {
+            const stored = localStorage.getItem(storageKey);
+            if (stored) {
+                this.persistentAnonymousUserId = stored;
+                this.log('Loaded persistent anonymous user ID:', this.persistentAnonymousUserId);
+            }
+            else {
+                // Generate new anonymous user ID
+                const uuid = this.generateUUID();
+                this.persistentAnonymousUserId = this.formatAnonymousUserId(uuid);
+                localStorage.setItem(storageKey, this.persistentAnonymousUserId);
+                this.log('Generated new persistent anonymous user ID:', this.persistentAnonymousUserId);
+            }
+        }
+        catch (error) {
+            this.log('Failed to initialize persistent anonymous user ID:', error);
+            // Fallback: generate temporary ID without persistence
+            const uuid = this.generateUUID();
+            this.persistentAnonymousUserId = this.formatAnonymousUserId(uuid);
+        }
+    }
+    /**
+     * Get the effective user ID (global userId or persistent anonymous ID)
+     */
+    getEffectiveUserId() {
+        return this.globalUserId || this.persistentAnonymousUserId || 'anonymous';
+    }
     log(...args) {
         if (this.config.debug) {
             console.log('[Grain Analytics]', ...args);
@@ -47,7 +114,7 @@ export class GrainAnalytics {
     formatEvent(event) {
         return {
             eventName: event.eventName,
-            userId: event.userId || this.globalUserId || 'anonymous',
+            userId: event.userId || this.getEffectiveUserId(),
             properties: event.properties || {},
         };
     }
@@ -253,6 +320,8 @@ export class GrainAnalytics {
     identify(userId) {
         this.log(`Identified user: ${userId}`);
         this.globalUserId = userId;
+        // Clear persistent anonymous user ID since we now have a real user ID
+        this.persistentAnonymousUserId = null;
     }
     /**
      * Set global user ID for all subsequent events
@@ -260,6 +329,10 @@ export class GrainAnalytics {
     setUserId(userId) {
         this.log(`Set global user ID: ${userId}`);
         this.globalUserId = userId;
+        // Clear persistent anonymous user ID if setting a real user ID
+        if (userId) {
+            this.persistentAnonymousUserId = null;
+        }
     }
     /**
      * Get current global user ID
@@ -267,6 +340,12 @@ export class GrainAnalytics {
     getUserId() {
         return this.globalUserId;
     }
+    /**
+     * Get current effective user ID (global userId or persistent anonymous ID)
+     */
+    getEffectiveUserIdPublic() {
+        return this.getEffectiveUserId();
+    }
     /**
      * Set user properties
      */
@@ -274,7 +353,7 @@ export class GrainAnalytics {
         if (this.isDestroyed) {
             throw new Error('Grain Analytics: Client has been destroyed');
         }
-        const userId = options?.userId || this.globalUserId || 'anonymous';
+        const userId = options?.userId || this.getEffectiveUserId();
         // Validate property count (max 4 properties)
         const propertyKeys = Object.keys(properties);
         if (propertyKeys.length > 4) {
@@ -420,6 +499,258 @@ export class GrainAnalytics {
             await this.sendEvents(chunk);
         }
     }
+    // Remote Config Methods
+    /**
+     * Initialize configuration cache from localStorage
+     */
+    initializeConfigCache() {
+        if (!this.config.enableConfigCache || typeof window === 'undefined')
+            return;
+        try {
+            const cached = localStorage.getItem(this.config.configCacheKey);
+            if (cached) {
+                this.configCache = JSON.parse(cached);
+                this.log('Loaded configuration from cache:', this.configCache);
+            }
+        }
+        catch (error) {
+            this.log('Failed to load configuration cache:', error);
+        }
+    }
+    /**
+     * Save configuration cache to localStorage
+     */
+    saveConfigCache(cache) {
+        if (!this.config.enableConfigCache || typeof window === 'undefined')
+            return;
+        try {
+            localStorage.setItem(this.config.configCacheKey, JSON.stringify(cache));
+            this.log('Saved configuration to cache:', cache);
+        }
+        catch (error) {
+            this.log('Failed to save configuration cache:', error);
+        }
+    }
+    /**
+     * Get configuration value with fallback to defaults
+     */
+    getConfig(key) {
+        // First check cache
+        if (this.configCache?.configurations?.[key]) {
+            return this.configCache.configurations[key];
+        }
+        // Then check defaults
+        if (this.config.defaultConfigurations?.[key]) {
+            return this.config.defaultConfigurations[key];
+        }
+        return undefined;
+    }
+    /**
+     * Get all configurations with fallback to defaults
+     */
+    getAllConfigs() {
+        const configs = { ...this.config.defaultConfigurations };
+        if (this.configCache?.configurations) {
+            Object.assign(configs, this.configCache.configurations);
+        }
+        return configs;
+    }
+    /**
+     * Fetch configurations from API
+     */
+    async fetchConfig(options = {}) {
+        if (this.isDestroyed) {
+            throw new Error('Grain Analytics: Client has been destroyed');
+        }
+        const userId = options.userId || this.getEffectiveUserId();
+        const immediateKeys = options.immediateKeys || [];
+        const properties = options.properties || {};
+        const request = {
+            userId,
+            immediateKeys,
+            properties,
+        };
+        let lastError;
+        for (let attempt = 0; attempt <= this.config.retryAttempts; attempt++) {
+            try {
+                const headers = await this.getAuthHeaders();
+                const url = `${this.config.apiUrl}/v1/client/${encodeURIComponent(this.config.tenantId)}/config/configurations`;
+                this.log(`Fetching configurations for user ${userId} (attempt ${attempt + 1})`);
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(request),
+                });
+                if (!response.ok) {
+                    let errorMessage = `HTTP ${response.status}`;
+                    try {
+                        const errorBody = await response.json();
+                        if (errorBody?.message) {
+                            errorMessage = errorBody.message;
+                        }
+                    }
+                    catch {
+                        const errorText = await response.text();
+                        if (errorText) {
+                            errorMessage = errorText;
+                        }
+                    }
+                    const error = new Error(`Failed to fetch configurations: ${errorMessage}`);
+                    error.status = response.status;
+                    throw error;
+                }
+                const configResponse = await response.json();
+                // Update cache if successful
+                if (configResponse.configurations) {
+                    this.updateConfigCache(configResponse, userId);
+                }
+                this.log(`Successfully fetched configurations for user ${userId}:`, configResponse);
+                return configResponse;
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt === this.config.retryAttempts) {
+                    break;
+                }
+                if (!this.isRetriableError(error)) {
+                    break;
+                }
+                const delayMs = this.config.retryDelay * Math.pow(2, attempt);
+                this.log(`Retrying config fetch in ${delayMs}ms after error:`, error);
+                await this.delay(delayMs);
+            }
+        }
+        console.error('[Grain Analytics] Failed to fetch configurations after all retries:', lastError);
+        throw lastError;
+    }
+    /**
+     * Get configuration asynchronously (cache-first with fallback to API)
+     */
+    async getConfigAsync(key, options = {}) {
+        // Return immediately if we have it in cache and not forcing refresh
+        if (!options.forceRefresh && this.configCache?.configurations?.[key]) {
+            return this.configCache.configurations[key];
+        }
+        // Return default if available and not forcing refresh
+        if (!options.forceRefresh && this.config.defaultConfigurations?.[key]) {
+            return this.config.defaultConfigurations[key];
+        }
+        // Fetch from API
+        try {
+            const response = await this.fetchConfig(options);
+            return response.configurations[key];
+        }
+        catch (error) {
+            this.log(`Failed to fetch config for key "${key}":`, error);
+            // Return default as fallback
+            return this.config.defaultConfigurations?.[key];
+        }
+    }
+    /**
+     * Get all configurations asynchronously (cache-first with fallback to API)
+     */
+    async getAllConfigsAsync(options = {}) {
+        // Return cache if available and not forcing refresh
+        if (!options.forceRefresh && this.configCache?.configurations) {
+            return { ...this.config.defaultConfigurations, ...this.configCache.configurations };
+        }
+        // Fetch from API
+        try {
+            const response = await this.fetchConfig(options);
+            return { ...this.config.defaultConfigurations, ...response.configurations };
+        }
+        catch (error) {
+            this.log('Failed to fetch all configs:', error);
+            // Return defaults as fallback
+            return { ...this.config.defaultConfigurations };
+        }
+    }
+    /**
+     * Update configuration cache and notify listeners
+     */
+    updateConfigCache(response, userId) {
+        const newCache = {
+            configurations: response.configurations,
+            snapshotId: response.snapshotId,
+            timestamp: response.timestamp,
+            userId,
+        };
+        const oldConfigs = this.configCache?.configurations || {};
+        this.configCache = newCache;
+        this.saveConfigCache(newCache);
+        // Notify listeners if configurations changed
+        if (JSON.stringify(oldConfigs) !== JSON.stringify(response.configurations)) {
+            this.notifyConfigChangeListeners(response.configurations);
+        }
+    }
+    /**
+     * Add configuration change listener
+     */
+    addConfigChangeListener(listener) {
+        this.configChangeListeners.push(listener);
+    }
+    /**
+     * Remove configuration change listener
+     */
+    removeConfigChangeListener(listener) {
+        const index = this.configChangeListeners.indexOf(listener);
+        if (index > -1) {
+            this.configChangeListeners.splice(index, 1);
+        }
+    }
+    /**
+     * Notify all configuration change listeners
+     */
+    notifyConfigChangeListeners(configurations) {
+        this.configChangeListeners.forEach(listener => {
+            try {
+                listener(configurations);
+            }
+            catch (error) {
+                console.error('[Grain Analytics] Config change listener error:', error);
+            }
+        });
+    }
+    /**
+     * Start automatic configuration refresh timer
+     */
+    startConfigRefreshTimer() {
+        if (this.configRefreshTimer) {
+            clearInterval(this.configRefreshTimer);
+        }
+        this.configRefreshTimer = window.setInterval(() => {
+            if (!this.isDestroyed && this.globalUserId) {
+                this.fetchConfig().catch((error) => {
+                    console.error('[Grain Analytics] Auto-config refresh failed:', error);
+                });
+            }
+        }, this.config.configRefreshInterval);
+    }
+    /**
+     * Stop automatic configuration refresh timer
+     */
+    stopConfigRefreshTimer() {
+        if (this.configRefreshTimer) {
+            clearInterval(this.configRefreshTimer);
+            this.configRefreshTimer = null;
+        }
+    }
+    /**
+     * Preload configurations for immediate access
+     */
+    async preloadConfig(immediateKeys = [], properties) {
+        if (!this.globalUserId) {
+            this.log('Cannot preload config: no user ID set');
+            return;
+        }
+        try {
+            await this.fetchConfig({ immediateKeys, properties });
+            this.startConfigRefreshTimer();
+        }
+        catch (error) {
+            this.log('Failed to preload config:', error);
+        }
+    }
     /**
      * Split events array into chunks of specified size
      */
@@ -439,6 +770,10 @@ export class GrainAnalytics {
             clearInterval(this.flushTimer);
             this.flushTimer = null;
         }
+        // Stop config refresh timer
+        this.stopConfigRefreshTimer();
+        // Clear config change listeners
+        this.configChangeListeners = [];
         // Send any remaining events (in chunks if necessary)
         if (this.eventQueue.length > 0) {
             const eventsToSend = [...this.eventQueue];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@grainql/analytics-web",
-  "version": "1.4.0",
-  "description": "Lightweight TypeScript SDK for sending analytics events to Grain's REST API",
+  "version": "1.6.1",
+  "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",
   "types": "dist/index.d.ts",