@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/instrumentation/input.js

@@ -0,0 +1,180 @@
+import { buildLocalTextDescriptor, buildLocalValueDescriptor, } from "../exporter/local-minimization.js";
+import { extractFieldName, extractFieldType, getElementAriaLabel, getElementLabel, getElementPlaceholder, getElementRole, getElementSectionHeading, getElementValue, resolveInteractionScopeDescriptor, resolveStableKeyDescriptor, } from "./dom.js";
+import { buildPrimaryActionKey } from "./common.js";
+import { getCurrentPageSnapshot } from "./location.js";
+import { buildScreenActionNamingEvidence } from "./naming-evidence.js";
+const buildFileDescriptors = (input) => {
+    const files = input.files ? Array.from(input.files) : [];
+    return files.map((file) => ({
+        mimeType: file.type || null,
+        size: file.size,
+    }));
+};
+const isInputCaptureElement = (target) => target instanceof HTMLInputElement ||
+    target instanceof HTMLTextAreaElement ||
+    target instanceof HTMLSelectElement;
+const isDeferredCommitElement = (target) => (target instanceof HTMLInputElement &&
+    target.type !== "checkbox" &&
+    target.type !== "radio" &&
+    target.type !== "file" &&
+    target.type !== "password") ||
+    target instanceof HTMLTextAreaElement;
+export const startInputCapture = (context) => {
+    if (typeof document === "undefined") {
+        return { stop: () => undefined };
+    }
+    const dirtyControls = new Set();
+    // OTel user-action covers discrete clicks; committed field values,
+    // selections, toggles, and file counts are Cluebase-only UX evidence.
+    const emitCommit = (target) => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        if (context.shouldIgnoreElement?.(target)) {
+            return;
+        }
+        if (target instanceof HTMLInputElement && target.type === "password") {
+            return;
+        }
+        try {
+            const stableKey = resolveStableKeyDescriptor(target);
+            const interactionScope = resolveInteractionScopeDescriptor(target);
+            const commonPayload = {
+                viewId: context.getViewId(),
+                formId: stableKey.formKey,
+                formKey: stableKey.formKey,
+                fieldType: extractFieldType(target),
+                elementTag: target.tagName.toLowerCase(),
+                elementRole: getElementRole(target),
+                primaryActionKey: buildPrimaryActionKey(getCurrentPageSnapshot().screenKey, stableKey.stableKey),
+                stableKey: stableKey.stableKey,
+                stableKeyQuality: stableKey.stableKeyQuality,
+                interactionScopeKind: interactionScope?.interactionScopeKind ?? null,
+                interactionScopeKey: interactionScope?.interactionScopeKey ?? null,
+                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),
+                ...buildScreenActionNamingEvidence(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 selectedOptions = Array.from(target.selectedOptions);
+                const selectedValues = selectedOptions.map((option) => option.value);
+                const selectedOptionLabels = selectedOptions
+                    .map((option) => (option.label || option.textContent || "").replace(/\s+/g, " ").trim())
+                    .filter((value) => value.length > 0);
+                context.onEvent({
+                    type: "selection_committed",
+                    occurredAtMs: Date.now(),
+                    payload: {
+                        ...commonPayload,
+                        selectedCount: selectedValues.length,
+                        selectedOptionLabels,
+                        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)),
+                },
+            });
+            if (isDeferredCommitElement(target)) {
+                dirtyControls.delete(target);
+            }
+        }
+        catch (error) {
+            context.onInternalError("capture/input:change", error);
+        }
+    };
+    const inputHandler = (event) => {
+        const target = event.target;
+        if (!isInputCaptureElement(target)) {
+            return;
+        }
+        if (!isDeferredCommitElement(target)) {
+            return;
+        }
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        if (context.shouldIgnoreElement?.(target)) {
+            return;
+        }
+        dirtyControls.add(target);
+    };
+    const changeHandler = (event) => {
+        const target = event.target;
+        if (!isInputCaptureElement(target)) {
+            return;
+        }
+        emitCommit(target);
+    };
+    const flushDirtyControls = () => {
+        for (const target of Array.from(dirtyControls)) {
+            if (!target.isConnected) {
+                dirtyControls.delete(target);
+                continue;
+            }
+            emitCommit(target);
+        }
+    };
+    const visibilityHandler = () => {
+        if (document.visibilityState === "hidden") {
+            flushDirtyControls();
+        }
+    };
+    document.addEventListener("change", changeHandler, true);
+    document.addEventListener("input", inputHandler, true);
+    document.addEventListener("visibilitychange", visibilityHandler, true);
+    window.addEventListener("pagehide", flushDirtyControls, true);
+    window.addEventListener("beforeunload", flushDirtyControls, true);
+    return {
+        stop: () => {
+            document.removeEventListener("change", changeHandler, true);
+            document.removeEventListener("input", inputHandler, true);
+            document.removeEventListener("visibilitychange", visibilityHandler, true);
+            window.removeEventListener("pagehide", flushDirtyControls, true);
+            window.removeEventListener("beforeunload", flushDirtyControls, true);
+            dirtyControls.clear();
+        },
+    };
+};

