@clue-ai/browser-sdk 0.0.1

package/README.md

@@ -0,0 +1,100 @@
+# @clue-ai/browser-sdk
+
+Clue browser ingest SDK.
+
+## Minimal integration
+
+After `pnpm add @clue-ai/browser-sdk`, the intended integration is:
+
+```ts
+import { ClueInit } from "@clue-ai/browser-sdk";
+
+ClueInit({
+  endpoint: process.env.NEXT_PUBLIC_CLUE_INGEST_ENDPOINT!,
+  projectKey: "...",
+  environment: "production",
+});
+```
+
+`projectKey` is the public ingest key. The API resolves authoritative
+`tenantId`, `projectId`, and `environmentId` from that key. `endpoint` must be
+injected from the host app and passed to `ClueInit`.
+
+## Responsibility boundary
+
+- SDK captures browser signals and applies local minimization where the signal is obviously high-risk.
+- API ingest privacy gate is authoritative for final allow/deny/unmask policy.
+- Worker-side sanitize is defense-in-depth only.
+- SDK sends `projectKey`, `environment`, `schemaVersion`, `sdkType`, `sdkVersion`, stable keys, and minimized capture payloads.
+- SDK does **not** authoritatively stamp `tenant_id`, `project_id`, `environment_id`, or final archive-safe request/response payloads.
+
+The browser SDK does **not** own final archive-safe allowlist decisions.
+
+## Default privacy/minimization behavior
+
+The browser SDK avoids shipping obvious high-risk plaintext and keeps the MVP
+default event surface intentionally narrow.
+
+- `input_change.value` -> local value metadata only
+- `selection_text` -> metadata only
+- raw selector/path -> never serialized; stable key only
+
+Current MVP defaults:
+
+- successful network emits one `request_finished`
+- failed network emits one `request_failed`
+- standard action capture emits `element_clicked`, `form_submitted`,
+  `input_committed`, `toggle_changed`, `selection_committed`,
+  `file_selected`, and `drag_drop_completed`
+- standard support capture emits only frustration signals
+  (`dead_click_detected`, `error_click_detected`, `rage_click_detected`)
+- normal batching flushes when the queued payload reaches the 48KB send
+  threshold, when no new event is added for 3 minutes, or when the page is
+  leaving
+- event type does not change the delivery rule in MVP
+
+Stable key precedence:
+
+1. `data-testid`
+2. `data-qa`
+3. safe `name`
+4. safe `aria-label`
+5. structural fallback
+
+`data-clue-id` and `data-clue-key` are not part of the MVP stable-key
+contract. Captured stable keys are best-effort evidence, not authoritative
+business meaning.
+
+## Sampling and cost guards
+
+- `sampling.sessionSampleRate` controls whether a session emits normal capture
+- oversized events degrade in stages before final drop:
+  - payload body removed
+  - metadata/schema only
+  - shell only
+- oversized batches stay below the configured payload hard max
+
+## Flush reliability
+
+The SDK flushes on:
+
+- `visibilitychange` -> `hidden`
+- `pagehide`
+- `beforeunload`
+
+The page-leave flush is best effort. The SDK does not persist unsent events in
+`localStorage` or `IndexedDB` in MVP.
+
+## Beacon contract
+
+- unload / hidden beacon sends only the request body
+- ingest must be able to resolve `projectKey` and `environment` from the body
+- custom auth headers cannot be assumed on the beacon path
+
+## Degraded event contract
+
+Downstream ingest must accept these as normal input:
+
+- no raw payload body
+- metadata + schema only
+- shell-only event

package/dist/authoring/overlay.d.ts

@@ -0,0 +1,12 @@
+import type { AuthoringRecordingController } from "./recording";
+declare function resolveAuthoringBaseEndpoint(ingestEndpoint: string): string;
+declare function resolveAuthoringActionUnitsEndpoint(ingestEndpoint: string): string;
+export { resolveAuthoringBaseEndpoint, resolveAuthoringActionUnitsEndpoint };
+export declare function startBusinessEventAuthoringOverlay(options: {
+    ingestEndpoint: string;
+    recording: AuthoringRecordingController;
+    onExit?: () => void;
+}): {
+    stop: () => void;
+    exit: () => void;
+} | null;

