@scalebun-release/react-native 2.5.0

package/src/features/crash/CrashFeature.ts

@@ -0,0 +1,87 @@
+/**
+ * ScaleBun SDK — Crash Feature
+ *
+ * Installs the JS global error handler (ErrorUtils) and routes every uncaught
+ * exception through the central CrashReporter, which fans it out to all sinks
+ * (desktop event stream + SaaS backend errors endpoint).
+ *
+ * SOLID: Single Responsibility — only owns the JS crash-handler lifecycle.
+ * Delivery concerns live in CrashReporter / its sinks.
+ */
+
+import type { IFeature, FeatureContext } from '../../core/contracts/IFeature';
+import { installCrashReporting } from './index';
+import { installRejectionHandler } from './rejectionHandler';
+import { getCrashReporter } from './CrashReporter';
+import { persistFatalJsCrash } from './nativeCrashBridge';
+import { Platform } from 'react-native';
+
+export class CrashFeature implements IFeature {
+    readonly name = 'crash';
+    private active = false;
+    private flushFn: () => Promise<void>;
+
+    constructor(flushFn: () => Promise<void>) {
+        this.flushFn = flushFn;
+    }
+
+    initialize(_context: FeatureContext): void {
+        if (this.active) return;
+        installCrashReporting((error: Error, isFatal: boolean) => {
+            getCrashReporter().report({
+                source: 'js',
+                type: isFatal ? 'crash' : 'handled',
+                isFatal,
+                message: error.message,
+                stack: error.stack,
+            });
+
+            if (isFatal) {
+                /**
+                 * Persist to disk FIRST, synchronously, before anything else.
+                 *
+                 * A fatal JS crash tears the process down before an async POST
+                 * can finish, so the report queued above can be lost. The native
+                 * write below completes on disk before this handler returns, and
+                 * the next launch drains and delivers it — the same guarantee
+                 * native crashes already had, now extended to JS.
+                 */
+                persistFatalJsCrash({
+                    message: error.message,
+                    stack: error.stack,
+                    platform: Platform.OS,
+                });
+                // Best-effort live delivery too, in case the process lingers.
+                this.flushFn();
+            }
+        });
+
+        /**
+         * Unhandled promise rejections — a SEPARATE intake from ErrorUtils, which never sees them.
+         *
+         * Never fatal: a rejected promise does not stop the app, so it is reported as 'handled' and
+         * does not flush. Marking these fatal would inflate the crash count with errors the user
+         * never experienced as a crash.
+         */
+        installRejectionHandler((error: Error) => {
+            getCrashReporter().report({
+                source: 'js',
+                type: 'handled',
+                isFatal: false,
+                message: error.message,
+                stack: error.stack,
+            });
+        });
+
+        this.active = true;
+    }
+
+    teardown(): void {
+        // Global error handler is process-global — cannot safely uninstall.
+        this.active = false;
+    }
+
+    get isActive(): boolean {
+        return this.active;
+    }
+}

package/src/features/crash/CrashReporter.ts

