@spotify-confidence/session-recording 0.0.0 → 0.17.3

package/package.json

@@ -1 +1,49 @@
-{"name":"@spotify-confidence/session-recording","version":"0.0.0","description":"Placeholder"}
+{
+  "name": "@spotify-confidence/session-recording",
+  "license": "Apache-2.0",
+  "version": "0.17.3",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spotify/confidence-sdk-js.git",
+    "directory": "csr/session-recording"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "prebuild": "node sync-version.mjs",
+    "build": "yarn run -T tsdown",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "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": {
+    "@spotify-confidence/csr-common": "^0.17.3",
+    "@spotify-confidence/csr-recorder": "^0.17.3"
+  },
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  }
+}

package/src/flag-observer.test.ts

@@ -0,0 +1,96 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { observeFlags, type FlagWrite } from './flag-observer';
+
+describe('observeFlags', () => {
+  beforeEach(() => {
+    delete (window as any).__confidence;
+  });
+
+  it('calls back when a flag is written after observation starts', () => {
+    const writes: FlagWrite[] = [];
+    observeFlags(w => writes.push(w));
+
+    (window as any).__confidence.flags['my-flag'] = { variant: 'treatment-a' };
+
+    expect(writes).toEqual([{ flagKey: 'my-flag', variant: 'treatment-a' }]);
+  });
+
+  it('emits snapshot entries for pre-existing flags', () => {
+    (window as any).__confidence = {
+      flags: {
+        'flag-a': { variant: 'v1' },
+        'flag-b': { variant: 'v2' },
+      },
+    };
+
+    const writes: FlagWrite[] = [];
+    observeFlags(w => writes.push(w));
+
+    expect(writes).toContainEqual({ flagKey: 'flag-a', variant: 'v1' });
+    expect(writes).toContainEqual({ flagKey: 'flag-b', variant: 'v2' });
+  });
+
+  it('observes new writes after reading the snapshot', () => {
+    (window as any).__confidence = {
+      flags: { existing: { variant: 'old' } },
+    };
+
+    const writes: FlagWrite[] = [];
+    observeFlags(w => writes.push(w));
+
+    (window as any).__confidence.flags['new-flag'] = { variant: 'new' };
+
+    expect(writes).toHaveLength(2);
+    expect(writes[0]).toEqual({ flagKey: 'existing', variant: 'old' });
+    expect(writes[1]).toEqual({ flagKey: 'new-flag', variant: 'new' });
+  });
+
+  it('cleanup replaces proxy with plain copy', () => {
+    const writes: FlagWrite[] = [];
+    const cleanup = observeFlags(w => writes.push(w));
+
+    (window as any).__confidence.flags['flag-a'] = { variant: 'v1' };
+    expect(writes).toHaveLength(1);
+
+    cleanup();
+
+    (window as any).__confidence.flags['flag-b'] = { variant: 'v2' };
+    expect(writes).toHaveLength(1);
+  });
+
+  it('preserves data after cleanup', () => {
+    observeFlags(() => {});
+    (window as any).__confidence.flags['my-flag'] = { variant: 'treatment' };
+
+    const cleanup = observeFlags(() => {});
+    cleanup();
+
+    expect((window as any).__confidence.flags['my-flag']).toEqual({ variant: 'treatment' });
+  });
+
+  it('ignores writes with missing variant', () => {
+    const writes: FlagWrite[] = [];
+    observeFlags(w => writes.push(w));
+
+    (window as any).__confidence.flags.bad = { noVariant: true };
+
+    expect(writes).toHaveLength(0);
+  });
+
+  it('ignores writes with non-string variant', () => {
+    const writes: FlagWrite[] = [];
+    observeFlags(w => writes.push(w));
+
+    (window as any).__confidence.flags.bad = { variant: 42 };
+
+    expect(writes).toHaveLength(0);
+  });
+
+  it('initializes window.__confidence if not present', () => {
+    observeFlags(() => {});
+
+    expect((window as any).__confidence).toBeDefined();
+    expect((window as any).__confidence.flags).toBeDefined();
+  });
+});

package/src/flag-observer.ts

