@emit-vision/sdk-js 0.4.1 → 0.4.3

package/README.md

@@ -218,3 +218,7 @@ init({
 - Do not use `email` or `username` as the `evaluationKey` — use an opaque user ID or session ID.
 - Use the helper packages when they reduce boilerplate, but keep direct browser
   SDK usage for the simplest client-side apps.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

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

@@ -1,4 +1,8 @@
 // src/flag-eval.ts
+function cacheKeyFor(env, opts) {
+  const keys = opts.flagKeys?.length ? [...opts.flagKeys].sort().join(",") : "*";
+  return `${env}:${opts.evaluationKey}:${keys}`;
+}
 var FlagEvaluator = class {
   constructor(cfg, onFlagsLoaded, captureExposure2, debug) {
     this.cfg = cfg;
@@ -14,7 +18,7 @@ var FlagEvaluator = class {
   async evaluateFlags(opts) {
     const env = opts.environment ?? "";
     const ttl = opts.ttlMs ?? this.cfg.ttlMs;
-    const key = `${env}:${opts.evaluationKey}`;
+    const key = cacheKeyFor(env, opts);
     const cached = this.cache.get(key);
     if (cached && Date.now() < cached.expiresAt) {
       this.debug("flag eval cache hit", { key });
@@ -24,7 +28,9 @@ var FlagEvaluator = class {
   }
   async getFlag(flagKey, fallback, opts) {
     try {
-      const flags = await this.evaluateFlags(opts);
+      const flags = await this.evaluateFlags(
+        opts.flagKeys?.length ? opts : { ...opts, flagKeys: [flagKey] }
+      );
       const value = flags[flagKey];
       return value !== void 0 ? value : fallback;
     } catch {
@@ -34,7 +40,7 @@ var FlagEvaluator = class {
   async refreshFlags(opts) {
     const env = opts.environment ?? "";
     const ttl = opts.ttlMs ?? this.cfg.ttlMs;
-    const key = `${env}:${opts.evaluationKey}`;
+    const key = cacheKeyFor(env, opts);
     this.cache.delete(key);
     return this.fetchAndCacheFlags(opts, env, ttl, key);
   }
@@ -157,6 +163,15 @@ function resolveAutoCapture(options) {
   };
 }
 
+// src/compress.ts
+var COMPRESS_THRESHOLD_BYTES = 8 * 1024;
+async function gzipBatchBody(body) {
+  if (typeof CompressionStream !== "function") return null;
+  const stream = new Blob([body]).stream().pipeThrough(new CompressionStream("gzip"));
+  const buffer = await new Response(stream).arrayBuffer();
+  return new Uint8Array(buffer);
+}
+
 // src/client-helpers.ts
 var SDK_NAME = "emit-vision-js";
 var SDK_VERSION = "0.4.0";
@@ -276,15 +291,51 @@ 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 body = buildBatchBody(chunk);
+  const compressed = byteLength(body) >= COMPRESS_THRESHOLD_BYTES ? await gzipBatchBody(body) : null;
   const response = await fetchImpl(`${endpoint}/v1/batch`, {
     method: "POST",
-    headers: { "content-type": "application/json", "x-emit-api-key": apiKey },
-    body: buildBatchBody(chunk),
-    keepalive: true
+    headers: {
+      "content-type": "application/json",
+      "x-emit-api-key": apiKey,
+      ...compressed ? { "content-encoding": "gzip" } : {}
+    },
+    body: compressed ?? body,
+    // keepalive lets a flush survive page unload, but browsers cap keepalive
+    // request bytes at ~64 KB total per page — a compressed send can be far
+    // bigger than that, so it skips keepalive and relies on the queue/retry
+    // path instead. Only the small, uncompressed path keeps the guarantee.
+    ...compressed ? {} : { 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 body2 = await response.json();
+      if (body2 && typeof body2.message === "string") serverMessage = body2.message;
+    } catch {
+    }
+    throw new FlushHttpError(
+      response.status,
+      Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0,
+      serverMessage
+    );
   }
 }
 
@@ -307,10 +358,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 +407,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 +496,9 @@ var FlushManager = class {
   timer;
   flushScheduled = false;
   retry;
+  storageKey;
+  consentGiven;
+  authFailureCount = 0;
   enqueue(payload) {
     if (this.retry.isDisabled()) return;
     const {
@@ -407,8 +537,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 +595,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 +656,7 @@ var FlushManager = class {
       return;
     }
     this.queue.unshift(...batch);
+    this.persistNow();
     const base = {
       restoredCount: batch.length,
       consecutiveFailures: result.consecutiveFailures,
@@ -489,6 +670,7 @@ var FlushManager = class {
     } else {
       debugLog("flush failed", this.options, {
         status: detail.status,
+        serverMessage: detail.serverMessage,
         ...base
       });
     }
@@ -608,9 +790,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 +831,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 +852,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 +892,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 +956,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 +981,7 @@ var EmitVisionClient = class {
       this.featureFlags,
       this.tags,
       this.options,
-      opts
+      { groupId: this.groupId, ...opts }
     );
   }
 };
@@ -809,6 +1041,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 +1077,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.3",
   "description": "Browser SDK for self-hosted emit-vision analytics and error tracking.",
   "private": false,
   "license": "MIT",
@@ -34,6 +34,19 @@
     }
   },
   "scripts": {
-    "build": "tsup --config tsup.config.ts"
+    "build": "tsup --config tsup.config.ts",
+    "size": "size-limit",
+    "prepack": "pnpm run build"
+  },
+  "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"
   }
-}
+}