react-native-acoustic-connect-beta 18.0.26 → 18.0.28

package/AcousticConnectRN.podspec

@@ -10,10 +10,10 @@ dependencyName = useRelease ? 'AcousticConnect' : 'AcousticConnectDebug'
 iOSVersion = connectConfig["Connect"]["iOSVersion"]
 
 # Floor required by the RN bridge:
-#   - `ConnectSDK.shared.enable(with:)` and `ConnectConfig` landed in 2.0.0
-#     (CA-135041) — anything older lacks the Swift symbols this file imports.
+#   - `ConnectSDK.shared.enable(with:)` and `ConnectConfig` landed in 2.0.0;
+#     anything older lacks the Swift symbols this file imports.
 #   - Bundle-less init via `_connectApplyBundleDefaults` landed in 2.0.5
-#     (CA-136977, Release_Connect_Module_2_0_5, 2026-04-13). Without it,
+#     (Release_Connect_Module_2_0_5, 2026-04-13). Without it,
 #     consumers who don't bundle `EOCoreSettings.bundle` + `TLFResources.bundle`
 #     fail to enable the SDK at all — the bridge ships no bundles and relies
 #     on programmatic config, so this fix is load-bearing here.
@@ -28,7 +28,10 @@ iOSVersion = connectConfig["Connect"]["iOSVersion"]
 # place to introduce a conditional floor keyed off
 # `ConnectConfig.json -> Connect.PushEnabled` (mirrors the Android conditional
 # on `connect-push-fcm` in `android/build.gradle`).
-sdkFloor = '>= 2.0.5'
+# 2.1.12 floor: `ConnectSDK.shared.push.requestAuthorization()` and
+# `getCurrentAuthorization()` land in 2.1.12. The push permission
+# bridge methods call them directly, so an older pod would fail to compile.
+sdkFloor = '>= 2.1.12'
 dependencyRequirements = iOSVersion.to_s.empty? ? [sdkFloor] : [sdkFloor, iOSVersion]
 
 # Write the merged consumer config to the resource-bundle source path AT POD INSTALL TIME.

package/README.md

@@ -11,11 +11,34 @@ For the full product overview see the
 
 - React Native 0.82.x – 0.85.x with the new architecture
 - React 19.1.1 or newer (or whatever your RN version pins)
