@emit-vision/sdk-js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emit Vision
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# @emit-vision/sdk-js
+
+Browser SDK for Emit Vision, the self-hostable analytics and error tracking stack in this repo.
+
+For a full local walkthrough, see [docs/sdk-guide.md](../../docs/sdk-guide.md).
+
+## Installation
+
+```bash
+npm install @emit-vision/sdk-js
+```
+
+To consume the package from another local project before publishing:
+
+```bash
+pnpm nx run sdk-js:build
+cd packages/sdk-js
+pnpm pack
+```
+
+Then install the generated tarball:
+
+```bash
+npm install /absolute/path/to/emit-vision/packages/sdk-js/emit-vision-sdk-js-0.1.0.tgz
+```
+
+## Quick Start
+
+```ts
+import { init, captureEvent } from "@emit-vision/sdk-js";
+
+init({
+  dsn: "http://evk_local_development_seed_key_000000000000@localhost:4301/v1",
+  environment: "development",
+  release: "web@1.0.0",
+  autoCapture: {
+    errors: true,
+    unhandledRejections: true,
+  },
+});
+
+captureEvent("user_signed_up", { plan: "free" });
+```
+
+## When to Use This Package
+
+Use `@emit-vision/sdk-js` directly when your app is already client-side and you
+want the thinnest possible integration path.
+
+Good fits include:
+
+- Vanilla TypeScript or JavaScript browser apps
+- Vite or other framework-agnostic frontend bundles
+- Apps that want full control over when `init()`, `captureEvent()`, and
+  `flush()` run
+
+If you are in React or Next.js, the helper packages wrap this SDK without
+changing the ingest contract:
+
+- `@emit-vision/sdk-react` for provider and hook ergonomics in React trees
+- `@emit-vision/sdk-next` for app-router projects that want a client provider
+  with server-side config composition
+
+Those helpers are convenience layers, not alternate transports. The same
+browser-only privacy and safety guidance still applies.
+
+## API Reference
+
+### `init(options: EmitVisionOptions): void`
+
+Initializes the SDK. Call it once, as early as possible.
+
+| Option              | Type                                                  | Default                                       | Description                                                                |
+| ------------------- | ----------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------- | ------ | --- | ---------------------------------------------------------- |
+| `dsn`               | `string`                                              | —                                             | Local DSN in the form `http://<api-key>@localhost:4301/v1`                 |
+| `apiKey`            | `string`                                              | —                                             | Explicit API key if you do not want to use a DSN                           |
+| `endpoint`          | `string`                                              | `http://localhost:4301`                       | Explicit ingest API base URL                                               |
+| `environment`       | `string`                                              | —                                             | Environment label such as `development` or `production`                    |
+| `release`           | `string`                                              | —                                             | Release or git SHA attached to outgoing events                             |
+| `sessionId`         | `string`                                              | —                                             | Session identifier attached to future events                               |
+| `deployment`        | `{ deploymentId?: string; buildId?: string }`         | —                                             | Optional deployment metadata attached to outgoing events                   |
+| `featureFlags`      | `Record<string, string                                | number                                        | boolean                                                                    | null>` | —   | Optional feature-flag snapshot attached to outgoing events |
+| `autoCapture`       | `{ errors?: boolean; unhandledRejections?: boolean }` | `{ errors: true, unhandledRejections: true }` | Controls automatic browser error capture                                   |
+| `autoCaptureErrors` | `boolean`                                             | `true`                                        | Backward-compatible alias that enables or disables both auto-capture hooks |
+| `debug`             | `boolean`                                             | `false`                                       | Emits SDK lifecycle messages to `console.debug`                            |
+| `flushIntervalMs`   | `number`                                              | `5000`                                        | Automatic flush cadence in milliseconds                                    |
+| `batchSize`         | `number`                                              | `20`                                          | Queue size that triggers an immediate flush                                |
+| `flagEvalTtlMs`     | `number`                                              | `60000`                                       | Default TTL (ms) for the in-memory flag evaluation cache                   |
+
+### `captureEvent(name: string, properties?, options?): void`
+
+```ts
+captureEvent("checkout_completed", { value: 99.99, currency: "USD" });
+```
+
+### `captureError(error: unknown, options?): void`
+
+```ts
+captureError(new Error("Payment failed"), {
+  context: { orderId: "123" },
+});
+```
+
+### `identify(userId: string, traits?): void`
+
+### `identify(user: EmitVisionUser): void`
+
+```ts
+identify("user_123", {
+  email: "user@example.com",
+  username: "jane",
+});
+```
+
+### `setContext(context: Record<string, unknown>): void`
+
+```ts
+setContext({ page: "/checkout", experiment: "variant_b" });
+```
+
+### `setDeploymentContext(context: { deploymentId?: string; buildId?: string }): void`
+
+```ts
+setDeploymentContext({ deploymentId: "deploy_123", buildId: "build_456" });
+```
+
+### `setFeatureFlags(flags: Record<string, string | number | boolean | null>): void`
+
+```ts
+setFeatureFlags({ newCheckout: true, pricingVariant: "control" });
+```
+
+### `setTags(tags: Record<string, string>): void`
+
+```ts
+setTags({ team: "payments", feature: "checkout" });
+```
+
+### `flush(): Promise<void>`
+
+```ts
+await flush();
+```
+
+## Feature Flag Evaluation
+
+The SDK can fetch and evaluate feature flags from your Emit Vision project. Evaluated
+variants are automatically merged into the telemetry context so that every subsequent
+`captureEvent` or `captureError` call includes the active flag assignments.
+
+```ts
+import {
+  init,
+  evaluateFlags,
+  getFlag,
+  refreshFlags,
+} from "@emit-vision/sdk-js";
+
+init({
+  dsn: "http://evk_local_development_seed_key_000000000000@localhost:4301/v1",
+  environment: "production",
+});
+
+// Fetch all active flags for a user. Pass evaluationKey explicitly —
+// the SDK never reads email or username automatically.
+const flags = await evaluateFlags({ evaluationKey: "user_abc123" });
+// flags → { "new-checkout": true, "pricing-variant": "control", ... }
+
+// Fetch a single flag with a typed fallback.
+const showNewCheckout = await getFlag("new-checkout", false, {
+  evaluationKey: "user_abc123",
+});
+
+// Force a fresh fetch (bypass cache) after a flag change.
+await refreshFlags({ evaluationKey: "user_abc123" });
+```
+
+### `evaluateFlags(options: FlagEvaluationOptions): Promise<FeatureFlagsContext>`
+
+Fetches all active flags for the given evaluation key. Results are cached in memory
+for `flagEvalTtlMs` milliseconds (default: `60 000`). Network failures return an empty
+object without throwing.
+
+### `getFlag<T>(flagKey, fallback, options): Promise<T>`
+
+Returns the value for a single flag. Returns `fallback` when the flag is absent or when
+the network is unavailable. Never throws.
+
+### `refreshFlags(options: FlagEvaluationOptions): Promise<FeatureFlagsContext>`
+
+Bypasses the in-memory cache and performs a fresh fetch. Useful immediately after a
+flag change in the dashboard.
+
+### `FlagEvaluationOptions`
+
+| Option          | Type       | Required | Description                                                                 |
+| --------------- | ---------- | -------- | --------------------------------------------------------------------------- |
+| `evaluationKey` | `string`   | Yes      | Opaque key used to bucket the caller (e.g. user ID, device ID, session ID). |
+| `environment`   | `string`   | No       | Overrides the environment set at `init` time for this request.              |
+| `ttlMs`         | `number`   | No       | Per-call TTL override in milliseconds.                                      |
+| `flagKeys`      | `string[]` | No       | Limit evaluation to specific flag keys. Omit to evaluate all active flags.  |
+
+Set the default cache TTL at init time with the `flagEvalTtlMs` option (default: `60 000`).
+
+```ts
+init({
+  dsn: "...",
+  flagEvalTtlMs: 30_000, // refresh evaluations every 30 s
+});
+```
+
+## Notes
+
+- Manual `captureError()` calls mark errors as handled.
+- Auto-captured `window.error` and `unhandledrejection` events are marked as unhandled.
+- The queue is in-memory only, so call `flush()` before critical navigations if you need immediate delivery.
+- Flag evaluations are cached in memory only — nothing is written to `localStorage`.
+- 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.

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+export type EmitVisionUser = {
+    id?: string;
+    email?: string;
+    username?: string;
+};
+export type EmitVisionTraits = Omit<EmitVisionUser, "id">;
+export type DeploymentContext = {
+    deploymentId?: string;
+    buildId?: string;
+};
+export type FeatureFlagsContext = Record<string, string | number | boolean | null>;
+export type FlagEvaluationOptions = {
+    /** Opaque key used to bucket the caller. Must be provided explicitly — the SDK never reads email or username automatically. */
+    evaluationKey: string;
+    /** Overrides the environment set at init time for this evaluation request. */
+    environment?: string;
+    /** How long (ms) to cache this result. Defaults to the `flagEvalTtlMs` option set at init (default: 60 000). */
+    ttlMs?: number;
+    /** Limit evaluation to specific flag keys. Omit to evaluate all active flags. */
+    flagKeys?: string[];
+};
+export type AutoCaptureOptions = {
+    errors?: boolean;
+    unhandledRejections?: boolean;
+    /** Automatically fire a `$flag_exposure` event for each flag after evaluation. Default: true. */
+    flagExposures?: boolean;
+};
+export type CaptureOptions = {
+    eventId?: string;
+    timestamp?: string;
+    environment?: string;
+    release?: string;
+    sessionId?: string;
+    user?: EmitVisionUser;
+    context?: Record<string, unknown>;
+    deployment?: DeploymentContext;
+    featureFlags?: FeatureFlagsContext;
+    tags?: Record<string, string>;
+};
+export type EmitVisionOptions = {
+    apiKey?: string;
+    dsn?: string;
+    endpoint?: string;
+    environment?: string;
+    release?: string;
+    sessionId?: string;
+    label?: string;
+    deployment?: DeploymentContext;
+    featureFlags?: FeatureFlagsContext;
+    autoCapture?: AutoCaptureOptions;
+    autoCaptureErrors?: boolean;
+    debug?: boolean;
+    flushOnCapture?: boolean;
+    flushIntervalMs?: number;
+    batchSize?: number;
+    fetchImpl?: typeof fetch;
+    /** TTL in milliseconds for in-memory flag evaluation cache. Default: 60 000 (1 minute). */
+    flagEvalTtlMs?: number;
+};
+type RequiredEmitVisionOptions = Required<Pick<EmitVisionOptions, "apiKey" | "endpoint" | "flushIntervalMs" | "batchSize" | "fetchImpl" | "flushOnCapture" | "flagEvalTtlMs">> & Pick<EmitVisionOptions, "environment" | "release" | "sessionId" | "label" | "deployment" | "featureFlags" | "debug"> & {
+    autoCapture: Required<AutoCaptureOptions> & {
+        flagExposures: boolean;
+    };
+};
+declare class EmitVisionClient {
+    private readonly options;
+    private queue;
+    private user;
+    private context;
+    private deployment;
+    private featureFlags;
+    private tags;
+    private timer;
+    private flushScheduled;
+    private readonly fetchImpl;
+    private readonly flagCache;
+    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;
+    setContext(context: Record<string, unknown>): void;
+    setDeploymentContext(context: DeploymentContext): void;
+    setFeatureFlags(featureFlags: FeatureFlagsContext): void;
+    /**
+     * Fetch and evaluate all active flags for the given evaluation key.
+     * Results are cached for `ttlMs` (defaults to `flagEvalTtlMs` from init options).
+     * On network failure returns an empty object and does not throw.
+     * Evaluated variants are automatically merged into the SDK's feature-flag context.
+     */
+    evaluateFlags(opts: FlagEvaluationOptions): Promise<FeatureFlagsContext>;
+    /**
+     * Return a single flag's value, evaluated for the given key.
+     * Returns `fallback` on network failure or when the flag is not found — never throws.
+     */
+    getFlag<T extends string | number | boolean | null>(flagKey: string, fallback: T, opts: FlagEvaluationOptions): Promise<T>;
+    /**
+     * Bypass the cache and re-fetch evaluations for the given key.
+     * Useful after a flag change in the dashboard that should apply immediately.
+     */
+    refreshFlags(opts: FlagEvaluationOptions): Promise<FeatureFlagsContext>;
+    captureExposure(flagKey: string, variantKey: string, variantValue?: string | number | boolean | null, reason?: string, environment?: string): void;
+    private fetchAndCacheFlags;
+    setTags(tags: Record<string, string>): void;
+    flush(): Promise<void>;
+    close(): void;
+    private enqueue;
+    private scheduleFlush;
+    private withDefaults;
+    private mergeDeployment;
+    private mergeFeatureFlags;
+    private readonly handleWindowError;
+    private readonly handleUnhandledRejection;
+    private debug;
+}
+export declare function init(options: EmitVisionOptions): EmitVisionClient;
+export declare function captureEvent(name: string, properties?: Record<string, unknown>, options?: CaptureOptions): void;
+export declare function captureError(error: unknown, options?: CaptureOptions): void;
+export declare function identify(user: EmitVisionUser): void;
+export declare function identify(userId: string, traits?: EmitVisionTraits): void;
+export declare function setContext(context: Record<string, unknown>): void;
+export declare function setDeploymentContext(context: DeploymentContext): void;
+export declare function setFeatureFlags(featureFlags: FeatureFlagsContext): void;
+export declare function setTags(tags: Record<string, string>): void;
+export declare function flush(): Promise<void>;
+export declare function evaluateFlags(options: FlagEvaluationOptions): Promise<FeatureFlagsContext>;
+export declare function getFlag<T extends string | number | boolean | null>(flagKey: string, fallback: T, options: FlagEvaluationOptions): Promise<T>;
+export declare function refreshFlags(options: FlagEvaluationOptions): Promise<FeatureFlagsContext>;
+export declare function captureExposure(flagKey: string, variantKey: string, variantValue?: string | number | boolean | null, reason?: string, environment?: string): void;
+export {};

