@spotify-confidence/csr-common 0.0.0 → 0.17.2

package/dist/uploader/index.d.cts

@@ -0,0 +1,9 @@
+import { a as ContextValue, i as ClientContext, o as UserAgentContext, r as Uploader, s as collectUserAgentContext, t as CreateUploaderOptions } from "../types-BFkUa8kB.cjs";
+
+//#region src/uploader/create-uploader.d.ts
+declare function createUploader(opts: CreateUploaderOptions): Promise<Uploader | null>;
+//#endregion
+//#region src/uploader/worker/worker-script.d.ts
+declare const workerScript: string;
+//#endregion
+export { type ClientContext, type ContextValue, type CreateUploaderOptions, type Uploader, type UserAgentContext, collectUserAgentContext, createUploader, workerScript };

package/dist/uploader/index.d.ts

@@ -0,0 +1,9 @@
+import { a as ContextValue, i as ClientContext, o as UserAgentContext, r as Uploader, s as collectUserAgentContext, t as CreateUploaderOptions } from "../types-BFkUa8kB.js";
+
+//#region src/uploader/create-uploader.d.ts
+declare function createUploader(opts: CreateUploaderOptions): Promise<Uploader | null>;
+//#endregion
+//#region src/uploader/worker/worker-script.d.ts
+declare const workerScript: string;
+//#endregion
+export { type ClientContext, type ContextValue, type CreateUploaderOptions, type Uploader, type UserAgentContext, collectUserAgentContext, createUploader, workerScript };

package/dist/uploader/index.js

