@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/provider/sdk.js

@@ -0,0 +1,614 @@
+import { EnvironmentManager } from "../context/environment.js";
+import { IdentityManager } from "../context/identity.js";
+import { OrganizationManager } from "../context/organization.js";
+import { SessionManager } from "../context/session.js";
+import { TabManager } from "../context/tab.js";
+import { TraceManager } from "../context/trace.js";
+import { BatchTransport } from "../exporter/batch.js";
+import { IngestClient } from "../exporter/client.js";
+import { DiagnosticStore } from "../exporter/diagnostics.js";
+import { detectIdentityPII, hashIdentityValue, isDeniedKey, } from "../exporter/sanitize.js";
+import { InternalMetricsStore } from "../internal/metrics.js";
+import { isConfigValid, resolveConfig, validateConfig } from "./config.js";
+import { DEFAULT_BATCH_FLUSH_THRESHOLD_BYTES, DEFAULT_CONSENT, DEFAULT_MAX_BATCH_QUEUE_BYTES, DEFAULT_MAX_BATCH_QUEUE_ITEMS, SDK_VERSION, } from "./constants.js";
+import { isValidPublicCustomEventName, normalizeProfileAvatarUrl, normalizePublicIdentityId, toStringOrNull, } from "./sdk-input-normalization.js";
+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";
+const createNoopLogger = () => {
+    return {
+        debug: () => undefined,
+        warn: () => undefined,
+        error: () => undefined,
+    };
+};
+const PROFILE_IDENTITY_KEYS = new Set([
+    "accountId",
+    "account_id",
+    "workspaceId",
+    "workspace_id",
+    "organizationId",
+    "organization_id",
+]);
+const safeProfileKeys = (traits, deniedKeys) => Object.keys(traits ?? {})
+    .filter((key) => !PROFILE_IDENTITY_KEYS.has(key) && !isDeniedKey(key, deniedKeys))
+    .sort();
+class CluebaseBrowserSdkImpl {
+    constructor(logger = createNoopLogger()) {
+        this.config = null;
+        this.initialized = false;
+        this.initSignature = null;
+        this.consent = DEFAULT_CONSENT;
+        this.identityManager = null;
+        this.sessionManager = null;
+        this.tabManager = null;
+        this.organizationManager = null;
+        this.environmentManager = null;
+        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();
+        this.eventPipeline = new ProviderEventPipeline();
+        this.runtimeSurfaces = new ProviderRuntimeSurfaces({
+            internalMetrics: this.internalMetrics,
+            logger: this.logger,
+            enqueueRawEvent: (event) => {
+                this.enqueueRawEvent(event);
+            },
+            getViewId: () => this.eventPipeline.getViewId(),
+            getConsent: () => this.consent,
+            getObservationContext: () => this.eventPipeline.getObservationContext(),
+            getTraceManager: () => this.traceManager,
+            getTransport: () => this.transport,
+            getTracerProvider: () => this.tracerProvider,
+        });
+    }
+    getInternalMetrics() {
+        return this.internalMetrics.getSnapshot();
+    }
+    getDiagnostics() {
+        return this.diagnostics.snapshot();
+    }
+    init(options) {
+        try {
+            const resolved = resolveConfig(options);
+            const issues = validateConfig(resolved);
+            if (!isConfigValid(resolved)) {
+                this.logger.warn("Cluebase Frontend SDK init validation failed", {
+                    error_code: "invalid_sdk_config",
+                });
+                this.warnPublicDrop("init", `invalid SDK config: ${issues.join(", ")}`);
+                return;
+            }
+            const nextSignature = JSON.stringify({
+                endpoint: resolved.endpoint,
+                originalEndpoint: resolved.originalEndpoint,
+                localSetupCheckEndpoint: resolved.localSetupCheckEndpoint,
+                projectKey: resolved.projectKey,
+                producerId: resolved.producerId,
+                transportProfile: resolved.transportProfile,
+                autocapture: resolved.autocapture,
+                captureNetwork: resolved.captureNetwork,
+                captureErrors: resolved.captureErrors,
+                capturePerformance: resolved.capturePerformance,
+                network: resolved.network,
+                batch: resolved.batch,
+                privacy: resolved.privacy,
+                sampling: resolved.sampling,
+                collection: resolved.collection,
+                release: resolved.release,
+            });
+            if (this.initialized && this.initSignature === nextSignature) {
+                this.logger.debug("Cluebase Frontend SDK init skipped", {
+                    reason: "same_config",
+                });
+                return;
+            }
+            this.shutdown();
+            this.internalMetrics.reset();
+            this.diagnostics = new DiagnosticStore();
+            this.config = resolved;
+            this.initSignature = nextSignature;
+            this.identityManager = new IdentityManager();
+            this.sessionManager = new SessionManager();
+            this.tabManager = new TabManager();
+            this.organizationManager = new OrganizationManager();
+            this.traceManager = new TraceManager();
+            this.environmentManager = new EnvironmentManager({
+                frontendRelease: resolved.release.frontendRelease,
+                contextTraitsProvider: resolved.contextTraitsProvider,
+            });
+            const effectiveBatch = resolved.batch;
+            const ingestClient = new IngestClient({
+                endpoint: resolved.endpoint,
+                projectKey: resolved.projectKey,
+                sdkType: "browser",
+                sdkVersion: SDK_VERSION,
+                schemaVersion: 1,
+                metrics: this.internalMetrics,
+                diagnostics: this.diagnostics,
+            });
+            this.transport = new BatchTransport({
+                client: ingestClient,
+                enabled: effectiveBatch.enabled,
+                flushIntervalMs: effectiveBatch.flushIntervalMs,
+                maxPayloadBytes: effectiveBatch.maxPayloadBytes,
+                flushThresholdBytes: DEFAULT_BATCH_FLUSH_THRESHOLD_BYTES,
+                queueMaxBytes: DEFAULT_MAX_BATCH_QUEUE_BYTES,
+                queueMaxItems: DEFAULT_MAX_BATCH_QUEUE_ITEMS,
+                projectKey: resolved.projectKey,
+                initialConsent: this.consent,
+                metrics: this.internalMetrics,
+                diagnostics: this.diagnostics,
+                onGovernorFeedback: (feedback) => {
+                    this.applyUsageGovernorFeedback(feedback);
+                },
+            });
+            this.consent = this.transport.currentConsent();
+            this.transport.start();
+            this.eventPipeline.configure({
+                config: resolved,
+                identityManager: this.identityManager,
+                sessionManager: this.sessionManager,
+                tabManager: this.tabManager,
+                organizationManager: this.organizationManager,
+                environmentManager: this.environmentManager,
+                traceManager: this.traceManager,
+                transport: this.transport,
+                internalMetrics: this.internalMetrics,
+                logger: this.logger,
+                getConsent: () => this.consent,
+            });
+            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,
+                getContext: () => this.buildContext(),
+            });
+            this.initialized = true;
+            this.refreshSessionCaptureEligibility();
+            const sessionLifecycle = this.sessionManager.ensureActiveSession(Date.now());
+            if (sessionLifecycle.started) {
+                this.enqueueRawEvent({
+                    type: "session_started",
+                    occurredAtMs: Date.now(),
+                    payload: {
+                        entryUrl: readCurrentLifecycleUrl(),
+                    },
+                }, true);
+            }
+            this.enqueueOfficialCustomEvent(OFFICIAL_CUSTOM_EVENT_NAME.sdkInitialized, {
+                sdk_action: "init",
+                sdk_scope: "lifecycle",
+            }, true);
+            this.flushLifecycleEvents();
+            if (resolved.autocapture && this.consent !== "denied") {
+                this.startCaptureModules();
+            }
+            this.installUnloadHandlers();
+        }
+        catch {
+            this.logger.error("Cluebase Frontend SDK init failed", {
+                error_code: "sdk_operation_failed",
+            });
+            this.warnPublicDrop("init", "sdk_operation_failed");
+        }
+    }
+    identify(userId, traits) {
+        if (!this.ensureInitializedForPublicCall("identify")) {
+            return;
+        }
+        if (!this.identityManager) {
+            this.warnPublicDrop("identify", "identity manager is unavailable");
+            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");
+                return;
+            }
+            const previousAnonymousId = this.identityManager.getContext().anonymousId;
+            const sanitizedUserId = this.sanitizeIdentityValue("userId", normalizedUserId);
+            const sanitizedTraits = this.sanitizeIdentifyTraits(traits);
+            const subjectProfileKeys = safeProfileKeys(traits, this.config?.privacy.deniedKeys ?? []);
+            this.identityManager.identify(sanitizedUserId, sanitizedTraits);
+            this.enqueueOfficialCustomEvent(OFFICIAL_CUSTOM_EVENT_NAME.identityIdentified, {
+                identity_action: "identify",
+                profile_keys: subjectProfileKeys,
+            }, false, {
+                link_type: "anonymous_to_user",
+                anonymous_id: previousAnonymousId,
+                user_id: sanitizedUserId,
+            });
+            this.flushLifecycleEvents();
+        }
+        catch {
+            this.logger.error("identify failed", {
+                error_code: "sdk_operation_failed",
+            });
+        }
+    }
+    setOrganization(organizationId, traits) {
+        if (!this.ensureInitializedForPublicCall("setOrganization")) {
+            return;
+        }
+        if (!this.organizationManager) {
+            this.warnPublicDrop("setOrganization", "organization manager is unavailable");
+            return;
+        }
+        try {
+            const normalizedOrganizationId = normalizePublicIdentityId(organizationId);
+            if (!normalizedOrganizationId) {
+                this.warnPublicDrop("setOrganization", "organizationId must be a non-empty string");
+                return;
+            }
+            const sanitizedOrgId = this.sanitizeIdentityValue("organizationId", normalizedOrganizationId);
+            const previousUserId = this.identityManager?.getContext().userId ?? null;
+            const organizationProfileKeys = safeProfileKeys(traits, this.config?.privacy.deniedKeys ?? []);
+            this.organizationManager.setOrganization(sanitizedOrgId, traits);
+            this.enqueueOfficialCustomEvent(OFFICIAL_CUSTOM_EVENT_NAME.organizationAssociated, {
+                organization_action: "associate",
+                profile_keys: organizationProfileKeys,
+            }, false, {
+                link_type: "user_to_organization",
+                user_id: previousUserId,
+                organization_id: sanitizedOrgId,
+            });
+            this.flushLifecycleEvents();
+        }
+        catch {
+            this.logger.error("setOrganization failed", {
+                error_code: "sdk_operation_failed",
+            });
+        }
+    }
+    reset() {
+        if (!this.initialized) {
+            return;
+        }
+        try {
+            const previousUserId = this.identityManager?.getContext().userId ?? null;
+            const previousOrganizationId = this.organizationManager?.getContext().organizationId ?? null;
+            this.enqueueOfficialCustomEvent(OFFICIAL_CUSTOM_EVENT_NAME.identityReset, {
+                identity_action: "reset",
+            }, false, {
+                link_type: "logout",
+                user_id: previousUserId,
+                organization_id: previousOrganizationId,
+            });
+        }
+        catch {
+            this.logger.error("reset failed", {
+                error_code: "sdk_operation_failed",
+            });
+        }
+        finally {
+            this.resetSessionState();
+        }
+    }
+    logout() {
+        if (!this.initialized) {
+            return;
+        }
+        try {
+            const previousUserId = this.identityManager?.getContext().userId ?? null;
+            const previousOrganizationId = this.organizationManager?.getContext().organizationId ?? null;
+            this.enqueueOfficialCustomEvent(OFFICIAL_CUSTOM_EVENT_NAME.identityReset, {
+                identity_action: "logout",
+            }, false, {
+                link_type: "logout",
+                user_id: previousUserId,
+                organization_id: previousOrganizationId,
+            });
+        }
+        catch {
+            this.logger.error("logout failed", {
+                error_code: "sdk_operation_failed",
+            });
+        }
+        finally {
+            this.resetSessionState();
+        }
+    }
+    resetSessionState() {
+        if (!this.initialized) {
+            return;
+        }
+        try {
+            const ended = this.sessionManager?.endSession(Date.now());
+            if (ended) {
+                this.enqueueRawEvent({
+                    type: "session_ended",
+                    occurredAtMs: Date.now(),
+                    payload: {
+                        sessionId: ended.sessionId,
+                        exitUrl: readCurrentLifecycleUrl(),
+                        durationMs: ended.durationMs,
+                    },
+                }, true);
+            }
+            this.identityManager?.reset();
+            this.organizationManager?.reset();
+            this.traceManager?.reset({ preserveActiveInteraction: true });
+            this.sessionManager?.reset(Date.now());
+            this.eventPipeline.resetViewId();
+            this.enqueueRawEvent({
+                type: "session_started",
+                occurredAtMs: Date.now(),
+                payload: {
+                    entryUrl: readCurrentLifecycleUrl(),
+                },
+            }, true);
+            this.flushLifecycleEvents();
+        }
+        catch {
+            this.logger.error("reset session state failed", {
+                error_code: "sdk_operation_failed",
+            });
+        }
+    }
+    track(eventName, properties, metrics) {
+        if (!this.ensureInitializedForPublicCall("track")) {
+            return;
+        }
+        if (!isValidPublicCustomEventName(eventName)) {
+            this.warnPublicDrop("track", "eventName must match ^[A-Za-z0-9_.:-]{1,128}$");
+            return;
+        }
+        this.enqueueRawEvent({
+            type: "custom_emitted",
+            occurredAtMs: Date.now(),
+            payload: {
+                eventName,
+                customEventOrigin: "explicit_track",
+                properties: properties ?? {},
+                metrics: metrics ?? {},
+            },
+        });
+    }
+    // SDK は observation source event だけを送り、ingest core が意味付けを行う。
+    setConsent(consent) {
+        this.consent = consent;
+        if (!this.initialized) {
+            return;
+        }
+        if (consent === "denied") {
+            this.runtimeSurfaces.abortBrowserTokenWarmup();
+            this.stopCaptureModules();
+            this.transport?.setConsent(consent);
+            this.identityManager?.clearUser();
+            this.organizationManager?.reset();
+            this.traceManager?.reset();
+            return;
+        }
+        this.transport?.setConsent(consent);
+        if (this.config?.autocapture && !this.runtimeSurfaces.isCaptureActive()) {
+            this.startCaptureModules();
+        }
+    }
+    ensureInitializedForPublicCall(operation) {
+        if (this.initialized && this.config && this.transport) {
+            return true;
+        }
+        this.warnPublicDrop(operation, "cluebase.init() has not completed");
+        return false;
+    }
+    warnPublicDrop(operation, _reason) {
+        this.internalMetrics.increment("public_drop_count");
+        this.logger.warn(`Cluebase Frontend SDK ${operation} dropped`, {
+            error_code: "sdk_public_drop",
+        });
+        try {
+            if (typeof console !== "undefined" &&
+                typeof console.warn === "function") {
+                console.warn(`[cluebase] ${operation} dropped`, {
+                    error_code: "sdk_public_drop",
+                });
+            }
+        }
+        catch {
+            // Public warnings must never break the host app.
+        }
+    }
+    warnPublicFieldDrop(operation, field, _reason) {
+        this.logger.warn(`Cluebase Frontend SDK ${operation} field dropped`, {
+            field,
+            error_code: "sdk_field_drop",
+        });
+        try {
+            if (typeof console !== "undefined" &&
+                typeof console.warn === "function") {
+                console.warn(`[cluebase] ${operation} field dropped`, { field, error_code: "sdk_field_drop" });
+            }
+        }
+        catch {
+            // Public warnings must never break the host app.
+        }
+    }
+    sanitizeIdentifyTraits(traits) {
+        if (!traits) {
+            return traits;
+        }
+        if (!("avatarUrl" in traits)) {
+            return traits;
+        }
+        const avatarUrl = traits.avatarUrl;
+        if (avatarUrl == null || toStringOrNull(avatarUrl) === null) {
+            return traits;
+        }
+        if (normalizeProfileAvatarUrl(avatarUrl) !== null) {
+            return traits;
+        }
+        this.warnPublicFieldDrop("identify", "avatarUrl", "must use http:, https:, or a safe raster data:image URL");
+        return { ...traits, avatarUrl: null };
+    }
+    enqueueOfficialCustomEvent(eventName, properties, skipSessionTouch = false, identityLinkHint) {
+        this.enqueueRawEvent({
+            type: "custom_emitted",
+            occurredAtMs: Date.now(),
+            payload: {
+                eventName,
+                customEventOrigin: "official_sdk_lifecycle",
+                metrics: {
+                    count: 1,
+                },
+                properties,
+                ...(identityLinkHint ? { identity_link_hint: identityLinkHint } : {}),
+            },
+        }, skipSessionTouch);
+    }
+    enqueueRawEvent(event, skipSessionTouch = false) {
+        if (!this.initialized || !this.config || !this.transport)
+            return;
+        this.eventPipeline.enqueueRawEvent(event, skipSessionTouch);
+    }
+    flushLifecycleEvents() {
+        void this.transport?.flush();
+    }
+    // 内部 transport の即時 flush を要求する。SPA navigation や明示的 shutdown シナリオ用。
+    async flush() {
+        const deadline = this.transport?.beginFlushDeadline();
+        try {
+            await awaitUntilDeadline(this.flushCaptureSummaries("manual_flush"), deadline?.signal);
+            await forceFlushCluebaseOtelProvider(this.tracerProvider, deadline?.signal);
+            await this.transport?.flush(deadline);
+        }
+        finally {
+            this.transport?.endFlushDeadline(deadline);
+        }
+    }
+    // 残バッファを flush した上で SDK を停止する。テスト / 明示的 shutdown 用。
+    async close() {
+        const closeSignal = this.transport?.beginClose();
+        await awaitUntilDeadline(this.flushCaptureSummaries("close"), closeSignal);
+        this.stopCaptureModules();
+        await forceFlushCluebaseOtelProvider(this.tracerProvider, closeSignal ?? undefined);
+        await this.transport?.close();
+        if (this.transport?.getDiagnostics().lifecycle === "closing_failed") {
+            this.runtimeSurfaces.stopRuntimeSurfaces();
+            return;
+        }
+        await this.shutdownAsync();
+    }
+    warmupBrowserToken(client) {
+        this.runtimeSurfaces.warmupBrowserToken(client);
+    }
+    startCaptureModules() {
+        if (!this.config) {
+            return;
+        }
+        this.runtimeSurfaces.startCaptureModules(this.config);
+    }
+    stopCaptureModules() {
+        this.runtimeSurfaces.stopCaptureModules();
+    }
+    async flushCaptureSummaries(reason) {
+        await this.runtimeSurfaces.flushCaptureSummaries(reason);
+    }
+    applyUsageGovernorFeedback(feedback) {
+        this.eventPipeline.applyUsageGovernorFeedback(feedback);
+    }
+    buildContext() {
+        return this.eventPipeline.buildContext();
+    }
+    installUnloadHandlers() {
+        this.runtimeSurfaces.installUnloadHandlers(() => {
+            const ended = this.sessionManager?.endSession(Date.now());
+            if (ended) {
+                this.enqueueRawEvent({
+                    type: "session_ended",
+                    occurredAtMs: Date.now(),
+                    payload: {
+                        sessionId: ended.sessionId,
+                        exitUrl: readCurrentLifecycleUrl(),
+                        durationMs: ended.durationMs,
+                    },
+                }, true);
+            }
+        });
+    }
+    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;
+        const trimmed = raw.trim();
+        if (!trimmed)
+            return trimmed;
+        const piiCategory = detectIdentityPII(trimmed);
+        if (piiCategory === null)
+            return trimmed;
+        const hashed = hashIdentityValue(trimmed);
+        this.logger.warn(`${field} looks like ${piiCategory}; replaced with deterministic hash to prevent PII leak via canonical span attributes. Use an opaque ID (UUID / ULID / numeric) instead.`);
+        return hashed;
+    }
+    shutdown() {
+        this.stopRuntimeSurfaces();
+        const provider = this.tracerProvider;
+        this.tracerProvider = null;
+        shutdownCluebaseOtelProvider(provider);
+        this.stopTransport();
+    }
+    async shutdownAsync() {
+        this.stopRuntimeSurfaces();
+        const provider = this.tracerProvider;
+        this.tracerProvider = null;
+        await shutdownCluebaseOtelProviderAsync(provider);
+        this.stopTransport();
+    }
+    stopRuntimeSurfaces() {
+        this.runtimeSurfaces.stopRuntimeSurfaces();
+    }
+    stopTransport() {
+        if (this.transport) {
+            this.transport.dispose();
+            this.transport = null;
+        }
+        this.traceManager = null;
+        this.initialized = false;
+        this.initSignature = null;
+        this.eventPipeline.clearRuntime();
+    }
+}
+const awaitUntilDeadline = async (promise, signal) => {
+    if (!signal) {
+        await promise;
+        return;
+    }
+    if (signal.aborted)
+        return;
+    await new Promise((resolve) => {
+        const abort = () => resolve();
+        signal.addEventListener("abort", abort, { once: true });
+        void promise.finally(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        });
+    });
+};
+export const createCluebaseBrowserSdk = () => {
+    return new CluebaseBrowserSdkImpl();
+};