package/dist/index.js

@@ -0,0 +1,462 @@
+const SDK_NAME = "emit-vision-js";
+const SDK_VERSION = "0.1.0";
+class EmitVisionClient {
+    options;
+    queue = [];
+    user;
+    context = {};
+    deployment;
+    featureFlags = {};
+    tags = {};
+    timer;
+    flushScheduled = false;
+    fetchImpl;
+    flagCache = new Map();
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetchImpl;
+        this.deployment = options.deployment
+            ? { ...options.deployment }
+            : undefined;
+        this.featureFlags = options.featureFlags ? { ...options.featureFlags } : {};
+        this.timer = setInterval(() => {
+            if (this.queue.length === 0) {
+                return;
+            }
+            this.flush().catch((err) => this.debug("background flush error", { error: err }));
+        }, options.flushIntervalMs);
+        if (options.autoCapture.errors && typeof window !== "undefined") {
+            window.addEventListener("error", this.handleWindowError);
+        }
+        if (options.autoCapture.unhandledRejections &&
+            typeof window !== "undefined") {
+            window.addEventListener("unhandledrejection", this.handleUnhandledRejection);
+        }
+        this.debug("initialized", {
+            endpoint: options.endpoint,
+            environment: options.environment,
+            release: options.release,
+            autoCapture: options.autoCapture,
+            batchSize: options.batchSize,
+            flushIntervalMs: options.flushIntervalMs,
+            flushOnCapture: options.flushOnCapture,
+        });
+    }
+    captureEvent(name, properties, options = {}) {
+        this.debug("queue event", { name, properties, options });
+        this.enqueue({
+            type: "event",
+            name,
+            properties,
+            ...this.withDefaults(options),
+        });
+    }
+    captureError(error, options = {}) {
+        const serialized = serializeError(error);
+        this.debug("queue error", {
+            message: serialized.message,
+            handled: serialized.handled,
+            options,
+        });
+        this.enqueue({
+            type: "error",
+            name: "error",
+            error: serialized,
+            ...this.withDefaults(options),
+        });
+    }
+    identify(userIdOrUser, traits = {}) {
+        this.user =
+            typeof userIdOrUser === "string"
+                ? { id: userIdOrUser, ...traits }
+                : { ...userIdOrUser };
+        this.debug("identified user", this.user);
+    }
+    setContext(context) {
+        this.context = { ...this.context, ...context };
+        this.debug("updated context", this.context);
+    }
+    setDeploymentContext(context) {
+        this.deployment =
+            Object.keys(context).length > 0 ? { ...context } : undefined;
+        this.debug("updated deployment context", this.deployment);
+    }
+    setFeatureFlags(featureFlags) {
+        this.featureFlags = { ...featureFlags };
+        this.debug("updated feature flags", this.featureFlags);
+    }
+    /**
+     * Fetch and evaluate all active flags for the given evaluation key.
+     * Results are cached for `ttlMs` (defaults to `flagEvalTtlMs` from init options).
+     * On network failure returns an empty object and does not throw.
+     * Evaluated variants are automatically merged into the SDK's feature-flag context.
+     */
+    async evaluateFlags(opts) {
+        const env = opts.environment ?? this.options.environment ?? "";
+        const ttl = opts.ttlMs ?? this.options.flagEvalTtlMs;
+        const key = `${env}:${opts.evaluationKey}`;
+        const cached = this.flagCache.get(key);
+        if (cached && Date.now() < cached.expiresAt) {
+            this.debug("flag eval cache hit", { key });
+            return cached.flags;
+        }
+        return this.fetchAndCacheFlags(opts, env, ttl, key);
+    }
+    /**
+     * Return a single flag's value, evaluated for the given key.
+     * Returns `fallback` on network failure or when the flag is not found — never throws.
+     */
+    async getFlag(flagKey, fallback, opts) {
+        try {
+            const flags = await this.evaluateFlags(opts);
+            const value = flags[flagKey];
+            return (value !== undefined ? value : fallback);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    /**
+     * Bypass the cache and re-fetch evaluations for the given key.
+     * Useful after a flag change in the dashboard that should apply immediately.
+     */
+    async refreshFlags(opts) {
+        const env = opts.environment ?? this.options.environment ?? "";
+        const ttl = opts.ttlMs ?? this.options.flagEvalTtlMs;
+        const key = `${env}:${opts.evaluationKey}`;
+        this.flagCache.delete(key);
+        return this.fetchAndCacheFlags(opts, env, ttl, key);
+    }
+    captureExposure(flagKey, variantKey, variantValue, reason, environment) {
+        this.captureEvent("$flag_exposure", {
+            flagKey,
+            variantKey,
+            ...(variantValue !== undefined ? { variantValue } : {}),
+            ...(reason ? { reason } : {}),
+            environment: environment ?? this.options.environment,
+        });
+    }
+    async fetchAndCacheFlags(opts, env, ttl, cacheKey) {
+        let flags = {};
+        let evaluations = {};
+        try {
+            const body = {
+                environment: env,
+                userKey: opts.evaluationKey,
+            };
+            if (opts.flagKeys && opts.flagKeys.length > 0) {
+                body.flagKeys = opts.flagKeys;
+            }
+            const response = await this.fetchImpl(`${this.options.endpoint}/v1/flags/evaluate`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-emit-api-key": this.options.apiKey,
+                },
+                body: JSON.stringify(body),
+            });
+            if (response.ok) {
+                const data = (await response.json());
+                evaluations = data.evaluations;
+                flags = Object.fromEntries(Object.entries(evaluations).map(([k, v]) => [k, v.variantValue]));
+                this.debug("flag eval complete", { count: Object.keys(flags).length });
+            }
+            else {
+                this.debug("flag eval response error", { status: response.status });
+            }
+        }
+        catch (err) {
+            this.debug("flag eval network error", { error: err });
+            // Return empty flags on network error — never throw to callers
+        }
+        this.flagCache.set(cacheKey, { flags, expiresAt: Date.now() + ttl });
+        // Merge evaluated variants into the existing feature-flag context so that
+        // subsequent captureEvent / captureError calls include them automatically.
+        this.featureFlags = { ...this.featureFlags, ...flags };
+        if (this.options.autoCapture.flagExposures) {
+            for (const [flagKey, entry] of Object.entries(evaluations)) {
+                this.captureExposure(flagKey, entry.variantKey, entry.variantValue, entry.reason, env);
+            }
+        }
+        return flags;
+    }
+    setTags(tags) {
+        this.tags = { ...this.tags, ...tags };
+        this.debug("updated tags", this.tags);
+    }
+    async flush() {
+        const batch = this.queue.splice(0, this.options.batchSize);
+        if (batch.length === 0) {
+            return;
+        }
+        this.debug("flushing batch", { count: batch.length });
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.options.endpoint}/v1/batch`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-emit-api-key": this.options.apiKey,
+                },
+                body: JSON.stringify({
+                    events: batch.map((item) => ({
+                        ...item,
+                        sdk: { name: SDK_NAME, version: SDK_VERSION },
+                    })),
+                }),
+                keepalive: true,
+            });
+        }
+        catch (err) {
+            this.queue.unshift(...batch);
+            this.debug("flush network error", {
+                error: err,
+                restoredCount: batch.length,
+            });
+            throw err;
+        }
+        if (!response.ok) {
+            this.queue.unshift(...batch);
+            this.debug("flush failed", {
+                status: response.status,
+                restoredCount: batch.length,
+            });
+            throw new Error(`emit-vision flush failed with ${response.status}`);
+        }
+        this.debug("flush complete", { count: batch.length });
+        if (this.options.flushOnCapture && this.queue.length > 0) {
+            this.scheduleFlush();
+        }
+    }
+    close() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (typeof window !== "undefined" && this.options.autoCapture.errors) {
+            window.removeEventListener("error", this.handleWindowError);
+        }
+        if (typeof window !== "undefined" &&
+            this.options.autoCapture.unhandledRejections) {
+            window.removeEventListener("unhandledrejection", this.handleUnhandledRejection);
+        }
+        this.debug("closed client");
+    }
+    enqueue(payload) {
+        this.queue.push(payload);
+        this.debug("queued payload", {
+            type: payload.type,
+            name: payload.name,
+            queueSize: this.queue.length,
+            flushOnCapture: this.options.flushOnCapture,
+            batchSize: this.options.batchSize,
+        });
+        if (this.options.flushOnCapture) {
+            this.debug("capture flush scheduled", {
+                queueSize: this.queue.length,
+            });
+            this.flush().catch((err) => this.debug("capture flush error", { error: err }));
+            return;
+        }
+        if (this.queue.length >= this.options.batchSize) {
+            this.flush().catch((err) => this.debug("batch flush error", { error: err }));
+        }
+    }
+    scheduleFlush() {
+        if (this.flushScheduled) {
+            return;
+        }
+        this.flushScheduled = true;
+        queueMicrotask(() => {
+            this.flushScheduled = false;
+            if (this.queue.length === 0) {
+                return;
+            }
+            this.flush().catch((err) => this.debug("scheduled flush error", { error: err }));
+        });
+    }
+    withDefaults(options) {
+        const { context, deployment, featureFlags, tags, user, environment, release, sessionId, ...rest } = options;
+        return {
+            ...rest,
+            environment: environment ?? this.options.environment,
+            release: release ?? this.options.release,
+            sessionId: sessionId ?? this.options.sessionId,
+            user: user ?? this.user,
+            context: Object.keys(this.context).length
+                ? { ...this.context, ...context }
+                : context,
+            deployment: this.mergeDeployment(deployment),
+            featureFlags: this.mergeFeatureFlags(featureFlags),
+            tags: Object.keys(this.tags).length ? { ...this.tags, ...tags } : tags,
+        };
+    }
+    mergeDeployment(deployment) {
+        const merged = {
+            ...(this.deployment ?? {}),
+            ...(deployment ?? {}),
+        };
+        return Object.keys(merged).length > 0 ? merged : undefined;
+    }
+    mergeFeatureFlags(featureFlags) {
+        const merged = {
+            ...this.featureFlags,
+            ...(featureFlags ?? {}),
+        };
+        return Object.keys(merged).length > 0 ? merged : undefined;
+    }
+    handleWindowError = (event) => {
+        const serialized = serializeError(event.error ?? event.message);
+        this.debug("auto-captured window error", {
+            message: serialized.message,
+        });
+        this.enqueue({
+            type: "error",
+            name: "error",
+            error: { ...serialized, handled: false },
+            ...this.withDefaults({ context: { source: "window.error" } }),
+        });
+    };
+    handleUnhandledRejection = (event) => {
+        const serialized = serializeError(event.reason);
+        this.debug("auto-captured rejection", {
+            message: serialized.message,
+        });
+        this.enqueue({
+            type: "error",
+            name: "error",
+            error: { ...serialized, handled: false },
+            ...this.withDefaults({
+                context: { source: "window.unhandledrejection" },
+            }),
+        });
+    };
+    debug(message, payload) {
+        if (!this.options.debug || typeof console.debug !== "function") {
+            return;
+        }
+        const prefix = this.options.label
+            ? `[emit-vision:${this.options.label}]`
+            : "[emit-vision]";
+        if (payload === undefined) {
+            console.debug(prefix, message);
+            return;
+        }
+        console.debug(prefix, message, payload);
+    }
+}
+let client;
+export function init(options) {
+    const transport = resolveTransport(options);
+    const autoCapture = resolveAutoCapture(options);
+    client?.close();
+    client = new EmitVisionClient({
+        ...options,
+        flushIntervalMs: options.flushIntervalMs ?? 5000,
+        batchSize: options.batchSize ?? 20,
+        debug: options.debug ?? false,
+        fetchImpl: options.fetchImpl ?? globalThis.fetch.bind(globalThis),
+        flushOnCapture: options.flushOnCapture ?? false,
+        flagEvalTtlMs: options.flagEvalTtlMs ?? 60_000,
+        apiKey: transport.apiKey,
+        endpoint: transport.endpoint ?? options.endpoint ?? "http://localhost:4301",
+        autoCapture,
+    });
+    return client;
+}
+export function captureEvent(name, properties, options) {
+    requireClient().captureEvent(name, properties, options);
+}
+export function captureError(error, options) {
+    requireClient().captureError(error, options);
+}
+export function identify(userIdOrUser, traits) {
+    requireClient().identify(userIdOrUser, traits);
+}
+export function setContext(context) {
+    requireClient().setContext(context);
+}
+export function setDeploymentContext(context) {
+    requireClient().setDeploymentContext(context);
+}
+export function setFeatureFlags(featureFlags) {
+    requireClient().setFeatureFlags(featureFlags);
+}
+export function setTags(tags) {
+    requireClient().setTags(tags);
+}
+export async function flush() {
+    await requireClient().flush();
+}
+export async function evaluateFlags(options) {
+    return requireClient().evaluateFlags(options);
+}
+export async function getFlag(flagKey, fallback, options) {
+    return requireClient().getFlag(flagKey, fallback, options);
+}
+export async function refreshFlags(options) {
+    return requireClient().refreshFlags(options);
+}
+export function captureExposure(flagKey, variantKey, variantValue, reason, environment) {
+    requireClient().captureExposure(flagKey, variantKey, variantValue, reason, environment);
+}
+function requireClient() {
+    if (!client) {
+        throw new Error("emit-vision SDK has not been initialized");
+    }
+    return client;
+}
+function resolveTransport(options) {
+    const dsn = options.dsn ? parseDsn(options.dsn) : null;
+    const apiKey = options.apiKey ?? dsn?.apiKey;
+    if (!apiKey) {
+        throw new Error("emit-vision init requires either apiKey or dsn");
+    }
+    return {
+        apiKey,
+        endpoint: stripTrailingSlash(options.endpoint ?? dsn?.endpoint),
+    };
+}
+function resolveAutoCapture(options) {
+    const legacyDefault = options.autoCaptureErrors === undefined ? true : options.autoCaptureErrors;
+    return {
+        errors: options.autoCapture?.errors ?? legacyDefault,
+        unhandledRejections: options.autoCapture?.unhandledRejections ?? legacyDefault,
+        flagExposures: options.autoCapture?.flagExposures ?? true,
+    };
+}
+function parseDsn(dsn) {
+    const parsed = new URL(dsn);
+    const apiKey = decodeURIComponent(parsed.username);
+    if (!apiKey) {
+        throw new Error("emit-vision dsn must include the API key before the @");
+    }
+    const pathname = stripTrailingSlash(parsed.pathname) ?? "";
+    const endpointPath = pathname.endsWith("/v1")
+        ? pathname.slice(0, -"/v1".length)
+        : pathname;
+    return {
+        apiKey,
+        endpoint: stripTrailingSlash(`${parsed.origin}${endpointPath}`),
+    };
+}
+function stripTrailingSlash(value) {
+    if (!value) {
+        return value;
+    }
+    return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+function serializeError(error) {
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            name: error.name,
+            stack: error.stack,
+            handled: true,
+        };
+    }
+    return {
+        message: typeof error === "string" ? error : JSON.stringify(error),
+        handled: true,
+    };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@emit-vision/sdk-js",
+  "version": "0.1.0",
+  "description": "Browser SDK for self-hosted emit-vision analytics and error tracking.",
+  "private": false,
+  "license": "MIT",
+  "author": "Emit Vision",
+  "homepage": "https://github.com/develemit/emit-vision/tree/main/packages/sdk-js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/develemit/emit-vision.git",
+    "directory": "packages/sdk-js"
+  },
+  "bugs": {
+    "url": "https://github.com/develemit/emit-vision/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  }
+}