@repliqo/sdk-react-native 0.1.0

package/src/snapshot/capture.ts

@@ -0,0 +1,142 @@
+import { SnapshotPayload, ScreenshotData } from '../types/snapshot';
+import { captureScreenshot } from './captureScreenshot';
+
+export interface SnapshotCaptureConfig {
+  captureInterval: number;
+  maxSnapshotsPerSession: number;
+}
+
+export type ScreenshotProvider = () => Promise<ScreenshotData | null>;
+
+type LogFn = (...args: any[]) => void;
+
+/**
+ * Captures JPEG screenshots of the RN view hierarchy at a fixed interval
+ * and forwards them to the host (usually the snapshot BatchQueue).
+ */
+export class SnapshotCapture {
+  private timeoutId: ReturnType<typeof setTimeout> | null = null;
+  private sequence: number = 0;
+  private config: SnapshotCaptureConfig;
+  private onSnapshot: (snapshot: SnapshotPayload) => void;
+  private sessionId: string | null = null;
+  private currentScreen: string = 'unknown';
+  private capturing: boolean = false;
+  private running: boolean = false;
+  private provider: ScreenshotProvider;
+  private log: LogFn;
+  private warn: LogFn;
+
+  constructor(
+    config: SnapshotCaptureConfig,
+    onSnapshot: (snapshot: SnapshotPayload) => void,
+    provider: ScreenshotProvider = captureScreenshot,
+    log: LogFn = () => {},
+    warn: LogFn = () => {},
+  ) {
+    this.config = config;
+    this.onSnapshot = onSnapshot;
+    this.provider = provider;
+    this.log = log;
+    this.warn = warn;
+  }
+
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    this.log('Snapshot capture started (interval:', this.config.captureInterval, 'ms)');
+    this.scheduleNext();
+  }
+
+  stop(): void {
+    this.running = false;
+    if (this.timeoutId !== null) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = null;
+    }
+    this.log('Snapshot capture stopped');
+  }
+
+  async captureNow(): Promise<void> {
+    await this.tick();
+  }
+
+  private scheduleNext(): void {
+    if (!this.running) return;
+    this.timeoutId = setTimeout(() => {
+      Promise.resolve(this.tick()).finally(() => {
+        if (this.running) {
+          this.scheduleNext();
+        }
+      });
+    }, this.config.captureInterval);
+  }
+
+  private async tick(): Promise<void> {
+    if (!this.sessionId) return;
+    if (this.capturing) return;
+
+    if (this.sequence >= this.config.maxSnapshotsPerSession) {
+      this.log('Max snapshots reached:', this.sequence);
+      this.stop();
+      return;
+    }
+
+    this.capturing = true;
+    let screenshot: ScreenshotData | null = null;
+    try {
+      screenshot = await this.provider();
+    } catch (err) {
+      this.warn('Snapshot capture failed:', err);
+      screenshot = null;
+    } finally {
+      this.capturing = false;
+    }
+
+    if (!screenshot) {
+      this.warn('Snapshot returned null (provider unavailable or failed)');
+      return;
+    }
+
+    // Strip `source` field before sending — the backend DTO only
+    // accepts { image, width, height, format } and rejects unknown props.
+    const { image, width, height, format } = screenshot;
+
+    const payload: SnapshotPayload = {
+      sessionId: this.sessionId,
+      screenName: this.currentScreen,
+      timestamp: new Date().toISOString(),
+      sequence: this.sequence,
+      isDiff: false,
+      data: { image, width, height, format },
+    };
+
+    this.sequence++;
+    this.log(
+      'Snapshot captured: seq=', this.sequence - 1,
+      'screen=', this.currentScreen,
+      'size=', Math.round(screenshot.image.length / 1024), 'KB',
+    );
+    this.onSnapshot(payload);
+  }
+
+  reset(): void {
+    this.sequence = 0;
+  }
+
+  setSessionId(sessionId: string | null): void {
+    this.sessionId = sessionId;
+  }
+
+  setCurrentScreen(screenName: string): void {
+    this.currentScreen = screenName;
+  }
+
+  getSequence(): number {
+    return this.sequence;
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+}

