@sessionsight/insights 1.0.0

package/src/transport.ts

@@ -0,0 +1,241 @@
+import type { IngestPayload, PrivacyConfig } from './types.js';
+
+const MAX_KEEPALIVE_BYTES = 60_000;
+
+/**
+ * WebSocket-first transport with HTTP fallback.
+ *
+ * On init, opens a persistent WebSocket to /ws/ingest. While the socket is
+ * open, payloads are sent as WS messages (zero network tab noise). If the
+ * socket isn't ready yet, drops, or fails to connect, falls back to HTTP
+ * fetch. sendBeacon (page unload) always uses HTTP since the WS may be
+ * closing.
+ */
+export class Transport {
+  private apiUrl: string;
+  private publicApiKey: string;
+  private propertyId: string;
+  private killed = false;
+
+  // WebSocket state
+  private ws: WebSocket | null = null;
+  private wsReady = false;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectDelay = 1_000;
+  private static readonly MAX_RECONNECT_DELAY = 30_000;
+  private closed = false;
+
+  // Privacy config callback
+  private onPrivacyConfig: ((config: PrivacyConfig) => void) | null = null;
+
+  constructor(apiUrl: string, publicApiKey: string, propertyId: string) {
+    this.apiUrl = apiUrl;
+    this.publicApiKey = publicApiKey;
+    this.propertyId = propertyId;
+    this.connectWs();
+  }
+
+  /** Register a callback for when the server sends privacy configuration. */
+  onPrivacy(callback: (config: PrivacyConfig) => void): void {
+    this.onPrivacyConfig = callback;
+  }
+
+  isKilled(): boolean {
+    return this.killed;
+  }
+
+  // ── WebSocket lifecycle ────────────────────────────────────────────
+
+  private connectWs(): void {
+    if (this.killed || this.closed) return;
+
+    try {
+      const wsUrl = this.apiUrl
+        .replace(/^http/, 'ws')
+        .replace(/\/$/, '');
+      this.ws = new WebSocket(`${wsUrl}/ws/ingest?key=${encodeURIComponent(this.publicApiKey)}&propertyId=${encodeURIComponent(this.propertyId)}`);
+
+      this.ws.onopen = () => {
+        // Wait for the 'ready' message before marking as ready
+      };
+
+      this.ws.onmessage = (event) => {
+        try {
+          const msg = JSON.parse(typeof event.data === 'string' ? event.data : '');
+          if (msg.type === 'ready') {
+            this.wsReady = true;
+            this.reconnectDelay = 1_000; // reset backoff on successful connection
+            if (msg.privacy && this.onPrivacyConfig) {
+              this.onPrivacyConfig(msg.privacy);
+            }
+          }
+          if (msg.type === 'error' && msg.code === 'QUOTA_EXCEEDED') {
+            // Server says quota exceeded; stop sending but don't kill (quota resets monthly)
+          }
+        } catch {
+          // ignore non-JSON messages
+        }
+      };
+
+      this.ws.onclose = (event) => {
+        this.wsReady = false;
+        this.ws = null;
+
+        // 4001 = invalid API key, same as HTTP 401/403
+        if (event.code === 4001) {
+          this.killed = true;
+          console.warn('SessionSight: invalid API key. Ingestion disabled.');
+          return;
+        }
+
+        // 4002 = subscription required
+        if (event.code === 4002) {
+          this.killed = true;
+          return;
+        }
+
+        this.scheduleReconnect();
+      };
+
+      this.ws.onerror = () => {
+        // onclose fires after onerror, so reconnect is handled there
+      };
+    } catch {
+      this.scheduleReconnect();
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.killed || this.closed || this.reconnectTimer) return;
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connectWs();
+    }, this.reconnectDelay);
+
+    // Exponential backoff with jitter
+    this.reconnectDelay = Math.min(
+      this.reconnectDelay * 2 + Math.random() * 500,
+      Transport.MAX_RECONNECT_DELAY,
+    );
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────
+
+  async send(payload: IngestPayload): Promise<void> {
+    if (this.killed) return;
+
+    // Try WebSocket first
+    if (this.wsReady && this.ws?.readyState === WebSocket.OPEN) {
+      try {
+        this.ws.send(JSON.stringify(payload));
+        return;
+      } catch {
+        // WS send failed, fall through to HTTP
+      }
+    }
+
+    // HTTP fallback
+    const chunks = this.chunkEvents(payload);
+    for (const chunk of chunks) {
+      await this.sendHttpChunk(chunk);
+      if (this.killed) return;
+    }
+  }
+
+  /**
+   * Best-effort send for page unload. Always uses HTTP (sendBeacon or fetch)
+   * since the WebSocket may be in the process of closing.
+   */
+  sendBeacon(payload: IngestPayload): void {
+    if (this.killed) return;
+
+    const chunks = this.chunkEvents(payload);
+    for (const chunk of chunks) {
+      try {
+        const body = JSON.stringify({ ...chunk, apiKey: this.publicApiKey });
+        if (body.length > MAX_KEEPALIVE_BYTES) {
+          // sendBeacon also has size limits; fall back to fetch for oversized chunks
+          this.sendHttpChunk(chunk);
+          continue;
+        }
+        const blob = new Blob([body], { type: 'application/json' });
+        navigator.sendBeacon(`${this.apiUrl}/v1/ingest`, blob);
+      } catch {
+        // Silently fail
+      }
+    }
+  }
+
+  /** Tear down the WebSocket (called when the recorder stops). */
+  destroy(): void {
+    this.closed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      try { this.ws.close(1000); } catch {}
+      this.ws = null;
+    }
+    this.wsReady = false;
+  }
+
+  // ── Internal helpers ───────────────────────────────────────────────
+
+  /**
+   * Split a payload into chunks that each fit under the keepalive size limit.
+   * Events that are individually larger than the limit get their own chunk.
+   */
+  private chunkEvents(payload: IngestPayload): IngestPayload[] {
+    const { events, ...rest } = payload;
+    if (events.length === 0) return [payload];
+
+    // Build the envelope once to know its overhead
+    const envelopeSize = JSON.stringify({ ...rest, events: [] }).length;
+
+    const chunks: IngestPayload[] = [];
+    let currentEvents: any[] = [];
+    let currentSize = envelopeSize;
+
+    for (const event of events) {
+      const eventSize = JSON.stringify(event).length + 1; // +1 for comma separator
+
+      if (currentEvents.length > 0 && currentSize + eventSize > MAX_KEEPALIVE_BYTES) {
+        chunks.push({ ...rest, events: currentEvents });
+        currentEvents = [];
+        currentSize = envelopeSize;
+      }
+
+      currentEvents.push(event);
+      currentSize += eventSize;
+    }
+
+    if (currentEvents.length > 0) {
+      chunks.push({ ...rest, events: currentEvents });
+    }
+
+    return chunks;
+  }
+
+  private async sendHttpChunk(payload: IngestPayload): Promise<void> {
+    try {
+      const body = JSON.stringify(payload);
+      const res = await fetch(`${this.apiUrl}/v1/ingest`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.publicApiKey,
+        },
+        body,
+        keepalive: body.length < MAX_KEEPALIVE_BYTES,
+      });
+      if (res.status === 401 || res.status === 403) {
+        this.killed = true;
+        console.warn('SessionSight: invalid API key. Ingestion disabled.');
+      }
+    } catch {
+      // Silently fail — don't break the host page
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,56 @@
+export interface SessionSightConfig {
+  publicApiKey: string;
+  propertyId?: string; // defaults to 'dev' (localhost)
+  apiUrl?: string;  // defaults to https://api.sessionsight.com
+  autoRecord?: boolean; // default true — set to false for manual recording control
+  enabled?: boolean | (() => boolean); // default true — pass false to defer, or a getter function for reactive consent
+}
+
+export interface PrivacyConfig {
+  privacyMode: 'default' | 'relaxed';
+  excludePages: string[];
+}
+
+export interface RecordOptions {
+  preRecordSecs?: number; // 0-5, default 0 — include N seconds of pre-buffer
+}
+
+export interface SessionMetadata {
+  url: string;
+  referrer: string;
+  userAgent: string;
+  screenWidth: number;
+  screenHeight: number;
+  language: string;
+}
+
+export interface IngestPayload {
+  sessionId: string;
+  propertyId: string;
+  visitorId: string;
+  events: any[];
+  metadata?: SessionMetadata;
+  userId?: string | null;
+  userProperties?: Record<string, string | number | boolean>;
+  seqStart?: number;
+  seqEnd?: number;
+  final?: boolean;
+}
+
+// ── Worker message protocol ──────────────────────────────────────
+
+/** Main thread → Worker */
+export type WorkerInMessage =
+  | { type: 'init'; apiUrl: string; publicApiKey: string; propertyId: string; sessionId: string; visitorId: string }
+  | { type: 'event'; event: any; seq: number }
+  | { type: 'metadata'; metadata: SessionMetadata }
+  | { type: 'identify'; userId: string; userProperties?: Record<string, string | number | boolean> }
+  | { type: 'flush' }
+  | { type: 'flush-final' };
+
+/** Worker → Main thread */
+export type WorkerOutMessage =
+  | { type: 'ack'; seq: number }
+  | { type: 'privacy'; config: PrivacyConfig }
+  | { type: 'killed'; reason: string }
+  | { type: 'ready' };

package/src/worker-bridge.ts

@@ -0,0 +1,315 @@
+/**
+ * WorkerBridge: main-thread coordinator for the Web Worker transport.
+ *
+ * Assigns sequence numbers to events, maintains a mirror buffer of unacked
+ * events for sendBeacon fallback, and relays worker messages (privacy config,
+ * kill signals) back to the recorder.
+ *
+ * Falls back to inline Transport when Workers are unavailable.
+ */
+
+import { Transport } from './transport.js';
+import { createInlineWorker } from './worker-inline.js';
+import type { PrivacyConfig, SessionMetadata, WorkerOutMessage, IngestPayload } from './types.js';
+
+const FLUSH_INTERVAL_MS = 6_000;
+const FLUSH_EVENT_THRESHOLD = 50;
+const MAX_KEEPALIVE_BYTES = 60_000;
+
+export class WorkerBridge {
+  private worker: Worker | null = null;
+  private seq = 0;
+  private lastAckedSeq = 0;
+  private mirrorBuffer: Array<{ event: any; seq: number }> = [];
+  private _killed = false;
+
+  // Callbacks
+  private onPrivacyCallback: ((config: PrivacyConfig) => void) | null = null;
+  private onKilledCallback: (() => void) | null = null;
+
+  // Session context (needed for sendBeacon payloads)
+  private sessionId: string;
+  private propertyId: string;
+  private visitorId: string;
+  private apiUrl: string;
+  private publicApiKey: string;
+
+  // Metadata and identify state (for sendBeacon payloads)
+  private metadata: SessionMetadata | null = null;
+  private metadataSent = false;
+  private userId: string | null = null;
+  private userProperties: Record<string, string | number | boolean> | null = null;
+  private userPropertiesDirty = false;
+
+  // Fallback: inline transport + buffer when Workers unavailable
+  private fallbackTransport: Transport | null = null;
+  private fallbackBuffer: any[] = [];
+  private fallbackFlushTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    apiUrl: string,
+    publicApiKey: string,
+    propertyId: string,
+    sessionId: string,
+    visitorId: string,
+  ) {
+    this.apiUrl = apiUrl;
+    this.publicApiKey = publicApiKey;
+    this.propertyId = propertyId;
+    this.sessionId = sessionId;
+    this.visitorId = visitorId;
+
+    const worker = createInlineWorker();
+    if (worker) {
+      this.worker = worker;
+      this.worker.onmessage = this.handleWorkerMessage;
+      this.worker.onerror = (e) => {
+        console.warn('SessionSight: worker error, falling back to main thread', e);
+        this.switchToFallback();
+      };
+      this.worker.postMessage({
+        type: 'init',
+        apiUrl,
+        publicApiKey,
+        propertyId,
+        sessionId,
+        visitorId,
+      });
+    } else {
+      this.initFallback();
+    }
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────
+
+  postEvent(event: any): void {
+    if (this._killed) return;
+
+    const seq = ++this.seq;
+
+    if (this.worker) {
+      this.mirrorBuffer.push({ event, seq });
+      try {
+        this.worker.postMessage({ type: 'event', event, seq });
+      } catch (e) {
+        console.warn('SessionSight: postMessage failed, falling back', e);
+        this.switchToFallback();
+        this.fallbackBuffer.push(event);
+      }
+    } else {
+      this.fallbackBuffer.push(event);
+      if (this.fallbackBuffer.length >= FLUSH_EVENT_THRESHOLD) {
+        this.fallbackFlush();
+      }
+    }
+  }
+
+  postMetadata(metadata: SessionMetadata): void {
+    this.metadata = metadata;
+    if (this.worker) {
+      try { this.worker.postMessage({ type: 'metadata', metadata }); } catch {}
+    }
+  }
+
+  postIdentify(userId: string, userProperties?: Record<string, string | number | boolean>): void {
+    this.userId = userId;
+    if (userProperties) {
+      this.userProperties = { ...(this.userProperties || {}), ...userProperties };
+      this.userPropertiesDirty = true;
+    }
+    if (this.worker) {
+      try { this.worker.postMessage({ type: 'identify', userId, userProperties }); } catch {}
+    }
+  }
+
+  /** Trigger an immediate flush (e.g. before page exclusion pause). */
+  flush(): void {
+    if (this.worker) {
+      try { this.worker.postMessage({ type: 'flush' }); } catch {}
+    } else {
+      this.fallbackFlush();
+    }
+  }
+
+  /**
+   * Page unload handler. Sends flush-final to worker AND fires sendBeacon
+   * with unacked events from the mirror buffer as a safety net.
+   */
+  sendBeacon(): void {
+    // Tell the worker to flush and close
+    if (this.worker) {
+      try { this.worker.postMessage({ type: 'flush-final' }); } catch {}
+    }
+
+    // Main-thread sendBeacon with unacked events
+    const unacked = this.worker
+      ? this.mirrorBuffer.filter(e => e.seq > this.lastAckedSeq)
+      : this.fallbackBuffer.splice(0).map((event, i) => ({ event, seq: this.lastAckedSeq + i + 1 }));
+
+    if (unacked.length === 0) return;
+
+    const events = unacked.map(e => e.event);
+    const payload: IngestPayload = {
+      sessionId: this.sessionId,
+      propertyId: this.propertyId,
+      visitorId: this.visitorId,
+      events,
+      seqStart: unacked[0]!.seq,
+      seqEnd: unacked[unacked.length - 1]!.seq,
+      final: true,
+    };
+
+    if (this.userId) payload.userId = this.userId;
+    if (this.userPropertiesDirty && this.userProperties) {
+      payload.userProperties = { ...this.userProperties };
+    }
+    if (!this.metadataSent && this.metadata) {
+      payload.metadata = this.metadata;
+      this.metadataSent = true;
+    }
+
+    try {
+      const body = JSON.stringify({ ...payload, apiKey: this.publicApiKey });
+      if (body.length <= MAX_KEEPALIVE_BYTES) {
+        const blob = new Blob([body], { type: 'application/json' });
+        navigator.sendBeacon(`${this.apiUrl}/v1/ingest`, blob);
+      } else {
+        // Oversized: fire fetch with keepalive as best-effort
+        fetch(`${this.apiUrl}/v1/ingest`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'x-api-key': this.publicApiKey },
+          body,
+          keepalive: true,
+        }).catch(() => {});
+      }
+    } catch {
+      // Silently fail
+    }
+  }
+
+  onPrivacy(callback: (config: PrivacyConfig) => void): void {
+    this.onPrivacyCallback = callback;
+    // Also register on fallback transport if active
+    if (this.fallbackTransport) {
+      this.fallbackTransport.onPrivacy(callback);
+    }
+  }
+
+  onKilled(callback: () => void): void {
+    this.onKilledCallback = callback;
+  }
+
+  isKilled(): boolean {
+    return this._killed;
+  }
+
+  destroy(): void {
+    if (this.worker) {
+      try { this.worker.terminate(); } catch {}
+      this.worker = null;
+    }
+    if (this.fallbackTransport) {
+      this.fallbackTransport.destroy();
+      this.fallbackTransport = null;
+    }
+    if (this.fallbackFlushTimer) {
+      clearInterval(this.fallbackFlushTimer);
+      this.fallbackFlushTimer = null;
+    }
+    this.mirrorBuffer = [];
+    this.fallbackBuffer = [];
+  }
+
+  // ── Worker message handling ────────────────────────────────────────
+
+  private handleWorkerMessage = (e: MessageEvent<WorkerOutMessage>): void => {
+    try {
+      const msg = e.data;
+      switch (msg.type) {
+        case 'ack':
+          this.lastAckedSeq = msg.seq;
+          // Prune mirror buffer: remove all entries up to acked seq
+          while (this.mirrorBuffer.length > 0 && this.mirrorBuffer[0]!.seq <= msg.seq) {
+            this.mirrorBuffer.shift();
+          }
+          break;
+
+        case 'privacy':
+          if (this.onPrivacyCallback) this.onPrivacyCallback(msg.config);
+          break;
+
+        case 'killed':
+          this._killed = true;
+          if (this.onKilledCallback) this.onKilledCallback();
+          break;
+
+        case 'ready':
+          // WebSocket connected in worker
+          break;
+      }
+    } catch (err) {
+      console.warn('SessionSight: error handling worker message', err);
+    }
+  };
+
+  // ── Fallback (inline transport) ────────────────────────────────────
+
+  private initFallback(): void {
+    this.fallbackTransport = new Transport(this.apiUrl, this.publicApiKey, this.propertyId);
+    if (this.onPrivacyCallback) {
+      this.fallbackTransport.onPrivacy(this.onPrivacyCallback);
+    }
+    this.fallbackFlushTimer = setInterval(() => this.fallbackFlush(), FLUSH_INTERVAL_MS);
+  }
+
+  /** Switch from worker mode to fallback after a worker error. */
+  private switchToFallback(): void {
+    if (this.fallbackTransport) return; // already switched
+
+    // Terminate broken worker
+    if (this.worker) {
+      try { this.worker.terminate(); } catch {}
+      this.worker = null;
+    }
+
+    this.initFallback();
+
+    // Re-send unacked events from mirror
+    for (const entry of this.mirrorBuffer) {
+      this.fallbackBuffer.push(entry.event);
+    }
+    this.mirrorBuffer = [];
+  }
+
+  private fallbackFlush(): void {
+    if (!this.fallbackTransport || this.fallbackBuffer.length === 0) return;
+
+    if (this.fallbackTransport.isKilled()) {
+      this._killed = true;
+      this.fallbackBuffer = [];
+      if (this.fallbackFlushTimer) { clearInterval(this.fallbackFlushTimer); this.fallbackFlushTimer = null; }
+      if (this.onKilledCallback) this.onKilledCallback();
+      return;
+    }
+
+    const events = this.fallbackBuffer.splice(0);
+    const payload: IngestPayload = {
+      sessionId: this.sessionId,
+      propertyId: this.propertyId,
+      visitorId: this.visitorId,
+      events,
+    };
+
+    if (this.userId) payload.userId = this.userId;
+    if (this.userPropertiesDirty && this.userProperties) {
+      payload.userProperties = { ...this.userProperties };
+      this.userPropertiesDirty = false;
+    }
+    if (!this.metadataSent && this.metadata) {
+      payload.metadata = this.metadata;
+      this.metadataSent = true;
+    }
+
+    this.fallbackTransport.send(payload);
+  }
+}

package/src/worker-inline.ts

@@ -0,0 +1,23 @@
+/**
+ * Creates a Web Worker from an inlined blob URL.
+ *
+ * The WORKER_SOURCE string is imported from _worker-bundle.ts, which is generated
+ * by running `bun run build:worker` (or the full `bun run build`).
+ * Run `bun run build:worker` once before starting the dev server.
+ */
+
+import { WORKER_SOURCE } from './_worker-bundle.js';
+
+export function createInlineWorker(): Worker | null {
+  try {
+    if (typeof Worker === 'undefined' || !WORKER_SOURCE) return null;
+    const blob = new Blob([WORKER_SOURCE], { type: 'application/javascript' });
+    const url = URL.createObjectURL(blob);
+    const worker = new Worker(url);
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+    return worker;
+  } catch (e) {
+    console.warn('SessionSight: failed to create worker, using main-thread fallback', e);
+    return null;
+  }
+}