webrec-sdk 1.0.0

package/dist/capture/console-interceptor.d.ts

@@ -0,0 +1,12 @@
+export type ConsoleEvent = {
+    level: string;
+    message: string;
+    url: string;
+};
+export type ConsoleCallback = (event: ConsoleEvent) => void;
+export declare class ConsoleInterceptor {
+    private originals;
+    private active;
+    start(callback: ConsoleCallback): void;
+    stop(): void;
+}

package/dist/capture/dead-click-detector.d.ts

@@ -0,0 +1,14 @@
+export type DeadClickCallback = (event: any) => void;
+export declare class DeadClickDetector {
+    private callback;
+    private clickHandler;
+    private pendingClicks;
+    private active;
+    private origXhrOpen;
+    private origFetch;
+    private activeNetworkCount;
+    start(callback: DeadClickCallback): void;
+    stop(): void;
+    private interceptNetwork;
+    private restoreNetwork;
+}

package/dist/capture/dom-recorder.d.ts

@@ -0,0 +1,8 @@
+import type { RecorderConfig } from '../config';
+export type EventCallback = (event: any) => void;
+export declare class DomRecorder {
+    private stopFn;
+    start(config: RecorderConfig, onEvent: EventCallback): void;
+    stop(): void;
+    isRecording(): boolean;
+}

package/dist/capture/error-click-detector.d.ts

@@ -0,0 +1,12 @@
+export type ErrorClickCallback = (event: any) => void;
+export declare class ErrorClickDetector {
+    private callback;
+    private clickHandler;
+    private errorHandler;
+    private rejectionHandler;
+    private clickBuffer;
+    private active;
+    start(callback: ErrorClickCallback): void;
+    stop(): void;
+    private checkForCorrelatedClick;
+}

package/dist/capture/error-tracker.d.ts

@@ -0,0 +1,16 @@
+export type RecorderErrorEvent = {
+    type: string;
+    message: string;
+    stack?: string;
+    url?: string;
+    line?: number;
+    column?: number;
+};
+export type ErrorCallback = (event: RecorderErrorEvent) => void;
+export declare class ErrorTracker {
+    private errorHandler;
+    private rejectionHandler;
+    private active;
+    start(callback: ErrorCallback): void;
+    stop(): void;
+}

package/dist/capture/interaction-enricher.d.ts

@@ -0,0 +1,17 @@
+export type EnrichedEventCallback = (event: any) => void;
+export declare class InteractionEnricher {
+    private callback;
+    private observer;
+    private clickHandler;
+    private submitHandler;
+    private changeHandler;
+    private active;
+    private dialogDebounceMap;
+    start(callback: EnrichedEventCallback): void;
+    stop(): void;
+    private startClickCapture;
+    private startSubmitCapture;
+    private startChangeCapture;
+    private startDialogDetection;
+    private emit;
+}

package/dist/capture/network-interceptor.d.ts

@@ -0,0 +1,30 @@
+export type NetworkEvent = {
+    method: string;
+    url: string;
+    status: number;
+    duration: number;
+    requestSize?: number;
+    responseSize?: number;
+    requestBody?: string;
+    responseBody?: string;
+    type: string;
+};
+export type NetworkCallback = (event: NetworkEvent) => void;
+export declare class NetworkInterceptor {
+    private originalFetch;
+    private originalXHROpen;
+    private originalXHRSend;
+    private active;
+    private sdkEndpoint;
+    start(callback: NetworkCallback, sdkEndpoint?: string): void;
+    /** Check if a URL is the SDK's own endpoint (should not be recorded) */
+    private isSdkUrl;
+    private interceptFetch;
+    private interceptXHR;
+    /**
+     * Strip common sensitive query parameters from URLs.
+     * Keeps the URL structure but redacts tokens, keys, passwords etc.
+     */
+    private sanitizeUrl;
+    stop(): void;
+}

