@scalebun-release/react-native 2.5.0

package/src/push/PushManager.ts

@@ -0,0 +1,318 @@
+/**
+ * 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 { Platform } from 'react-native';
+import { logger } from '../core/logger/internalLogger';
+import { emitAutomaticEvent } from '../analytics/automaticEvents';
+import { detectPushCapabilities } from './detect/capabilities';
+import { selectAdapter } from './adapters/selectAdapter';
+import { ManualAdapter } from './adapters/ManualAdapter';
+import type {
+    AdapterId,
+    EnablePushOptions,
+    EnablePushResult,
+    PushAdapter,
+    PushNotification,
+    PushProviderId,
+} from './types';
+
+const DEFAULT_CHANNEL_ID = 'scalebun_default';
+
+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 class PushManager {
+    private deps: PushManagerDeps;
+    private adapter: PushAdapter | null = null;
+    private token: string | null = null;
+    /** Last token value already sent to the backend, to drop redundant re-registrations. */
+    private lastSyncedToken: string | null = null;
+    private enabled = false;
+    private usable = false;
+    private reason = 'not enabled';
+    private permission: string | null = null;
+    private unsubscribers: Array<() => void> = [];
+
+    constructor(deps: PushManagerDeps) {
+        this.deps = deps;
+    }
+
+    public async enable(options: EnablePushOptions = {}): Promise<EnablePushResult> {
+        try {
+            if (this.enabled && this.adapter) {
+                return {
+                    ok: this.usable,
+                    adapter: this.adapter.id,
+                    reason: this.reason,
+                    permission: this.permission as any,
+                };
+            }
+
+            const caps = detectPushCapabilities(true);
+            const selection = selectAdapter(caps, options);
+            this.adapter = selection.adapter;
+            this.usable = selection.usable;
+            this.reason = selection.reason;
+            this.enabled = true;
+
+            if (!selection.usable) {
+                // Fail clear (requirement 8): keep the adapter (Noop) but report why.
+                logger.warn('[push] enablePush: no usable provider —', selection.reason);
+                return { ok: false, adapter: this.adapter.id, reason: this.reason };
+            }
+
+            __DEV__ && logger.info('[push] adapter:', this.adapter.id, '—', selection.reason);
+
+            // 1) Permission
+            if (!options.skipPermissionRequest) {
+                const before = this.permission;
+                this.permission = await this.adapter.requestPermission();
+                if (this.permission === 'denied') {
+                    logger.warn('[push] notification permission denied');
+                }
+                // Permission outcomes were STATE the SDK held and never an event, so the core mobile
+                // growth loop — "reached the paywall → was prompted → granted" — could not be built as a
+                // funnel. This is the one permission the SDK requests itself, so it is captured
+                // automatically; everything else (camera, location, photos) is the host's to report via
+                // `ScaleBun.trackPermission()`.
+                emitAutomaticEvent('permission_result', {
+                    permission: 'notifications',
+                    status: this.permission,
+                    // Distinguishes a first prompt from a re-check: only the first can change a mind.
+                    previous_status: before ?? undefined,
+                    prompted: true,
+                });
+            }
+
+            // 2) Android channel
+            if (Platform.OS === 'android') {
+                await this.adapter.createAndroidChannel(
+                    options.android ?? { channelId: DEFAULT_CHANNEL_ID, channelName: 'Notifications' },
+                );
+            }
+
+            // 3) Wire the automatic product-event collector independently of
+            // optional host callbacks. Notification text/body are intentionally
+            // excluded because they may contain personal data.
+            this.unsubscribers.push(
+                this.adapter.onForegroundMessage((message) => {
+                    this.captureNotification('push_received', message);
+                }),
+            );
+            this.unsubscribers.push(
+                this.adapter.onNotificationOpened((message) => {
+                    this.captureNotification('push_opened', message);
+                }),
+            );
+
+            // 4) Wire consumer callbacks
+            if (options.onForegroundNotification) {
+                this.unsubscribers.push(
+                    this.adapter.onForegroundMessage(options.onForegroundNotification),
+                );
+            }
+            if (options.onNotificationOpened) {
+                this.unsubscribers.push(
+                    this.adapter.onNotificationOpened(options.onNotificationOpened),
+                );
+            }
+
+            // Fetch the cold-start notification once for both automatic capture
+            // and the optional host callback.
+            this.adapter
+                .getInitialNotification()
+                .then((message) => {
+                    if (!message) return;
+                    this.captureNotification('push_opened', message, true);
+                    options.onNotificationOpened?.(message);
+                })
+                .catch(() => {});
+
+            // 5) Token acquisition + refresh → backend sync
+            this.unsubscribers.push(
+                this.adapter.onTokenRefresh((t) => {
+                    this.token = t;
+                    this.syncToken(t).catch(() => {});
+                }),
+            );
+
+            const initialToken = await this.adapter.getToken();
+            let tokenRegistered = false;
+            if (initialToken) {
+                this.token = initialToken;
+                const res = await this.syncToken(initialToken);
+                tokenRegistered = res !== false && res?.ok !== false;
+            } else {
+                logger.warn('[push] no token acquired yet (may arrive via onTokenRefresh)');
+            }
+
+            return {
+                ok: true,
+                adapter: this.adapter.id,
+                reason: this.reason,
+                permission: this.permission as any,
+                tokenRegistered,
+            };
+        } catch (err: any) {
+            logger.warn('[push] enablePush failed:', err?.message, err?.stack);
+            return {
+                ok: false,
+                adapter: this.adapter?.id ?? 'noop',
+                reason: `enablePush threw: ${err?.message ?? 'unknown error'}`,
+            };
+        }
+    }
+
+    private captureNotification(
+        type: 'push_received' | 'push_opened',
+        message: PushNotification,
+        coldStart = false,
+    ): void {
+        emitAutomaticEvent(type, {
+            message_id: message.messageId,
+            campaign_id:
+                message.data.scalebunCampaignId ??
+                message.data.campaignId ??
+                message.data.campaign_id,
+            sent_time: message.sentTime,
+            cold_start: coldStart || undefined,
+        });
+    }
+
+    /**
+     * 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 async syncToken(token: string, force = false): Promise<any> {
+        if (!force && token === this.lastSyncedToken) {
+            __DEV__ && logger.debug('[push] token unchanged since last registration — skipping');
+            return { ok: true, skipped: true };
+        }
+        const platform = Platform.OS === 'ios' ? 'ios' : 'android';
+        // The active adapter decides the provider: direct-APNs (raw APNs token on
+        // iOS) → 'apns'; Firebase-routed (FCM) → 'fcm'. Default by platform when no
+        // adapter is set (manual setToken before enable).
+        const pushProvider: PushProviderId =
+            this.adapter?.pushProvider() ?? (platform === 'ios' ? 'apns' : 'fcm');
+        __DEV__ && logger.debug(`[push] registering device token with backend (provider=${pushProvider})`);
+        const res = await this.deps.registerToken({ pushToken: token, platform, pushProvider, tokenStatus: 'active' });
+        this.lastSyncedToken = token;
+        return res;
+    }
+
+    // ─── Manual-provider host inputs ────────────────────────────────────
+
+    public setToken(token: string): void {
+        this.token = token;
+        if (this.adapter instanceof ManualAdapter) {
+            this.adapter.setToken(token); // fires onTokenRefresh → syncToken
+        } else {
+            this.syncToken(token).catch(() => {});
+        }
+    }
+
+    public emitForeground(message: PushNotification): void {
+        if (this.adapter instanceof ManualAdapter) this.adapter.emitForeground(message);
+    }
+
+    public emitNotificationOpened(message: PushNotification): void {
+        if (this.adapter instanceof ManualAdapter) this.adapter.emitNotificationOpened(message);
+    }
+
+    public getToken(): string | null {
+        return this.token;
+    }
+
+    /**
+     * 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.
+     */
+    public resyncToken(): void {
+        if (this.token) this.syncToken(this.token, true).catch(() => {});
+    }
+
+    // ─── Late subscription (thin facade API) ────────────────────────────
+    // Attach a notification listener AFTER enablePush (in addition to the
+    // enablePush({ onForegroundNotification, onNotificationOpened }) options).
+    // No-op (returns an inert unsubscribe) until an adapter is selected.
+
+    public onForegroundNotification(cb: (message: PushNotification) => void): () => void {
+        if (!this.adapter) return () => {};
+        const unsub = this.adapter.onForegroundMessage(cb);
+        this.unsubscribers.push(unsub);
+        return unsub;
+    }
+
+    public onNotificationOpened(cb: (message: PushNotification) => void): () => void {
+        if (!this.adapter) return () => {};
+        const unsub = this.adapter.onNotificationOpened(cb);
+        this.unsubscribers.push(unsub);
+        // Also deliver the cold-start notification, once available.
+        this.adapter
+            .getInitialNotification()
+            .then((n) => {
+                if (n) cb(n);
+            })
+            .catch(() => {});
+        return unsub;
+    }
+
+    public status(): PushStatus {
+        return {
+            enabled: this.enabled,
+            adapter: this.adapter?.id ?? null,
+            usable: this.usable,
+            reason: this.reason,
+            token: this.token,
+            permission: this.permission,
+        };
+    }
+
+    public teardown(): void {
+        for (const unsub of this.unsubscribers) {
+            try {
+                unsub();
+            } catch {
+                // ignore
+            }
+        }
+        this.unsubscribers = [];
+        this.adapter?.teardown();
+        this.adapter = null;
+        this.enabled = false;
+        this.usable = false;
+        this.token = null;
+        this.lastSyncedToken = null;
+    }
+}

