react-native-notify-kit 9.7.0 → 10.1.0

package/README.md

@@ -1,17 +1,24 @@
+<!-- markdownlint-disable MD033 MD041 -->
+<p align="center">
+  <img src="https://raw.githubusercontent.com/marcocrupi/react-native-notify-kit/main/docs/assets/logo.png" alt="react-native-notify-kit" width="160" />
+</p>
+
 # react-native-notify-kit
 
-Maintained Notifee-compatible fork — a feature-rich React Native notification library (Android & iOS).
+Maintained Notifee-compatible fork: a feature-rich React Native notification library (Android & iOS).
 
-<!-- markdownlint-disable MD033 -->
 <p align="center">
   <a href="https://www.npmjs.com/package/react-native-notify-kit"><img src="https://img.shields.io/npm/v/react-native-notify-kit.svg" alt="npm version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a>
   <img src="https://img.shields.io/badge/platform-Android%20%7C%20iOS-green.svg" alt="Platform">
   <img src="https://img.shields.io/badge/React%20Native-%3E%3D0.73-blue.svg" alt="React Native">
+  <a href="https://docs.page/marcocrupi/react-native-notify-kit/react-native/overview"><img src="https://img.shields.io/badge/docs-docs.page-blue.svg" alt="Documentation"></a>
 </p>
 
 <hr/>
 
