@clue-ai/browser-sdk 0.0.1

package/dist/capture/form.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureModuleContext, CaptureStopHandle } from "../core/types";
+export declare const startFormCapture: (context: CaptureModuleContext) => CaptureStopHandle;

package/dist/capture/form.js

@@ -0,0 +1,137 @@
+import { buildLocalTextDescriptor } from "../privacy/local-minimization";
+import { extractFieldName, extractFieldType, getElementAriaLabel, getElementClassList, getElementLabel, getElementPlaceholder, getElementRole, getElementSectionHeading, isEditableElement, resolveClickDisplayTarget, resolveStableKeyDescriptor, } from "./dom";
+const VALIDATION_REASON_KEYS = [
+    "valueMissing",
+    "typeMismatch",
+    "patternMismatch",
+    "tooLong",
+    "tooShort",
+    "rangeUnderflow",
+    "rangeOverflow",
+    "stepMismatch",
+    "badInput",
+    "customError",
+];
+const toSnakeCase = (value) => value.replace(/[A-Z]/g, (char) => `_${char.toLowerCase()}`);
+const isFormControlElement = (element) => element instanceof HTMLInputElement ||
+    element instanceof HTMLSelectElement ||
+    element instanceof HTMLTextAreaElement;
+const fingerprintText = (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 buildValidationEvidence = (form) => {
+    const invalidControls = Array.from(form.elements)
+        .filter((element) => {
+        return isFormControlElement(element) && !element.validity.valid;
+    })
+        .slice(0, 25);
+    const invalidFieldStableKeys = invalidControls
+        .map((element) => resolveStableKeyDescriptor(element)?.stableKey ?? null)
+        .filter((value) => Boolean(value));
+    const validationReasonCodes = [
+        ...new Set(invalidControls.flatMap((element) => VALIDATION_REASON_KEYS
+            .filter((key) => element.validity[key])
+            .map((key) => toSnakeCase(key)))),
+    ].sort();
+    const validationMessages = invalidControls
+        .map((element) => element.validationMessage.trim())
+        .filter(Boolean)
+        .sort();
+    return {
+        invalidFieldCount: invalidControls.length,
+        invalidFieldStableKeys,
+        validationReasonCodes,
+        validationMessageFingerprint: validationMessages.length > 0
+            ? fingerprintText(validationMessages.join("|"))
+            : null,
+    };
+};
+export const startFormCapture = (context) => {
+    if (typeof document === "undefined") {
+        return { stop: () => undefined };
+    }
+    const submitHandler = (event) => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        const target = event.target;
+        if (!(target instanceof HTMLFormElement)) {
+            return;
+        }
+        if (context.shouldIgnoreElement?.(target)) {
+            return;
+        }
+        try {
+            const formKey = target.id ||
+                target.getAttribute("name") ||
+                null;
+            const rawSubmitter = event.submitter instanceof Element ? event.submitter : null;
+            const submitter = rawSubmitter
+                ? resolveClickDisplayTarget(rawSubmitter)
+                : null;
+            const submitterStableKey = submitter
+                ? resolveStableKeyDescriptor(submitter)
+                : null;
+            const validationEvidence = buildValidationEvidence(target);
+            const submitResult = validationEvidence.invalidFieldCount > 0
+                ? "validation_blocked"
+                : "unknown";
+            const resultSource = validationEvidence.invalidFieldCount > 0 ? "browser_validation" : null;
+            context.onEvent({
+                type: "form_submitted",
+                occurredAtMs: Date.now(),
+                payload: {
+                    viewId: context.getViewId(),
+                    formId: target.id || null,
+                    formKey,
+                    formName: target.getAttribute("name"),
+                    submitResult,
+                    resultSource,
+                    invalidFieldCount: validationEvidence.invalidFieldCount,
+                    invalidFieldStableKeys: validationEvidence.invalidFieldStableKeys,
+                    validationReasonCodes: validationEvidence.validationReasonCodes,
+                    validationMessageFingerprint: validationEvidence.validationMessageFingerprint,
+                    elementTag: submitter?.tagName.toLowerCase() ?? null,
+                    elementRole: submitter ? getElementRole(submitter) : null,
+                    stableKey: submitterStableKey?.stableKey ?? null,
+                    stableKeyQuality: submitterStableKey?.stableKeyQuality ?? null,
+                    elementId: submitter?.id || null,
+                    elementClass: submitter ? getElementClassList(submitter) : null,
+                    elementLabelMeta: buildLocalTextDescriptor(submitter ? getElementLabel(submitter) : null),
+                    ariaLabelMeta: buildLocalTextDescriptor(submitter ? getElementAriaLabel(submitter) : null),
+                    placeholderMeta: buildLocalTextDescriptor(submitter ? getElementPlaceholder(submitter) : null),
+                    clickTargetText: submitter ? getElementLabel(submitter) : null,
+                    clickTargetAriaLabel: submitter
+                        ? getElementAriaLabel(submitter)
+                        : null,
+                    clickTargetTitle: submitter?.getAttribute("title") || null,
+                    fieldName: submitter ? extractFieldName(submitter) : null,
+                    fieldType: submitter ? extractFieldType(submitter) : null,
+                    fieldDisplayLabel: submitter ? getElementLabel(submitter) : null,
+                    fieldAriaLabel: submitter
+                        ? getElementAriaLabel(submitter)
+                        : null,
+                    fieldPlaceholder: submitter
+                        ? getElementPlaceholder(submitter)
+                        : null,
+                    isEditable: submitter ? isEditableElement(submitter) : false,
+                    sectionHeading: getElementSectionHeading(target),
+                },
+            });
+        }
+        catch (error) {
+            context.onInternalError("capture/form:submit", error);
+        }
+    };
+    document.addEventListener("submit", submitHandler, true);
+    return {
+        stop: () => {
+            document.removeEventListener("submit", submitHandler, true);
+        },
+    };
+};

