react-native-notify-kit 10.8.1 → 10.9.0

package/README.md

@@ -48,7 +48,7 @@ This fork fills the gap: it preserves all of Notifee's advanced features, migrat
 - iOS FCM Mode Notification Service Extension automation via config plugin.
 - Android foreground service manifest configuration via config plugin, with explicit opt-in for foreground service types.
 - Android Expo FCM smoke validation using RNFirebase data-only messages and `notifee.handleFcmMessage`.
-- Minimum supported React Native: `>=0.73`
+- React Native peer dependency: `>=0.73`; see the [validation scope](https://docs.page/marcocrupi/react-native-notify-kit/react-native/environment-support#react-native-088-validation) for tested versions.
 - Development target: React Native `0.85.3`
 - License: `Apache-2.0`
 - Full changelog: [CHANGELOG.md](CHANGELOG.md)
@@ -524,8 +524,8 @@ This fork is a complete migration to React Native's **New Architecture**:
 - **TurboModules only** — no legacy Bridge support (`NativeModules` replaced with `TurboModuleRegistry`)
 - **Android bridge rewritten in Kotlin** (original was Java)
 - **iOS bridge uses Objective-C++** with `NativeNotifeeModuleSpecJSI` TurboModule conformance
-- **Minimum React Native >=0.73**, development target **0.85.3**
-- **Toolchain**: Yarn 4, Node 22+, JDK 17+ for Android builds, library Android module compileSdk/targetSdk 35
+- **React Native peer dependency >=0.73**, development target **0.85.3**
+- **Toolchain**: Yarn 4, Node 22+, JDK 17+ for Android builds. Library `minSdk = 24` and `targetSdk = 35`; `compileSdk` inherits a usable `rootProject.ext.compileSdkVersion`, with a minimum/fallback of 35. SDK 37 is not required; the AAR consumer minimum stays at 35, including with AGP 9.
 - **Android JDK baseline**: JDK 17 and JDK 21 are the validated Android build baselines; newer JDKs are not blocked by NotifyKit but depend on the consumer Android toolchain
 - **Single Android module** — the original Notifee shipped a pre-compiled AAR bundled inside the npm tarball under a frozen Maven coordinate; this fork compiles the core from source as part of the React Native bridge module on every consumer build. Eliminates the `FAIL_ON_PROJECT_REPOS` issue on RN 0.74+ and the Gradle cache staleness bug that could serve outdated bytecode after `yarn upgrade`.
 - **Expo CNG development builds** — iOS FCM Mode NSE automation and Android foreground service manifest configuration are available through the config plugin. Android Expo FCM smoke validation uses RNFirebase data-only messages plus `notifee.handleFcmMessage`.
@@ -536,6 +536,8 @@ This fork is a complete migration to React Native's **New Architecture**:
 - **New API: `setNotificationConfig()`** — opt-out flag to prevent Notifee from intercepting iOS remote notification handlers (see [New APIs](#new-apis) below)
 - **Baseline Profile** — the library AAR ships a Baseline Profile that instructs ART to AOT-compile the foreground service notification hot path at install time, eliminating JIT penalty on first invocation
 
+Android API 35 and the current WorkManager dependency require **AGP 8.6.0 or newer** (AGP 8.6 requires Gradle 8.7). Higher SDKs need a compatible toolchain: API 36 requires AGP 8.9.1 or newer; API 37 requires AGP 9.1.1 or newer. Select Gradle for the chosen AGP and React Native version using the [Android compatibility tables](https://developer.android.com/build/releases/about-agp). The RN 0.85.3 smoke app remains configured for SDK 36 and Gradle 9.3.1. TypeScript builds, consumer types and client tests have also been validated with RN 0.88.0; Android build and selected device checks covered RN 0.88 with SDK 37. See the [environment support guide](https://docs.page/marcocrupi/react-native-notify-kit/react-native/environment-support#react-native-088-validation) for the scope and remaining limits. Hosts that only configure the app DSL or a version catalog must expose the root extra property before the library is evaluated to opt into a higher SDK. See the [installation guide](https://docs.page/marcocrupi/react-native-notify-kit/react-native/installation) for accepted values, fallback behavior, and standalone build limitations.
+
 ## Bugs Fixed from Upstream Notifee
 
 This fork fixes the following bugs that were never resolved in the original Notifee repository:
@@ -640,7 +642,7 @@ These changes are documented in the [CHANGELOG](CHANGELOG.md) under the release
 
 ## Foreground Service Setup (Android 14+)
 
-**10.8.1 — [Issue #81](https://github.com/marcocrupi/react-native-notify-kit/issues/81):** on Android 12+, the library automatically handles a denied initial foreground promotion non-fatally for an eligible START retried or redelivered by Android after process death. Ordinary app-requested START failures retain their existing error handling. This does not guarantee service survival or restart under Android/OEM restrictions. See the [Foreground Service guide](https://github.com/marcocrupi/react-native-notify-kit/blob/main/docs/react-native/android/foreground-service.mdx) for details.
+**10.8.1 — [Issue #81](https://github.com/marcocrupi/react-native-notify-kit/issues/81):** on Android 12+, the library automatically handles a denied initial foreground promotion non-fatally for an eligible START retried or redelivered by Android after process death. Outside the qualified API 35+ tracked initial denial recovery described below for #82, app-requested START failures retain their existing error handling. This does not guarantee service survival or restart under Android/OEM restrictions. See the [Foreground Service guide](https://github.com/marcocrupi/react-native-notify-kit/blob/main/docs/react-native/android/foreground-service.mdx) for details.
 
 Android 14 (API 34) requires all foreground services to declare an explicit `foregroundServiceType`. If you use `asForegroundService: true` in your notifications, add the following to your app's `AndroidManifest.xml`:
 
@@ -667,23 +669,23 @@ Android 14 (API 34) requires all foreground services to declare an explicit `for
 
 Available types: `camera`, `connectedDevice`, `dataSync`, `health`, `location`, `mediaPlayback`, `mediaProjection`, `microphone`, `phoneCall`, `remoteMessaging`, `shortService`, `specialUse`, `systemExempted`. Choose the type that matches your use case — using the wrong type may cause Google Play policy violations.
 
-> **Note:** `shortService` has a 3-minute timeout on Android 14+. If your foreground service needs to run longer, use a different type. The library's `onTimeout()` handler will gracefully stop the service if the timeout fires.
+> **Note:** `shortService` has a 3-minute timeout on Android 14+. Choose a type that matches the actual work and its permitted duration. Timeout handling prioritizes demotion when the callback executes, but timely teardown and JavaScript delivery remain best-effort under Android/OEM restrictions. See the [Foreground Service guide](docs/react-native/android/foreground-service.mdx#handling-fg_timeout).
 
 ### Foreground service use case guide
 
 Choosing the right `foregroundServiceType` matters — the wrong choice can cause Doze-driven CPU suspension with the screen off, Google Play policy rejection, or premature kills by the Android 14+ type-specific timeouts. This matrix maps common use cases to the recommended type and calls out the caveats you need to know before shipping:
 
-| Use case                                     | Recommended type                                   | Doze CPU exempt? | Type timeout                      | Key caveat                                                                                                                        |
-| -------------------------------------------- | -------------------------------------------------- | ---------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| Silent rest / workout / cooking timer        | **`SET_ALARM_CLOCK` trigger — not an FGS**         | N/A              | N/A                               | See the ["Timers: foreground service or `SET_ALARM_CLOCK`?"](#timers-foreground-service-or-set_alarm_clock) decision guide below. |
-| Timer with audio cue (metronome, guided set) | `mediaPlayback`                                    | Yes              | None                              | Must actually play audio — silent `mediaPlayback` is a Play Store policy violation.                                               |
-| Short operation (< 3 min)                    | `shortService`                                     | No               | **3 min**                         | Library's `onTimeout()` stops cleanly and emits `TYPE_FG_TIMEOUT` to JS.                                                          |
-| Long-running data sync                       | `dataSync`                                         | No               | 6 h (API 34); stricter on API 35+ | Pair with `openBatteryOptimizationSettings()` for reliability on OEM devices.                                                     |
-| Location / navigation / fitness GPS          | `location`                                         | Yes              | None                              | Requires `ACCESS_FINE_LOCATION` runtime permission.                                                                               |
-| Music / podcast / audiobook playback         | `mediaPlayback`                                    | Yes              | None                              | Must be real playback — see policy callout below.                                                                                 |
-| Bluetooth / USB device sync                  | `connectedDevice`                                  | No               | None                              | Requires companion-device or Bluetooth permission.                                                                                |
-| Enterprise / DPC / system-critical           | `specialUse` or `systemExempted`                   | Varies           | None                              | `specialUse` requires a `<property>` element and Play Store justification review.                                                 |
-| Arbitrary deferrable background work         | **None — use `WorkManager` directly, not an FGS.** | N/A              | N/A                               | FGS is not the right abstraction for deferrable work.                                                                             |
+| Use case                                     | Recommended type                                   | Doze CPU exempt? | Type timeout                                          | Key caveat                                                                                                                        |
+| -------------------------------------------- | -------------------------------------------------- | ---------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Silent rest / workout / cooking timer        | **`SET_ALARM_CLOCK` trigger — not an FGS**         | N/A              | N/A                                                   | See the ["Timers: foreground service or `SET_ALARM_CLOCK`?"](#timers-foreground-service-or-set_alarm_clock) decision guide below. |
+| Timer with audio cue (metronome, guided set) | `mediaPlayback`                                    | Yes              | None                                                  | Must actually play audio — silent `mediaPlayback` is a Play Store policy violation.                                               |
+| Short operation (< 3 min)                    | `shortService`                                     | No               | **3 min**                                             | Native timeout handling and `EventType.FG_TIMEOUT` delivery are best-effort.                                                      |
+| Long-running data sync                       | `dataSync`                                         | No               | 6 h cumulative per app/type per 24 h (target API 35+) | Coordinate the shared budget; OEM battery settings do not guarantee execution.                                                    |
+| Location / navigation / fitness GPS          | `location`                                         | Yes              | None                                                  | Requires `ACCESS_FINE_LOCATION` runtime permission.                                                                               |
+| Music / podcast / audiobook playback         | `mediaPlayback`                                    | Yes              | None                                                  | Must be real playback — see policy callout below.                                                                                 |
+| Bluetooth / USB device sync                  | `connectedDevice`                                  | No               | None                                                  | Requires companion-device or Bluetooth permission.                                                                                |
+| Enterprise / DPC / system-critical           | `specialUse` or `systemExempted`                   | Varies           | None                                                  | `specialUse` requires a `<property>` element and Play Store justification review.                                                 |
+| Arbitrary deferrable background work         | **None — use `WorkManager` directly, not an FGS.** | N/A              | N/A                                                   | FGS is not the right abstraction for deferrable work.                                                                             |
 
 > **Warning:** **`mediaPlayback` requires active audio playback.** [Google Play's Foreground Service Types policy](https://support.google.com/googleplay/android-developer/answer/13392821) explicitly prohibits declaring `mediaPlayback` for services that do not play audio. A silent timer, stopwatch, or rest-timer declared as `mediaPlayback` will be rejected during Play Store review. For silent long-running timers, prefer the `SET_ALARM_CLOCK` trigger path (see the decision guide below).
 
@@ -691,10 +693,23 @@ Choosing the right `foregroundServiceType` matters — the wrong choice can caus
 
 Android 15 (API 35) tightens foreground service restrictions further:
 
-- **`dataSync` cumulative 6-hour limit per 24-hour window.** Apps that previously started a fresh `dataSync` FGS repeatedly will hit the new cap.
+- **`dataSync` cumulative 6-hour budget per app/type in a 24-hour window**, for apps targeting API 35+. A new START or process recreation does not reset it; bringing the app to the foreground resets the allowance under Android's rules. There is no reliable public API for the remaining budget.
 - **`mediaProcessing` is a new dedicated type** for short media transcode / processing operations, with its own timeout.
 - **`specialUse` requires a `<property>` element** on the `<service>` tag with `android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"` and a user-visible justification string. Play Store review uses this property to evaluate the declaration.
-- **Type-specific timeouts fire `onTimeout(int startId, int fgsType)`.** This fork already implements the API 35+ overload — at timeout the service stops cleanly and the library emits `TYPE_FG_TIMEOUT` to JS with both `startId` and `fgsType` in the event payload.
+- **Timeout handling is hardened when the callback can execute.** Native handling prioritizes foreground demotion and coordinates conditional stopping with concurrent STARTs. `EventType.FG_TIMEOUT = 9` is Android-only and delivered best-effort, with optional `startId` and `fgsType`; it does not confirm Android service teardown, cancel JavaScript work, or authorize a restart. Device-level process suspension may still prevent timely handling.
+- **Qualified initial promotion denial on API 35+ is non-fatal.** If Android denies `startForeground()` for an eligible tracked START on a never-promoted instance, the library terminalizes only that request, preserves other pending STARTs, and does not start its runner. This is separate from framework RETRY/REDELIVERY recovery after process death ([#81](https://github.com/marcocrupi/react-native-notify-kit/issues/81)).
+
+See the [Foreground Service guide](docs/react-native/android/foreground-service.mdx#android-15-data-sync-timeouts) for timeout handling, interruptible tasks, and the limits of [Issue #82](https://github.com/marcocrupi/react-native-notify-kit/issues/82).
+
+**10.9.0: optional best-effort run limit.** Set `android.foregroundServiceBestEffortStopAfterMs` to request a voluntary
+stop attempt for a single `dataSync` foreground run on Android API 35+. It is disabled by default and accepts safe integer
+milliseconds from 60,000 to 18,000,000, starting at the first successful promotion. Same-ID updates do not extend it.
+The internal inexact AlarmManager alarm may arrive minutes late or never; this is not a hard maximum, does not cancel
+JavaScript work, and has not been shown to eliminate vivo/iQOO/OEM timeout crashes. Native handling uses REMOVE and
+selective stopping; the separate best-effort `FG_RUN_LIMIT_REACHED = 10` event does not certify AMS teardown.
+A resolved `displayNotification()` Promise does not confirm alarm scheduling. See the
+[complete contract, failure diagnostics and copyable example](docs/react-native/android/foreground-service.mdx#voluntary-best-effort-run-limit-api-35)
+for validation, process-recreation limits and cooperative cancellation.
 
 If you target API 35+, audit your `foregroundServiceType` choice against the matrix above before shipping. The canonical reference is the [Android 15 foreground service behavior changes](https://developer.android.com/about/versions/15/behavior-changes-15#fgs-changes) documentation.
 

package/android/build.gradle

@@ -1,7 +1,8 @@
 import org.gradle.internal.jvm.Jvm
 
 buildscript {
-  // The Android Gradle plugin is only required when opening the android folder stand-alone.
+  // Legacy standalone declaration only; this folder is not a complete standalone RN build.
+  // API 35 and WorkManager 2.11.1 require at least AGP 8.6.0.
   // This avoids unnecessary downloads and potential conflicts when the library is included as a
   // module dependency in an application project.
   if (project == rootProject) {
@@ -11,7 +12,7 @@ buildscript {
     }
 
     dependencies {
-      classpath("com.android.tools.build:gradle:8.2.2")
+      classpath("com.android.tools.build:gradle:8.6.0")
       classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24")
     }
   }
@@ -60,13 +61,46 @@ if (project.hasProperty('reactNativeProjects')) {
   project.evaluationDependsOn(':app')
 }
 
+// Follow the conventional React Native host property without changing the host's SDK.
+// Only configuration parsing can fall back; SDK/toolchain/build errors must propagate.
+def notifeeCompileSdk = 35
+if (rootProject.ext.has('compileSdkVersion')) {
+  def hostCompileSdk = rootProject.ext.get('compileSdkVersion')
+  Integer hostApi = null
+  try {
+    if (hostCompileSdk instanceof Number) {
+      hostApi = new BigDecimal(hostCompileSdk.toString()).intValueExact()
+    } else if (hostCompileSdk instanceof CharSequence) {
+      def sdk = hostCompileSdk.toString().trim()
+      if (sdk ==~ /(?:android-)?[0-9]+/) {
+        hostApi = new BigDecimal(sdk.replaceFirst(/^android-/, '')).intValueExact()
+      }
+    }
+  } catch (NumberFormatException | ArithmeticException ignored) {
+    // Non-finite numbers, fractions and integer overflow are unusable configuration.
+  }
+  if (hostApi != null && hostApi > 0) {
+    notifeeCompileSdk = Math.max(35, hostApi)
+  } else {
+    logger.warn("[react-native-notify-kit] Ignoring unusable rootProject.ext.compileSdkVersion " +
+      "(type: ${hostCompileSdk == null ? 'null' : hostCompileSdk.getClass().simpleName}); " +
+      "expected a positive integer API level or stable android-N identifier in the 32-bit integer range. " +
+      "Using compileSdk 35.")
+  }
+}
+
 android {
   namespace = "io.invertase.notifee"
-  compileSdk = 35
+  compileSdk = notifeeCompileSdk
 
   defaultConfig {
     minSdk = 24
     targetSdk = 35
+    // AGP 9 otherwise defaults the consumer minimum to the inherited compile SDK.
+    // Keep the API 35 dependency baseline independent of the SDK used to compile.
+    aarMetadata {
+      minCompileSdk = 35
+    }
     multiDexEnabled = true
 
     testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
@@ -105,6 +139,18 @@ android {
   }
 
   testOptions.unitTests.all {
+    // RN pins compilation to Java 17. Run tests on the selected build JDK so a JDK 21
+    // invocation can simulate newer Android APIs without changing the bytecode target.
+    javaLauncher = javaToolchains.launcherFor {
+      languageVersion = JavaLanguageVersion.of(jvmMajorVersion)
+    }
+    // Robolectric's API 36+ FileDescriptor interceptor accesses SharedSecrets on Java 21.
+    jvmArgs '--add-opens=java.base/jdk.internal.access=ALL-UNNAMED'
+    // Simulation SDKs are independent of compileSdk. API 36/37 require a JDK 21 test JVM;
+    // JDK 17 can select earlier APIs with -Drobolectric.enabledSdks=24,26,28,29,30,31,32,33,34,35.
+    if (System.getProperty('robolectric.enabledSdks') != null) {
+      systemProperty 'robolectric.enabledSdks', System.getProperty('robolectric.enabledSdks')
+    }
     testLogging {
       events "failed", "skipped"
       showStackTraces = true
@@ -164,7 +210,7 @@ dependencies {
 
   // --- Test dependencies ---
   testImplementation 'junit:junit:4.13.2' // https://github.com/junit-team/junit4/releases
-  testImplementation 'org.robolectric:robolectric:4.14.1' // https://github.com/robolectric/robolectric/releases
+  testImplementation 'org.robolectric:robolectric:4.17' // https://github.com/robolectric/robolectric/releases
   testImplementation 'org.mockito:mockito-core:5.19.0' // https://github.com/mockito/mockito/releases
   androidTestImplementation 'androidx.test.ext:junit:1.1.3' // https://developer.android.com/jetpack/androidx/releases/test
   androidTestImplementation 'androidx.test.espresso:espresso-core:3.4.0' // see above

package/android/src/main/AndroidManifest.xml

@@ -25,6 +25,10 @@
       android:theme="@android:style/Theme.Translucent.NoTitleBar"
       android:exported="true" />
 
+    <receiver
+      android:name="app.notifee.core.ForegroundServiceRunLimitReceiver"
+      android:exported="false" />
+
     <!-- Foreground Service -->
     <service
       android:name="app.notifee.core.ForegroundService"