@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/provider/sdk-otel-pipeline.js

@@ -0,0 +1,148 @@
+import { trace } from "@opentelemetry/api";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
+import { resolveBrowserTokenEndpoint, resolveCanonicalIngestEndpoint, } from "../exporter/client.js";
+import { ObservationSourceEventExporter } from "../exporter/observation-source-event-exporter.js";
+import { createFrontendResourceAttributes } from "../exporter/frontend-resource.js";
+import { createCluebaseNetworkPropagator } from "../instrumentation/network.js";
+import { getSessionCaptureEligibility } from "./sdk-event-pipeline.js";
+export const createCluebaseOtelPipeline = ({ resolved, getTransport, getContext, }) => {
+    if (!getTransport()) {
+        return null;
+    }
+    const resource = resourceFromAttributes(createFrontendResourceAttributes(resolved));
+    const collectionPermits = new WeakMap();
+    const exporter = new ObservationSourceEventExporter({
+        enqueueImpl: (event, permit) => {
+            const transport = getTransport();
+            if (!transport) {
+                return;
+            }
+            transport.enqueue(event, permit);
+        },
+        getCollectionPermit: (span) => {
+            const transport = getTransport();
+            if (!transport)
+                return undefined;
+            if (span) {
+                return collectionPermits.get(span);
+            }
+            if (getSessionCaptureEligibility(transport) === false) {
+                return undefined;
+            }
+            return transport.capturePermit();
+        },
+        flushImpl: async () => {
+            const transport = getTransport();
+            if (!transport) {
+                return;
+            }
+            await transport.flush();
+        },
+        shutdownImpl: async () => {
+            const transport = getTransport();
+            if (!transport) {
+                return;
+            }
+            await transport.flush();
+        },
+        getContext,
+        deniedKeys: resolved.privacy?.deniedKeys ?? [],
+        ignoreUrlPrefixes: [
+            resolveCanonicalIngestEndpoint(resolved.endpoint),
+            resolveCanonicalIngestEndpoint(resolved.originalEndpoint),
+            resolveBrowserTokenEndpoint(resolved.endpoint),
+            resolveBrowserTokenEndpoint(resolved.originalEndpoint),
+            ...(resolved.localSetupCheckEndpoint
+                ? [resolved.localSetupCheckEndpoint]
+                : []),
+        ].filter((url) => typeof url === "string" && url.length > 0),
+    });
+    const provider = new WebTracerProvider({
+        resource,
+        spanProcessors: [
+            new BatchSpanProcessor(exporter, {
+                scheduledDelayMillis: resolved.batch.flushIntervalMs,
+                maxQueueSize: 2048,
+                maxExportBatchSize: 512,
+            }),
+            collectionPermitProcessor(getTransport, collectionPermits),
+        ],
+    });
+    const mode = resolved.otelProviderMode;
+    const shouldRegister = mode === "register" || (mode === "detect" && !hasHostInstalledProvider());
+    if (shouldRegister) {
+        provider.register({
+            propagator: createCluebaseNetworkPropagator(),
+        });
+    }
+    return provider;
+};
+const collectionPermitProcessor = (getTransport, permits) => ({
+    onStart(span) {
+        const transport = getTransport();
+        if (transport && getSessionCaptureEligibility(transport) !== false) {
+            permits.set(span, transport.capturePermit());
+        }
+    },
+    onEnding() { },
+    onEnd() { },
+    forceFlush: async () => undefined,
+    shutdown: async () => undefined,
+});
+export const shutdownCluebaseOtelProvider = (provider) => {
+    if (!provider) {
+        return;
+    }
+    void provider.shutdown().catch(() => undefined);
+};
+export const shutdownCluebaseOtelProviderAsync = async (provider) => {
+    if (!provider) {
+        return;
+    }
+    try {
+        await provider.shutdown();
+    }
+    catch {
+        // shutdown is best-effort per OTel contract.
+    }
+};
+export const forceFlushCluebaseOtelProvider = async (provider, signal) => {
+    if (!provider) {
+        return;
+    }
+    try {
+        await awaitWithAbort(provider.forceFlush(), signal);
+    }
+    catch {
+        // forceFlush is best-effort per OTel contract.
+    }
+};
+const awaitWithAbort = async (promise, signal) => {
+    if (!signal)
+        return await promise;
+    if (signal.aborted)
+        throw new DOMException("aborted", "AbortError");
+    return await new Promise((resolve, reject) => {
+        const abort = () => reject(new DOMException("aborted", "AbortError"));
+        signal.addEventListener("abort", abort, { once: true });
+        void promise.then((value) => {
+            signal.removeEventListener("abort", abort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", abort);
+            reject(error);
+        });
+    });
+};
+const hasHostInstalledProvider = () => {
+    try {
+        const current = trace.getTracerProvider();
+        const ctorName = current?.constructor?.name ?? "";
+        return ctorName !== "" && ctorName !== "ProxyTracerProvider";
+    }
+    catch {
+        return false;
+    }
+};

package/dist/provider/sdk-runtime-surfaces.d.ts

@@ -0,0 +1,49 @@
+import { TraceManager } from "../context/trace.js";
+import { type IngestClient } from "../exporter/client.js";
+import type { BatchTransport } from "../exporter/batch.js";
+import type { InternalMetricsStore } from "../internal/metrics.js";
+import type { CluebaseOtelProvider } from "./sdk-otel-pipeline.js";
+import type { CaptureModuleContext, CluebaseConsentState, CluebaseInternalLogger, RawCapturedEvent, ResolvedCluebaseConfig } from "./types.js";
+type ProviderRuntimeSurfacesOptions = {
+    internalMetrics: InternalMetricsStore;
+    logger: CluebaseInternalLogger;
+    enqueueRawEvent: (event: RawCapturedEvent) => void;
+    getViewId: () => string | null;
+    getConsent: () => CluebaseConsentState;
+    getObservationContext: () => {
+        anonymousId: string | null;
+        userId: string | null;
+        organizationId?: string | null;
+        sessionId: string | null;
+        tabId: string | null;
+    };
+    getTraceManager: () => TraceManager | null;
+    getTransport: () => BatchTransport | null;
+    getTracerProvider: () => CluebaseOtelProvider | null;
+};
+export declare class ProviderRuntimeSurfaces {
+    private readonly internalMetrics;
+    private readonly logger;
+    private readonly enqueueRawEvent;
+    private readonly getViewId;
+    private readonly getConsent;
+    private readonly getObservationContext;
+    private readonly getTraceManager;
+    private readonly getTransport;
+    private readonly getTracerProvider;
+    private captureHandles;
+    private unloadHandlers;
+    private flushDebounceTimer;
+    private browserTokenWarmupController;
+    constructor(options: ProviderRuntimeSurfacesOptions);
+    buildCaptureContext(): CaptureModuleContext;
+    warmupBrowserToken(client: IngestClient): void;
+    startCaptureModules(config: ResolvedCluebaseConfig): void;
+    stopCaptureModules(): void;
+    abortBrowserTokenWarmup(): void;
+    flushCaptureSummaries(reason: string): Promise<void>;
+    installUnloadHandlers(onUnloadSessionEnd: () => void): void;
+    isCaptureActive(): boolean;
+    stopRuntimeSurfaces(): void;
+}
+export {};

package/dist/provider/sdk-runtime-surfaces.js

@@ -0,0 +1,216 @@
+import { TraceManager } from "../context/trace.js";
+import { resolveBrowserTokenEndpoint, resolveCanonicalIngestEndpoint, } from "../exporter/client.js";
+import { startActionCapture } from "../instrumentation/action.js";
+import { startDragCapture } from "../instrumentation/drag.js";
+import { startErrorCapture } from "../instrumentation/error.js";
+import { startFormCapture } from "../instrumentation/form.js";
+import { startInputCapture } from "../instrumentation/input.js";
+import { startNavigationCapture } from "../instrumentation/navigation.js";
+import { startNetworkCapture } from "../instrumentation/network.js";
+import { startPageCapture } from "../instrumentation/page.js";
+import { startPerformanceCapture } from "../instrumentation/performance.js";
+const FLUSH_DEBOUNCE_MS = 200;
+export class ProviderRuntimeSurfaces {
+    constructor(options) {
+        this.captureHandles = [];
+        this.unloadHandlers = [];
+        this.flushDebounceTimer = null;
+        this.browserTokenWarmupController = null;
+        this.internalMetrics = options.internalMetrics;
+        this.logger = options.logger;
+        this.enqueueRawEvent = options.enqueueRawEvent;
+        this.getViewId = options.getViewId;
+        this.getConsent = options.getConsent;
+        this.getObservationContext = options.getObservationContext;
+        this.getTraceManager = options.getTraceManager;
+        this.getTransport = options.getTransport;
+        this.getTracerProvider = options.getTracerProvider;
+    }
+    buildCaptureContext() {
+        return {
+            onEvent: (event) => {
+                this.enqueueRawEvent(event);
+            },
+            onInternalError: (source, _error) => {
+                this.internalMetrics.increment("capture_error_count");
+                this.logger.error("capture module error", {
+                    source,
+                    error_code: "capture_module_error",
+                });
+            },
+            getViewId: () => this.getViewId(),
+            getConsent: () => this.getConsent(),
+            getObservationContext: () => this.getObservationContext(),
+            shouldIgnoreElement: () => false,
+            startInteraction: (input) => {
+                return (this.getTraceManager()?.startInteraction(input) ??
+                    input.interactionId ??
+                    null);
+            },
+            requestFlush: () => {
+                void this.flushCaptureSummaries("capture_flush");
+                if (this.flushDebounceTimer)
+                    return;
+                this.flushDebounceTimer = setTimeout(() => {
+                    this.flushDebounceTimer = null;
+                    const transport = this.getTransport();
+                    if (!transport)
+                        return;
+                    transport.flush().catch((_err) => {
+                        this.logger.warn("auto-flush after capture event failed", {
+                            error_code: "capture_flush_failed",
+                        });
+                    });
+                }, FLUSH_DEBOUNCE_MS);
+            },
+        };
+    }
+    warmupBrowserToken(client) {
+        this.browserTokenWarmupController?.abort();
+        const controller = new AbortController();
+        this.browserTokenWarmupController = controller;
+        void client
+            .warmupBrowserToken(controller.signal)
+            .catch((_error) => {
+            if (controller.signal.aborted) {
+                return;
+            }
+            this.logger.warn("browser token warmup failed", {
+                error_code: "browser_token_warmup_failed",
+            });
+        })
+            .finally(() => {
+            if (this.browserTokenWarmupController === controller) {
+                this.browserTokenWarmupController = null;
+            }
+        });
+    }
+    startCaptureModules(config) {
+        const captureContext = this.buildCaptureContext();
+        const handles = [];
+        handles.push(startInputCapture(captureContext));
+        handles.push(startPageCapture(captureContext));
+        handles.push(startNavigationCapture(captureContext));
+        handles.push(startActionCapture(captureContext));
+        handles.push(startFormCapture(captureContext));
+        handles.push(startDragCapture(captureContext));
+        if (config.captureNetwork) {
+            handles.push(startNetworkCapture(captureContext, {
+                tracerProvider: this.getTracerProvider() ?? undefined,
+                deniedKeys: config.privacy.deniedKeys,
+                ignoreUrlPrefixes: [
+                    resolveCanonicalIngestEndpoint(config.endpoint),
+                    resolveBrowserTokenEndpoint(config.endpoint),
+                ],
+                tracePropagationOrigins: config.network.tracePropagationOrigins,
+                createRequestTraceContext: (input) => {
+                    const traceManager = this.getTraceManager();
+                    if (traceManager) {
+                        return traceManager.createRequestContext(input);
+                    }
+                    return new TraceManager().createRequestContext(input);
+                },
+            }));
+        }
+        if (config.capturePerformance) {
+            handles.push(startPerformanceCapture(captureContext));
+        }
+        if (config.captureErrors) {
+            handles.push(startErrorCapture(captureContext));
+        }
+        this.captureHandles = handles;
+    }
+    stopCaptureModules() {
+        for (const handle of this.captureHandles) {
+            try {
+                handle.stop();
+            }
+            catch {
+                this.logger.warn("failed to stop capture module", {
+                    error_code: "capture_stop_failed",
+                });
+            }
+        }
+        this.captureHandles = [];
+    }
+    abortBrowserTokenWarmup() {
+        this.browserTokenWarmupController?.abort();
+        this.browserTokenWarmupController = null;
+    }
+    async flushCaptureSummaries(reason) {
+        const pending = [];
+        for (const handle of this.captureHandles) {
+            try {
+                const result = handle.flush?.(reason);
+                if (result && typeof result.then === "function") {
+                    pending.push(result);
+                }
+            }
+            catch {
+                this.logger.warn("failed to flush capture module", {
+                    error_code: "capture_flush_failed",
+                });
+            }
+        }
+        if (pending.length === 0)
+            return;
+        const results = await Promise.allSettled(pending);
+        for (const result of results) {
+            if (result.status === "rejected") {
+                this.logger.warn("failed to flush capture module", {
+                    error_code: "capture_flush_failed",
+                });
+            }
+        }
+    }
+    installUnloadHandlers(onUnloadSessionEnd) {
+        if (typeof window === "undefined") {
+            return;
+        }
+        let handled = false;
+        const handler = () => {
+            if (handled) {
+                return;
+            }
+            handled = true;
+            onUnloadSessionEnd();
+            this.getTransport()?.flushOnUnload();
+        };
+        const visibilityHandler = () => {
+            if (document.visibilityState !== "hidden") {
+                return;
+            }
+            this.getTransport()?.flushOnUnload();
+        };
+        window.addEventListener("pagehide", handler, { capture: true });
+        window.addEventListener("beforeunload", handler, { capture: true });
+        document.addEventListener("visibilitychange", visibilityHandler, {
+            capture: true,
+        });
+        this.unloadHandlers.push(() => {
+            window.removeEventListener("pagehide", handler, true);
+            window.removeEventListener("beforeunload", handler, true);
+            document.removeEventListener("visibilitychange", visibilityHandler, true);
+        });
+    }
+    isCaptureActive() {
+        return this.captureHandles.length > 0;
+    }
+    stopRuntimeSurfaces() {
+        this.stopCaptureModules();
+        if (this.flushDebounceTimer) {
+            clearTimeout(this.flushDebounceTimer);
+            this.flushDebounceTimer = null;
+        }
+        this.abortBrowserTokenWarmup();
+        for (const dispose of this.unloadHandlers) {
+            try {
+                dispose();
+            }
+            catch {
+                // Ignore.
+            }
+        }
+        this.unloadHandlers = [];
+    }
+}

package/dist/provider/sdk.d.ts

@@ -0,0 +1,2 @@
+import type { CluebaseBrowserSdk } from "./types.js";
+export declare const createCluebaseBrowserSdk: () => CluebaseBrowserSdk;