@repliqo/sdk-react-native 0.3.8 → 0.4.0

package/dist/trackers/error.tracker.js

@@ -6,7 +6,32 @@ class ErrorTracker {
         this.sessionId = null;
         this.currentScreen = null;
         this.originalHandler = null;
+        this.wrapperHandler = null;
         this.isActive = false;
+        /**
+         * Handle an unhandled promise rejection. Guarded on isActive because the
+         * underlying trackers can't always be unregistered.
+         */
+        this.handleUnhandledRejection = (_id, error) => {
+            if (!this.isActive)
+                return;
+            try {
+                const message = error instanceof Error ? error.message : String(error);
+                const stack = error instanceof Error ? error.stack : undefined;
+                const crash = {
+                    sessionId: this.sessionId || undefined,
+                    type: 'unhandled_rejection',
+                    message,
+                    stackTrace: stack || undefined,
+                    screenName: this.currentScreen || undefined,
+                    timestamp: new Date().toISOString(),
+                };
+                this.onCrash(crash);
+            }
+            catch (_e) {
+                // Never crash the app due to error reporting
+            }
+        };
         this.onCrash = onCrash;
     }
     setSessionId(id) {
@@ -25,8 +50,11 @@ class ErrorTracker {
     stop() {
         if (!this.isActive)
             return;
+        // Flip the flag FIRST — the rejection trackers can't always be
+        // unregistered (Hermes), so their callbacks guard on isActive.
         this.isActive = false;
         this.restoreGlobalErrorHandler();
+        this.teardownUnhandledRejectionHandler();
     }
     /**
      * Manual error reporting - allows consumers to report caught errors.
@@ -53,66 +81,115 @@ class ErrorTracker {
             const ErrorUtils = global.ErrorUtils;
             if (ErrorUtils) {
                 this.originalHandler = ErrorUtils.getGlobalHandler();
-                ErrorUtils.setGlobalHandler((error, isFatal) => {
-                    try {
-                        const crash = {
-                            sessionId: this.sessionId || undefined,
-                            type: isFatal ? 'native_crash' : 'js_error',
-                            message: error.message,
-                            stackTrace: error.stack || undefined,
-                            screenName: this.currentScreen || undefined,
-                            metadata: { isFatal },
-                            timestamp: new Date().toISOString(),
-                        };
-                        this.onCrash(crash);
-                    }
-                    catch (_e) {
-                        // Never crash the app due to error reporting
+                this.wrapperHandler = (error, isFatal) => {
+                    if (this.isActive) {
+                        try {
+                            const crash = {
+                                sessionId: this.sessionId || undefined,
+                                type: isFatal ? 'native_crash' : 'js_error',
+                                message: error.message,
+                                stackTrace: error.stack || undefined,
+                                screenName: this.currentScreen || undefined,
+                                metadata: { isFatal },
+                                timestamp: new Date().toISOString(),
+                            };
+                            this.onCrash(crash);
+                        }
+                        catch (_e) {
+                            // Never crash the app due to error reporting
+                        }
                     }
                     // Always call original handler so RN can handle the error
                     if (this.originalHandler) {
                         this.originalHandler(error, isFatal);
                     }
-                });
+                };
+                ErrorUtils.setGlobalHandler(this.wrapperHandler);
             }
         }
         catch (_e) {
             // Never crash the app due to error handler setup
         }
     }
+    /**
+     * Register with the mechanisms React Native ACTUALLY uses to surface
+     * unhandled promise rejections:
+     *
+     *  1. Hermes' native promise rejection tracker (Hermes engine).
+     *  2. The `promise` polyfill's rejection-tracking module (JSC and older
+     *     RN versions).
+     *
+     * A bare global callback (the old approach) is never invoked by RN — it
+     * silently captured nothing.
+     *
+     * KNOWN LIMITATION: these trackers hold a single handler — registering
+     * REPLACES whatever was installed before (RN's dev LogBox warning, or
+     * another SDK like Sentry if it initialized first), and there is no
+     * unregister API, so after stop() an inert handler remains installed.
+     * If you run multiple error-tracking SDKs, initialize Repliqo FIRST so
+     * the other SDK's handler wins, or disable enableCrashTracking.
+     */
     setupUnhandledRejectionHandler() {
+        // Kept for manual invocation / test hooks.
         try {
-            if (typeof global !== 'undefined') {
-                global.__analyticsUnhandledRejection = (_id, error) => {
-                    try {
-                        const message = error instanceof Error ? error.message : String(error);
-                        const stack = error instanceof Error ? error.stack : undefined;
-                        const crash = {
-                            sessionId: this.sessionId || undefined,
-                            type: 'unhandled_rejection',
-                            message,
-                            stackTrace: stack || undefined,
-                            screenName: this.currentScreen || undefined,
-                            timestamp: new Date().toISOString(),
-                        };
-                        this.onCrash(crash);
-                    }
-                    catch (_e) {
-                        // Never crash the app due to error reporting
-                    }
-                };
+            global.__analyticsUnhandledRejection =
+                this.handleUnhandledRejection;
+        }
+        catch (_e) {
+            /* ignore */
+        }
+        // Hermes: native promise rejection tracking.
+        try {
+            const hermes = global.HermesInternal;
+            if (hermes?.hasPromise?.() && hermes?.enablePromiseRejectionTracker) {
+                hermes.enablePromiseRejectionTracker({
+                    allRejections: true,
+                    onUnhandled: this.handleUnhandledRejection,
+                    onHandled: () => { },
+                });
+                return;
             }
         }
         catch (_e) {
-            // Never crash the app due to rejection handler setup
+            /* ignore — fall through to the polyfill */
+        }
+        // JSC / promise polyfill path.
+        try {
+            const rejectionTracking = require('promise/setimmediate/rejection-tracking');
+            rejectionTracking.enable({
+                allRejections: true,
+                onUnhandled: this.handleUnhandledRejection,
+                onHandled: () => { },
+            });
+        }
+        catch (_e) {
+            // Module unavailable (e.g. jest without the polyfill) — the global
+            // hook above still allows manual reporting.
+        }
+    }
+    teardownUnhandledRejectionHandler() {
+        try {
+            delete global.__analyticsUnhandledRejection;
+        }
+        catch (_e) {
+            /* ignore */
         }
+        // Hermes offers no unregister API and disabling the polyfill tracker
+        // could clobber another library's handler — the isActive guard in
+        // handleUnhandledRejection makes lingering registrations inert.
     }
     restoreGlobalErrorHandler() {
         try {
             const ErrorUtils = global.ErrorUtils;
             if (ErrorUtils && this.originalHandler) {
-                ErrorUtils.setGlobalHandler(this.originalHandler);
+                // Only restore if WE are still the installed handler — another
+                // library may have wrapped us after start(), and restoring would
+                // clobber its handler.
+                if (ErrorUtils.getGlobalHandler() === this.wrapperHandler) {
+                    ErrorUtils.setGlobalHandler(this.originalHandler);
+                }
                 this.originalHandler = null;
+                this.wrapperHandler = null;
             }
         }
         catch (_e) {

package/dist/trackers/navigation.tracker.js

@@ -57,6 +57,17 @@ function useNavigationTracker() {
                 // AppAnalytics not initialized, silently ignore
             }
         }
+        else if (currentRouteName && !previousRouteName) {
+            // First route seen without onReady having fired (some apps only wire
+            // onStateChange). Without this, currentScreen stays null until the
+            // SECOND navigation and early touches/visits go unattributed.
+            try {
+                client_1.AppAnalytics.getInstance().onScreenEnter(currentRouteName);
+            }
+            catch {
+                // AppAnalytics not initialized, silently ignore
+            }
+        }
         routeNameRef.current = currentRouteName;
     }, []);
     return {

package/dist/transport/api.client.d.ts

@@ -11,10 +11,39 @@ export declare class ApiClient {
     private logger;
     constructor(baseUrl: string, apiKey: string, logger: Logger);
     private getHeaders;
+    /**
+     * 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 fetchWithTimeout;
+    /**
+     * 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;
+    /**
+     * 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 safeJson;
     startSession(deviceId: string, deviceInfo?: DeviceInfo): Promise<{
         id: string;
     }>;
     endSession(sessionId: string): Promise<void>;
+    /**
+     * Attach the host app's user identity to a session.
+     * Fire-and-forget: errors are logged but never thrown.
+     */
+    identifySession(sessionId: string, userId: string, traits?: Record<string, unknown>): Promise<void>;
     sendEventsBatch(sessionId: string, events: AnalyticsEvent[]): Promise<{
         count: number;
     }>;
@@ -22,7 +51,11 @@ export declare class ApiClient {
     sendSnapshotsBatch(snapshots: SnapshotPayload[]): Promise<{
         count: number;
     }>;
-    sendCrashReport(crash: CrashReport): Promise<void>;
+    /**
+     * Send a single crash report. Never throws; returns true when the
+     * server accepted it (used to clear the persisted pending copy).
+     */
+    sendCrashReport(crash: CrashReport): Promise<boolean>;
     sendCrashesBatch(crashes: CrashReport[]): Promise<{
         count: number;
     }>;

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;
 }