@scalebun-release/react-native 2.5.0

package/lib/typescript/public/ScaleBunProvider.d.ts

@@ -0,0 +1,23 @@
+import { type ReactElement, type ReactNode } from 'react';
+import type { ScaleBunInitConfig, SimplifiedInitConfig } from './types';
+import { type EngagePromptProviderProps } from '../features/engage/EngagePromptProvider';
+export interface ScaleBunProviderProps extends Omit<EngagePromptProviderProps, 'engage' | 'children'> {
+    /** The same object accepted by `ScaleBun.init()`. Read once on mount. */
+    config: SimplifiedInitConfig | ScaleBunInitConfig | Record<string, unknown>;
+    /** Optional React Navigation ref used by automatic screen collection. */
+    navigationRef?: unknown;
+    /**
+     * Capture privacy-safe root touch metadata without wrapping individual
+     * buttons. Defaults to true; no text/input value is collected.
+     */
+    captureInteractions?: boolean;
+    onReady?: () => void;
+    onInitError?: (error: unknown) => void;
+    children: ReactNode;
+}
+/**
+ * One application-level wrapper for initialization, Engage rendering, screen
+ * discovery, and zero-instrumentation interaction collection.
+ */
+export declare function ScaleBunProvider({ config, navigationRef, captureInteractions, onReady, onInitError, children, ...engageProps }: ScaleBunProviderProps): ReactElement;
+//# sourceMappingURL=ScaleBunProvider.d.ts.map

package/lib/typescript/public/typedTracker.d.ts

