appambit-push-notifications 0.3.0 → 1.0.0

package/android/src/main/java/com/appambitpushnotifications/AppAmbitHeadlessService.kt

@@ -0,0 +1,177 @@
+package com.appambitpushnotifications
+
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+import com.appambit.sdk.models.AppAmbitNotification
+import com.facebook.react.HeadlessJsTaskService
+import com.facebook.react.ReactApplication
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.jstasks.HeadlessJsTaskConfig
+
+class AppAmbitHeadlessService : HeadlessJsTaskService() {
+
+    companion object {
+        private const val TAG = "AppAmbitHeadless"
+
+        const val HEADLESS_TASK_NAME = "AppAmbitBackgroundNotification"
+
+        // Intent extras
+        private const val EXTRA_TITLE              = "aa_title"
+        private const val EXTRA_BODY               = "aa_body"
+        private const val EXTRA_IMAGE_URL          = "aa_image_url"
+        private const val EXTRA_ANDROID_COLOR      = "aa_android_color"
+        private const val EXTRA_ANDROID_ICON       = "aa_android_small_icon"
+        private const val EXTRA_ANDROID_TICKER     = "aa_android_ticker"
+        private const val EXTRA_ANDROID_STICKY     = "aa_android_sticky"
+        private const val EXTRA_ANDROID_VISIBILITY = "aa_android_visibility"
+        private const val EXTRA_ANDROID_CHANNEL_ID = "aa_android_channel_id"
+        private const val EXTRA_ANDROID_TAG        = "aa_android_tag"
+        private const val EXTRA_ANDROID_SOUND      = "aa_android_sound"
+        private const val EXTRA_ANDROID_CLICK_ACTION = "aa_android_click_action"
+        private const val EXTRA_DATA_KEYS          = "aa_data_keys"
+        private const val EXTRA_DATA_VALS          = "aa_data_vals"
+
+        private const val TASK_TIMEOUT_MS = 30_000L
+
+        fun enqueueNotification(context: Context, notification: AppAmbitNotification) {
+            Log.d(TAG, "Enqueueing headless task for: ${notification.title}")
+            HeadlessJsTaskService.acquireWakeLockNow(context)
+            val intent = buildIntent(context, notification)
+            try {
+                context.startService(intent)
+            } catch (e: Exception) {
+                Log.e(TAG, "Could not start HeadlessService", e)
+            }
+        }
+
+        private fun buildIntent(context: Context, notification: AppAmbitNotification): Intent {
+            val data   = notification.data
+            val intent = Intent(context, AppAmbitHeadlessService::class.java)
+
+            intent.putExtra(EXTRA_TITLE,         notification.title)
+            intent.putExtra(EXTRA_BODY,          notification.body)
+            intent.putExtra(EXTRA_ANDROID_COLOR, notification.color)
+            intent.putExtra(EXTRA_ANDROID_ICON,  notification.smallIconName)
+
+            val imageUrl = notification.imageUrl
+                ?: data["_aa_image_url"]
+                ?: data["image_url"]
+                ?: data["image"]
+            intent.putExtra(EXTRA_IMAGE_URL, imageUrl)
+
+            intent.putExtra(EXTRA_ANDROID_TICKER,       data["_aa_ticker"]       ?: data["ticker"])
+            intent.putExtra(EXTRA_ANDROID_VISIBILITY,   data["_aa_visibility"]   ?: data["visibility"])
+            intent.putExtra(EXTRA_ANDROID_CHANNEL_ID,   data["_aa_channel_id"]   ?: data["channelId"] ?: data["channel_id"])
+            intent.putExtra(EXTRA_ANDROID_TAG,          data["_aa_tag"]          ?: data["tag"])
+            intent.putExtra(EXTRA_ANDROID_SOUND,        data["_aa_sound"]        ?: data["sound"])
+            intent.putExtra(EXTRA_ANDROID_CLICK_ACTION, data["_aa_click_action"] ?: data["clickAction"] ?: data["click_action"])
+
+            val stickyStr = data["_aa_sticky"] ?: data["sticky"]
+            if (stickyStr != null) {
+                intent.putExtra(EXTRA_ANDROID_STICKY, stickyStr.equals("true", ignoreCase = true) || stickyStr == "1")
+            }
+
+            val filteredData = data.filterKeys { it !in AppAmbitPayloadUtils.INTERNAL_KEYS }
+            if (filteredData.isNotEmpty()) {
+                val keys   = filteredData.keys.toTypedArray()
+                val values = keys.map { filteredData[it] }.toTypedArray()
+                intent.putExtra(EXTRA_DATA_KEYS, keys)
+                intent.putExtra(EXTRA_DATA_VALS, values)
+            }
+            return intent
+        }
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        if (application !is ReactApplication) {
+            Log.e(TAG,
+                "Application does not implement ReactApplication. " +
+                "Headless JS cannot start. Ensure your Application class extends ReactApplication."
+            )
+            stopSelf()
+            return START_NOT_STICKY
+        }
+        return super.onStartCommand(intent, flags, startId)
+    }
+
+    override fun getTaskConfig(intent: Intent?): HeadlessJsTaskConfig? {
+        val extras   = intent?.extras ?: return null
+        val rm       = AppAmbitRemoteMessageStore.get()
+        val fcmNotif = rm?.notification
+
+        val payload = Arguments.createMap()
+        payload.putString("title",    extras.getString(EXTRA_TITLE))
+        payload.putString("body",     extras.getString(EXTRA_BODY))
+
+        val imageUrl = extras.getString(EXTRA_IMAGE_URL) ?: fcmNotif?.imageUrl?.toString()
+        if (imageUrl != null) payload.putString("imageUrl", imageUrl) else payload.putNull("imageUrl")
+
+        val keys   = extras.getStringArray(EXTRA_DATA_KEYS)
+        val values = extras.getStringArray(EXTRA_DATA_VALS)
+        val dataMap = Arguments.createMap()
+        if (keys != null && values != null) {
+            keys.forEachIndexed { i, key ->
+                if (i < values.size) dataMap.putString(key, values[i])
+            }
+        }
+        payload.putMap("data", dataMap)
+
+        // ── FCM message-level fields ──────────────────────────────────────────
+        AppAmbitPayloadUtils.putFcmMessageFields(payload, rm)
+
+        // ── Android sub-object ────────────────────────────────────────────────
+        val androidMap = Arguments.createMap()
+
+        putStringOrNull(androidMap, "color",        extras.getString(EXTRA_ANDROID_COLOR))
+        putStringOrNull(androidMap, "smallIconName", extras.getString(EXTRA_ANDROID_ICON))
+
+        // Intent extras take priority; fall back to RemoteMessage.Notification
+        putStringOrNull(androidMap, "ticker",
+            extras.getString(EXTRA_ANDROID_TICKER) ?: fcmNotif?.ticker)
+        putStringOrNull(androidMap, "channelId",
+            extras.getString(EXTRA_ANDROID_CHANNEL_ID) ?: fcmNotif?.channelId)
+        putStringOrNull(androidMap, "tag",
+            extras.getString(EXTRA_ANDROID_TAG) ?: fcmNotif?.tag)
+        putStringOrNull(androidMap, "sound",
+            extras.getString(EXTRA_ANDROID_SOUND) ?: fcmNotif?.sound)
+        putStringOrNull(androidMap, "clickAction",
+            extras.getString(EXTRA_ANDROID_CLICK_ACTION) ?: fcmNotif?.clickAction)
+        putStringOrNull(androidMap, "visibility",
+            extras.getString(EXTRA_ANDROID_VISIBILITY)
+                ?: AppAmbitPayloadUtils.fcmVisibilityToString(fcmNotif?.visibility))
+
+        when {
+            extras.containsKey(EXTRA_ANDROID_STICKY) ->
+                androidMap.putBoolean("sticky", extras.getBoolean(EXTRA_ANDROID_STICKY))
+            fcmNotif != null ->
+                androidMap.putBoolean("sticky", fcmNotif.sticky)
+            else ->
+                androidMap.putNull("sticky")
+        }
+
+        if (fcmNotif != null) {
+            androidMap.putBoolean("localOnly", fcmNotif.localOnly)
+        } else {
+            androidMap.putNull("localOnly")
+        }
+
+        payload.putMap("android", androidMap)
+        payload.putNull("ios")
+
+        Log.d(TAG, "HeadlessJsTask config built for: ${extras.getString(EXTRA_TITLE)}")
+        return HeadlessJsTaskConfig(
+            HEADLESS_TASK_NAME,
+            payload,
+            TASK_TIMEOUT_MS,
+            /* allowedInForeground = */ true
+        )
+    }
+
+    // ── Helpers ───────────────────────────────────────────────────────────────
+
+    private fun putStringOrNull(map: com.facebook.react.bridge.WritableMap, key: String, value: String?) {
+        AppAmbitPayloadUtils.putStringOrNull(map, key, value)
+    }
+
+}

