@cedarai/session-replay-sdk 0.1.0

package/src/transport.test.ts

@@ -0,0 +1,256 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { Transport } from './transport.js';
+import type { SessionEvent, SDKConfig } from './types.js';
+
+function makeConfig(overrides: Partial<SDKConfig> = {}): SDKConfig {
+  return {
+    serverUrl: 'https://replay.getcedar.ai',
+    cedarSessionId: 'test-session-123',
+    batchIntervalMs: 5000,
+    batchMaxSize: 1024 * 512,
+    ...overrides,
+  };
+}
+
+function makeRRWebEvent(timestamp = Date.now()): SessionEvent {
+  return { type: 'rrweb', data: { type: 2, timestamp, data: { node: { type: 0 } } } };
+}
+
+function makeConsoleEvent(timestamp = Date.now()): SessionEvent {
+  return { type: 'console', timestamp, data: { level: 'log', args: ['test'] } };
+}
+
+describe('Transport', () => {
+  let transport: Transport;
+  let fetchSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    // Mock fetch globally
+    fetchSpy = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    vi.stubGlobal('fetch', fetchSpy);
+  });
+
+  afterEach(() => {
+    transport?.stop();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  // ── Event queuing ────────────────────────────────────────────────────
+
+  describe('event queuing', () => {
+    it('queues events without immediately sending', () => {
+      transport = new Transport(makeConfig());
+      transport.start();
+      transport.enqueue(makeRRWebEvent());
+      transport.enqueue(makeConsoleEvent());
+
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+
+    it('does not send events before start() is called', () => {
+      transport = new Transport(makeConfig({ batchIntervalMs: 100 }));
+      transport.enqueue(makeRRWebEvent());
+
+      vi.advanceTimersByTime(200);
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── Flush on interval ────────────────────────────────────────────────
+
+  describe('flush on interval', () => {
+    it('flushes after batchIntervalMs', () => {
+      transport = new Transport(makeConfig({ batchIntervalMs: 5000 }));
+      transport.start();
+      transport.enqueue(makeRRWebEvent());
+
+      vi.advanceTimersByTime(5000);
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not flush when queue is empty', () => {
+      transport = new Transport(makeConfig({ batchIntervalMs: 5000 }));
+      transport.start();
+
+      vi.advanceTimersByTime(5000);
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+
+    it('flushes repeatedly on each interval', () => {
+      transport = new Transport(makeConfig({ batchIntervalMs: 1000 }));
+      transport.start();
+
+      transport.enqueue(makeRRWebEvent());
+      vi.advanceTimersByTime(1000);
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+
+      transport.enqueue(makeConsoleEvent());
+      vi.advanceTimersByTime(1000);
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  // ── Flush on size ────────────────────────────────────────────────────
+
+  describe('flush on size', () => {
+    it('flushes when batch exceeds batchMaxSize', () => {
+      transport = new Transport(makeConfig({ batchMaxSize: 100 })); // tiny limit
+      transport.start();
+
+      // Each event is ~60+ bytes JSON, so 2 should exceed 100 bytes
+      transport.enqueue(makeRRWebEvent());
+      transport.enqueue(makeRRWebEvent());
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // ── Payload format ───────────────────────────────────────────────────
+
+  describe('payload format', () => {
+    it('sends correct payload structure to serverUrl/api/ingest', () => {
+      transport = new Transport(makeConfig({ batchIntervalMs: 1000 }));
+      transport.start();
+      transport.enqueue(makeRRWebEvent(1000));
+      transport.enqueue(makeConsoleEvent(1100));
+
+      vi.advanceTimersByTime(1000);
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      const [url, options] = fetchSpy.mock.calls[0];
+      expect(url).toBe('https://replay.getcedar.ai/api/ingest');
+      expect(options.method).toBe('POST');
+      expect(options.headers['Content-Type']).toBe('application/json');
+
+      const body = JSON.parse(options.body);
+      expect(body.sessionId).toBe('test-session-123');
+      expect(body.events).toHaveLength(2);
+      expect(body.events[0].type).toBe('rrweb');
+      expect(body.events[1].type).toBe('console');
+      expect(typeof body.batchTimestamp).toBe('number');
+      expect(typeof body.startedAt).toBe('number');
+    });
+
+    it('clears the queue after successful flush', () => {
+      transport = new Transport(makeConfig({ batchIntervalMs: 1000 }));
+      transport.start();
+      transport.enqueue(makeRRWebEvent());
+
+      vi.advanceTimersByTime(1000);
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+
+      // Next interval: no events, should not send
+      vi.advanceTimersByTime(1000);
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // ── Manual flush ─────────────────────────────────────────────────────
+
+  describe('flush()', () => {
+    it('immediately sends queued events', () => {
+      transport = new Transport(makeConfig());
+      transport.start();
+      transport.enqueue(makeRRWebEvent());
+
+      transport.flush();
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('does nothing if queue is empty', () => {
+      transport = new Transport(makeConfig());
+      transport.start();
+
+      transport.flush();
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── stop() ───────────────────────────────────────────────────────────
+
+  describe('stop()', () => {
+    it('flushes remaining events on stop', () => {
+      transport = new Transport(makeConfig());
+      transport.start();
+      transport.enqueue(makeRRWebEvent());
+
+      transport.stop();
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('stops the interval timer', () => {
+      transport = new Transport(makeConfig({ batchIntervalMs: 1000 }));
+      transport.start();
+      transport.stop();
+
+      transport.enqueue(makeRRWebEvent());
+      vi.advanceTimersByTime(2000);
+      // Only the flush from stop(), not from interval
+      expect(fetchSpy).toHaveBeenCalledTimes(0); // stop flushed empty, enqueue after stop is ignored
+    });
+  });
+
+  // ── Self-interception guard ──────────────────────────────────────────
+
+  describe('self-interception', () => {
+    it('uses the provided originalFetch, not window.fetch', () => {
+      const originalFetch = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+      transport = new Transport(makeConfig({ batchIntervalMs: 1000 }), originalFetch);
+      transport.start();
+      transport.enqueue(makeRRWebEvent());
+
+      vi.advanceTimersByTime(1000);
+
+      // Should call originalFetch, not window.fetch
+      expect(originalFetch).toHaveBeenCalledTimes(1);
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── sendBeacon on unload ─────────────────────────────────────────────
+
+  describe('sendBeacon fallback', () => {
+    it('uses sendBeacon when flushOnUnload is called', () => {
+      const sendBeaconSpy = vi.fn().mockReturnValue(true);
+      vi.stubGlobal('navigator', { sendBeacon: sendBeaconSpy });
+
+      transport = new Transport(makeConfig());
+      transport.start();
+      transport.enqueue(makeRRWebEvent());
+
+      transport.flushOnUnload();
+
+      expect(sendBeaconSpy).toHaveBeenCalledTimes(1);
+      const [url] = sendBeaconSpy.mock.calls[0];
+      expect(url).toContain('https://replay.getcedar.ai/api/ingest');
+      expect(url).toContain('encoding=gzip');
+    });
+
+    it('does nothing on unload if queue is empty', () => {
+      const sendBeaconSpy = vi.fn().mockReturnValue(true);
+      vi.stubGlobal('navigator', { sendBeacon: sendBeaconSpy });
+
+      transport = new Transport(makeConfig());
+      transport.start();
+
+      transport.flushOnUnload();
+      expect(sendBeaconSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── Error resilience ─────────────────────────────────────────────────
+
+  describe('error resilience', () => {
+    it('does not throw if fetch fails', () => {
+      fetchSpy.mockRejectedValue(new Error('Network error'));
+
+      transport = new Transport(makeConfig({ batchIntervalMs: 1000 }));
+      transport.start();
+      transport.enqueue(makeRRWebEvent());
+
+      expect(() => vi.advanceTimersByTime(1000)).not.toThrow();
+    });
+  });
+});

package/src/transport.ts

@@ -0,0 +1,114 @@
+import type { SessionEvent, SDKConfig, BatchPayload } from './types.js';
+
+export class Transport {
+  private config: SDKConfig;
+  private queue: SessionEvent[] = [];
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private started = false;
+  private startedAt: number = Date.now();
+  private fetchFn: typeof fetch;
+
+  /**
+   * @param config SDK configuration
+   * @param originalFetch Original fetch reference to avoid self-interception.
+   *   If not provided, uses globalThis.fetch.
+   */
+  constructor(config: SDKConfig, originalFetch?: typeof fetch) {
+    this.config = config;
+    const fn = originalFetch ?? globalThis.fetch;
+    this.fetchFn = fn.bind(globalThis);
+  }
+
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.startedAt = Date.now();
+
+    const interval = this.config.batchIntervalMs ?? 5000;
+    this.timer = setInterval(() => {
+      this.flush();
+    }, interval);
+  }
+
+  stop(): void {
+    if (!this.started) return;
+    this.started = false;
+
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+
+    this.flush();
+  }
+
+  enqueue(event: SessionEvent): void {
+    if (!this.started) return;
+
+    this.queue.push(event);
+
+    // Check if batch exceeds max size
+    const maxSize = this.config.batchMaxSize ?? 1024 * 512;
+    const estimatedSize = this.estimateQueueSize();
+    if (estimatedSize >= maxSize) {
+      this.flush();
+    }
+  }
+
+  flush(): void {
+    if (this.queue.length === 0) return;
+
+    const events = this.queue.splice(0);
+    const payload = this.buildPayload(events);
+
+    // Fire and forget — don't block on the response
+    this.fetchFn(`${this.config.serverUrl}/api/ingest`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    }).catch(() => {
+      // Silently ignore send failures — don't crash the host app
+    });
+  }
+
+  /**
+   * Flush via sendBeacon for page unload. sendBeacon cannot set custom headers,
+   * so we send as a Blob and indicate gzip via query param.
+   */
+  flushOnUnload(): void {
+    if (this.queue.length === 0) return;
+
+    const events = this.queue.splice(0);
+    const payload = this.buildPayload(events);
+    const body = JSON.stringify(payload);
+
+    // sendBeacon has a ~64KB limit. For now, send uncompressed JSON as a Blob.
+    // TODO: Add gzip compression (pako) and truncation for large payloads.
+    const blob = new Blob([body], { type: 'application/json' });
+    const url = `${this.config.serverUrl}/api/ingest?encoding=gzip`;
+
+    navigator.sendBeacon(url, blob);
+  }
+
+  private buildPayload(events: SessionEvent[]): BatchPayload {
+    return {
+      sessionId: this.config.cedarSessionId,
+      batchTimestamp: Date.now(),
+      startedAt: this.startedAt,
+      userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+      viewportWidth: typeof window !== 'undefined' ? window.innerWidth : 0,
+      viewportHeight: typeof window !== 'undefined' ? window.innerHeight : 0,
+      url: typeof window !== 'undefined' ? window.location.href : '',
+      events,
+    };
+  }
+
+  private estimateQueueSize(): number {
+    // Rough estimate: JSON.stringify each event and sum lengths
+    let size = 0;
+    for (const event of this.queue) {
+      size += JSON.stringify(event).length;
+    }
+    return size;
+  }
+}

package/src/types.ts

@@ -0,0 +1,101 @@
+export interface SDKConfig {
+  serverUrl: string;
+  cedarSessionId: string;
+  batchIntervalMs?: number;     // default: 5000
+  batchMaxSize?: number;        // default: 512KB
+  console?: ConsoleConfig;
+}
+
+export interface ConsoleConfig {
+  log?: boolean;     // default: true
+  info?: boolean;    // default: true
+  warn?: boolean;    // default: true
+  error?: boolean;   // default: true
+  debug?: boolean;   // default: true
+}
+
+export interface RecorderConfig {
+  checkoutEveryNms?: number;
+  blockSelector?: string;
+  maskAllInputs?: boolean;
+  inlineStylesheet?: boolean;
+  sampling?: Record<string, unknown>;
+}
+
+// Events the SDK produces
+export type SessionEvent =
+  | RRWebSessionEvent
+  | NetworkSessionEvent
+  | ConsoleSessionEvent
+  | ErrorSessionEvent
+  | CustomSessionEvent;
+
+export interface RRWebSessionEvent {
+  type: 'rrweb';
+  data: Record<string, unknown>;
+}
+
+export interface NetworkSessionEvent {
+  type: 'network';
+  timestamp: number;
+  data: {
+    id: string;
+    method: string;
+    url: string;
+    graphqlOperationName?: string;
+    requestHeaders?: Record<string, string>;
+    requestBody?: string;
+    status?: number;
+    responseHeaders?: Record<string, string>;
+    responseBody?: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    error?: string;
+  };
+}
+
+export interface ConsoleSessionEvent {
+  type: 'console';
+  timestamp: number;
+  data: {
+    level: 'log' | 'warn' | 'error' | 'info' | 'debug';
+    args: string[];
+    trace?: string;
+  };
+}
+
+export interface ErrorSessionEvent {
+  type: 'error';
+  timestamp: number;
+  data: {
+    message: string;
+    stack?: string;
+    source?: string;
+    lineno?: number;
+    colno?: number;
+    type: 'uncaught' | 'unhandledrejection' | 'manual';
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+  };
+}
+
+export interface CustomSessionEvent {
+  type: 'custom';
+  timestamp: number;
+  data: {
+    name: string;
+    properties?: Record<string, unknown>;
+  };
+}
+
+export interface BatchPayload {
+  sessionId: string;
+  batchTimestamp: number;
+  startedAt: number;
+  userAgent: string;
+  viewportWidth: number;
+  viewportHeight: number;
+  url: string;
+  events: SessionEvent[];
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'happy-dom',
+    include: ['src/**/*.test.ts'],
+  },
+});