@repliqo/sdk-react-native 0.3.8 → 0.4.0

package/src/transport/batch-queue.ts

@@ -1,95 +1,212 @@
-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;
-  }
-}
+/**
+ * Thrown by an onFlush callback to signal that the batch was PERMANENTLY
+ * rejected (e.g. HTTP 400/413 — malformed or oversized payload). The queue
+ * drops the batch instead of retrying it forever, which would otherwise
+ * block the queue and evict everything behind it.
+ */
+export class NonRetryableFlushError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NonRetryableFlushError';
+  }
+}
+
+/**
+ * Thrown by an onFlush callback that delivers items in MULTIPLE requests
+ * (e.g. one events batch per session) when only a PREFIX of the items was
+ * consumed. Without it the queue would treat the flush as all-or-nothing:
+ * a transient failure after a successful sub-batch would RE-SEND the
+ * delivered items on retry (duplicates), and a poison sub-batch would
+ * DROP items belonging to never-attempted sub-batches.
+ *
+ * `consumedCount` = items delivered or permanently dropped, counted from
+ * the FRONT of the flushed array (sub-batches must be processed in order).
+ * `transient` = whether the stop reason was retryable (applies backoff and
+ * keeps the remaining items for retry).
+ */
+export class PartialFlushError extends Error {
+  constructor(
+    public readonly consumedCount: number,
+    public readonly transient: boolean,
+    message?: string,
+  ) {
+    super(message ?? `Partial flush: ${consumedCount} consumed`);
+    this.name = 'PartialFlushError';
+  }
+}
+
+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;
+  /**
+   * In-flight flush promise. flush() returns THIS promise when a flush is
+   * already running (instead of resolving immediately), so callers like
+   * endSession() that `await flush()` actually wait for delivery.
+   */
+  private inFlight: Promise<void> | null = null;
+  /**
+   * Items evicted from the FRONT of the buffer while a flush was in flight.
+   * Evicted items are the oldest — i.e. part of the in-flight batch — so
+   * after a successful flush we must remove (sent - alreadyEvicted) items,
+   * or we'd delete unsent NEW items that shifted to the front.
+   */
+  private evictedDuringFlush = 0;
+  /** Number of items captured by the in-flight flush (0 when idle). */
+  private inFlightCount = 0;
+  // 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) {
+      const evictCount = this.buffer.length - this.maxBufferSize + 1;
+      this.buffer.splice(0, evictCount);
+      if (this.inFlight) {
+        this.evictedDuringFlush += evictCount;
+      }
+    }
+
+    this.buffer.push(item);
+    if (this.buffer.length >= this.maxSize) {
+      this.flush();
+    }
+  }
+
+  /**
+   * Flush the buffer. If a flush is already in flight, returns its promise
+   * (never a silent no-op). Never rejects — failures are kept in the buffer
+   * and retried with backoff by the auto-flush timer.
+   */
+  flush(): Promise<void> {
+    if (this.inFlight) {
+      return this.inFlight;
+    }
+    if (this.buffer.length === 0) {
+      return Promise.resolve();
+    }
+
+    this.inFlight = this.doFlush().finally(() => {
+      this.inFlight = null;
+    });
+    return this.inFlight;
+  }
+
+  private async doFlush(): Promise<void> {
+    this.evictedDuringFlush = 0;
+    const items = [...this.buffer];
+    this.inFlightCount = items.length;
+
+    /** Remove `count` in-flight items from the buffer front, net of any
+     *  that were already evicted (or cleared) while the flush ran. */
+    const removeConsumed = (count: number) => {
+      const toRemove = Math.max(
+        0,
+        Math.min(count, items.length) - this.evictedDuringFlush,
+      );
+      this.buffer.splice(0, toRemove);
+      // Consumed items absorb the eviction credit first.
+      this.evictedDuringFlush = Math.max(
+        0,
+        this.evictedDuringFlush - Math.min(count, items.length),
+      );
+    };
+
+    try {
+      await this.onFlush(items);
+      removeConsumed(items.length);
+      this.consecutiveFailures = 0;
+      this.ticksToSkip = 0;
+    } catch (err) {
+      if (err instanceof PartialFlushError) {
+        // A prefix of the items was delivered/dropped by a multi-request
+        // flush; keep only the unconsumed remainder.
+        removeConsumed(err.consumedCount);
+        if (err.transient) {
+          this.applyBackoff();
+        } else {
+          this.consecutiveFailures = 0;
+          this.ticksToSkip = 0;
+        }
+      } else if (err instanceof NonRetryableFlushError) {
+        // Poison batch: the server permanently rejected it. Drop it so it
+        // can't block the queue forever.
+        removeConsumed(items.length);
+        this.consecutiveFailures = 0;
+        this.ticksToSkip = 0;
+      } else {
+        // Transient failure: keep events in buffer for retry with
+        // exponential backoff (1, 2, 4, 8 ticks skipped).
+        this.applyBackoff();
+      }
+    } finally {
+      this.inFlightCount = 0;
+    }
+  }
+
+  private applyBackoff(): void {
+    this.consecutiveFailures++;
+    this.ticksToSkip = Math.min(
+      Math.pow(2, this.consecutiveFailures - 1),
+      BatchQueue.MAX_BACKOFF_TICKS,
+    );
+  }
+
+  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;
+  }
+
+  /** Read-only snapshot of the buffered items (for persistence). */
+  peekAll(): readonly T[] {
+    return [...this.buffer];
+  }
+
+  /** Remove every buffered item (after persisting, or on session discard). */
+  clear(): void {
+    this.buffer.length = 0;
+    // If a flush is in flight, all of its items just left the buffer —
+    // account for them as evicted so the flush's completion splice does
+    // not delete NEW items added after this clear().
+    this.evictedDuringFlush = this.inFlightCount;
+  }
+}

package/src/types/events.ts

@@ -1,60 +1,72 @@
-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;
-  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;
-  /** Enable full-content screen captures for heatmap backgrounds. Defaults to true when enableSnapshots is true. */
-  enableHeatmapCapture?: boolean;
-  enableCrashTracking?: boolean;
-  debug?: boolean;
-}
+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;
+  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;
+  /** Enable full-content screen captures for heatmap backgrounds. Defaults to true when enableSnapshots is true. */
+  enableHeatmapCapture?: boolean;
+  enableCrashTracking?: boolean;
+  /**
+   * Async key-value storage for offline persistence (events buffered at
+   * backgrounding + crash reports). Pass AsyncStorage from
+   * @react-native-async-storage/async-storage, or any compatible object.
+   * If omitted, the SDK tries to auto-load AsyncStorage; if unavailable,
+   * persistence is disabled (in-memory only).
+   */
+  storage?: {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+  };
+  debug?: boolean;
+}