@scalebun-release/react-native 2.5.0

package/lib/module/features/replay/integrations/touch/ReplayRoot.js

@@ -0,0 +1,96 @@
+/**
+ * Session Replay SDK — ReplayRoot Component
+ *
+ * Root wrapper component for touch/interaction tracking.
+ * Wrap your app root with this to enable automatic interaction detection.
+ *
+ * Usage:
+ *   import { ReplayRoot } from '@scalebun/replay-sdk';
+ *
+ *   function App() {
+ *     return (
+ *       <ReplayRoot>
+ *         <NavigationContainer>...</NavigationContainer>
+ *       </ReplayRoot>
+ *     );
+ *   }
+ */
+
+import React, { useRef, useCallback } from 'react';
+import { View } from 'react-native';
+import { bridgeAdapter } from '../../bridge/adapters/bridgeAdapter';
+import { sessionOrchestrator } from '../../replay/session/sessionOrchestrator';
+import { logger } from '../../core/logger/logger';
+import { jsx as _jsx } from "react/jsx-runtime";
+const SCROLL_THRESHOLD = 20; // pixels
+const SWIPE_THRESHOLD = 80;
+const LONG_PRESS_THRESHOLD = 500; // ms
+const INTERACTION_DEBOUNCE_MS = 300;
+export function ReplayRoot({
+  children,
+  disableInteractionTracking = false
+}) {
+  const touchStartRef = useRef(null);
+  const lastInteractionRef = useRef(0);
+  const handleTouchStart = useCallback(event => {
+    if (disableInteractionTracking) return;
+    const touch = event.nativeEvent;
+    touchStartRef.current = {
+      x: touch.pageX,
+      y: touch.pageY,
+      timestamp: Date.now()
+    };
+  }, [disableInteractionTracking]);
+  const handleTouchEnd = useCallback(event => {
+    if (disableInteractionTracking || !touchStartRef.current) return;
+    if (!sessionOrchestrator.isRecording) return;
+    const now = Date.now();
+    // Debounce
+    if (now - lastInteractionRef.current < INTERACTION_DEBOUNCE_MS) return;
+    lastInteractionRef.current = now;
+    const touch = event.nativeEvent;
+    const start = touchStartRef.current;
+    touchStartRef.current = null;
+    const dx = touch.pageX - start.x;
+    const dy = touch.pageY - start.y;
+    const distance = Math.sqrt(dx * dx + dy * dy);
+    const duration = now - start.timestamp;
+    let interactionType;
+    if (duration >= LONG_PRESS_THRESHOLD && distance < SCROLL_THRESHOLD) {
+      interactionType = 'long_press';
+    } else if (distance >= SWIPE_THRESHOLD) {
+      interactionType = Math.abs(dx) > Math.abs(dy) ? 'swipe' : 'scroll';
+    } else if (distance >= SCROLL_THRESHOLD) {
+      interactionType = 'scroll';
+    } else {
+      interactionType = 'tap';
+    }
+
+    // Fire and forget — never block the UI
+    bridgeAdapter.reportInteraction({
+      type: interactionType,
+      x: Math.round(touch.pageX),
+      y: Math.round(touch.pageY),
+      timestamp: now,
+      duration,
+      screenName: sessionOrchestrator.currentScreen
+    }).catch(() => {});
+
+    // Also trigger a frame capture for interaction modes
+    bridgeAdapter.captureFrame('interaction').catch(() => {});
+    __DEV__ && logger.debug(`Interaction: ${interactionType} at (${Math.round(touch.pageX)}, ${Math.round(touch.pageY)})`);
+  }, [disableInteractionTracking]);
+  return /*#__PURE__*/_jsx(View, {
+    style: {
+      flex: 1
+    },
+    onStartShouldSetResponder: () => true,
+    onStartShouldSetResponderCapture: () => false,
+    onMoveShouldSetResponder: () => false,
+    onResponderGrant: handleTouchStart,
+    onResponderRelease: handleTouchEnd,
+    collapsable: false,
+    children: children
+  });
+}
+//# sourceMappingURL=ReplayRoot.js.map

package/lib/module/features/replay/pipeline/batching/batchManager.js