@@ -0,0 +1,32 @@
+export type FlagWrite = { flagKey: string; variant: string };
+export type FlagWriteCallback = (write: FlagWrite) => void;
+
+export function observeFlags(onFlagWrite: FlagWriteCallback): () => void {
+  if (typeof window === 'undefined') return () => {};
+
+  const confidence = ((window as any).__confidence ??= {});
+  const existing: Record<string, { variant: string }> = confidence.flags ?? {};
+  const target: Record<string, { variant: string }> = { ...existing };
+
+  const proxy = new Proxy(target, {
+    set(_target, prop, value) {
+      if (typeof prop === 'string' && value && typeof value.variant === 'string') {
+        _target[prop] = value;
+        onFlagWrite({ flagKey: prop, variant: value.variant });
+      }
+      return true;
+    },
+  });
+
+  confidence.flags = proxy;
+
+  for (const [name, data] of Object.entries(existing)) {
+    if (data && typeof (data as any).variant === 'string') {
+      onFlagWrite({ flagKey: name, variant: (data as any).variant });
+    }
+  }
+
+  return () => {
+    confidence.flags = { ...target };
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,195 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const createUploader = vi.hoisted(() => vi.fn());
+const record = vi.hoisted(() => vi.fn());
+
+vi.mock('@spotify-confidence/csr-common/uploader', () => ({
+  createUploader,
+}));
+vi.mock('@spotify-confidence/csr-recorder', () => ({
+  record,
+}));
+
+import { initSessionRecorder } from './index';
+
+function flushPromises() {
+  return new Promise(r => setTimeout(r, 0));
+}
+
+function mockUploader() {
+  const fn = Object.assign(vi.fn(), { close: vi.fn() });
+  return fn;
+}
+
+describe('initSessionRecorder', () => {
+  afterEach(() => vi.resetAllMocks());
+
+  it('always returns a SessionRecorder', () => {
+    createUploader.mockResolvedValueOnce(mockUploader());
+    record.mockReturnValueOnce(() => {});
+
+    const recorder = initSessionRecorder({ clientSecret: 'secret' });
+
+    expect(recorder.start).toBeTypeOf('function');
+    expect(recorder.stop).toBeTypeOf('function');
+  });
+
+  it('automatic mode inits and records immediately', async () => {
+    createUploader.mockResolvedValueOnce(mockUploader());
+    record.mockReturnValueOnce(() => {});
+
+    initSessionRecorder({ clientSecret: 'secret' });
+    await flushPromises();
+
+    expect(createUploader).toHaveBeenCalledOnce();
+    expect(createUploader.mock.calls[0][0]).toMatchObject({
+      forceRecord: false,
+    });
+    expect(record).toHaveBeenCalledOnce();
+  });
+
+  it('forwards options to createUploader and record', async () => {
+    createUploader.mockResolvedValueOnce(mockUploader());
+    record.mockReturnValueOnce(() => {});
+
+    const ctx = { buildVersion: '2.3.1' };
+    initSessionRecorder({
+      clientSecret: 'secret',
+      targetingKey: 'user-42',
+      context: ctx,
+      maskSelectors: ['.private'],
+      blockSelectors: ['video', '.third-party'],
+      maskInputs: false,
+    });
+    await flushPromises();
+
+    expect(createUploader.mock.calls[0][0]).toMatchObject({
+      apiUrl: 'https://recording.confidence.dev',
+      websocketUrl: 'wss://recording-ws.confidence.dev/sessions/stream',
+      clientSecret: 'secret',
+      targetingKey: 'user-42',
+      context: ctx,
+    });
+    expect(record.mock.calls[0][1]).toEqual({
+      maskSelectors: ['.private'],
+      blockSelectors: ['video', '.third-party'],
+      maskInputs: false,
+    });
+  });
+
+  it('automatic mode does not call record when backend skips', async () => {
+    createUploader.mockResolvedValueOnce(null);
+
+    initSessionRecorder({ clientSecret: 'secret' });
+    await flushPromises();
+
+    expect(record).not.toHaveBeenCalled();
+  });
+
+  it('does not throw when createUploader rejects', async () => {
+    createUploader.mockRejectedValueOnce(new Error('boom'));
+
+    const recorder = initSessionRecorder({ clientSecret: 'secret' });
+    await flushPromises();
+
+    expect(recorder).toBeDefined();
+  });
+
+  it('manual mode does not init until start is called', async () => {
+    createUploader.mockResolvedValueOnce(mockUploader());
+    record.mockReturnValueOnce(() => {});
+
+    const recorder = initSessionRecorder({
+      clientSecret: 'secret',
+      mode: 'manual',
+    });
+    await flushPromises();
+
+    expect(createUploader).not.toHaveBeenCalled();
+    expect(record).not.toHaveBeenCalled();
+
+    recorder.start();
+    await flushPromises();
+
+    expect(createUploader).toHaveBeenCalledOnce();
+    expect(createUploader.mock.calls[0][0]).toMatchObject({
+      forceRecord: true,
+    });
+    expect(record).toHaveBeenCalledOnce();
+  });
+
+  it('start is a no-op in automatic mode', async () => {
+    createUploader.mockResolvedValueOnce(mockUploader());
+    record.mockReturnValueOnce(() => {});
+
+    const recorder = initSessionRecorder({ clientSecret: 'secret' });
+    await flushPromises();
+
+    recorder.start();
+    await flushPromises();
+
+    expect(createUploader).toHaveBeenCalledOnce();
+  });
+
+  it('stop tears down the recorder and closes the transport', async () => {
+    const stopFn = vi.fn();
+    const uploader = mockUploader();
+    createUploader.mockResolvedValueOnce(uploader);
+    record.mockReturnValueOnce(stopFn);
+
+    const recorder = initSessionRecorder({ clientSecret: 'secret' });
+    await flushPromises();
+
+    recorder.stop();
+    expect(stopFn).toHaveBeenCalledOnce();
+    expect(uploader.close).toHaveBeenCalledOnce();
+
+    recorder.stop();
+    expect(stopFn).toHaveBeenCalledOnce();
+    expect(uploader.close).toHaveBeenCalledOnce();
+  });
+
+  it('isRecording reflects recording state', async () => {
+    const stopFn = vi.fn();
+    createUploader.mockResolvedValueOnce(mockUploader());
+    record.mockReturnValueOnce(stopFn);
+
+    const recorder = initSessionRecorder({ clientSecret: 'secret' });
+    expect(recorder.isRecording).toBe(false);
+
+    await flushPromises();
+    expect(recorder.isRecording).toBe(true);
+
+    recorder.stop();
+    expect(recorder.isRecording).toBe(false);
+  });
+
+  it('isRecording is false in manual mode before start', async () => {
+    createUploader.mockResolvedValueOnce(mockUploader());
+    record.mockReturnValueOnce(() => {});
+
+    const recorder = initSessionRecorder({
+      clientSecret: 'secret',
+      mode: 'manual',
+    });
+    await flushPromises();
+
+    expect(recorder.isRecording).toBe(false);
+
+    recorder.start();
+    await flushPromises();
+
+    expect(recorder.isRecording).toBe(true);
+  });
+
+  it('stop before init completes prevents recording', async () => {
+    createUploader.mockResolvedValueOnce(mockUploader());
+    record.mockReturnValueOnce(() => {});
+
+    const recorder = initSessionRecorder({ clientSecret: 'secret' });
+    recorder.stop();
+    await flushPromises();
+
+    expect(record).not.toHaveBeenCalled();
+  });
+});

package/src/index.ts

@@ -0,0 +1,248 @@
+import { record } from '@spotify-confidence/csr-recorder';
+import type { ConsoleLogLevel } from '@spotify-confidence/csr-common';
+import {
+  RecordingEventType,
+  type TagPluginData,
+  type MeasurePluginData,
+  type FlagEvaluationPluginData,
+  validateKey,
+  validateTagValue,
+  validateMeasureValue,
+} from '@spotify-confidence/csr-common';
+import { observeFlags } from './flag-observer';
+import { createUploader, type ClientContext } from '@spotify-confidence/csr-common/uploader';
+import { SDK_VERSION } from './version';
+
+const DEFAULT_API_URL = 'https://recording.confidence.dev';
+const DEFAULT_WEBSOCKET_URL = 'wss://recording-ws.confidence.dev/sessions/stream';
+export interface InitSessionRecorderOptions {
+  /** Per-tenant secret. */
+  clientSecret: string;
+  /** End-user identifier (visitor / device id). */
+  targetingKey?: string;
+  /** CSS selectors whose text content should be masked. */
+  maskSelectors?: string[];
+  /** CSS selectors whose subtrees should be blocked (replaced with a placeholder, never serialized). */
+  blockSelectors?: string[];
+  /** Mask values of every `<input>` / `<textarea>` / `contenteditable`. Defaults to `true`. */
+  maskInputs?: boolean;
+  /** Capture browser console output. Defaults to `false`. Pass `true` for all levels or `{ levels: [...] }` for specific ones. */
+  captureConsoleLogs?: boolean | { levels: ConsoleLogLevel[] };
+  /** Capture fetch/XHR metadata (method, URL, status, duration). Defaults to `false`. */
+  captureNetworkRequests?: boolean;
+  /** Capture client-side route changes (pathname only). Defaults to `true`. */
+  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.
+   *
+   * Import `defaultParameterizeRoute` from `@spotify-confidence/csr-recorder`
+   * to compose with the built-in rules.
+   */
+  parameterizeRoute?: (route: string) => string;
+  /** Backend base URL. Defaults to the Confidence production endpoint. */
+  apiUrl?: string;
+  /** WebSocket ingest URL. Defaults to the Confidence production endpoint. */
+  websocketUrl?: string;
+  /** Application version or commit hash, e.g. "1.2.3" or "abc1234". Stored on the recording for filtering. */
+  appVersion?: string;
+  /** Custom dimensions merged into the session context alongside auto-collected browser metadata. */
+  context?: ClientContext;
+  /**
+   * `'automatic'` (default) — starts recording as soon as the session is established.
+   * `'manual'` — does nothing until `start()` is called, bypassing sampling and targeting rules.
+   */
+  mode?: 'automatic' | 'manual';
+  /** Verbose tracer for debugging — called with one-line lifecycle/transport messages. */
+  debugLogger?: (msg: string) => void;
+}
+
+export interface SessionRecorder {
+  /** Start recording. In `automatic` mode this is a no-op. In `manual` mode it establishes a session and begins recording. */
+  start(): void;
+  /** Stop recording permanently. Idempotent. */
+  stop(): void;
+  /** Attach a custom tag to this recording. Tags with the same key accumulate values. Omit value for a valueless marker. */
+  tag(key: string, value?: string): void;
+  /** Record a numeric measurement. Measurements with the same key are summed. Omit value to count occurrences (each call adds 1). */
+  measure(key: string, value?: number): void;
+  /** Whether the recorder is actively capturing events. */
+  readonly isRecording: boolean;
+}
+
+function csrDebugLogger(): ((msg: string) => void) | undefined {
+  try {
+    if (sessionStorage.getItem('CSR_DEBUG')) {
+      // Debug logger intentionally uses console — only active when CSR_DEBUG is set.
+      // eslint-disable-next-line no-console
+      return (msg: string) => console.log(msg);
+    }
+  } catch (_e) {
+    // sessionStorage may be unavailable (sandboxed iframe, etc.)
+  }
+  return undefined;
+}
+
+/**
+ * Create a session recorder. In `automatic` mode (default) recording begins
+ * as soon as a session is established. In `manual` mode nothing happens
+ * until {@link SessionRecorder.start} is called.
+ *
+ * Always returns a {@link SessionRecorder} — safe to call, never throws.
+ */
+export function initSessionRecorder(options: InitSessionRecorderOptions): SessionRecorder {
+  const userLogger = options.debugLogger ?? csrDebugLogger();
+  const debugLogger = userLogger ? (msg: string) => userLogger(`[CSR] ${msg}`) : undefined;
+
+  let stopRecorder: (() => void) | null = null;
+  let closeUploader: (() => void) | null = null;
+  let stopObservingFlags: (() => void) | null = null;
+  let sendEvent: ((event: unknown) => void) | null = null;
+  let started = false;
+  let stopped = false;
+
+  const recordingConfig = {
+    maskSelectors: options.maskSelectors,
+    blockSelectors: options.blockSelectors,
+    maskInputs: options.maskInputs,
+    captureConsoleLogs: options.captureConsoleLogs,
+    captureNetworkRequests: options.captureNetworkRequests,
+    captureRouteChanges: options.captureRouteChanges,
+    parameterizeRoute: options.parameterizeRoute,
+  };
+
+  async function initAndRecord(forceRecord: boolean) {
+    try {
+      const uploader = await createUploader({
+        apiUrl: options.apiUrl ?? DEFAULT_API_URL,
+        websocketUrl: options.websocketUrl ?? DEFAULT_WEBSOCKET_URL,
+        clientSecret: options.clientSecret,
+        targetingKey: options.targetingKey,
+        context: {
+          ...options.context,
+          _csr_sdk_version: SDK_VERSION,
+          ...(options.appVersion ? { _app_version: options.appVersion } : {}),
+        },
+        forceRecord,
+        debugLogger,
+        onTerminate: ({ reason }) => {
+          debugLogger?.(`Recording terminated: ${reason}`);
+          stopObservingFlags?.();
+          stopObservingFlags = null;
+          stopRecorder?.();
+          stopRecorder = null;
+          stopped = true;
+        },
+      });
+
+      if (stopped) {
+        uploader?.close();
+        return;
+      }
+
+      if (uploader === null) {
+        debugLogger?.('Recording skipped by backend');
+        return;
+      }
+
+      closeUploader = () => uploader.close();
+
+      sendEvent = event => {
+        try {
+          uploader(event);
+        } catch (err) {
+          debugLogger?.(`Event dropped: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      };
+
+      stopRecorder = record(sendEvent, recordingConfig);
+
+      stopObservingFlags = observeFlags(({ flagKey, variant }) => {
+        const data: FlagEvaluationPluginData = {
+          plugin: 'csr:flagEvaluation',
+          payload: { flagKey, variant },
+        };
+        sendEvent?.({
+          type: RecordingEventType.Plugin,
+          timestamp: Date.now(),
+          data,
+        });
+      });
+    } catch (err) {
+      debugLogger?.(`Recording disabled: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  const mode = options.mode ?? 'automatic';
+
+  if (mode === 'automatic') {
+    started = true;
+    void initAndRecord(false);
+  }
+
+  return {
+    start() {
+      if (started || stopped) return;
+      started = true;
+      void initAndRecord(true);
+    },
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      stopObservingFlags?.();
+      stopObservingFlags = null;
+      stopRecorder?.();
+      stopRecorder = null;
+      sendEvent = null;
+      closeUploader?.();
+      closeUploader = null;
+    },
+    tag(key: string, value?: string) {
+      const keyErr = validateKey(key);
+      if (keyErr) {
+        debugLogger?.(`tag() dropped: ${keyErr}`);
+        return;
+      }
+      const valErr = validateTagValue(value);
+      if (valErr) {
+        debugLogger?.(`tag() dropped: ${valErr}`);
+        return;
+      }
+      const data: TagPluginData = {
+        plugin: 'csr:tag',
+        payload: value !== undefined ? { key, value } : { key },
+      };
+      sendEvent?.({
+        type: RecordingEventType.Plugin,
+        timestamp: Date.now(),
+        data,
+      });
+    },
+    measure(key: string, value?: number) {
+      const keyErr = validateKey(key);
+      if (keyErr) {
+        debugLogger?.(`measure() dropped: ${keyErr}`);
+        return;
+      }
+      const valErr = validateMeasureValue(value);
+      if (valErr) {
+        debugLogger?.(`measure() dropped: ${valErr}`);
+        return;
+      }
+      const data: MeasurePluginData = {
+        plugin: 'csr:measure',
+        payload: value !== undefined ? { key, value } : { key },
+      };
+      sendEvent?.({
+        type: RecordingEventType.Plugin,
+        timestamp: Date.now(),
+        data,
+      });
+    },
+    get isRecording() {
+      return stopRecorder !== null;
+    },
+  };
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const SDK_VERSION = '0.17.3';