@repliqo/sdk-react-native 0.3.8 → 0.4.1

package/src/transport/api.client.ts

@@ -1,327 +1,430 @@
-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;
-    }
-  }
-
-  /**
-   * Upload a full-content screen capture for heatmap backgrounds.
-   * Fire-and-forget: errors are logged but never thrown.
-   */
-  /**
-   * Upload a scroll tile for collaborative screen building.
-   *
-   * @param viewportTop Y position (window logical px) of the ScrollView's
-   *   top edge. Used by the backend to crop each tile to just the
-   *   scrollable area, removing fixed headers/footers that would
-   *   otherwise duplicate in the composite.
-   * @param windowHeight Window height (logical px) at capture time.
-   *   Used by the backend to compute image-to-logical scale for cropping.
-   */
-  async uploadScreenTile(
-    sessionId: string,
-    screenName: string,
-    image: string,
-    width: number,
-    height: number,
-    scrollOffsetY: number,
-    viewportHeight: number,
-    contentHeight: number,
-    viewportTop?: number,
-    windowHeight?: number,
-  ): Promise<void> {
-    try {
-      const body: Record<string, unknown> = {
-        sessionId,
-        screenName,
-        image,
-        width,
-        height,
-        scrollOffsetY: Math.round(scrollOffsetY),
-        viewportHeight: Math.round(viewportHeight),
-        contentHeight: Math.round(contentHeight),
-      };
-      if (typeof viewportTop === 'number' && Number.isFinite(viewportTop)) {
-        body.viewportTop = Math.round(viewportTop);
-      }
-      if (typeof windowHeight === 'number' && Number.isFinite(windowHeight)) {
-        body.windowHeight = Math.round(windowHeight);
-      }
-
-      const response = await fetch(
-        `${this.baseUrl}/api/screen-tiles`,
-        {
-          method: 'POST',
-          headers: this.getHeaders(),
-          body: JSON.stringify(body),
-        },
-      );
-
-      if (!response.ok) {
-        const text = await response.text();
-        this.logger.warn(
-          'Screen tile upload failed:',
-          response.status,
-          text?.substring(0, 200),
-        );
-      }
-    } catch (error) {
-      this.logger.warn('Error uploading screen tile:', error);
-    }
-  }
-
-  async uploadScreenCapture(
-    screenName: string,
-    image: string,
-    width: number,
-    height: number,
-    isFullContent: boolean,
-  ): Promise<void> {
-    try {
-      const response = await fetch(
-        `${this.baseUrl}/api/screen-captures`,
-        {
-          method: 'POST',
-          headers: this.getHeaders(),
-          body: JSON.stringify({
-            screenName,
-            image,
-            width,
-            height,
-            isFullContent,
-          }),
-        },
-      );
-
-      if (!response.ok) {
-        const text = await response.text();
-        this.logger.warn(
-          'Screen capture upload failed:',
-          response.status,
-          text?.substring(0, 200),
-        );
-      }
-    } catch (error) {
-      this.logger.warn('Error uploading screen capture:', error);
-    }
-  }
-}
+import { AnalyticsEvent, DeviceInfo, ScreenVisit } from '../types/events';
+import { SnapshotPayload } from '../types/snapshot';
+import { CrashReport } from '../types/crash';
+import { Logger } from '../core/logger';
+import { NonRetryableFlushError } from './batch-queue';
+
+export interface SessionResponse {
+  sessionId: string;
+}
+
+/** Abort any request that hasn't completed within this window. */
+const FETCH_TIMEOUT_MS = 15_000;
+
+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,
+    };
+  }
+
+  /**
+   * fetch with a hard timeout. Without it, a single stalled request keeps
+   * the BatchQueue's in-flight lock held indefinitely — no flush can run,
+   * the buffer fills up and starts evicting events (silent data loss).
+   */
+  private async fetchWithTimeout(
+    url: string,
+    init: RequestInit,
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Classify a non-ok batch response. Permanent PAYLOAD errors (the batch
+   * itself will never be accepted: 400 malformed, 413 too large, 422
+   * unprocessable, 404 gone) surface as NonRetryableFlushError so the
+   * queue drops the poison batch instead of retrying it forever.
+   *
+   * 401/403 are NOT the payload's fault — they mean the API key is wrong
+   * or was rotated. Treat them as transient (retry with backoff) so a key
+   * rotation doesn't silently destroy every live SDK's buffered data.
+   * 408/429 are transient by definition.
+   */
+  private batchError(context: string, status: number): Error {
+    const message = `${context}: ${status}`;
+    const isPermanent =
+      status >= 400 &&
+      status < 500 &&
+      status !== 401 &&
+      status !== 403 &&
+      status !== 408 &&
+      status !== 429;
+    return isPermanent
+      ? new NonRetryableFlushError(message)
+      : new Error(message);
+  }
+
+  /**
+   * Parse a 2xx response body, tolerating malformed JSON. The server
+   * already accepted the data — throwing here would make the queue retry
+   * an already-persisted batch and create duplicates.
+   */
+  private async safeJson<T>(response: Response, fallback: T): Promise<T> {
+    try {
+      return (await response.json()) as T;
+    } catch {
+      this.logger.warn('Response body was not valid JSON; treating as success');
+      return fallback;
+    }
+  }
+
+  async startSession(
+    deviceId: string,
+    deviceInfo?: DeviceInfo,
+  ): Promise<{ id: string }> {
+    try {
+      const response = await this.fetchWithTimeout(`${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 this.fetchWithTimeout(
+        `${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);
+    }
+  }
+
+  /**
+   * Attach the host app's user identity to a session.
+   * Fire-and-forget: errors are logged but never thrown.
+   */
+  async identifySession(
+    sessionId: string,
+    userId: string,
+    traits?: Record<string, unknown>,
+  ): Promise<void> {
+    try {
+      const response = await this.fetchWithTimeout(
+        `${this.baseUrl}/api/sessions/${sessionId}/identify`,
+        {
+          method: 'PATCH',
+          headers: this.getHeaders(),
+          body: JSON.stringify({ userId, traits }),
+        },
+      );
+
+      if (!response.ok) {
+        const text = await response.text();
+        this.logger.warn('Identify failed:', response.status, text?.substring(0, 200));
+        return;
+      }
+
+      this.logger.log('Session identified as user:', userId);
+    } catch (error) {
+      this.logger.warn('Error identifying session:', error);
+    }
+  }
+
+  async sendEventsBatch(
+    sessionId: string,
+    events: AnalyticsEvent[],
+  ): Promise<{ count: number }> {
+    try {
+      const response = await this.fetchWithTimeout(
+        `${this.baseUrl}/api/events/batch`,
+        {
+          method: 'POST',
+          headers: this.getHeaders(),
+          body: JSON.stringify({ sessionId, events }),
+        },
+      );
+
+      if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        this.logger.error(
+          'Failed to send events batch:',
+          response.status,
+          text,
+        );
+        throw this.batchError('Failed to send events batch', response.status);
+      }
+
+      const data = await this.safeJson(response, { count: events.length });
+      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 this.fetchWithTimeout(
+        `${this.baseUrl}/api/screens/visit/batch`,
+        {
+          method: 'POST',
+          headers: this.getHeaders(),
+          body: JSON.stringify({ visits }),
+        },
+      );
+
+      if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        this.logger.error(
+          'Failed to send screen visits batch:',
+          response.status,
+          text,
+        );
+        throw this.batchError(
+          '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 this.fetchWithTimeout(
+        `${this.baseUrl}/api/snapshots/batch`,
+        {
+          method: 'POST',
+          headers: this.getHeaders(),
+          body: JSON.stringify({ snapshots }),
+        },
+      );
+
+      if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        this.logger.error(
+          'Failed to send snapshots batch:',
+          response.status,
+          text,
+        );
+        throw this.batchError(
+          'Failed to send snapshots batch',
+          response.status,
+        );
+      }
+
+      const data = await this.safeJson(response, { count: snapshots.length });
+      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;
+    }
+  }
+
+  /**
+   * Send a single crash report. Never throws; returns true when the
+   * server accepted it (used to clear the persisted pending copy).
+   */
+  async sendCrashReport(crash: CrashReport): Promise<boolean> {
+    try {
+      const response = await this.fetchWithTimeout(`${this.baseUrl}/api/crashes`, {
+        method: 'POST',
+        headers: this.getHeaders(),
+        body: JSON.stringify(crash),
+      });
+
+      if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        this.logger.error(
+          'Failed to send crash report:',
+          response.status,
+          text,
+        );
+        return false;
+      }
+
+      this.logger.log('Crash report sent:', crash.type, crash.message);
+      return true;
+    } catch (error) {
+      // Fire-and-forget: catch errors silently, never throw
+      this.logger.error('Error sending crash report:', error);
+      return false;
+    }
+  }
+
+  async sendCrashesBatch(
+    crashes: CrashReport[],
+  ): Promise<{ count: number }> {
+    try {
+      const response = await this.fetchWithTimeout(`${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;
+    }
+  }
+
+  /**
+   * Upload a full-content screen capture for heatmap backgrounds.
+   * Fire-and-forget: errors are logged but never thrown.
+   */
+  /**
+   * Upload a scroll tile for collaborative screen building.
+   *
+   * @param viewportTop Y position (window logical px) of the ScrollView's
+   *   top edge. Used by the backend to crop each tile to just the
+   *   scrollable area, removing fixed headers/footers that would
+   *   otherwise duplicate in the composite.
+   * @param windowHeight Window height (logical px) at capture time.
+   *   Used by the backend to compute image-to-logical scale for cropping.
+   */
+  async uploadScreenTile(
+    sessionId: string,
+    screenName: string,
+    image: string,
+    width: number,
+    height: number,
+    scrollOffsetY: number,
+    viewportHeight: number,
+    contentHeight: number,
+    viewportTop?: number,
+    windowHeight?: number,
+  ): Promise<void> {
+    try {
+      const body: Record<string, unknown> = {
+        sessionId,
+        screenName,
+        image,
+        width,
+        height,
+        scrollOffsetY: Math.round(scrollOffsetY),
+        viewportHeight: Math.round(viewportHeight),
+        contentHeight: Math.round(contentHeight),
+      };
+      if (typeof viewportTop === 'number' && Number.isFinite(viewportTop)) {
+        body.viewportTop = Math.round(viewportTop);
+      }
+      if (typeof windowHeight === 'number' && Number.isFinite(windowHeight)) {
+        body.windowHeight = Math.round(windowHeight);
+      }
+
+      const response = await this.fetchWithTimeout(
+        `${this.baseUrl}/api/screen-tiles`,
+        {
+          method: 'POST',
+          headers: this.getHeaders(),
+          body: JSON.stringify(body),
+        },
+      );
+
+      if (!response.ok) {
+        const text = await response.text();
+        this.logger.warn(
+          'Screen tile upload failed:',
+          response.status,
+          text?.substring(0, 200),
+        );
+      }
+    } catch (error) {
+      this.logger.warn('Error uploading screen tile:', error);
+    }
+  }
+
+  async uploadScreenCapture(
+    screenName: string,
+    image: string,
+    width: number,
+    height: number,
+    isFullContent: boolean,
+  ): Promise<void> {
+    try {
+      const response = await this.fetchWithTimeout(
+        `${this.baseUrl}/api/screen-captures`,
+        {
+          method: 'POST',
+          headers: this.getHeaders(),
+          body: JSON.stringify({
+            screenName,
+            image,
+            width,
+            height,
+            isFullContent,
+          }),
+        },
+      );
+
+      if (!response.ok) {
+        const text = await response.text();
+        this.logger.warn(
+          'Screen capture upload failed:',
+          response.status,
+          text?.substring(0, 200),
+        );
+      }
+    } catch (error) {
+      this.logger.warn('Error uploading screen capture:', error);
+    }
+  }
+}