@kitbase/events 0.1.1

package/dist/index.js

@@ -0,0 +1,1218 @@
+// src/client.ts
+import { v4 as uuidv4 } from "uuid";
+
+// src/errors.ts
+var KitbaseError = class _KitbaseError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "KitbaseError";
+    Object.setPrototypeOf(this, _KitbaseError.prototype);
+  }
+};
+var AuthenticationError = class _AuthenticationError extends KitbaseError {
+  constructor(message = "Invalid API key") {
+    super(message);
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, _AuthenticationError.prototype);
+  }
+};
+var ApiError = class _ApiError extends KitbaseError {
+  statusCode;
+  response;
+  constructor(message, statusCode, response) {
+    super(message);
+    this.name = "ApiError";
+    this.statusCode = statusCode;
+    this.response = response;
+    Object.setPrototypeOf(this, _ApiError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends KitbaseError {
+  field;
+  constructor(message, field) {
+    super(message);
+    this.name = "ValidationError";
+    this.field = field;
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var TimeoutError = class _TimeoutError extends KitbaseError {
+  constructor(message = "Request timed out") {
+    super(message);
+    this.name = "TimeoutError";
+    Object.setPrototypeOf(this, _TimeoutError.prototype);
+  }
+};
+
+// src/queue/index.ts
+import Dexie from "dexie";
+var DEFAULT_CONFIG = {
+  enabled: false,
+  maxQueueSize: 1e3,
+  flushInterval: 3e4,
+  flushBatchSize: 50,
+  maxRetries: 3,
+  retryBaseDelay: 1e3
+};
+function isIndexedDBAvailable() {
+  try {
+    return typeof window !== "undefined" && typeof window.indexedDB !== "undefined" && window.indexedDB !== null;
+  } catch {
+    return false;
+  }
+}
+function isBrowser() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
+var KitbaseQueueDB = class extends Dexie {
+  events;
+  constructor(dbName) {
+    super(dbName);
+    this.version(1).stores({
+      events: "++id, timestamp, retries, lastAttempt"
+    });
+  }
+};
+var MemoryQueue = class {
+  queue = [];
+  idCounter = 1;
+  async enqueue(payload) {
+    const event = {
+      id: this.idCounter++,
+      payload,
+      timestamp: Date.now(),
+      retries: 0
+    };
+    this.queue.push(event);
+    return event.id;
+  }
+  async dequeue(count) {
+    this.queue.sort((a, b) => a.timestamp - b.timestamp);
+    return this.queue.slice(0, count);
+  }
+  async delete(ids) {
+    this.queue = this.queue.filter((e) => !ids.includes(e.id));
+  }
+  async updateRetries(ids) {
+    const now = Date.now();
+    for (const event of this.queue) {
+      if (ids.includes(event.id)) {
+        event.retries++;
+        event.lastAttempt = now;
+      }
+    }
+  }
+  async getStats() {
+    const size = this.queue.length;
+    const oldestEvent = size > 0 ? Math.min(...this.queue.map((e) => e.timestamp)) : void 0;
+    return { size, oldestEvent };
+  }
+  async clear() {
+    this.queue = [];
+  }
+  async enforceMaxSize(maxSize) {
+    if (this.queue.length > maxSize) {
+      this.queue.sort((a, b) => a.timestamp - b.timestamp);
+      this.queue = this.queue.slice(-maxSize);
+    }
+  }
+  async getEventsExceedingRetries(maxRetries) {
+    return this.queue.filter((e) => e.retries >= maxRetries).map((e) => e.id);
+  }
+};
+var EventQueue = class {
+  config;
+  dbName;
+  db = null;
+  memoryQueue = null;
+  flushTimer = null;
+  isFlushing = false;
+  sendEvents = null;
+  useIndexedDB;
+  debugMode = false;
+  debugLogger = null;
+  constructor(config = {}, dbName = "kitbase-events") {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.dbName = dbName;
+    this.useIndexedDB = isIndexedDBAvailable();
+    if (this.useIndexedDB) {
+      this.db = new KitbaseQueueDB(this.dbName);
+    } else {
+      this.memoryQueue = new MemoryQueue();
+    }
+  }
+  /**
+   * Set debug mode and logger
+   */
+  setDebugMode(enabled, logger) {
+    this.debugMode = enabled;
+    this.debugLogger = logger ?? null;
+  }
+  log(message, data) {
+    if (this.debugMode && this.debugLogger) {
+      this.debugLogger(message, data);
+    }
+  }
+  /**
+   * Set the callback for sending events
+   */
+  setSendCallback(callback) {
+    this.sendEvents = callback;
+  }
+  /**
+   * Check if the queue storage is available
+   */
+  isAvailable() {
+    return this.useIndexedDB || this.memoryQueue !== null;
+  }
+  /**
+   * Get the storage type being used
+   */
+  getStorageType() {
+    return this.useIndexedDB ? "indexeddb" : "memory";
+  }
+  /**
+   * Add an event to the queue
+   */
+  async enqueue(payload) {
+    const event = {
+      payload,
+      timestamp: Date.now(),
+      retries: 0
+    };
+    if (this.useIndexedDB && this.db) {
+      await this.db.events.add(event);
+      this.log("Event queued to IndexedDB", payload);
+    } else if (this.memoryQueue) {
+      await this.memoryQueue.enqueue(payload);
+      this.log("Event queued to memory", payload);
+    }
+    await this.enforceMaxQueueSize();
+  }
+  /**
+   * Get and remove the next batch of events to send
+   */
+  async dequeue(count) {
+    if (this.useIndexedDB && this.db) {
+      return this.db.events.where("retries").below(this.config.maxRetries).sortBy("timestamp").then((events) => events.slice(0, count));
+    } else if (this.memoryQueue) {
+      const events = await this.memoryQueue.dequeue(count);
+      return events.filter((e) => e.retries < this.config.maxRetries);
+    }
+    return [];
+  }
+  /**
+   * Mark events as successfully sent (remove from queue)
+   */
+  async markSent(ids) {
+    if (ids.length === 0) return;
+    if (this.useIndexedDB && this.db) {
+      await this.db.events.bulkDelete(ids);
+      this.log(`Removed ${ids.length} sent events from queue`);
+    } else if (this.memoryQueue) {
+      await this.memoryQueue.delete(ids);
+      this.log(`Removed ${ids.length} sent events from memory queue`);
+    }
+  }
+  /**
+   * Mark events as failed and increment retry count
+   */
+  async markFailed(ids) {
+    if (ids.length === 0) return;
+    const now = Date.now();
+    if (this.useIndexedDB && this.db) {
+      await this.db.transaction("rw", this.db.events, async () => {
+        for (const id of ids) {
+          const event = await this.db.events.get(id);
+          if (event) {
+            await this.db.events.update(id, {
+              retries: event.retries + 1,
+              lastAttempt: now
+            });
+          }
+        }
+      });
+      this.log(`Marked ${ids.length} events as failed`);
+    } else if (this.memoryQueue) {
+      await this.memoryQueue.updateRetries(ids);
+      this.log(`Marked ${ids.length} events as failed in memory queue`);
+    }
+    await this.removeExpiredRetries();
+  }
+  /**
+   * Remove events that have exceeded max retry attempts
+   */
+  async removeExpiredRetries() {
+    if (this.useIndexedDB && this.db) {
+      const expiredIds = await this.db.events.where("retries").aboveOrEqual(this.config.maxRetries).primaryKeys();
+      if (expiredIds.length > 0) {
+        await this.db.events.bulkDelete(expiredIds);
+        this.log(`Removed ${expiredIds.length} events that exceeded max retries`);
+      }
+    } else if (this.memoryQueue) {
+      const expiredIds = await this.memoryQueue.getEventsExceedingRetries(
+        this.config.maxRetries
+      );
+      if (expiredIds.length > 0) {
+        await this.memoryQueue.delete(expiredIds);
+        this.log(`Removed ${expiredIds.length} events that exceeded max retries`);
+      }
+    }
+  }
+  /**
+   * Enforce the maximum queue size by removing oldest events
+   */
+  async enforceMaxQueueSize() {
+    if (this.useIndexedDB && this.db) {
+      const count = await this.db.events.count();
+      if (count > this.config.maxQueueSize) {
+        const excess = count - this.config.maxQueueSize;
+        const oldestEvents = await this.db.events.orderBy("timestamp").limit(excess).primaryKeys();
+        await this.db.events.bulkDelete(oldestEvents);
+        this.log(`Removed ${excess} oldest events to enforce queue size limit`);
+      }
+    } else if (this.memoryQueue) {
+      await this.memoryQueue.enforceMaxSize(this.config.maxQueueSize);
+    }
+  }
+  /**
+   * Get queue statistics
+   */
+  async getStats() {
+    if (this.useIndexedDB && this.db) {
+      const size = await this.db.events.count();
+      const oldestEvent = await this.db.events.orderBy("timestamp").first().then((e) => e?.timestamp);
+      return { size, oldestEvent, isFlushing: this.isFlushing };
+    } else if (this.memoryQueue) {
+      const stats = await this.memoryQueue.getStats();
+      return { ...stats, isFlushing: this.isFlushing };
+    }
+    return { size: 0, isFlushing: this.isFlushing };
+  }
+  /**
+   * Clear all events from the queue
+   */
+  async clear() {
+    if (this.useIndexedDB && this.db) {
+      await this.db.events.clear();
+      this.log("Queue cleared (IndexedDB)");
+    } else if (this.memoryQueue) {
+      await this.memoryQueue.clear();
+      this.log("Queue cleared (memory)");
+    }
+  }
+  /**
+   * Start the automatic flush timer
+   */
+  startFlushTimer() {
+    if (this.flushTimer) return;
+    this.flushTimer = setInterval(() => {
+      this.flush().catch((err) => {
+        this.log("Flush timer error", err);
+      });
+    }, this.config.flushInterval);
+    if (isBrowser()) {
+      window.addEventListener("online", this.handleOnline);
+    }
+    this.log(`Flush timer started (interval: ${this.config.flushInterval}ms)`);
+  }
+  /**
+   * Stop the automatic flush timer
+   */
+  stopFlushTimer() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (isBrowser()) {
+      window.removeEventListener("online", this.handleOnline);
+    }
+    this.log("Flush timer stopped");
+  }
+  /**
+   * Handle coming back online
+   */
+  handleOnline = () => {
+    this.log("Browser came online, triggering flush");
+    this.flush().catch((err) => {
+      this.log("Online flush error", err);
+    });
+  };
+  /**
+   * Check if we're currently online
+   */
+  isOnline() {
+    if (isBrowser()) {
+      return navigator.onLine;
+    }
+    return true;
+  }
+  /**
+   * Manually trigger a flush of queued events
+   */
+  async flush() {
+    if (this.isFlushing) {
+      this.log("Flush already in progress, skipping");
+      return;
+    }
+    if (!this.isOnline()) {
+      this.log("Offline, skipping flush");
+      return;
+    }
+    if (!this.sendEvents) {
+      this.log("No send callback configured, skipping flush");
+      return;
+    }
+    this.isFlushing = true;
+    try {
+      const stats = await this.getStats();
+      if (stats.size === 0) {
+        this.log("Queue is empty, nothing to flush");
+        return;
+      }
+      this.log(`Flushing queue (${stats.size} events)`);
+      let processed = 0;
+      while (true) {
+        const events = await this.dequeue(this.config.flushBatchSize);
+        if (events.length === 0) break;
+        this.log(`Sending batch of ${events.length} events`);
+        try {
+          const sentIds = await this.sendEvents(events);
+          await this.markSent(sentIds);
+          const failedIds = events.filter((e) => !sentIds.includes(e.id)).map((e) => e.id);
+          if (failedIds.length > 0) {
+            await this.markFailed(failedIds);
+          }
+          processed += sentIds.length;
+        } catch (error) {
+          const allIds = events.map((e) => e.id);
+          await this.markFailed(allIds);
+          this.log("Batch send failed", error);
+          break;
+        }
+      }
+      this.log(`Flush complete, sent ${processed} events`);
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+  /**
+   * Close the database connection
+   */
+  async close() {
+    this.stopFlushTimer();
+    if (this.db) {
+      this.db.close();
+      this.log("Database connection closed");
+    }
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.kitbase.dev";
+var TIMEOUT = 3e4;
+var DEFAULT_STORAGE_KEY = "kitbase_anonymous_id";
+var DEFAULT_SESSION_STORAGE_KEY = "kitbase_session";
+var DEFAULT_SESSION_TIMEOUT = 30 * 60 * 1e3;
+var ANALYTICS_CHANNEL = "__analytics";
+var MemoryStorage = class {
+  data = /* @__PURE__ */ new Map();
+  getItem(key) {
+    return this.data.get(key) ?? null;
+  }
+  setItem(key, value) {
+    this.data.set(key, value);
+  }
+  removeItem(key) {
+    this.data.delete(key);
+  }
+};
+function getDefaultStorage() {
+  if (typeof window !== "undefined" && window.localStorage) {
+    return window.localStorage;
+  }
+  return new MemoryStorage();
+}
+var Kitbase = class {
+  token;
+  baseUrl;
+  storage;
+  storageKey;
+  anonymousId = null;
+  // Super properties (memory-only, merged into all events)
+  superProperties = {};
+  // Time event tracking
+  timedEvents = /* @__PURE__ */ new Map();
+  // Debug mode
+  debugMode;
+  // Offline queue
+  queue = null;
+  offlineEnabled;
+  // Analytics & Session tracking
+  session = null;
+  sessionTimeout;
+  sessionStorageKey;
+  analyticsEnabled;
+  autoTrackPageViews;
+  userId = null;
+  unloadListenerAdded = false;
+  constructor(config) {
+    if (!config.token) {
+      throw new ValidationError("API token is required", "token");
+    }
+    this.token = config.token;
+    this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    this.storageKey = config.storageKey ?? DEFAULT_STORAGE_KEY;
+    this.debugMode = config.debug ?? false;
+    if (config.storage === null) {
+      this.storage = null;
+    } else {
+      this.storage = config.storage ?? getDefaultStorage();
+    }
+    this.initializeAnonymousId();
+    this.sessionTimeout = config.analytics?.sessionTimeout ?? DEFAULT_SESSION_TIMEOUT;
+    this.sessionStorageKey = config.analytics?.sessionStorageKey ?? DEFAULT_SESSION_STORAGE_KEY;
+    this.analyticsEnabled = config.analytics?.autoTrackSessions ?? true;
+    this.autoTrackPageViews = config.analytics?.autoTrackPageViews ?? false;
+    if (this.analyticsEnabled) {
+      this.loadSession();
+      this.setupUnloadListener();
+      if (this.autoTrackPageViews && typeof window !== "undefined") {
+        this.enableAutoPageViews();
+      }
+    }
+    this.offlineEnabled = config.offline?.enabled ?? false;
+    if (this.offlineEnabled) {
+      this.queue = new EventQueue(config.offline);
+      this.queue.setDebugMode(this.debugMode, this.log.bind(this));
+      this.queue.setSendCallback(this.sendQueuedEvents.bind(this));
+      this.queue.startFlushTimer();
+      this.log("Offline queueing enabled", {
+        storageType: this.queue.getStorageType()
+      });
+    }
+  }
+  /**
+   * Initialize the anonymous ID from storage or generate a new one
+   */
+  initializeAnonymousId() {
+    if (this.storage) {
+      const stored = this.storage.getItem(this.storageKey);
+      if (stored) {
+        this.anonymousId = stored;
+        return;
+      }
+    }
+    this.anonymousId = uuidv4();
+    if (this.storage && this.anonymousId) {
+      this.storage.setItem(this.storageKey, this.anonymousId);
+    }
+  }
+  /**
+   * Get the current anonymous ID
+   */
+  getAnonymousId() {
+    return this.anonymousId;
+  }
+  // ============================================================
+  // Debug Mode
+  // ============================================================
+  /**
+   * Enable or disable debug mode
+   * When enabled, all SDK operations are logged to the console
+   *
+   * @param enabled - Whether to enable debug mode
+   *
+   * @example
+   * ```typescript
+   * kitbase.setDebugMode(true);
+   * // All events and operations will now be logged
+   * ```
+   */
+  setDebugMode(enabled) {
+    this.debugMode = enabled;
+    if (this.queue) {
+      this.queue.setDebugMode(enabled, this.log.bind(this));
+    }
+    this.log(`Debug mode ${enabled ? "enabled" : "disabled"}`);
+  }
+  /**
+   * Check if debug mode is enabled
+   */
+  isDebugMode() {
+    return this.debugMode;
+  }
+  /**
+   * Internal logging function
+   */
+  log(message, data) {
+    if (!this.debugMode) return;
+    const prefix = "[Kitbase]";
+    if (data !== void 0) {
+      console.log(prefix, message, data);
+    } else {
+      console.log(prefix, message);
+    }
+  }
+  // ============================================================
+  // Super Properties
+  // ============================================================
+  /**
+   * Register super properties that will be included with every event
+   * These properties are stored in memory only and reset on page reload
+   *
+   * @param properties - Properties to register
+   *
+   * @example
+   * ```typescript
+   * kitbase.register({
+   *   app_version: '2.1.0',
+   *   platform: 'web',
+   *   environment: 'production',
+   * });
+   * ```
+   */
+  register(properties) {
+    this.superProperties = { ...this.superProperties, ...properties };
+    this.log("Super properties registered", properties);
+  }
+  /**
+   * Register super properties only if they haven't been set yet
+   * Useful for setting default values that shouldn't override existing ones
+   *
+   * @param properties - Properties to register if not already set
+   *
+   * @example
+   * ```typescript
+   * kitbase.registerOnce({ first_visit: new Date().toISOString() });
+   * ```
+   */
+  registerOnce(properties) {
+    const newProps = {};
+    for (const [key, value] of Object.entries(properties)) {
+      if (!(key in this.superProperties)) {
+        newProps[key] = value;
+      }
+    }
+    if (Object.keys(newProps).length > 0) {
+      this.superProperties = { ...this.superProperties, ...newProps };
+      this.log("Super properties registered (once)", newProps);
+    }
+  }
+  /**
+   * Remove a super property
+   *
+   * @param key - The property key to remove
+   *
+   * @example
+   * ```typescript
+   * kitbase.unregister('platform');
+   * ```
+   */
+  unregister(key) {
+    if (key in this.superProperties) {
+      delete this.superProperties[key];
+      this.log("Super property removed", { key });
+    }
+  }
+  /**
+   * Get all registered super properties
+   *
+   * @returns A copy of the current super properties
+   *
+   * @example
+   * ```typescript
+   * const props = kitbase.getSuperProperties();
+   * console.log(props); // { app_version: '2.1.0', platform: 'web' }
+   * ```
+   */
+  getSuperProperties() {
+    return { ...this.superProperties };
+  }
+  /**
+   * Clear all super properties
+   *
+   * @example
+   * ```typescript
+   * kitbase.clearSuperProperties();
+   * ```
+   */
+  clearSuperProperties() {
+    this.superProperties = {};
+    this.log("Super properties cleared");
+  }
+  // ============================================================
+  // Time Events (Duration Tracking)
+  // ============================================================
+  /**
+   * Start timing an event
+   * When the same event is tracked later, a $duration property (in seconds)
+   * will automatically be included
+   *
+   * @param eventName - The name of the event to time
+   *
+   * @example
+   * ```typescript
+   * kitbase.timeEvent('Video Watched');
+   * // ... user watches video ...
+   * await kitbase.track({
+   *   channel: 'engagement',
+   *   event: 'Video Watched',
+   *   tags: { video_id: '123' }
+   * });
+   * // Event will include $duration: 45.2 (seconds)
+   * ```
+   */
+  timeEvent(eventName) {
+    this.timedEvents.set(eventName, Date.now());
+    this.log("Timer started", { event: eventName });
+  }
+  /**
+   * Cancel a timed event without tracking it
+   *
+   * @param eventName - The name of the event to cancel timing for
+   *
+   * @example
+   * ```typescript
+   * kitbase.timeEvent('Checkout Flow');
+   * // User abandons checkout
+   * kitbase.cancelTimeEvent('Checkout Flow');
+   * ```
+   */
+  cancelTimeEvent(eventName) {
+    if (this.timedEvents.has(eventName)) {
+      this.timedEvents.delete(eventName);
+      this.log("Timer cancelled", { event: eventName });
+    }
+  }
+  /**
+   * Get all currently timed events
+   *
+   * @returns Array of event names that are currently being timed
+   *
+   * @example
+   * ```typescript
+   * const timedEvents = kitbase.getTimedEvents();
+   * console.log(timedEvents); // ['Video Watched', 'Checkout Flow']
+   * ```
+   */
+  getTimedEvents() {
+    return Array.from(this.timedEvents.keys());
+  }
+  /**
+   * Get the duration of a timed event (without stopping it)
+   *
+   * @param eventName - The name of the event
+   * @returns Duration in seconds, or null if not being timed
+   */
+  getEventDuration(eventName) {
+    const startTime = this.timedEvents.get(eventName);
+    if (startTime === void 0) return null;
+    return (Date.now() - startTime) / 1e3;
+  }
+  // ============================================================
+  // Offline Queue
+  // ============================================================
+  /**
+   * Get offline queue statistics
+   *
+   * @returns Queue statistics including size and flush status
+   *
+   * @example
+   * ```typescript
+   * const stats = await kitbase.getQueueStats();
+   * console.log(stats); // { size: 5, isFlushing: false }
+   * ```
+   */
+  async getQueueStats() {
+    if (!this.queue) return null;
+    return this.queue.getStats();
+  }
+  /**
+   * Manually flush the offline queue
+   * Events are automatically flushed on interval and when coming back online,
+   * but this method can be used to trigger an immediate flush
+   *
+   * @example
+   * ```typescript
+   * await kitbase.flushQueue();
+   * ```
+   */
+  async flushQueue() {
+    if (!this.queue) return;
+    await this.queue.flush();
+  }
+  /**
+   * Clear all events from the offline queue
+   *
+   * @example
+   * ```typescript
+   * await kitbase.clearQueue();
+   * ```
+   */
+  async clearQueue() {
+    if (!this.queue) return;
+    await this.queue.clear();
+  }
+  /**
+   * Callback for the queue to send batched events
+   */
+  async sendQueuedEvents(events) {
+    const sentIds = [];
+    for (const event of events) {
+      try {
+        await this.sendRequest("/sdk/v1/logs", event.payload);
+        sentIds.push(event.id);
+      } catch (error) {
+        this.log("Failed to send queued event", { id: event.id, error });
+      }
+    }
+    return sentIds;
+  }
+  // ============================================================
+  // Track Event
+  // ============================================================
+  /**
+   * Track an event
+   *
+   * When offline queueing is enabled, events are always written to the local
+   * database first (write-ahead), then sent to the server. This ensures no
+   * events are lost if the browser crashes or the network fails.
+   *
+   * @param options - Event tracking options
+   * @returns Promise resolving to the track response
+   * @throws {ValidationError} When required fields are missing
+   * @throws {AuthenticationError} When the API key is invalid (only when offline disabled)
+   * @throws {ApiError} When the API returns an error (only when offline disabled)
+   * @throws {TimeoutError} When the request times out (only when offline disabled)
+   */
+  async track(options) {
+    this.validateTrackOptions(options);
+    let duration;
+    const startTime = this.timedEvents.get(options.event);
+    if (startTime !== void 0) {
+      duration = (Date.now() - startTime) / 1e3;
+      this.timedEvents.delete(options.event);
+      this.log("Timer stopped", { event: options.event, duration });
+    }
+    const includeAnonymousId = options.includeAnonymousId !== false;
+    const mergedTags = {
+      ...this.superProperties,
+      ...options.tags ?? {},
+      ...duration !== void 0 ? { $duration: duration } : {}
+    };
+    const payload = {
+      channel: options.channel,
+      event: options.event,
+      timestamp: Date.now(),
+      ...options.user_id && { user_id: options.user_id },
+      ...includeAnonymousId && this.anonymousId && { anonymous_id: this.anonymousId },
+      ...options.icon && { icon: options.icon },
+      ...options.notify !== void 0 && { notify: options.notify },
+      ...options.description && { description: options.description },
+      ...Object.keys(mergedTags).length > 0 && { tags: mergedTags }
+    };
+    this.log("Track", { event: options.event, payload });
+    if (this.queue) {
+      await this.queue.enqueue(payload);
+      this.log("Event persisted to queue");
+      this.queue.flush().catch((err) => {
+        this.log("Background flush failed", err);
+      });
+      return {
+        id: `queued-${Date.now()}`,
+        event: options.event,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    }
+    const response = await this.sendRequest("/sdk/v1/logs", payload);
+    this.log("Event sent successfully", { id: response.id });
+    return response;
+  }
+  validateTrackOptions(options) {
+    if (!options.event) {
+      throw new ValidationError("Event is required", "event");
+    }
+  }
+  /**
+   * Send a request to the API
+   */
+  async sendRequest(endpoint, body) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), TIMEOUT);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-sdk-key": `${this.token}`
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorBody = await this.parseResponseBody(response);
+        if (response.status === 401) {
+          throw new AuthenticationError();
+        }
+        throw new ApiError(
+          this.getErrorMessage(errorBody, response.statusText),
+          response.status,
+          errorBody
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new TimeoutError();
+      }
+      throw error;
+    }
+  }
+  async parseResponseBody(response) {
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+  getErrorMessage(body, fallback) {
+    if (body && typeof body === "object" && "message" in body) {
+      return String(body.message);
+    }
+    if (body && typeof body === "object" && "error" in body) {
+      return String(body.error);
+    }
+    return fallback;
+  }
+  // ============================================================
+  // Analytics & Session Management
+  // ============================================================
+  /**
+   * Load session from storage
+   */
+  loadSession() {
+    if (!this.storage) return;
+    try {
+      const stored = this.storage.getItem(this.sessionStorageKey);
+      if (stored) {
+        const session = JSON.parse(stored);
+        const now = Date.now();
+        if (now - session.lastActivityAt < this.sessionTimeout) {
+          this.session = session;
+          this.log("Session restored", { sessionId: session.id });
+        } else {
+          this.storage.removeItem(this.sessionStorageKey);
+          this.log("Session expired, removed from storage");
+        }
+      }
+    } catch (error) {
+      this.log("Failed to load session from storage", error);
+    }
+  }
+  /**
+   * Save session to storage
+   */
+  saveSession() {
+    if (!this.storage || !this.session) return;
+    try {
+      this.storage.setItem(this.sessionStorageKey, JSON.stringify(this.session));
+    } catch (error) {
+      this.log("Failed to save session to storage", error);
+    }
+  }
+  /**
+   * Get or create a session
+   */
+  getOrCreateSession() {
+    const now = Date.now();
+    if (this.session && now - this.session.lastActivityAt > this.sessionTimeout) {
+      this.endSession();
+      this.session = null;
+    }
+    if (!this.session) {
+      const referrer = typeof document !== "undefined" ? document.referrer : void 0;
+      const path = typeof window !== "undefined" ? window.location.pathname : void 0;
+      this.session = {
+        id: uuidv4(),
+        startedAt: now,
+        lastActivityAt: now,
+        screenViewCount: 0,
+        entryPath: path,
+        entryReferrer: referrer
+      };
+      this.log("New session created", { sessionId: this.session.id });
+      this.trackSessionStart();
+    }
+    this.session.lastActivityAt = now;
+    this.saveSession();
+    return this.session;
+  }
+  /**
+   * Get the current session ID (or null if no active session)
+   */
+  getSessionId() {
+    return this.session?.id ?? null;
+  }
+  /**
+   * Get the current session data
+   */
+  getSession() {
+    return this.session ? { ...this.session } : null;
+  }
+  /**
+   * Track session start event
+   */
+  trackSessionStart() {
+    if (!this.session) return;
+    const utmParams = this.getUtmParams();
+    this.track({
+      channel: ANALYTICS_CHANNEL,
+      event: "session_start",
+      tags: {
+        __session_id: this.session.id,
+        __entry_path: this.session.entryPath ?? "",
+        __referrer: this.session.entryReferrer ?? "",
+        ...utmParams
+      }
+    }).catch((err) => this.log("Failed to track session_start", err));
+  }
+  /**
+   * End the current session (clears local state only - server calculates metrics)
+   */
+  endSession() {
+    if (!this.session) return;
+    this.log("Session ended", { sessionId: this.session.id });
+    if (this.storage) {
+      this.storage.removeItem(this.sessionStorageKey);
+    }
+    this.session = null;
+  }
+  /**
+   * Setup listeners for session lifecycle management
+   */
+  setupUnloadListener() {
+    if (typeof window === "undefined" || this.unloadListenerAdded) return;
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") {
+        this.saveSession();
+        this.log("Page hidden, session state saved");
+      }
+    });
+    window.addEventListener("pagehide", () => {
+      this.endSession();
+      this.log("Page unloading, session ended locally");
+    });
+    this.unloadListenerAdded = true;
+    this.log("Session lifecycle listeners added");
+  }
+  /**
+   * Get UTM parameters from URL
+   */
+  getUtmParams() {
+    if (typeof window === "undefined") return {};
+    const params = new URLSearchParams(window.location.search);
+    const utmParams = {};
+    const utmKeys = ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
+    for (const key of utmKeys) {
+      const value = params.get(key);
+      if (value) {
+        utmParams[`__${key}`] = value;
+      }
+    }
+    return utmParams;
+  }
+  /**
+   * Track a page view
+   *
+   * @param options - Page view options
+   * @returns Promise resolving to the track response
+   *
+   * @example
+   * ```typescript
+   * // Track current page
+   * await kitbase.trackPageView();
+   *
+   * // Track with custom path
+   * await kitbase.trackPageView({ path: '/products/123', title: 'Product Details' });
+   * ```
+   */
+  async trackPageView(options = {}) {
+    const session = this.getOrCreateSession();
+    session.screenViewCount++;
+    this.saveSession();
+    const path = options.path ?? (typeof window !== "undefined" ? window.location.pathname : "");
+    const title = options.title ?? (typeof document !== "undefined" ? document.title : "");
+    const referrer = options.referrer ?? (typeof document !== "undefined" ? document.referrer : "");
+    return this.track({
+      channel: ANALYTICS_CHANNEL,
+      event: "screen_view",
+      tags: {
+        __session_id: session.id,
+        __path: path,
+        __title: title,
+        __referrer: referrer,
+        ...this.getUtmParams(),
+        ...options.tags ?? {}
+      }
+    });
+  }
+  /**
+   * Enable automatic page view tracking
+   * Intercepts browser history changes (pushState, replaceState, popstate)
+   *
+   * @example
+   * ```typescript
+   * kitbase.enableAutoPageViews();
+   * // Now all route changes will automatically be tracked
+   * ```
+   */
+  enableAutoPageViews() {
+    if (typeof window === "undefined") {
+      this.log("Auto page views not available in non-browser environment");
+      return;
+    }
+    this.trackPageView().catch((err) => this.log("Failed to track initial page view", err));
+    const originalPushState = history.pushState.bind(history);
+    history.pushState = (...args) => {
+      originalPushState(...args);
+      this.trackPageView().catch((err) => this.log("Failed to track page view (pushState)", err));
+    };
+    const originalReplaceState = history.replaceState.bind(history);
+    history.replaceState = (...args) => {
+      originalReplaceState(...args);
+    };
+    window.addEventListener("popstate", () => {
+      this.trackPageView().catch((err) => this.log("Failed to track page view (popstate)", err));
+    });
+    this.log("Auto page view tracking enabled");
+  }
+  /**
+   * Track a revenue event
+   *
+   * @param options - Revenue options
+   * @returns Promise resolving to the track response
+   *
+   * @example
+   * ```typescript
+   * // Track a $19.99 purchase
+   * await kitbase.trackRevenue({
+   *   amount: 1999,
+   *   currency: 'USD',
+   *   tags: { product_id: 'prod_123', plan: 'premium' },
+   * });
+   * ```
+   */
+  async trackRevenue(options) {
+    const session = this.getOrCreateSession();
+    return this.track({
+      channel: ANALYTICS_CHANNEL,
+      event: "revenue",
+      user_id: options.user_id ?? this.userId ?? void 0,
+      tags: {
+        __session_id: session.id,
+        __revenue: options.amount,
+        __currency: options.currency ?? "USD",
+        ...options.tags ?? {}
+      }
+    });
+  }
+  /**
+   * Identify a user
+   * Links the current anonymous ID to a user ID for future events
+   *
+   * @param options - Identify options
+   *
+   * @example
+   * ```typescript
+   * kitbase.identify({
+   *   userId: 'user_123',
+   *   traits: { email: 'user@example.com', plan: 'premium' },
+   * });
+   * ```
+   */
+  identify(options) {
+    this.userId = options.userId;
+    if (options.traits) {
+      this.register({
+        __user_id: options.userId,
+        ...options.traits
+      });
+    } else {
+      this.register({ __user_id: options.userId });
+    }
+    this.track({
+      channel: ANALYTICS_CHANNEL,
+      event: "identify",
+      user_id: options.userId,
+      tags: {
+        __session_id: this.session?.id ?? "",
+        __anonymous_id: this.anonymousId ?? "",
+        ...options.traits ?? {}
+      }
+    }).catch((err) => this.log("Failed to track identify", err));
+    this.log("User identified", { userId: options.userId });
+  }
+  /**
+   * Get the current user ID (set via identify)
+   */
+  getUserId() {
+    return this.userId;
+  }
+  /**
+   * Reset the user identity and session
+   * Call this when a user logs out
+   *
+   * @example
+   * ```typescript
+   * kitbase.reset();
+   * ```
+   */
+  reset() {
+    if (this.session) {
+      this.endSession();
+      this.session = null;
+    }
+    this.userId = null;
+    this.anonymousId = uuidv4();
+    if (this.storage) {
+      this.storage.setItem(this.storageKey, this.anonymousId);
+    }
+    this.clearSuperProperties();
+    this.log("User reset complete");
+  }
+  // ============================================================
+  // Cleanup
+  // ============================================================
+  /**
+   * Shutdown the client and cleanup resources
+   * Call this when you're done using the client to stop timers and close connections
+   *
+   * @example
+   * ```typescript
+   * await kitbase.shutdown();
+   * ```
+   */
+  async shutdown() {
+    this.log("Shutting down");
+    if (this.queue) {
+      await this.queue.flush();
+      await this.queue.close();
+      this.queue = null;
+    }
+    this.timedEvents.clear();
+    this.log("Shutdown complete");
+  }
+};
+export {
+  ApiError,
+  AuthenticationError,
+  Kitbase,
+  KitbaseError,
+  TimeoutError,
+  ValidationError
+};
+//# sourceMappingURL=index.js.map