@spotify-confidence/csr-recorder 0.0.0 → 0.17.2

package/package.json

@@ -1 +1,49 @@
-{"name":"@spotify-confidence/csr-recorder","version":"0.0.0","description":"Placeholder"}
+{
+  "name": "@spotify-confidence/csr-recorder",
+  "license": "Apache-2.0",
+  "version": "0.17.2",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spotify/confidence-sdk-js.git",
+    "directory": "csr/csr-recorder"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "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"
+      }
+    }
+  },
+  "dependencies": {
+    "@rrweb/rrweb-plugin-console-record": "^2.0.0-alpha.20",
+    "@spotify-confidence/csr-common": "^0.17.2",
+    "rrweb": "^2.0.0-alpha.20"
+  },
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  }
+}

package/src/engine/index.ts

@@ -0,0 +1,11 @@
+import { RecordingEvent } from '@spotify-confidence/csr-common';
+import { RecordingConfig } from '../types';
+
+/**
+ * Abstraction over the underlying recording library (rrweb, custom, etc.).
+ * The Recorder class depends on this interface — never on rrweb directly.
+ */
+export interface RecordingEngine {
+  start(config: RecordingConfig, onEvent: (event: RecordingEvent) => void): void;
+  stop(): void;
+}

package/src/engine/rrweb-engine.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { RrwebEngine } from './rrweb-engine';
+
+const recordSpy = vi.fn().mockReturnValue(() => {});
+
+vi.mock('rrweb', () => ({
+  record: (opts: unknown) => recordSpy(opts),
+}));
+
+describe('RrwebEngine', () => {
+  beforeEach(() => recordSpy.mockClear());
+
+  it('defaults maskAllInputs=true when maskInputs is omitted', () => {
+    new RrwebEngine().start({}, () => {});
+    expect(recordSpy.mock.calls[0][0].maskAllInputs).toBe(true);
+  });
+
+  it('forwards maskInputs=false to maskAllInputs', () => {
+    new RrwebEngine().start({ maskInputs: false }, () => {});
+    expect(recordSpy.mock.calls[0][0].maskAllInputs).toBe(false);
+  });
+
+  it('joins maskSelectors with `,` for maskTextSelector', () => {
+    new RrwebEngine().start({ maskSelectors: ['.private', '[data-pii]'] }, () => {});
+    expect(recordSpy.mock.calls[0][0].maskTextSelector).toBe('.private,[data-pii]');
+  });
+
+  it('omits maskTextSelector when maskSelectors is explicitly empty', () => {
+    new RrwebEngine().start({ maskSelectors: [] }, () => {});
+    expect(recordSpy.mock.calls[0][0]).not.toHaveProperty('maskTextSelector');
+  });
+
+  it('applies default maskTextSelector when maskSelectors is absent', () => {
+    new RrwebEngine().start({}, () => {});
+    expect(recordSpy.mock.calls[0][0].maskTextSelector).toBe('[data-csr-mask]');
+  });
+
+  it('joins blockSelectors with `,` for blockSelector', () => {
+    new RrwebEngine().start({ blockSelectors: ['video', '.third-party'] }, () => {});
+    expect(recordSpy.mock.calls[0][0].blockSelector).toBe('video,.third-party');
+  });
+
+  it('omits blockSelector when blockSelectors is explicitly empty', () => {
+    new RrwebEngine().start({ blockSelectors: [] }, () => {});
+    expect(recordSpy.mock.calls[0][0]).not.toHaveProperty('blockSelector');
+  });
+
+  it('applies default blockSelector when blockSelectors is absent', () => {
+    new RrwebEngine().start({}, () => {});
+    expect(recordSpy.mock.calls[0][0].blockSelector).toBe('[data-csr-block]');
+  });
+
+  it('throttles mousemove to 100ms and records only last input value', () => {
+    new RrwebEngine().start({}, () => {});
+    const opts = recordSpy.mock.calls[0][0];
+    expect(opts.sampling).toEqual({ mousemove: 100, input: 'last' });
+  });
+
+  it('enables slimDOMOptions to strip head noise', () => {
+    new RrwebEngine().start({}, () => {});
+    expect(recordSpy.mock.calls[0][0].slimDOMOptions).toBe('all');
+  });
+});

package/src/engine/rrweb-engine.ts

