@eventra_dev/eventra-sdk 1.1.3 → 1.1.5

package/dist/index.mjs

@@ -1,21 +1,125 @@
 // src/client.ts
+var SDK_NAME = "@eventra_dev/eventra-sdk";
+var DEFAULT_ENDPOINT = "https://api.eventra.dev/api/v1/ingest/batch";
+var SDK_VERSION = "1.1.5";
+var LEADER_KEY = "__eventra_leader__";
+var LEADER_TTL_MS = 4e3;
+var QUEUE_KEY = "__eventra_q__";
+var CHANNEL_NAME = "eventra-sdk";
+var MAX_EVENT_NAME = 64;
+var MAX_USER_ID = 120;
+var MAX_PROPERTIES_JSON_BYTES = 32e3;
+var MAX_PROPERTIES_DEPTH = 8;
+var DEFAULT_MAX_PAYLOAD_BYTES = 6e4;
+var DEFAULT_MAX_RETRY_DELAY_MS = 3e4;
+var FETCH_TIMEOUT_MS = 5e3;
+var CIRCUIT_FAILURE_THRESHOLD = 5;
+var CIRCUIT_COOLDOWN_MS = 5e3;
+var activeInstances = 0;
 function detectRuntime() {
   const g = globalThis;
-  if (typeof window !== "undefined") return "browser";
+  if (typeof window !== "undefined" && !g.EdgeRuntime) return "browser";
   if (g.EdgeRuntime) return "edge";
   if (g.process?.env?.AWS_LAMBDA_FUNCTION_NAME) return "serverless";
   if (g.process?.versions?.node) return "node";
   return "unknown";
 }
-function uuid() {
-  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+function uuidV4() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
     return crypto.randomUUID();
   }
