@clue-ai/browser-sdk 0.0.1

package/dist/normalize/canonical.d.ts

@@ -0,0 +1,13 @@
+import type { CanonicalBaseEvent, ClueContext, FrontendEventCategory, FrontendEventName, FrontendEventStatus } from "../core/types";
+export type CanonicalBaseInput = {
+    eventName: FrontendEventName;
+    eventCategory: FrontendEventCategory;
+    status: FrontendEventStatus;
+    context: ClueContext;
+    occurredAtMs?: number;
+    traceId?: string | null;
+    requestId?: string | null;
+    requestSpanId?: string | null;
+    interactionId?: string | null;
+};
+export declare const createCanonicalBaseEvent: (input: CanonicalBaseInput) => CanonicalBaseEvent;

package/dist/normalize/canonical.js

@@ -0,0 +1,77 @@
+import { EVENT_SOURCE, EVENT_VERSION, SOURCE_SCHEMA_VERSION, SURFACE_TYPE, } from "../core/constants";
+import { generateEventId } from "./event-id";
+export const createCanonicalBaseEvent = (input) => {
+    const eventId = generateEventId();
+    const occurredAt = new Date(input.occurredAtMs ?? Date.now()).toISOString();
+    const ingestedAt = new Date().toISOString();
+    return {
+        event_id: eventId,
+        source_event_id: eventId,
+        source_schema_version: SOURCE_SCHEMA_VERSION,
+        source_event_type: input.eventName,
+        source_event_kind: input.eventCategory,
+        producer_id: input.context.producer_id,
+        event_name: input.eventName,
+        event_category: input.eventCategory,
+        event_source: EVENT_SOURCE,
+        event_version: EVENT_VERSION,
+        occurred_at: occurredAt,
+        ingested_at: ingestedAt,
+        status: input.status,
+        sdk_collection_mode: input.context.sdk_collection_mode,
+        // project / tenant / privacy authority is resolved server-side at ingest.
+        anonymous_id: input.context.anonymous_id,
+        user_id: input.context.user_id,
+        account_id: input.context.account_id,
+        organization_id: input.context.organization_id ?? null,
+        user_profile: input.context.user_profile ?? undefined,
+        account_profile: input.context.account_profile ?? undefined,
+        workspace_id: input.context.workspace_id,
+        session_id: input.context.session_id,
+        tab_id: input.context.tab_id,
+        trace_id: input.traceId ?? input.context.trace_id,
+        request_id: input.requestId ?? input.context.request_id,
+        request_span_id: input.requestSpanId ?? input.context.request_span_id,
+        interaction_id: input.interactionId ?? input.context.interaction_id,
+        correlation_id: input.context.correlation_id,
+        surface_type: SURFACE_TYPE,
+        environment: input.context.environment,
+        frontend_release: input.context.frontend_release,
+        backend_release: null,
+        feature_flags: input.context.feature_flags,
+        experiment_variant: input.context.experiment_variant,
+        device_type: input.context.device_type,
+        browser: input.context.browser,
+        os: input.context.os,
+        locale: input.context.locale,
+        country: input.context.country,
+        referrer: input.context.referrer,
+        browser_family: input.context.browser_family,
+        browser_major_version: input.context.browser_major_version,
+        browser_engine: input.context.browser_engine,
+        os_family: input.context.os_family,
+        os_major_version: input.context.os_major_version,
+        timezone: input.context.timezone,
+        pointer_type_candidate: input.context.pointer_type_candidate,
+        touch_capable: input.context.touch_capable,
+        cookies_enabled: input.context.cookies_enabled,
+        local_storage_available: input.context.local_storage_available,
+        session_storage_available: input.context.session_storage_available,
+        service_worker_supported: input.context.service_worker_supported,
+        webgl_supported: input.context.webgl_supported,
+        reduced_motion: input.context.reduced_motion,
+        color_scheme: input.context.color_scheme,
+        account_status: input.context.account_status,
+        plan_tier: input.context.plan_tier,
+        billing_status: input.context.billing_status,
+        customer_lifecycle_stage: input.context.customer_lifecycle_stage,
+        organization_size_bucket: input.context.organization_size_bucket,
+        user_role: input.context.user_role,
+        permission_group: input.context.permission_group,
+        onboarding_state: input.context.onboarding_state,
+        trial_days_remaining_bucket: input.context.trial_days_remaining_bucket,
+        customer_health_bucket: input.context.customer_health_bucket,
+        properties: {},
+        metrics: {},
+    };
+};