@@ -0,0 +1,250 @@
+import Bowser from "bowser";
+//#region src/uploader/client-context.ts
+function collectUserAgentContext() {
+	if (typeof window === "undefined" || typeof navigator === "undefined") return void 0;
+	const parsed = Bowser.parse(navigator.userAgent);
+	let timeZone;
+	try {
+		timeZone = new Intl.DateTimeFormat().resolvedOptions().timeZone;
+	} catch (_e) {}
+	return {
+		userAgent: navigator.userAgent,
+		os: parsed.os.name?.toLowerCase().replace(/\s+/g, ""),
+		browser: parsed.browser.name?.toLowerCase().replace(/\s+/g, ""),
+		browserVersion: parsed.browser.version?.split(".")[0],
+		mobile: parsed.platform.type ? parsed.platform.type === "mobile" || parsed.platform.type === "tablet" : void 0,
+		languageCode: navigator.language,
+		timeZone,
+		viewportWidth: window.innerWidth,
+		viewportHeight: window.innerHeight,
+		screenWidth: window.screen.width,
+		screenHeight: window.screen.height,
+		devicePixelRatio: window.devicePixelRatio,
+		uri: `${window.location.origin}${window.location.pathname}`,
+		referrer: document.referrer
+	};
+}
+//#endregion
+//#region src/uploader/worker/worker-script.ts
+const workerScript = "//#region src/uploader/worker/web-socket-transport.ts\n/**\n* WebSocket-backed Transport. Internal retry policy: clean server-initiated close after the\n* first successful open → reconnect and resume; abrupt close (or any close before the first\n* open) → fire `onClose` and stop. Frames received while a (re)connect is in progress are\n* buffered and flushed on open.\n*\n* `ready()` resolves on the first successful open and rejects on close-before-open. Callers\n* should await it before treating the Transport as live, so a failure to open can be caught\n* (e.g. 4404 unknown session) and recovered from.\n*/\nvar WebSocketTransport = class {\n	url;\n	ws = null;\n	onCloseCb = null;\n	onStateChangeCb = null;\n	intentionallyClosed = false;\n	dead = false;\n	/** Frames buffered while a (re)connect is in progress. */\n	pending = [];\n	readyPromise;\n	constructor(url) {\n		this.url = url;\n		this.readyPromise = new Promise((resolve, reject) => {\n			this.connect(false, resolve, reject);\n		});\n		this.readyPromise.catch(() => {});\n	}\n	ready() {\n		return this.readyPromise;\n	}\n	send(frame) {\n		if (this.dead || this.intentionallyClosed) return;\n		if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify(frame));\n		else this.pending.push(frame);\n	}\n	close(reason = \"transport-close\") {\n		this.intentionallyClosed = true;\n		this.ws?.close(1e3, reason);\n	}\n	onClose(cb) {\n		this.onCloseCb = cb;\n	}\n	onStateChange(cb) {\n		this.onStateChangeCb = cb;\n	}\n	connect(isReconnect, onReady, onReadyFail) {\n		const ws = new WebSocket(this.url);\n		this.ws = ws;\n		let opened = false;\n		ws.onopen = () => {\n			opened = true;\n			onReady?.();\n			if (isReconnect) this.onStateChangeCb?.({ connected: true });\n			while (this.pending.length > 0) {\n				const f = this.pending.shift();\n				ws.send(JSON.stringify(f));\n			}\n		};\n		ws.onclose = (event) => {\n			if (this.intentionallyClosed) return;\n			if (!opened) {\n				const reason = `${isReconnect ? \"reconnect\" : \"initial\"}-failed code=${event.code}`;\n				if (onReadyFail) {\n					onReadyFail(new Error(reason));\n					this.dead = true;\n				} else this.die(reason);\n				return;\n			}\n			if (event.wasClean && (event.code === 1e3 || event.code === 1001)) {\n				this.onStateChangeCb?.({ connected: false });\n				this.connect(true);\n			} else this.die(`close code=${event.code} wasClean=${event.wasClean}`);\n		};\n	}\n	die(reason) {\n		this.dead = true;\n		this.onCloseCb?.({ reason });\n	}\n};\n//#endregion\n//#region src/uploader/worker/csr-client.ts\n/**\n* Single Client implementation that talks to the recording backend's REST + WS protocol.\n* Both dev-server and prod implement the same protocol, so we don't need polymorphism here yet.\n*/\nvar CsrClient = class {\n	apiUrl;\n	clientSecret;\n	targetingKey;\n	context;\n	websocketUrl;\n	log;\n	forceRecord;\n	constructor(apiUrl, clientSecret, targetingKey, context, websocketUrl, log = () => {}, forceRecord) {\n		this.apiUrl = apiUrl;\n		this.clientSecret = clientSecret;\n		this.targetingKey = targetingKey;\n		this.context = context;\n		this.websocketUrl = websocketUrl;\n		this.log = log;\n		this.forceRecord = forceRecord;\n	}\n	async initSession() {\n		const url = `${this.trimSlash(this.apiUrl)}/v1/sessions:initSession`;\n		this.log(`fetch POST ${url}`);\n		const res = await fetch(url, {\n			method: \"POST\",\n			headers: { \"Content-Type\": \"application/json\" },\n			body: JSON.stringify({\n				clientSecret: this.clientSecret,\n				...this.targetingKey ? { targetingKey: this.targetingKey } : {},\n				...this.context && Object.keys(this.context).length > 0 ? { context: this.context } : {},\n				...this.forceRecord ? { forceRecord: true } : {}\n			})\n		});\n		if (!res.ok) throw new Error(`init-session failed: HTTP ${res.status}`);\n		const data = await res.json();\n		if (data.skipRecording) return { skipRecording: true };\n		if (!data.sessionId || !data.sessionToken) throw new Error(\"init-session response missing sessionId or sessionToken\");\n		return {\n			sessionId: data.sessionId,\n			sessionToken: data.sessionToken\n		};\n	}\n	async openTransport(sessionToken) {\n		const wsBase = this.websocketUrl ?? `${this.toWsScheme(this.trimSlash(this.apiUrl))}/sessions/stream`;\n		const url = `${wsBase}${wsBase.includes(\"?\") ? \"&\" : \"?\"}session_token=${encodeURIComponent(sessionToken)}`;\n		this.log(`WebSocket connect ${url}`);\n		const transport = new WebSocketTransport(url);\n		await transport.ready();\n		return transport;\n	}\n	trimSlash(s) {\n		return s.endsWith(\"/\") ? s.slice(0, -1) : s;\n	}\n	toWsScheme(base) {\n		if (base.startsWith(\"https://\")) return `wss://${base.slice(8)}`;\n		if (base.startsWith(\"http://\")) return `ws://${base.slice(7)}`;\n		return base;\n	}\n};\n//#endregion\n//#region src/uploader/worker/core.ts\nconst IDLE_GRACE_MS = 5e3;\nlet state = { phase: \"init\" };\nconst ports = [];\nlet idleTimer = null;\nfunction cancelIdleTimer() {\n	if (idleTimer !== null) {\n		clearTimeout(idleTimer);\n		idleTimer = null;\n	}\n}\nfunction log(msg) {\n	for (const handle of ports) if (handle.debugLogs) handle.port.postMessage({\n		type: \"log\",\n		msg\n	});\n}\n/**\n* The first hello \"locks in\" the session's apiUrl/clientSecret. Any later tab arriving\n* with different values is misconfigured — we reject it rather than silently using the\n* locked values. In SharedWorker mode the `name = hash(clientSecret)` scoping already\n* prevents secret-mismatch from sharing a worker, but this defends against the dedicated\n* path and against future bugs.\n*/\nlet lockedConfig = null;\nfunction registerPort(adapter) {\n	cancelIdleTimer();\n	const handle = {\n		port: adapter,\n		hello: null,\n		debugLogs: false\n	};\n	ports.push(handle);\n	adapter.onmessage((data) => {\n		handleMessage(handle, data);\n	});\n}\nfunction handleMessage(handle, message) {\n	switch (message.type) {\n		case \"hello\":\n			handle.hello = message;\n			handle.debugLogs = message.debugLogs ?? false;\n			if (rejectIfIncompatible(handle)) return;\n			if (state.phase !== \"dead\" && state.phase !== \"skipping\") detectDuplicateTab(handle);\n			onHello(handle);\n			return;\n		case \"frame\":\n			onFrame(message.frame);\n			return;\n		case \"bye\":\n			onBye(handle);\n			return;\n		default: break;\n	}\n}\n/**\n* Reject hellos whose `apiUrl`/`clientSecret` don't match the values established by the\n* first hello. Returns true if the port was rejected (caller should not continue\n* processing this hello).\n*/\nfunction rejectIfIncompatible(handle) {\n	if (lockedConfig === null) return false;\n	const incoming = handle.hello;\n	if (incoming.apiUrl === lockedConfig.apiUrl && incoming.websocketUrl === lockedConfig.websocketUrl && incoming.clientSecret === lockedConfig.clientSecret) return false;\n	handle.port.postMessage({\n		type: \"dead\",\n		reason: \"incompatible-options: apiUrl/websocketUrl/clientSecret differ from the worker session\"\n	});\n	const idx = ports.indexOf(handle);\n	if (idx >= 0) ports.splice(idx, 1);\n	return true;\n}\n/**\n* If another already-connected port has the same `tabId`, this hello is from a duplicate\n* tab (browser \"Duplicate\" command clones sessionStorage). Mint a fresh `tabId` so the two\n* tabs don't collide on the same `(sessionId, tabId)` Recording. The new tabId is returned\n* to the tab in `welcome` so it can update its own state and sessionStorage.\n*/\nfunction detectDuplicateTab(handle) {\n	const tabId = handle.hello.tabId;\n	if (!ports.some((p) => p !== handle && p.hello?.tabId === tabId)) return;\n	const fresh = crypto.randomUUID();\n	handle.newTabId = fresh;\n	handle.hello.tabId = fresh;\n}\nfunction onHello(handle) {\n	switch (state.phase) {\n		case \"init\":\n			lockedConfig = {\n				apiUrl: handle.hello.apiUrl,\n				websocketUrl: handle.hello.websocketUrl,\n				clientSecret: handle.hello.clientSecret\n			};\n			log(`hello received apiUrl=${handle.hello.apiUrl} websocketUrl=${handle.hello.websocketUrl ?? \"(derive)\"} sessionIdHint=${handle.hello.sessionIdHint ?? \"(none)\"}`);\n			state = { phase: \"initializing\" };\n			initializeSession(handle.hello).then(flushPendingWelcomes);\n			return;\n		case \"initializing\": return;\n		case \"active\":\n			sendActiveWelcome(handle, state.sessionId, state.sessionToken);\n			return;\n		case \"idle\": {\n			const { client, sessionId, sessionToken } = state;\n			state = { phase: \"initializing\" };\n			resumeTransport(client, sessionId, sessionToken).then(flushPendingWelcomes);\n			return;\n		}\n		case \"skipping\":\n			if (handle.hello.forceRecord) {\n				log(\"forceRecord set; re-initializing from skipping state\");\n				state = { phase: \"initializing\" };\n				initializeSession(handle.hello).then(flushPendingWelcomes);\n				return;\n			}\n			handle.port.postMessage({\n				type: \"welcome\",\n				result: { skipRecording: true }\n			});\n			return;\n		case \"dead\":\n			handle.port.postMessage({\n				type: \"dead\",\n				reason: state.reason\n			});\n			return;\n		default: break;\n	}\n}\nasync function initializeSession(firstHello) {\n	const client = new CsrClient(firstHello.apiUrl, firstHello.clientSecret, firstHello.targetingKey, firstHello.context, firstHello.websocketUrl, log, firstHello.forceRecord);\n	if (firstHello.sessionIdHint && firstHello.sessionTokenHint) {\n		log(`adopting sessionIdHint=${firstHello.sessionIdHint}`);\n		try {\n			const transport = await client.openTransport(firstHello.sessionTokenHint);\n			wireTransport(transport);\n			state = {\n				phase: \"active\",\n				client,\n				transport,\n				sessionId: firstHello.sessionIdHint,\n				sessionToken: firstHello.sessionTokenHint\n			};\n			log(\"hint adopted; transport open\");\n			if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n			return;\n		} catch (err) {\n			log(`hint rejected (${String(err)}); falling back to fresh init`);\n		}\n	}\n	let result;\n	try {\n		result = await client.initSession();\n	} catch (err) {\n		log(`init-session threw: ${String(err)}`);\n		transitionToDead(`init-session-failed: ${String(err)}`);\n		return;\n	}\n	if (\"skipRecording\" in result) {\n		log(\"init-session: skipRecording\");\n		state = { phase: \"skipping\" };\n		return;\n	}\n	log(`init-session ok sessionId=${result.sessionId}`);\n	let transport;\n	try {\n		transport = await client.openTransport(result.sessionToken);\n	} catch (err) {\n		log(`openTransport threw: ${String(err)}`);\n		transitionToDead(`open-transport-failed: ${String(err)}`);\n		return;\n	}\n	wireTransport(transport);\n	log(\"transport open; session active\");\n	state = {\n		phase: \"active\",\n		client,\n		transport,\n		sessionId: result.sessionId,\n		sessionToken: result.sessionToken\n	};\n	if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n}\nasync function resumeTransport(client, sessionId, sessionToken) {\n	log(\"resuming transport from idle\");\n	let transport;\n	try {\n		transport = await client.openTransport(sessionToken);\n	} catch (err) {\n		log(`resume-transport threw: ${String(err)}`);\n		transitionToDead(`resume-transport-failed: ${String(err)}`);\n		return;\n	}\n	wireTransport(transport);\n	log(\"transport resumed\");\n	state = {\n		phase: \"active\",\n		client,\n		transport,\n		sessionId,\n		sessionToken\n	};\n	if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n}\nfunction wireTransport(transport) {\n	transport.onClose((info) => {\n		if (state.phase !== \"active\") return;\n		transitionToDead(info.reason);\n	});\n	transport.onStateChange((info) => {\n		if (state.phase !== \"active\") return;\n		for (const handle of ports) handle.port.postMessage({\n			type: \"state\",\n			connected: info.connected\n		});\n	});\n}\nfunction transitionToDead(reason) {\n	state = {\n		phase: \"dead\",\n		reason\n	};\n	for (const handle of ports) handle.port.postMessage({\n		type: \"dead\",\n		reason\n	});\n}\nfunction flushPendingWelcomes() {\n	for (const handle of ports) {\n		if (handle.hello === null) continue;\n		if (state.phase === \"active\") sendActiveWelcome(handle, state.sessionId, state.sessionToken);\n		else if (state.phase === \"skipping\") handle.port.postMessage({\n			type: \"welcome\",\n			result: { skipRecording: true }\n		});\n		else if (state.phase === \"dead\") handle.port.postMessage({\n			type: \"dead\",\n			reason: state.reason\n		});\n	}\n}\nfunction sendActiveWelcome(handle, currentSessionId, currentSessionToken) {\n	const hint = handle.hello?.sessionIdHint;\n	const adopted = hint !== void 0 && hint !== currentSessionId;\n	const newTabId = handle.newTabId;\n	handle.port.postMessage({\n		type: \"welcome\",\n		result: {\n			sessionId: currentSessionId,\n			sessionToken: currentSessionToken\n		},\n		adoptedFromSessionId: adopted ? hint : void 0,\n		newTabId,\n		resetCounter: adopted || newTabId !== void 0\n	});\n}\nfunction onFrame(frame) {\n	if (state.phase !== \"active\") return;\n	state.transport.send(frame);\n}\nfunction onBye(handle) {\n	const idx = ports.indexOf(handle);\n	if (idx >= 0) ports.splice(idx, 1);\n	if (ports.length === 0 && state.phase === \"active\") {\n		log(`last tab disconnected; closing transport in ${IDLE_GRACE_MS}ms`);\n		idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n	}\n}\nfunction enterIdle() {\n	idleTimer = null;\n	if (state.phase !== \"active\" || ports.length > 0) return;\n	log(\"idle timeout; closing transport\");\n	state.transport.close(\"idle\");\n	state = {\n		phase: \"idle\",\n		client: state.client,\n		sessionId: state.sessionId,\n		sessionToken: state.sessionToken\n	};\n}\n//#endregion\n//#region src/uploader/worker/entry.ts\nconst SharedWorkerScopeCtor = globalThis.SharedWorkerGlobalScope;\nif (typeof SharedWorkerScopeCtor === \"function\" && self instanceof SharedWorkerScopeCtor) self.onconnect = (event) => {\n	const port = event.ports[0];\n	port.start();\n	registerPort(adaptMessagePort(port));\n};\nelse registerPort(adaptDedicatedSelf());\nfunction adaptMessagePort(port) {\n	return {\n		postMessage: (message) => port.postMessage(message),\n		onmessage: (cb) => {\n			port.onmessage = (e) => cb(e.data);\n		}\n	};\n}\nfunction adaptDedicatedSelf() {\n	const ws = self;\n	return {\n		postMessage: (message) => ws.postMessage(message),\n		onmessage: (cb) => {\n			ws.onmessage = (e) => cb(e.data);\n		}\n	};\n}\n//#endregion\n";
+//#endregion
+//#region src/uploader/create-uploader.ts
+const STORAGE_TAB_ID = "csr:tabId";
+const STORAGE_SESSION = "csr:session";
+const STORAGE_COUNTER = "csr:counter";
+const DEFAULT_SESSION_TTL_MS = 1800 * 1e3;
+async function createUploader(opts) {
+	const log = opts.debugLogger;
+	const sessionTtlMs = opts.sessionTtlMs ?? DEFAULT_SESSION_TTL_MS;
+	const tabId = readOrMintTabId();
+	const sessionHint = readSessionHint(sessionTtlMs);
+	const counterHint = readCounter();
+	const mode = resolveMode(opts.workerMode ?? "auto");
+	log?.(`tab: createUploader mode=${mode} tabId=${tabId} sessionHint=${sessionHint?.id ?? "(none)"} counterHint=${counterHint}`);
+	const port = await openWorkerPort(mode, opts.clientSecret, opts.workerUrl);
+	let phase = "awaiting-welcome";
+	let sessionId = null;
+	let sessionToken = null;
+	let effectiveTabId = tabId;
+	let resolveWelcome;
+	const welcomePromise = new Promise((res) => {
+		resolveWelcome = res;
+	});
+	port.setHandler((data) => {
+		const msg = data;
+		if (msg.type === "log") {
+			log?.(`worker: ${msg.msg}`);
+			return;
+		}
+		if (phase === "awaiting-welcome") {
+			if (msg.type === "welcome" || msg.type === "dead") {
+				phase = msg.type === "welcome" ? "active" : "dead";
+				resolveWelcome(msg);
+			}
+			return;
+		}
+		if (msg.type === "state" && sessionId !== null) {
+			opts.onStateChange?.({
+				sessionId,
+				tabId: effectiveTabId,
+				connected: msg.connected,
+				sessionToken
+			});
+			return;
+		}
+		if (msg.type === "dead") {
+			phase = "dead";
+			if (sessionId !== null) opts.onStateChange?.({
+				sessionId,
+				tabId: effectiveTabId,
+				connected: false,
+				sessionToken
+			});
+			opts.onTerminate?.({ reason: msg.reason });
+		}
+	});
+	const autoUA = collectUserAgentContext();
+	const context = {
+		...autoUA ? { userAgent: autoUA } : {},
+		...opts.context ?? {}
+	};
+	port.postMessage({
+		type: "hello",
+		apiUrl: opts.apiUrl,
+		websocketUrl: opts.websocketUrl,
+		clientSecret: opts.clientSecret,
+		targetingKey: opts.targetingKey,
+		context,
+		forceRecord: opts.forceRecord,
+		sessionIdHint: sessionHint?.id,
+		sessionTokenHint: sessionHint?.token,
+		tabId,
+		debugLogs: log !== void 0
+	});
+	log?.("tab: hello sent, awaiting welcome");
+	const welcome = await welcomePromise;
+	log?.(welcome.type === "welcome" ? `tab: welcome (${"sessionId" in welcome.result ? `sessionId=${welcome.result.sessionId}` : "skipRecording"})` : `tab: dead reason=${welcome.reason}`);
+	if (welcome.type === "dead") throw new Error(`uploader: ${welcome.reason}`);
+	if ("skipRecording" in welcome.result) {
+		if (opts.forceRecord) log?.("tab: forceRecord was set but backend still skipped — backend may not support forceRecord yet");
+		return null;
+	}
+	sessionId = welcome.result.sessionId;
+	sessionToken = welcome.result.sessionToken;
+	writeSession(welcome.result.sessionId, welcome.result.sessionToken);
+	if (welcome.newTabId !== void 0) {
+		effectiveTabId = welcome.newTabId;
+		sessionStorage.setItem(STORAGE_TAB_ID, effectiveTabId);
+	}
+	let counter = welcome.resetCounter ? 0 : counterHint;
+	let nextAdoptionMeta = welcome.adoptedFromSessionId !== void 0 ? {
+		adoptedFromSessionId: welcome.adoptedFromSessionId,
+		adoptedAt: Date.now()
+	} : void 0;
+	opts.onStateChange?.({
+		sessionId,
+		tabId: effectiveTabId,
+		connected: true,
+		sessionToken
+	});
+	const flush = () => {
+		writeCounter(counter);
+	};
+	window.addEventListener("pagehide", () => {
+		flush();
+		try {
+			port.postMessage({
+				type: "bye",
+				reason: "pagehide"
+			});
+		} catch (_e) {}
+	});
+	document.addEventListener("visibilitychange", () => {
+		if (document.visibilityState === "hidden") flush();
+	});
+	const uploader = ((event) => {
+		if (phase === "dead") throw new Error("uploader: terminated");
+		const frame = {
+			tabId: effectiveTabId,
+			eventCounter: counter,
+			data: event,
+			...nextAdoptionMeta ?? {}
+		};
+		counter += 1;
+		nextAdoptionMeta = void 0;
+		port.postMessage({
+			type: "frame",
+			frame
+		});
+	});
+	uploader.close = () => {
+		flush();
+		try {
+			port.postMessage({
+				type: "bye",
+				reason: "stop"
+			});
+		} catch (_e) {}
+	};
+	return uploader;
+}
+function resolveMode(mode) {
+	if (mode === "auto") return typeof SharedWorker !== "undefined" ? "shared" : "dedicated";
+	return mode;
+}
+async function openWorkerPort(mode, clientSecret, workerUrl) {
+	const url = workerUrl ?? toDataUrl("//#region src/uploader/worker/web-socket-transport.ts\n/**\n* WebSocket-backed Transport. Internal retry policy: clean server-initiated close after the\n* first successful open → reconnect and resume; abrupt close (or any close before the first\n* open) → fire `onClose` and stop. Frames received while a (re)connect is in progress are\n* buffered and flushed on open.\n*\n* `ready()` resolves on the first successful open and rejects on close-before-open. Callers\n* should await it before treating the Transport as live, so a failure to open can be caught\n* (e.g. 4404 unknown session) and recovered from.\n*/\nvar WebSocketTransport = class {\n	url;\n	ws = null;\n	onCloseCb = null;\n	onStateChangeCb = null;\n	intentionallyClosed = false;\n	dead = false;\n	/** Frames buffered while a (re)connect is in progress. */\n	pending = [];\n	readyPromise;\n	constructor(url) {\n		this.url = url;\n		this.readyPromise = new Promise((resolve, reject) => {\n			this.connect(false, resolve, reject);\n		});\n		this.readyPromise.catch(() => {});\n	}\n	ready() {\n		return this.readyPromise;\n	}\n	send(frame) {\n		if (this.dead || this.intentionallyClosed) return;\n		if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify(frame));\n		else this.pending.push(frame);\n	}\n	close(reason = \"transport-close\") {\n		this.intentionallyClosed = true;\n		this.ws?.close(1e3, reason);\n	}\n	onClose(cb) {\n		this.onCloseCb = cb;\n	}\n	onStateChange(cb) {\n		this.onStateChangeCb = cb;\n	}\n	connect(isReconnect, onReady, onReadyFail) {\n		const ws = new WebSocket(this.url);\n		this.ws = ws;\n		let opened = false;\n		ws.onopen = () => {\n			opened = true;\n			onReady?.();\n			if (isReconnect) this.onStateChangeCb?.({ connected: true });\n			while (this.pending.length > 0) {\n				const f = this.pending.shift();\n				ws.send(JSON.stringify(f));\n			}\n		};\n		ws.onclose = (event) => {\n			if (this.intentionallyClosed) return;\n			if (!opened) {\n				const reason = `${isReconnect ? \"reconnect\" : \"initial\"}-failed code=${event.code}`;\n				if (onReadyFail) {\n					onReadyFail(new Error(reason));\n					this.dead = true;\n				} else this.die(reason);\n				return;\n			}\n			if (event.wasClean && (event.code === 1e3 || event.code === 1001)) {\n				this.onStateChangeCb?.({ connected: false });\n				this.connect(true);\n			} else this.die(`close code=${event.code} wasClean=${event.wasClean}`);\n		};\n	}\n	die(reason) {\n		this.dead = true;\n		this.onCloseCb?.({ reason });\n	}\n};\n//#endregion\n//#region src/uploader/worker/csr-client.ts\n/**\n* Single Client implementation that talks to the recording backend's REST + WS protocol.\n* Both dev-server and prod implement the same protocol, so we don't need polymorphism here yet.\n*/\nvar CsrClient = class {\n	apiUrl;\n	clientSecret;\n	targetingKey;\n	context;\n	websocketUrl;\n	log;\n	forceRecord;\n	constructor(apiUrl, clientSecret, targetingKey, context, websocketUrl, log = () => {}, forceRecord) {\n		this.apiUrl = apiUrl;\n		this.clientSecret = clientSecret;\n		this.targetingKey = targetingKey;\n		this.context = context;\n		this.websocketUrl = websocketUrl;\n		this.log = log;\n		this.forceRecord = forceRecord;\n	}\n	async initSession() {\n		const url = `${this.trimSlash(this.apiUrl)}/v1/sessions:initSession`;\n		this.log(`fetch POST ${url}`);\n		const res = await fetch(url, {\n			method: \"POST\",\n			headers: { \"Content-Type\": \"application/json\" },\n			body: JSON.stringify({\n				clientSecret: this.clientSecret,\n				...this.targetingKey ? { targetingKey: this.targetingKey } : {},\n				...this.context && Object.keys(this.context).length > 0 ? { context: this.context } : {},\n				...this.forceRecord ? { forceRecord: true } : {}\n			})\n		});\n		if (!res.ok) throw new Error(`init-session failed: HTTP ${res.status}`);\n		const data = await res.json();\n		if (data.skipRecording) return { skipRecording: true };\n		if (!data.sessionId || !data.sessionToken) throw new Error(\"init-session response missing sessionId or sessionToken\");\n		return {\n			sessionId: data.sessionId,\n			sessionToken: data.sessionToken\n		};\n	}\n	async openTransport(sessionToken) {\n		const wsBase = this.websocketUrl ?? `${this.toWsScheme(this.trimSlash(this.apiUrl))}/sessions/stream`;\n		const url = `${wsBase}${wsBase.includes(\"?\") ? \"&\" : \"?\"}session_token=${encodeURIComponent(sessionToken)}`;\n		this.log(`WebSocket connect ${url}`);\n		const transport = new WebSocketTransport(url);\n		await transport.ready();\n		return transport;\n	}\n	trimSlash(s) {\n		return s.endsWith(\"/\") ? s.slice(0, -1) : s;\n	}\n	toWsScheme(base) {\n		if (base.startsWith(\"https://\")) return `wss://${base.slice(8)}`;\n		if (base.startsWith(\"http://\")) return `ws://${base.slice(7)}`;\n		return base;\n	}\n};\n//#endregion\n//#region src/uploader/worker/core.ts\nconst IDLE_GRACE_MS = 5e3;\nlet state = { phase: \"init\" };\nconst ports = [];\nlet idleTimer = null;\nfunction cancelIdleTimer() {\n	if (idleTimer !== null) {\n		clearTimeout(idleTimer);\n		idleTimer = null;\n	}\n}\nfunction log(msg) {\n	for (const handle of ports) if (handle.debugLogs) handle.port.postMessage({\n		type: \"log\",\n		msg\n	});\n}\n/**\n* The first hello \"locks in\" the session's apiUrl/clientSecret. Any later tab arriving\n* with different values is misconfigured — we reject it rather than silently using the\n* locked values. In SharedWorker mode the `name = hash(clientSecret)` scoping already\n* prevents secret-mismatch from sharing a worker, but this defends against the dedicated\n* path and against future bugs.\n*/\nlet lockedConfig = null;\nfunction registerPort(adapter) {\n	cancelIdleTimer();\n	const handle = {\n		port: adapter,\n		hello: null,\n		debugLogs: false\n	};\n	ports.push(handle);\n	adapter.onmessage((data) => {\n		handleMessage(handle, data);\n	});\n}\nfunction handleMessage(handle, message) {\n	switch (message.type) {\n		case \"hello\":\n			handle.hello = message;\n			handle.debugLogs = message.debugLogs ?? false;\n			if (rejectIfIncompatible(handle)) return;\n			if (state.phase !== \"dead\" && state.phase !== \"skipping\") detectDuplicateTab(handle);\n			onHello(handle);\n			return;\n		case \"frame\":\n			onFrame(message.frame);\n			return;\n		case \"bye\":\n			onBye(handle);\n			return;\n		default: break;\n	}\n}\n/**\n* Reject hellos whose `apiUrl`/`clientSecret` don't match the values established by the\n* first hello. Returns true if the port was rejected (caller should not continue\n* processing this hello).\n*/\nfunction rejectIfIncompatible(handle) {\n	if (lockedConfig === null) return false;\n	const incoming = handle.hello;\n	if (incoming.apiUrl === lockedConfig.apiUrl && incoming.websocketUrl === lockedConfig.websocketUrl && incoming.clientSecret === lockedConfig.clientSecret) return false;\n	handle.port.postMessage({\n		type: \"dead\",\n		reason: \"incompatible-options: apiUrl/websocketUrl/clientSecret differ from the worker session\"\n	});\n	const idx = ports.indexOf(handle);\n	if (idx >= 0) ports.splice(idx, 1);\n	return true;\n}\n/**\n* If another already-connected port has the same `tabId`, this hello is from a duplicate\n* tab (browser \"Duplicate\" command clones sessionStorage). Mint a fresh `tabId` so the two\n* tabs don't collide on the same `(sessionId, tabId)` Recording. The new tabId is returned\n* to the tab in `welcome` so it can update its own state and sessionStorage.\n*/\nfunction detectDuplicateTab(handle) {\n	const tabId = handle.hello.tabId;\n	if (!ports.some((p) => p !== handle && p.hello?.tabId === tabId)) return;\n	const fresh = crypto.randomUUID();\n	handle.newTabId = fresh;\n	handle.hello.tabId = fresh;\n}\nfunction onHello(handle) {\n	switch (state.phase) {\n		case \"init\":\n			lockedConfig = {\n				apiUrl: handle.hello.apiUrl,\n				websocketUrl: handle.hello.websocketUrl,\n				clientSecret: handle.hello.clientSecret\n			};\n			log(`hello received apiUrl=${handle.hello.apiUrl} websocketUrl=${handle.hello.websocketUrl ?? \"(derive)\"} sessionIdHint=${handle.hello.sessionIdHint ?? \"(none)\"}`);\n			state = { phase: \"initializing\" };\n			initializeSession(handle.hello).then(flushPendingWelcomes);\n			return;\n		case \"initializing\": return;\n		case \"active\":\n			sendActiveWelcome(handle, state.sessionId, state.sessionToken);\n			return;\n		case \"idle\": {\n			const { client, sessionId, sessionToken } = state;\n			state = { phase: \"initializing\" };\n			resumeTransport(client, sessionId, sessionToken).then(flushPendingWelcomes);\n			return;\n		}\n		case \"skipping\":\n			if (handle.hello.forceRecord) {\n				log(\"forceRecord set; re-initializing from skipping state\");\n				state = { phase: \"initializing\" };\n				initializeSession(handle.hello).then(flushPendingWelcomes);\n				return;\n			}\n			handle.port.postMessage({\n				type: \"welcome\",\n				result: { skipRecording: true }\n			});\n			return;\n		case \"dead\":\n			handle.port.postMessage({\n				type: \"dead\",\n				reason: state.reason\n			});\n			return;\n		default: break;\n	}\n}\nasync function initializeSession(firstHello) {\n	const client = new CsrClient(firstHello.apiUrl, firstHello.clientSecret, firstHello.targetingKey, firstHello.context, firstHello.websocketUrl, log, firstHello.forceRecord);\n	if (firstHello.sessionIdHint && firstHello.sessionTokenHint) {\n		log(`adopting sessionIdHint=${firstHello.sessionIdHint}`);\n		try {\n			const transport = await client.openTransport(firstHello.sessionTokenHint);\n			wireTransport(transport);\n			state = {\n				phase: \"active\",\n				client,\n				transport,\n				sessionId: firstHello.sessionIdHint,\n				sessionToken: firstHello.sessionTokenHint\n			};\n			log(\"hint adopted; transport open\");\n			if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n			return;\n		} catch (err) {\n			log(`hint rejected (${String(err)}); falling back to fresh init`);\n		}\n	}\n	let result;\n	try {\n		result = await client.initSession();\n	} catch (err) {\n		log(`init-session threw: ${String(err)}`);\n		transitionToDead(`init-session-failed: ${String(err)}`);\n		return;\n	}\n	if (\"skipRecording\" in result) {\n		log(\"init-session: skipRecording\");\n		state = { phase: \"skipping\" };\n		return;\n	}\n	log(`init-session ok sessionId=${result.sessionId}`);\n	let transport;\n	try {\n		transport = await client.openTransport(result.sessionToken);\n	} catch (err) {\n		log(`openTransport threw: ${String(err)}`);\n		transitionToDead(`open-transport-failed: ${String(err)}`);\n		return;\n	}\n	wireTransport(transport);\n	log(\"transport open; session active\");\n	state = {\n		phase: \"active\",\n		client,\n		transport,\n		sessionId: result.sessionId,\n		sessionToken: result.sessionToken\n	};\n	if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n}\nasync function resumeTransport(client, sessionId, sessionToken) {\n	log(\"resuming transport from idle\");\n	let transport;\n	try {\n		transport = await client.openTransport(sessionToken);\n	} catch (err) {\n		log(`resume-transport threw: ${String(err)}`);\n		transitionToDead(`resume-transport-failed: ${String(err)}`);\n		return;\n	}\n	wireTransport(transport);\n	log(\"transport resumed\");\n	state = {\n		phase: \"active\",\n		client,\n		transport,\n		sessionId,\n		sessionToken\n	};\n	if (ports.length === 0) idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n}\nfunction wireTransport(transport) {\n	transport.onClose((info) => {\n		if (state.phase !== \"active\") return;\n		transitionToDead(info.reason);\n	});\n	transport.onStateChange((info) => {\n		if (state.phase !== \"active\") return;\n		for (const handle of ports) handle.port.postMessage({\n			type: \"state\",\n			connected: info.connected\n		});\n	});\n}\nfunction transitionToDead(reason) {\n	state = {\n		phase: \"dead\",\n		reason\n	};\n	for (const handle of ports) handle.port.postMessage({\n		type: \"dead\",\n		reason\n	});\n}\nfunction flushPendingWelcomes() {\n	for (const handle of ports) {\n		if (handle.hello === null) continue;\n		if (state.phase === \"active\") sendActiveWelcome(handle, state.sessionId, state.sessionToken);\n		else if (state.phase === \"skipping\") handle.port.postMessage({\n			type: \"welcome\",\n			result: { skipRecording: true }\n		});\n		else if (state.phase === \"dead\") handle.port.postMessage({\n			type: \"dead\",\n			reason: state.reason\n		});\n	}\n}\nfunction sendActiveWelcome(handle, currentSessionId, currentSessionToken) {\n	const hint = handle.hello?.sessionIdHint;\n	const adopted = hint !== void 0 && hint !== currentSessionId;\n	const newTabId = handle.newTabId;\n	handle.port.postMessage({\n		type: \"welcome\",\n		result: {\n			sessionId: currentSessionId,\n			sessionToken: currentSessionToken\n		},\n		adoptedFromSessionId: adopted ? hint : void 0,\n		newTabId,\n		resetCounter: adopted || newTabId !== void 0\n	});\n}\nfunction onFrame(frame) {\n	if (state.phase !== \"active\") return;\n	state.transport.send(frame);\n}\nfunction onBye(handle) {\n	const idx = ports.indexOf(handle);\n	if (idx >= 0) ports.splice(idx, 1);\n	if (ports.length === 0 && state.phase === \"active\") {\n		log(`last tab disconnected; closing transport in ${IDLE_GRACE_MS}ms`);\n		idleTimer = setTimeout(enterIdle, IDLE_GRACE_MS);\n	}\n}\nfunction enterIdle() {\n	idleTimer = null;\n	if (state.phase !== \"active\" || ports.length > 0) return;\n	log(\"idle timeout; closing transport\");\n	state.transport.close(\"idle\");\n	state = {\n		phase: \"idle\",\n		client: state.client,\n		sessionId: state.sessionId,\n		sessionToken: state.sessionToken\n	};\n}\n//#endregion\n//#region src/uploader/worker/entry.ts\nconst SharedWorkerScopeCtor = globalThis.SharedWorkerGlobalScope;\nif (typeof SharedWorkerScopeCtor === \"function\" && self instanceof SharedWorkerScopeCtor) self.onconnect = (event) => {\n	const port = event.ports[0];\n	port.start();\n	registerPort(adaptMessagePort(port));\n};\nelse registerPort(adaptDedicatedSelf());\nfunction adaptMessagePort(port) {\n	return {\n		postMessage: (message) => port.postMessage(message),\n		onmessage: (cb) => {\n			port.onmessage = (e) => cb(e.data);\n		}\n	};\n}\nfunction adaptDedicatedSelf() {\n	const ws = self;\n	return {\n		postMessage: (message) => ws.postMessage(message),\n		onmessage: (cb) => {\n			ws.onmessage = (e) => cb(e.data);\n		}\n	};\n}\n//#endregion\n");
+	if (mode === "shared") {
+		const options = {
+			name: await hashSecret(clientSecret),
+			type: "module",
+			extendedLifetime: true
+		};
+		const worker = new SharedWorker(url, options);
+		worker.port.start();
+		return {
+			postMessage: (m) => worker.port.postMessage(m),
+			setHandler: (cb) => {
+				worker.port.onmessage = (e) => cb(e.data);
+			}
+		};
+	}
+	const worker = new Worker(url, { type: "module" });
+	return {
+		postMessage: (m) => worker.postMessage(m),
+		setHandler: (cb) => {
+			worker.onmessage = (e) => cb(e.data);
+		}
+	};
+}
+function toDataUrl(script) {
+	const bytes = new TextEncoder().encode(script);
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+	return `data:application/javascript;base64,${btoa(binary)}`;
+}
+async function hashSecret(secret) {
+	const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(secret));
+	return Array.from(new Uint8Array(buf)).slice(0, 8).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function readOrMintTabId() {
+	let id = sessionStorage.getItem(STORAGE_TAB_ID);
+	if (!id) {
+		id = crypto.randomUUID();
+		sessionStorage.setItem(STORAGE_TAB_ID, id);
+	}
+	return id;
+}
+function readSessionHint(ttlMs) {
+	const raw = sessionStorage.getItem(STORAGE_SESSION);
+	if (!raw) return null;
+	try {
+		const parsed = JSON.parse(raw);
+		if (Date.now() - parsed.ts > ttlMs) return null;
+		if (!parsed.token) return null;
+		return {
+			id: parsed.id,
+			token: parsed.token
+		};
+	} catch (_e) {
+		return null;
+	}
+}
+function writeSession(sessionId, sessionToken) {
+	sessionStorage.setItem(STORAGE_SESSION, JSON.stringify({
+		id: sessionId,
+		token: sessionToken,
+		ts: Date.now()
+	}));
+}
+function readCounter() {
+	const raw = sessionStorage.getItem(STORAGE_COUNTER);
+	if (!raw) return 0;
+	const n = Number(raw);
+	return Number.isFinite(n) ? n : 0;
+}
+function writeCounter(counter) {
+	sessionStorage.setItem(STORAGE_COUNTER, String(counter));
+}
+//#endregion
+export { collectUserAgentContext, createUploader, workerScript };