package/dist/capture/scroll-depth-tracker.d.ts

@@ -0,0 +1,21 @@
+export type ScrollDepthCallback = (event: any) => void;
+export declare class ScrollDepthTracker {
+    private callback;
+    private scrollHandler;
+    private visibilityHandler;
+    private active;
+    private maxDepthPercent;
+    private currentUrl;
+    private throttleTimer;
+    private lastEmittedUrl;
+    private origPushState;
+    private origReplaceState;
+    private popstateHandler;
+    start(callback: ScrollDepthCallback): void;
+    stop(): void;
+    private calculateDepth;
+    private emitDepth;
+    private onNavigate;
+    private interceptNavigation;
+    private restoreNavigation;
+}

package/dist/config.d.ts

@@ -0,0 +1,51 @@
+export interface RecorderConfig {
+    apiKey: string;
+    endpoint?: string;
+    maskAllInputs?: boolean;
+    blockClass?: string;
+    ignoreClass?: string;
+    blockSelector?: string;
+    ignoreSelector?: string;
+    captureNetwork?: boolean;
+    captureConsole?: boolean;
+    captureErrors?: boolean;
+    /** Record canvas/WebGL elements. Increases CPU usage. Default false. */
+    recordCanvas?: boolean;
+    /** Collect fonts used on the page for accurate replay. Default true. */
+    collectFonts?: boolean;
+    batchSize?: number;
+    flushInterval?: number;
+    /** Max events to hold in memory. Oldest evicted when exceeded. Default 2000. */
+    maxQueueSize?: number;
+    /** Max retry attempts for failed flushes. Default 3. */
+    maxRetries?: number;
+    sessionTimeout?: number;
+    /** Percentage of traffic to record (0-100). Default 100 = record all. */
+    sampleRate?: number;
+    /** Minimum time in ms user must spend on page before recording starts. Default 0. */
+    minTimeOnPage?: number;
+    /** Minimum session duration in seconds before data is sent. Sessions shorter are discarded. Default 0. */
+    minSessionDuration?: number;
+    /** Ignore sessions on these URL patterns (regex strings). */
+    ignoreUrls?: string[];
+    /** Only record sessions on these URL patterns (regex strings). If set, only matching URLs are recorded. */
+    allowUrls?: string[];
+    /** Whether to respect Do Not Track browser setting. Default true. */
+    respectDoNotTrack?: boolean;
+    /** Delay in ms before recording starts after init. Default 0. */
+    startDelay?: number;
+    /** Enable verbose debug logging to console. Default false. */
+    debug?: boolean;
+    sampling?: {
+        mousemove?: boolean | number;
+        scroll?: number;
+        input?: 'last' | 'all';
+    };
+    privacy?: {
+        maskInputs?: boolean;
+        maskTextContent?: boolean;
+        blockSelectors?: string[];
+        ignoreSelectors?: string[];
+    };
+}
+export declare const DEFAULT_CONFIG: Required<Omit<RecorderConfig, 'apiKey'>>;

package/dist/identity/session-manager.d.ts

@@ -0,0 +1,21 @@
+export declare class SessionManager {
+    private sessionId;
+    private anonymousId;
+    private timeout;
+    constructor(timeout: number);
+    /**
+     * Get or create a persistent anonymous ID stored in localStorage.
+     * Unlike session IDs (sessionStorage, tab-scoped, rotates on timeout),
+     * the anonymous ID persists across tabs and browser restarts — it
+     * represents the same device/browser until the user clears storage.
+     */
+    private getOrCreateAnonymousId;
+    private getOrCreateSession;
+    private persist;
+    touch(): void;
+    getSessionId(): string;
+    getAnonymousId(): string;
+    /** Get timestamp of last activity (for timeout rotation checks) */
+    getLastActivity(): number | null;
+    reset(): string;
+}

package/dist/identity/user-identifier.d.ts

