@scoperat/tracker 0.3.1 → 0.4.1

package/README.md

@@ -32,13 +32,14 @@ scoperat.reset();
 
 Initialize the tracker. Must be called before any other method.
 
-| Option          | Type                      | Default                  | Description                  |
-| --------------- | ------------------------- | ------------------------ | ---------------------------- |
-| `endpoint`      | `string`                  | `window.location.origin` | API base URL                 |
-| `flushAt`       | `number`                  | `10`                     | Flush after this many events |
-| `flushInterval` | `number`                  | `3000`                   | Auto-flush interval in ms    |
-| `timeout`       | `number`                  | `10000`                  | Request timeout in ms        |
-| `onError`       | `(error, events) => void` | —                        | Error callback               |
+| Option          | Type                      | Default                  | Description                          |
+| --------------- | ------------------------- | ------------------------ | ------------------------------------ |
+| `endpoint`      | `string`                  | `window.location.origin` | API base URL                         |
+| `flushAt`       | `number`                  | `10`                     | Flush after this many events         |
+| `flushInterval` | `number`                  | `3000`                   | Auto-flush interval in ms            |
+| `timeout`       | `number`                  | `10000`                  | Request timeout in ms                |
+| `maxQueueSize`  | `number`                  | `1000`                   | Max buffered events (oldest dropped) |
+| `onError`       | `(error, events) => void` | —                        | Error callback                       |
 
 ### `scoperat.identify(userId, traits?)`
 
@@ -65,7 +66,7 @@ Flush remaining events and stop the auto-flush timer. Call before app teardown.
 - **Auto-batching** — events are buffered and sent in batches for efficiency
 - **Anonymous IDs** — persistent anonymous ID via `localStorage`, auto-generated on first visit
 - **sendBeacon fallback** — uses `navigator.sendBeacon` on page hide for reliable delivery
-- **Retry on failure** — failed batches are re-queued for the next flush
+- **Retry on failure** — transient failures (network errors, 5xx, 408/429) are re-queued and retried with exponential backoff; non-retryable 4xx batches are dropped
 - **Zero dependencies** — no runtime dependencies
 - **Tree-shakeable** — marked as side-effect-free for optimal bundling
 - **ESM-only** — ships as pure ES modules

package/dist/index.d.ts

