@sessionvision/core 0.2.0

package/README.md

@@ -0,0 +1,361 @@
+# Session Vision Core SDK
+
+The `@sessionvision/core` package is the canonical JavaScript SDK used across the product.
+It powers the inline HTML snippet **and** provides lightweight React/Vue wrappers via
+subpath exports:
+
+- `@sessionvision/core` – vanilla SDK used by the HTML snippet or custom loaders
+- `@sessionvision/core/react` – `<SessionVisionProvider>` + React hooks
+- `@sessionvision/core/vue` – Vue plugin + composables
+
+A single npm release now covers all browser integrations while keeping bundle sizes tiny.
+
+> **Tip:** To start all services including the snippet demo, run `./scripts/dev` from the repository root. This starts the snippet manual test page at http://localhost:3001/tests/manual/index.html along with all other development services.
+
+## Prerequisites
+
+- Node.js >= 18.0.0
+- npm
+
+## Usage
+
+```bash
+npm install @sessionvision/core
+```
+
+### Vanilla / HTML Snippet
+
+```ts
+import sessionvision from '@sessionvision/core';
+
+sessionvision.init('proj_abc123', {
+  autocapture: true,
+  debug: true,
+});
+```
+
+### React
+
+```tsx
+import { SessionVisionProvider, useCapture } from '@sessionvision/core/react';
+
+function App() {
+  const capture = useCapture();
+
+  return (
+    <SessionVisionProvider apiKey={import.meta.env.VITE_SESSIONVISION_KEY}>
+      <button onClick={() => capture('cta_clicked')}>Track</button>
+    </SessionVisionProvider>
+  );
+}
+```
+
+### Vue
+
+```ts
+import { createApp } from 'vue';
+import { createSessionVision } from '@sessionvision/core/vue';
+import App from './App.vue';
+
+const app = createApp(App);
+app.use(createSessionVision(import.meta.env.VITE_SESSIONVISION_KEY));
+app.mount('#app');
+```
+
+## Building
+
+Build the SDK for development or production:
+
+```bash
+# Build all outputs (UMD, ESM, minified, stub)
+npm run build
+
+# Build and watch for changes during development
+npm run build:watch
+```
+
+Build outputs are written to `dist/`:
+- `sessionvision.js` / `sessionvision.min.js` - UMD bundles for CDN snippet
+- `sessionvision.esm.js` - ESM entry point
+- `sessionvision.cjs.js` - CommonJS build for Node/bundlers
+- `react/index.{esm,cjs}.js` - React provider + hooks
+- `vue/index.{esm,cjs}.js` - Vue plugin + composables
+- `stub.min.js` / `stub-template.ts` - Inline stub script + TypeScript helper
+
+## Testing
+
+### Unit Tests (Jest)
+
+Unit tests cover core functionality like UUID generation, PII masking, event buffering, and identity management.
+
+```bash
+# Run all unit tests
+npm test
+
+# Run tests in watch mode (re-runs on file changes)
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+```
+
+Unit tests are located in `tests/unit/` and use jsdom for browser API mocking.
+
+### End-to-End Tests (Playwright)
+
+E2E tests verify the SDK works correctly in real browsers, including pageview tracking, click capture, form submissions, SPA navigation, and user identification.
+
+```bash
+# Run all E2E tests (headless)
+npm run test:e2e
+
+# Run with Playwright UI (interactive test runner)
+npm run test:e2e:ui
+
+# Run with visible browser windows
+npm run test:e2e:headed
+
+# Debug mode (step through tests)
+npm run test:e2e:debug
+```
+
+E2E tests are located in `tests/e2e/` and run against multiple browsers:
+- Chromium (Desktop)
+- Firefox (Desktop)
+- WebKit/Safari (Desktop)
+- Chrome Mobile (Pixel 5 emulation)
+- Safari Mobile (iPhone 12 emulation)
+
+#### E2E Test Infrastructure
+
+The E2E tests use a local test server (`tests/e2e/server.mjs`) that:
+- Serves the built SDK at `http://localhost:3333/sessionvision.js`
+- Serves test fixtures at `http://localhost:3333/`
+- Provides mock API endpoints for event ingestion
+- Exposes test control endpoints for inspecting captured events
+
+The server starts automatically when you run Playwright tests.
+
+## Local Development
+
+### Manual Testing Page
+
+For interactive development and debugging, use the manual test page:
+
+1. **Build the SDK first:**
+   ```bash
+   npm run build
+   ```
+
+2. **Start a local server** (from the snippet directory):
+   ```bash
+   npx serve .
+   ```
+   Or use any static file server of your choice.
+
+3. **Open the manual test page:**
+   ```
+   http://localhost:3001/tests/manual/index.html
+   ```
+
+The manual test page (`tests/manual/index.html`) provides:
+- Real-time display of captured events in a console overlay
+- Buttons to test custom events (purchase, signup, etc.)
+- Form submission testing with input masking
+- User identification testing (identify/reset)
+- SPA navigation simulation
+- Property registration testing
+
+**Note:** By default, the manual test page points to `http://localhost:3000` for the API. Update the `apiHost` in the page's initialization code if your backend runs on a different port.
+
+### E2E Test Fixture Page
+
+For quick testing against the E2E fixture page:
+
+1. **Build the SDK:**
+   ```bash
+   npm run build
+   ```
+
+2. **Start the test server manually:**
+   ```bash
+   node tests/e2e/server.mjs
+   ```
+
+3. **Open the fixture page:**
+   ```
+   http://localhost:3333/
+   ```
+
+This page is simpler than the manual test page and is designed for automated testing, but can be useful for quick checks.
+
+### Inspecting Captured Events (E2E Server)
+
+When using the E2E test server, you can inspect captured events:
+
+```bash
+# Get all captured events
+curl http://localhost:3333/__test__/events
+
+# Reset captured events
+curl -X POST http://localhost:3333/__test__/reset
+```
+
+## Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run build` | Build all SDK bundles |
+| `npm run build:watch` | Build and watch for changes |
+| `npm test` | Run unit tests |
+| `npm run test:watch` | Run unit tests in watch mode |
+| `npm run test:coverage` | Run unit tests with coverage |
+| `npm run test:e2e` | Run Playwright E2E tests |
+| `npm run test:e2e:ui` | Run E2E tests with Playwright UI |
+| `npm run test:e2e:headed` | Run E2E tests with visible browsers |
+| `npm run test:e2e:debug` | Run E2E tests in debug mode |
+| `npm run lint` | Lint TypeScript source files |
+| `npm run typecheck` | Run TypeScript type checking |
+| `npm run clean` | Remove build artifacts |
+
+## Public API
+
+The SDK exposes the following methods on the global `sessionvision` object:
+
+```javascript
+// Initialize the SDK
+sessionvision.init('your_project_token', {
+  apiHost: 'https://api.example.com',
+  autocapture: {
+    pageviews: true,
+    clicks: true,
+    forms: true
+  }
+});
+
+// Track a custom event
+sessionvision.capture('button_clicked', { button_name: 'signup' });
+
+// Identify a user
+sessionvision.identify('user_123', { email: 'user@example.com', plan: 'pro' });
+
+// Reset user identity (e.g., on logout)
+sessionvision.reset();
+
+// Get the current distinct ID
+const id = sessionvision.getDistinctId();
+
+// Register persistent properties (sent with every event)
+sessionvision.register({ app_version: '2.1.0' });
+
+// Register properties only if not already set
+sessionvision.registerOnce({ initial_referrer: document.referrer });
+```
+
+## Architecture
+
+The SDK uses a three-tier loading architecture:
+
+| Layer | File | Size | Purpose |
+|-------|------|------|---------|
+| 1 | Inline stub | <1KB | Pasted in `<head>`, creates queue, loads SDK |
+| 2 | Main SDK | <30KB | Core tracking, identity, autocapture |
+| 3 | Recorder | ~50KB | rrweb session recording (loaded conditionally) |
+
+## Key Features
+
+- **Autocapture**: Automatically captures pageviews, clicks, and form submissions
+- **Event Buffering**: Batches events (max 10) with 5-second flush intervals
+- **PII Masking**: Automatically masks emails, phone numbers, and credit cards
+- **Session Management**: 30-minute inactivity timeout
+- **SPA Support**: Tracks client-side navigation via History API
+- **Retry Logic**: Exponential backoff for failed requests
+
+## Production Deployment
+
+The snippet is deployed to Cloudflare R2 with Cloudflare CDN.
+
+### One-Time Setup
+
+1. **Create R2 bucket in Cloudflare Dashboard:**
+   - Go to R2 → Create Bucket
+   - Name: `session-vision-cdn` (or your preferred name)
+   - Enable public access via custom domain
+
+2. **Configure CORS:**
+   ```bash
+   export CLOUDFLARE_ACCOUNT_ID=your-account-id
+   export CLOUDFLARE_R2_ACCESS_KEY=your-access-key
+   export CLOUDFLARE_R2_SECRET_KEY=your-secret-key
+   export SNIPPET_BUCKET=session-vision-cdn
+
+   ./scripts/setup-snippet-cors
+   ```
+
+3. **Configure custom domain:**
+   - In R2 bucket settings, add `cdn.yourdomain.com` as a custom domain
+   - Cloudflare automatically handles CDN caching
+
+### Deploying Updates
+
+```bash
+# Set credentials
+export CLOUDFLARE_ACCOUNT_ID=your-account-id
+export CLOUDFLARE_R2_ACCESS_KEY=your-access-key
+export CLOUDFLARE_R2_SECRET_KEY=your-secret-key
+export SNIPPET_BUCKET=session-vision-cdn
+
+# Preview what will be uploaded
+./scripts/deploy-snippet --dry-run
+
+# Deploy
+./scripts/deploy-snippet
+```
+
+The deploy script builds the snippet and uploads to three paths:
+
+| Path | Cache | Use Case |
+|------|-------|----------|
+| `/v0.1.0/` | 1 year (immutable) | Production - pin to exact version |
+| `/v0/` | 1 hour | Production - auto-update within major |
+| `/latest/` | 5 minutes | Development only |
+
+### CDN URLs
+
+After deployment, the snippet is available at:
+```
+https://your-bucket.your-objectstorage.com/v0/sessionvision.min.js
+```
+
+Or via Cloudflare:
+```
+https://cdn.yourdomain.com/v0/sessionvision.min.js
+```
+
+## Troubleshooting
+
+### Build errors
+
+If you encounter build errors, try:
+```bash
+npm run clean
+rm -rf node_modules
+npm install
+npm run build
+```
+
+### E2E tests failing to start
+
+Ensure port 3333 is available. Kill any existing processes:
+```bash
+lsof -ti:3333 | xargs kill -9
+```
+
+### Tests not picking up code changes
+
+Make sure to rebuild before running E2E tests:
+```bash
+npm run build && npm run test:e2e
+```
+
+For unit tests, Jest handles TypeScript transformation automatically.

