@sessionvision/core 0.2.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/capture/autocapture.d.ts

@@ -1,6 +1,7 @@
 /**
  * Autocapture module
- * Handles automatic capture of clicks and form submissions
+ * Handles automatic capture of clicks, form submissions,
+ * rage clicks, and dead clicks
  */
 import { ResolvedConfig } from '../types';
 /**

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

@@ -0,0 +1,19 @@
+/**
+ * Dead Click Detection
+ *
+ * Detects clicks that produce no visible DOM changes.
+ * Emits $dead_click events when no response is detected.
+ */
+import { ResolvedConfig } from '../types';
+export declare function shouldExcludeFromDeadClick(element: Element): boolean;
+export declare class DeadClickDetector {
+    private static readonly DEFAULT_TIMEOUT_MS;
+    private pendingClick;
+    private timeoutMs;
+    constructor(_config: ResolvedConfig);
+    monitorClick(event: MouseEvent, element: Element, properties: Record<string, unknown>): void;
+    private cancelPending;
+    private isMeaningfulMutation;
+    private emitDeadClick;
+    destroy(): void;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Form Field Tracking
+ *
+ * Tracks form field interactions for abandonment analysis.
+ * Emits $form_start when user begins filling a form,
+ * $form_field_change when fields are modified.
+ */
+import { ResolvedConfig } from '../types';
+/**
+ * State for a form that has been started
+ */
+interface FormState {
+    startTime: number;
+    fieldCount: number;
+    interactedFields: Set<string>;
+    filledFields: Set<string>;
+}
+/**
+ * Get the current state for a form
+ */
+export declare function getFormState(formSelector: string): FormState | undefined;
+/**
+ * Reset tracking for a specific form (called after submit)
+ */
+export declare function resetForm(formSelector: string): void;
+/**
+ * Get form tracking data for enhanced submit event
+ */
+export declare function getFormTrackingData(form: HTMLFormElement): {
+    formSelector: string;
+    formFieldCount: number;
+    formFieldsFilled: string[];
+    formFieldsInteracted: string[];
+    formCompletionRate: number;
+    formTimeToSubmitMs: number | null;
+};
+/**
+ * Initialize form field tracking
+ */
+export declare function initFormFieldTracking(_cfg: ResolvedConfig): void;
+/**
+ * Stop form field tracking
+ */
+export declare function stopFormFieldTracking(): void;
+/**
+ * Check if form field tracking is active
+ */
+export declare function isFormFieldTrackingEnabled(): boolean;
+/**
+ * Reset for testing
+ */
+export declare function _reset(): void;
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * Rage Click Detection
+ *
+ * Detects rapid repeated clicks indicating user frustration.
+ * Emits a single $rage_click event after the click sequence ends.
+ */
+import { ResolvedConfig } from '../types';
+export declare function shouldExcludeFromRageClick(element: Element): boolean;
+export declare class RageClickDetector {
+    private clicks;
+    private emitTimeout;
+    private threshold;
+    private windowMs;
+    private radiusPx;
+    private static readonly DEFAULT_THRESHOLD;
+    private static readonly DEFAULT_WINDOW_MS;
+    private static readonly DEFAULT_RADIUS_PX;
+    constructor(_config: ResolvedConfig);
+    recordClick(event: MouseEvent, element: Element, properties: Record<string, unknown>): void;
+    private scheduleEmit;
+    private maybeEmitRageClick;
+    private isClickCluster;
+    private emitRageClick;
+    destroy(): void;
+}

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

@@ -8,9 +8,15 @@ export interface AutocaptureConfig {
     /** Capture $pageview events (default: true) */
     pageview?: boolean;
     /** Capture $click events (default: true) */
-    clicks?: boolean;
+    click?: boolean;
     /** Capture $form_submit events (default: true) */
     formSubmit?: boolean;
+    /** Detect rage clicks - rapid repeated clicks indicating frustration (default: true) */
+    rageClick?: boolean;
+    /** Detect dead clicks - clicks with no DOM response (default: true) */
+    deadClick?: boolean;
+    /** Track form field interactions for abandonment analysis (default: true) */
+    formAbandonment?: boolean;
 }
 /**
  * SDK configuration options passed to init()
@@ -30,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
@@ -44,12 +54,22 @@ export interface ResolvedConfig {
     maskAllInputs: boolean;
     autocapture: {
         pageview: boolean;
-        clicks: boolean;
+        click: boolean;
         formSubmit: boolean;
+        rageClick: boolean;
+        deadClick: boolean;
+        formAbandonment: boolean;
+    };
+    recording?: false | {
+        maskAllInputs?: boolean;
     };
 }
 /**
  * Remote configuration fetched from server
+ *
+ * Only recording and session settings are remotely configurable.
+ * Autocapture settings (including rage/dead click detection) are
+ * configured locally via init() options.
  */
 export interface RemoteConfig {
     recording?: {
@@ -59,7 +79,6 @@ export interface RemoteConfig {
     session?: {
         timeoutMinutes: number;
     };
-    version?: string;
 }
 /**
  * User traits for identify()
@@ -123,6 +142,65 @@ export interface ClickEventProperties extends EventProperties {
     $element_selector: string;
     $element_href: string | null;
 }
+/**
+ * Rage click event properties
+ */
+export interface RageClickEventProperties extends EventProperties {
+    $element_tag: string;
+    $element_text: string;
+    $element_classes: string;
+    $element_id: string | null;
+    $element_selector: string;
+    $element_href: string | null;
+    $click_count: number;
+    $rage_click_duration_ms: number;
+    $click_x: number;
+    $click_y: number;
+    $element_x: number;
+    $element_y: number;
+    $click_positions: Array<{
+        x: number;
+        y: number;
+        timestamp: number;
+    }>;
+}
+/**
+ * Dead click event properties
+ */
+export interface DeadClickEventProperties extends EventProperties {
+    $element_tag: string;
+    $element_text: string;
+    $element_classes: string;
+    $element_id: string | null;
+    $element_selector: string;
+    $element_href: string | null;
+    $click_x: number;
+    $click_y: number;
+    $element_x: number;
+    $element_y: number;
+    $wait_duration_ms: number;
+    $element_is_interactive: boolean;
+}
+/**
+ * Form start event properties
+ */
+export interface FormStartEventProperties extends EventProperties {
+    $form_id: string | null;
+    $form_name: string | null;
+    $form_selector: string;
+    $form_field_count: number;
+}
+/**
+ * Form field change event properties
+ */
+export interface FormFieldChangeEventProperties extends EventProperties {
+    $form_selector: string;
+    $field_selector: string;
+    $field_name: string | null;
+    $field_type: string;
+    $field_index: number;
+    $has_value: boolean;
+}
 /**
  * Form submit event properties
  */
@@ -131,6 +209,12 @@ export interface FormSubmitEventProperties extends EventProperties {
     $form_action: string;
     $form_method: string;
     $form_name: string | null;
+    $form_selector: string;
+    $form_field_count: number;
+    $form_fields_filled: string[];
+    $form_fields_interacted: string[];
+    $form_completion_rate: number;
+    $form_time_to_submit_ms: number | null;
 }
 /**
  * Pageview event properties
@@ -185,6 +269,20 @@ export interface SessionVisionAPI {
     register(properties: EventProperties): void;
     /** Register properties only if they don't already exist */
     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 */
@@ -194,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
  */
@@ -223,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;