@spotify-confidence/csr-common 0.0.0 → 0.17.2

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [0.17.2](https://github.com/spotify/confidence-sdk-js/compare/csr-common-v0.17.1...csr-common-v0.17.2) (2026-06-15)
+
+
+### 🐛 Bug Fixes
+
+* improve csr package READMEs ([#367](https://github.com/spotify/confidence-sdk-js/issues/367)) ([3c5a254](https://github.com/spotify/confidence-sdk-js/commit/3c5a254b6b7bd23142ffe7ce6d99f327e67ff478))
+
+## [0.17.1](https://github.com/spotify/confidence-sdk-js/compare/csr-common-v0.17.0...csr-common-v0.17.1) (2026-06-15)
+
+
+### 🐛 Bug Fixes
+
+* add csr packages to release-please ([#363](https://github.com/spotify/confidence-sdk-js/issues/363)) ([f868e03](https://github.com/spotify/confidence-sdk-js/commit/f868e036ee27fcdd26ee26c8a47d2466a47e2a60))
+
+
+### ✨ New Features
+
+* add session recording packages ([#360](https://github.com/spotify/confidence-sdk-js/issues/360)) ([4584f50](https://github.com/spotify/confidence-sdk-js/commit/4584f502f17d01a15390789519c99308797a513d))

package/README.md

@@ -0,0 +1,16 @@
+# @spotify-confidence/csr-common
+
+![](https://img.shields.io/badge/lifecycle-beta-a0c3d2.svg)
+
+Shared types, event definitions, and utilities for the Confidence session recording SDK. This package is a foundation dependency — most consumers should use `@spotify-confidence/session-recording` directly.
+
+## What's in here
+
+- **Event types** — `RecordingEvent`, `RecordingEventType`, `IncrementalSource`, and custom event data types used across the recording pipeline.
+- **Validation** — `validateKey`, `validateTagValue`, `validateMeasureValue` for custom tags and measurements.
+- **Uploader** — `createUploader` factory and WebSocket transport for streaming recording frames to the Confidence backend. Available via the `csr-common/uploader` subpath export.
+- **Client context** — `collectUserAgentContext` for auto-collecting browser/OS/screen metadata.
+
+## License
+
+Apache 2.0 — see [LICENSE](../../LICENSE).

package/dist/index.cjs

@@ -0,0 +1,116 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/events.ts
+/**
+* Mirrors rrweb's serialized-node types but decoupled — we own the enum.
+*/
+let SerializedNodeType = /* @__PURE__ */ function(SerializedNodeType) {
+	SerializedNodeType[SerializedNodeType["Document"] = 0] = "Document";
+	SerializedNodeType[SerializedNodeType["DocumentType"] = 1] = "DocumentType";
+	SerializedNodeType[SerializedNodeType["Element"] = 2] = "Element";
+	SerializedNodeType[SerializedNodeType["Text"] = 3] = "Text";
+	SerializedNodeType[SerializedNodeType["CDATA"] = 4] = "CDATA";
+	SerializedNodeType[SerializedNodeType["Comment"] = 5] = "Comment";
+	return SerializedNodeType;
+}({});
+/**
+* Mirrors rrweb event types but decoupled — we own the enum.
+*/
+let RecordingEventType = /* @__PURE__ */ function(RecordingEventType) {
+	RecordingEventType[RecordingEventType["DomContentLoaded"] = 0] = "DomContentLoaded";
+	RecordingEventType[RecordingEventType["Load"] = 1] = "Load";
+	RecordingEventType[RecordingEventType["FullSnapshot"] = 2] = "FullSnapshot";
+	RecordingEventType[RecordingEventType["IncrementalSnapshot"] = 3] = "IncrementalSnapshot";
+	RecordingEventType[RecordingEventType["Meta"] = 4] = "Meta";
+	RecordingEventType[RecordingEventType["Custom"] = 5] = "Custom";
+	RecordingEventType[RecordingEventType["Plugin"] = 6] = "Plugin";
+	return RecordingEventType;
+}({});
+/**
+* Incremental snapshot sub-types.
+*/
+let IncrementalSource = /* @__PURE__ */ function(IncrementalSource) {
+	IncrementalSource[IncrementalSource["Mutation"] = 0] = "Mutation";
+	IncrementalSource[IncrementalSource["MouseMove"] = 1] = "MouseMove";
+	IncrementalSource[IncrementalSource["MouseInteraction"] = 2] = "MouseInteraction";
+	IncrementalSource[IncrementalSource["Scroll"] = 3] = "Scroll";
+	IncrementalSource[IncrementalSource["ViewportResize"] = 4] = "ViewportResize";
+	IncrementalSource[IncrementalSource["Input"] = 5] = "Input";
+	IncrementalSource[IncrementalSource["TouchMove"] = 6] = "TouchMove";
+	IncrementalSource[IncrementalSource["MediaInteraction"] = 7] = "MediaInteraction";
+	IncrementalSource[IncrementalSource["StyleSheetRule"] = 8] = "StyleSheetRule";
+	IncrementalSource[IncrementalSource["CanvasMutation"] = 9] = "CanvasMutation";
+	IncrementalSource[IncrementalSource["Font"] = 10] = "Font";
+	IncrementalSource[IncrementalSource["Log"] = 11] = "Log";
+	IncrementalSource[IncrementalSource["Drag"] = 12] = "Drag";
+	IncrementalSource[IncrementalSource["StyleDeclaration"] = 13] = "StyleDeclaration";
+	IncrementalSource[IncrementalSource["Selection"] = 14] = "Selection";
+	IncrementalSource[IncrementalSource["AdoptedStyleSheet"] = 15] = "AdoptedStyleSheet";
+	return IncrementalSource;
+}({});
+/**
+* From rrweb MouseInteractions.
+*/
+let MouseInteractions = /* @__PURE__ */ function(MouseInteractions) {
+	MouseInteractions[MouseInteractions["MouseUp"] = 0] = "MouseUp";
+	MouseInteractions[MouseInteractions["MouseDown"] = 1] = "MouseDown";
+	MouseInteractions[MouseInteractions["Click"] = 2] = "Click";
+	MouseInteractions[MouseInteractions["ContextMenu"] = 3] = "ContextMenu";
+	MouseInteractions[MouseInteractions["DblClick"] = 4] = "DblClick";
+	MouseInteractions[MouseInteractions["Focus"] = 5] = "Focus";
+	MouseInteractions[MouseInteractions["Blur"] = 6] = "Blur";
+	MouseInteractions[MouseInteractions["TouchStart"] = 7] = "TouchStart";
+	MouseInteractions[MouseInteractions["TouchMove_Departed"] = 8] = "TouchMove_Departed";
+	MouseInteractions[MouseInteractions["TouchEnd"] = 9] = "TouchEnd";
+	MouseInteractions[MouseInteractions["TouchCancel"] = 10] = "TouchCancel";
+	return MouseInteractions;
+}({});
+//#endregion
+//#region src/url.ts
+/**
+* Extract only the pathname from a URL, stripping origin, query string, and
+* hash. Used across recorder and analyzer to avoid capturing PII in route data.
+*/
+function stripUrl(url) {
+	try {
+		return new URL(url).pathname;
+	} catch (_e) {
+		return url;
+	}
+}
+//#endregion
+//#region src/custom-event-limits.ts
+const MAX_KEY_LENGTH = 128;
+const MAX_TAG_VALUE_LENGTH = 256;
+const MAX_DISTINCT_KEYS = 100;
+const MAX_VALUES_PER_KEY = 1e3;
+const VALID_KEY_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+function validateKey(key) {
+	if (typeof key !== "string" || key.length === 0) return "key is empty";
+	if (key.length > 128) return `key exceeds 128 characters`;
+	if (!VALID_KEY_PATTERN.test(key)) return "key contains invalid characters (allowed: a-z A-Z 0-9 _ . -)";
+	return null;
+}
+function validateTagValue(value) {
+	if (value === void 0) return null;
+	if (typeof value !== "string") return "tag value is not a string";
+	if (value.length > 256) return `tag value exceeds 256 characters`;
+	return null;
+}
+function validateMeasureValue(value) {
+	if (value === void 0) return null;
+	if (typeof value !== "number" || !Number.isFinite(value)) return "measure value must be a finite number";
+	return null;
+}
+//#endregion
+exports.IncrementalSource = IncrementalSource;
+exports.MAX_DISTINCT_KEYS = MAX_DISTINCT_KEYS;
+exports.MAX_KEY_LENGTH = MAX_KEY_LENGTH;
+exports.MAX_TAG_VALUE_LENGTH = MAX_TAG_VALUE_LENGTH;
+exports.MAX_VALUES_PER_KEY = MAX_VALUES_PER_KEY;
+exports.MouseInteractions = MouseInteractions;
+exports.RecordingEventType = RecordingEventType;
+exports.SerializedNodeType = SerializedNodeType;
+exports.stripUrl = stripUrl;
+exports.validateKey = validateKey;
+exports.validateMeasureValue = validateMeasureValue;
+exports.validateTagValue = validateTagValue;

package/dist/index.d.cts

@@ -0,0 +1,239 @@
+import { i as ClientContext, n as Frame, o as UserAgentContext } from "./types-BFkUa8kB.cjs";
+
+//#region src/events.d.ts
+/**
+* Mirrors rrweb's serialized-node types but decoupled — we own the enum.
+*/
+declare enum SerializedNodeType {
+  Document = 0,
+  DocumentType = 1,
+  Element = 2,
+  Text = 3,
+  CDATA = 4,
+  Comment = 5
+}
+/**
+* Mirrors rrweb event types but decoupled — we own the enum.
+*/
+declare enum RecordingEventType {
+  DomContentLoaded = 0,
+  Load = 1,
+  FullSnapshot = 2,
+  IncrementalSnapshot = 3,
+  Meta = 4,
+  Custom = 5,
+  Plugin = 6
+}
+/**
+* Incremental snapshot sub-types.
+*/
+declare enum IncrementalSource {
+  Mutation = 0,
+  MouseMove = 1,
+  MouseInteraction = 2,
+  Scroll = 3,
+  ViewportResize = 4,
+  Input = 5,
+  TouchMove = 6,
+  MediaInteraction = 7,
+  StyleSheetRule = 8,
+  CanvasMutation = 9,
+  Font = 10,
+  Log = 11,
+  Drag = 12,
+  StyleDeclaration = 13,
+  Selection = 14,
+  AdoptedStyleSheet = 15
+}
+/**
+* From rrweb MouseInteractions.
+*/
+declare enum MouseInteractions {
+  MouseUp = 0,
+  MouseDown = 1,
+  Click = 2,
+  ContextMenu = 3,
+  DblClick = 4,
+  Focus = 5,
+  Blur = 6,
+  TouchStart = 7,
+  TouchMove_Departed = 8,
+  TouchEnd = 9,
+  TouchCancel = 10
+}
+type RageClickCustomData = {
+  tag: "csr:rageClick";
+  payload: {
+    targetId: number;
+    clickCount: number;
+    durationMs: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+type FormFieldReEditCustomData = {
+  tag: "csr:formFieldReEdit";
+  payload: {
+    targetId: number;
+    editCount: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+type ScrollBackCustomData = {
+  tag: "csr:scrollBack";
+  payload: {
+    scrollBackPx: number;
+    fromY: number;
+    toY: number;
+    pathname?: string;
+  };
+};
+type ElementDescriptor = {
+  tagName: string;
+  classes?: string[];
+  textContent?: string;
+  attributes?: Record<string, string>;
+};
+type ClickCustomData = {
+  tag: "csr:click";
+  payload: {
+    targetId: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+type InputCustomData = {
+  tag: "csr:input";
+  payload: {
+    targetId: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+type DeadClickCustomData = {
+  tag: "csr:deadClick";
+  payload: {
+    targetId: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+type TabUnfocusCustomData = {
+  tag: "csr:tabUnfocus";
+  payload: {
+    pathname?: string;
+  };
+};
+type TabRefocusCustomData = {
+  tag: "csr:tabRefocus";
+  payload: {
+    awayDurationMs: number;
+    pathname?: string;
+  };
+};
+type RouteChangeTrigger = "pushState" | "replaceState" | "popstate" | "navigation";
+type RouteChangePayload = {
+  from: string;
+  to: string;
+  trigger: RouteChangeTrigger;
+};
+type RouteChangeCustomData = {
+  tag: "csr:routeChange";
+  payload: RouteChangePayload;
+};
+/**
+* Plugin event data emitted by the recorder for tab visibility changes.
+*/
+type TabVisibilityPluginData = {
+  plugin: "csr:tabVisibility";
+  payload: {
+    hidden: boolean;
+  };
+};
+type ConsoleLogLevel = "log" | "warn" | "error" | "debug" | "info";
+/**
+* Plugin event data emitted by rrweb's console record plugin.
+* Shape matches `@rrweb/rrweb-plugin-console-record` LogData.
+*/
+type ConsoleLogPluginData = {
+  plugin: "rrweb/console@1";
+  payload: {
+    level: ConsoleLogLevel;
+    payload: string[];
+    trace: string[];
+  };
+};
+type NetworkRequestInitiator = "fetch" | "xhr";
+/**
+* Plugin event data emitted by the recorder for network requests.
+*/
+type NetworkRequestPluginData = {
+  plugin: "csr:networkRequest";
+  payload: {
+    initiator: NetworkRequestInitiator;
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    requestSize?: number;
+    responseSize?: number;
+  };
+};
+type RouteChangePluginData = {
+  plugin: "csr:routeChange";
+  payload: RouteChangePayload;
+};
+type TagPluginData = {
+  plugin: "csr:tag";
+  payload: {
+    key: string;
+    value?: string;
+  };
+};
+type MeasurePluginData = {
+  plugin: "csr:measure";
+  payload: {
+    key: string;
+    value?: number;
+  };
+};
+/**
+* Closed union of every Custom event we emit. Add a new variant here when
+* introducing a new tag — emitting an unregistered tag is a TS error.
+*/
+type CustomEventData = ClickCustomData | InputCustomData | RageClickCustomData | FormFieldReEditCustomData | ScrollBackCustomData | DeadClickCustomData | TabUnfocusCustomData | TabRefocusCustomData | RouteChangeCustomData;
+/**
+* A single recorded event.
+*
+* For non-Custom events `data` is `unknown` (decoupled from rrweb internals).
+* For Custom events `data.tag` discriminates the payload across the closed
+* `CustomEventData` union.
+*/
+type RecordingEvent = {
+  type: RecordingEventType.Custom;
+  timestamp: number;
+  data: CustomEventData;
+} | {
+  type: Exclude<RecordingEventType, RecordingEventType.Custom>;
+  timestamp: number;
+  data: unknown;
+};
+//#endregion
+//#region src/url.d.ts
+/**
+* Extract only the pathname from a URL, stripping origin, query string, and
+* hash. Used across recorder and analyzer to avoid capturing PII in route data.
+*/
+declare function stripUrl(url: string): string;
+//#endregion
+//#region src/custom-event-limits.d.ts
+declare const MAX_KEY_LENGTH = 128;
+declare const MAX_TAG_VALUE_LENGTH = 256;
+declare const MAX_DISTINCT_KEYS = 100;
+declare const MAX_VALUES_PER_KEY = 1e3;
+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 ClickCustomData, type ClientContext, type ConsoleLogLevel, type ConsoleLogPluginData, type CustomEventData, type DeadClickCustomData, type ElementDescriptor, type FormFieldReEditCustomData, type Frame, IncrementalSource, type InputCustomData, MAX_DISTINCT_KEYS, MAX_KEY_LENGTH, MAX_TAG_VALUE_LENGTH, MAX_VALUES_PER_KEY, type MeasurePluginData, MouseInteractions, type NetworkRequestInitiator, type NetworkRequestPluginData, type RageClickCustomData, type RecordingEvent, RecordingEventType, type RouteChangeCustomData, type RouteChangePayload, type RouteChangePluginData, type RouteChangeTrigger, type ScrollBackCustomData, SerializedNodeType, type TabRefocusCustomData, type TabUnfocusCustomData, type TabVisibilityPluginData, type TagPluginData, type UserAgentContext, stripUrl, validateKey, validateMeasureValue, validateTagValue };

package/dist/index.d.ts

@@ -0,0 +1,239 @@
+import { i as ClientContext, n as Frame, o as UserAgentContext } from "./types-BFkUa8kB.js";
+
+//#region src/events.d.ts
+/**
+* Mirrors rrweb's serialized-node types but decoupled — we own the enum.
+*/
+declare enum SerializedNodeType {
+  Document = 0,
+  DocumentType = 1,
+  Element = 2,
+  Text = 3,
+  CDATA = 4,
+  Comment = 5
+}
+/**
+* Mirrors rrweb event types but decoupled — we own the enum.
+*/
+declare enum RecordingEventType {
+  DomContentLoaded = 0,
+  Load = 1,
+  FullSnapshot = 2,
+  IncrementalSnapshot = 3,
+  Meta = 4,
+  Custom = 5,
+  Plugin = 6
+}
+/**
+* Incremental snapshot sub-types.
+*/
+declare enum IncrementalSource {
+  Mutation = 0,
+  MouseMove = 1,
+  MouseInteraction = 2,
+  Scroll = 3,
+  ViewportResize = 4,
+  Input = 5,
+  TouchMove = 6,
+  MediaInteraction = 7,
+  StyleSheetRule = 8,
+  CanvasMutation = 9,
+  Font = 10,
+  Log = 11,
+  Drag = 12,
+  StyleDeclaration = 13,
+  Selection = 14,
+  AdoptedStyleSheet = 15
+}
+/**
+* From rrweb MouseInteractions.
+*/
+declare enum MouseInteractions {
+  MouseUp = 0,
+  MouseDown = 1,
+  Click = 2,
+  ContextMenu = 3,
+  DblClick = 4,
+  Focus = 5,
+  Blur = 6,
+  TouchStart = 7,
+  TouchMove_Departed = 8,
+  TouchEnd = 9,
+  TouchCancel = 10
+}
+type RageClickCustomData = {
+  tag: "csr:rageClick";
+  payload: {
+    targetId: number;
+    clickCount: number;
+    durationMs: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+type FormFieldReEditCustomData = {
+  tag: "csr:formFieldReEdit";
+  payload: {
+    targetId: number;
+    editCount: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+type ScrollBackCustomData = {
+  tag: "csr:scrollBack";
+  payload: {
+    scrollBackPx: number;
+    fromY: number;
+    toY: number;
+    pathname?: string;
+  };
+};
+type ElementDescriptor = {
+  tagName: string;
+  classes?: string[];
+  textContent?: string;
+  attributes?: Record<string, string>;
+};
+type ClickCustomData = {
+  tag: "csr:click";
+  payload: {
+    targetId: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+type InputCustomData = {
+  tag: "csr:input";
+  payload: {
+    targetId: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+type DeadClickCustomData = {
+  tag: "csr:deadClick";
+  payload: {
+    targetId: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+type TabUnfocusCustomData = {
+  tag: "csr:tabUnfocus";
+  payload: {
+    pathname?: string;
+  };
+};
+type TabRefocusCustomData = {
+  tag: "csr:tabRefocus";
+  payload: {
+    awayDurationMs: number;
+    pathname?: string;
+  };
+};
+type RouteChangeTrigger = "pushState" | "replaceState" | "popstate" | "navigation";
+type RouteChangePayload = {
+  from: string;
+  to: string;
+  trigger: RouteChangeTrigger;
+};
+type RouteChangeCustomData = {
+  tag: "csr:routeChange";
+  payload: RouteChangePayload;
+};
+/**
+* Plugin event data emitted by the recorder for tab visibility changes.
+*/
+type TabVisibilityPluginData = {
+  plugin: "csr:tabVisibility";
+  payload: {
+    hidden: boolean;
+  };
+};
+type ConsoleLogLevel = "log" | "warn" | "error" | "debug" | "info";
+/**
+* Plugin event data emitted by rrweb's console record plugin.
+* Shape matches `@rrweb/rrweb-plugin-console-record` LogData.
+*/
+type ConsoleLogPluginData = {
+  plugin: "rrweb/console@1";
+  payload: {
+    level: ConsoleLogLevel;
+    payload: string[];
+    trace: string[];
+  };
+};
+type NetworkRequestInitiator = "fetch" | "xhr";
+/**
+* Plugin event data emitted by the recorder for network requests.
+*/
+type NetworkRequestPluginData = {
+  plugin: "csr:networkRequest";
+  payload: {
+    initiator: NetworkRequestInitiator;
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    requestSize?: number;
+    responseSize?: number;
+  };
+};
+type RouteChangePluginData = {
+  plugin: "csr:routeChange";
+  payload: RouteChangePayload;
+};
+type TagPluginData = {
+  plugin: "csr:tag";
+  payload: {
+    key: string;
+    value?: string;
+  };
+};
+type MeasurePluginData = {
+  plugin: "csr:measure";
+  payload: {
+    key: string;
+    value?: number;
+  };
+};
+/**
+* Closed union of every Custom event we emit. Add a new variant here when
+* introducing a new tag — emitting an unregistered tag is a TS error.
+*/
+type CustomEventData = ClickCustomData | InputCustomData | RageClickCustomData | FormFieldReEditCustomData | ScrollBackCustomData | DeadClickCustomData | TabUnfocusCustomData | TabRefocusCustomData | RouteChangeCustomData;
+/**
+* A single recorded event.
+*
+* For non-Custom events `data` is `unknown` (decoupled from rrweb internals).
+* For Custom events `data.tag` discriminates the payload across the closed
+* `CustomEventData` union.
+*/
+type RecordingEvent = {
+  type: RecordingEventType.Custom;
+  timestamp: number;
+  data: CustomEventData;
+} | {
+  type: Exclude<RecordingEventType, RecordingEventType.Custom>;
+  timestamp: number;
+  data: unknown;
+};
+//#endregion
+//#region src/url.d.ts
+/**
+* Extract only the pathname from a URL, stripping origin, query string, and
+* hash. Used across recorder and analyzer to avoid capturing PII in route data.
+*/
+declare function stripUrl(url: string): string;
+//#endregion
+//#region src/custom-event-limits.d.ts
+declare const MAX_KEY_LENGTH = 128;
+declare const MAX_TAG_VALUE_LENGTH = 256;
+declare const MAX_DISTINCT_KEYS = 100;
+declare const MAX_VALUES_PER_KEY = 1e3;
+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 ClickCustomData, type ClientContext, type ConsoleLogLevel, type ConsoleLogPluginData, type CustomEventData, type DeadClickCustomData, type ElementDescriptor, type FormFieldReEditCustomData, type Frame, IncrementalSource, type InputCustomData, MAX_DISTINCT_KEYS, MAX_KEY_LENGTH, MAX_TAG_VALUE_LENGTH, MAX_VALUES_PER_KEY, type MeasurePluginData, MouseInteractions, type NetworkRequestInitiator, type NetworkRequestPluginData, type RageClickCustomData, type RecordingEvent, RecordingEventType, type RouteChangeCustomData, type RouteChangePayload, type RouteChangePluginData, type RouteChangeTrigger, type ScrollBackCustomData, SerializedNodeType, type TabRefocusCustomData, type TabUnfocusCustomData, type TabVisibilityPluginData, type TagPluginData, type UserAgentContext, stripUrl, validateKey, validateMeasureValue, validateTagValue };