@clue-ai/browser-sdk 0.0.1

package/dist/transport/client.js

@@ -0,0 +1,267 @@
+import { mergeIngestUsageGovernorFeedback, parseGovernorFeedbackEnvelope, } from "../core/usage-governor";
+import { executeWithRetry, isRetryableStatus } from "./retry";
+export const CLUE_SDK_REQUEST_HEADER = "x-clue-sdk-request";
+export const CLUE_ENVIRONMENT_HEADER = "x-clue-environment";
+export const CLUE_SDK_VERSION_HEADER = "x-clue-sdk-version";
+export const CLUE_SOURCE_SCHEMA_VERSION_HEADER = "x-clue-source-schema-version";
+export const CLUE_SERVICE_KEY_HEADER = "x-clue-service-key";
+export const CLUE_BROWSER_TOKEN_HEADER = "x-clue-browser-token";
+class HttpStatusError extends Error {
+    constructor(status) {
+        super(`HTTP ${status}`);
+        this.status = status;
+    }
+}
+class IngestRejectedResponseError extends Error {
+    constructor(status, retryStrategy) {
+        super(`ingest rejected with retry strategy ${retryStrategy ?? "none"}`);
+        this.status = status;
+        this.retryStrategy = retryStrategy;
+    }
+}
+export class IngestClient {
+    constructor(options) {
+        this.endpoint = options.endpoint;
+        this.projectKey = options.projectKey;
+        this.environment = options.environment;
+        this.serviceKey = options.serviceKey ?? options.producerId;
+        this.producerId = options.producerId;
+        this.browserTokenProvider = options.browserTokenProvider ?? null;
+        this.sdkType = options.sdkType;
+        this.sdkVersion = options.sdkVersion;
+        this.schemaVersion = options.schemaVersion;
+        this.metrics = options.metrics ?? null;
+    }
+    async send(events, options = {}) {
+        if (events.length === 0) {
+            return {
+                ok: true,
+                status: null,
+                attempts: 0,
+                governor: null,
+                retryStrategy: null,
+            };
+        }
+        const maxPayloadBytes = Math.max(1024, options.maxPayloadBytes ?? Number.MAX_SAFE_INTEGER);
+        const metadata = options.metadata ?? this.createBatchEnvelopeMetadata();
+        const payload = this.stringifyPayload(events, metadata);
+        const browserToken = await this.resolveBrowserToken();
+        const beaconPayload = options.useBeacon && browserToken === null
+            ? this.stringifyPayload(events, metadata, {
+                includeCompatibilityRouting: true,
+            })
+            : null;
+        const payloadSize = new TextEncoder().encode(payload).byteLength;
+        this.metrics?.increment("payload_size_bytes", payloadSize);
+        if (payloadSize > maxPayloadBytes ||
+            (beaconPayload !== null &&
+                new TextEncoder().encode(beaconPayload).byteLength > maxPayloadBytes)) {
+            this.metrics?.increment("dropped_count", events.length);
+            this.metrics?.increment("send_failure_count");
+            this.metrics?.increment("transport_failed_count");
+            return {
+                ok: false,
+                status: null,
+                attempts: 0,
+                governor: null,
+                retryStrategy: null,
+            };
+        }
+        let attempts = 0;
+        let lastStatus = null;
+        let governor = null;
+        let retryStrategy = null;
+        if (beaconPayload !== null && this.trySendBeacon(beaconPayload)) {
+            this.metrics?.increment("sent_count", events.length);
+            return {
+                ok: true,
+                status: 202,
+                attempts: 1,
+                governor: null,
+                retryStrategy: null,
+            };
+        }
+        const result = await executeWithRetry(async () => {
+            const response = await fetch(this.endpoint, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-clue-project-key": this.projectKey,
+                    [CLUE_SERVICE_KEY_HEADER]: this.serviceKey,
+                    ...(browserToken
+                        ? { [CLUE_BROWSER_TOKEN_HEADER]: browserToken }
+                        : {}),
+                    [CLUE_SDK_REQUEST_HEADER]: this.sdkType,
+                    [CLUE_ENVIRONMENT_HEADER]: this.environment,
+                    [CLUE_SDK_VERSION_HEADER]: this.sdkVersion,
+                    [CLUE_SOURCE_SCHEMA_VERSION_HEADER]: String(this.schemaVersion),
+                },
+                body: payload,
+                keepalive: options.keepalive ?? options.useBeacon ?? false,
+                credentials: "omit",
+            });
+            if (!response.ok) {
+                throw new HttpStatusError(response.status);
+            }
+            const ingestResponse = await this.readIngestResponse(response);
+            if (ingestResponse.accepted === false) {
+                throw new IngestRejectedResponseError(response.status, ingestResponse.retryStrategy);
+            }
+            return {
+                status: response.status,
+                governor: ingestResponse.governor,
+                retryStrategy: ingestResponse.retryStrategy,
+            };
+        }, (error) => {
+            if (error instanceof IngestRejectedResponseError) {
+                return error.retryStrategy === "retry_same_batch";
+            }
+            if (error instanceof HttpStatusError) {
+                return isRetryableStatus(error.status);
+            }
+            return true;
+        });
+        attempts += result.attempts;
+        lastStatus =
+            typeof result.value?.status === "number"
+                ? result.value.status
+                : result.error instanceof IngestRejectedResponseError
+                    ? result.error.status
+                    : result.error instanceof HttpStatusError
+                        ? result.error.status
+                        : null;
+        governor = mergeIngestUsageGovernorFeedback(governor, result.value?.governor ?? null);
+        retryStrategy =
+            result.value?.retryStrategy ??
+                (result.error instanceof IngestRejectedResponseError
+                    ? result.error.retryStrategy
+                    : null);
+        if (result.attempts > 1) {
+            this.metrics?.increment("retry_count", result.attempts - 1);
+            this.metrics?.increment("transport_retry_count", result.attempts - 1);
+        }
+        if (!result.ok) {
+            this.metrics?.increment("send_failure_count");
+            this.metrics?.increment("transport_failed_count");
+            return {
+                ok: false,
+                status: lastStatus,
+                attempts,
+                governor,
+                retryStrategy,
+            };
+        }
+        this.metrics?.increment("sent_count", events.length);
+        return {
+            ok: true,
+            status: lastStatus,
+            attempts,
+            governor,
+            retryStrategy,
+        };
+    }
+    measurePayloadBytes(events, metadata = {
+        batch_id: "batch_00000000-0000-4000-8000-000000000000",
+        idempotency_key: "idem_00000000-0000-4000-8000-000000000000",
+        sent_at: "2026-01-01T00:00:00.000Z",
+    }) {
+        return new TextEncoder().encode(this.stringifyPayload(events, metadata))
+            .byteLength;
+    }
+    stringifyPayload(events, metadata, options = {}) {
+        return JSON.stringify({
+            ...(options.includeCompatibilityRouting
+                ? {
+                    project_key: this.projectKey,
+                    environment: this.environment,
+                }
+                : {}),
+            batch_id: metadata.batch_id,
+            idempotency_key: metadata.idempotency_key,
+            sent_at: metadata.sent_at,
+            source_type: "browser_sdk",
+            source_schema_version: String(this.schemaVersion),
+            producer_metadata: {
+                producer_id: this.producerId,
+                sdk_type: this.sdkType,
+                sdk_version: this.sdkVersion,
+            },
+            events: events.map((event) => this.withSourceEvidence(event)),
+        });
+    }
+    withSourceEvidence(event) {
+        return {
+            ...event,
+            source_event_id: event.source_event_id ?? event.event_id,
+            source_schema_version: String(this.schemaVersion),
+            source_event_type: event.source_event_type ?? event.event_name,
+            source_event_kind: event.source_event_kind ?? event.event_category,
+            producer_id: event.producer_id ?? this.producerId,
+        };
+    }
+    createBatchEnvelopeMetadata() {
+        const id = this.createId();
+        return {
+            batch_id: `batch_${id}`,
+            idempotency_key: `idem_${id}`,
+            sent_at: new Date().toISOString(),
+        };
+    }
+    createId() {
+        try {
+            if (typeof globalThis.crypto !== "undefined" &&
+                typeof globalThis.crypto.randomUUID === "function") {
+                return globalThis.crypto.randomUUID();
+            }
+        }
+        catch {
+            // Fall through to a local random id when crypto is unavailable.
+        }
+        return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    }
+    trySendBeacon(payload) {
+        try {
+            if (typeof navigator === "undefined" || !navigator.sendBeacon) {
+                return false;
+            }
+            const blob = new Blob([payload], { type: "application/json" });
+            return navigator.sendBeacon(this.endpoint, blob);
+        }
+        catch {
+            return false;
+        }
+    }
+    async resolveBrowserToken() {
+        if (!this.browserTokenProvider) {
+            return null;
+        }
+        const token = await this.browserTokenProvider();
+        const trimmed = token.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    async readIngestResponse(response) {
+        try {
+            const body = await response.text();
+            if (!body.trim()) {
+                return {
+                    accepted: null,
+                    governor: null,
+                    retryStrategy: null,
+                };
+            }
+            const parsedBody = JSON.parse(body);
+            return {
+                accepted: typeof parsedBody.accepted === "boolean" ? parsedBody.accepted : null,
+                governor: parseGovernorFeedbackEnvelope(parsedBody),
+                retryStrategy: parsedBody.retry_strategy ?? null,
+            };
+        }
+        catch {
+            return {
+                accepted: null,
+                governor: null,
+                retryStrategy: null,
+            };
+        }
+    }
+}

