@genn-inc/cluebase-frontend-sdk 0.0.1 → 0.0.3

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

@@ -1,4 +1,4 @@
-import { trace } from "@opentelemetry/api";
+import { context, propagation, trace } from "@opentelemetry/api";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
@@ -7,6 +7,15 @@ import { ObservationSourceEventExporter } from "../exporter/observation-source-e
 import { createFrontendResourceAttributes } from "../exporter/frontend-resource.js";
 import { createCluebaseNetworkPropagator } from "../instrumentation/network.js";
 import { getSessionCaptureEligibility } from "./sdk-event-pipeline.js";
+const globalSnapshots = new WeakMap();
+const readContextManager = () => Reflect.get(context, "_getContextManager").call(context);
+const readPropagator = () => Reflect.get(propagation, "_getGlobalPropagator").call(propagation);
+const isNoopContextManager = (manager) => manager.constructor.name === "NoopContextManager";
+const isNoopPropagator = (propagator) => propagator.constructor.name === "NoopTextMapPropagator";
+const getTracerDelegate = (provider) => {
+    const candidate = provider;
+    return candidate.getDelegate?.();
+};
 export const createCluebaseOtelPipeline = ({ resolved, getTransport, getContext, }) => {
     if (!getTransport()) {
         return null;
@@ -73,9 +82,22 @@ export const createCluebaseOtelPipeline = ({ resolved, getTransport, getContext,
     const mode = resolved.otelProviderMode;
     const shouldRegister = mode === "register" || (mode === "detect" && !hasHostInstalledProvider());
     if (shouldRegister) {
+        const contextBeforeRegister = readContextManager();
+        const propagatorBeforeRegister = readPropagator();
         provider.register({
             propagator: createCluebaseNetworkPropagator(),
         });
+        globalSnapshots.set(provider, {
+            installedTracer: getTracerDelegate(trace.getTracerProvider()) === provider ? provider : null,
+            installedContextManager: isNoopContextManager(contextBeforeRegister)
+                ? readContextManager()
+                : null,
+            installedPropagator: isNoopPropagator(propagatorBeforeRegister)
+                ? readPropagator()
+                : null,
+            contextWasAlreadyRegistered: !isNoopContextManager(contextBeforeRegister),
+            propagatorWasAlreadyRegistered: !isNoopPropagator(propagatorBeforeRegister),
+        });
     }
     return provider;
 };
@@ -95,7 +117,10 @@ export const shutdownCluebaseOtelProvider = (provider) => {
     if (!provider) {
         return;
     }
-    void provider.shutdown().catch(() => undefined);
+    void provider
+        .shutdown()
+        .catch(() => undefined)
+        .finally(() => restoreCluebaseOtelGlobals(provider));
 };
 export const shutdownCluebaseOtelProviderAsync = async (provider) => {
     if (!provider) {
@@ -105,8 +130,30 @@ export const shutdownCluebaseOtelProviderAsync = async (provider) => {
         await provider.shutdown();
     }
     catch {
-        // shutdown is best-effort per OTel contract.
     }
+    finally {
+        restoreCluebaseOtelGlobals(provider);
+    }
+};
+const restoreCluebaseOtelGlobals = (provider) => {
+    const snapshot = globalSnapshots.get(provider);
+    if (!snapshot)
+        return;
+    if (snapshot.installedTracer &&
+        getTracerDelegate(trace.getTracerProvider()) === snapshot.installedTracer) {
+        trace.disable();
+    }
+    if (!snapshot.contextWasAlreadyRegistered &&
+        snapshot.installedContextManager &&
+        readContextManager() === snapshot.installedContextManager) {
+        context.disable();
+    }
+    if (!snapshot.propagatorWasAlreadyRegistered &&
+        snapshot.installedPropagator &&
+        readPropagator() === snapshot.installedPropagator) {
+        propagation.disable();
+    }
+    globalSnapshots.delete(provider);
 };
 export const forceFlushCluebaseOtelProvider = async (provider, signal) => {
     if (!provider) {
@@ -116,7 +163,6 @@ export const forceFlushCluebaseOtelProvider = async (provider, signal) => {
         await awaitWithAbort(provider.forceFlush(), signal);
     }
     catch {
-        // forceFlush is best-effort per OTel contract.
     }
 };
 const awaitWithAbort = async (promise, signal) => {

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

@@ -47,6 +47,9 @@ export class ProviderRuntimeSurfaces {
                     input.interactionId ??
                     null);
             },
+            bindEventContext: (event) => {
+                this.getTraceManager()?.bindEventContext(event);
+            },
             requestFlush: () => {
                 void this.flushCaptureSummaries("capture_flush");
                 if (this.flushDebounceTimer)
@@ -208,7 +211,6 @@ export class ProviderRuntimeSurfaces {
                 dispose();
             }
             catch {
-                // Ignore.
             }
         }
         this.unloadHandlers = [];

package/dist/provider/sdk.js

@@ -15,6 +15,7 @@ import { isValidPublicCustomEventName, normalizeProfileAvatarUrl, normalizePubli
 import { OFFICIAL_CUSTOM_EVENT_NAME, ProviderEventPipeline, readCurrentLifecycleUrl, } from "./sdk-event-pipeline.js";
 import { createCluebaseOtelPipeline, forceFlushCluebaseOtelProvider, shutdownCluebaseOtelProvider, shutdownCluebaseOtelProviderAsync, } from "./sdk-otel-pipeline.js";
 import { ProviderRuntimeSurfaces } from "./sdk-runtime-surfaces.js";
+import { getSdkErrorDetails, reportSdkError } from "./sdk-error.js";
 const createNoopLogger = () => {
     return {
         debug: () => undefined,
@@ -47,10 +48,6 @@ class CluebaseBrowserSdkImpl {
         this.traceManager = null;
         this.diagnostics = new DiagnosticStore();
         this.transport = null;
-        // OTel TracerProvider wired with the source-signal exporter so every span
-        // produced by `@opentelemetry/api`'s global tracer flows through
-        // `ObservationSourceEventExporter` → `BatchTransport.enqueue` →
-        // Cluebase ingest endpoint.
         this.tracerProvider = null;
         this.logger = logger;
         this.internalMetrics = new InternalMetricsStore();
@@ -120,6 +117,7 @@ class CluebaseBrowserSdkImpl {
             this.tabManager = new TabManager();
             this.organizationManager = new OrganizationManager();
             this.traceManager = new TraceManager();
+            this.traceManager.enableAsyncContext();
             this.environmentManager = new EnvironmentManager({
                 frontendRelease: resolved.release.frontendRelease,
                 contextTraitsProvider: resolved.contextTraitsProvider,
@@ -168,9 +166,6 @@ class CluebaseBrowserSdkImpl {
             if (this.consent !== "denied") {
                 this.warmupBrowserToken(ingestClient);
             }
-            // Wire WebTracerProvider with the canonical exporter. The provider is
-            // registered globally so OTel-instrumented code and capture modules
-            // converge on the same transport buffer.
             this.tracerProvider = createCluebaseOtelPipeline({
                 resolved,
                 getTransport: () => this.transport,
@@ -198,11 +193,24 @@ class CluebaseBrowserSdkImpl {
             }
             this.installUnloadHandlers();
         }
-        catch {
+        catch (error) {
+            const errorDetails = getSdkErrorDetails(error);
             this.logger.error("Cluebase Frontend SDK init failed", {
                 error_code: "sdk_operation_failed",
+                ...errorDetails,
             });
+            reportSdkError("init", error);
             this.warnPublicDrop("init", "sdk_operation_failed");
+            try {
+                this.shutdown();
+            }
+            catch (cleanupError) {
+                this.logger.error("Cluebase Frontend SDK init cleanup failed", {
+                    error_code: "sdk_cleanup_failed",
+                    ...getSdkErrorDetails(cleanupError),
+                });
+                reportSdkError("init cleanup", cleanupError);
+            }
         }
     }
     identify(userId, traits) {
@@ -214,8 +222,6 @@ class CluebaseBrowserSdkImpl {
             return;
         }
         try {
-            // Capture the pre-identify anonymous id so the worker can fuse the
-            // anonymous → identified subject as a single resolution chain.
             const normalizedUserId = normalizePublicIdentityId(userId);
             if (!normalizedUserId) {
                 this.warnPublicDrop("identify", "userId must be a non-empty string");
@@ -380,7 +386,6 @@ class CluebaseBrowserSdkImpl {
             },
         });
     }
-    // SDK は observation source event だけを送り、ingest core が意味付けを行う。
     setConsent(consent) {
         this.consent = consent;
         if (!this.initialized) {
@@ -421,7 +426,6 @@ class CluebaseBrowserSdkImpl {
             }
         }
         catch {
-            // Public warnings must never break the host app.
         }
     }
     warnPublicFieldDrop(operation, field, _reason) {
@@ -436,7 +440,6 @@ class CluebaseBrowserSdkImpl {
             }
         }
         catch {
-            // Public warnings must never break the host app.
         }
     }
     sanitizeIdentifyTraits(traits) {
@@ -479,7 +482,6 @@ class CluebaseBrowserSdkImpl {
     flushLifecycleEvents() {
         void this.transport?.flush();
     }
-    // 内部 transport の即時 flush を要求する。SPA navigation や明示的 shutdown シナリオ用。
     async flush() {
         const deadline = this.transport?.beginFlushDeadline();
         try {
@@ -491,7 +493,6 @@ class CluebaseBrowserSdkImpl {
             this.transport?.endFlushDeadline(deadline);
         }
     }
-    // 残バッファを flush した上で SDK を停止する。テスト / 明示的 shutdown 用。
     async close() {
         const closeSignal = this.transport?.beginClose();
         await awaitUntilDeadline(this.flushCaptureSummaries("close"), closeSignal);
@@ -499,7 +500,7 @@ class CluebaseBrowserSdkImpl {
         await forceFlushCluebaseOtelProvider(this.tracerProvider, closeSignal ?? undefined);
         await this.transport?.close();
         if (this.transport?.getDiagnostics().lifecycle === "closing_failed") {
-            this.runtimeSurfaces.stopRuntimeSurfaces();
+            await this.shutdownAsync();
             return;
         }
         await this.shutdownAsync();
@@ -544,14 +545,6 @@ class CluebaseBrowserSdkImpl {
     refreshSessionCaptureEligibility() {
         this.eventPipeline.refreshSessionCaptureEligibility();
     }
-    /**
-     * Sanitize an identity value (userId / organizationId) before publishing.
-     * If the caller passed an email / phone / credit-card / SSN-shaped
-     * value, hash it deterministically and warn via the internal logger.
-     * This prevents raw PII from landing in canonical span attributes
-     * (`cluebase.actor.user_id`) and raw observation storage.
-     *
-     */
     sanitizeIdentityValue(field, raw) {
         if (typeof raw !== "string")
             return raw;
@@ -587,6 +580,7 @@ class CluebaseBrowserSdkImpl {
             this.transport.dispose();
             this.transport = null;
         }
+        this.traceManager?.disableAsyncContext();
         this.traceManager = null;
         this.initialized = false;
         this.initSignature = null;

package/dist/provider/types.d.ts

@@ -3,11 +3,6 @@ import type { DiagnosticsSnapshot } from "../exporter/diagnostics.js";
 import type { FrontendEventName, ParameterCaptureMode, SdkCollectionMode } from "./contracts.js";
 export type { FrontendEventCategory, FrontendEventName, FrontendEventStatus, ParameterCaptureMode, SdkCollectionMode, } from "./contracts.js";
 export type CluebaseConsentState = "granted" | "denied" | "unknown";
-/**
- * MVP group taxonomy. Public `cluebase.group(...)` accepts only the customer
- * company concept. `account` / `workspace` are future concepts and are not
- * exposed as MVP group inputs.
- */
 export type CluebaseGroupType = "organization";
 export type CanonicalJsonValue = string | number | boolean | null | CanonicalJsonValue[] | {
     [key: string]: CanonicalJsonValue;
@@ -37,14 +32,8 @@ export type DiagnosticCollectionConfig = {
     reason?: string;
     enabledBy?: string;
 };
-/**
- * Public bootstrap options accepted by `cluebase.init`.
- *
- * The SDK derives dev/prod from the `projectKey` prefix. Browser ingest obtains
- * short-lived tokens from `POST <endpoint>/api/v1/ingest/browser-tokens`.
- */
 export type CluebaseInitOptions = {
-    endpoint: string;
+    endpoint?: string;
     projectKey: string;
     autocapture?: boolean;
     captureNetwork?: boolean;
@@ -70,23 +59,6 @@ export type CluebaseInitOptions = {
         frontendRelease?: string;
     };
     contextTraitsProvider?: () => CluebaseTrackProperties;
-    /**
-     * Controls how the SDK's internal ``WebTracerProvider`` interacts with
-     * the page's global OTel context.
-     *
-     * - ``"register"`` (default for SDKs initialised on pages without
-     *   pre-existing OTel): call ``WebTracerProvider#register()`` so any
-     *   ``trace.getTracer(...)`` call in the page routes through Cluebase's
-     *   exporter, including Cluebase's own runtime span emissions.
-     * - ``"standalone"``: do not register globally. Cluebase's pipeline is
-     *   private; only spans created via the SDK's own internal tracer
-     *   reach the exporter. Use this when the host app already manages an
-     *   OTel TracerProvider (Sentry, Datadog, Honeycomb, etc.) and Cluebase
-     *   must not hijack it.
-     * - ``"detect"`` (recommended): inspect ``trace.getTracerProvider()``;
-     *   if a non-proxy provider is already installed, behave as
-     *   ``standalone``; otherwise behave as ``register``.
-     */
     otelProviderMode?: "register" | "standalone" | "detect";
 };
 export type ResolvedCluebaseConfig = {
@@ -195,6 +167,7 @@ export type CluebaseContext = {
     trace_id: string;
     request_id: string;
     request_span_id: string;
+    action_id: string | null;
     interaction_id: string;
     correlation_id: string | null;
     sdk_collection_mode: SdkCollectionMode;
@@ -255,16 +228,6 @@ export type CluebaseSubjectProfile = {
     contact_identity_hash: string | null;
     contact_domain: string | null;
 };
-/**
- * Customer-facing trait dict accepted by `cluebase.identify` /
- * `cluebase.setOrganization`.
- *
- * Customers use the camelCase form on every SDK. The ingest core normalizes
- * these values after receiving the SDK source signal.
- *
- * `displayName`, `email`, and `emailAddress` are accepted alternate keys.
- * Email traits are transported only as privacy-safe contact-derived fields.
- */
 export type CluebaseSubjectTraits = {
     name?: string | null;
     email?: string | null;
@@ -315,6 +278,7 @@ export type CaptureModuleContext = {
         interactionScopeKey?: string | null;
         nowMs?: number;
     }) => string | null;
+    bindEventContext?: (event: Event) => void;
     requestFlush?: () => void;
 };
 export type CaptureStopHandle = {

package/dist/provider/usage-governor.js

@@ -4,8 +4,6 @@ export const DEFAULT_INGEST_USAGE_GOVERNOR_FEEDBACK = {
     limitReasons: [],
     retryAfterAt: null,
 };
-// 正本から生成した一覧をそのまま使います。ここへ書き写していたため
-// `replay_storage` が抜け、受付側が「止めよ」と言っても画面側が捨てていました。
 const COST_CAPABILITIES = new Set(GENERATED_COST_CAPABILITIES);
 const LIMIT_KINDS = new Set(GENERATED_LIMIT_KINDS);
 const THRESHOLD_STAGES = new Set(GENERATED_THRESHOLD_STAGES);

package/package.json

@@ -1,59 +1,54 @@
 {
-	"name": "@genn-inc/cluebase-frontend-sdk",
-	"version": "0.0.1",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/genn-inc/cluebase.git"
-	},
-	"description": "Cluebase Frontend SDK — OTel-based observation-source event capture for frontend apps",
-	"type": "module",
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
-	"files": [
-		"dist/",
-		"README.md"
-	],
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"browser": "./dist/index.js",
-			"default": "./dist/index.js"
-		}
-	},
-	"scripts": {
-		"build": "node ./scripts/clean-dist.mjs && node ../../../scripts/generate-shared-contract-tables.mjs && node ./scripts/generate-version-module.mjs && tsc -p tsconfig.build.json && node ./scripts/fix-esm-relative-imports.mjs",
-		"prepack": "pnpm build",
-		"prepublishOnly": "pnpm lint && pnpm test:cov && pnpm typecheck && pnpm test:package-import",
-		"lint": "pnpm exec biome lint src",
-		"test:package-import": "pnpm build && node ../../../tests/distribution/frontend-sdk/check-package-import.mjs",
-		"typecheck": "tsc -p tsconfig.typecheck.json",
-		"_comment_test": "実環境が要る試験 (`*-live.test.ts`) を既定の実行から外します (`tests/README.md` §12.2)。**綴りで拾います** — file 名を並べると、新しい live を足した人がここへ足し忘れて黙ります。**設定側 (`vitest.config.ts`) の `exclude` には置けません**: 実測 (2026-08-21) では、そこへ置くと live を名指しした実行まで `No test files found` で落ちます。script に置けば、手元と CI で対象が同じまま、実環境のあるジョブだけが名指しで拾えます。",
-		"test": "vitest run --config ../../../tests/config/vitest/frontend-sdk.config.ts --exclude \"../../../tests/integration/frontend-sdk/**/*-live.test.ts\"",
-		"test:cov": "vitest run --config ../../../tests/config/vitest/frontend-sdk.config.ts --coverage --exclude \"../../../tests/integration/frontend-sdk/**/*-live.test.ts\"",
-		"_comment_test_live": "実環境がある段だけがここを呼びます。**vitest の位置引数は glob ではなく道筋への部分一致です** — 実測 (2026-08-21): `vitest run \"src/**/*-live.test.ts\"` は `No test files found` で 0 件、`vitest run live.test.ts` は 1 件。綴りを CI ではなくここに置くので、CI 側は script 名を呼ぶだけになります。",
-		"test:live": "vitest run --config ../../../tests/config/vitest/frontend-sdk.config.ts ../../../tests/integration/frontend-sdk"
-	},
-	"devDependencies": {
-		"@cluebase/schema": "workspace:*",
-		"@cluebase/shared": "workspace:*",
-		"@vitest/coverage-v8": "^3.2.4",
-		"jsdom": "^26.1.0",
-		"typescript": "^5.9.3",
-		"vitest": "^3.2.7"
-	},
-	"dependencies": {
-		"@noble/hashes": "1.8.0",
-		"@opentelemetry/api": ">=1.9.1 <1.10.0",
-		"@opentelemetry/api-logs": ">=0.218.0 <1.0.0",
-		"@opentelemetry/browser-instrumentation": ">=0.5.2 <1.0.0",
-		"@opentelemetry/core": ">=2.7.1 <3.0.0",
-		"@opentelemetry/instrumentation-document-load": ">=0.63.0 <1.0.0",
-		"@opentelemetry/instrumentation-fetch": ">=0.218.0 <1.0.0",
-		"@opentelemetry/instrumentation-xml-http-request": ">=0.218.0 <1.0.0",
-		"@opentelemetry/resources": ">=2.7.1 <3.0.0",
-		"@opentelemetry/sdk-trace-base": ">=2.7.1 <3.0.0",
-		"@opentelemetry/sdk-trace-web": ">=2.7.1 <3.0.0",
-		"json-canonicalize": "2.0.0",
-		"zod": "^4.4.3"
-	}
-}
+  "name": "@genn-inc/cluebase-frontend-sdk",
+  "version": "0.0.3",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/genn-inc/cluebase.git"
+  },
+  "description": "Cluebase Frontend SDK — OTel-based observation-source event capture for frontend apps",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "jsdom": "^26.1.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7",
+    "@cluebase/schema": "1.0.0",
+    "@cluebase/shared": "1.0.0"
+  },
+  "dependencies": {
+    "@noble/hashes": "1.8.0",
+    "@opentelemetry/api": ">=1.9.1 <1.10.0",
+    "@opentelemetry/api-logs": ">=0.218.0 <1.0.0",
+    "@opentelemetry/browser-instrumentation": ">=0.5.2 <1.0.0",
+    "@opentelemetry/core": ">=2.7.1 <3.0.0",
+    "@opentelemetry/instrumentation-document-load": ">=0.63.0 <1.0.0",
+    "@opentelemetry/instrumentation-fetch": ">=0.218.0 <1.0.0",
+    "@opentelemetry/instrumentation-xml-http-request": ">=0.218.0 <1.0.0",
+    "@opentelemetry/resources": ">=2.7.1 <3.0.0",
+    "@opentelemetry/sdk-trace-base": ">=2.7.1 <3.0.0",
+    "@opentelemetry/sdk-trace-web": ">=2.7.1 <3.0.0",
+    "json-canonicalize": "2.0.0",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "node ./scripts/clean-dist.mjs && node ../../../scripts/generate-shared-contract-tables.mjs && node ./scripts/generate-version-module.mjs && tsc -p tsconfig.build.json && node ./scripts/fix-esm-relative-imports.mjs",
+    "lint": "pnpm exec biome lint src",
+    "test:package-import": "pnpm build && node ../../../tests/distribution/frontend-sdk/check-package-import.mjs",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run --config ../../../tests/config/vitest/frontend-sdk.config.ts",
+    "test:cov": "vitest run --config ../../../tests/config/vitest/frontend-sdk.config.ts --coverage"
+  }
+}