package/dist/authoring/overlay.js

@@ -0,0 +1,468 @@
+import { clearPersistedBusinessEventAuthoringToken, isBusinessEventAuthoringSession, persistBusinessEventAuthoringToken, readPersistedBusinessEventAuthoringToken, } from "./session";
+import { AUTHORING_INTERNAL_REQUEST_HEADER, AUTHORING_INTERNAL_REQUEST_HEADER_VALUE, } from "./surface";
+import { mountToolbar } from "./toolbar-view";
+function notifyOpener(session) {
+    if (!window.opener) {
+        return;
+    }
+    window.opener.postMessage({
+        type: "clue-business-event-authoring-ready",
+        sessionId: session.session_id,
+        targetOrigin: window.location.origin,
+        href: window.location.href,
+        title: document.title,
+    }, session.clue_origin);
+}
+function reportOverlayError(phase, error) {
+    if (typeof console === "undefined") {
+        return;
+    }
+    console.error("[clue] business event authoring overlay failed", {
+        phase,
+        error,
+    });
+}
+function buildLocalPausedSession(session, nowIso) {
+    return {
+        ...session,
+        status: "paused",
+        recording_windows: session.recording_windows.map((window, index, windows) => {
+            if (index !== windows.length - 1 || window.end_at !== null) {
+                return window;
+            }
+            return {
+                start_at: window.start_at,
+                end_at: nowIso,
+            };
+        }),
+    };
+}
+function shouldKeepAuthoringStreamOpen(session) {
+    return (session !== null &&
+        session.status !== "ended" &&
+        session.recording_windows.length > 0);
+}
+function resolveAuthoringBaseEndpoint(ingestEndpoint) {
+    const url = new URL(ingestEndpoint);
+    if (url.pathname.endsWith("/ingest/browser")) {
+        url.pathname = url.pathname.replace(/\/ingest\/browser$/, "/business-events/authoring");
+        return url.toString().replace(/\/$/, "");
+    }
+    url.pathname = "/api/v1/business-events/authoring";
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+}
+function resolveBootstrapEndpoint(ingestEndpoint) {
+    return `${resolveAuthoringBaseEndpoint(ingestEndpoint)}/bootstrap`;
+}
+function resolveAuthoringActionUnitsEndpoint(ingestEndpoint) {
+    return `${resolveAuthoringBaseEndpoint(ingestEndpoint)}/action-units`;
+}
+function resolveAuthoringActionUnitsSnapshotEndpoint(ingestEndpoint) {
+    return `${resolveAuthoringBaseEndpoint(ingestEndpoint)}/action-units/snapshot`;
+}
+function resolveAuthoringActionUnitsStreamEndpoint(ingestEndpoint) {
+    return `${resolveAuthoringBaseEndpoint(ingestEndpoint)}/action-units/stream`;
+}
+function resolveAuthoringRecordingControlEndpoint(ingestEndpoint, action) {
+    return `${resolveAuthoringBaseEndpoint(ingestEndpoint)}/recording/${action}`;
+}
+function resolveAuthoringSaveEndpoint(ingestEndpoint) {
+    return `${resolveAuthoringBaseEndpoint(ingestEndpoint)}/save`;
+}
+function isAuthoringActionUnit(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const actionUnit = value;
+    return (typeof actionUnit.action_unit_id === "string" &&
+        typeof actionUnit.start_at === "string" &&
+        typeof actionUnit.end_at === "string" &&
+        typeof actionUnit.summary_label === "string" &&
+        typeof actionUnit.status === "string" &&
+        Array.isArray(actionUnit.atoms) &&
+        Array.isArray(actionUnit.request_spans));
+}
+function isAuthoringStreamEvent(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const event = value;
+    if (event.type === "heartbeat") {
+        return typeof event.session_id === "string";
+    }
+    if (event.type === "recording_state_changed") {
+        return (typeof event.session_id === "string" &&
+            typeof event.sequence === "number" &&
+            isBusinessEventAuthoringSession(event.session));
+    }
+    if (event.type === "action_unit_upserted" ||
+        event.type === "action_unit_closed") {
+        return (typeof event.session_id === "string" &&
+            typeof event.sequence === "number" &&
+            isAuthoringActionUnit(event.action_unit));
+    }
+    return false;
+}
+async function readJsonResponse(response) {
+    return response.json().catch(() => null);
+}
+function buildAuthoringRequestHeaders() {
+    return {
+        "content-type": "application/json",
+        [AUTHORING_INTERNAL_REQUEST_HEADER]: AUTHORING_INTERNAL_REQUEST_HEADER_VALUE,
+    };
+}
+async function bootstrapAuthoringSession(bootstrapEndpoint, token) {
+    const response = await fetch(bootstrapEndpoint, {
+        method: "POST",
+        headers: buildAuthoringRequestHeaders(),
+        body: JSON.stringify({ token }),
+        credentials: "omit",
+    });
+    if (!response.ok) {
+        throw new Error(`authoring bootstrap failed: ${response.status}`);
+    }
+    const payload = await readJsonResponse(response);
+    const session = payload && typeof payload === "object" ? payload.session : null;
+    if (!isBusinessEventAuthoringSession(session)) {
+        throw new Error("authoring bootstrap returned an invalid session");
+    }
+    return session;
+}
+async function fetchAuthoringActionUnitSnapshot(params) {
+    const response = await fetch(params.snapshotEndpoint, {
+        method: "POST",
+        headers: buildAuthoringRequestHeaders(),
+        body: JSON.stringify({
+            token: params.token,
+            limit: 200,
+        }),
+        credentials: "omit",
+    });
+    if (!response.ok) {
+        throw new Error(`authoring snapshot failed: ${response.status}`);
+    }
+    const payload = await readJsonResponse(response);
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        throw new Error("authoring snapshot returned an invalid payload");
+    }
+    const session = payload.session;
+    const actionUnits = payload.action_units;
+    if (!isBusinessEventAuthoringSession(session) || !Array.isArray(actionUnits)) {
+        throw new Error("authoring snapshot returned an invalid payload");
+    }
+    return {
+        session,
+        action_units: actionUnits.filter(isAuthoringActionUnit),
+    };
+}
+async function controlAuthoringRecording(params) {
+    const response = await fetch(params.endpoint, {
+        method: "POST",
+        headers: buildAuthoringRequestHeaders(),
+        body: JSON.stringify({
+            token: params.token,
+        }),
+        credentials: "omit",
+    });
+    if (!response.ok) {
+        throw new Error(`authoring recording control failed: ${response.status}`);
+    }
+    const payload = await readJsonResponse(response);
+    const session = payload && typeof payload === "object" ? payload.session : null;
+    if (!isBusinessEventAuthoringSession(session)) {
+        throw new Error("authoring recording control returned an invalid session");
+    }
+    return session;
+}
+async function saveAuthoringSelection(params) {
+    const response = await fetch(params.endpoint, {
+        method: "POST",
+        headers: buildAuthoringRequestHeaders(),
+        body: JSON.stringify({
+            token: params.token,
+            title: params.title,
+            description: params.description,
+            save_mode: params.saveMode,
+            selected_action_unit_ids: params.selectedActionUnitIds,
+        }),
+        credentials: "omit",
+    });
+    if (!response.ok) {
+        throw new Error(`authoring save failed: ${response.status}`);
+    }
+    return readJsonResponse(response);
+}
+export { resolveAuthoringBaseEndpoint, resolveAuthoringActionUnitsEndpoint };
+export function startBusinessEventAuthoringOverlay(options) {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+        return null;
+    }
+    const token = readPersistedBusinessEventAuthoringToken();
+    if (!token) {
+        return null;
+    }
+    persistBusinessEventAuthoringToken(token);
+    let mountedToolbar = null;
+    let streamSource = null;
+    let streamRetryTimer = null;
+    let isStopped = false;
+    let isExited = false;
+    let currentSession = null;
+    const exitAuthoring = () => {
+        if (isExited) {
+            return;
+        }
+        isExited = true;
+        options.recording.reset();
+        options.onExit?.();
+    };
+    const stopOverlay = (params) => {
+        if (isStopped) {
+            return;
+        }
+        isStopped = true;
+        if (streamRetryTimer !== null) {
+            window.clearTimeout(streamRetryTimer);
+            streamRetryTimer = null;
+        }
+        streamSource?.close();
+        streamSource = null;
+        mountedToolbar?.dispose();
+        mountedToolbar?.root.remove();
+        delete document.documentElement.dataset.clueBusinessEventAuthoring;
+        if (params?.clearSessionToken) {
+            clearPersistedBusinessEventAuthoringToken();
+        }
+        exitAuthoring();
+    };
+    const syncSession = (session) => {
+        currentSession = session;
+        options.recording.syncSession({
+            status: session.status,
+            recording_windows: session.recording_windows,
+        });
+        if (!shouldKeepAuthoringStreamOpen(session)) {
+            if (streamRetryTimer !== null) {
+                window.clearTimeout(streamRetryTimer);
+                streamRetryTimer = null;
+            }
+            streamSource?.close();
+            streamSource = null;
+            return;
+        }
+        ensureStream();
+    };
+    const syncSnapshot = async () => {
+        const snapshot = await fetchAuthoringActionUnitSnapshot({
+            snapshotEndpoint: resolveAuthoringActionUnitsSnapshotEndpoint(options.ingestEndpoint),
+            token,
+        });
+        if (isStopped) {
+            return;
+        }
+        syncSession(snapshot.session);
+        options.recording.replaceActionUnits(snapshot.action_units);
+    };
+    const ensureStream = () => {
+        if (isStopped || !shouldKeepAuthoringStreamOpen(currentSession)) {
+            if (streamRetryTimer !== null) {
+                window.clearTimeout(streamRetryTimer);
+                streamRetryTimer = null;
+            }
+            streamSource?.close();
+            streamSource = null;
+            return;
+        }
+        if (streamSource) {
+            return;
+        }
+        if (streamRetryTimer !== null) {
+            window.clearTimeout(streamRetryTimer);
+            streamRetryTimer = null;
+        }
+        const streamUrl = new URL(resolveAuthoringActionUnitsStreamEndpoint(options.ingestEndpoint));
+        streamUrl.searchParams.set("token", token);
+        const source = new EventSource(streamUrl.toString());
+        streamSource = source;
+        source.onmessage = (message) => {
+            if (isStopped) {
+                return;
+            }
+            try {
+                const parsed = JSON.parse(message.data);
+                if (!isAuthoringStreamEvent(parsed)) {
+                    return;
+                }
+                if (parsed.type === "heartbeat") {
+                    return;
+                }
+                if (parsed.type === "recording_state_changed") {
+                    syncSession(parsed.session);
+                    return;
+                }
+                options.recording.upsertActionUnit(parsed.action_unit);
+            }
+            catch (error) {
+                reportOverlayError("stream", error);
+            }
+        };
+        source.onerror = () => {
+            if (isStopped) {
+                return;
+            }
+            source.close();
+            if (streamSource === source) {
+                streamSource = null;
+            }
+            if (!shouldKeepAuthoringStreamOpen(currentSession) ||
+                streamRetryTimer !== null) {
+                return;
+            }
+            streamRetryTimer = window.setTimeout(() => {
+                streamRetryTimer = null;
+                ensureStream();
+            }, 3000);
+        };
+    };
+    const setRecording = async (shouldRecord) => {
+        const session = currentSession;
+        if (!session) {
+            return;
+        }
+        const nextAction = shouldRecord
+            ? session.recording_windows.length === 0
+                ? "start"
+                : "resume"
+            : "pause";
+        try {
+            const nextSession = await controlAuthoringRecording({
+                endpoint: resolveAuthoringRecordingControlEndpoint(options.ingestEndpoint, nextAction),
+                token,
+            });
+            if (isStopped) {
+                return;
+            }
+            syncSession(nextSession);
+            if (nextSession.recording_windows.length === 0) {
+                options.recording.replaceActionUnits([]);
+                return;
+            }
+            await syncSnapshot();
+        }
+        catch (error) {
+            if (!shouldRecord) {
+                syncSession(buildLocalPausedSession(session, new Date().toISOString()));
+            }
+            reportOverlayError("recording", error);
+        }
+    };
+    const resetRecording = async () => {
+        const nextSession = await controlAuthoringRecording({
+            endpoint: resolveAuthoringRecordingControlEndpoint(options.ingestEndpoint, "reset"),
+            token,
+        });
+        if (isStopped) {
+            return;
+        }
+        syncSession(nextSession);
+        options.recording.replaceActionUnits([]);
+    };
+    const endSessionAndStop = () => {
+        void (async () => {
+            try {
+                await controlAuthoringRecording({
+                    endpoint: resolveAuthoringRecordingControlEndpoint(options.ingestEndpoint, "end"),
+                    token,
+                });
+            }
+            catch (error) {
+                reportOverlayError("end", error);
+            }
+            finally {
+                stopOverlay({ clearSessionToken: true });
+            }
+        })();
+    };
+    void bootstrapAuthoringSession(resolveBootstrapEndpoint(options.ingestEndpoint), token)
+        .then((session) => {
+        if (isStopped) {
+            return;
+        }
+        if (session.target_origin !== window.location.origin) {
+            stopOverlay();
+            return;
+        }
+        persistBusinessEventAuthoringToken(token);
+        syncSession(session);
+        const mount = () => {
+            if (isStopped) {
+                return;
+            }
+            void mountToolbar(session, {
+                onClose: endSessionAndStop,
+                onReady: () => {
+                    notifyOpener(session);
+                },
+                recording: options.recording,
+                onSetRecording: setRecording,
+                onResetRecording: resetRecording,
+                onSave: ({ title, description, saveMode, selectedActionUnitIds }) => saveAuthoringSelection({
+                    endpoint: resolveAuthoringSaveEndpoint(options.ingestEndpoint),
+                    token,
+                    title,
+                    description,
+                    saveMode,
+                    selectedActionUnitIds,
+                }),
+            })
+                .then(async (toolbar) => {
+                if (isStopped) {
+                    toolbar.dispose();
+                    toolbar.root.remove();
+                    return;
+                }
+                mountedToolbar = toolbar;
+                if (currentSession?.recording_windows.length) {
+                    try {
+                        await syncSnapshot();
+                    }
+                    catch (error) {
+                        reportOverlayError("snapshot", error);
+                    }
+                }
+            })
+                .catch((error) => {
+                reportOverlayError("mount", error);
+            });
+        };
+        let didMount = false;
+        const mountOnce = () => {
+            if (didMount) {
+                return;
+            }
+            didMount = true;
+            mount();
+        };
+        if (document.readyState === "loading") {
+            document.addEventListener("DOMContentLoaded", mountOnce, { once: true });
+            window.setTimeout(mountOnce, 0);
+            return;
+        }
+        mountOnce();
+    })
+        .catch((error) => {
+        reportOverlayError("bootstrap", error);
+        stopOverlay();
+    });
+    return {
+        stop: () => {
+            stopOverlay();
+        },
+        exit: () => {
+            endSessionAndStop();
+        },
+    };
+}

