@clue-ai/browser-sdk 0.0.1

package/dist/privacy/sanitize.js

@@ -0,0 +1,145 @@
+import { ALWAYS_DENIED_KEYS, MASKED_VALUE, MAX_SANITIZE_DEPTH, } from "../core/constants";
+import { toPathTemplate } from "../normalize/path-template";
+const normalizeHeaderKey = (key) => key.trim().toLowerCase();
+const normalizeLookupKey = (key) => key
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+const toDeniedSet = (deniedKeys) => {
+    return new Set([...ALWAYS_DENIED_KEYS, ...deniedKeys]
+        .map((entry) => normalizeLookupKey(entry))
+        .filter(Boolean));
+};
+const isDeniedKeyWithSet = (key, deniedSet) => {
+    const normalized = normalizeLookupKey(key);
+    if (!normalized) {
+        return false;
+    }
+    if (deniedSet.has(normalized)) {
+        return true;
+    }
+    const padded = `_${normalized}_`;
+    for (const denied of deniedSet) {
+        if (padded.includes(`_${denied}_`)) {
+            return true;
+        }
+    }
+    return false;
+};
+export const isDeniedKey = (key, deniedKeys = []) => {
+    return isDeniedKeyWithSet(key, toDeniedSet(deniedKeys));
+};
+export const sanitizeHeaders = (headers, deniedKeys = []) => {
+    const deniedSet = toDeniedSet(deniedKeys);
+    const sanitized = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (isDeniedKeyWithSet(key, deniedSet)) {
+            continue;
+        }
+        sanitized[normalizeHeaderKey(key)] = value;
+    }
+    return sanitized;
+};
+export const sanitizeObject = (value, deniedKeys = []) => {
+    const deniedSet = toDeniedSet(deniedKeys);
+    const seen = new WeakSet();
+    const walk = (current, depth) => {
+        if (current == null) {
+            return null;
+        }
+        if (depth > MAX_SANITIZE_DEPTH) {
+            return null;
+        }
+        if (Array.isArray(current)) {
+            return current.map((entry) => {
+                const next = walk(entry, depth + 1);
+                return next === undefined ? null : next;
+            });
+        }
+        if (typeof current === "object") {
+            const objectValue = current;
+            if (seen.has(objectValue)) {
+                return null;
+            }
+            seen.add(objectValue);
+            const sanitized = {};
+            for (const [key, child] of Object.entries(objectValue)) {
+                if (isDeniedKeyWithSet(key, deniedSet)) {
+                    continue;
+                }
+                const next = walk(child, depth + 1);
+                if (next === undefined) {
+                    continue;
+                }
+                sanitized[key] = next;
+            }
+            seen.delete(objectValue);
+            return sanitized;
+        }
+        if (typeof current === "function" || typeof current === "symbol") {
+            return undefined;
+        }
+        return current;
+    };
+    return walk(value, 0);
+};
+export const parseUrlForNetwork = (rawUrl) => {
+    const toQueryRecord = (url) => {
+        const query = {};
+        url.searchParams.forEach((value, key) => {
+            const current = query[key];
+            if (current === undefined) {
+                query[key] = value;
+                return;
+            }
+            if (Array.isArray(current)) {
+                query[key] = [...current, value];
+                return;
+            }
+            query[key] = [current, value];
+        });
+        return query;
+    };
+    try {
+        const url = new URL(rawUrl, globalThis.location?.origin);
+        const query = url.search ? `?${MASKED_VALUE}` : "";
+        return {
+            host: url.host,
+            pathTemplate: toPathTemplate(url.pathname),
+            path: url.pathname,
+            query: toQueryRecord(url),
+            urlMaskedQuery: `${url.origin}${url.pathname}${query}`,
+        };
+    }
+    catch {
+        return {
+            host: "",
+            pathTemplate: "/",
+            path: "/",
+            query: {},
+            urlMaskedQuery: MASKED_VALUE,
+        };
+    }
+};
+export const maybeParseJson = (value) => {
+    if (typeof value !== "string") {
+        return value;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const isJsonLike = (trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+        (trimmed.startsWith("[") && trimmed.endsWith("]"));
+    if (!isJsonLike) {
+        return null;
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+};

package/dist/privacy/schema-evidence.d.ts

@@ -0,0 +1,20 @@
+type SchemaEvidence = {
+    schemaHash: string | null;
+    fieldPaths: string[];
+    shapeSize: number;
+};
+export declare const buildSchemaEvidence: (value: unknown) => SchemaEvidence;
+export declare const extractErrorCodeCandidate: (value: unknown) => string | null;
+export declare const deriveOutcomeClass: (input: {
+    statusCode?: number | null;
+    failureType?: string | null;
+    responseBody?: unknown;
+}) => string;
+export type GraphqlEvidence = {
+    requestKind: "graphql" | null;
+    graphqlOperationName: string | null;
+    graphqlOperationType: "query" | "mutation" | "subscription" | null;
+    graphqlTopLevelFields: string[];
+};
+export declare const extractGraphqlEvidence: (body: unknown) => GraphqlEvidence;
+export {};

package/dist/privacy/schema-evidence.js

@@ -0,0 +1,238 @@
+const MAX_FIELD_PATHS = 100;
+const MAX_DEPTH = 8;
+const fnv1a = (value) => {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `fnv1a:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+};
+const valueType = (value) => {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    if (typeof value === "object") {
+        return "object";
+    }
+    return typeof value;
+};
+const buildShape = (value, path, fieldPaths, depth) => {
+    if (depth > MAX_DEPTH) {
+        return { type: "max_depth" };
+    }
+    if (Array.isArray(value)) {
+        if (path && fieldPaths.length < MAX_FIELD_PATHS) {
+            fieldPaths.push(`${path}[]`);
+        }
+        return {
+            type: "array",
+            items: value.length > 0
+                ? buildShape(value[0], `${path}[]`, fieldPaths, depth + 1)
+                : "empty",
+        };
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        const fields = {};
+        for (const key of Object.keys(record).sort()) {
+            const childPath = path ? `${path}.${key}` : key;
+            if (fieldPaths.length < MAX_FIELD_PATHS) {
+                fieldPaths.push(childPath);
+            }
+            fields[key] = buildShape(record[key], childPath, fieldPaths, depth + 1);
+        }
+        return {
+            type: "object",
+            fields,
+        };
+    }
+    return { type: valueType(value) };
+};
+export const buildSchemaEvidence = (value) => {
+    if (value === null || value === undefined) {
+        return {
+            schemaHash: null,
+            fieldPaths: [],
+            shapeSize: 0,
+        };
+    }
+    const fieldPaths = [];
+    const shape = buildShape(value, "", fieldPaths, 0);
+    const uniqueFieldPaths = [...new Set(fieldPaths)].sort();
+    return {
+        schemaHash: fnv1a(JSON.stringify(shape)),
+        fieldPaths: uniqueFieldPaths,
+        shapeSize: uniqueFieldPaths.length,
+    };
+};
+const sanitizeToken = (value) => {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length > 96) {
+        return null;
+    }
+    if (!/^[A-Za-z0-9_.:-]+$/.test(trimmed)) {
+        return null;
+    }
+    return trimmed.toLowerCase();
+};
+export const extractErrorCodeCandidate = (value) => {
+    if (!value || typeof value !== "object") {
+        return sanitizeToken(value);
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            const candidate = extractErrorCodeCandidate(entry);
+            if (candidate) {
+                return candidate;
+            }
+        }
+        return null;
+    }
+    const record = value;
+    for (const key of ["code", "error_code", "type", "error"]) {
+        const candidate = sanitizeToken(record[key]);
+        if (candidate) {
+            return candidate;
+        }
+    }
+    for (const key of ["errors", "detail", "extensions"]) {
+        const candidate = extractErrorCodeCandidate(record[key]);
+        if (candidate) {
+            return candidate;
+        }
+    }
+    return null;
+};
+export const deriveOutcomeClass = (input) => {
+    const failureType = input.failureType ?? null;
+    if (failureType) {
+        if (failureType === "AbortError" || failureType.includes("abort")) {
+            return "aborted";
+        }
+        if (failureType.includes("timeout")) {
+            return "timeout";
+        }
+        return "network_failed";
+    }
+    const statusCode = input.statusCode ?? 0;
+    if (statusCode === 401) {
+        return "auth_denied";
+    }
+    if (statusCode === 403) {
+        return "permission_denied";
+    }
+    if (statusCode === 409) {
+        return "conflict";
+    }
+    if (statusCode === 422) {
+        return "validation_error";
+    }
+    if (statusCode === 429) {
+        return "rate_limited";
+    }
+    if (statusCode >= 500) {
+        return "server_error";
+    }
+    if (statusCode >= 400) {
+        return "client_error";
+    }
+    return "success";
+};
+const stripGraphqlNoise = (query) => {
+    return query
+        .replace(/#[^\n\r]*/g, "")
+        .replace(/"([^"\\]|\\.)*"/g, "\"\"")
+        .replace(/'([^'\\]|\\.)*'/g, "''");
+};
+const readTopLevelGraphqlFields = (query) => {
+    const openIndex = query.indexOf("{");
+    if (openIndex < 0) {
+        return [];
+    }
+    const fields = [];
+    let depth = 0;
+    let parenDepth = 0;
+    let token = "";
+    for (let index = openIndex; index < query.length; index += 1) {
+        const char = query[index];
+        if (char === "(") {
+            if (depth === 1) {
+                if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(token) && token !== "on") {
+                    fields.push(token);
+                }
+                token = "";
+            }
+            parenDepth += 1;
+            continue;
+        }
+        if (char === ")") {
+            parenDepth = Math.max(0, parenDepth - 1);
+            token = "";
+            continue;
+        }
+        if (char === "{") {
+            depth += 1;
+            token = "";
+            continue;
+        }
+        if (char === "}") {
+            if (depth === 1 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(token)) {
+                fields.push(token);
+            }
+            depth -= 1;
+            token = "";
+            continue;
+        }
+        if (depth !== 1 || parenDepth > 0) {
+            continue;
+        }
+        if (/[A-Za-z0-9_]/.test(char)) {
+            token += char;
+            continue;
+        }
+        if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(token) && token !== "on") {
+            fields.push(token);
+        }
+        token = "";
+    }
+    return [...new Set(fields)].slice(0, 20).sort();
+};
+export const extractGraphqlEvidence = (body) => {
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+        return {
+            requestKind: null,
+            graphqlOperationName: null,
+            graphqlOperationType: null,
+            graphqlTopLevelFields: [],
+        };
+    }
+    const record = body;
+    const query = typeof record.query === "string" ? record.query : null;
+    if (!query) {
+        return {
+            requestKind: null,
+            graphqlOperationName: null,
+            graphqlOperationType: null,
+            graphqlTopLevelFields: [],
+        };
+    }
+    const normalizedQuery = stripGraphqlNoise(query);
+    const operationMatch = normalizedQuery.match(/\b(query|mutation|subscription)\s*([A-Za-z_][A-Za-z0-9_]*)?/);
+    const operationType = operationMatch?.[1] ?? "query";
+    const operationName = typeof record.operationName === "string" && record.operationName.trim()
+        ? record.operationName.trim()
+        : operationMatch?.[2] ?? null;
+    return {
+        requestKind: "graphql",
+        graphqlOperationName: operationName,
+        graphqlOperationType: operationType,
+        graphqlTopLevelFields: readTopLevelGraphqlFields(normalizedQuery),
+    };
+};

package/dist/transport/batch.d.ts

@@ -0,0 +1,37 @@
+import type { CanonicalBaseEvent, IngestUsageGovernorFeedback } from "../core/types";
+import type { InternalMetricsStore } from "../internal/metrics";
+import type { IngestClient } from "./client";
+export type BatchTransportOptions = {
+    enabled: boolean;
+    flushIntervalMs: number;
+    maxPayloadBytes: number;
+    client: IngestClient;
+    metrics?: InternalMetricsStore;
+    queueMaxBytes?: number;
+    onGovernorFeedback?: (feedback: IngestUsageGovernorFeedback) => void;
+};
+export declare class BatchTransport {
+    private readonly queue;
+    private readonly client;
+    private readonly enabled;
+    private readonly flushIntervalMs;
+    private readonly maxPayloadBytes;
+    private readonly flushThresholdBytes;
+    private readonly metrics;
+    private readonly onGovernorFeedback;
+    private idleHandle;
+    private flushing;
+    private flushAgainAfterCurrent;
+    private pendingBatches;
+    constructor(options: BatchTransportOptions);
+    start(): void;
+    stop(): void;
+    enqueue(event: CanonicalBaseEvent): void;
+    private scheduleIdleFlush;
+    flush(): Promise<void>;
+    flushOnUnload(): void;
+    clear(): void;
+    private partitionEvents;
+    private splitBatch;
+    private shouldRetainFailedBatch;
+}

package/dist/transport/batch.js

@@ -0,0 +1,182 @@
+import { EventQueue } from "./queue";
+export class BatchTransport {
+    constructor(options) {
+        this.enabled = options.enabled;
+        this.flushIntervalMs = Math.max(100, options.flushIntervalMs);
+        this.maxPayloadBytes = Math.max(1024, options.maxPayloadBytes);
+        this.flushThresholdBytes = Math.floor(this.maxPayloadBytes * 0.8);
+        this.client = options.client;
+        this.metrics = options.metrics ?? null;
+        this.onGovernorFeedback = options.onGovernorFeedback ?? null;
+        this.queue = new EventQueue({
+            metrics: this.metrics ?? undefined,
+            maxItems: Number.MAX_SAFE_INTEGER,
+            maxBytes: options.queueMaxBytes,
+        });
+        this.idleHandle = null;
+        this.flushing = false;
+        this.flushAgainAfterCurrent = false;
+        this.pendingBatches = [];
+    }
+    start() {
+        if (!this.enabled) {
+            return;
+        }
+    }
+    stop() {
+        if (this.idleHandle) {
+            clearTimeout(this.idleHandle);
+            this.idleHandle = null;
+        }
+    }
+    enqueue(event) {
+        this.queue.enqueue(event);
+        this.scheduleIdleFlush();
+        if (!this.enabled) {
+            void this.flush();
+            return;
+        }
+        if (this.queue.bytes() >= this.flushThresholdBytes) {
+            void this.flush();
+        }
+    }
+    scheduleIdleFlush() {
+        if (!this.enabled) {
+            return;
+        }
+        if (this.idleHandle) {
+            clearTimeout(this.idleHandle);
+        }
+        this.idleHandle = setTimeout(() => {
+            this.idleHandle = null;
+            void this.flush();
+        }, this.flushIntervalMs);
+    }
+    async flush() {
+        if (this.flushing) {
+            if (!this.enabled) {
+                this.flushAgainAfterCurrent = true;
+            }
+            return;
+        }
+        if (this.queue.isEmpty() && this.pendingBatches.length === 0) {
+            return;
+        }
+        this.flushing = true;
+        try {
+            if (this.pendingBatches.length === 0) {
+                this.pendingBatches.push(...this.partitionEvents(this.queue.drain()));
+            }
+            while (this.pendingBatches.length > 0) {
+                const batch = this.pendingBatches.shift();
+                if (!batch || batch.events.length === 0) {
+                    continue;
+                }
+                this.metrics?.increment("batch_flush_count");
+                const result = await this.client.send(batch.events, {
+                    maxPayloadBytes: this.maxPayloadBytes,
+                    metadata: batch.metadata,
+                });
+                if (result.governor) {
+                    this.onGovernorFeedback?.(result.governor);
+                }
+                if (!result.ok) {
+                    if (result.retryStrategy === "split_batch") {
+                        const splitBatches = this.splitBatch(batch);
+                        if (splitBatches.length > 0) {
+                            this.pendingBatches.unshift(...splitBatches);
+                            this.scheduleIdleFlush();
+                            continue;
+                        }
+                        this.metrics?.increment("dropped_count", batch.events.length);
+                        this.metrics?.increment("oversized_event_dropped_count");
+                        continue;
+                    }
+                    if (this.shouldRetainFailedBatch(result.retryStrategy)) {
+                        this.pendingBatches.unshift(batch);
+                        this.scheduleIdleFlush();
+                        break;
+                    }
+                    this.metrics?.increment("dropped_count", batch.events.length);
+                    this.metrics?.increment("transport_failed_count");
+                    continue;
+                }
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+        if (!this.enabled &&
+            (this.flushAgainAfterCurrent ||
+                this.pendingBatches.length > 0 ||
+                !this.queue.isEmpty())) {
+            this.flushAgainAfterCurrent = false;
+            await this.flush();
+        }
+    }
+    flushOnUnload() {
+        this.stop();
+        const pendingBatches = [
+            ...this.pendingBatches,
+            ...this.partitionEvents(this.queue.drain()),
+        ];
+        this.pendingBatches = [];
+        for (const batch of pendingBatches) {
+            void this.client.send(batch.events, {
+                useBeacon: true,
+                maxPayloadBytes: this.maxPayloadBytes,
+                metadata: batch.metadata,
+            });
+        }
+    }
+    clear() {
+        this.queue.clear();
+        this.pendingBatches = [];
+    }
+    partitionEvents(events) {
+        const batches = [];
+        let metadata = this.client.createBatchEnvelopeMetadata();
+        let current = [];
+        for (const event of events) {
+            const candidate = [...current, event];
+            if (current.length > 0 &&
+                this.client.measurePayloadBytes(candidate, metadata) >
+                    this.maxPayloadBytes) {
+                batches.push({ events: current, metadata });
+                metadata = this.client.createBatchEnvelopeMetadata();
+                current = [];
+            }
+            if (this.client.measurePayloadBytes([event], metadata) >
+                this.maxPayloadBytes) {
+                this.metrics?.increment("dropped_count");
+                this.metrics?.increment("oversized_event_count");
+                this.metrics?.increment("oversized_event_dropped_count");
+                continue;
+            }
+            current.push(event);
+        }
+        if (current.length > 0) {
+            batches.push({ events: current, metadata });
+        }
+        return batches;
+    }
+    splitBatch(batch) {
+        if (batch.events.length <= 1) {
+            return [];
+        }
+        const midpoint = Math.ceil(batch.events.length / 2);
+        return [
+            {
+                events: batch.events.slice(0, midpoint),
+                metadata: this.client.createBatchEnvelopeMetadata(),
+            },
+            {
+                events: batch.events.slice(midpoint),
+                metadata: this.client.createBatchEnvelopeMetadata(),
+            },
+        ].filter((child) => child.events.length > 0);
+    }
+    shouldRetainFailedBatch(retryStrategy) {
+        return retryStrategy === null || retryStrategy === "retry_same_batch";
+    }
+}

package/dist/transport/client.d.ts

@@ -0,0 +1,61 @@
+import type { CanonicalBaseEvent, ClueEnvironment, IngestUsageGovernorFeedback } from "../core/types";
+import type { InternalMetricsStore } from "../internal/metrics";
+export declare const CLUE_SDK_REQUEST_HEADER = "x-clue-sdk-request";
+export declare const CLUE_ENVIRONMENT_HEADER = "x-clue-environment";
+export declare const CLUE_SDK_VERSION_HEADER = "x-clue-sdk-version";
+export declare const CLUE_SOURCE_SCHEMA_VERSION_HEADER = "x-clue-source-schema-version";
+export declare const CLUE_SERVICE_KEY_HEADER = "x-clue-service-key";
+export declare const CLUE_BROWSER_TOKEN_HEADER = "x-clue-browser-token";
+export type IngestClientOptions = {
+    endpoint: string;
+    projectKey: string;
+    environment: ClueEnvironment;
+    serviceKey?: string;
+    producerId: string;
+    browserTokenProvider?: () => string | Promise<string>;
+    sdkType: "browser";
+    sdkVersion: string;
+    schemaVersion: number;
+    metrics?: InternalMetricsStore;
+};
+export type SendEventsOptions = {
+    keepalive?: boolean;
+    useBeacon?: boolean;
+    maxPayloadBytes?: number;
+    metadata?: BatchEnvelopeMetadata;
+};
+export type SendEventsResult = {
+    ok: boolean;
+    status: number | null;
+    attempts: number;
+    governor: IngestUsageGovernorFeedback | null;
+    retryStrategy: IngestRetryStrategy | null;
+};
+export type BatchEnvelopeMetadata = {
+    batch_id: string;
+    idempotency_key: string;
+    sent_at: string;
+};
+export type IngestRetryStrategy = "split_batch" | "retry_same_batch" | "stop_and_report" | "mark_failed" | "drop_event";
+export declare class IngestClient {
+    private readonly endpoint;
+    private readonly projectKey;
+    private readonly environment;
+    private readonly serviceKey;
+    private readonly producerId;
+    private readonly browserTokenProvider;
+    private readonly sdkType;
+    private readonly sdkVersion;
+    private readonly schemaVersion;
+    private readonly metrics;
+    constructor(options: IngestClientOptions);
+    send(events: CanonicalBaseEvent[], options?: SendEventsOptions): Promise<SendEventsResult>;
+    measurePayloadBytes(events: CanonicalBaseEvent[], metadata?: BatchEnvelopeMetadata): number;
+    private stringifyPayload;
+    private withSourceEvidence;
+    createBatchEnvelopeMetadata(): BatchEnvelopeMetadata;
+    private createId;
+    private trySendBeacon;
+    private resolveBrowserToken;
+    private readIngestResponse;
+}