package/dist/react/capture/autocapture.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Autocapture module
+ * Handles automatic capture of clicks and form submissions
+ */
+import { ResolvedConfig } from '../types';
+/**
+ * Set the configuration
+ */
+export declare function setAutocaptureConfig(cfg: ResolvedConfig): void;
+/**
+ * Initialize click tracking
+ */
+export declare function initClickTracking(): void;
+/**
+ * Stop click tracking
+ */
+export declare function stopClickTracking(): void;
+/**
+ * Initialize form submission tracking
+ */
+export declare function initFormTracking(): void;
+/**
+ * Stop form submission tracking
+ */
+export declare function stopFormTracking(): void;
+/**
+ * Initialize all autocapture based on configuration
+ */
+export declare function initAutocapture(cfg: ResolvedConfig): void;
+/**
+ * Stop all autocapture
+ */
+export declare function stopAutocapture(): void;
+/**
+ * Check if click tracking is active
+ */
+export declare function isClickTrackingEnabled(): boolean;
+/**
+ * Check if form tracking is active
+ */
+export declare function isFormTrackingEnabled(): boolean;
+/**
+ * Reset for testing
+ */
+export declare function _reset(): void;

package/dist/react/capture/event.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Event capture module
+ * Core event capture functionality
+ */
+import { CapturedEvent, EventProperties, ResolvedConfig } from '../types';
+type EventCallback = (event: CapturedEvent) => void;
+/**
+ * Set the configuration
+ */
+export declare function setConfig(cfg: ResolvedConfig): void;
+/**
+ * Set the callback to be called when an event is captured
+ */
+export declare function setEventCallback(callback: EventCallback): void;
+/**
+ * Capture an event
+ */
+export declare function captureEvent(eventName: string, properties?: EventProperties, options?: {
+    includeAutoProperties?: boolean;
+}): void;
+/**
+ * Capture an internal/system event (like $identify)
+ */
+export declare function captureSystemEvent(eventName: string, properties?: EventProperties): void;
+/**
+ * Clear callbacks (for testing)
+ */
+export declare function _clearCallbacks(): void;
+export {};