-  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    bytes[6] = bytes[6] & 15 | 64;
+    bytes[8] = bytes[8] & 63 | 128;
+    const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+  }
+  throw new Error("Eventra: crypto API unavailable \u2014 cannot generate idempotencyKey");
 }
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
+function truncate(value, max) {
+  if (value === void 0) return void 0;
+  return value.length > max ? value.slice(0, max) : value;
+}
+function validateEventName(name) {
+  const trimmed = name.trim();
+  if (!trimmed) {
+    throw new Error("Eventra: event name is required");
+  }
+  if (trimmed.length > MAX_EVENT_NAME) {
+    throw new Error(`Eventra: event name exceeds max length (${MAX_EVENT_NAME})`);
+  }
+  return trimmed;
+}
+function backoffMs(attempt, base) {
+  const exp = Math.min(DEFAULT_MAX_RETRY_DELAY_MS, base * 2 ** attempt);
+  const jitter = exp * (0.5 + Math.random() * 0.5);
+  return jitter;
+}
+function utf8ByteLength(value) {
+  if (typeof TextEncoder !== "undefined") {
+    return new TextEncoder().encode(value).length;
+  }
+  const g = globalThis;
+  if (g.Buffer) {
+    return g.Buffer.byteLength(value, "utf8");
+  }
+  return value.length;
+}
+function mergeQueues(...queues) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const q of queues) {
+    for (const e of q) {
+      if (seen.has(e.idempotencyKey)) continue;
+      seen.add(e.idempotencyKey);
+      out.push(e);
+    }
+  }
+  return out;
+}
+function validateProperties(properties) {
+  const depth = (obj, level) => {
+    if (level > MAX_PROPERTIES_DEPTH) {
+      throw new Error(`Eventra: properties exceed max depth (${MAX_PROPERTIES_DEPTH})`);
+    }
+    if (obj === null || typeof obj !== "object") return;
+    if (Array.isArray(obj)) {
+      for (const item of obj) depth(item, level + 1);
+      return;
+    }
+    for (const value of Object.values(obj)) {
+      depth(value, level + 1);
+    }
+  };
+  depth(properties, 0);
+  const json = JSON.stringify(properties);
+  if (utf8ByteLength(json) > MAX_PROPERTIES_JSON_BYTES) {
+    throw new Error(
+      `Eventra: properties exceed max size (${MAX_PROPERTIES_JSON_BYTES} bytes)`
+    );
+  }
+  return properties;
+}
+function estimateEnvelopeBytes(events, sdk, sentAt) {
+  return utf8ByteLength(
+    JSON.stringify({
+      sentAt,
+      sdk,
+      events
+    })
+  );
+}
+var RetryableDeliveryError = class extends Error {
+  constructor(message = "retryable delivery error") {
+    super(message);
+    this.name = "RetryableDeliveryError";
+  }
+};
 var Storage = class {
   constructor() {
     this.enabled = false;
@@ -43,62 +147,167 @@ var Storage = class {
     } catch {
     }
   }
+  remove(key) {
+    if (!this.enabled) return;
+    try {
+      localStorage.removeItem(key);
+    } catch {
+    }
+  }
 };
 var Leader = class {
-  constructor(enabled) {
-    this.isLeader = true;
-    if (!enabled) return;
-    if (typeof BroadcastChannel !== "undefined") {
-      this.channel = new BroadcastChannel("eventra");
-      this.channel.onmessage = (e) => {
-        if (e.data === "leader") this.isLeader = false;
+  constructor(onLeadershipChange) {
+    this.onLeadershipChange = onLeadershipChange;
+    this.tabId = uuidV4();
+    this.isLeader = false;
+    if (typeof localStorage === "undefined") {
+      this.isLeader = true;
+      return;
+    }
+    this.tick();
+    this.election = setInterval(() => this.tick(), LEADER_TTL_MS / 2);
+    if (typeof window !== "undefined") {
+      this.onStorage = (e) => {
+        if (e.key === LEADER_KEY) this.tick();
       };
-      this.channel.postMessage("leader");
+      window.addEventListener("storage", this.onStorage);
+    }
+  }
+  tick() {
+    const was = this.isLeader;
+    if (this.isLeader) {
+      if (!this.verifyLease()) {
+        this.isLeader = false;
+      } else {
+        this.renew();
+      }
+    } else {
+      this.isLeader = this.tryAcquire();
+      if (this.isLeader) {
+        if (!this.heartbeat) {
+          this.heartbeat = setInterval(() => this.renew(), LEADER_TTL_MS / 2);
+        }
+      }
+    }
+    if (!this.isLeader && this.heartbeat) {
+      clearInterval(this.heartbeat);
+      this.heartbeat = void 0;
+    }
+    if (was !== this.isLeader) {
+      this.onLeadershipChange?.(this.isLeader);
+    }
+  }
+  tryAcquire() {
+    try {
+      const now = Date.now();
+      const raw = localStorage.getItem(LEADER_KEY);
+      if (!raw) {
+        this.renew();
+        return true;
+      }
+      const parsed = JSON.parse(raw);
+      if (now - parsed.ts > LEADER_TTL_MS) {
+        this.renew();
+        return true;
+      }
+      if (parsed.tabId === this.tabId) {
+        this.renew();
+        return true;
+      }
+      return false;
+    } catch {
+      return true;
+    }
+  }
+  verifyLease() {
+    try {
+      const raw = localStorage.getItem(LEADER_KEY);
+      if (!raw) return false;
+      const parsed = JSON.parse(raw);
+      return parsed.tabId === this.tabId && Date.now() - parsed.ts <= LEADER_TTL_MS;
+    } catch {
+      return false;
+    }
+  }
+  renew() {
+    try {
+      localStorage.setItem(
+        LEADER_KEY,
+        JSON.stringify({ ts: Date.now(), tabId: this.tabId })
+      );
+    } catch {
     }
   }
   canSend() {
     return this.isLeader;
   }
   destroy() {
-    this.channel?.close();
+    if (this.election) clearInterval(this.election);
+    if (this.heartbeat) clearInterval(this.heartbeat);
+    if (this.onStorage && typeof window !== "undefined") {
+      window.removeEventListener("storage", this.onStorage);
+    }
+    if (this.isLeader && typeof localStorage !== "undefined") {
+      try {
+        const raw = localStorage.getItem(LEADER_KEY);
+        if (raw) {
+          const parsed = JSON.parse(raw);
+          if (parsed.tabId === this.tabId) {
+            localStorage.removeItem(LEADER_KEY);
+          }
+        }
+      } catch {
+      }
+    }
   }
 };
 var Eventra = class {
   constructor(options) {
     this.queue = [];
+    this.sending = null;
     this.inFlight = false;
     this.destroyed = false;
+    this.shuttingDown = false;
     this.storage = new Storage();
     this.leader = null;
     this.failureCount = 0;
     this.circuitOpenUntil = 0;
+    this.circuitHalfOpen = false;
     this.exitHandlers = [];
-    if (!options.apiKey) throw new Error("apiKey required");
-    if (!options.endpoint) throw new Error("endpoint required");
+    if (!options.apiKey) throw new Error("Eventra: apiKey required");
+    activeInstances++;
+    if (activeInstances > 1 && typeof console !== "undefined") {
+      console.warn(
+        "Eventra: multiple SDK instances detected \u2014 duplicate timers and sends are possible"
+      );
+    }
     this.options = options;
     this.apiKey = options.apiKey;
-    this.endpoint = options.endpoint;
+    this.endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
     this.runtime = detectRuntime();
     this.fetch = options.fetchImpl ?? globalThis.fetch;
     if (!this.fetch) {
-      throw new Error("fetch not available \u2014 provide fetchImpl");
+      throw new Error("Eventra: fetch not available \u2014 provide fetchImpl");
     }
     this.maxBatch = options.maxBatchSize ?? 50;
     this.maxQueue = options.maxQueueSize ?? 1e4;
+    this.maxPayloadBytes = options.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES;
     this.flushInterval = options.flushInterval ?? 2e3;
     this.retries = options.maxRetries ?? 3;
     this.retryDelay = options.retryBaseDelayMs ?? 300;
     this.sdkInfo = {
-      name: "@eventra_dev/eventra-sdk",
-      version: "1.0.0",
+      name: SDK_NAME,
+      version: SDK_VERSION,
       runtime: this.runtime
     };
     if (this.runtime === "browser") {
-      const saved = this.storage.get("__eventra_q__");
-      if (Array.isArray(saved)) this.queue = saved;
+      this.loadAndMergeQueue();
+      this.setupQueueSync();
     }
     if (this.runtime === "browser" && options.multiTabMode === "leader") {
-      this.leader = new Leader(true);
+      this.leader = new Leader((isLeader) => {
+        if (isLeader) void this.flush();
+      });
     }
     if (!options.disableTimer) {
       this.startTimer();
@@ -110,23 +319,31 @@ var Eventra = class {
       this.setupProcessExit();
     }
   }
-  // ================= PUBLIC =================
   track(name, options) {
-    if (this.destroyed) return;
+    if (this.destroyed || this.shuttingDown) return;
+    let eventName;
+    let properties;
+    try {
+      eventName = validateEventName(name);
+      properties = validateProperties(options?.properties ?? {});
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "invalid event";
+      throw new Error(message);
+    }
     if (this.queue.length >= this.maxQueue) {
       this.options.onEventsDropped?.(1);
       return;
     }
     const event = {
-      idempotencyKey: uuid(),
-      name,
-      userId: options?.userId,
-      properties: options?.properties ?? {},
+      idempotencyKey: uuidV4(),
+      name: eventName,
+      userId: truncate(options?.userId, MAX_USER_ID),
+      properties,
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     };
     this.queue.push(event);
     if (this.runtime === "browser") {
-      this.persist();
+      this.syncQueue();
     }
     if (this.queue.length >= this.maxBatch) {
       void this.flush();
@@ -137,54 +354,134 @@ var Eventra = class {
   }
   async flush() {
     if (this.inFlight || this.destroyed) return;
-    if (!this.queue.length) return;
+    if (!this.queue.length && !this.sending?.length) return;
     if (this.leader && !this.leader.canSend()) return;
-    if (Date.now() < this.circuitOpenUntil) return;
-    this.inFlight = true;
-    const batch = this.queue.splice(0, this.maxBatch);
-    if (this.runtime === "browser") {
-      this.persist();
+    const now = Date.now();
+    if (now < this.circuitOpenUntil) return;
+    if (this.circuitOpenUntil > 0 && now >= this.circuitOpenUntil) {
+      this.circuitHalfOpen = true;
+      this.circuitOpenUntil = 0;
     }
+    this.inFlight = true;
     try {
-      await this.send(batch);
-      this.failureCount = 0;
-    } catch {
-      this.queue = [...batch, ...this.queue];
-      if (this.runtime === "browser") {
-        this.persist();
+      while (this.queue.length > 0) {
+        const batch = this.buildBatch();
+        if (!batch.length) break;
+        this.sending = batch;
+        try {
+          await this.send(batch);
+          this.removeDelivered(batch);
+          this.failureCount = 0;
+          this.circuitHalfOpen = false;
+        } catch (err) {
+          if (err instanceof RetryableDeliveryError) {
+            this.failureCount++;
+            if (this.circuitHalfOpen || this.failureCount >= CIRCUIT_FAILURE_THRESHOLD) {
+              this.circuitOpenUntil = Date.now() + CIRCUIT_COOLDOWN_MS;
+              this.circuitHalfOpen = false;
+            }
+            break;
+          }
+          break;
+        } finally {
+          this.sending = null;
+        }
+        if (this.circuitOpenUntil > Date.now()) break;
       }
-      this.failureCount++;
-      if (this.failureCount >= 5) {
-        this.circuitOpenUntil = Date.now() + 5e3;
+      if (this.runtime === "browser") {
+        this.syncQueue();
       }
     } finally {
       this.inFlight = false;
     }
   }
+  /** Flush pending events, then tear down timers and listeners */
+  async shutdown() {
+    if (this.shuttingDown) return;
+    this.shuttingDown = true;
+    try {
+      await this.flush();
+    } finally {
+      this.destroy();
+    }
+  }
   destroy() {
+    if (this.destroyed) return;
     this.destroyed = true;
+    activeInstances = Math.max(0, activeInstances - 1);
     if (this.timer) clearInterval(this.timer);
     this.leader?.destroy();
+    if (this.channel) {
+      this.channel.close();
+      this.channel = void 0;
+    }
+    if (this.onStorageQueue && typeof window !== "undefined") {
+      window.removeEventListener("storage", this.onStorageQueue);
+    }
     for (const off of this.exitHandlers) {
       off();
     }
   }
-  // ================= SEND =================
+  buildBatch() {
+    const batch = [];
+    const sentAt = (/* @__PURE__ */ new Date()).toISOString();
+    let index = 0;
+    while (index < this.queue.length && batch.length < this.maxBatch) {
+      const event = this.queue[index];
+      const candidate = [...batch, event];
+      const bytes = estimateEnvelopeBytes(candidate, this.sdkInfo, sentAt);
+      if (bytes > this.maxPayloadBytes) {
+        if (batch.length === 0) {
+          const poisonKey = event.idempotencyKey;
+          this.dropPoisonEvent(event);
+          if (this.queue[index]?.idempotencyKey === poisonKey) {
+            index++;
+          }
+          continue;
+        }
+        break;
+      }
+      batch.push(event);
+      index++;
+    }
+    return batch;
+  }
+  dropPoisonEvent(event) {
+    this.removeDelivered([event]);
+    this.options.onEventsDropped?.(1);
+    this.options.onDeliveryFailed?.({ status: 413, events: [event] });
+    if (this.runtime === "browser") {
+      this.syncQueue();
+    }
+  }
+  removeDelivered(batch) {
+    const keys = new Set(batch.map((e) => e.idempotencyKey));
+    this.queue = this.queue.filter((e) => !keys.has(e.idempotencyKey));
+  }
   async send(events) {
-    const payload = JSON.stringify({
-      sentAt: (/* @__PURE__ */ new Date()).toISOString(),
-      sdk: this.sdkInfo,
-      events
-    });
-    if (this.runtime === "browser" && typeof navigator !== "undefined" && navigator.sendBeacon && payload.length < 6e4 && document.visibilityState === "hidden") {
-      navigator.sendBeacon(this.endpoint, payload);
+    let payload;
+    try {
+      payload = JSON.stringify({
+        sentAt: (/* @__PURE__ */ new Date()).toISOString(),
+        sdk: this.sdkInfo,
+        events
+      });
+    } catch {
+      this.options.onDeliveryFailed?.({ status: 0, events });
+      this.removeDelivered(events);
+      return;
+    }
+    const payloadBytes = utf8ByteLength(payload);
+    if (payloadBytes > this.maxPayloadBytes) {
+      this.dropPoisonEvents(events);
       return;
     }
-    let attempt = 0;
-    while (attempt <= this.retries) {
+    const useKeepalive = this.runtime === "browser" && typeof document !== "undefined" && document.visibilityState === "hidden" && payloadBytes <= this.maxPayloadBytes;
+    const maxAttempts = Math.max(1, this.retries);
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
       try {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 5e3);
         const res = await this.fetch(this.endpoint, {
           method: "POST",
           headers: {
@@ -192,20 +489,86 @@ var Eventra = class {
             "x-api-key": this.apiKey
           },
           body: payload,
-          signal: controller.signal
+          signal: controller.signal,
+          keepalive: useKeepalive
         });
-        clearTimeout(timeout);
-        if (res.status >= 400 && res.status < 500) return;
-        if (!res.ok) throw new Error();
+        if (res.status === 429 || res.status >= 500) {
+          throw new RetryableDeliveryError();
+        }
+        if (res.status >= 400 && res.status < 500) {
+          this.options.onDeliveryFailed?.({ status: res.status, events });
+          this.removeDelivered(events);
+          return;
+        }
+        if (!res.ok) {
+          throw new RetryableDeliveryError();
+        }
         return;
-      } catch {
-        attempt++;
-        if (attempt > this.retries) throw new Error();
-        await sleep(this.retryDelay * 2 ** attempt);
+      } catch (err) {
+        const isLast = attempt >= maxAttempts - 1;
+        if (isLast) {
+          throw err instanceof RetryableDeliveryError ? err : new RetryableDeliveryError();
+        }
+        await sleep(backoffMs(attempt + 1, this.retryDelay));
+      } finally {
+        clearTimeout(timeout);
       }
     }
   }
-  // ================= INTERNAL =================
+  dropPoisonEvents(events) {
+    for (const event of events) {
+      this.dropPoisonEvent(event);
+    }
+  }
+  loadAndMergeQueue() {
+    const remote = this.storage.get(QUEUE_KEY);
+    if (Array.isArray(remote)) {
+      this.queue = mergeQueues(this.queue, remote);
+    }
+    this.trimQueue();
+  }
+  syncQueue() {
+    const remote = this.storage.get(QUEUE_KEY);
+    const merged = mergeQueues(
+      Array.isArray(remote) ? remote : [],
+      this.queue
+    );
+    this.queue = this.trimQueue(merged);
+    this.storage.set(QUEUE_KEY, this.queue);
+    this.broadcastQueue();
+  }
+  trimQueue(queue = this.queue) {
+    if (queue.length <= this.maxQueue) return queue;
+    const dropped = queue.length - this.maxQueue;
+    this.options.onEventsDropped?.(dropped);
+    return queue.slice(-this.maxQueue);
+  }
+  broadcastQueue() {
+    try {
+      this.channel?.postMessage({
+        type: "queue-sync",
+        events: this.queue
+      });
+    } catch {
+    }
+  }
+  setupQueueSync() {
+    if (typeof BroadcastChannel !== "undefined") {
+      this.channel = new BroadcastChannel(CHANNEL_NAME);
+      this.channel.onmessage = (e) => {
+        if (e.data?.type !== "queue-sync" || !Array.isArray(e.data.events)) return;
+        this.queue = mergeQueues(this.queue, e.data.events);
+        this.queue = this.trimQueue();
+      };
+    }
+    if (typeof window !== "undefined") {
+      this.onStorageQueue = (e) => {
+        if (e.key !== QUEUE_KEY) return;
+        this.loadAndMergeQueue();
+      };
+      window.addEventListener("storage", this.onStorageQueue);
+    }
+  }
   startTimer() {
     this.timer = setInterval(() => {
       void this.flush();
@@ -217,37 +580,29 @@ var Eventra = class {
         void this.flush();
       }
     };
+    const pageHide = () => {
+      void this.flush();
+    };
     window.addEventListener("visibilitychange", handler);
+    window.addEventListener("pagehide", pageHide);
     this.exitHandlers.push(() => {
       window.removeEventListener("visibilitychange", handler);
+      window.removeEventListener("pagehide", pageHide);
     });
   }
   setupProcessExit() {
-    const g = globalThis;
-    const flushSafe = async () => {
-      try {
-        await this.flush();
-      } catch {
-      }
+    const proc = globalThis.process;
+    if (!proc?.on) return;
+    const onSignal = () => {
+      void this.shutdown();
     };
-    const beforeExit = () => {
-      void flushSafe();
-    };
-    const sigint = async () => {
-      await flushSafe();
-      g.exit();
-    };
-    g?.on?.("beforeExit", beforeExit);
-    g?.on?.("SIGINT", sigint);
+    proc.once("SIGINT", onSignal);
+    proc.once("SIGTERM", onSignal);
     this.exitHandlers.push(() => {
-      g?.off?.("beforeExit", beforeExit);
-      g?.off?.("SIGINT", sigint);
+      proc.off?.("SIGINT", onSignal);
+      proc.off?.("SIGTERM", onSignal);
     });
   }
-  persist() {
-    if (this.runtime !== "browser") return;
-    this.storage.set("__eventra_q__", this.queue);
-  }
 };
 export {
   Eventra