@sessionsight/insights 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SessionSight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# @sessionsight/insights
+
+The SessionSight SDK captures user sessions on your website — recording DOM state, clicks, scrolls, mouse movement, form interactions, and page navigations. The data powers session replay, heatmaps, conversion funnels, and form analytics in the SessionSight dashboard.
+
+## Installation
+
+```bash
+npm install @sessionsight/insights
+```
+
+Or via script tag:
+
+```html
+<script src="https://cdn.sessionsight.com/sessionsight.js"></script>
+```
+
+## Quick Start
+
+### npm / ES Module
+
+```ts
+import SessionSight from '@sessionsight/insights';
+
+SessionSight.init({
+  publicApiKey: 'sessionsight_pub_...',
+  propertyId: 'your-property-id',
+});
+```
+
+### Script tag
+
+```html
+<script src="https://cdn.sessionsight.com/sessionsight.js"></script>
+<script>
+  SessionSight.init({
+    publicApiKey: 'sessionsight_pub_...',
+    propertyId: 'your-property-id',
+  });
+</script>
+```
+
+That's it. Recording starts automatically.
+
+## API
+
+### `SessionSight.init(config)`
+
+Initializes the SDK. Must be called before any other method.
+
+```ts
+SessionSight.init({
+  publicApiKey: 'sessionsight_pub_...', // Required. Your public API key from the dashboard.
+  propertyId: 'your-property-id', // Required. Your property ID from the dashboard.
+  apiUrl: 'https://api.sessionsight.com', // Optional. Override the API endpoint.
+  autoRecord: true, // Optional. Set to false for manual recording control.
+});
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `publicApiKey` | `string` | **required** | Your public API key from the SessionSight dashboard (API Keys page). |
+| `propertyId` | `string` | `'dev'` | Your property ID from the SessionSight dashboard (Settings → Properties). Defaults to `'dev'` for local development. |
+| `apiUrl` | `string` | `https://api.sessionsight.com` | API endpoint. Override for self-hosted or local development. |
+| `autoRecord` | `boolean` | `true` | When `true`, recording starts immediately. When `false`, the SDK captures into a 5-second rolling pre-buffer but doesn't send data until `record()` is called. |
+| `enabled` | `boolean \| (() => boolean)` | `true` | Controls whether the SDK is active. Pass `false` to defer setup, or a getter function for reactive consent (the SDK polls the getter every second and automatically starts/stops when the value changes). |
+
+### `SessionSight.setEnabled(enabled)`
+
+Manually toggles the SDK on or off after `init()` has been called. Only needed when `enabled` was passed as a static `boolean`. If you passed a getter function, the SDK manages this automatically.
+
+```ts
+// Initialize with tracking deferred
+SessionSight.init({
+  publicApiKey: 'sessionsight_pub_...',
+  propertyId: 'your-property-id',
+  enabled: false,
+});
+
+// Later, after user grants consent:
+SessionSight.setEnabled(true);
+
+// If user revokes consent:
+SessionSight.setEnabled(false);
+```
+
+When disabled, the SDK tears down all listeners and flushes remaining events. When re-enabled, it creates a fresh session. Calling `setEnabled(true)` when already enabled (or `false` when already disabled) is a no-op.
+
+### `SessionSight.record(options?)`
+
+Starts recording and sending data to the server. Only needed when `autoRecord: false`.
+
+```ts
+// Start recording from this moment
+SessionSight.record();
+
+// Start recording, including the last 3 seconds of activity
+SessionSight.record({ preRecordSecs: 3 });
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `preRecordSecs` | `number` | `0` | Include up to 5 seconds of pre-buffered events captured before `record()` was called. |
+
+Calling `record()` when already recording is a no-op.
+
+### `SessionSight.identify(userId, properties?)`
+
+Associates the current session with a user ID and optional user properties. Call this after your user logs in.
+
+```ts
+// Identify with just a user ID
+SessionSight.identify('user-123');
+
+// Identify with user properties for segmentation
+SessionSight.identify('user-123', {
+  plan: 'pro',
+  accountType: 'enterprise',
+  role: 'admin',
+});
+```
+
+The user ID appears in the SessionSight dashboard alongside session data. No PII is required — use any stable identifier.
+
+Properties are stored on the visitor profile and can be used for segmentation — filtering sessions, heatmaps, and funnels by user attributes. Use categorical/descriptive values here (plan tier, account type, role). For monetary values (purchase amounts, revenue), use the [@sessionsight/goals](../goals/README.md) SDK instead.
+
+### `SessionSight.getVisitorId()`
+
+Returns the current visitor ID, or `null` if the SDK hasn't been initialized.
+
+```ts
+const visitorId = SessionSight.getVisitorId();
+// Send to your backend for use with the Flags SDK
+```
+
+The visitor ID is also available as a first-party cookie (`ss_vid`) on your domain, so your backend can read it directly from the request without any frontend code.
+
+### `SessionSight.stop()`
+
+Stops recording, flushes any remaining events, and tears down all listeners.
+
+```ts
+SessionSight.stop();
+```
+
+After calling `stop()`, you must call `init()` again to start a new session.
+
+## User-Triggered Recording
+
+For cases where you only want to record specific interactions (e.g. after a user hits an error, or during a specific flow):
+
+```ts
+// Initialize without auto-recording
+SessionSight.init({
+  publicApiKey: 'sessionsight_pub_...',
+  propertyId: 'your-property-id',
+  autoRecord: false,
+});
+
+// Later, when something interesting happens:
+document.getElementById('checkout-btn').addEventListener('click', () => {
+  // Start recording, including the last 5 seconds of what the user was doing
+  SessionSight.record({ preRecordSecs: 5 });
+});
+```
+
+The pre-buffer captures DOM state, mouse movements, clicks, and all other events in a rolling 5-second window. When `record()` is called, those buffered events are included in the recording so you can see what led up to the trigger.
+
+## Form Tracking
+
+Forms are automatically tracked. The SDK captures:
+- When a user starts interacting with a form
+- Which fields they focus on and how long they spend on each
+- Whether each field was filled (boolean only — **no field values are captured**)
+- Form submission with completion metrics
+
+### Naming Forms
+
+By default, forms are identified by their page URL and position. Add a `data-ss-form` attribute for a custom name:
+
+```html
+<form data-ss-form="Signup Form">
+  <!-- fields -->
+</form>
+```
+
+The name appears in the Form Analytics section of the dashboard and can also be changed from there.
+
+## What Gets Captured
+
+| Data | Captured | Notes |
+|------|----------|-------|
+| DOM state | Yes | Full page snapshot with inline CSS for replay |
+| Mouse movement | Yes | Position sampled every 500ms |
+| Clicks | Yes | All clicks with coordinates; button/link clicks with labels |
+| Scroll depth | Yes | Scroll position sampled every 1s |
+| Page navigations | Yes | SPA navigations detected via History API |
+| Form field interactions | Yes | Focus/blur timing, filled state (boolean) |
+| Form field values | **No** | Never captured — only whether a field has a value |
+| Passwords | **No** | Never captured |
+| Cookies / localStorage | **No** | Never captured |
+| Network requests | **No** | Not captured |
+
+## Privacy & Data Attributes
+
+The SDK uses a three-layer privacy system:
+
+1. **Automatic PII detection** (always active): emails, phone numbers, credit card numbers, SSNs, IBANs, and API keys are automatically replaced with `[REDACTED]` before data leaves the browser. This cannot be disabled.
+
+2. **Privacy mode** (configured per-property in the dashboard):
+   - **Default**: all text is scrambled using a character-width-preserving algorithm. Replays show layout and behavior but text is unreadable.
+   - **Relaxed**: text is shown as-is, with only detected PII redacted.
+
+3. **HTML data attributes** (element-level overrides):
+
+| Attribute | Effect |
+|-----------|--------|
+| `data-ss-mask` | Force scrambling on this element and its children, even in relaxed mode |
+| `data-ss-unmask` | Allow readable text (PII still redacted) on this element and its children, even in default mode |
+| `data-ss-exclude` | Block recording entirely. Element is replaced with an empty placeholder that preserves dimensions |
+
+```html
+<nav data-ss-unmask>Readable navigation links</nav>
+<div data-ss-mask>Scrambled even in relaxed mode</div>
+<div data-ss-exclude>Completely hidden from recordings</div>
+```
+
+Data attributes cascade to child elements. The nearest ancestor with `data-ss-mask` or `data-ss-unmask` wins. `data-ss-exclude` always takes priority.
+
+You can also exclude entire pages from recording using glob patterns configured in the dashboard (e.g., `/admin/*`, `/checkout`).
+
+## Visitor Tracking
+
+The SDK generates a persistent `visitorId` stored in both `localStorage` (`sessionsight_visitor_id`) and a first-party cookie (`ss_vid`). This allows tracking the same visitor across sessions on the same device/browser. The ID is a random UUID with no connection to personal information.
+
+The cookie makes the visitor ID available to your backend on every request, which is useful for passing it to the Feature Flags SDK for segment-based targeting.
+
+In incognito/private browsing, a session-only ID is used instead.
+
+## Cookie Consent
+
+If your site requires cookie consent before tracking, pass a getter function to `enabled`. The SDK polls it every second and automatically starts or stops when the value changes:
+
+```ts
+SessionSight.init({
+  publicApiKey: 'sessionsight_pub_...',
+  propertyId: 'your-property-id',
+  enabled: () => hasConsent,
+});
+```
+
+No data is collected, no cookies are set, and no listeners are attached until the getter returns `true`. If the user later revokes consent, the SDK tears down automatically.
+
+This works with any framework's reactive state:
+
+```ts
+// Svelte 5
+let consent = $state(false);
+SessionSight.init({ ..., enabled: () => consent });
+
+// Vue
+const consent = ref(false);
+SessionSight.init({ ..., enabled: () => consent.value });
+
+// React (via ref)
+const consentRef = useRef(false);
+SessionSight.init({ ..., enabled: () => consentRef.current });
+
+// Solid
+const [consent] = createSignal(false);
+SessionSight.init({ ..., enabled: consent });
+```
+
+Alternatively, pass a static `boolean` and use `setEnabled()` to toggle manually.
+
+## Build Outputs
+
+| File | Format | Use |
+|------|--------|-----|
+| `dist/index.js` | ES Module | `import SessionSight from '@sessionsight/insights'` |
+| `dist/index.d.ts` | TypeScript declarations | Type support |
+| `dist/sessionsight.js` | IIFE (minified) | `<script>` tag, exposes `window.SessionSight` |
+
+Build with:
+
+```bash
+bun run build
+```

package/build.ts

@@ -0,0 +1,47 @@
+/**
+ * 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/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@sessionsight/insights",
+  "version": "1.0.0",
+  "description": "Session replay, heatmaps, and user analytics SDK for SessionSight.",
+  "author": "SessionSight",
+  "license": "MIT",
+  "homepage": "https://sessionsight.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SessionSight/sdks.git",
+    "directory": "packages/insights"
+  },
+  "bugs": {
+    "url": "https://github.com/SessionSight/sdks/issues"
+  },
+  "keywords": [
+    "analytics",
+    "session-replay",
+    "heatmaps",
+    "user-insights",
+    "sessionsight"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "import": "./dist/index.js",
+        "types": "./dist/index.d.ts"
+      }
+    }
+  },
+  "scripts": {
+    "build": "bun run build.ts",
+    "build:worker": "bun run build.ts --worker-only",
+    "dev:setup": "bun run build.ts --worker-only"
+  },
+  "dependencies": {
+    "@sessionsight/sdk-shared": "workspace:*",
+    "rrweb": "^2.0.0-alpha.20"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/_worker-bundle.d.ts

@@ -0,0 +1,3 @@
+// 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

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

package/src/index.ts

@@ -0,0 +1,240 @@
+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;