package/src/push/adapters/ManualAdapter.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 { Platform } from 'react-native';
+import type {
+    AndroidChannelConfig,
+    NotificationPermissionStatus,
+    PushAdapter,
+    PushNotification,
+    PushProviderId,
+} from '../types';
+
+export class ManualAdapter implements PushAdapter {
+    public readonly id = 'manual' as const;
+    private token: string | null;
+    private provider?: PushProviderId;
+    private refreshListeners = new Set<(token: string) => void>();
+    private foregroundListeners = new Set<(m: PushNotification) => void>();
+    private openedListeners = new Set<(m: PushNotification) => void>();
+
+    constructor(initialToken?: string | null, provider?: PushProviderId) {
+        this.token = initialToken ?? null;
+        this.provider = provider;
+    }
+
+    public isAvailable(): boolean {
+        return true;
+    }
+
+    /**
+     * 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'.
+     */
+    public pushProvider(): PushProviderId {
+        return this.provider ?? (Platform.OS === 'ios' ? 'apns' : 'fcm');
+    }
+
+    public async requestPermission(): Promise<NotificationPermissionStatus> {
+        // The host app owns permission in manual mode.
+        return 'granted';
+    }
+
+    public async createAndroidChannel(_channel: AndroidChannelConfig): Promise<void> {
+        // Host app owns channel creation in manual mode.
+    }
+
+    public async getToken(): Promise<string | null> {
+        return this.token;
+    }
+
+    public onTokenRefresh(cb: (token: string) => void): () => void {
+        this.refreshListeners.add(cb);
+        return () => this.refreshListeners.delete(cb);
+    }
+
+    public onForegroundMessage(cb: (message: PushNotification) => void): () => void {
+        this.foregroundListeners.add(cb);
+        return () => this.foregroundListeners.delete(cb);
+    }
+
+    public onNotificationOpened(cb: (message: PushNotification) => void): () => void {
+        this.openedListeners.add(cb);
+        return () => this.openedListeners.delete(cb);
+    }
+
+    public async getInitialNotification(): Promise<PushNotification | null> {
+        return null;
+    }
+
+    public teardown(): void {
+        this.refreshListeners.clear();
+        this.foregroundListeners.clear();
+        this.openedListeners.clear();
+    }
+
+    // ─── Host-driven inputs (forwarded by ScaleBun.push.*) ──────────────
+
+    public setToken(token: string): void {
+        this.token = token;
+        for (const cb of this.refreshListeners) cb(token);
+    }
+
+    public emitForeground(message: PushNotification): void {
+        for (const cb of this.foregroundListeners) cb(message);
+    }
+
+    public emitNotificationOpened(message: PushNotification): void {
+        for (const cb of this.openedListeners) cb(message);
+    }
+}