package/dist/capture/frustration.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureModuleContext, CaptureStopHandle } from "../core/types";
+export declare const startFrustrationCapture: (context: CaptureModuleContext) => CaptureStopHandle;

package/dist/capture/frustration.js

@@ -0,0 +1,171 @@
+import { buildLocalTextDescriptor } from "../privacy/local-minimization";
+import { getElementAriaLabel, getElementLabel, getElementPlaceholder, getElementRole, resolveClickDisplayTarget, resolveStableKeyDescriptor, } from "./dom";
+const CLICK_WINDOW_MS = 1200;
+const RAGE_CLICK_COUNT = 3;
+const RAGE_DISTANCE_PX = 24;
+const buildDomPath = (element) => {
+    const segments = [];
+    let current = element;
+    while (current && segments.length < 8) {
+        const tag = current.tagName.toLowerCase();
+        const id = current.id ? `#${current.id}` : "";
+        const className = typeof current.className === "string" && current.className.trim()
+            ? `.${current.className.trim().split(/\s+/).slice(0, 2).join(".")}`
+            : "";
+        segments.unshift(`${tag}${id}${className}`);
+        current = current.parentElement;
+    }
+    return segments.join(" > ");
+};
+const isLikelyInteractive = (element) => {
+    const interactiveTags = new Set([
+        "a",
+        "button",
+        "input",
+        "select",
+        "textarea",
+        "summary",
+    ]);
+    const tag = element.tagName.toLowerCase();
+    if (interactiveTags.has(tag)) {
+        return true;
+    }
+    if (element.getAttribute("role") === "button") {
+        return true;
+    }
+    if (element.hasAttribute("onclick")) {
+        return true;
+    }
+    return false;
+};
+const isLikelyErrorElement = (element) => {
+    if (element.getAttribute("aria-invalid") === "true") {
+        return true;
+    }
+    const cls = typeof element.className === "string"
+        ? element.className.toLowerCase()
+        : "";
+    return cls.includes("error") || cls.includes("invalid");
+};
+const isWithinDistance = (a, b) => {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    return dx * dx + dy * dy <= RAGE_DISTANCE_PX * RAGE_DISTANCE_PX;
+};
+export const startFrustrationCapture = (context) => {
+    if (typeof document === "undefined" || typeof window === "undefined") {
+        return { stop: () => undefined };
+    }
+    const clickSamples = [];
+    const timeoutHandles = new Set();
+    const clickHandler = (event) => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        const target = event.target;
+        if (!(target instanceof Element)) {
+            return;
+        }
+        if (context.shouldIgnoreElement?.(target)) {
+            return;
+        }
+        const displayTarget = resolveClickDisplayTarget(target);
+        if (context.shouldIgnoreElement?.(displayTarget)) {
+            return;
+        }
+        const now = Date.now();
+        const domPath = buildDomPath(displayTarget);
+        const sample = {
+            at: now,
+            x: event.clientX,
+            y: event.clientY,
+            domPath,
+        };
+        clickSamples.push(sample);
+        while (clickSamples.length > 0 &&
+            now - clickSamples[0].at > CLICK_WINDOW_MS) {
+            clickSamples.shift();
+        }
+        const recentOnSameTarget = clickSamples.filter((entry) => {
+            return (now - entry.at <= CLICK_WINDOW_MS &&
+                entry.domPath === domPath &&
+                isWithinDistance(entry, sample));
+        });
+        if (recentOnSameTarget.length >= RAGE_CLICK_COUNT) {
+            const stableKey = resolveStableKeyDescriptor(displayTarget);
+            context.onEvent({
+                type: "rage_click_detected",
+                occurredAtMs: now,
+                payload: {
+                    viewId: context.getViewId(),
+                    stableKey: stableKey.stableKey,
+                    stableKeyQuality: stableKey.stableKeyQuality,
+                    formKey: stableKey.formKey,
+                    elementTag: displayTarget.tagName.toLowerCase(),
+                    elementRole: getElementRole(displayTarget),
+                    elementLabelMeta: buildLocalTextDescriptor(getElementLabel(displayTarget)),
+                    ariaLabelMeta: buildLocalTextDescriptor(getElementAriaLabel(displayTarget)),
+                    placeholderMeta: buildLocalTextDescriptor(getElementPlaceholder(displayTarget)),
+                    repeatCount: recentOnSameTarget.length,
+                },
+            });
+        }
+        if (isLikelyErrorElement(displayTarget)) {
+            const stableKey = resolveStableKeyDescriptor(displayTarget);
+            context.onEvent({
+                type: "error_click_detected",
+                occurredAtMs: now,
+                payload: {
+                    viewId: context.getViewId(),
+                    stableKey: stableKey.stableKey,
+                    stableKeyQuality: stableKey.stableKeyQuality,
+                    formKey: stableKey.formKey,
+                    elementTag: displayTarget.tagName.toLowerCase(),
+                    elementRole: getElementRole(displayTarget),
+                    elementLabelMeta: buildLocalTextDescriptor(getElementLabel(displayTarget)),
+                    ariaLabelMeta: buildLocalTextDescriptor(getElementAriaLabel(displayTarget)),
+                    placeholderMeta: buildLocalTextDescriptor(getElementPlaceholder(displayTarget)),
+                    repeatCount: 1,
+                },
+            });
+        }
+        const locationBefore = window.location.href;
+        const activeBefore = document.activeElement;
+        const interactive = isLikelyInteractive(displayTarget);
+        const timeoutHandle = window.setTimeout(() => {
+            timeoutHandles.delete(timeoutHandle);
+            const noNavigation = window.location.href === locationBefore;
+            const noFocusChange = document.activeElement === activeBefore;
+            if (!interactive && noNavigation && noFocusChange) {
+                const stableKey = resolveStableKeyDescriptor(displayTarget);
+                context.onEvent({
+                    type: "dead_click_detected",
+                    occurredAtMs: Date.now(),
+                    payload: {
+                        viewId: context.getViewId(),
+                        stableKey: stableKey.stableKey,
+                        stableKeyQuality: stableKey.stableKeyQuality,
+                        formKey: stableKey.formKey,
+                        elementTag: displayTarget.tagName.toLowerCase(),
+                        elementRole: getElementRole(displayTarget),
+                        elementLabelMeta: buildLocalTextDescriptor(getElementLabel(displayTarget)),
+                        ariaLabelMeta: buildLocalTextDescriptor(getElementAriaLabel(displayTarget)),
+                        placeholderMeta: buildLocalTextDescriptor(getElementPlaceholder(displayTarget)),
+                        repeatCount: 1,
+                    },
+                });
+            }
+        }, 900);
+        timeoutHandles.add(timeoutHandle);
+    };
+    document.addEventListener("click", clickHandler, true);
+    return {
+        stop: () => {
+            document.removeEventListener("click", clickHandler, true);
+            for (const handle of timeoutHandles) {
+                window.clearTimeout(handle);
+            }
+            timeoutHandles.clear();
+        },
+    };
+};