package/package.json

@@ -1 +1,58 @@
-{"name":"@spotify-confidence/csr-common","version":"0.0.0","description":"Placeholder"}
+{
+  "name": "@spotify-confidence/csr-common",
+  "license": "Apache-2.0",
+  "version": "0.17.2",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spotify/confidence-sdk-js.git",
+    "directory": "csr/csr-common"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./uploader": {
+      "types": "./dist/uploader/index.d.ts",
+      "import": "./dist/uploader/index.js",
+      "require": "./dist/uploader/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "prebuild": "node scripts/build-worker.mjs",
+    "build": "yarn run -T tsdown",
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "require": "./dist/index.cjs"
+      },
+      "./uploader": {
+        "types": "./dist/uploader/index.d.ts",
+        "import": "./dist/uploader/index.js",
+        "require": "./dist/uploader/index.cjs"
+      }
+    }
+  },
+  "dependencies": {
+    "bowser": "^2.14.1"
+  },
+  "module": "./dist/index.js"
+}

package/src/custom-event-limits.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest';
+import {
+  validateKey,
+  validateTagValue,
+  validateMeasureValue,
+  MAX_KEY_LENGTH,
+  MAX_TAG_VALUE_LENGTH,
+} from './custom-event-limits';
+
+describe('validateKey', () => {
+  it('accepts valid keys', () => {
+    expect(validateKey('page_view')).toBeNull();
+    expect(validateKey('click.count')).toBeNull();
+    expect(validateKey('my-feature')).toBeNull();
+    expect(validateKey('A1')).toBeNull();
+  });
+
+  it('rejects empty key', () => {
+    expect(validateKey('')).toBe('key is empty');
+  });
+
+  it('rejects key exceeding max length', () => {
+    expect(validateKey('a'.repeat(MAX_KEY_LENGTH + 1))).toContain('exceeds');
+  });
+
+  it('accepts key at max length', () => {
+    expect(validateKey('a'.repeat(MAX_KEY_LENGTH))).toBeNull();
+  });
+
+  it('rejects keys with invalid characters', () => {
+    expect(validateKey('has space')).toContain('invalid characters');
+    expect(validateKey('key=val')).toContain('invalid characters');
+    expect(validateKey('a/b')).toContain('invalid characters');
+    expect(validateKey('<script>')).toContain('invalid characters');
+  });
+});
+
+describe('validateTagValue', () => {
+  it('accepts undefined', () => {
+    expect(validateTagValue(undefined)).toBeNull();
+  });
+
+  it('accepts valid string', () => {
+    expect(validateTagValue('hello')).toBeNull();
+  });
+
+  it('accepts empty string', () => {
+    expect(validateTagValue('')).toBeNull();
+  });
+
+  it('rejects value exceeding max length', () => {
+    expect(validateTagValue('x'.repeat(MAX_TAG_VALUE_LENGTH + 1))).toContain('exceeds');
+  });
+
+  it('accepts value at max length', () => {
+    expect(validateTagValue('x'.repeat(MAX_TAG_VALUE_LENGTH))).toBeNull();
+  });
+});
+
+describe('validateMeasureValue', () => {
+  it('accepts undefined', () => {
+    expect(validateMeasureValue(undefined)).toBeNull();
+  });
+
+  it('accepts finite numbers', () => {
+    expect(validateMeasureValue(0)).toBeNull();
+    expect(validateMeasureValue(42)).toBeNull();
+    expect(validateMeasureValue(-1.5)).toBeNull();
+  });
+
+  it('rejects NaN', () => {
+    expect(validateMeasureValue(NaN)).toContain('finite');
+  });
+
+  it('rejects Infinity', () => {
+    expect(validateMeasureValue(Infinity)).toContain('finite');
+    expect(validateMeasureValue(-Infinity)).toContain('finite');
+  });
+});