package/src/push/adapters/NativeBridgeAdapter.ts

@@ -0,0 +1,142 @@
+/**
+ * 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 { Platform, PermissionsAndroid } from 'react-native';
+import { logger } from '../../core/logger/internalLogger';
+import {
+    getNativePushToken,
+    subscribeNativePushTokenRefresh,
+} from '../../features/engage/engagePushTokenBridge';
+import {
+    requestNativePushPermission,
+    subscribeNativeForegroundNotification,
+    subscribeNativeNotificationOpened,
+    consumeInitialNativeNotificationFull,
+} from '../native/nativeNotifications';
+import type {
+    AndroidChannelConfig,
+    NotificationPermissionStatus,
+    PushAdapter,
+    PushNotification,
+    PushProviderId,
+} from '../types';
+
+export class NativeBridgeAdapter implements PushAdapter {
+    public readonly id = 'native' as const;
+    private available: boolean;
+    private unsubscribers: Array<() => void> = [];
+
+    constructor(available: boolean) {
+        this.available = available;
+    }
+
+    public isAvailable(): boolean {
+        return this.available;
+    }
+
+    /** Direct APNs (raw APNs token) on iOS; reflective FCM token on Android. */
+    public pushProvider(): PushProviderId {
+        return Platform.OS === 'ios' ? 'apns' : 'fcm';
+    }
+
+    public async requestPermission(): Promise<NotificationPermissionStatus> {
+        try {
+            if (Platform.OS === 'android') {
+                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 — request authorization natively via UNUserNotificationCenter.
+            const status = await requestNativePushPermission();
+            if (status === 'granted' || status === 'provisional' || status === 'denied') {
+                return status;
+            }
+            // Native delegate unavailable (older native build): registration still
+            // proceeds; report unavailable rather than a false 'granted'.
+            return 'unavailable';
+        } catch (err: any) {
+            logger.warn('[push] native requestPermission failed:', err?.message);
+            return 'denied';
+        }
+    }
+
+    public async createAndroidChannel(_channel: AndroidChannelConfig): Promise<void> {
+        // The native bridge has no JS channel API; FCM uses the manifest-declared
+        // fallback channel (default_notification_channel_id). No-op on iOS.
+        __DEV__ && logger.debug('[push] native adapter relies on FCM fallback channel');
+    }
+
+    public async getToken(): Promise<string | null> {
+        const t = await getNativePushToken();
+        return t?.token ?? null;
+    }
+
+    public onTokenRefresh(cb: (token: string) => void): () => void {
+        const unsub = subscribeNativePushTokenRefresh((t) => {
+            if (t?.token) cb(t.token);
+        });
+        this.unsubscribers.push(unsub);
+        return unsub;
+    }
+
+    public onForegroundMessage(cb: (message: PushNotification) => void): () => void {
+        // iOS: native UNUserNotificationCenter willPresent. Android: inert (the OS
+        // renders the tray and the native bridge is token-only there).
+        if (Platform.OS !== 'ios') return () => {};
+        const unsub = subscribeNativeForegroundNotification((note) => {
+            cb({ title: note.title, body: note.body, data: note.data ?? {} });
+        });
+        this.unsubscribers.push(unsub);
+        return unsub;
+    }
+
+    public onNotificationOpened(cb: (message: PushNotification) => void): () => void {
+        // iOS: native UNUserNotificationCenter didReceive (tap). Same event name as
+        // Android so the payload shape matches ({ data }). Inert on Android here.
+        if (Platform.OS !== 'ios') return () => {};
+        const unsub = subscribeNativeNotificationOpened((data) => {
+            cb({ data });
+        });
+        this.unsubscribers.push(unsub);
+        return unsub;
+    }
+
+    public async getInitialNotification(): Promise<PushNotification | null> {
+        if (Platform.OS !== 'ios') return null;
+        const note = await consumeInitialNativeNotificationFull();
+        if (!note) return null;
+        return { title: note.title, body: note.body, data: note.data ?? {} };
+    }
+
+    public teardown(): void {
+        for (const unsub of this.unsubscribers) {
+            try {
+                unsub();
+            } catch {
+                // ignore
+            }
+        }
+        this.unsubscribers = [];
+    }
+}