package/dist/react/capture/pageview.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Pageview tracking module
+ * Handles initial page load and SPA navigation
+ */
+import { PageviewEventProperties } from '../types';
+/**
+ * Capture a pageview event
+ */
+export declare function capturePageview(customProperties?: Partial<PageviewEventProperties>): void;
+/**
+ * Initialize pageview tracking
+ * - Captures initial pageview
+ * - Listens for SPA navigation (pushState, replaceState, popstate)
+ */
+export declare function initPageviewTracking(): void;
+/**
+ * Stop pageview tracking
+ */
+export declare function stopPageviewTracking(): void;
+/**
+ * Check if pageview tracking is initialized
+ */
+export declare function isPageviewTrackingActive(): boolean;
+/**
+ * Reset for testing
+ */
+export declare function _reset(): void;

package/dist/react/capture/properties.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Automatic properties module
+ * Collects browser, device, and environment information
+ */
+import { AutomaticProperties, EventProperties } from '../types';
+/**
+ * Get all automatic properties
+ */
+export declare function getAutomaticProperties(): AutomaticProperties;
+/**
+ * Get registered properties (properties sent with every event)
+ */
+export declare function getRegisteredProperties(): EventProperties;
+/**
+ * Register properties to be sent with every event
+ */
+export declare function registerProperties(properties: EventProperties): void;
+/**
+ * Register properties only if they don't already exist
+ */
+export declare function registerOnceProperties(properties: EventProperties): void;
+/**
+ * Clear all registered properties
+ */
+export declare function clearRegisteredProperties(): void;

