zixflow-reactnative 1.1.2 → 1.1.4

package/android/src/main/java/com/zixflow/reactnative/sdk/liveactivities/NativeLiveActivitiesModule.kt

@@ -0,0 +1,310 @@
+package com.zixflow.reactnative.sdk.liveactivities
+
+import android.graphics.Color
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.module.annotations.ReactModule
+import com.zixflow.messagingpush.MessagingPushModuleConfig
+import com.zixflow.messagingpush.ModuleMessagingPushFCM
+import com.zixflow.messagingpush.data.communication.ZixflowLiveNotificationsCallback
+import com.zixflow.messagingpush.di.pushModuleConfig
+import com.zixflow.messagingpush.livenotification.LiveNotificationAsset
+import com.zixflow.messagingpush.livenotification.LiveNotificationBranding
+import com.zixflow.messagingpush.livenotification.LiveNotificationData
+import com.zixflow.messagingpush.livenotification.LiveNotificationType
+import com.zixflow.reactnative.sdk.NativeZixflowLiveActivitiesSpec
+import com.zixflow.reactnative.sdk.extension.getTypedValue
+import com.zixflow.sdk.core.di.SDKComponent
+import com.zixflow.sdk.core.util.Logger
+
+/**
+ * React Native module implementation for Zixflow Live Activities / Live Notifications
+ * using TurboModules with new architecture.
+ *
+ * Live Notifications live on the FCM push module ([ModuleMessagingPushFCM]); this bridge
+ * maps the wrapper's template payloads to [LiveNotificationData] and forwards them.
+ */
+@ReactModule(name = NativeLiveActivitiesModule.NAME)
+class NativeLiveActivitiesModule(
+    private val reactContext: ReactApplicationContext,
+) : NativeZixflowLiveActivitiesSpec(reactContext) {
+    private val logger: Logger
+        get() = SDKComponent.logger
+
+    // Live Notifications are hosted by the FCM push module. Reach it via the module registry
+    // (the wrapper can't reference the SDK-internal MODULE_NAME constant, so use the literal).
+    //
+    // Deliberately not runCatching: `as?` yields null instead of throwing, so a failure branch keyed
+    // on a thrown error would never run and the message below would never be logged.
+    private fun getPushModule(): ModuleMessagingPushFCM? {
+        val module = SDKComponent.modules[PUSH_FCM_MODULE_NAME] as? ModuleMessagingPushFCM
+        if (module == null) {
+            logger.error("Live Notifications: push module is not initialized. Ensure the SDK is initialized with live activity templates enabled.")
+        }
+        return module
+    }
+
+    override fun handleWidgetUrl(url: String?, promise: Promise?) {
+        // Zixflow Live Activity widget URLs are an iOS-only contract. Preserve every Android
+        // URL so a shared Expo Router redirectSystemPath implementation cannot suppress routing.
+        promise?.resolve(url)
+    }
+
+    override fun start(payload: ReadableMap?, promise: Promise?) {
+        val module = getPushModule() ?: return promise.rejectNotAvailable()
+        try {
+            val map = requireNotNull(payload) { "payload is required" }
+            // Custom types have no built-in template, so they take the SDK's untyped map path and are
+            // rendered by the app's own callback. Built-ins keep the typed path.
+            val isCustom = map.getString("type") == CUSTOM_TYPE_DISCRIMINATOR
+            val activityType = if (isCustom) {
+                requireCustomActivityType()
+            } else {
+                requireNotNull(map.getString("type")) { "payload.type is required" }
+            }
+            if (activityType !in enabledActivityTypes()) {
+                return promise.rejectNotRegistered(activityType)
+            }
+            val id = if (isCustom) {
+                module.startLiveNotification(activityType, customData(map))
+            } else {
+                module.startLiveNotification(parseData(map))
+            }
+            promise?.resolve(id)
+        } catch (ex: Throwable) {
+            promise?.reject("live_activity_start_failed", ex.message, ex)
+        }
+    }
+
+    override fun update(activityId: String?, payload: ReadableMap?, promise: Promise?) {
+        val module = getPushModule() ?: return promise.rejectNotAvailable()
+        try {
+            val id = requireNotNull(activityId) { "activityId is required" }
+            val map = requireNotNull(payload) { "payload is required" }
+            if (map.getString("type") == CUSTOM_TYPE_DISCRIMINATOR) {
+                module.updateLiveNotification(id, requireCustomActivityType(), customData(map))
+            } else {
+                module.updateLiveNotification(id, parseData(map))
+            }
+            promise?.resolve(null)
+        } catch (ex: Throwable) {
+            promise?.reject("live_activity_update_failed", ex.message, ex)
+        }
+    }
+
+    /**
+     * Ends a live notification. [payload] is accepted for signature parity with iOS, where a final
+     * content-state is what makes ActivityKit render a terminal state; Android renders its own
+     * terminal state (the notification simply stops being ongoing), so it is ignored here.
+     */
+    override fun end(activityId: String?, payload: ReadableMap?, promise: Promise?) {
+        val module = getPushModule() ?: return promise.rejectNotAvailable()
+        try {
+            module.endLiveNotification(requireNotNull(activityId) { "activityId is required" })
+            promise?.resolve(null)
+        } catch (ex: Throwable) {
+            promise?.reject("live_activity_end_failed", ex.message, ex)
+        }
+    }
+
+    /**
+     * The app's own identifier for the custom template. Absent means the app sent a custom payload
+     * without configuring `liveNotifications.customType` — say so, rather than starting a
+     * notification the allowlist would silently drop.
+     */
+    /**
+     * Identifiers the SDK currently has enabled. Read from the live module config rather than cached
+     * at wrapper init: the config can also be built by generated native code that never calls
+     * [applyLiveActivitiesConfig] — the Expo config plugin does exactly that — and a cached set would
+     * be empty there, rejecting every start.
+     */
+    private fun enabledActivityTypes(): Set<String> =
+        SDKComponent.pushModuleConfig.liveNotificationTypes
+
+    /**
+     * The custom identifier, preferring what the wrapper saw and otherwise deriving it from the live
+     * config: exactly one custom type is supported, so it is the single enabled identifier that no
+     * built-in [LiveNotificationType] claims.
+     */
+    private fun customActivityTypeOrNull(): String? = customActivityType
+        ?: enabledActivityTypes().firstOrNull { identifier ->
+            LiveNotificationType.entries.none { it.identifier == identifier }
+        }
+
+    private fun requireCustomActivityType(): String = requireNotNull(customActivityTypeOrNull()) {
+        "No custom Live Activity type is configured. Set `liveNotifications.customType` in your " +
+            "Zixflow SDK config to your own reverse-DNS identifier, and render it from your " +
+            "ZixflowLiveNotificationsCallback."
+    }
+
+    /** Flattens the payload's `data` map. Android stringifies every value downstream anyway. */
+    private fun customData(payload: ReadableMap): Map<String, Any?> =
+        payload.getMap("data")?.toHashMap() ?: emptyMap()
+
+    private fun parseData(payload: ReadableMap): LiveNotificationData {
+        return when (val type = payload.getString("type")) {
+            LiveNotificationType.SEGMENTS.identifier -> LiveNotificationData.Segments(
+                header = payload.requireString("header"),
+                status = payload.requireString("status"),
+                substatus = payload.optString("substatus"),
+                segmentsTotal = payload.requireDouble("segmentsTotal").toInt(),
+                segmentsComplete = payload.requireDouble("segmentsComplete").toInt(),
+                trailingText = payload.optString("trailingText"),
+            )
+
+            LiveNotificationType.COUNTDOWN_TIMER.identifier -> LiveNotificationData.CountdownTimer(
+                header = payload.requireString("header"),
+                title = payload.requireString("title"),
+                statusMessage = payload.optString("statusMessage"),
+                endTime = if (payload.hasKey("endTime") && !payload.isNull("endTime")) {
+                    payload.getDouble("endTime").toLong()
+                } else {
+                    null
+                },
+            )
+
+            // A newer native SDK may know this type even though this wrapper build doesn't.
+            // Reject softly (the caller turns this into a rejected promise) rather than crash.
+            else -> throw IllegalArgumentException("Unsupported Live Activity template: $type")
+        }
+    }
+
+    private fun ReadableMap.requireString(key: String): String =
+        requireNotNull(if (hasKey(key)) getString(key) else null) { "$key is required" }
+
+    private fun ReadableMap.optString(key: String): String? =
+        if (hasKey(key) && !isNull(key)) getString(key) else null
+
+    private fun ReadableMap.requireDouble(key: String): Double {
+        require(hasKey(key) && !isNull(key)) { "$key is required" }
+        return getDouble(key)
+    }
+
+    private fun Promise?.rejectNotAvailable() {
+        this?.reject(
+            "live_activity_module_unavailable",
+            "Live Notifications are unavailable. Enable live activity templates in the SDK config.",
+        )
+    }
+
+    /** Mirrors iOS's `live_activity_type_not_registered` so the same mistake reads the same way. */
+    private fun Promise?.rejectNotRegistered(activityType: String?) {
+        this?.reject(
+            "live_activity_type_not_registered",
+            "Live Activity type '$activityType' is not registered. Add it to " +
+                "`liveNotifications.types` in your Zixflow SDK config (or set " +
+                "`liveNotifications.customType` for a custom type).",
+        )
+    }
+
+    companion object {
+        const val NAME = "NativeZixflowLiveActivities"
+
+        // The SDK's ModuleMessagingPushFCM.MODULE_NAME is `internal`, so we mirror its value here.
+        private const val PUSH_FCM_MODULE_NAME = "MessagingPushFCM"
+
+        // Discriminator JavaScript sends for the custom template. Not a wire identifier — the
+        // notification is started under the app's own `liveNotifications.customType`.
+        private const val CUSTOM_TYPE_DISCRIMINATOR = "custom"
+
+        // The app's own identifier for the custom template, captured from config at SDK init.
+        @Volatile
+        private var customActivityType: String? = null
+
+        // Host-app callback used to render custom (app-defined) live notifications. The native SDK
+        // only accepts it at build time, so the app must register it before the SDK initializes
+        // (e.g. in Application.onCreate before React Native starts). Stored statically because the
+        // SDK config is applied in applyLiveActivitiesConfig, not on this module instance.
+        @Volatile
+        private var liveNotificationCallback: ZixflowLiveNotificationsCallback? = null
+
+        /**
+         * Register the host app's callback for rendering live notifications itself. Custom
+         * (app-defined) activity types have no built-in template, so the app must build the
+         * [android.app.Notification] in
+         * [ZixflowLiveNotificationsCallback.createLiveNotification]; returning `null` there
+         * falls back to the SDK's built-in template.
+         * Call this before the Zixflow SDK is initialized.
+         */
+        @JvmStatic
+        fun setLiveNotificationCallback(callback: ZixflowLiveNotificationsCallback) {
+            liveNotificationCallback = callback
+        }
+
+        /**
+         * Applies live activity configuration onto the FCM push module's config builder. Live
+         * Notifications are hosted by [ModuleMessagingPushFCM], so their config (enabled templates,
+         * custom types, branding) is set on the same [MessagingPushModuleConfig].
+         *
+         * @param builder the push module's config builder.
+         * @param config the `liveNotifications` config map from the customer app.
+         */
+        internal fun applyLiveActivitiesConfig(
+            builder: MessagingPushModuleConfig.Builder,
+            config: Map<String, Any>,
+        ) {
+            // Wire the host app's live-notification renderer, if one was registered.
+            liveNotificationCallback?.let { builder.setLiveNotificationCallback(it) }
+
+            // Unrecognized identifiers are ignored: a newer native SDK may ship types this
+            // wrapper build doesn't know, and that must never break the ones it does know.
+            val templateTypes = config.getTypedValue<List<*>>("types")
+                ?.mapNotNull { it as? String }
+                ?.mapNotNull { identifier ->
+                    LiveNotificationType.entries.firstOrNull { it.identifier == identifier }
+                }
+                .orEmpty()
+            if (templateTypes.isNotEmpty()) {
+                builder.enableLiveNotificationTypes(*templateTypes.toTypedArray())
+            }
+
+            // The custom template. Allowlisting the identifier is both necessary and sufficient:
+            // LiveNotificationHandler drops any push whose activityType isn't in this set, and a type
+            // with no built-in template falls through to the host app's render callback.
+            //
+            // Assigned unconditionally: a re-initialize that drops `customType` must clear it, or
+            // `start` would keep minting notifications under an identifier no longer allowlisted —
+            // which the handler then discards, leaving the caller with an id and nothing on screen.
+            val customType = config.getTypedValue<String>("customType")?.trim()?.takeIf { it.isNotEmpty() }
+            customActivityType = customType
+            if (customType != null) {
+                builder.enableCustomLiveNotificationTypes(customType)
+            }
+
+            val branding = config.getTypedValue<Map<String, Any>>("branding")
+            if (branding != null) {
+                val accentColor = branding.getTypedValue<String>("accentColorHex")
+                    ?.let { runCatching { Color.parseColor(it) }.getOrNull() }
+                    ?: Color.TRANSPARENT
+                // A bundled drawable is preferred over a remote URL: it renders without a network
+                // round-trip, so the logo is present on the very first frame.
+                val logo = branding.getTypedValue<String>("logoResource")
+                    ?.let { name -> drawableResId(name)?.let(LiveNotificationAsset::Drawable) }
+                    ?: branding.getTypedValue<String>("logoUrl")
+                        ?.let(LiveNotificationAsset::RemoteUrl)
+                val smallIcon = branding.getTypedValue<String>("smallIconResource")
+                    ?.let { name -> drawableResId(name) }
+                builder.setLiveNotificationBranding(
+                    LiveNotificationBranding(
+                        companyName = branding.getTypedValue<String>("companyName").orEmpty(),
+                        accentColor = accentColor,
+                        smallIcon = smallIcon,
+                        logo = logo,
+                    ),
+                )
+            }
+        }
+
+        /**
+         * Resolve a bundled drawable by name, or `null` when the host app doesn't ship one under
+         * that name — a missing asset must degrade to "no image", never crash rendering.
+         */
+        private fun drawableResId(name: String): Int? {
+            val context = SDKComponent.android().applicationContext
+            return context.resources
+                .getIdentifier(name, "drawable", context.packageName)
+                .takeIf { it != 0 }
+        }
+    }
+}

