@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/exporter/event-id.js

@@ -0,0 +1,75 @@
+const randomBytes = (length) => {
+    if (typeof globalThis.crypto === "undefined" ||
+        typeof globalThis.crypto.getRandomValues !== "function") {
+        throw new Error("Cluebase SDK requires crypto.getRandomValues for ID generation");
+    }
+    const bytes = new Uint8Array(length);
+    globalThis.crypto.getRandomValues(bytes);
+    return bytes;
+};
+const toHex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+let generatorId = null;
+let monotonicCounter = 0;
+let lastMonotonicTime = 0;
+const getGeneratorId = () => {
+    generatorId ?? (generatorId = toHex(randomBytes(16)));
+    return generatorId;
+};
+const nextMonotonicParts = () => {
+    const performanceNow = typeof globalThis.performance !== "undefined" &&
+        typeof globalThis.performance.now === "function"
+        ? Math.floor(globalThis.performance.now() * 1000)
+        : Date.now();
+    const monotonicTime = performanceNow > lastMonotonicTime
+        ? performanceNow
+        : lastMonotonicTime + 1;
+    lastMonotonicTime = monotonicTime;
+    monotonicCounter = (monotonicCounter + 1) % Number.MAX_SAFE_INTEGER;
+    return { monotonicTime, counter: monotonicCounter };
+};
+export const generateMonotonicId = (prefix) => {
+    const { monotonicTime, counter } = nextMonotonicParts();
+    const generator = getGeneratorId();
+    const id = [
+        generator,
+        monotonicTime.toString(36),
+        counter.toString(36),
+        toHex(randomBytes(8)),
+    ].join("_");
+    return prefix ? `${prefix}_${id}` : id;
+};
+export const generateTraceId = () => {
+    const { monotonicTime, counter } = nextMonotonicParts();
+    const generator = getGeneratorId();
+    return [
+        generator.slice(0, 12),
+        monotonicTime.toString(16).padStart(12, "0").slice(-12),
+        counter.toString(16).padStart(4, "0").slice(-4),
+        toHex(randomBytes(2)),
+    ].join("");
+};
+export const generateEventId = () => {
+    return generateMonotonicId();
+};
+export const generateAnonymousId = () => {
+    return generateMonotonicId("anon");
+};
+export const generateSessionId = () => {
+    return generateMonotonicId("sess");
+};
+export const generateTabId = () => {
+    return generateMonotonicId("tab");
+};
+export const generateRequestId = () => {
+    return generateMonotonicId("req");
+};
+export const generateRequestSpanId = () => {
+    const { counter } = nextMonotonicParts();
+    return `${counter.toString(16).padStart(4, "0").slice(-4)}${toHex(randomBytes(6))}`;
+};
+export const generateInteractionId = () => {
+    return generateMonotonicId("int");
+};
+export const generateViewId = () => {
+    return generateMonotonicId("view");
+};

package/dist/exporter/frontend-resource.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedCluebaseConfig } from "../provider/types.js";
+export type FrontendResourceAttributes = Readonly<Record<string, string>>;
+export type FrontendResourceInput = FrontendResourceAttributes | {
+    readonly attributes?: Readonly<Record<string, unknown>>;
+};
+type ResourceRecord = {
+    [key: string]: string;
+};
+/**
+ * Build the only Resource attributes emitted by the browser SDK's own OTel
+ * provider. Values are intentionally strings so the same snapshot can be
+ * used to construct an OTel Resource and to enrich raw source signals.
+ */
+export declare const createFrontendResourceAttributes: (resolved: ResolvedCluebaseConfig) => FrontendResourceAttributes;
+/**
+ * Copy only approved frontend Resource attributes into the serialized source
+ * signal. The returned object is a detached, bounded JSON-safe snapshot.
+ */
+export declare const toFrontendSourceResource: (resource: FrontendResourceInput | undefined, deniedKeys?: readonly string[]) => ResourceRecord;
+export {};

package/dist/exporter/frontend-resource.js

