@repliqo/sdk-react-native 0.3.8 → 0.4.0

package/src/core/config.ts

@@ -1,30 +1,38 @@
-import { SDKConfig } from '../types/events';
-
-export const REPLIQO_API_URL = 'https://api-repliqo.odmservice.site';
-
-export const DEFAULT_CONFIG: Required<Omit<SDKConfig, 'apiKey' | 'appId'>> = {
-  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,
-  enableHeatmapCapture: true,
-  enableCrashTracking: true,
-  debug: false,
-};
-
-export type ResolvedConfig = SDKConfig & typeof DEFAULT_CONFIG;
-
-export function resolveConfig(config: SDKConfig): ResolvedConfig {
-  return { ...DEFAULT_CONFIG, ...config };
-}
+import { SDKConfig } from '../types/events';
+
+export const REPLIQO_API_URL = 'https://api-repliqo.odmservice.site';
+
+export const DEFAULT_CONFIG: Required<
+  Omit<SDKConfig, 'apiKey' | 'appId' | 'storage'>
+> = {
+  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,
+  enableHeatmapCapture: true,
+  enableCrashTracking: true,
+  debug: false,
+};
+
+export type ResolvedConfig = SDKConfig & typeof DEFAULT_CONFIG;
+
+export function resolveConfig(config: SDKConfig): ResolvedConfig {
+  // Strip keys whose value is explicitly `undefined` — otherwise
+  // `{ enableSnapshots: maybeUndefinedVar }` would silently override the
+  // default `true` with `undefined` and disable the feature.
+  const cleaned = Object.fromEntries(
+    Object.entries(config).filter(([, v]) => v !== undefined),
+  ) as SDKConfig;
+  return { ...DEFAULT_CONFIG, ...cleaned };
+}

package/src/core/storage.ts

@@ -0,0 +1,51 @@
+/**
+ * Minimal async key-value storage contract, compatible with
+ * @react-native-async-storage/async-storage (and trivially mockable).
+ *
+ * Used to persist analytics data across app kills:
+ *  - buffered events that couldn't be flushed before backgrounding
+ *  - crash reports (a fatal crash kills the app before the report's
+ *    network request can complete — persistence is the only way those
+ *    reports survive to the next launch)
+ */
+export interface PersistentStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+
+/* Dynamic optional require — AsyncStorage is an optional peer. */
+declare const require: any;
+
+/**
+ * Try to auto-load @react-native-async-storage/async-storage. Returns null
+ * when the host app doesn't have it installed — persistence is then
+ * disabled gracefully (in-memory only, pre-existing behavior).
+ */
+export function tryLoadAsyncStorage(): PersistentStorage | null {
+  try {
+    const mod = require('@react-native-async-storage/async-storage');
+    const storage = mod?.default ?? mod;
+    if (
+      storage &&
+      typeof storage.getItem === 'function' &&
+      typeof storage.setItem === 'function' &&
+      typeof storage.removeItem === 'function'
+    ) {
+      return storage as PersistentStorage;
+    }
+  } catch {
+    // Not installed — fine.
+  }
+  return null;
+}
+
+/** Storage keys namespaced to avoid colliding with the host app's data. */
+export const STORAGE_KEYS = {
+  pendingEvents: '@repliqo/pending_events',
+  pendingCrashes: '@repliqo/pending_crashes',
+} as const;
+
+/** Caps so a long-offline device can't grow storage unboundedly. */
+export const MAX_PERSISTED_EVENTS = 500;
+export const MAX_PERSISTED_CRASHES = 20;

package/src/index.ts

@@ -1,50 +1,54 @@
-// 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';
-
-// Components
-export { RepliqoScrollView } from './components/RepliqoScrollView';
-
-// Config
-export { DEFAULT_CONFIG } from './core/config';
-export type { ResolvedConfig } from './core/config';
+// 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';
+
+// Components
+export { RepliqoScrollView } from './components/RepliqoScrollView';
+export { RepliqoFlatList } from './components/RepliqoFlatList';
+
+// Storage (offline persistence contract)
+export type { PersistentStorage } from './core/storage';
+
+// Config
+export { DEFAULT_CONFIG } from './core/config';
+export type { ResolvedConfig } from './core/config';

package/src/snapshot/NativeScreenCapture.ts

@@ -1,62 +1,62 @@
-import { NativeModules, Platform } from 'react-native';
-
-export interface NativeFrameResult {
-  image: string;
-  width: number;
-  height: number;
-  format: 'jpeg';
-}
-
-interface NativeCaptureResult {
-  image: string;
-  width: number;
-  height: number;
-  format: string;
-}
-
-interface NativeScreenCaptureModule {
-  captureFrame(): Promise<NativeCaptureResult | 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.
- *
- * This is the ONLY native capture path. Full-content capture of
- * off-screen ScrollView content is NOT possible natively (React Native
- * doesn't render off-screen content to the GPU/view tree) — full-content
- * heatmap backgrounds are instead built collaboratively from viewport
- * tiles captured as the user naturally scrolls (see RepliqoScrollView).
- *
- * @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;
-  }
-}
+import { NativeModules, Platform } from 'react-native';
+
+export interface NativeFrameResult {
+  image: string;
+  width: number;
+  height: number;
+  format: 'jpeg';
+}
+
+interface NativeCaptureResult {
+  image: string;
+  width: number;
+  height: number;
+  format: string;
+}
+
+interface NativeScreenCaptureModule {
+  captureFrame(): Promise<NativeCaptureResult | 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.
+ *
+ * This is the ONLY native capture path. Full-content capture of
+ * off-screen ScrollView content is NOT possible natively (React Native
+ * doesn't render off-screen content to the GPU/view tree) — full-content
+ * heatmap backgrounds are instead built collaboratively from viewport
+ * tiles captured as the user naturally scrolls (see RepliqoScrollView).
+ *
+ * @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;
+  }
+}

package/src/snapshot/capture.ts

@@ -1,142 +1,154 @@
-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;
-  }
-}
+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;
+  }
+
+  /**
+   * Generation counter. Incremented on every start()/stop() so that timer
+   * chains from a PREVIOUS generation cannot reschedule themselves. Without
+   * it, a fast stop()→start() while a tick's capture is still in flight
+   * leaves two parallel timer chains alive (double capture rate).
+   */
+  private epoch = 0;
+
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    this.epoch++;
+    this.log('Snapshot capture started (interval:', this.config.captureInterval, 'ms)');
+    this.scheduleNext(this.epoch);
+  }
+
+  stop(): void {
+    this.running = false;
+    this.epoch++;
+    if (this.timeoutId !== null) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = null;
+    }
+    this.log('Snapshot capture stopped');
+  }
+
+  async captureNow(): Promise<void> {
+    await this.tick();
+  }
+
+  private scheduleNext(epoch: number): void {
+    if (!this.running || epoch !== this.epoch) return;
+    this.timeoutId = setTimeout(() => {
+      // Orphan timer from a previous generation — do nothing.
+      if (epoch !== this.epoch) return;
+      Promise.resolve(this.tick()).finally(() => {
+        if (this.running && epoch === this.epoch) {
+          this.scheduleNext(epoch);
+        }
+      });
+    }, 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;
+  }
+}