@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/instrumentation/performance.js

@@ -0,0 +1,365 @@
+import { WebVitalsInstrumentation } from "@opentelemetry/browser-instrumentation/experimental/web-vitals";
+import { DocumentLoadInstrumentation } from "@opentelemetry/instrumentation-document-load";
+import { FRONTEND_EVENT_NAME } from "../provider/contracts.js";
+import { currentPageUrl } from "./common.js";
+const SUMMARY_WINDOW_MS = 60000;
+const LONG_TASK_THRESHOLD_MS = 250;
+const INTERACTION_LONG_TASK_THRESHOLD_MS = 100;
+const INTERACTION_LONG_TASK_WINDOW_MS = 2000;
+const createInitialState = () => ({
+    windowStartedAtMs: Date.now(),
+    summaryCount: 0,
+    droppedCount: 0,
+    longTaskCount: 0,
+    resourceFailureCount: 0,
+    worstDurationMs: 0,
+    worstMetricName: null,
+    webVitals: {
+        lcp_ms: null,
+        cls: null,
+        fcp_ms: null,
+        ttfb_ms: null,
+        inp_ms: null,
+    },
+    loadDurationMs: null,
+    interactionReadyMs: null,
+    lastInteractionAtMs: null,
+});
+const durationBucket = (value) => {
+    if (value < 100) {
+        return "lt_100ms";
+    }
+    if (value < 250) {
+        return "100_249ms";
+    }
+    if (value < 1000) {
+        return "250_999ms";
+    }
+    if (value < 2500) {
+        return "1000_2499ms";
+    }
+    return "gte_2500ms";
+};
+const countBucket = (value) => {
+    if (value <= 0) {
+        return "0";
+    }
+    if (value === 1) {
+        return "1";
+    }
+    if (value <= 3) {
+        return "2_3";
+    }
+    if (value <= 10) {
+        return "4_10";
+    }
+    return "gt_10";
+};
+const optionalDurationBucket = (value) => value === null ? null : durationBucket(value);
+const ratingForSummary = (state) => {
+    const lcp = state.webVitals.lcp_ms;
+    const cls = state.webVitals.cls;
+    const inp = state.webVitals.inp_ms;
+    if ((lcp !== null && lcp > 4000) ||
+        (cls !== null && cls > 0.25) ||
+        (inp !== null && inp > 500) ||
+        state.worstDurationMs >= 2500) {
+        return "poor";
+    }
+    if ((lcp !== null && lcp > 2500) ||
+        (cls !== null && cls > 0.1) ||
+        (inp !== null && inp > 200) ||
+        state.worstDurationMs >= 1000) {
+        return "needs_improvement";
+    }
+    return "good";
+};
+const updateWorstDuration = (state, metricName, valueMs) => {
+    if (!Number.isFinite(valueMs) || valueMs < state.worstDurationMs) {
+        return;
+    }
+    state.worstDurationMs = Math.round(valueMs);
+    state.worstMetricName = metricName;
+};
+const observeEntryType = (observers, entryType, callback) => {
+    if (typeof PerformanceObserver === "undefined" ||
+        !PerformanceObserver.supportedEntryTypes?.includes(entryType)) {
+        return;
+    }
+    try {
+        const observer = new PerformanceObserver(callback);
+        observer.observe({ type: entryType, buffered: true });
+        observers.push(observer);
+    }
+    catch {
+        // Some browsers expose an entry type but still reject buffered observation.
+    }
+};
+const readPerformanceNavigation = () => {
+    if (typeof performance === "undefined") {
+        return null;
+    }
+    const entry = performance.getEntriesByType("navigation")[0];
+    return entry && typeof entry.duration === "number"
+        ? entry
+        : null;
+};
+const recordNavigationTiming = (state, navigation) => {
+    state.summaryCount += 1;
+    state.loadDurationMs = Math.max(0, Math.round(navigation.duration));
+    updateWorstDuration(state, "page_load", navigation.duration);
+    const ttfb = Math.max(0, navigation.responseStart - navigation.requestStart);
+    state.webVitals.ttfb_ms = Math.round(ttfb);
+    updateWorstDuration(state, "ttfb", ttfb);
+};
+const numberEntryField = (entry, key) => {
+    const value = entry[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+};
+const recordLcpEntry = (state, entry) => {
+    const valueMs = numberEntryField(entry, "renderTime") ??
+        numberEntryField(entry, "loadTime") ??
+        entry.startTime;
+    if (!Number.isFinite(valueMs)) {
+        return;
+    }
+    state.summaryCount += 1;
+    state.webVitals.lcp_ms = Math.round(valueMs);
+    updateWorstDuration(state, "lcp", valueMs);
+};
+const recordPaintEntry = (state, entry) => {
+    if (entry.name !== "first-contentful-paint") {
+        return;
+    }
+    state.summaryCount += 1;
+    state.webVitals.fcp_ms = Math.round(entry.startTime);
+    updateWorstDuration(state, "fcp", entry.startTime);
+};
+const recordLayoutShiftEntry = (state, entry) => {
+    if (entry.hadRecentInput === true) {
+        return;
+    }
+    const value = numberEntryField(entry, "value");
+    if (value === null) {
+        return;
+    }
+    state.summaryCount += 1;
+    state.webVitals.cls = Number(((state.webVitals.cls ?? 0) + value).toFixed(4));
+};
+const recordEventTimingEntry = (state, entry) => {
+    const interactionId = numberEntryField(entry, "interactionId");
+    if (interactionId === null || interactionId <= 0) {
+        return;
+    }
+    const durationMs = Math.max(0, Math.round(entry.duration));
+    state.summaryCount += 1;
+    state.webVitals.inp_ms = Math.max(state.webVitals.inp_ms ?? 0, durationMs);
+    updateWorstDuration(state, "inp", durationMs);
+};
+const readWebVitalName = (attributes) => {
+    const value = attributes?.["browser.web_vital.name"];
+    return typeof value === "string" && value.length > 0 ? value : null;
+};
+const readWebVitalValue = (attributes) => {
+    const value = attributes?.["browser.web_vital.value"];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+};
+export const startPerformanceCapture = (context) => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+        return { stop: () => undefined };
+    }
+    let state = createInitialState();
+    const observers = [];
+    const documentLoadInstrumentation = new DocumentLoadInstrumentation({
+        semconvStabilityOptIn: "http/dup",
+        applyCustomAttributesOnSpan: {
+            documentLoad: () => {
+                const navigation = readPerformanceNavigation();
+                if (navigation) {
+                    recordNavigationTiming(state, navigation);
+                }
+            },
+        },
+    });
+    const webVitalsInstrumentation = new WebVitalsInstrumentation({
+        applyCustomLogRecordData: (logRecord) => {
+            const metricName = readWebVitalName(logRecord.attributes);
+            const metricValue = readWebVitalValue(logRecord.attributes);
+            if (!metricName || metricValue === null) {
+                return;
+            }
+            state.summaryCount += 1;
+            switch (metricName.toUpperCase()) {
+                case "LCP":
+                    state.webVitals.lcp_ms = Math.round(metricValue);
+                    updateWorstDuration(state, "lcp", metricValue);
+                    break;
+                case "FCP":
+                    state.webVitals.fcp_ms = Math.round(metricValue);
+                    updateWorstDuration(state, "fcp", metricValue);
+                    break;
+                case "INP":
+                    state.webVitals.inp_ms = Math.round(metricValue);
+                    updateWorstDuration(state, "inp", metricValue);
+                    break;
+                case "CLS":
+                    state.webVitals.cls = Number(metricValue.toFixed(4));
+                    break;
+                case "TTFB":
+                    state.webVitals.ttfb_ms = Math.round(metricValue);
+                    updateWorstDuration(state, "ttfb", metricValue);
+                    break;
+                default:
+                    updateWorstDuration(state, metricName.toLowerCase(), metricValue);
+                    break;
+            }
+        },
+    });
+    documentLoadInstrumentation.enable();
+    webVitalsInstrumentation.enable();
+    const emitSummary = (flushReason) => {
+        if (context.getConsent() === "denied") {
+            state = createInitialState();
+            return;
+        }
+        const summaryCount = state.summaryCount;
+        if (summaryCount === 0 && state.droppedCount === 0) {
+            return;
+        }
+        const viewId = context.getViewId();
+        const summaryWindowMs = Math.max(0, Date.now() - state.windowStartedAtMs);
+        context.onEvent({
+            type: FRONTEND_EVENT_NAME.performanceSummaryObserved,
+            occurredAtMs: Date.now(),
+            payload: {
+                viewId,
+                // must strip query string to avoid leaking OAuth
+                // callback / password-reset / magic-link tokens that may
+                // live in `window.location.href`. See `instrumentation/common.ts`.
+                pageUrl: currentPageUrl() ?? "",
+                collectorName: "performance_rum",
+                aggregationKind: "per_view_window",
+                summaryWindowMs,
+                summaryCount,
+                droppedCount: state.droppedCount,
+                sampleRate: 1,
+                budgetWindowMs: SUMMARY_WINDOW_MS,
+                rateLimitKey: viewId
+                    ? `view:${viewId}:performance`
+                    : "view:unknown:performance",
+                performanceKind: "view",
+                rating: ratingForSummary(state),
+                metricName: state.worstMetricName ?? "performance_summary",
+                metricValueBucket: durationBucket(state.worstDurationMs),
+                loadDurationBucket: optionalDurationBucket(state.loadDurationMs),
+                interactionReadyMsBucket: optionalDurationBucket(state.interactionReadyMs),
+                longTaskCountBucket: countBucket(state.longTaskCount),
+                resourceFailureCountBucket: countBucket(state.resourceFailureCount),
+                longTaskCount: state.longTaskCount,
+                resourceFailureCount: state.resourceFailureCount,
+                slowResourceCount: 0,
+                worstDurationBucket: durationBucket(state.worstDurationMs),
+                flushReason,
+                webVitalBuckets: {
+                    lcp: optionalDurationBucket(state.webVitals.lcp_ms),
+                    fcp: optionalDurationBucket(state.webVitals.fcp_ms),
+                    ttfb: optionalDurationBucket(state.webVitals.ttfb_ms),
+                    inp: optionalDurationBucket(state.webVitals.inp_ms),
+                    cls: state.webVitals.cls === null
+                        ? null
+                        : state.webVitals.cls > 0.25
+                            ? "poor"
+                            : state.webVitals.cls > 0.1
+                                ? "needs_improvement"
+                                : "good",
+                },
+            },
+        });
+        state = createInitialState();
+    };
+    const intervalId = window.setInterval(() => {
+        emitSummary("interval");
+    }, SUMMARY_WINDOW_MS);
+    const pageHideHandler = () => {
+        emitSummary("pagehide");
+    };
+    const visibilityHandler = () => {
+        if (document.visibilityState === "hidden") {
+            emitSummary("visibility_hidden");
+        }
+    };
+    const resourceErrorHandler = (event) => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        if (!(event.target instanceof Element)) {
+            return;
+        }
+        state.resourceFailureCount += 1;
+        state.summaryCount += 1;
+    };
+    const interactionHandler = () => {
+        state.lastInteractionAtMs = Date.now();
+    };
+    window.addEventListener("error", resourceErrorHandler, true);
+    window.addEventListener("pointerdown", interactionHandler, true);
+    window.addEventListener("pagehide", pageHideHandler, true);
+    document.addEventListener("visibilitychange", visibilityHandler, true);
+    // Long tasks and resource load failures are retained as Cluebase summary-only
+    // UX evidence because the accepted browser OTel modules above cover
+    // document load and Web Vitals, not this per-view aggregate.
+    observeEntryType(observers, "longtask", (list) => {
+        for (const entry of list.getEntries()) {
+            const nearInteraction = state.lastInteractionAtMs !== null &&
+                Date.now() - state.lastInteractionAtMs <=
+                    INTERACTION_LONG_TASK_WINDOW_MS;
+            const threshold = nearInteraction
+                ? INTERACTION_LONG_TASK_THRESHOLD_MS
+                : LONG_TASK_THRESHOLD_MS;
+            if (entry.duration < threshold) {
+                continue;
+            }
+            state.longTaskCount += 1;
+            state.summaryCount += 1;
+            updateWorstDuration(state, "long_task", entry.duration);
+        }
+    });
+    observeEntryType(observers, "largest-contentful-paint", (list) => {
+        for (const entry of list.getEntries()) {
+            recordLcpEntry(state, entry);
+        }
+    });
+    observeEntryType(observers, "paint", (list) => {
+        for (const entry of list.getEntries()) {
+            recordPaintEntry(state, entry);
+        }
+    });
+    observeEntryType(observers, "layout-shift", (list) => {
+        for (const entry of list.getEntries()) {
+            recordLayoutShiftEntry(state, entry);
+        }
+    });
+    observeEntryType(observers, "event", (list) => {
+        for (const entry of list.getEntries()) {
+            recordEventTimingEntry(state, entry);
+        }
+    });
+    return {
+        flush: (reason) => {
+            emitSummary(reason);
+        },
+        stop: () => {
+            emitSummary("stop");
+            documentLoadInstrumentation.disable();
+            webVitalsInstrumentation.disable();
+            window.clearInterval(intervalId);
+            window.removeEventListener("error", resourceErrorHandler, true);
+            window.removeEventListener("pointerdown", interactionHandler, true);
+            window.removeEventListener("pagehide", pageHideHandler, true);
+            document.removeEventListener("visibilitychange", visibilityHandler, true);
+            for (const observer of observers) {
+                observer.disconnect();
+            }
+        },
+    };
+};

