@spotify-confidence/csr-common 0.18.5 → 0.18.6

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.18.6](https://github.com/spotify/confidence-sdk-js/compare/csr-common-v0.18.5...csr-common-v0.18.6) (2026-08-18)
+
+
+### ✨ New Features
+
+* **csr-recorder:** capture GraphQL operation names ([#434](https://github.com/spotify/confidence-sdk-js/issues/434)) ([c4610ef](https://github.com/spotify/confidence-sdk-js/commit/c4610ef2945cecf632a3027b58ec373bc8b562e7))
+* **csr:** ship standalone worker file and expose workerUrl option ([#412](https://github.com/spotify/confidence-sdk-js/issues/412)) ([7b38441](https://github.com/spotify/confidence-sdk-js/commit/7b38441e439d28496ee72b2d5a2fdfe6f6ab9b40))
+
 ## [0.18.5](https://github.com/spotify/confidence-sdk-js/compare/csr-common-v0.18.4...csr-common-v0.18.5) (2026-08-12)
 
 

package/dist/confidence-worker.js

@@ -0,0 +1,446 @@
+//#region src/uploader/worker/web-socket-transport.ts
+/**
+* WebSocket-backed Transport. Internal retry policy: clean server-initiated close after the
+* first successful open → reconnect and resume; abrupt close (or any close before the first
+* open) → fire `onClose` and stop. Frames received while a (re)connect is in progress are
+* buffered and flushed on open.
+*
+* `ready()` resolves on the first successful open and rejects on close-before-open. Callers
+* should await it before treating the Transport as live, so a failure to open can be caught
+* (e.g. 4404 unknown session) and recovered from.
+*/
+var WebSocketTransport = class {
+	url;
+	ws = null;
+	onCloseCb = null;
+	onStateChangeCb = null;
+	intentionallyClosed = false;
+	dead = false;
+	/** Frames buffered while a (re)connect is in progress. */
+	pending = [];
+	readyPromise;
+	constructor(url) {
+		this.url = url;
+		this.readyPromise = new Promise((resolve, reject) => {
+			this.connect(false, resolve, reject);
+		});
+		this.readyPromise.catch(() => {});
+	}
+	ready() {
+		return this.readyPromise;
+	}
+	send(frame) {
+		if (this.dead || this.intentionallyClosed) return;
+		if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify(frame));
+		else this.pending.push(frame);
+	}
+	close(reason = "transport-close") {
+		this.intentionallyClosed = true;
+		this.ws?.close(1e3, reason);
+	}
+	onClose(cb) {
+		this.onCloseCb = cb;
+	}
+	onStateChange(cb) {
+		this.onStateChangeCb = cb;
+	}
+	connect(isReconnect, onReady, onReadyFail) {
+		const ws = new WebSocket(this.url);
+		this.ws = ws;
+		let opened = false;
+		ws.onopen = () => {
+			opened = true;
+			onReady?.();
+			if (isReconnect) this.onStateChangeCb?.({ connected: true });
+			while (this.pending.length > 0) {
+				const f = this.pending.shift();
+				ws.send(JSON.stringify(f));
+			}
+		};
+		ws.onclose = (event) => {
+			if (this.intentionallyClosed) return;
+			if (!opened) {
+				const reason = `${isReconnect ? "reconnect" : "initial"}-failed code=${event.code}`;
+				if (onReadyFail) {
+					onReadyFail(new Error(reason));
+					this.dead = true;
+				} else this.die(reason);
+				return;
+			}
+			if (event.wasClean && (event.code === 1e3 || event.code === 1001)) {
+				this.onStateChangeCb?.({ connected: false });
+				this.connect(true);
+			} else this.die(`close code=${event.code} wasClean=${event.wasClean}`);
+		};
+	}
+	die(reason) {
+		this.dead = true;
+		this.onCloseCb?.({ reason });
+	}
+};
+//#endregion
+//#region src/uploader/worker/csr-client.ts
+/**
+* Single Client implementation that talks to the recording backend's REST + WS protocol.
+* Both dev-server and prod implement the same protocol, so we don't need polymorphism here yet.
+*/
+var CsrClient = class {
+	apiUrl;
+	clientSecret;
+	context;
+	websocketUrl;
+	log;
+	forceRecord;
+	constructor(apiUrl, clientSecret, context, websocketUrl, log = () => {}, forceRecord) {
+		this.apiUrl = apiUrl;
+		this.clientSecret = clientSecret;
+		this.context = context;
+		this.websocketUrl = websocketUrl;
+		this.log = log;
+		this.forceRecord = forceRecord;
+	}
+	async initSession() {
+		const url = `${this.trimSlash(this.apiUrl)}/v1/sessions:initSession`;
+		this.log(`fetch POST ${url}`);
+		const res = await fetch(url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				clientSecret: this.clientSecret,
+				...this.context && Object.keys(this.context).length > 0 ? { context: this.context } : {},
+				...this.forceRecord ? { forceRecord: true } : {}
+			})
+		});
+		if (!res.ok) throw new Error(`init-session failed: HTTP ${res.status}`);
+		const data = await res.json();
+		if (data.skipRecording) return { skipRecording: true };
+		if (!data.sessionId || !data.sessionToken) throw new Error("init-session response missing sessionId or sessionToken");
+		return {
+			sessionId: data.sessionId,
+			sessionToken: data.sessionToken
+		};
+	}
+	async openTransport(sessionToken) {
+		const wsBase = this.websocketUrl ?? `${this.toWsScheme(this.trimSlash(this.apiUrl))}/sessions/stream`;
+		const url = `${wsBase}${wsBase.includes("?") ? "&" : "?"}session_token=${encodeURIComponent(sessionToken)}`;
+		this.log(`WebSocket connect ${url.replace(/session_token=[^&]*/, "session_token=[REDACTED]")}`);
+		const transport = new WebSocketTransport(url);
+		await transport.ready();
+		return transport;
+	}
+	trimSlash(s) {
+		return s.endsWith("/") ? s.slice(0, -1) : s;
+	}
+	toWsScheme(base) {
+		if (base.startsWith("https://")) return `wss://${base.slice(8)}`;
+		if (base.startsWith("http://")) return `ws://${base.slice(7)}`;
+		return base;
+	}
+};
+//#endregion
+//#region src/uploader/worker/core.ts
+const IDLE_GRACE_MS = 5e3;
+let state = { phase: "init" };
+const ports = [];
+let idleTimer = null;
+function cancelIdleTimer() {
+	if (idleTimer !== null) {
+		clearTimeout(idleTimer);
+		idleTimer = null;
+	}
+}
+function log(msg) {
+	for (const handle of ports) if (handle.debugLogs) handle.port.postMessage({
+		type: "log",
+		msg
+	});
+}
+/**
+* The first hello "locks in" the session's apiUrl/clientSecret. Any later tab arriving
+* with different values is misconfigured — we reject it rather than silently using the
+* locked values. In SharedWorker mode the `name = hash(clientSecret)` scoping already
+* prevents secret-mismatch from sharing a worker, but this defends against the dedicated
+* path and against future bugs.
+*/
+let lockedConfig = null;
+function registerPort(adapter) {
+	cancelIdleTimer();
+	const handle = {
+		port: adapter,
+		hello: null,
+		debugLogs: false
+	};
+	ports.push(handle);
+	adapter.onmessage((data) => {
+		handleMessage(handle, data);
+	});
+}
+function handleMessage(handle, message) {
+	switch (message.type) {
+		case "hello":
+			handle.hello = message;
+			handle.debugLogs = message.debugLogs ?? false;
+			if (rejectIfIncompatible(handle)) return;
+			if (state.phase !== "dead" && state.phase !== "skipping") detectDuplicateTab(handle);
+			onHello(handle);
+			return;
+		case "frame":
+			onFrame(message.frame);
+			return;
+		case "bye":
+			onBye(handle);
+			return;
+		default: break;
+	}
+}
+/**
+* Reject hellos whose `apiUrl`/`clientSecret` don't match the values established by the
+* first hello. Returns true if the port was rejected (caller should not continue
+* processing this hello).
+*/
+function rejectIfIncompatible(handle) {
+	if (lockedConfig === null) return false;
+	const incoming = handle.hello;
+	if (incoming.apiUrl === lockedConfig.apiUrl && incoming.websocketUrl === lockedConfig.websocketUrl && incoming.clientSecret === lockedConfig.clientSecret) return false;
+	handle.port.postMessage({
+		type: "dead",
+		reason: "incompatible-options: apiUrl/websocketUrl/clientSecret differ from the worker session"
+	});
+	const idx = ports.indexOf(handle);
+	if (idx >= 0) ports.splice(idx, 1);
+	return true;
+}
+/**
+* If another already-connected port has the same `tabId`, this hello is from a duplicate
+* tab (browser "Duplicate" command clones sessionStorage). Mint a fresh `tabId` so the two
+* tabs don't collide on the same `(sessionId, tabId)` Recording. The new tabId is returned
+* to the tab in `welcome` so it can update its own state and sessionStorage.
+*/
+function detectDuplicateTab(handle) {
+	const tabId = handle.hello.tabId;
+	if (!ports.some((p) => p !== handle && p.hello?.tabId === tabId)) return;
+	const fresh = crypto.randomUUID();
+	handle.newTabId = fresh;
+	handle.hello.tabId = fresh;
+}
+function onHello(handle) {
+	switch (state.phase) {
+		case "init":
+			lockedConfig = {
+				apiUrl: handle.hello.apiUrl,
+				websocketUrl: handle.hello.websocketUrl,
+				clientSecret: handle.hello.clientSecret
+			};
+			log(`hello received apiUrl=${handle.hello.apiUrl} websocketUrl=${handle.hello.websocketUrl ?? "(derive)"} sessionIdHint=${handle.hello.sessionIdHint ?? "(none)"}`);
+			state = { phase: "initializing" };
+			initializeSession(handle.hello).then(flushPendingWelcomes);
+			return;
+		case "initializing": return;
+		case "active":
+			sendActiveWelcome(handle, state.sessionId, state.sessionToken);
+			return;
+		case "idle": {
+			const { client, sessionId, sessionToken } = state;
+			state = { phase: "initializing" };
+			resumeTransport(client, sessionId, sessionToken).then(flushPendingWelcomes);
+			return;
+		}
+		case "skipping":
+			if (handle.hello.forceRecord) {
+				log("forceRecord set; re-initializing from skipping state");
+				state = { phase: "initializing" };
+				initializeSession(handle.hello).then(flushPendingWelcomes);
+				return;
+			}
+			handle.port.postMessage({
+				type: "welcome",
+				result: { skipRecording: true }
+			});
+			return;
+		case "dead":
+			handle.port.postMessage({
+				type: "dead",
+				reason: state.reason
+			});
+			return;
+		default: break;
+	}
+}
+async function initializeSession(firstHello) {
+	const client = new CsrClient(firstHello.apiUrl, firstHello.clientSecret, firstHello.context, firstHello.websocketUrl, log, firstHello.forceRecord);
+	if (firstHello.sessionIdHint && firstHello.sessionTokenHint) {
+		log(`adopting sessionIdHint=${firstHello.sessionIdHint}`);
+		try {
+			const transport = await client.openTransport(firstHello.sessionTokenHint);
+			wireTransport(transport);
+			state = {
+				phase: "active",
+				client,
+				transport,
+				sessionId: firstHello.sessionIdHint,
+				sessionToken: firstHello.sessionTokenHint
+			};
+			log("hint adopted; transport open");
+			if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);
+			return;
+		} catch (err) {
+			log(`hint rejected (${String(err)}); falling back to fresh init`);
+		}
+	}
+	let result;
+	try {
+		result = await client.initSession();
+	} catch (err) {
+		log(`init-session threw: ${String(err)}`);
+		transitionToDead(`init-session-failed: ${String(err)}`);
+		return;
+	}
+	if ("skipRecording" in result) {
+		log("init-session: skipRecording");
+		state = { phase: "skipping" };
+		return;
+	}
+	log(`init-session ok sessionId=${result.sessionId}`);
+	let transport;
+	try {
+		transport = await client.openTransport(result.sessionToken);
+	} catch (err) {
+		log(`openTransport threw: ${String(err)}`);
+		transitionToDead(`open-transport-failed: ${String(err)}`);
+		return;
+	}
+	wireTransport(transport);
+	log("transport open; session active");
+	state = {
+		phase: "active",
+		client,
+		transport,
+		sessionId: result.sessionId,
+		sessionToken: result.sessionToken
+	};
+	if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);
+}
+async function resumeTransport(client, sessionId, sessionToken) {
+	log("resuming transport from idle");
+	let transport;
+	try {
+		transport = await client.openTransport(sessionToken);
+	} catch (err) {
+		log(`resume-transport threw: ${String(err)}`);
+		transitionToDead(`resume-transport-failed: ${String(err)}`);
+		return;
+	}
+	wireTransport(transport);
+	log("transport resumed");
+	state = {
+		phase: "active",
+		client,
+		transport,
+		sessionId,
+		sessionToken
+	};
+	if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);
+}
+function wireTransport(transport) {
+	transport.onClose((info) => {
+		if (state.phase !== "active") return;
+		transitionToDead(info.reason);
+	});
+	transport.onStateChange((info) => {
+		if (state.phase !== "active") return;
+		for (const handle of ports) handle.port.postMessage({
+			type: "state",
+			connected: info.connected
+		});
+	});
+}
+function transitionToDead(reason) {
+	state = {
+		phase: "dead",
+		reason
+	};
+	for (const handle of ports) handle.port.postMessage({
+		type: "dead",
+		reason
+	});
+}
+function flushPendingWelcomes() {
+	for (const handle of ports) {
+		if (handle.hello === null) continue;
+		if (state.phase === "active") sendActiveWelcome(handle, state.sessionId, state.sessionToken);
+		else if (state.phase === "skipping") handle.port.postMessage({
+			type: "welcome",
+			result: { skipRecording: true }
+		});
+		else if (state.phase === "dead") handle.port.postMessage({
+			type: "dead",
+			reason: state.reason
+		});
+	}
+}
+function sendActiveWelcome(handle, currentSessionId, currentSessionToken) {
+	const hint = handle.hello?.sessionIdHint;
+	const adopted = hint !== void 0 && hint !== currentSessionId;
+	const newTabId = handle.newTabId;
+	handle.port.postMessage({
+		type: "welcome",
+		result: {
+			sessionId: currentSessionId,
+			sessionToken: currentSessionToken
+		},
+		adoptedFromSessionId: adopted ? hint : void 0,
+		newTabId,
+		resetCounter: adopted || newTabId !== void 0
+	});
+}
+function onFrame(frame) {
+	if (state.phase !== "active") return;
+	state.transport.send(frame);
+}
+function onBye(handle) {
+	const idx = ports.indexOf(handle);
+	if (idx >= 0) ports.splice(idx, 1);
+	if (ports.length === 0 && state.phase === "active") {
+		log(`last tab disconnected; closing transport in ${IDLE_GRACE_MS}ms`);
+		idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);
+	}
+}
+function enterIdle() {
+	idleTimer = null;
+	if (state.phase !== "active" || ports.length > 0) return;
+	log("idle timeout; closing transport");
+	state.transport.close("idle");
+	state = {
+		phase: "idle",
+		client: state.client,
+		sessionId: state.sessionId,
+		sessionToken: state.sessionToken
+	};
+}
+//#endregion
+//#region src/uploader/worker/entry.ts
+const SharedWorkerScopeCtor = globalThis.SharedWorkerGlobalScope;
+if (typeof SharedWorkerScopeCtor === "function" && self instanceof SharedWorkerScopeCtor) self.onconnect = (event) => {
+	const port = event.ports[0];
+	port.start();
+	registerPort(adaptMessagePort(port));
+};
+else registerPort(adaptDedicatedSelf());
+function adaptMessagePort(port) {
+	return {
+		postMessage: (message) => port.postMessage(message),
+		onmessage: (cb) => {
+			port.onmessage = (e) => cb(e.data);
+		}
+	};
+}
+function adaptDedicatedSelf() {
+	const ws = self;
+	return {
+		postMessage: (message) => ws.postMessage(message),
+		onmessage: (cb) => {
+			ws.onmessage = (e) => cb(e.data);
+		}
+	};
+}
+//#endregion