package/android/src/main/java/com/zixflow/reactnative/sdk/logging/NativeZixflowLoggingModule.kt

@@ -6,7 +6,7 @@ import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReadableMap
 import com.zixflow.reactnative.sdk.NativeZixflowLoggingSpec
 import com.zixflow.sdk.core.di.SDKComponent
-import com.zixflow.sdk.core.util.CioLogLevel
+import com.zixflow.sdk.core.util.ZixflowLogLevel
 
 /**
  * React Native module implementation for Zixflow Logging Native SDK
@@ -72,7 +72,7 @@ class NativeZixflowLoggingModule(
     }
 
     // Converts native SDK log events to React Native compatible format and emits them.
-    private fun emitLogEvent(level: CioLogLevel, message: String) {
+    private fun emitLogEvent(level: ZixflowLogLevel, message: String) {
         // Defensive check: only emit if emitter is available
         val emitter = logEventEmitter ?: return
 

package/android/src/main/java/com/zixflow/reactnative/sdk/messaginginapp/NativeMessagingInAppModule.kt

@@ -10,6 +10,8 @@ import com.zixflow.messaginginapp.di.inAppMessaging
 import com.zixflow.messaginginapp.gist.data.model.InboxMessage
 import com.zixflow.messaginginapp.gist.data.model.response.InboxMessageFactory
 import com.zixflow.messaginginapp.inbox.NotificationInbox
+import com.zixflow.messaginginapp.type.ColorScheme
+import com.zixflow.messaginginapp.type.NotificationInboxAccessibilityLabels
 import com.zixflow.reactnative.sdk.NativeZixflowMessagingInAppSpec
 import com.zixflow.reactnative.sdk.constant.Keys
 import com.zixflow.reactnative.sdk.extension.getTypedValue
@@ -33,6 +35,7 @@ class NativeMessagingInAppModule(
 
     private val inAppEventListener = ReactInAppEventListener.instance
     private val inboxChangeListener = ReactNotificationInboxChangeListener.instance
+    private val inboxEventListener = ReactInboxEventListener.instance
 
     // Dedicated lock for inbox listener setup to avoid blocking other operations
     private val inboxListenerLock = Any()
@@ -63,6 +66,7 @@ class NativeMessagingInAppModule(
     override fun invalidate() {
         inAppEventListener.clearEventEmitter()
         clearInboxChangeListener()
+        clearInboxEventListener()
         super.invalidate()
     }
 
@@ -70,10 +74,76 @@ class NativeMessagingInAppModule(
         inAppMessagingModule?.dismissMessage()
     }
 
+    // Nullable like every other argument-taking override here, and for the same reason: Codegen
+    // declares the parameter non-null, so a non-null Kotlin type would throw
+    // `Intrinsics.checkNotNullParameter` before the body runs when JavaScript passes null — which
+    // is what an untyped caller reading a stored theme sends on first launch.
+    override fun setColorScheme(colorScheme: String?) {
+        val resolved = colorSchemeFromRawValue(colorScheme)
+        if (resolved == null) {
+            // Leave the current scheme alone rather than resetting it to AUTO, so a bad value
+            // cannot quietly undo a scheme the app set correctly earlier.
+            logger.error(
+                "Unrecognized in-app colorScheme '$colorScheme', expected one of auto, light, " +
+                    "dark. Leaving the color scheme unchanged."
+            )
+            return
+        }
+        val module = inAppMessagingModule
+        if (module == null) {
+            // Reachable when the host calls this before Zixflow.initialize, or without the
+            // in-app module configured. Logged rather than ignored: the scheme is silently not
+            // applied, and nothing else surfaces that.
+            logger.error(
+                "In-app messaging is not available, so the color scheme was not applied. " +
+                    "Ensure Zixflow SDK is initialized with the inApp configuration."
+            )
+            return
+        }
+        module.setColorScheme(resolved)
+    }
+
     override fun setupInboxListener() {
         setupInboxChangeListener()
     }
 
+    /**
+     * Registers the native inbox event forwarder with the SDK and wires it to the React Native
+     * event emitter. Called when a JS inbox event listener is registered.
+     */
+    override fun registerInboxEventListener() {
+        inboxEventListener.setEventEmitter { data ->
+            emitOnInboxEventReceived(data)
+        }
+        val module = inAppMessagingModule
+        if (module == null) {
+            // Without this the failure is invisible: the JS subscription reports success while the SDK
+            // never forwards anything, so inbox callbacks silently never arrive. Matches the guidance
+            // used by getMessages() for the same situation.
+            logger.error(
+                "Cannot register inbox event listener: in-app messaging is not available. " +
+                    "Ensure Zixflow SDK is initialized before registering the listener."
+            )
+            return
+        }
+        module.setInboxEventListener(inboxEventListener)
+    }
+
+    /**
+     * Unregisters the native inbox event forwarder by installing a no-op listener (the native API is
+     * non-null), restoring the SDK's default action handling. Called when the JS inbox event
+     * listener is removed.
+     */
+    override fun unregisterInboxEventListener() {
+        inAppMessagingModule?.setInboxEventListener(NoOpInboxEventListener)
+        inboxEventListener.clearEventEmitter()
+    }
+
+    private fun clearInboxEventListener() {
+        inAppMessagingModule?.setInboxEventListener(NoOpInboxEventListener)
+        inboxEventListener.clearEventEmitter()
+    }
+
     override fun getMessages(topic: String?, promise: Promise?) {
         try {
             val inbox = requireInboxInstance() ?: run {
@@ -191,25 +261,94 @@ class NativeMessagingInAppModule(
          *
          * @param builder ZixflowBuilder instance to add InAppMessaging module
          * @param config Configuration provided by customer app for InAppMessaging module
-         * @param region Region to be used for InAppMessaging module
          */
         internal fun addNativeModuleFromConfig(
             builder: ZixflowBuilder,
-            config: Map<String, Any>,
-            region: Region
+            config: Map<String, Any>
         ) {
-            val siteId = config.getTypedValue<String>(Keys.Config.SITE_ID)
-            if (siteId.isNullOrBlank()) {
-                SDKComponent.logger.error("Site ID is required to initialize InAppMessaging module")
-                return
-            }
-
             val module = ModuleMessagingInApp(
-                MessagingInAppModuleConfig.Builder(siteId = siteId, region = region).apply {
+                MessagingInAppModuleConfig.Builder().apply {
                     setEventListener(eventListener = ReactInAppEventListener.instance)
+                    colorSchemeFromConfig(config)?.let { colorScheme ->
+                        setColorScheme(colorScheme)
+                    }
+                    inboxAccessibilityLabelsFromConfig(config)?.let { labels ->
+                        setNotificationInboxAccessibilityLabels(labels)
+                    }
                 }.build(),
             )
             builder.addZixflowModule(module)
         }
+
+        /**
+         * Maps the wrapper's `colorScheme` value onto the native [ColorScheme], or null when the
+         * value is absent or unrecognized.
+         *
+         * The accepted values are lowercase because that is the wire contract the JavaScript
+         * `ZixflowColorScheme` enum serializes to and the one iOS already matches. Kept free of
+         * logging so each caller can report a bad value in its own terms: at initialization an
+         * unrecognized value falls back to AUTO, while the runtime setter leaves the scheme the
+         * app already chose untouched.
+         */
+        internal fun colorSchemeFromRawValue(rawValue: String?): ColorScheme? = when (rawValue) {
+            "auto" -> ColorScheme.AUTO
+            "light" -> ColorScheme.LIGHT
+            "dark" -> ColorScheme.DARK
+            else -> null
+        }
+
+        private fun colorSchemeFromConfig(config: Map<String, Any>): ColorScheme? {
+            // Absent is not a mistake — the SDK's own AUTO default stands — so only a value the
+            // host actually provided is worth reporting.
+            val rawValue = config.getTypedValue<String>(Keys.Config.COLOR_SCHEME) ?: return null
+
+            return colorSchemeFromRawValue(rawValue).also { resolved ->
+                if (resolved == null) {
+                    SDKComponent.logger.error(
+                        "Unrecognized in-app colorScheme '$rawValue', expected one of auto, " +
+                            "light, dark. Falling back to the device appearance."
+                    )
+                }
+            }
+        }
+
+        /**
+         * Builds the host's inbox accessibility labels from the wrapper configuration, or null when
+         * the app provided none — in which case the SDK keeps its default of emitting no labels at
+         * all rather than falling back to English.
+         *
+         * `bellWithUnreadCount` arrives as a template string because the bridge carries data but not
+         * functions; it is converted here into the `(Int) -> String` the native SDK expects. A
+         * template without the placeholder is returned verbatim for every count; the JavaScript
+         * layer warns about that case, where the developer can actually see it.
+         */
+        private fun inboxAccessibilityLabelsFromConfig(
+            config: Map<String, Any>
+        ): NotificationInboxAccessibilityLabels? {
+            val labels = config.getTypedValue<Map<String, Any>>(
+                Keys.Config.NOTIFICATION_INBOX_ACCESSIBILITY_LABELS
+            ) ?: return null
+
+            val unreadCountTemplate = labels.getTypedValue<String>(
+                Keys.InboxAccessibilityLabels.BELL_WITH_UNREAD_COUNT
+            )
+            return NotificationInboxAccessibilityLabels(
+                bell = labels.getTypedValue<String>(Keys.InboxAccessibilityLabels.BELL),
+                bellWithUnreadCount = unreadCountTemplate?.let { template ->
+                    { count: Int ->
+                        template.replace(
+                            Keys.InboxAccessibilityLabels.COUNT_PLACEHOLDER,
+                            count.toString()
+                        )
+                    }
+                },
+                loadingIndicator = labels.getTypedValue<String>(
+                    Keys.InboxAccessibilityLabels.LOADING_INDICATOR
+                ),
+                emptyState = labels.getTypedValue<String>(
+                    Keys.InboxAccessibilityLabels.EMPTY_STATE
+                )
+            )
+        }
     }
 }

package/android/src/main/java/com/zixflow/reactnative/sdk/messaginginapp/ReactInboxEventListener.kt

@@ -0,0 +1,99 @@
+package com.zixflow.reactnative.sdk.messaginginapp
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReadableMap
+import com.zixflow.messaginginapp.gist.data.model.InboxMessage
+import com.zixflow.messaginginapp.type.InboxEventListener
+
+/**
+ * React Native bridge for Zixflow Visual Notification Inbox events.
+ *
+ * Registered on the SDK (via [com.zixflow.messaginginapp.ModuleMessagingInApp.setInboxEventListener])
+ * only while a JS listener is registered. Because the New-Arch event emitter is one-way we cannot
+ * round-trip a bool back from JS, so [messageActionTaken] forwards the event fire-and-forget and
+ * RETURNS `true` — telling the SDK the host handled the action so the SDK suppresses its default
+ * navigation. The JS host owns action handling while a listener is registered. Observational
+ * callbacks forward fire-and-forget.
+ */
+class ReactInboxEventListener private constructor() : InboxEventListener {
+    // Event emitter function to send events to React Native layer
+    private var eventEmitter: ((ReadableMap) -> Unit)? = null
+
+    // Sets the event emitter function
+    internal fun setEventEmitter(emitter: ((ReadableMap) -> Unit)?) {
+        this.eventEmitter = emitter
+    }
+
+    // Clears the event emitter to prevent memory leaks
+    internal fun clearEventEmitter() {
+        this.eventEmitter = null
+    }
+
+    // Emits an inbox message event to React Native with a serialized message payload
+    private fun emitInboxEvent(
+        eventType: String,
+        message: InboxMessage,
+        actionName: String? = null,
+        actionValue: String? = null,
+    ) {
+        // Get the emitter, return early if not set
+        val emitter = eventEmitter ?: return
+
+        val data = Arguments.createMap().apply {
+            putString("eventType", eventType)
+            putMap("message", message.toWritableMap())
+            actionName?.let { putString("actionName", it) }
+            actionValue?.let { putString("actionValue", it) }
+        }
+
+        emitter.invoke(data)
+    }
+
+    override fun messageActionTaken(
+        message: InboxMessage,
+        actionName: String,
+        actionValue: String,
+    ): Boolean {
+        emitInboxEvent(
+            eventType = "messageActionTaken",
+            message = message,
+            actionName = actionName,
+            actionValue = actionValue,
+        )
+        // Host (React Native) owns action handling while a listener is registered.
+        return true
+    }
+
+    override fun messageShown(message: InboxMessage) = emitInboxEvent(
+        eventType = "messageShown",
+        message = message,
+    )
+
+    override fun messageOpened(message: InboxMessage) = emitInboxEvent(
+        eventType = "messageOpened",
+        message = message,
+    )
+
+    override fun messageDismissed(message: InboxMessage) = emitInboxEvent(
+        eventType = "messageDismissed",
+        message = message,
+    )
+
+    companion object {
+        // Singleton instance with public visibility for direct access by Expo plugin
+        val instance: ReactInboxEventListener by lazy { ReactInboxEventListener() }
+    }
+}
+
+/**
+ * No-op inbox listener used to clear the forwarder from the SDK. Returning `false` from
+ * [messageActionTaken] restores the SDK's default action handling. The native
+ * `setInboxEventListener` API is non-null, so a no-op is installed rather than clearing.
+ */
+internal object NoOpInboxEventListener : InboxEventListener {
+    override fun messageActionTaken(
+        message: InboxMessage,
+        actionName: String,
+        actionValue: String,
+    ): Boolean = false
+}

package/android/src/main/java/com/zixflow/reactnative/sdk/messaginginbox/NotificationInboxBellViewManager.kt

@@ -0,0 +1,38 @@
+package com.zixflow.reactnative.sdk.messaginginbox
+
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.SimpleViewManager
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.ViewManagerDelegate
+import com.facebook.react.viewmanagers.NotificationInboxBellNativeManagerDelegate
+import com.facebook.react.viewmanagers.NotificationInboxBellNativeManagerInterface
+
+/**
+ * View manager for the Visual Notification Inbox bell (just the bell; host opens its own UI).
+ *
+ * Registers the `onTap` direct event so taps reach the JS wrapper.
+ */
+@ReactModule(name = NotificationInboxBellViewManager.NAME)
+class NotificationInboxBellViewManager :
+    NotificationInboxBellNativeManagerInterface<ReactNotificationInboxBellView>,
+    SimpleViewManager<ReactNotificationInboxBellView>() {
+    private val delegate = NotificationInboxBellNativeManagerDelegate(this)
+
+    override fun getName() = NAME
+    override fun getDelegate(): ViewManagerDelegate<ReactNotificationInboxBellView> = delegate
+
+    override fun createViewInstance(
+        reactContext: ThemedReactContext
+    ): ReactNotificationInboxBellView = ReactNotificationInboxBellView(reactContext)
+
+    override fun getExportedCustomDirectEventTypeConstants(): MutableMap<String, Any> {
+        val customEvents = super.getExportedCustomDirectEventTypeConstants() ?: mutableMapOf()
+        customEvents[ReactNotificationInboxBellView.ON_TAP] =
+            mapOf("registrationName" to ReactNotificationInboxBellView.ON_TAP)
+        return customEvents
+    }
+
+    companion object {
+        internal const val NAME = "NotificationInboxBellNative"
+    }
+}