@sessionsight/insights 1.0.0 → 1.0.1

package/dist/transport.d.ts

@@ -0,0 +1,43 @@
+import type { IngestPayload, PrivacyConfig } from './types.js';
+/**
+ * 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 declare class Transport {
+    private apiUrl;
+    private publicApiKey;
+    private propertyId;
+    private killed;
+    private ws;
+    private wsReady;
+    private reconnectTimer;
+    private reconnectDelay;
+    private static readonly MAX_RECONNECT_DELAY;
+    private closed;
+    private onPrivacyConfig;
+    constructor(apiUrl: string, publicApiKey: string, propertyId: string);
+    /** Register a callback for when the server sends privacy configuration. */
+    onPrivacy(callback: (config: PrivacyConfig) => void): void;
+    isKilled(): boolean;
+    private connectWs;
+    private scheduleReconnect;
+    send(payload: IngestPayload): Promise<void>;
+    /**
+     * 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;
+    /** Tear down the WebSocket (called when the recorder stops). */
+    destroy(): void;
+    /**
+     * 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;
+    private sendHttpChunk;
+}

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+export interface SessionSightConfig {
+    publicApiKey: string;
+    propertyId?: string;
+    apiUrl?: string;
+    autoRecord?: boolean;
+    enabled?: boolean | (() => boolean);
+}
+export interface PrivacyConfig {
+    privacyMode: 'default' | 'relaxed';
+    excludePages: string[];
+}
+export interface RecordOptions {
+    preRecordSecs?: number;
+}
+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;
+}
+/** 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/dist/worker-bridge.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 type { PrivacyConfig, SessionMetadata } from './types.js';
+export declare class WorkerBridge {
+    private worker;
+    private seq;
+    private lastAckedSeq;
+    private mirrorBuffer;
+    private _killed;
+    private onPrivacyCallback;
+    private onKilledCallback;
+    private sessionId;
+    private propertyId;
+    private visitorId;
+    private apiUrl;
+    private publicApiKey;
+    private metadata;
+    private metadataSent;
+    private userId;
+    private userProperties;
+    private userPropertiesDirty;
+    private fallbackTransport;
+    private fallbackBuffer;
+    private fallbackFlushTimer;
+    constructor(apiUrl: string, publicApiKey: string, propertyId: string, sessionId: string, visitorId: string);
+    postEvent(event: any): void;
+    postMetadata(metadata: SessionMetadata): void;
+    postIdentify(userId: string, userProperties?: Record<string, string | number | boolean>): void;
+    /** Trigger an immediate flush (e.g. before page exclusion pause). */
+    flush(): void;
+    /**
+     * Page unload handler. Sends flush-final to worker AND fires sendBeacon
+     * with unacked events from the mirror buffer as a safety net.
+     */
+    sendBeacon(): void;
+    onPrivacy(callback: (config: PrivacyConfig) => void): void;
+    onKilled(callback: () => void): void;
+    isKilled(): boolean;
+    destroy(): void;
+    private handleWorkerMessage;
+    private initFallback;
+    /** Switch from worker mode to fallback after a worker error. */
+    private switchToFallback;
+    private fallbackFlush;
+}

package/dist/worker-inline.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export declare function createInlineWorker(): Worker | null;

package/dist/worker.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SessionSight Insights Web Worker
+ *
+ * Owns the event buffer, flush lifecycle, and WebSocket/HTTP transport.
+ * Receives pre-masked events from the main thread via postMessage.
+ * This file is bundled into a string and inlined as a blob URL at build time.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sessionsight/insights",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Session replay, heatmaps, and user analytics SDK for SessionSight.",
   "author": "SessionSight",
   "license": "MIT",
@@ -20,6 +20,9 @@
     "user-insights",
     "sessionsight"
   ],
+  "files": [
+    "dist"
+  ],
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/build.ts

@@ -1,47 +0,0 @@
-/**
- * Build script for the SessionSight Insights SDK.
- *
- * Supports two modes:
- *   bun run build:worker  — generate _worker-bundle.ts only (for dev)
- *   bun run build         — full build (worker + ESM + types + IIFE)
- *
- * The _worker-bundle.ts file is kept around (gitignored) so the dev
- * server can resolve the static import in worker-inline.ts.
- */
-
-import { $ } from 'bun';
-
-const workerOnly = process.argv.includes('--worker-only');
-
-// Phase 1: Build the worker to a standalone minified bundle
-const workerResult = await Bun.build({
-  entrypoints: ['src/worker.ts'],
-  format: 'esm',
-  target: 'browser',
-  minify: true,
-});
-
-if (!workerResult.success) {
-  console.error('Failed to build worker:');
-  for (const log of workerResult.logs) console.error(log);
-  process.exit(1);
-}
-
-const workerCode = await workerResult.outputs[0]!.text();
-console.log(`Worker bundle: ${(workerCode.length / 1024).toFixed(1)}KB minified`);
-
-// Phase 2: Write the generated bundle module
-const bundleSource = `// AUTO-GENERATED by build.ts. Do not edit.\nexport const WORKER_SOURCE = ${JSON.stringify(workerCode)};\n`;
-await Bun.write('src/_worker-bundle.ts', bundleSource);
-console.log('Generated src/_worker-bundle.ts');
-
-if (workerOnly) {
-  console.log('Worker build complete (dev mode).');
-  process.exit(0);
-}
-
-// Phase 3: Build ESM, declarations, and IIFE
-await $`bun build src/index.ts --outdir dist --format esm --target browser`;
-await $`bunx tsc --emitDeclarationOnly --declaration --outDir dist`;
-await $`bun build src/iife.ts --outfile dist/sessionsight.js --format iife --target browser --minify`;
-console.log('Full build complete.');

