@repliqo/sdk-react-native 0.1.0

package/src/core/client.ts

@@ -0,0 +1,425 @@
+import { AppState, AppStateStatus } from 'react-native';
+import {
+  AnalyticsEvent,
+  DeviceInfo,
+  ScreenVisit,
+  SDKConfig,
+} from '../types/events';
+import { SnapshotPayload } from '../types/snapshot';
+import { SnapshotCapture } from '../snapshot/capture';
+import { ResolvedConfig, resolveConfig } from './config';
+import { Logger } from './logger';
+import { ApiClient } from '../transport/api.client';
+import { BatchQueue } from '../transport/batch-queue';
+import { ErrorTracker } from '../trackers/error.tracker';
+// Native multi-window capture is used automatically via captureScreenshot()
+// when the ScreenCaptureModule is linked. No permission or service needed.
+
+export class AppAnalytics {
+  private static instance: AppAnalytics | null = null;
+
+  private config: ResolvedConfig;
+  private apiClient: ApiClient;
+  private eventQueue: BatchQueue<AnalyticsEvent>;
+  private screenVisitQueue: BatchQueue<ScreenVisit>;
+  private snapshotQueue: BatchQueue<SnapshotPayload>;
+  private snapshotCapture: SnapshotCapture | null = null;
+  private errorTracker: ErrorTracker | null = null;
+  private sessionId: string | null = null;
+  private currentScreen: string | null = null;
+  private currentScreenEnteredAt: string | null = null;
+  private logger: Logger;
+  private appStateSubscription: { remove: () => void } | null = null;
+
+  private constructor(config: SDKConfig) {
+    this.config = resolveConfig(config);
+    this.logger = new Logger(this.config.debug);
+    this.apiClient = new ApiClient(
+      this.config.baseUrl,
+      this.config.apiKey,
+      this.logger,
+    );
+
+    this.eventQueue = new BatchQueue<AnalyticsEvent>(
+      this.config.batchSize,
+      this.config.flushInterval,
+      async (events: AnalyticsEvent[]) => {
+        if (!this.sessionId) {
+          this.logger.warn(
+            'Cannot flush events: no active session',
+          );
+          throw new Error('No active session');
+        }
+        await this.apiClient.sendEventsBatch(this.sessionId, events);
+      },
+    );
+
+    this.screenVisitQueue = new BatchQueue<ScreenVisit>(
+      this.config.batchSize,
+      this.config.flushInterval,
+      async (visits: ScreenVisit[]) => {
+        await this.apiClient.sendScreenVisitsBatch(visits);
+      },
+    );
+
+    // Snapshots are heavier (~15-30 KB JPEG each) so they use a smaller
+    // batch size, shorter flush interval, and a tighter memory cap than
+    // the event queue. All configurable via SDKConfig.
+    this.snapshotQueue = new BatchQueue<SnapshotPayload>(
+      this.config.snapshotBatchSize,
+      this.config.snapshotFlushInterval,
+      async (snapshots: SnapshotPayload[]) => {
+        await this.apiClient.sendSnapshotsBatch(snapshots);
+      },
+      this.config.snapshotMaxBufferSize,
+    );
+
+    this.eventQueue.startAutoFlush();
+    this.screenVisitQueue.startAutoFlush();
+    this.snapshotQueue.startAutoFlush();
+
+    if (this.config.enableSnapshots) {
+      this.snapshotCapture = new SnapshotCapture(
+        {
+          captureInterval: this.config.snapshotInterval,
+          maxSnapshotsPerSession: this.config.maxSnapshotsPerSession,
+        },
+        (snapshot: SnapshotPayload) => {
+          this.snapshotQueue.add(snapshot);
+        },
+        undefined, // default captureScreenshot provider
+        (...args: any[]) => this.logger.log(...args),
+        (...args: any[]) => this.logger.warn(...args),
+      );
+    }
+
+    if (this.config.enableCrashTracking) {
+      this.errorTracker = new ErrorTracker((crash) => {
+        // Crash reports are sent immediately (fire-and-forget), not batched
+        this.apiClient.sendCrashReport(crash).catch(() => {});
+      });
+      this.errorTracker.start();
+    }
+
+    this.setupAppStateListener();
+
+    this.logger.log('SDK initialized with config:', {
+      baseUrl: this.config.baseUrl,
+      appId: this.config.appId,
+      batchSize: this.config.batchSize,
+      flushInterval: this.config.flushInterval,
+      enableSnapshots: this.config.enableSnapshots,
+      snapshotInterval: this.config.snapshotInterval,
+      enableCrashTracking: this.config.enableCrashTracking,
+    });
+  }
+
+  static init(config: SDKConfig): AppAnalytics {
+    if (AppAnalytics.instance) {
+      AppAnalytics.instance.logger.warn(
+        'AppAnalytics already initialized. Returning existing instance.',
+      );
+      return AppAnalytics.instance;
+    }
+
+    AppAnalytics.instance = new AppAnalytics(config);
+    return AppAnalytics.instance;
+  }
+
+  static getInstance(): AppAnalytics {
+    if (!AppAnalytics.instance) {
+      throw new Error(
+        'AppAnalytics not initialized. Call AppAnalytics.init(config) first.',
+      );
+    }
+    return AppAnalytics.instance;
+  }
+
+  static destroy(): void {
+    if (AppAnalytics.instance) {
+      const instance = AppAnalytics.instance;
+      instance.logger.log('Destroying AppAnalytics instance');
+
+      if (instance.errorTracker) {
+        instance.errorTracker.stop();
+        instance.errorTracker = null;
+      }
+
+      if (instance.snapshotCapture) {
+        instance.snapshotCapture.stop();
+        instance.snapshotCapture = null;
+      }
+
+
+      instance.eventQueue.stopAutoFlush();
+      instance.screenVisitQueue.stopAutoFlush();
+      instance.snapshotQueue.stopAutoFlush();
+
+      if (instance.appStateSubscription) {
+        instance.appStateSubscription.remove();
+        instance.appStateSubscription = null;
+      }
+
+      // Attempt a final flush (fire-and-forget)
+      instance.flush().catch(() => {});
+
+      AppAnalytics.instance = null;
+    }
+  }
+
+  async startSession(
+    deviceId: string,
+    deviceInfo?: DeviceInfo,
+  ): Promise<string> {
+    try {
+      const response = await this.apiClient.startSession(deviceId, deviceInfo);
+      this.sessionId = response.id;
+      this.logger.log('Session started with ID:', this.sessionId);
+
+      this.errorTracker?.setSessionId(this.sessionId);
+
+      if (this.snapshotCapture) {
+        this.snapshotCapture.setSessionId(this.sessionId);
+        this.snapshotCapture.reset();
+
+        // Native capture (MediaProjection) is NOT started automatically.
+        // It requires a system dialog that is confusing if shown on every
+        // launch. The host app can call enableNativeCapture() explicitly
+        // when the user opts in. Until then, view-shot is used.
+        this.startSnapshotCapture();
+      }
+
+      return this.sessionId;
+    } catch (error) {
+      this.logger.error('Failed to start session:', error);
+      throw error;
+    }
+  }
+
+  async endSession(): Promise<void> {
+    if (!this.sessionId) {
+      this.logger.warn('No active session to end');
+      return;
+    }
+
+    // Stop snapshot capture
+    this.stopSnapshotCapture();
+
+    // Flush any pending screen exit
+    if (this.currentScreen && this.currentScreenEnteredAt) {
+      this.onScreenExit(this.currentScreen);
+    }
+
+    // Flush remaining data
+    await this.flush();
+
+    try {
+      await this.apiClient.endSession(this.sessionId);
+      this.logger.log('Session ended:', this.sessionId);
+    } catch (error) {
+      this.logger.error('Failed to end session:', error);
+    }
+
+    this.sessionId = null;
+    this.currentScreen = null;
+    this.currentScreenEnteredAt = null;
+
+    this.errorTracker?.setSessionId(null);
+
+    if (this.snapshotCapture) {
+      this.snapshotCapture.setSessionId(null);
+    }
+  }
+
+  trackTouch(
+    x: number,
+    y: number,
+    screenName?: string,
+    extra?: Record<string, any>,
+  ): void {
+    if (!this.sessionId) {
+      this.logger.warn('Cannot track touch: no active session');
+      return;
+    }
+
+    if (!this.config.enableTouchTracking) {
+      return;
+    }
+
+    const event: AnalyticsEvent = {
+      type: 'touch',
+      screenName: screenName || this.currentScreen || undefined,
+      data: { x, y, ...extra },
+      timestamp: new Date().toISOString(),
+    };
+
+    this.eventQueue.add(event);
+    this.logger.log('Touch tracked:', event);
+  }
+
+  trackNavigation(fromScreen: string, toScreen: string): void {
+    if (!this.sessionId) {
+      this.logger.warn('Cannot track navigation: no active session');
+      return;
+    }
+
+    if (!this.config.enableNavigationTracking) {
+      return;
+    }
+
+    const event: AnalyticsEvent = {
+      type: 'navigation',
+      screenName: toScreen,
+      data: { fromScreen, toScreen },
+      timestamp: new Date().toISOString(),
+    };
+
+    this.eventQueue.add(event);
+    this.logger.log('Navigation tracked:', fromScreen, '->', toScreen);
+  }
+
+  trackCustomEvent(eventName: string, data?: Record<string, any>): void {
+    if (!this.sessionId) {
+      this.logger.warn('Cannot track custom event: no active session');
+      return;
+    }
+
+    const event: AnalyticsEvent = {
+      type: 'custom',
+      screenName: this.currentScreen || undefined,
+      data: { eventName, ...data },
+      timestamp: new Date().toISOString(),
+    };
+
+    this.eventQueue.add(event);
+    this.logger.log('Custom event tracked:', eventName);
+  }
+
+  reportError(error: Error, metadata?: Record<string, any>): void {
+    if (!this.errorTracker) {
+      this.logger.warn(
+        'Cannot report error: crash tracking is not enabled',
+      );
+      return;
+    }
+
+    this.errorTracker.reportError(error, metadata);
+  }
+
+  onScreenEnter(screenName: string): void {
+    this.currentScreen = screenName;
+    this.currentScreenEnteredAt = new Date().toISOString();
+    this.errorTracker?.setCurrentScreen(screenName);
+    this.snapshotCapture?.setCurrentScreen(screenName);
+    this.logger.log('Screen entered:', screenName);
+  }
+
+  onScreenExit(screenName: string): void {
+    if (
+      this.sessionId &&
+      this.currentScreen === screenName &&
+      this.currentScreenEnteredAt
+    ) {
+      const enteredAt = this.currentScreenEnteredAt;
+      const exitedAt = new Date().toISOString();
+      const duration =
+        new Date(exitedAt).getTime() - new Date(enteredAt).getTime();
+
+      const visit: ScreenVisit = {
+        sessionId: this.sessionId,
+        screenName,
+        enteredAt,
+        exitedAt,
+        duration,
+      };
+
+      this.screenVisitQueue.add(visit);
+      this.logger.log('Screen exited:', screenName, 'duration:', duration);
+    }
+
+    if (this.currentScreen === screenName) {
+      this.currentScreen = null;
+      this.currentScreenEnteredAt = null;
+      this.errorTracker?.setCurrentScreen(null);
+    }
+  }
+
+  async flush(): Promise<void> {
+    this.logger.log('Flushing queues...');
+    await Promise.all([
+      this.eventQueue.flush(),
+      this.screenVisitQueue.flush(),
+      this.snapshotQueue.flush(),
+    ]);
+    this.logger.log('Flush complete');
+  }
+
+  getSessionId(): string | null {
+    return this.sessionId;
+  }
+
+  getCurrentScreen(): string | null {
+    return this.currentScreen;
+  }
+
+  /**
+   * Force an immediate screenshot capture, outside the periodic schedule.
+   * Useful for capturing specific moments (e.g. right after a critical
+   * user action). Respects the in-flight lock and session cap.
+   */
+  async captureSnapshot(screenName?: string): Promise<void> {
+    if (!this.sessionId || !this.snapshotCapture) {
+      return;
+    }
+    if (screenName) {
+      this.snapshotCapture.setCurrentScreen(screenName);
+    }
+    await this.snapshotCapture.captureNow();
+  }
+
+  startSnapshotCapture(): void {
+    if (this.snapshotCapture) {
+      this.snapshotCapture.start();
+      this.logger.log('Snapshot capture started');
+    }
+  }
+
+  stopSnapshotCapture(): void {
+    if (this.snapshotCapture) {
+      this.snapshotCapture.stop();
+      this.logger.log('Snapshot capture stopped');
+    }
+  }
+
+  isInitialized(): boolean {
+    return true;
+  }
+
+  private setupAppStateListener(): void {
+    let wasInBackground = false;
+
+    this.appStateSubscription = AppState.addEventListener(
+      'change',
+      (nextAppState: AppStateStatus) => {
+        if (nextAppState === 'background' || nextAppState === 'inactive') {
+          this.logger.log(
+            'App going to background, pausing snapshots + flushing',
+          );
+          this.stopSnapshotCapture();
+          wasInBackground = true;
+
+          this.flush().catch((error) => {
+            this.logger.error('Error flushing on app state change:', error);
+          });
+        } else if (nextAppState === 'active' && wasInBackground) {
+          wasInBackground = false;
+          this.logger.log('App returned to foreground, resuming snapshots');
+
+          if (this.snapshotCapture && this.sessionId) {
+            this.startSnapshotCapture();
+          }
+        }
+      },
+    );
+  }
+}

