@grainql/analytics-web 1.6.1 → 1.7.0

package/dist/index.global.dev.js

@@ -1,4 +1,4 @@
-/* Grain Analytics Web SDK v1.6.1 | MIT License | Development Build */
+/* Grain Analytics Web SDK v1.7.0 | MIT License | Development Build */
 "use strict";
 var Grain = (() => {
   var __defProp = Object.defineProperty;
@@ -133,6 +133,113 @@ var Grain = (() => {
         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;
+        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: (/* @__PURE__ */ new Date()).toISOString(),
+        context,
+        originalError: error
+      };
+    }
+    /**
+     * Log formatted error gracefully
+     */
+    logError(formattedError) {
+      const { code, message, digest, timestamp, context } = formattedError;
+      const errorOutput = {
+        "\u{1F6A8} 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("\u{1F6A8} Grain Analytics Error:", errorOutput);
+      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,
@@ -216,18 +323,20 @@ var Grain = (() => {
         } catch (error) {
           lastError = error;
           if (attempt === this.config.retryAttempts) {
-            break;
+            const formattedError = this.formatError(error, `sendEvents (attempt ${attempt + 1}/${this.config.retryAttempts + 1})`, events);
+            this.logError(formattedError);
+            return;
           }
           if (!this.isRetriableError(error)) {
-            break;
+            const formattedError = this.formatError(error, `sendEvents (non-retriable error)`, events);
+            this.logError(formattedError);
+            return;
           }
           const delayMs = this.config.retryDelay * Math.pow(2, attempt);
           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)
@@ -252,7 +361,8 @@ var Grain = (() => {
         });
         this.log(`Successfully sent ${events.length} events via fetch (keepalive)`);
       } catch (error) {
-        console.error("[Grain Analytics] Failed to send events via beacon:", error);
+        const formattedError = this.formatError(error, "sendEventsWithBeacon", events);
+        this.logError(formattedError);
       }
     }
     startFlushTimer() {
@@ -262,7 +372,8 @@ var Grain = (() => {
       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);
@@ -296,26 +407,34 @@ var Grain = (() => {
       });
     }
     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 || {};
-      }
-      const formattedEvent = this.formatEvent(event);
-      this.eventQueue.push(formattedEvent);
-      this.log(`Queued event: ${event.eventName}`, event.properties);
-      if (opts.flush || this.eventQueue.length >= this.config.batchSize) {
-        await this.flush();
+      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);
+        if (opts.flush || this.eventQueue.length >= this.config.batchSize) {
+          await this.flush();
+        }
+      } catch (error) {
+        const formattedError = this.formatError(error, "track");
+        this.logError(formattedError);
       }
     }
     /**
@@ -352,32 +471,46 @@ var Grain = (() => {
      * 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();
-      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");
-      }
-      const serializedProperties = {};
-      for (const [key, value] of Object.entries(properties)) {
-        if (value === null || value === void 0) {
-          serializedProperties[key] = "";
-        } else if (typeof value === "string") {
-          serializedProperties[key] = value;
-        } else {
-          serializedProperties[key] = JSON.stringify(value);
+      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;
+        }
+        const userId = options?.userId || this.getEffectiveUserId();
+        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;
+        }
+        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;
+        }
+        const serializedProperties = {};
+        for (const [key, value] of Object.entries(properties)) {
+          if (value === null || value === void 0) {
+            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
@@ -416,79 +549,126 @@ var Grain = (() => {
         } catch (error) {
           lastError = error;
           if (attempt === this.config.retryAttempts) {
-            break;
+            const formattedError = this.formatError(error, `sendProperties (attempt ${attempt + 1}/${this.config.retryAttempts + 1})`);
+            this.logError(formattedError);
+            return;
           }
           if (!this.isRetriableError(error)) {
-            break;
+            const formattedError = this.formatError(error, "sendProperties (non-retriable error)");
+            this.logError(formattedError);
+            return;
           }
           const delayMs = this.config.retryDelay * Math.pow(2, attempt);
           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 = [];
-      const chunks = this.chunkEvents(eventsToSend, this.config.maxEventsPerRequest);
-      for (const chunk of chunks) {
-        await this.sendEvents(chunk);
+      try {
+        if (this.eventQueue.length === 0)
+          return;
+        const eventsToSend = [...this.eventQueue];
+        this.eventQueue = [];
+        const chunks = this.chunkEvents(eventsToSend, this.config.maxEventsPerRequest);
+        for (const chunk of chunks) {
+          await this.sendEvents(chunk);
+        }
+      } catch (error) {
+        const formattedError = this.formatError(error, "flush");
+        this.logError(formattedError);
       }
     }
     // Remote Config Methods
@@ -547,82 +727,98 @@ var Grain = (() => {
      * 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;
+      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;
+                }
               }
+              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();
-          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 configResponse = await response.json();
+            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) {
+              const formattedError = this.formatError(error, `fetchConfig (attempt ${attempt + 1}/${this.config.retryAttempts + 1})`);
+              this.logError(formattedError);
+              return null;
+            }
+            if (!this.isRetriableError(error)) {
+              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 = {}) {
-      if (!options.forceRefresh && this.configCache?.configurations?.[key]) {
-        return this.configCache.configurations[key];
-      }
-      if (!options.forceRefresh && this.config.defaultConfigurations?.[key]) {
-        return this.config.defaultConfigurations[key];
-      }
       try {
+        if (!options.forceRefresh && this.configCache?.configurations?.[key]) {
+          return this.configCache.configurations[key];
+        }
+        if (!options.forceRefresh && this.config.defaultConfigurations?.[key]) {
+          return this.config.defaultConfigurations[key];
+        }
         const response = await this.fetchConfig(options);
-        return response.configurations[key];
+        if (response) {
+          return response.configurations[key];
+        }
+        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 this.config.defaultConfigurations?.[key];
       }
     }
@@ -630,14 +826,18 @@ var Grain = (() => {
      * Get all configurations asynchronously (cache-first with fallback to API)
      */
     async getAllConfigsAsync(options = {}) {
-      if (!options.forceRefresh && this.configCache?.configurations) {
-        return { ...this.config.defaultConfigurations, ...this.configCache.configurations };
-      }
       try {
+        if (!options.forceRefresh && this.configCache?.configurations) {
+          return { ...this.config.defaultConfigurations, ...this.configCache.configurations };
+        }
         const response = await this.fetchConfig(options);
-        return { ...this.config.defaultConfigurations, ...response.configurations };
+        if (response) {
+          return { ...this.config.defaultConfigurations, ...response.configurations };
+        }
+        return { ...this.config.defaultConfigurations };
       } catch (error) {
-        this.log("Failed to fetch all configs:", error);
+        const formattedError = this.formatError(error, "getAllConfigsAsync");
+        this.logError(formattedError);
         return { ...this.config.defaultConfigurations };
       }
     }
@@ -695,7 +895,8 @@ var Grain = (() => {
       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);
@@ -713,15 +914,18 @@ var Grain = (() => {
      * 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);
       }
     }
     /**