@grainql/analytics-web 1.3.0 → 1.6.0

package/dist/index.mjs

@@ -8,6 +8,11 @@ export class GrainAnalytics {
         this.flushTimer = null;
         this.isDestroyed = false;
         this.globalUserId = 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 +22,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,
         };
@@ -27,6 +37,7 @@ export class GrainAnalytics {
         this.validateConfig();
         this.setupBeforeUnload();
         this.startFlushTimer();
+        this.initializeConfigCache();
     }
     validateConfig() {
         if (!this.config.tenantId) {
@@ -100,7 +111,7 @@ export class GrainAnalytics {
         for (let attempt = 0; attempt <= this.config.retryAttempts; attempt++) {
             try {
                 const headers = await this.getAuthHeaders();
-                const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}`;
+                const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/multi`;
                 this.log(`Sending ${events.length} events to ${url} (attempt ${attempt + 1})`);
                 const response = await fetch(url, {
                     method: 'POST',
@@ -151,7 +162,7 @@ export class GrainAnalytics {
             return;
         try {
             const headers = await this.getAuthHeaders();
-            const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}`;
+            const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/multi`;
             const body = JSON.stringify({ events });
             // Try beacon API first (more reliable for page unload)
             if (typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
@@ -267,6 +278,95 @@ export class GrainAnalytics {
     getUserId() {
         return this.globalUserId;
     }
+    /**
+     * Set user properties
+     */
+    async setProperty(properties, options) {
+        if (this.isDestroyed) {
+            throw new Error('Grain Analytics: Client has been destroyed');
+        }
+        const userId = options?.userId || this.globalUserId || 'anonymous';
+        // Validate property count (max 4 properties)
+        const propertyKeys = Object.keys(properties);
+        if (propertyKeys.length > 4) {
+            throw new Error('Grain Analytics: Maximum 4 properties allowed per request');
+        }
+        if (propertyKeys.length === 0) {
+            throw new Error('Grain Analytics: At least one property is required');
+        }
+        // Serialize all values to strings
+        const serializedProperties = {};
+        for (const [key, value] of Object.entries(properties)) {
+            if (value === null || value === undefined) {
+                serializedProperties[key] = '';
+            }
+            else if (typeof value === 'string') {
+                serializedProperties[key] = value;
+            }
+            else {
+                serializedProperties[key] = JSON.stringify(value);
+            }
+        }
+        const payload = {
+            userId,
+            ...serializedProperties,
+        };
+        await this.sendProperties(payload);
+    }
+    /**
+     * Send properties to the API
+     */
+    async sendProperties(payload) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.config.retryAttempts; attempt++) {
+            try {
+                const headers = await this.getAuthHeaders();
+                const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/properties`;
+                this.log(`Setting properties for user ${payload.userId} (attempt ${attempt + 1})`);
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(payload),
+                });
+                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 set properties: ${errorMessage}`);
+                    error.status = response.status;
+                    throw error;
+                }
+                this.log(`Successfully set properties for user ${payload.userId}`);
+                return; // Success, exit retry loop
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt === this.config.retryAttempts) {
+                    // Last attempt, don't retry
+                    break;
+                }
+                if (!this.isRetriableError(error)) {
+                    // Non-retriable error, don't retry
+                    break;
+                }
+                const delayMs = this.config.retryDelay * Math.pow(2, attempt); // Exponential backoff
+                this.log(`Retrying in ${delayMs}ms after error:`, error);
+                await this.delay(delayMs);
+            }
+        }
+        console.error('[Grain Analytics] Failed to set properties after all retries:', lastError);
+        throw lastError;
+    }
     // Template event methods
     /**
      * Track user login event
@@ -331,6 +431,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.globalUserId || 'anonymous';
+        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
      */
@@ -350,6 +702,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.3.0",
-  "description": "Lightweight TypeScript SDK for sending analytics events to Grain's REST API",
+  "version": "1.6.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",
   "types": "dist/index.d.ts",