package/dist/index.d.cts

@@ -210,6 +210,9 @@ type ConsoleLogPluginData = {
   };
 };
 type NetworkRequestInitiator = "fetch" | "xhr";
+type GraphQLRequestMetadata = {
+  operationName: string;
+};
 /**
 * Plugin event data emitted by the recorder for network requests.
 */
@@ -223,6 +226,7 @@ type NetworkRequestPluginData = {
     durationMs: number;
     requestSize?: number;
     responseSize?: number;
+    graphql?: GraphQLRequestMetadata;
   };
 };
 type RouteChangePluginData = {
@@ -330,4 +334,4 @@ declare function validateKey(key: string): string | null;
 declare function validateTagValue(value: string | undefined): string | null;
 declare function validateMeasureValue(value: number | undefined): string | null;
 //#endregion
-export { type AwayGapCustomData, type ClickCustomData, type ClientContext, type ConsoleLogLevel, type ConsoleLogPluginData, type CustomEventData, type DeadClickCustomData, type DialogOpenedCustomData, type ElementDescriptor, type ErrorMessageCustomData, type FlagEvaluationPluginData, type FormFieldReEditCustomData, type Frame, type IdleGapCustomData, type IncrementalSnapshotData, IncrementalSource, type InputCustomData, MAX_DISTINCT_KEYS, MAX_KEY_LENGTH, MAX_TAG_VALUE_LENGTH, MAX_VALUES_PER_KEY, type MeasurePluginData, type MouseInteractionData, MouseInteractions, type NetworkRequestInitiator, type NetworkRequestPluginData, type OpaqueIncrementalData, type RageClickCustomData, type RecordingEvent, RecordingEventType, type RouteChangeCustomData, type RouteChangePayload, type RouteChangePluginData, type RouteChangeTrigger, type ScrollBackCustomData, type SelectionData, type SelectionRange, SerializedNodeType, type TabRefocusCustomData, type TabUnfocusCustomData, type TabVisibilityPluginData, type TagPluginData, type UserAgentContext, stripUrl, validateKey, validateMeasureValue, validateTagValue };
+export { type AwayGapCustomData, type ClickCustomData, type ClientContext, type ConsoleLogLevel, type ConsoleLogPluginData, type CustomEventData, type DeadClickCustomData, type DialogOpenedCustomData, type ElementDescriptor, type ErrorMessageCustomData, type FlagEvaluationPluginData, type FormFieldReEditCustomData, type Frame, type GraphQLRequestMetadata, type IdleGapCustomData, type IncrementalSnapshotData, IncrementalSource, type InputCustomData, MAX_DISTINCT_KEYS, MAX_KEY_LENGTH, MAX_TAG_VALUE_LENGTH, MAX_VALUES_PER_KEY, type MeasurePluginData, type MouseInteractionData, MouseInteractions, type NetworkRequestInitiator, type NetworkRequestPluginData, type OpaqueIncrementalData, type RageClickCustomData, type RecordingEvent, RecordingEventType, type RouteChangeCustomData, type RouteChangePayload, type RouteChangePluginData, type RouteChangeTrigger, type ScrollBackCustomData, type SelectionData, type SelectionRange, SerializedNodeType, type TabRefocusCustomData, type TabUnfocusCustomData, type TabVisibilityPluginData, type TagPluginData, type UserAgentContext, stripUrl, validateKey, validateMeasureValue, validateTagValue };

package/dist/index.d.ts

@@ -210,6 +210,9 @@ type ConsoleLogPluginData = {
   };
 };
 type NetworkRequestInitiator = "fetch" | "xhr";