package/dist/normalize/event-id.d.ts

@@ -0,0 +1,8 @@
+export declare const generateEventId: () => string;
+export declare const generateAnonymousId: () => string;
+export declare const generateSessionId: () => string;
+export declare const generateTabId: () => string;
+export declare const generateRequestId: () => string;
+export declare const generateRequestSpanId: () => string;
+export declare const generateInteractionId: () => string;
+export declare const generateViewId: () => string;

package/dist/normalize/event-id.js

@@ -0,0 +1,39 @@
+const fallbackRandom = () => {
+    return `${Math.random().toString(16).slice(2)}${Date.now().toString(16)}`;
+};
+const randomUuidLike = () => {
+    try {
+        if (typeof globalThis.crypto?.randomUUID === "function") {
+            return globalThis.crypto.randomUUID();
+        }
+    }
+    catch {
+        // Ignore and fallback.
+    }
+    const seed = fallbackRandom().padEnd(32, "0").slice(0, 32);
+    return `${seed.slice(0, 8)}-${seed.slice(8, 12)}-${seed.slice(12, 16)}-${seed.slice(16, 20)}-${seed.slice(20, 32)}`;
+};
+export const generateEventId = () => {
+    return randomUuidLike();
+};
+export const generateAnonymousId = () => {
+    return `anon_${randomUuidLike()}`;
+};
+export const generateSessionId = () => {
+    return `sess_${randomUuidLike()}`;
+};
+export const generateTabId = () => {
+    return `tab_${randomUuidLike()}`;
+};
+export const generateRequestId = () => {
+    return `req_${randomUuidLike()}`;
+};
+export const generateRequestSpanId = () => {
+    return `rsp_${randomUuidLike()}`;
+};
+export const generateInteractionId = () => {
+    return `int_${randomUuidLike()}`;
+};
+export const generateViewId = () => {
+    return `view_${randomUuidLike()}`;
+};

package/dist/normalize/path-template.d.ts

@@ -0,0 +1 @@
+export declare const toPathTemplate: (pathname: string) => string;

package/dist/normalize/path-template.js

@@ -0,0 +1,33 @@
+const UUID_SEGMENT = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const HEX_SEGMENT = /^[0-9a-f]{16,}$/i;
+const NUMBER_SEGMENT = /^\d+$/;
+const TOKEN_SEGMENT = /^[A-Za-z0-9_-]{24,}$/;
+export const toPathTemplate = (pathname) => {
+    if (!pathname || pathname === "/") {
+        return "/";
+    }
+    const normalizedPath = pathname.startsWith("/") ? pathname : `/${pathname}`;
+    const [pathOnly] = normalizedPath.split("?");
+    const segments = pathOnly
+        .split("/")
+        .filter((segment) => segment.length > 0)
+        .map((segment) => {
+        if (NUMBER_SEGMENT.test(segment)) {
+            return ":id";
+        }
+        if (UUID_SEGMENT.test(segment)) {
+            return ":uuid";
+        }
+        if (HEX_SEGMENT.test(segment)) {
+            return ":hex";
+        }
+        if (TOKEN_SEGMENT.test(segment)) {
+            return ":token";
+        }
+        return segment;
+    });
+    if (segments.length === 0) {
+        return "/";
+    }
+    return `/${segments.join("/")}`;
+};

package/dist/privacy/local-minimization.d.ts

@@ -0,0 +1,29 @@
+type LocalValueType = "string" | "number" | "boolean" | "null" | "object" | "array";
+export type LocalTextDescriptor = {
+    present: true;
+    length: number;
+};
+export type LocalValueDescriptor = {
+    present: true;
+    valueType: LocalValueType;
+    length?: number;
+    itemCount?: number;
+    keyCount?: number;
+    fileCount?: number;
+};
+export type LocalStructuredSummary = LocalValueDescriptor | {
+    present: true;
+    valueType: "object";
+    keyCount: number;
+    fields: Record<string, LocalStructuredSummary | null>;
+} | {
+    present: true;
+    valueType: "array";
+    itemCount: number;
+    items: Array<LocalStructuredSummary | null>;
+};
+export declare const buildLocalTextDescriptor: (value: string | null | undefined) => LocalTextDescriptor | null;
+export declare const buildLocalValueDescriptor: (value: unknown) => LocalValueDescriptor | null;
+export declare const buildLocalStructuredSummary: (value: unknown, depth?: number) => LocalStructuredSummary | null;
+export declare const buildLocalQuerySummary: (query: Record<string, string | string[]>) => Record<string, LocalStructuredSummary | null>;
+export {};