package/android/src/main/java/com/appambitpushnotifications/AppAmbitInitProvider.kt

@@ -0,0 +1,73 @@
+package com.appambitpushnotifications
+
+import android.content.ContentProvider
+import android.content.ContentValues
+import android.database.Cursor
+import android.net.Uri
+import android.util.Log
+
+/**
+ * AppAmbitInitProvider — early-initialisation ContentProvider.
+ *
+ * Android starts ContentProviders BEFORE [Application.onCreate], which makes them
+ * the only reliable way to obtain an [android.app.Application] context at process
+ * startup — even when the process is created solely to handle an FCM message (killed state).
+ *
+ * This provider sets [AppAmbitContextHolder.applicationContext] at the earliest possible
+ * moment so that any component in the SDK can rely on it without waiting for the React
+ * Native bridge to initialise.
+ *
+ * This is the exact same pattern used by:
+ *   - Firebase (FirebaseInitProvider)
+ *   - WorkManager (WorkManagerInitializer)
+ *   - OneSignal (OneSignalSyncServiceUtils)
+ *
+ * Registration:
+ *   Declared automatically in the SDK's AndroidManifest.xml (merged into the host app):
+ *
+ *   <provider
+ *       android:name="com.appambitpushnotifications.AppAmbitInitProvider"
+ *       android:authorities="${applicationId}.appambit-init-provider"
+ *       android:exported="false"
+ *       android:initOrder="100" />
+ *
+ * No action is required from the consumer app.
+ */
+internal class AppAmbitInitProvider : ContentProvider() {
+
+    private val TAG = "AppAmbitInitProvider"
+
+    override fun onCreate(): Boolean {
+        val appContext = context?.applicationContext
+        if (appContext == null) {
+            Log.e(TAG, "Context is null during ContentProvider.onCreate — cannot initialise AppAmbitContextHolder")
+            return false
+        }
+        AppAmbitContextHolder.set(appContext)
+        Log.d(TAG, "AppAmbitContextHolder initialised early via ContentProvider")
+        return true
+    }
+
+    // ── Required ContentProvider stubs (this provider serves no data) ─────────
+
+    override fun query(
+        uri: Uri,
+        projection: Array<String>?,
+        selection: String?,
+        selectionArgs: Array<String>?,
+        sortOrder: String?
+    ): Cursor? = null
+
+    override fun getType(uri: Uri): String? = null
+
+    override fun insert(uri: Uri, values: ContentValues?): Uri? = null
+
+    override fun delete(uri: Uri, selection: String?, selectionArgs: Array<String>?): Int = 0
+
+    override fun update(
+        uri: Uri,
+        values: ContentValues?,
+        selection: String?,
+        selectionArgs: Array<String>?
+    ): Int = 0
+}