package/dist/instrumentation/location.d.ts

@@ -0,0 +1,11 @@
+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 declare const getPageSnapshotFromUrl: (href: string | null) => PageSnapshot;
+export {};

package/dist/instrumentation/location.js

@@ -0,0 +1,69 @@
+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),
+    };
+};
+export const getPageSnapshotFromUrl = (href) => {
+    if (typeof document === "undefined") {
+        return {
+            url: href,
+            path: null,
+            screenKey: null,
+            urlCanonical: buildUrlCanonical(href),
+            pageTitleCandidate: null,
+            primaryHeadingCandidate: null,
+        };
+    }
+    let path = null;
+    try {
+        path = href ? new URL(href, globalThis.location?.origin).pathname || "/" : null;
+    }
+    catch {
+        path = null;
+    }
+    return {
+        url: href,
+        path,
+        screenKey: path,
+        urlCanonical: buildUrlCanonical(href),
+        pageTitleCandidate: document.title || null,
+        primaryHeadingCandidate: readPrimaryHeadingCandidate(document),
+    };
+};

package/dist/instrumentation/naming-evidence.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 画面上の操作が**何なのか**を後段が言い当てるための材料。
+ *
+ * 名付ける相手は、押された要素そのものを見られません。ここで採らなかったものは
+ * 「無かった」のと同じになります。実測では、要素の鍵だけを渡した押下が
+ * `execute_primary_action` / 確信度 0.18 になりました。
+ *
+ * 文言 (名前・題・行き先) は顧客が書いたもので、個人に結び付く値が混ざり得ます。
+ * 伏せるかどうかは受付側が顧客の設定 1 本で決めるので、ここでは伏せません。
+ * **文言が伏せられても、役割・祖先の並び・安定した識別子だけで慎重な一般名が
+ * 作れる**ように、機械が決めた値を必ず一緒に載せます。
+ */
+export type ScreenActionNamingEvidence = {
+    accessibleName: string | null;
+    accessibleNameSource: string | null;
+    ancestorChain: string | null;
+    documentTitle: string | null;
+    navigationHref: string | null;
+};
+export declare const buildScreenActionNamingEvidence: (element: Element) => ScreenActionNamingEvidence;

package/dist/instrumentation/naming-evidence.js

@@ -0,0 +1,11 @@
+import { getAccessibleName, getAncestorChain, getDocumentTitle, getNavigationHref, } from "./dom.js";
+export const buildScreenActionNamingEvidence = (element) => {
+    const accessibleName = getAccessibleName(element);
+    return {
+        accessibleName: accessibleName?.name ?? null,
+        accessibleNameSource: accessibleName?.source ?? null,
+        ancestorChain: getAncestorChain(element),
+        documentTitle: getDocumentTitle(element),
+        navigationHref: getNavigationHref(element),
+    };
+};

