@scalebun/react-native 1.10.4 → 1.10.6

package/src/features/session/BackendSessionAdapter.ts

@@ -157,6 +157,13 @@ export class BackendSessionAdapter implements SessionTransport {
     // the flush timer retries, so nothing is lost to a start/child race. The durable native
     // outbox path has its own ordering; this guards only the JS in-memory fallback.
     private readonly _startedSessionIds = new Set<string>();
+    // §11 offline-start recovery: INGESTION_START payloads whose POST failed (e.g. the app
+    // launched with no connectivity). Without this, a failed START was logged and forgotten —
+    // the row-ready gate never opened, every child lane re-buffered forever, and the session
+    // stayed stuck until an app restart even after the network returned. Each flush tick
+    // re-attempts these until acked (network errors keep retrying; permanent 4xx gives up).
+    private readonly _pendingStartPayloads = new Map<string, Record<string, unknown>>();
+    private _startRetryInFlight = false;
     private pendingFrames: Array<{ frame: ReplayFrame; imageData: string }> = [];
     private pendingEvents: JourneyEvent[] = [];
     private pendingNetworkRequests: Array<Record<string, unknown>> = [];
@@ -299,12 +306,23 @@ export class BackendSessionAdapter implements SessionTransport {
                     },
                 };
                 __DEV__ && logger.debug(`[BackendSessionAdapter] POST session start: ${session.sessionId}`);
-                return this._post(startEndpoint, payload);
-            })
-            .then(() => {
-                // §11: row now exists — release the child-lane flush gate for this id.
-                this._startedSessionIds.add(session.sessionId);
-                __DEV__ && logger.info(`[ScaleBun Replay] backend session upload success`);
+                return this._post(startEndpoint, payload).then(
+                    () => {
+                        // §11: row now exists — release the child-lane flush gate for this id.
+                        this._startedSessionIds.add(session.sessionId);
+                        this._pendingStartPayloads.delete(session.sessionId);
+                        __DEV__ && logger.info(`[ScaleBun Replay] backend session upload success`);
+                    },
+                    (err) => {
+                        // Offline-start recovery: keep the payload; the flush timer re-attempts it
+                        // until the row is acked. A permanent 4xx (rejected key) is not retried —
+                        // the same payload can never succeed.
+                        if (!BackendSessionAdapter._isPermanentHttpError(err)) {
+                            this._pendingStartPayloads.set(session.sessionId, payload);
+                        }
+                        logger.info(`[ScaleBun Replay] backend session upload failure`);
+                    },
+                );
             })
             .catch(() => logger.info(`[ScaleBun Replay] backend session upload failure`));
     }
@@ -423,10 +441,22 @@ export class BackendSessionAdapter implements SessionTransport {
                     environment: m?.buildType,
                 },
             };
-            await this._post(startEndpoint, payload);
+            try {
+                await this._post(startEndpoint, payload);
+            } catch (err) {
+                // Offline-start recovery: keep the payload for the flush-tick retry loop.
+                // Without this a session that started with no connectivity NEVER opened its
+                // row-ready gate — frames/events re-buffered for the life of the process and
+                // only an app restart recovered it, even after the network came back.
+                if (!BackendSessionAdapter._isPermanentHttpError(err)) {
+                    this._pendingStartPayloads.set(session.sessionId, payload);
+                }
+                throw err;
+            }
             // §11: row exists. When recording adopts this analytics id (one-row merge),
             // this also releases the recording child-lane gate (_sessionRowReady).
             this._startedSessionIds.add(session.sessionId);
+            this._pendingStartPayloads.delete(session.sessionId);
             // Row is confirmed — replay any events buffered while START was in flight.
             // The pre-ack flush at the top of this method is gated off until now, so
             // this is what actually drains the pre-ready buffer (no premature 404).
@@ -437,6 +467,47 @@ export class BackendSessionAdapter implements SessionTransport {
         }
     }
 