+- `react-native-nitro-modules` at the **exact** version this package pins in `peerDependencies` (currently **`0.35.9`**) — your app must resolve exactly this version; see [Nitro version pin](#nitro-version-pin)
 - Node 20 or newer
 - iOS deployment target ≥ 15.1, AcousticConnect / AcousticConnectDebug pod ≥ 2.0.5
 - Android `minSdk` ≥ 26, `compileSdk` ≥ 35, `io.github.go-acoustic:connect` in `[11.0.11, 12.0.0)`
 - **Expo is not supported by this package.** Expo apps should use the sibling
-  Config Plugin (tracked separately under PES-4002 / CA-137701).
+  Config Plugin (shipped separately).
+
+### Nitro version pin
+
+This package pins `react-native-nitro-modules` to an **exact version**
+(currently **`0.35.9`**) in its `peerDependencies` — deliberately *not* a range.
+**Your app must resolve exactly that version.**
+
+**Why (important): Nitro patch releases can contain breaking changes.** The SDK
+ships native bindings generated against one specific Nitro version, and Nitro's
+generated-code ↔ runtime contract is **not patch-safe**. For example, a
+`0.35.4` → `0.35.9` *patch* bump changed Nitro's native registration and caused
+this SDK's HybridObject to fail to load with a `ClassNotFoundException`, taking
+the entire module offline at runtime. Because even a patch can break it, a
+version *range* (`^`/`~`/`>=…<…`) cannot guarantee compatibility — so the pin is
+exact.
+
+If your app resolves a different Nitro version, the SDK may fail to start. You
+*can* force past the peer check with `--legacy-peer-deps` / `--force`, **but
+then you own making it work** — we cannot guard against breaking changes in
+arbitrary future Nitro patch releases. When this SDK adopts a newer Nitro, it
+ships in a new SDK release with the pin bumped; upgrade the SDK and Nitro
+together.
 
 ## Installation
 
@@ -222,16 +245,22 @@ and the `<Connect>` component.
 
 ### `npm install` peer-dependency conflicts
 
-If `npm install` errors out on a peer-dependency resolution involving Expo or
-older `react-native-nitro-modules` versions, retry with:
+This package pins `react-native-nitro-modules` to an **exact** version (see
+[Nitro version pin](#nitro-version-pin)). If `npm install` errors on the Nitro
+peer, your app is resolving a *different* Nitro version. Check it with:
 
 ```bash
-npm install react-native-nitro-modules --legacy-peer-deps
+npm ls react-native-nitro-modules
 ```
 
-This usually only happens when an existing project pulls in stale Expo
-transitives. Permanent fix: align RN, React, and Nitro versions with the
-[Requirements](#requirements) section above.
+**Supported fix:** align your app to the exact version this package requires
+(and match React Native / React per the [Requirements](#requirements)).
+
+`--legacy-peer-deps` / `--force` will silence the error, but the pin is
+intentional: a mismatched Nitro version can break the SDK at runtime (an
+init-time `ClassNotFoundException`), and bypassing means **you take on that
+risk** — we cannot guard against breaking changes in arbitrary Nitro patch
+releases. Match the version rather than bypass it.
 
 ### iOS — `pod install` fails with `[Connect] requires AcousticConnect >= 2.0.5`
 

package/android/CMakeLists.txt

@@ -7,7 +7,7 @@
 # prohibited.
 #
 #
-# Created by Omar Hernandez on 5/9/25.
+# Created on 5/9/25.
 #
 
 project(AcousticConnectRN)

package/android/build.gradle

@@ -7,7 +7,7 @@
 // prohibited.
 //
 //
-//  Created by Omar Hernandez on 5/9/25.
+//  Created on 5/9/25.
 //
 
 buildscript {

package/android/src/main/assets/ConnectBasicConfig.properties

@@ -1,4 +1,4 @@
-#Fri May 29 08:54:08 PDT 2026
+#Fri Jun 05 01:23:00 PDT 2026
 UseWhiteList=true
 PrintScreen=3
 UseRandomSample=false

package/android/src/main/java/com/acousticconnectrn/AcousticConnectRNPackage.java

@@ -7,7 +7,7 @@
 // prohibited.
 //
 //
-//  Created by Omar Hernandez on 5/9/25.
+//  Created on 5/9/25.
 //
 
 package com.acousticconnectrn;

package/android/src/main/java/com/acousticconnectrn/HybridAcousticConnectRN.kt

@@ -7,7 +7,7 @@
 // prohibited.
 //
 //
-//  Created by Omar Hernandez on 5/9/25.
+//  Created on 5/9/25.
 //
 
 package com.acousticconnectrn
@@ -29,6 +29,7 @@ import android.view.WindowManager
 import android.view.inputmethod.InputMethodManager
 import android.widget.EditText
 import android.widget.TextView
+import androidx.activity.ComponentActivity
 import androidx.fragment.app.DialogFragment
 import com.acoustic.connect.android.connectmod.Connect
 import com.acoustic.connect.android.connectmod.Connect.TLF_ON_FOCUS_CHANGE_IN
@@ -47,6 +48,7 @@ import com.acoustic.connect.android.connectmod.Connect.logScreenview
 import com.acoustic.connect.android.connectmod.Connect.onResume
 import com.acoustic.connect.android.connectmod.Connect.registerFormField
 import com.acoustic.connect.android.connectmod.Connect.resumeConnect
+import com.acoustic.connect.android.connectmod.push.PushPermissionState
 import com.facebook.react.bridge.LifecycleEventListener
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.uimanager.UIManagerHelper
@@ -54,8 +56,14 @@ import com.ibm.eo.EOCore
 import com.ibm.eo.model.EOMonitoringLevel
 import com.margelo.nitro.NitroModules.Companion.applicationContext
 import com.margelo.nitro.acousticconnectrn.HybridAcousticConnectRNSpec
+import com.margelo.nitro.acousticconnectrn.PushErrorInfo
+import com.margelo.nitro.acousticconnectrn.PushPermissionResult
 import com.margelo.nitro.acousticconnectrn.Variant_Boolean_String_Double
+import com.margelo.nitro.acousticconnectrn.Variant_NullType_Boolean
 import com.margelo.nitro.acousticconnectrn.Variant_NullType_String
+import com.margelo.nitro.core.ArrayBuffer
+import com.margelo.nitro.core.NullType
+import com.margelo.nitro.core.Promise
 import com.tl.uic.Tealeaf
 import com.tl.uic.model.ScreenviewType
 import com.tl.uic.util.DialogUtil
@@ -168,7 +176,7 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         return app
     }
 
-    // region Gate-keeper API (CA-137696)
+    // region Gate-keeper API
 
     /**
      * Re-enables the Connect SDK after a prior `disable()`. All configuration
@@ -185,8 +193,7 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
      * Push wiring on Android is gated at build time by `Connect.PushEnabled`
      * in `ConnectConfig.json`, which `android/build.gradle` consults to
      * include the `connect-push-fcm` artifact. Token forwarding to Connect
-     * lives in CA-137698 and runs through the host app's
-     * `FirebaseMessagingService`.
+     * runs through the host app's `FirebaseMessagingService`.
      *
      * @return true on accepted dispatch, false if no application context.
      */
@@ -226,27 +233,227 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         return true
     }
 
+    // region Push (Android)
+    //
+    // The shared Nitro spec declares these push methods on both platforms. On
+    // Android the native SDK owns the ENTIRE push lifecycle — Connect's own
+    // FirebaseMessagingService (shipped in connect-push-fcm) handles inbound
+    // delivery, PushReceived / PushAction logging, and token registration
+    // automatically. Unlike iOS, Android has no manual JS-forwarding API, so
+    // every JS→native forwarder is a no-op that reports "handled", kept only
+    // for cross-platform API symmetry:
+    //   - pushDidReceiveNotification, pushDidReceiveResponse,
+    //     pushDidRegisterWithToken, pushDidFailToRegister,
+    //     pushDidReceiveAuthorization
+    //
+    // The only Android-relevant behaviour is permission wiring:
+    //   - pushRequestPermission / pushGetPermissionState — POST_NOTIFICATIONS
+    //
+    // pushGetToken / pushGetTokenAsync are intentionally NOT on the surface —
+    // parked (the native SDK registers the token with Connect automatically;
+    // no JS accessor is needed). None of these methods reject.
+
+    /**
+     * iOS-primary forwarder. On Android the FCM token is captured and registered
+     * with Connect automatically by the native messaging service, so this is a
+     * no-op that reports "handled". Never rejects.
+     */
+    override fun pushDidRegisterWithToken(deviceToken: ArrayBuffer): Promise<Boolean> {
+        Log.d(TAG, "[bridge] pushDidRegisterWithToken: no-op on Android (native SDK owns token registration)")
+        return Promise.resolved(true)
+    }
+
+    /**
+     * iOS-primary forwarder. Android surfaces registration failures through the
+     * native SDK's own error path, so this is a no-op. Never rejects.
+     */
+    override fun pushDidFailToRegister(error: PushErrorInfo): Promise<Boolean> {
+        Log.d(TAG, "[bridge] pushDidFailToRegister: no-op on Android (domain=${error.domain}, code=${error.code})")
+        return Promise.resolved(true)
+    }
+
+    /**
+     * iOS-primary forwarder. Android has **no** manual push-delivery API: the
+     * native SDK's own `FirebaseMessagingService` (shipped in `connect-push-fcm`)
+     * receives inbound messages and logs the PushReceived signal automatically.
+     * There is no sanctioned JS-forwarding entry point on Android — and outside
+     * Connect's push transport there is no registered device to attribute a
+     * PushReceived to — so this is a no-op that reports "handled". Kept for
+     * cross-platform API symmetry with iOS (where it forwards to the SDK in
+     * manual mode). Never rejects.
+     */
+    override fun pushDidReceiveNotification(userInfo: Map<String, Variant_Boolean_String_Double>): Promise<Boolean> {
+        Log.d(TAG, "[bridge] pushDidReceiveNotification: no-op on Android (native FCM service owns delivery + logging)")
+        return Promise.resolved(true)
+    }
+
+    /**
+     * iOS-primary forwarder. Tap (PushAction) handling on Android routes through
+     * the native SDK's `NotificationActionActivity`, so this is a no-op. Never
+     * rejects.
+     */
+    override fun pushDidReceiveResponse(
+        actionIdentifier: String,
+        userInfo: Map<String, Variant_Boolean_String_Double>,
+    ): Promise<Boolean> {
+        Log.d(TAG, "[bridge] pushDidReceiveResponse: no-op on Android (native SDK handles tap actions)")
+        return Promise.resolved(true)
+    }
+
+    /**
+     * No-op on Android. Permission state is auto-detected on every activity
+     * start by the SDK's ActivityLifecycleHandler, so an externally-supplied
+     * authorization result needs no forwarding. Kept for API symmetry with iOS
+     * (where it forwards to the native SDK). Never rejects.
+     */
+    override fun pushDidReceiveAuthorization(granted: Variant_NullType_Boolean?, error: PushErrorInfo?): Promise<Boolean> {
+        Log.d(TAG, "[bridge] pushDidReceiveAuthorization: no-op on Android (state self-heals via lifecycle)")
+        return Promise.resolved(true)
+    }
+
+    /**
+     * Requests the POST_NOTIFICATIONS permission. Delegates to
+     * [com.acoustic.connect.android.connectmod.push.PushApi.requestNotificationPermission],
+     * which fully manages the system dialog and the Activity Result registration,
+     * then resolves from its one-shot callback. On pre-TIRAMISU devices the SDK
+     * resolves `granted = true` immediately.
+     *
+     * **Never rejects.** If no foreground [ComponentActivity] is available, or
+     * the SDK call throws, it resolves `{ granted: false, error: <reason> }`.
+     *
+     * Intentionally NOT gated by [isConnectPushFcmAvailable]. The permission
+     * API ([PushApi]/`ConnectPush` and the `NotificationPermission*` classes)
+     * ships in the core `connect` artifact, which is always on the classpath —
+     * the `connect-push-fcm` variant pulls `connect` in transitively (see
+     * `android/build.gradle`). So `Connect.push` is a non-null core object, not
+     * a stub, and accessing it cannot raise `NoClassDefFoundError` from a
+     * missing FCM artifact. POST_NOTIFICATIONS is an OS-level concern that is
+     * meaningful regardless of whether FCM message delivery is bundled; gating
+     * it on the FCM probe would wrongly disable a working capability in
+     * analytics-only (`PushEnabled=false`) builds. The only FCM-adjacent path
+     * the SDK runs from here — `sendToken()` in the result callback — is itself
+     * guarded by the SDK's `isInitialized()` and no-ops when transport is absent.
+     */
+    override fun pushRequestPermission(): Promise<PushPermissionResult> {
+        val promise = Promise<PushPermissionResult>()
+        runOnMain {
+            // Re-read the foreground activity inside the main-looper block: it can
+            // change between the bridge call and this dispatch (e.g. a rotation /
+            // configuration change). Guard against a finishing or destroyed
+            // activity, not just null — handing such an activity to the SDK lets it
+            // register an ActivityResultLauncher whose result callback never fires,
+            // which would hang this Promise forever. Resolving deterministically
+            // here is preferable to a silent never-resolving Promise.
+            val activity = getCurrentActivity() as? ComponentActivity
+            if (activity == null || activity.isFinishing || activity.isDestroyed) {
+                Log.w(TAG, "[bridge] pushRequestPermission: no usable foreground ComponentActivity")
+                promise.resolve(
+                    PushPermissionResult(false, Variant_NullType_String.create("no-foreground-activity")),
+                )
+                return@runOnMain
+            }
+            try {
+                // The `granted` callback is always delivered on the main thread:
+                // either synchronously here (pre-TIRAMISU / already-granted paths,
+                // still on this looper) or via AndroidX ActivityResultRegistry,
+                // which dispatches results on the main thread. Promise.resolve is
+                // additionally thread-agnostic — it delegates to native, which
+                // marshals onto the JS thread — so resolution is safe regardless of
+                // the calling thread.
+                Connect.push.requestNotificationPermission(activity) { granted ->
+                    promise.resolve(PushPermissionResult(granted, null))
+                }
+            } catch (e: Exception) {
+                Log.w(TAG, "[bridge] pushRequestPermission: request failed — ${e.message}")
+                promise.resolve(
+                    PushPermissionResult(false, Variant_NullType_String.create(e.message ?: "permission-request-failed")),
+                )
+            }
+        }
+        return promise
+    }
+
+    /**
+     * Returns the current POST_NOTIFICATIONS permission as the cross-platform
+     * tri-state: `true` granted, `false` denied, `null` not yet
+     * determined. Maps [PushPermissionState] from the native SDK. Does not
+     * prompt. Never rejects — resolves `null` if the context is unavailable or
+     * the SDK call throws.
+     *
+     * Runs on the main looper (via [runOnMain]), matching every other
+     * `Connect.push.*` invocation in this bridge rather than executing on the
+     * Nitro bridge thread the HybridObject method is dispatched on. Besides
+     * keeping the threading contract consistent, this serialises the call with
+     * [pushRequestPermission]'s SDK callback: both ultimately touch the same
+     * notification-permission `SharedPreferences` store (the SDK's
+     * `getPushPermissionState` does a read-then-write to reconcile a
+     * Settings-side revocation), so funnelling both through main avoids an
+     * interleaved read/write across threads.
+     *
+     * Like [pushRequestPermission], this is intentionally NOT gated by
+     * [isConnectPushFcmAvailable] — the permission API lives in the core
+     * `connect` artifact (always on the classpath) and never touches the FCM
+     * transport classes, so there is no missing-artifact / stub-object risk.
+     */
+    override fun pushGetPermissionState(): Promise<Variant_NullType_Boolean> {
+        val promise = Promise<Variant_NullType_Boolean>()
+        runOnMain {
+            val context = applicationContext?.applicationContext
+            if (context == null) {
+                promise.resolve(Variant_NullType_Boolean.create(NullType.NULL))
+                return@runOnMain
+            }
+            try {
+                // Redundant against today's 3-value enum, but kept deliberately
+                // for forward-compatibility with future SDK enum values (see the
+                // `else` branch below), so silence the redundancy warning.
+                @Suppress("REDUNDANT_ELSE_IN_WHEN")
+                val triState = when (Connect.push.getPushPermissionState(context)) {
+                    PushPermissionState.GRANTED -> Variant_NullType_Boolean.create(true)
+                    PushPermissionState.DENIED -> Variant_NullType_Boolean.create(false)
+                    PushPermissionState.NOT_DETERMINED -> Variant_NullType_Boolean.create(NullType.NULL)
+                    // PushPermissionState is a Connect-SDK enum that may gain
+                    // values in a future release. An explicit `else` keeps this
+                    // forward-compatible: it avoids a compile break if the bridge
+                    // is rebuilt against an SDK with a new state, and replaces the
+                    // synthetic NoWhenBranchMatchedException (binary-incompat case:
+                    // bridge built against the old enum, run against a newer one)
+                    // with a deliberate fallback. Any unknown/new state maps to the
+                    // tri-state `null` ("not determined") — the safest default.
+                    else -> Variant_NullType_Boolean.create(NullType.NULL)
+                }
+                promise.resolve(triState)
+            } catch (e: Exception) {
+                Log.w(TAG, "[bridge] pushGetPermissionState: query failed — ${e.message}")
+                promise.resolve(Variant_NullType_Boolean.create(NullType.NULL))
+            }
+        }
+        return promise
+    }
+
+    // endregion
+
     /**
      * Checks whether the `connect-push-fcm` artifact is on the classpath and
      * logs the result. The artifact is gated by `Connect.PushEnabled` in
      * `ConnectConfig.json` via `android/build.gradle`'s conditional
      * `implementation` clause. A missing artifact when `PushEnabled` was set
      * to true points at a build-pipeline issue (didn't run `config.gradle`
-     * or the conditional didn't fire). Once CA-137698 lands the actual
-     * Connect push API on Android, this method also gates the wire-up.
+     * or the conditional didn't fire). This method also gates the push
+     * wire-up against the resolved Connect push API on Android.
      */
     private fun logResolvedPushAvailability() {
         val pushAvailable = isConnectPushFcmAvailable()
         Log.i(TAG, "[config] connect-push-fcm on classpath: $pushAvailable")
         if (!pushAvailable) {
-            Log.i(TAG, "[config] Push is not active on Android in this build. To enable, set Connect.PushEnabled=true in ConnectConfig.json and re-sync Gradle to include connect-push-fcm. Token forwarding wires in CA-137698.")
+            Log.i(TAG, "[config] Push is not active on Android in this build. To enable, set Connect.PushEnabled=true in ConnectConfig.json and re-sync Gradle to include connect-push-fcm.")
         }
     }
 
     private fun isConnectPushFcmAvailable(): Boolean {
         // Probe a known class shipped by the connect-push-fcm artifact. The
-        // exact class lives in the Connect Android SDK's push module and is
-        // finalised under CA-137698; this Class.forName probe is robust to
+        // exact class lives in the Connect Android SDK's push module. This
+        // Class.forName probe is robust to
         // package-name changes because it falls through silently when the
         // class is missing (which is the default in a no-push build).
         return try {
@@ -1067,10 +1274,11 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         const val DIALOG_CAPTURE_DELAY_MS = 500L // Configurable delay for dialog screenshot capture
 
         // Class probed at runtime to detect whether the connect-push-fcm
-        // artifact was included in the build. Conservative placeholder — the
-        // actual class name is finalised under CA-137698; if that ticket lands
-        // a different fully-qualified name, update this constant.
+        // transport artifact was included in the build (i.e. automatic mode,
+        // where Connect's own FirebaseMessagingService is the PushReceived
+        // sink). Points at the FCM messaging service shipped
+        // by the connect-push-fcm artifact.
         private const val CONNECT_PUSH_FCM_PROBE_CLASS =
-            "com.acoustic.connect.android.push.fcm.ConnectPushFcm"
+            "com.acoustic.connect.android.connectmod.push.services.fcm.FCMPushService"
     }
 }

package/ios/Bridge.h

@@ -7,7 +7,7 @@
 // prohibited.
 //
 //
-//  Created by Omar Hernandez on 5/9/25.
+//  Created on 5/9/25.
 //
 
 #pragma once

package/ios/HybridAcousticConnectRN.swift

@@ -7,7 +7,7 @@
 // prohibited.
 //
 //
-//  Created by Omar Hernandez on 5/9/25.
+//  Created on 5/9/25.
 //
 
 import Foundation
@@ -62,10 +62,39 @@ private enum ConnectConfigStore {
     }
 }
 
+// MARK: - Push adapter wrappers
+
+/// Bridges a JS-supplied `userInfo` dictionary to the SDK's `ConnectNotification`
+/// protocol (a single `userInfo` requirement).
+private struct HybridAcousticConnectNotification: ConnectNotification {
+    let userInfo: [AnyHashable: Any]
+
+    init(userInfo: [String: Any]) {
+        self.userInfo = userInfo.reduce(into: [AnyHashable: Any]()) { $0[$1.key] = $1.value }
+    }
+}
+
+/// Bridges a JS-supplied response to the SDK's `ConnectNotificationResponse`
+/// protocol (`actionIdentifier` + `userInfo`).
+private struct HybridAcousticConnectNotificationResponse: ConnectNotificationResponse {
+    let actionIdentifier: String
+    let userInfo: [AnyHashable: Any]
+
+    init(actionIdentifier: String, userInfo: [String: Any]) {
+        self.actionIdentifier = actionIdentifier
+        self.userInfo = userInfo.reduce(into: [AnyHashable: Any]()) { $0[$1.key] = $1.value }
+    }
+}
+
 class HybridAcousticConnectRN: HybridAcousticConnectRNSpec {
 
+    /// Push mode resolved from `ConnectConfig.json` at `load()` time. The push
+    /// bridge methods branch on this synchronously rather than calling into the
+    /// `@MainActor` SDK to detect mode (mirrors the Android bridge): manual mode
+    /// forwards events to the SDK; automatic/off surface `EAC-RN-007` (`false`).
+    ///
     // Constructor — auto-inits the SDK from `ConnectConfig.json`. Matches the
-    // pre-CA-137696 behaviour; consumers that need consent-gated init can call
+    // pre-existing auto-init behaviour; consumers that need consent-gated init can call
     // `disable()` immediately and `enable()` once they have permission.
     override init() {
         super.init()
@@ -304,6 +333,154 @@ class HybridAcousticConnectRN: HybridAcousticConnectRNSpec {
         return true
     }
 
+    // MARK: - Push: APNs lifecycle
+
+    /// Forwards the raw APNs device token to the SDK. Nitro hands us native
+    /// `Data` via `ArrayBuffer` — no hex conversion, no validation. Idempotent
+    /// in automatic mode (the SDK already captured the token via its swizzle).
+    ///
+    /// Resolves `true` once the SDK accepted the token, `false` if the call was
+    /// rejected (e.g. push not enabled). Never rejects.
+    func pushDidRegisterWithToken(deviceToken: ArrayBuffer) throws -> Promise<Bool> {
+        let token = deviceToken.toData(copyIfNeeded: true)
+        return Promise.async { @MainActor in
+            do {
+                try ConnectSDK.shared.push.didRegisterWithToken(token)
+                return true
+            } catch {
+                bridgeLog.error("pushDidRegisterWithToken failed: \(error.localizedDescription, privacy: .public)")
+                return false
+            }
+        }
+    }
+
+    /// Forwards an APNs registration failure to the SDK as an `NSError`.
+    /// Resolves `true` once forwarded, `false` on failure. Never rejects.
+    func pushDidFailToRegister(error: PushErrorInfo) throws -> Promise<Bool> {
+        let nsError = Self.nsError(from: error)
+        return Promise.async { @MainActor in
+            do {
+                try ConnectSDK.shared.push.didFailToRegisterWithError(nsError)
+                return true
+            } catch {
+                bridgeLog.error("pushDidFailToRegister failed: \(error.localizedDescription, privacy: .public)")
+                return false
+            }
+        }
+    }
+
+    // MARK: - Push: notification delivery — manual mode only
+
+    /// Forwards a received notification so the SDK logs `pushReceived` (manual
+    /// mode). Resolves `true` when processed. In automatic/off mode the SDK
+    /// throws `pushModeNotManual` (its own delegate already handles delivery);
+    /// the bridge catches it and resolves `false` — the `EAC-RN-007` surface.
+    /// Never rejects.
+    func pushDidReceiveNotification(userInfo: [String: Variant_Bool_String_Double]) throws -> Promise<Bool> {
+        let notification = HybridAcousticConnectNotification(userInfo: convertToAnyDictionary(input: userInfo))
+        return Promise.async { @MainActor in
+            do {
+                try ConnectSDK.shared.push.didReceiveNotification(notification)
+                return true
+            } catch {
+                bridgeLog.error("pushDidReceiveNotification failed: \(error.localizedDescription, privacy: .public)")
+                return false
+            }
+        }
+    }
+
+    /// Forwards a notification response (tap / action) so the SDK runs the
+    /// built-in action and logs `pushAction` (manual mode). Resolves `true` when
+    /// processed; `false` (EAC-RN-007) in automatic/off mode via the same
+    /// caught `pushModeNotManual`. Never rejects.
+    func pushDidReceiveResponse(actionIdentifier: String, userInfo: [String: Variant_Bool_String_Double]) throws -> Promise<Bool> {
+        let response = HybridAcousticConnectNotificationResponse(
+            actionIdentifier: actionIdentifier,
+            userInfo: convertToAnyDictionary(input: userInfo)
+        )
+        return Promise.async { @MainActor in
+            do {
+                try ConnectSDK.shared.push.didReceive(response)
+                return true
+            } catch {
+                bridgeLog.error("pushDidReceiveResponse failed: \(error.localizedDescription, privacy: .public)")
+                return false
+            }
+        }
+    }
+
+    // MARK: - Push: permission management
+
+    /// Forwards externally-obtained permission state to the SDK. Tri-state
+    /// `granted`: `true`/`false` forward; `nil` (notDetermined) is recorded by
+    /// the OS, not forwarded — the SDK has no notion of an "unknown" state.
+    func pushDidReceiveAuthorization(granted: Variant_NullType_Bool?, error: PushErrorInfo?) throws -> Promise<Bool> {
+        // `nil` (notDetermined) is intentionally not forwarded — the SDK has no
+        // notion of an "unknown" authorization. This resolves `true` ("handled —
+        // accepted, not forwarded"), not a failure.
+        guard let triState = granted?.asType(Bool.self) else {
+            return Promise.resolved(withResult: true)
+        }
+        // Not gated on push mode: the SDK's didReceiveAuthorization is safe in
+        // both modes, so externally-obtained permission state is always forwarded.
+        let nsError = error.map(Self.nsError(from:))
+        return Promise.async { @MainActor in
+            do {
+                try ConnectSDK.shared.push.didReceiveAuthorization(granted: triState, error: nsError)
+                return true
+            } catch {
+                bridgeLog.error("pushDidReceiveAuthorization failed: \(error.localizedDescription, privacy: .public)")
+                return false
+            }
+        }
+    }
+
+    /// Requests notification permission via the SDK, presenting the system
+    /// prompt when the status is undetermined, and resolves with the structured
+    /// result. Never rejects — a system error (or push-not-enabled) surfaces in
+    /// `error` with `granted: false`.
+    func pushRequestPermission() throws -> Promise<PushPermissionResult> {
+        return Promise.async { @MainActor in
+            do {
+                let result = try await ConnectSDK.shared.push.requestAuthorization()
+                let error: Variant_NullType_String? = result.error.map { .second($0.localizedDescription) }
+                return PushPermissionResult(granted: result.granted, error: error)
+            } catch {
+                bridgeLog.error("pushRequestPermission failed: \(error.localizedDescription, privacy: .public)")
+                return PushPermissionResult(granted: false, error: .second(error.localizedDescription))
+            }
+        }
+    }
+
+    /// Reads the current notification permission state without prompting, mapped
+    /// to a tri-state: `true` granted, `false` denied, `null` not determined.
+    /// Never rejects — push-not-enabled resolves as `null`.
+    func pushGetPermissionState() throws -> Promise<Variant_NullType_Bool> {
+        return Promise.async { @MainActor in
+            do {
+                if let granted = try await ConnectSDK.shared.push.getCurrentAuthorization() {
+                    return .second(granted)
+                }
+                return .first(.null)
+            } catch {
+                bridgeLog.error("pushGetPermissionState failed: \(error.localizedDescription, privacy: .public)")
+                return .first(.null)
+            }
+        }
+    }
+
+    // MARK: - Push: helpers
+
+    /// Builds an `NSError` from the structured bridge error object, shared by
+    /// `pushDidFailToRegister` and `pushDidReceiveAuthorization`.
+    private static func nsError(from info: PushErrorInfo) -> NSError {
+        NSError(
+            domain: info.domain ?? "ConnectRNBridge",
+            code: Int(info.code ?? -1),
+            userInfo: [NSLocalizedDescriptionKey: info.message]
+        )
+    }
+
     /// Sets the module's configuration item from AdvancedConfig.json or BasicConfig.plist that matches the specified key as a BOOL value.
     /// - Parameters:
     ///   - key: Key to update value in configuration settings.