package/dist/react/core/config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Configuration management module
+ * Handles fetching, caching, and merging configuration
+ */
+import { SessionVisionConfig, ResolvedConfig, RemoteConfig } from '../types';
+/**
+ * Resolve user config with defaults
+ */
+export declare function resolveConfig(projectToken: string, userConfig?: SessionVisionConfig): ResolvedConfig;
+/**
+ * Fetch remote configuration from server
+ */
+export declare function fetchRemoteConfig(resolvedConfig: ResolvedConfig): Promise<RemoteConfig | null>;
+/**
+ * Apply remote config settings
+ */
+export declare function applyRemoteConfig(remoteConfig: RemoteConfig): void;
+/**
+ * Get default remote config for offline mode
+ */
+export declare function getDefaultRemoteConfig(): RemoteConfig;

package/dist/react/core/init.d.ts

@@ -0,0 +1,53 @@
+/**
+ * SDK initialization module
+ * Orchestrates the initialization of all SDK components
+ */
+import { SessionVisionConfig, ResolvedConfig, UserTraits, EventProperties } from '../types';
+/**
+ * Initialize the SDK
+ */
+export declare function init(projectToken: string, config?: SessionVisionConfig): Promise<void>;
+/**
+ * Capture a custom event
+ */
+export declare function capture(eventName: string, properties?: EventProperties): void;
+/**
+ * Identify a user
+ */
+export declare function identify(userId: string, traits?: UserTraits): void;
+/**
+ * Reset user identity (for logout)
+ */
+export declare function reset(): void;
+/**
+ * Get the current distinct ID
+ */
+export declare function getDistinctIdValue(): string;
+/**
+ * Register properties to send with every event
+ */
+export declare function register(properties: EventProperties): void;
+/**
+ * Register properties only if they don't exist
+ */
+export declare function registerOnce(properties: EventProperties): void;
+/**
+ * Manually flush the event buffer
+ */
+export declare function flushEvents(): Promise<void>;
+/**
+ * Shutdown the SDK
+ */
+export declare function shutdown(): void;
+/**
+ * Check if the SDK is initialized
+ */
+export declare function isSDKInitialized(): boolean;
+/**
+ * Get the current configuration
+ */
+export declare function getConfig(): ResolvedConfig | null;
+/**
+ * Reset for testing
+ */
+export declare function _reset(): void;