package/src/core/config.ts

@@ -0,0 +1,27 @@
+import { SDKConfig } from '../types/events';
+
+export const DEFAULT_CONFIG: Required<Omit<SDKConfig, 'apiKey' | 'appId' | 'baseUrl'>> = {
+  batchSize: 20,
+  flushInterval: 30000,
+  enableTouchTracking: true,
+  enableNavigationTracking: true,
+  enableSnapshots: true,
+  // 0.5 fps. JPEG screenshots at 390px/40% quality are ~15-30 KB each,
+  // so 2 s gives a good quality/bandwidth tradeoff for MVP session replay.
+  snapshotInterval: 2000,
+  // Cap sessions at ~30 minutes of continuous capture (900 frames).
+  maxSnapshotsPerSession: 900,
+  // Smaller batches than events - JPEGs are heavier.
+  snapshotBatchSize: 8,
+  snapshotFlushInterval: 15000,
+  // ~32 * 30KB ≈ 1 MB cap on in-memory buffer if the backend is down.
+  snapshotMaxBufferSize: 32,
+  enableCrashTracking: true,
+  debug: false,
+};
+
+export type ResolvedConfig = SDKConfig & typeof DEFAULT_CONFIG;
+
+export function resolveConfig(config: SDKConfig): ResolvedConfig {
+  return { ...DEFAULT_CONFIG, ...config };
+}