@@ -0,0 +1,88 @@
+/**
+ * TYPED TRACKING PLAN — compile-time checking for `track()`.
+ *
+ * Mirrors the web SDK's `typedTracker.ts` on purpose: `track(name, props)` is the ONE call that
+ * behaves identically on both platforms. The automatic-event vocabularies share nothing — web emits
+ * `$pageview`/`$autocapture`/`$form_start`, this SDK emits `screen_viewed`/`app_foregrounded`/
+ * `permission_result` — so any event a product wants on BOTH has to be an explicit `track()`. A
+ * cross-platform event deserves one shared declaration, and this is the shape of it.
+ *
+ *   const tracker = createTypedTracker(ScaleBun, {
+ *     appointment_booked: {
+ *       required: ['clinic_id', 'slot_type'],
+ *       props: { clinic_id: 'string', slot_type: 'string', lead_time_hours: 'number' },
+ *     },
+ *   });
+ *
+ *   tracker.track('appointment_booked', { clinic_id: 'jc_01', slot_type: 'same_day' });   // ✓
+ *   tracker.track('appointment_bookd',  { … });                       // ✗ unknown event
+ *   tracker.track('appointment_booked', { clinic_id: 1, … });         // ✗ wrong type
+ *
+ * ⚠️ ONE DIFFERENCE FROM WEB, stated rather than left to be discovered: the web SDK ALSO evaluates
+ * its plan at RUNTIME (`analyticsOptions.plan` → `governance.ts`), so there a violation additionally
+ * warns and — in strict mode — drops. **This SDK has no runtime governance consumer today.** So
+ * `tracker.plan` is types-only here. It is exported in the identical shape so a single plan object
+ * can be shared with a web build and so it is already correct if runtime governance ever lands, but
+ * nothing on this platform reads it yet. Do not assume a violation is caught at runtime on mobile.
+ *
+ * Zero third-party dependencies, ~10 lines of runtime. Everything else is types, which cost nothing
+ * in the bundle.
+ */
+/** The primitive types a plan can declare. */
+export type PlanPropType = 'string' | 'number' | 'boolean';
+export interface TrackedEventSpec {
+    /** Property keys that must be present. */
+    readonly required?: readonly string[];
+    /** Expected primitive type per property key. */
+    readonly props?: Readonly<Record<string, PlanPropType>>;
+}
+export type TrackedEventMap = Readonly<Record<string, TrackedEventSpec>>;
+type Primitive<T> = T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : never;
+type RequiredKeys<S extends TrackedEventSpec> = S['required'] extends readonly (infer K extends string)[] ? K : never;
+type Declared<S extends TrackedEventSpec> = S['props'] extends Readonly<Record<string, PlanPropType>> ? S['props'] : Record<never, never>;
+/**
+ * The props object for one event: declared-and-required become mandatory, declared-and-not-required
+ * become optional, and a key listed in `required` but never typed stays mandatory as `unknown` — the
+ * plan said it must be there, and silently dropping it would be worse than typing it loosely.
+ */
+export type PropsFor<S extends TrackedEventSpec> = {
+    [K in keyof Declared<S> as K extends RequiredKeys<S> ? K : never]: Primitive<Declared<S>[K]>;
+} & {
+    [K in keyof Declared<S> as K extends RequiredKeys<S> ? never : K]?: Primitive<Declared<S>[K]>;
+} & {
+    [K in Exclude<RequiredKeys<S>, keyof Declared<S>>]: unknown;
+};
+/** Whether an event can be tracked with no argument at all (nothing required). */
+type PropsArg<S extends TrackedEventSpec> = Record<string, never> extends PropsFor<S> ? [props?: PropsFor<S>] : [props: PropsFor<S>];
+/** The minimum surface a tracker needs — the ScaleBun facade satisfies it structurally. */
+export interface TrackTarget {
+    track(name: string, props?: Record<string, any>): void;
+}
+/** The plan shape, kept byte-identical to web so one declaration can serve both platforms. */
+export interface TypedTrackerPlan<M extends TrackedEventMap> {
+    events: M;
+    allowUnknownEvents: boolean;
+    strict: boolean;
+}
+export interface TypedTracker<M extends TrackedEventMap> {
+    /** Type-checked `track`. Unknown event names and bad props are compile errors. */
+    track<N extends keyof M & string>(name: N, ...args: PropsArg<M[N]>): void;
+    /**
+     * The plan object. On WEB this goes to `init({ analytics: { plan } })` and is enforced at runtime;
+     * on this platform nothing reads it yet — see the note at the top of this file.
+     */
+    readonly plan: TypedTrackerPlan<M>;
+    /** Escape hatch for a genuinely dynamic name — explicit, so it is greppable in review. */
+    trackUnchecked(name: string, props?: Record<string, any>): void;
+}
+export declare function createTypedTracker<const M extends TrackedEventMap>(sdk: TrackTarget, events: M, options?: {
+    allowUnknownEvents?: boolean;
+    strict?: boolean;
+}): TypedTracker<M>;
+/**
+ * Declare a plan without wiring a tracker — for sharing one plan across modules or across platforms.
+ * Identity at runtime; its whole job is to preserve the literal types (via `const`).
+ */
+export declare function defineTrackingPlan<const M extends TrackedEventMap>(events: M): M;
+export {};
+//# sourceMappingURL=typedTracker.d.ts.map

package/lib/typescript/public/types.d.ts