package/src/push/adapters/NoopAdapter.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 { Platform } from 'react-native';
+import type {
+    AndroidChannelConfig,
+    NotificationPermissionStatus,
+    PushAdapter,
+    PushNotification,
+    PushProviderId,
+} from '../types';
+
+export class NoopAdapter implements PushAdapter {
+    public readonly id = 'noop' as const;
+
+    public isAvailable(): boolean {
+        return false;
+    }
+    public pushProvider(): PushProviderId {
+        return Platform.OS === 'ios' ? 'apns' : 'fcm';
+    }
+    public async requestPermission(): Promise<NotificationPermissionStatus> {
+        return 'unavailable';
+    }
+    public async createAndroidChannel(_channel: AndroidChannelConfig): Promise<void> {}
+    public async getToken(): Promise<string | null> {
+        return null;
+    }
+    public onTokenRefresh(_cb: (token: string) => void): () => void {
+        return () => {};
+    }
+    public onForegroundMessage(_cb: (message: PushNotification) => void): () => void {
+        return () => {};
+    }
+    public onNotificationOpened(_cb: (message: PushNotification) => void): () => void {
+        return () => {};
+    }
+    public async getInitialNotification(): Promise<PushNotification | null> {
+        return null;
+    }
+    public teardown(): void {}
+}