@@ -0,0 +1,49 @@
+import { RecordingEvent, type ConsoleLogLevel } from '@spotify-confidence/csr-common';
+import { RecordingConfig, DEFAULT_MASK_SELECTORS, DEFAULT_BLOCK_SELECTORS } from '../types';
+import { RecordingEngine } from './index';
+import { record } from 'rrweb';
+import { getRecordConsolePlugin } from '@rrweb/rrweb-plugin-console-record';
+
+const ALL_CONSOLE_LEVELS: ConsoleLogLevel[] = ['log', 'warn', 'error', 'debug', 'info'];
+
+/**
+ * rrweb adapter — bundles rrweb so consumers don't take a peer-dep on it.
+ */
+export class RrwebEngine implements RecordingEngine {
+  private stopFn: (() => void) | null = null;
+
+  start(config: RecordingConfig, onEvent: (event: RecordingEvent) => void): void {
+    const maskSelectors = config.maskSelectors ?? DEFAULT_MASK_SELECTORS;
+    const blockSelectors = config.blockSelectors ?? DEFAULT_BLOCK_SELECTORS;
+
+    const plugins = [];
+    const { captureConsoleLogs } = config;
+    if (captureConsoleLogs) {
+      const levels = captureConsoleLogs === true ? ALL_CONSOLE_LEVELS : captureConsoleLogs.levels;
+      if (levels.length > 0) {
+        plugins.push(getRecordConsolePlugin({ level: levels }));
+      }
+    }
+
+    this.stopFn =
+      record({
+        emit: event => {
+          onEvent(event as unknown as RecordingEvent);
+        },
+        maskAllInputs: config.maskInputs ?? true,
+        ...(maskSelectors.length ? { maskTextSelector: maskSelectors.join(',') } : {}),
+        ...(blockSelectors.length ? { blockSelector: blockSelectors.join(',') } : {}),
+        ...(plugins.length ? { plugins } : {}),
+        sampling: {
+          mousemove: 100,
+          input: 'last',
+        },
+        slimDOMOptions: 'all',
+      }) ?? null;
+  }
+
+  stop(): void {
+    this.stopFn?.();
+    this.stopFn = null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { Recorder } from './recorder';
+export { type RecordingEngine } from './engine';
+export { RrwebEngine } from './engine/rrweb-engine';
+export {
+  type RecorderOptions,
+  type RecordingConfig,
+  RecorderState,
+  DEFAULT_MASK_SELECTORS,
+  DEFAULT_BLOCK_SELECTORS,
+} from './types';
+export { record } from './start-recording';

package/src/recorder-routing.test.ts

@@ -0,0 +1,162 @@
+// @vitest-environment happy-dom
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { RecordingEvent, RecordingEventType, type RouteChangePluginData } from '@spotify-confidence/csr-common';
+import { Recorder } from './recorder';
+import { RecordingEngine } from './engine';
+
+class MockEngine implements RecordingEngine {
+  private onEvent: ((event: RecordingEvent) => void) | null = null;
+  startCalled = false;
+  stopCalled = false;
+
+  start(_config: unknown, onEvent: (event: RecordingEvent) => void): void {
+    this.startCalled = true;
+    this.onEvent = onEvent;
+  }
+
+  stop(): void {
+    this.stopCalled = true;
+    this.onEvent = null;
+  }
+
+  emit(event: RecordingEvent): void {
+    this.onEvent?.(event);
+  }
+}
+
+function routeChangeEvents(onEvent: ReturnType<typeof vi.fn>) {
+  return (onEvent.mock.calls as [RecordingEvent][])
+    .map(([e]) => e)
+    .filter(e => e.type === RecordingEventType.Plugin && (e.data as RouteChangePluginData).plugin === 'csr:routeChange')
+    .map(e => (e.data as RouteChangePluginData).payload);
+}
+
+describe('Recorder route change capture', () => {
+  let originalPushState: typeof history.pushState;
+  let originalReplaceState: typeof history.replaceState;
+
+  beforeEach(() => {
+    originalPushState = history.pushState;
+    originalReplaceState = history.replaceState;
+  });
+
+  afterEach(() => {
+    history.pushState = originalPushState;
+    history.replaceState = originalReplaceState;
+  });
+
+  it('patches history by default', () => {
+    const engine = new MockEngine();
+    const recorder = new Recorder({ engine, onEvent: vi.fn() });
+    recorder.start();
+    expect(history.pushState).not.toBe(originalPushState);
+    recorder.stop();
+  });
+
+  it('does not patch history when captureRouteChanges is false', () => {
+    const engine = new MockEngine();
+    const recorder = new Recorder({ engine, onEvent: vi.fn() });
+    recorder.start({ captureRouteChanges: false });
+    expect(history.pushState).toBe(originalPushState);
+    recorder.stop();
+  });
+
+  it('restores history on stop', () => {
+    const engine = new MockEngine();
+    const recorder = new Recorder({ engine, onEvent: vi.fn() });
+    recorder.start();
+    recorder.stop();
+    expect(history.pushState).toBe(originalPushState);
+    expect(history.replaceState).toBe(originalReplaceState);
+  });
+
+  it('emits a Plugin event for pushState', () => {
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start();
+
+    history.pushState({}, '', '/new-page');
+
+    const events = routeChangeEvents(onEvent);
+    expect(events).toHaveLength(1);
+    expect(events[0].to).toBe('/new-page');
+    expect(events[0].trigger).toBe('pushState');
+
+    recorder.stop();
+  });
+
+  it('emits a Plugin event for replaceState', () => {
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start();
+
+    history.replaceState({}, '', '/replaced');
+
+    const events = routeChangeEvents(onEvent);
+    expect(events).toHaveLength(1);
+    expect(events[0].to).toBe('/replaced');
+    expect(events[0].trigger).toBe('replaceState');
+
+    recorder.stop();
+  });
+
+  it('does not emit when URL is unchanged', () => {
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start();
+
+    const currentPath = window.location.pathname;
+    history.replaceState({}, '', currentPath);
+
+    const events = routeChangeEvents(onEvent);
+    expect(events).toHaveLength(0);
+
+    recorder.stop();
+  });
+
+  it('emits for popstate events', () => {
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start();
+
+    history.pushState({}, '', '/page-a');
+    history.pushState({}, '', '/page-b');
+
+    const prePopEvents = routeChangeEvents(onEvent);
+    expect(prePopEvents).toHaveLength(2);
+
+    history.back();
+    // happy-dom fires popstate synchronously on history.back()
+    window.dispatchEvent(new PopStateEvent('popstate'));
+
+    const allEvents = routeChangeEvents(onEvent);
+    const popstateEvents = allEvents.filter(e => e.trigger === 'popstate');
+    expect(popstateEvents.length).toBeGreaterThanOrEqual(1);
+
+    recorder.stop();
+  });
+
+  it('removes popstate listener on stop', () => {
+    const addSpy = vi.spyOn(window, 'addEventListener');
+    const removeSpy = vi.spyOn(window, 'removeEventListener');
+
+    const engine = new MockEngine();
+    const recorder = new Recorder({ engine, onEvent: vi.fn() });
+    recorder.start();
+
+    const popstateAdds = addSpy.mock.calls.filter(([t]) => t === 'popstate');
+    expect(popstateAdds.length).toBe(1);
+
+    recorder.stop();
+
+    const popstateRemoves = removeSpy.mock.calls.filter(([t]) => t === 'popstate');
+    expect(popstateRemoves.length).toBe(1);
+
+    addSpy.mockRestore();
+    removeSpy.mockRestore();
+  });
+});

package/src/recorder.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { RecordingEvent, RecordingEventType, type NetworkRequestPluginData } from '@spotify-confidence/csr-common';
+import { Recorder } from './recorder';
+import { RecordingEngine } from './engine';
+import { RecorderState } from './types';
+
+function makeEvent(timestamp: number): RecordingEvent {
+  return { type: RecordingEventType.Meta, timestamp, data: {} };
+}
+
+class MockEngine implements RecordingEngine {
+  private onEvent: ((event: RecordingEvent) => void) | null = null;
+  startCalled = false;
+  stopCalled = false;
+
+  start(_config: unknown, onEvent: (event: RecordingEvent) => void): void {
+    this.startCalled = true;
+    this.onEvent = onEvent;
+  }
+
+  stop(): void {
+    this.stopCalled = true;
+    this.onEvent = null;
+  }
+
+  emit(event: RecordingEvent): void {
+    this.onEvent?.(event);
+  }
+}
+
+describe('Recorder', () => {
+  it('starts in Idle state', () => {
+    const engine = new MockEngine();
+    const recorder = new Recorder({ engine, onEvent: vi.fn() });
+    expect(recorder.currentState).toBe(RecorderState.Idle);
+  });
+
+  it('transitions to Recording on start', () => {
+    const engine = new MockEngine();
+    const recorder = new Recorder({ engine, onEvent: vi.fn() });
+    recorder.start();
+    expect(recorder.currentState).toBe(RecorderState.Recording);
+    expect(engine.startCalled).toBe(true);
+  });
+
+  it('transitions to Stopped on stop', () => {
+    const engine = new MockEngine();
+    const recorder = new Recorder({ engine, onEvent: vi.fn() });
+    recorder.start();
+    recorder.stop();
+    expect(recorder.currentState).toBe(RecorderState.Stopped);
+    expect(engine.stopCalled).toBe(true);
+  });
+
+  it('ignores duplicate start calls', () => {
+    const engine = new MockEngine();
+    const recorder = new Recorder({ engine, onEvent: vi.fn() });
+    recorder.start();
+    recorder.start();
+    expect(recorder.currentState).toBe(RecorderState.Recording);
+  });
+
+  it('ignores stop when not recording', () => {
+    const engine = new MockEngine();
+    const recorder = new Recorder({ engine, onEvent: vi.fn() });
+    recorder.stop();
+    expect(recorder.currentState).toBe(RecorderState.Idle);
+    expect(engine.stopCalled).toBe(false);
+  });
+
+  it('passes each event to the onEvent callback', () => {
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start();
+
+    engine.emit(makeEvent(1));
+    engine.emit(makeEvent(2));
+
+    expect(onEvent).toHaveBeenCalledTimes(2);
+    expect(onEvent).toHaveBeenNthCalledWith(1, makeEvent(1));
+    expect(onEvent).toHaveBeenNthCalledWith(2, makeEvent(2));
+  });
+});
+
+describe('Recorder network request capture', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('does not patch fetch by default', () => {
+    const engine = new MockEngine();
+    const recorder = new Recorder({ engine, onEvent: vi.fn() });
+    recorder.start();
+    expect(globalThis.fetch).toBe(originalFetch);
+    recorder.stop();
+  });
+
+  it('patches fetch when captureNetworkRequests is true', () => {
+    const engine = new MockEngine();
+    const recorder = new Recorder({ engine, onEvent: vi.fn() });
+    recorder.start({ captureNetworkRequests: true });
+    expect(globalThis.fetch).not.toBe(originalFetch);
+    recorder.stop();
+  });
+
+  it('restores fetch on stop', () => {
+    const engine = new MockEngine();
+    const recorder = new Recorder({ engine, onEvent: vi.fn() });
+    recorder.start({ captureNetworkRequests: true });
+    recorder.stop();
+    expect(globalThis.fetch).toBe(originalFetch);
+  });
+
+  it('emits a Plugin event for a successful fetch', async () => {
+    const mockResponse = new Response('ok', {
+      status: 200,
+      headers: { 'content-length': '2' },
+    });
+    globalThis.fetch = vi.fn().mockResolvedValue(mockResponse);
+
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start({ captureNetworkRequests: true });
+
+    await globalThis.fetch('https://api.example.com/data');
+
+    const pluginEvents = onEvent.mock.calls
+      .map(([e]: [RecordingEvent]) => e)
+      .filter(e => e.type === RecordingEventType.Plugin);
+    expect(pluginEvents).toHaveLength(1);
+    const data = pluginEvents[0].data as NetworkRequestPluginData;
+    expect(data.plugin).toBe('csr:networkRequest');
+    expect(data.payload.initiator).toBe('fetch');
+    expect(data.payload.method).toBe('GET');
+    expect(data.payload.url).toBe('https://api.example.com/data');
+    expect(data.payload.status).toBe(200);
+    expect(data.payload.responseSize).toBe(2);
+    expect(data.payload.durationMs).toBeGreaterThanOrEqual(0);
+
+    recorder.stop();
+  });
+
+  it('emits status 0 for a failed fetch', async () => {
+    globalThis.fetch = vi.fn().mockRejectedValue(new TypeError('Network error'));
+
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start({ captureNetworkRequests: true });
+
+    await globalThis.fetch('https://api.example.com/data').catch(() => {});
+
+    const pluginEvents = onEvent.mock.calls
+      .map(([e]: [RecordingEvent]) => e)
+      .filter(e => e.type === RecordingEventType.Plugin);
+    expect(pluginEvents).toHaveLength(1);
+    const data = pluginEvents[0].data as NetworkRequestPluginData;
+    expect(data.payload.status).toBe(0);
+
+    recorder.stop();
+  });
+
+  it('captures the method from init', async () => {
+    const mockResponse = new Response('', { status: 201 });
+    globalThis.fetch = vi.fn().mockResolvedValue(mockResponse);
+
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start({ captureNetworkRequests: true });
+
+    await globalThis.fetch('https://api.example.com/data', { method: 'post' });
+
+    const pluginEvents = onEvent.mock.calls
+      .map(([e]: [RecordingEvent]) => e)
+      .filter(e => e.type === RecordingEventType.Plugin);
+    const data = pluginEvents[0].data as NetworkRequestPluginData;
+    expect(data.payload.method).toBe('POST');
+
+    recorder.stop();
+  });
+
+  it('captures the method from a Request object', async () => {
+    const mockResponse = new Response('', { status: 200 });
+    globalThis.fetch = vi.fn().mockResolvedValue(mockResponse);
+
+    const engine = new MockEngine();
+    const onEvent = vi.fn();
+    const recorder = new Recorder({ engine, onEvent });
+    recorder.start({ captureNetworkRequests: true });
+
+    await globalThis.fetch(new Request('https://api.example.com/data', { method: 'DELETE' }));
+
+    const pluginEvents = onEvent.mock.calls
+      .map(([e]: [RecordingEvent]) => e)
+      .filter(e => e.type === RecordingEventType.Plugin);
+    const data = pluginEvents[0].data as NetworkRequestPluginData;
+    expect(data.payload.method).toBe('DELETE');
+    expect(data.payload.url).toBe('https://api.example.com/data');
+
+    recorder.stop();
+  });
+});