+    /**
+     * Re-attempt any INGESTION_START whose POST failed (offline app launch). Runs on every
+     * flush tick of BOTH lanes — cheap no-op when the map is empty, single-flight guarded.
+     * On ack: opens the row-ready gate and drains whichever lane the id belongs to, which is
+     * exactly what un-sticks a replay that started offline once connectivity returns.
+     */
+    private _retryPendingStarts(): void {
+        if (this.destroyed || this._startRetryInFlight || this._pendingStartPayloads.size === 0) return;
+        const entry = this._pendingStartPayloads.entries().next().value as
+            | [string, Record<string, unknown>]
+            | undefined;
+        if (!entry) return;
+        const [sessionId, payload] = entry;
+        // A stale pending start for a session that already ended AND is not the open analytics
+        // session would create a row nothing will ever finalize — drop it instead.
+        const stillRelevant = sessionId === this.currentSessionId || sessionId === this._analyticsSessionId;
+        if (!stillRelevant) {
+            this._pendingStartPayloads.delete(sessionId);
+            return;
+        }
+        this._startRetryInFlight = true;
+        const startEndpoint = this.config.clientKey ? ENDPOINTS.INGESTION_START : '/replay/sessions';
+        this._post(startEndpoint, payload)
+            .then(() => {
+                this._startedSessionIds.add(sessionId);
+                this._pendingStartPayloads.delete(sessionId);
+                __DEV__ && logger.info(`[ScaleBun Replay] deferred session start delivered: ${sessionId}`);
+                if (sessionId === this._analyticsSessionId) {
+                    this._flushAnalyticsEvents().catch(() => { });
+                }
+            })
+            .catch((err) => {
+                if (BackendSessionAdapter._isPermanentHttpError(err)) {
+                    this._pendingStartPayloads.delete(sessionId); // will never succeed — stop retrying
+                }
+            })
+            .finally(() => {
+                this._startRetryInFlight = false;
+            });
+    }
+
     /**
      * Enqueue a user track() event. Buffers (bounded, drop-oldest) when the
      * analytics session is not yet open; flushes at >=20 once it is.
@@ -590,6 +661,7 @@ export class BackendSessionAdapter implements SessionTransport {
     private _startAnalyticsFlushTimer(): void {
         this._stopAnalyticsFlushTimer();
         this.analyticsFlushTimer = setInterval(() => {
+            this._retryPendingStarts();
             this._flushAnalyticsEvents().catch(() => { });
         }, this.config.flushIntervalMs);
     }
@@ -864,6 +936,7 @@ export class BackendSessionAdapter implements SessionTransport {
         this._analyticsSessionId = null;
         this._pendingFinalizeId = null;
         this._startedSessionIds.clear();
+        this._pendingStartPayloads.clear();
     }
 
     // ─── Internal: Flush ────────────────────────────────────────────────
@@ -1466,6 +1539,7 @@ export class BackendSessionAdapter implements SessionTransport {
     private _startFlushTimer(): void {
         this._stopFlushTimer();
         this.flushTimer = setInterval(() => {
+            this._retryPendingStarts();
             this._flushFrames().catch(() => { });
             this._flushEvents().catch(() => { });
             this._flushNetwork().catch(() => { });

package/src/features/session/SessionManager.ts

@@ -121,6 +121,22 @@ export class SessionManager {
      */
     private _lastNativeViewportJsUnits: { width: number; height: number; space: string } | null = null;
 
+    /**
+     * Exact-duplicate gesture suppression (QA: one physical tap recorded 2–3×).
+     *
+     * Measured in production data: the native tracker re-emitted the SAME tap — identical
+     * gestureType and identical coordinates to the SUB-PIXEL (e.g. x=466.962890625) — at
+     * 160–240ms gaps, sometimes twice. A human re-tap cannot reproduce a sub-pixel float
+     * exactly, so exact coordinate equality within the window is a safe discriminator: real
+     * double-taps land on at least slightly different pixels and pass through untouched.
+     * The pipeline's own 100ms dedup was too narrow for these; this window covers what was
+     * actually observed with margin. Sits at the ONE entry point every gesture source funnels
+     * through, so recording and analytics lanes are protected equally.
+     */
+    private _lastGestureSig: string | null = null;
+    private _lastGestureTs = 0;
+    private static readonly GESTURE_DEDUP_WINDOW_MS = 400;
+
     private _nativeCapture: NativeCaptureFn;
     private _rawTransport: DebugTransport | null;
     /** Memoized native file-outbox frame adapter (gated by the backend transport). */
