@scalebun-release/react-native 2.5.0

package/src/features/replay/replay/session/sessionOrchestrator.ts

@@ -0,0 +1,286 @@
+/**
+ * Session Replay SDK — Session Orchestrator
+ *
+ * JS-side session lifecycle coordination.
+ * Manages state transitions, connects integrations to native module,
+ * and handles session timers/limits.
+ *
+ * This is the main coordinator — it does NOT own capture logic
+ * (that's native). It manages JS-side state, event subscriptions,
+ * and integration wiring.
+ */
+
+import { AppState, type AppStateStatus } from 'react-native';
+import type { ReplayConfig, ReplayUser, ReplaySyncCallback } from '../../public/types';
+import { SessionState, CapturingMode } from '../../public/enums';
+import { bridgeAdapter } from '../../bridge/adapters/bridgeAdapter';
+import {
+    replayEventEmitter,
+    type SessionStateChangedEvent,
+    type SessionLimitReachedEvent,
+    type ScreenChangedEvent,
+} from '../../bridge/eventEmitter';
+import { AutoScreenDetector } from '../../../navigation/AutoScreenDetector';
+import { logger } from '../../core/logger/logger';
+import { generateSessionId } from '../../core/ids/sessionId';
+import * as clock from '../../core/clock/clock';
+import { fireAndForget } from '../../core/errors/safeCall';
+
+class SessionOrchestrator {
+    private _config: ReplayConfig | null = null;
+    private _state: SessionState = SessionState.Idle;
+    private _sessionId: string | null = null;
+    private _user: ReplayUser | null = null;
+    private _syncCallback: ReplaySyncCallback | null = null;
+    private _currentScreen: string = 'unknown';
+    private _durationTimer: ReturnType<typeof setInterval> | null = null;
+    private _frequencyTimer: ReturnType<typeof setInterval> | null = null;
+    private _appStateSubscription: ReturnType<typeof AppState.addEventListener> | null = null;
+    private _initialized = false;
+    private _startedAt: number = 0;
+
+    // ─── Initialization ─────────────────────────────────────────────────
+
+    async initialize(config: ReplayConfig): Promise<boolean> {
+        if (this._initialized) {
+            logger.warn('SessionOrchestrator already initialized');
+            return true;
+        }
+
+        this._config = config;
+
+        // Initialize native module (non-fatal if unavailable)
+        try {
+            const success = await bridgeAdapter.initialize(config);
+            if (!success) {
+                __DEV__ && logger.info('Native replay module not available — running in transport-only mode');
+            }
+        } catch (nativeErr: any) {
+            __DEV__ && logger.info('Native replay module not available:', nativeErr?.message);
+        }
+
+        // Listen to native events (no-ops if native not available)
+        try { this._setupNativeEventListeners(); } catch { /* ignore */ }
+
+        // Listen to app state changes
+        this._appStateSubscription = AppState.addEventListener('change', this._onAppStateChange);
+
+        this._initialized = true;
+        __DEV__ && logger.info('SessionOrchestrator initialized');
+
+        // Auto-start if configured
+        if (config.autoStart && config.enabled) {
+            try { await this.start(); } catch { /* ignore if native unavailable */ }
+        }
+
+        return true;
+    }
+
+    // ─── Session Lifecycle ──────────────────────────────────────────────
+
+    async start(): Promise<void> {
+        if (!this._initialized || !this._config?.enabled) return;
+        if (this._state === SessionState.Recording) return;
+
+        this._sessionId = generateSessionId();
+        this._startedAt = clock.now();
+        clock.markSessionStart();
+
+        // Try native start — non-fatal if unavailable
+        await bridgeAdapter.startSession();
+
+        this._state = SessionState.Recording;
+        this._startDurationTimer();
+        this._startFrequencyTimerIfNeeded();
+
+        __DEV__ && logger.info(`Session started: ${this._sessionId}`);
+    }
+
+    async stop(): Promise<void> {
+        if (this._state === SessionState.Idle) return;
+
+        this._state = SessionState.Finalizing;
+        this._stopTimers();
+
+        await bridgeAdapter.stopSession();
+
+        this._state = SessionState.Idle;
+        clock.resetClock();
+
+        __DEV__ && logger.info(`Session stopped: ${this._sessionId}`);
+        this._sessionId = null;
+        this._startedAt = 0;
+    }
+
+    async pause(): Promise<void> {
+        if (this._state !== SessionState.Recording) return;
+        this._state = SessionState.Paused;
+        this._stopTimers();
+        await bridgeAdapter.pauseSession();
+        __DEV__ && logger.debug('Session paused');
+    }
+
+    async resume(): Promise<void> {
+        if (this._state !== SessionState.Paused) return;
+        this._state = SessionState.Recording;
+        this._startDurationTimer();
+        this._startFrequencyTimerIfNeeded();
+        await bridgeAdapter.resumeSession();
+        __DEV__ && logger.debug('Session resumed');
+    }
+
+    // ─── Capture ────────────────────────────────────────────────────────
+
+    async captureManualFrame(): Promise<void> {
+        if (this._state !== SessionState.Recording) return;
+        await bridgeAdapter.captureManualFrame();
+    }
+
+    // ─── Screen Tracking ────────────────────────────────────────────────
+
+    async setCurrentScreen(screenName: string): Promise<void> {
+        this._currentScreen = screenName;
+        if (this._state === SessionState.Recording) {
+            await bridgeAdapter.setCurrentScreen(screenName);
+        }
+    }
+
+    // ─── User ───────────────────────────────────────────────────────────
+
+    async setUser(user: ReplayUser): Promise<void> {
+        this._user = user;
+        await bridgeAdapter.setUser(user);
+    }
+
+    async clearUser(): Promise<void> {
+        this._user = null;
+        await bridgeAdapter.clearUser();
+    }
+
+    // ─── Sync Callback ─────────────────────────────────────────────────
+
+    setSyncCallback(callback: ReplaySyncCallback | null): void {
+        this._syncCallback = callback;
+    }
+
+    // ─── Configuration Updates ──────────────────────────────────────────
+
+    async setEnabled(enabled: boolean): Promise<void> {
+        if (this._config) this._config.enabled = enabled;
+        await bridgeAdapter.setEnabled(enabled);
+
+        if (!enabled && this._state === SessionState.Recording) {
+            await this.stop();
+        }
+    }
+
+    async setCapturingMode(mode: CapturingMode): Promise<void> {
+        if (this._config) this._config.captureMode = mode;
+        await bridgeAdapter.setCapturingMode(mode);
+        // Restart frequency timer if mode changed
+        this._stopFrequencyTimer();
+        this._startFrequencyTimerIfNeeded();
+    }
+
+    // ─── Internal: Timers ───────────────────────────────────────────────
+
+    private _startDurationTimer(): void {
+        const maxDuration = this._config?.maxSessionDurationMs ?? 300_000;
+        this._durationTimer = setTimeout(() => {
+            logger.warn(`Session max duration reached (${maxDuration}ms)`);
+            fireAndForget('auto-stop', () => this.stop());
+        }, maxDuration);
+    }
+
+    private _startFrequencyTimerIfNeeded(): void {
+        if (this._config?.captureMode !== CapturingMode.Frequency) return;
+        const interval = this._config.screenshotCaptureIntervalMs;
+        this._frequencyTimer = setInterval(() => {
+            if (this._state === SessionState.Recording) {
+                fireAndForget('frequency-capture', async () => { await bridgeAdapter.captureFrame('timer'); });
+            }
+        }, interval);
+    }
+
+    private _stopTimers(): void {
+        if (this._durationTimer) {
+            clearTimeout(this._durationTimer);
+            this._durationTimer = null;
+        }
+        this._stopFrequencyTimer();
+    }
+
+    private _stopFrequencyTimer(): void {
+        if (this._frequencyTimer) {
+            clearInterval(this._frequencyTimer);
+            this._frequencyTimer = null;
+        }
+    }
+
+    // ─── Internal: App State ────────────────────────────────────────────
+
+    private _onAppStateChange = (nextState: AppStateStatus): void => {
+        if (nextState === 'background' && this._state === SessionState.Recording) {
+            fireAndForget('background-pause', () => this.pause());
+        } else if (nextState === 'active' && this._state === SessionState.Paused) {
+            fireAndForget('foreground-resume', () => this.resume());
+        }
+    };
+
+    // ─── Internal: Native Event Listeners ───────────────────────────────
+
+    private _setupNativeEventListeners(): void {
+        replayEventEmitter.onSessionStateChanged((event: SessionStateChangedEvent) => {
+            __DEV__ && logger.debug(`Native state: ${event.previousState} → ${event.newState}`);
+        });
+
+        replayEventEmitter.onSessionLimitReached((event: SessionLimitReachedEvent) => {
+            logger.warn(`Session limit reached: ${event.limitType} (${event.currentValue}/${event.maxValue})`);
+            if (event.limitType === 'duration' || event.limitType === 'frames') {
+                fireAndForget('limit-stop', () => this.stop());
+            }
+        });
+
+        replayEventEmitter.onError((event) => {
+            logger.error(`Native error [${event.code}]: ${event.message}`);
+            if (event.fatal) {
+                fireAndForget('fatal-stop', () => this.stop());
+            }
+        });
+
+        replayEventEmitter.onScreenChanged((event: ScreenChangedEvent) => {
+            const name = event?.screenName;
+            if (!name || name === 'unknown') return;
+            // Update replay orchestrator's local screen state
+            this._currentScreen = name;
+            // Feed into AutoScreenDetector so SessionManager emits SCREEN_VIEW → backend
+            try {
+                AutoScreenDetector.getInstance().setNativeScreen(name);
+            } catch { /* no-throw */ }
+        });
+    }
+
+    // ─── Query ──────────────────────────────────────────────────────────
+
+    get state(): SessionState { return this._state; }
+    get sessionId(): string | null { return this._sessionId; }
+    get currentScreen(): string { return this._currentScreen; }
+    get isRecording(): boolean { return this._state === SessionState.Recording; }
+
+    // ─── Destroy ────────────────────────────────────────────────────────
+
+    async destroy(): Promise<void> {
+        this._stopTimers();
+        this._appStateSubscription?.remove();
+        replayEventEmitter.destroy();
+        await bridgeAdapter.destroy();
+        this._initialized = false;
+        this._state = SessionState.Idle;
+        this._sessionId = null;
+        this._config = null;
+        __DEV__ && logger.info('SessionOrchestrator destroyed');
+    }
+}
+
+/** Singleton orchestrator */
+export const sessionOrchestrator = new SessionOrchestrator();

