@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/instrumentation/drag.js

@@ -0,0 +1,82 @@
+import { buildLocalValueDescriptor } from "../exporter/local-minimization.js";
+import { extractFieldName, extractFieldType, getElementAriaLabel, getElementLabel, getElementPlaceholder, getElementRole, getElementSectionHeading, resolveInteractionScopeDescriptor, resolveStableKeyDescriptor, } from "./dom.js";
+import { buildScreenActionNamingEvidence } from "./naming-evidence.js";
+const readDragPayload = (event) => {
+    const dataTransfer = event.dataTransfer;
+    if (!dataTransfer) {
+        return {
+            itemCount: 0,
+            fileCount: 0,
+            dragTypes: [],
+        };
+    }
+    const itemCount = dataTransfer.items?.length ?? 0;
+    const fileCount = dataTransfer.files?.length ?? 0;
+    const dragTypes = Array.from(dataTransfer.types ?? []).filter(Boolean);
+    return {
+        itemCount,
+        fileCount,
+        dragTypes,
+    };
+};
+export const startDragCapture = (context) => {
+    if (typeof document === "undefined") {
+        return { stop: () => undefined };
+    }
+    // Drop payload summaries are retained as Cluebase-only UX evidence; accepted
+    // browser OTel instrumentation does not expose this committed drop signal.
+    const dropHandler = (event) => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        const target = event.target;
+        if (!(target instanceof Element)) {
+            return;
+        }
+        if (context.shouldIgnoreElement?.(target)) {
+            return;
+        }
+        try {
+            const stableKey = resolveStableKeyDescriptor(target);
+            const interactionScope = resolveInteractionScopeDescriptor(target);
+            const dragPayload = readDragPayload(event);
+            context.onEvent({
+                type: "drag_drop_completed",
+                occurredAtMs: Date.now(),
+                payload: {
+                    viewId: context.getViewId(),
+                    elementTag: target.tagName.toLowerCase(),
+                    elementRole: getElementRole(target),
+                    stableKey: stableKey.stableKey,
+                    stableKeyQuality: stableKey.stableKeyQuality,
+                    formKey: stableKey.formKey,
+                    interactionScopeKind: interactionScope?.interactionScopeKind ?? null,
+                    interactionScopeKey: interactionScope?.interactionScopeKey ?? null,
+                    fieldNameMeta: buildLocalValueDescriptor(extractFieldName(target)),
+                    elementLabelMeta: buildLocalValueDescriptor(getElementLabel(target)),
+                    ariaLabelMeta: buildLocalValueDescriptor(getElementAriaLabel(target)),
+                    placeholderMeta: buildLocalValueDescriptor(getElementPlaceholder(target)),
+                    fieldName: extractFieldName(target),
+                    fieldType: extractFieldType(target),
+                    fieldDisplayLabel: getElementLabel(target),
+                    fieldAriaLabel: getElementAriaLabel(target),
+                    fieldPlaceholder: getElementPlaceholder(target),
+                    sectionHeading: getElementSectionHeading(target),
+                    ...buildScreenActionNamingEvidence(target),
+                    dragItemCount: dragPayload.itemCount,
+                    fileCount: dragPayload.fileCount,
+                    dragTypes: dragPayload.dragTypes,
+                },
+            });
+        }
+        catch (error) {
+            context.onInternalError("capture/drag:drop", error);
+        }
+    };
+    document.addEventListener("drop", dropHandler, true);
+    return {
+        stop: () => {
+            document.removeEventListener("drop", dropHandler, true);
+        },
+    };
+};

package/dist/instrumentation/error.d.ts

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

package/dist/instrumentation/error.js