package/src/_worker-bundle.d.ts

@@ -1,3 +0,0 @@
-// Type stub for the build-time generated worker bundle.
-// The actual file is created by build.ts and deleted after build.
-export declare const WORKER_SOURCE: string;

package/src/iife.ts

@@ -1,3 +0,0 @@
-import SessionSight from './index.js';
-
-(window as any).SessionSight = SessionSight;

package/src/index.ts

@@ -1,240 +0,0 @@
-import { Recorder } from './recorder.js';
-import { WorkerBridge } from './worker-bridge.js';
-import type { SessionSightConfig, RecordOptions, PrivacyConfig } from './types.js';
-import { normalizeApiUrl, getOrCreateVisitorId } from '@sessionsight/sdk-shared';
-
-const PRIVACY_CACHE_KEY = 'sessionsight_privacy_config';
-
-let recorder: Recorder | null = null;
-let pendingConfig: { bridge: WorkerBridge; propertyId: string; autoRecord: boolean } | null = null;
-let enabledGetter: (() => boolean) | null = null;
-let enabledPollTimer: ReturnType<typeof setInterval> | null = null;
-let lastEnabledValue: boolean | null = null;
-let visibilityResurrectionListener: (() => void) | null = null;
-/** The last privacy config received from the server, used for session resurrection. */
-let lastPrivacyConfig: PrivacyConfig = { privacyMode: 'default', excludePages: [] };
-
-/** Stored config for recreating the recorder after visibility-based session end. */
-let lastInitConfig: { bridge: WorkerBridge; propertyId: string; autoRecord: boolean } | null = null;
-let storedVisitorId: string = '';
-
-/** Read cached privacy config from sessionStorage, or return defaults. */
-function getCachedPrivacyConfig(propertyId: string): PrivacyConfig {
-  try {
-    const raw = sessionStorage.getItem(PRIVACY_CACHE_KEY);
-    if (raw) {
-      const parsed = JSON.parse(raw);
-      if (parsed.propertyId === propertyId) {
-        return { privacyMode: parsed.privacyMode, excludePages: parsed.excludePages };
-      }
-    }
-  } catch {}
-  return { privacyMode: 'default', excludePages: [] };
-}
-
-/** Write privacy config to sessionStorage for use on subsequent page loads. */
-function cachePrivacyConfig(propertyId: string, config: PrivacyConfig): void {
-  try {
-    sessionStorage.setItem(PRIVACY_CACHE_KEY, JSON.stringify({
-      propertyId,
-      privacyMode: config.privacyMode,
-      excludePages: config.excludePages,
-    }));
-  } catch {}
-}
-
-function pollEnabled(): void {
-  if (!enabledGetter) return;
-  const current = enabledGetter();
-  if (current === lastEnabledValue) return;
-  lastEnabledValue = current;
-
-  if (current) {
-    if (recorder || !pendingConfig) return;
-    const { bridge, propertyId, autoRecord } = pendingConfig;
-    pendingConfig = null;
-    recorder = new Recorder(bridge, propertyId, storedVisitorId, { privacyMode: lastPrivacyConfig.privacyMode, excludePages: lastPrivacyConfig.excludePages });
-    recorder.start(autoRecord);
-  } else {
-    if (!recorder) return;
-    pendingConfig = {
-      bridge: recorder.getBridge(),
-      propertyId: recorder.getPropertyId(),
-      autoRecord: true,
-    };
-    recorder.stop();
-    recorder = null;
-  }
-}
-
-/**
- * SDK-level visibility listener that lives independently of the recorder.
- * When a recorder ends itself due to the tab being hidden for too long,
- * this listener creates a fresh recorder when the tab becomes visible again.
- */
-function handleVisibilityResurrection(): void {
-  if (document.visibilityState !== 'visible') return;
-  if (!recorder?.endedByVisibility) return;
-  if (!lastInitConfig) return;
-
-  // If using an enabled getter and it currently returns false, don't resurrect
-  if (enabledGetter && !enabledGetter()) return;
-
-  const { bridge, propertyId, autoRecord } = lastInitConfig;
-  recorder = new Recorder(bridge, propertyId, storedVisitorId, { privacyMode: lastPrivacyConfig.privacyMode, excludePages: lastPrivacyConfig.excludePages });
-  recorder.start(autoRecord);
-}
-
-function startPolling(): void {
-  if (enabledPollTimer) return;
-  enabledPollTimer = setInterval(pollEnabled, 1000);
-}
-
-function stopPolling(): void {
-  if (enabledPollTimer) {
-    clearInterval(enabledPollTimer);
-    enabledPollTimer = null;
-  }
-}
-
-const SessionSight = {
-  init(config: SessionSightConfig): void {
-    try {
-      if (typeof window === 'undefined' || typeof document === 'undefined') {
-        console.warn('SessionSight: browser environment required. Skipping initialization in SSR/Node.');
-        return;
-      }
-
-      if (recorder || pendingConfig) {
-        console.warn('SessionSight is already initialized.');
-        return;
-      }
-
-      if (!config.publicApiKey) {
-        console.error('SessionSight: publicApiKey is required.');
-        return;
-      }
-
-      const propertyId = config.propertyId || 'dev';
-      const apiUrl = normalizeApiUrl(config.apiUrl || '');
-      const autoRecord = config.autoRecord !== false;
-
-      // Use cached privacy config if available, otherwise start with most restrictive defaults
-      const cachedConfig = getCachedPrivacyConfig(propertyId);
-      lastPrivacyConfig = cachedConfig;
-      const privacyMode = cachedConfig.privacyMode;
-      const excludePages = cachedConfig.excludePages;
-
-      // Generate session context
-      const sessionId = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
-        ? crypto.randomUUID()
-        : `${Date.now()}-${Math.random().toString(36).slice(2)}`;
-      storedVisitorId = getOrCreateVisitorId();
-
-      const bridge = new WorkerBridge(apiUrl, config.publicApiKey, propertyId, sessionId, storedVisitorId);
-
-      // Listen for server-delivered privacy config from the worker/WebSocket
-      bridge.onPrivacy((serverConfig) => {
-        lastPrivacyConfig = serverConfig;
-        cachePrivacyConfig(propertyId, serverConfig);
-        if (recorder) {
-          recorder.applyPrivacyConfig(serverConfig);
-        }
-      });
-
-      // Store config for session resurrection after visibility-based session end
-      lastInitConfig = { bridge, propertyId, autoRecord };
-
-      // Register SDK-level visibility listener (lives independently of recorder lifecycle)
-      if (!visibilityResurrectionListener) {
-        visibilityResurrectionListener = handleVisibilityResurrection;
-        document.addEventListener('visibilitychange', visibilityResurrectionListener);
-      }
-
-      const enabledOption = config.enabled;
-
-      if (typeof enabledOption === 'function') {
-        enabledGetter = enabledOption;
-        const initialValue = enabledGetter();
-        lastEnabledValue = initialValue;
-
-        if (initialValue) {
-          recorder = new Recorder(bridge, propertyId, storedVisitorId, { privacyMode, excludePages });
-          recorder.start(autoRecord);
-        } else {
-          pendingConfig = { bridge, propertyId, autoRecord };
-        }
-
-        startPolling();
-      } else {
-        const enabled = enabledOption !== false;
-        if (enabled) {
-          recorder = new Recorder(bridge, propertyId, storedVisitorId, { privacyMode, excludePages });
-          recorder.start(autoRecord);
-        } else {
-          pendingConfig = { bridge, propertyId, autoRecord };
-        }
-      }
-    } catch (e) {
-      console.warn('SessionSight: failed to initialize', e);
-    }
-  },
-
-  setEnabled(enabled: boolean): void {
-    if (enabled) {
-      if (recorder) return;
-      if (!pendingConfig) {
-        console.warn('SessionSight: call init() before setEnabled().');
-        return;
-      }
-      const { bridge, propertyId, autoRecord } = pendingConfig;
-      pendingConfig = null;
-      recorder = new Recorder(bridge, propertyId, storedVisitorId, { privacyMode: lastPrivacyConfig.privacyMode, excludePages: lastPrivacyConfig.excludePages });
-      recorder.start(autoRecord);
-    } else {
-      if (!recorder) return;
-      pendingConfig = {
-        bridge: recorder.getBridge(),
-        propertyId: recorder.getPropertyId(),
-        autoRecord: true,
-      };
-      recorder.stop();
-      recorder = null;
-    }
-    lastEnabledValue = enabled;
-  },
-
-  record(options?: RecordOptions): void {
-    if (recorder) {
-      recorder.beginRecording(options);
-    }
-  },
-
-  stop(): void {
-    stopPolling();
-    enabledGetter = null;
-    lastEnabledValue = null;
-    lastInitConfig = null;
-    if (visibilityResurrectionListener) {
-      document.removeEventListener('visibilitychange', visibilityResurrectionListener);
-      visibilityResurrectionListener = null;
-    }
-    if (recorder) {
-      recorder.stop();
-      recorder = null;
-    }
-    pendingConfig = null;
-  },
-
-  identify(userId: string, properties?: Record<string, string | number | boolean>): void {
-    if (recorder) {
-      recorder.identify(userId, properties);
-    }
-  },
-
-  getVisitorId(): string | null {
-    return recorder ? recorder.getVisitorId() : null;
-  },
-};
-
-export default SessionSight;