@sessionvision/core 0.3.0 → 0.4.0

package/README.md

@@ -39,12 +39,15 @@ sessionvision.init('proj_abc123', {
 ```tsx
 import { SessionVisionProvider, useCapture } from '@sessionvision/core/react';
 
-function App() {
+function TrackButton() {
   const capture = useCapture();
+  return <button onClick={() => capture('cta_clicked')}>Track</button>;
+}
 
+function App() {
   return (
-    <SessionVisionProvider apiKey={import.meta.env.VITE_SESSIONVISION_KEY}>
-      <button onClick={() => capture('cta_clicked')}>Track</button>
+    <SessionVisionProvider apiKey="your_project_token">
+      <TrackButton />
     </SessionVisionProvider>
   );
 }
@@ -58,7 +61,7 @@ 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.use(createSessionVision('your_project_token'));
 app.mount('#app');
 ```
 
@@ -119,12 +122,9 @@ npm run test:e2e:headed
 npm run test:e2e:debug
 ```
 
-E2E tests are located in `tests/e2e/` and run against multiple browsers:
+E2E tests are located in `tests/e2e/` and run against:
 - Chromium (Desktop)
-- Firefox (Desktop)
-- WebKit/Safari (Desktop)
 - Chrome Mobile (Pixel 5 emulation)
-- Safari Mobile (iPhone 12 emulation)
 
 #### E2E Test Infrastructure
 
@@ -227,9 +227,9 @@ The SDK exposes the following methods on the global `sessionvision` object:
 sessionvision.init('your_project_token', {
   apiHost: 'https://api.example.com',
   autocapture: {
-    pageviews: true,
-    clicks: true,
-    forms: true
+    pageview: true,
+    click: true,
+    formSubmit: true
   }
 });
 
@@ -250,6 +250,9 @@ sessionvision.register({ app_version: '2.1.0' });
 
 // Register properties only if not already set
 sessionvision.registerOnce({ initial_referrer: document.referrer });
+
+// Manually flush the event buffer (useful before navigation)
+await sessionvision.flushEvents();
 ```
 
 ## Architecture

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

@@ -7,10 +7,22 @@ import { SessionVisionConfig, ResolvedConfig, RemoteConfig } from '../types';
  * Resolve user config with defaults
  */
 export declare function resolveConfig(projectToken: string, userConfig?: SessionVisionConfig): ResolvedConfig;
+/**
+ * Get cached remote config if valid (exported for fast path in init.ts)
+ */
+export declare function getCachedRemoteConfig(projectToken: string): RemoteConfig | null;
+/**
+ * Resolve the recorder bundle URL relative to the SDK's apiHost
+ */
+export declare function resolveRecorderUrl(config: ResolvedConfig): string;
+interface FetchRemoteConfigOptions {
+    /** Inject <link rel="prefetch"> for the recorder bundle (for first-time visitors with no cache) */
+    prefetchRecorder?: boolean;
+}
 /**
  * Fetch remote configuration from server
  */
-export declare function fetchRemoteConfig(resolvedConfig: ResolvedConfig): Promise<RemoteConfig | null>;
+export declare function fetchRemoteConfig(resolvedConfig: ResolvedConfig, options?: FetchRemoteConfigOptions): Promise<RemoteConfig | null>;
 /**
  * Apply remote config settings
  */
@@ -19,3 +31,4 @@ export declare function applyRemoteConfig(remoteConfig: RemoteConfig): void;
  * Get default remote config for offline mode
  */
 export declare function getDefaultRemoteConfig(): RemoteConfig;
+export {};

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

@@ -47,6 +47,31 @@ export declare function isSDKInitialized(): boolean;
  * Get the current configuration
  */
 export declare function getConfig(): ResolvedConfig | null;
+/**
+ * Manually start recording. Respects remote config — no-op if recording.enabled is false.
+ * Bypasses sampling when recording is enabled.
+ */
+export declare function startRecording(): Promise<void>;
+/**
+ * Stop recording for this session
+ */
+export declare function stopRecording(): void;
+/**
+ * Check if recording is active
+ */
+export declare function isRecording(): boolean;
+/**
+ * Tag the current recording with custom metadata
+ */
+export declare function tagRecordingFn(tags: Record<string, string>): void;
+/**
+ * Subscribe to SDK events
+ */
+export declare function onEvent(event: string, callback: (data?: unknown) => void): void;
+/**
+ * Unsubscribe from SDK events
+ */
+export declare function offEvent(event: string, callback: (data?: unknown) => void): void;
 /**
  * Reset for testing
  */

package/dist/react/recorder/chunk.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Chunk manager for recording events
+ * Buffers rrweb events and manages chunked uploads
+ */
+import { RecordingEvent, ResolvedConfig } from '../types';
+type EventEmitFn = (event: string, data?: unknown) => void;
+interface ChunkManagerOptions {
+    config: ResolvedConfig;
+    emit: EventEmitFn;
+}
+export declare class ChunkManager {
+    private buffer;
+    private bufferSize;
+    private chunkNumber;
+    private lastFlush;
+    private flushTimer;
+    private config;
+    private emit;
+    private tags;
+    private chunkStartTime;
+    private hasFullSnapshot;
+    private started;
+    constructor(options: ChunkManagerOptions);
+    /**
+     * Start the chunk manager flush timer
+     */
+    start(): void;
+    /**
+     * Stop the chunk manager
+     */
+    stop(): void;
+    /**
+     * Add an rrweb event to the buffer
+     */
+    addEvent(event: RecordingEvent): void;
+    /**
+     * Set tags to be sent with the next chunk
+     */
+    setTags(tags: Record<string, string>): void;
+    /**
+     * Check if the buffer should be flushed
+     */
+    private shouldFlush;
+    /**
+     * Flush the buffer — send accumulated events as a chunk
+     */
+    flush(): void;
+    /**
+     * Get the current chunk number (for testing)
+     */
+    getChunkNumber(): number;
+    /**
+     * Get the current buffer size in bytes (for testing)
+     */
+    getBufferSize(): number;
+    private handleVisibilityChange;
+    private handleBeforeUnload;
+}
+export {};

package/dist/react/recorder/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Session Recorder entry point
+ * Handles initialization, sampling decision, and lifecycle management
+ */
+import { RemoteConfig, ResolvedConfig } from '../types';
+type EventListener = (data?: unknown) => void;
+export declare function on(event: string, callback: EventListener): void;
+export declare function off(event: string, callback: EventListener): void;
+/**
+ * Deterministic sampling based on session ID
+ * Same session always gets same result (important for multi-page sessions)
+ */
+export declare function shouldRecordSession(sampleRate: number, sessionId: string): boolean;
+/**
+ * Initialize the recorder — called after the recorder bundle is loaded
+ */
+export declare function initRecorder(config: ResolvedConfig, _remoteConfig: RemoteConfig): void;
+/**
+ * Stop the recorder
+ */
+export declare function stopRecorder(): void;
+/**
+ * Check if the recorder is currently active
+ */
+export declare function isRecorderActive(): boolean;
+/**
+ * Tag the current recording with custom metadata
+ */
+export declare function tagRecording(tags: Record<string, string>): void;
+/**
+ * Reset recorder state (for testing)
+ */
+export declare function _resetRecorder(): void;
+/**
+ * Recorder module interface (exposed via global for script-based loading)
+ */
+export interface RecorderModule {
+    initRecorder: typeof initRecorder;
+    stopRecorder: typeof stopRecorder;
+    isRecorderActive: typeof isRecorderActive;
+    tagRecording: typeof tagRecording;
+    shouldRecordSession: typeof shouldRecordSession;
+    on: typeof on;
+    off: typeof off;
+}
+export {};

package/dist/react/recorder/mask.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Privacy & masking bridge for session recordings
+ * Bridges rrweb's masking callbacks with the SDK's existing PII detection
+ */
+/**
+ * Mask text content for rrweb's maskTextFn callback
+ */
+export declare function maskTextForRecording(text: string): string;
+/**
+ * Mask input values for rrweb's maskInputFn callback
+ * Respects data-sessionvision-unmask attribute
+ */
+export declare function maskInputForRecording(text: string, element: HTMLElement): string;

package/dist/react/recorder/rrweb.d.ts

@@ -0,0 +1,19 @@
+/**
+ * rrweb integration module
+ * Wraps rrweb with configured capture options and handles events
+ */
+import { RecordingEvent, ResolvedConfig } from '../types';
+type EventCallback = (event: RecordingEvent) => void;
+/**
+ * Start rrweb recording
+ */
+export declare function startRrwebRecording(config: ResolvedConfig, onEvent: EventCallback): void;
+/**
+ * Stop rrweb recording
+ */
+export declare function stopRrwebRecording(): void;
+/**
+ * Check if rrweb is currently recording
+ */
+export declare function isRrwebRecording(): boolean;
+export {};

package/dist/react/recorder/upload.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Upload manager for recording chunks
+ * Sends recording chunks to the ingest API as $recording events
+ */
+import { RecordingEvent, ResolvedConfig } from '../types';
+interface ChunkPayload {
+    chunkNumber: number;
+    startTime: number;
+    endTime: number;
+    events: RecordingEvent[];
+    fullSnapshotIncluded: boolean;
+    tags?: Record<string, string>;
+    isFirstChunk: boolean;
+}
+/**
+ * Send a recording chunk to the ingest API
+ * Uses the same endpoint as regular events with the $recording event name
+ */
+export declare function sendRecordingChunk(config: ResolvedConfig, chunk: ChunkPayload): Promise<boolean>;
+export {};

package/dist/react/types.d.ts

@@ -36,6 +36,10 @@ export interface SessionVisionConfig {
     maskAllInputs?: boolean;
     /** Enable/disable auto-capture (default: true) */
     autocapture?: boolean | AutocaptureConfig;
+    /** Override recording behavior. Set false to force-disable regardless of remote config. */
+    recording?: false | {
+        maskAllInputs?: boolean;
+    };
 }
 /**
  * Internal resolved configuration
@@ -56,6 +60,9 @@ export interface ResolvedConfig {
         deadClick: boolean;
         formAbandonment: boolean;
     };
+    recording?: false | {
+        maskAllInputs?: boolean;
+    };
 }
 /**
  * Remote configuration fetched from server
@@ -264,6 +271,18 @@ export interface SessionVisionAPI {
     registerOnce(properties: EventProperties): void;
     /** Manually flush the event buffer */
     flushEvents(): Promise<void>;
+    /** Subscribe to SDK events (e.g., 'recording:error', 'recording:quota_exceeded') */
+    on(event: string, callback: (data?: unknown) => void): void;
+    /** Unsubscribe from SDK events */
+    off(event: string, callback: (data?: unknown) => void): void;
+    /** Manually start recording. Respects remote config — no-op if recording.enabled is false. Bypasses sampling when recording is enabled. */
+    startRecording(): void;
+    /** Stop recording for this session */
+    stopRecording(): void;
+    /** Check if recording is active */
+    isRecording(): boolean;
+    /** Tag the current recording with custom metadata */
+    tagRecording(tags: Record<string, string>): void;
     /** SDK version */
     version: string;
     /** Internal: queued method calls before SDK loads */
@@ -273,6 +292,23 @@ export interface SessionVisionAPI {
     /** Internal: SDK version marker */
     __SV?: number;
 }
+/**
+ * Recording event type (rrweb event)
+ */
+export interface RecordingEvent {
+    type: number;
+    data: unknown;
+    timestamp: number;
+}
+/**
+ * Recording chunk configuration
+ */
+export declare const RECORDING_CONFIG: {
+    readonly FLUSH_INTERVAL_MS: 5000;
+    readonly MAX_BUFFER_SIZE_BYTES: number;
+    readonly FULL_SNAPSHOT_INTERVAL_MS: number;
+    readonly RETRY_DELAY_MS: 2000;
+};
 /**
  * Storage key constants
  */
@@ -302,6 +338,6 @@ export declare const BUFFER_CONFIG: {
     readonly RETRY_DELAYS_MS: readonly [1000, 2000, 4000];
 };
 /**
- * Config cache TTL in milliseconds (1 hour)
+ * Config cache TTL in milliseconds (4 hours)
  */
 export declare const CONFIG_CACHE_TTL_MS: number;