@spotify-confidence/csr-common 0.0.0 → 0.17.2

package/src/events.ts

@@ -0,0 +1,252 @@
+/**
+ * Mirrors rrweb's serialized-node types but decoupled — we own the enum.
+ */
+export enum SerializedNodeType {
+  Document = 0,
+  DocumentType = 1,
+  Element = 2,
+  Text = 3,
+  CDATA = 4,
+  Comment = 5,
+}
+
+/**
+ * Mirrors rrweb event types but decoupled — we own the enum.
+ */
+export enum RecordingEventType {
+  DomContentLoaded = 0,
+  Load = 1,
+  FullSnapshot = 2,
+  IncrementalSnapshot = 3,
+  Meta = 4,
+  Custom = 5,
+  Plugin = 6,
+}
+
+/**
+ * Incremental snapshot sub-types.
+ */
+export enum IncrementalSource {
+  Mutation = 0,
+  MouseMove = 1,
+  MouseInteraction = 2,
+  Scroll = 3,
+  ViewportResize = 4,
+  Input = 5,
+  TouchMove = 6,
+  MediaInteraction = 7,
+  StyleSheetRule = 8,
+  CanvasMutation = 9,
+  Font = 10,
+  Log = 11,
+  Drag = 12,
+  StyleDeclaration = 13,
+  Selection = 14,
+  AdoptedStyleSheet = 15,
+}
+
+/**
+ * From rrweb MouseInteractions.
+ */
+export enum MouseInteractions {
+  MouseUp = 0,
+  MouseDown = 1,
+  Click = 2,
+  ContextMenu = 3,
+  DblClick = 4,
+  Focus = 5,
+  Blur = 6,
+  TouchStart = 7,
+  TouchMove_Departed = 8,
+  TouchEnd = 9,
+  TouchCancel = 10,
+}
+
+export type RageClickCustomData = {
+  tag: 'csr:rageClick';
+  payload: {
+    targetId: number;
+    clickCount: number;
+    durationMs: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+
+export type FormFieldReEditCustomData = {
+  tag: 'csr:formFieldReEdit';
+  payload: {
+    targetId: number;
+    editCount: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+
+export type ScrollBackCustomData = {
+  tag: 'csr:scrollBack';
+  payload: {
+    scrollBackPx: number;
+    fromY: number;
+    toY: number;
+    pathname?: string;
+  };
+};
+
+export type ElementDescriptor = {
+  tagName: string;
+  classes?: string[];
+  textContent?: string;
+  attributes?: Record<string, string>;
+};
+
+export type ClickCustomData = {
+  tag: 'csr:click';
+  payload: {
+    targetId: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+
+export type InputCustomData = {
+  tag: 'csr:input';
+  payload: {
+    targetId: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+
+export type DeadClickCustomData = {
+  tag: 'csr:deadClick';
+  payload: {
+    targetId: number;
+    element?: ElementDescriptor;
+    pathname?: string;
+  };
+};
+
+export type TabUnfocusCustomData = {
+  tag: 'csr:tabUnfocus';
+  payload: {
+    pathname?: string;
+  };
+};
+
+export type TabRefocusCustomData = {
+  tag: 'csr:tabRefocus';
+  payload: {
+    awayDurationMs: number;
+    pathname?: string;
+  };
+};
+
+export type RouteChangeTrigger = 'pushState' | 'replaceState' | 'popstate' | 'navigation';
+
+export type RouteChangePayload = {
+  from: string;
+  to: string;
+  trigger: RouteChangeTrigger;
+};
+
+export type RouteChangeCustomData = {
+  tag: 'csr:routeChange';
+  payload: RouteChangePayload;
+};
+
+/**
+ * Plugin event data emitted by the recorder for tab visibility changes.
+ */
+export type TabVisibilityPluginData = {
+  plugin: 'csr:tabVisibility';
+  payload: { hidden: boolean };
+};
+
+export type ConsoleLogLevel = 'log' | 'warn' | 'error' | 'debug' | 'info';
+
+/**
+ * Plugin event data emitted by rrweb's console record plugin.
+ * Shape matches `@rrweb/rrweb-plugin-console-record` LogData.
+ */
+export type ConsoleLogPluginData = {
+  plugin: 'rrweb/console@1';
+  payload: {
+    level: ConsoleLogLevel;
+    payload: string[];
+    trace: string[];
+  };
+};
+
+export type NetworkRequestInitiator = 'fetch' | 'xhr';
+
+/**
+ * Plugin event data emitted by the recorder for network requests.
+ */
+export type NetworkRequestPluginData = {
+  plugin: 'csr:networkRequest';
+  payload: {
+    initiator: NetworkRequestInitiator;
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    requestSize?: number;
+    responseSize?: number;
+  };
+};
+
+export type RouteChangePluginData = {
+  plugin: 'csr:routeChange';
+  payload: RouteChangePayload;
+};
+
+export type TagPluginData = {
+  plugin: 'csr:tag';
+  payload: {
+    key: string;
+    value?: string;
+  };
+};
+
+export type MeasurePluginData = {
+  plugin: 'csr:measure';
+  payload: {
+    key: string;
+    value?: number;
+  };
+};
+
+/**
+ * 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.
+ */
+export type CustomEventData =
+  | ClickCustomData
+  | InputCustomData
+  | RageClickCustomData
+  | FormFieldReEditCustomData
+  | ScrollBackCustomData
+  | DeadClickCustomData
+  | TabUnfocusCustomData
+  | TabRefocusCustomData
+  | RouteChangeCustomData;
+
+/**
+ * A single recorded event.
+ *
+ * For non-Custom events `data` is `unknown` (decoupled from rrweb internals).
+ * For Custom events `data.tag` discriminates the payload across the closed
+ * `CustomEventData` union.
+ */
+export type RecordingEvent =
+  | {
+      type: RecordingEventType.Custom;
+      timestamp: number;
+      data: CustomEventData;
+    }
+  | {
+      type: Exclude<RecordingEventType, RecordingEventType.Custom>;
+      timestamp: number;
+      data: unknown;
+    };

package/src/index.ts

@@ -0,0 +1,44 @@
+export {
+  SerializedNodeType,
+  RecordingEventType,
+  IncrementalSource,
+  MouseInteractions,
+  type RecordingEvent,
+  type CustomEventData,
+  type ClickCustomData,
+  type InputCustomData,
+  type RageClickCustomData,
+  type FormFieldReEditCustomData,
+  type ScrollBackCustomData,
+  type DeadClickCustomData,
+  type ElementDescriptor,
+  type TabUnfocusCustomData,
+  type TabRefocusCustomData,
+  type TabVisibilityPluginData,
+  type ConsoleLogLevel,
+  type ConsoleLogPluginData,
+  type NetworkRequestInitiator,
+  type NetworkRequestPluginData,
+  type RouteChangeTrigger,
+  type RouteChangePayload,
+  type RouteChangeCustomData,
+  type RouteChangePluginData,
+  type TagPluginData,
+  type MeasurePluginData,
+} from './events';
+
+export { stripUrl } from './url';
+
+export {
+  MAX_KEY_LENGTH,
+  MAX_TAG_VALUE_LENGTH,
+  MAX_DISTINCT_KEYS,
+  MAX_VALUES_PER_KEY,
+  validateKey,
+  validateTagValue,
+  validateMeasureValue,
+} from './custom-event-limits';
+
+export { type Frame } from './uploader/types';
+
+export { type ClientContext, type UserAgentContext } from './uploader/client-context';

package/src/test-utils/index.ts

@@ -0,0 +1,3 @@
+export { installMockWsServer } from './mock-ws-server';
+export { installMockFetch, jsonResponse } from './mock-fetch';
+export { createMockPort, type MockPort } from './mock-port';

package/src/test-utils/mock-fetch.ts

@@ -0,0 +1,34 @@
+import { onTestFinished, vi } from 'vitest';
+
+/**
+ * Stub `globalThis.fetch` with a handler. `calls` records every invocation
+ * with its URL and `RequestInit`. Auto-restores when the current test ends.
+ *
+ * Must be called from within a test (or a helper called from one) so vitest
+ * has a test context to attach the cleanup to.
+ */
+export function installMockFetch(
+  handler: (input: RequestInfo | URL, init?: RequestInit) => Response | Promise<Response>,
+): { calls: Array<{ url: string; init?: RequestInit }> } {
+  const calls: Array<{ url: string; init?: RequestInit }> = [];
+  const original = globalThis.fetch;
+  globalThis.fetch = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+    calls.push({
+      url: typeof input === 'string' ? input : input.toString(),
+      init,
+    });
+    return handler(input, init);
+  }) as typeof fetch;
+  onTestFinished(() => {
+    globalThis.fetch = original;
+  });
+  return { calls };
+}
+
+/** Convenience for the JSON shape returned by the recording backend's init endpoint. */
+export function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}

package/src/test-utils/mock-port.ts

@@ -0,0 +1,51 @@
+import { vi } from 'vitest';
+import type { PortAdapter } from '../uploader/worker/core';
+
+/**
+ * In-memory `PortAdapter` for testing the worker `core.ts` directly without
+ * a real `Worker`.
+ *
+ * - `tabSends(msg)` simulates a tab posting into the worker (synchronous).
+ * - `received` captures everything the worker has posted back.
+ * - `next(predicate)` polls until a matching message arrives, then returns it.
+ *   The cursor advances on each call so successive `next()`s walk forward
+ *   through the buffer rather than re-matching earlier messages.
+ */
+export interface MockPort {
+  adapter: PortAdapter;
+  tabSends: (message: unknown) => void;
+  received: unknown[];
+  next: <T = unknown>(predicate: (m: unknown) => boolean) => Promise<T>;
+}
+
+export function createMockPort(): MockPort {
+  const received: unknown[] = [];
+  let handler: ((data: unknown) => void) | null = null;
+  let cursor = 0;
+  const adapter: PortAdapter = {
+    postMessage: message => received.push(message),
+    onmessage: cb => {
+      handler = cb;
+    },
+  };
+  return {
+    adapter,
+    received,
+    tabSends: message => {
+      if (handler === null) {
+        throw new Error('no handler registered yet — register the port first');
+      }
+      handler(message);
+    },
+    next: <T = unknown>(predicate: (m: unknown) => boolean): Promise<T> =>
+      vi.waitFor(() => {
+        for (let i = cursor; i < received.length; i++) {
+          if (predicate(received[i])) {
+            cursor = i + 1;
+            return received[i] as T;
+          }
+        }
+        throw new Error('no matching message yet');
+      }),
+  };
+}

package/src/test-utils/mock-ws-server.ts

@@ -0,0 +1,78 @@
+import { Server, type Client } from 'mock-socket';
+import { onTestFinished, vi } from 'vitest';
+
+/**
+ * Spin up a mock WebSocket server at `url`. Replaces `globalThis.WebSocket`
+ * so code under test (`new WebSocket(...)`) connects to the mock. Auto-stops
+ * when the current test ends.
+ *
+ * Helpers (always prefer these over reading `connections`/`messages` directly):
+ * - `waitForConnection()` resolves with each successive client connection.
+ * - `nextMessage()` resolves with the next inbound (client → server) payload.
+ * - `nextMessages(n)` resolves once `n` payloads have been received.
+ *
+ * Must be called from within a test (or a helper called from one) so vitest
+ * has a test context to attach the cleanup to.
+ */
+export function installMockWsServer(url: string): {
+  server: Server;
+  connections: Client[];
+  messages: string[];
+  waitForConnection: () => Promise<Client>;
+  nextMessage: () => Promise<string>;
+  nextMessages: (n: number) => Promise<string[]>;
+} {
+  const server = new Server(url);
+  const connections: Client[] = [];
+  const messages: string[] = [];
+  let nextConnIndex = 0;
+  let nextMsgIndex = 0;
+
+  server.on('connection', (socket: Client) => {
+    connections.push(socket);
+    // mock-socket dispatches 'server::message' as a MessageEvent — pull the payload off `.data`.
+    socket.on('message', ((event: MessageEvent | string) => {
+      const data = typeof event === 'string' ? event : event.data;
+      messages.push(typeof data === 'string' ? data : String(data));
+    }) as (m: string | Blob | ArrayBuffer | ArrayBufferView) => void);
+  });
+
+  function waitForConnection(): Promise<Client> {
+    return vi.waitFor(() => {
+      if (nextConnIndex >= connections.length) {
+        throw new Error('no new connection yet');
+      }
+      const ws = connections[nextConnIndex];
+      nextConnIndex += 1;
+      return ws;
+    });
+  }
+
+  function nextMessage(): Promise<string> {
+    return vi.waitFor(() => {
+      if (nextMsgIndex >= messages.length) {
+        throw new Error('no new message yet');
+      }
+      const message = messages[nextMsgIndex];
+      nextMsgIndex += 1;
+      return message;
+    });
+  }
+
+  async function nextMessages(n: number): Promise<string[]> {
+    const out: string[] = [];
+    for (let i = 0; i < n; i++) out.push(await nextMessage());
+    return out;
+  }
+
+  onTestFinished(() => server.stop());
+
+  return {
+    server,
+    connections,
+    messages,
+    waitForConnection,
+    nextMessage,
+    nextMessages,
+  };
+}

package/src/uploader/client-context.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const parse = vi.hoisted(() => vi.fn());
+
+vi.mock('bowser', () => ({ default: { parse } }));
+
+import { collectUserAgentContext } from './client-context';
+
+function stubBrowser(
+  overrides: {
+    navigator?: Record<string, unknown>;
+    window?: Record<string, unknown>;
+    document?: Record<string, unknown>;
+  } = {},
+) {
+  vi.stubGlobal('navigator', {
+    userAgent: 'Mozilla/5.0',
+    language: 'en-US',
+    ...overrides.navigator,
+  });
+  vi.stubGlobal('window', {
+    location: { origin: 'https://example.com', pathname: '/path' },
+    innerWidth: 1440,
+    innerHeight: 900,
+    screen: { width: 2560, height: 1440 },
+    devicePixelRatio: 2,
+    ...overrides.window,
+  });
+  vi.stubGlobal('document', {
+    referrer: 'https://referrer.example/',
+    ...overrides.document,
+  });
+}
+
+describe('collectUserAgentContext', () => {
+  beforeEach(() => {
+    parse.mockImplementation(() => ({
+      os: {},
+      browser: {},
+      platform: {},
+      engine: {},
+    }));
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('returns undefined in an SSR/Node context (no window)', () => {
+    expect(collectUserAgentContext()).toBeUndefined();
+  });
+
+  it('returns undefined when window exists but navigator does not', () => {
+    vi.stubGlobal('window', {});
+    vi.stubGlobal('navigator', undefined);
+    expect(collectUserAgentContext()).toBeUndefined();
+  });
+
+  it('captures all fields from a populated env', () => {
+    parse.mockReturnValueOnce({
+      os: { name: 'macOS' },
+      browser: { name: 'Chrome', version: '120.0.6099.225' },
+      platform: { type: 'desktop' },
+      engine: {},
+    });
+    stubBrowser();
+
+    expect(collectUserAgentContext()).toMatchObject({
+      userAgent: 'Mozilla/5.0',
+      os: 'macos',
+      browser: 'chrome',
+      browserVersion: '120',
+      mobile: false,
+      languageCode: 'en-US',
+      timeZone: expect.any(String),
+      viewportWidth: 1440,
+      viewportHeight: 900,
+      screenWidth: 2560,
+      screenHeight: 1440,
+      devicePixelRatio: 2,
+      uri: 'https://example.com/path',
+      referrer: 'https://referrer.example/',
+    });
+  });
+
+  it('flags `mobile` platform type as mobile=true', () => {
+    parse.mockReturnValueOnce({
+      os: {},
+      browser: {},
+      platform: { type: 'mobile' },
+      engine: {},
+    });
+    stubBrowser();
+    expect(collectUserAgentContext()?.mobile).toBe(true);
+  });
+
+  it('flags `tablet` platform type as mobile=true', () => {
+    parse.mockReturnValueOnce({
+      os: {},
+      browser: {},
+      platform: { type: 'tablet' },
+      engine: {},
+    });
+    stubBrowser();
+    expect(collectUserAgentContext()?.mobile).toBe(true);
+  });
+
+  it('omits os/browser/browserVersion/mobile when bowser returns nothing useful', () => {
+    stubBrowser();
+    const ctx = collectUserAgentContext();
+    expect(ctx?.os).toBeUndefined();
+    expect(ctx?.browser).toBeUndefined();
+    expect(ctx?.browserVersion).toBeUndefined();
+    expect(ctx?.mobile).toBeUndefined();
+  });
+
+  it('extracts major version from a full version string', () => {
+    parse.mockReturnValueOnce({
+      os: {},
+      browser: { name: 'Safari', version: '17.4.1' },
+      platform: {},
+      engine: {},
+    });
+    stubBrowser();
+    expect(collectUserAgentContext()?.browserVersion).toBe('17');
+  });
+
+  it('lowercases and strips whitespace from os/browser names', () => {
+    parse.mockReturnValueOnce({
+      os: { name: 'Chrome OS' },
+      browser: { name: 'Microsoft Edge', version: '120.0.0' },
+      platform: {},
+      engine: {},
+    });
+    stubBrowser();
+    const ctx = collectUserAgentContext();
+    expect(ctx?.os).toBe('chromeos');
+    expect(ctx?.browser).toBe('microsoftedge');
+  });
+
+  it('omits timeZone when Intl.DateTimeFormat throws', () => {
+    stubBrowser();
+    vi.spyOn(Intl, 'DateTimeFormat').mockImplementation(() => {
+      throw new Error('embedded context with no Intl support');
+    });
+    expect(collectUserAgentContext()?.timeZone).toBeUndefined();
+  });
+});

package/src/uploader/client-context.ts

@@ -0,0 +1,70 @@
+import Bowser from 'bowser';
+
+/**
+ * JSON-shaped values accepted in a Context — matches `google.protobuf.Struct`.
+ */
+export type ContextValue = string | number | boolean | null | ContextValue[] | { [key: string]: ContextValue };
+
+/**
+ * Browser-environment metadata captured at session init. Sent verbatim in the
+ * `context` field of the InitSession request.
+ */
+export type UserAgentContext = {
+  userAgent?: string;
+  /** Coarse OS family — `windows`, `macos`, `ios`, `android`, `linux`, or `unknown`. */
+  os?: string;
+  /** Coarse browser family — `chrome`, `firefox`, `safari`, `edge`, or `unknown`. */
+  browser?: string;
+  /** Browser major version. */
+  browserVersion?: string;
+  mobile?: boolean;
+  /** BCP-47 language tag (e.g. `en-US`). */
+  languageCode?: string;
+  /** IANA time zone (e.g. `Europe/Stockholm`). */
+  timeZone?: string;
+  /** Viewport in CSS pixels. */
+  viewportWidth?: number;
+  viewportHeight?: number;
+  /** Physical screen in CSS pixels. */
+  screenWidth?: number;
+  screenHeight?: number;
+  devicePixelRatio?: number;
+  /** Initial document URI — without query/hash to avoid leaking PII. */
+  uri?: string;
+  referrer?: string;
+};
+
+export interface ClientContext {
+  userAgent?: UserAgentContext;
+  [key: string]: ContextValue | undefined;
+}
+
+export function collectUserAgentContext(): UserAgentContext | undefined {
+  if (typeof window === 'undefined' || typeof navigator === 'undefined') return undefined;
+
+  const parsed = Bowser.parse(navigator.userAgent);
+
+  let timeZone: string | undefined;
+  try {
+    timeZone = new Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch (_e) {
+    // Some embedded contexts throw.
+  }
+
+  return {
+    userAgent: navigator.userAgent,
+    os: parsed.os.name?.toLowerCase().replace(/\s+/g, ''),
+    browser: parsed.browser.name?.toLowerCase().replace(/\s+/g, ''),
+    browserVersion: parsed.browser.version?.split('.')[0],
+    mobile: parsed.platform.type ? parsed.platform.type === 'mobile' || parsed.platform.type === 'tablet' : undefined,
+    languageCode: navigator.language,
+    timeZone,
+    viewportWidth: window.innerWidth,
+    viewportHeight: window.innerHeight,
+    screenWidth: window.screen.width,
+    screenHeight: window.screen.height,
+    devicePixelRatio: window.devicePixelRatio,
+    uri: `${window.location.origin}${window.location.pathname}`,
+    referrer: document.referrer,
+  };
+}