package/dist/capture/input.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureModuleContext, CaptureStopHandle } from "../core/types";
+export declare const startInputCapture: (context: CaptureModuleContext) => CaptureStopHandle;

package/dist/capture/input.js

@@ -0,0 +1,109 @@
+import { buildLocalTextDescriptor, buildLocalValueDescriptor, } from "../privacy/local-minimization";
+import { extractFieldName, extractFieldType, getElementAriaLabel, getElementLabel, getElementPlaceholder, getElementRole, getElementSectionHeading, getElementValue, resolveStableKeyDescriptor, } from "./dom";
+const buildFileDescriptors = (input) => {
+    const files = input.files ? Array.from(input.files) : [];
+    return files.map((file) => ({
+        mimeType: file.type || null,
+        size: file.size,
+    }));
+};
+export const startInputCapture = (context) => {
+    if (typeof document === "undefined") {
+        return { stop: () => undefined };
+    }
+    const changeHandler = (event) => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        const target = event.target;
+        if (!(target instanceof HTMLInputElement) &&
+            !(target instanceof HTMLTextAreaElement) &&
+            !(target instanceof HTMLSelectElement)) {
+            return;
+        }
+        if (context.shouldIgnoreElement?.(target)) {
+            return;
+        }
+        try {
+            const stableKey = resolveStableKeyDescriptor(target);
+            const commonPayload = {
+                viewId: context.getViewId(),
+                formId: stableKey.formKey,
+                formKey: stableKey.formKey,
+                fieldType: extractFieldType(target),
+                elementTag: target.tagName.toLowerCase(),
+                elementRole: getElementRole(target),
+                stableKey: stableKey.stableKey,
+                stableKeyQuality: stableKey.stableKeyQuality,
+                fieldNameMeta: buildLocalTextDescriptor(extractFieldName(target)),
+                elementLabelMeta: buildLocalTextDescriptor(getElementLabel(target)),
+                ariaLabelMeta: buildLocalTextDescriptor(getElementAriaLabel(target)),
+                placeholderMeta: buildLocalTextDescriptor(getElementPlaceholder(target)),
+                fieldName: extractFieldName(target),
+                fieldDisplayLabel: getElementLabel(target),
+                fieldAriaLabel: getElementAriaLabel(target),
+                fieldPlaceholder: getElementPlaceholder(target),
+                sectionHeading: getElementSectionHeading(target),
+            };
+            if (target instanceof HTMLInputElement &&
+                (target.type === "checkbox" || target.type === "radio")) {
+                context.onEvent({
+                    type: "toggle_changed",
+                    occurredAtMs: Date.now(),
+                    payload: {
+                        ...commonPayload,
+                        checked: target.checked,
+                        inputValueMeta: buildLocalValueDescriptor(target.value),
+                    },
+                });
+                return;
+            }
+            if (target instanceof HTMLSelectElement) {
+                const selectedValues = Array.from(target.selectedOptions).map((option) => option.value);
+                context.onEvent({
+                    type: "selection_committed",
+                    occurredAtMs: Date.now(),
+                    payload: {
+                        ...commonPayload,
+                        selectedCount: selectedValues.length,
+                        selectedValueMeta: buildLocalValueDescriptor(selectedValues),
+                    },
+                });
+                return;
+            }
+            if (target instanceof HTMLInputElement && target.type === "file") {
+                const fileDescriptors = buildFileDescriptors(target);
+                context.onEvent({
+                    type: "file_selected",
+                    occurredAtMs: Date.now(),
+                    payload: {
+                        ...commonPayload,
+                        fileCount: fileDescriptors.length,
+                        fileSelectionMeta: buildLocalValueDescriptor({
+                            fileCount: fileDescriptors.length,
+                        }),
+                        fileDescriptors,
+                    },
+                });
+                return;
+            }
+            context.onEvent({
+                type: "input_committed",
+                occurredAtMs: Date.now(),
+                payload: {
+                    ...commonPayload,
+                    inputValueMeta: buildLocalValueDescriptor(getElementValue(target)),
+                },
+            });
+        }
+        catch (error) {
+            context.onInternalError("capture/input:change", error);
+        }
+    };
+    document.addEventListener("change", changeHandler, true);
+    return {
+        stop: () => {
+            document.removeEventListener("change", changeHandler, true);
+        },
+    };
+};