package/src/custom-event-limits.ts

@@ -0,0 +1,25 @@
+export const MAX_KEY_LENGTH = 128;
+export const MAX_TAG_VALUE_LENGTH = 256;
+export const MAX_DISTINCT_KEYS = 100;
+export const MAX_VALUES_PER_KEY = 1000;
+const VALID_KEY_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+
+export function validateKey(key: string): string | null {
+  if (typeof key !== 'string' || key.length === 0) return 'key is empty';
+  if (key.length > MAX_KEY_LENGTH) return `key exceeds ${MAX_KEY_LENGTH} characters`;
+  if (!VALID_KEY_PATTERN.test(key)) return 'key contains invalid characters (allowed: a-z A-Z 0-9 _ . -)';
+  return null;
+}
+
+export function validateTagValue(value: string | undefined): string | null {
+  if (value === undefined) return null;
+  if (typeof value !== 'string') return 'tag value is not a string';
+  if (value.length > MAX_TAG_VALUE_LENGTH) return `tag value exceeds ${MAX_TAG_VALUE_LENGTH} characters`;
+  return null;
+}
+
+export function validateMeasureValue(value: number | undefined): string | null {
+  if (value === undefined) return null;
+  if (typeof value !== 'number' || !Number.isFinite(value)) return 'measure value must be a finite number';
+  return null;
+}