@grainql/analytics-web 1.6.1 → 1.7.0

package/dist/index.mjs

@@ -111,6 +111,125 @@ export class GrainAnalytics {
             console.log('[Grain Analytics]', ...args);
         }
     }
+    /**
+     * Create error digest from events
+     */
+    createErrorDigest(events) {
+        const eventNames = [...new Set(events.map(e => e.eventName))];
+        const userIds = [...new Set(events.map(e => e.userId))];
+        let totalProperties = 0;
+        let totalSize = 0;
+        events.forEach(event => {
+            const properties = event.properties || {};
+            totalProperties += Object.keys(properties).length;
+            totalSize += JSON.stringify(event).length;
+        });
+        return {
+            eventCount: events.length,
+            totalProperties,
+            totalSize,
+            eventNames,
+            userIds,
+        };
+    }
+    /**
+     * Format error with beautiful structure
+     */
+    formatError(error, context, events) {
+        const digest = events ? this.createErrorDigest(events) : {
+            eventCount: 0,
+            totalProperties: 0,
+            totalSize: 0,
+            eventNames: [],
+            userIds: [],
+        };
+        let code = 'UNKNOWN_ERROR';
+        let message = 'An unknown error occurred';
+        if (error instanceof Error) {
+            message = error.message;
+            // Determine error code based on error type and message
+            if (message.includes('fetch failed') || message.includes('network error')) {
+                code = 'NETWORK_ERROR';
+            }
+            else if (message.includes('timeout')) {
+                code = 'TIMEOUT_ERROR';
+            }
+            else if (message.includes('HTTP 4')) {
+                code = 'CLIENT_ERROR';
+            }
+            else if (message.includes('HTTP 5')) {
+                code = 'SERVER_ERROR';
+            }
+            else if (message.includes('JSON')) {
+                code = 'PARSE_ERROR';
+            }
+            else if (message.includes('auth') || message.includes('unauthorized')) {
+                code = 'AUTH_ERROR';
+            }
+            else if (message.includes('rate limit') || message.includes('429')) {
+                code = 'RATE_LIMIT_ERROR';
+            }
+            else {
+                code = 'GENERAL_ERROR';
+            }
+        }
+        else if (typeof error === 'string') {
+            message = error;
+            code = 'STRING_ERROR';
+        }
+        else if (error && typeof error === 'object' && 'status' in error) {
+            const status = error.status;
+            code = `HTTP_${status}`;
+            message = `HTTP ${status} error`;
+        }
+        return {
+            code,
+            message,
+            digest,
+            timestamp: new Date().toISOString(),
+            context,
+            originalError: error,
+        };
+    }
+    /**
+     * Log formatted error gracefully
+     */
+    logError(formattedError) {
+        const { code, message, digest, timestamp, context } = formattedError;
+        const errorOutput = {
+            '🚨 Grain Analytics Error': {
+                'Error Code': code,
+                'Message': message,
+                'Context': context,
+                'Timestamp': timestamp,
+                'Event Digest': {
+                    'Events': digest.eventCount,
+                    'Properties': digest.totalProperties,
+                    'Size (bytes)': digest.totalSize,
+                    'Event Names': digest.eventNames.length > 0 ? digest.eventNames.join(', ') : 'None',
+                    'User IDs': digest.userIds.length > 0 ? digest.userIds.slice(0, 3).join(', ') + (digest.userIds.length > 3 ? '...' : '') : 'None',
+                }
+            }
+        };
+        console.error('🚨 Grain Analytics Error:', errorOutput);
+        // Also log in a more compact format for debugging
+        if (this.config.debug) {
+            console.error(`[Grain Analytics] ${code}: ${message} (${context}) - Events: ${digest.eventCount}, Props: ${digest.totalProperties}, Size: ${digest.totalSize}B`);
+        }
+    }
+    /**
+     * Safely execute a function with error handling
+     */
+    async safeExecute(fn, context, events) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, context, events);
+            this.logError(formattedError);
+            return null;
+        }
+    }
     formatEvent(event) {
         return {
             eventName: event.eventName,
@@ -198,20 +317,22 @@ export class GrainAnalytics {
             catch (error) {
                 lastError = error;
                 if (attempt === this.config.retryAttempts) {
-                    // Last attempt, don't retry
-                    break;
+                    // Last attempt, don't retry - log error gracefully
+                    const formattedError = this.formatError(error, `sendEvents (attempt ${attempt + 1}/${this.config.retryAttempts + 1})`, events);
+                    this.logError(formattedError);
+                    return; // Don't throw, just return gracefully
                 }
                 if (!this.isRetriableError(error)) {
-                    // Non-retriable error, don't retry
-                    break;
+                    // Non-retriable error, don't retry - log error gracefully
+                    const formattedError = this.formatError(error, `sendEvents (non-retriable error)`, events);
+                    this.logError(formattedError);
+                    return; // Don't throw, just return gracefully
                 }
                 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 send events after all retries:', lastError);
-        throw lastError;
     }
     async sendEventsWithBeacon(events) {
         if (events.length === 0)
@@ -239,7 +360,9 @@ export class GrainAnalytics {
             this.log(`Successfully sent ${events.length} events via fetch (keepalive)`);
         }
         catch (error) {
-            console.error('[Grain Analytics] Failed to send events via beacon:', error);
+            // Log error gracefully for beacon failures (page unload scenarios)
+            const formattedError = this.formatError(error, 'sendEventsWithBeacon', events);
+            this.logError(formattedError);
         }
     }
     startFlushTimer() {
@@ -249,7 +372,8 @@ export class GrainAnalytics {
         this.flushTimer = window.setInterval(() => {
             if (this.eventQueue.length > 0) {
                 this.flush().catch((error) => {
-                    console.error('[Grain Analytics] Auto-flush failed:', error);
+                    const formattedError = this.formatError(error, 'auto-flush');
+                    this.logError(formattedError);
                 });
             }
         }, this.config.flushInterval);
@@ -290,28 +414,37 @@ export class GrainAnalytics {
         });
     }
     async track(eventOrName, propertiesOrOptions, options) {
-        if (this.isDestroyed) {
-            throw new Error('Grain Analytics: Client has been destroyed');
-        }
-        let event;
-        let opts = {};
-        if (typeof eventOrName === 'string') {
-            event = {
-                eventName: eventOrName,
-                properties: propertiesOrOptions,
-            };
-            opts = options || {};
-        }
-        else {
-            event = eventOrName;
-            opts = propertiesOrOptions || {};
+        try {
+            if (this.isDestroyed) {
+                const error = new Error('Grain Analytics: Client has been destroyed');
+                const formattedError = this.formatError(error, 'track (client destroyed)');
+                this.logError(formattedError);
+                return;
+            }
+            let event;
+            let opts = {};
+            if (typeof eventOrName === 'string') {
+                event = {
+                    eventName: eventOrName,
+                    properties: propertiesOrOptions,
+                };
+                opts = options || {};
+            }
+            else {
+                event = eventOrName;
+                opts = propertiesOrOptions || {};
+            }
+            const formattedEvent = this.formatEvent(event);
+            this.eventQueue.push(formattedEvent);
+            this.log(`Queued event: ${event.eventName}`, event.properties);
+            // Check if we should flush immediately
+            if (opts.flush || this.eventQueue.length >= this.config.batchSize) {
+                await this.flush();
+            }
         }
-        const formattedEvent = this.formatEvent(event);
-        this.eventQueue.push(formattedEvent);
-        this.log(`Queued event: ${event.eventName}`, event.properties);
-        // Check if we should flush immediately
-        if (opts.flush || this.eventQueue.length >= this.config.batchSize) {
-            await this.flush();
+        catch (error) {
+            const formattedError = this.formatError(error, 'track');
+            this.logError(formattedError);
         }
     }
     /**
@@ -350,36 +483,51 @@ export class GrainAnalytics {
      * Set user properties
      */
     async setProperty(properties, options) {
-        if (this.isDestroyed) {
-            throw new Error('Grain Analytics: Client has been destroyed');
-        }
-        const userId = options?.userId || this.getEffectiveUserId();
-        // 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] = '';
+        try {
+            if (this.isDestroyed) {
+                const error = new Error('Grain Analytics: Client has been destroyed');
+                const formattedError = this.formatError(error, 'setProperty (client destroyed)');
+                this.logError(formattedError);
+                return;
             }
-            else if (typeof value === 'string') {
-                serializedProperties[key] = value;
+            const userId = options?.userId || this.getEffectiveUserId();
+            // Validate property count (max 4 properties)
+            const propertyKeys = Object.keys(properties);
+            if (propertyKeys.length > 4) {
+                const error = new Error('Grain Analytics: Maximum 4 properties allowed per request');
+                const formattedError = this.formatError(error, 'setProperty (validation)');
+                this.logError(formattedError);
+                return;
             }
-            else {
-                serializedProperties[key] = JSON.stringify(value);
+            if (propertyKeys.length === 0) {
+                const error = new Error('Grain Analytics: At least one property is required');
+                const formattedError = this.formatError(error, 'setProperty (validation)');
+                this.logError(formattedError);
+                return;
+            }
+            // 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);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'setProperty');
+            this.logError(formattedError);
         }
-        const payload = {
-            userId,
-            ...serializedProperties,
-        };
-        await this.sendProperties(payload);
     }
     /**
      * Send properties to the API
@@ -420,83 +568,139 @@ export class GrainAnalytics {
             catch (error) {
                 lastError = error;
                 if (attempt === this.config.retryAttempts) {
-                    // Last attempt, don't retry
-                    break;
+                    // Last attempt, don't retry - log error gracefully
+                    const formattedError = this.formatError(error, `sendProperties (attempt ${attempt + 1}/${this.config.retryAttempts + 1})`);
+                    this.logError(formattedError);
+                    return; // Don't throw, just return gracefully
                 }
                 if (!this.isRetriableError(error)) {
-                    // Non-retriable error, don't retry
-                    break;
+                    // Non-retriable error, don't retry - log error gracefully
+                    const formattedError = this.formatError(error, 'sendProperties (non-retriable error)');
+                    this.logError(formattedError);
+                    return; // Don't throw, just return gracefully
                 }
                 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
      */
     async trackLogin(properties, options) {
-        return this.track('login', properties, options);
+        try {
+            return await this.track('login', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackLogin');
+            this.logError(formattedError);
+        }
     }
     /**
      * Track user signup event
      */
     async trackSignup(properties, options) {
-        return this.track('signup', properties, options);
+        try {
+            return await this.track('signup', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackSignup');
+            this.logError(formattedError);
+        }
     }
     /**
      * Track checkout event
      */
     async trackCheckout(properties, options) {
-        return this.track('checkout', properties, options);
+        try {
+            return await this.track('checkout', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackCheckout');
+            this.logError(formattedError);
+        }
     }
     /**
      * Track page view event
      */
     async trackPageView(properties, options) {
-        return this.track('page_view', properties, options);
+        try {
+            return await this.track('page_view', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackPageView');
+            this.logError(formattedError);
+        }
     }
     /**
      * Track purchase event
      */
     async trackPurchase(properties, options) {
-        return this.track('purchase', properties, options);
+        try {
+            return await this.track('purchase', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackPurchase');
+            this.logError(formattedError);
+        }
     }
     /**
      * Track search event
      */
     async trackSearch(properties, options) {
-        return this.track('search', properties, options);
+        try {
+            return await this.track('search', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackSearch');
+            this.logError(formattedError);
+        }
     }
     /**
      * Track add to cart event
      */
     async trackAddToCart(properties, options) {
-        return this.track('add_to_cart', properties, options);
+        try {
+            return await this.track('add_to_cart', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackAddToCart');
+            this.logError(formattedError);
+        }
     }
     /**
      * Track remove from cart event
      */
     async trackRemoveFromCart(properties, options) {
-        return this.track('remove_from_cart', properties, options);
+        try {
+            return await this.track('remove_from_cart', properties, options);
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'trackRemoveFromCart');
+            this.logError(formattedError);
+        }
     }
     /**
      * Manually flush all queued events
      */
     async flush() {
-        if (this.eventQueue.length === 0)
-            return;
-        const eventsToSend = [...this.eventQueue];
-        this.eventQueue = [];
-        // Split events into chunks to respect maxEventsPerRequest limit
-        const chunks = this.chunkEvents(eventsToSend, this.config.maxEventsPerRequest);
-        // Send all chunks sequentially to maintain order
-        for (const chunk of chunks) {
-            await this.sendEvents(chunk);
+        try {
+            if (this.eventQueue.length === 0)
+                return;
+            const eventsToSend = [...this.eventQueue];
+            this.eventQueue = [];
+            // Split events into chunks to respect maxEventsPerRequest limit
+            const chunks = this.chunkEvents(eventsToSend, this.config.maxEventsPerRequest);
+            // Send all chunks sequentially to maintain order
+            for (const chunk of chunks) {
+                await this.sendEvents(chunk);
+            }
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'flush');
+            this.logError(formattedError);
         }
     }
     // Remote Config Methods
@@ -559,89 +763,109 @@ export class GrainAnalytics {
      * 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;
+        try {
+            if (this.isDestroyed) {
+                const error = new Error('Grain Analytics: Client has been destroyed');
+                const formattedError = this.formatError(error, 'fetchConfig (client destroyed)');
+                this.logError(formattedError);
+                return null;
+            }
+            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;
+                        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 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;
+                    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;
                 }
-                if (!this.isRetriableError(error)) {
-                    break;
+                catch (error) {
+                    lastError = error;
+                    if (attempt === this.config.retryAttempts) {
+                        // Last attempt, don't retry - log error gracefully
+                        const formattedError = this.formatError(error, `fetchConfig (attempt ${attempt + 1}/${this.config.retryAttempts + 1})`);
+                        this.logError(formattedError);
+                        return null;
+                    }
+                    if (!this.isRetriableError(error)) {
+                        // Non-retriable error, don't retry - log error gracefully
+                        const formattedError = this.formatError(error, 'fetchConfig (non-retriable error)');
+                        this.logError(formattedError);
+                        return null;
+                    }
+                    const delayMs = this.config.retryDelay * Math.pow(2, attempt);
+                    this.log(`Retrying config fetch in ${delayMs}ms after error:`, error);
+                    await this.delay(delayMs);
                 }
-                const delayMs = this.config.retryDelay * Math.pow(2, attempt);
-                this.log(`Retrying config fetch in ${delayMs}ms after error:`, error);
-                await this.delay(delayMs);
             }
+            return null;
+        }
+        catch (error) {
+            const formattedError = this.formatError(error, 'fetchConfig');
+            this.logError(formattedError);
+            return null;
         }
-        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 {
+            // 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
             const response = await this.fetchConfig(options);
-            return response.configurations[key];
+            if (response) {
+                return response.configurations[key];
+            }
+            // Return default as fallback
+            return this.config.defaultConfigurations?.[key];
         }
         catch (error) {
-            this.log(`Failed to fetch config for key "${key}":`, error);
+            const formattedError = this.formatError(error, 'getConfigAsync');
+            this.logError(formattedError);
             // Return default as fallback
             return this.config.defaultConfigurations?.[key];
         }
@@ -650,17 +874,22 @@ export class GrainAnalytics {
      * 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 {
+            // Return cache if available and not forcing refresh
+            if (!options.forceRefresh && this.configCache?.configurations) {
+                return { ...this.config.defaultConfigurations, ...this.configCache.configurations };
+            }
+            // Fetch from API
             const response = await this.fetchConfig(options);
-            return { ...this.config.defaultConfigurations, ...response.configurations };
+            if (response) {
+                return { ...this.config.defaultConfigurations, ...response.configurations };
+            }
+            // Return defaults as fallback
+            return { ...this.config.defaultConfigurations };
         }
         catch (error) {
-            this.log('Failed to fetch all configs:', error);
+            const formattedError = this.formatError(error, 'getAllConfigsAsync');
+            this.logError(formattedError);
             // Return defaults as fallback
             return { ...this.config.defaultConfigurations };
         }
@@ -721,7 +950,8 @@ export class GrainAnalytics {
         this.configRefreshTimer = window.setInterval(() => {
             if (!this.isDestroyed && this.globalUserId) {
                 this.fetchConfig().catch((error) => {
-                    console.error('[Grain Analytics] Auto-config refresh failed:', error);
+                    const formattedError = this.formatError(error, 'auto-config refresh');
+                    this.logError(formattedError);
                 });
             }
         }, this.config.configRefreshInterval);
@@ -739,16 +969,19 @@ export class GrainAnalytics {
      * 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();
+            if (!this.globalUserId) {
+                this.log('Cannot preload config: no user ID set');
+                return;
+            }
+            const response = await this.fetchConfig({ immediateKeys, properties });
+            if (response) {
+                this.startConfigRefreshTimer();
+            }
         }
         catch (error) {
-            this.log('Failed to preload config:', error);
+            const formattedError = this.formatError(error, 'preloadConfig');
+            this.logError(formattedError);
         }
     }
     /**