@@ -0,0 +1,189 @@
+/**
+ * ScaleBun SDK — Crash Reporter
+ *
+ * Single, central entry point for ALL crash/error reports regardless of origin
+ * (JS uncaught, handled via captureError, or native drained on next launch).
+ *
+ * SOLID:
+ *  - Single Responsibility: normalize a crash report and fan it out to sinks.
+ *  - Open/Closed: add new delivery targets by registering a CrashSink — no
+ *    caller or existing-sink changes required.
+ *  - Liskov/Interface Segregation: every sink implements the same minimal
+ *    `CrashSink` contract (one method).
+ *  - Dependency Inversion: callers depend on the CrashReporter abstraction,
+ *    not on the desktop/backend transports directly.
+ */
+
+import { noThrow } from '../../core/lifecycle/crashSafe';
+import { SessionManager } from '../session/SessionManager';
+import { scrubCrashFields } from './scrubCrash';
+
+/** Where the crash originated. */
+export type CrashSource = 'js' | 'handled' | 'native' | 'manual';
+
+/** Normalized, transport-agnostic crash report. */
+export interface CrashReport {
+    /** Human-readable error message. */
+    message: string;
+    /** Stack trace (JS string or joined native frames). */
+    stack?: string;
+    /** Coarse classification persisted on the backend: crash | handled | native. */
+    type: string;
+    /** True for process-terminating crashes. */
+    isFatal: boolean;
+    /** Origin of the report — used by sinks for tagging, never for routing. */
+    source: CrashSource;
+    /** Active screen at crash time, when known. */
+    screenName?: string;
+    /** ios | android, when known. */
+    platform?: string;
+    /** ISO timestamp; sinks default to now when omitted. */
+    timestamp?: string;
+    /** Free-form extra context (thread name, signal, cause, ...). */
+    metadata?: Record<string, unknown>;
+    /**
+     * The session this crash BELONGS to, when that is not the current one.
+     *
+     * Set only by a recovered native crash: it happened in a process that is already gone, so the
+     * session it belongs to is not the session running now. Without it the report is routed through
+     * whichever SessionManager exists at drain time and lands on the NEW session — marking a healthy
+     * session crashed and the crashed one clean.
+     *
+     * Absent means "the current session", which is correct for every live report.
+     */
+    sessionId?: string;
+    /**
+     * Stable id for a recovered native crash — the idempotency key.
+     *
+     * Generated ONCE when the crash was first written to disk, never per attempt, so any number of
+     * retries collapse to one backend record. An id minted at upload time would defeat dedupe
+     * entirely and turn every retry into a fresh duplicate crash.
+     */
+    crashId?: string;
+}
+
+/**
+ * A delivery target for crash reports. Implementations MUST be no-throw:
+ * a failing sink must never break crash delivery to the other sinks.
+ */
+export interface CrashSink {
+    readonly name: string;
+    deliver(report: CrashReport): void;
+}
+
+/**
+ * Fans a normalized crash report out to every registered sink.
+ * Sink failures are isolated (noThrow) so one bad target cannot starve others.
+ */
+export class CrashReporter {
+    private readonly sinks: CrashSink[] = [];
+
+    /** Register a delivery target. Returns an unsubscribe fn. */
+    registerSink(sink: CrashSink): () => void {
+        this.sinks.push(sink);
+        return () => {
+            const i = this.sinks.indexOf(sink);
+            if (i >= 0) this.sinks.splice(i, 1);
+        };
+    }
+
+    /**
+     * Deliver a crash report to all sinks. No-throw.
+     *
+     * Scrubbed ONCE, here, before any sink sees it — so no intake and no sink can carry a token or
+     * a phone number off the device (see scrubCrash.ts). If scrubbing itself fails, the report is
+     * reduced to what cannot leak rather than sent raw.
+     */
+    report(report: CrashReport): void {
+        const clean =
+            noThrow(() => scrubCrashFields(report)) ??
+            ({ ...report, message: 'Unscrubbable error message', stack: undefined, metadata: undefined } as CrashReport);
+        for (const sink of this.sinks) {
+            noThrow(() => sink.deliver(clean));
+        }
+    }
+}
+
+/**
+ * Desktop / analytics sink — emits a `$crash` event through the SDK event
+ * pipeline (debug stream + legacy events). Decoupled from the facade via an
+ * injected track function (Dependency Inversion).
+ */
+export class DesktopEventSink implements CrashSink {
+    readonly name = 'desktop';
+    constructor(
+        private readonly trackFn: (name: string, payload?: Record<string, unknown>) => void,
+    ) {}
+
+    deliver(report: CrashReport): void {
+        this.trackFn('$crash', {
+            message: report.message,
+            stack: report.stack,
+            isFatal: report.isFatal,
+            type: report.type,
+            source: report.source,
+            screenName: report.screenName,
+            platform: report.platform,
+            ...(report.metadata ?? {}),
+        });
+    }
+}
+
+/**
+ * SaaS backend sink — routes the report to the dedicated ingestion errors
+ * endpoint (the data the dashboard Crashes view reads). No-op when no
+ * clientKey-backed session is active.
+ */
+export class BackendErrorsSink implements CrashSink {
+    readonly name = 'backend';
+
+    deliver(report: CrashReport): void {
+        const transport = SessionManager.getExistingInstance()?.getBackendTransport();
+        if (!transport) return;
+        // D12: this used to forward four fields and drop the rest — so a native
+        // crash's signal/thread/exception-type were captured on device and
+        // discarded one call before the wire, every RN error row had a NULL
+        // platform (making Issue.primaryPlatform mean "web-only"), and fatality
+        // was indistinguishable from a handled error. The receiver has always
+        // accepted all of these.
+        transport.queueError({
+            type: report.type,
+            message: report.message,
+            stack: report.stack,
+            screenName: report.screenName,
+            platform: report.platform,
+            isFatal: report.isFatal,
+            metadata: report.metadata,
+            /**
+             * Carried through so the transport can address the ORIGINAL session.
+             *
+             * Set only on a recovered native crash, whose session died with its process. Omitted
+             * for every live report, where the current session is the right answer — so this
+             * changes nothing about normal error delivery.
+             */
+            ...(report.sessionId ? { sessionId: report.sessionId } : {}),
+            // Becomes SessionError.clientId, which is @unique — that constraint is what turns a
+            // retried crash into one record instead of a duplicate.
+            ...(report.crashId ? { clientId: report.crashId } : {}),
+        });
+        // Best-effort immediate delivery so the crash surfaces quickly.
+        transport.flushErrors().catch(() => {});
+    }
+}
+
+// ─── Module singleton ───────────────────────────────────────────────────────
+// A process-wide reporter so any origin (facade, CrashFeature, native drain)
+// reports through the same fan-out without prop-drilling.
+
+let _reporter: CrashReporter | null = null;
+
+/** Returns the shared reporter, lazily creating it on first use. */
+export function getCrashReporter(): CrashReporter {
+    if (!_reporter) _reporter = new CrashReporter();
+    return _reporter;
+}
+
+/** Reset (tests / SDK re-init). */
+export function resetCrashReporter(): void {
+    _reporter = null;
+}