package/dist/capture/location.d.ts

@@ -0,0 +1,10 @@
+type PageSnapshot = {
+    url: string | null;
+    path: string | null;
+    screenKey: string | null;
+    urlCanonical: string | null;
+    pageTitleCandidate: string | null;
+    primaryHeadingCandidate: string | null;
+};
+export declare const getCurrentPageSnapshot: () => PageSnapshot;
+export {};

package/dist/capture/location.js

@@ -0,0 +1,42 @@
+const buildUrlCanonical = (href) => {
+    if (!href) {
+        return null;
+    }
+    try {
+        const url = new URL(href, globalThis.location?.origin);
+        return `${url.origin}${url.pathname}`;
+    }
+    catch {
+        return null;
+    }
+};
+const readPrimaryHeadingCandidate = (documentRef) => {
+    const heading = documentRef.querySelector("h1, main h1, [role='heading'][aria-level='1']");
+    if (!(heading instanceof Element)) {
+        return null;
+    }
+    const text = heading.textContent?.replace(/\s+/g, " ").trim() ?? "";
+    return text.length > 0 ? text.slice(0, 120) : null;
+};
+export const getCurrentPageSnapshot = () => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+        return {
+            url: null,
+            path: null,
+            screenKey: null,
+            urlCanonical: null,
+            pageTitleCandidate: null,
+            primaryHeadingCandidate: null,
+        };
+    }
+    const url = window.location.href;
+    const path = window.location.pathname || "/";
+    return {
+        url,
+        path,
+        screenKey: path,
+        urlCanonical: buildUrlCanonical(url),
+        pageTitleCandidate: document.title || null,
+        primaryHeadingCandidate: readPrimaryHeadingCandidate(document),
+    };
+};

