@dashx/react-native 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to `@dashx/react-native` are documented in this file. Format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follow [SemVer](https://semver.org/).
 
+## [1.4.1] — 2026-05-06
+
+### Required upgrade steps
+
+1. **Bump the dashx-ios pod tag to 1.5.1 in your `ios/Podfile`** — `pod install` will refuse the upgrade otherwise (the podspec floor is now `>= 1.5.1`):
+
+   ```ruby
+   pod 'DashX/SDK', :git => 'https://github.com/dashxhq/dashx-ios.git', :tag => '1.5.1'
+   ```
+
+   The floor is required because earlier dashx-ios versions either fall back to silent-push on the backend (pre-1.3.0, throttled by iOS) or omit `.timeSensitive` from the authorization request (pre-1.5.1, causing `interruption-level: time-sensitive` payloads to silently downgrade and stay filterable by Focus / Reduce Interruptions / Scheduled Summary on iOS 18 / 26).
+
+2. **Wire `fallbackToSettings: true` somewhere in your permission UI** to recover existing iOS users — fresh installs are auto-fixed by the upgrade, but users who already granted notification permission under the old SDK keep an `.authorized` state without the time-sensitive entitlement, and Apple's `requestAuthorization` is a one-shot grant that can't be silently upgraded. They have to flip the **Time Sensitive Notifications** toggle in iOS Settings themselves.
+
+   ```js
+   // From a "Notifications acting up?" affordance, or as a one-time
+   // post-upgrade prompt:
+   await DashX.requestNotificationPermission({ fallbackToSettings: true });
+   ```
+
+   When the user is already determined (granted or denied on iOS / permanently denied on Android), this opens the system notification settings page instead of firing a futile `requestAuthorization`. Without this step, your existing iOS users will keep experiencing the original "intermittent / second attempt works" symptom even after upgrading to 1.4.1.
+
+### Migration
+
+- **Consumers who subclass `DashXReactNativeModuleImpl`** and override `requestNotificationPermission(promise:)` need to update the override signature to `requestNotificationPermission(fallbackToSettings: Boolean, promise: Promise)`. Otherwise Kotlin's override resolution silently drops to the impl's version and your custom logic stops running. Same applies to anyone subclassing the new-arch / old-arch `DashXReactNativeModule` wrappers. Most consumers don't subclass these — flagged here for the few that do.
+
+### Added
+
+- **`DashX.requestNotificationPermission({ fallbackToSettings })`.** Optional flag, default `false`. When `true`, the SDK detects platform-specific dead-ends and opens the system notification-settings page instead of firing a futile prompt:
+  - **iOS** — already granted or denied (iOS no-ops `requestAuthorization` in that state).
+  - **Android** — `POST_NOTIFICATIONS` permanently denied (Android 13+, two-strikes rule). `requestPermissions()` auto-resolves DENIED without UI in that state.
+
+  Existing call sites (`DashX.requestNotificationPermission()` with no arguments) compile and behave unchanged.
+
+### Fixed
+
+- **Foreground push duplicate-display race in `DashXNotificationHandler.handleRemoteNotification`.** Now short-circuits when the payload already carries `aps.alert`, letting iOS render the notification natively via NSE / `willPresent` instead of racing a duplicate `UNUserNotificationCenter.add(...)` against it. Without the short-circuit the local re-add could clobber the NSE-attached image or briefly flicker on screen.
+- **Suspension race in the image-attached reconstruction path.** The `fetchCompletionHandler` now fires only after the async image download and the local `add()` both complete, with a 25-second budget under iOS's background-push limit. Previously the handler fired immediately while the download was still in flight, letting iOS suspend the process before the notification actually displayed.
+
 ## [1.4.0] — 2026-04-27
 
 ### Changed

package/DashXReactNative.podspec

@@ -21,10 +21,16 @@ Pod::Spec.new do |s|
   install_modules_dependencies(s)
 
   # DashX iOS SDK — consumers must provide the source in their Podfile:
-  #   pod 'DashX/SDK', :git => 'https://github.com/dashxhq/dashx-ios.git', :tag => '1.5.0'
+  #   pod 'DashX/SDK', :git => 'https://github.com/dashxhq/dashx-ios.git', :tag => '1.5.1'
   # For local development:
   #   pod 'DashX', :path => '../dashx-ios'
-  s.dependency "DashX/SDK"
+  #
+  # Floor of 1.5.1 — earlier versions either fall back to silent-push on the
+  # backend (pre-1.3.0, which iOS throttles aggressively) or omit the
+  # `.timeSensitive` authorization option (pre-1.5.1, which causes
+  # `interruption-level: time-sensitive` payloads to silently downgrade to
+  # `active` on iOS 18 / 26 and stay subject to Focus / Summary filtering).
+  s.dependency "DashX/SDK", ">= 1.5.1"
 
   # Hard dependency so that `canImport(FirebaseMessaging)`
   # evaluates at this pod's compile time, where consumer-Podfile pods aren't

package/android/src/main/java/com/dashx/rn/sdk/DashXReactNativeModuleImpl.kt

@@ -5,8 +5,10 @@ import android.app.Activity
 import android.app.NotificationChannel
 import android.app.NotificationManager
 import android.content.Context
+import android.content.Intent
 import android.content.pm.PackageManager
 import android.os.Build
+import android.provider.Settings
 import androidx.core.app.ActivityCompat
 import androidx.core.content.ContextCompat
 import com.dashx.rn.sdk.util.*
@@ -330,7 +332,7 @@ class DashXReactNativeModuleImpl(private val reactContext: ReactApplicationConte
         )
     }
 
