@spotify-confidence/csr-common 0.18.3 → 0.18.5

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.18.5](https://github.com/spotify/confidence-sdk-js/compare/csr-common-v0.18.4...csr-common-v0.18.5) (2026-08-12)
+
+
+### ✨ New Features
+
+* **csr-common:** type incremental interaction data ([#430](https://github.com/spotify/confidence-sdk-js/issues/430)) ([43db5d9](https://github.com/spotify/confidence-sdk-js/commit/43db5d91f5368fab10eb5c97ba116575bc728672))
+
+## [0.18.4](https://github.com/spotify/confidence-sdk-js/compare/csr-common-v0.18.3...csr-common-v0.18.4) (2026-08-05)
+
+
+### ✨ New Features
+
+* **csr-common:** optional eventId identity on custom event payloads ([#428](https://github.com/spotify/confidence-sdk-js/issues/428)) ([f49970a](https://github.com/spotify/confidence-sdk-js/commit/f49970a4ccd34cbfbdef7729df19a256f077fced))
+
 ## [0.18.3](https://github.com/spotify/confidence-sdk-js/compare/csr-common-v0.18.2...csr-common-v0.18.3) (2026-07-16)
 
 

package/dist/index.d.cts

@@ -61,9 +61,43 @@ declare enum MouseInteractions {
   TouchEnd = 9,
   TouchCancel = 10
 }
+/**
+* Incremental mouse-interaction data emitted by rrweb.
+*/
+type MouseInteractionData = {
+  source: IncrementalSource.MouseInteraction;
+  type: MouseInteractions;
+  id: number;
+  x?: number;
+  y?: number;
+  pointerType?: number;
+};
+type SelectionRange = {
+  start: number;
+  startOffset: number;
+  end: number;
+  endOffset: number;
+};
+/**
+* Incremental text-selection data emitted by rrweb.
+*/
+type SelectionData = {
+  source: IncrementalSource.Selection;
+  ranges: SelectionRange[];
+};
+/**
+* Incremental sources that csr-common does not model yet. The source remains
+* discriminated so consumers can narrow the known mouse and selection shapes.
+*/
+type OpaqueIncrementalData = {
+  source: Exclude<IncrementalSource, IncrementalSource.MouseInteraction | IncrementalSource.Selection>;
+  [key: string]: unknown;
+};
+type IncrementalSnapshotData = MouseInteractionData | SelectionData | OpaqueIncrementalData;
 type RageClickCustomData = {
   tag: "csr:rageClick";
   payload: {
+    eventId?: string;
     targetId: number;
     clickCount: number;
     durationMs: number;
@@ -74,6 +108,7 @@ type RageClickCustomData = {
 type FormFieldReEditCustomData = {
   tag: "csr:formFieldReEdit";
   payload: {
+    eventId?: string;
     targetId: number;
     editCount: number;
     element?: ElementDescriptor;
@@ -83,6 +118,7 @@ type FormFieldReEditCustomData = {
 type ScrollBackCustomData = {
   tag: "csr:scrollBack";
   payload: {
+    eventId?: string;
     scrollBackPx: number;
     fromY: number;
     toY: number;
@@ -98,6 +134,7 @@ type ElementDescriptor = {
 type ClickCustomData = {
   tag: "csr:click";
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -106,6 +143,7 @@ type ClickCustomData = {
 type InputCustomData = {
   tag: "csr:input";
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -116,6 +154,7 @@ type InputCustomData = {
 type DeadClickCustomData = {
   tag: "csr:deadClick";
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -124,12 +163,14 @@ type DeadClickCustomData = {
 type TabUnfocusCustomData = {
   tag: "csr:tabUnfocus";
   payload: {
+    eventId?: string;
     pathname?: string;
   };
 };
 type TabRefocusCustomData = {
   tag: "csr:tabRefocus";
   payload: {
+    eventId?: string;
     awayDurationMs: number;
     pathname?: string;
   };
@@ -142,7 +183,9 @@ type RouteChangePayload = {
 };
 type RouteChangeCustomData = {
   tag: "csr:routeChange";
-  payload: RouteChangePayload;
+  payload: RouteChangePayload & {
+    eventId?: string;
+  };
 };
 /**
 * Plugin event data emitted by the recorder for tab visibility changes.
@@ -211,18 +254,21 @@ type FlagEvaluationPluginData = {
 type ErrorMessageCustomData = {
   tag: "csr:errorMessage";
   payload: {
+    eventId?: string;
     text: string;
   };
 };
 type DialogOpenedCustomData = {
   tag: "csr:dialogOpened";
   payload: {
+    eventId?: string;
     content: string[];
   };
 };
 type IdleGapCustomData = {
   tag: "csr:idleGap";
   payload: {
+    eventId?: string;
     visibleGapS: number;
     totalGapS: number;
     hiddenS: number;
@@ -232,6 +278,7 @@ type IdleGapCustomData = {
 type AwayGapCustomData = {
   tag: "csr:awayGap";
   payload: {
+    eventId?: string;
     totalGapS: number;
     hiddenS: number;
   };
@@ -239,6 +286,11 @@ type AwayGapCustomData = {
 /**
 * 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.
+*
+* Every payload carries an optional `eventId`: a per-event identity stamped
+* at emission by the analyzer (uuid). It is inert metadata — players ignore
+* it — and exists so downstream review tooling can reference and remove
+* individual generated events without patching untyped data.
 */
 type CustomEventData = ClickCustomData | InputCustomData | RageClickCustomData | FormFieldReEditCustomData | ScrollBackCustomData | DeadClickCustomData | TabUnfocusCustomData | TabRefocusCustomData | RouteChangeCustomData | ErrorMessageCustomData | DialogOpenedCustomData | IdleGapCustomData | AwayGapCustomData;
 /**
@@ -253,7 +305,11 @@ type RecordingEvent = {
   timestamp: number;
   data: CustomEventData;
 } | {
-  type: Exclude<RecordingEventType, RecordingEventType.Custom>;
+  type: RecordingEventType.IncrementalSnapshot;
+  timestamp: number;
+  data: IncrementalSnapshotData;
+} | {
+  type: Exclude<RecordingEventType, RecordingEventType.Custom | RecordingEventType.IncrementalSnapshot>;
   timestamp: number;
   data: unknown;
 };
@@ -274,4 +330,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, 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 };
+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 };

package/dist/index.d.ts

@@ -61,9 +61,43 @@ declare enum MouseInteractions {
   TouchEnd = 9,
   TouchCancel = 10
 }
+/**
+* Incremental mouse-interaction data emitted by rrweb.
+*/
+type MouseInteractionData = {
+  source: IncrementalSource.MouseInteraction;
+  type: MouseInteractions;
+  id: number;
+  x?: number;
+  y?: number;
+  pointerType?: number;
+};
+type SelectionRange = {
+  start: number;
+  startOffset: number;
+  end: number;
+  endOffset: number;
+};
+/**
+* Incremental text-selection data emitted by rrweb.
+*/
+type SelectionData = {
+  source: IncrementalSource.Selection;
+  ranges: SelectionRange[];
+};
+/**
+* Incremental sources that csr-common does not model yet. The source remains
+* discriminated so consumers can narrow the known mouse and selection shapes.
+*/
+type OpaqueIncrementalData = {
+  source: Exclude<IncrementalSource, IncrementalSource.MouseInteraction | IncrementalSource.Selection>;
+  [key: string]: unknown;
+};
+type IncrementalSnapshotData = MouseInteractionData | SelectionData | OpaqueIncrementalData;
 type RageClickCustomData = {
   tag: "csr:rageClick";
   payload: {
+    eventId?: string;
     targetId: number;
     clickCount: number;
     durationMs: number;
@@ -74,6 +108,7 @@ type RageClickCustomData = {
 type FormFieldReEditCustomData = {
   tag: "csr:formFieldReEdit";
   payload: {
+    eventId?: string;
     targetId: number;
     editCount: number;
     element?: ElementDescriptor;
@@ -83,6 +118,7 @@ type FormFieldReEditCustomData = {
 type ScrollBackCustomData = {
   tag: "csr:scrollBack";
   payload: {
+    eventId?: string;
     scrollBackPx: number;
     fromY: number;
     toY: number;
@@ -98,6 +134,7 @@ type ElementDescriptor = {
 type ClickCustomData = {
   tag: "csr:click";
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -106,6 +143,7 @@ type ClickCustomData = {
 type InputCustomData = {
   tag: "csr:input";
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -116,6 +154,7 @@ type InputCustomData = {
 type DeadClickCustomData = {
   tag: "csr:deadClick";
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -124,12 +163,14 @@ type DeadClickCustomData = {
 type TabUnfocusCustomData = {
   tag: "csr:tabUnfocus";
   payload: {
+    eventId?: string;
     pathname?: string;
   };
 };
 type TabRefocusCustomData = {
   tag: "csr:tabRefocus";
   payload: {
+    eventId?: string;
     awayDurationMs: number;
     pathname?: string;
   };
@@ -142,7 +183,9 @@ type RouteChangePayload = {
 };
 type RouteChangeCustomData = {
   tag: "csr:routeChange";
-  payload: RouteChangePayload;
+  payload: RouteChangePayload & {
+    eventId?: string;
+  };
 };
 /**
 * Plugin event data emitted by the recorder for tab visibility changes.
@@ -211,18 +254,21 @@ type FlagEvaluationPluginData = {
 type ErrorMessageCustomData = {
   tag: "csr:errorMessage";
   payload: {
+    eventId?: string;
     text: string;
   };
 };
 type DialogOpenedCustomData = {
   tag: "csr:dialogOpened";
   payload: {
+    eventId?: string;
     content: string[];
   };
 };
 type IdleGapCustomData = {
   tag: "csr:idleGap";
   payload: {
+    eventId?: string;
     visibleGapS: number;
     totalGapS: number;
     hiddenS: number;
@@ -232,6 +278,7 @@ type IdleGapCustomData = {
 type AwayGapCustomData = {
   tag: "csr:awayGap";
   payload: {
+    eventId?: string;
     totalGapS: number;
     hiddenS: number;
   };
@@ -239,6 +286,11 @@ type AwayGapCustomData = {
 /**
 * 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.
+*
+* Every payload carries an optional `eventId`: a per-event identity stamped
+* at emission by the analyzer (uuid). It is inert metadata — players ignore
+* it — and exists so downstream review tooling can reference and remove
+* individual generated events without patching untyped data.
 */
 type CustomEventData = ClickCustomData | InputCustomData | RageClickCustomData | FormFieldReEditCustomData | ScrollBackCustomData | DeadClickCustomData | TabUnfocusCustomData | TabRefocusCustomData | RouteChangeCustomData | ErrorMessageCustomData | DialogOpenedCustomData | IdleGapCustomData | AwayGapCustomData;
 /**
@@ -253,7 +305,11 @@ type RecordingEvent = {
   timestamp: number;
   data: CustomEventData;
 } | {
-  type: Exclude<RecordingEventType, RecordingEventType.Custom>;
+  type: RecordingEventType.IncrementalSnapshot;
+  timestamp: number;
+  data: IncrementalSnapshotData;
+} | {
+  type: Exclude<RecordingEventType, RecordingEventType.Custom | RecordingEventType.IncrementalSnapshot>;
   timestamp: number;
   data: unknown;
 };
@@ -274,4 +330,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, 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 };
+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 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spotify-confidence/csr-common",
   "license": "Apache-2.0",
-  "version": "0.18.3",
+  "version": "0.18.5",
   "repository": {
     "type": "git",
     "url": "https://github.com/spotify/confidence-sdk-js.git",

package/src/events.ts

@@ -62,9 +62,48 @@ export enum MouseInteractions {
   TouchCancel = 10,
 }
 
+/**
+ * Incremental mouse-interaction data emitted by rrweb.
+ */
+export type MouseInteractionData = {
+  source: IncrementalSource.MouseInteraction;
+  type: MouseInteractions;
+  id: number;
+  x?: number;
+  y?: number;
+  pointerType?: number;
+};
+
+export type SelectionRange = {
+  start: number;
+  startOffset: number;
+  end: number;
+  endOffset: number;
+};
+
+/**
+ * Incremental text-selection data emitted by rrweb.
+ */
+export type SelectionData = {
+  source: IncrementalSource.Selection;
+  ranges: SelectionRange[];
+};
+
+/**
+ * Incremental sources that csr-common does not model yet. The source remains
+ * discriminated so consumers can narrow the known mouse and selection shapes.
+ */
+export type OpaqueIncrementalData = {
+  source: Exclude<IncrementalSource, IncrementalSource.MouseInteraction | IncrementalSource.Selection>;
+  [key: string]: unknown;
+};
+
+export type IncrementalSnapshotData = MouseInteractionData | SelectionData | OpaqueIncrementalData;
+
 export type RageClickCustomData = {
   tag: 'csr:rageClick';
   payload: {
+    eventId?: string;
     targetId: number;
     clickCount: number;
     durationMs: number;
@@ -76,6 +115,7 @@ export type RageClickCustomData = {
 export type FormFieldReEditCustomData = {
   tag: 'csr:formFieldReEdit';
   payload: {
+    eventId?: string;
     targetId: number;
     editCount: number;
     element?: ElementDescriptor;
@@ -86,6 +126,7 @@ export type FormFieldReEditCustomData = {
 export type ScrollBackCustomData = {
   tag: 'csr:scrollBack';
   payload: {
+    eventId?: string;
     scrollBackPx: number;
     fromY: number;
     toY: number;
@@ -103,6 +144,7 @@ export type ElementDescriptor = {
 export type ClickCustomData = {
   tag: 'csr:click';
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -112,6 +154,7 @@ export type ClickCustomData = {
 export type InputCustomData = {
   tag: 'csr:input';
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -123,6 +166,7 @@ export type InputCustomData = {
 export type DeadClickCustomData = {
   tag: 'csr:deadClick';
   payload: {
+    eventId?: string;
     targetId: number;
     element?: ElementDescriptor;
     pathname?: string;
@@ -132,6 +176,7 @@ export type DeadClickCustomData = {
 export type TabUnfocusCustomData = {
   tag: 'csr:tabUnfocus';
   payload: {
+    eventId?: string;
     pathname?: string;
   };
 };
@@ -139,6 +184,7 @@ export type TabUnfocusCustomData = {
 export type TabRefocusCustomData = {
   tag: 'csr:tabRefocus';
   payload: {
+    eventId?: string;
     awayDurationMs: number;
     pathname?: string;
   };
@@ -154,7 +200,9 @@ export type RouteChangePayload = {
 
 export type RouteChangeCustomData = {
   tag: 'csr:routeChange';
-  payload: RouteChangePayload;
+  // Intersected rather than added to RouteChangePayload so the plugin-event
+  // shape (RouteChangePluginData) stays free of analyzer identity.
+  payload: RouteChangePayload & { eventId?: string };
 };
 
 /**
@@ -231,6 +279,7 @@ export type FlagEvaluationPluginData = {
 export type ErrorMessageCustomData = {
   tag: 'csr:errorMessage';
   payload: {
+    eventId?: string;
     text: string;
   };
 };
@@ -238,6 +287,7 @@ export type ErrorMessageCustomData = {
 export type DialogOpenedCustomData = {
   tag: 'csr:dialogOpened';
   payload: {
+    eventId?: string;
     content: string[];
   };
 };
@@ -245,6 +295,7 @@ export type DialogOpenedCustomData = {
 export type IdleGapCustomData = {
   tag: 'csr:idleGap';
   payload: {
+    eventId?: string;
     visibleGapS: number;
     totalGapS: number;
     hiddenS: number;
@@ -255,6 +306,7 @@ export type IdleGapCustomData = {
 export type AwayGapCustomData = {
   tag: 'csr:awayGap';
   payload: {
+    eventId?: string;
     totalGapS: number;
     hiddenS: number;
   };
@@ -263,6 +315,11 @@ export type AwayGapCustomData = {
 /**
  * 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.
+ *
+ * Every payload carries an optional `eventId`: a per-event identity stamped
+ * at emission by the analyzer (uuid). It is inert metadata — players ignore
+ * it — and exists so downstream review tooling can reference and remove
+ * individual generated events without patching untyped data.
  */
 export type CustomEventData =
   | ClickCustomData
@@ -293,7 +350,12 @@ export type RecordingEvent =
       data: CustomEventData;
     }
   | {
-      type: Exclude<RecordingEventType, RecordingEventType.Custom>;
+      type: RecordingEventType.IncrementalSnapshot;
+      timestamp: number;
+      data: IncrementalSnapshotData;
+    }
+  | {
+      type: Exclude<RecordingEventType, RecordingEventType.Custom | RecordingEventType.IncrementalSnapshot>;
       timestamp: number;
       data: unknown;
     };

package/src/index.ts

@@ -4,6 +4,11 @@ export {
   IncrementalSource,
   MouseInteractions,
   type RecordingEvent,
+  type IncrementalSnapshotData,
+  type MouseInteractionData,
+  type OpaqueIncrementalData,
+  type SelectionData,
+  type SelectionRange,
   type CustomEventData,
   type ClickCustomData,
   type InputCustomData,