@dashx/react-native 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+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.3.0] — 2026-04-20
+
+### Breaking
+- **`DashX` pod → `DashX/SDK`.** The podspec now depends on the `DashX/SDK` subspec of [dashx-ios 1.3.1+](https://github.com/dashxhq/dashx-ios) with no version constraint. Consumers must update their Podfile:
+  ```ruby
+  # before
+  pod 'DashX', :git => 'https://github.com/dashxhq/dashx-ios.git', :tag => '1.1.9'
+
+  # after
+  pod 'DashX/SDK', :git => 'https://github.com/dashxhq/dashx-ios.git', :tag => '1.3.1'
+  ```
+- **`FirebaseMessaging` is now a hard dependency.** Previously the bridge guarded Firebase usage with `#if canImport(FirebaseMessaging)`, but `canImport` doesn't see consumer-Podfile pods at this pod's compile time, so the guard silently elided every FCM code path — push registration stopped working on fresh installs. Consumers must enable modular headers in their Podfile:
+  ```ruby
+  use_modular_headers!
+  # or, per-pod:
+  pod 'FirebaseMessaging', :modular_headers => true
+  ```
+
+### Added
+- `DashX.onNotificationClicked(callback)` — fires when the user taps a DashX notification or one of its action buttons. Callback receives `{ notification, action, actionIdentifier }` where `action` is a resolved `NavigationAction` (`deepLink` / `screen` / `richLanding` / `clickAction`) or `null`.
+- `DashXNotificationResponseResult.navigationAction` — new Swift-only field on the helper result type returned by `DashXNotificationHandler.handleNotificationResponse(_:)`.
+- `NotificationClickedEvent` exported from `index.d.ts`.
+
+### Fixed
+- **iOS dev builds silently failing to receive pushes.** `Messaging.messaging().setAPNSToken(_, type: .unknown)` sometimes mis-tagged the APNs environment on dev-signed binaries, producing an FCM token whose pushes 410'd at Apple. The bridge now forces `.sandbox` in `DEBUG` configurations and `.prod` otherwise.
+- **`DashX.setIdentity(uid, token)` now passes `null` / `""` / `undefined` through to the native SDK unchanged** (apart from normalizing `undefined → null`, since the RN bridge can't carry `undefined`). Previously the JS wrapper threw on `null` / `""` / `undefined` for `uid`, contradicting the nullable signatures on iOS (`NSString?`) and Android (`String?`). TypeScript signature updated: `setIdentity(uid: string | null, token?: string | null): void`.
+
+## [1.2.0] — 2026-04-16
+
+Previous release — see git log.

package/DashXReactNative.podspec

@@ -21,8 +21,15 @@ Pod::Spec.new do |s|
   install_modules_dependencies(s)
 
   # DashX iOS SDK — consumers must provide the source in their Podfile:
-  #   pod 'DashX', :git => 'https://github.com/dashxhq/dashx-ios.git', :tag => '1.1.9'
+  #   pod 'DashX/SDK', :git => 'https://github.com/dashxhq/dashx-ios.git', :tag => '1.3.1'
   # For local development:
   #   pod 'DashX', :path => '../dashx-ios'
-  s.dependency "DashX", "~> 1.1.9"
+  s.dependency "DashX/SDK"
+
+  # Hard dependency so that `canImport(FirebaseMessaging)`
+  # evaluates at this pod's compile time, where consumer-Podfile pods aren't
+  # visible — so an "optional" guard silently elides every Firebase code path.
+  # Consumers should set `use_modular_headers!` (or `:modular_headers => true`
+  # on FirebaseMessaging) in their Podfile so this Swift import resolves.
+  s.dependency "FirebaseMessaging"
 end

package/__tests__/index.test.js

@@ -106,8 +106,25 @@ describe('setIdentity', () => {
     );
   });
 
-  it('throws if uid is missing', () => {
-    expect(() => DashX.setIdentity(null, 'token')).toThrow('uid is required');
+  it('passes null uid through to native', () => {
+    DashX.setIdentity(null, 'token');
+    expect(mockNativeModule.setIdentity).toHaveBeenCalledWith(null, 'token');
+  });
+
+  it('normalizes undefined uid to null', () => {
+    DashX.setIdentity(undefined, 'token');
+    expect(mockNativeModule.setIdentity).toHaveBeenCalledWith(null, 'token');
+  });
+
+  it('passes empty-string uid through to native without coercing to null', () => {
+    DashX.setIdentity('', 'token');
+    expect(mockNativeModule.setIdentity).toHaveBeenCalledWith('', 'token');
+  });
+
+  it('throws if uid is not a string or null', () => {
+    expect(() => DashX.setIdentity(42, 'token')).toThrow(
+      'uid must be a string or null'
+    );
   });
 
   it('passes null token through to native', () => {
@@ -115,10 +132,21 @@ describe('setIdentity', () => {
     expect(mockNativeModule.setIdentity).toHaveBeenCalledWith('uid', null);
   });
 
+  it('passes empty-string token through to native without coercing to null', () => {
+    DashX.setIdentity('uid', '');
+    expect(mockNativeModule.setIdentity).toHaveBeenCalledWith('uid', '');
+  });
+
   it('passes undefined token as null to native', () => {
     DashX.setIdentity('uid');
     expect(mockNativeModule.setIdentity).toHaveBeenCalledWith('uid', null);
   });
+
+  it('throws if token is not a string or null', () => {
+    expect(() => DashX.setIdentity('uid', 42)).toThrow(
+      'token must be a string or null'
+    );
+  });
 });
 
 // --- reset ---

package/index.d.ts

@@ -74,6 +74,12 @@ export type NavigationAction =
   | { type: 'richLanding'; url: string }
   | { type: 'clickAction'; action: string };
 
+export interface NotificationClickedEvent {
+  notification: NotificationMessage;
+  action: NavigationAction | null;
+  actionIdentifier: string;
+}
+
 export interface ProcessURLOptions {
   source?: string;
   forwardToLinkHandler?: boolean;
@@ -92,9 +98,11 @@ export interface DashXInstance {
   identify(options: IdentifyOptions): void;
 
   /**
-   * Set user identity using a UID and authentication token.
+   * Set user identity using a UID and authentication token. Both are
+   * nullable — passing `null` clears that field on the native SDK. Empty
+   * strings are forwarded as-is (no coercion to `null`).
    */
-  setIdentity(uid: string, token?: string | null): void;
+  setIdentity(uid: string | null, token?: string | null): void;
 
   /**
    * Clear the current user identity and reset SDK state.
@@ -224,6 +232,18 @@ export interface DashXInstance {
    * Returns a subscription that can be removed via `.remove()`.
    */
   onLinkReceived(callback: (url: string) => void): EmitterSubscription;
+
+  /**
+   * Register a listener for notification tap events. Fired when the user taps
+   * a DashX notification or one of its action buttons. The callback receives
+   * the full notification payload, the resolved `NavigationAction` (parsed
+   * from the payload; `null` if no navigation intent could be resolved), and
+   * the raw `actionIdentifier` from `UNNotificationResponse`.
+   * Returns a subscription that can be removed via `.remove()`.
+   */
+  onNotificationClicked(
+    callback: (event: NotificationClickedEvent) => void
+  ): EmitterSubscription;
 }
 
 declare const DashX: DashXInstance;

package/index.js

@@ -58,12 +58,16 @@ const DashX = {
   },
 
   setIdentity(uid, token) {
-    if (!uid || typeof uid !== 'string') {
-      throw new Error(
-        'DashX.setIdentity: uid is required and must be a string'
-      );
+    // Both uid and token are nullable passthroughs to the native SDK. Only
+    // validate TYPE here — the native side decides semantics. `undefined` is
+    // normalized to `null` because the RN bridge can't carry undefined.
+    if (uid !== null && uid !== undefined && typeof uid !== 'string') {
+      throw new Error('DashX.setIdentity: uid must be a string or null');
+    }
+    if (token !== null && token !== undefined && typeof token !== 'string') {
+      throw new Error('DashX.setIdentity: token must be a string or null');
     }
-    return getNativeDashX().setIdentity(uid, token || null);
+    return getNativeDashX().setIdentity(uid ?? null, token ?? null);
   },
 
   reset() {
@@ -214,6 +218,15 @@ const DashX = {
     }
     return getEventEmitter().addListener('linkReceived', callback);
   },
+
+  onNotificationClicked(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error(
+        'DashX.onNotificationClicked: callback must be a function'
+      );
+    }
+    return getEventEmitter().addListener('notificationClicked', callback);
+  },
 };
 
 export default DashX;

package/ios/DashXNotificationHandler.swift

@@ -2,9 +2,7 @@ import Foundation
 import UIKit
 import UserNotifications
 import DashX
-#if canImport(FirebaseMessaging)
 import FirebaseMessaging
-#endif
 
 /// The result of handling a notification response.
 /// Consumers can use `url` to navigate and `actionIdentifier` for custom action handling.
@@ -14,11 +12,15 @@ public final class DashXNotificationResponseResult: NSObject {
     @objc public let actionIdentifier: String
     /// The DashX notification URL, if present in the payload.
     @objc public let url: URL?
+    /// The resolved navigation intent for the tap / action button.
+    /// Non-@objc (the enum isn't representable in Obj-C); read via Swift.
+    public let navigationAction: NavigationAction?
 
-    init(userInfo: [AnyHashable: Any], actionIdentifier: String, url: URL?) {
+    init(userInfo: [AnyHashable: Any], actionIdentifier: String, url: URL?, navigationAction: NavigationAction?) {
         self.userInfo = userInfo
         self.actionIdentifier = actionIdentifier
         self.url = url
+        self.navigationAction = navigationAction
     }
 }
 
@@ -30,9 +32,7 @@ public final class DashXNotificationHandler: NSObject {
         userInfo: [AnyHashable: Any],
         completionHandler: @escaping (UIBackgroundFetchResult) -> Void
     ) {
-        #if canImport(FirebaseMessaging)
         Messaging.messaging().appDidReceiveMessage(userInfo)
-        #endif
 
         DashXEventEmitter.instance.dispatch(
             name: "messageReceived",
@@ -88,9 +88,7 @@ public final class DashXNotificationHandler: NSObject {
     public static func handleNotificationResponse(_ response: UNNotificationResponse) -> DashXNotificationResponseResult {
         let userInfo = response.notification.request.content.userInfo
 
-        #if canImport(FirebaseMessaging)
         Messaging.messaging().appDidReceiveMessage(userInfo)
-        #endif
 
         DashXEventEmitter.instance.dispatch(
             name: "messageReceived",
@@ -104,11 +102,25 @@ public final class DashXNotificationHandler: NSObject {
         }
 
         let notificationUrl = userInfo.dashxNotificationUrl()
+        let dashxData = userInfo.dashxNotificationData()
+        let navigationAction = dashxData?.navigationAction(forActionIdentifier: response.actionIdentifier)
+
+        if response.actionIdentifier != UNNotificationDismissActionIdentifier {
+            DashXEventEmitter.instance.dispatch(
+                name: "notificationClicked",
+                body: [
+                    "notification": bridgeSafePayload(from: userInfo),
+                    "action": jsonDictionary(from: navigationAction) ?? NSNull(),
+                    "actionIdentifier": response.actionIdentifier,
+                ]
+            )
+        }
 
         return DashXNotificationResponseResult(
             userInfo: userInfo,
             actionIdentifier: response.actionIdentifier,
-            url: notificationUrl
+            url: notificationUrl,
+            navigationAction: navigationAction
         )
     }
 
@@ -119,14 +131,21 @@ public final class DashXNotificationHandler: NSObject {
     /// `application(_:didRegisterForRemoteNotificationsWithDeviceToken:)`.
     @objc
     public static func handleDeviceToken(_ deviceToken: Data) {
-        #if canImport(FirebaseMessaging)
-        Messaging.messaging().setAPNSToken(deviceToken, type: .unknown)
+        // Force the APNs environment explicitly rather than using `.unknown`
+        // (auto-detect). Firebase's auto-detection reads the token's aps
+        // entitlement from the signed binary and sometimes mis-tags dev
+        // builds as production, producing an FCM token whose pushes silently
+        // fail at APNs with 410 Unregistered.
+        #if DEBUG
+        Messaging.messaging().setAPNSToken(deviceToken, type: .sandbox)
+        #else
+        Messaging.messaging().setAPNSToken(deviceToken, type: .prod)
+        #endif
         Messaging.messaging().token { token, error in
             if let token = token {
                 DashX.setFCMToken(to: token)
             }
         }
-        #endif
     }
 
     // MARK: - Foreground Notification
@@ -142,9 +161,7 @@ public final class DashXNotificationHandler: NSObject {
     ) {
         let userInfo = notification.request.content.userInfo
 
-        #if canImport(FirebaseMessaging)
         Messaging.messaging().appDidReceiveMessage(userInfo)
-        #endif
 
         DashX.trackMessage(message: userInfo, event: .delivered)
 
@@ -197,6 +214,24 @@ public final class DashXNotificationHandler: NSObject {
         task.resume()
     }
 
+    /// Serializes a ``NavigationAction`` into the JS-bridge shape mirrored by
+    /// `NavigationAction` in `index.d.ts`. Returns `nil` for `nil` input.
+    private static func jsonDictionary(from action: NavigationAction?) -> [String: Any]? {
+        guard let action else { return nil }
+        switch action {
+        case .deepLink(let url):
+            return ["type": "deepLink", "url": url.absoluteString]
+        case .screen(let name, let data):
+            var dict: [String: Any] = ["type": "screen", "name": name]
+            if let data { dict["data"] = data }
+            return dict
+        case .richLanding(let url):
+            return ["type": "richLanding", "url": url.absoluteString]
+        case .clickAction(let actionString):
+            return ["type": "clickAction", "action": actionString]
+        }
+    }
+
     private static func bridgeSafePayload(from userInfo: [AnyHashable: Any]) -> [String: Any] {
         userInfo.reduce(into: [String: Any]()) { result, pair in
             let key = String(describing: pair.key)

package/ios/DashXReactNative.swift

@@ -16,7 +16,7 @@ class DashXReactNative: RCTEventEmitter {
     }
 
     override func supportedEvents() -> [String] {
-        return ["messageReceived", "linkReceived"]
+        return ["messageReceived", "linkReceived", "notificationClicked"]
     }
 
     @objc(configure:)

package/package.json

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