@klime/browser 1.0.3 → 1.2.1

package/dist/index.js

@@ -1,296 +1,431 @@
-const DEFAULT_ENDPOINT = "https://i.klime.com";
-const DEFAULT_FLUSH_INTERVAL = 2000;
-const DEFAULT_MAX_BATCH_SIZE = 20;
-const DEFAULT_MAX_QUEUE_SIZE = 1000;
-const DEFAULT_RETRY_MAX_ATTEMPTS = 5;
-const DEFAULT_RETRY_INITIAL_DELAY = 1000;
-const MAX_BATCH_SIZE = 100;
-const MAX_EVENT_SIZE_BYTES = 200 * 1024; // 200KB
-const MAX_BATCH_SIZE_BYTES = 10 * 1024 * 1024; // 10MB
-const SDK_VERSION = "1.0.1";
-export class KlimeClient {
-    constructor(config) {
-        this.queue = [];
-        this.flushTimer = null;
-        this.isShutdown = false;
-        this.flushPromise = null;
-        this.unloadHandler = null;
-        if (!config.writeKey) {
-            throw new Error("writeKey is required");
-        }
-        this.config = {
-            writeKey: config.writeKey,
-            endpoint: config.endpoint || DEFAULT_ENDPOINT,
-            flushInterval: config.flushInterval ?? DEFAULT_FLUSH_INTERVAL,
-            maxBatchSize: Math.min(config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE, MAX_BATCH_SIZE),
-            maxQueueSize: config.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE,
-            retryMaxAttempts: config.retryMaxAttempts ?? DEFAULT_RETRY_MAX_ATTEMPTS,
-            retryInitialDelay: config.retryInitialDelay ?? DEFAULT_RETRY_INITIAL_DELAY,
-            autoFlushOnUnload: config.autoFlushOnUnload ?? true,
-        };
-        if (this.config.autoFlushOnUnload && typeof window !== "undefined") {
-            this.unloadHandler = () => {
-                this.flush();
-            };
-            window.addEventListener("beforeunload", this.unloadHandler);
-        }
-        this.scheduleFlush();
+// src/types.ts
+var SendError = class extends Error {
+  constructor(message, events) {
+    super(message);
+    this.name = "SendError";
+    this.events = events;
+  }
+};
+
+// src/index.ts
+var DEFAULT_ENDPOINT = "https://i.klime.com";
+var DEFAULT_FLUSH_INTERVAL = 2e3;
+var DEFAULT_MAX_BATCH_SIZE = 20;
+var DEFAULT_MAX_QUEUE_SIZE = 1e3;
+var DEFAULT_RETRY_MAX_ATTEMPTS = 5;
+var DEFAULT_RETRY_INITIAL_DELAY = 1e3;
+var MAX_BATCH_SIZE = 100;
+var MAX_EVENT_SIZE_BYTES = 200 * 1024;
+var MAX_BATCH_SIZE_BYTES = 10 * 1024 * 1024;
+var KEEPALIVE_MAX_BODY_BYTES = 64 * 1024;
+var SDK_VERSION = "1.1.0";
+var createDefaultLogger = () => ({
+  debug: (message, ...args) => console.debug(`[Klime] ${message}`, ...args),
+  info: (message, ...args) => console.info(`[Klime] ${message}`, ...args),
+  warn: (message, ...args) => console.warn(`[Klime] ${message}`, ...args),
+  error: (message, ...args) => console.error(`[Klime] ${message}`, ...args)
+});
+var KlimeClient = class {
+  constructor(config) {
+    this.queue = [];
+    this.flushTimer = null;
+    this.isShutdown = false;
+    this.flushPromise = null;
+    this.unloadHandler = null;
+    this.visibilityChangeHandler = null;
+    if (!config.writeKey) {
+      throw new Error("writeKey is required");
     }
-    track(event, properties, options) {
-        if (this.isShutdown) {
-            return;
-        }
-        const eventObj = {
-            type: "track",
-            messageId: this.generateUUID(),
-            event,
-            timestamp: this.generateTimestamp(),
-            properties: properties || {},
-            context: this.getContext(),
-        };
-        if (options?.userId) {
-            eventObj.userId = options.userId;
-        }
-        if (options?.groupId) {
-            eventObj.groupId = options.groupId;
+    this.config = {
+      writeKey: config.writeKey,
+      endpoint: config.endpoint || DEFAULT_ENDPOINT,
+      flushInterval: config.flushInterval ?? DEFAULT_FLUSH_INTERVAL,
+      maxBatchSize: Math.min(
+        config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE,
+        MAX_BATCH_SIZE
+      ),
+      maxQueueSize: config.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE,
+      retryMaxAttempts: config.retryMaxAttempts ?? DEFAULT_RETRY_MAX_ATTEMPTS,
+      retryInitialDelay: config.retryInitialDelay ?? DEFAULT_RETRY_INITIAL_DELAY,
+      autoFlushOnUnload: config.autoFlushOnUnload ?? true,
+      logger: config.logger ?? createDefaultLogger(),
+      onError: config.onError,
+      onSuccess: config.onSuccess
+    };
+    if (this.config.autoFlushOnUnload && typeof window !== "undefined") {
+      this.unloadHandler = () => {
+        this.flush();
+      };
+      window.addEventListener("beforeunload", this.unloadHandler);
+      window.addEventListener("pagehide", this.unloadHandler);
+      this.visibilityChangeHandler = () => {
+        if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+          this.flush();
         }
-        this.enqueue(eventObj);
+      };
+      document.addEventListener("visibilitychange", this.visibilityChangeHandler);
     }
-    identify(userId, traits) {
-        if (this.isShutdown) {
-            return;
-        }
-        const eventObj = {
-            type: "identify",
-            messageId: this.generateUUID(),
-            userId,
-            timestamp: this.generateTimestamp(),
-            traits: traits || {},
-            context: this.getContext(),
-        };
-        this.enqueue(eventObj);
-    }
-    group(groupId, traits, options) {
-        if (this.isShutdown) {
-            return;
-        }
-        const eventObj = {
-            type: "group",
-            messageId: this.generateUUID(),
-            groupId,
-            timestamp: this.generateTimestamp(),
-            traits: traits || {},
-            context: this.getContext(),
-        };
-        if (options?.userId) {
-            eventObj.userId = options.userId;
-        }
-        this.enqueue(eventObj);
+    this.scheduleFlush();
+  }
+  track(event, properties, options) {
+    if (this.isShutdown) {
+      return;
     }
-    async flush() {
-        if (this.flushPromise) {
-            return this.flushPromise;
-        }
-        this.flushPromise = this.doFlush();
-        try {
-            await this.flushPromise;
-        }
-        finally {
-            this.flushPromise = null;
-        }
+    const eventObj = {
+      type: "track",
+      messageId: this.generateUUID(),
+      event,
+      timestamp: this.generateTimestamp(),
+      properties: properties || {},
+      context: this.getContext()
+    };
+    if (options?.userId) {
+      eventObj.userId = options.userId;
     }
-    async shutdown() {
-        if (this.isShutdown) {
-            return;
-        }
-        this.isShutdown = true;
-        if (this.unloadHandler && typeof window !== "undefined") {
-            window.removeEventListener("beforeunload", this.unloadHandler);
+    if (options?.groupId) {
+      eventObj.groupId = options.groupId;
+    }
+    this.enqueue(eventObj);
+  }
+  identify(userId, traits) {
+    if (this.isShutdown) {
+      return;
+    }
+    const eventObj = {
+      type: "identify",
+      messageId: this.generateUUID(),
+      userId,
+      timestamp: this.generateTimestamp(),
+      traits: traits || {},
+      context: this.getContext()
+    };
+    this.enqueue(eventObj);
+  }
+  group(groupId, traits, options) {
+    if (this.isShutdown) {
+      return;
+    }
+    const eventObj = {
+      type: "group",
+      messageId: this.generateUUID(),
+      groupId,
+      timestamp: this.generateTimestamp(),
+      traits: traits || {},
+      context: this.getContext()
+    };
+    if (options?.userId) {
+      eventObj.userId = options.userId;
+    }
+    this.enqueue(eventObj);
+  }
+  /**
+   * Track an event synchronously. Returns BatchResponse or throws SendError.
+   */
+  async trackSync(event, properties, options) {
+    if (this.isShutdown) {
+      throw new SendError("Client is shutdown", []);
+    }
+    const eventObj = {
+      type: "track",
+      messageId: this.generateUUID(),
+      event,
+      timestamp: this.generateTimestamp(),
+      properties: properties || {},
+      context: this.getContext()
+    };
+    if (options?.userId) {
+      eventObj.userId = options.userId;
+    }
+    if (options?.groupId) {
+      eventObj.groupId = options.groupId;
+    }
+    return this.sendSync([eventObj]);
+  }
+  /**
+   * Identify a user synchronously. Returns BatchResponse or throws SendError.
+   */
+  async identifySync(userId, traits) {
+    if (this.isShutdown) {
+      throw new SendError("Client is shutdown", []);
+    }
+    const eventObj = {
+      type: "identify",
+      messageId: this.generateUUID(),
+      userId,
+      timestamp: this.generateTimestamp(),
+      traits: traits || {},
+      context: this.getContext()
+    };
+    return this.sendSync([eventObj]);
+  }
+  /**
+   * Associate a user with a group synchronously. Returns BatchResponse or throws SendError.
+   */
+  async groupSync(groupId, traits, options) {
+    if (this.isShutdown) {
+      throw new SendError("Client is shutdown", []);
+    }
+    const eventObj = {
+      type: "group",
+      messageId: this.generateUUID(),
+      groupId,
+      timestamp: this.generateTimestamp(),
+      traits: traits || {},
+      context: this.getContext()
+    };
+    if (options?.userId) {
+      eventObj.userId = options.userId;
+    }
+    return this.sendSync([eventObj]);
+  }
+  /**
+   * Return the number of events currently in the queue.
+   */
+  getQueueSize() {
+    return this.queue.length;
+  }
+  async flush() {
+    if (this.flushPromise) {
+      return this.flushPromise;
+    }
+    this.flushPromise = this.doFlush();
+    try {
+      await this.flushPromise;
+    } finally {
+      this.flushPromise = null;
+    }
+  }
+  async shutdown() {
+    if (this.isShutdown) {
+      return;
+    }
+    this.isShutdown = true;
+    if (this.unloadHandler && typeof window !== "undefined") {
+      window.removeEventListener("beforeunload", this.unloadHandler);
+      window.removeEventListener("pagehide", this.unloadHandler);
+    }
+    if (this.visibilityChangeHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityChangeHandler);
+    }
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+  }
+  enqueue(event) {
+    const eventSize = this.estimateEventSize(event);
+    if (eventSize > MAX_EVENT_SIZE_BYTES) {
+      this.config.logger.warn(
+        `Event size (${eventSize} bytes) exceeds ${MAX_EVENT_SIZE_BYTES} bytes limit`
+      );
+      return;
+    }
+    if (this.queue.length >= this.config.maxQueueSize) {
+      const dropped = this.queue.shift();
+      this.config.logger.warn(`Queue full, dropping oldest event: ${dropped?.type}`);
+    }
+    this.queue.push(event);
+    this.config.logger.debug(`Enqueued ${event.type} event, queue size: ${this.queue.length}`);
+    if (this.queue.length >= this.config.maxBatchSize) {
+      this.flush();
+    }
+  }
+  async doFlush() {
+    if (this.queue.length === 0) {
+      return;
+    }
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    while (this.queue.length > 0) {
+      const batch = this.extractBatch();
+      if (batch.length === 0) {
+        break;
+      }
+      await this.sendBatch(batch);
+    }
+    this.scheduleFlush();
+  }
+  extractBatch() {
+    const batch = [];
+    let batchSize = 0;
+    while (this.queue.length > 0 && batch.length < MAX_BATCH_SIZE) {
+      const event = this.queue[0];
+      const eventSize = this.estimateEventSize(event);
+      if (batchSize + eventSize > MAX_BATCH_SIZE_BYTES) {
+        break;
+      }
+      batch.push(this.queue.shift());
+      batchSize += eventSize;
+    }
+    return batch;
+  }
+  async sendBatch(batch) {
+    if (batch.length === 0) {
+      return;
+    }
+    this.config.logger.debug(`Sending batch of ${batch.length} events`);
+    const result = await this.doSend(batch);
+    if (result === null) {
+      const error = new Error(`Failed to send batch of ${batch.length} events after retries`);
+      this.invokeOnError(error, batch);
+    } else if (result.failed > 0 && result.errors) {
+      this.config.logger.warn(
+        `Batch partially failed. Accepted: ${result.accepted}, Failed: ${result.failed}`,
+        result.errors
+      );
+      this.invokeOnSuccess(result);
+    } else {
+      this.config.logger.debug(`Batch sent successfully. Accepted: ${result.accepted}`);
+      this.invokeOnSuccess(result);
+    }
+  }
+  async sendSync(events) {
+    this.config.logger.debug(`Sending ${events.length} events synchronously`);
+    const result = await this.doSend(events);
+    if (result === null) {
+      throw new SendError(`Failed to send ${events.length} events after retries`, events);
+    }
+    return result;
+  }
+  async doSend(batch) {
+    const request = { batch };
+    const requestUrl = `${this.config.endpoint}/v1/batch`;
+    const body = JSON.stringify(request);
+    const useKeepalive = body.length <= KEEPALIVE_MAX_BODY_BYTES;
+    let attempt = 0;
+    let delay = this.config.retryInitialDelay;
+    while (attempt < this.config.retryMaxAttempts) {
+      try {
+        const response = await fetch(requestUrl, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.config.writeKey}`
+          },
+          body,
+          keepalive: useKeepalive
+        });
+        const data = await response.json();
+        if (response.ok) {
+          return data;
         }
-        if (this.flushTimer) {
-            clearTimeout(this.flushTimer);
-            this.flushTimer = null;
+        if (response.status === 400 || response.status === 401) {
+          this.config.logger.error(`Permanent error (${response.status}):`, data);
+          return null;
         }
-        await this.flush();
-    }
-    enqueue(event) {
-        // Check event size
-        const eventSize = this.estimateEventSize(event);
-        if (eventSize > MAX_EVENT_SIZE_BYTES) {
-            console.error(`Klime: Event size (${eventSize} bytes) exceeds ${MAX_EVENT_SIZE_BYTES} bytes limit`);
-            return;
+        if (response.status === 429 || response.status === 503) {
+          const retryAfter = response.headers.get("Retry-After");
+          if (retryAfter) {
+            delay = parseInt(retryAfter, 10) * 1e3;
+          }
+          attempt++;
+          if (attempt < this.config.retryMaxAttempts) {
+            this.config.logger.debug(`Retrying after ${delay}ms (attempt ${attempt})`);
+            await this.sleep(delay);
+            delay = Math.min(delay * 2, 16e3);
+            continue;
+          }
         }
-        // Drop oldest if queue is full
-        if (this.queue.length >= this.config.maxQueueSize) {
-            this.queue.shift();
+        attempt++;
+        if (attempt < this.config.retryMaxAttempts) {
+          this.config.logger.debug(`Retrying after ${delay}ms (attempt ${attempt})`);
+          await this.sleep(delay);
+          delay = Math.min(delay * 2, 16e3);
         }
-        this.queue.push(event);
-        // Check if we should flush immediately
-        if (this.queue.length >= this.config.maxBatchSize) {
-            this.flush();
+      } catch (error) {
+        attempt++;
+        if (attempt < this.config.retryMaxAttempts) {
+          this.config.logger.debug(`Retrying after ${delay}ms (attempt ${attempt})`);
+          await this.sleep(delay);
+          delay = Math.min(delay * 2, 16e3);
+        } else {
+          this.config.logger.error("Failed to send batch after retries:", error);
         }
+      }
     }
-    async doFlush() {
-        if (this.queue.length === 0) {
-            return;
-        }
-        // Clear the flush timer
-        if (this.flushTimer) {
-            clearTimeout(this.flushTimer);
-            this.flushTimer = null;
-        }
-        // Process batches
-        while (this.queue.length > 0) {
-            const batch = this.extractBatch();
-            if (batch.length === 0) {
-                break;
-            }
-            await this.sendBatch(batch);
-        }
-        // Schedule next flush
-        this.scheduleFlush();
-    }
-    extractBatch() {
-        const batch = [];
-        let batchSize = 0;
-        while (this.queue.length > 0 && batch.length < MAX_BATCH_SIZE) {
-            const event = this.queue[0];
-            const eventSize = this.estimateEventSize(event);
-            // Check if adding this event would exceed batch size limit
-            if (batchSize + eventSize > MAX_BATCH_SIZE_BYTES) {
-                break;
-            }
-            batch.push(this.queue.shift());
-            batchSize += eventSize;
-        }
-        return batch;
+    return null;
+  }
+  invokeOnError(error, batch) {
+    if (this.config.onError) {
+      try {
+        this.config.onError(error, batch);
+      } catch (e) {
+        this.config.logger.error("Error in onError callback:", e);
+      }
     }
-    async sendBatch(batch) {
-        if (batch.length === 0) {
-            return;
-        }
-        const request = { batch };
-        const url = `${this.config.endpoint}/v1/batch`;
-        let attempt = 0;
-        let delay = this.config.retryInitialDelay;
-        while (attempt < this.config.retryMaxAttempts) {
-            try {
-                const response = await fetch(url, {
-                    method: "POST",
-                    headers: {
-                        "Content-Type": "application/json",
-                        Authorization: `Bearer ${this.config.writeKey}`,
-                    },
-                    body: JSON.stringify(request),
-                });
-                const data = await response.json();
-                if (response.ok) {
-                    // Success - check for partial failures
-                    if (data.failed > 0 && data.errors) {
-                        console.warn(`Klime: Batch partially failed. Accepted: ${data.accepted}, Failed: ${data.failed}`, data.errors);
-                    }
-                    return;
-                }
-                // Handle error responses
-                if (response.status === 400 || response.status === 401) {
-                    // Permanent errors - don't retry
-                    console.error(`Klime: Permanent error (${response.status}):`, data);
-                    return;
-                }
-                // Transient errors - retry with backoff
-                if (response.status === 429 || response.status === 503) {
-                    const retryAfter = response.headers.get("Retry-After");
-                    if (retryAfter) {
-                        delay = parseInt(retryAfter, 10) * 1000;
-                    }
-                    attempt++;
-                    if (attempt < this.config.retryMaxAttempts) {
-                        await this.sleep(delay);
-                        delay = Math.min(delay * 2, 16000); // Cap at 16s
-                        continue;
-                    }
-                }
-                // Other errors - retry
-                attempt++;
-                if (attempt < this.config.retryMaxAttempts) {
-                    await this.sleep(delay);
-                    delay = Math.min(delay * 2, 16000);
-                }
-            }
-            catch (error) {
-                // Network errors - retry
-                attempt++;
-                if (attempt < this.config.retryMaxAttempts) {
-                    await this.sleep(delay);
-                    delay = Math.min(delay * 2, 16000);
-                }
-                else {
-                    console.error("Klime: Failed to send batch after retries:", error);
-                }
-            }
-        }
+  }
+  invokeOnSuccess(response) {
+    if (this.config.onSuccess) {
+      try {
+        this.config.onSuccess(response);
+      } catch (e) {
+        this.config.logger.error("Error in onSuccess callback:", e);
+      }
     }
-    scheduleFlush() {
-        if (this.isShutdown || this.flushTimer) {
-            return;
-        }
-        this.flushTimer = setTimeout(() => {
-            this.flush();
-        }, this.config.flushInterval);
+  }
+  scheduleFlush() {
+    if (this.isShutdown || this.flushTimer) {
+      return;
     }
-    generateUUID() {
-        if (typeof crypto !== "undefined" && crypto.randomUUID) {
-            return crypto.randomUUID();
-        }
-        // Fallback for older browsers
-        return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-            const r = (Math.random() * 16) | 0;
-            const v = c === "x" ? r : (r & 0x3) | 0x8;
-            return v.toString(16);
-        });
+    this.flushTimer = setTimeout(() => {
+      this.flush();
+    }, this.config.flushInterval);
+  }
+  generateUUID() {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+      return crypto.randomUUID();
     }
-    generateTimestamp() {
-        return new Date().toISOString();
-    }
-    getContext() {
-        const context = {
-            library: {
-                name: "js-sdk",
-                version: SDK_VERSION,
-            },
-        };
-        if (typeof navigator !== "undefined") {
-            if (navigator.userAgent) {
-                context.userAgent = navigator.userAgent;
-            }
-            if (navigator.language) {
-                context.locale = navigator.language;
-            }
-        }
-        if (typeof Intl !== "undefined" && Intl.DateTimeFormat) {
-            try {
-                const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
-                if (timezone) {
-                    context.timezone = timezone;
-                }
-            }
-            catch (e) {
-                // Ignore timezone errors
-            }
-        }
-        return context;
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+      const r = Math.random() * 16 | 0;
+      const v = c === "x" ? r : r & 3 | 8;
+      return v.toString(16);
+    });
+  }
+  generateTimestamp() {
+    return (/* @__PURE__ */ new Date()).toISOString();
+  }
+  getContext() {
+    const context = {
+      library: {
+        name: "js-sdk",
+        version: SDK_VERSION
+      }
+    };
+    if (typeof navigator !== "undefined") {
+      if (navigator.userAgent) {
+        context.userAgent = navigator.userAgent;
+      }
+      if (navigator.language) {
+        context.locale = navigator.language;
+      }
     }
-    estimateEventSize(event) {
-        // Rough estimate: JSON stringified size
-        try {
-            return JSON.stringify(event).length;
-        }
-        catch {
-            // Fallback: rough estimate based on structure
-            return 500; // Conservative estimate
+    if (typeof Intl !== "undefined" && Intl.DateTimeFormat) {
+      try {
+        const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        if (timezone) {
+          context.timezone = timezone;
         }
+      } catch (e) {
+      }
     }
-    sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+    return context;
+  }
+  estimateEventSize(event) {
+    try {
+      return JSON.stringify(event).length;
+    } catch {
+      return 500;
     }
-}
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+export {
+  KlimeClient,
+  SendError
+};
+//# sourceMappingURL=index.js.map