react-native-notify-kit 9.6.0 → 10.0.0

package/src/fcm/index.ts

@@ -0,0 +1,4 @@
+export { parseFcmPayload } from './parseFcmPayload';
+export type { ParsedPayload } from './parseFcmPayload';
+export { reconstructNotification } from './reconstructNotification';
+export type { FcmRemoteMessage, FcmConfig } from './types';

package/src/fcm/parseFcmPayload.ts

@@ -0,0 +1,56 @@
+/*
+ * Pure function — parses the `notifee_options` blob from an FCM data payload.
+ */
+
+const PREFIX = '[react-native-notify-kit]';
+
+export type ParsedPayload = {
+  _v?: number;
+  title?: string;
+  body?: string;
+  android?: Record<string, unknown>;
+  ios?: Record<string, unknown>;
+  [key: string]: unknown;
+};
+
+/**
+ * Extracts and JSON-parses the `notifee_options` value from the FCM data map.
+ * Returns the parsed object on success, or `null` when:
+ *  - `data` is undefined/null
+ *  - `data.notifee_options` is missing
+ *  - JSON parsing fails (a `console.warn` is emitted)
+ */
+export function parseFcmPayload(data: Record<string, string> | undefined): ParsedPayload | null {
+  if (!data || typeof data.notifee_options !== 'string') {
+    return null;
+  }
+
+  let parsed: ParsedPayload;
+  try {
+    parsed = JSON.parse(data.notifee_options);
+  } catch (e: unknown) {
+    const detail = e instanceof Error ? e.message : String(e);
+    console.warn(
+      `${PREFIX} Failed to parse notifee_options: ${detail}. Falling back to raw title/body.`,
+    );
+    return null;
+  }
+
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    console.warn(
+      `${PREFIX} notifee_options parsed to a non-object value. Falling back to raw title/body.`,
+    );
+    return null;
+  }
+
+  // Version check (Rule C5) — coerce to number to handle string _v from
+  // intermediaries that stringify FCM data values.
+  const versionNum = Number(parsed._v);
+  if (!Number.isNaN(versionNum) && versionNum > 1) {
+    console.warn(
+      `${PREFIX} notifee_options version ${versionNum} is newer than supported version 1. Display may be incomplete.`,
+    );
+  }
+
+  return parsed;
+}

package/src/fcm/reconstructNotification.ts