package/android/src/main/java/com/appambitpushnotifications/AppAmbitMessagingService.kt

@@ -0,0 +1,12 @@
+package com.appambitpushnotifications
+
+import com.appambit.sdk.MessagingService
+import com.google.firebase.messaging.RemoteMessage
+
+class AppAmbitMessagingService : MessagingService() {
+
+    override fun onMessageReceived(remoteMessage: RemoteMessage) {
+        AppAmbitRemoteMessageStore.set(remoteMessage)
+        super.onMessageReceived(remoteMessage)
+    }
+}

package/android/src/main/java/com/appambitpushnotifications/AppAmbitNotificationSerializer.kt

@@ -0,0 +1,88 @@
+package com.appambitpushnotifications
+
+import com.appambit.sdk.models.AppAmbitNotification
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+
+internal object AppAmbitNotificationSerializer {
+
+    fun toEventPayload(notification: AppAmbitNotification): WritableMap {
+        val data         = notification.data
+        val rm           = AppAmbitRemoteMessageStore.get()
+        val fcmNotif     = rm?.notification
+        val payload      = Arguments.createMap()
+
+        // ── Core fields ───────────────────────────────────────────────────────
+        payload.putString("title", notification.title)
+        payload.putString("body",  notification.body)
+
+        val imageUrl = notification.imageUrl
+            ?: data["_aa_image_url"]
+            ?: data["image_url"]
+            ?: data["image"]
+            ?: fcmNotif?.imageUrl?.toString()
+        AppAmbitPayloadUtils.putStringOrNull(payload, "imageUrl", imageUrl)
+
+        // ── Custom data — strip internal _aa_* keys ───────────────────────────
+        val dataMap = Arguments.createMap()
+        data.forEach { (key, value) ->
+            if (key !in AppAmbitPayloadUtils.INTERNAL_KEYS) dataMap.putString(key, value)
+        }
+        payload.putMap("data", dataMap)
+
+        // ── FCM message-level fields ──────────────────────────────────────────
+        AppAmbitPayloadUtils.putFcmMessageFields(payload, rm)
+
+        // ── Android sub-object ────────────────────────────────────────────────
+        payload.putMap("android", buildAndroidMap(data, notification, fcmNotif))
+        payload.putNull("ios")
+
+        return payload
+    }
+
+    private fun buildAndroidMap(
+        data: Map<String, String>,
+        notification: AppAmbitNotification,
+        fcmNotif: com.google.firebase.messaging.RemoteMessage.Notification?
+    ): WritableMap {
+        val map = Arguments.createMap()
+
+        // Fields from AppAmbitNotification model directly
+        AppAmbitPayloadUtils.putStringOrNull(map, "color",         notification.color)
+        AppAmbitPayloadUtils.putStringOrNull(map, "smallIconName", notification.smallIconName)
+
+        // Fields read from data map (_aa_* prefix wins) with RemoteMessage.Notification fallback
+        AppAmbitPayloadUtils.putStringOrNull(map, "ticker",
+            data["_aa_ticker"] ?: data["ticker"] ?: fcmNotif?.ticker)
+        AppAmbitPayloadUtils.putStringOrNull(map, "channelId",
+            data["_aa_channel_id"] ?: data["channelId"] ?: data["channel_id"] ?: fcmNotif?.channelId)
+        AppAmbitPayloadUtils.putStringOrNull(map, "tag",
+            data["_aa_tag"] ?: data["tag"] ?: fcmNotif?.tag)
+        AppAmbitPayloadUtils.putStringOrNull(map, "sound",
+            data["_aa_sound"] ?: data["sound"] ?: fcmNotif?.sound)
+        AppAmbitPayloadUtils.putStringOrNull(map, "clickAction",
+            data["_aa_click_action"] ?: data["clickAction"] ?: data["click_action"] ?: fcmNotif?.clickAction)
+        AppAmbitPayloadUtils.putStringOrNull(map, "visibility",
+            data["_aa_visibility"] ?: data["visibility"]
+                ?: AppAmbitPayloadUtils.fcmVisibilityToString(fcmNotif?.visibility))
+        // sticky: data key takes priority, then RemoteMessage.Notification field
+        val stickyParsed = AppAmbitPayloadUtils.parseSticky(data["_aa_sticky"] ?: data["sticky"])
+        when {
+            stickyParsed != null ->
+                map.putBoolean("sticky", stickyParsed)
+            fcmNotif != null ->
+                map.putBoolean("sticky", fcmNotif.sticky)
+            else ->
+                map.putNull("sticky")
+        }
+
+        if (fcmNotif != null) {
+            map.putBoolean("localOnly", fcmNotif.localOnly)
+        } else {
+            map.putNull("localOnly")
+        }
+
+        return map
+    }
+
+}