+> 📘 **Full documentation:** [docs.page/marcocrupi/react-native-notify-kit](https://docs.page/marcocrupi/react-native-notify-kit/react-native/overview) — public API reference, platform guides, FCM Mode, server SDK, and the `init-nse` CLI.
+
 An actively maintained fork of Notifee for React Native notifications, continued and improved by Marco Crupi.
 
 This repository preserves the original Notifee APIs and native core while continuing development for modern React Native releases.
@@ -135,10 +142,38 @@ useEffect(() => {
 }, []);
 ```
 
+> **Which handler fires when (iOS):**
+>
+> - Tap a notification while the app is **active in foreground** → `onForegroundEvent` receives `PRESS`.
+> - Tap a notification while the app is **in background or killed** → `onBackgroundEvent` receives `PRESS`, even though iOS immediately brings the app to the foreground right after. At the moment iOS delivers the tap to the delegate, `UIApplication.applicationState` is `Inactive`, not `Active`, so the event is routed to the background handler.
+> - Foreground delivery of a Notifee-owned notification → `onForegroundEvent` receives `DELIVERED`.
+>
+> Register **both** handlers if you need to react to taps in every app state. Resolves the confusion reported in upstream [invertase/notifee#1155](https://github.com/invertase/notifee/issues/1155).
+
+## Notifee FCM Mode (NEW in 10.0.0)
+
+**Use `react-native-notify-kit` as the sole FCM display layer on both Android and iOS** — one developer API, no duplicate notifications on Android, no silent-push drops on iOS. Ship a server SDK payload, let the client handle it in one line, and scaffold the iOS Notification Service Extension with a single CLI command:
+
+```bash
+# server: build the payload
+import { buildNotifyKitPayload } from 'react-native-notify-kit/server';
+await admin.messaging().send(buildNotifyKitPayload({ token, notification: { title, body, android, ios } }));
+
+# client (Android + iOS): one line in setBackgroundMessageHandler / onMessage
+await notifee.handleFcmMessage(remoteMessage);
+
+# iOS NSE scaffold
+npx react-native-notify-kit init-nse && cd ios && pod install
+```
+
+See the full guide: **[docs/fcm-mode.mdx](docs/fcm-mode.mdx)** — covers architecture, server SDK reference, client API, NSE setup, payload schema, migration, troubleshooting, and known limitations.
+
 ## Push Notifications (Firebase)
 
 This library handles notification **display and management**. For receiving push notifications, pair it with [`@react-native-firebase/messaging`](https://rnfirebase.io/messaging/usage):
 
+> **New in 10.0.0:** for a turnkey FCM integration that handles both platforms (no duplicate on Android, APNs-reliable on iOS), use **[Notifee FCM Mode](docs/fcm-mode.mdx)** instead of the manual pattern below. The sections that follow still apply for basic Firebase setup (google-services plugin, permissions, APNs capability).
+
 ### Android setup
 
 1. Add Firebase dependencies to your app:
@@ -196,7 +231,22 @@ messaging().onMessage(async remoteMessage => {
 
 ## iOS Notification Service Extension
 
-To modify push notification content before display (e.g., attach images), create a Notification Service Extension:
+To modify push notification content before display (e.g., attach images), create a Notification Service Extension.
+
+### Automated setup (recommended)
+
+From your project root, with `react-native-notify-kit` installed:
+
+```bash
+npx react-native-notify-kit init-nse
+cd ios && pod install
+```
+
+The CLI scaffolds a Swift NSE target (default name: `NotifyKitNSE`), patches your Podfile, and wires `.pbxproj`. Open your `.xcworkspace` in Xcode, verify the NSE target's signing, and build. See [docs/fcm-mode.mdx#ios-nse-setup](docs/fcm-mode.mdx#ios-nse-setup) for the full CLI reference (target name, bundle suffix, `--dry-run`, `--force`).
+
+### Manual setup
+
+For Expo, monorepos with non-standard iOS paths, or heavily-customized Xcode configurations where the CLI can't patch the project cleanly:
 
 1. In Xcode: **File > New > Target > Notification Service Extension**
 2. Add to your Podfile:
@@ -234,6 +284,40 @@ To modify push notification content before display (e.g., attach images), create
 
 5. Run `cd ios && pod install`
 
+## Server SDK
+
+`react-native-notify-kit` ships a **zero-dependency server SDK** under the `/server` subpath, for building FCM HTTP v1 payloads that the client `handleFcmMessage` handler consumes. Runs in Node.js 22+ and Firebase Cloud Functions.
+
+```ts
+import { buildNotifyKitPayload } from 'react-native-notify-kit/server';
+import * as admin from 'firebase-admin';
+
+const message = buildNotifyKitPayload({
+  token: '<device FCM token>',
+  notification: {
+    id: 'order-42',
+    title: 'Your order is on the way',
+    body: 'Tap to see live tracking',
+    data: { orderId: '42' },
+    android: { channelId: 'orders', smallIcon: 'ic_notification' },
+    ios: { sound: 'default', interruptionLevel: 'timeSensitive' },
+  },
+  options: { androidPriority: 'high', ttl: 3600 },
+});
+
+await admin.messaging().send(message);
+```
+
+Full reference: [docs/fcm-mode.mdx#server-sdk-reference](docs/fcm-mode.mdx#server-sdk-reference) (types, validation rules, payload shape, FCM 4 KB limit).
+
+## CLI Tools
+
+The library ships a small CLI at `npx react-native-notify-kit`. Currently one command is available:
+
+- `npx react-native-notify-kit init-nse` — scaffolds an iOS Notification Service Extension (Swift), patches the Podfile, and wires `.pbxproj`. See [docs/fcm-mode.mdx#ios-nse-setup](docs/fcm-mode.mdx#ios-nse-setup) for options.
+
+The CLI is prepacked into the main package at publish time, so `npx react-native-notify-kit` works immediately after `yarn add react-native-notify-kit` — no separate install.
+
 ## Jest Testing
 
 Mock the native module in your Jest setup file:
@@ -263,7 +347,7 @@ This fork is a complete migration to React Native's **New Architecture**:
 - **Toolchain**: Yarn 4, Node 22+, Java 17, compileSdk/targetSdk 35
 - **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`.
 - **Core notification logic (NotifeeCore) is unchanged** — the public API is fully compatible with the original Notifee
-- **33 upstream bugs fixed** — see [Bugs Fixed from Upstream Notifee](#bugs-fixed-from-upstream-notifee) below
+- **35 upstream bugs fixed** — see [Bugs Fixed from Upstream Notifee](#bugs-fixed-from-upstream-notifee) below
 - **Reliable trigger notifications** — AlarmManager is the default backend instead of WorkManager, with automatic fallback when exact alarm permission is not granted
 - **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
@@ -293,7 +377,7 @@ This fork fixes the following bugs that were never resolved in the original Noti
 | `!=` reference equality on String comparison in `NotificationPendingIntent` (latent — would activate when `getLaunchActivity()` returns a non-null value for `id=default`) | Android | Pre-existing (latent) | 9.1.19 |
 | `pressAction.launchActivity` not defaulted at native layer when `pressAction.id === 'default'` | Android | N/A (defense-in-depth) | 9.1.19 |
 | Duplicate symbols linker error when using NSE (`$NotifeeExtension = true`) with static frameworks — `NotifeeExtensionHelper` compiled by both `RNNotifee` and `RNNotifeeCore` pods | iOS | Pre-existing | 9.1.22 |
-| `FAIL_ON_PROJECT_REPOS` rejection on RN 0.74+ — library injected a Maven repository into the consumer's `rootProject.allprojects` block, rejected by `dependencyResolutionManagement` mode | Android | N/A (architectural) | 9.2.0 |
+| `Could not resolve app.notifee:core:+` / `FAIL_ON_PROJECT_REPOS` rejection — library injected a Maven repository into the consumer's `rootProject.allprojects` block, which broke on (a) RN 0.74+ with `dependencyResolutionManagement`, (b) Expo SDK 53/54 where `extraMavenRepos` is not propagated to subprojects, and (c) Gradle 8 dependency locking with legacy XML parsers | Android | [#1079](https://github.com/invertase/notifee/issues/1079), [#1226](https://github.com/invertase/notifee/issues/1226), [#1262](https://github.com/invertase/notifee/issues/1262) | 9.2.0 |
 | Stale Gradle cache could serve outdated AAR bytecode after `yarn upgrade` — same Maven coordinate reused across releases violated Gradle's coordinate-immutability assumption | Android | N/A (architectural) | 9.2.0 |
 | `EventType.DELIVERED` not emitted for `displayNotification()` in foreground (only for trigger notifications) — `notifeeTrigger != nil` guard in `willPresentNotification:` suppressed the event, breaking iOS/Android symmetry | iOS | Pre-existing | 9.3.0 |
 | Tapping a notification without explicit `pressAction` does nothing (app doesn't open) — `NotificationPendingIntent.createIntent()` creates a tap-less PendingIntent when `pressActionModelBundle` is null, especially visible on trigger notifications after app kill | Android | Pre-existing (latent) | 9.3.0 |
@@ -305,8 +389,11 @@ This fork fixes the following bugs that were never resolved in the original Noti
 | Notification Service Extension attachment downloads had no timeout cap (default 60-second `NSURLSession` timeout exceeds iOS's ~30-second NSE budget), causing extension process kill and notification loss on slow networks | iOS | Pre-existing | 9.4.0 |
 | `cancelTriggerNotifications()` / `createTriggerNotification()` promises resolve before Room DB write completes, causing ~3% race on cancel-then-create patterns. Also fixes a previously-undocumented reboot-recovery data-loss bug in `NotifeeAlarmManager.rescheduleNotification` and an ordering bug in `NotificationManager.doScheduledWork` | Android | [#549](https://github.com/invertase/notifee/issues/549) | 9.5.0 |
 | Scheduled trigger notifications silently lost across device reboot on OEM devices (Xiaomi MIUI, OnePlus, Huawei EMUI, Oppo ColorOS, Vivo FuntouchOS) whose vendor OS suppresses `BOOT_COMPLETED` until the user manually enables autostart. Also handles zombie non-repeating triggers whose fire time already passed (fire-once within a 24-hour grace period, then delete the Room row; delete silently beyond the grace period) and adds try/catch/finally guards to all notifee `BroadcastReceiver` async paths. | Android | [#734](https://github.com/invertase/notifee/issues/734) | 9.6.0 |
+| `RepeatFrequency.DAILY` / `WEEKLY` triggers fire on day 1 but never on day 2+ (also reproduces with arrays of 24 daily reminders) — pre-fix: stale Room anchors after the post-fire repeat recalculation, plus DST ±1h shift on repeating triggers, plus reboot recovery silently dropping the rearmed PendingIntent on OEM devices that suppress `BOOT_COMPLETED` | Android | [#601](https://github.com/invertase/notifee/issues/601), [#1063](https://github.com/invertase/notifee/issues/1063) | 9.1.14 (DST + persist recalc) + 9.5.0 (await Room) + 9.6.0 (BOOT_COUNT cold-start, race guard) |
+| Scheduled `TIMESTAMP` trigger notifications lost after device reboot on Android 14 emulator with battery optimizations off — pre-fix: `RebootBroadcastReceiver` dropped the goAsync handoff before Room writes completed; OEM devices that suppress `BOOT_COMPLETED` never re-armed the alarm at all | Android | [#991](https://github.com/invertase/notifee/issues/991) | 9.1.12 (goAsync in `RebootBroadcastReceiver`) + 9.5.0 (await Room in `rescheduleNotification`) + 9.6.0 (BOOT_COUNT cold-start for OEM suppressors) |
 | `ObjectAlreadyConsumedException` in headless task when the same `WritableMap` is reused or the `taskConfig` accessor is read twice — `TaskConfig.init` mutated the caller's map instead of copying it first. Latent in most apps but observed in production by upstream users with high-frequency headless events | Android | [#266](https://github.com/invertase/notifee/issues/266) | 9.6.0 |
 | `getDisplayedNotifications()` returned no `data` field on Android, breaking iOS/Android API symmetry where iOS exposes custom keys via `parseDataFromUserInfo:` (see platform limitation note below — the fix is API parity for app-posted notifications, not a workaround for FCM background auto-display) | Android | [#393](https://github.com/invertase/notifee/issues/393) | 9.7.0 |
+| Small icon resolution failure in release builds causes `IllegalArgumentException` at `NotificationCompat.Builder.build()` — library now falls back to the app launcher icon and logs a warning instead of failing the notification display | Android | [#733](https://github.com/invertase/notifee/issues/733) | 10.1.0 |
 
 > **Important note on `getDisplayedNotifications()` and FCM custom data on Android.**
 >
@@ -363,6 +450,8 @@ In addition to bug fixes, the fork makes a few opinionated default changes vs `@
 
 - **iOS `EventType.DELIVERED` now emitted for all foreground notifications** (since 9.3.0 — **BREAKING vs upstream**). Upstream Notifee had a guard in `willPresentNotification:` that suppressed DELIVERED for notifications created via `displayNotification()` (immediate display), emitting it only for trigger notifications. Android always emitted DELIVERED in both cases. The fork removes the guard so iOS matches Android. If you registered `onForegroundEvent` listeners that did heavy work on DELIVERED assuming the event would only fire for trigger notifications, audit them — you may now receive an event per `displayNotification()` call while in foreground. **Known limitation**: trigger notifications that fire while the app is in background or killed still do not emit DELIVERED on iOS — this is a platform limitation (`willPresentNotification:` is only invoked in foreground, and iOS provides no delegate callback for background-delivered triggers). If you need delivery confirmation for background trigger notifications on iOS, check the notification's presence via `getDisplayedNotifications()` after the app returns to foreground.
 
+- **Failed `smallIcon` resolution falls back to the app launcher icon instead of failing the notification** (since 10.1.0). Previously, when the string in `android.smallIcon` did not resolve to a valid resource ID at runtime (asset only in `src/debug/res/`, R8 resource shrinking, naming mismatch), the library logged the failure at DEBUG level — invisible in release logcat — and skipped `setSmallIcon()`, causing `NotificationCompat.Builder.build()` to throw `IllegalArgumentException`. The library now resolves to the app's launcher icon as a fallback and logs a warning with the original icon name and likely causes. See the [Troubleshooting section](#small-icon-not-showing-in-android-release-builds-falls-back-to-launcher-icon) for diagnosis tips.
+
 These changes are documented in the [CHANGELOG](CHANGELOG.md) under the release that introduced them. If you rely on any of the upstream defaults, you can either pin to the specific behavior via the opt-out flags listed above, or open an issue to discuss.
 
 ## Foreground Service Setup (Android 14+)
@@ -627,6 +716,26 @@ Default is `true` (backward compatible — Notifee handles everything, same as o
 
 ### Troubleshooting
 
+#### Small icon not showing in Android release builds (falls back to launcher icon)
+
+From 10.1.0, when the resource ID for `android.smallIcon` cannot be resolved at runtime, the library logs a warning and falls back to your app's launcher icon instead of failing the notification display. If you see your launcher icon in a notification where you expected a custom small icon, filter logcat for the `NOTIFEE` tag to find the resolution failure.
+
+Three causes account for the vast majority of reports:
+
+**Asset only in `src/debug/res/`.** When you add a drawable from Android Studio with the "Image Asset" wizard, the IDE sometimes places it under the `debug` variant only. The resource exists in debug builds but disappears in release. Copy or move the asset into `android/app/src/main/res/drawable-*/` (and the density buckets) so it participates in the release build.
+
+**R8 / ProGuard resource shrinking.** Release builds with `shrinkResources true` in the app's `build.gradle` can strip drawables that R8 judges unreferenced from code. Declare the asset as keep in `android/app/src/main/res/raw/keep.xml`:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<resources xmlns:tools="http://schemas.android.com/tools"
+    tools:keep="@drawable/ic_notification" />
+```
+
+**Naming mismatch.** Android resource names are case-sensitive and only accept `[a-z0-9_]`. A string like `smallIcon: 'icNotification'` will not resolve `ic_notification.png`. Rename the `smallIcon` value to match the file on disk exactly.
+
+For the full procedure on creating a small-icon asset via Android Studio, see [docs/react-native/android/appearance.mdx](docs/react-native/android/appearance.mdx).
+
 #### Custom sounds for push notifications in background or killed state
 
 If you've set `android.sound` and `ios.sound` in `displayNotification(...)` and the custom sound plays only when the app is in foreground, this is expected platform behavior — not a library bug. When a **remote push** (FCM/APNs) arrives while the app is killed, your JavaScript code never runs, so anything you configured client-side is ignored.
@@ -642,6 +751,31 @@ An advanced alternative on Android is to switch the backend to an FCM **data-onl
 
 Reference: [invertase/notifee#927](https://github.com/invertase/notifee/issues/927).
 
+#### Silent pushes and background fetch — handled by Firebase, not by this library
+
+`react-native-notify-kit` hooks into `UNUserNotificationCenterDelegate` on iOS to display notifications and dispatch tap/delivery events to JS. It does **not** hook into `application:didReceiveRemoteNotification:fetchCompletionHandler:` — the iOS entry point for silent pushes (`content-available: 1` with no visible alert) and background fetch. Those paths belong to [`@react-native-firebase/messaging`](https://rnfirebase.io/messaging/usage) via `setBackgroundMessageHandler`.
+
+If a silent push arrives while the app is killed and its only job is to trigger JS code (no notification displayed), subject to iOS's background budget it is handled entirely by Firebase's path — `notifee.onBackgroundEvent` will not fire, by design. If the silent push's JS handler then calls `notifee.displayNotification()`, the subsequent user tap on the displayed notification does flow through Notifee and fires `onBackgroundEvent` normally.
+
+Relates to upstream [invertase/notifee#597](https://github.com/invertase/notifee/issues/597) for apps with slow startup. For remote notifications that should fire `onBackgroundEvent` reliably on iOS, use [FCM Mode](docs/fcm-mode.mdx) — see also the note on [#1133](https://github.com/invertase/notifee/issues/1133) in the FCM Mode guide.
+
+#### `Could not resolve app.notifee:core:+` — does not apply to this fork
+
+If you arrived here from a Google search for this error, note: the error is specific
+to `@notifee/react-native` (the archived upstream package), where the native core was
+distributed as a pre-compiled AAR inside a bundled Maven repo at
+`node_modules/@notifee/react-native/android/libs/`. The fork eliminated that
+distribution model in 9.2.0 — the core compiles from source as part of the bridge
+module, so there is no Maven coordinate to resolve, no `extraMavenRepos` to configure
+on Expo, and no `FAIL_ON_PROJECT_REPOS` conflict on RN 0.74+. Migrating from
+`@notifee/react-native` to `react-native-notify-kit` removes the error with no
+additional `build.gradle` patching, no config plugin, and no Expo `extraMavenRepos`
+entry.
+
+References: upstream issues [#1079](https://github.com/invertase/notifee/issues/1079),
+[#1226](https://github.com/invertase/notifee/issues/1226),
+[#1262](https://github.com/invertase/notifee/issues/1262).
+
 ### Manual warmup control
 
 The library automatically pre-warms the foreground service notification path during app startup via `InitProvider`. **Most apps do not need to do anything extra.** However, in certain edge cases the automatic warmup may not be sufficient:
@@ -688,7 +822,7 @@ The script runs the macrobenchmark test in `apps/smoke/android/baselineprofile/`
 
 ## Documentation
 
-The upstream Notifee documentation remains the best reference for the public API and platform guides used by this fork.
+The full `react-native-notify-kit` documentation is hosted on docs.page and is kept in sync with this repo. It covers the public API, platform guides, FCM Mode, the server SDK, and the `init-nse` CLI.
 
 - [Overview](https://docs.page/marcocrupi/react-native-notify-kit/react-native/overview)
 - [Reference](https://docs.page/marcocrupi/react-native-notify-kit/react-native/reference)

package/RNNotifeeCore.podspec

@@ -16,6 +16,8 @@ Pod::Spec.new do |s|
 
   s.cocoapods_version        = '>= 1.10.0'
   s.ios.deployment_target   = '15.1'
+  s.module_name            = 'RNNotifeeCore'
+  s.pod_target_xcconfig    = { 'DEFINES_MODULE' => 'YES' }
     
   if defined?($NotifeeCoreFromSources) && $NotifeeCoreFromSources == true
     # internal dev flag used by Notifee devs, ignore

package/android/src/androidTest/java/app/notifee/core/RebootRecoveryTest.java

@@ -14,8 +14,8 @@ package app.notifee.core;
  * NOT RUN IN CI.
  *
  * Instrumented regression suite for the reboot-recovery path in
- * NotifeeAlarmManager.rescheduleNotifications, covering three upstream
- * issues across five test cases:
+ * NotifeeAlarmManager.rescheduleNotifications, covering four upstream
+ * issues across six test cases:
  *
  *   1. rescheduleNotifications_advancesEveryAnchorBeforeCompleting
  *      (upstream invertase/notifee#549 — reboot-recovery anchor persistence
@@ -54,6 +54,15 @@ package app.notifee.core;
  *      handleStaleNonRepeatingTrigger routes the failure through the
  *      resilient branch that still runs deleteById.
  *
+ *   6. rescheduleNotifications_nonRepeatingFuture_preservesAnchorAndRearmsAlarm
+ *      (upstream invertase/notifee#991 — non-repeating TIMESTAMP triggers lost
+ *      after device reboot on Android 14). Seeds a non-repeating row 5 minutes
+ *      in the future and asserts the row survives reboot recovery with its
+ *      anchor preserved AND a fresh AlarmManager PendingIntent registered.
+ *      Complements the past-stale paths above by covering the happy-path
+ *      branch where setNextTimestamp early-returns at TimestampTriggerModel:136
+ *      and rescheduleNotification re-arms the original anchor.
+ *
  * Run manually via the smoke harness (recommended — wraps gradle + copies
  * reports + fails loud if no XML reports are found):
  *
@@ -133,6 +142,9 @@ public class RebootRecoveryTest {
   /** 48 hours before "now" — well beyond the 24h grace period. */
   private static final long STALE_BEYOND_GRACE_OFFSET_MS = 48 * HOUR_IN_MS;
 
+  /** 5 minutes after "now" — the future-non-repeating happy path for upstream #991. */
+  private static final long FUTURE_NON_REPEATING_OFFSET_MS = 5L * 60 * 1000;
+
   /**
    * Channel id used by the within-grace stale-trigger test fixture. Must match a real Android
    * notification channel created in {@link #setUp()} so {@code
@@ -181,6 +193,7 @@ public class RebootRecoveryTest {
     NotifeeAlarmManager.cancelNotification(staleWithinGraceTestId());
     NotifeeAlarmManager.cancelNotification(staleBeyondGraceTestId());
     NotifeeAlarmManager.cancelNotification(staleDisplayFailsTestId());
+    NotifeeAlarmManager.cancelNotification(nonRepeatingFutureTestId());
     // Dismiss any notifications the within-grace tests may have posted so the device
     // notification shade is left clean — the Room row is the test's contract, but the
     // visible notification is a side effect we should not leave behind.
@@ -387,6 +400,81 @@ public class RebootRecoveryTest {
         repo.getWorkDataById(id).get(5, TimeUnit.SECONDS) == null);
   }
 
+  /**
+   * Regression test for upstream invertase/notifee#991 — non-repeating TIMESTAMP triggers whose
+   * fire time is still in the future at boot must be re-armed with their original anchor preserved.
+   *
+   * <p>The existing #734 tests cover the past-stale branches of {@code
+   * handleStaleNonRepeatingTrigger}; this fills the happy-path gap. Seeds a non-repeating trigger 5
+   * minutes in the future, invokes reboot recovery, and asserts that:
+   *
+   * <ul>
+   *   <li>the Room row survives (not stale → not deleted),
+   *   <li>the timestamp is unchanged (non-repeating → {@code setNextTimestamp} early-returns at
+   *       {@code TimestampTriggerModel.java:136-139}),
+   *   <li>an {@code AlarmManager} {@code PendingIntent} has been re-registered for the row, proving
+   *       {@code rescheduleNotification} → {@code scheduleTimestampTriggerNotification} reached the
+   *       alarm-set call.
+   * </ul>
+   */
+  @Test
+  public void rescheduleNotifications_nonRepeatingFuture_preservesAnchorAndRearmsAlarm()
+      throws Exception {
+    long now = System.currentTimeMillis();
+    long futureAnchor = now + FUTURE_NON_REPEATING_OFFSET_MS;
+    String id = nonRepeatingFutureTestId();
+
+    repo.insert(buildNonRepeatingEntity(id, futureAnchor)).get(5, TimeUnit.SECONDS);
+    assertEquals(1, repo.getAll().get(5, TimeUnit.SECONDS).size());
+
+    new NotifeeAlarmManager().rescheduleNotifications(null);
+
+    PendingIntent pi = awaitPendingIntentRegistered(id);
+    assertNotNull(
+        "AlarmManager PendingIntent must be re-registered for the non-repeating future row " + id,
+        pi);
+
+    WorkDataEntity row = repo.getWorkDataById(id).get(5, TimeUnit.SECONDS);
+    assertNotNull("non-repeating future row must survive reboot recovery", row);
+    Bundle triggerBundle = ObjectUtils.bytesToBundle(row.getTrigger());
+    long preservedAnchor = ObjectUtils.getLong(triggerBundle.get("timestamp"));
+    assertEquals(
+        "non-repeating future trigger anchor must NOT be advanced — setNextTimestamp early-returns"
+            + " when repeatFrequency is -1 and timestamp is in the future",
+        futureAnchor,
+        preservedAnchor);
+  }
+
+  /**
+   * Polls until an {@code AlarmManager} {@code PendingIntent} keyed off {@code id.hashCode()} is
+   * registered (FLAG_NO_CREATE returns non-null). Times out via {@link #fail(String)} if the
+   * reschedule pass never reaches {@code alarmManager.set*}.
+   */
+  private PendingIntent awaitPendingIntentRegistered(String id) throws Exception {
+    Intent intent = new Intent(context, NotificationAlarmReceiver.class);
+    intent.putExtra("notificationId", id);
+    long deadline = System.currentTimeMillis() + POLL_DEADLINE_MS;
+    while (System.currentTimeMillis() < deadline) {
+      PendingIntent pi =
+          PendingIntent.getBroadcast(
+              context,
+              id.hashCode(),
+              intent,
+              PendingIntent.FLAG_NO_CREATE | PendingIntent.FLAG_MUTABLE);
+      if (pi != null) {
+        return pi;
+      }
+      Thread.sleep(POLL_INTERVAL_MS);
+    }
+    fail(
+        "AlarmManager PendingIntent for "
+            + id
+            + " was not registered within "
+            + POLL_DEADLINE_MS
+            + "ms — the #991 fix in rescheduleNotification may be broken");
+    return null; // unreachable
+  }
+
   /** Polls {@link WorkDataRepository#getWorkDataById(String)} until it returns {@code null}. */
   private void awaitRowDeleted(String id) throws Exception {
     long deadline = System.currentTimeMillis() + POLL_DEADLINE_MS;
@@ -566,4 +654,8 @@ public class RebootRecoveryTest {
   private static String staleDisplayFailsTestId() {
     return "reboot-recovery-stale-display-fails-test";
   }
+
+  private static String nonRepeatingFutureTestId() {
+    return "reboot-recovery-non-repeating-future-test";
+  }
 }

package/android/src/main/AndroidManifest.xml

@@ -49,15 +49,16 @@
       </intent-filter>
     </receiver>
 
+    <!--
+      NotificationAlarmReceiver is invoked exclusively via PendingIntent broadcasts from
+      AlarmManager (NotifeeAlarmManager.scheduleTimestampTriggerNotification). It does not
+      handle any system-broadcast Intent action — onReceive dispatches intent.getExtras()
+      to NotifeeAlarmManager.displayScheduledNotification, which early-returns on null
+      extras. Reboot recovery is owned by RebootBroadcastReceiver above.
+    -->
     <receiver
       android:name="app.notifee.core.NotificationAlarmReceiver"
-      android:exported="false">
-      <intent-filter>
-        <action android:name="android.intent.action.BOOT_COMPLETED" />
-        <action android:name="android.intent.action.QUICKBOOT_POWERON" />
-        <action android:name="com.htc.intent.action.QUICKBOOT_POWERON"/>
-      </intent-filter>
-    </receiver>
+      android:exported="false" />
 
     <!-- Broadcast Receiver -->
     <receiver

package/android/src/main/java/app/notifee/core/NotificationManager.java

@@ -312,6 +312,8 @@ class NotificationManager {
               } else {
                 builder.setSmallIcon(smallIconId);
               }
+            } else {
+              builder.setSmallIcon(ResourceUtils.getFallbackSmallIconId(getApplicationContext()));
             }
 
             if (androidModel.getSortKey() != null) {

package/android/src/main/java/app/notifee/core/model/NotificationAndroidModel.java

@@ -533,9 +533,14 @@ public class NotificationAndroidModel {
     int smallIconId = ResourceUtils.getImageResourceId(rawIcon);
 
     if (smallIconId == 0) {
-      Logger.d(
-          "NotificationAndroidModel",
-          String.format("Notification small icon '%s' could not be found", rawIcon));
+      Logger.w(
+          TAG,
+          String.format(
+              "Notification small icon '%s' could not be resolved; falling back to the app"
+                  + " launcher icon. Common causes: asset only in src/debug/res, R8 resource"
+                  + " shrinking, or name mismatch (names must be lowercase with underscores)."
+                  + " See README Troubleshooting.",
+              rawIcon));
       return null;
     }
 

package/android/src/main/java/app/notifee/core/utility/ResourceUtils.java

@@ -18,6 +18,7 @@ package app.notifee.core.utility;
  */
 
 import android.content.Context;
+import android.content.pm.ApplicationInfo;
 import android.graphics.Bitmap;
 import android.graphics.Canvas;
 import android.graphics.Color;
@@ -223,6 +224,33 @@ public class ResourceUtils {
     return resourceId;
   }
 
+  /**
+   * Returns a resource id guaranteed to be usable as a smallIcon. Three-layer fallback: (1) {@code
+   * applicationInfo.icon}, (2) {@code applicationInfo.logo}, (3) the system {@code
+   * android.R.drawable.ic_dialog_info} drawable. Never returns 0, never throws.
+   *
+   * <p>Used by {@link app.notifee.core.NotificationManager} to keep a notification valid when the
+   * user-supplied {@code smallIcon} string cannot be resolved to a drawable at runtime.
+   */
+  public static int getFallbackSmallIconId(Context context) {
+    try {
+      if (context != null) {
+        ApplicationInfo info = context.getApplicationInfo();
+        if (info != null) {
+          if (info.icon != 0) {
+            return info.icon;
+          }
+          if (info.logo != 0) {
+            return info.logo;
+          }
+        }
+      }
+    } catch (Exception e) {
+      Logger.w(TAG, "getFallbackSmallIconId -> falling back to system default icon", e);
+    }
+    return android.R.drawable.ic_dialog_info;
+  }
+
   /** Attempts to find a resource id by name and type */
   private static int getResourceIdByName(String name, String type) {
     if (name == null || name.isEmpty()) {

package/android/src/test/java/app/notifee/core/model/NotificationAndroidModelSmallIconFallbackTest.java

@@ -0,0 +1,74 @@
+package app.notifee.core.model;
+
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import static org.junit.Assert.assertNull;
+
+import android.os.Bundle;
+import app.notifee.core.ContextHolder;
+import org.junit.Before;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.robolectric.RobolectricTestRunner;
+import org.robolectric.RuntimeEnvironment;
+
+/**
+ * Unit coverage for {@link NotificationAndroidModel#getSmallIcon()}.
+ *
+ * <p>The method returns {@code null} when the smallIcon string cannot be resolved to a valid
+ * resource id. This is the trigger condition that {@link app.notifee.core.NotificationManager}
+ * translates into the launcher-icon fallback (upstream invertase/notifee#733).
+ *
+ * <p>The happy path (valid resource id returned) is covered end-to-end by smoke tests on real
+ * devices — unit-testing it here would require a real drawable registered against the test
+ * application package, which Robolectric does not stage by default.
+ */
+@RunWith(RobolectricTestRunner.class)
+public class NotificationAndroidModelSmallIconFallbackTest {
+
+  @Before
+  public void setUp() {
+    // getSmallIcon() -> ResourceUtils.getImageResourceId() -> getResourceIdByName() reads
+    // ContextHolder.getApplicationContext() to call context.getResources().getIdentifier(...).
+    // Robolectric does not auto-populate ContextHolder, so we wire it up here. Same pattern
+    // used by ForegroundServiceTest and NotifeeAlarmManagerHandleStaleTest.
+    ContextHolder.setApplicationContext(RuntimeEnvironment.getApplication());
+  }
+
+  @Test
+  public void returnsNull_whenSmallIconKeyMissing() {
+    Bundle bundle = new Bundle();
+    NotificationAndroidModel model = NotificationAndroidModel.fromBundle(bundle);
+    assertNull(model.getSmallIcon());
+  }
+
+  @Test
+  public void returnsNull_whenSmallIconCannotBeResolved() {
+    Bundle bundle = new Bundle();
+    bundle.putString("smallIcon", "nonexistent_icon_name_for_test");
+    NotificationAndroidModel model = NotificationAndroidModel.fromBundle(bundle);
+    assertNull(model.getSmallIcon());
+  }
+
+  @Test
+  public void returnsNull_whenSmallIconEmptyString() {
+    Bundle bundle = new Bundle();
+    bundle.putString("smallIcon", "");
+    NotificationAndroidModel model = NotificationAndroidModel.fromBundle(bundle);
+    assertNull(model.getSmallIcon());
+  }
+}