package/src/features/crash/NativeCrashFeature.ts

@@ -0,0 +1,42 @@
+import type { IFeature, FeatureContext } from '../../core/contracts/IFeature';
+import { installNativeCrashHandler, drainNativeCrash } from './nativeCrashBridge';
+import { logger } from '../../core/logger/internalLogger';
+
+/**
+ * Installs native crash handlers (Android UncaughtExceptionHandler,
+ * iOS NSSetUncaughtExceptionHandler + signal handlers) and drains any
+ * crash record left from the previous process run.
+ *
+ * Runs alongside CrashFeature (which covers JS exceptions via ErrorUtils).
+ * Does not replace or modify the JS handler.
+ */
+export class NativeCrashFeature implements IFeature {
+    readonly name = 'crash.native';
+    private active = false;
+
+    initialize(_context: FeatureContext): void {
+        if (this.active) return;
+        this.active = true;
+
+        // Fire-and-forget: install native handler and drain previous crash.
+        // Failures are swallowed inside each bridge function (noThrow-wrapped).
+        installNativeCrashHandler().catch(() => {});
+
+        drainNativeCrash()
+            .then((found) => {
+                if (found) {
+                    __DEV__ && logger.info('[NativeCrashFeature] Previous native crash queued for upload');
+                }
+            })
+            .catch(() => {});
+    }
+
+    teardown(): void {
+        // Native crash handlers are process-global — cannot safely uninstall.
+        this.active = false;
+    }
+
+    get isActive(): boolean {
+        return this.active;
+    }
+}