@@ -1088,6 +1104,21 @@ export class SessionManager {
         screenHeight?: number;
         platform?: string;
     }): void {
+        // Exact-duplicate suppression — see _lastGestureSig. Signature is the gesture type plus
+        // raw coordinates verbatim; String() keeps undefined coords distinct from 0 (a payload
+        // with no coords never collides with a real origin tap).
+        const dedupSig = `${gestureType}|${String(details?.x)}|${String(details?.y)}|${String(details?.endX)}|${String(details?.endY)}`;
+        const nowTs = Date.now();
+        if (
+            dedupSig === this._lastGestureSig &&
+            nowTs - this._lastGestureTs <= SessionManager.GESTURE_DEDUP_WINDOW_MS
+        ) {
+            this._lastGestureTs = nowTs; // a burst of 3 stays suppressed even if gaps chain past the window
+            return;
+        }
+        this._lastGestureSig = dedupSig;
+        this._lastGestureTs = nowTs;
+
         // Build the canonical gesture payload ONCE so the recording lane and the
         // (additive) analytics lane carry byte-identical keys (normalizedX/Y,
         // gestureType, etc.). Same object shape that was previously inlined.

package/src/public/ScaleBunFacade.ts

@@ -20,7 +20,7 @@ import { PersistentQueue } from '../pipeline/queue/persistentQueue';
 import { MemoryBackend, createStorageBackend } from '../storage/StorageBackend';
 import { HttpClient } from '../transport/http/httpClient';
 import { getDeviceId } from '../core/id/deviceId';
-import { mergeDeviceContext, resolveEventPlatform } from '../core/context/device';
+import { mergeDeviceContext, nativeDeviceContext, resolveEventPlatform } from '../core/context/device';
 import { coreContainer } from '../core/di/container';
 import { flushQueue } from '../pipeline/queue/flushQueue';
 import {
@@ -48,6 +48,7 @@ import type {
 } from '../features/replay/public/types';
 import { SDKBootstrapper } from '../bootstrap/SDKBootstrapper';
 import { EventTracker } from '../analytics/EventTracker';
+import { bridgeAdapter } from '../features/replay/bridge/adapters/bridgeAdapter';
 import {
     emitAutomaticEvent,
     type AutomaticEventName,
@@ -368,6 +369,8 @@ class ScaleBunFacade {
                  * the whole time. The SDK knows the device; the integrator is guessing at it.
                  * Everything outside the detected keys is still theirs.
                  */
+                // Everything Platform.constants knows. On iOS that is neither the model nor the
+                // manufacturer, so the bridge completes it below once it answers.
                 context: mergeDeviceContext(rawConfig?.context),
                 // Use the same foreground id as replay/journey capture. The
                 // callback is resolved per event because the session subsystem
@@ -384,6 +387,19 @@ class ScaleBunFacade {
             this._eventTracker.start();
             __DEV__ && logger.info('[ScaleBun] Envelope event tracking started → /v1/batch.');
 
+            // Complete the device context from the native bridge.
+            //
+            // `Platform.constants` answers Android synchronously — model and manufacturer ride the
+            // first event. It answers NEITHER on iOS, so without this every iOS installation
+            // reported no device model at all: `nativeDeviceContext` existed for exactly this and
+            // had no caller, and the bridge's own answer was `UIDevice.current.model` — the string
+            // "iPhone", identical on every iPhone ever made.
+            //
+            // Fire-and-forget on purpose. The bridge is async and absent entirely on Expo Go or an
+            // older native binary; waiting on it would delay the first event, and failing on it
+            // would take analytics down over a nice-to-have field.
+            this._applyNativeDeviceContext(this._eventTracker);
+
             // Android: capture the Play Install Referrer once per install → feeds the
             // deterministic click_id path + a one-off install_referrer event (UTM/gclid).
             // Fire-and-forget; no-op off Android.
@@ -405,6 +421,30 @@ class ScaleBunFacade {
         }
     }
 
+
+    /**
+     * Fold the native bridge's device facts into the analytics context once it answers.
+     *
+     * Detected values never overwrite a populated one with an empty one — `nativeDeviceContext`
+     * drops absent keys and `applyDetectedContext` ignores an empty patch — so a bridge that
+     * cannot answer leaves whatever `Platform.constants` already found.
+     */
+    private _applyNativeDeviceContext(tracker: EventTracker): void {
+        Promise.resolve()
+            .then(() => bridgeAdapter.getDeviceInfo())
+            .then(info => {
+                if (!info) return;
+                tracker.applyDetectedContext(
+                    nativeDeviceContext({
+                        osVersion: info.osVersion,
+                        deviceModel: info.deviceModel,
+                        // iOS ships no manufacturer over the bridge; it is a constant there and the
+                        // static path already set it. Android's arrives via Platform.constants.
+                    }),
+                );
+            })
+            .catch(() => { /* bridge unavailable — the static context stands */ });
+    }
     /**
      * Android-only: read the Play Install Referrer once per install and route it into
      * attribution. `scalebun_click_id` → the deterministic click path; the full
@@ -584,17 +624,96 @@ class ScaleBunFacade {
         });
     }
 
-    /** Clear user identity */
-    public clearUser() {
+    /**
+     * Clear user identity.
+     *
+     * SB-11: pass `{ purgeLocal: true }` on logout / consent withdrawal to also
+     * erase all locally-stored SDK data (see {@link eraseLocalData}). Without it,
+     * behaviour is unchanged (identity-only clear).
+     */
+    public clearUser(options?: { purgeLocal?: boolean }) {
         return noThrow(() => {
             this._identifiedUserId = null;
             this._pendingIdentity = null;
             if (!this.initialized) return;
             this._eventTracker?.clearIdentity();
             this.track('$clear_user', {});
+            if (options?.purgeLocal) void this.eraseLocalData();
+        });
+    }
+
+    /**
+     * SB-11: erase all locally-stored SDK data from the device — the durable event
+     * queue, the pre-init buffer, and the first-party KV store (cached install /
+     * anonymous / session IDs, plus any queued payloads including SB-26 disk data).
+     *
+     * Order matters: capture is stopped FIRST so nothing is written back in behind
+     * the delete. Best-effort and never throws.
+     *
+     * Note: native replay frames written to disk on iOS are addressed separately
+     * (SB-15); this covers every store reachable from JS today.
+     */
+    public async eraseLocalData(): Promise<void> {
+        try {
+            // 1) Stop capture so no new frames/events are produced mid-erase.
+            try {
+                SessionManager.getExistingInstance()?.endSession('ended');
+            } catch { /* best-effort */ }
+            // 2) Clear the durable queue and the pre-init buffer.
+            try {
+                this._getQueue().clear();
+            } catch { /* best-effort */ }
+            try {
+                this._preInitBuffer.clear();
+            } catch { /* best-effort */ }
+            // 3) Wipe the first-party KV store (cached IDs + any on-disk queue
+            //    residue) by removing every key through the backend interface.
+            try {
+                const store = createStorageBackend();
+                for (const key of store.getAllKeys()) {
+                    store.delete(key);
+                }
+            } catch { /* best-effort */ }
+        } catch {
+            // Never throw — erasure is a safety operation on a best-effort basis.
+        }
+    }
+
+    /**
+     * SB-11: record the user's data-collection consent. When `enabled` is false,
+     * capture is stopped immediately; pass `{ purgeLocal: true }` to also erase
+     * everything already stored locally. Never throws.
+     */
+    public setConsent(enabled: boolean, options?: { purgeLocal?: boolean }): void {
+        noThrow(() => {
+            if (enabled) return;
+            try {
+                SessionManager.getExistingInstance()?.endSession('ended');
+            } catch { /* best-effort */ }
+            if (options?.purgeLocal) void this.eraseLocalData();
         });
     }
 
+    /**
+     * SB-10: return the effective privacy policy actually in force, resolving the
+     * public config against the SDK's safe defaults. Lets callers and tests assert
+     * what is active rather than guessing from the (previously dead) config object.
+     */
+    public getEffectivePrivacyPolicy(): Required<
+        Pick<PrivacyConfig, 'maskTextInputs' | 'maskImages' | 'redactAuth' | 'redactCookies' | 'redactBodies'>
+    > {
+        const p = this._privacyConfig ?? {};
+        return {
+            // Real default is true (matches the replay capture default) — the old
+            // doc comment claiming "false" was both wrong and less safe.
+            maskTextInputs: p.maskTextInputs ?? true,
+            maskImages: p.maskImages ?? false,
+            redactAuth: p.redactAuth ?? true,
+            redactCookies: p.redactCookies ?? true,
+            redactBodies: p.redactBodies ?? false,
+        };
+    }
+
     /**
      * Submit in-app rating (1-5 stars).
      * Attaches to current session when available; otherwise sends standalone.

package/src/public/types.ts

@@ -187,7 +187,7 @@ export interface PrivacyConfig {
     redactCookies?: boolean;
     /** Redact request/response bodies in network capture. Default: false */
     redactBodies?: boolean;
-    /** Mask text input values in session replay. Default: false */
+    /** Mask text input values in session replay. Default: true */
     maskTextInputs?: boolean;
     /** Mask image content in session replay. Default: false */
     maskImages?: boolean;