package/android/src/main/java/com/appambitpushnotifications/AppAmbitPayloadUtils.kt

@@ -0,0 +1,59 @@
+package com.appambitpushnotifications
+
+import com.facebook.react.bridge.WritableMap
+import com.google.firebase.messaging.RemoteMessage
+
+/**
+ * Shared helpers for building the cross-platform NotificationPayload on Android.
+ *
+ * Used by both delivery paths:
+ *  - [AppAmbitNotificationSerializer]: app alive (reads from AppAmbitNotification).
+ *  - [AppAmbitHeadlessService]: app killed (reads from Intent extras).
+ */
+internal object AppAmbitPayloadUtils {
+
+    /** Internal _aa_* keys injected by checkInitialIntent (cold-start opened path). */
+    val INTERNAL_KEYS = setOf(
+        "_aa_image_url", "_aa_ticker", "_aa_sticky",
+        "_aa_visibility", "_aa_channel_id", "_aa_priority",
+        "_aa_tag", "_aa_sound", "_aa_click_action"
+    )
+
+    fun putStringOrNull(map: WritableMap, key: String, value: String?) {
+        if (value != null) map.putString(key, value) else map.putNull(key)
+    }
+
+    /** RemoteMessage.PRIORITY_HIGH=1, PRIORITY_NORMAL=2, PRIORITY_UNKNOWN=0 */
+    fun fcmPriorityToString(priority: Int): String? = when (priority) {
+        1 -> "high"
+        2 -> "normal"
+        else -> null
+    }
+
+    fun fcmVisibilityToString(visibility: Int?): String? = when (visibility) {
+        1 -> "public"
+        0 -> "private"
+        -1 -> "secret"
+        else -> null
+    }
+
+    fun parseSticky(value: String?): Boolean? =
+        value?.let { it.equals("true", ignoreCase = true) || it == "1" }
+
+    /** FCM message-level fields, shared by both delivery paths. */
+    fun putFcmMessageFields(payload: WritableMap, rm: RemoteMessage?) {
+        if (rm != null) {
+            putStringOrNull(payload, "messageId", rm.messageId)
+            payload.putDouble("sentTime", rm.sentTime.toDouble())
+            payload.putInt("ttl", rm.ttl)
+            putStringOrNull(payload, "collapseKey", rm.collapseKey)
+            putStringOrNull(payload, "from", rm.from)
+            putStringOrNull(payload, "messagePriority", fcmPriorityToString(rm.priority))
+            putStringOrNull(payload, "originalPriority", fcmPriorityToString(rm.originalPriority))
+        } else {
+            for (key in listOf("messageId", "sentTime", "ttl", "collapseKey",
+                               "from", "messagePriority", "originalPriority"))
+                payload.putNull(key)
+        }
+    }
+}

