@scalebun-release/react-native 2.5.0

package/lib/module/push/adapters/RNFirebaseMessagingAdapter.js

@@ -0,0 +1,241 @@
+/**
+ * @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 { Platform, PermissionsAndroid } from 'react-native';
+import { ensureNativeChannel, showNativeNotification, subscribeNativeNotificationOpened, consumeInitialNativeNotification, hasNativeNotificationSupport } from '../native/nativeNotifications';
+import { loadMessaging } from './loadMessaging';
+import { loadNotifee } from './loadNotifee';
+// NOTE: this adapter intentionally does NOT import the SDK's internalLogger and
+// keeps NO inline require() of its own — each optional-dep require lives in its
+// own single-require module (`./loadMessaging`, `./loadNotifee`). Two inline
+// require()s in ONE module makes Metro's dependency collector emit a dependency
+// map one entry short, desyncing the require indices so `_dependencyMap[N]` reads
+// `undefined` → "Requiring unknown module 'undefined'" (and the cascading
+// "Cannot read property 'logger' of undefined"). One require per module keeps each
+// dependency map in sync. Logging stays on `console` (error-path only); the rest
+// of the SDK keeps using internalLogger for level control.
+const log = {
+  debug: (...args) => console.debug('[ScaleBun:Debug]', ...args),
+  warn: (...args) => console.warn('[ScaleBun:Warn]', ...args)
+};
+function toPushNotification(remoteMessage) {
+  const rawData = remoteMessage?.data ?? {};
+  const data = {};
+  for (const k of Object.keys(rawData)) {
+    const v = rawData[k];
+    data[k] = typeof v === 'string' ? v : JSON.stringify(v);
+  }
+  return {
+    messageId: remoteMessage?.messageId,
+    title: remoteMessage?.notification?.title,
+    body: remoteMessage?.notification?.body,
+    data,
+    sentTime: typeof remoteMessage?.sentTime === 'number' ? remoteMessage.sentTime : undefined
+  };
+}
+export class RNFirebaseMessagingAdapter {
+  id = 'rnfirebase';
+  unsubscribers = [];
+  /** Channel id last created — foreground native display posts onto it. */
+  channelId = 'scalebun_default';
+  constructor() {
+    this.messaging = loadMessaging();
+  }
+  isAvailable() {
+    return this.messaging != null;
+  }
+
+  /** Firebase-routed token (FCM) on both platforms — even on iOS (APNs-backed FCM). */
+  pushProvider() {
+    return 'fcm';
+  }
+  async requestPermission() {
+    try {
+      if (Platform.OS === 'android') {
+        // Android 13+ (API 33) requires the runtime POST_NOTIFICATIONS grant.
+        const apiLevel = typeof Platform.Version === 'number' ? Platform.Version : 0;
+        if (apiLevel >= 33) {
+          const res = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS);
+          return res === PermissionsAndroid.RESULTS.GRANTED ? 'granted' : 'denied';
+        }
+        return 'granted';
+      }
+
+      // iOS — delegate to FCM/APNs.
+      if (!this.messaging) return 'unavailable';
+      const authStatus = await this.messaging().requestPermission();
+      // messaging.AuthorizationStatus: NOT_DETERMINED=-1, DENIED=0, AUTHORIZED=1, PROVISIONAL=2
+      if (authStatus === 1) return 'granted';
+      if (authStatus === 2) return 'provisional';
+      return 'denied';
+    } catch (err) {
+      log.warn('[push] requestPermission failed:', err?.message);
+      return 'denied';
+    }
+  }
+  async createAndroidChannel(channel) {
+    // Native-first: create the channel via the SDK's native presenter
+    // (framework NotificationManager). Notifee is NOT required. Fail-soft to
+    // FCM's manifest-declared fallback channel when native is unavailable.
+    try {
+      if (Platform.OS !== 'android') return;
+      this.channelId = channel.channelId;
+      const createdNatively = await ensureNativeChannel({
+        channelId: channel.channelId,
+        channelName: channel.channelName ?? channel.channelId,
+        importance: channel.importance ?? 4,
+        description: channel.description
+      });
+      if (createdNatively) {
+        log.debug('[push] native channel created:', channel.channelId);
+        return;
+      }
+
+      // Optional adapter fallback (NOT a core dependency): if the host app
+      // happens to ship @notifee/react-native, use it; otherwise FCM uses the
+      // manifest-declared fallback channel.
+      const notifee = loadNotifee();
+      if (notifee?.createChannel) {
+        await notifee.createChannel({
+          id: channel.channelId,
+          name: channel.channelName ?? channel.channelId,
+          importance: channel.importance ?? 4,
+          description: channel.description
+        });
+        return;
+      }
+      log.debug('[push] no native/notifee channel; relying on FCM fallback channel');
+    } catch (err) {
+      log.warn('[push] createAndroidChannel failed (FCM fallback channel will be used):', err?.message);
+    }
+  }
+  async getToken() {
+    if (!this.messaging) return null;
+    try {
+      if (Platform.OS === 'ios') {
+        // APNs token must be registered before FCM token on iOS.
+        await this.messaging().registerDeviceForRemoteMessages?.();
+      }
+      const token = await this.messaging().getToken();
+      return token ? String(token) : null;
+    } catch (err) {
+      log.warn('[push] getToken failed:', err?.message);
+      return null;
+    }
+  }
+  onTokenRefresh(cb) {
+    if (!this.messaging) return () => {};
+    try {
+      const unsub = this.messaging().onTokenRefresh(token => cb(String(token)));
+      this.unsubscribers.push(unsub);
+      return unsub;
+    } catch (err) {
+      log.warn('[push] onTokenRefresh failed:', err?.message);
+      return () => {};
+    }
+  }
+  onForegroundMessage(cb) {
+    if (!this.messaging) return () => {};
+    try {
+      const unsub = this.messaging().onMessage(rm => {
+        const note = toPushNotification(rm);
+        // Native-first foreground DISPLAY: while the app is foreground the OS
+        // suppresses the FCM tray notification, so render it ourselves via the
+        // native presenter (no Notifee). Fail-soft — delivery to `cb` is
+        // unaffected if display is unavailable.
+        if (Platform.OS === 'android' && hasNativeNotificationSupport()) {
+          void showNativeNotification({
+            title: note.title,
+            body: note.body,
+            channelId: this.channelId,
+            data: note.data
+          });
+        }
+        cb(note);
+      });
+      this.unsubscribers.push(unsub);
+      return unsub;
+    } catch (err) {
+      log.warn('[push] onForegroundMessage failed:', err?.message);
+      return () => {};
+    }
+  }
+  onNotificationOpened(cb) {
+    const unsubs = [];
+
+    // Background-tray taps: the OS rendered the FCM notification; RNFirebase
+    // surfaces the open event.
+    if (this.messaging) {
+      try {
+        const unsub = this.messaging().onNotificationOpenedApp(rm => cb(toPushNotification(rm)));
+        unsubs.push(unsub);
+      } catch (err) {
+        log.warn('[push] onNotificationOpened (fcm) failed:', err?.message);
+      }
+    }
+
+    // Foreground/native-rendered taps: our native presenter posted the
+    // notification; the native module emits the open (with data) on tap.
+    const nativeUnsub = subscribeNativeNotificationOpened(data => {
+      cb({
+        data
+      });
+    });
+    unsubs.push(nativeUnsub);
+    const teardown = () => {
+      for (const u of unsubs) {
+        try {
+          u();
+        } catch {
+          // ignore
+        }
+      }
+    };
+    this.unsubscribers.push(teardown);
+    return teardown;
+  }
+  async getInitialNotification() {
+    // Cold start from a background-tray tap (RNFirebase) takes precedence; fall
+    // back to a native-rendered notification tap (consumed once).
+    try {
+      if (this.messaging) {
+        const rm = await this.messaging().getInitialNotification();
+        if (rm) return toPushNotification(rm);
+      }
+    } catch (err) {
+      log.warn('[push] getInitialNotification (fcm) failed:', err?.message);
+    }
+    const nativeData = await consumeInitialNativeNotification();
+    if (nativeData) return {
+      data: nativeData
+    };
+    return null;
+  }
+  teardown() {
+    for (const unsub of this.unsubscribers) {
+      try {
+        unsub();
+      } catch {
+        // ignore
+      }
+    }
+    this.unsubscribers = [];
+  }
+}
+//# sourceMappingURL=RNFirebaseMessagingAdapter.js.map

