@repliqo/sdk-react-native 0.3.7 → 0.4.0

package/dist/transport/api.client.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiClient = void 0;
+const batch_queue_1 = require("./batch-queue");
+/** Abort any request that hasn't completed within this window. */
+const FETCH_TIMEOUT_MS = 15000;
 class ApiClient {
     constructor(baseUrl, apiKey, logger) {
         this.baseUrl = baseUrl.replace(/\/+$/, '');
@@ -13,9 +16,61 @@ class ApiClient {
             '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).
+     */
+    async fetchWithTimeout(url, init) {
+        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.
+     */
+    batchError(context, status) {
+        const message = `${context}: ${status}`;
+        const isPermanent = status >= 400 &&
+            status < 500 &&
+            status !== 401 &&
+            status !== 403 &&
+            status !== 408 &&
+            status !== 429;
+        return isPermanent
+            ? new batch_queue_1.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.
+     */
+    async safeJson(response, fallback) {
+        try {
+            return (await response.json());
+        }
+        catch {
+            this.logger.warn('Response body was not valid JSON; treating as success');
+            return fallback;
+        }
+    }
     async startSession(deviceId, deviceInfo) {
         try {
-            const response = await fetch(`${this.baseUrl}/api/sessions/start`, {
+            const response = await this.fetchWithTimeout(`${this.baseUrl}/api/sessions/start`, {
                 method: 'POST',
                 headers: this.getHeaders(),
                 body: JSON.stringify({ deviceId, deviceInfo }),
@@ -36,7 +91,7 @@ class ApiClient {
     }
     async endSession(sessionId) {
         try {
-            const response = await fetch(`${this.baseUrl}/api/sessions/${sessionId}/end`, {
+            const response = await this.fetchWithTimeout(`${this.baseUrl}/api/sessions/${sessionId}/end`, {
                 method: 'PATCH',
                 headers: this.getHeaders(),
             });
@@ -51,19 +106,41 @@ class ApiClient {
             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, userId, traits) {
+        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, events) {
         try {
-            const response = await fetch(`${this.baseUrl}/api/events/batch`, {
+            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();
+                const text = await response.text().catch(() => '');
                 this.logger.error('Failed to send events batch:', response.status, text);
-                throw new Error(`Failed to send events batch: ${response.status}`);
+                throw this.batchError('Failed to send events batch', response.status);
             }
-            const data = await response.json();
+            const data = await this.safeJson(response, { count: events.length });
             this.logger.log('Events batch sent, count:', data.count);
             return { count: data.count };
         }
@@ -74,15 +151,15 @@ class ApiClient {
     }
     async sendScreenVisitsBatch(visits) {
         try {
-            const response = await fetch(`${this.baseUrl}/api/screens/visit/batch`, {
+            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();
+                const text = await response.text().catch(() => '');
                 this.logger.error('Failed to send screen visits batch:', response.status, text);
-                throw new Error(`Failed to send screen visits batch: ${response.status}`);
+                throw this.batchError('Failed to send screen visits batch', response.status);
             }
             this.logger.log('Screen visits batch sent, count:', visits.length);
         }
@@ -93,17 +170,17 @@ class ApiClient {
     }
     async sendSnapshotsBatch(snapshots) {
         try {
-            const response = await fetch(`${this.baseUrl}/api/snapshots/batch`, {
+            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();
+                const text = await response.text().catch(() => '');
                 this.logger.error('Failed to send snapshots batch:', response.status, text);
-                throw new Error(`Failed to send snapshots batch: ${response.status}`);
+                throw this.batchError('Failed to send snapshots batch', response.status);
             }
-            const data = await response.json();
+            const data = await this.safeJson(response, { count: snapshots.length });
             this.logger.log('Snapshots batch sent, count:', data.count);
             return { count: data.count };
         }
@@ -112,28 +189,34 @@ class ApiClient {
             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) {
         try {
-            const response = await fetch(`${this.baseUrl}/api/crashes`, {
+            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();
+                const text = await response.text().catch(() => '');
                 this.logger.error('Failed to send crash report:', response.status, text);
-                return;
+                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) {
         try {
-            const response = await fetch(`${this.baseUrl}/api/crashes/batch`, {
+            const response = await this.fetchWithTimeout(`${this.baseUrl}/api/crashes/batch`, {
                 method: 'POST',
                 headers: this.getHeaders(),
                 body: JSON.stringify({ crashes }),
@@ -184,7 +267,7 @@ class ApiClient {
             if (typeof windowHeight === 'number' && Number.isFinite(windowHeight)) {
                 body.windowHeight = Math.round(windowHeight);
             }
-            const response = await fetch(`${this.baseUrl}/api/screen-tiles`, {
+            const response = await this.fetchWithTimeout(`${this.baseUrl}/api/screen-tiles`, {
                 method: 'POST',
                 headers: this.getHeaders(),
                 body: JSON.stringify(body),
@@ -200,7 +283,7 @@ class ApiClient {
     }
     async uploadScreenCapture(screenName, image, width, height, isFullContent) {
         try {
-            const response = await fetch(`${this.baseUrl}/api/screen-captures`, {
+            const response = await this.fetchWithTimeout(`${this.baseUrl}/api/screen-captures`, {
                 method: 'POST',
                 headers: this.getHeaders(),
                 body: JSON.stringify({

package/dist/transport/batch-queue.d.ts

@@ -1,3 +1,30 @@
+/**
+ * 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 declare class NonRetryableFlushError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare class PartialFlushError extends Error {
+    readonly consumedCount: number;
+    readonly transient: boolean;
+    constructor(consumedCount: number, transient: boolean, message?: string);
+}
 export declare class BatchQueue<T> {
     private buffer;
     private maxSize;
@@ -5,14 +32,39 @@ export declare class BatchQueue<T> {
     private flushIntervalMs;
     private onFlush;
     private intervalId;
-    private flushing;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Number of items captured by the in-flight flush (0 when idle). */
+    private inFlightCount;
     private consecutiveFailures;
     private ticksToSkip;
     private static readonly MAX_BACKOFF_TICKS;
     constructor(maxSize: number | undefined, flushIntervalMs: number | undefined, onFlush: (items: T[]) => Promise<void>, maxBufferSize?: number);
     add(item: T): void;
+    /**
+     * 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>;
+    private doFlush;
+    private applyBackoff;
     startAutoFlush(): void;
     stopAutoFlush(): void;
     get pending(): number;
+    /** Read-only snapshot of the buffered items (for persistence). */
+    peekAll(): readonly T[];
+    /** Remove every buffered item (after persisting, or on session discard). */
+    clear(): void;
 }

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.7",
-  "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"
+  }
+}