@repliqo/sdk-react-native 0.1.0

package/src/transport/api.client.ts

@@ -0,0 +1,225 @@
+import { AnalyticsEvent, DeviceInfo, ScreenVisit } from '../types/events';
+import { SnapshotPayload } from '../types/snapshot';
+import { CrashReport } from '../types/crash';
+import { Logger } from '../core/logger';
+
+export interface SessionResponse {
+  sessionId: string;
+}
+
+export class ApiClient {
+  private baseUrl: string;
+  private apiKey: string;
+  private logger: Logger;
+
+  constructor(baseUrl: string, apiKey: string, logger: Logger) {
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.apiKey = apiKey;
+    this.logger = logger;
+  }
+
+  private getHeaders(): Record<string, string> {
+    return {
+      'Content-Type': 'application/json',
+      'x-api-key': this.apiKey,
+    };
+  }
+
+  async startSession(
+    deviceId: string,
+    deviceInfo?: DeviceInfo,
+  ): Promise<{ id: string }> {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/sessions/start`, {
+        method: 'POST',
+        headers: this.getHeaders(),
+        body: JSON.stringify({ deviceId, deviceInfo }),
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        this.logger.error('Failed to start session:', response.status, text);
+        throw new Error(`Failed to start session: ${response.status}`);
+      }
+
+      const data: SessionResponse = await response.json();
+      this.logger.log('Session started:', data.sessionId);
+      return { id: data.sessionId };
+    } catch (error) {
+      this.logger.error('Error starting session:', error);
+      throw error;
+    }
+  }
+
+  async endSession(sessionId: string): Promise<void> {
+    try {
+      const response = await fetch(
+        `${this.baseUrl}/api/sessions/${sessionId}/end`,
+        {
+          method: 'PATCH',
+          headers: this.getHeaders(),
+        },
+      );
+
+      if (!response.ok) {
+        const text = await response.text();
+        this.logger.error('Failed to end session:', response.status, text);
+        return;
+      }
+
+      this.logger.log('Session ended:', sessionId);
+    } catch (error) {
+      this.logger.error('Error ending session:', error);
+    }
+  }
+
+  async sendEventsBatch(
+    sessionId: string,
+    events: AnalyticsEvent[],
+  ): Promise<{ count: number }> {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/events/batch`, {
+        method: 'POST',
+        headers: this.getHeaders(),
+        body: JSON.stringify({ sessionId, events }),
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        this.logger.error(
+          'Failed to send events batch:',
+          response.status,
+          text,
+        );
+        throw new Error(`Failed to send events batch: ${response.status}`);
+      }
+
+      const data = await response.json();
+      this.logger.log('Events batch sent, count:', data.count);
+      return { count: data.count };
+    } catch (error) {
+      this.logger.error('Error sending events batch:', error);
+      throw error;
+    }
+  }
+
+  async sendScreenVisitsBatch(visits: ScreenVisit[]): Promise<void> {
+    try {
+      const response = await fetch(
+        `${this.baseUrl}/api/screens/visit/batch`,
+        {
+          method: 'POST',
+          headers: this.getHeaders(),
+          body: JSON.stringify({ visits }),
+        },
+      );
+
+      if (!response.ok) {
+        const text = await response.text();
+        this.logger.error(
+          'Failed to send screen visits batch:',
+          response.status,
+          text,
+        );
+        throw new Error(
+          `Failed to send screen visits batch: ${response.status}`,
+        );
+      }
+
+      this.logger.log('Screen visits batch sent, count:', visits.length);
+    } catch (error) {
+      this.logger.error('Error sending screen visits batch:', error);
+      throw error;
+    }
+  }
+
+  async sendSnapshotsBatch(
+    snapshots: SnapshotPayload[],
+  ): Promise<{ count: number }> {
+    try {
+      const response = await fetch(
+        `${this.baseUrl}/api/snapshots/batch`,
+        {
+          method: 'POST',
+          headers: this.getHeaders(),
+          body: JSON.stringify({ snapshots }),
+        },
+      );
+
+      if (!response.ok) {
+        const text = await response.text();
+        this.logger.error(
+          'Failed to send snapshots batch:',
+          response.status,
+          text,
+        );
+        throw new Error(
+          `Failed to send snapshots batch: ${response.status}`,
+        );
+      }
+
+      const data = await response.json();
+      this.logger.log('Snapshots batch sent, count:', data.count);
+      return { count: data.count };
+    } catch (error) {
+      this.logger.error('Error sending snapshots batch:', error);
+      throw error;
+    }
+  }
+
+  async sendCrashReport(crash: CrashReport): Promise<void> {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/crashes`, {
+        method: 'POST',
+        headers: this.getHeaders(),
+        body: JSON.stringify(crash),
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        this.logger.error(
+          'Failed to send crash report:',
+          response.status,
+          text,
+        );
+        return;
+      }
+
+      this.logger.log('Crash report sent:', crash.type, crash.message);
+    } catch (error) {
+      // Fire-and-forget: catch errors silently, never throw
+      this.logger.error('Error sending crash report:', error);
+    }
+  }
+
+  async sendCrashesBatch(
+    crashes: CrashReport[],
+  ): Promise<{ count: number }> {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/crashes/batch`, {
+        method: 'POST',
+        headers: this.getHeaders(),
+        body: JSON.stringify({ crashes }),
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        this.logger.error(
+          'Failed to send crashes batch:',
+          response.status,
+          text,
+        );
+        throw new Error(
+          `Failed to send crashes batch: ${response.status}`,
+        );
+      }
+
+      const data = await response.json();
+      this.logger.log('Crashes batch sent, count:', data.count);
+      return { count: data.count };
+    } catch (error) {
+      this.logger.error('Error sending crashes batch:', error);
+      throw error;
+    }
+  }
+}