@@ -0,0 +1,113 @@
+/**
+ * Session Replay SDK — Batch Manager
+ *
+ * Accumulates frames and events, then creates upload batches
+ * when batch size is reached or flush is triggered.
+ */
+
+import { BoundedQueue } from '../../core/queue/boundedQueue';
+import { generateBatchId } from '../../core/ids/sessionId';
+import { logger } from '../../core/logger/logger';
+class BatchManager {
+  _batchSize = 10;
+  _batchIndex = 0;
+  _sessionId = null;
+  _pendingFrames = [];
+  _pendingEvents = [];
+  _pendingImages = {};
+  _readyBatches = new BoundedQueue(50);
+  configure(batchSize) {
+    this._batchSize = Math.max(1, Math.min(batchSize, 50));
+  }
+  setSessionId(sessionId) {
+    this._sessionId = sessionId;
+    this._batchIndex = 0;
+    this._pendingFrames.length = 0;
+    this._pendingEvents.length = 0;
+    Object.keys(this._pendingImages).forEach(k => delete this._pendingImages[k]);
+  }
+
+  /** Add a frame to the pending batch */
+  addFrame(frame, base64Image) {
+    this._pendingFrames.push(frame);
+    this._pendingImages[frame.frameId] = base64Image;
+    if (this._pendingFrames.length >= this._batchSize) {
+      this._createBatch();
+    }
+  }
+
+  /** Add an event to the pending batch */
+  addEvent(event) {
+    this._pendingEvents.push(event);
+  }
+
+  /** Force-flush all pending items into a batch */
+  flush() {
+    if (this._pendingFrames.length === 0 && this._pendingEvents.length === 0) {
+      return null;
+    }
+    return this._createBatch();
+  }
+
+  /** Dequeue the next ready batch for upload */
+  dequeueReadyBatch() {
+    return this._readyBatches.dequeue();
+  }
+
+  /** Check if there are ready batches */
+  get hasReadyBatches() {
+    return !this._readyBatches.isEmpty;
+  }
+  get pendingFrameCount() {
+    return this._pendingFrames.length;
+  }
+  get readyBatchCount() {
+    return this._readyBatches.size;
+  }
+
+  /** Reset all state */
+  reset() {
+    this._batchIndex = 0;
+    this._sessionId = null;
+    this._pendingFrames.length = 0;
+    this._pendingEvents.length = 0;
+    Object.keys(this._pendingImages).forEach(k => delete this._pendingImages[k]);
+    this._readyBatches.clear();
+  }
+  _createBatch() {
+    const batch = {
+      batchId: generateBatchId(),
+      sessionId: this._sessionId ?? 'unknown',
+      batchIndex: this._batchIndex++,
+      frames: [...this._pendingFrames],
+      events: [...this._pendingEvents],
+      images: {
+        ...this._pendingImages
+      },
+      createdAt: Date.now(),
+      sizeBytes: this._estimateSize()
+    };
+
+    // Clear pending
+    this._pendingFrames.length = 0;
+    this._pendingEvents.length = 0;
+    Object.keys(this._pendingImages).forEach(k => delete this._pendingImages[k]);
+
+    // Enqueue for upload
+    if (!this._readyBatches.enqueue(batch)) {
+      logger.warn('Batch queue full — dropping oldest batch');
+    }
+    __DEV__ && logger.debug(`Batch created: ${batch.batchId} (${batch.frames.length} frames, ${batch.events.length} events)`);
+    return batch;
+  }
+  _estimateSize() {
+    let size = 0;
+    for (const img of Object.values(this._pendingImages)) {
+      size += img.length; // base64 string length approximates byte size
+    }
+    size += JSON.stringify(this._pendingEvents).length;
+    return size;
+  }
+}
+export const batchManager = new BatchManager();
+//# sourceMappingURL=batchManager.js.map

package/lib/module/features/replay/pipeline/envelope/envelopeBuilder.js

