@scalebun/react-native 1.0.2 → 1.0.4

package/src/push/types.ts

@@ -1,159 +1,159 @@
-/**
- * ScaleBun SDK — Push subsystem shared types.
- *
- * These types are platform-agnostic on purpose. The same event model
- * (PushNotification), identity contract (registerDeviceToken input on the
- * facade), and adapter shape are intended to be mirrored by future Flutter /
- * native SDKs so the backend token-registration and push-event contracts stay
- * identical across platforms. Only the adapter implementation is platform code.
- */
-
-export type PushPlatform = 'android' | 'ios';
-
-/**
- * Backend push-provider routing key. `fcm` = Firebase Cloud Messaging token
- * (Android, and iOS when routed through Firebase). `apns` = a raw Apple Push
- * Notification service device token (direct APNs, iOS only). This is the source of
- * truth the backend uses to pick the tenant's send transport for a device token.
- */
-export type PushProviderId = 'fcm' | 'apns';
-
-/**
- * Stable identifiers for the selected compatibility path. Surfaced by the
- * doctor CLI and `ScaleBun.push.status()` so developers know which path is live.
- *
- * - `rnfirebase` — @react-native-firebase/messaging (full callbacks).
- * - `native`     — the ScaleBunEngage native bridge (reflective FCM/APNs token).
- *                  Works under bridgeless regardless of the installed RNFirebase
- *                  JS version; token-only (no foreground/opened message stream).
- * - `manual`     — host supplies the token.
- * - `noop`       — fail-clear fallback.
- */
-export type AdapterId = 'rnfirebase' | 'native' | 'manual' | 'noop';
-
-export type NotificationPermissionStatus = 'granted' | 'denied' | 'provisional' | 'unavailable';
-
-/**
- * Normalized notification event. Every adapter maps its provider-specific
- * payload into this shape so consumer callbacks never depend on RNFirebase (or
- * any provider) types.
- */
-export interface PushNotification {
-    /** Provider message id when available. */
-    messageId?: string;
-    title?: string;
-    body?: string;
-    /** Arbitrary data payload (FCM `data`, APNs custom keys). Always defined. */
-    data: Record<string, string>;
-    /** Best-effort delivery time (ms epoch) when the provider reports it. */
-    sentTime?: number;
-}
-
-export interface AndroidChannelConfig {
-    channelId: string;
-    channelName?: string;
-    /** Android importance 0-5; defaults to 4 (HIGH) when omitted. */
-    importance?: number;
-    description?: string;
-}
-
-/**
- * Internal push provider abstraction (requirement 2).
- *
- * An adapter is responsible ONLY for talking to the platform: permission,
- * channels, token lifecycle, and notification events. It does NOT talk to the
- * ScaleBun backend — token registration/sync is owned by PushManager so the
- * backend contract is identical for every adapter.
- *
- * Every method must be safe to call and must not throw; failures are reported
- * via return values / status, never exceptions.
- */
-export interface PushAdapter {
-    readonly id: AdapterId;
-
-    /** True when this adapter's underlying provider is actually usable now. */
-    isAvailable(): boolean;
-
-    /**
-     * Push provider the acquired token belongs to — the backend routing key.
-     * Direct APNs (raw APNs device token on iOS) → 'apns'; Firebase-routed tokens
-     * (FCM, both platforms) → 'fcm'. Platform-dependent for adapters that bridge
-     * the native OS token directly (e.g. the ScaleBunEngage native bridge yields a raw
-     * APNs token on iOS but an FCM token on Android).
-     */
-    pushProvider(): PushProviderId;
-
-    /** Request OS notification permission (Android 13+, iOS). */
-    requestPermission(): Promise<NotificationPermissionStatus>;
-
-    /** Create/ensure an Android notification channel. No-op on iOS. */
-    createAndroidChannel(channel: AndroidChannelConfig): Promise<void>;
-
-    /** Acquire the current push token (FCM/APNs). Null when unavailable. */
-    getToken(): Promise<string | null>;
-
-    /** Subscribe to token rotation. Returns an unsubscribe fn. */
-    onTokenRefresh(cb: (token: string) => void): () => void;
-
-    /** Subscribe to messages received while the app is foregrounded. */
-    onForegroundMessage(cb: (message: PushNotification) => void): () => void;
-
-    /** Subscribe to the user tapping a notification (app already running). */
-    onNotificationOpened(cb: (message: PushNotification) => void): () => void;
-
-    /** The notification that cold-started the app, if any. */
-    getInitialNotification(): Promise<PushNotification | null>;
-
-    /** Remove all listeners. Idempotent. */
-    teardown(): void;
-}
-
-/**
- * Result of runtime environment probing used to pick an adapter (requirement 4).
- */
-export interface PushCapabilities {
-    platform: PushPlatform | 'unknown';
-    /** e.g. "0.78.3"; null when unknown. */
-    rnVersion: string | null;
-    rnVersionParts: { major: number; minor: number; patch: number } | null;
-    /** New Architecture / bridgeless runtime detected. */
-    isNewArchitecture: boolean;
-    isBridgeless: boolean;
-    /** @react-native-firebase/messaging require() succeeded. */
-    hasRNFirebaseMessaging: boolean;
-    /** Best-effort installed @react-native-firebase version, e.g. "21.6.1". */
-    rnFirebaseVersion: string | null;
-    rnFirebaseMajor: number | null;
-    /** The ScaleBunEngage native module is linked (native FCM/APNs token bridge). */
-    hasNativeEngageBridge: boolean;
-}
-
-/** Why a given adapter was (not) selected — actionable, surfaced to developers. */
-export interface AdapterSelection {
-    adapter: PushAdapter;
-    /** Human-readable, actionable explanation. */
-    reason: string;
-    /** True when the selected adapter can actually deliver a token. */
-    usable: boolean;
-}
-
-export interface EnablePushOptions {
-    /** Force a specific compatibility path; defaults to 'auto'. */
-    provider?: 'auto' | 'rnfirebase' | 'native' | 'manual';
-    /** Android channel config; a sensible default is used when omitted. */
-    android?: AndroidChannelConfig;
-    /** For provider:'manual' — a token the host app already obtained. */
-    manualToken?: string;
-    /** Skip the OS permission prompt (host app handles it). */
-    skipPermissionRequest?: boolean;
-    onForegroundNotification?: (message: PushNotification) => void;
-    onNotificationOpened?: (message: PushNotification) => void;
-}
-
-export interface EnablePushResult {
-    ok: boolean;
-    adapter: AdapterId;
-    reason: string;
-    permission?: NotificationPermissionStatus;
-    tokenRegistered?: boolean;
-}
+/**
+ * ScaleBun SDK — Push subsystem shared types.
+ *
+ * These types are platform-agnostic on purpose. The same event model
+ * (PushNotification), identity contract (registerDeviceToken input on the
+ * facade), and adapter shape are intended to be mirrored by future Flutter /
+ * native SDKs so the backend token-registration and push-event contracts stay
+ * identical across platforms. Only the adapter implementation is platform code.
+ */
+
+export type PushPlatform = 'android' | 'ios';
+
+/**
+ * Backend push-provider routing key. `fcm` = Firebase Cloud Messaging token
+ * (Android, and iOS when routed through Firebase). `apns` = a raw Apple Push
+ * Notification service device token (direct APNs, iOS only). This is the source of
+ * truth the backend uses to pick the tenant's send transport for a device token.
+ */
+export type PushProviderId = 'fcm' | 'apns';
+
+/**
+ * Stable identifiers for the selected compatibility path. Surfaced by the
+ * doctor CLI and `ScaleBun.push.status()` so developers know which path is live.
+ *
+ * - `rnfirebase` — @react-native-firebase/messaging (full callbacks).
+ * - `native`     — the ScaleBunEngage native bridge (reflective FCM/APNs token).
+ *                  Works under bridgeless regardless of the installed RNFirebase
+ *                  JS version; token-only (no foreground/opened message stream).
+ * - `manual`     — host supplies the token.
+ * - `noop`       — fail-clear fallback.
+ */
+export type AdapterId = 'rnfirebase' | 'native' | 'manual' | 'noop';
+
+export type NotificationPermissionStatus = 'granted' | 'denied' | 'provisional' | 'unavailable';
+
+/**
+ * Normalized notification event. Every adapter maps its provider-specific
+ * payload into this shape so consumer callbacks never depend on RNFirebase (or
+ * any provider) types.
+ */
+export interface PushNotification {
+    /** Provider message id when available. */
+    messageId?: string;
+    title?: string;
+    body?: string;
+    /** Arbitrary data payload (FCM `data`, APNs custom keys). Always defined. */
+    data: Record<string, string>;
+    /** Best-effort delivery time (ms epoch) when the provider reports it. */
+    sentTime?: number;
+}
+
+export interface AndroidChannelConfig {
+    channelId: string;
+    channelName?: string;
+    /** Android importance 0-5; defaults to 4 (HIGH) when omitted. */
+    importance?: number;
+    description?: string;
+}
+
+/**
+ * Internal push provider abstraction (requirement 2).
+ *
+ * An adapter is responsible ONLY for talking to the platform: permission,
+ * channels, token lifecycle, and notification events. It does NOT talk to the
+ * ScaleBun backend — token registration/sync is owned by PushManager so the
+ * backend contract is identical for every adapter.
+ *
+ * Every method must be safe to call and must not throw; failures are reported
+ * via return values / status, never exceptions.
+ */
+export interface PushAdapter {
+    readonly id: AdapterId;
+
+    /** True when this adapter's underlying provider is actually usable now. */
+    isAvailable(): boolean;
+
+    /**
+     * Push provider the acquired token belongs to — the backend routing key.
+     * Direct APNs (raw APNs device token on iOS) → 'apns'; Firebase-routed tokens
+     * (FCM, both platforms) → 'fcm'. Platform-dependent for adapters that bridge
+     * the native OS token directly (e.g. the ScaleBunEngage native bridge yields a raw
+     * APNs token on iOS but an FCM token on Android).
+     */
+    pushProvider(): PushProviderId;
+
+    /** Request OS notification permission (Android 13+, iOS). */
+    requestPermission(): Promise<NotificationPermissionStatus>;
+
+    /** Create/ensure an Android notification channel. No-op on iOS. */
+    createAndroidChannel(channel: AndroidChannelConfig): Promise<void>;
+
+    /** Acquire the current push token (FCM/APNs). Null when unavailable. */
+    getToken(): Promise<string | null>;
+
+    /** Subscribe to token rotation. Returns an unsubscribe fn. */
+    onTokenRefresh(cb: (token: string) => void): () => void;
+
+    /** Subscribe to messages received while the app is foregrounded. */
+    onForegroundMessage(cb: (message: PushNotification) => void): () => void;
+
+    /** Subscribe to the user tapping a notification (app already running). */
+    onNotificationOpened(cb: (message: PushNotification) => void): () => void;
+
+    /** The notification that cold-started the app, if any. */
+    getInitialNotification(): Promise<PushNotification | null>;
+
+    /** Remove all listeners. Idempotent. */
+    teardown(): void;
+}
+
+/**
+ * Result of runtime environment probing used to pick an adapter (requirement 4).
+ */
+export interface PushCapabilities {
+    platform: PushPlatform | 'unknown';
+    /** e.g. "0.78.3"; null when unknown. */
+    rnVersion: string | null;
+    rnVersionParts: { major: number; minor: number; patch: number } | null;
+    /** New Architecture / bridgeless runtime detected. */
+    isNewArchitecture: boolean;
+    isBridgeless: boolean;
+    /** @react-native-firebase/messaging require() succeeded. */
+    hasRNFirebaseMessaging: boolean;
+    /** Best-effort installed @react-native-firebase version, e.g. "21.6.1". */
+    rnFirebaseVersion: string | null;
+    rnFirebaseMajor: number | null;
+    /** The ScaleBunEngage native module is linked (native FCM/APNs token bridge). */
+    hasNativeEngageBridge: boolean;
+}
+
+/** Why a given adapter was (not) selected — actionable, surfaced to developers. */
+export interface AdapterSelection {
+    adapter: PushAdapter;
+    /** Human-readable, actionable explanation. */
+    reason: string;
+    /** True when the selected adapter can actually deliver a token. */
+    usable: boolean;
+}
+
+export interface EnablePushOptions {
+    /** Force a specific compatibility path; defaults to 'auto'. */
+    provider?: 'auto' | 'rnfirebase' | 'native' | 'manual';
+    /** Android channel config; a sensible default is used when omitted. */
+    android?: AndroidChannelConfig;
+    /** For provider:'manual' — a token the host app already obtained. */
+    manualToken?: string;
+    /** Skip the OS permission prompt (host app handles it). */
+    skipPermissionRequest?: boolean;
+    onForegroundNotification?: (message: PushNotification) => void;
+    onNotificationOpened?: (message: PushNotification) => void;
+}
+
+export interface EnablePushResult {
+    ok: boolean;
+    adapter: AdapterId;
+    reason: string;
+    permission?: NotificationPermissionStatus;
+    tokenRegistered?: boolean;
+}

