@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/instrumentation/common.js

@@ -0,0 +1,90 @@
+/**
+ * Shared instrumentation helpers used across multiple capture modules
+ * (network, performance, navigation, etc.).
+ *
+ * The most important contract here is URL sanitization for any payload
+ * that may carry the user's current browsing URL. The page URL must never
+ * be emitted with query string intact, because OAuth callback /
+ * password-reset / magic-link flows place secret tokens in the query
+ * string. Any instrumentation module that needs a "page URL" field on
+ * its outgoing event payload MUST go through `currentPageUrl()` here.
+ *
+ * Previously `instrumentation/performance.ts` emitted
+ * `pageUrl: window.location.href` directly while
+ * `instrumentation/network.ts` had its own internal stripping helper.
+ * This module unifies the behavior so all callers share a single
+ * implementation and a single test surface.
+ */
+/**
+ * Resolves `value` to a URL, falling back to the current document
+ * location for relative URLs. Returns `null` if neither parsing succeeds.
+ */
+export const resolveUrlAgainstCurrentLocation = (value) => {
+    try {
+        return new URL(value);
+    }
+    catch { }
+    const currentHref = typeof globalThis.location?.href === "string" &&
+        globalThis.location.href.length > 0
+        ? globalThis.location.href
+        : null;
+    if (!currentHref) {
+        return null;
+    }
+    try {
+        return new URL(value, currentHref);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Strips the query string and hash from the given URL, returning
+ * `origin + pathname` only. Falls back to a `split("?")` form if URL
+ * parsing fails so callers never receive a query-bearing string.
+ *
+ * The query string is the primary leak surface for OAuth callbacks
+ * (`?code=...&state=...`) and password reset links (`?token=...`).
+ */
+export const stripQueryFromUrl = (url) => {
+    try {
+        const resolvedUrl = resolveUrlAgainstCurrentLocation(url);
+        if (!resolvedUrl) {
+            return url.split("?")[0] ?? url;
+        }
+        return `${resolvedUrl.origin}${resolvedUrl.pathname}`;
+    }
+    catch {
+        return url.split("?")[0] ?? url;
+    }
+};
+/**
+ * Returns the current page URL with all query parameters and hash
+ * fragments stripped. Returns `null` if `globalThis.location` is not
+ * available (e.g., non-browser environments).
+ *
+ * THIS IS THE ONLY APPROVED WAY TO POPULATE A `pageUrl` FIELD ON ANY
+ * INSTRUMENTATION EVENT PAYLOAD. Do not use `window.location.href`
+ * directly.
+ */
+export const currentPageUrl = () => {
+    const href = globalThis.location?.href;
+    return href ? stripQueryFromUrl(href) : null;
+};
+/**
+ * Single sentinel marker used by Cluebase-owned History API wrappers. OTel-owned
+ * navigation instrumentation may patch history independently and must remain
+ * the primary navigation source.
+ */
+export const HISTORY_WRAPPED_MARKER = "__cluebaseHistoryWrapped";
+export const isHistoryAlreadyCluebaseWrapped = (historyApi) => {
+    const push = historyApi.pushState;
+    const replace = historyApi.replaceState;
+    return Boolean(push[HISTORY_WRAPPED_MARKER] || replace[HISTORY_WRAPPED_MARKER]);
+};
+/**
+ * 画面操作 1 種類を指す安定キー。意味層は操作の identity 単位で行動名を付けるため、
+ * 通信経路 (method / path) を持たない画面操作にも同じ粒度の識別子が要る。
+ * 画面と操作対象の安定キーの組で「どの画面のどの操作か」を表す。
+ */
+export const buildPrimaryActionKey = (screenKey, targetStableKey) => screenKey && targetStableKey ? `${screenKey}#${targetStableKey}` : null;

package/dist/instrumentation/dom.d.ts

@@ -0,0 +1,63 @@
+export declare const buildDomPath: (element: Element) => string;
+export declare const getTextPreview: (element: Element) => string | null;
+export declare const getElementClassList: (element: Element) => string[] | null;
+export declare const getElementRole: (element: Element) => string | null;
+export declare const getElementPlaceholder: (element: Element) => string | null;
+export declare const getElementAriaLabel: (element: Element) => string | null;
+export declare const getElementSectionHeading: (element: Element) => string | null;
+/** どの段が名前を決めたか。伏せられていても残る**機械が決めた値**です。 */
+export type AccessibleNameSource = "aria_labelledby" | "aria_label" | "native_label" | "content" | "title";
+export type AccessibleName = {
+    name: string;
+    source: AccessibleNameSource;
+};
+/**
+ * 要素の名前を **1 本**に決めます。
+ *
+ * 順序は W3C の名前算出 (Accessible Name Computation) に従います。
+ * `aria-labelledby` → `aria-label` → 対応ラベル / `alt` → 要素内の文言 → `title`。
+ * **自前の優先順を作ってはいけません。** 顧客の画面を読み上げる道具が名乗る名前と
+ * 食い違う名前を保管すると、行動の名付けが「利用者が見ている名前」から離れます。
+ *
+ * 生の候補を並べて持たないのも同じ理由です。どれを採るかを後段でもう一度決めると、
+ * 決め方が 2 つになります。
+ */
+export declare const getAccessibleName: (element: Element) => AccessibleName | null;
+export declare const getElementLabel: (element: Element) => string | null;
+/**
+ * 押された要素の**祖先の並び**。`main > form[role=search] > button` の形で返します。
+ *
+ * 綴りは**機械が決めた値だけ**で作ります (要素の種類と役割)。顧客が書いた文言を
+ * 混ぜないので、文言を伏せた状態でも「画面のどのまとまりの中の操作か」が残ります。
+ */
+export declare const getAncestorChain: (element: Element) => string | null;
+/** 画面の題。頁が何の画面かを表す、顧客が書いた文言です。 */
+export declare const getDocumentTitle: (element: Element) => string | null;
+/**
+ * 押した後に行く先。`href` を持つ要素はその値を返します。
+ *
+ * 問い合わせ文字列は落とします。**そこに載るのは利用者ごとに違う値**で、
+ * 名前に入れると行動の型が利用者の数だけ増えます。
+ */
+export declare const getNavigationHref: (element: Element) => string | null;
+export declare const resolveClickDisplayTarget: (element: Element) => Element;
+export declare const shouldCaptureClickTarget: (element: Element) => boolean;
+export type StableKeyQuality = "official" | "compat" | "structural";
+export type StableKeyDescriptor = {
+    stableKey: string;
+    stableKeyQuality: StableKeyQuality;
+    formKey: string | null;
+};
+export type InteractionScopeDescriptor = {
+    interactionScopeKind: "form" | "dialog" | "fieldset";
+    interactionScopeKey: string;
+};
+export declare const getFormKey: (element: Element) => string | null;
+export declare const resolveStableKeyDescriptor: (element: Element) => StableKeyDescriptor;
+export declare const getStableKey: (element: Element) => string;
+export declare const resolveInteractionScopeDescriptor: (element: Element) => InteractionScopeDescriptor | null;
+export declare const extractFieldName: (element: Element) => string | null;
+export declare const extractFieldType: (element: Element) => string | null;
+export declare const findParentFormId: (element: Element) => string | null;
+export declare const isEditableElement: (element: Element) => boolean;
+export declare const getElementValue: (element: Element) => unknown;