+type GraphQLRequestMetadata = {
+  operationName: string;
+};
 /**
 * Plugin event data emitted by the recorder for network requests.
 */
@@ -223,6 +226,7 @@ type NetworkRequestPluginData = {
     durationMs: number;
     requestSize?: number;
     responseSize?: number;
+    graphql?: GraphQLRequestMetadata;
   };
 };
 type RouteChangePluginData = {
@@ -330,4 +334,4 @@ declare function validateKey(key: string): string | null;
 declare function validateTagValue(value: string | undefined): string | null;
 declare function validateMeasureValue(value: number | undefined): string | null;
 //#endregion
-export { type AwayGapCustomData, type ClickCustomData, type ClientContext, type ConsoleLogLevel, type ConsoleLogPluginData, type CustomEventData, type DeadClickCustomData, type DialogOpenedCustomData, type ElementDescriptor, type ErrorMessageCustomData, type FlagEvaluationPluginData, type FormFieldReEditCustomData, type Frame, type IdleGapCustomData, type IncrementalSnapshotData, IncrementalSource, type InputCustomData, MAX_DISTINCT_KEYS, MAX_KEY_LENGTH, MAX_TAG_VALUE_LENGTH, MAX_VALUES_PER_KEY, type MeasurePluginData, type MouseInteractionData, MouseInteractions, type NetworkRequestInitiator, type NetworkRequestPluginData, type OpaqueIncrementalData, type RageClickCustomData, type RecordingEvent, RecordingEventType, type RouteChangeCustomData, type RouteChangePayload, type RouteChangePluginData, type RouteChangeTrigger, type ScrollBackCustomData, type SelectionData, type SelectionRange, SerializedNodeType, type TabRefocusCustomData, type TabUnfocusCustomData, type TabVisibilityPluginData, type TagPluginData, type UserAgentContext, stripUrl, validateKey, validateMeasureValue, validateTagValue };
+export { type AwayGapCustomData, type ClickCustomData, type ClientContext, type ConsoleLogLevel, type ConsoleLogPluginData, type CustomEventData, type DeadClickCustomData, type DialogOpenedCustomData, type ElementDescriptor, type ErrorMessageCustomData, type FlagEvaluationPluginData, type FormFieldReEditCustomData, type Frame, type GraphQLRequestMetadata, type IdleGapCustomData, type IncrementalSnapshotData, IncrementalSource, type InputCustomData, MAX_DISTINCT_KEYS, MAX_KEY_LENGTH, MAX_TAG_VALUE_LENGTH, MAX_VALUES_PER_KEY, type MeasurePluginData, type MouseInteractionData, MouseInteractions, type NetworkRequestInitiator, type NetworkRequestPluginData, type OpaqueIncrementalData, type RageClickCustomData, type RecordingEvent, RecordingEventType, type RouteChangeCustomData, type RouteChangePayload, type RouteChangePluginData, type RouteChangeTrigger, type ScrollBackCustomData, type SelectionData, type SelectionRange, SerializedNodeType, type TabRefocusCustomData, type TabUnfocusCustomData, type TabVisibilityPluginData, type TagPluginData, type UserAgentContext, stripUrl, validateKey, validateMeasureValue, validateTagValue };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spotify-confidence/csr-common",
   "license": "Apache-2.0",
-  "version": "0.18.5",
+  "version": "0.18.6",
   "repository": {
     "type": "git",
     "url": "https://github.com/spotify/confidence-sdk-js.git",
@@ -28,7 +28,7 @@
   ],
   "scripts": {
     "prebuild": "node scripts/build-worker.mjs",
-    "build": "yarn run -T tsdown",
+    "build": "yarn run -T tsdown && node scripts/emit-worker-file.mjs",
     "typecheck": "tsc --noEmit"
   },
   "publishConfig": {

package/src/events.ts

@@ -230,6 +230,10 @@ export type ConsoleLogPluginData = {
 
 export type NetworkRequestInitiator = 'fetch' | 'xhr';
 
+export type GraphQLRequestMetadata = {
+  operationName: string;
+};
+
 /**
  * Plugin event data emitted by the recorder for network requests.
  */
@@ -243,6 +247,7 @@ export type NetworkRequestPluginData = {
     durationMs: number;
     requestSize?: number;
     responseSize?: number;
+    graphql?: GraphQLRequestMetadata;
   };
 };
 

package/src/index.ts

@@ -23,6 +23,7 @@ export {
   type ConsoleLogLevel,
   type ConsoleLogPluginData,
   type NetworkRequestInitiator,
+  type GraphQLRequestMetadata,
   type NetworkRequestPluginData,
   type RouteChangeTrigger,
   type RouteChangePayload,