package/src/snapshot/captureScreenshot.ts

@@ -0,0 +1,109 @@
+import { Dimensions } from 'react-native';
+import {
+  isNativeScreenCaptureAvailable,
+  captureNativeFrame,
+} from './NativeScreenCapture';
+
+export type CaptureSource = 'native' | 'viewshot';
+
+export interface ScreenshotResult {
+  image: string;
+  width: number;
+  height: number;
+  format: 'jpeg';
+  /** Which capture method produced this frame. */
+  source: CaptureSource;
+}
+
+const TARGET_WIDTH = 390;
+const JPEG_QUALITY = 0.4;
+
+// --- view-shot fallback (lazy-loaded) ---
+
+let viewShotCaptureScreen: ((opts: any) => Promise<string>) | null = null;
+let viewShotResolved = false;
+
+function resolveViewShot(): ((opts: any) => Promise<string>) | null {
+  if (viewShotResolved) return viewShotCaptureScreen;
+  viewShotResolved = true;
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const viewShot = require('react-native-view-shot');
+    if (typeof viewShot.captureScreen === 'function') {
+      viewShotCaptureScreen = viewShot.captureScreen;
+    } else if (typeof viewShot.captureRef === 'function') {
+      viewShotCaptureScreen = (opts: any) =>
+        viewShot.captureRef('window', opts);
+    }
+  } catch {
+    // view-shot not installed - native capture only
+  }
+
+  return viewShotCaptureScreen;
+}
+
+/**
+ * Capture a JPEG screenshot using the best available method:
+ *
+ *  1. Native multi-window capture (Android) — uses View.draw() on all
+ *     app windows via WindowManagerGlobal reflection. Captures modals,
+ *     alerts, dialogs, overlays. No permissions needed.
+ *  2. react-native-view-shot fallback — captures the main RN view only
+ *     (no modals or native dialogs)
+ *  3. null — if both are unavailable
+ *
+ * Never throws. Returns null on any failure.
+ */
+export async function captureScreenshot(): Promise<ScreenshotResult | null> {
+  // Strategy 1: Native multi-window capture (preferred on Android)
+  if (isNativeScreenCaptureAvailable()) {
+    const native = await captureNativeFrame();
+    if (native) return { ...native, source: 'native' as CaptureSource };
+    // If native returns null (e.g. first frame not ready), fall through
+    // to view-shot for this single frame rather than showing nothing.
+  }
+
+  // Strategy 2: react-native-view-shot fallback
+  const captureScreen = resolveViewShot();
+  if (!captureScreen) return null;
+
+  try {
+    const { width: screenWidth, height: screenHeight } =
+      Dimensions.get('window');
+
+    const aspectRatio = screenHeight / screenWidth;
+    const outputWidth = Math.min(TARGET_WIDTH, screenWidth);
+    const outputHeight = Math.round(outputWidth * aspectRatio);
+
+    const base64 = await captureScreen({
+      format: 'jpg',
+      quality: JPEG_QUALITY,
+      width: outputWidth,
+      height: outputHeight,
+      result: 'base64',
+    });
+
+    if (typeof base64 !== 'string' || base64.length === 0) {
+      return null;
+    }
+
+    return {
+      image: base64,
+      width: outputWidth,
+      height: outputHeight,
+      format: 'jpeg',
+      source: 'viewshot' as CaptureSource,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Test-only: reset cached view-shot resolution.
+ */
+export function __resetCaptureRefForTests(): void {
+  viewShotCaptureScreen = null;
+  viewShotResolved = false;
+}

package/src/trackers/error.tracker.ts

@@ -0,0 +1,136 @@
+import { CrashReport } from '../types/crash';
+
+type CrashCallback = (crash: CrashReport) => void;
+
+export class ErrorTracker {
+  private onCrash: CrashCallback;
+  private sessionId: string | null = null;
+  private currentScreen: string | null = null;
+  private originalHandler:
+    | ((error: Error, isFatal?: boolean) => void)
+    | null = null;
+  private isActive = false;
+
+  constructor(onCrash: CrashCallback) {
+    this.onCrash = onCrash;
+  }
+
+  setSessionId(id: string | null): void {
+    this.sessionId = id;
+  }
+
+  setCurrentScreen(screen: string | null): void {
+    this.currentScreen = screen;
+  }
+
+  start(): void {
+    if (this.isActive) return;
+    this.isActive = true;
+    this.setupGlobalErrorHandler();
+    this.setupUnhandledRejectionHandler();
+  }
+
+  stop(): void {
+    if (!this.isActive) return;
+    this.isActive = false;
+    this.restoreGlobalErrorHandler();
+  }
+
+  /**
+   * Manual error reporting - allows consumers to report caught errors.
+   */
+  reportError(error: Error, metadata?: Record<string, any>): void {
+    try {
+      const crash: CrashReport = {
+        sessionId: this.sessionId || undefined,
+        type: 'js_error',
+        message: error.message,
+        stackTrace: error.stack || undefined,
+        screenName: this.currentScreen || undefined,
+        metadata,
+        timestamp: new Date().toISOString(),
+      };
+      this.onCrash(crash);
+    } catch (_e) {
+      // Never crash the app due to error reporting
+    }
+  }
+
+  private setupGlobalErrorHandler(): void {
+    try {
+      const ErrorUtils = (global as any).ErrorUtils;
+      if (ErrorUtils) {
+        this.originalHandler = ErrorUtils.getGlobalHandler();
+        ErrorUtils.setGlobalHandler(
+          (error: Error, isFatal?: boolean) => {
+            try {
+              const crash: CrashReport = {
+                sessionId: this.sessionId || undefined,
+                type: isFatal ? 'native_crash' : 'js_error',
+                message: error.message,
+                stackTrace: error.stack || undefined,
+                screenName: this.currentScreen || undefined,
+                metadata: { isFatal },
+                timestamp: new Date().toISOString(),
+              };
+              this.onCrash(crash);
+            } catch (_e) {
+              // Never crash the app due to error reporting
+            }
+
+            // Always call original handler so RN can handle the error
+            if (this.originalHandler) {
+              this.originalHandler(error, isFatal);
+            }
+          },
+        );
+      }
+    } catch (_e) {
+      // Never crash the app due to error handler setup
+    }
+  }
+
+  private setupUnhandledRejectionHandler(): void {
+    try {
+      if (typeof global !== 'undefined') {
+        (global as any).__analyticsUnhandledRejection = (
+          _id: number,
+          error: any,
+        ) => {
+          try {
+            const message =
+              error instanceof Error ? error.message : String(error);
+            const stack =
+              error instanceof Error ? error.stack : undefined;
+
+            const crash: CrashReport = {
+              sessionId: this.sessionId || undefined,
+              type: 'unhandled_rejection',
+              message,
+              stackTrace: stack || undefined,
+              screenName: this.currentScreen || undefined,
+              timestamp: new Date().toISOString(),
+            };
+            this.onCrash(crash);
+          } catch (_e) {
+            // Never crash the app due to error reporting
+          }
+        };
+      }
+    } catch (_e) {
+      // Never crash the app due to rejection handler setup
+    }
+  }
+
+  private restoreGlobalErrorHandler(): void {
+    try {
+      const ErrorUtils = (global as any).ErrorUtils;
+      if (ErrorUtils && this.originalHandler) {
+        ErrorUtils.setGlobalHandler(this.originalHandler);
+        this.originalHandler = null;
+      }
+    } catch (_e) {
+      // Never crash the app due to handler restoration
+    }
+  }
+}

package/src/trackers/navigation.tracker.ts

@@ -0,0 +1,98 @@
+import { useRef, useCallback } from 'react';
+import { AppAnalytics } from '../core/client';
+
+interface NavigationState {
+  routes: Array<{ name: string; key: string; state?: NavigationState }>;
+  index: number;
+}
+
+function getActiveRouteName(state: NavigationState | undefined): string | null {
+  if (!state) {
+    return null;
+  }
+
+  const route = state.routes[state.index];
+  if (!route) {
+    return null;
+  }
+
+  // Dive into nested navigators
+  if (route.state) {
+    return getActiveRouteName(route.state as NavigationState);
+  }
+
+  return route.name;
+}
+
+export function useNavigationTracker() {
+  const routeNameRef = useRef<string | null>(null);
+  const navigationRef = useRef<any>(null);
+
+  const onReady = useCallback(() => {
+    if (navigationRef.current) {
+      const state = navigationRef.current.getRootState() as
+        | NavigationState
+        | undefined;
+      const currentRouteName = getActiveRouteName(state);
+      routeNameRef.current = currentRouteName;
+
+      if (currentRouteName) {
+        try {
+          const analytics = AppAnalytics.getInstance();
+          analytics.onScreenEnter(currentRouteName);
+        } catch {
+          // AppAnalytics not initialized, silently ignore
+        }
+      }
+    }
+  }, []);
+
+  const onStateChange = useCallback(() => {
+    if (!navigationRef.current) {
+      return;
+    }
+
+    const state = navigationRef.current.getRootState() as
+      | NavigationState
+      | undefined;
+    const currentRouteName = getActiveRouteName(state);
+    const previousRouteName = routeNameRef.current;
+
+    if (
+      currentRouteName &&
+      previousRouteName &&
+      currentRouteName !== previousRouteName
+    ) {
+      try {
+        const analytics = AppAnalytics.getInstance();
+        analytics.trackNavigation(previousRouteName, currentRouteName);
+        analytics.onScreenExit(previousRouteName);
+        analytics.onScreenEnter(currentRouteName);
+      } catch {
+        // AppAnalytics not initialized, silently ignore
+      }
+    }
+
+    routeNameRef.current = currentRouteName;
+  }, []);
+
+  return {
+    navigationRef,
+    onStateChange,
+    onReady,
+  };
+}
+
+export function trackScreenChange(
+  fromScreen: string,
+  toScreen: string,
+): void {
+  try {
+    const analytics = AppAnalytics.getInstance();
+    analytics.trackNavigation(fromScreen, toScreen);
+    analytics.onScreenExit(fromScreen);
+    analytics.onScreenEnter(toScreen);
+  } catch {
+    // AppAnalytics not initialized, silently ignore
+  }
+}

package/src/trackers/screen.tracker.ts

@@ -0,0 +1,19 @@
+import { AppAnalytics } from '../core/client';
+
+export function trackScreenEnter(screenName: string): void {
+  try {
+    const analytics = AppAnalytics.getInstance();
+    analytics.onScreenEnter(screenName);
+  } catch {
+    // AppAnalytics not initialized, silently ignore
+  }
+}
+
+export function trackScreenExit(screenName: string): void {
+  try {
+    const analytics = AppAnalytics.getInstance();
+    analytics.onScreenExit(screenName);
+  } catch {
+    // AppAnalytics not initialized, silently ignore
+  }
+}

package/src/trackers/touch.tracker.tsx

@@ -0,0 +1,44 @@
+import React from 'react';
+import { View, GestureResponderEvent } from 'react-native';
+import { AppAnalytics } from '../core/client';
+
+interface TouchTrackerProps {
+  children: React.ReactNode;
+  screenName?: string;
+  enabled?: boolean;
+}
+
+export const TouchTracker: React.FC<TouchTrackerProps> = ({
+  children,
+  screenName,
+  enabled = true,
+}) => {
+  const handleTouchCapture = React.useCallback(
+    (event: GestureResponderEvent): boolean => {
+      if (!enabled) {
+        return false;
+      }
+
+      try {
+        const analytics = AppAnalytics.getInstance();
+        const { pageX, pageY } = event.nativeEvent;
+        analytics.trackTouch(pageX, pageY, screenName);
+      } catch {
+        // AppAnalytics not initialized, silently ignore
+      }
+
+      // Return false so touches pass through to children
+      return false;
+    },
+    [enabled, screenName],
+  );
+
+  return (
+    <View
+      style={{ flex: 1 }}
+      onStartShouldSetResponderCapture={handleTouchCapture}
+    >
+      {children}
+    </View>
+  );
+};