userlens-session-recorder 2.0.2 → 2.2.0

package/dist/sessionManager.d.ts

@@ -0,0 +1,61 @@
+export type SessionChange = "none" | "expired" | "rotated";
+/**
+ * Owns the (session_uuid, window_id, chunk_seq, last_active) lifecycle.
+ *
+ * Two storage scopes:
+ *   - shared (localStorage): session_uuid + last_active — visible to every tab
+ *     of the same origin so tabs can adopt one logical session and a single
+ *     idle timeout governs the whole user.
+ *   - per-tab (sessionStorage): window_id + chunk_seq — independent per tab so
+ *     concurrent tabs can upload chunks without colliding on chunk_seq.
+ *
+ * The recorder talks to this class instead of touching storage directly.
+ */
+export declare class SessionManager {
+    #private;
+    private readonly timeoutMs;
+    private _sessionUuid;
+    private _windowId;
+    constructor(timeoutMs: number);
+    initialize(): void;
+    get sessionUuid(): string;
+    get windowId(): string;
+    /**
+     * Reconciles in-memory session_uuid with whatever shared storage says.
+     * Called on every event so cross-tab session changes are picked up quickly.
+     *
+     * Returns:
+     *   "expired" — shared session has been idle past timeout; we rotated.
+     *   "rotated" — another tab rotated the session_uuid; we adopted it.
+     *   "none"    — no change, business as usual.
+     *
+     * Caller takes a fresh full snapshot on "expired" or "rotated" so this
+     * window's first chunk in the new session is replayable on its own.
+     */
+    syncWithSharedState(now: number): SessionChange;
+    /** Bump shared last_active. Call only on real user interactions. */
+    bumpActivity(now: number): void;
+    /** Read this window's current chunk_seq for a pending upload. */
+    currentChunkSeq(): number | null;
+    /**
+     * Mark a chunk_seq as committed after a successful upload. No-ops if the
+     * stored seq has moved on (e.g. a session rotation reset it to 0 mid-flight).
+     */
+    commitChunkSeq(uploadedSeq: number): void;
+    /**
+     * Reserve and return the current chunk_seq for a pagehide flush, advancing
+     * storage so the next normal upload uses seq+1. Returns null if window state
+     * is missing.
+     */
+    reserveChunkSeq(): number | null;
+    /** Hard reset: wipe shared session and start a fresh one. */
+    reset(): void;
+    /**
+     * Called from pagehide. Lets a future reload of the same tab reuse the
+     * window_id (because the flag is gone), while a cloned tab still sees the
+     * flag set in its inherited sessionStorage and treats itself as a duplicate.
+     */
+    notifyPageHide(): void;
+    /** Full teardown — call on stop(). */
+    dispose(): void;
+}

package/dist/storage.d.ts

@@ -0,0 +1,10 @@
+import type { SharedSessionState, WindowState } from "./types";
+export declare function readSharedSessionState(): SharedSessionState | null;
+export declare function writeSharedSessionState(state: SharedSessionState): void;
+export declare function clearSharedSessionState(): void;
+export declare function readWindowState(): WindowState | null;
+export declare function writeWindowState(state: WindowState): void;
+export declare function clearWindowState(): void;
+export declare function wasPrimaryWindowFlagAlreadySet(): boolean;
+export declare function markPrimaryWindow(): void;
+export declare function clearPrimaryWindowFlag(): void;

package/dist/types/index.d.ts

@@ -1,24 +1,47 @@
+import { eventWithTime } from 'rrweb';
+
 type MaskingOption = "passwords" | "all";
+type RecorderMode = "auto" | "manual";
 interface SessionRecordingOptions {
     TIMEOUT?: number;
     BUFFER_SIZE?: number;
     maskingOptions?: MaskingOption[];
     recordCrossOriginIframes?: boolean;
 }
-interface SessionRecorderConfig {
+interface EventBatch {
+    session_uuid: string;
+    window_id: string;
+    chunk_seq: number;
+    chunk_start_ts: string;
+    chunk_end_ts: string;
+    events: eventWithTime[];
+    keepalive?: boolean;
+}
+type OnEventsCallback = (batch: EventBatch) => void | Promise<void>;
+interface AutoModeConfig {
+    mode?: "auto";
     WRITE_CODE: string;
     userId: string;
     recordingOptions?: SessionRecordingOptions;
     debug?: boolean;
 }
+interface ManualModeConfig {
+    mode: "manual";
+    onEvents: OnEventsCallback;
+    recordingOptions?: SessionRecordingOptions;
+    debug?: boolean;
+}
+type SessionRecorderConfig = AutoModeConfig | ManualModeConfig;
 
 declare class SessionRecorder {
     #private;
+    private mode;
     private userId?;
+    private onEvents?;
     private TIMEOUT;
     private BUFFER_SIZE;
     private maskingOptions;
-    private sessionUuid;
+    private sessionManager;
     private sessionEvents;
     private bufferBytes;
     private rrwebStop;
@@ -30,4 +53,4 @@ declare class SessionRecorder {
 }
 
 export { SessionRecorder as default };
-export type { MaskingOption, SessionRecorderConfig };
+export type { AutoModeConfig, EventBatch, ManualModeConfig, MaskingOption, OnEventsCallback, RecorderMode, SessionRecorderConfig };