package/lib/module/push/adapters/loadMessaging.js

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+
+export function loadMessaging() {
+  try {
+    const mod = require('@react-native-firebase/messaging');
+    return mod?.default ?? mod;
+  } catch {
+    return null;
+  }
+}
+//# sourceMappingURL=loadMessaging.js.map

package/lib/module/push/adapters/loadNotifee.js

@@ -0,0 +1,30 @@
+/**
+ * Isolated lazy loader for the OPTIONAL `@notifee/react-native` 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. `loadMessaging` 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.
+ */
+
+export function loadNotifee() {
+  try {
+    const mod = require('@notifee/react-native');
+    const notifee = mod?.default ?? mod;
+    // Validate the real Notifee API rather than mere truthiness: when Notifee is
+    // absent, `withScaleBun` resolves it to an empty stub module, so require the
+    // channel API this adapter actually uses before treating it as available.
+    if (typeof notifee?.createChannel === 'function') {
+      return notifee;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+//# sourceMappingURL=loadNotifee.js.map

package/lib/module/push/adapters/selectAdapter.js

@@ -0,0 +1,147 @@
+/**
+ * Smart adapter selection (requirements 3 & 4).
+ *
+ * Given probed capabilities, pick the safest supported compatibility path. Two
+ * real token sources exist:
+ *   1. RNFirebase JS (@react-native-firebase/messaging) — full feature set
+ *      (token + foreground/opened callbacks), but the JS layer reads native
+ *      modules in a way that needs v18+ under the New Architecture/bridgeless.
+ *   2. The ScaleBunEngage native bridge — acquires the token by reflecting into
+ *      Firebase in NATIVE code, so it works under bridgeless regardless of the
+ *      installed RNFirebase version. Token-only (no message callbacks).
+ *
+ * Auto priority: RNFirebase when usable → native bridge (rescues the cases where
+ * RNFirebase is absent/incompatible) → manual → noop (fail-clear, actionable).
+ */
+
+import { RNFirebaseMessagingAdapter } from './RNFirebaseMessagingAdapter';
+import { NativeBridgeAdapter } from './NativeBridgeAdapter';
+import { ManualAdapter } from './ManualAdapter';
+import { NoopAdapter } from './NoopAdapter';
+
+/** First RNFirebase major with working New Architecture / bridgeless support. */
+export const MIN_BRIDGELESS_RNFIREBASE_MAJOR = 18;
+
+/** Whether the RNFirebase JS adapter is usable for the current runtime. */
+function rnFirebaseUsable(caps) {
+  if (!caps.hasRNFirebaseMessaging) return false;
+  if (!caps.isBridgeless) return true; // legacy bridge: any installed major works
+  // Bridgeless: needs v18+. Unknown version → optimistic (doctor verifies).
+  if (caps.rnFirebaseMajor == null) return true;
+  return caps.rnFirebaseMajor >= MIN_BRIDGELESS_RNFIREBASE_MAJOR;
+}
+export function selectAdapter(caps, options = {}) {
+  const provider = options.provider ?? 'auto';
+
+  // ─── Explicit manual override ───────────────────────────────────────
+  if (provider === 'manual') {
+    return {
+      adapter: new ManualAdapter(options.manualToken ?? null),
+      usable: true,
+      reason: 'Manual provider selected: host app supplies the push token.'
+    };
+  }
+
+  // ─── Explicit native override ───────────────────────────────────────
+  if (provider === 'native') {
+    if (caps.hasNativeEngageBridge) {
+      return {
+        adapter: new NativeBridgeAdapter(true),
+        usable: true,
+        reason: "provider:'native' forced — ScaleBunEngage native token bridge."
+      };
+    }
+    return {
+      adapter: new NoopAdapter(),
+      usable: false,
+      reason: "provider:'native' was forced but the ScaleBunEngage native module is not linked. " + 'Rebuild the app with the ScaleBun native module, or use provider:"manual".'
+    };
+  }
+
+  // ─── Explicit RNFirebase override ───────────────────────────────────
+  if (provider === 'rnfirebase') {
+    const adapter = new RNFirebaseMessagingAdapter();
+    if (!adapter.isAvailable()) {
+      return {
+        adapter: new NoopAdapter(),
+        usable: false,
+        reason: "provider:'rnfirebase' was forced but @react-native-firebase/messaging is not installed. " + 'Install it, or use provider:"manual".'
+      };
+    }
+    return {
+      adapter,
+      usable: true,
+      reason: "provider:'rnfirebase' forced."
+    };
+  }
+
+  // ─── Auto on iOS: prefer native Direct APNs ─────────────────────────
+  // iOS registers the raw APNs device token (pushProvider:'apns') through the
+  // ScaleBunEngage native bridge — no Firebase required. This is the default
+  // onboarding path once `npx scalebun init ios` has wired the AppDelegate
+  // forwarding hooks. Selected ahead of RNFirebase so a customer app that
+  // happens to ship @react-native-firebase (e.g. for Analytics) still gets
+  // Direct APNs on iOS without passing provider:'native'. An app that
+  // deliberately wants iOS-over-FCM uses the advanced provider:'rnfirebase'
+  // override. Android falls through to the RNFirebase/FCM path below.
+  if (caps.platform === 'ios' && caps.hasNativeEngageBridge) {
+    return {
+      adapter: new NativeBridgeAdapter(true),
+      usable: true,
+      reason: 'iOS Direct APNs via the ScaleBunEngage native bridge (raw APNs token, ' + 'pushProvider:apns). No Firebase required. Run `npx scalebun init ios` to ' + 'wire the AppDelegate forwarding hooks if push tokens never arrive.'
+    };
+  }
+
+  // ─── Auto: prefer RNFirebase (full callbacks) when usable ───────────
+  if (rnFirebaseUsable(caps)) {
+    const adapter = new RNFirebaseMessagingAdapter();
+    if (!caps.isBridgeless) {
+      return {
+        adapter,
+        usable: true,
+        reason: `RNFirebase adapter selected (legacy bridge${caps.rnFirebaseVersion ? `, v${caps.rnFirebaseVersion}` : ''}).`
+      };
+    }
+    if (caps.rnFirebaseMajor == null) {
+      return {
+        adapter,
+        usable: true,
+        reason: 'RNFirebase adapter selected for bridgeless, but its version could not be ' + `verified at runtime. Ensure @react-native-firebase >= ${MIN_BRIDGELESS_RNFIREBASE_MAJOR}. ` + 'Run `npx scalebun doctor` to confirm.'
+      };
+    }
+    return {
+      adapter,
+      usable: true,
+      reason: `RNFirebase adapter selected (New Architecture/bridgeless, v${caps.rnFirebaseVersion}).`
+    };
+  }
+
+  // ─── Auto: native ScaleBunEngage bridge rescues otherwise-noop cases ─────
+  // Covers: RNFirebase < 18 under bridgeless, or no RNFirebase JS at all, as
+  // long as the native module + native Firebase are present. Token-only.
+  if (caps.hasNativeEngageBridge) {
+    const why = caps.hasRNFirebaseMessaging ? `@react-native-firebase v${caps.rnFirebaseVersion ?? '?'} is incompatible with the ` + `New Architecture/bridgeless runtime (RN ${caps.rnVersion ?? 'unknown'}), so the ` + 'ScaleBunEngage native token bridge was selected' : 'No RNFirebase JS detected — the ScaleBunEngage native token bridge was selected';
+    return {
+      adapter: new NativeBridgeAdapter(true),
+      usable: true,
+      reason: `${why}. Token registration works; foreground/opened message callbacks require ` + `@react-native-firebase >= ${MIN_BRIDGELESS_RNFIREBASE_MAJOR} (e.g. v21).`
+    };
+  }
+
+  // ─── RNFirebase present but incompatible, no native rescue ──────────
+  if (caps.hasRNFirebaseMessaging) {
+    return {
+      adapter: new NoopAdapter(),
+      usable: false,
+      reason: `@react-native-firebase v${caps.rnFirebaseVersion} is incompatible with the New ` + `Architecture/bridgeless runtime (RN ${caps.rnVersion ?? 'unknown'}). ` + `Upgrade @react-native-firebase to >= ${MIN_BRIDGELESS_RNFIREBASE_MAJOR} (e.g. v21), ` + 'or use provider:"manual" with your own token.'
+    };
+  }
+
+  // ─── No provider at all ─────────────────────────────────────────────
+  return {
+    adapter: new NoopAdapter(),
+    usable: false,
+    reason: 'No push provider detected. Install @react-native-firebase/messaging ' + `(>= ${MIN_BRIDGELESS_RNFIREBASE_MAJOR} for the New Architecture), link the ScaleBun ` + 'native module, or call enablePush({ provider:"manual", manualToken }) with your own token.'
+  };
+}
+//# sourceMappingURL=selectAdapter.js.map

package/lib/module/push/detect/capabilities.js

@@ -0,0 +1,130 @@
+/**
+ * Runtime capability detection (requirement 4).
+ *
+ * Probes the live JS runtime — RN version, New Architecture / bridgeless mode,
+ * whether @react-native-firebase/messaging is installed & at what version, and
+ * whether the ScaleBunEngage native token bridge is linked — so the selector can
+ * choose the safest supported adapter automatically.
+ *
+ * All probes are defensive: anything unknown degrades to a conservative default
+ * rather than throwing. Build-time concerns (config files on disk, manifest
+ * permissions) live in the doctor CLI, not here.
+ */
+
+import { Platform, NativeModules } from 'react-native';
+function detectPlatform() {
+  if (Platform.OS === 'android') return 'android';
+  if (Platform.OS === 'ios') return 'ios';
+  return 'unknown';
+}
+function detectRnVersion() {
+  try {
+    // Populated by RN core on both old and new architecture.
+    const v = Platform?.constants?.reactNativeVersion;
+    if (v && typeof v.major === 'number') {
+      const parts = {
+        major: v.major,
+        minor: v.minor ?? 0,
+        patch: v.patch ?? 0
+      };
+      return {
+        version: `${parts.major}.${parts.minor}.${parts.patch}`,
+        parts
+      };
+    }
+  } catch {
+    // fall through
+  }
+  return {
+    version: null,
+    parts: null
+  };
+}
+
+/**
+ * Bridgeless is the RN 0.74+ flavour of the New Architecture. The core sets
+ * `global.RN$Bridgeless = true` when running bridgeless. TurboModules (new arch
+ * without bridgeless) expose `global.__turboModuleProxy`.
+ */
+function detectArchitecture() {
+  const g = globalThis;
+  const isBridgeless = g?.RN$Bridgeless === true;
+  const hasTurboModules = g?.__turboModuleProxy != null || typeof g?.RN$TurboInterop !== 'undefined';
+  const fabricEnabled = g?.nativeFabricUIManager != null;
+  return {
+    isBridgeless,
+    isNewArchitecture: isBridgeless || hasTurboModules || fabricEnabled
+  };
+}
+function detectRNFirebase() {
+  let present = false;
+  try {
+    // Presence: the messaging module resolves at runtime.
+    require('@react-native-firebase/messaging');
+    present = true;
+  } catch {
+    return {
+      present: false,
+      version: null,
+      major: null
+    };
+  }
+
+  // Best-effort version (Node/Metro may not bundle package.json). The doctor
+  // CLI reads this reliably from node_modules; here it's advisory only.
+  let version = null;
+  try {
+    const pkg = require('@react-native-firebase/app/package.json');
+    if (pkg?.version) version = String(pkg.version);
+  } catch {
+    try {
+      const pkg = require('@react-native-firebase/messaging/package.json');
+      if (pkg?.version) version = String(pkg.version);
+    } catch {
+      // version stays null; presence still true
+    }
+  }
+  const major = version ? parseInt(version.split('.')[0], 10) : null;
+  return {
+    present,
+    version,
+    major: Number.isFinite(major) ? major : null
+  };
+}
+
+/**
+ * The ScaleBunEngage native module (Android Kotlin / iOS Swift) exposes a reflective
+ * FCM/APNs token bridge that works under bridgeless regardless of the installed
+ * @react-native-firebase JS version. Presence == the native module is linked.
+ */
+function detectNativeEngageBridge() {
+  try {
+    const mod = NativeModules?.ScaleBunEngage;
+    return mod != null && typeof mod.getPushToken === 'function';
+  } catch {
+    return false;
+  }
+}
+let cached = null;
+export function detectPushCapabilities(force = false) {
+  if (cached && !force) return cached;
+  const {
+    version,
+    parts
+  } = detectRnVersion();
+  const arch = detectArchitecture();
+  const fb = detectRNFirebase();
+  cached = {
+    platform: detectPlatform(),
+    rnVersion: version,
+    rnVersionParts: parts,
+    isNewArchitecture: arch.isNewArchitecture,
+    isBridgeless: arch.isBridgeless,
+    hasRNFirebaseMessaging: fb.present,
+    rnFirebaseVersion: fb.version,
+    rnFirebaseMajor: fb.major,
+    hasNativeEngageBridge: detectNativeEngageBridge()
+  };
+  return cached;
+}
+//# sourceMappingURL=capabilities.js.map

package/lib/module/push/index.js

@@ -0,0 +1,9 @@
+/**
+ * Push subsystem — internal barrel. Consumer-facing surface is exposed through
+ * the ScaleBun facade (ScaleBun.enablePush / ScaleBun.push.*), not this file.
+ */
+
+export { PushManager } from './PushManager';
+export { detectPushCapabilities } from './detect/capabilities';
+export { selectAdapter, MIN_BRIDGELESS_RNFIREBASE_MAJOR } from './adapters/selectAdapter';
+//# sourceMappingURL=index.js.map