package/dist/privacy/local-minimization.js

@@ -0,0 +1,88 @@
+const MAX_SUMMARY_DEPTH = 4;
+const MAX_SUMMARY_KEYS = 32;
+const MAX_SUMMARY_ITEMS = 12;
+export const buildLocalTextDescriptor = (value) => {
+    if (value == null) {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    return {
+        present: true,
+        length: trimmed.length,
+    };
+};
+export const buildLocalValueDescriptor = (value) => {
+    if (value == null) {
+        return null;
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed
+            ? { present: true, valueType: "string", length: trimmed.length }
+            : null;
+    }
+    if (typeof value === "number") {
+        return { present: true, valueType: "number" };
+    }
+    if (typeof value === "boolean") {
+        return { present: true, valueType: "boolean" };
+    }
+    if (Array.isArray(value)) {
+        return {
+            present: true,
+            valueType: "array",
+            itemCount: value.length,
+        };
+    }
+    if (typeof value === "object") {
+        const record = value;
+        const fileCount = typeof record.fileCount === "number" && Number.isFinite(record.fileCount)
+            ? Math.max(0, Math.floor(record.fileCount))
+            : undefined;
+        return {
+            present: true,
+            valueType: "object",
+            keyCount: Object.keys(record).length,
+            ...(typeof fileCount === "number" ? { fileCount } : {}),
+        };
+    }
+    return null;
+};
+export const buildLocalStructuredSummary = (value, depth = 0) => {
+    if (depth >= MAX_SUMMARY_DEPTH) {
+        return buildLocalValueDescriptor(value);
+    }
+    if (Array.isArray(value)) {
+        return {
+            present: true,
+            valueType: "array",
+            itemCount: value.length,
+            items: value
+                .slice(0, MAX_SUMMARY_ITEMS)
+                .map((entry) => buildLocalStructuredSummary(entry, depth + 1)),
+        };
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        const limitedEntries = Object.entries(record).slice(0, MAX_SUMMARY_KEYS);
+        return {
+            present: true,
+            valueType: "object",
+            keyCount: Object.keys(record).length,
+            fields: Object.fromEntries(limitedEntries.map(([key, child]) => [
+                key,
+                buildLocalStructuredSummary(child, depth + 1),
+            ])),
+        };
+    }
+    return buildLocalValueDescriptor(value);
+};
+export const buildLocalQuerySummary = (query) => {
+    return Object.fromEntries(Object.entries(query).map(([key, value]) => [
+        key,
+        buildLocalStructuredSummary(value),
+    ]));
+};

package/dist/privacy/mask.d.ts

@@ -0,0 +1,7 @@
+export declare const maskString: (value: string | null | undefined) => string | null;
+export declare const maskStringArray: (value: string[] | null | undefined) => string[] | null;
+export declare const maskUnknown: (value: unknown) => unknown;
+export declare const maskDomPath: (domPath: string | null | undefined) => string | null;
+export declare const maskMessage: (message: string | null | undefined) => string | null;
+export declare const maskUrl: (urlValue: string | null | undefined) => string | null;
+export declare const maskInputValue: () => string;

package/dist/privacy/mask.js

@@ -0,0 +1,60 @@
+import { MASKED_VALUE } from "../core/constants";
+export const maskString = (value) => {
+    if (value == null) {
+        return null;
+    }
+    if (!value.trim()) {
+        return null;
+    }
+    return MASKED_VALUE;
+};
+export const maskStringArray = (value) => {
+    if (!value || value.length === 0) {
+        return null;
+    }
+    return value.map(() => MASKED_VALUE);
+};
+export const maskUnknown = (value) => {
+    if (value == null) {
+        return null;
+    }
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "bigint") {
+        return MASKED_VALUE;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => maskUnknown(entry));
+    }
+    if (typeof value === "object") {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            out[key] = maskUnknown(child);
+        }
+        return out;
+    }
+    return MASKED_VALUE;
+};
+export const maskDomPath = (domPath) => {
+    return maskString(domPath);
+};
+export const maskMessage = (message) => {
+    return maskString(message);
+};
+export const maskUrl = (urlValue) => {
+    if (!urlValue) {
+        return null;
+    }
+    try {
+        const url = new URL(urlValue, globalThis.location?.origin);
+        const query = url.search ? `?${MASKED_VALUE}` : "";
+        return `${url.origin}${url.pathname}${query}`;
+    }
+    catch {
+        return MASKED_VALUE;
+    }
+};
+export const maskInputValue = () => {
+    return MASKED_VALUE;
+};