package/src/features/crash/capture.ts

@@ -0,0 +1,48 @@
+import { noThrow } from '../../core/lifecycle/crashSafe';
+import { getCrashReporter } from './CrashReporter';
+
+/**
+ * Manual error/message capture — the `Sentry.captureException` equivalent.
+ *
+ * D3: these used to write envelopes into `memoryQueue`, a queue whose only
+ * drain (`Dispatcher.flush`) was registered in the DI container and never
+ * resolved by anything — every capture was accumulated and discarded. They
+ * were also never exported, so the two entry points were reachable by nobody
+ * and delivered to nowhere.
+ *
+ * Now they ride the SAME pipeline as automatic crash capture (CrashReporter →
+ * BackendErrorsSink → `/ingestion/sessions/:id/errors`) — the one path in this
+ * SDK that is proven to land rows.
+ */
+export function captureException(
+    error: Error,
+    extra?: { screenName?: string; metadata?: Record<string, unknown> },
+): void {
+    noThrow(() => {
+        getCrashReporter().report({
+            type: 'handled',
+            message: error.message,
+            stack: error.stack,
+            isFatal: false,
+            source: 'manual',
+            screenName: extra?.screenName,
+            metadata: extra?.metadata,
+        });
+    });
+}
+
+export function captureMessage(
+    message: string,
+    extra?: { screenName?: string; metadata?: Record<string, unknown> },
+): void {
+    noThrow(() => {
+        getCrashReporter().report({
+            type: 'handled',
+            message,
+            isFatal: false,
+            source: 'manual',
+            screenName: extra?.screenName,
+            metadata: extra?.metadata,
+        });
+    });
+}

package/src/features/crash/globalHandler.ts

@@ -0,0 +1,39 @@
+import { noThrow } from '../../core/lifecycle/crashSafe';
+import { logger } from '../../core/logger/internalLogger';
+
+/**
+ * Install the JS global (uncaught) error handler via React Native's `ErrorUtils`.
+ *
+ * `ErrorUtils` is accessed through `globalThis` rather than imported because:
+ *  - it is a runtime global; importing it from 'react-native' conflicts with the
+ *    ambient global value under `isolatedModules`, and
+ *  - on the New Architecture / bridgeless runtime it may be installed lazily, so
+ *    we feature-detect before use. (Calling it unguarded threw
+ *    "Cannot read property 'getGlobalHandler' of undefined" on New Arch.)
+ *
+ * No-op (logs once) when `ErrorUtils` is unavailable.
+ */
+export function installGlobalHandler(onCrash: (error: Error, isFatal: boolean) => void) {
+    noThrow(() => {
+        const errorUtils = (globalThis as any).ErrorUtils;
+        if (!errorUtils || typeof errorUtils.getGlobalHandler !== 'function') {
+            __DEV__ && logger.debug('[Crash] ErrorUtils unavailable — global JS error handler not installed');
+            return;
+        }
+
+        const originalHandler = errorUtils.getGlobalHandler();
+
+        errorUtils.setGlobalHandler((error: any, isFatal?: boolean) => {
+            __DEV__ && logger.debug('Caught global error:', error?.message);
+
+            onCrash(error, !!isFatal);
+
+            // Call original handler to maintain default behavior (e.g. RedBox)
+            if (originalHandler) {
+                originalHandler(error, isFatal);
+            }
+        });
+
+        __DEV__ && logger.debug('Global error handler installed');
+    });
+}

package/src/features/crash/index.ts

@@ -0,0 +1,8 @@
+import { installGlobalHandler } from './globalHandler';
+import { noThrow } from '../../core/lifecycle/crashSafe';
+
+export function installCrashReporting(onCrash: (error: Error, isFatal: boolean) => void) {
+    noThrow(() => {
+        installGlobalHandler(onCrash);
+    });
+}