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

package/dist/provider/sdk.js

@@ -7,15 +7,17 @@ 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 { detectWholeValuePII, hashIdentityValue, isDeniedKey, } from "../exporter/sanitize.js";
+import { initSdkCoreWasm } from "../exporter/sdk-core-wasm.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 { LifecycleEventDedup } from "./lifecycle-event-dedup.js";
+import { getSdkErrorDetails, reportSdkError } from "./sdk-error.js";
 import { OFFICIAL_CUSTOM_EVENT_NAME, ProviderEventPipeline, readCurrentLifecycleUrl, } from "./sdk-event-pipeline.js";
+import { isValidPublicCustomEventName, normalizeProfileAvatarUrl, normalizePublicIdentityId, toStringOrNull, } from "./sdk-input-normalization.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,6 +49,8 @@ class CluebaseBrowserSdkImpl {
         this.environmentManager = null;
         this.traceManager = null;
         this.diagnostics = new DiagnosticStore();
+        this.lifecycleDedup = new LifecycleEventDedup();
+        this.ingestUrlPrefixes = [];
         this.transport = null;
         this.tracerProvider = null;
         this.logger = logger;
@@ -58,9 +62,8 @@ class CluebaseBrowserSdkImpl {
             enqueueRawEvent: (event) => {
                 this.enqueueRawEvent(event);
             },
-            getViewId: () => this.eventPipeline.getViewId(),
+            eventPipeline: this.eventPipeline,
             getConsent: () => this.consent,
-            getObservationContext: () => this.eventPipeline.getObservationContext(),
             getTraceManager: () => this.traceManager,
             getTransport: () => this.transport,
             getTracerProvider: () => this.tracerProvider,
@@ -72,6 +75,19 @@ class CluebaseBrowserSdkImpl {
     getDiagnostics() {
         return this.diagnostics.snapshot();
     }
+    withActionContext(callback) {
+        let snapshot = null;
+        try {
+            snapshot = this.traceManager?.getCurrentActionContext() ?? null;
+        }
+        catch (error) {
+            reportSdkError("withActionContext", error);
+        }
+        if (!snapshot || !this.traceManager) {
+            return callback();
+        }
+        return this.traceManager.runWithActionContext(snapshot, callback);
+    }
     init(options) {
         try {
             const resolved = resolveConfig(options);
@@ -86,10 +102,8 @@ class CluebaseBrowserSdkImpl {
             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,
@@ -110,6 +124,7 @@ class CluebaseBrowserSdkImpl {
             this.shutdown();
             this.internalMetrics.reset();
             this.diagnostics = new DiagnosticStore();
+            this.lifecycleDedup.clear();
             this.config = resolved;
             this.initSignature = nextSignature;
             this.identityManager = new IdentityManager();
@@ -131,22 +146,27 @@ class CluebaseBrowserSdkImpl {
                 schemaVersion: 1,
                 metrics: this.internalMetrics,
                 diagnostics: this.diagnostics,
+                onEndpointsResolved: (endpoints) => {
+                    this.adoptIngestUrlPrefixes(endpoints);
+                },
             });
             this.transport = new BatchTransport({
                 client: ingestClient,
                 enabled: effectiveBatch.enabled,
                 flushIntervalMs: effectiveBatch.flushIntervalMs,
+                maxSize: effectiveBatch.maxSize,
                 maxPayloadBytes: effectiveBatch.maxPayloadBytes,
                 flushThresholdBytes: DEFAULT_BATCH_FLUSH_THRESHOLD_BYTES,
                 queueMaxBytes: DEFAULT_MAX_BATCH_QUEUE_BYTES,
                 queueMaxItems: DEFAULT_MAX_BATCH_QUEUE_ITEMS,
                 projectKey: resolved.projectKey,
+                endpoint: resolved.endpoint,
+                sdkVersion: SDK_VERSION,
+                sourceSchemaVersion: "1",
+                sdkRequest: "browser",
                 initialConsent: this.consent,
                 metrics: this.internalMetrics,
                 diagnostics: this.diagnostics,
-                onGovernorFeedback: (feedback) => {
-                    this.applyUsageGovernorFeedback(feedback);
-                },
             });
             this.consent = this.transport.currentConsent();
             this.transport.start();
@@ -166,10 +186,14 @@ class CluebaseBrowserSdkImpl {
             if (this.consent !== "denied") {
                 this.warmupBrowserToken(ingestClient);
             }
+            void initSdkCoreWasm().catch((error) => {
+                reportSdkError("init sdk core wasm", error);
+            });
             this.tracerProvider = createCluebaseOtelPipeline({
                 resolved,
                 getTransport: () => this.transport,
                 getContext: () => this.buildContext(),
+                ignoreUrlPrefixes: this.ingestUrlPrefixes,
             });
             this.initialized = true;
             this.refreshSessionCaptureEligibility();
@@ -232,6 +256,16 @@ class CluebaseBrowserSdkImpl {
             const sanitizedTraits = this.sanitizeIdentifyTraits(traits);
             const subjectProfileKeys = safeProfileKeys(traits, this.config?.privacy.deniedKeys ?? []);
             this.identityManager.identify(sanitizedUserId, sanitizedTraits);
+            if (!this.lifecycleDedup.shouldEmit({
+                action: "identify",
+                userId: sanitizedUserId,
+                anonymousId: previousAnonymousId,
+                organizationId: this.organizationManager?.getContext().organizationId ?? null,
+                subjectTraits: this.identityManager.getContext().traits,
+                profileKeys: subjectProfileKeys,
+            })) {
+                return;
+            }
             this.enqueueOfficialCustomEvent(OFFICIAL_CUSTOM_EVENT_NAME.identityIdentified, {
                 identity_action: "identify",
                 profile_keys: subjectProfileKeys,
@@ -263,9 +297,20 @@ class CluebaseBrowserSdkImpl {
                 return;
             }
             const sanitizedOrgId = this.sanitizeIdentityValue("organizationId", normalizedOrganizationId);
-            const previousUserId = this.identityManager?.getContext().userId ?? null;
+            const identityBeforeGroup = this.identityManager?.getContext();
+            const previousUserId = identityBeforeGroup?.userId ?? null;
             const organizationProfileKeys = safeProfileKeys(traits, this.config?.privacy.deniedKeys ?? []);
             this.organizationManager.setOrganization(sanitizedOrgId, traits);
+            if (!this.lifecycleDedup.shouldEmit({
+                action: "associate_organization",
+                userId: previousUserId,
+                anonymousId: identityBeforeGroup?.anonymousId ?? null,
+                organizationId: sanitizedOrgId,
+                organizationTraits: this.organizationManager.getContext().traits,
+                profileKeys: organizationProfileKeys,
+            })) {
+                return;
+            }
             this.enqueueOfficialCustomEvent(OFFICIAL_CUSTOM_EVENT_NAME.organizationAssociated, {
                 organization_action: "associate",
                 profile_keys: organizationProfileKeys,
@@ -282,31 +327,72 @@ class CluebaseBrowserSdkImpl {
             });
         }
     }
-    reset() {
-        if (!this.initialized) {
+    link(input) {
+        if (!this.ensureInitializedForPublicCall("link")) {
+            return;
+        }
+        const subject = input?.subject;
+        if (subject?.type !== "organization") {
+            this.warnPublicDrop("link", "subject.type must be 'organization'");
+            return;
+        }
+        const organizationId = normalizePublicIdentityId(subject.id);
+        if (!organizationId) {
+            this.warnPublicDrop("link", "subject.id must be a non-empty string");
+            return;
+        }
+        this.emitExternalLink("link", organizationId, input?.external?.namespace, input?.external?.id);
+    }
+    linkExternalAccount(namespace, externalId) {
+        if (!this.ensureInitializedForPublicCall("linkExternalAccount")) {
+            return;
+        }
+        if (!this.organizationManager) {
+            this.warnPublicDrop("linkExternalAccount", "organization manager is unavailable");
+            return;
+        }
+        const organizationId = this.organizationManager.getContext().organizationId;
+        if (!organizationId) {
+            this.warnPublicDrop("linkExternalAccount", "setOrganization must be called before linkExternalAccount");
             return;
         }
+        this.emitExternalLink("linkExternalAccount", organizationId, namespace, externalId);
+    }
+    emitExternalLink(publicCallName, organizationId, namespace, externalId) {
         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",
+            const normalizedNamespace = normalizePublicIdentityId(namespace);
+            const normalizedExternalId = normalizePublicIdentityId(externalId);
+            if (!normalizedNamespace || !normalizedExternalId) {
+                this.warnPublicDrop(publicCallName, "namespace and externalId must be non-empty strings");
+                return;
+            }
+            const sanitizedExternalId = this.sanitizeIdentityValue("externalId", normalizedExternalId);
+            if (!this.lifecycleDedup.shouldEmit({
+                action: "link",
+                organizationId,
+                externalNamespace: normalizedNamespace,
+                externalId: sanitizedExternalId,
+            })) {
+                return;
+            }
+            this.enqueueOfficialCustomEvent(OFFICIAL_CUSTOM_EVENT_NAME.externalAccountLinked, {
+                identity_action: "link",
+                external_namespace: normalizedNamespace,
             }, false, {
-                link_type: "logout",
-                user_id: previousUserId,
-                organization_id: previousOrganizationId,
+                link_type: "canonical_subject_to_external",
+                organization_id: organizationId,
+                external_namespace: normalizedNamespace,
+                external_id: sanitizedExternalId,
             });
+            this.flushLifecycleEvents();
         }
         catch {
-            this.logger.error("reset failed", {
+            this.logger.error(`${publicCallName} failed`, {
                 error_code: "sdk_operation_failed",
             });
         }
-        finally {
-            this.resetSessionState();
-        }
     }
-    logout() {
+    reset() {
         if (!this.initialized) {
             return;
         }
@@ -322,7 +408,7 @@ class CluebaseBrowserSdkImpl {
             });
         }
         catch {
-            this.logger.error("logout failed", {
+            this.logger.error("reset failed", {
                 error_code: "sdk_operation_failed",
             });
         }
@@ -387,6 +473,9 @@ class CluebaseBrowserSdkImpl {
         });
     }
     setConsent(consent) {
+        if (this.consent !== consent) {
+            this.lifecycleDedup.clear();
+        }
         this.consent = consent;
         if (!this.initialized) {
             return;
@@ -425,8 +514,7 @@ class CluebaseBrowserSdkImpl {
                 });
             }
         }
-        catch {
-        }
+        catch { }
     }
     warnPublicFieldDrop(operation, field, _reason) {
         this.logger.warn(`Cluebase Frontend SDK ${operation} field dropped`, {
@@ -436,11 +524,13 @@ class CluebaseBrowserSdkImpl {
         try {
             if (typeof console !== "undefined" &&
                 typeof console.warn === "function") {
-                console.warn(`[cluebase] ${operation} field dropped`, { field, error_code: "sdk_field_drop" });
+                console.warn(`[cluebase] ${operation} field dropped`, {
+                    field,
+                    error_code: "sdk_field_drop",
+                });
             }
         }
-        catch {
-        }
+        catch { }
     }
     sanitizeIdentifyTraits(traits) {
         if (!traits) {
@@ -483,21 +573,15 @@ class CluebaseBrowserSdkImpl {
         void this.transport?.flush();
     }
     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);
-        }
+        await this.flushCaptureSummaries("manual_flush");
+        await forceFlushCluebaseOtelProvider(this.tracerProvider);
+        await this.transport?.flush();
     }
     async close() {
-        const closeSignal = this.transport?.beginClose();
-        await awaitUntilDeadline(this.flushCaptureSummaries("close"), closeSignal);
+        this.transport?.beginClose();
+        await this.flushCaptureSummaries("close");
         this.stopCaptureModules();
-        await forceFlushCluebaseOtelProvider(this.tracerProvider, closeSignal ?? undefined);
+        await forceFlushCluebaseOtelProvider(this.tracerProvider);
         await this.transport?.close();
         if (this.transport?.getDiagnostics().lifecycle === "closing_failed") {
             await this.shutdownAsync();
@@ -508,11 +592,19 @@ class CluebaseBrowserSdkImpl {
     warmupBrowserToken(client) {
         this.runtimeSurfaces.warmupBrowserToken(client);
     }
+    adoptIngestUrlPrefixes(endpoints) {
+        for (const url of [endpoints.ingestBatchUrl, endpoints.browserTokenUrl]) {
+            if (url.length > 0 && !this.ingestUrlPrefixes.includes(url)) {
+                this.ingestUrlPrefixes.push(url);
+            }
+        }
+        this.runtimeSurfaces.refreshIgnoreUrlPrefixes();
+    }
     startCaptureModules() {
         if (!this.config) {
             return;
         }
-        this.runtimeSurfaces.startCaptureModules(this.config);
+        this.runtimeSurfaces.startCaptureModules(this.config, this.ingestUrlPrefixes);
     }
     stopCaptureModules() {
         this.runtimeSurfaces.stopCaptureModules();
@@ -520,9 +612,6 @@ class CluebaseBrowserSdkImpl {
     async flushCaptureSummaries(reason) {
         await this.runtimeSurfaces.flushCaptureSummaries(reason);
     }
-    applyUsageGovernorFeedback(feedback) {
-        this.eventPipeline.applyUsageGovernorFeedback(feedback);
-    }
     buildContext() {
         return this.eventPipeline.buildContext();
     }
@@ -551,7 +640,7 @@ class CluebaseBrowserSdkImpl {
         const trimmed = raw.trim();
         if (!trimmed)
             return trimmed;
-        const piiCategory = detectIdentityPII(trimmed);
+        const piiCategory = detectWholeValuePII(trimmed);
         if (piiCategory === null)
             return trimmed;
         const hashed = hashIdentityValue(trimmed);

package/dist/provider/types.d.ts

@@ -1,9 +1,19 @@
-import type { InternalMetricsSnapshot } from "../internal/metrics.js";
 import type { DiagnosticsSnapshot } from "../exporter/diagnostics.js";
+import type { InternalMetricsSnapshot } from "../internal/metrics.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";
 export type CluebaseGroupType = "organization";
+export type CluebaseLinkInput = {
+    subject: {
+        type: CluebaseGroupType;
+        id: string;
+    };
+    external: {
+        namespace: string;
+        id: string;
+    };
+};
 export type CanonicalJsonValue = string | number | boolean | null | CanonicalJsonValue[] | {
     [key: string]: CanonicalJsonValue;
 };
@@ -19,7 +29,6 @@ export type CluebaseGroupTraits = {
 } & {
     [traitName: string]: CanonicalJsonInputValue;
 };
-export type TransportProfile = "standard";
 export type RequestLifecycleOutcome = "completed" | "failed" | "aborted" | "unknown";
 export type DiagnosticCollectionConfig = {
     enabledCollectors?: string[];
@@ -64,10 +73,8 @@ export type CluebaseInitOptions = {
 export type ResolvedCluebaseConfig = {
     endpoint: string;
     originalEndpoint: string;
-    localSetupCheckEndpoint: string | null;
     projectKey: string;
     producerId: string;
-    transportProfile: TransportProfile;
     autocapture: boolean;
     captureNetwork: boolean;
     captureErrors: boolean;
@@ -112,7 +119,8 @@ export type CluebaseBrowserSdk = {
     init(options: CluebaseInitOptions): void;
     identify(userId: string, traits?: CluebaseSubjectTraits): void;
     setOrganization(organizationId: string, traits?: CluebaseGroupTraits): void;
-    logout(): void;
+    link(input: CluebaseLinkInput): void;
+    linkExternalAccount(namespace: string, externalId: string): void;
     reset(): void;
     track(eventName: string, properties?: CluebaseTrackProperties, metrics?: CluebaseTrackMetrics): void;
     setConsent(consent: CluebaseConsentState): void;
@@ -120,23 +128,7 @@ export type CluebaseBrowserSdk = {
     flush(): Promise<void>;
     close(): Promise<void>;
     getDiagnostics(): DiagnosticsSnapshot;
-};
-export type { CostCapability } from "../_generated/usage-governor-tables.js";
-import type { CostCapability } from "../_generated/usage-governor-tables.js";
-export type LimitKind = "monthly_overage_amount_limit" | "internal_cost_limit" | "internal_limit" | "operator_global_monthly_cost_limit";
-export type ThresholdStage = "info" | "warning" | "urgent" | "reached";
-export type LimitReason = {
-    limitKind: LimitKind;
-    meterKey: string;
-    thresholdStage: ThresholdStage;
-    currentValue: number;
-    limitValue: number;
-    retryAfterAt: string | null;
-};
-export type IngestUsageGovernorFeedback = {
-    disabledCapabilities: CostCapability[];
-    limitReasons: LimitReason[];
-    retryAfterAt: string | null;
+    withActionContext<T>(callback: () => T): T;
 };
 export type ParameterSnapshotLeafType = "string" | "number" | "boolean" | "null" | "object" | "array";
 export type ParameterSnapshotLeaf = {
@@ -149,12 +141,14 @@ export type ParameterSnapshotLeaf = {
 export type ParameterSnapshotValue = ParameterSnapshotLeaf | ParameterSnapshotValue[] | {
     [key: string]: ParameterSnapshotValue;
 };
-export type SdkIdentityLinkType = "anonymous_to_user" | "user_to_organization" | "logout";
+export type SdkIdentityLinkType = "anonymous_to_user" | "user_to_organization" | "logout" | "canonical_subject_to_external";
 export type SdkIdentityLinkHint = {
     link_type: SdkIdentityLinkType;
     anonymous_id?: string | null;
     user_id?: string | null;
     organization_id?: string | null;
+    external_namespace?: string | null;
+    external_id?: string | null;
 };
 export type CluebaseContext = {
     producer_id: string | null;
@@ -267,7 +261,6 @@ export type CaptureModuleContext = {
         sessionId: string | null;
         tabId: string | null;
     };
-    shouldIgnoreElement?: (element: Element) => boolean;
     startInteraction?: (input: {
         interactionId?: string | null;
         interactionInitiator?: string | null;
@@ -284,4 +277,5 @@ export type CaptureModuleContext = {
 export type CaptureStopHandle = {
     stop: () => void;
     flush?: (reason: string) => void | Promise<void>;
+    refreshIgnoreUrlPrefixes?: () => void;
 };

package/dist/wasm/pkg-web/cluebase_sdk_core_wasm.d.ts

@@ -0,0 +1,44 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export function deliveryCommandJson(request_json: string): string;
+
+export function spanToObservationSourceEventJson(span_json: string, options_json: string): string;
+
+export function spanToSdkSignalJson(span_json: string, options_json: string): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly deliveryCommandJson: (a: number, b: number, c: number) => void;
+    readonly spanToObservationSourceEventJson: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly spanToSdkSignalJson: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly __wbindgen_export: (a: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;