@maple-dev/browser 0.2.0 → 0.3.0

package/README.md

@@ -35,6 +35,19 @@ That single call:
 - writes session metadata at start (`active`) and on page hide (`ended`),
   including the trace ids observed during the session.
 
+## Identifying users
+
+Pass `userId` to `init()` when you already know the signed-in user, or call
+`MapleBrowser.identify(user.id)` later. The id is attached to future session
+metadata rows and stamped as `user.id` on future browser-created spans.
+
+```ts
+MapleBrowser.identify(user.id)
+
+// after sign-out
+MapleBrowser.identify(null)
+```
+
 ## Privacy
 
 `maskAllInputs` (default **on**) masks every `<input>` value. Use rrweb's

package/dist/index.d.mts

@@ -16,8 +16,8 @@ interface MapleBrowserConfig {
   readonly serviceVersion?: string;
   /** Deployment environment, e.g. "production". */
   readonly environment?: string;
-  /** Optional user id attached to the replay session. */
-  readonly userId?: string;
+  /** Optional user id attached to replay sessions and future browser spans. */
+  readonly userId?: string | null | undefined;
   readonly tracing?: {
     /** Default true. */readonly enabled?: boolean;
     /**
@@ -65,8 +65,8 @@ interface MapleBrowserHandle {
  * ```
  */
 declare const MapleBrowser: {
-  init: (config: MapleBrowserConfig) => MapleBrowserHandle; /** Attach (or replace) the user id on the active session. Safe to call repeatedly. */
-  identify: (userId: string) => void;
+  init: (config: MapleBrowserConfig) => MapleBrowserHandle; /** Attach, replace, or clear the user id on the active session. Safe to call repeatedly. */
+  identify: (userId?: string | null) => void;
 };
 //#endregion
 export { MapleBrowser, type MapleBrowserConfig, type MapleBrowserHandle };

package/dist/index.mjs

@@ -730,6 +730,9 @@ function startReplaySession(options) {
 //#endregion
 //#region src/config.ts
 const DEFAULT_ENDPOINT = "https://ingest.maple.dev";
+function normalizeUserId(userId) {
+	return userId ? userId : void 0;
+}
 function resolveConfig(config) {
 	return {
 		ingestKey: config.ingestKey,
@@ -738,7 +741,7 @@ function resolveConfig(config) {
 		serviceNamespace: config.serviceNamespace,
 		serviceVersion: config.serviceVersion,
 		environment: config.environment,
-		userId: config.userId,
+		userId: normalizeUserId(config.userId),
 		tracingEnabled: config.tracing?.enabled ?? true,
 		tracingInstrumentFetch: config.tracing?.instrumentFetch ?? true,
 		replayEnabled: config.replay?.enabled ?? true,
@@ -754,8 +757,13 @@ function resolveConfig(config) {
 * alongside the BatchSpanProcessor, does no export of its own.
 */
 var TraceIdCollector = class {
+	constructor(getUserId = () => void 0) {
+		this.getUserId = getUserId;
+	}
 	onStart(span) {
 		recordTraceId(span.spanContext().traceId);
+		const userId = this.getUserId();
+		if (userId !== void 0) span.setAttribute("user.id", userId);
 	}
 	onEnd(_span) {}
 	forceFlush() {
@@ -794,7 +802,7 @@ function setupTracing(config, sessionId) {
 	});
 	const provider = new WebTracerProvider({
 		resource: resourceFromAttributes(attributes),
-		spanProcessors: [new TraceIdCollector(), new BatchSpanProcessor(exporter)]
+		spanProcessors: [new TraceIdCollector(() => config.userId), new BatchSpanProcessor(exporter)]
 	});
 	provider.register();
 	if (config.tracingInstrumentFetch) registerInstrumentations({ instrumentations: [new FetchInstrumentation({ ignoreUrls: [new RegExp(`${escapeRegExp(config.endpoint)}/v1/`)] })] });
@@ -854,18 +862,14 @@ function init(rawConfig) {
 	return handle;
 }
 /**
-* Attach (or replace) the user id on the active session. Idempotent and safe to
-* call on every render. The session's authoritative row is the latest-version
-* "ended" row posted on suspend/unload, which reads `config.userId` at that
-* moment — so an id set here before the session ends is what the session is
-* tagged with.
+* Attach, replace, or clear the user id on the active session. Idempotent and
+* safe to call on every render. Future browser-created spans read this value
+* when they start, and future session metadata rows read it when they post.
 */
 function identify(userId) {
 	if (typeof window === "undefined") return;
 	if (!activeConfig) return;
-	if (!userId) return;
-	if (activeConfig.userId === userId) return;
-	activeConfig.userId = userId;
+	activeConfig.userId = normalizeUserId(userId);
 }
 //#endregion
 //#region src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@maple-dev/browser",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Maple browser SDK — OpenTelemetry tracing and rrweb session replay in one package. Every span and replay event shares a session id for trace↔replay correlation.",
 	"keywords": [
 		"maple",