@emit-vision/sdk-js 0.4.1 → 0.4.2

package/dist/index.d.ts

@@ -38,6 +38,7 @@ type CaptureOptions = {
     release?: string;
     sessionId?: string;
     user?: EmitVisionUser;
+    groupId?: string;
     context?: Record<string, unknown>;
     deployment?: DeploymentContext;
     featureFlags?: FeatureFlagsContext;
@@ -60,6 +61,10 @@ type EmitVisionOptions = {
     flushIntervalMs?: number;
     batchSize?: number;
     fetchImpl?: typeof fetch;
+    /** Project ID — passed through to the DevTools debug channel so the extension can build dashboard deep links. Not required for event capture. */
+    projectId?: string;
+    /** Initial group ID to associate with all events. Can be overridden per-event or updated via `group()`. */
+    groupId?: string;
     /** TTL in milliseconds for in-memory flag evaluation cache. Default: 60 000 (1 minute). */
     flagEvalTtlMs?: number;
     /** Initial delay (ms) before retrying after a flush failure. Default: 1000. Doubles each consecutive failure up to {@link retryBackoffMaxMs}. Set to 0 to retry immediately on every tick. */
@@ -68,17 +73,72 @@ type EmitVisionOptions = {
     retryBackoffMaxMs?: number;
     /** Disable the SDK after this many consecutive flush failures: the queue is dropped, future captures become no-ops, and a single warning is logged. Default: 20. Set to 0 to disable the cap and retry forever. */
     maxConsecutiveFlushFailures?: number;
+    /** When true, events are queued in memory but not sent until `consent()` is called. Default: false. */
+    consentRequired?: boolean;
+    /** Set to true when `consentRequired` is true but consent is already known at init time (e.g. read from a cookie server-side). Skips the consent gate. Default: false. */
+    consentGiven?: boolean;
 };
 type RequiredEmitVisionOptions = Required<Pick<EmitVisionOptions, "apiKey" | "endpoint" | "flushIntervalMs" | "batchSize" | "fetchImpl" | "flushOnCapture" | "flagEvalTtlMs" | "retryBackoffInitialMs" | "retryBackoffMaxMs" | "maxConsecutiveFlushFailures">> & Pick<EmitVisionOptions, "environment" | "release" | "sessionId" | "label" | "deployment" | "featureFlags" | "debug"> & {
     autoCapture: Required<AutoCaptureOptions> & {
         flagExposures: boolean;
         pageViews: boolean;
     };
+    projectId?: string;
+    groupId?: string;
+    consentRequired?: boolean;
+    consentGiven?: boolean;
+};
+
+type DevToolsMessage = {
+    type: "init";
+    payload: {
+        sdkVersion: string;
+        endpoint: string;
+        environment?: string;
+        release?: string;
+        sessionId: string;
+        autoCapture: AutoCaptureOptions;
+        projectId?: string;
+        consentRequired?: boolean;
+    };
+} | {
+    type: "event";
+    payload: {
+        name: string;
+        properties?: Record<string, unknown>;
+        eventId?: string;
+        timestamp?: string;
+        environment?: string;
+        sessionId?: string;
+    };
+} | {
+    type: "identify";
+    payload: {
+        userId?: string;
+        traits?: Record<string, unknown>;
+    };
+} | {
+    type: "flush";
+    payload: {
+        count: number;
+    };
+} | {
+    type: "error";
+    payload: {
+        message: string;
+    };
+} | {
+    type: "group";
+    payload: {
+        groupId: string;
+        traits?: Record<string, unknown>;
+    };
 };
 
 declare class EmitVisionClient {
     private readonly options;
     private user;
+    private groupId;
     private context;
     private deployment;
     private featureFlags;
@@ -86,10 +146,13 @@ declare class EmitVisionClient {
     private readonly flagEval;
     private readonly autoCapture;
     private readonly flusher;
+    private readonly persistOnHide;
+    private readonly persistOnHidden;
     constructor(options: RequiredEmitVisionOptions);
     captureEvent(name: string, properties?: Record<string, unknown>, options?: CaptureOptions): void;
     captureError(error: unknown, options?: CaptureOptions): void;
     identify(userIdOrUser: string | EmitVisionUser, traits?: EmitVisionTraits): void;
+    group(groupId: string, traits?: Record<string, unknown>): void;
     setContext(context: Record<string, unknown>): void;
     setDeploymentContext(context: DeploymentContext): void;
     setFeatureFlags(featureFlags: FeatureFlagsContext): void;
@@ -104,6 +167,7 @@ declare class EmitVisionClient {
     }, options?: CaptureOptions): void;
     captureExposure(flagKey: string, variantKey: string, variantValue?: string | number | boolean | null, reason?: string, environment?: string): void;
     setTags(tags: Record<string, string>): void;
+    consent(): Promise<void>;
     flush(): Promise<void>;
     close(): void;
     private withDefaults;
@@ -125,9 +189,11 @@ declare function setDeploymentContext(context: DeploymentContext): void;
 declare function setFeatureFlags(featureFlags: FeatureFlagsContext): void;
 declare function setTags(tags: Record<string, string>): void;
 declare function flush(): Promise<void>;
+declare function consent(): Promise<void>;
+declare function group(groupId: string, traits?: Record<string, unknown>): void;
 declare function evaluateFlags(options: FlagEvaluationOptions): Promise<FeatureFlagsContext>;
 declare function getFlag<T extends string | number | boolean | null>(flagKey: string, fallback: T, options: FlagEvaluationOptions): Promise<T>;
 declare function refreshFlags(options: FlagEvaluationOptions): Promise<FeatureFlagsContext>;
 declare function captureExposure(flagKey: string, variantKey: string, variantValue?: string | number | boolean | null, reason?: string, environment?: string): void;
 
-export { type AutoCaptureOptions, type CaptureOptions, type DeploymentContext, type EmitVisionOptions, type EmitVisionTraits, type EmitVisionUser, type FeatureFlagsContext, type FlagEvaluationOptions, captureError, captureEvent, captureExposure, captureFeedback, capturePageView, evaluateFlags, flush, getFlag, identify, init, refreshFlags, setContext, setDeploymentContext, setFeatureFlags, setTags };
+export { type AutoCaptureOptions, type CaptureOptions, type DeploymentContext, type DevToolsMessage, type EmitVisionOptions, type EmitVisionTraits, type EmitVisionUser, type FeatureFlagsContext, type FlagEvaluationOptions, captureError, captureEvent, captureExposure, captureFeedback, capturePageView, consent, evaluateFlags, flush, getFlag, group, identify, init, refreshFlags, setContext, setDeploymentContext, setFeatureFlags, setTags };

package/dist/index.js

@@ -276,6 +276,21 @@ function mergeFeatureFlagsFn(clientFlags, overrideFlags) {
 function buildFlushDisabledMessage(label, consecutiveFailures, dropped) {
   return `[emit-vision${label ? `:${label}` : ""}] disabled after ${consecutiveFailures} consecutive flush failures; dropping ${dropped} queued events. Re-init the SDK to resume.`;
 }
+function buildAuthDisabledMessage(label, status, dropped) {
+  return `[emit-vision${label ? `:${label}` : ""}] SDK disabled: received ${AUTH_FAILURE_CAP} consecutive ${status} responses from the ingest API. This usually means your DSN or API key is invalid \u2014 check the dsn or apiKey option passed to init(). Dropping ${dropped} queued events.`;
+}
+var AUTH_FAILURE_CAP = 3;
+var FlushHttpError = class extends Error {
+  constructor(status, retryAfterSeconds, serverMessage) {
+    super(`emit-vision flush failed with ${status}`);
+    this.status = status;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.serverMessage = serverMessage;
+  }
+  status;
+  retryAfterSeconds;
+  serverMessage;
+};
 async function executeHttpSend(chunk, endpoint, apiKey, fetchImpl) {
   const response = await fetchImpl(`${endpoint}/v1/batch`, {
     method: "POST",
@@ -284,7 +299,18 @@ async function executeHttpSend(chunk, endpoint, apiKey, fetchImpl) {
     keepalive: true
   });
   if (!response.ok) {
-    throw new Error(`emit-vision flush failed with ${response.status}`);
+    const retryAfter = Number(response.headers?.get?.("retry-after"));
+    let serverMessage;
+    try {
+      const body = await response.json();
+      if (body && typeof body.message === "string") serverMessage = body.message;
+    } catch {
+    }
+    throw new FlushHttpError(
+      response.status,
+      Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0,
+      serverMessage
+    );
   }
 }
 
@@ -307,10 +333,20 @@ var FlushRetryController = class {
     if (this.disabled) return Infinity;
     return Math.max(0, this.backoffUntil - now);
   }
+  forceDisable() {
+    this.disabled = true;
+    this.backoffUntil = 0;
+  }
   reset() {
     this.consecutiveFailures = 0;
     this.backoffUntil = 0;
   }
+  /** Push the next retry out to honor a server-sent Retry-After hint. Capped at 5 minutes; never shortens an existing backoff. */
+  applyRetryAfter(seconds, now = Date.now()) {
+    if (this.disabled || !Number.isFinite(seconds) || seconds <= 0) return;
+    const cappedMs = Math.min(seconds, 300) * 1e3;
+    this.backoffUntil = Math.max(this.backoffUntil, now + cappedMs);
+  }
   recordFailure(now = Date.now()) {
     this.consecutiveFailures += 1;
     if (this.opts.failureCap > 0 && this.consecutiveFailures >= this.opts.failureCap) {
@@ -346,11 +382,77 @@ var FlushRetryController = class {
   }
 };
 
+// src/persistence.ts
+var MAX_PERSISTED_EVENTS = 200;
+var MAX_PERSISTED_AGE_MS = 24 * 60 * 60 * 1e3;
+function persistenceKey(apiKey, projectId) {
+  return `emit-vision:queue:${projectId ?? "-"}:${apiKey.slice(0, 16)}`;
+}
+function getStorage() {
+  try {
+    if (typeof localStorage === "undefined") return null;
+    return localStorage;
+  } catch {
+    return null;
+  }
+}
+function persistQueue(key, queue) {
+  const storage = getStorage();
+  if (!storage || queue.length === 0) return;
+  const record = {
+    savedAt: Date.now(),
+    events: queue.slice(0, MAX_PERSISTED_EVENTS)
+  };
+  try {
+    storage.setItem(key, JSON.stringify(record));
+  } catch {
+  }
+}
+function restoreQueue(key, now = Date.now()) {
+  const storage = getStorage();
+  if (!storage) return [];
+  try {
+    const raw = storage.getItem(key);
+    storage.removeItem(key);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.savedAt !== "number" || !Array.isArray(parsed.events)) {
+      return [];
+    }
+    if (now - parsed.savedAt > MAX_PERSISTED_AGE_MS) return [];
+    return parsed.events.slice(0, MAX_PERSISTED_EVENTS);
+  } catch {
+    return [];
+  }
+}
+function clearPersistedQueue(key) {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    storage.removeItem(key);
+  } catch {
+  }
+}
+
+// src/devtools-channel.ts
+function dispatchDevToolsEvent(type, payload) {
+  if (typeof window === "undefined" || typeof window.dispatchEvent !== "function") {
+    return;
+  }
+  window.dispatchEvent(
+    new CustomEvent("__emitVisionDevTools", {
+      detail: { type, payload, timestamp: Date.now() }
+    })
+  );
+}
+
 // src/client-flush.ts
 var FlushManager = class {
   constructor(options, fetchImpl) {
     this.options = options;
     this.fetchImpl = fetchImpl;
+    this.consentGiven = !options.consentRequired || (options.consentGiven ?? false);
+    this.storageKey = persistenceKey(options.apiKey, options.projectId);
     this.retry = new FlushRetryController({
       initialMs: options.retryBackoffInitialMs,
       maxMs: options.retryBackoffMaxMs,
@@ -369,6 +471,9 @@ var FlushManager = class {
   timer;
   flushScheduled = false;
   retry;
+  storageKey;
+  consentGiven;
+  authFailureCount = 0;
   enqueue(payload) {
     if (this.retry.isDisabled()) return;
     const {
@@ -407,8 +512,27 @@ var FlushManager = class {
       );
     }
   }
+  giveConsent() {
+    this.consentGiven = true;
+    return this.flush();
+  }
+  /** Restore any queue persisted by a previous page load, prepending it so older events flush first. */
+  restorePersisted() {
+    const restored = restoreQueue(this.storageKey);
+    if (restored.length === 0) return;
+    this.queue.unshift(...restored);
+    debugLog("restored persisted queue", this.options, {
+      count: restored.length
+    });
+  }
+  /** Spill the current queue to localStorage (pagehide / tab hidden). No-op without consent. */
+  persistNow() {
+    if (!this.consentGiven || this.retry.isDisabled()) return;
+    persistQueue(this.storageKey, this.queue);
+  }
   async flush() {
     if (this.retry.isDisabled()) return;
+    if (!this.consentGiven) return;
     const batch = this.queue.splice(0, this.options.batchSize);
     if (batch.length === 0) return;
     debugLog("flushing batch", this.options, { count: batch.length });
@@ -446,19 +570,50 @@ var FlushManager = class {
         this.fetchImpl
       );
     } catch (err) {
-      const m = err instanceof Error ? /flush failed with (\d+)/.exec(err.message) : null;
       this.handleFlushFailure(
         chunk,
         tailCount,
-        m ? { reason: "status", status: Number(m[1]) } : { reason: "network", error: err }
+        err instanceof FlushHttpError ? {
+          reason: "status",
+          status: err.status,
+          retryAfterSeconds: err.retryAfterSeconds,
+          serverMessage: err.serverMessage
+        } : { reason: "network", error: err }
       );
       throw err;
     }
     this.retry.reset();
+    this.authFailureCount = 0;
+    clearPersistedQueue(this.storageKey);
     debugLog("flush complete", this.options, { count: chunk.length });
+    dispatchDevToolsEvent("flush", { count: chunk.length });
   }
   handleFlushFailure(batch, tailCount, detail) {
+    if (detail.reason === "status" && (detail.status === 401 || detail.status === 403)) {
+      this.authFailureCount += 1;
+      if (this.authFailureCount >= AUTH_FAILURE_CAP) {
+        const dropped = this.queue.length + batch.length + tailCount;
+        this.queue = [];
+        this.close();
+        this.retry.forceDisable();
+        const msg = buildAuthDisabledMessage(
+          this.options.label,
+          detail.status,
+          dropped
+        );
+        if (typeof console.warn === "function") console.warn(msg);
+        debugLog("disabled (auth)", this.options, {
+          status: detail.status,
+          authFailures: this.authFailureCount,
+          dropped
+        });
+        return;
+      }
+    }
     const result = this.retry.recordFailure();
+    if (detail.reason === "status" && (detail.status === 429 || detail.status === 503) && detail.retryAfterSeconds !== void 0) {
+      this.retry.applyRetryAfter(detail.retryAfterSeconds);
+    }
     if (result.justDisabled) {
       const dropped = this.queue.length + batch.length + tailCount;
       this.queue = [];
@@ -476,6 +631,7 @@ var FlushManager = class {
       return;
     }
     this.queue.unshift(...batch);
+    this.persistNow();
     const base = {
       restoredCount: batch.length,
       consecutiveFailures: result.consecutiveFailures,
@@ -489,6 +645,7 @@ var FlushManager = class {
     } else {
       debugLog("flush failed", this.options, {
         status: detail.status,
+        serverMessage: detail.serverMessage,
         ...base
       });
     }
@@ -608,9 +765,17 @@ var BrowserAutoCapture = class {
 var EmitVisionClient = class {
   constructor(options) {
     this.options = options;
+    this.groupId = options.groupId;
     this.deployment = options.deployment ? { ...options.deployment } : void 0;
     this.featureFlags = options.featureFlags ? { ...options.featureFlags } : {};
     this.flusher = new FlushManager(options, options.fetchImpl);
+    this.flusher.restorePersisted();
+    if (typeof window !== "undefined") {
+      window.addEventListener("pagehide", this.persistOnHide);
+    }
+    if (typeof document !== "undefined") {
+      document.addEventListener("visibilitychange", this.persistOnHidden);
+    }
     this.flagEval = new FlagEvaluator(
       {
         endpoint: options.endpoint,
@@ -641,9 +806,20 @@ var EmitVisionClient = class {
       flushIntervalMs: options.flushIntervalMs,
       flushOnCapture: options.flushOnCapture
     });
+    dispatchDevToolsEvent("init", {
+      sdkVersion: SDK_VERSION,
+      endpoint: options.endpoint,
+      environment: options.environment,
+      release: options.release,
+      sessionId: options.sessionId ?? "",
+      autoCapture: options.autoCapture,
+      projectId: options.projectId,
+      consentRequired: options.consentRequired
+    });
   }
   options;
   user;
+  groupId;
   context = {};
   deployment;
   featureFlags = {};
@@ -651,13 +827,28 @@ var EmitVisionClient = class {
   flagEval;
   autoCapture;
   flusher;
+  persistOnHide = () => this.flusher.persistNow();
+  persistOnHidden = () => {
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+      this.flusher.persistNow();
+    }
+  };
   captureEvent(name, properties, options = {}) {
+    const eventId = options.eventId ?? (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : void 0);
     debugLog("queue event", this.options, { name, properties, options });
     this.flusher.enqueue({
       type: "event",
       name,
       properties,
-      ...this.withDefaults(options)
+      ...this.withDefaults({ ...options, eventId })
+    });
+    dispatchDevToolsEvent("event", {
+      name,
+      properties,
+      eventId,
+      timestamp: options.timestamp,
+      environment: options.environment,
+      sessionId: options.sessionId
     });
   }
   captureError(error, options = {}) {
@@ -676,6 +867,13 @@ var EmitVisionClient = class {
   identify(userIdOrUser, traits = {}) {
     this.user = typeof userIdOrUser === "string" ? { id: userIdOrUser, ...traits } : { ...userIdOrUser };
     debugLog("identified user", this.options, this.user);
+    const { id, ...rest } = this.user;
+    dispatchDevToolsEvent("identify", { userId: id, traits: rest });
+  }
+  group(groupId, traits) {
+    this.groupId = groupId;
+    debugLog("set group", this.options, { groupId, traits });
+    dispatchDevToolsEvent("group", { groupId, traits });
   }
   setContext(context) {
     this.context = { ...this.context, ...context };
@@ -733,10 +931,19 @@ var EmitVisionClient = class {
     this.tags = { ...this.tags, ...tags };
     debugLog("updated tags", this.options, this.tags);
   }
+  consent() {
+    return this.flusher.giveConsent();
+  }
   flush() {
     return this.flusher.flush();
   }
   close() {
+    if (typeof window !== "undefined") {
+      window.removeEventListener("pagehide", this.persistOnHide);
+    }
+    if (typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.persistOnHidden);
+    }
     this.flusher.close();
     this.autoCapture.detach();
     debugLog("closed client", this.options);
@@ -749,7 +956,7 @@ var EmitVisionClient = class {
       this.featureFlags,
       this.tags,
       this.options,
-      opts
+      { groupId: this.groupId, ...opts }
     );
   }
 };
@@ -809,6 +1016,12 @@ function setTags(tags) {
 async function flush() {
   await requireClient().flush();
 }
+async function consent() {
+  await requireClient().consent();
+}
+function group(groupId, traits) {
+  requireClient().group(groupId, traits);
+}
 async function evaluateFlags(options) {
   return requireClient().evaluateFlags(options);
 }
@@ -839,9 +1052,11 @@ export {
   captureExposure,
   captureFeedback,
   capturePageView,
+  consent,
   evaluateFlags,
   flush,
   getFlag,
+  group,
   identify,
   init,
   refreshFlags,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emit-vision/sdk-js",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Browser SDK for self-hosted emit-vision analytics and error tracking.",
   "private": false,
   "license": "MIT",
@@ -33,7 +33,19 @@
       "default": "./dist/index.js"
     }
   },
+  "size-limit": [
+    {
+      "name": "@emit-vision/sdk-js (gzip)",
+      "path": "dist/index.js",
+      "limit": "9 kB"
+    }
+  ],
+  "devDependencies": {
+    "@size-limit/file": "^11.1.6",
+    "size-limit": "^11.1.6"
+  },
   "scripts": {
-    "build": "tsup --config tsup.config.ts"
+    "build": "tsup --config tsup.config.ts",
+    "size": "size-limit"
   }
 }