@multiplayer-app/session-recorder-react-native 1.3.16 → 1.3.21

package/src/session-recorder.ts

@@ -1,7 +1,7 @@
 import {
   SessionType,
   type ISession,
-  type IUserAttributes
+  type IUserAttributes,
 } from '@multiplayer-app/session-recorder-common';
 import { Observable } from 'lib0/observable';
 import { type eventWithTime } from '@rrweb/types';
@@ -20,7 +20,8 @@ import {
 import {
   SESSION_STOPPED_EVENT,
   REMOTE_SESSION_RECORDING_START,
-  REMOTE_SESSION_RECORDING_STOP
+  REMOTE_SESSION_RECORDING_STOP,
+  SESSION_SAVE_BUFFER_EVENT,
 } from './config';
 import { getFormattedDate, isSessionActive, getNavigatorInfo } from './utils';
 import {
@@ -31,6 +32,7 @@ import { BASE_CONFIG, getSessionRecorderConfig } from './config';
 
 import { StorageService } from './services/storage.service';
 import { NetworkService } from './services/network.service';
+import { CrashBufferService } from './services/crashBuffer.service';
 import {
   ApiService,
   type StartSessionRequest,
@@ -42,7 +44,8 @@ type SessionRecorderEvents = 'state-change' | 'init';
 
 class SessionRecorder
   extends Observable<SessionRecorderEvents>
-  implements ISessionRecorder, EventRecorder {
+  implements ISessionRecorder, EventRecorder
+{
   private _configs: SessionRecorderConfigs;
   private _apiService = new ApiService();
   private _socketService = new SocketService();
@@ -50,6 +53,8 @@ class SessionRecorder
   private _recorder = new RecorderReactNativeSDK();
   private _storageService = StorageService.getInstance();
   private _networkService = NetworkService.getInstance();
+  private _crashBuffer = CrashBufferService.getInstance();
+  private _isFlushingBuffer: boolean = false;
   private _startRequestController: AbortController | null = null;
 
   // Whether the session recorder is initialized
@@ -162,7 +167,10 @@ class SessionRecorder
   /**
    * Capture an exception manually and send it as an error trace.
    */
-  public captureException(error: unknown, errorInfo?: Record<string, any>): void {
+  public captureException(
+    error: unknown,
+    errorInfo?: Record<string, any>
+  ): void {
     try {
       const normalizedError = this._normalizeError(error);
       const normalizedErrorInfo = this._normalizeErrorInfo(errorInfo);
@@ -172,6 +180,119 @@ class SessionRecorder
     }
   }
 
+  public async flushBuffer(payload?: { reason?: string }): Promise<any> {
+    if (!this._configs?.buffering?.enabled) return null;
+    if (this._isFlushingBuffer) return null;
+    if (this.sessionState !== SessionState.stopped || this.sessionId)
+      return null;
+
+    const windowMs = Math.max(
+      10_000,
+      (this._configs.buffering.windowMinutes || 2) * 60 * 1000
+    );
+
+    this._isFlushingBuffer = true;
+    try {
+      const reason = payload?.reason || 'manual';
+      await this._crashBuffer.setAttrs({
+        sessionAttributes: this.sessionAttributes,
+        resourceAttributes: getNavigatorInfo(),
+        userAttributes: this._userAttributes,
+      });
+
+      const snapshot = await this._crashBuffer.snapshot(windowMs);
+      if (
+        snapshot.rrwebEvents.length === 0 &&
+        snapshot.otelSpans.length === 0
+      ) {
+        return null;
+      }
+
+      const request: StartSessionRequest = {
+        name: `${this._configs.application} ${getFormattedDate(new Date())}`,
+        stoppedAt: new Date().toISOString(),
+        sessionAttributes: this.sessionAttributes,
+        resourceAttributes: getNavigatorInfo(),
+        ...(this._userAttributes
+          ? { userAttributes: this._userAttributes }
+          : {}),
+        debugSessionData: {
+          meta: {
+            reason,
+            windowMs: snapshot.windowMs,
+            fromTs: snapshot.fromTs,
+            toTs: snapshot.toTs,
+          },
+          events: snapshot.rrwebEvents,
+          spans: snapshot.otelSpans.map((s) => s.span),
+          attrs: snapshot.attrs,
+        },
+      };
+
+      try {
+        const res = await this._apiService.startSession(request);
+        await this._crashBuffer.clear();
+        return res;
+      } catch (_e) {
+        // swallow: flush is best-effort; never throw into app code
+        return null;
+      }
+    } finally {
+      this._isFlushingBuffer = false;
+    }
+  }
+
+  private async _flushBuffer(sessionId: string): Promise<any> {
+    if (!this._configs?.buffering?.enabled) return null;
+    if (this._isFlushingBuffer) return null;
+    if (this.sessionState !== SessionState.stopped || this.sessionId)
+      return null;
+
+    const windowMs = Math.max(
+      10_000,
+      (this._configs.buffering.windowMinutes || 2) * 60 * 1000
+    );
+
+    this._isFlushingBuffer = true;
+    try {
+      const snapshot = await this._crashBuffer.snapshot(windowMs);
+      if (
+        snapshot.rrwebEvents.length === 0 &&
+        snapshot.otelSpans.length === 0
+      ) {
+        return null;
+      }
+      const spans = snapshot.otelSpans.map((s) => s.span);
+      const events = snapshot.rrwebEvents.map((e) => e.event);
+      await Promise.all([
+        this._tracer.exportTraces(spans),
+        this._apiService.exportEvents(sessionId, { events }),
+        this._apiService.updateSessionAttributes(sessionId, {
+          name: this._getSessionName(),
+          sessionAttributes: this.sessionAttributes,
+          resourceAttributes: getNavigatorInfo(),
+          userAttributes: this._userAttributes || undefined,
+        }),
+      ]);
+    } catch (_e) {
+      // swallow: flush is best-effort; never throw into app code
+    } finally {
+      await this._crashBuffer.clear();
+      this._isFlushingBuffer = false;
+    }
+  }
+
+  private async _createExceptionSession(span: any): Promise<void> {
+    try {
+      const session = await this._apiService.createErrorSession({ span });
+      if (session) {
+        void this._flushBuffer(session._id);
+      }
+    } catch (_ignored) {
+      // best-effort
+    }
+  }
+
   private async _loadStoredSessionData(): Promise<void> {
     try {
       await StorageService.initialize();
@@ -216,14 +337,39 @@ class SessionRecorder
       this._configs.captureHeaders
     );
 
+    // Crash buffer wiring (RN): set BEFORE tracer init so early spans don't get exported.
+    const bufferEnabled = Boolean(this._configs.buffering?.enabled);
+    const windowMs = Math.max(
+      10_000,
+      (this._configs.buffering?.windowMinutes || 2) * 60 * 1000
+    );
+    this._tracer.setCrashBuffer(
+      bufferEnabled ? this._crashBuffer : undefined,
+      windowMs
+    );
+
     this._tracer.init(this._configs);
     this._apiService.init(this._configs);
     this._socketService.init({
       apiKey: this._configs.apiKey,
       socketUrl: this._configs.apiBaseUrl,
-      keepAlive: this._configs.useWebsocket
+      keepAlive: this._configs.useWebsocket,
+      clientId: this._tracer.clientId,
     });
-    this._recorder.init(this._configs, this._socketService);
+
+    this._recorder.init(
+      this._configs,
+      this._socketService,
+      bufferEnabled ? this._crashBuffer : undefined,
+      { enabled: bufferEnabled, windowMs }
+    );
+
+    this._crashBuffer.on('error-span-appended', (payload) => {
+      if (this.sessionState !== SessionState.stopped || this.sessionId) return;
+      if (!payload.span) return;
+      this._createExceptionSession(payload.span);
+    });
+
     await this._networkService.init();
     this._setupNetworkCallbacks();
     this._registerSocketServiceListeners();
@@ -234,10 +380,42 @@ class SessionRecorder
         this.sessionState === SessionState.paused)
     ) {
       this._start();
+    } else {
+      this._startBufferOnlyRecording();
     }
     this.emit('init', []);
   }
 
+  private _startBufferOnlyRecording(): void {
+    if (!this._configs?.buffering?.enabled) return;
+    if (this.sessionState !== SessionState.stopped || this.sessionId) return;
+
+    const windowMs = Math.max(
+      10_000,
+      (this._configs.buffering.windowMinutes || 2) * 60 * 1000
+    );
+
+    // Best-effort: persist current attrs so flush has context.
+    this._crashBuffer.setAttrs({
+      sessionAttributes: this.sessionAttributes,
+      resourceAttributes: getNavigatorInfo(),
+      userAttributes: this._userAttributes,
+    });
+
+    // Wire buffer into tracer + recorder (only used when sessionId is null).
+    this._tracer.setCrashBuffer(this._crashBuffer, windowMs);
+    this._recorder.init(this._configs, this._socketService, this._crashBuffer, {
+      enabled: true,
+      windowMs,
+    });
+
+    // Start capturing events without an active debug session id.
+    try {
+      this._recorder.stop();
+    } catch (_e) {}
+    this._recorder.start(null, SessionType.MANUAL);
+  }
+
   /**
    * Register socket service event listeners
    */
@@ -248,18 +426,32 @@ class SessionRecorder
     });
 
     this._socketService.on(REMOTE_SESSION_RECORDING_START, (payload: any) => {
-      logger.info('SessionRecorder', 'Remote session recording started', payload);
+      logger.info(
+        'SessionRecorder',
+        'Remote session recording started',
+        payload
+      );
       if (this.sessionState === SessionState.stopped) {
         this.start();
       }
     });
 
     this._socketService.on(REMOTE_SESSION_RECORDING_STOP, (payload: any) => {
-      logger.info('SessionRecorder', 'Remote session recording stopped', payload);
+      logger.info(
+        'SessionRecorder',
+        'Remote session recording stopped',
+        payload
+      );
       if (this.sessionState !== SessionState.stopped) {
         this.stop();
       }
     });
+
+    this._socketService.on(SESSION_SAVE_BUFFER_EVENT, (payload: any) => {
+      if (payload?.debugSession?._id) {
+        void this._flushBuffer(payload.debugSession._id);
+      }
+    });
   }
 
   /**
@@ -409,7 +601,7 @@ class SessionRecorder
           sessionAttributes: this.sessionAttributes,
           resourceAttributes: getNavigatorInfo(),
           stoppedAt: Date.now(),
-          name: this._getSessionName()
+          name: this._getSessionName(),
         }
       );
 
@@ -486,7 +678,9 @@ class SessionRecorder
         sessionAttributes: this.sessionAttributes,
         resourceAttributes: getNavigatorInfo(),
         name: this._getSessionName(),
-        ...(this._userAttributes ? { userAttributes: this._userAttributes } : {}),
+        ...(this._userAttributes
+          ? { userAttributes: this._userAttributes }
+          : {}),
       };
       const request: StartSessionRequest = !this.continuousRecording
         ? payload
@@ -519,6 +713,10 @@ class SessionRecorder
     this.sessionType = this.sessionType;
 
     if (this.sessionId) {
+      // Switch from buffer-only recording to session recording cleanly.
+      try {
+        this._recorder.stop();
+      } catch (_e) {}
       this._tracer.start(this.sessionId, this.sessionType);
       this._recorder.start(this.sessionId, this.sessionType);
       if (this.session) {
@@ -533,15 +731,16 @@ class SessionRecorder
   private _stop(): void {
     this.sessionState = SessionState.stopped;
     this._socketService.unsubscribeFromSession(true);
-    this._tracer.shutdown();
+    this._tracer.stop();
     this._recorder.stop();
+    this._startBufferOnlyRecording();
   }
 
   /**
    * Pause the session tracing and recording
    */
   private _pause(): void {
-    this._tracer.shutdown();
+    this._tracer.stop();
     this._recorder.stop();
     this.sessionState = SessionState.paused;
   }
@@ -551,7 +750,10 @@ class SessionRecorder
    */
   private _resume(): void {
     if (this.sessionId) {
-      this._tracer.setSessionId(this.sessionId, this.sessionType);
+      this._tracer.start(this.sessionId, this.sessionType);
+      try {
+        this._recorder.stop();
+      } catch (_e) {}
       this._recorder.start(this.sessionId, this.sessionType);
     }
     this.sessionState = SessionState.started;
@@ -729,18 +931,19 @@ class SessionRecorder
     }
   }
 
