@spotify-confidence/csr-common 0.18.8 → 0.18.9

package/src/events.ts

@@ -23,6 +23,35 @@ export enum RecordingEventType {
   Plugin = 6,
 }
 
+export const RecordingCustomEventTag = {
+  RageClick: 'csr:rageClick',
+  FormFieldReEdit: 'csr:formFieldReEdit',
+  ScrollBack: 'csr:scrollBack',
+  Click: 'csr:click',
+  Input: 'csr:input',
+  DeadClick: 'csr:deadClick',
+  TabUnfocus: 'csr:tabUnfocus',
+  TabRefocus: 'csr:tabRefocus',
+  RouteChange: 'csr:routeChange',
+  ErrorMessage: 'csr:errorMessage',
+  DialogOpened: 'csr:dialogOpened',
+  IdleGap: 'csr:idleGap',
+  AwayGap: 'csr:awayGap',
+} as const;
+
+export const RecordingPluginName = {
+  BlockedElementLabels: 'csr/blocked-element-labels@1',
+  Clipboard: 'csr/clipboard@1',
+  ClickModifiers: 'csr/click-modifiers@1',
+  TabVisibility: 'csr:tabVisibility',
+  ConsoleLog: 'rrweb/console@1',
+  NetworkRequest: 'csr:networkRequest',
+  RouteChange: 'csr:routeChange',
+  Tag: 'csr:tag',
+  Measure: 'csr:measure',
+  FlagEvaluation: 'csr:flagEvaluation',
+} as const;
+
 /**
  * Incremental snapshot sub-types.
  */