package/android/src/main/java/com/appambitpushnotifications/AppAmbitPushEventEmitter.kt

@@ -0,0 +1,100 @@
+package com.appambitpushnotifications
+
+import android.util.Log
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.modules.core.DeviceEventManagerModule
+import java.util.concurrent.CopyOnWriteArrayList
+
+/**
+ * Thread-safe event emitter for the AppAmbit Push SDK.
+ *
+ * Design goals:
+ * 1. Never crash if ReactContext is not yet initialized (e.g. cold start).
+ * 2. Queue events that arrive before JS is ready and drain them once the
+ *    bridge is up.
+ * 3. Provide a single place to route all native→JS events so that the
+ *    Module, the HeadlessTask, and the ServiceExtension all emit through
+ *    the same channel.
+ */
+internal object AppAmbitPushEventEmitter {
+
+    private const val TAG = "AppAmbitEmitter"
+    private const val MAX_QUEUE_SIZE = 100
+
+    // Events used by the SDK — kept here to avoid magic strings everywhere.
+    const val EVENT_FOREGROUND  = "AppAmbit_onForegroundNotification"
+    const val EVENT_BACKGROUND  = "AppAmbit_onBackgroundNotification"
+    const val EVENT_OPENED      = "AppAmbit_onOpenedNotification"
+
+    @Volatile
+    private var reactContext: ReactApplicationContext? = null
+
+    // Queue for events that arrive before the React bridge is ready.
+    private val eventQueue = CopyOnWriteArrayList<Pair<String, WritableMap>>()
+
+    // ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    /**
+     * Called once the TurboModule is instantiated.
+     * Drains the queue of any events that arrived before JS was ready.
+     */
+    fun attach(context: ReactApplicationContext) {
+        reactContext = context
+        Log.d(TAG, "ReactContext attached — draining ${eventQueue.size} queued events")
+        val iter = eventQueue.iterator()
+        while (iter.hasNext()) {
+            val (event, payload) = iter.next()
+            dispatchToJS(event, payload)
+        }
+        eventQueue.clear()
+    }
+
+    /**
+     * Called when the module is invalidated (e.g. hot reload or app restart).
+     *
+     * NOTE: we intentionally do NOT clear [eventQueue] here. Events that arrived
+     * during a React Native reload should be delivered to the next bridge instance
+     * once [attach] is called again.
+     */
+    fun detach() {
+        reactContext = null
+        // eventQueue is preserved so events survive a bridge restart / hot reload.
+    }
+
+    // ── Emission ─────────────────────────────────────────────────────────────
+
+    /**
+     * Emit an event. If the React bridge is ready the event is delivered
+     * immediately; otherwise it is queued until [attach] is called.
+     */
+    fun emit(eventName: String, payload: WritableMap) {
+        if (!dispatchToJS(eventName, payload)) {
+            Log.d(TAG, "Bridge not ready — queuing event: $eventName")
+            if (eventQueue.size >= MAX_QUEUE_SIZE) {
+                eventQueue.removeAt(0)
+                Log.w(TAG, "Event queue full — dropped oldest event")
+            }
+            eventQueue.add(eventName to payload)
+        }
+    }
+
+    /**
+     * Returns true if the event was emitted, false if the bridge was not available.
+     */
+    private fun dispatchToJS(eventName: String, payload: WritableMap): Boolean {
+        val ctx = reactContext ?: return false
+        return try {
+            if (ctx.hasActiveReactInstance()) {
+                ctx.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+                    .emit(eventName, payload)
+                true
+            } else {
+                false
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to emit event $eventName", e)
+            false
+        }
+    }
+}

package/android/src/main/java/com/appambitpushnotifications/AppAmbitRNServiceExtension.kt

@@ -0,0 +1,75 @@
+package com.appambitpushnotifications
+
+import android.content.Context
+import android.util.Log
+import com.appambit.sdk.IAppAmbitNotificationServiceExtension
+import com.appambit.sdk.models.AppAmbitNotification
+
+/**
+ * Concrete implementation of [IAppAmbitNotificationServiceExtension] that acts
+ * as the bridge between the AppAmbit Android Push SDK and React Native.
+ *
+ * Registration:
+ *   Declared in the consuming app's AndroidManifest.xml as a <meta-data> entry:
+ *
+ *   <meta-data
+ *     android:name="com.appambit.sdk.NotificationServiceExtension"
+ *     android:value="com.appambitpushnotifications.AppAmbitRNServiceExtension" />
+ *
+ * The SDK's MessagingService reads this meta-data key and reflectively instantiates
+ * this class, then calls [onNotificationForeground] or [onNotificationBackground]
+ * depending on the current app state.
+ *
+ * Threading:
+ *   Both callbacks are invoked on a background thread from within FirebaseMessagingService.
+ *   The AppAmbitPushEventEmitter is thread-safe, so no synchronization is needed here.
+ *
+ * Background / killed state:
+ *   When the app is in background or killed, [onNotificationBackground] fires.
+ *   We receive the FirebaseMessagingService Context directly (always valid) and
+ *   pass it to AppAmbitHeadlessService so it can start without any static holder.
+ */
+class AppAmbitRNServiceExtension : IAppAmbitNotificationServiceExtension {
+
+    private val TAG = "AppAmbitRNExtension"
+
+    // ── Abstract method implementations (no-ops) ──────────────────────────────
+    // MessagingService always calls the Context-carrying overloads below.
+    // These no-context variants exist solely to satisfy the interface contract.
+
+    override fun onNotificationForeground(notification: AppAmbitNotification) = Unit
+
+    override fun onNotificationBackground(notification: AppAmbitNotification) = Unit
+
+    // ── Context-carrying overrides (actual implementations) ───────────────────
+    // Overriding a default interface method takes full priority over the default.
+    // MessagingService calls ext.onNotificationXxx(this, notification) — "this"
+    // is the FirebaseMessagingService, which is a valid Context at all times,
+    // even in killed state before the React Native bridge exists.
+
+    /**
+     * Called when the app is in the foreground.
+     * [context] is the FirebaseMessagingService — always valid.
+     */
+    override fun onNotificationForeground(context: Context, notification: AppAmbitNotification) {
+        Log.d(TAG, "onNotificationForeground: ${notification.title}")
+        val payload = AppAmbitNotificationSerializer.toEventPayload(notification)
+        AppAmbitPushEventEmitter.emit(AppAmbitPushEventEmitter.EVENT_FOREGROUND, payload)
+    }
+
+    /**
+     * Called when the app is in background or killed state.
+     * [context] is the FirebaseMessagingService — always valid, even before the RN bridge starts.
+     */
+    override fun onNotificationBackground(context: Context, notification: AppAmbitNotification) {
+        Log.d(TAG, "onNotificationBackground: ${notification.title}")
+        val payload = AppAmbitNotificationSerializer.toEventPayload(notification)
+
+        // 1. Try to emit directly (works when the React host is alive in background).
+        AppAmbitPushEventEmitter.emit(AppAmbitPushEventEmitter.EVENT_BACKGROUND, payload)
+
+        // 2. Trigger Headless JS using the FirebaseMessagingService context (always valid).
+        //    This starts the JS task even in killed state, without relying on any RN bridge holder.
+        AppAmbitHeadlessService.enqueueNotification(context, notification)
+    }
+}

package/android/src/main/java/com/appambitpushnotifications/AppAmbitRemoteMessageStore.kt

@@ -0,0 +1,26 @@
+package com.appambitpushnotifications
+
+import com.google.firebase.messaging.RemoteMessage
+import java.util.concurrent.atomic.AtomicLong
+import java.util.concurrent.atomic.AtomicReference
+
+internal object AppAmbitRemoteMessageStore {
+
+    private val stored   = AtomicReference<RemoteMessage?>(null)
+    private val storedAt = AtomicLong(0L)
+    private const val TTL_MS = 60_000L
+
+    fun set(message: RemoteMessage) {
+        stored.set(message)
+        storedAt.set(System.currentTimeMillis())
+    }
+
+    fun get(): RemoteMessage? {
+        val msg = stored.get() ?: return null
+        if (System.currentTimeMillis() - storedAt.get() > TTL_MS) {
+            stored.set(null)
+            return null
+        }
+        return msg
+    }
+}