@@ -0,0 +1,201 @@
+/*
+ * Pure function — builds a Notification object from a parsed notifee_options
+ * blob, an FCM remote message, and the current FcmConfig.
+ */
+
+import { Notification } from '../types/Notification';
+import { NotificationAndroid, AndroidStyle } from '../types/NotificationAndroid';
+import { NotificationIOS } from '../types/NotificationIOS';
+import { isAndroid, isIOS } from '../utils';
+import type { FcmConfig, FcmRemoteMessage } from './types';
+import type { ParsedPayload } from './parseFcmPayload';
+
+const PREFIX = '[react-native-notify-kit]';
+const RESERVED_DATA_KEYS = new Set(['notifee_options', 'notifee_data']);
+
+const VALID_INTERRUPTION_LEVELS = new Set(['active', 'critical', 'passive', 'timeSensitive']);
+
+const STYLE_TYPE_MAP: Record<string, AndroidStyle | undefined> = {
+  BIG_TEXT: AndroidStyle.BIGTEXT,
+  BIG_PICTURE: AndroidStyle.BIGPICTURE,
+};
+
+/**
+ * Reconstructs a {@link Notification} object suitable for
+ * `displayNotification` from the parsed FCM payload + config defaults.
+ */
+export function reconstructNotification(
+  parsed: ParsedPayload | null,
+  remoteMessage: FcmRemoteMessage,
+  config: FcmConfig,
+): Notification {
+  const data = rebuildData(remoteMessage.data);
+
+  const title =
+    parsed?.title ?? remoteMessage.notification?.title ?? remoteMessage.data?.title ?? '';
+
+  const body = parsed?.body ?? remoteMessage.notification?.body ?? remoteMessage.data?.body ?? '';
+
+  const notification: Notification = {
+    id:
+      ((parsed as Record<string, unknown> | null)?.id as string | undefined) ??
+      remoteMessage.messageId,
+    title,
+    body,
+  };
+
+  if (Object.keys(data).length > 0) {
+    notification.data = data;
+  }
+
+  if (isAndroid && (parsed?.android || config.defaultChannelId || config.defaultPressAction)) {
+    notification.android = buildAndroidConfig(parsed?.android, config);
+  }
+
+  if (isIOS && parsed?.ios) {
+    notification.ios = buildIosConfig(parsed.ios);
+  }
+
+  return notification;
+}
+
+// ---------------------------------------------------------------------------
+// Data reconstruction (Rules C6 / C7)
+// ---------------------------------------------------------------------------
+
+function rebuildData(rawData: Record<string, string> | undefined): Record<string, string> {
+  if (!rawData) {
+    return {};
+  }
+
+  // Start with top-level data keys (excluding reserved)
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(rawData)) {
+    if (!RESERVED_DATA_KEYS.has(key)) {
+      result[key] = value;
+    }
+  }
+
+  // Merge notifee_data blob — overrides top-level on conflict (Rule C7)
+  const notifeeDataRaw = rawData.notifee_data;
+  if (typeof notifeeDataRaw === 'string') {
+    try {
+      const notifeeData = JSON.parse(notifeeDataRaw) as Record<string, string>;
+      if (notifeeData && typeof notifeeData === 'object') {
+        Object.assign(result, notifeeData);
+      }
+    } catch {
+      console.warn(`${PREFIX} Failed to parse notifee_data. Using top-level data keys only.`);
+    }
+  }
+
+  // Post-merge strip: notifee_data blob could contain reserved keys
+  for (const key of RESERVED_DATA_KEYS) {
+    delete result[key];
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Android config mapping
+// ---------------------------------------------------------------------------
+
+function buildAndroidConfig(
+  raw: Record<string, unknown> | undefined,
+  config: FcmConfig,
+): NotificationAndroid {
+  const android: NotificationAndroid = {};
+
+  // channelId: payload > config default
+  const channelId = raw?.channelId ?? config.defaultChannelId;
+  if (typeof channelId === 'string') {
+    android.channelId = channelId;
+  }
+
+  // pressAction: payload > config default
+  const pressAction = raw?.pressAction ?? config.defaultPressAction;
+  if (pressAction && typeof pressAction === 'object') {
+    android.pressAction = pressAction as NotificationAndroid['pressAction'];
+  }
+
+  // Direct string copies
+  if (typeof raw?.smallIcon === 'string') android.smallIcon = raw.smallIcon;
+  if (typeof raw?.largeIcon === 'string') android.largeIcon = raw.largeIcon;
+  if (typeof raw?.color === 'string') android.color = raw.color;
+
+  // Actions array — pass through (trust server validation)
+  if (Array.isArray(raw?.actions)) {
+    android.actions = raw.actions as NotificationAndroid['actions'];
+  }
+
+  // Style — enum mapping with defense-in-depth for unknown types
+  if (raw?.style && typeof raw.style === 'object') {
+    const style = raw.style as { type?: string; text?: string; picture?: string };
+    if (typeof style.type === 'string') {
+      const mappedType = STYLE_TYPE_MAP[style.type];
+      if (mappedType !== undefined) {
+        if (mappedType === AndroidStyle.BIGTEXT && typeof style.text === 'string') {
+          android.style = { type: AndroidStyle.BIGTEXT, text: style.text };
+        } else if (mappedType === AndroidStyle.BIGPICTURE && typeof style.picture === 'string') {
+          android.style = { type: AndroidStyle.BIGPICTURE, picture: style.picture };
+        } else {
+          const field = mappedType === AndroidStyle.BIGTEXT ? 'text' : 'picture';
+          console.warn(
+            `${PREFIX} android.style.type '${style.type}' present but required '${field}' field missing or not a string. Style ignored.`,
+          );
+        }
+      } else {
+        console.warn(`${PREFIX} Unknown android.style.type '${style.type}'. Style ignored.`);
+      }
+    }
+  }
+
+  return android;
+}
+
+// ---------------------------------------------------------------------------
+// iOS config mapping
+// ---------------------------------------------------------------------------
+
+function buildIosConfig(raw: Record<string, unknown>): NotificationIOS {
+  const ios: NotificationIOS = {};
+
+  if (typeof raw.sound === 'string') ios.sound = raw.sound;
+  if (typeof raw.categoryId === 'string') ios.categoryId = raw.categoryId;
+  if (typeof raw.threadId === 'string') ios.threadId = raw.threadId;
+
+  // interruptionLevel — defense-in-depth for unknown values
+  if (typeof raw.interruptionLevel === 'string') {
+    if (VALID_INTERRUPTION_LEVELS.has(raw.interruptionLevel)) {
+      ios.interruptionLevel = raw.interruptionLevel as NotificationIOS['interruptionLevel'];
+    } else {
+      console.warn(`${PREFIX} Unknown ios.interruptionLevel '${raw.interruptionLevel}'. Ignored.`);
+    }
+  }
+
+  // Attachments — rename identifier → id, filter out invalid entries
+  if (Array.isArray(raw.attachments)) {
+    ios.attachments = (raw.attachments as Array<unknown>)
+      .filter((att): att is Record<string, unknown> => {
+        if (att == null || typeof att !== 'object') return false;
+        const a = att as Record<string, unknown>;
+        if (typeof a.url !== 'string' || a.url.length === 0) {
+          console.warn(`${PREFIX} ios.attachments entry has missing or empty url. Skipped.`);
+          return false;
+        }
+        return true;
+      })
+      .map(att => {
+        const mapped: { id?: string; url: string } = {
+          url: att.url as string,
+        };
+        if (typeof att.identifier === 'string') {
+          mapped.id = att.identifier;
+        }
+        return mapped;
+      });
+  }
+
+  return ios;
+}

package/src/fcm/types.ts

@@ -0,0 +1,57 @@
+/*
+ * Types for the FCM message handler. Declared structurally to avoid a peer
+ * dependency on @react-native-firebase/messaging.
+ */
+
+/**
+ * Minimal subset of `@react-native-firebase/messaging`'s RemoteMessage that
+ * `handleFcmMessage` actually reads.
+ */
+export type FcmRemoteMessage = {
+  messageId?: string;
+  data?: Record<string, string>;
+  notification?: {
+    title?: string;
+    body?: string;
+  };
+};
+
+/**
+ * Configuration for `handleFcmMessage`. Call `setFcmConfig` once
+ * at app startup (typically in `index.js` before `registerComponent`).
+ */
+export type FcmConfig = {
+  /**
+   * Default channelId used when `notifee_options.android.channelId` is absent.
+   * If this is also absent and the payload has no channelId,
+   * `displayNotification` will throw on Android — same behavior as calling
+   * `displayNotification` without a channel.
+   */
+  defaultChannelId?: string;
+
+  /**
+   * Default pressAction when `notifee_options.android.pressAction` is absent.
+   * Mirrors the existing behavior: `{ id: 'default', launchActivity: 'default' }`.
+   */
+  defaultPressAction?: { id: string; launchActivity?: string };
+
+  /**
+   * What to do when `remoteMessage.data.notifee_options` is absent entirely.
+   * - `'display'`: build a minimal notification from `remoteMessage.notification`
+   *   title/body (or `data.title`/`data.body` as a fallback). Uses `defaultChannelId`.
+   * - `'ignore'`: return `null` without displaying anything.
+   *
+   * @default 'display'
+   */
+  fallbackBehavior?: 'display' | 'ignore';
+
+  /** iOS-specific options. */
+  ios?: {
+    /**
+     * When `true`, foreground notifications delivered via `handleFcmMessage`
+     * are NOT displayed (only events are emitted).
+     * @default false
+     */
+    suppressForegroundBanner?: boolean;
+  };
+};

package/src/index.ts

@@ -31,3 +31,5 @@ export * from './types/Notification';
 export * from './types/Trigger';
 export * from './types/NotificationIOS';
 export * from './types/NotificationAndroid';
+export * from './types/PowerManagerInfo';
+export type { FcmRemoteMessage, FcmConfig } from './fcm/types';

package/src/internal/fcmContract.d.ts

@@ -0,0 +1,150 @@
+/**
+ * FCM wire contract — shared between the server SDK (Node) and the upcoming
+ * Phase 2 client `handleFcmMessage`. Types only, no runtime code.
+ *
+ * This module is the single source of truth for the shape of `notifee_options`
+ * embedded in FCM data / APNs payloads. Both sides (server builder, client
+ * reader) import from here to guarantee parity.
+ *
+ * NOT a public API. Consumers should use `react-native-notify-kit/server` for
+ * building payloads and the main `react-native-notify-kit` module for client
+ * handling. The `internal/` directory exists to hold cross-module contracts
+ * that are not for end users.
+ */
+
+export type NotifyKitPressAction = {
+  id: string;
+  launchActivity?: string;
+};
+
+export type NotifyKitAndroidAction = {
+  title: string;
+  pressAction: NotifyKitPressAction;
+  input?: boolean;
+};
+
+export type NotifyKitAndroidStyle =
+  | { type: 'BIG_TEXT'; text: string }
+  | { type: 'BIG_PICTURE'; picture: string };
+
+export type NotifyKitAndroidConfig = {
+  channelId?: string;
+  smallIcon?: string;
+  largeIcon?: string;
+  color?: string;
+  pressAction?: NotifyKitPressAction;
+  actions?: NotifyKitAndroidAction[];
+  style?: NotifyKitAndroidStyle;
+};
+
+export type NotifyKitIosAttachment = {
+  url: string;
+  identifier?: string;
+};
+
+export type NotifyKitIosInterruptionLevel = 'passive' | 'active' | 'timeSensitive' | 'critical';
+
+export type NotifyKitIosConfig = {
+  sound?: string;
+  categoryId?: string;
+  threadId?: string;
+  interruptionLevel?: NotifyKitIosInterruptionLevel;
+  attachments?: NotifyKitIosAttachment[];
+};
+
+export type NotifyKitNotification = {
+  /**
+   * Optional notification identifier. When provided, it is also used as the
+   * FCM collapse key (Android `collapse_key`, iOS `apns-collapse-id`) unless
+   * `options.collapseKey` is explicitly set. Collapse key precedence (Rule 7):
+   *   1. `options.collapseKey` if set
+   *   2. `notification.id` if set
+   *   3. Omitted (no collapse behaviour)
+   *
+   * This means setting `id` implicitly enables notification replacement on the
+   * device: a new notification with the same `id` replaces the previous one.
+   * If you need `id` for local deduplication without collapse behaviour, set a
+   * distinct `options.collapseKey` or leave both unset.
+   */
+  id?: string;
+  title: string;
+  body: string;
+  data?: Record<string, string>;
+  android?: NotifyKitAndroidConfig;
+  ios?: NotifyKitIosConfig;
+};
+
+export type NotifyKitOptions = {
+  androidPriority?: 'high' | 'normal';
+  iosBadgeCount?: number;
+  ttl?: number;
+  collapseKey?: string;
+};
+
+export type NotifyKitPayloadInput = {
+  token?: string;
+  topic?: string;
+  condition?: string;
+  notification: NotifyKitNotification;
+  options?: NotifyKitOptions;
+};
+
+export type ApnsInterruptionLevel = 'passive' | 'active' | 'time-sensitive' | 'critical';
+
+export type NotifyKitAndroidOutput = {
+  priority: 'HIGH' | 'NORMAL';
+  collapse_key?: string;
+  ttl?: string;
+};
+
+export type NotifyKitApnsAps = {
+  alert: { title: string; body: string };
+  sound?: string;
+  category?: string;
+  'mutable-content': 1;
+  'thread-id'?: string;
+  'interruption-level'?: ApnsInterruptionLevel;
+  badge?: number;
+};
+
+export type NotifyKitApnsHeaders = {
+  'apns-push-type': 'alert';
+  'apns-priority': '10';
+  'apns-collapse-id'?: string;
+  'apns-expiration'?: string;
+};
+
+export type NotifyKitApnsPayload = {
+  aps: NotifyKitApnsAps;
+  notifee_options: string;
+  notifee_data?: string;
+};
+
+export type NotifyKitApnsOutput = {
+  headers: NotifyKitApnsHeaders;
+  payload: NotifyKitApnsPayload;
+};
+
+export type NotifyKitPayloadOutput = {
+  token?: string;
+  topic?: string;
+  condition?: string;
+  data: Record<string, string>;
+  android: NotifyKitAndroidOutput;
+  apns: NotifyKitApnsOutput;
+  sizeBytes: number;
+};
+
+export type SerializedNotifeeOptions = {
+  _v: 1;
+  title: string;
+  body: string;
+  android?: NotifyKitAndroidConfig;
+  ios?: NotifyKitIosConfig;
+};
+
+// Android output must never carry a `notification` field (the server enforces
+// data-only delivery for Android to prevent FCM from auto-displaying). This
+// invariant is exercised at runtime by the `never includes a notification
+// field` test in buildPayload.test.ts and is enforced structurally by the
+// shape of NotifyKitAndroidOutput above.

package/src/types/Module.ts

@@ -17,6 +17,7 @@ import {
 } from './NotificationIOS';
 import { PowerManagerInfo } from './PowerManagerInfo';
 import { DisplayedNotification, NotificationSettings, TriggerNotification } from '..';
+import type { FcmConfig, FcmRemoteMessage } from '../fcm/types';
 
 export interface Module {
   /**
@@ -660,6 +661,28 @@ export interface Module {
    * @platform android
    */
   hideNotificationDrawer(): void;
+
+  /**
+   * Processes an FCM remote message produced by the NotifyKit server SDK and
+   * displays a Notifee notification according to the embedded `notifee_options`.
+   *
+   * Safe to call from both `setBackgroundMessageHandler` and `onMessage`.
+   *
+   * @returns The displayed notification ID, or `null` if the call was an
+   *          intentional no-op (iOS background, `fallbackBehavior: 'ignore'`,
+   *          `suppressForegroundBanner`).
+   */
+  handleFcmMessage(remoteMessage: FcmRemoteMessage): Promise<string | null>;
+
+  /**
+   * Configures defaults for {@link handleFcmMessage}. Call once at app startup,
+   * typically in `index.js` before `registerComponent`.
+   *
+   * Returns Promise for forward compatibility — a future version may persist
+   * config across cold starts, which would be async. Currently resolves
+   * synchronously.
+   */
+  setFcmConfig(config: FcmConfig): Promise<void>;
 }
 
 /**

package/src/types/Notification.ts

@@ -46,10 +46,41 @@ export interface Notification {
   body?: string | undefined;
 
   /**
-   * Additional data to store on the notification.
-   *
-   * Data can be used to provide additional context to your notification which can be retrieved
-   * at a later point in time (e.g. via an event).
+   * Additional data to associate with the notification.
+   *
+   * On Android, when populated by `getDisplayedNotifications()`, the `data`
+   * field reflects custom keys present in the underlying `Notification.extras`,
+   * with the following keys filtered out: prefixes `android.`, `google.`,
+   * `gcm.`, `fcm.` (with trailing dot — `fcmRegion` survives), and `notifee`
+   * (no trailing dot — library's reserved namespace, `notifeeFoo` is also
+   * filtered), plus exact keys `from`, `collapse_key`, `message_type`,
+   * `message_id`, `aps`, `fcm_options`.
+   *
+   * **Important FCM platform limitation on Android**: when the FCM Android SDK
+   * auto-displays a `notification`+`data` push while the app is in background
+   * or killed, custom `data` fields are placed only on the tap-action
+   * `PendingIntent` and never on `Notification.extras`. This is FCM's design
+   * (see `CommonNotificationBuilder.createContentIntent` in the firebase-android-sdk
+   * source) and cannot be worked around from any library — the PendingIntent's
+   * extras are sealed by Android's security model. Tracked in
+   * firebase-android-sdk#2639 (open since 2021).
+   *
+   * The `data` field DOES surface custom keys for: notifications created via
+   * `notifee.displayNotification({ data })`, FCM data-only messages handled
+   * in `onMessageReceived` followed by an explicit `displayNotification()`,
+   * custom `FirebaseMessagingService.handleIntent` overrides that inject
+   * extras before display, and notifications posted by other libraries that
+   * call `NotificationCompat.Builder.addExtras(bundle)`.
+   *
+   * Recommended pattern for full control over FCM push notifications on Android:
+   * send FCM data-only messages (no `notification` field server-side), handle
+   * them in `onMessageReceived`, and render the notification via
+   * `notifee.displayNotification()`.
+   *
+   * Note: the `fcm` filter diverges from iOS, which uses a broader bare-`fcm*`
+   * prefix filter (deliberately, to catch `fcm_options`). On Android, only
+   * `fcm.` (with dot) and the exact key `fcm_options` are filtered — custom
+   * keys like `fcmRegion` are preserved on Android but filtered on iOS.
    */
   data?: { [key: string]: string | object | number };
 

package/src/version.ts

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