@@ -0,0 +1,318 @@
+import { ErrorsInstrumentation } from "@opentelemetry/browser-instrumentation/experimental/errors";
+const ERROR_BURST_DEBOUNCE_MS = 250;
+const EXCEPTION_EVENT_NAME = "exception";
+const ATTR_EXCEPTION_TYPE = "exception.type";
+const ATTR_EXCEPTION_MESSAGE = "exception.message";
+const ATTR_EXCEPTION_STACKTRACE = "exception.stacktrace";
+const ATTR_CLUEBASE_ERROR_EVENT_TYPE = "cluebase.error.event_type";
+const ATTR_CLUEBASE_ERROR_FINGERPRINT = "cluebase.error.fingerprint";
+const ATTR_CLUEBASE_ERROR_SOURCE_FILE = "cluebase.error.source_file";
+const ATTR_CLUEBASE_ERROR_SOURCE_FILE_HINT = "cluebase.error.source_file_hint";
+const ATTR_CLUEBASE_ERROR_LINE_NUMBER = "cluebase.error.line_number";
+const ATTR_CLUEBASE_ERROR_COLUMN_NUMBER = "cluebase.error.column_number";
+const hashString = (value) => {
+    let hash = 2166136261;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return `err_${(hash >>> 0).toString(16).padStart(8, "0")}`;
+};
+const sourceFileHintFromValue = (value) => {
+    if (!value) {
+        return null;
+    }
+    try {
+        const resolved = new URL(value, globalThis.location?.origin);
+        const segments = resolved.pathname.split("/").filter(Boolean);
+        return segments[segments.length - 1] ?? null;
+    }
+    catch {
+        const normalized = value.split(/[?#]/, 1)[0] ?? value;
+        const segments = normalized.split("/").filter(Boolean);
+        return segments[segments.length - 1] ?? (normalized || null);
+    }
+};
+const firstStackLine = (stack) => stack
+    ?.split("\n")
+    .map((line) => line.trim())
+    .find(Boolean) ?? "";
+const buildFingerprint = (input) => {
+    return hashString([
+        input.type,
+        input.errorType ?? "",
+        input.message ?? "",
+        sourceFileHintFromValue(input.sourceFile) ?? "",
+        input.lineNumber ?? "",
+        input.columnNumber ?? "",
+        firstStackLine(input.stack),
+    ].join("|"));
+};
+const readStringAttribute = (logRecord, key) => {
+    const value = logRecord.attributes?.[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+};
+const readNumberAttribute = (logRecord, key) => {
+    const value = logRecord.attributes?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+};
+export const startErrorCapture = (context) => {
+    if (typeof window === "undefined") {
+        return { stop: () => undefined };
+    }
+    const pendingByFingerprint = new Map();
+    const errorMetadata = new WeakMap();
+    const flushFingerprint = (fingerprint) => {
+        const bucket = pendingByFingerprint.get(fingerprint);
+        if (!bucket) {
+            return;
+        }
+        if (bucket.timer) {
+            clearTimeout(bucket.timer);
+        }
+        context.onEvent({
+            type: bucket.event.type,
+            occurredAtMs: bucket.lastOccurredAtMs,
+            payload: {
+                ...bucket.event.payload,
+                repeatCount: bucket.repeatCount,
+            },
+        });
+        pendingByFingerprint.delete(fingerprint);
+    };
+    const scheduleFlush = (fingerprint) => {
+        const bucket = pendingByFingerprint.get(fingerprint);
+        if (!bucket) {
+            return;
+        }
+        if (bucket.timer) {
+            clearTimeout(bucket.timer);
+        }
+        bucket.timer = setTimeout(() => {
+            flushFingerprint(fingerprint);
+        }, ERROR_BURST_DEBOUNCE_MS);
+    };
+    const queueErrorEnvelope = (type, occurredAtMs, payload) => {
+        const fingerprint = payload.errorFingerprint;
+        if (!fingerprint) {
+            context.onEvent({
+                type,
+                occurredAtMs,
+                payload: {
+                    ...payload,
+                    repeatCount: 1,
+                },
+            });
+            return;
+        }
+        const existing = pendingByFingerprint.get(fingerprint);
+        if (existing) {
+            existing.repeatCount += 1;
+            existing.lastOccurredAtMs = occurredAtMs;
+            existing.event.payload = {
+                ...existing.event.payload,
+                ...payload,
+            };
+            scheduleFlush(fingerprint);
+            return;
+        }
+        pendingByFingerprint.set(fingerprint, {
+            event: {
+                type,
+                occurredAtMs,
+                payload,
+            },
+            repeatCount: 1,
+            lastOccurredAtMs: occurredAtMs,
+            timer: null,
+        });
+        scheduleFlush(fingerprint);
+    };
+    const rememberErrorEventMetadata = (event) => {
+        if (event.error instanceof Error) {
+            errorMetadata.set(event.error, {
+                sourceFile: event.filename || null,
+                lineNumber: event.lineno || undefined,
+                columnNumber: event.colno || undefined,
+            });
+        }
+    };
+    const buildCluebaseErrorAttributes = (error) => {
+        if (context.getConsent() === "denied") {
+            return {};
+        }
+        const metadata = error instanceof Error ? errorMetadata.get(error) : undefined;
+        const type = metadata ? "frontend_error" : "unhandled_rejection";
+        const errorType = error instanceof Error ? error.name : "PromiseRejection";
+        const message = error instanceof Error ? error.message : error;
+        const stack = error instanceof Error ? (error.stack ?? null) : null;
+        const sourceFile = metadata?.sourceFile ?? null;
+        const fingerprint = buildFingerprint({
+            type,
+            errorType,
+            message,
+            sourceFile,
+            lineNumber: metadata?.lineNumber,
+            columnNumber: metadata?.columnNumber,
+            stack,
+        });
+        const attributes = {
+            [ATTR_CLUEBASE_ERROR_EVENT_TYPE]: type,
+            [ATTR_CLUEBASE_ERROR_FINGERPRINT]: fingerprint,
+        };
+        if (!(error instanceof Error)) {
+            attributes[ATTR_EXCEPTION_TYPE] = errorType;
+            attributes[ATTR_EXCEPTION_MESSAGE] = message;
+        }
+        const sourceFileHint = sourceFileHintFromValue(sourceFile);
+        if (sourceFile) {
+            attributes[ATTR_CLUEBASE_ERROR_SOURCE_FILE] = sourceFile;
+        }
+        if (sourceFileHint) {
+            attributes[ATTR_CLUEBASE_ERROR_SOURCE_FILE_HINT] = sourceFileHint;
+        }
+        if (metadata?.lineNumber !== undefined) {
+            attributes[ATTR_CLUEBASE_ERROR_LINE_NUMBER] = metadata.lineNumber;
+        }
+        if (metadata?.columnNumber !== undefined) {
+            attributes[ATTR_CLUEBASE_ERROR_COLUMN_NUMBER] = metadata.columnNumber;
+        }
+        return attributes;
+    };
+    const emitFromOtelLogRecord = (logRecord) => {
+        if (logRecord.eventName !== EXCEPTION_EVENT_NAME ||
+            context.getConsent() === "denied") {
+            return;
+        }
+        const type = readStringAttribute(logRecord, ATTR_CLUEBASE_ERROR_EVENT_TYPE) ??
+            "unhandled_rejection";
+        if (type !== "frontend_error" && type !== "unhandled_rejection") {
+            return;
+        }
+        const errorType = readStringAttribute(logRecord, ATTR_EXCEPTION_TYPE) ?? "Error";
+        const message = readStringAttribute(logRecord, ATTR_EXCEPTION_MESSAGE);
+        const stack = readStringAttribute(logRecord, ATTR_EXCEPTION_STACKTRACE);
+        const sourceFile = readStringAttribute(logRecord, ATTR_CLUEBASE_ERROR_SOURCE_FILE);
+        const sourceFileHint = readStringAttribute(logRecord, ATTR_CLUEBASE_ERROR_SOURCE_FILE_HINT) ??
+            sourceFileHintFromValue(sourceFile);
+        const lineNumber = readNumberAttribute(logRecord, ATTR_CLUEBASE_ERROR_LINE_NUMBER);
+        const columnNumber = readNumberAttribute(logRecord, ATTR_CLUEBASE_ERROR_COLUMN_NUMBER);
+        const fingerprint = readStringAttribute(logRecord, ATTR_CLUEBASE_ERROR_FINGERPRINT) ??
+            buildFingerprint({
+                type,
+                errorType,
+                message,
+                sourceFile,
+                lineNumber,
+                columnNumber,
+                stack,
+            });
+        const occurredAtMs = Date.now();
+        queueErrorEnvelope(type, occurredAtMs, {
+            viewId: context.getViewId(),
+            errorType,
+            errorFingerprint: fingerprint,
+            sourceFileHint,
+            message,
+            stack,
+            sourceFile,
+            lineNumber,
+            columnNumber,
+        });
+    };
+    const flushAllPending = () => {
+        const fingerprints = Array.from(pendingByFingerprint.keys());
+        for (const fingerprint of fingerprints) {
+            try {
+                flushFingerprint(fingerprint);
+            }
+            catch (error) {
+                context.onInternalError("capture/error:flush", error);
+            }
+        }
+    };
+    const pagehideHandler = () => {
+        flushAllPending();
+    };
+    const visibilityHandler = () => {
+        if (document.visibilityState === "hidden") {
+            flushAllPending();
+        }
+    };
+    const fallbackErrorHandler = (event) => {
+        if (context.getConsent() === "denied" ||
+            event.error instanceof Error ||
+            event.error != null) {
+            return;
+        }
+        if (event.target instanceof Element && !event.message) {
+            return;
+        }
+        const message = event.message || null;
+        const sourceFile = event.filename || null;
+        const lineNumber = event.lineno || undefined;
+        const columnNumber = event.colno || undefined;
+        const errorType = "ErrorEvent";
+        const fingerprint = buildFingerprint({
+            type: "frontend_error",
+            errorType,
+            message,
+            sourceFile,
+            lineNumber,
+            columnNumber,
+            stack: null,
+        });
+        queueErrorEnvelope("frontend_error", Date.now(), {
+            viewId: context.getViewId(),
+            errorType,
+            errorFingerprint: fingerprint,
+            sourceFileHint: sourceFileHintFromValue(sourceFile),
+            message,
+            stack: null,
+            sourceFile,
+            lineNumber,
+            columnNumber,
+        });
+    };
+    window.addEventListener("error", rememberErrorEventMetadata, true);
+    window.addEventListener("error", fallbackErrorHandler, true);
+    window.addEventListener("pagehide", pagehideHandler, true);
+    document.addEventListener("visibilitychange", visibilityHandler, true);
+    const instrumentation = new ErrorsInstrumentation({
+        applyCustomAttributes: (error) => {
+            try {
+                return buildCluebaseErrorAttributes(error);
+            }
+            catch (cause) {
+                context.onInternalError("capture/error:otel", cause);
+                return {};
+            }
+        },
+    });
+    const logger = {
+        enabled: () => true,
+        emit: (logRecord) => {
+            try {
+                emitFromOtelLogRecord(logRecord);
+            }
+            catch (cause) {
+                context.onInternalError("capture/error:otel", cause);
+            }
+        },
+    };
+    const loggerProvider = {
+        getLogger: () => logger,
+    };
+    instrumentation.setLoggerProvider(loggerProvider);
+    instrumentation.enable();
+    return {
+        stop: () => {
+            flushAllPending();
+            instrumentation.disable();
+            window.removeEventListener("error", rememberErrorEventMetadata, true);
+            window.removeEventListener("error", fallbackErrorHandler, true);
+            window.removeEventListener("pagehide", pagehideHandler, true);
+            document.removeEventListener("visibilitychange", visibilityHandler, true);
+        },
+    };
+};

package/dist/instrumentation/form.d.ts

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

package/dist/instrumentation/form.js

@@ -0,0 +1,132 @@
+import { buildLocalTextDescriptor } from "../exporter/local-minimization.js";
+import { extractFieldName, extractFieldType, getElementAriaLabel, getElementClassList, getElementLabel, getElementPlaceholder, getElementRole, getElementSectionHeading, isEditableElement, resolveClickDisplayTarget, resolveInteractionScopeDescriptor, resolveStableKeyDescriptor, } from "./dom.js";
+import { buildPrimaryActionKey } from "./common.js";
+import { getCurrentPageSnapshot } from "./location.js";
+import { buildScreenActionNamingEvidence } from "./naming-evidence.js";
+import { fingerprintText } from "../exporter/text-fingerprint.js";
+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 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 };
+    }
+    // OTel browser user-action covers the submitter click; this retains
+    // Cluebase-only form validation outcome evidence that OTel does not provide.
+    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 interactionScope = resolveInteractionScopeDescriptor(target);
+            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,
+                    primaryActionKey: buildPrimaryActionKey(getCurrentPageSnapshot().screenKey, formKey ?? submitterStableKey?.stableKey ?? null),
+                    formName: target.getAttribute("name"),
+                    interactionScopeKind: interactionScope?.interactionScopeKind ?? null,
+                    interactionScopeKey: interactionScope?.interactionScopeKey ?? null,
+                    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),
+                    ...buildScreenActionNamingEvidence(submitter ?? target),
+                },
+            });
+        }
+        catch (error) {
+            context.onInternalError("capture/form:submit", error);
+        }
+    };
+    document.addEventListener("submit", submitHandler, true);
+    return {
+        stop: () => {
+            document.removeEventListener("submit", submitHandler, true);
+        },
+    };
+};

package/dist/instrumentation/input.d.ts

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