package/src/transport/batch-queue.ts

@@ -0,0 +1,95 @@
+export class BatchQueue<T> {
+  private buffer: T[] = [];
+  private maxSize: number;
+  private maxBufferSize: number;
+  private flushIntervalMs: number;
+  private onFlush: (items: T[]) => Promise<void>;
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+  private flushing: boolean = false;
+  // Exponential backoff state: on each failure we double the skip count,
+  // capped at 8 ticks. A successful flush resets it to 0.
+  private consecutiveFailures: number = 0;
+  private ticksToSkip: number = 0;
+  private static readonly MAX_BACKOFF_TICKS = 8;
+
+  constructor(
+    maxSize: number = 20,
+    flushIntervalMs: number = 30000,
+    onFlush: (items: T[]) => Promise<void>,
+    maxBufferSize: number = 1000,
+  ) {
+    this.maxSize = maxSize;
+    this.flushIntervalMs = flushIntervalMs;
+    this.onFlush = onFlush;
+    this.maxBufferSize = maxBufferSize;
+  }
+
+  add(item: T): void {
+    // Evict oldest items if buffer is at max capacity
+    if (this.buffer.length >= this.maxBufferSize) {
+      this.buffer.splice(0, this.buffer.length - this.maxBufferSize + 1);
+    }
+
+    this.buffer.push(item);
+    if (this.buffer.length >= this.maxSize) {
+      this.flush();
+    }
+  }
+
+  async flush(): Promise<void> {
+    if (this.buffer.length === 0 || this.flushing) {
+      return;
+    }
+
+    this.flushing = true;
+    const items = [...this.buffer];
+
+    try {
+      await this.onFlush(items);
+      // Only clear the items that were successfully flushed.
+      // New items might have been added during the async flush,
+      // so we splice out only the count we sent.
+      this.buffer.splice(0, items.length);
+      // Successful flush resets the backoff state.
+      this.consecutiveFailures = 0;
+      this.ticksToSkip = 0;
+    } catch {
+      // On failure, keep events in buffer so they can be retried.
+      // Apply exponential backoff: 1, 2, 4, 8 ticks skipped before
+      // the next auto-flush attempt.
+      this.consecutiveFailures++;
+      this.ticksToSkip = Math.min(
+        Math.pow(2, this.consecutiveFailures - 1),
+        BatchQueue.MAX_BACKOFF_TICKS,
+      );
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  startAutoFlush(): void {
+    if (this.intervalId !== null) {
+      return;
+    }
+    this.intervalId = setInterval(() => {
+      // Honor backoff: skip this tick if we're still in a cooldown from
+      // a previous failure.
+      if (this.ticksToSkip > 0) {
+        this.ticksToSkip--;
+        return;
+      }
+      this.flush();
+    }, this.flushIntervalMs);
+  }
+
+  stopAutoFlush(): void {
+    if (this.intervalId !== null) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+
+  get pending(): number {
+    return this.buffer.length;
+  }
+}

package/src/types/crash.ts

@@ -0,0 +1,10 @@
+export interface CrashReport {
+  sessionId?: string;
+  type: 'js_error' | 'native_crash' | 'unhandled_rejection';
+  message: string;
+  stackTrace?: string;
+  screenName?: string;
+  deviceInfo?: Record<string, any>;
+  metadata?: Record<string, any>;
+  timestamp: string;
+}

package/src/types/events.ts

@@ -0,0 +1,59 @@
+export type EventType = 'touch' | 'scroll' | 'gesture' | 'navigation' | 'custom';
+
+export interface AnalyticsEvent {
+  type: EventType;
+  screenName?: string;
+  data: Record<string, any>;
+  timestamp: string; // ISO 8601
+}
+
+export interface TouchEventData {
+  x: number;
+  y: number;
+  elementTag?: string;
+  elementText?: string;
+}
+
+export interface NavigationEventData {
+  fromScreen: string;
+  toScreen: string;
+}
+
+export interface ScreenVisit {
+  sessionId: string;
+  screenName: string;
+  enteredAt: string;
+  exitedAt?: string;
+  duration?: number;
+}
+
+export interface DeviceInfo {
+  os: string;
+  osVersion: string;
+  model: string;
+  brand: string;
+  screenWidth: number;
+  screenHeight: number;
+  appVersion?: string;
+}
+
+export interface SDKConfig {
+  apiKey: string;
+  appId: string;
+  baseUrl: string;
+  batchSize?: number;
+  flushInterval?: number;
+  enableTouchTracking?: boolean;
+  enableNavigationTracking?: boolean;
+  enableSnapshots?: boolean;
+  snapshotInterval?: number;
+  maxSnapshotsPerSession?: number;
+  /** Max snapshots per network batch. Defaults to 8. */
+  snapshotBatchSize?: number;
+  /** Auto-flush interval for the snapshot queue (ms). Defaults to 15000. */
+  snapshotFlushInterval?: number;
+  /** Max snapshots kept in memory if the backend is unreachable. Defaults to 32. */
+  snapshotMaxBufferSize?: number;
+  enableCrashTracking?: boolean;
+  debug?: boolean;
+}

package/src/types/snapshot.ts

@@ -0,0 +1,23 @@
+/**
+ * Repliqo snapshot types.
+ *
+ * The SDK captures JPEG screenshots of the view hierarchy via
+ * react-native-view-shot. Each snapshot is stored as a base64 JPEG
+ * together with its rendered dimensions.
+ */
+
+export interface ScreenshotData {
+  image: string;
+  width: number;
+  height: number;
+  format: 'jpeg';
+}
+
+export interface SnapshotPayload {
+  sessionId: string;
+  screenName: string;
+  timestamp: string;
+  sequence: number;
+  isDiff: boolean;
+  data: ScreenshotData;
+}