-
   /**
    * Normalize an error info object to a Record<string, any>
    * @param errorInfo - the error info to normalize
    * @returns the normalized error info
    */
-  private _normalizeErrorInfo(errorInfo?: Record<string, any>): Record<string, any> {
-    if (!errorInfo) return {}
+  private _normalizeErrorInfo(
+    errorInfo?: Record<string, any>
+  ): Record<string, any> {
+    if (!errorInfo) return {};
     try {
-      return JSON.parse(JSON.stringify(errorInfo))
+      return JSON.parse(JSON.stringify(errorInfo));
     } catch (_e) {
-      return { errorInfo: String(errorInfo) }
+      return { errorInfo: String(errorInfo) };
     }
   }
 
@@ -749,7 +952,11 @@ class SessionRecorder
    * @returns the session name
    */
   private _getSessionName(date: Date = new Date()): string {
-    const userName = this.sessionAttributes?.userName || this._userAttributes?.userName || this._userAttributes?.name || '';
+    const userName =
+      this.sessionAttributes?.userName ||
+      this._userAttributes?.userName ||
+      this._userAttributes?.name ||
+      '';
     return userName
       ? `${userName}'s session on ${getFormattedDate(date, { month: 'short', day: 'numeric' })}`
       : `Session on ${getFormattedDate(date)}`;

package/src/types/session-recorder.ts

@@ -162,6 +162,18 @@ export interface SessionRecorderOptions {
   * @default true
   */
   useWebsocket?: boolean
+
+  /**
+   * (Optional) Client-side crash buffer configuration.
+   * When enabled, the SDK keeps a rolling window of recent events + traces
+   * even if the user did not start a manual/continuous recording.
+   */
+  buffering?: {
+    /** Enable/disable buffering. @default true */
+    enabled?: boolean
+    /** Rolling window size (minutes). @default 1 */
+    windowMinutes?: number
+  }
 }
 
 /**
@@ -349,6 +361,12 @@ export interface ISessionRecorder {
    * Capture an exception and send it as an error trace
    */
   captureException(error: unknown, errorInfo?: Record<string, any>): void;
+
+  /**
+   * Flush the local crash buffer by creating a debug session and uploading buffered data.
+   * No-op if a live recording is currently active.
+   */
+  flushBuffer(payload?: { reason?: string }): Promise<any>;
 }
 
 /**