package/dist/transport/queue.d.ts

@@ -0,0 +1,22 @@
+import type { CanonicalBaseEvent } from "../core/types";
+import type { InternalMetricsStore } from "../internal/metrics";
+export declare class EventQueue {
+    private readonly items;
+    private readonly maxItems;
+    private readonly maxBytes;
+    private readonly metrics;
+    private currentBytes;
+    constructor(options?: {
+        maxItems?: number;
+        maxBytes?: number;
+        metrics?: InternalMetricsStore;
+    });
+    enqueue(event: CanonicalBaseEvent): void;
+    dequeue(count: number): CanonicalBaseEvent[];
+    drain(): CanonicalBaseEvent[];
+    size(): number;
+    bytes(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    private measureEventBytes;
+}

package/dist/transport/queue.js

@@ -0,0 +1,56 @@
+export class EventQueue {
+    constructor(options) {
+        this.items = [];
+        this.maxItems = Math.max(1, options?.maxItems ?? 1000);
+        this.maxBytes = Math.max(1024, options?.maxBytes ?? Number.MAX_SAFE_INTEGER);
+        this.metrics = options?.metrics ?? null;
+        this.currentBytes = 0;
+    }
+    enqueue(event) {
+        this.metrics?.increment("enqueue_count");
+        const eventBytes = this.measureEventBytes(event);
+        while (this.items.length > 0 &&
+            (this.items.length >= this.maxItems ||
+                this.currentBytes + eventBytes > this.maxBytes)) {
+            const dropped = this.items.shift();
+            this.currentBytes = Math.max(0, this.currentBytes - (dropped ? this.measureEventBytes(dropped) : 0));
+            this.metrics?.increment("dropped_count");
+        }
+        if (this.items.length >= this.maxItems) {
+            const dropped = this.items.shift();
+            this.currentBytes = Math.max(0, this.currentBytes - (dropped ? this.measureEventBytes(dropped) : 0));
+            this.metrics?.increment("dropped_count");
+        }
+        this.items.push(event);
+        this.currentBytes += eventBytes;
+    }
+    dequeue(count) {
+        if (count <= 0) {
+            return [];
+        }
+        const events = this.items.splice(0, count);
+        for (const event of events) {
+            this.currentBytes = Math.max(0, this.currentBytes - this.measureEventBytes(event));
+        }
+        return events;
+    }
+    drain() {
+        return this.dequeue(this.items.length);
+    }
+    size() {
+        return this.items.length;
+    }
+    bytes() {
+        return this.currentBytes;
+    }
+    isEmpty() {
+        return this.items.length === 0;
+    }
+    clear() {
+        this.items.length = 0;
+        this.currentBytes = 0;
+    }
+    measureEventBytes(event) {
+        return new TextEncoder().encode(JSON.stringify(event)).byteLength;
+    }
+}

package/dist/transport/retry.d.ts

@@ -0,0 +1,14 @@
+export type RetryPolicy = {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+};
+export type RetryResult<T> = {
+    ok: boolean;
+    value?: T;
+    error?: unknown;
+    attempts: number;
+};
+export declare const isRetryableStatus: (status: number) => boolean;
+export declare const computeRetryDelay: (attempt: number, policy: RetryPolicy) => number;
+export declare const executeWithRetry: <T>(fn: () => Promise<T>, shouldRetry: (error: unknown) => boolean, policy?: RetryPolicy) => Promise<RetryResult<T>>;

package/dist/transport/retry.js

@@ -0,0 +1,46 @@
+import { RETRY_CONFIG } from "../core/constants";
+export const isRetryableStatus = (status) => {
+    return status === 429 || (status >= 500 && status < 600);
+};
+export const computeRetryDelay = (attempt, policy) => {
+    const exponent = Math.max(0, attempt - 1);
+    const raw = policy.baseDelayMs * 2 ** exponent;
+    const capped = Math.min(raw, policy.maxDelayMs);
+    const jitter = Math.floor(Math.random() * Math.min(200, capped));
+    return capped + jitter;
+};
+const sleep = (ms) => {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+};
+export const executeWithRetry = async (fn, shouldRetry, policy = RETRY_CONFIG) => {
+    let lastError;
+    for (let attempt = 1; attempt <= policy.maxAttempts; attempt += 1) {
+        try {
+            const value = await fn();
+            return {
+                ok: true,
+                value,
+                attempts: attempt,
+            };
+        }
+        catch (error) {
+            lastError = error;
+            const retryable = shouldRetry(error);
+            if (!retryable || attempt >= policy.maxAttempts) {
+                return {
+                    ok: false,
+                    error,
+                    attempts: attempt,
+                };
+            }
+            await sleep(computeRetryDelay(attempt, policy));
+        }
+    }
+    return {
+        ok: false,
+        error: lastError,
+        attempts: policy.maxAttempts,
+    };
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@clue-ai/browser-sdk",
+	"version": "0.0.1",
+	"description": "Clue Browser SDK for raw telemetry capture and transport",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist/",
+		"README.md"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "node ./scripts/clean-dist.mjs && node ./scripts/generate-service-logo-module.mjs && tsc -p tsconfig.build.json",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"test": "vitest run",
+		"test:cov": "vitest run --coverage"
+	},
+	"devDependencies": {
+		"@vitest/coverage-v8": "^3.2.4",
+		"jsdom": "^26.1.0",
+		"typescript": "^5.9.0",
+		"vitest": "^3.2.4"
+	},
+	"dependencies": {
+		"anim-event": "^1.0.17",
+		"cssprefix": "^2.0.17",
+		"lucide": "^1.8.0",
+		"m-class-list": "^1.1.10",
+		"plain-draggable": "^2.5.15",
+		"pointer-event": "^1.3.1"
+	}
+}