react-native-notify-kit 9.2.1 → 9.4.0

package/ios/RNNotifee/NotifeeApiModule.mm

@@ -28,6 +28,9 @@ static NSInteger kReactNativeNotifeeNotificationTypeTrigger = 2;
 static NSInteger kReactNativeNotifeeNotificationTypeAll = 0;
 
 @implementation NotifeeApiModule {
+  // Guarded by @synchronized(self): didReceiveNotifeeCoreEvent: may be called
+  // from arbitrary threads (UNUserNotificationCenter callbacks), while
+  // startObserving/stopObserving/sendNotifeeCoreEvent: run on the main thread.
   bool hasListeners;
   NSMutableArray *pendingCoreEvents;
 }
@@ -53,15 +56,21 @@ RCT_EXPORT_MODULE();
 }
 
 - (void)startObserving {
-  hasListeners = YES;
-  for (NSDictionary *eventBody in pendingCoreEvents) {
+  NSArray *eventsToFlush;
+  @synchronized(self) {
+    hasListeners = YES;
+    eventsToFlush = [pendingCoreEvents copy];
+    [pendingCoreEvents removeAllObjects];
+  }
+  for (NSDictionary *eventBody in eventsToFlush) {
     [self sendNotifeeCoreEvent:eventBody];
   }
-  [pendingCoreEvents removeAllObjects];
 }
 
 - (void)stopObserving {
-  hasListeners = NO;
+  @synchronized(self) {
+    hasListeners = NO;
+  }
 }
 
 + (BOOL)requiresMainQueueSetup {
@@ -80,18 +89,25 @@ RCT_EXPORT_MODULE();
 #pragma mark - Events
 
 - (void)didReceiveNotifeeCoreEvent:(NSDictionary *_Nonnull)event {
-  if (hasListeners) {
+  BOOL shouldSend;
+  @synchronized(self) {
+    shouldSend = hasListeners;
+    if (!shouldSend) {
+      [pendingCoreEvents addObject:event];
+    }
+  }
+  if (shouldSend) {
     [self sendNotifeeCoreEvent:event];
-  } else {
-    [pendingCoreEvents addObject:event];
   }
 }
 
 - (void)sendNotifeeCoreEvent:(NSDictionary *_Nonnull)eventBody {
   dispatch_async(dispatch_get_main_queue(), ^{
-    if (!hasListeners) {
-      [pendingCoreEvents addObject:eventBody];
-      return;
+    @synchronized(self) {
+      if (!hasListeners) {
+        [pendingCoreEvents addObject:eventBody];
+        return;
+      }
     }
     // Routing foreground vs background is based on UIApplication state.
     // iOS delivers didReceiveNotificationResponse: while the app is in
@@ -107,7 +123,8 @@ RCT_EXPORT_MODULE();
     // API-triggered events require an interactive JS context. If this
     // becomes a real-world problem, the routing should be split by event
     // type rather than by state alone.
-    BOOL isBackground = RCTRunningInAppExtension() ||
+    BOOL isBackground =
+        RCTRunningInAppExtension() ||
         [UIApplication sharedApplication].applicationState != UIApplicationStateActive;
     if (isBackground) {
       [self sendEventWithName:kReactNativeNotifeeNotificationBackgroundEvent body:eventBody];
@@ -417,6 +434,11 @@ RCT_EXPORT_MODULE();
   resolve(nil);
 }
 
+- (void)prewarmForegroundService:(RCTPromiseResolveBlock)resolve
+                          reject:(RCTPromiseRejectBlock)reject {
+  resolve(nil);
+}
+
 - (void)hideNotificationDrawer {
   // Android-only, no-op on iOS
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-notify-kit",
-  "version": "9.2.1",
+  "version": "9.4.0",
   "author": "Marco Crupi",
   "description": "Maintained Notifee-compatible fork for React Native — advanced local notifications for Android & iOS.",
   "main": "dist/index.js",

package/src/NotifeeApiModule.ts

@@ -826,6 +826,13 @@ export default class NotifeeApiModule extends NotifeeNativeModule implements Mod
     return this.native.stopForegroundService();
   };
 
+  public prewarmForegroundService = (): Promise<void> => {
+    if (!isAndroid) {
+      return Promise.resolve();
+    }
+    return this.native.prewarmForegroundService();
+  };
+
   public hideNotificationDrawer = (): void => {
     if (!isAndroid) {
       return;

package/src/specs/NativeNotifeeModule.ts

@@ -49,6 +49,7 @@ export interface Spec extends TurboModule {
   getPowerManagerInfo(): Promise<Object>;
   openPowerManagerSettings(): Promise<void>;
   stopForegroundService(): Promise<void>;
+  prewarmForegroundService(): Promise<void>;
   hideNotificationDrawer(): void;
   addListener(eventName: string): void;
   removeListeners(count: number): void;

package/src/types/Module.ts

@@ -419,6 +419,26 @@ export interface Module {
    */
   stopForegroundService(): Promise<void>;
 
+  /**
+   * Pre-warms the foreground service notification path by eagerly loading critical
+   * classes and warming the `INotificationManager` Binder proxy on a background thread.
+   *
+   * Most apps do **not** need this method — the library automatically performs warmup
+   * at app startup via `InitProvider`. This API is an escape hatch for edge cases:
+   *
+   * - Apps where the library is lazy-loaded or code-split
+   * - Apps that want to defer warmup to after the splash screen
+   * - Low-end devices where the `InitProvider` warmup hasn't finished by the time
+   *   the first notification is displayed
+   *
+   * Safe to call multiple times (idempotent). On iOS this resolves immediately as a no-op.
+   *
+   * See the "Advanced / Troubleshooting" section in the README for more details.
+   *
+   * @platform android
+   */
+  prewarmForegroundService(): Promise<void>;
+
   /**
    * Request specific notification permissions for your application on the current device.
    *

package/src/types/NotificationAndroid.ts

@@ -262,14 +262,18 @@ export interface NotificationAndroid {
   onlyAlertOnce?: boolean;
 
   /**
-   * By default notifications have no behaviour when a user presses them. The
-   * `pressAction` property allows you to set what happens when a user presses
-   * the notification.
+   * Controls what happens when a user presses the notification.
+   *
+   * Defaults to `{ id: 'default', launchActivity: 'default' }` when omitted,
+   * which opens the app's main activity on tap.
+   *
+   * Pass `null` explicitly to create a non-tappable notification (the notification
+   * will display but tapping it will do nothing).
    *
    * View the [Interaction](/react-native/android/interaction) documentation to learn
    * more.
    */
-  pressAction?: NotificationPressAction;
+  pressAction?: NotificationPressAction | null;
 
   /**
    * The `fullScreenAction` property allows you to show a custom UI
@@ -288,6 +292,23 @@ export interface NotificationAndroid {
    */
   foregroundServiceTypes?: AndroidForegroundServiceType[];
 
+  /**
+   * Controls the display behavior of the foreground service notification on Android 12+.
+   *
+   * When `asForegroundService` is `true` and this property is not set, it defaults to
+   * `AndroidForegroundServiceBehavior.IMMEDIATE`, which eliminates the up to 10-second
+   * display delay that Android 12+ imposes on foreground service notifications.
+   *
+   * Set to `AndroidForegroundServiceBehavior.DEFERRED` to restore the platform default
+   * deferred behavior, or `AndroidForegroundServiceBehavior.DEFAULT` for the framework-neutral
+   * default.
+   *
+   * Ignored when `asForegroundService` is `false` or not set.
+   *
+   * @platform android API 31+
+   */
+  foregroundServiceBehavior?: AndroidForegroundServiceBehavior;
+
   /**
    * Set a notification importance for devices without channel support.
    *
@@ -1476,3 +1497,48 @@ export enum AndroidForegroundServiceType {
   FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED = 1024,
   FOREGROUND_SERVICE_TYPE_MANIFEST = -1,
 }
+
+/**
+ * Controls the display behavior of foreground service notifications on Android 12+.
+ *
+ * Values are aligned with androidx.core.app.NotificationCompat constants:
+ *   DEFAULT   = NotificationCompat.FOREGROUND_SERVICE_DEFAULT   (0)
+ *   IMMEDIATE = NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE (1)
+ *   DEFERRED  = NotificationCompat.FOREGROUND_SERVICE_DEFERRED  (2)
+ *
+ * Do not change these numeric values without updating the native getter in
+ * NotificationAndroidModel.java.
+ *
+ * @platform android
+ */
+export enum AndroidForegroundServiceBehavior {
+  /**
+   * Framework default. Equivalent to not calling `setForegroundServiceBehavior()` at all.
+   * On Android 12+, the system may defer display of the foreground service notification
+   * by up to 10 seconds unless an exemption applies.
+   *
+   * Corresponds to `NotificationCompat.FOREGROUND_SERVICE_DEFAULT`.
+   */
+  DEFAULT = 0,
+
+  /**
+   * The foreground service notification is shown immediately after the service starts.
+   * Eliminates the 10-second display delay imposed by Android 12+ on foreground service
+   * notifications.
+   *
+   * This is the library default when `asForegroundService` is `true` and
+   * `foregroundServiceBehavior` is not explicitly set.
+   *
+   * Corresponds to `NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE`.
+   */
+  IMMEDIATE = 1,
+
+  /**
+   * The foreground service notification display may be deferred by up to 10 seconds by the
+   * system. This matches the default Android 12+ behavior and the (unintended) behavior of
+   * upstream `@notifee/react-native`.
+   *
+   * Corresponds to `NotificationCompat.FOREGROUND_SERVICE_DEFERRED`.
+   */
+  DEFERRED = 2,
+}

package/src/utils/validate.ts

@@ -82,9 +82,17 @@ export function isValidUrl(url: string): boolean {
 }
 
 export function isValidEnum(value: any, enumType: Record<string, any>): boolean {
-  if (!Object.values(enumType).includes(value)) {
-    return false;
-  }
+  // Filter out reverse-mapped string keys that TypeScript adds to numeric enums.
+  // In a numeric enum { A=0, B=1 }, Object.values() returns [0, 1, "A", "B"].
+  // The reverse-mapped string "A" satisfies typeof enumType["A"] === 'number',
+  // whereas real string enum values (e.g., TimeUnit.SECONDS = 'SECONDS')
+  // satisfy typeof enumType["SECONDS"] === 'string', so they are kept.
+  const values = Object.values(enumType).filter(
+    v => typeof v !== 'string' || typeof enumType[v] !== 'number',
+  );
+  return values.includes(value);
+}
 
-  return true;
+export function getNumericEnumValues(enumType: Record<string, any>): number[] {
+  return Object.values(enumType).filter((v): v is number => typeof v === 'number');
 }

package/src/validators/validateAndroidChannel.ts

@@ -2,7 +2,7 @@
  * Copyright (c) 2016-present Invertase Limited
  */
 
-import { objectHasProperty, isArray, isBoolean, isObject, isString } from '../utils';
+import { objectHasProperty, isArray, isBoolean, isObject, isString, isValidEnum } from '../utils';
 import { isValidColor, isValidVibratePattern } from './validate';
 
 import { AndroidImportance } from '../types/NotificationAndroid';
@@ -121,7 +121,7 @@ export default function validateAndroidChannel(channel: AndroidChannel): Android
    * importance
    */
   if (objectHasProperty(channel, 'importance') && channel.importance !== undefined) {
-    if (!Object.values(AndroidImportance).includes(channel.importance)) {
+    if (!isValidEnum(channel.importance, AndroidImportance)) {
       throw new Error("'channel.importance' expected an Importance value.");
     }
 
@@ -149,7 +149,7 @@ export default function validateAndroidChannel(channel: AndroidChannel): Android
    * visibility
    */
   if (objectHasProperty(channel, 'visibility') && channel.visibility !== undefined) {
-    if (!Object.values(AndroidVisibility).includes(channel.visibility)) {
+    if (!isValidEnum(channel.visibility, AndroidVisibility)) {
       throw new Error("'channel.visibility' expected visibility to be an AndroidVisibility value.");
     }
 

package/src/validators/validateAndroidNotification.ts

@@ -13,6 +13,8 @@ import {
   isString,
   isUndefined,
   isIOS,
+  isValidEnum,
+  getNumericEnumValues,
 } from '../utils';
 
 import { AndroidImportance } from '../types/NotificationAndroid';
@@ -20,6 +22,7 @@ import {
   AndroidBadgeIconType,
   AndroidCategory,
   AndroidDefaults,
+  AndroidForegroundServiceBehavior,
   AndroidForegroundServiceType,
   AndroidFlags,
   AndroidGroupAlertBehavior,
@@ -116,6 +119,22 @@ export default function validateAndroidNotification(
     out.asForegroundService = android.asForegroundService;
   }
 
+  /**
+   * foregroundServiceBehavior
+   */
+  if (
+    objectHasProperty(android, 'foregroundServiceBehavior') &&
+    !isUndefined(android.foregroundServiceBehavior)
+  ) {
+    if (!isValidEnum(android.foregroundServiceBehavior, AndroidForegroundServiceBehavior)) {
+      throw new Error(
+        "'notification.android.foregroundServiceBehavior' expected a valid AndroidForegroundServiceBehavior.",
+      );
+    }
+
+    out.foregroundServiceBehavior = android.foregroundServiceBehavior;
+  }
+
   /**
    * lightUpScreen
    */
@@ -153,7 +172,7 @@ export default function validateAndroidNotification(
    * badgeIconType
    */
   if (objectHasProperty(android, 'badgeIconType') && !isUndefined(android.badgeIconType)) {
-    if (!Object.values(AndroidBadgeIconType).includes(android.badgeIconType)) {
+    if (!isValidEnum(android.badgeIconType, AndroidBadgeIconType)) {
       throw new Error(
         "'notification.android.badgeIconType' expected a valid AndroidBadgeIconType.",
       );
@@ -239,7 +258,7 @@ export default function validateAndroidNotification(
       );
     }
 
-    const defaults = Object.values(AndroidDefaults);
+    const defaults = getNumericEnumValues(AndroidDefaults);
 
     for (let i = 0; i < android.defaults.length; i++) {
       if (!defaults.includes(android.defaults[i])) {
@@ -270,7 +289,7 @@ export default function validateAndroidNotification(
     objectHasProperty(android, 'groupAlertBehavior') &&
     !isUndefined(android.groupAlertBehavior)
   ) {
-    if (!Object.values(AndroidGroupAlertBehavior).includes(android.groupAlertBehavior)) {
+    if (!isValidEnum(android.groupAlertBehavior, AndroidGroupAlertBehavior)) {
       throw new Error(
         "'notification.android.groupAlertBehavior' expected a valid AndroidGroupAlertBehavior.",
       );
@@ -407,10 +426,10 @@ export default function validateAndroidNotification(
       );
     }
 
-    const defaults = Object.values(AndroidForegroundServiceType);
+    const foregroundServiceTypeValues = getNumericEnumValues(AndroidForegroundServiceType);
 
     for (let i = 0; i < android.foregroundServiceTypes.length; i++) {
-      if (!defaults.includes(android.foregroundServiceTypes[i])) {
+      if (!foregroundServiceTypeValues.includes(android.foregroundServiceTypes[i])) {
         throw new Error(
           "'notification.android.foregroundServiceTypes' invalid array value, expected an AndroidForegroundServiceType value.",
         );
@@ -429,13 +448,13 @@ export default function validateAndroidNotification(
     }
 
     if (android.flags.length === 0) {
-      throw new Error("'notification.android.flags' expected an array containing AndroidDefaults.");
+      throw new Error("'notification.android.flags' expected an array containing AndroidFlags.");
     }
 
-    const defaults = Object.values(AndroidFlags);
+    const flagValues = getNumericEnumValues(AndroidFlags);
 
     for (let i = 0; i < android.flags.length; i++) {
-      if (!defaults.includes(android.flags[i])) {
+      if (!flagValues.includes(android.flags[i])) {
         throw new Error(
           "'notification.android.flags' invalid array value, expected an AndroidFlags value.",
         );
@@ -458,13 +477,33 @@ export default function validateAndroidNotification(
 
   /**
    * pressAction
+   *
+   * Defaults to { id: 'default', launchActivity: 'default' } when omitted,
+   * so tapping the notification opens the app. Pass pressAction: null explicitly
+   * to opt out (non-tappable notification).
+   *
+   * The opt-out uses a reserved sentinel id ('__NOTIFEE_OPT_OUT__') in the bundle
+   * sent to native, so the native layer can distinguish "absent" (synthesize default)
+   * from "explicitly null" (no launch intent). The same constant is defined in
+   * NotificationPendingIntent.java as PRESS_ACTION_OPT_OUT_ID.
    */
-  if (objectHasProperty(android, 'pressAction') && !isUndefined(android.pressAction)) {
+  if (
+    objectHasProperty(android, 'pressAction') &&
+    android.pressAction !== null &&
+    !isUndefined(android.pressAction)
+  ) {
     try {
       out.pressAction = validateAndroidPressAction(android.pressAction);
     } catch (e: any) {
       throw new Error(`'notification.android.pressAction' ${e.message}`);
     }
+  } else if (android.pressAction === null) {
+    // Explicit opt-out: emit sentinel so native can distinguish from "absent".
+    // DO NOT use '__NOTIFEE_OPT_OUT__' as a real pressAction id — reserved sentinel.
+    out.pressAction = { id: '__NOTIFEE_OPT_OUT__' };
+  } else {
+    // pressAction omitted or undefined: inject default so tapping opens the app
+    out.pressAction = { id: 'default', launchActivity: 'default' };
   }
 
   /**
@@ -482,7 +521,7 @@ export default function validateAndroidNotification(
    * importance
    */
   if (objectHasProperty(android, 'importance') && !isUndefined(android.importance)) {
-    if (!Object.values(AndroidImportance).includes(android.importance)) {
+    if (!isValidEnum(android.importance, AndroidImportance)) {
       throw new Error("'notification.android.importance' expected a valid Importance.");
     }
 
@@ -693,7 +732,7 @@ export default function validateAndroidNotification(
    * visibility
    */
   if (objectHasProperty(android, 'visibility') && android.visibility !== undefined) {
-    if (!Object.values(AndroidVisibility).includes(android.visibility)) {
+    if (!isValidEnum(android.visibility, AndroidVisibility)) {
       throw new Error(
         "'notification.android.visibility' expected a valid AndroidVisibility value.",
       );
@@ -739,5 +778,19 @@ export default function validateAndroidNotification(
     out.ongoing = true;
   }
 
+  /**
+   * Auto-set foregroundServiceBehavior to IMMEDIATE for foreground service notifications.
+   * Only set when asForegroundService is true and the user did not provide an explicit value.
+   * When asForegroundService is false/undefined, strip the property entirely — it has no effect
+   * on non-FGS notifications and including it would bloat the Bundle unnecessarily.
+   */
+  if (out.asForegroundService) {
+    if (android && !objectHasProperty(android, 'foregroundServiceBehavior')) {
+      out.foregroundServiceBehavior = AndroidForegroundServiceBehavior.IMMEDIATE;
+    }
+  } else {
+    delete out.foregroundServiceBehavior;
+  }
+
   return out;
 }

package/src/validators/validateIOSPermissions.ts

@@ -28,7 +28,7 @@ export default function validateIOSPermissions(
 
   if (objectHasProperty(permissions, 'badge')) {
     if (!isBoolean(permissions.badge)) {
-      throw new Error("'alert' badge a boolean value.");
+      throw new Error("'badge' expected a boolean value.");
     }
 
     out.badge = permissions.badge;

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '9.2.1';
+export const version = '9.4.0';