@spotify-confidence/csr-recorder 0.0.0 → 0.17.3

package/src/recorder.ts

@@ -0,0 +1,289 @@
+import {
+  RecordingEvent,
+  RecordingEventType,
+  type TabVisibilityPluginData,
+  type NetworkRequestPluginData,
+  type RouteChangePluginData,
+  type RouteChangeTrigger,
+} from '@spotify-confidence/csr-common';
+import { RecorderOptions, RecorderState, RecordingConfig } from './types';
+import { RecordingEngine } from './engine';
+import { defaultParameterizeRoute } from './route-parameterizer';
+
+export class Recorder {
+  private readonly engine: RecordingEngine;
+  private readonly onEvent: (event: RecordingEvent) => void;
+  private state: RecorderState = RecorderState.Idle;
+  private visibilityHandler: (() => void) | null = null;
+  private originalFetch: typeof globalThis.fetch | null = null;
+  private originalXhrOpen: typeof XMLHttpRequest.prototype.open | null = null;
+  private originalXhrSend: typeof XMLHttpRequest.prototype.send | null = null;
+  private originalPushState: typeof history.pushState | null = null;
+  private originalReplaceState: typeof history.replaceState | null = null;
+  private popstateHandler: (() => void) | null = null;
+  private parameterizeRoute!: (route: string) => string;
+
+  constructor(options: RecorderOptions) {
+    this.engine = options.engine;
+    this.onEvent = options.onEvent;
+  }
+
+  get currentState(): RecorderState {
+    return this.state;
+  }
+
+  start(config?: RecordingConfig): void {
+    if (this.state === RecorderState.Recording) {
+      return;
+    }
+    this.state = RecorderState.Recording;
+    this.parameterizeRoute = config?.parameterizeRoute ?? defaultParameterizeRoute;
+
+    this.engine.start(config ?? {}, event => {
+      if (event.type === RecordingEventType.Meta) {
+        const data = event.data as { href?: string };
+        if (typeof data?.href === 'string') {
+          event = { ...event, data: { ...data, href: this.parameterizeHref(data.href) } };
+        }
+      }
+      this.onEvent(event);
+    });
+
+    if (typeof document !== 'undefined') {
+      this.visibilityHandler = () => {
+        const data: TabVisibilityPluginData = {
+          plugin: 'csr:tabVisibility',
+          payload: { hidden: document.hidden },
+        };
+        this.onEvent({
+          type: RecordingEventType.Plugin,
+          timestamp: Date.now(),
+          data,
+        });
+      };
+      document.addEventListener('visibilitychange', this.visibilityHandler);
+    }
+
+    if (config?.captureNetworkRequests) {
+      this.patchNetwork();
+    }
+
+    if (config?.captureRouteChanges !== false) {
+      this.patchRouting();
+    }
+  }
+
+  private emitNetworkRequest(payload: NetworkRequestPluginData['payload']): void {
+    const data: NetworkRequestPluginData = {
+      plugin: 'csr:networkRequest',
+      payload,
+    };
+    this.onEvent({
+      type: RecordingEventType.Plugin,
+      timestamp: Date.now(),
+      data,
+    });
+  }
+
+  private patchNetwork(): void {
+    this.patchFetch();
+    this.patchXhr();
+  }
+
+  private patchFetch(): void {
+    if (typeof globalThis.fetch !== 'function') return;
+    const originalFetch = globalThis.fetch;
+    this.originalFetch = originalFetch;
+    const emit = this.emitNetworkRequest.bind(this);
+
+    globalThis.fetch = (input: RequestInfo | URL, init?: RequestInit) => {
+      const method = input instanceof Request ? input.method : init?.method ?? 'GET';
+      let url: string;
+      if (input instanceof Request) {
+        url = input.url;
+      } else if (input instanceof URL) {
+        url = input.href;
+      } else {
+        url = String(input);
+      }
+      const requestSize = init?.body ? new Blob([init.body as BlobPart]).size : undefined;
+      const start = Date.now();
+
+      return originalFetch.call(globalThis, input, init).then(
+        response => {
+          const contentLength = response.headers.get('content-length');
+          emit({
+            initiator: 'fetch',
+            method: method.toUpperCase(),
+            url,
+            status: response.status,
+            durationMs: Date.now() - start,
+            ...(requestSize !== null && requestSize !== undefined ? { requestSize } : {}),
+            ...(contentLength ? { responseSize: Number(contentLength) } : {}),
+          });
+          return response;
+        },
+        error => {
+          emit({
+            initiator: 'fetch',
+            method: method.toUpperCase(),
+            url,
+            status: 0,
+            durationMs: Date.now() - start,
+            ...(requestSize !== null && requestSize !== undefined ? { requestSize } : {}),
+          });
+          throw error;
+        },
+      );
+    };
+  }
+
+  private patchXhr(): void {
+    if (typeof XMLHttpRequest === 'undefined') return;
+    const originalOpen = XMLHttpRequest.prototype.open;
+    const originalSend = XMLHttpRequest.prototype.send;
+    this.originalXhrOpen = originalOpen;
+    this.originalXhrSend = originalSend;
+    const emit = this.emitNetworkRequest.bind(this);
+
+    XMLHttpRequest.prototype.open = function csrOpen(
+      this: XMLHttpRequest,
+      method: string,
+      url: string | URL,
+      ...rest: unknown[]
+    ) {
+      (this as unknown as Record<string, unknown>).__csr_method = method;
+      (this as unknown as Record<string, unknown>).__csr_url = String(url);
+      return originalOpen.apply(this, [method, url, ...rest] as Parameters<typeof XMLHttpRequest.prototype.open>);
+    };
+
+    XMLHttpRequest.prototype.send = function csrSend(
+      this: XMLHttpRequest,
+      body?: Document | XMLHttpRequestBodyInit | null,
+    ) {
+      const meta = this as unknown as Record<string, unknown>;
+      const method = (meta.__csr_method as string) ?? 'GET';
+      const url = (meta.__csr_url as string) ?? '';
+      const requestSize = body !== null && body !== undefined ? new Blob([body as BlobPart]).size : undefined;
+      const start = Date.now();
+
+      this.addEventListener('loadend', function csrLoadend(this: XMLHttpRequest) {
+        const contentLength = this.getResponseHeader('content-length');
+        emit({
+          initiator: 'xhr',
+          method: method.toUpperCase(),
+          url,
+          status: this.status,
+          durationMs: Date.now() - start,
+          ...(requestSize !== null && requestSize !== undefined ? { requestSize } : {}),
+          ...(contentLength ? { responseSize: Number(contentLength) } : {}),
+        });
+      });
+
+      return originalSend.call(this, body);
+    };
+  }
+
+  private parameterizeHref(href: string): string {
+    try {
+      const url = new URL(href);
+      url.pathname = this.parameterizeRoute(url.pathname);
+      return url.toString();
+    } catch (_e) {
+      return this.parameterizeRoute(href);
+    }
+  }
+
+  private emitRouteChange(from: string, to: string, trigger: RouteChangeTrigger): void {
+    if (from === to) return;
+    const paramFrom = this.parameterizeRoute(from);
+    const paramTo = this.parameterizeRoute(to);
+    if (paramFrom === paramTo) return;
+    const data: RouteChangePluginData = {
+      plugin: 'csr:routeChange',
+      payload: { from: paramFrom, to: paramTo, trigger },
+    };
+    this.onEvent({
+      type: RecordingEventType.Plugin,
+      timestamp: Date.now(),
+      data,
+    });
+  }
+
+  private static currentPathname(): string {
+    return window.location.pathname;
+  }
+
+  private patchRouting(): void {
+    if (typeof window === 'undefined') return;
+
+    let lastUrl = Recorder.currentPathname();
+
+    const emitNav = (trigger: RouteChangeTrigger) => {
+      const before = lastUrl;
+      lastUrl = Recorder.currentPathname();
+      this.emitRouteChange(before, lastUrl, trigger);
+    };
+
+    const originalPushState = history.pushState.bind(history);
+    this.originalPushState = history.pushState;
+    history.pushState = (...args: Parameters<typeof history.pushState>) => {
+      originalPushState(...args);
+      emitNav('pushState');
+    };
+
+    const originalReplaceState = history.replaceState.bind(history);
+    this.originalReplaceState = history.replaceState;
+    history.replaceState = (...args: Parameters<typeof history.replaceState>) => {
+      originalReplaceState(...args);
+      emitNav('replaceState');
+    };
+
+    this.popstateHandler = () => emitNav('popstate');
+    window.addEventListener('popstate', this.popstateHandler);
+  }
+
+  private restoreRouting(): void {
+    if (this.originalPushState) {
+      history.pushState = this.originalPushState;
+      this.originalPushState = null;
+    }
+    if (this.originalReplaceState) {
+      history.replaceState = this.originalReplaceState;
+      this.originalReplaceState = null;
+    }
+    if (this.popstateHandler) {
+      window.removeEventListener('popstate', this.popstateHandler);
+      this.popstateHandler = null;
+    }
+  }
+
+  private restoreNetwork(): void {
+    if (this.originalFetch) {
+      globalThis.fetch = this.originalFetch;
+      this.originalFetch = null;
+    }
+    if (this.originalXhrOpen) {
+      XMLHttpRequest.prototype.open = this.originalXhrOpen;
+      this.originalXhrOpen = null;
+    }
+    if (this.originalXhrSend) {
+      XMLHttpRequest.prototype.send = this.originalXhrSend;
+      this.originalXhrSend = null;
+    }
+  }
+
+  stop(): void {
+    if (this.state !== RecorderState.Recording) {
+      return;
+    }
+    if (this.visibilityHandler) {
+      document.removeEventListener('visibilitychange', this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
+    this.restoreNetwork();
+    this.restoreRouting();
+    this.engine.stop();
+    this.state = RecorderState.Stopped;
+  }
+}

package/src/route-parameterizer.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import { defaultParameterizeRoute } from './route-parameterizer';
+
+describe('defaultParameterizeRoute', () => {
+  it('leaves static routes unchanged', () => {
+    expect(defaultParameterizeRoute('/users/settings')).toBe('/users/settings');
+  });
+
+  it('replaces numeric IDs', () => {
+    expect(defaultParameterizeRoute('/users/123')).toBe('/users/:id');
+    expect(defaultParameterizeRoute('/users/123/posts/456')).toBe('/users/:id/posts/:id');
+  });
+
+  it('replaces UUIDs', () => {
+    expect(defaultParameterizeRoute('/users/550e8400-e29b-41d4-a716-446655440000')).toBe('/users/:uuid');
+  });
+
+  it('replaces uppercase UUIDs', () => {
+    expect(defaultParameterizeRoute('/users/550E8400-E29B-41D4-A716-446655440000')).toBe('/users/:uuid');
+  });
+
+  it('replaces long hex strings (MongoDB ObjectIDs)', () => {
+    expect(defaultParameterizeRoute('/items/507f1f77bcf86cd799439011')).toBe('/items/:id');
+  });
+
+  it('handles mixed segments', () => {
+    expect(defaultParameterizeRoute('/org/550e8400-e29b-41d4-a716-446655440000/users/42/profile')).toBe(
+      '/org/:uuid/users/:id/profile',
+    );
+  });
+
+  it('preserves root path', () => {
+    expect(defaultParameterizeRoute('/')).toBe('/');
+  });
+
+  it('preserves empty string', () => {
+    expect(defaultParameterizeRoute('')).toBe('');
+  });
+
+  it('does not replace short hex strings', () => {
+    expect(defaultParameterizeRoute('/features/abcdef')).toBe('/features/abcdef');
+  });
+
+  it('does not replace words that look vaguely hex-ish', () => {
+    expect(defaultParameterizeRoute('/dashboard/feed')).toBe('/dashboard/feed');
+  });
+
+  it('handles trailing slash', () => {
+    expect(defaultParameterizeRoute('/users/123/')).toBe('/users/:id/');
+  });
+
+  it('replaces AIP-122 generated IDs', () => {
+    expect(defaultParameterizeRoute('/workflows/abtest/instances/cmvkznnjmbkc9rw2oxws/report')).toBe(
+      '/workflows/abtest/instances/:id/report',
+    );
+  });
+
+  it('replaces multiple AIP-122 IDs', () => {
+    expect(defaultParameterizeRoute('/admin/workflows/a0smva5nxuhv4yts6pax/instances/cmvkznnjmbkc9rw2oxws')).toBe(
+      '/admin/workflows/:id/instances/:id',
+    );
+  });
+
+  it('does not replace short lowercase strings as AIP-122', () => {
+    expect(defaultParameterizeRoute('/workflows/abtest')).toBe('/workflows/abtest');
+  });
+
+  it('replaces segments containing embedded hex IDs', () => {
+    expect(defaultParameterizeRoute('/items/prefix507f1f77bcf86cd799439011suffix')).toBe('/items/:id');
+  });
+
+  it('replaces MD5 hashes', () => {
+    expect(defaultParameterizeRoute('/cache/d41d8cd98f00b204e9800998ecf8427e')).toBe('/cache/:id');
+  });
+});

package/src/route-parameterizer.ts

@@ -0,0 +1,20 @@
+const SEGMENT_PATTERNS: Array<{ pattern: RegExp; replacement: string }> = [
+  { pattern: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, replacement: ':uuid' },
+  { pattern: /^\d+$/, replacement: ':id' },
+  // AIP-122 generated IDs: 20-char lowercase alphanumeric starting with a letter
+  { pattern: /^[a-z][a-z0-9]{19}$/, replacement: ':id' },
+  { pattern: /[0-9a-f]{20}/i, replacement: ':id' },
+];
+
+export function defaultParameterizeRoute(route: string): string {
+  return route
+    .split('/')
+    .map(segment => {
+      if (!segment) return segment;
+      for (const { pattern, replacement } of SEGMENT_PATTERNS) {
+        if (pattern.test(segment)) return replacement;
+      }
+      return segment;
+    })
+    .join('/');
+}

package/src/start-recording.ts

@@ -0,0 +1,21 @@
+import { RecordingEvent } from '@spotify-confidence/csr-common';
+import { Recorder } from './recorder';
+import { RrwebEngine } from './engine/rrweb-engine';
+import { RecordingConfig } from './types';
+
+/**
+ * Start recording DOM events. Each event is passed to the callback
+ * as it is captured — no buffering or batching.
+ *
+ * Returns a function that stops the recording.
+ */
+export function record(onEvent: (event: RecordingEvent) => void, config?: RecordingConfig): () => void {
+  const recorder = new Recorder({
+    engine: new RrwebEngine(),
+    onEvent,
+  });
+
+  recorder.start(config);
+
+  return () => recorder.stop();
+}

package/src/types.ts

@@ -0,0 +1,80 @@
+export interface RecorderOptions {
+  /** Engine used to capture DOM events (defaults to rrweb). */
+  engine: import('./engine').RecordingEngine;
+  /** Called for each recorded event. */
+  onEvent: (event: import('@spotify-confidence/csr-common').RecordingEvent) => void;
+}
+
+export const DEFAULT_MASK_SELECTORS: string[] = ['[data-csr-mask]'];
+export const DEFAULT_BLOCK_SELECTORS: string[] = ['[data-csr-block]'];
+
+export interface RecordingConfig {
+  /**
+   * CSS selectors for text content that should be masked. Joined with `,` and
+   * passed to rrweb as `maskTextSelector`. Text inside matching elements is
+   * replaced with `*` of the same length on the wire.
+   */
+  maskSelectors?: string[];
+  /**
+   * CSS selectors for elements whose subtree should be blocked entirely.
+   * Joined with `,` and passed to rrweb as `blockSelector`. Matching elements
+   * are replaced with a same-sized placeholder; their contents are never
+   * serialized — stronger than masking, use for media, third-party widgets,
+   * or anything that shouldn't leave the page at all.
+   */
+  blockSelectors?: string[];
+  /**
+   * Mask the values of every `<input>` / `<textarea>` / `contenteditable`.
+   * Defaults to `true` — typed PII (emails, names, search queries) doesn't
+   * leave the page. Pass `false` to record raw input values; `<input
+   * type="password">` is masked by rrweb regardless.
+   */
+  maskInputs?: boolean;
+  /**
+   * Capture browser console output during the recording. Defaults to `false`
+   * because console output frequently contains PII, tokens, and other
+   * sensitive data that should not be ingested into the recording pipeline
+   * without explicit opt-in.
+   *
+   * - `true` — capture all levels (log, warn, error, debug, info).
+   * - `{ levels: [...] }` — capture only the listed levels.
+   */
+  captureConsoleLogs?: boolean | { levels: import('@spotify-confidence/csr-common').ConsoleLogLevel[] };
+  /**
+   * Capture network requests (fetch and XMLHttpRequest) during the recording.
+   * Defaults to `false` because request URLs and metadata can contain PII,
+   * tokens, or other sensitive data.
+   *
+   * Only metadata is captured (method, URL, status, duration, sizes) — no
+   * headers or bodies are recorded.
+   */
+  captureNetworkRequests?: boolean;
+  /**
+   * Capture client-side route changes during the recording. Defaults to
+   * `true`. Only the pathname is recorded; origin, query strings, and
+   * hashes are stripped.
+   */
+  captureRouteChanges?: boolean;
+  /**
+   * Transform a raw pathname into a route pattern before it is emitted in
+   * route-change and Meta events. For example, `/users/123/profile` becomes
+   * `/users/:id/profile`. This ensures per-page metrics are grouped by route
+   * rather than by individual page visit.
+   *
+   * The default implementation replaces common dynamic segments:
+   * - UUIDs → `:uuid`
+   * - Numeric IDs → `:id`
+   * - AIP-122 IDs → `:id`
+   * - Long hex strings (20+ chars, e.g. MongoDB ObjectIDs) → `:id`
+   *
+   * Provide a custom function to handle application-specific patterns.
+   * Import `defaultParameterizeRoute` to compose with the built-in rules.
+   */
+  parameterizeRoute?: (route: string) => string;
+}
+
+export enum RecorderState {
+  Idle = 'idle',
+  Recording = 'recording',
+  Stopped = 'stopped',
+}