@@ -107,7 +136,7 @@ export type OpaqueIncrementalData = {
 export type IncrementalSnapshotData = MouseInteractionData | SelectionData | OpaqueIncrementalData;
 
 export type RageClickCustomData = {
-  tag: 'csr:rageClick';
+  tag: typeof RecordingCustomEventTag.RageClick;
   payload: {
     eventId?: string;
     targetId: number;
@@ -119,7 +148,7 @@ export type RageClickCustomData = {
 };
 
 export type FormFieldReEditCustomData = {
-  tag: 'csr:formFieldReEdit';
+  tag: typeof RecordingCustomEventTag.FormFieldReEdit;
   payload: {
     eventId?: string;
     targetId: number;
@@ -130,7 +159,7 @@ export type FormFieldReEditCustomData = {
 };
 
 export type ScrollBackCustomData = {
-  tag: 'csr:scrollBack';
+  tag: typeof RecordingCustomEventTag.ScrollBack;
   payload: {
     eventId?: string;
     scrollBackPx: number;
@@ -148,7 +177,7 @@ export type ElementDescriptor = {
 };
 
 export type ClickCustomData = {
-  tag: 'csr:click';
+  tag: typeof RecordingCustomEventTag.Click;
   payload: {
     eventId?: string;
     targetId: number;
@@ -163,7 +192,7 @@ export type ClickCustomData = {
 };
 
 export type InputCustomData = {
-  tag: 'csr:input';
+  tag: typeof RecordingCustomEventTag.Input;
   payload: {
     eventId?: string;
     targetId: number;
@@ -178,7 +207,7 @@ export type InputCustomData = {
 export type ClipboardAction = 'copy' | 'cut' | 'paste';
 
 export type ClipboardPluginData = {
-  plugin: 'csr/clipboard@1';
+  plugin: typeof RecordingPluginName.Clipboard;
   payload: {
     action: ClipboardAction;
     targetId: number;
@@ -186,7 +215,7 @@ export type ClipboardPluginData = {
 };
 
 export type DeadClickCustomData = {
-  tag: 'csr:deadClick';
+  tag: typeof RecordingCustomEventTag.DeadClick;
   payload: {
     eventId?: string;
     targetId: number;
@@ -196,7 +225,7 @@ export type DeadClickCustomData = {
 };
 
 export type TabUnfocusCustomData = {
-  tag: 'csr:tabUnfocus';
+  tag: typeof RecordingCustomEventTag.TabUnfocus;
   payload: {
     eventId?: string;
     pathname?: string;
@@ -204,7 +233,7 @@ export type TabUnfocusCustomData = {
 };
 
 export type TabRefocusCustomData = {
-  tag: 'csr:tabRefocus';
+  tag: typeof RecordingCustomEventTag.TabRefocus;
   payload: {
     eventId?: string;
     awayDurationMs: number;
@@ -221,7 +250,7 @@ export type RouteChangePayload = {
 };
 
 export type RouteChangeCustomData = {
-  tag: 'csr:routeChange';
+  tag: typeof RecordingCustomEventTag.RouteChange;
   // Intersected rather than added to RouteChangePayload so the plugin-event
   // shape (RouteChangePluginData) stays free of analyzer identity.
   payload: RouteChangePayload & { eventId?: string };
@@ -231,7 +260,7 @@ export type RouteChangeCustomData = {
  * Plugin event data emitted by the recorder for tab visibility changes.
  */
 export type TabVisibilityPluginData = {
-  plugin: 'csr:tabVisibility';
+  plugin: typeof RecordingPluginName.TabVisibility;
   payload: { hidden: boolean };
 };
 
@@ -242,7 +271,7 @@ export type ConsoleLogLevel = 'log' | 'warn' | 'error' | 'debug' | 'info';
  * Shape matches `@rrweb/rrweb-plugin-console-record` LogData.
  */
 export type ConsoleLogPluginData = {
-  plugin: 'rrweb/console@1';
+  plugin: typeof RecordingPluginName.ConsoleLog;
   payload: {
     level: ConsoleLogLevel;
     payload: string[];
@@ -260,7 +289,7 @@ export type GraphQLRequestMetadata = {
  * Plugin event data emitted by the recorder for network requests.
  */
 export type NetworkRequestPluginData = {
-  plugin: 'csr:networkRequest';
+  plugin: typeof RecordingPluginName.NetworkRequest;
   payload: {
     initiator: NetworkRequestInitiator;
     method: string;
@@ -274,12 +303,12 @@ export type NetworkRequestPluginData = {
 };
 
 export type RouteChangePluginData = {
-  plugin: 'csr:routeChange';
+  plugin: typeof RecordingPluginName.RouteChange;
   payload: RouteChangePayload;
 };
 
 export type TagPluginData = {
-  plugin: 'csr:tag';
+  plugin: typeof RecordingPluginName.Tag;
   payload: {
     key: string;
     value?: string;
@@ -287,7 +316,7 @@ export type TagPluginData = {
 };
 
 export type MeasurePluginData = {
-  plugin: 'csr:measure';
+  plugin: typeof RecordingPluginName.Measure;
   payload: {
     key: string;
     value?: number;
@@ -295,7 +324,7 @@ export type MeasurePluginData = {
 };
 
 export type FlagEvaluationPluginData = {
-  plugin: 'csr:flagEvaluation';
+  plugin: typeof RecordingPluginName.FlagEvaluation;
   payload: {
     flagKey: string;
     variant: string;
@@ -303,8 +332,18 @@ export type FlagEvaluationPluginData = {
   };
 };
 
+export type PluginEventData =
+  | ClipboardPluginData
+  | TabVisibilityPluginData
+  | ConsoleLogPluginData
+  | NetworkRequestPluginData
+  | RouteChangePluginData
+  | TagPluginData
+  | MeasurePluginData
+  | FlagEvaluationPluginData;
+
 export type ErrorMessageCustomData = {
-  tag: 'csr:errorMessage';
+  tag: typeof RecordingCustomEventTag.ErrorMessage;
   payload: {
     eventId?: string;
     text: string;
@@ -312,7 +351,7 @@ export type ErrorMessageCustomData = {
 };
 
 export type DialogOpenedCustomData = {
-  tag: 'csr:dialogOpened';
+  tag: typeof RecordingCustomEventTag.DialogOpened;
   payload: {
     eventId?: string;
     content: string[];
@@ -320,7 +359,7 @@ export type DialogOpenedCustomData = {
 };
 
 export type IdleGapCustomData = {
-  tag: 'csr:idleGap';
+  tag: typeof RecordingCustomEventTag.IdleGap;
   payload: {
     eventId?: string;
     visibleGapS: number;
@@ -331,7 +370,7 @@ export type IdleGapCustomData = {
 };
 
 export type AwayGapCustomData = {
-  tag: 'csr:awayGap';
+  tag: typeof RecordingCustomEventTag.AwayGap;
   payload: {
     eventId?: string;
     totalGapS: number;
@@ -382,7 +421,15 @@ export type RecordingEvent =
       data: IncrementalSnapshotData;
     }
   | {
-      type: Exclude<RecordingEventType, RecordingEventType.Custom | RecordingEventType.IncrementalSnapshot>;
+      type: RecordingEventType.Plugin;
+      timestamp: number;
+      data: PluginEventData;
+    }
+  | {
+      type: Exclude<
+        RecordingEventType,
+        RecordingEventType.Custom | RecordingEventType.IncrementalSnapshot | RecordingEventType.Plugin
+      >;
       timestamp: number;
       data: unknown;
     };

package/src/index.ts

@@ -1,9 +1,12 @@
 export {
   SerializedNodeType,
   RecordingEventType,
+  RecordingCustomEventTag,
+  RecordingPluginName,
   IncrementalSource,
   MouseInteractions,
   type RecordingEvent,
+  type PluginEventData,
   type IncrementalSnapshotData,
   type MouseInteractionData,
   type OpaqueIncrementalData,
@@ -42,6 +45,10 @@ export {
 
 export { stripUrl } from './url';
 
+export { RecordingMetricKey } from './metrics';
+
+export { isSessionActivityEvent, isUserInteractionEvent, isUserInteractionMetric } from './session-activity';
+
 export {
   MAX_KEY_LENGTH,
   MAX_TAG_VALUE_LENGTH,

package/src/metrics.ts

@@ -0,0 +1,15 @@
+export const RecordingMetricKey = {
+  Click: 'clicks',
+  Input: 'inputs',
+  RageClick: 'rageClicks',
+  DeadClick: 'deadClicks',
+  ScrollBack: 'scrollBacks',
+  TabUnfocus: 'tabUnfocuses',
+  ErrorMessage: 'errorMessages',
+  FailedNetworkRequest: 'networkRequestsFailed',
+  NetworkRequest: 'networkRequests',
+  ConsoleLog: 'consoleLogs',
+  ConsoleWarning: 'consoleWarnings',
+  ConsoleError: 'consoleErrors',
+  RouteChange: 'routeChanges',
+} as const;

package/src/session-activity.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+import { IncrementalSource, RecordingCustomEventTag, RecordingEventType, RecordingPluginName } from './events';
+import { RecordingMetricKey } from './metrics';
+import { isSessionActivityEvent, isUserInteractionEvent, isUserInteractionMetric } from './session-activity';
+
+describe('session activity', () => {
+  it.each([
+    {
+      type: RecordingEventType.IncrementalSnapshot,
+      data: { source: IncrementalSource.MouseMove },
+    },
+    {
+      type: RecordingEventType.IncrementalSnapshot,
+      data: { source: IncrementalSource.MouseInteraction },
+    },
+    {
+      type: RecordingEventType.Custom,
+      data: { tag: RecordingCustomEventTag.Input },
+    },
+    {
+      type: RecordingEventType.Plugin,
+      data: { plugin: RecordingPluginName.RouteChange },
+    },
+    {
+      type: RecordingEventType.Custom,
+      data: { tag: RecordingCustomEventTag.TabUnfocus },
+    },
+  ])('identifies user interaction events', event => {
+    expect(isUserInteractionEvent(event)).toBe(true);
+  });
+
+  it.each([
+    {
+      type: RecordingEventType.IncrementalSnapshot,
+      data: { source: IncrementalSource.Mutation },
+    },
+    {
+      type: RecordingEventType.Plugin,
+      data: { plugin: RecordingPluginName.NetworkRequest },
+    },
+    null,
+    {},
+  ])('ignores passive and malformed events', event => {
+    expect(isUserInteractionEvent(event)).toBe(false);
+  });
+
+  it('treats page metadata as session activity without treating it as an interaction', () => {
+    const event = { type: RecordingEventType.Meta, data: {} };
+
+    expect(isUserInteractionEvent(event)).toBe(false);
+    expect(isSessionActivityEvent(event)).toBe(true);
+  });
+
+  it.each([
+    RecordingMetricKey.Click,
+    RecordingMetricKey.Input,
+    RecordingMetricKey.RageClick,
+    RecordingMetricKey.DeadClick,
+    RecordingMetricKey.ScrollBack,
+    RecordingMetricKey.TabUnfocus,
+    RecordingMetricKey.RouteChange,
+  ])('identifies user interaction metrics', metricKey => {
+    expect(isUserInteractionMetric(metricKey)).toBe(true);
+  });
+
+  it.each([RecordingMetricKey.NetworkRequest, RecordingMetricKey.ConsoleError, 'unknownMetric'])(
+    'ignores passive metrics',
+    metricKey => {
+      expect(isUserInteractionMetric(metricKey)).toBe(false);
+    },
+  );
+});

package/src/session-activity.ts

@@ -0,0 +1,64 @@
+import { IncrementalSource, RecordingCustomEventTag, RecordingEventType, RecordingPluginName } from './events';
+import { RecordingMetricKey } from './metrics';
+
+const USER_INTERACTION_SOURCES = new Set<number>([
+  IncrementalSource.MouseMove,
+  IncrementalSource.MouseInteraction,
+  IncrementalSource.Scroll,
+  IncrementalSource.Input,
+  IncrementalSource.TouchMove,
+  IncrementalSource.MediaInteraction,
+  IncrementalSource.Drag,
+  IncrementalSource.Selection,
+]);
+
+const USER_INTERACTION_TAGS = new Set<string>([
+  RecordingCustomEventTag.Click,
+  RecordingCustomEventTag.Input,
+  RecordingCustomEventTag.RageClick,
+  RecordingCustomEventTag.DeadClick,
+  RecordingCustomEventTag.ScrollBack,
+  RecordingCustomEventTag.TabUnfocus,
+  RecordingCustomEventTag.TabRefocus,
+  RecordingCustomEventTag.FormFieldReEdit,
+  RecordingCustomEventTag.RouteChange,
+]);
+
+const USER_INTERACTION_PLUGINS = new Set<string>([RecordingPluginName.RouteChange]);
+
+const USER_INTERACTION_METRIC_KEYS = new Set<string>([
+  RecordingMetricKey.Click,
+  RecordingMetricKey.Input,
+  RecordingMetricKey.RageClick,
+  RecordingMetricKey.DeadClick,
+  RecordingMetricKey.ScrollBack,
+  RecordingMetricKey.TabUnfocus,
+  RecordingMetricKey.RouteChange,
+]);
+
+const isObject = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null;
+
+export const isUserInteractionEvent = (event: unknown): boolean => {
+  if (!isObject(event) || !isObject(event.data)) {
+    return false;
+  }
+
+  if (event.type === RecordingEventType.IncrementalSnapshot) {
+    return typeof event.data.source === 'number' && USER_INTERACTION_SOURCES.has(event.data.source);
+  }
+
+  if (event.type === RecordingEventType.Custom) {
+    return typeof event.data.tag === 'string' && USER_INTERACTION_TAGS.has(event.data.tag);
+  }
+
+  return (
+    event.type === RecordingEventType.Plugin &&
+    typeof event.data.plugin === 'string' &&
+    USER_INTERACTION_PLUGINS.has(event.data.plugin)
+  );
+};
+
+export const isUserInteractionMetric = (metricKey: string): boolean => USER_INTERACTION_METRIC_KEYS.has(metricKey);
+
+export const isSessionActivityEvent = (event: unknown): boolean =>
+  (isObject(event) && event.type === RecordingEventType.Meta) || isUserInteractionEvent(event);

package/src/uploader/create-uploader.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { IncrementalSource, RecordingEventType, RecordingPluginName } from '../events';
 import type { CreateUploaderOptions } from './types';
 
 vi.mock('./worker/worker-script', () => ({
@@ -89,6 +90,7 @@ describe('createUploader', () => {
 
   afterEach(() => {
     vi.restoreAllMocks();
+    vi.unstubAllGlobals();
     blobUrls.length = 0;
     delete (globalThis as Record<string, unknown>).SharedWorker;
   });
@@ -323,4 +325,74 @@ describe('createUploader', () => {
       );
     });
   });
+
+  it('marks active and passive frames for the backend inactivity timeout', async () => {
+    const messages: unknown[] = [];
+    vi.stubGlobal('window', {
+      addEventListener() {},
+      devicePixelRatio: 1,
+      innerHeight: 800,
+      innerWidth: 1200,
+      location: { origin: 'https://example.com', pathname: '/' },
+      screen: { height: 800, width: 1200 },
+    });
+    vi.stubGlobal('document', {
+      addEventListener() {},
+      referrer: '',
+      visibilityState: 'visible',
+    });
+    vi.stubGlobal('navigator', {
+      language: 'en',
+      userAgent: 'test',
+    });
+    vi.stubGlobal(
+      'Worker',
+      class {
+        onerror: ((event: Event) => void) | null = null;
+        onmessage: ((event: MessageEvent) => void) | null = null;
+
+        postMessage(message: unknown) {
+          messages.push(message);
+          if (typeof message === 'object' && message !== null && 'type' in message && message.type === 'hello') {
+            queueMicrotask(() =>
+              this.onmessage?.(
+                new MessageEvent('message', {
+                  data: {
+                    type: 'welcome',
+                    result: { sessionId: 'sessions/test', sessionToken: 'token' },
+                  },
+                }),
+              ),
+            );
+          }
+        }
+      },
+    );
+    vi.stubGlobal('SharedWorker', undefined);
+
+    const createUploader = await loadCreateUploader();
+    const uploader = await createUploader({ ...DEFAULTS, workerMode: 'dedicated' });
+
+    uploader?.({
+      type: RecordingEventType.Plugin,
+      data: { plugin: RecordingPluginName.NetworkRequest },
+    });
+    uploader?.({
+      type: RecordingEventType.IncrementalSnapshot,
+      data: { source: IncrementalSource.MouseInteraction },
+    });
+
+    expect(messages).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          type: 'frame',
+          frame: expect.objectContaining({ userActivity: false }),
+        }),
+        expect.objectContaining({
+          type: 'frame',
+          frame: expect.objectContaining({ userActivity: true }),
+        }),
+      ]),
+    );
+  });
 });

package/src/uploader/create-uploader.ts

@@ -1,5 +1,6 @@
 import type { CreateUploaderOptions, Frame, Uploader } from './types';
 import { ClientContext, collectUserAgentContext } from './client-context';
+import { isSessionActivityEvent } from '../session-activity';
 import { workerScript } from './worker/worker-script';
 
 const STORAGE_TAB_ID = 'csr:tabId';
@@ -213,6 +214,7 @@ export async function createUploader(opts: CreateUploaderOptions): Promise<Uploa
       tabId: effectiveTabId,
       eventCounter: counter,
       data: event,
+      userActivity: isSessionActivityEvent(event),
       ...(nextAdoptionMeta ?? {}),
     };
     counter += 1;

package/src/uploader/types.ts

@@ -94,6 +94,8 @@ export interface Frame {
   eventCounter: number;
   /** Opaque payload from the recorder. */
   data: unknown;
+  /** Whether the frame should refresh the backend's session inactivity timeout. */
+  userActivity?: boolean;
   /** Set only on the first frame emitted after the tab was adopted into a different session. */
   adoptedFromSessionId?: string;
   /** Epoch millis of the adoption event. */