@@ -0,0 +1,316 @@
+/**
+ * ScaleBun SDK — Public Types
+ *
+ * User-facing TypeScript types for the SDK.
+ * Only types in this file should be exported from the root index.ts.
+ *
+ * Preserves the current config model (projectId, publishableKey, apiBaseUrl).
+ * Adds a `features` opt-out object for default-on capability control.
+ */
+/**
+ * Performance pipeline activation flags, tiered by cost-vs-value.
+ *
+ * Defaults are conservative ("default-safe"): cheap event-driven Tier-1
+ * collectors are on; the heavier UI-hang watchdog and the Tier-2 sampled
+ * collectors are off until their overhead is measured on a low-end device.
+ * Every flag is read at init — change rates/enablement without an SDK release.
+ */
+export interface PerformanceFlags {
+    /** Master enable; also gates native ScaleBunPerformance.initialize(). Default: true */
+    enabled?: boolean;
+    /** Tier-1: cheap, event-driven collectors. */
+    tier1?: {
+        /** App launch (one-shot at start). Default: true */
+        appLaunch?: boolean;
+        /** Screen load (per navigation). Default: true */
+        screenLoad?: boolean;
+        /** Network perf (slow/failed requests). Default: true */
+        network?: boolean;
+        /** UI hang / ANR watchdog — emits only on a real hang. Default: true (forward-only; needs native module). */
+        uiHang?: boolean;
+    };
+    /** Tier-2: heavy, continuous collectors (frame_metrics + js_stall), per-session sampled. */
+    tier2?: {
+        /** Master enable for Tier-2. Default: true (still gated by sampleRate). */
+        enabled?: boolean;
+        /** Per-session sampling fraction 0..1. Default: 0.1 (conservative; set 0 to disable). */
+        sampleRate?: number;
+    };
+}
+/** Feature opt-out flags. All default to `true` (enabled). */
+export interface ScaleBunFeatures {
+    /** Enable session replay capture. Default: true */
+    replay?: boolean;
+    /** Enable network request monitoring. Default: true */
+    network?: boolean;
+    /** Enable crash reporting. Default: true */
+    crashes?: boolean;
+    /** Enable unified session tracking. Default: true */
+    session?: boolean;
+    /** Enable user journey tracking. Default: true */
+    journey?: boolean;
+    /** Enable native performance monitoring. Default: true */
+    performance?: boolean;
+}
+/**
+ * SDK initialization config.
+ *
+ * Extends the current core config with an optional `features` block
+ * for selective feature opt-out.
+ *
+ * The core config properties (projectId, publishableKey, apiBaseUrl)
+ * are preserved exactly as they exist today.
+ */
+export interface ScaleBunInitConfig {
+    /** Project ID from dashboard */
+    projectId: string;
+    /** Publishable API key from dashboard */
+    publishableKey: string;
+    /**
+     * @deprecated The endpoint is LOCKED to the ScaleBun cloud. Any value passed here is accepted
+     * (for backward compatibility) but ignored — the bootstrapper always uses the fixed
+     * `DEFAULT_API_BASE_URL`. To target a different backend, change that constant at build time.
+     */
+    apiBaseUrl?: string;
+    /** @deprecated Use desktopDebug instead */
+    debug?: boolean;
+    /** Enable session replay capture (feature on/off). Default: true */
+    sessionReplay?: boolean;
+    /**
+     * Session-replay capture options (SaaS mode).
+     * - `record` (default **true**): auto-start frame recording at cold launch so replays appear out
+     *   of the box. Set `false` for events-only sessions — you can still record on demand with
+     *   `ScaleBun.startSession()`.
+     * - `captureMode` / `intervalMs` / `quality`: tune capture cadence.
+     */
+    replay?: {
+        record?: boolean;
+        captureMode?: 'navigation' | 'interactions';
+        intervalMs?: number;
+        quality?: 'high' | 'normal' | 'low' | 'grayscale';
+    };
+    /** Event flush interval in ms. Default: 5000 */
+    flushIntervalMs?: number;
+    /** Max events per flush batch. Default: 1000 */
+    maxQueueSize?: number;
+    /** Enable network request monitoring. Default: true */
+    enableNetworkMonitoring?: boolean;
+    /** Feature opt-out flags (all enabled by default) */
+    features?: ScaleBunFeatures;
+    /** Performance pipeline activation flags (tiered, default-safe). */
+    performance?: PerformanceFlags;
+    /**
+     * Capture `console.*` output into the Diagnose → Logs lane (SaaS mode). Default: **false**.
+     * Off by default because console output can carry PII/secrets and adds ingest volume.
+     * Requires a `clientKey`; no desktop-debug/devTools setup needed.
+     */
+    captureConsoleLogs?: boolean;
+}
+/** User identity for the SDK */
+export interface ScaleBunUser {
+    /** Unique user identifier */
+    id: string;
+    /** Display name */
+    name?: string;
+    /** Email address */
+    email?: string;
+    /** Arbitrary key-value metadata */
+    attributes?: Record<string, string | number | boolean>;
+    /** Arbitrary properties (alias for attributes, used by ingestion) */
+    properties?: Record<string, any>;
+}
+/**
+ * Debug / desktop connection config.
+ *
+ * When `true`, auto-connects using resolved defaults (10.0.2.2 for Android
+ * emulator, localhost otherwise, port 9333).
+ *
+ * When an object, provides explicit connection parameters.
+ * Passing `false` or omitting disables desktop debug connection.
+ */
+export type DebugConnectionConfig = boolean | {
+    /** Auto-connect to desktop using default host resolution. Default: true */
+    autoConnect?: boolean;
+    /** Explicit desktop host (IP or hostname). Overrides auto-resolution. */
+    host?: string;
+    /** Desktop WebSocket port. Default: 9333 */
+    port?: number;
+    /** App name shown in desktop device list */
+    appName?: string;
+    /** App bundle ID */
+    bundleId?: string;
+    /**
+     * Shared secret for desktop authentication.
+     * Must match the secret shown in Desktop's Connection panel.
+     *
+     * If the desktop has enforcement ON and this is omitted/wrong,
+     * the connection will be rejected (WS close code 4401).
+     *
+     * Default: null (omitted from HelloMessage — backward compatible).
+     *
+     * Migration path:
+     *   1. Open Desktop → Connection panel → copy the displayed secret.
+     *   2. Add `secret: '<copied value>'` here.
+     *   3. If the desktop has enforcement OFF, this field is ignored.
+     *
+     * SECURITY NOTE: This is local-network authentication only.
+     * The WS channel (ws://) is unencrypted. The secret prevents
+     * unauthorized connections, not eavesdropping.
+     */
+    secret?: string | null;
+};
+/** SDK-wide privacy settings */
+export interface PrivacyConfig {
+    /** Redact Authorization headers in network capture. Default: true */
+    redactAuth?: boolean;
+    /** Redact Cookie headers in network capture. Default: true */
+    redactCookies?: boolean;
+    /** Redact request/response bodies in network capture. Default: false */
+    redactBodies?: boolean;
+    /** Mask text input values in session replay. Default: true */
+    maskTextInputs?: boolean;
+    /** Mask image content in session replay. Default: false */
+    maskImages?: boolean;
+}
+/** Report branding settings (applied to export output) */
+export interface BrandingConfig {
+    /** Company name for report header */
+    company?: string;
+    /** Mark reports as confidential */
+    confidential?: boolean;
+    /** Custom report footer text */
+    footer?: string;
+}
+/** Built-in export preset names (maps to desktop BUILTIN_PRESETS) */
+export type ExportPresetName = 'executive' | 'engineering' | 'qa' | 'forensic' | 'journey' | 'compact';
+/** Simplified export options for the public API */
+export interface SimplifiedExportOptions {
+    /** Export format. Default: 'pdf' */
+    format?: 'pdf' | 'docx';
+    /** Detail level. Default: 'standard' */
+    detail?: 'minimal' | 'standard' | 'detailed' | 'forensic';
+    /** Built-in preset to use (overrides format/detail if set) */
+    preset?: ExportPresetName;
+    /** Include screenshots in report. Default: true */
+    includeScreenshots?: boolean;
+}
+/** Result of an export operation */
+export interface ExportResult {
+    /** Whether the export completed successfully */
+    success: boolean;
+    /** File path where the report was saved (desktop-local) */
+    filePath?: string;
+    /** Error message if export failed */
+    error?: string;
+    /** Export was cancelled by the user */
+    cancelled?: boolean;
+}
+/**
+ * Simplified SDK initialization config.
+ *
+ * This is the primary config type for `ScaleBun.init()`.
+ * It merges the previous multi-step setup (init + enableDebug + feature flags)
+ * into a single config object.
+ *
+ * Minimal usage:
+ * ```ts
+ * await ScaleBun.init({
+ *   projectId: 'proj_xxx',
+ *   publishableKey: 'pk_xxx',
+ * });
+ * ```
+ *
+ * With debug auto-connect:
+ * ```ts
+ * await ScaleBun.init({
+ *   projectId: 'proj_xxx',
+ *   publishableKey: 'pk_xxx',
+ *   debug: true,
+ * });
+ * ```
+ */
+export interface SimplifiedInitConfig {
+    /** Project ID from dashboard */
+    projectId: string;
+    /** Publishable API key from dashboard */
+    publishableKey: string;
+    /**
+     * @deprecated The endpoint is LOCKED to the ScaleBun cloud. Any value passed here is accepted
+     * (for backward compatibility) but ignored — the bootstrapper always uses the fixed
+     * `DEFAULT_API_BASE_URL`. To target a different backend, change that constant at build time.
+     */
+    apiBaseUrl?: string;
+    /**
+     * Desktop debug connection.
+     *
+     * - `true` → auto-connect with default host/port
+     * - `{ host, port }` → explicit connection
+     * - `false` or omitted → no desktop connection
+     */
+    desktopDebug?: DebugConnectionConfig;
+    /** @deprecated Use desktopDebug instead. */
+    debug?: DebugConnectionConfig;
+    /** Enable session replay capture (feature on/off). Default: true */
+    sessionReplay?: boolean;
+    /**
+     * Session-replay capture options (SaaS mode).
+     * - `record` (default **true**): auto-start frame recording at cold launch so replays appear out
+     *   of the box. Set `false` for events-only sessions — you can still record on demand with
+     *   `ScaleBun.startSession()`.
+     * - `captureMode` / `intervalMs` / `quality`: tune capture cadence.
+     */
+    replay?: {
+        record?: boolean;
+        captureMode?: 'navigation' | 'interactions';
+        intervalMs?: number;
+        quality?: 'high' | 'normal' | 'low' | 'grayscale';
+    };
+    /** SDK-wide privacy settings */
+    privacy?: PrivacyConfig;
+    /** Feature opt-out flags (all enabled by default) */
+    features?: ScaleBunFeatures;
+    /** Enable verbose SDK logging. Default: false */
+    verbose?: boolean;
+    /** Event flush interval in ms. Default: 5000 */
+    flushIntervalMs?: number;
+    /** Max events per flush batch. Default: 1000 */
+    maxQueueSize?: number;
+    /** Performance pipeline activation flags (tiered, default-safe). */
+    performance?: PerformanceFlags;
+    /**
+     * Capture `console.*` output into the Diagnose → Logs lane (SaaS mode). Default: **false**.
+     * Off by default because console output can carry PII/secrets and adds ingest volume —
+     * enable it deliberately. Requires a `clientKey`; no desktop-debug/devTools setup needed.
+     */
+    captureConsoleLogs?: boolean;
+    /** Dashboard App ID. Required to enable the envelope event-tracking lane. */
+    appId?: string;
+    /** SDK client key (SaaS mode). Also used to authenticate the envelope lane. */
+    clientKey?: string;
+    /**
+     * Patch React Native's ScrollView export so every scroll view reports its scroll offset,
+     * giving taps their content depth without the app swapping to ScaleBunScrollView.
+     *
+     * OFF BY DEFAULT because it changes what the host renders, not merely what the SDK records:
+     * every scroll view in the app — including ones inside libraries you did not write — routes
+     * through an SDK wrapper. Turn it on deliberately. With it off, taps on a plain ScrollView
+     * report no content depth and say so, rather than reporting a fabricated offset of 0.
+     */
+    autoInstrumentScrollViews?: boolean;
+    /** Platform OVERRIDE — auto-detected from Platform.OS when omitted (integrations should omit it). */
+    platform?: 'ios' | 'android' | 'web' | 'react_native';
+    /**
+     * Enable the Phase 1 envelope tracking lane (first_open/app_open/session_start/
+     * track/identify/trackPurchase → /v1/batch). Default: true when appId is present.
+     */
+    eventTracking?: boolean;
+    /**
+     * Upload zero-instrumentation screen, deep-link, interaction, push, and Engage
+     * events. Direct `ScaleBun.init()` integrations must opt in; the application-
+     * level `ScaleBunProvider` enables it by default.
+     */
+    automaticEventTracking?: boolean;
+    /** Auto-emit first_open/app_open/session_start on init. Default: true. */
+    autoLifecycleEvents?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/push/PushManager.d.ts

@@ -0,0 +1,69 @@
+/**
+ * PushManager — orchestrates the full enablePush flow on top of whatever
+ * adapter the selector picks.
+ *
+ * Responsibilities (the parts that are identical across every adapter and every
+ * future platform): permission → channel → token acquisition → token refresh →
+ * backend registration/sync → notification callbacks → cold-start notification.
+ *
+ * Backend registration is injected (registerToken) rather than imported, so the
+ * push subsystem stays decoupled from the facade and the device-token contract
+ * lives in exactly one place. In this SDK the facade routes registerToken into
+ * the existing Engage outbox (EngageTransport.registerDeviceToken).
+ */
+import type { AdapterId, EnablePushOptions, EnablePushResult, PushNotification, PushProviderId } from './types';
+export interface PushManagerDeps {
+    /** Backend device-token registration (routes through the Engage outbox). */
+    registerToken: (input: {
+        pushToken: string;
+        platform: 'android' | 'ios';
+        /** Backend routing key: direct APNs (iOS) → 'apns'; Firebase → 'fcm'. */
+        pushProvider: PushProviderId;
+        tokenStatus?: 'active' | 'inactive';
+    }) => Promise<any>;
+}
+export interface PushStatus {
+    enabled: boolean;
+    adapter: AdapterId | null;
+    usable: boolean;
+    reason: string;
+    token: string | null;
+    permission: string | null;
+}
+export declare class PushManager {
+    private deps;
+    private adapter;
+    private token;
+    /** Last token value already sent to the backend, to drop redundant re-registrations. */
+    private lastSyncedToken;
+    private enabled;
+    private usable;
+    private reason;
+    private permission;
+    private unsubscribers;
+    constructor(deps: PushManagerDeps);
+    enable(options?: EnablePushOptions): Promise<EnablePushResult>;
+    private captureNotification;
+    /**
+     * Register a device token with the backend. Redundant registrations of the same token
+     * (e.g. onTokenRefresh firing the initial token that getToken already returned) are
+     * skipped unless `force` is set. `force` is used by resyncToken to re-send the
+     * token→user link when the identified user changes, so identity re-linking is preserved.
+     */
+    private syncToken;
+    setToken(token: string): void;
+    emitForeground(message: PushNotification): void;
+    emitNotificationOpened(message: PushNotification): void;
+    getToken(): string | null;
+    /**
+     * Re-register the current token with the backend (idempotent upsert). Used when the
+     * identified user changes after push is already enabled, so the token→user link is
+     * re-sent. No-op when no token has been acquired yet.
+     */
+    resyncToken(): void;
+    onForegroundNotification(cb: (message: PushNotification) => void): () => void;
+    onNotificationOpened(cb: (message: PushNotification) => void): () => void;
+    status(): PushStatus;
+    teardown(): void;
+}
+//# sourceMappingURL=PushManager.d.ts.map

package/lib/typescript/push/adapters/ManualAdapter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Manual / custom adapter — a real, production path for apps that obtain their
+ * push token themselves (their own native FCM/APNs code, an alternate provider,
+ * or a provider the SDK has no built-in adapter for).
+ *
+ * The host app supplies the token (via enablePush({ provider:'manual',
+ * manualToken }) or ScaleBun.push.setToken()) and drives notification events
+ * (ScaleBun.push.emitForeground / emitNotificationOpened). PushManager then
+ * syncs the token to the backend exactly like any other adapter, so the
+ * device-token contract is identical regardless of how the token was acquired.
+ */
+import type { AndroidChannelConfig, NotificationPermissionStatus, PushAdapter, PushNotification, PushProviderId } from '../types';
+export declare class ManualAdapter implements PushAdapter {
+    readonly id: "manual";
+    private token;
+    private provider?;
+    private refreshListeners;
+    private foregroundListeners;
+    private openedListeners;
+    constructor(initialToken?: string | null, provider?: PushProviderId);
+    isAvailable(): boolean;
+    /**
+     * Provider the host-supplied token belongs to. Defaults by platform
+     * (iOS → 'apns', Android → 'fcm') unless the host overrides it — an FCM token
+     * on iOS (via the host's own Firebase) stays routable by passing 'fcm'.
+     */
+    pushProvider(): PushProviderId;
+    requestPermission(): Promise<NotificationPermissionStatus>;
+    createAndroidChannel(_channel: AndroidChannelConfig): Promise<void>;
+    getToken(): Promise<string | null>;
+    onTokenRefresh(cb: (token: string) => void): () => void;
+    onForegroundMessage(cb: (message: PushNotification) => void): () => void;
+    onNotificationOpened(cb: (message: PushNotification) => void): () => void;
+    getInitialNotification(): Promise<PushNotification | null>;
+    teardown(): void;
+    setToken(token: string): void;
+    emitForeground(message: PushNotification): void;
+    emitNotificationOpened(message: PushNotification): void;
+}
+//# sourceMappingURL=ManualAdapter.d.ts.map

package/lib/typescript/push/adapters/NativeBridgeAdapter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Native ScaleBunEngage bridge adapter.
+ *
+ * Wraps the SDK's own `ScaleBunEngage` native module (Android Kotlin / iOS Swift) to
+ * acquire the platform push token and (on iOS) handle notifications — with NO
+ * @react-native-firebase JS dependency and NO Notifee. It works under the New
+ * Architecture / bridgeless runtime, exactly the case where the RNFirebase JS
+ * adapter is unusable.
+ *
+ * Platform behaviour:
+ *  - iOS (direct APNs): the native `UNUserNotificationCenter` surface owns the full
+ *    flow — request permission, capture the RAW APNs device token (NOT an FCM
+ *    token, NOT via Firebase), foreground presentation, tap/open, and cold-start.
+ *    `pushProvider()` is 'apns'. This is the native-first direct-APNs path.
+ *  - Android: token acquisition + refresh only (the reflective FCM token; the OS
+ *    renders the tray, so foreground/opened message callbacks are inert here and
+ *    full callbacks come from the RNFirebase adapter). `pushProvider()` is 'fcm'.
+ */
+import type { AndroidChannelConfig, NotificationPermissionStatus, PushAdapter, PushNotification, PushProviderId } from '../types';
+export declare class NativeBridgeAdapter implements PushAdapter {
+    readonly id: "native";
+    private available;
+    private unsubscribers;
+    constructor(available: boolean);
+    isAvailable(): boolean;
+    /** Direct APNs (raw APNs token) on iOS; reflective FCM token on Android. */
+    pushProvider(): PushProviderId;
+    requestPermission(): Promise<NotificationPermissionStatus>;
+    createAndroidChannel(_channel: AndroidChannelConfig): Promise<void>;
+    getToken(): Promise<string | null>;
+    onTokenRefresh(cb: (token: string) => void): () => void;
+    onForegroundMessage(cb: (message: PushNotification) => void): () => void;
+    onNotificationOpened(cb: (message: PushNotification) => void): () => void;
+    getInitialNotification(): Promise<PushNotification | null>;
+    teardown(): void;
+}
+//# sourceMappingURL=NativeBridgeAdapter.d.ts.map

package/lib/typescript/push/adapters/NoopAdapter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Safe fallback adapter (requirement 8). Selected only when no usable push path
+ * exists. Every method is inert and it reports `isAvailable() === false`, so
+ * enablePush fails clearly with an actionable reason instead of silently
+ * pretending push works.
+ */
+import type { AndroidChannelConfig, NotificationPermissionStatus, PushAdapter, PushNotification, PushProviderId } from '../types';
+export declare class NoopAdapter implements PushAdapter {
+    readonly id: "noop";
+    isAvailable(): boolean;
+    pushProvider(): PushProviderId;
+    requestPermission(): Promise<NotificationPermissionStatus>;
+    createAndroidChannel(_channel: AndroidChannelConfig): Promise<void>;
+    getToken(): Promise<string | null>;
+    onTokenRefresh(_cb: (token: string) => void): () => void;
+    onForegroundMessage(_cb: (message: PushNotification) => void): () => void;
+    onNotificationOpened(_cb: (message: PushNotification) => void): () => void;
+    getInitialNotification(): Promise<PushNotification | null>;
+    teardown(): void;
+}
+//# sourceMappingURL=NoopAdapter.d.ts.map

package/lib/typescript/push/adapters/RNFirebaseMessagingAdapter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @react-native-firebase/messaging adapter.
+ *
+ * Covers BOTH the legacy bridge and the New Architecture / bridgeless runtime —
+ * the JS surface (`messaging()`) is identical; the difference is the *installed*
+ * RNFirebase version, which the selector gates (bridgeless needs v18+). This
+ * adapter never imports RNFirebase at module scope: it `require`s it lazily so
+ * the SDK has zero hard dependency on Firebase (requirement 5).
+ *
+ * Android notification channels + foreground display: native-first. RNFirebase/
+ * messaging has no JS channel API and does NOT render a notification while the app
+ * is foreground. The SDK's NATIVE layer (`ScaleBunEngage` → `ScaleBunNotificationPresenter`,
+ * framework APIs only) owns channel creation and foreground display — NO Notifee is
+ * required by the core. When the native surface is unavailable we fail soft to FCM's
+ * manifest-declared fallback channel (background/tray delivery is unaffected — the OS
+ * renders those from the FCM `notification` payload). Token registration with the
+ * ScaleBun backend is NOT done here — PushManager owns that.
+ */
+import type { AndroidChannelConfig, NotificationPermissionStatus, PushAdapter, PushNotification, PushProviderId } from '../types';
+export declare class RNFirebaseMessagingAdapter implements PushAdapter {
+    readonly id: "rnfirebase";
+    private messaging;
+    private unsubscribers;
+    /** Channel id last created — foreground native display posts onto it. */
+    private channelId;
+    constructor();
+    isAvailable(): boolean;
+    /** Firebase-routed token (FCM) on both platforms — even on iOS (APNs-backed FCM). */
+    pushProvider(): PushProviderId;
+    requestPermission(): Promise<NotificationPermissionStatus>;
+    createAndroidChannel(channel: AndroidChannelConfig): Promise<void>;
+    getToken(): Promise<string | null>;
+    onTokenRefresh(cb: (token: string) => void): () => void;
+    onForegroundMessage(cb: (message: PushNotification) => void): () => void;
+    onNotificationOpened(cb: (message: PushNotification) => void): () => void;
+    getInitialNotification(): Promise<PushNotification | null>;
+    teardown(): void;
+}
+//# sourceMappingURL=RNFirebaseMessagingAdapter.d.ts.map

package/lib/typescript/push/adapters/loadMessaging.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Isolated lazy loader for the OPTIONAL `@react-native-firebase/messaging` dep.
+ *
+ * WHY ITS OWN FILE: Metro's dependency collector emits a dependency map one
+ * entry short for a module that contains TWO OR MORE different-string inline
+ * `require()` calls, so the require indices desync and `_dependencyMap[N]` reads
+ * `undefined` ("Requiring unknown module 'undefined'"). Keeping exactly ONE
+ * inline require per module avoids the miscount. `loadNotifee` lives in its own
+ * sibling file for the same reason.
+ *
+ * The string must still be STATICALLY resolvable at bundle time; hosts that don't
+ * install it must stub it in metro.config.js. See FIX_PUSH_UNKNOWN_MODULE.md.
+ */
+type AnyFn = (...args: any[]) => any;
+export declare function loadMessaging(): AnyFn | null;
+export {};
+//# sourceMappingURL=loadMessaging.d.ts.map