-    fun requestNotificationPermission(promise: Promise) {
+    fun requestNotificationPermission(fallbackToSettings: Boolean, promise: Promise) {
         if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
             promise.resolve(PERMISSION_AUTHORIZED)
             return
@@ -345,14 +347,36 @@ class DashXReactNativeModuleImpl(private val reactContext: ReactApplicationConte
             return
         }
 
-        val activity = reactContext.currentActivity as? PermissionAwareActivity
+        val activity = reactContext.currentActivity
         if (activity == null) {
             promise.reject(E_UNSPECIFIED, "No current activity to request permission from")
             return
         }
 
-        reactContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
-            .edit()
+        // "Permanently denied" detection on Android 13+: we asked at least
+        // once before AND the system says we shouldn't show a rationale.
+        // In that state `requestPermissions()` auto-resolves DENIED without
+        // any UI, so re-prompting is futile — Settings is the only path.
+        val prefs = reactContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        val previouslyRequested = prefs.getBoolean(KEY_PERMISSION_REQUESTED, false)
+        val permanentlyDenied = previouslyRequested && !ActivityCompat.shouldShowRequestPermissionRationale(
+            activity,
+            Manifest.permission.POST_NOTIFICATIONS
+        )
+
+        if (fallbackToSettings && permanentlyDenied) {
+            openAppNotificationSettings()
+            promise.resolve(PERMISSION_DENIED)
+            return
+        }
+
+        val permAwareActivity = activity as? PermissionAwareActivity
+        if (permAwareActivity == null) {
+            promise.reject(E_UNSPECIFIED, "Activity does not support permission requests")
+            return
+        }
+
+        prefs.edit()
             .putBoolean(KEY_PERMISSION_REQUESTED, true)
             .apply()
 
@@ -363,13 +387,21 @@ class DashXReactNativeModuleImpl(private val reactContext: ReactApplicationConte
             true
         }
 
-        activity.requestPermissions(
+        permAwareActivity.requestPermissions(
             arrayOf(Manifest.permission.POST_NOTIFICATIONS),
             NOTIFICATION_PERMISSION_REQUEST_CODE,
             listener
         )
     }
 
+    private fun openAppNotificationSettings() {
+        val intent = Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS).apply {
+            putExtra(Settings.EXTRA_APP_PACKAGE, reactContext.packageName)
+            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        }
+        reactContext.startActivity(intent)
+    }
+
     fun getNotificationPermissionStatus(promise: Promise) {
         if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
             promise.resolve(PERMISSION_AUTHORIZED)

package/android/src/newarch/java/com/dashx/rn/sdk/DashXReactNativeModule.kt

@@ -69,8 +69,8 @@ class DashXReactNativeModule(reactContext: ReactApplicationContext) :
 
     override fun fetchAsset(assetId: String, promise: Promise) = impl.fetchAsset(assetId, promise)
 
-    override fun requestNotificationPermission(promise: Promise) =
-        impl.requestNotificationPermission(promise)
+    override fun requestNotificationPermission(fallbackToSettings: Boolean, promise: Promise) =
+        impl.requestNotificationPermission(fallbackToSettings, promise)
 
     override fun getNotificationPermissionStatus(promise: Promise) =
         impl.getNotificationPermissionStatus(promise)

package/android/src/oldarch/java/com/dashx/rn/sdk/DashXReactNativeModule.kt

@@ -87,8 +87,8 @@ class DashXReactNativeModule(reactContext: ReactApplicationContext) :
     fun fetchAsset(assetId: String, promise: Promise) = impl.fetchAsset(assetId, promise)
 
     @ReactMethod
-    fun requestNotificationPermission(promise: Promise) =
-        impl.requestNotificationPermission(promise)
+    fun requestNotificationPermission(fallbackToSettings: Boolean, promise: Promise) =
+        impl.requestNotificationPermission(fallbackToSettings, promise)
 
     @ReactMethod
     fun getNotificationPermissionStatus(promise: Promise) =

package/index.d.ts

@@ -235,9 +235,19 @@ export interface DashXInstance {
 
   /**
    * Request push notification permission from the user.
+   *
+   * @param options.fallbackToSettings — when `true`, if the user has previously
+   *   granted or denied permission, opens the system notification settings
+   *   page so they can enable Time Sensitive notifications (or re-enable
+   *   notifications). Defaults to `false`. Use this to recover users who
+   *   granted permission before the SDK started requesting `.timeSensitive`,
+   *   since iOS won't silently add new options to an existing grant.
+   *
    * Resolves with a NotificationPermissionStatus integer.
    */
-  requestNotificationPermission(): Promise<NotificationPermissionStatus>;
+  requestNotificationPermission(options?: {
+    fallbackToSettings?: boolean
+  }): Promise<NotificationPermissionStatus>;
 
   /**
    * Get the current push notification permission status without prompting.

package/index.js

@@ -218,8 +218,9 @@ const DashX = {
     );
   },
 
-  requestNotificationPermission() {
-    return getNativeDashX().requestNotificationPermission();
+  requestNotificationPermission(options) {
+    const fallbackToSettings = Boolean(options && options.fallbackToSettings);
+    return getNativeDashX().requestNotificationPermission(fallbackToSettings);
   },
 
   getNotificationPermissionStatus() {

package/ios/DashXNotificationHandler.swift

@@ -39,6 +39,15 @@ public final class DashXNotificationHandler: NSObject {
             body: bridgeSafePayload(from: userInfo)
         )
 
+        // Alert pushes (aps.alert present) are displayed by iOS directly via
+        // the Notification Service Extension. Skipping the silent-push
+        // reconstruction prevents a duplicate `add()` from racing the
+        // system-displayed banner and clobbering its NSE-attached image.
+        if let aps = userInfo["aps"] as? [AnyHashable: Any], aps["alert"] != nil {
+            completionHandler(.newData)
+            return
+        }
+
         guard let dashxData = userInfo.dashxNotificationData() else {
             completionHandler(.noData)
             return
@@ -74,13 +83,42 @@ public final class DashXNotificationHandler: NSObject {
         )
         UNUserNotificationCenter.current().setNotificationCategories([category])
 
+        // Defer the completion handler until after the local notification has
+        // actually been added. iOS suspends the process the moment we call
+        // `completionHandler`, so firing it before the async download + add
+        // chain finishes was dropping notifications mid-flight. The 25s budget
+        // sits comfortably under iOS's ~30s background-push limit.
+        let fire = makeOnceFire(completionHandler)
+        DispatchQueue.main.asyncAfter(deadline: .now() + .seconds(25)) {
+            fire(.newData)
+        }
+
         if let imagePath = dashxData.image, let imageURL = URL(string: imagePath) {
-            createNotificationWithImage(id: dashxData.id, imageURL: imageURL, content: content)
+            createNotificationWithImage(id: dashxData.id, imageURL: imageURL, content: content) {
+                fire(.newData)
+            }
         } else {
-            createNotification(id: dashxData.id, content: content)
+            createNotification(id: dashxData.id, content: content) {
+                fire(.newData)
+            }
         }
+    }
 
-        completionHandler(.newData)
+    /// Wraps `completionHandler` so it can be invoked safely from any of the
+    /// (download done) / (add done) / (timeout) callbacks — second invocation
+    /// is a no-op.
+    private static func makeOnceFire(
+        _ completionHandler: @escaping (UIBackgroundFetchResult) -> Void
+    ) -> (UIBackgroundFetchResult) -> Void {
+        let lock = NSLock()
+        var fired = false
+        return { result in
+            lock.lock()
+            defer { lock.unlock() }
+            guard !fired else { return }
+            fired = true
+            completionHandler(result)
+        }
     }
 
     @objc
@@ -175,23 +213,29 @@ public final class DashXNotificationHandler: NSObject {
 
     // MARK: - Private Helpers
 
-    private static func createNotification(id: String, content: UNMutableNotificationContent) {
+    private static func createNotification(
+        id: String,
+        content: UNMutableNotificationContent,
+        completion: @escaping () -> Void
+    ) {
         let request = UNNotificationRequest(identifier: id, content: content, trigger: nil)
         UNUserNotificationCenter.current().add(request) { error in
             if let error = error {
                 DashXLog.d(tag: #function, "Failed to schedule notification: \(error.localizedDescription)")
             }
+            completion()
         }
     }
 
     private static func createNotificationWithImage(
         id: String,
         imageURL: URL,
-        content: UNMutableNotificationContent
+        content: UNMutableNotificationContent,
+        completion: @escaping () -> Void
     ) {
         let task = URLSession.shared.downloadTask(with: imageURL) { location, _, error in
             guard let location = location, error == nil else {
-                createNotification(id: id, content: content)
+                createNotification(id: id, content: content, completion: completion)
                 return
             }
 
@@ -206,10 +250,10 @@ public final class DashXNotificationHandler: NSObject {
                     options: nil
                 )
                 content.attachments = [attachment]
-                createNotification(id: id, content: content)
             } catch {
-                createNotification(id: id, content: content)
+                // fall through with no attachment
             }
+            createNotification(id: id, content: content, completion: completion)
         }
         task.resume()
     }

package/ios/DashXReactNative.mm

@@ -55,7 +55,7 @@ RCT_EXTERN_METHOD(processURL:(NSString *)url source:(NSString * _Nullable)source
 
 RCT_EXTERN_METHOD(trackNotificationNavigation:(NSDictionary * _Nullable)action notificationId:(NSString * _Nullable)notificationId);
 
-RCT_EXTERN_METHOD(requestNotificationPermission:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject);
+RCT_EXTERN_METHOD(requestNotificationPermission:(BOOL)fallbackToSettings resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject);
 
 RCT_EXTERN_METHOD(getNotificationPermissionStatus:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject);
 

package/ios/DashXReactNative.swift

@@ -232,9 +232,9 @@ class DashXReactNative: RCTEventEmitter {
         DashX.trackNotificationNavigation(navigationAction, notificationId: notificationId as String?)
     }
 
-    @objc(requestNotificationPermission:reject:)
-    func requestNotificationPermission(_ resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
-        DashX.requestNotificationPermission { status in resolve(status.rawValue) }
+    @objc(requestNotificationPermission:resolve:reject:)
+    func requestNotificationPermission(_ fallbackToSettings: Bool, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+        DashX.requestNotificationPermission(fallbackToSettings: fallbackToSettings) { status in resolve(status.rawValue) }
     }
 
     @objc(getNotificationPermissionStatus:reject:)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dashx/react-native",
   "title": "DashX React Native",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "DashX SDK for React Native",
   "main": "index.js",
   "types": "index.d.ts",

package/src/NativeDashXReactNative.ts

@@ -32,7 +32,7 @@ export interface Spec extends TurboModule {
     action: Object | null,
     notificationId: string | null
   ): void;
-  requestNotificationPermission(): Promise<number>;
+  requestNotificationPermission(fallbackToSettings: boolean): Promise<number>;
   getNotificationPermissionStatus(): Promise<number>;
 
   addListener(eventName: string): void;