@@ -37,6 +37,12 @@ interface InitOptions {
     flushInterval?: number;
     timeout?: number;
     onError?: (error: Error, events: TrackEvent[]) => void;
+    /**
+     * Maximum number of events buffered while the ingest API is
+     * unreachable. When full, the oldest non-error event is dropped
+     * (surfaced through `onError`). Defaults to 1000.
+     */
+    maxQueueSize?: number;
     /** Session inactivity timeout in ms. Defaults to 30 minutes. */
     sessionTimeout?: number;
     /** Automatically capture uncaught errors and unhandled rejections. Defaults to false. */
@@ -108,8 +114,16 @@ declare class TrackerImpl {
     private timeout;
     private onError?;
     private buffer;
+    private maxQueueSize;
     private timer;
     private visibilityHandler;
+    private pageHideHandler;
+    private uninstallErrorHandlers;
+    /** Consecutive flush failures, drives exponential retry backoff. */
+    private flushFailures;
+    /** Timestamp before which automatic flushes are suppressed (backoff). */
+    private nextFlushAllowedAt;
+    private exceptionFlushScheduled;
     private userId;
     private orgId;
     private traits;
@@ -188,7 +202,22 @@ declare class TrackerImpl {
     addBreadcrumb(category: string, message: string, data?: Record<string, unknown>): void;
     track(event: string, properties?: Record<string, unknown>): void;
     track(event: TrackEvent): void;
+    /**
+     * Push an event onto the buffer, evicting the oldest event when the
+     * queue is full. `$exception` events are preferentially retained.
+     */
+    private enqueue;
+    /** Flush unless we're inside a retry-backoff window. */
+    private maybeFlush;
+    private scheduleExceptionFlush;
     flush(): Promise<FlushResult>;
+    /**
+     * Record a failed flush and push out the next automatic flush with
+     * exponential backoff (capped) so a down ingest endpoint isn't
+     * hammered on every `flushInterval` tick. Explicit `flush()` calls
+     * are unaffected.
+     */
+    private recordFlushFailure;
     /**
      * Fire-and-forget flush that survives page unload.
      *
@@ -208,6 +237,7 @@ declare class TrackerImpl {
     refreshFlags(): Promise<void>;
     shutdown(): Promise<void>;
 }
+
 declare const scoperat: TrackerImpl;
 
 export { type EvaluatedFlag, type EventSource, FlagClient, type FlushResult, type IdentifyOptions, type IdentifyTraits, type InitOptions, type TrackEvent, scoperat as default };

package/dist/index.js

@@ -103,54 +103,107 @@ function getBrowserContext() {
 
 // src/errors.ts
 var DEDUP_COOLDOWN_MS = 6e4;
+var MAX_DEDUP_ENTRIES = 200;
+var MAX_MESSAGE_LENGTH = 2048;
+var MAX_STACK_LENGTH = 16384;
+var MAX_REASON_JSON_LENGTH = 1024;
 var dedupMap = /* @__PURE__ */ new Map();
-function simpleFingerprint(type, stack) {
+function truncate2(str, max) {
+  return str.length > max ? str.slice(0, max) + "\u2026" : str;
+}
+function fingerprint(type, message, stack) {
   const firstFrame = stack?.split("\n")[1]?.trim() ?? "";
-  return `${type}:${firstFrame}`;
+  return `${type}:${truncate2(message, 100)}:${firstFrame}`;
 }
-function isDuplicate(fingerprint) {
-  const lastSent = dedupMap.get(fingerprint);
-  if (lastSent && Date.now() - lastSent < DEDUP_COOLDOWN_MS) return true;
-  dedupMap.set(fingerprint, Date.now());
+function isDuplicate(fp) {
+  const now = Date.now();
+  const lastSent = dedupMap.get(fp);
+  if (lastSent && now - lastSent < DEDUP_COOLDOWN_MS) return true;
+  dedupMap.set(fp, now);
+  pruneDedupMap(now);
   return false;
 }
+function pruneDedupMap(now) {
+  if (dedupMap.size <= MAX_DEDUP_ENTRIES) return;
+  for (const [key, ts] of dedupMap) {
+    if (now - ts >= DEDUP_COOLDOWN_MS) dedupMap.delete(key);
+  }
+  for (const key of dedupMap.keys()) {
+    if (dedupMap.size <= MAX_DEDUP_ENTRIES) break;
+    dedupMap.delete(key);
+  }
+}
 function sendException(tracker, props, getBreadcrumbs2) {
-  const fp = simpleFingerprint(props.type, props.stack);
+  const fp = fingerprint(props.type, props.message, props.stack);
   if (isDuplicate(fp)) return;
   tracker.track("$exception", {
     ...props,
+    message: truncate2(props.message, MAX_MESSAGE_LENGTH),
+    stack: props.stack ? truncate2(props.stack, MAX_STACK_LENGTH) : void 0,
     context: { breadcrumbs: getBreadcrumbs2() }
   });
 }
+function describeRejectionReason(reason) {
+  if (reason instanceof Error) {
+    return {
+      type: reason.name || "UnhandledRejection",
+      message: reason.message,
+      stack: reason.stack
+    };
+  }
+  if (typeof reason === "object" && reason !== null) {
+    let json;
+    try {
+      json = JSON.stringify(reason) ?? Object.prototype.toString.call(reason);
+    } catch {
+      json = Object.prototype.toString.call(reason);
+    }
+    return {
+      type: "UnhandledRejection",
+      message: `Non-Error promise rejection: ${truncate2(json, MAX_REASON_JSON_LENGTH)}`,
+      stack: void 0
+    };
+  }
+  return {
+    type: "UnhandledRejection",
+    message: String(reason),
+    stack: void 0
+  };
+}
+var uninstallHandlers = null;
 function installGlobalHandlers(tracker, getBreadcrumbs2) {
-  if (typeof window === "undefined") return;
-  window.onerror = (_message, filename, lineno, colno, error) => {
-    const err = error ?? new Error(String(_message));
+  if (typeof window === "undefined") return () => {
+  };
+  if (uninstallHandlers) return uninstallHandlers;
+  const onError = (event) => {
+    const error = event.error;
+    const message = error?.message || (typeof event.message === "string" && event.message ? event.message : "Unknown error");
+    const opaque = !error && /^Script error\.?$/.test(message);
     sendException(
       tracker,
       {
-        type: err.name || "Error",
-        message: err.message || String(_message),
-        stack: err.stack,
+        type: error?.name || "Error",
+        message,
+        stack: error?.stack,
         handled: false,
         mechanism: "onerror",
         source: "browser",
-        filename,
-        lineno,
-        colno
+        filename: event.filename || void 0,
+        lineno: event.lineno || void 0,
+        colno: event.colno || void 0,
+        ...opaque ? { opaque: true } : {}
       },
       getBreadcrumbs2
     );
   };
-  window.onunhandledrejection = (event) => {
-    const reason = event.reason;
-    const err = reason instanceof Error ? reason : new Error(String(reason));
+  const onRejection = (event) => {
+    const { type, message, stack } = describeRejectionReason(event.reason);
     sendException(
       tracker,
       {
-        type: err.name || "UnhandledRejection",
-        message: err.message,
-        stack: err.stack,
+        type,
+        message,
+        stack,
         handled: false,
         mechanism: "onunhandledrejection",
         source: "browser"
@@ -158,6 +211,14 @@ function installGlobalHandlers(tracker, getBreadcrumbs2) {
       getBreadcrumbs2
     );
   };
+  window.addEventListener("error", onError);
+  window.addEventListener("unhandledrejection", onRejection);
+  uninstallHandlers = () => {
+    window.removeEventListener("error", onError);
+    window.removeEventListener("unhandledrejection", onRejection);
+    uninstallHandlers = null;
+  };
+  return uninstallHandlers;
 }
 
 // src/flag-client.ts
@@ -262,7 +323,9 @@ var DEFAULT_FLUSH_AT = 10;
 var DEFAULT_FLUSH_INTERVAL = 3e3;
 var DEFAULT_TIMEOUT = 1e4;
 var DEFAULT_SESSION_TIMEOUT = 30 * 60 * 1e3;
+var DEFAULT_MAX_QUEUE_SIZE = 1e3;
 var MAX_BATCH_SIZE = 100;
+var MAX_RETRY_BACKOFF = 6e4;
 var ANON_ID_KEY = "__scoperat_anon_id";
 var SESSION_ID_KEY = "__scoperat_session_id";
 var LAST_ACTIVITY_KEY = "__scoperat_last_activity";
@@ -303,8 +366,16 @@ var TrackerImpl = class {
   timeout = DEFAULT_TIMEOUT;
   onError;
   buffer = [];
+  maxQueueSize = DEFAULT_MAX_QUEUE_SIZE;
   timer = null;
   visibilityHandler = null;
+  pageHideHandler = null;
+  uninstallErrorHandlers = null;
+  /** Consecutive flush failures, drives exponential retry backoff. */
+  flushFailures = 0;
+  /** Timestamp before which automatic flushes are suppressed (backoff). */
+  nextFlushAllowedAt = 0;
+  exceptionFlushScheduled = false;
   userId;
   orgId;
   traits = {};
@@ -322,12 +393,12 @@ var TrackerImpl = class {
     this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
     this.onError = options.onError;
     this.sessionTimeout = options.sessionTimeout ?? DEFAULT_SESSION_TIMEOUT;
+    this.maxQueueSize = options.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE;
     this.anonymousId = getOrCreateAnonId();
     if (this.timer) clearInterval(this.timer);
     this.timer = setInterval(() => {
       if (this.buffer.length > 0) {
-        this.flush().catch(() => {
-        });
+        this.maybeFlush();
       }
     }, this.flushInterval);
     if (typeof window !== "undefined") {
@@ -340,9 +411,18 @@ var TrackerImpl = class {
         }
       };
       window.addEventListener("visibilitychange", this.visibilityHandler);
+      if (this.pageHideHandler) {
+        window.removeEventListener("pagehide", this.pageHideHandler);
+      }
+      this.pageHideHandler = () => {
+        if (this.buffer.length > 0) {
+          this.flushSync();
+        }
+      };
+      window.addEventListener("pagehide", this.pageHideHandler);
     }
     if (options.captureErrors) {
-      installGlobalHandlers(this, getBreadcrumbs);
+      this.uninstallErrorHandlers = installGlobalHandlers(this, getBreadcrumbs);
       startBreadcrumbCollection();
     }
     this._flagClient?.destroy();
@@ -356,13 +436,10 @@ var TrackerImpl = class {
         userId: this.userId,
         anonymousId: this.anonymousId,
         orgId: this.orgId
-      }),
-      onEvaluation: (key, flag) => this.track("$flag_evaluation", {
-        flag_key: key,
-        flag_value: flag.value,
-        flag_type: flag.type,
-        flag_source: flag.source
       })
+      // Flag evaluations are an internal system signal, not a product
+      // event — we deliberately don't emit `$flag_evaluation` into the
+      // user's event stream (the server also refuses to persist it).
     });
   }
   /** The underlying flag evaluation client. Use for direct SDK integration. */
@@ -600,7 +677,7 @@ var TrackerImpl = class {
   emitSessionEvent(event, sessionId, reason, occurredAt) {
     if (!this.writeKey) return;
     const traitsContext = Object.keys(this.traits).length > 0 ? { traits: this.traits } : {};
-    this.buffer.push({
+    this.enqueue({
       event,
       properties: { reason },
       occurred_at: occurredAt ?? (/* @__PURE__ */ new Date()).toISOString(),
@@ -646,17 +723,20 @@ var TrackerImpl = class {
   }
   captureException(error, context) {
     if (!this.writeKey) return;
-    const breadcrumbs = getBreadcrumbs();
-    this.track("$exception", {
-      type: error.name || "Error",
-      message: error.message,
-      stack: error.stack,
-      handled: true,
-      mechanism: context?.mechanism ?? "manual",
-      source: "browser",
-      ...context,
-      context: { breadcrumbs }
-    });
+    const { mechanism, ...extra } = context ?? {};
+    sendException(
+      this,
+      {
+        type: error.name || "Error",
+        message: error.message,
+        stack: error.stack,
+        handled: true,
+        mechanism: typeof mechanism === "string" ? mechanism : "manual",
+        source: "browser",
+        extra: Object.keys(extra).length > 0 ? extra : void 0
+      },
+      getBreadcrumbs
+    );
   }
   addBreadcrumb(category, message, data) {
     addBreadcrumb({
@@ -685,12 +765,44 @@ var TrackerImpl = class {
         ...evt.context
       }
     };
-    this.buffer.push(enriched);
-    if (this.buffer.length >= this.flushAt) {
-      this.flush().catch(() => {
-      });
+    this.enqueue(enriched);
+    if (enriched.event === "$exception") {
+      this.scheduleExceptionFlush();
+    } else if (this.buffer.length >= this.flushAt) {
+      this.maybeFlush();
     }
   }
+  /**
+   * Push an event onto the buffer, evicting the oldest event when the
+   * queue is full. `$exception` events are preferentially retained.
+   */
+  enqueue(evt) {
+    if (this.buffer.length >= this.maxQueueSize) {
+      const idx = this.buffer.findIndex((e) => e.event !== "$exception");
+      const dropped = this.buffer.splice(idx === -1 ? 0 : idx, 1);
+      if (dropped.length > 0) {
+        this.onError?.(
+          new Error("Event buffer full \u2014 dropped oldest event"),
+          dropped
+        );
+      }
+    }
+    this.buffer.push(evt);
+  }
+  /** Flush unless we're inside a retry-backoff window. */
+  maybeFlush() {
+    if (Date.now() < this.nextFlushAllowedAt) return;
+    this.flush().catch(() => {
+    });
+  }
+  scheduleExceptionFlush() {
+    if (this.exceptionFlushScheduled) return;
+    this.exceptionFlushScheduled = true;
+    setTimeout(() => {
+      this.exceptionFlushScheduled = false;
+      this.maybeFlush();
+    }, 0);
+  }
   async flush() {
     if (!this.writeKey || this.buffer.length === 0) {
       return { success: true, ingested: 0 };
@@ -708,17 +820,41 @@ var TrackerImpl = class {
       });
       if (!res.ok) {
         const body = await res.text().catch(() => "");
-        throw new Error(`API returned ${res.status}: ${body}`);
+        const err = new Error(`API returned ${res.status}: ${body}`);
+        const retryable = res.status === 408 || res.status === 429 || res.status >= 500;
+        if (retryable) {
+          this.buffer.unshift(...batch);
+        }
+        this.recordFlushFailure();
+        this.onError?.(err, batch);
+        return { success: false, ingested: 0 };
       }
+      this.flushFailures = 0;
+      this.nextFlushAllowedAt = 0;
       const json = await res.json();
       return { success: true, ingested: json.ingested };
     } catch (error) {
       this.buffer.unshift(...batch);
+      this.recordFlushFailure();
       const err = error instanceof Error ? error : new Error(String(error));
       this.onError?.(err, batch);
       return { success: false, ingested: 0 };
     }
   }
+  /**
+   * Record a failed flush and push out the next automatic flush with
+   * exponential backoff (capped) so a down ingest endpoint isn't
+   * hammered on every `flushInterval` tick. Explicit `flush()` calls
+   * are unaffected.
+   */
+  recordFlushFailure() {
+    this.flushFailures += 1;
+    const delay = Math.min(
+      this.flushInterval * 2 ** this.flushFailures,
+      MAX_RETRY_BACKOFF
+    );
+    this.nextFlushAllowedAt = Date.now() + delay;
+  }
   /**
    * Fire-and-forget flush that survives page unload.
    *
@@ -770,12 +906,21 @@ var TrackerImpl = class {
     }
     this._flagClient?.destroy();
     this._flagClient = null;
-    if (typeof window !== "undefined" && this.visibilityHandler) {
-      window.removeEventListener("visibilitychange", this.visibilityHandler);
-      this.visibilityHandler = null;
+    if (typeof window !== "undefined") {
+      if (this.visibilityHandler) {
+        window.removeEventListener("visibilitychange", this.visibilityHandler);
+        this.visibilityHandler = null;
+      }
+      if (this.pageHideHandler) {
+        window.removeEventListener("pagehide", this.pageHideHandler);
+        this.pageHideHandler = null;
+      }
     }
+    this.uninstallErrorHandlers?.();
+    this.uninstallErrorHandlers = null;
     while (this.buffer.length > 0) {
-      await this.flush();
+      const result = await this.flush();
+      if (!result.success) break;
     }
   }
 };