package/dist/integrations/next-router.d.ts

@@ -0,0 +1,16 @@
+export type NextRouterEventsLike = {
+    on: (event: string, handler: (...args: unknown[]) => void) => void;
+    off: (event: string, handler: (...args: unknown[]) => void) => void;
+};
+export type NextRouterLike = {
+    asPath?: string;
+    events: NextRouterEventsLike;
+};
+export type NextRouterIntegrationOptions = {
+    router: NextRouterLike;
+    onRouteChange: (fromPath: string, toPath: string) => void;
+};
+export type NextRouterIntegrationHandle = {
+    detach: () => void;
+};
+export declare const attachNextRouterIntegration: (options: NextRouterIntegrationOptions) => NextRouterIntegrationHandle;

package/dist/integrations/next-router.js

@@ -0,0 +1,18 @@
+export const attachNextRouterIntegration = (options) => {
+    const { router, onRouteChange } = options;
+    let lastPath = router.asPath ?? "";
+    const handler = (nextUrl) => {
+        const nextPath = typeof nextUrl === "string" ? nextUrl : (router.asPath ?? "");
+        if (!nextPath || nextPath === lastPath) {
+            return;
+        }
+        onRouteChange(lastPath, nextPath);
+        lastPath = nextPath;
+    };
+    router.events.on("routeChangeComplete", handler);
+    return {
+        detach: () => {
+            router.events.off("routeChangeComplete", handler);
+        },
+    };
+};