package/dist/privacy/parameter-snapshot.d.ts

@@ -0,0 +1,14 @@
+import type { ParameterSnapshotValue } from "../core/types";
+type ParameterSnapshotBundle = {
+    snapshot: ParameterSnapshotValue;
+    allowedValueKeys: string[];
+};
+type ParameterSnapshotOptions = {
+    allowedPaths: string[];
+    deniedKeys: string[];
+    pathPrefix?: string;
+};
+export declare const buildUnavailableParameterSnapshot: () => ParameterSnapshotValue;
+export declare const truncateParameterSnapshotValue: (value: ParameterSnapshotValue) => ParameterSnapshotValue;
+export declare const buildParameterSnapshotBundle: (value: unknown, options: ParameterSnapshotOptions) => ParameterSnapshotBundle;
+export {};

package/dist/privacy/parameter-snapshot.js

@@ -0,0 +1,206 @@
+import { FORBIDDEN_PARAMETER_VALUE, MASKED_VALUE, MAX_SANITIZE_DEPTH, TRUNCATED_PARAMETER_VALUE, } from "../core/constants";
+import { PARAMETER_CAPTURE_MODE } from "../core/contracts";
+import { isDeniedKey } from "./sanitize";
+const SNAPSHOT_UNAVAILABLE_KEY = "_clue_snapshot_unavailable";
+const normalizeParameterLookupPath = (path) => {
+    return path.replace(/\[\d+\]/g, "[]");
+};
+const inferLeafType = (value) => {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    if (typeof value === "object") {
+        return "object";
+    }
+    switch (typeof value) {
+        case "string":
+            return "string";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        default:
+            return "string";
+    }
+};
+const toPlaintextLeafValue = (value) => {
+    if (value === null) {
+        return null;
+    }
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    return String(value);
+};
+const measureSerializedBytes = (value) => {
+    try {
+        return new TextEncoder().encode(JSON.stringify(value)).length;
+    }
+    catch {
+        return undefined;
+    }
+};
+const buildLeaf = (value, captureMode) => {
+    const leafType = inferLeafType(value);
+    const originalSizeBytes = captureMode === PARAMETER_CAPTURE_MODE.forbidden
+        ? undefined
+        : measureSerializedBytes(value);
+    return {
+        type: leafType,
+        value: captureMode === PARAMETER_CAPTURE_MODE.allowedPlaintext
+            ? toPlaintextLeafValue(value)
+            : captureMode === PARAMETER_CAPTURE_MODE.forbidden
+                ? FORBIDDEN_PARAMETER_VALUE
+                : MASKED_VALUE,
+        capture_mode: captureMode,
+        ...(typeof originalSizeBytes === "number"
+            ? { original_size_bytes: originalSizeBytes }
+            : {}),
+    };
+};
+export const buildUnavailableParameterSnapshot = () => ({
+    [SNAPSHOT_UNAVAILABLE_KEY]: buildLeaf("snapshot_unavailable", PARAMETER_CAPTURE_MODE.maskedFingerprint),
+});
+const isParameterSnapshotLeaf = (value) => {
+    return (!!value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        "type" in value &&
+        "value" in value &&
+        "capture_mode" in value);
+};
+export const truncateParameterSnapshotValue = (value) => {
+    if (Array.isArray(value)) {
+        return value.map((entry) => truncateParameterSnapshotValue(entry));
+    }
+    if (isParameterSnapshotLeaf(value)) {
+        const originalSizeBytes = typeof value.original_size_bytes === "number"
+            ? value.original_size_bytes
+            : value.capture_mode === PARAMETER_CAPTURE_MODE.allowedPlaintext
+                ? measureSerializedBytes(value.value)
+                : undefined;
+        return {
+            type: value.type,
+            value: TRUNCATED_PARAMETER_VALUE,
+            capture_mode: PARAMETER_CAPTURE_MODE.truncated,
+            truncated_reason: "max_event_bytes",
+            ...(typeof originalSizeBytes === "number"
+                ? { original_size_bytes: originalSizeBytes }
+                : {}),
+        };
+    }
+    const truncated = {};
+    for (const [key, child] of Object.entries(value)) {
+        truncated[key] = truncateParameterSnapshotValue(child);
+    }
+    return truncated;
+};
+const buildAllowedPathLookup = (allowedPaths) => {
+    const lookup = new Map();
+    for (const entry of allowedPaths) {
+        const trimmed = entry.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const normalized = normalizeParameterLookupPath(trimmed);
+        if (!lookup.has(normalized)) {
+            lookup.set(normalized, trimmed);
+        }
+    }
+    return lookup;
+};
+export const buildParameterSnapshotBundle = (value, options) => {
+    const allowedPathLookup = buildAllowedPathLookup(options.allowedPaths);
+    const seen = new WeakSet();
+    const rootPathPrefix = options.pathPrefix?.trim() ?? "";
+    const walk = (current, path, depth) => {
+        if (depth > MAX_SANITIZE_DEPTH) {
+            return {
+                snapshot: buildLeaf(null, PARAMETER_CAPTURE_MODE.maskedFingerprint),
+                allowedValueKeys: [],
+            };
+        }
+        if (current === undefined ||
+            typeof current === "function" ||
+            typeof current === "symbol") {
+            return {
+                snapshot: undefined,
+                allowedValueKeys: [],
+            };
+        }
+        if (Array.isArray(current)) {
+            if (current.length === 0) {
+                return {
+                    snapshot: [],
+                    allowedValueKeys: [],
+                };
+            }
+            const representative = walk(current[0], `${path}[]`, depth + 1);
+            if (representative.snapshot === undefined) {
+                return {
+                    snapshot: [],
+                    allowedValueKeys: representative.allowedValueKeys,
+                };
+            }
+            return {
+                snapshot: [representative.snapshot],
+                allowedValueKeys: representative.allowedValueKeys,
+            };
+        }
+        if (current && typeof current === "object") {
+            const objectValue = current;
+            if (seen.has(objectValue)) {
+                return {
+                    snapshot: buildLeaf(null, PARAMETER_CAPTURE_MODE.maskedFingerprint),
+                    allowedValueKeys: [],
+                };
+            }
+            seen.add(objectValue);
+            const snapshot = {};
+            const allowedValueKeys = [];
+            for (const [key, child] of Object.entries(objectValue)) {
+                const childPath = path ? `${path}.${key}` : key;
+                if (isDeniedKey(key, options.deniedKeys)) {
+                    snapshot[key] = buildLeaf(child, PARAMETER_CAPTURE_MODE.forbidden);
+                    continue;
+                }
+                const childBundle = walk(child, childPath, depth + 1);
+                if (childBundle.snapshot === undefined) {
+                    continue;
+                }
+                snapshot[key] = childBundle.snapshot;
+                allowedValueKeys.push(...childBundle.allowedValueKeys);
+            }
+            seen.delete(objectValue);
+            return {
+                snapshot,
+                allowedValueKeys,
+            };
+        }
+        const matchedAllowedPath = path
+            ? allowedPathLookup.get(normalizeParameterLookupPath(path)) ?? null
+            : null;
+        const captureMode = matchedAllowedPath
+            ? PARAMETER_CAPTURE_MODE.allowedPlaintext
+            : PARAMETER_CAPTURE_MODE.maskedFingerprint;
+        return {
+            snapshot: buildLeaf(current, captureMode),
+            allowedValueKeys: matchedAllowedPath ? [matchedAllowedPath] : [],
+        };
+    };
+    const rootBundle = walk(value, rootPathPrefix, 0);
+    const snapshot = rootBundle.snapshot &&
+        typeof rootBundle.snapshot === "object" &&
+        !Array.isArray(rootBundle.snapshot)
+        ? rootBundle.snapshot
+        : {};
+    return {
+        snapshot,
+        allowedValueKeys: [...new Set(rootBundle.allowedValueKeys)].sort(),
+    };
+};

package/dist/privacy/sanitize.d.ts

@@ -0,0 +1,11 @@
+export declare const isDeniedKey: (key: string, deniedKeys?: string[]) => boolean;
+export declare const sanitizeHeaders: (headers: Record<string, string>, deniedKeys?: string[]) => Record<string, string>;
+export declare const sanitizeObject: (value: unknown, deniedKeys?: string[]) => unknown;
+export declare const parseUrlForNetwork: (rawUrl: string) => {
+    host: string;
+    pathTemplate: string;
+    path: string;
+    query: Record<string, string | string[]>;
+    urlMaskedQuery: string;
+};
+export declare const maybeParseJson: (value: unknown) => unknown;