package/dist/authoring/recording.d.ts

@@ -0,0 +1,125 @@
+import type { BusinessEventAuthoringSession } from "./session";
+export type AuthoringActionUnitAtom = {
+    atom_id: string;
+    occurred_at: string;
+    received_at: string;
+    event_category: string | null;
+    event_name: string;
+    event_role: string;
+    session_id: string | null;
+    stable_key: string | null;
+    ui_target_id?: string | null;
+    url_canonical?: string | null;
+    form_key: string | null;
+    service_key: string | null;
+    backend_scope: string | null;
+    operation_key: string | null;
+    screen_key: string | null;
+    request_kind: string | null;
+    result_kind: string | null;
+    error_kind: string | null;
+    route_template: string | null;
+    code_path_key: string | null;
+    container_key: string | null;
+    raw_properties_json?: Record<string, unknown> | null;
+    element_label_candidate?: string | null;
+    aria_label_candidate?: string | null;
+    placeholder_candidate?: string | null;
+    field_name_candidate?: string | null;
+    field_type?: string | null;
+    section_heading?: string | null;
+};
+export type AuthoringActionUnitRequestSpan = {
+    request_span_id: string;
+    summary_title: string;
+    endpoint_canonical: string;
+    status_kind: string;
+    duration_ms: number;
+    resource_kind: string | null;
+};
+export type AuthoringActionUnit = {
+    action_unit_id: string;
+    start_at: string;
+    end_at: string;
+    status: string;
+    unit_type: string;
+    primary_ui_target_id?: string | null;
+    route_from?: string | null;
+    route_to?: string | null;
+    summary_label: string;
+    primary_screen_label?: string | null;
+    primary_target_label?: string | null;
+    close_reason: string;
+    atom_count: number;
+    request_span_count: number;
+    algorithm_version: number;
+    atoms: readonly AuthoringActionUnitAtom[];
+    request_spans: readonly AuthoringActionUnitRequestSpan[];
+};
+export type AuthoringRecordedAtom = {
+    id: string;
+    title: string;
+    subtitle: string | null;
+    detailLabel: string | null;
+    occurredAtLabel: string;
+    badgeLabel: string;
+    roleLabel: string;
+};
+export type AuthoringRecordedRequestSpan = {
+    id: string;
+    title: string;
+    subtitle: string;
+    statusLabel: string;
+    durationLabel: string;
+};
+export type AuthoringHighlightTrace = {
+    highlightSurfaceContextKind: string;
+    highlightSurfaceRootId: string | null;
+    highlightSurfaceTitle: string | null;
+    candidateCountTotal: number;
+    candidateCountAfterContextFilter: number;
+    highlightMatchStage: string;
+    highlightRenderMode: "overlay_box" | "inline_outline" | "none";
+    highlightRejectReason: string | null;
+    top1Score: number | null;
+    top2Score: number | null;
+    usedSameSurfaceFilter: boolean;
+    overlayZIndex: number | null;
+    targetEffectiveZIndex: number | null;
+    surfaceEffectiveZIndex: number | null;
+};
+export type AuthoringRecordedEvent = {
+    id: string;
+    actionUnit: AuthoringActionUnit;
+    occurredAtLabel: string;
+    title: string;
+    subtitle: string | null;
+    screenLabel: string | null;
+    badgeLabel: string;
+    selected: boolean;
+    pendingRemoval: boolean;
+    highlightTrace: AuthoringHighlightTrace | null;
+    atoms: readonly AuthoringRecordedAtom[];
+    requestSpans: readonly AuthoringRecordedRequestSpan[];
+};
+export type AuthoringRecordingSnapshot = {
+    isRecording: boolean;
+    hasRecordedWindow: boolean;
+    entries: readonly AuthoringRecordedEvent[];
+    selectedCount: number;
+    saveTargetCount: number;
+};
+export type AuthoringRecordingController = {
+    getSnapshot: () => AuthoringRecordingSnapshot;
+    subscribe: (listener: (snapshot: AuthoringRecordingSnapshot) => void) => () => void;
+    syncSession: (session: Pick<BusinessEventAuthoringSession, "status" | "recording_windows">) => void;
+    toggleSelected: (eventId: string) => void;
+    markPendingRemoval: (eventId: string) => void;
+    restorePendingRemoval: (eventId: string) => void;
+    setHighlightTrace: (eventId: string, trace: AuthoringHighlightTrace | null) => void;
+    replaceActionUnits: (actionUnits: readonly AuthoringActionUnit[]) => void;
+    upsertActionUnit: (actionUnit: AuthoringActionUnit) => void;
+    reset: () => void;
+};
+export declare const formatActionUnitSectionTitle: (actionUnit: AuthoringActionUnit) => string;
+export declare const createAuthoringRecordingController: () => AuthoringRecordingController;