package/dist/integrations/react-router.d.ts

@@ -0,0 +1,7 @@
+export type ReactRouterIntegrationOptions = {
+    onRouteChange: (fromPath: string, toPath: string) => void;
+};
+export type ReactRouterIntegrationHandle = {
+    detach: () => void;
+};
+export declare const attachReactRouterIntegration: (options: ReactRouterIntegrationOptions) => ReactRouterIntegrationHandle;

package/dist/integrations/react-router.js

@@ -0,0 +1,61 @@
+import { HISTORY_WRAPPED_MARKER, isHistoryAlreadyCluebaseWrapped, } from "../instrumentation/common.js";
+export const attachReactRouterIntegration = (options) => {
+    if (typeof window === "undefined") {
+        return {
+            detach: () => undefined,
+        };
+    }
+    let lastPath = window.location.pathname;
+    let attached = true;
+    const emit = () => {
+        if (!attached) {
+            return;
+        }
+        const nextPath = window.location.pathname;
+        if (nextPath === lastPath) {
+            return;
+        }
+        options.onRouteChange(lastPath, nextPath);
+        lastPath = nextPath;
+    };
+    // Idempotent guard for Cluebase-owned History API wrappers. OTel navigation
+    // instrumentation may patch history separately and remains the primary
+    // navigation source.
+    const sentinelPushState = history.pushState;
+    const sentinelReplaceState = history.replaceState;
+    const alreadyWrapped = isHistoryAlreadyCluebaseWrapped(history);
+    const originalPushState = sentinelPushState;
+    const originalReplaceState = sentinelReplaceState;
+    const wrappedPushState = function (...args) {
+        originalPushState.apply(this, args);
+        emit();
+    };
+    wrappedPushState[HISTORY_WRAPPED_MARKER] = true;
+    const wrappedReplaceState = function (...args) {
+        originalReplaceState.apply(this, args);
+        emit();
+    };
+    wrappedReplaceState[HISTORY_WRAPPED_MARKER] = true;
+    if (!alreadyWrapped) {
+        history.pushState = wrappedPushState;
+        history.replaceState = wrappedReplaceState;
+    }
+    const popstateHandler = () => {
+        emit();
+    };
+    window.addEventListener("popstate", popstateHandler, true);
+    return {
+        detach: () => {
+            attached = false;
+            if (!alreadyWrapped) {
+                if (history.pushState === wrappedPushState) {
+                    history.pushState = originalPushState;
+                }
+                if (history.replaceState === wrappedReplaceState) {
+                    history.replaceState = originalReplaceState;
+                }
+            }
+            window.removeEventListener("popstate", popstateHandler, true);
+        },
+    };
+};