package/src/features/replay/replay/timeline/timelineModels.ts

@@ -0,0 +1,129 @@
+/**
+ * Session Replay SDK — Timeline Models
+ *
+ * Internal timeline event representation and factory.
+ */
+
+import type { ReplayTimelineEvent } from '../../public/types';
+import { TimelineEventType } from '../../public/enums';
+import { generateEventId } from '../../core/ids/sessionId';
+import * as clock from '../../core/clock/clock';
+
+/** Create a timeline event */
+export function createTimelineEvent(params: {
+    sessionId: string;
+    type: TimelineEventType;
+    screenName: string;
+    label: string;
+    frameId?: string;
+    data?: Record<string, unknown>;
+}): ReplayTimelineEvent {
+    return {
+        eventId: generateEventId(),
+        sessionId: params.sessionId,
+        type: params.type,
+        timestamp: clock.now(),
+        screenName: params.screenName,
+        label: params.label,
+        frameId: params.frameId,
+        data: params.data,
+    };
+}
+
+/** Create a screen viewed event */
+export function screenViewedEvent(sessionId: string, screenName: string): ReplayTimelineEvent {
+    return createTimelineEvent({
+        sessionId,
+        type: TimelineEventType.ScreenViewed,
+        screenName,
+        label: `Viewed: ${screenName}`,
+    });
+}
+
+/** Create a user interaction event */
+export function interactionEvent(
+    sessionId: string,
+    screenName: string,
+    interactionType: string,
+    target?: string,
+): ReplayTimelineEvent {
+    const typeMap: Record<string, TimelineEventType> = {
+        tap: TimelineEventType.UserTap,
+        long_press: TimelineEventType.UserLongPress,
+        scroll: TimelineEventType.UserScroll,
+        swipe: TimelineEventType.UserSwipe,
+        text_input: TimelineEventType.TextInputChange,
+    };
+    return createTimelineEvent({
+        sessionId,
+        type: typeMap[interactionType] ?? TimelineEventType.UserTap,
+        screenName,
+        label: `${interactionType}${target ? ` on ${target}` : ''}`,
+        data: { interactionType, target },
+    });
+}
+
+/** Create a network request event */
+export function networkEvent(
+    sessionId: string,
+    screenName: string,
+    method: string,
+    url: string,
+    statusCode: number,
+    durationMs: number,
+): ReplayTimelineEvent {
+    return createTimelineEvent({
+        sessionId,
+        type: TimelineEventType.NetworkRequest,
+        screenName,
+        label: `${method} ${url} → ${statusCode} (${durationMs}ms)`,
+        data: { method, url, statusCode, durationMs },
+    });
+}
+
+/** Create a breadcrumb event */
+export function breadcrumbEvent(
+    sessionId: string,
+    screenName: string,
+    category: string,
+    message: string,
+    data?: Record<string, unknown>,
+): ReplayTimelineEvent {
+    return createTimelineEvent({
+        sessionId,
+        type: TimelineEventType.CustomBreadcrumb,
+        screenName,
+        label: `[${category}] ${message}`,
+        data: { category, ...data },
+    });
+}
+
+/** Create an error event */
+export function errorEvent(
+    sessionId: string,
+    screenName: string,
+    errorMessage: string,
+    fatal: boolean = false,
+): ReplayTimelineEvent {
+    return createTimelineEvent({
+        sessionId,
+        type: fatal ? TimelineEventType.CrashCaptured : TimelineEventType.ErrorCaptured,
+        screenName,
+        label: errorMessage,
+        data: { fatal },
+    });
+}
+
+/** Create an app lifecycle event */
+export function lifecycleEvent(
+    sessionId: string,
+    screenName: string,
+    foreground: boolean,
+): ReplayTimelineEvent {
+    return createTimelineEvent({
+        sessionId,
+        type: foreground ? TimelineEventType.AppForeground : TimelineEventType.AppBackground,
+        screenName,
+        label: foreground ? 'App entered foreground' : 'App entered background',
+    });
+}