@@ -0,0 +1,21 @@
+export interface UserTraits {
+    name?: string;
+    displayName?: string;
+    email?: string;
+    [key: string]: any;
+}
+export declare class UserIdentifier {
+    private userId;
+    private traits;
+    private onIdentify;
+    constructor();
+    setCallback(cb: (userId: string, traits: UserTraits) => void): void;
+    identify(userId: string, traits?: UserTraits): void;
+    getUserId(): string | null;
+    getTraits(): UserTraits;
+    /** Re-fire the identify callback (e.g. after session rotation) without changing stored identity */
+    reidentify(): void;
+    reset(): void;
+    private persist;
+    private restore;
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import type { RecorderConfig } from './config';
+import type { UserTraits } from './identity/user-identifier';
+/**
+ * WebRec - Session recording SDK
+ *
+ * Usage:
+ *   WebRec.init({ apiKey: 'rec_xxx' })
+ *   WebRec.identify('user-123', { name: 'John', email: 'john@example.com' })
+ *   WebRec.track('checkout_complete', { value: 99 })
+ *   WebRec.stop()     // Pause recording
+ *   WebRec.start()    // Resume recording
+ *   WebRec.destroy()  // Full teardown (allows reinitialize)
+ */
+export declare const WebRec: {
+    init(config: RecorderConfig): void;
+    identify(userId: string, traits?: UserTraits): void;
+    /** Emit a custom business event */
+    track(eventName: string, properties?: Record<string, any>): void;
+    stop(): void;
+    start(): void;
+    /** Full teardown — destroy all listeners, interceptors, and state. Allows calling init() again. */
+    destroy(): void;
+    getSessionId(): string | null;
+    /** Get a link to this session in the recorder dashboard */
+    getSessionUrl(): string | null;
+    isRecording(): boolean;
+};
+export type { RecorderConfig, UserTraits };
+export default WebRec;

package/dist/privacy/masking.d.ts

@@ -0,0 +1,15 @@
+import type { RecorderConfig } from '../config';
+export declare function getMaskConfig(config: RecorderConfig): {
+    maskAllInputs: boolean;
+    maskInputOptions: {
+        password: boolean;
+        email: boolean;
+        tel: boolean;
+    };
+    maskTextClass: string;
+    maskTextSelector: string;
+    blockClass: string;
+    blockSelector: string;
+    ignoreClass: string;
+    maskTextFn: ((text: string) => string) | undefined;
+};

package/dist/recorder.d.ts

@@ -0,0 +1,43 @@
+import type { RecorderConfig } from './config';
+import { type UserTraits } from './identity/user-identifier';
+export declare class Recorder {
+    private config;
+    private domRecorder;
+    private networkInterceptor;
+    private consoleInterceptor;
+    private errorTracker;
+    private interactionEnricher;
+    private deadClickDetector;
+    private errorClickDetector;
+    private scrollDepthTracker;
+    private transport;
+    private beacon;
+    private sessionManager;
+    private userIdentifier;
+    private initialized;
+    private recording;
+    private sampled;
+    private initTime;
+    private routeChangeCleanup;
+    private visibilityCleanup;
+    private rageClickCleanup;
+    private sessionCheckTimer;
+    private log;
+    init(userConfig: RecorderConfig): void;
+    start(): void;
+    stop(): void;
+    /** Full teardown - allows reinitializing with new config */
+    destroy(): void;
+    identify(userId: string, traits?: UserTraits): void;
+    /** Emit a custom business event (e.g., 'checkout_complete', 'add_to_cart') */
+    track(eventName: string, properties?: Record<string, any>): void;
+    getSessionId(): string | null;
+    /** Get a URL that links directly to this session in the recorder UI */
+    getSessionUrl(): string | null;
+    isRecording(): boolean;
+    private startRouteTracking;
+    private startVisibilityTracking;
+    private startRageClickDetection;
+    private startSessionCheck;
+    private captureWebVitals;
+}

package/dist/surveys.d.ts

@@ -0,0 +1,8 @@
+/**
+ * In-App Surveys Module
+ *
+ * Fetches active surveys from the API, renders them in a Shadow DOM widget,
+ * and submits responses. Designed to be called from recorder.ts after
+ * recording starts.
+ */
+export declare function initSurveys(endpoint: string, apiKey: string, getSessionId: () => string | null, debug?: boolean): void;

package/dist/transport/batch-transport.d.ts

@@ -0,0 +1,45 @@
+export interface TransportConfig {
+    endpoint: string;
+    apiKey: string;
+    batchSize: number;
+    flushInterval: number;
+    maxQueueSize?: number;
+    maxRetries?: number;
+    /** Minimum session duration in seconds before data is actually sent. Events are buffered until met. */
+    minSessionDuration?: number;
+    /** Timestamp when the session started, used with minSessionDuration. */
+    sessionStartTime?: number;
+    /** URL pattern to filter out SDK's own requests in network interceptor */
+    sdkEndpoint?: string;
+    debug?: boolean;
+}
+export declare class BatchTransport {
+    private queue;
+    private timer;
+    private config;
+    private sessionId;
+    private anonymousId;
+    private seq;
+    private flushing;
+    private identityProvider;
+    constructor(config: TransportConfig, sessionId: string, anonymousId?: string);
+    /** Register a callback that returns the current user identity (if any) for inclusion in batch meta */
+    setIdentityProvider(provider: () => {
+        userId: string | null;
+        traits: Record<string, any>;
+    }): void;
+    start(): void;
+    stop(): void;
+    enqueue(event: any): void;
+    flush(): void;
+    private sendWithRetry;
+    private retryBatch;
+    /** Drain and return the queue atomically (for beacon transport on page unload) */
+    drainQueue(): any[];
+    /** Peek at queue without draining (for diagnostics) */
+    getQueueLength(): number;
+    updateSessionId(sessionId: string): void;
+    getSessionId(): string;
+    getAnonymousId(): string;
+    getEndpoint(): string;
+}

package/dist/transport/beacon-transport.d.ts

@@ -0,0 +1,17 @@
+import type { BatchTransport } from './batch-transport';
+/**
+ * Uses navigator.sendBeacon + visibilitychange/pagehide as a fallback
+ * to ensure any remaining events are sent before the page closes.
+ */
+export declare class BeaconTransport {
+    private transport;
+    private apiKey;
+    private active;
+    private visibilityHandler;
+    private pagehideHandler;
+    private beforeunloadHandler;
+    constructor(transport: BatchTransport, apiKey: string);
+    start(): void;
+    private sendChunk;
+    stop(): void;
+}

package/dist/utils/compression.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Synchronous gzip compression (pako). Used as fallback.
+ */
+export declare function gzipCompress(data: string): Uint8Array;
+/**
+ * Async gzip compression. Uses native CompressionStream API when available
+ * (zero-cost, off main thread in browsers that support it), falls back to pako.
+ *
+ * Supported: Chrome 80+, Firefox 113+, Safari 16.4+, Edge 80+
+ */
+export declare function compressAsync(data: string): Promise<Uint8Array>;

package/dist/utils/idle-callback.d.ts

@@ -0,0 +1,6 @@
+type IdleCallback = (deadline: {
+    didTimeout: boolean;
+    timeRemaining: () => number;
+}) => void;
+export declare function requestIdle(callback: IdleCallback, timeout?: number): void;
+export {};

package/dist/utils/safe-exec.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Wraps a function to silently catch errors - NEVER crash the host application.
+ */
+export declare function safeExec<T>(fn: () => T, fallback?: T): T | undefined;
+export declare function safeExecAsync<T>(fn: () => Promise<T>): Promise<T | undefined>;

package/dist/utils/uuid.d.ts

@@ -0,0 +1 @@
+export declare function uuid(): string;