@scalebun/react-native 1.0.3 → 1.1.0

package/src/features/session/BackendSessionAdapter.ts

@@ -258,6 +258,7 @@ export class BackendSessionAdapter implements SessionTransport {
         bridgeAdapter.getDeviceInfo()
             .then(nativeInfo => {
                 const m = session.metadata;
+                this._cachedAppVersion = nativeInfo?.appVersion ?? m?.appVersion ?? null;
                 const payload = {
                     sessionId: session.sessionId,
                     deviceId: session.deviceId,
@@ -394,6 +395,7 @@ export class BackendSessionAdapter implements SessionTransport {
         try {
             const nativeInfo = await bridgeAdapter.getDeviceInfo();
             const m = session.metadata;
+            this._cachedAppVersion = nativeInfo?.appVersion ?? m?.appVersion ?? null;
             const payload = {
                 sessionId: session.sessionId,
                 deviceId: session.deviceId,
@@ -639,18 +641,56 @@ export class BackendSessionAdapter implements SessionTransport {
         }
     }
 
+    // D8/D9/D12: this signature was {type, message, stack, screenName} — four
+    // fields — while the backend row and every dashboard surface were already
+    // built for the rest. The consequences of the four-field bottleneck:
+    // regression detection permanently false (no appVersion on any mobile
+    // error), Issue.primaryPlatform NULL for every RN crash (no platform), and
+    // native crash signal/thread/exception-type discarded one call before the
+    // wire (no metadata). The receiver needed nothing; only this signature did.
+    /** App version resolved at session start; errors stamp it so regression
+     *  detection has a version to work with (D8). Null until a session starts. */
+    private _cachedAppVersion: string | null = null;
+
+    private _appVersion(): string | undefined {
+        return this._cachedAppVersion ?? undefined;
+    }
+
     queueError(data: {
         type: string; message: string; stack?: string; screenName?: string;
+        platform?: string;
+        appVersion?: string;
+        isFatal?: boolean;
+        metadata?: Record<string, unknown>;
+        /** Target session. Set ONLY by a recovered native crash; absent means the current session. */
+        sessionId?: string;
+        /** Stable idempotency key. Set ONLY by a recovered crash; the backend dedupes on it. */
+        clientId?: string;
     }): void {
         if (this.destroyed || !this.config.clientKey) return;
-        this.pendingErrors.push({ ...data, clientId: this._clientId(), timestamp: new Date().toISOString() });
+        this.pendingErrors.push({
+            ...data,
+            // The session already knows the app version — never make a crash
+            // reporter's callers supply what the transport can fill itself.
+            appVersion: data.appVersion ?? this._appVersion(),
+            // A recovered crash brings its OWN clientId — the stable id written when the crash was
+            // first persisted. Generating a fresh one here would mint a new identity on every retry
+            // and defeat the unique constraint the backend dedupes with.
+            clientId: data.clientId ?? this._clientId(),
+            timestamp: new Date().toISOString(),
+        });
         if (this.pendingErrors.length >= 10) {
             this._flushErrors().catch(() => {});
         }
     }
 
-    /** Public: force-flush queued errors immediately (handled-error delivery). */
-    flushErrors(): Promise<void> {
+    /**
+     * Public: force-flush queued errors immediately (handled-error delivery).
+     *
+     * @returns whether the batch was DURABLY accepted. Crash recovery deletes its on-disk record on
+     *          this answer, so it must reflect the backend and not merely that the call returned.
+     */
+    flushErrors(): Promise<boolean> {
         return this._flushErrors();
     }
 
@@ -724,13 +764,23 @@ export class BackendSessionAdapter implements SessionTransport {
     private async _enqueueNative(
         lane: 'events' | 'network' | 'errors' | 'performance' | 'logs',
         records: Array<Record<string, unknown>>,
+        /**
+         * Session to enqueue UNDER. Defaults to the current one, which is right for every live lane.
+         *
+         * A recovered native crash must override it. Without this parameter the outbox stamped
+         * `currentSessionId` on everything, so with the outbox enabled a recovered crash was filed
+         * against the session created after the restart — the exact defect the routing above exists
+         * to prevent, reappearing through a path that routing never touched.
+         */
+        targetSessionId?: string,
     ): Promise<boolean> {
-        if (!this.nativeOutboxEnabled || !this.currentSessionId) return false;
+        const sessionId = targetSessionId || this.currentSessionId;
+        if (!this.nativeOutboxEnabled || !sessionId) return false;
         const native = getReplaySdkNative();
         if (!native?.enqueueOutboxRecords) return false;
         if (!(await this._ensureNativeOutbox(native))) return false;
         try {
-            return await native.enqueueOutboxRecords(lane, this.currentSessionId, records);
+            return await native.enqueueOutboxRecords(lane, sessionId, records);
         } catch {
             return false;
         }
@@ -852,6 +902,17 @@ export class BackendSessionAdapter implements SessionTransport {
         if (screen) out.screenName = screen;
         const label = e.subtype ?? e.type;
         if (label && label !== e.type) out.label = label;
+        /**
+         * THIS MAPPER ENUMERATES. Every field the wire carries has to be named here, so a field
+         * added to JourneyEvent and not added here is dropped silently — no error, no warning, and
+         * nothing downstream can tell the difference between "the SDK did not send it" and "the
+         * user never produced it". `frameId` was exactly that case: the column, the DTO field and
+         * the ingest write all existed already, and the value died on this line.
+         *
+         * Omitted when absent rather than sent as null, matching how screenName and label behave
+         * above — the v2 lean shape drops empty fields and the server reconstructs them.
+         */
+        if (e.frameId) out.frameId = e.frameId;
         const data = this._pruneEmpty(e.payload);
         if (data && Object.keys(data).length > 0) out.data = data;
         return out;
@@ -1265,15 +1326,81 @@ export class BackendSessionAdapter implements SessionTransport {
         }
     }
 
-    private async _flushErrors(): Promise<void> {
-        if (this.pendingErrors.length === 0 || !this.currentSessionId || !this.config.clientKey) return;
+    /**
+     * D11: deliver a bug report to the SAME ingest the web SDK uses
+     * (`POST /ingestion/sessions/:id/bug-reports`). Fire-and-forget with one
+     * retry deferral: RN previously had NO path to this endpoint at all —
+     * `reportBug()` emitted an analytics event no handler consumed, so the
+     * bug-reports page was empty forever for every RN app.
+     */
+    submitBugReport(report: { message: string; title?: string; email?: string }): void {
+        if (this.destroyed || !this.config.clientKey || !this.currentSessionId) return;
+        void this._post(
+            `/ingestion/sessions/${this.currentSessionId}/bug-reports`,
+            { ...report, timestamp: Date.now() },
+        ).catch(() => {
+            /* best-effort; the $bug_report analytics breadcrumb still records intent */
+        });
+    }
+
+    /**
+     * @returns TRUE only when every group in this batch was DURABLY accepted — an HTTP 2xx, or a
+     *          handoff to the native outbox, which is itself a persistent retrying queue.
+     *
+     * The return value is not cosmetic: `drainNativeCrash` deletes the on-disk crash record on the
+     * strength of it. This method used to return `void` and swallow its own errors in the catch
+     * below, so "the promise resolved" meant nothing at all — a failed POST looked exactly like a
+     * successful one, and the caller would have deleted the only durable copy of a crash that never
+     * arrived. Anything less than a real acknowledgement here reintroduces the loss this whole
+     * change exists to prevent.
+     */
+    private async _flushErrors(): Promise<boolean> {
+        if (this.pendingErrors.length === 0 || !this.currentSessionId || !this.config.clientKey) return false;
         const batch = this.pendingErrors.splice(0, 20);
         try {
-            if (await this._enqueueNative('errors', batch)) return;
-            if (!this._sessionRowReady()) { this.pendingErrors.unshift(...batch); return; }
-            await this._post(ENDPOINTS.INGESTION_ERRORS(this.currentSessionId), { errors: batch });
+            if (!this._sessionRowReady()) { this.pendingErrors.unshift(...batch); return false; }
+            /**
+             * ROUTED BY THE ERROR'S OWN SESSION, not by whichever session is current.
+             *
+             * A recovered native crash carries the id of the session it actually happened in — that
+             * process is gone, so the current session is the wrong owner. Sending it under
+             * `currentSessionId` is what marked a healthy session crashed and left the crashed one
+             * looking clean.
+             *
+             * The URL still carries a session because that is the established ingest shape; the
+             * error's own `sessionId` simply chooses WHICH one. Errors are grouped by their target
+             * so a batch mixing a recovered crash with live errors cannot drag the live ones onto
+             * the dead session.
+             */
+            const byTarget = new Map<string, typeof batch>();
+            for (const e of batch) {
+                const target = (e as { sessionId?: string }).sessionId || this.currentSessionId;
+                byTarget.set(target, [...(byTarget.get(target) ?? []), e]);
+            }
+            let allAccepted = true;
+            for (const [target, errors] of byTarget) {
+                // `sessionId` is a routing instruction, not payload — strip it so the stored row is
+                // byte-identical to one sent the ordinary way.
+                const cleaned = errors.map(({ sessionId: _s, ...rest }: any) => rest);
+
+                // The outbox is enqueued PER TARGET, so a recovered crash keeps its own session.
+                if (await this._enqueueNative('errors', cleaned, target)) continue;
+
+                try {
+                    await this._post(ENDPOINTS.INGESTION_ERRORS(target), { errors: cleaned });
+                } catch (err) {
+                    allAccepted = false;
+                    // A permanent error (4xx) will never succeed, so re-queuing it would spin
+                    // forever; anything else is worth another attempt.
+                    if (!BackendSessionAdapter._isPermanentHttpError(err)) {
+                        this.pendingErrors.unshift(...errors);
+                    }
+                }
+            }
+            return allAccepted;
         } catch (err) {
             if (!BackendSessionAdapter._isPermanentHttpError(err)) this.pendingErrors.unshift(...batch);
+            return false;
         }
     }
 

package/src/features/session/JourneyEventPipeline.ts

@@ -91,6 +91,8 @@ export class JourneyEventPipeline {
             traceId?: string;
             source?: JourneyEventSource;
             journeyId?: string;
+            /** Frame that was on screen when this happened. Resolved by the caller; see sessionTypes. */
+            frameId?: string;
         },
     ): JourneyEvent | null {
         try {
@@ -120,6 +122,7 @@ export class JourneyEventPipeline {
                 subtype: opts?.subtype,
                 severity: opts?.severity ?? inferSeverity(type),
                 screen: opts?.screen,
+                frameId: opts?.frameId,
                 payload: opts?.payload,
                 correlationId: opts?.correlationId,
                 traceId: opts?.traceId,

package/src/features/session/ReplayCaptureManager.ts

@@ -36,6 +36,7 @@ import {
     getFrameRetentionPriority,
     QUALITY_PRESETS,
 } from './sessionTypes';
+import type { PlatformOS } from '../../core/context/device';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -70,7 +71,8 @@ export interface StagedFrameResult {
     frameHash: string;
     masked: boolean;
     timestamp: number;
-    platform: 'android' | 'ios';
+    // Widened: frames now carry the REAL Platform.OS instead of being relabelled 'android'.
+    platform: PlatformOS;
 }
 
 /** JS-authoritative frame metadata written to the outbox on commit. */
@@ -258,6 +260,15 @@ export class ReplayCaptureManager {
     private _lastKeyframeTs = 0;
     /** P2-5: frameId of the last emitted keyframe — delta base reference. */
     private _lastKeyframeId: string | null = null;
+    /**
+     * Screen the last emitted keyframe was captured on.
+     *
+     * Tracked alongside the id purely so `currentKeyframe()` can refuse to hand a frame to an
+     * event on a different screen. The id and timestamp alone cannot answer that, and a frame
+     * from the previous screen is worse than none — it attaches a tap to a photograph of
+     * somewhere else, which every layer downstream would then present with full confidence.
+     */
+    private _lastKeyframeScreen: string | null = null;
     /** P2-5: emitted frames since the last keyframe (keyframe-interval guard). */
     private _framesSinceKeyframe = 0;
 
@@ -275,6 +286,45 @@ export class ReplayCaptureManager {
 
     // ─── Public API ─────────────────────────────────────────────────────
 
+    /**
+     * The keyframe that is still showing, or null.
+     *
+     * Answers "which picture was the user looking at" for an event that is about to be emitted,
+     * so a tap can carry the id of the frame it happened ON. Read-only; captures nothing.
+     *
+     * TWO CONDITIONS, both refusals rather than approximations:
+     *
+     *   SAME SCREEN. A keyframe from the previous screen is not what the user was looking at.
+     *   Navigation evicts the pending capture rather than re-pointing it, so after a screen
+     *   change the newest keyframe genuinely belongs to somewhere else.
+     *
+     *   STILL FRESH. A screen mutates constantly — a list loads, a banner rotates, a sheet is
+     *   dismissed. Past `maxAgeMs` the stored picture stops being evidence of what is on screen,
+     *   and stale evidence presented as current is the failure mode this whole feature exists to
+     *   avoid. 10 s is deliberately conservative: the capture manager already photographs on
+     *   interaction, navigation and scroll settle, so a genuinely active screen refreshes well
+     *   inside it, and a screen quiet for longer than that is one nobody is interacting with.
+     *
+     * Returning null is a correct, common answer and downstream MUST treat it as "not captured"
+     * rather than as a default.
+     */
+    currentKeyframe(
+        screenName?: string,
+        maxAgeMs = 10_000,
+        now: number = Date.now(),
+    ): { frameId: string; screen: string | null; capturedAt: number } | null {
+        if (!this._lastKeyframeId || this._lastKeyframeTs <= 0) return null;
+        if (now - this._lastKeyframeTs > maxAgeMs) return null;
+        // Compared only when the caller knows its screen. An event with no screen cannot be shown
+        // to belong to this frame, so it does not get one.
+        if (!screenName || this._lastKeyframeScreen !== screenName) return null;
+        return {
+            frameId: this._lastKeyframeId,
+            screen: this._lastKeyframeScreen,
+            capturedAt: this._lastKeyframeTs,
+        };
+    }
+
     /** Set callback for when a frame is captured */
     setFrameEmitCallback(cb: FrameEmitCallback): void {
         this.onFrameEmit = cb;
@@ -291,6 +341,7 @@ export class ReplayCaptureManager {
         this._lastFrameHash = null;
         this._lastKeyframeTs = 0;
         this._lastKeyframeId = null;
+        this._lastKeyframeScreen = null;
         this._framesSinceKeyframe = 0;
 
         // Start frequency timer if in frequency mode
@@ -808,6 +859,7 @@ export class ReplayCaptureManager {
             if (frameType === 'keyframe') {
                 this._lastKeyframeId = frameId;
                 this._lastKeyframeTs = now;
+                this._lastKeyframeScreen = screenName ?? null;
                 this._framesSinceKeyframe = 0;
             } else {
                 this._framesSinceKeyframe++;

package/src/features/session/SessionManager.ts

@@ -40,6 +40,7 @@ import { generateEventId } from '../replay/core/ids/sessionId';
 import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
 import { redactBody } from '../../debug/redaction';
 import { consumeCalibrationTarget } from '../journey/calibrationContext';
+import { resolvePlatformOS } from '../../core/context/device';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -385,12 +386,11 @@ export class SessionManager {
                 startedAt: Date.now(),
                 status: 'active',
                 metadata: {
-                    platform: (() => {
-                        try {
-                            const { Platform } = require('react-native');
-                            return Platform.OS === 'ios' ? 'ios' : 'android';
-                        } catch { return 'android'; }
-                    })(), // Real OS; enriched by native device info when available
+                    // The real Platform.OS. This used to be a ternary whose else-branch was 'android'
+                    // and whose catch was ALSO 'android' — so a macOS session, a Windows session, and
+                    // a failure to load react-native at all were reported identically, as Android.
+                    // Enriched by native device info when the bridge answers.
+                    platform: resolvePlatformOS(),
                     buildType: __DEV__ ? 'debug' : 'release',
                     ...metadata,
                     // Capture window dp dims here so emitEvent() can normalize coords
@@ -748,6 +748,20 @@ export class SessionManager {
             // new object and strips known-sensitive keys; coords/gesture survive.
             const safePayload = redactBody(payload) as Record<string, unknown>;
 
+            /**
+             * NO `frameId` HERE, and it is not an oversight.
+             *
+             * This method is guarded by `if (this.active) return;` — it runs ONLY when no replay
+             * recording is active, which is precisely when no screenshots are being captured.
+             * There is no frame on screen to point at, so an analytics-lane tap can never be
+             * attributed to a visual state.
+             *
+             * That makes it a permanent property of this lane rather than a gap to close later,
+             * and the dashboard has to account for it: these taps live in the heatmap grid
+             * alongside recorded ones, so a state filter necessarily covers a subset of the
+             * traffic. `heat:screen-coverage` reports that subset's size per app for exactly this
+             * reason.
+             */
             const event: JourneyEvent = {
                 eventId: generateEventId(),
                 // sessionId is (re)stamped by the analytics lane at flush time.
@@ -849,7 +863,32 @@ export class SessionManager {
                 } catch { /* no-throw */ }
             }
 
-            const event = this.pipeline.emit(type, opts);
+            /**
+             * Which frame was on screen when this happened.
+             *
+             * Resolved BEFORE `pipeline.emit`, and deliberately before the capture triggers
+             * below: those capture the frame that shows the RESULT of the interaction, and a tap
+             * belongs to the state it was made IN, not the one it produced. Reading after them
+             * would attribute every tap to its own consequence.
+             *
+             * USER_ACTION only. A SCREEN_VIEW's frame is the screen being left, which is
+             * misleading rather than useful, and no consumer asks for it.
+             *
+             * `currentKeyframe` returns null unless the frame is from this same screen and still
+             * fresh — see its contract. Null is the common, correct answer and stays absent on
+             * the event rather than becoming a default.
+             */
+            const framedOpts =
+                type === 'USER_ACTION'
+                    ? {
+                          ...opts,
+                          frameId: this.captureManager?.currentKeyframe(
+                              opts?.screen ?? this._lastKnownScreen ?? undefined,
+                          )?.frameId,
+                      }
+                    : opts;
+
+            const event = this.pipeline.emit(type, framedOpts);
 
             // Trigger capture on screen view or interaction
             if (event) {

package/src/features/session/nativeCapture.ts

@@ -4,6 +4,7 @@
  * Provides the callback for the SessionManager to request screenshots
  * from the native layer (PixelCopy on Android, UIWindow on iOS).
  */
+import { resolvePlatformOS, type PlatformOS } from '../../core/context/device';
 
 export const nativeCapture = async (sessionId: string, reason: string, _quality: any) => {
     try {
@@ -17,8 +18,8 @@ export const nativeCapture = async (sessionId: string, reason: string, _quality:
         const result = await replaySdk.captureScreenshot(reason);
         if (!result?.base64) return null;
 
-        const { Platform } = require('react-native');
-        const platform: 'android' | 'ios' = Platform.OS === 'ios' ? 'ios' : 'android';
+        // Platform.OS verbatim. The ternary this replaces labelled every non-iOS frame 'android'.
+        const platform: PlatformOS = resolvePlatformOS();
 
         return {
             base64: result.base64 as string,

package/src/features/session/outboxFrameCapture.ts

@@ -15,13 +15,14 @@
  * transparently falls back to the legacy `captureScreenshot` path.
  */
 
-import { Platform } from 'react-native';
 import { getReplaySdkNative } from '../replay/bridge/nativeModule';
+import { resolvePlatformOS, type PlatformOS } from '../../core/context/device';
 import type { OutboxFrameCapture, StagedFrameResult, OutboxFrameMeta } from './ReplayCaptureManager';
 
 /** Build the adapter. `ensureReady` resolves false when the native outbox is off. */
 export function makeOutboxFrameCapture(ensureReady: () => Promise<boolean>): OutboxFrameCapture {
-    const platform: 'android' | 'ios' = Platform.OS === 'ios' ? 'ios' : 'android';
+    // Platform.OS verbatim — see core/context/device.
+    const platform: PlatformOS = resolvePlatformOS();
 
     return {
         async capture(sessionId, screenName, trigger): Promise<StagedFrameResult | null> {

package/src/features/session/sessionTypes.ts

@@ -1,3 +1,4 @@
+import type { PlatformOS } from '../../core/context/device';
 /**
  * ScaleBun SDK — Unified Session Domain Model
  *
@@ -21,7 +22,9 @@ export interface SessionMetadata {
     appName?: string;
     appVersion?: string;
     bundleId?: string;
-    platform?: 'android' | 'ios' | 'web';
+    // Widened to the real Platform.OS — see core/context/device. The wire's platform field is an
+    // open enum, so a value this union did not anticipate travels rather than being coerced.
+    platform?: PlatformOS;
     osVersion?: string;
     deviceModel?: string;
     deviceName?: string;
@@ -78,6 +81,22 @@ export interface JourneyEvent {
     severity?: JourneyEventSeverity;
     /** Screen name at time of event */
     screen?: string;
+    /**
+     * frameId of the screenshot that was ON SCREEN when this event happened.
+     *
+     * The picture the user was looking at, not the one that follows. Mobile has no DOM to
+     * reconstruct, so a captured frame is the only record of what a screen looked like at a
+     * moment — which makes this the join key between a tap and the state it was made in.
+     *
+     * Set only when a keyframe from the SAME screen was captured recently enough to still be
+     * showing (see SessionManager.currentFrameForEvent). Absent means "not captured", which is a
+     * DIFFERENT answer from "nothing was open" and must never be folded into it:
+     *   · the analytics lane never has one — it runs only when no recording is active, so no
+     *     screenshots exist at all
+     *   · a tap right after navigation has none — the capture is debounced and evicted on
+     *     screen change
+     */
+    frameId?: string;
     payload?: Record<string, unknown>;
     /** Links related events (e.g. network request start → complete) */
     correlationId?: string;
@@ -114,7 +133,9 @@ export interface ReplayFrame {
     quality: ReplayQuality;
     captureReason: CaptureReason;
     /** Native-only capture — JS never captures frames */
-    sourcePlatform: 'android' | 'ios';
+    // Widened: a frame reports the REAL Platform.OS. The old union forced every non-iOS capture to
+    // be relabelled 'android', which is how RN-macOS and RN-Windows sessions became Android ones.
+    sourcePlatform: PlatformOS;
     redactionState?: 'none' | 'text-masked' | 'full';
     /** Screen name at capture time — for frame-to-screen correlation */
     screen?: string;
@@ -363,7 +384,9 @@ export interface NativeFrameResult {
     /** Byte size of the compressed image */
     byteSize: number;
     /** Platform that performed the capture */
-    platform: 'android' | 'ios';
+    // Widened from 'android'|'ios': a frame is labelled with the REAL Platform.OS now, and the
+    // old union forced every non-iOS capture to be relabelled 'android'.
+    platform: PlatformOS;
     /** Actual on-device encoding after the AVIF->WebP->JPEG fallback (P2-2). */
     format?: string;
     /** Optional native frame hash for change detection (P2-1). JS falls back to hashing base64. */

package/src/index.ts

@@ -12,7 +12,7 @@
 
 // ─── Default Export: SDK Facade Singleton ───────────────────────────────────
 // Usage: import ScaleBun from '@scalebun/react-native';
-//        await ScaleBun.init({ projectId: '...', publishableKey: '...', apiBaseUrl: '...' });
+//        await ScaleBun.init({ projectId: '...', publishableKey: '...' });
 
 export { default } from './public/ScaleBunFacade';
 export { ScaleBunProvider } from './public/ScaleBunProvider';
@@ -49,6 +49,9 @@ export {
 } from './features/engage/EngageAnchor';
 
 // ─── OTA Updates ───────────────────────────────────────────────────────────
+// D3: manual capture — existed for a year, exported to nobody, delivered to a
+// queue nothing drained. Now rides the proven crash pipeline.
+export { captureException, captureMessage } from './features/crash/capture';
 export { otaOrchestrator, OtaOrchestrator } from './features/ota/OtaOrchestrator';
 export type { SyncResult, BootGuardConfig } from './features/ota/OtaOrchestrator';
 export { useOtaUpdate } from './features/ota/useOtaUpdate';