package/dist/capture/navigation.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureModuleContext, CaptureStopHandle } from "../core/types";
+export declare const startNavigationCapture: (context: CaptureModuleContext) => CaptureStopHandle;

package/dist/capture/navigation.js

@@ -0,0 +1,100 @@
+import { generateViewId } from "../normalize/event-id";
+import { getCurrentPageSnapshot } from "./location";
+export const startNavigationCapture = (context) => {
+    if (typeof window === "undefined") {
+        return { stop: () => undefined };
+    }
+    let currentSnapshot = getCurrentPageSnapshot();
+    let currentViewId = context.getViewId();
+    let viewEnteredAtMs = Date.now();
+    const emitRouteChange = () => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        const nextSnapshot = getCurrentPageSnapshot();
+        if (nextSnapshot.path === currentSnapshot.path) {
+            return;
+        }
+        const now = Date.now();
+        const previousViewId = currentViewId;
+        const nextViewId = generateViewId();
+        context.onEvent({
+            type: "page_leave",
+            occurredAtMs: now,
+            payload: {
+                viewId: previousViewId,
+                screenKey: currentSnapshot.screenKey,
+                path: currentSnapshot.path,
+                timeOnPageMs: Math.max(0, now - viewEnteredAtMs),
+            },
+        });
+        context.onEvent({
+            type: "route_change",
+            occurredAtMs: now,
+            payload: {
+                fromViewId: previousViewId,
+                toViewId: nextViewId,
+                fromScreenKey: currentSnapshot.screenKey,
+                toScreenKey: nextSnapshot.screenKey,
+                fromPath: currentSnapshot.path,
+                toPath: nextSnapshot.path,
+            },
+        });
+        context.onEvent({
+            type: "page_view",
+            occurredAtMs: now,
+            payload: {
+                viewId: nextViewId,
+                screenKey: nextSnapshot.screenKey,
+                path: nextSnapshot.path,
+                urlCanonical: nextSnapshot.urlCanonical,
+                pageTitleCandidate: nextSnapshot.pageTitleCandidate,
+                routeNameCandidate: null,
+                primaryHeadingCandidate: nextSnapshot.primaryHeadingCandidate,
+            },
+        });
+        currentViewId = nextViewId;
+        currentSnapshot = nextSnapshot;
+        viewEnteredAtMs = now;
+    };
+    const originalPushState = history.pushState;
+    const originalReplaceState = history.replaceState;
+    const wrappedPushState = function (...args) {
+        const result = originalPushState.apply(this, args);
+        try {
+            emitRouteChange();
+        }
+        catch (error) {
+            context.onInternalError("capture/navigation:pushState", error);
+        }
+        return result;
+    };
+    const wrappedReplaceState = function (...args) {
+        const result = originalReplaceState.apply(this, args);
+        try {
+            emitRouteChange();
+        }
+        catch (error) {
+            context.onInternalError("capture/navigation:replaceState", error);
+        }
+        return result;
+    };
+    history.pushState = wrappedPushState;
+    history.replaceState = wrappedReplaceState;
+    const popstateHandler = () => {
+        try {
+            emitRouteChange();
+        }
+        catch (error) {
+            context.onInternalError("capture/navigation:popstate", error);
+        }
+    };
+    window.addEventListener("popstate", popstateHandler, true);
+    return {
+        stop: () => {
+            history.pushState = originalPushState;
+            history.replaceState = originalReplaceState;
+            window.removeEventListener("popstate", popstateHandler, true);
+        },
+    };
+};

package/dist/capture/network.d.ts

@@ -0,0 +1,13 @@
+import type { CaptureModuleContext, CaptureStopHandle } from "../core/types";
+export declare const startNetworkCapture: (context: CaptureModuleContext, options?: {
+    ignoreUrlPrefixes?: string[];
+    tracePropagationOrigins?: string[];
+    important4xxPathPrefixes?: string[];
+    createRequestTraceContext?: () => {
+        traceId: string;
+        parentSpanId: string | null;
+        requestId: string;
+        requestSpanId: string;
+        interactionId: string | null;
+    };
+}) => CaptureStopHandle;