@@ -0,0 +1,52 @@
+import { isDeniedKey } from "./sanitize.js";
+import { SDK_VERSION } from "../provider/constants.js";
+import { CLUEBASE_OTEL_SDK_SOURCE_REQUIRED_RESOURCE_KEYS, CLUEBASE_OTEL_SDK_SOURCE_RESOURCE_KEYS, } from "../_generated/otel-resource-keys.js";
+const FRONTEND_RESOURCE_KEYS = new Set(CLUEBASE_OTEL_SDK_SOURCE_RESOURCE_KEYS);
+const FRONTEND_REQUIRED_RESOURCE_KEYS = new Set(CLUEBASE_OTEL_SDK_SOURCE_REQUIRED_RESOURCE_KEYS);
+const MAX_RESOURCE_VALUE_BYTES = 512;
+/**
+ * Build the only Resource attributes emitted by the browser SDK's own OTel
+ * provider. Values are intentionally strings so the same snapshot can be
+ * used to construct an OTel Resource and to enrich raw source signals.
+ */
+export const createFrontendResourceAttributes = (resolved) => ({
+    "service.name": resolved.producerId,
+    "service.version": resolved.release.frontendRelease ?? "unknown",
+    "cluebase.project_key": resolved.projectKey,
+    "cluebase.producer_id": resolved.producerId,
+    "cluebase.service_type": "frontend",
+    "cluebase.sdk.type": "browser",
+    "cluebase.sdk.version": SDK_VERSION,
+    "cluebase.sdk.collection_mode": resolved.collection?.mode ?? "standard",
+    "cluebase.runtime_language": "browser",
+});
+/**
+ * Copy only approved frontend Resource attributes into the serialized source
+ * signal. The returned object is a detached, bounded JSON-safe snapshot.
+ */
+export const toFrontendSourceResource = (resource, deniedKeys = []) => {
+    const input = resource && "attributes" in resource ? resource.attributes : resource;
+    const output = {};
+    let entries;
+    try {
+        entries = Object.entries(input ?? {});
+    }
+    catch {
+        return output;
+    }
+    for (const [key, value] of entries) {
+        if (!FRONTEND_RESOURCE_KEYS.has(key) ||
+            (isDeniedKey(key, deniedKeys) && !FRONTEND_REQUIRED_RESOURCE_KEYS.has(key))) {
+            continue;
+        }
+        if (key === "cluebase.service_type" && value !== "frontend") {
+            continue;
+        }
+        if (typeof value === "string" &&
+            value.trim().length > 0 &&
+            new TextEncoder().encode(value).byteLength <= MAX_RESOURCE_VALUE_BYTES) {
+            output[key] = value;
+        }
+    }
+    return output;
+};

package/dist/exporter/local-minimization.d.ts

@@ -0,0 +1,29 @@
+type LocalValueType = "string" | "number" | "boolean" | "null" | "object" | "array";
+export type LocalTextDescriptor = {
+    present: true;
+    length: number;
+};
+export type LocalValueDescriptor = {
+    present: true;
+    valueType: LocalValueType;
+    length?: number;
+    itemCount?: number;
+    keyCount?: number;
+    fileCount?: number;
+};
+export type LocalStructuredSummary = LocalValueDescriptor | {
+    present: true;
+    valueType: "object";
+    keyCount: number;
+    fields: Record<string, LocalStructuredSummary | null>;
+} | {
+    present: true;
+    valueType: "array";
+    itemCount: number;
+    items: Array<LocalStructuredSummary | null>;
+};
+export declare const buildLocalTextDescriptor: (value: string | null | undefined) => LocalTextDescriptor | null;
+export declare const buildLocalValueDescriptor: (value: unknown) => LocalValueDescriptor | null;
+export declare const buildLocalStructuredSummary: (value: unknown, depth?: number) => LocalStructuredSummary | null;
+export declare const buildLocalQuerySummary: (query: Record<string, string | string[]>) => Record<string, LocalStructuredSummary | null>;
+export {};