package/dist/instrumentation/navigation.d.ts

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

package/dist/instrumentation/navigation.js

@@ -0,0 +1,144 @@
+import { NavigationInstrumentation } from "@opentelemetry/browser-instrumentation/experimental/navigation";
+import { generateViewId } from "../exporter/event-id.js";
+import { getCurrentPageSnapshot, getPageSnapshotFromUrl } from "./location.js";
+const readStringAttribute = (attributes, key) => {
+    const value = attributes?.[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+};
+const readBooleanAttribute = (attributes, key) => {
+    const value = attributes?.[key];
+    return typeof value === "boolean" ? value : null;
+};
+const sanitizeNavigationUrl = (value) => {
+    try {
+        const url = new URL(value, globalThis.location?.origin);
+        url.search = "";
+        url.hash = "";
+        return url.toString();
+    }
+    catch {
+        return value.split(/[?#]/, 1)[0] ?? value;
+    }
+};
+export const startNavigationCapture = (context) => {
+    if (typeof window === "undefined") {
+        return { stop: () => undefined };
+    }
+    let currentSnapshot = getCurrentPageSnapshot();
+    let currentViewId = context.getViewId();
+    let viewEnteredAtMs = Date.now();
+    let initialPageViewEmitted = false;
+    const emitInitialPageView = (destinationUrl) => {
+        if (initialPageViewEmitted || context.getConsent() === "denied") {
+            return;
+        }
+        const snapshot = getPageSnapshotFromUrl(destinationUrl);
+        const viewId = context.getViewId();
+        const now = Date.now();
+        context.onEvent({
+            type: "page_view",
+            occurredAtMs: now,
+            payload: {
+                viewId,
+                screenKey: snapshot.screenKey,
+                path: snapshot.path,
+                urlCanonical: snapshot.urlCanonical,
+                pageTitleCandidate: snapshot.pageTitleCandidate,
+                routeNameCandidate: null,
+                primaryHeadingCandidate: snapshot.primaryHeadingCandidate,
+            },
+        });
+        initialPageViewEmitted = true;
+        currentSnapshot = snapshot;
+        currentViewId = viewId;
+        viewEnteredAtMs = now;
+    };
+    const emitRouteChange = (destinationUrl) => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        const nextSnapshot = getPageSnapshotFromUrl(destinationUrl);
+        if (!nextSnapshot.path || 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,
+                // 離脱イベントは遷移後に送られるため、周囲の文脈から URL を取ると
+                // 次の画面を指す。離れた画面自身の URL を payload で名乗る。
+                urlCanonical: currentSnapshot.urlCanonical,
+                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;
+        context.requestFlush?.();
+    };
+    const instrumentation = new NavigationInstrumentation({
+        useNavigationApiIfAvailable: true,
+        sanitizeUrl: sanitizeNavigationUrl,
+    });
+    const logger = {
+        enabled: () => true,
+        emit: (logRecord) => {
+            if (logRecord.eventName !== "browser.navigation") {
+                return;
+            }
+            try {
+                const destinationUrl = readStringAttribute(logRecord.attributes, "url.full") ??
+                    window.location.href;
+                if (readBooleanAttribute(logRecord.attributes, "browser.navigation.same_document") === false) {
+                    emitInitialPageView(destinationUrl);
+                    return;
+                }
+                emitRouteChange(destinationUrl);
+            }
+            catch (error) {
+                context.onInternalError("capture/navigation:otel", error);
+            }
+        },
+    };
+    const loggerProvider = {
+        getLogger: () => logger,
+    };
+    instrumentation.setLoggerProvider(loggerProvider);
+    instrumentation.enable();
+    return {
+        stop: () => {
+            instrumentation.disable();
+        },
+    };
+};

package/dist/instrumentation/network-request.d.ts

@@ -0,0 +1,103 @@
+import { type LocalStructuredSummary } from "../exporter/local-minimization.js";
+import { type ParameterSnapshotBundle } from "../exporter/parameter-snapshot.js";
+import type { CaptureModuleContext } from "../provider/types.js";
+export type HeaderRecord = {
+    [key: string]: string;
+};
+type QueryValues = {
+    [key: string]: string | string[];
+};
+type EmptyStructuredSummary = {
+    readonly [key: string]: never;
+};
+export type RequestParameterSource = {
+    headers?: HeaderRecord;
+    query?: QueryValues;
+    body?: unknown;
+};
+export type RequestMetadataSummary = LocalStructuredSummary | EmptyStructuredSummary;
+export type RequestTraceContext = {
+    traceId: string;
+    parentSpanId: string | null;
+    requestId: string;
+    requestSpanId: string;
+    interactionId: string;
+    interactionInitiator?: string | null;
+    interactionStartEventKind?: string | null;
+    originFrontendInteractionId?: string | null;
+};
+export type RequestShapeEvidence = {
+    requestKind: "fetch" | "xhr" | string;
+    requestSchemaHash: string | null;
+    requestFieldPaths: string[];
+    requestShapeSize: number;
+    graphqlOperationName: string | null;
+    graphqlOperationType: string | null;
+    graphqlTopLevelFields: string[];
+};
+export type ResponseShapeEvidence = {
+    outcomeClass: string | null;
+    errorCodeCandidate: string | null;
+    responseSchemaHash: string | null;
+    responseFieldPaths: string[];
+    responseShapeSize: number;
+};
+export type NetworkRequestMeta = {
+    method: string;
+    rawUrl: string;
+    url: string;
+    path: string;
+    pathTemplate: string;
+    targetService: string | null;
+    startedAtMs: number;
+    traceId: string;
+    parentSpanId: string | null;
+    requestId: string;
+    requestSpanId: string;
+    interactionId: string;
+    interactionInitiator: string | null;
+    interactionStartEventKind: string | null;
+    originFrontendInteractionId: string | null;
+    viewId: string | null;
+    requestHeaders: HeaderRecord;
+    queryKeys: string[];
+    /** 値を持たない入れ物。顧客が名指しした項目だけ、方針が届いた時に値を持つ。 */
+    requestParametersSnapshot: ParameterSnapshotBundle;
+    requestMetadataSummary: RequestMetadataSummary;
+    requestShapeEvidence: RequestShapeEvidence;
+    requestSizeBytes?: number;
+    pageUrl: string | null;
+};
+export type FetchInstrumentationFailure = {
+    status?: number;
+    message?: string;
+    name?: string;
+};
+export type FetchInstrumentationResult = Response | FetchInstrumentationFailure;
+export declare const headersToRecord: (headers: HeadersInit | undefined) => HeaderRecord;
+export declare const buildParameterSource: (input: {
+    headers?: HeaderRecord;
+    query?: QueryValues;
+    body?: unknown;
+}) => RequestParameterSource;
+export declare const buildResponseShapeEvidence: (input: {
+    normalizedResponseBody: unknown;
+    statusCode?: number | null;
+    failureType?: string | null;
+}) => ResponseShapeEvidence;
+export declare const deriveFailureTypeFromStatus: (status: number) => string | null;
+export declare const getXhrResponseBody: (xhr: XMLHttpRequest) => unknown;
+export declare const parseXhrHeaders: (rawHeaders: string) => HeaderRecord;
+export declare const createRequestMeta: (input: {
+    context: CaptureModuleContext;
+    method: string;
+    rawUrl: string;
+    requestHeaders: HeaderRecord;
+    body: BodyInit | null;
+    defaultRequestKind: "fetch" | "xhr";
+    traceContext: RequestTraceContext;
+    startedAtMs?: number;
+    /** 顧客が init で足した落とす項目名。既定の落とす表は下の組み立てが自分で読む。 */
+    deniedKeys?: readonly string[];
+}) => NetworkRequestMeta;
+export {};