@spotify-confidence/session-recording 0.18.6 → 0.18.7

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.18.7](https://github.com/spotify/confidence-sdk-js/compare/session-recording-v0.18.6...session-recording-v0.18.7) (2026-08-18)
+
+
+### ✨ New Features
+
+* **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))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @spotify-confidence/csr-common bumped to 0.18.6
+    * @spotify-confidence/csr-recorder bumped to 0.17.12
+
 ## [0.18.6](https://github.com/spotify/confidence-sdk-js/compare/session-recording-v0.18.5...session-recording-v0.18.6) (2026-08-12)
 
 

package/README.md

@@ -87,6 +87,9 @@ const recorder = initSessionRecorder({
   // Recording mode
   mode: 'automatic', // 'automatic' (default) or 'manual'
 
+  // CSP: self-hosted worker (only needed when data: and blob: are blocked)
+  // workerUrl: '/confidence-worker.js',
+
   // Debug
   debugLogger: msg => console.log(msg), // lifecycle/transport messages (default: off, or console.log when CSR_DEBUG is set in sessionStorage)
 });
@@ -142,6 +145,74 @@ Then reload the page. The SDK will detect the flag and log to `console.log` auto
 
 > **Tip:** We recommend enabling debug logging when first integrating the SDK. It lets you confirm that a session is established, events are flowing, and the backend is reachable — all before you open the Confidence dashboard.
 
+## Content Security Policy (CSP)
+
+The SDK runs its upload logic in a Web Worker. By default it loads the worker from a `data:` URL, which requires no setup but may be blocked by strict Content Security Policies.
+
+### Required directives
+
+| Directive     | Value                                                                       |
+| ------------- | --------------------------------------------------------------------------- |
+| `worker-src`  | `data:` (default), or `blob:` (automatic fallback), or `'self'` (see below) |
+| `connect-src` | `https://recording.confidence.dev wss://recording-ws.confidence.dev`        |
+
+### If `data:` is blocked
+
+The SDK automatically falls back to a `blob:` URL. Most CSPs already allow `blob:` in `worker-src` — if yours does, no action is needed.
+
+### If both `data:` and `blob:` are blocked
+
+Self-host the worker script. The package ships a standalone file you can copy to your static assets:
+
+**Option A: copy from `node_modules`**
+
+```bash
+# After install, copy the worker to your public directory
+cp node_modules/@spotify-confidence/session-recording/dist/confidence-worker.js public/
+```
+
+**Option B: build-tool integration (Vite, webpack, etc.)**
+
+```typescript
+import { workerScript } from '@spotify-confidence/session-recording/worker';
+import { writeFileSync } from 'fs';
+
+// In a build plugin or script — write the worker to your output directory
+writeFileSync('dist/confidence-worker.js', workerScript);
+```
+
+**Option C: serve via a route (Express, Next.js API route, etc.)**
+
+```typescript
+import { workerScript } from '@spotify-confidence/session-recording/worker';
+
+app.get('/confidence-worker.js', (req, res) => {
+  res.type('application/javascript').send(workerScript);
+});
+```
+
+Then pass the URL:
+
+```typescript
+const recorder = initSessionRecorder({
+  clientSecret: '<your-client-secret>',
+  workerUrl: '/confidence-worker.js',
+});
+```
+
+Your CSP only needs `worker-src 'self'` with this setup.
+
+> **Note:** The worker version must match the SDK version. After upgrading `@spotify-confidence/session-recording`, re-copy or re-deploy the worker file.
+
+### Troubleshooting
+
+If recording silently fails, open DevTools and look for:
+
+- A `SecurityError` mentioning `worker-src` — your CSP blocks the worker. Use one of the options above.
+- A blocked `connect-src` request to `recording.confidence.dev` — add the hosts to your CSP.
+
+Enable [debug logging](#debug-logging) to see the full lifecycle and pinpoint where it fails.
+
 ## Manual mode
 
 Use `manual` mode to control when recording starts — useful for gating on user consent or feature flags.

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