package/dist/exporter/local-minimization.js

@@ -0,0 +1,87 @@
+const MAX_SUMMARY_DEPTH = 4;
+const MAX_SUMMARY_KEYS = 32;
+const MAX_SUMMARY_ITEMS = 12;
+const isReadableObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+export const buildLocalTextDescriptor = (value) => {
+    if (value == null) {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    return {
+        present: true,
+        length: trimmed.length,
+    };
+};
+export const buildLocalValueDescriptor = (value) => {
+    if (value == null) {
+        return null;
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed
+            ? { present: true, valueType: "string", length: trimmed.length }
+            : null;
+    }
+    if (typeof value === "number") {
+        return { present: true, valueType: "number" };
+    }
+    if (typeof value === "boolean") {
+        return { present: true, valueType: "boolean" };
+    }
+    if (Array.isArray(value)) {
+        return {
+            present: true,
+            valueType: "array",
+            itemCount: value.length,
+        };
+    }
+    if (isReadableObject(value)) {
+        const fileCount = typeof value.fileCount === "number" && Number.isFinite(value.fileCount)
+            ? Math.max(0, Math.floor(value.fileCount))
+            : undefined;
+        return {
+            present: true,
+            valueType: "object",
+            keyCount: Object.keys(value).length,
+            ...(typeof fileCount === "number" ? { fileCount } : {}),
+        };
+    }
+    return null;
+};
+export const buildLocalStructuredSummary = (value, depth = 0) => {
+    if (depth >= MAX_SUMMARY_DEPTH) {
+        return buildLocalValueDescriptor(value);
+    }
+    if (Array.isArray(value)) {
+        return {
+            present: true,
+            valueType: "array",
+            itemCount: value.length,
+            items: value
+                .slice(0, MAX_SUMMARY_ITEMS)
+                .map((entry) => buildLocalStructuredSummary(entry, depth + 1)),
+        };
+    }
+    if (isReadableObject(value)) {
+        const limitedEntries = Object.entries(value).slice(0, MAX_SUMMARY_KEYS);
+        return {
+            present: true,
+            valueType: "object",
+            keyCount: Object.keys(value).length,
+            fields: Object.fromEntries(limitedEntries.map(([key, child]) => [
+                key,
+                buildLocalStructuredSummary(child, depth + 1),
+            ])),
+        };
+    }
+    return buildLocalValueDescriptor(value);
+};
+export const buildLocalQuerySummary = (query) => {
+    return Object.fromEntries(Object.entries(query).map(([key, value]) => [
+        key,
+        buildLocalStructuredSummary(value),
+    ]));
+};

package/dist/exporter/observation-source-event-exporter.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Browser-SDK observation source event exporter.
+ *
+ * Production OTel {@link SpanExporter} for the Frontend SDK. Forwards each
+ * {@link ReadableSpan} as a source-signal envelope and routes it onto the
+ * SDK's existing transport buffer. Final classification and canonical shaping
+ * happen in the Cluebase backend ingestion core.
+ *
+ * The exporter is registered onto the global `WebTracerProvider` in
+ * `provider/sdk.ts:cluebase.init`. `enqueue(event)` accepts source-signal
+ * envelopes from capture modules.
+ */
+import { type ExportResult, ExportResultCode } from "@opentelemetry/core";
+import type { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
+import type { CluebaseContext } from "../provider/types.js";
+import type { CollectionPermit } from "./browser-outbox.js";
+import type { BrowserSourceEvent, BrowserSourceSignalEvent } from "./source-event.js";
+export declare const EXPORT_RESULT_SUCCESS: ExportResultCode;
+export declare const EXPORT_RESULT_FAILED: ExportResultCode;
+export interface ObservationSourceEventExporterOptions {
+    enqueueImpl: (event: BrowserSourceEvent, permit?: CollectionPermit) => void;
+    getCollectionPermit?: (span: ReadableSpan | null) => CollectionPermit | undefined;
+    flushImpl: () => Promise<void>;
+    shutdownImpl?: () => Promise<void>;
+    /**
+     * Returns the active {@link CluebaseContext} for the current SDK instance.
+     * Called once per `export()` invocation so browser-environment fields
+     * (device, browser, locale, etc.) reflect the SDK state at export time.
+     */
+    getContext: () => CluebaseContext;
+    deniedKeys?: readonly string[];
+    /**
+     * URL prefixes that should NOT produce source-signal events.
+     * Used to skip spans that the Cluebase ingest BatchTransport itself
+     * generates when the host installs ``@opentelemetry/instrumentation-fetch``
+     * (otherwise Cluebase's own POSTs would loop back through the exporter as
+     * fetch spans, generating duplicate ingest events ad-infinitum).
+     */
+    ignoreUrlPrefixes?: readonly string[];
+}
+export declare class ObservationSourceEventExporter implements SpanExporter {
+    private closed;
+    private readonly enqueueImpl;
+    private readonly getCollectionPermit;
+    private readonly flushImpl;
+    private readonly shutdownImpl?;
+    private readonly getContext;
+    private readonly deniedKeys;
+    private readonly ignoreUrlPrefixes;
+    private exportedSpanCount;
+    private droppedSpanCount;
+    private skippedLoopSpanCount;
+    constructor(options: ObservationSourceEventExporterOptions);
+    private ignoreSpanReason;
+    /**
+     * Enqueue a source-signal event emitted by capture modules through
+     * `context.onEvent`.
+     */
+    enqueue(event: BrowserSourceSignalEvent): void;
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    internalMetrics(): {
+        exported_span_count: number;
+        dropped_span_count: number;
+        skipped_loop_span_count: number;
+        closed: boolean;
+    };
+}

package/dist/exporter/observation-source-event-exporter.js

@@ -0,0 +1,154 @@
+/**
+ * Browser-SDK observation source event exporter.
+ *
+ * Production OTel {@link SpanExporter} for the Frontend SDK. Forwards each
+ * {@link ReadableSpan} as a source-signal envelope and routes it onto the
+ * SDK's existing transport buffer. Final classification and canonical shaping
+ * happen in the Cluebase backend ingestion core.
+ *
+ * The exporter is registered onto the global `WebTracerProvider` in
+ * `provider/sdk.ts:cluebase.init`. `enqueue(event)` accepts source-signal
+ * envelopes from capture modules.
+ */
+import { ExportResultCode } from "@opentelemetry/core";
+import { logSwallowed } from "../internal/internal-log.js";
+import { spanToSourceSignalEvent } from "./span-to-source-signal.js";
+export const EXPORT_RESULT_SUCCESS = ExportResultCode.SUCCESS;
+export const EXPORT_RESULT_FAILED = ExportResultCode.FAILED;
+export class ObservationSourceEventExporter {
+    constructor(options) {
+        this.closed = false;
+        this.exportedSpanCount = 0;
+        this.droppedSpanCount = 0;
+        this.skippedLoopSpanCount = 0;
+        this.enqueueImpl = options.enqueueImpl;
+        this.getCollectionPermit = options.getCollectionPermit ?? null;
+        this.flushImpl = options.flushImpl;
+        this.shutdownImpl = options.shutdownImpl;
+        this.getContext = options.getContext;
+        this.deniedKeys = options.deniedKeys ?? [];
+        this.ignoreUrlPrefixes = (options.ignoreUrlPrefixes ?? []).filter((p) => typeof p === "string" && p.length > 0);
+    }
+    ignoreSpanReason(span) {
+        const spanFields = span;
+        const attrs = spanFields.attributes ?? {};
+        if (attrs["cluebase.capture.skip"] === true)
+            return "loop";
+        const httpUrl = attrs["http.url"];
+        const fullUrl = attrs["url.full"];
+        const url = typeof httpUrl === "string"
+            ? httpUrl
+            : typeof fullUrl === "string"
+                ? fullUrl
+                : undefined;
+        if (url &&
+            this.ignoreUrlPrefixes.some((prefix) => url.startsWith(prefix))) {
+            return "loop";
+        }
+        if (!Object.keys(attrs).some((key) => key.startsWith("cluebase."))) {
+            return "unmarked";
+        }
+        return null;
+    }
+    /**
+     * Enqueue a source-signal event emitted by capture modules through
+     * `context.onEvent`.
+     */
+    enqueue(event) {
+        if (this.closed)
+            return;
+        const permit = this.getCollectionPermit?.(null);
+        if (this.getCollectionPermit && permit === undefined) {
+            return;
+        }
+        this.enqueueImpl(event, permit);
+    }
+    export(spans, resultCallback) {
+        if (this.closed) {
+            resultCallback({
+                code: ExportResultCode.FAILED,
+                error: new Error("exporter_closed"),
+            });
+            return;
+        }
+        try {
+            const context = this.getContext();
+            for (const span of spans) {
+                const ignoreReason = this.ignoreSpanReason(span);
+                if (ignoreReason) {
+                    if (ignoreReason === "loop") {
+                        this.skippedLoopSpanCount += 1;
+                    }
+                    continue;
+                }
+                try {
+                    const permit = this.getCollectionPermit?.(span);
+                    if (this.getCollectionPermit && permit === undefined) {
+                        this.droppedSpanCount += 1;
+                        continue;
+                    }
+                    const sourceSignal = spanToSourceSignalEvent(span, {
+                        context,
+                        deniedKeys: this.deniedKeys,
+                    });
+                    this.enqueueImpl(sourceSignal, permit);
+                    this.exportedSpanCount += 1;
+                }
+                catch (cause) {
+                    this.droppedSpanCount += 1;
+                    logSwallowed("spanToSourceSignalEvent", cause, {
+                        spanName: span.name,
+                    });
+                }
+            }
+            void this.flushImpl()
+                .then(() => resultCallback({ code: ExportResultCode.SUCCESS }))
+                .catch((cause) => resultCallback({
+                code: ExportResultCode.FAILED,
+                error: cause instanceof Error ? cause : new Error(String(cause)),
+            }));
+        }
+        catch (cause) {
+            resultCallback({
+                code: ExportResultCode.FAILED,
+                error: cause instanceof Error ? cause : new Error(String(cause)),
+            });
+        }
+    }
+    async forceFlush() {
+        if (this.closed)
+            return;
+        try {
+            await this.flushImpl();
+        }
+        catch (cause) {
+            // forceFlush is best-effort; swallow to keep the OTel contract.
+            logSwallowed("forceFlush", cause);
+        }
+    }
+    async shutdown() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            if (this.shutdownImpl) {
+                await this.shutdownImpl();
+            }
+            else {
+                await this.flushImpl();
+            }
+        }
+        catch (cause) {
+            // shutdown is non-raising per the OTel contract.
+            logSwallowed("shutdown", cause);
+        }
+    }
+    internalMetrics() {
+        return {
+            exported_span_count: this.exportedSpanCount,
+            dropped_span_count: this.droppedSpanCount,
+            skipped_loop_span_count: this.skippedLoopSpanCount,
+            closed: this.closed,
+        };
+    }
+}

package/dist/exporter/parameter-snapshot.d.ts

@@ -0,0 +1,14 @@
+import type { ParameterSnapshotValue } from "../provider/types.js";
+export type ParameterSnapshotBundle = {
+    snapshot: ParameterSnapshotValue;
+    allowedValueKeys: string[];
+};
+type ParameterSnapshotOptions = {
+    allowedPaths: readonly string[];
+    deniedKeys: readonly string[];
+    pathPrefix?: string;
+};
+export declare const buildUnavailableParameterSnapshot: () => ParameterSnapshotValue;
+export declare const truncateParameterSnapshotValue: (value: ParameterSnapshotValue) => ParameterSnapshotValue;
+export declare const buildParameterSnapshotBundle: (value: unknown, options: ParameterSnapshotOptions) => ParameterSnapshotBundle;
+export {};