package/src/core/logger.ts

@@ -0,0 +1,27 @@
+export class Logger {
+  private debugEnabled: boolean;
+  private prefix: string;
+
+  constructor(debugEnabled: boolean, prefix: string = '[Repliqo]') {
+    this.debugEnabled = debugEnabled;
+    this.prefix = prefix;
+  }
+
+  log(...args: any[]): void {
+    if (this.debugEnabled) {
+      console.log(this.prefix, ...args);
+    }
+  }
+
+  warn(...args: any[]): void {
+    if (this.debugEnabled) {
+      console.warn(this.prefix, ...args);
+    }
+  }
+
+  error(...args: any[]): void {
+    if (this.debugEnabled) {
+      console.error(this.prefix, ...args);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+// Main class
+export { AppAnalytics } from './core/client';
+
+// Trackers
+export { TouchTracker } from './trackers/touch.tracker';
+export {
+  useNavigationTracker,
+  trackScreenChange,
+} from './trackers/navigation.tracker';
+export {
+  trackScreenEnter,
+  trackScreenExit,
+} from './trackers/screen.tracker';
+export { ErrorTracker } from './trackers/error.tracker';
+
+// Snapshot
+export { SnapshotCapture } from './snapshot/capture';
+export { captureScreenshot } from './snapshot/captureScreenshot';
+export {
+  isNativeScreenCaptureAvailable,
+  captureNativeFrame,
+} from './snapshot/NativeScreenCapture';
+
+// Types
+export type {
+  EventType,
+  AnalyticsEvent,
+  TouchEventData,
+  NavigationEventData,
+  ScreenVisit,
+  DeviceInfo,
+  SDKConfig,
+} from './types/events';
+
+export type {
+  ScreenshotData,
+  SnapshotPayload,
+} from './types/snapshot';
+
+export type { CrashReport } from './types/crash';
+
+export type { SnapshotCaptureConfig } from './snapshot/capture';
+export type { ScreenshotResult } from './snapshot/captureScreenshot';
+
+// Config
+export { DEFAULT_CONFIG } from './core/config';
+export type { ResolvedConfig } from './core/config';

package/src/snapshot/NativeScreenCapture.ts

@@ -0,0 +1,54 @@
+import { NativeModules, Platform } from 'react-native';
+
+export interface NativeFrameResult {
+  image: string;
+  width: number;
+  height: number;
+  format: 'jpeg';
+}
+
+interface NativeScreenCaptureModule {
+  captureFrame(): Promise<{
+    image: string;
+    width: number;
+    height: number;
+    format: string;
+  } | null>;
+  isAvailable(): Promise<boolean>;
+}
+
+const NativeModule: NativeScreenCaptureModule | null =
+  Platform.OS === 'android'
+    ? (NativeModules.ScreenCaptureModule as NativeScreenCaptureModule) ?? null
+    : null;
+
+/** Whether the native multi-window capture module is available. */
+export function isNativeScreenCaptureAvailable(): boolean {
+  return NativeModule !== null;
+}
+
+/**
+ * Capture a single frame using native multi-window capture.
+ * Captures ALL visible windows: main view + modals + alerts + dialogs.
+ *
+ * No permissions required. No dialog. No foreground service.
+ *
+ * @returns NativeFrameResult or null if capture failed / not available
+ */
+export async function captureNativeFrame(): Promise<NativeFrameResult | null> {
+  if (!NativeModule) return null;
+
+  try {
+    const result = await NativeModule.captureFrame();
+    if (!result || !result.image) return null;
+
+    return {
+      image: result.image,
+      width: result.width,
+      height: result.height,
+      format: 'jpeg',
+    };
+  } catch {
+    return null;
+  }
+}