@dashx/react-native 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.2] — 2026-04-22
+
+### Added
+- **`DashX.onPushNotificationReceived(callback)`** — new name for registering a foreground push listener. Same signature, same subscription shape; matches the `@dashx/browser` API so cross-platform apps using a Metro `.web.ts` wrapper can share the callsite.
+
+### Deprecated
+- **`DashX.onMessageReceived(callback)`** is now a deprecated alias of `onPushNotificationReceived` and logs a one-time `console.warn` on first call. The name leaked up from Android's Firebase `FirebaseMessagingService.onMessageReceived` override and was ambiguous in the DashX domain ("message" overloaded with `trackMessage` and in-app notifications). Scheduled for removal in the next major version.
+
 ## [1.3.1] — 2026-04-21
 
 ### Added

package/__tests__/index.test.js

@@ -310,20 +310,54 @@ describe('setLogLevel', () => {
   });
 });
 
-// --- onMessageReceived ---
+// --- onPushNotificationReceived ---
 
-describe('onMessageReceived', () => {
+describe('onPushNotificationReceived', () => {
   it('throws if callback is not a function', () => {
-    expect(() => DashX.onMessageReceived('not a function')).toThrow(
+    expect(() => DashX.onPushNotificationReceived('not a function')).toThrow(
       'callback must be a function'
     );
   });
 
   it('registers a listener for messageReceived events', () => {
+    const callback = jest.fn();
+    const subscription = DashX.onPushNotificationReceived(callback);
+    expect(mockAddListener).toHaveBeenCalledWith('messageReceived', callback);
+    expect(subscription).toBeDefined();
+  });
+});
+
+// --- onMessageReceived (deprecated alias) ---
+
+describe('onMessageReceived (deprecated)', () => {
+  let warnSpy;
+
+  beforeEach(() => {
+    warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  it('registers a listener and emits a deprecation warning on first call', () => {
     const callback = jest.fn();
     const subscription = DashX.onMessageReceived(callback);
     expect(mockAddListener).toHaveBeenCalledWith('messageReceived', callback);
     expect(subscription).toBeDefined();
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('onMessageReceived is deprecated')
+    );
+  });
+
+  it('warns only once across repeated calls', () => {
+    warnSpy.mockClear();
+    DashX.onMessageReceived(jest.fn());
+    DashX.onMessageReceived(jest.fn());
+    DashX.onMessageReceived(jest.fn());
+    // The first call across the whole test run already consumed the one-shot
+    // warning (from the previous test). No new warnings should fire.
+    expect(warnSpy).not.toHaveBeenCalled();
   });
 });
 

package/index.d.ts

@@ -165,9 +165,17 @@ export interface DashXInstance {
   setLogLevel(level: LogLevel): void;
 
   /**
-   * Register a listener for incoming push notification messages.
+   * Register a listener for incoming push notifications.
    * Returns a subscription that can be removed via `.remove()`.
    */
+  onPushNotificationReceived(
+    callback: (message: NotificationMessage) => void
+  ): EmitterSubscription;
+
+  /**
+   * @deprecated Use `onPushNotificationReceived` instead.
+   * Will be removed in the next major version.
+   */
   onMessageReceived(
     callback: (message: NotificationMessage) => void
   ): EmitterSubscription;

package/index.js

@@ -29,6 +29,8 @@ function getNativeDashX() {
   return _nativeDashX;
 }
 
+let _onMessageReceivedDeprecationWarned = false;
+
 let _eventEmitter = null;
 function getEventEmitter() {
   if (!_eventEmitter) {
@@ -142,13 +144,25 @@ const DashX = {
     return getNativeDashX().setLogLevel(level);
   },
 
-  onMessageReceived(callback) {
+  onPushNotificationReceived(callback) {
     if (typeof callback !== 'function') {
-      throw new Error('DashX.onMessageReceived: callback must be a function');
+      throw new Error(
+        'DashX.onPushNotificationReceived: callback must be a function'
+      );
     }
     return getEventEmitter().addListener('messageReceived', callback);
   },
 
+  onMessageReceived(callback) {
+    if (!_onMessageReceivedDeprecationWarned) {
+      console.warn(
+        'DashX.onMessageReceived is deprecated and will be removed in the next major version. Use DashX.onPushNotificationReceived instead.'
+      );
+      _onMessageReceivedDeprecationWarned = true;
+    }
+    return DashX.onPushNotificationReceived(callback);
+  },
+
   uploadAsset(filePath, resource, attribute) {
     if (!filePath || typeof filePath !== 'string') {
       throw new Error('DashX.uploadAsset: filePath must be a string');

package/package.json

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