@@ -0,0 +1,43 @@
+/**
+ * Session Replay SDK — Envelope Builder
+ *
+ * Constructs upload payload envelopes for session manifest,
+ * frame batches, event batches, and finalization payloads.
+ */
+
+import { SessionState } from '../../public/enums';
+const SCHEMA_VERSION = 1;
+export function buildSessionManifest(session, totalBatches, finalized) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    session,
+    totalBatches,
+    finalized
+  };
+}
+export function buildFrameBatch(sessionId, batchIndex, frames, images) {
+  return {
+    sessionId,
+    batchIndex,
+    frames,
+    images
+  };
+}
+export function buildEventBatch(sessionId, batchIndex, events) {
+  return {
+    sessionId,
+    batchIndex,
+    events
+  };
+}
+export function buildFinalization(sessionId, endedAt, durationMs, totalFrames, totalEvents) {
+  return {
+    sessionId,
+    endedAt,
+    durationMs,
+    totalFrames,
+    totalEvents,
+    finalState: SessionState.Completed
+  };
+}
+//# sourceMappingURL=envelopeBuilder.js.map

package/lib/module/features/replay/pipeline/retry/retryPolicy.js

@@ -0,0 +1,45 @@
+/**
+ * Session Replay SDK — Retry Policy
+ *
+ * Exponential backoff retry for upload failures.
+ */
+
+import { logger } from '../../core/logger/logger';
+export const DEFAULT_RETRY_CONFIG = {
+  maxAttempts: 3,
+  baseDelayMs: 1000,
+  maxDelayMs: 30_000,
+  backoffMultiplier: 2
+};
+
+/** Calculate delay for a given attempt number (exponential backoff with jitter) */
+export function calculateDelay(attempt, config = DEFAULT_RETRY_CONFIG) {
+  const exponential = config.baseDelayMs * Math.pow(config.backoffMultiplier, attempt);
+  const capped = Math.min(exponential, config.maxDelayMs);
+  // Add jitter: ±25%
+  const jitter = capped * 0.25 * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(capped + jitter));
+}
+
+/** Execute an async function with retry policy */
+export async function withRetry(label, fn, shouldRetry, config = DEFAULT_RETRY_CONFIG) {
+  let lastError;
+  for (let attempt = 0; attempt < config.maxAttempts; attempt++) {
+    try {
+      return await fn(attempt);
+    } catch (err) {
+      lastError = err;
+      if (attempt >= config.maxAttempts - 1 || !shouldRetry(err, attempt)) {
+        break;
+      }
+      const delay = calculateDelay(attempt, config);
+      __DEV__ && logger.debug(`${label}: retry ${attempt + 1}/${config.maxAttempts} in ${delay}ms`);
+      await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=retryPolicy.js.map

package/lib/module/features/replay/pipeline/transport/transportTypes.js

@@ -0,0 +1,60 @@
+/**
+ * Session Replay SDK — Transport Types
+ *
+ * Transport layer interfaces for session upload.
+ */
+
+/**
+ * Transport interface — implemented by native or JS-side HTTP clients.
+ * The native implementation is preferred for background upload support.
+ */
+
+/** Default JS-side transport using fetch */
+export class FetchTransport {
+  _abortController = null;
+  constructor(config) {
+    this._config = config;
+  }
+  async send(payload) {
+    this._abortController = new AbortController();
+    const url = `${this._config.endpoint}${payload.path}`;
+    try {
+      const response = await fetch(url, {
+        method: payload.method,
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': this._config.apiKey,
+          ...payload.headers
+        },
+        body: payload.body,
+        signal: this._abortController.signal
+      });
+      return {
+        success: response.ok,
+        statusCode: response.status,
+        retryable: response.status >= 500 || response.status === 429,
+        error: response.ok ? undefined : `HTTP ${response.status}`
+      };
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        return {
+          success: false,
+          statusCode: 0,
+          retryable: false,
+          error: 'Cancelled'
+        };
+      }
+      return {
+        success: false,
+        statusCode: 0,
+        retryable: true,
+        error: err?.message ?? 'Network error'
+      };
+    }
+  }
+  cancel() {
+    this._abortController?.abort();
+    this._abortController = null;
+  }
+}
+//# sourceMappingURL=transportTypes.js.map

package/lib/module/features/replay/public/api.js

@@ -0,0 +1,332 @@
+/**
+ * Session Replay SDK — Public API Facade
+ *
+ * This is the main entry point for SDK consumers.
+ * All methods are no-throw — errors are logged and silently handled.
+ *
+ * Usage (standalone):
+ *   import { ReplaySdk } from '@scalebun/replay-sdk';
+ *   ReplaySdk.init({ apiKey: '...', endpoint: '...' });
+ *
+ * Usage (via scalebun-sdk):
+ *   // Called internally by bootstrap.ts:
+ *   ReplaySdk.init(config, { debugTransport: transport });
+ */
+
+import { validateConfig } from '../core/config/validator';
+import { sessionOrchestrator } from '../replay/session/sessionOrchestrator';
+import { breadcrumbCollector } from '../replay/breadcrumbs/breadcrumbCollector';
+import { bridgeAdapter } from '../bridge/adapters/bridgeAdapter';
+import { batchManager } from '../pipeline/batching/batchManager';
+import { installConsoleIntegration, uninstallConsoleIntegration, setConsoleEnabled } from '../integrations/logs/consoleIntegration';
+import { setNetworkEnabled } from '../integrations/network/networkAdapter';
+import { setVerbose, logger } from '../core/logger/logger';
+import { safeCall, safeCallAsync } from '../core/errors/safeCall';
+import { isDevOrEmulator } from '../core/env/environmentDetector';
+
+// Transport layer
+
+import { DesktopReplayTransport } from '../transport/DesktopReplayTransport';
+import { BackendReplayTransport } from '../transport/BackendReplayTransport';
+import { CompositeReplayTransport } from '../transport/CompositeReplayTransport';
+
+// ─── State ──────────────────────────────────────────────────────────────────
+
+let _initialized = false;
+let _config = null;
+let _transport = null;
+
+// ─── Init Options ───────────────────────────────────────────────────────────
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+export const ReplaySdk = {
+  // ─── Initialization ─────────────────────────────────────────────────
+
+  /**
+   * Initialize the Session Replay SDK.
+   *
+   * Must be called before any other SDK method.
+   * Safe to call multiple times — re-initializes with new config.
+   *
+   * @param partialConfig - SDK configuration (merged with defaults)
+   * @param opts - Optional init options (e.g. external debugTransport)
+   */
+  async init(partialConfig, opts) {
+    return safeCallAsync('ReplaySdk.init', async () => {
+      const {
+        config,
+        warnings
+      } = validateConfig(partialConfig);
+      _config = config;
+
+      // Apply verbose logging
+      setVerbose(config.verboseLogging);
+
+      // Log validation warnings
+      for (const w of warnings) {
+        logger.warn(`Config: ${w}`);
+      }
+      if (!config.enabled) {
+        __DEV__ && logger.info('SDK disabled via config');
+        return;
+      }
+
+      // ── Build transport layer ───────────────────────────────────
+      const transports = [];
+
+      // Desktop transport (always, if debugTransport provided)
+      if (opts?.debugTransport) {
+        transports.push(new DesktopReplayTransport(opts.debugTransport));
+        __DEV__ && logger.info('Desktop replay transport enabled');
+      }
+
+      // Backend transport (flag-controlled + env check)
+      if (config.sendToBackend && config.endpoint && config.apiKey) {
+        const shouldSkip = isDevOrEmulator() && !config.forceBackendInDev;
+        if (!shouldSkip) {
+          transports.push(new BackendReplayTransport({
+            endpoint: config.endpoint,
+            apiKey: config.apiKey,
+            batchSize: config.uploadBatchSize
+          }));
+          __DEV__ && logger.info('Backend replay transport enabled');
+        } else {
+          __DEV__ && logger.info('Backend replay transport skipped (dev/emulator mode)');
+        }
+      }
+
+      // Build composite transport
+      if (transports.length > 0) {
+        _transport = new CompositeReplayTransport(transports);
+      }
+
+      // ── Install integrations ────────────────────────────────────
+      if (config.sdkLogsEnabled) {
+        installConsoleIntegration();
+      }
+      setNetworkEnabled(config.networkLogsEnabled);
+
+      // Configure batch manager
+      batchManager.configure(config.uploadBatchSize);
+
+      // Initialize native module + session orchestrator
+      // Native module may not be available (e.g. no native build yet).
+      // That's fine — transport + JS integrations still work.
+      try {
+        const success = await sessionOrchestrator.initialize(config);
+        if (success) {
+          __DEV__ && logger.info('SDK initialized with native module');
+        } else {
+          logger.warn('Native module not available — transport-only mode');
+        }
+      } catch (nativeErr) {
+        logger.warn('Native module init failed (non-fatal):', nativeErr?.message);
+      }
+      _initialized = true;
+      __DEV__ && logger.info('SDK initialized successfully');
+    }, undefined);
+  },
+  // ─── Transport Access ───────────────────────────────────────────────
+
+  /** @internal Get the active transport (for integration with SessionManager) */
+  _getTransport() {
+    return _transport;
+  },
+  // ─── Session Lifecycle ──────────────────────────────────────────────
+
+  /** Start a new replay session */
+  async start() {
+    return safeCallAsync('ReplaySdk.start', async () => {
+      if (!_initialized) {
+        logger.warn('SDK not initialized');
+        return;
+      }
+      await sessionOrchestrator.start();
+    }, undefined);
+  },
+  /** Stop the current replay session and finalize */
+  async stop() {
+    return safeCallAsync('ReplaySdk.stop', async () => {
+      if (!_initialized) return;
+      await sessionOrchestrator.stop();
+    }, undefined);
+  },
+  /** Pause the current session (e.g. when app backgrounds) */
+  async pause() {
+    return safeCallAsync('ReplaySdk.pause', async () => {
+      if (!_initialized) return;
+      await sessionOrchestrator.pause();
+    }, undefined);
+  },
+  /** Resume a paused session */
+  async resume() {
+    return safeCallAsync('ReplaySdk.resume', async () => {
+      if (!_initialized) return;
+      await sessionOrchestrator.resume();
+    }, undefined);
+  },
+  // ─── Capture ────────────────────────────────────────────────────────
+
+  /** Manually trigger a frame capture */
+  async captureManualFrame() {
+    return safeCallAsync('ReplaySdk.captureManualFrame', async () => {
+      if (!_initialized) return;
+      await sessionOrchestrator.captureManualFrame();
+    }, undefined);
+  },
+  // ─── Configuration ──────────────────────────────────────────────────
+
+  /** Enable or disable the SDK at runtime */
+  async setEnabled(enabled) {
+    return safeCallAsync('ReplaySdk.setEnabled', async () => {
+      if (!_initialized) return;
+      await sessionOrchestrator.setEnabled(enabled);
+    }, undefined);
+  },
+  /** Change the capture mode at runtime */
+  async setCapturingMode(mode) {
+    return safeCallAsync('ReplaySdk.setCapturingMode', async () => {
+      if (!_initialized) return;
+      await sessionOrchestrator.setCapturingMode(mode);
+    }, undefined);
+  },
+  /** Change screenshot quality at runtime */
+  async setScreenshotQuality(quality) {
+    return safeCallAsync('ReplaySdk.setScreenshotQuality', async () => {
+      if (!_initialized) return;
+      await bridgeAdapter.setScreenshotQuality(quality);
+    }, undefined);
+  },
+  /** Change capture interval (frequency mode) */
+  async setScreenshotCaptureInterval(intervalMs) {
+    return safeCallAsync('ReplaySdk.setScreenshotCaptureInterval', async () => {
+      if (!_initialized) return;
+      await bridgeAdapter.setScreenshotCaptureInterval(intervalMs);
+    }, undefined);
+  },
+  /** Enable/disable user step tracking */
+  async setUserStepsEnabled(enabled) {
+    return safeCallAsync('ReplaySdk.setUserStepsEnabled', async () => {
+      if (!_initialized) return;
+      await bridgeAdapter.setEnabled(enabled);
+    }, undefined);
+  },
+  /** Enable/disable network log capture */
+  setNetworkLogsEnabled(enabled) {
+    safeCall('ReplaySdk.setNetworkLogsEnabled', () => {
+      setNetworkEnabled(enabled);
+    }, undefined);
+  },
+  /** Enable/disable SDK log capture */
+  setSdkLogsEnabled(enabled) {
+    safeCall('ReplaySdk.setSdkLogsEnabled', () => {
+      setConsoleEnabled(enabled);
+    }, undefined);
+  },
+  // ─── Screen Tracking ────────────────────────────────────────────────
+
+  /** Set the current screen name for replay context */
+  async setCurrentScreen(screenName) {
+    return safeCallAsync('ReplaySdk.setCurrentScreen', async () => {
+      if (!_initialized) return;
+      await sessionOrchestrator.setCurrentScreen(screenName);
+    }, undefined);
+  },
+  // ─── User Identity ──────────────────────────────────────────────────
+
+  /** Set user identity for the current session */
+  async setUser(user) {
+    return safeCallAsync('ReplaySdk.setUser', async () => {
+      if (!_initialized) return;
+      await sessionOrchestrator.setUser(user);
+    }, undefined);
+  },
+  /** Clear user identity */
+  async clearUser() {
+    return safeCallAsync('ReplaySdk.clearUser', async () => {
+      if (!_initialized) return;
+      await sessionOrchestrator.clearUser();
+    }, undefined);
+  },
+  // ─── Privacy ────────────────────────────────────────────────────────
+
+  /** Update privacy options at runtime */
+  async setPrivacyOptions(options) {
+    return safeCallAsync('ReplaySdk.setPrivacyOptions', async () => {
+      if (!_initialized || !_config) return;
+      _config.privacy = {
+        ..._config.privacy,
+        ...options
+      };
+      await bridgeAdapter.setPrivacyOptions(_config.privacy);
+    }, undefined);
+  },
+  // ─── Breadcrumbs ────────────────────────────────────────────────────
+
+  /** Add a custom breadcrumb to the session timeline */
+  async addBreadcrumb(breadcrumb) {
+    return safeCallAsync('ReplaySdk.addBreadcrumb', async () => {
+      await breadcrumbCollector.addBreadcrumb(breadcrumb);
+    }, undefined);
+  },
+  // ─── Sync / Upload ──────────────────────────────────────────────────
+
+  /** Set a callback invoked before each upload batch. Return false to cancel. */
+  setSyncCallback(callback) {
+    safeCall('ReplaySdk.setSyncCallback', () => {
+      sessionOrchestrator.setSyncCallback(callback);
+    }, undefined);
+  },
+  /** Force-flush pending data for upload */
+  async flush() {
+    return safeCallAsync('ReplaySdk.flush', async () => {
+      if (!_initialized) return;
+      await bridgeAdapter.flushUpload();
+    }, undefined);
+  },
+  // ─── Query ──────────────────────────────────────────────────────────
+
+  /** Get a link to the current session replay (if available) */
+  async getSessionReplayLink() {
+    return safeCallAsync('ReplaySdk.getSessionReplayLink', async () => {
+      if (!_initialized) return null;
+      const result = await bridgeAdapter.getSessionReplayLink();
+      if (!result) return null;
+      return {
+        url: result.url,
+        sessionId: result.sessionId,
+        uploaded: result.uploaded
+      };
+    }, null);
+  },
+  /** Get whether the SDK is currently recording */
+  get isRecording() {
+    return safeCall('ReplaySdk.isRecording', () => sessionOrchestrator.isRecording, false);
+  },
+  /** Get the current session ID */
+  get sessionId() {
+    return safeCall('ReplaySdk.sessionId', () => sessionOrchestrator.sessionId, null);
+  },
+  // ─── Cleanup ────────────────────────────────────────────────────────
+
+  /** Destroy the SDK and release all resources */
+  async destroy() {
+    return safeCallAsync('ReplaySdk.destroy', async () => {
+      uninstallConsoleIntegration();
+      batchManager.reset();
+      breadcrumbCollector.clear();
+      await sessionOrchestrator.destroy();
+
+      // Destroy transport
+      if (_transport) {
+        _transport.destroy();
+        _transport = null;
+      }
+      _initialized = false;
+      _config = null;
+      __DEV__ && logger.info('SDK destroyed');
+    }, undefined);
+  }
+};
+//# sourceMappingURL=api.js.map