@yraylabs/boring-analytics 0.1.0

package/dist/index.js

@@ -0,0 +1,603 @@
+'use strict';
+
+// src/transport.ts
+var Transport = class {
+  constructor(config) {
+    this.config = config;
+  }
+  async sendEvents(events) {
+    await this.post("/ingest/events", { events });
+  }
+  async sendErrors(errors) {
+    await this.post("/ingest/errors", { errors });
+  }
+  async post(path, body) {
+    const url = this.config.endpoint.replace(/\/+$/, "") + path;
+    let lastError;
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      try {
+        const response = await fetch(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-api-key": this.config.apiKey
+          },
+          body: JSON.stringify(body),
+          keepalive: true
+        });
+        if (response.ok) return;
+        if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+          const text = await response.text().catch(() => "");
+          throw new Error(`HTTP ${response.status}: ${text}`);
+        }
+        lastError = new Error(`HTTP ${response.status}`);
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (err instanceof Error && err.message.startsWith("HTTP 4")) {
+          break;
+        }
+      }
+      if (attempt < this.config.maxRetries) {
+        await this.backoff(attempt);
+      }
+    }
+    if (lastError) {
+      this.config.onError?.(lastError);
+    }
+  }
+  backoff(attempt) {
+    const delay = Math.min(1e3 * 2 ** attempt, 3e4);
+    const jitter = delay * (0.5 + Math.random() * 0.5);
+    return new Promise((resolve) => setTimeout(resolve, jitter));
+  }
+};
+
+// src/queue.ts
+var EventQueue = class {
+  constructor(transport, config) {
+    this.items = [];
+    this.timer = null;
+    this.flushing = false;
+    this.transport = transport;
+    this.config = config;
+    this.startTimer();
+  }
+  add(item) {
+    this.items.push(item);
+    this.config.debug.log(`Queued ${item.kind}:`, item.kind === "event" ? item.payload.name : item.payload.message);
+    if (this.items.length >= this.config.flushAt) {
+      void this.flush();
+    }
+  }
+  async flush() {
+    if (this.flushing || this.items.length === 0) return;
+    this.flushing = true;
+    const batch = this.items.splice(0);
+    try {
+      const events = [];
+      const errors = [];
+      for (const item of batch) {
+        if (item.kind === "event") events.push(item.payload);
+        else errors.push(item.payload);
+      }
+      const promises = [];
+      if (events.length > 0) {
+        this.config.debug.log(`Flushing ${events.length} events`);
+        promises.push(this.transport.sendEvents(events));
+      }
+      if (errors.length > 0) {
+        this.config.debug.log(`Flushing ${errors.length} errors`);
+        promises.push(this.transport.sendErrors(errors));
+      }
+      await Promise.all(promises);
+    } catch {
+      this.items.unshift(...batch);
+    } finally {
+      this.flushing = false;
+    }
+  }
+  startTimer() {
+    if (this.config.flushInterval > 0) {
+      this.timer = setInterval(() => {
+        void this.flush();
+      }, this.config.flushInterval);
+      if (this.timer && typeof this.timer.unref === "function") {
+        this.timer.unref();
+      }
+    }
+  }
+  async shutdown() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    await this.flush();
+  }
+  get size() {
+    return this.items.length;
+  }
+};
+
+// src/utils.ts
+function generateId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  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);
+  });
+}
+function isBrowser() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
+function createDebugLogger(enabled) {
+  return {
+    log: (...args) => {
+      if (enabled) console.log("[BoringAnalytics]", ...args);
+    },
+    warn: (...args) => {
+      if (enabled) console.warn("[BoringAnalytics]", ...args);
+    },
+    error: (...args) => {
+      if (enabled) console.error("[BoringAnalytics]", ...args);
+    }
+  };
+}
+
+// src/session.ts
+var ANON_ID_KEY = "anonymous_id";
+var SESSION_ID_KEY = "session_id";
+var SESSION_EXPIRY_KEY = "session_expiry";
+var SESSION_TIMEOUT_MS = 30 * 60 * 1e3;
+var SessionManager = class {
+  constructor(storage) {
+    this.userId = null;
+    this.storage = storage;
+    this.anonymousId = this.storage.get(ANON_ID_KEY) ?? this.createAnonymousId();
+    this.sessionId = this.resolveSession();
+  }
+  createAnonymousId() {
+    const id = generateId();
+    this.storage.set(ANON_ID_KEY, id);
+    return id;
+  }
+  resolveSession() {
+    const existingSession = this.storage.get(SESSION_ID_KEY);
+    const expiryStr = this.storage.get(SESSION_EXPIRY_KEY);
+    const expiry = expiryStr ? parseInt(expiryStr, 10) : 0;
+    if (existingSession && Date.now() < expiry) {
+      this.touchSession();
+      return existingSession;
+    }
+    return this.startNewSession();
+  }
+  startNewSession() {
+    const id = generateId();
+    this.sessionId = id;
+    this.storage.set(SESSION_ID_KEY, id);
+    this.touchSession();
+    return id;
+  }
+  touchSession() {
+    this.storage.set(
+      SESSION_EXPIRY_KEY,
+      String(Date.now() + SESSION_TIMEOUT_MS)
+    );
+  }
+  setUserId(id) {
+    this.userId = id;
+  }
+  getUserId() {
+    return this.userId;
+  }
+  getAnonymousId() {
+    return this.anonymousId;
+  }
+  getSessionId() {
+    this.sessionId = this.resolveSession();
+    return this.sessionId;
+  }
+  reset() {
+    this.userId = null;
+    this.anonymousId = this.createAnonymousId();
+    this.sessionId = this.startNewSession();
+  }
+};
+
+// src/error-handler.ts
+var GlobalErrorHandler = class {
+  constructor(callback) {
+    this.installed = false;
+    this.originalOnError = null;
+    this.originalOnUnhandledRejection = null;
+    this.handleNodeError = (error) => {
+      this.callback(error, "uncaughtException");
+    };
+    this.handleNodeRejection = (reason) => {
+      const error = reason instanceof Error ? reason : new Error(String(reason));
+      this.callback(error, "unhandledRejection");
+    };
+    this.callback = callback;
+  }
+  install() {
+    if (this.installed) return;
+    this.installed = true;
+    if (isBrowser()) {
+      this.installBrowser();
+    } else {
+      this.installNode();
+    }
+  }
+  uninstall() {
+    if (!this.installed) return;
+    this.installed = false;
+    if (isBrowser()) {
+      this.uninstallBrowser();
+    } else {
+      this.uninstallNode();
+    }
+  }
+  installBrowser() {
+    this.originalOnError = window.onerror;
+    window.onerror = (message, source, lineno, colno, error) => {
+      if (error) {
+        this.callback(error, source ?? void 0);
+      } else if (typeof message === "string") {
+        this.callback(new Error(message), source ?? void 0);
+      }
+      this.originalOnError?.call(window, message, source, lineno, colno, error);
+    };
+    this.originalOnUnhandledRejection = window.onunhandledrejection;
+    window.onunhandledrejection = (event) => {
+      const error = event.reason instanceof Error ? event.reason : new Error(String(event.reason));
+      this.callback(error, "unhandledrejection");
+      this.originalOnUnhandledRejection?.call(window, event);
+    };
+  }
+  uninstallBrowser() {
+    window.onerror = this.originalOnError;
+    window.onunhandledrejection = this.originalOnUnhandledRejection;
+  }
+  installNode() {
+    if (typeof process === "undefined") return;
+    process.on("uncaughtException", this.handleNodeError);
+    process.on("unhandledRejection", this.handleNodeRejection);
+  }
+  uninstallNode() {
+    if (typeof process === "undefined") return;
+    process.removeListener("uncaughtException", this.handleNodeError);
+    process.removeListener("unhandledRejection", this.handleNodeRejection);
+  }
+};
+
+// src/context.ts
+function parseUserAgent(ua) {
+  const browser = { name: "Unknown", version: void 0 };
+  const os = { name: "Unknown", version: void 0 };
+  const device = { type: "desktop" };
+  if (/Mobi|Android|iPhone|iPad|iPod/i.test(ua)) {
+    device.type = /iPad|Tablet/i.test(ua) ? "tablet" : "mobile";
+  }
+  if (/Edg\//i.test(ua)) {
+    browser.name = "Edge";
+    browser.version = ua.match(/Edg\/([\d.]+)/)?.[1];
+  } else if (/OPR\//i.test(ua) || /Opera/i.test(ua)) {
+    browser.name = "Opera";
+    browser.version = ua.match(/(?:OPR|Opera)\/([\d.]+)/)?.[1];
+  } else if (/Chrome\//i.test(ua) && !/Chromium/i.test(ua)) {
+    browser.name = "Chrome";
+    browser.version = ua.match(/Chrome\/([\d.]+)/)?.[1];
+  } else if (/Safari\//i.test(ua) && !/Chrome/i.test(ua)) {
+    browser.name = "Safari";
+    browser.version = ua.match(/Version\/([\d.]+)/)?.[1];
+  } else if (/Firefox\//i.test(ua)) {
+    browser.name = "Firefox";
+    browser.version = ua.match(/Firefox\/([\d.]+)/)?.[1];
+  }
+  if (/Windows NT/i.test(ua)) {
+    os.name = "Windows";
+    const ntVersion = ua.match(/Windows NT ([\d.]+)/)?.[1];
+    const versionMap = {
+      "10.0": "10+",
+      "6.3": "8.1",
+      "6.2": "8",
+      "6.1": "7"
+    };
+    os.version = ntVersion ? versionMap[ntVersion] ?? ntVersion : void 0;
+  } else if (/Mac OS X/i.test(ua)) {
+    os.name = "macOS";
+    os.version = ua.match(/Mac OS X ([\d_.]+)/)?.[1]?.replace(/_/g, ".");
+  } else if (/Android/i.test(ua)) {
+    os.name = "Android";
+    os.version = ua.match(/Android ([\d.]+)/)?.[1];
+  } else if (/iPhone OS|iPad/i.test(ua)) {
+    os.name = "iOS";
+    os.version = ua.match(/OS ([\d_]+)/)?.[1]?.replace(/_/g, ".");
+  } else if (/Linux/i.test(ua)) {
+    os.name = "Linux";
+  }
+  return { browser, os, device };
+}
+function gatherContext() {
+  if (!isBrowser()) {
+    return {};
+  }
+  const ua = navigator.userAgent;
+  const { browser, os, device } = parseUserAgent(ua);
+  return {
+    userAgent: ua,
+    locale: navigator.language,
+    page: {
+      url: window.location.href,
+      referrer: document.referrer || void 0,
+      title: document.title || void 0,
+      path: window.location.pathname
+    },
+    browser,
+    os,
+    device
+  };
+}
+function mergeContext(auto, user) {
+  if (!user) return auto;
+  return {
+    ...auto,
+    ...user,
+    page: { ...auto.page, ...user.page },
+    browser: { ...auto.browser, ...user.browser },
+    os: { ...auto.os, ...user.os },
+    device: { ...auto.device, ...user.device }
+  };
+}
+
+// src/storage.ts
+var PREFIX = "ba_";
+var LocalStorage = class {
+  get(key) {
+    try {
+      return localStorage.getItem(PREFIX + key);
+    } catch {
+      return null;
+    }
+  }
+  set(key, value) {
+    try {
+      localStorage.setItem(PREFIX + key, value);
+    } catch {
+    }
+  }
+  remove(key) {
+    try {
+      localStorage.removeItem(PREFIX + key);
+    } catch {
+    }
+  }
+};
+var MemoryStorage = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  get(key) {
+    return this.store.get(PREFIX + key) ?? null;
+  }
+  set(key, value) {
+    this.store.set(PREFIX + key, value);
+  }
+  remove(key) {
+    this.store.delete(PREFIX + key);
+  }
+};
+function createStorage() {
+  try {
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem("__ba_test__", "1");
+      localStorage.removeItem("__ba_test__");
+      return new LocalStorage();
+    }
+  } catch {
+  }
+  return new MemoryStorage();
+}
+
+// src/client.ts
+var DEFAULT_ENDPOINT = "https://api.boringanalytics.io";
+var DEFAULT_FLUSH_AT = 20;
+var DEFAULT_FLUSH_INTERVAL = 5e3;
+var DEFAULT_MAX_RETRIES = 3;
+var BoringAnalytics = class {
+  constructor(config) {
+    this.errorHandler = null;
+    this.pageViewUnsubscribe = null;
+    if (!config.apiKey) {
+      throw new Error("BoringAnalytics: apiKey is required");
+    }
+    this.config = {
+      ...config,
+      defaultProperties: config.defaultProperties ?? {}
+    };
+    this.debug = createDebugLogger(config.debug ?? false);
+    this.debug.log("Initializing with endpoint:", config.endpoint ?? DEFAULT_ENDPOINT);
+    const storage = createStorage();
+    this.session = new SessionManager(storage);
+    const transport = new Transport({
+      endpoint: config.endpoint ?? DEFAULT_ENDPOINT,
+      apiKey: config.apiKey,
+      maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+      onError: config.onError
+    });
+    this.queue = new EventQueue(transport, {
+      flushAt: config.flushAt ?? DEFAULT_FLUSH_AT,
+      flushInterval: config.flushInterval ?? DEFAULT_FLUSH_INTERVAL,
+      debug: this.debug
+    });
+    const autoCapture = config.autoCapture ?? {};
+    if (autoCapture.errors !== false) {
+      this.errorHandler = new GlobalErrorHandler((error, source) => {
+        this.captureError(error, {
+          handled: false,
+          metadata: { source }
+        });
+      });
+      this.errorHandler.install();
+    }
+    if (autoCapture.pageViews && isBrowser()) {
+      this.installPageViewTracking();
+    }
+  }
+  // --- Public API ---
+  /**
+   * Track a named event.
+   *
+   * @example
+   * analytics.track('button_clicked', { properties: { buttonId: 'signup' } });
+   */
+  track(name, options = {}) {
+    this.enqueueEvent("TRACK", name, options.properties, options.timestamp, options.context);
+  }
+  /**
+   * Identify a user with traits.
+   * Sets the userId for all subsequent calls.
+   *
+   * @example
+   * analytics.identify('user-123', { traits: { email: 'user@example.com' } });
+   */
+  identify(userId, options = {}) {
+    this.session.setUserId(userId);
+    this.enqueueEvent("IDENTIFY", "identify", options.traits, options.timestamp, options.context);
+  }
+  /**
+   * Track a page view (typically browser).
+   *
+   * @example
+   * analytics.page('Home');
+   * analytics.page('Product', { properties: { productId: '123' } });
+   */
+  page(name, options = {}) {
+    const pageName = name ?? (isBrowser() ? document.title : "Page View");
+    this.enqueueEvent("PAGE", pageName, options.properties, options.timestamp, options.context);
+  }
+  /**
+   * Track a screen view (typically mobile).
+   */
+  screen(name, options = {}) {
+    this.enqueueEvent("SCREEN", name, options.properties, options.timestamp, options.context);
+  }
+  /**
+   * Associate a user with a group.
+   */
+  group(groupId, options = {}) {
+    this.enqueueEvent("GROUP", groupId, options.traits, options.timestamp, options.context);
+  }
+  /**
+   * Create an alias between two user identities.
+   */
+  alias(userId, previousId) {
+    this.enqueueEvent("ALIAS", "alias", { userId, previousId });
+  }
+  /**
+   * Capture an error for error monitoring.
+   *
+   * @example
+   * try { riskyOp(); }
+   * catch (err) { analytics.captureError(err, { tags: { env: 'prod' } }); }
+   */
+  captureError(error, options = {}) {
+    const err = typeof error === "string" ? new Error(error) : error;
+    const autoContext = gatherContext();
+    const payload = {
+      type: err.name || "Error",
+      message: err.message,
+      stackTrace: err.stack,
+      level: options.level ?? "ERROR",
+      fingerprint: options.fingerprint,
+      handled: options.handled ?? true,
+      metadata: options.metadata,
+      tags: options.tags,
+      timestamp: (options.timestamp ?? /* @__PURE__ */ new Date()).toISOString(),
+      userId: this.session.getUserId() ?? void 0,
+      sessionId: this.session.getSessionId(),
+      context: {
+        userAgent: autoContext.userAgent,
+        browser: autoContext.browser?.name,
+        os: autoContext.os?.name,
+        device: autoContext.device?.type,
+        url: autoContext.page?.url,
+        release: options.release
+      }
+    };
+    this.queue.add({ kind: "error", payload });
+  }
+  /**
+   * Flush all queued events and errors immediately.
+   */
+  async flush() {
+    await this.queue.flush();
+  }
+  /**
+   * Reset the current user. Clears userId, generates new anonymousId and sessionId.
+   * Call this on logout.
+   */
+  reset() {
+    this.session.reset();
+    this.debug.log("User reset");
+  }
+  /**
+   * Gracefully shut down: flush remaining events, remove global handlers.
+   */
+  async shutdown() {
+    this.debug.log("Shutting down");
+    this.errorHandler?.uninstall();
+    this.pageViewUnsubscribe?.();
+    await this.queue.shutdown();
+  }
+  // --- Internal ---
+  enqueueEvent(type, name, properties, timestamp, userContext) {
+    const autoContext = gatherContext();
+    const context = mergeContext(autoContext, userContext);
+    const payload = {
+      type,
+      name,
+      properties: { ...this.config.defaultProperties, ...properties },
+      timestamp: (timestamp ?? /* @__PURE__ */ new Date()).toISOString(),
+      userId: this.session.getUserId() ?? void 0,
+      sessionId: this.session.getSessionId(),
+      anonymousId: this.session.getAnonymousId(),
+      context
+    };
+    this.queue.add({ kind: "event", payload });
+  }
+  installPageViewTracking() {
+    if (!isBrowser()) return;
+    let lastUrl = window.location.href;
+    const checkUrl = () => {
+      const currentUrl = window.location.href;
+      if (currentUrl !== lastUrl) {
+        lastUrl = currentUrl;
+        this.page();
+      }
+    };
+    const origPushState = history.pushState.bind(history);
+    const origReplaceState = history.replaceState.bind(history);
+    history.pushState = (...args) => {
+      origPushState(...args);
+      checkUrl();
+    };
+    history.replaceState = (...args) => {
+      origReplaceState(...args);
+      checkUrl();
+    };
+    window.addEventListener("popstate", checkUrl);
+    this.pageViewUnsubscribe = () => {
+      history.pushState = origPushState;
+      history.replaceState = origReplaceState;
+      window.removeEventListener("popstate", checkUrl);
+    };
+    this.page();
+  }
+};
+
+exports.BoringAnalytics = BoringAnalytics;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map