@repliqo/sdk-react-native 0.3.7 → 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,52 +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,
-  captureFullContent,
-} from './snapshot/NativeScreenCapture';
-export type { FullContentResult } 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,157 +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 NativeFullContentResult extends NativeCaptureResult {
-  isFullContent: boolean;
-}
-
-interface NativeTile {
-  image: string;
-  width: number;
-  height: number;
-  scrollOffsetY: number;
-  viewportHeight: number;
-  contentHeight: number;
-  format: string;
-}
-
-interface NativeScreenCaptureModule {
-  captureFrame(): Promise<NativeCaptureResult | null>;
-  captureFullContent(): Promise<NativeFullContentResult | null>;
-  scanFullContent(): Promise<NativeTile[] | 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;
-  }
-}
-
-/**
- * Capture the FULL content of the primary ScrollView on screen,
- * including content scrolled off-screen. Used for heatmap backgrounds.
- *
- * Falls back to a viewport capture if no ScrollView is found.
- * Max height: 5000px. JPEG quality: 60%. Width: ~500px.
- *
- * @returns NativeFrameResult or null if capture failed / not available
- */
-export interface FullContentResult extends NativeFrameResult {
-  /** True if the capture includes full scrollable content. False if viewport-only fallback. */
-  isFullContent: boolean;
-}
-
-/**
- * Capture the FULL content of the primary ScrollView on screen,
- * including content scrolled off-screen. Used for heatmap backgrounds.
- *
- * Falls back to a viewport capture if no ScrollView is found.
- * Max height: 5000px. JPEG quality: 60%. Width: ~500px.
- *
- * Known limitation: FlatList/SectionList use RecyclerView which only
- * renders visible items — full-content capture falls back to viewport.
- *
- * @returns FullContentResult with isFullContent flag, or null
- */
-export async function captureFullContent(): Promise<FullContentResult | null> {
-  if (!NativeModule) return null;
-
-  try {
-    const result = await NativeModule.captureFullContent();
-    if (!result || !result.image) return null;
-
-    return {
-      image: result.image,
-      width: result.width,
-      height: result.height,
-      format: 'jpeg',
-      isFullContent: !!result.isFullContent,
-    };
-  } catch {
-    return null;
-  }
-}
-
-export interface ScanTile {
-  image: string;
-  width: number;
-  height: number;
-  scrollOffsetY: number;
-  viewportHeight: number;
-  contentHeight: number;
-}
-
-/**
- * Perform a fast programmatic scroll-scan of the main ScrollView.
- * Captures the entire content as viewport tiles in ~300-500ms.
- *
- * The scan is invisible to the user — scroll position is saved and
- * restored. Returns an array of tiles covering the full content.
- *
- * @returns Array of tiles, or null if no ScrollView or not available
- */
-export async function scanFullContent(): Promise<ScanTile[] | null> {
-  if (!NativeModule) return null;
-
-  try {
-    const tiles = await NativeModule.scanFullContent();
-    if (!tiles || !Array.isArray(tiles) || tiles.length === 0) return null;
-
-    return tiles
-      .filter((t) => t && t.image)
-      .map((t) => ({
-        image: t.image,
-        width: t.width,
-        height: t.height,
-        scrollOffsetY: t.scrollOffsetY,
-        viewportHeight: t.viewportHeight,
-        contentHeight: t.contentHeight,
-      }));
-  } 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;
+  }
+}