package/dist/internal/internal-log.d.ts

@@ -0,0 +1,23 @@
+/**
+ * SDK-internal diagnostic logger for the Frontend SDK.
+ *
+ * Mirror of Node SDK ``internal-log.ts`` and Python SDK ``_internal_log.py``.
+ * Exposes a single configurable {@link InternalLogger}. Default is a no-op
+ * so the SDK does not write to the host page's console.
+ */
+export type InternalLogContext = {
+    [key: string]: string | number | boolean | null;
+};
+type InternalLogContextInput = {
+    [key: string]: string | number | boolean | null | undefined;
+};
+export interface InternalLogger {
+    debug(message: string, context?: InternalLogContext): void;
+    info(message: string, context?: InternalLogContext): void;
+    warn(message: string, context?: InternalLogContext): void;
+    error(message: string, context?: InternalLogContext): void;
+}
+export declare function setInternalLogger(logger: InternalLogger | null | undefined): void;
+export declare function getInternalLogger(): InternalLogger;
+export declare function logSwallowed(operation: string, _cause: unknown, context?: InternalLogContextInput): void;
+export {};

package/dist/internal/internal-log.js

@@ -0,0 +1,47 @@
+/**
+ * SDK-internal diagnostic logger for the Frontend SDK.
+ *
+ * Mirror of Node SDK ``internal-log.ts`` and Python SDK ``_internal_log.py``.
+ * Exposes a single configurable {@link InternalLogger}. Default is a no-op
+ * so the SDK does not write to the host page's console.
+ */
+const SAFE_CONTEXT_KEYS = new Set([
+    "attempt",
+    "code",
+    "count",
+    "error_code",
+    "http_status",
+    "operation",
+    "reason",
+    "strategy",
+]);
+const SAFE_TOKEN = /^[a-z0-9_.-]{1,128}$/;
+const NO_OP_LOGGER = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+let currentLogger = NO_OP_LOGGER;
+export function setInternalLogger(logger) {
+    currentLogger = logger ?? NO_OP_LOGGER;
+}
+export function getInternalLogger() {
+    return currentLogger;
+}
+export function logSwallowed(operation, _cause, context = {}) {
+    const details = {};
+    for (const [key, value] of Object.entries(context)) {
+        if (SAFE_CONTEXT_KEYS.has(key) &&
+            (value === null || typeof value === "boolean" ||
+                (typeof value === "number" && Number.isFinite(value)) ||
+                (typeof value === "string" && SAFE_TOKEN.test(value)))) {
+            details[key] = value;
+        }
+    }
+    // Exception text and stacks may contain customer payloads, credentials, or
+    // source paths. The internal logger is an optional diagnostic sink, so it
+    // keeps only bounded caller-provided classification fields, matching the
+    // backend SDKs and the API/worker log contract.
+    currentLogger.debug(`cluebase.sdk swallowed ${operation}`, details);
+}