package/src/specs/NativeReplaySdk.ts

@@ -1,99 +1,99 @@
-import type { TurboModule } from 'react-native';
-import { TurboModuleRegistry } from 'react-native';
-
-/**
- * React Native Codegen spec for the native session-replay module (`ReplaySdk`).
- *
- * Architecture-compatibility only — this does NOT change any replay business
- * logic. It declares the New Architecture (TurboModule) method surface so the
- * native module registers as a real TurboModule on Android; on iOS the module
- * subclasses `RCTEventEmitter` and is served via the interop layer.
- *
- * Replay events (`ReplaySdk_SessionStateChanged`, `_FrameCaptured`,
- * `_SessionLimitReached`, `_ScreenChanged`, …) are delivered via the device
- * event emitter and consumed with `NativeEventEmitter`, independent of this
- * spec and identical on both architectures. `addListener` / `removeListeners`
- * satisfy `NativeEventEmitter`.
- *
- * Codegen has a limited type system, so config/result maps are generic
- * `Object`. The richer types (NativeFrameResult, NativeSessionInfo, …) are kept
- * in `bridge/nativeModule.ts`, which casts this module to that interface — so no
- * caller loses typing.
- */
-export interface Spec extends TurboModule {
-  // Lifecycle
-  initialize(config: Object): Promise<boolean>;
-  startSession(): Promise<string>;
-  stopSession(): Promise<boolean>;
-  pauseSession(): Promise<boolean>;
-  resumeSession(): Promise<boolean>;
-
-  // Capture (resolve a frame Object or null at runtime)
-  captureFrame(reason: string): Promise<Object>;
-  captureManualFrame(): Promise<Object>;
-  captureScreenshot(reason: string): Promise<Object>;
-
-  // Native file outbox (durable; behind enableNativeFileOutbox).
-  // MUST be declared here: on strict New Arch codegen the TurboModule proxy only
-  // exposes Spec-declared methods, so omitting these makes the frame outbox path
-  // (captureScreenshotToFile → commit) silently resolve undefined → zero frames.
-  initOutbox(config: Object): Promise<boolean>;
-  captureScreenshotToFile(input: Object): Promise<Object>;
-  commitOutboxFrame(meta: Object): Promise<string>;
-  discardOutboxFrame(sessionId: string, frameId: string): Promise<boolean>;
-  enqueueOutboxRecords(lane: string, sessionId: string, records: Object[]): Promise<boolean>;
-  flushNativeOutbox(): Promise<boolean>;
-  recoverNativeOutbox(): Promise<boolean>;
-  getOutboxStats(): Promise<Object>;
-
-  // Voice notes (Slice D)
-  startVoiceRecording(): Promise<void>;
-  stopVoiceRecording(): Promise<Object>;
-  cancelVoiceRecording(): Promise<void>;
-
-  // Configuration
-  setEnabled(enabled: boolean): Promise<void>;
-  setCapturingMode(mode: string): Promise<void>;
-  setScreenshotQuality(quality: string): Promise<void>;
-  setScreenshotCaptureInterval(intervalMs: number): Promise<void>;
-  setUserStepsEnabled(enabled: boolean): Promise<void>;
-  setNetworkLogsEnabled(enabled: boolean): Promise<void>;
-  setSdkLogsEnabled(enabled: boolean): Promise<void>;
-
-  // Privacy
-  setPrivacyOptions(options: Object): Promise<void>;
-  maskElement(elementId: string): Promise<void>;
-  unmaskElement(elementId: string): Promise<void>;
-
-  // User
-  setUser(user: Object): Promise<void>;
-  clearUser(): Promise<void>;
-
-  // Breadcrumbs
-  addBreadcrumb(breadcrumb: Object): Promise<void>;
-  addNetworkBreadcrumb(request: Object): Promise<void>;
-
-  // Screen tracking
-  setCurrentScreen(screenName: string): Promise<void>;
-
-  // Interaction tracking
-  reportInteraction(interaction: Object): Promise<void>;
-
-  // Query (resolve an Object or null at runtime)
-  getSessionInfo(): Promise<Object>;
-  getDeviceInfo(): Promise<Object>;
-  getSessionReplayLink(): Promise<Object>;
-
-  // Upload
-  flushUpload(): Promise<boolean>;
-  cancelUpload(): Promise<void>;
-
-  // Cleanup
-  destroy(): Promise<void>;
-
-  // NativeEventEmitter contract.
-  addListener(eventName: string): void;
-  removeListeners(count: number): void;
-}
-
-export default TurboModuleRegistry.get<Spec>('ReplaySdk');
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * React Native Codegen spec for the native session-replay module (`ReplaySdk`).
+ *
+ * Architecture-compatibility only — this does NOT change any replay business
+ * logic. It declares the New Architecture (TurboModule) method surface so the
+ * native module registers as a real TurboModule on Android; on iOS the module
+ * subclasses `RCTEventEmitter` and is served via the interop layer.
+ *
+ * Replay events (`ReplaySdk_SessionStateChanged`, `_FrameCaptured`,
+ * `_SessionLimitReached`, `_ScreenChanged`, …) are delivered via the device
+ * event emitter and consumed with `NativeEventEmitter`, independent of this
+ * spec and identical on both architectures. `addListener` / `removeListeners`
+ * satisfy `NativeEventEmitter`.
+ *
+ * Codegen has a limited type system, so config/result maps are generic
+ * `Object`. The richer types (NativeFrameResult, NativeSessionInfo, …) are kept
+ * in `bridge/nativeModule.ts`, which casts this module to that interface — so no
+ * caller loses typing.
+ */
+export interface Spec extends TurboModule {
+  // Lifecycle
+  initialize(config: Object): Promise<boolean>;
+  startSession(): Promise<string>;
+  stopSession(): Promise<boolean>;
+  pauseSession(): Promise<boolean>;
+  resumeSession(): Promise<boolean>;
+
+  // Capture (resolve a frame Object or null at runtime)
+  captureFrame(reason: string): Promise<Object>;
+  captureManualFrame(): Promise<Object>;
+  captureScreenshot(reason: string): Promise<Object>;
+
+  // Native file outbox (durable; behind enableNativeFileOutbox).
+  // MUST be declared here: on strict New Arch codegen the TurboModule proxy only
+  // exposes Spec-declared methods, so omitting these makes the frame outbox path
+  // (captureScreenshotToFile → commit) silently resolve undefined → zero frames.
+  initOutbox(config: Object): Promise<boolean>;
+  captureScreenshotToFile(input: Object): Promise<Object>;
+  commitOutboxFrame(meta: Object): Promise<string>;
+  discardOutboxFrame(sessionId: string, frameId: string): Promise<boolean>;
+  enqueueOutboxRecords(lane: string, sessionId: string, records: Object[]): Promise<boolean>;
+  flushNativeOutbox(): Promise<boolean>;
+  recoverNativeOutbox(): Promise<boolean>;
+  getOutboxStats(): Promise<Object>;
+
+  // Voice notes (Slice D)
+  startVoiceRecording(): Promise<void>;
+  stopVoiceRecording(): Promise<Object>;
+  cancelVoiceRecording(): Promise<void>;
+
+  // Configuration
+  setEnabled(enabled: boolean): Promise<void>;
+  setCapturingMode(mode: string): Promise<void>;
+  setScreenshotQuality(quality: string): Promise<void>;
+  setScreenshotCaptureInterval(intervalMs: number): Promise<void>;
+  setUserStepsEnabled(enabled: boolean): Promise<void>;
+  setNetworkLogsEnabled(enabled: boolean): Promise<void>;
+  setSdkLogsEnabled(enabled: boolean): Promise<void>;
+
+  // Privacy
+  setPrivacyOptions(options: Object): Promise<void>;
+  maskElement(elementId: string): Promise<void>;
+  unmaskElement(elementId: string): Promise<void>;
+
+  // User
+  setUser(user: Object): Promise<void>;
+  clearUser(): Promise<void>;
+
+  // Breadcrumbs
+  addBreadcrumb(breadcrumb: Object): Promise<void>;
+  addNetworkBreadcrumb(request: Object): Promise<void>;
+
+  // Screen tracking
+  setCurrentScreen(screenName: string): Promise<void>;
+
+  // Interaction tracking
+  reportInteraction(interaction: Object): Promise<void>;
+
+  // Query (resolve an Object or null at runtime)
+  getSessionInfo(): Promise<Object>;
+  getDeviceInfo(): Promise<Object>;
+  getSessionReplayLink(): Promise<Object>;
+
+  // Upload
+  flushUpload(): Promise<boolean>;
+  cancelUpload(): Promise<void>;
+
+  // Cleanup
+  destroy(): Promise<void>;
+
+  // NativeEventEmitter contract.
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.get<Spec>('ReplaySdk');

package/src/specs/NativeScaleBunCrash.ts

@@ -1,36 +1,52 @@
-import type { TurboModule } from 'react-native';
-import { TurboModuleRegistry } from 'react-native';
-
-/**
- * React Native Codegen spec for the native crash module (`ScaleBunCrash`).
- *
- * This declares the New Architecture (TurboModule) interface. Codegen turns it
- * into the native `NativeScaleBunCrashSpec` base classes (Kotlin `com.scalebun.spec`
- * / generated ObjC protocol) that the Phase 2 `newarch` wrappers implement. On
- * Old Architecture the identical JS surface is served by the legacy
- * NativeModule. Method names/shapes mirror the existing native module exactly:
- * `install` / `crashNow` / `drainPendingCrash`.
- *
- * Type note: codegen has a limited type system, so `drainPendingCrash` is typed
- * as a generic `Object`. At runtime it resolves either a crash record
- * (name, exceptionType, message, threadName, timestamp, platform, stackTrace[],
- * cause{}) or `null` when there is no pending crash — callers must null-check.
- */
-export interface Spec extends TurboModule {
-  /** Install the native uncaught-exception / signal handler. Idempotent. */
-  install(): Promise<boolean>;
-
-  /** DEV/TEST only: crash the process so the next launch can drain it. */
-  crashNow(): Promise<boolean>;
-
-  /** Return the previous run's crash record (or null), then clear it. */
-  drainPendingCrash(): Promise<Object>;
-}
-
-/**
- * Resolved via `get` (not `getEnforcing`) so the SDK degrades gracefully when
- * the native module is unavailable (web/SSR, Expo Go) — it returns `null`
- * instead of throwing. On Old Architecture the bridge falls back to the legacy
- * `NativeModules.ScaleBunCrash`.
- */
-export default TurboModuleRegistry.get<Spec>('ScaleBunCrash');
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * React Native Codegen spec for the native crash module (`ScaleBunCrash`).
+ *
+ * This declares the New Architecture (TurboModule) interface. Codegen turns it
+ * into the native `NativeScaleBunCrashSpec` base classes (Kotlin `com.scalebun.spec`
+ * / generated ObjC protocol) that the Phase 2 `newarch` wrappers implement. On
+ * Old Architecture the identical JS surface is served by the legacy
+ * NativeModule. Method names/shapes mirror the existing native module exactly:
+ * `install` / `crashNow` / `drainPendingCrash`.
+ *
+ * Type note: codegen has a limited type system, so `drainPendingCrash` is typed
+ * as a generic `Object`. At runtime it resolves either a crash record
+ * (name, exceptionType, message, threadName, timestamp, platform, stackTrace[],
+ * cause{}) or `null` when there is no pending crash — callers must null-check.
+ */
+export interface Spec extends TurboModule {
+  /** Install the native uncaught-exception / signal handler. Idempotent. */
+  install(): Promise<boolean>;
+
+  /** DEV/TEST only: crash the process so the next launch can drain it. */
+  crashNow(): Promise<boolean>;
+
+  /**
+   * Record which session is live so a crash can name it.
+   *
+   * Called once per session. Native writes it to crash-safe storage BEFORE any crash can happen —
+   * a fatal handler cannot call back into JS to ask.
+   */
+  setActiveSessionId(sessionId: string): Promise<boolean>;
+
+  /** Return the previous run's crash record (or null), then clear it. */
+  drainPendingCrash(): Promise<Object>;
+
+  /**
+   * Delete a delivered crash by its stable id.
+   *
+   * Called ONLY after the backend has accepted it. The read is non-destructive precisely so this
+   * can be the moment of deletion — a failed upload must leave the durable copy in place.
+   */
+  clearPendingCrash(crashId: string): Promise<boolean>;
+}
+
+/**
+ * Resolved via `get` (not `getEnforcing`) so the SDK degrades gracefully when
+ * the native module is unavailable (web/SSR, Expo Go) — it returns `null`
+ * instead of throwing. On Old Architecture the bridge falls back to the legacy
+ * `NativeModules.ScaleBunCrash`.
+ */
+export default TurboModuleRegistry.get<Spec>('ScaleBunCrash');