package/dist/react/core/queue.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Queue replay module
+ * Handles replaying method calls that were queued before SDK loaded
+ */
+import { QueuedCall, SessionVisionAPI } from '../types';
+/**
+ * Replay queued method calls
+ * The stub queues calls like ['capture', 'event_name', {...}] before SDK loads
+ */
+export declare function replayQueue(queue: QueuedCall[] | undefined, api: SessionVisionAPI): void;
+/**
+ * Parse the legacy array-style queue format
+ * PostHog-style: sessionvision._q = [['capture', 'event', {}], ...]
+ */
+export declare function parseLegacyQueue(legacyQueue: unknown[][] | undefined): QueuedCall[];
+/**
+ * Get init calls from _i array
+ */
+export declare function getInitCalls(initArray: Array<[string, unknown?]> | undefined): Array<{
+    projectToken: string;
+    config?: unknown;
+}>;

package/dist/react/identity/anonymous.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Anonymous ID management
+ * Generates and persists anonymous user identifiers using UUID v4
+ */
+/**
+ * Get the current anonymous ID, creating one if it doesn't exist
+ */
+export declare function getAnonymousId(): string;
+/**
+ * Set a specific anonymous ID (used when migrating from another analytics tool)
+ */
+export declare function setAnonymousId(id: string): void;
+/**
+ * Reset the anonymous ID (generates a new one)
+ * Called during reset() when user logs out
+ */
+export declare function resetAnonymousId(): string;
+/**
+ * Clear the anonymous ID from storage and cache
+ * Used internally during full reset
+ */
+export declare function clearAnonymousId(): void;
+/**
+ * Check if an anonymous ID exists
+ */
+export declare function hasAnonymousId(): boolean;
+/**
+ * Clear the in-memory cache (for testing)
+ */
+export declare function _clearCache(): void;

package/dist/react/identity/identify.d.ts

@@ -0,0 +1,46 @@
+/**
+ * User identification management
+ * Handles identify() calls and user ID persistence
+ */
+import { UserTraits } from '../types';
+/**
+ * Set the callback to be called when identify() is invoked
+ * Used by the SDK to capture an $identify event
+ */
+export declare function setIdentifyCallback(callback: (userId: string, traits?: UserTraits) => void): void;
+/**
+ * Get the current user ID, or null if not identified
+ */
+export declare function getUserId(): string | null;
+/**
+ * Identify a user with an ID and optional traits
+ * - Sets the user ID in localStorage
+ * - Triggers an $identify event with traits
+ * - Forward-only: does not retroactively link past anonymous events
+ */
+export declare function identify(userId: string, traits?: UserTraits): void;
+/**
+ * Check if a user is currently identified
+ */
+export declare function isIdentified(): boolean;
+/**
+ * Get the distinct ID (user ID if identified, anonymous ID otherwise)
+ */
+export declare function getDistinctId(): string;
+/**
+ * Reset user identity
+ * - Clears user ID
+ * - Generates new anonymous ID
+ * - Starts new session
+ * Used on logout
+ */
+export declare function reset(): void;
+/**
+ * Clear the user ID only (without resetting anonymous ID or session)
+ * Used internally
+ */
+export declare function clearUserId(): void;
+/**
+ * Clear the in-memory cache (for testing)
+ */
+export declare function _clearCache(): void;