package/dist/internal/metrics.d.ts

@@ -0,0 +1,10 @@
+export type InternalMetricKey = "enqueue_count" | "sent_count" | "send_failure_count" | "dropped_count" | "events_summarized_count" | "sampling_dropped_count" | "oversized_event_count" | "oversized_event_dropped_count" | "snapshot_truncated_count" | "retry_count" | "batch_flush_count" | "payload_size_bytes" | "masking_error_count" | "capture_error_count" | "transport_failed_count" | "transport_retry_count" | "transport_requeue_count" | "browser_token_failure_count" | "browser_token_missing_cached_count" | "pending_batch_count" | "public_drop_count" | "ingest_dropped_event_count" | "parameter_snapshot_oversized_dropped";
+export type InternalMetricsSnapshot = Record<InternalMetricKey, number>;
+export declare class InternalMetricsStore {
+    private values;
+    constructor();
+    increment(key: InternalMetricKey, by?: number): void;
+    set(key: InternalMetricKey, value: number): void;
+    getSnapshot(): InternalMetricsSnapshot;
+    reset(): void;
+}

package/dist/internal/metrics.js

@@ -0,0 +1,50 @@
+const createInitialSnapshot = () => {
+    return {
+        enqueue_count: 0,
+        sent_count: 0,
+        send_failure_count: 0,
+        dropped_count: 0,
+        events_summarized_count: 0,
+        sampling_dropped_count: 0,
+        oversized_event_count: 0,
+        oversized_event_dropped_count: 0,
+        snapshot_truncated_count: 0,
+        retry_count: 0,
+        batch_flush_count: 0,
+        payload_size_bytes: 0,
+        masking_error_count: 0,
+        capture_error_count: 0,
+        transport_failed_count: 0,
+        transport_retry_count: 0,
+        transport_requeue_count: 0,
+        browser_token_failure_count: 0,
+        browser_token_missing_cached_count: 0,
+        pending_batch_count: 0,
+        public_drop_count: 0,
+        ingest_dropped_event_count: 0,
+        parameter_snapshot_oversized_dropped: 0,
+    };
+};
+export class InternalMetricsStore {
+    constructor() {
+        this.values = createInitialSnapshot();
+    }
+    increment(key, by = 1) {
+        if (!Number.isFinite(by)) {
+            return;
+        }
+        this.values[key] += by;
+    }
+    set(key, value) {
+        if (!Number.isFinite(value)) {
+            return;
+        }
+        this.values[key] = value;
+    }
+    getSnapshot() {
+        return { ...this.values };
+    }
+    reset() {
+        this.values = createInitialSnapshot();
+    }
+}

package/dist/provider/_version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION: "0.0.1";

package/dist/provider/_version.js

@@ -0,0 +1,3 @@
+// This file is generated by scripts/generate-version-module.mjs.
+// Do NOT edit by hand. The source of truth is `package.json` `version`.
+export const SDK_VERSION = "0.0.1";

package/dist/provider/config.d.ts

@@ -0,0 +1,12 @@
+import type { CluebaseInitOptions, ResolvedCluebaseConfig } from "./types.js";
+/**
+ * Read an address Cluebase is able to send to, or `null` when it cannot.
+ *
+ * `cluebase.init` refuses such an endpoint loudly and `resolveConfig` drops it to
+ * `""`; the two reactions differ but the question does not, so neither restates
+ * the rule.
+ */
+export declare const parseSendableUrl: (value: string) => URL | null;
+export declare const resolveConfig: (options: CluebaseInitOptions) => ResolvedCluebaseConfig;
+export declare const validateConfig: (config: ResolvedCluebaseConfig) => string[];
+export declare const isConfigValid: (config: ResolvedCluebaseConfig) => boolean;