package/src/features/replay/transport/BackendReplayTransport.ts

@@ -0,0 +1,215 @@
+/**
+ * Session Replay SDK — Backend Replay Transport
+ *
+ * Uploads replay data to a backend API via HTTP.
+ * Uses batching for frames/events and retry with exponential backoff.
+ *
+ * Design:
+ * - sendSessionStart → POST /v1/replay/sessions
+ * - sendFrame → buffered, flushed in batches to POST /v1/replay/sessions/:id/frames
+ * - sendEvent → buffered, flushed in batches to POST /v1/replay/sessions/:id/events
+ * - sendSessionEnd → flushes pending + POST /v1/replay/sessions/:id/finalize
+ *
+ * Never throws — all errors are caught and logged.
+ */
+
+import type {
+    ReplayTransport,
+    ReplaySessionStartPayload,
+    ReplaySessionEndPayload,
+    ReplayFramePayload,
+    ReplayEventPayload,
+} from './ReplayTransport';
+import { logger } from '../core/logger/logger';
+import { withRetry, DEFAULT_RETRY_CONFIG } from '../pipeline/retry/retryPolicy';
+
+// ─── Config ─────────────────────────────────────────────────────────────────
+
+export interface BackendTransportConfig {
+    endpoint: string;
+    apiKey: string;
+    /** Number of frames to batch before uploading. Default: 5 */
+    batchSize?: number;
+    /** Auto-flush interval in ms. Default: 3000 */
+    flushIntervalMs?: number;
+    /** Request timeout in ms. Default: 30000 */
+    timeoutMs?: number;
+}
+
+// ─── Implementation ─────────────────────────────────────────────────────────
+
+export class BackendReplayTransport implements ReplayTransport {
+    private _config: Required<BackendTransportConfig>;
+    private _pendingFrames: Array<{ frame: ReplayFramePayload; imageData: string }> = [];
+    private _pendingEvents: ReplayEventPayload[] = [];
+    private _flushTimer: ReturnType<typeof setInterval> | null = null;
+    private _currentSessionId: string | null = null;
+    private _destroyed = false;
+
+    constructor(config: BackendTransportConfig) {
+        this._config = {
+            batchSize: 5,
+            flushIntervalMs: 3000,
+            timeoutMs: 30_000,
+            ...config,
+        };
+    }
+
+    sendSessionStart(payload: ReplaySessionStartPayload): void {
+        this._currentSessionId = payload.sessionId;
+
+        // Start auto-flush timer
+        this._startFlushTimer();
+
+        // POST session manifest
+        this._post(`/v1/replay/sessions`, {
+            sessionId: payload.sessionId,
+            startedAt: payload.startedAt,
+            device: payload.device,
+            config: payload.config,
+        }).catch(() => { /* logged in _post */ });
+    }
+
+    sendFrame(frame: ReplayFramePayload, imageData: string): void {
+        if (this._destroyed) return;
+
+        this._pendingFrames.push({ frame, imageData });
+
+        if (this._pendingFrames.length >= this._config.batchSize) {
+            this._flushFrames().catch(() => { /* logged */ });
+        }
+    }
+
+    sendEvent(event: ReplayEventPayload): void {
+        if (this._destroyed) return;
+
+        this._pendingEvents.push(event);
+
+        // Flush events in batches of 20
+        if (this._pendingEvents.length >= 20) {
+            this._flushEvents().catch(() => { /* logged */ });
+        }
+    }
+
+    sendSessionEnd(payload: ReplaySessionEndPayload): void {
+        // Flush all pending data first
+        Promise.all([
+            this._flushFrames(),
+            this._flushEvents(),
+        ]).then(() => {
+            return this._post(
+                `/v1/replay/sessions/${payload.sessionId}/finalize`,
+                {
+                    endedAt: payload.endedAt,
+                    durationMs: payload.durationMs,
+                    totalFrames: payload.totalFrames,
+                    totalEvents: payload.totalEvents,
+                    finalState: payload.finalState,
+                },
+            );
+        }).catch(() => { /* logged */ }).finally(() => {
+            this._stopFlushTimer();
+        });
+    }
+
+    destroy(): void {
+        this._destroyed = true;
+        this._stopFlushTimer();
+        this._pendingFrames = [];
+        this._pendingEvents = [];
+        this._currentSessionId = null;
+    }
+
+    // ─── Internal: Flush ────────────────────────────────────────────────
+
+    private async _flushFrames(): Promise<void> {
+        if (this._pendingFrames.length === 0 || !this._currentSessionId) return;
+
+        const batch = this._pendingFrames.splice(0, this._config.batchSize);
+        const frames = batch.map(b => b.frame);
+        const images: Record<string, string> = {};
+        for (const b of batch) {
+            images[b.frame.frameId] = b.imageData;
+        }
+
+        try {
+            await this._post(
+                `/v1/replay/sessions/${this._currentSessionId}/frames`,
+                { frames, images },
+            );
+        } catch {
+            // Re-queue failed frames at the front
+            this._pendingFrames.unshift(...batch);
+        }
+    }
+
+    private async _flushEvents(): Promise<void> {
+        if (this._pendingEvents.length === 0 || !this._currentSessionId) return;
+
+        const batch = this._pendingEvents.splice(0, 20);
+
+        try {
+            await this._post(
+                `/v1/replay/sessions/${this._currentSessionId}/events`,
+                { events: batch },
+            );
+        } catch {
+            // Re-queue failed events at the front
+            this._pendingEvents.unshift(...batch);
+        }
+    }
+
+    // ─── Internal: Timer ────────────────────────────────────────────────
+
+    private _startFlushTimer(): void {
+        this._stopFlushTimer();
+        this._flushTimer = setInterval(() => {
+            this._flushFrames().catch(() => { /* logged */ });
+            this._flushEvents().catch(() => { /* logged */ });
+        }, this._config.flushIntervalMs);
+    }
+
+    private _stopFlushTimer(): void {
+        if (this._flushTimer) {
+            clearInterval(this._flushTimer);
+            this._flushTimer = null;
+        }
+    }
+
+    // ─── Internal: HTTP ─────────────────────────────────────────────────
+
+    private async _post(path: string, body: unknown): Promise<void> {
+        const url = `${this._config.endpoint}${path}`;
+
+        await withRetry(
+            `BackendTransport ${path}`,
+            async () => {
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), this._config.timeoutMs);
+
+                try {
+                    const response = await fetch(url, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                            'X-API-Key': this._config.apiKey,
+                        },
+                        body: JSON.stringify(body),
+                        signal: controller.signal,
+                    });
+
+                    if (!response.ok) {
+                        const err = new Error(`HTTP ${response.status}`);
+                        (err as any).status = response.status;
+                        (err as any).retryable = response.status >= 500 || response.status === 429;
+                        throw err;
+                    }
+                } finally {
+                    clearTimeout(timeout);
+                }
+            },
+            (err) => err?.retryable !== false,
+            DEFAULT_RETRY_CONFIG,
+        );
+    }
+}