@repliqo/sdk-react-native 0.3.8 → 0.4.0

package/dist/transport/batch-queue.js

@@ -1,11 +1,60 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BatchQueue = void 0;
+exports.BatchQueue = exports.PartialFlushError = exports.NonRetryableFlushError = void 0;
+/**
+ * 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.
+ */
+class NonRetryableFlushError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NonRetryableFlushError';
+    }
+}
+exports.NonRetryableFlushError = 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).
+ */
+class PartialFlushError extends Error {
+    constructor(consumedCount, transient, message) {
+        super(message ?? `Partial flush: ${consumedCount} consumed`);
+        this.consumedCount = consumedCount;
+        this.transient = transient;
+        this.name = 'PartialFlushError';
+    }
+}
+exports.PartialFlushError = PartialFlushError;
 class BatchQueue {
     constructor(maxSize = 20, flushIntervalMs = 30000, onFlush, maxBufferSize = 1000) {
         this.buffer = [];
         this.intervalId = null;
-        this.flushing = false;
+        /**
+         * 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.
+         */
+        this.inFlight = 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.
+         */
+        this.evictedDuringFlush = 0;
+        /** Number of items captured by the in-flight flush (0 when idle). */
+        this.inFlightCount = 0;
         // Exponential backoff state: on each failure we double the skip count,
         // capped at 8 ticks. A successful flush resets it to 0.
         this.consecutiveFailures = 0;
@@ -18,40 +67,86 @@ class BatchQueue {
     add(item) {
         // 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);
+            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();
         }
     }
-    async flush() {
-        if (this.buffer.length === 0 || this.flushing) {
-            return;
+    /**
+     * 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() {
+        if (this.inFlight) {
+            return this.inFlight;
+        }
+        if (this.buffer.length === 0) {
+            return Promise.resolve();
         }
-        this.flushing = true;
+        this.inFlight = this.doFlush().finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    async doFlush() {
+        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) => {
+            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);
-            // 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.
+            removeConsumed(items.length);
             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);
+        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.flushing = false;
+            this.inFlightCount = 0;
         }
     }
+    applyBackoff() {
+        this.consecutiveFailures++;
+        this.ticksToSkip = Math.min(Math.pow(2, this.consecutiveFailures - 1), BatchQueue.MAX_BACKOFF_TICKS);
+    }
     startAutoFlush() {
         if (this.intervalId !== null) {
             return;
@@ -75,6 +170,18 @@ class BatchQueue {
     get pending() {
         return this.buffer.length;
     }
+    /** Read-only snapshot of the buffered items (for persistence). */
+    peekAll() {
+        return [...this.buffer];
+    }
+    /** Remove every buffered item (after persisting, or on session discard). */
+    clear() {
+        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;
+    }
 }
 exports.BatchQueue = BatchQueue;
 BatchQueue.MAX_BACKOFF_TICKS = 8;

package/dist/types/events.d.ts

@@ -50,5 +50,17 @@ export interface SDKConfig {
     /** 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;
 }

package/package.json

@@ -1,64 +1,68 @@
-{
-  "name": "@repliqo/sdk-react-native",
-  "version": "0.3.8",
-  "description": "Session replay & analytics SDK for React Native. Captures screenshots (including modals/alerts), navigation, screen visits, and custom events.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/SbtnAvls/app-analytics-api",
-    "directory": "packages/sdk-react-native"
-  },
-  "homepage": "https://repliqo.odmservice.site",
-  "license": "MIT",
-  "keywords": [
-    "react-native",
-    "analytics",
-    "session-replay",
-    "screen-capture",
-    "heatmaps",
-    "uxcam",
-    "repliqo"
-  ],
-  "files": [
-    "dist/",
-    "android/src/",
-    "android/build.gradle",
-    "src/",
-    "INTEGRATION_GUIDE.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "jest",
-    "prepublishOnly": "npm run build"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "peerDependencies": {
-    "@react-navigation/native": ">=6.0.0",
-    "react": ">=17.0.0",
-    "react-native": ">=0.68.0",
-    "react-native-view-shot": ">=3.0.0"
-  },
-  "peerDependenciesMeta": {
-    "react-native-view-shot": {
-      "optional": true
-    },
-    "@react-navigation/native": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@react-navigation/native": "^6.1.0",
-    "@types/jest": "^29.5.0",
-    "@types/react": "^18.2.0",
-    "@types/react-native": "^0.72.0",
-    "jest": "^29.7.0",
-    "react": "^18.2.0",
-    "react-native": "^0.73.0",
-    "react-native-view-shot": "^4.0.3",
-    "ts-jest": "^29.1.0",
-    "typescript": "^5.3.0"
-  }
-}
+{
+  "name": "@repliqo/sdk-react-native",
+  "version": "0.4.0",
+  "description": "Session replay & analytics SDK for React Native. Captures screenshots (including modals/alerts), navigation, screen visits, and custom events.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SbtnAvls/app-analytics-api",
+    "directory": "packages/sdk-react-native"
+  },
+  "homepage": "https://repliqo.odmservice.site",
+  "license": "MIT",
+  "keywords": [
+    "react-native",
+    "analytics",
+    "session-replay",
+    "screen-capture",
+    "heatmaps",
+    "uxcam",
+    "repliqo"
+  ],
+  "files": [
+    "dist/",
+    "android/src/",
+    "android/build.gradle",
+    "src/",
+    "INTEGRATION_GUIDE.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@react-navigation/native": ">=6.0.0",
+    "react": ">=17.0.0",
+    "react-native": ">=0.68.0",
+    "react-native-view-shot": ">=3.0.0",
+    "@react-native-async-storage/async-storage": ">=1.17.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native-view-shot": {
+      "optional": true
+    },
+    "@react-navigation/native": {
+      "optional": true
+    },
+    "@react-native-async-storage/async-storage": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@react-navigation/native": "^6.1.0",
+    "@types/jest": "^29.5.0",
+    "@types/react": "^18.2.0",
+    "@types/react-native": "^0.72.0",
+    "jest": "^29.7.0",
+    "react": "^18.2.0",
+    "react-native": "^0.73.0",
+    "react-native-view-shot": "^4.0.3",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/components/RepliqoFlatList.tsx

@@ -0,0 +1,64 @@
+import React from 'react';
+import { FlatList, type FlatListProps } from 'react-native';
+import { useRepliqoScrollTracking } from './useRepliqoScrollTracking';
+
+/**
+ * Drop-in replacement for React Native's FlatList with the same analytics
+ * behavior as RepliqoScrollView:
+ *
+ *  1. Reports scroll offset for accurate heatmap touch coords
+ *  2. Captures viewport tiles on scroll stops AND during continuous
+ *     scroll for collaborative screen building
+ *  3. Registers its window-relative bounds with the SDK so touches can
+ *     be auto-classified as "content" (inside the list) or "fixed" UI
+ *
+ * Note on tiles: FlatList virtualizes — off-screen rows aren't rendered —
+ * but that's exactly why the collaborative tile approach works here too:
+ * tiles are captured from what's ON screen as the user naturally scrolls.
+ *
+ * Note on contentHeight: with virtualization, RN estimates the content
+ * size until rows render; onContentSizeChange keeps our metadata in sync
+ * as the estimate refines.
+ */
+function RepliqoFlatListInner<ItemT>(
+  {
+    onScroll,
+    onMomentumScrollEnd,
+    onScrollEndDrag,
+    onLayout,
+    onContentSizeChange,
+    ...props
+  }: FlatListProps<ItemT>,
+  ref: React.Ref<FlatList<ItemT>>,
+) {
+  const tracking = useRepliqoScrollTracking(ref, {
+    onScroll,
+    onMomentumScrollEnd,
+    onScrollEndDrag,
+    onLayout,
+    onContentSizeChange,
+  });
+
+  return (
+    <FlatList<ItemT>
+      ref={tracking.setRef as React.Ref<FlatList<ItemT>>}
+      {...props}
+      onScroll={tracking.onScroll}
+      onScrollEndDrag={tracking.onScrollEndDrag}
+      onMomentumScrollEnd={tracking.onMomentumScrollEnd}
+      onLayout={tracking.onLayout}
+      onContentSizeChange={tracking.onContentSizeChange}
+      scrollEventThrottle={props.scrollEventThrottle ?? 16}
+    />
+  );
+}
+
+export const RepliqoFlatList = React.forwardRef(RepliqoFlatListInner) as <
+  ItemT,
+>(
+  props: FlatListProps<ItemT> & {
+    ref?: React.Ref<FlatList<ItemT>>;
+  },
+) => React.ReactElement;
+
+(RepliqoFlatList as any).displayName = 'RepliqoFlatList';