react-native-notify-kit 9.7.0 → 10.1.0

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/validators/validateTrigger.ts

@@ -52,11 +52,35 @@ export default function validateTrigger(trigger: Trigger): Trigger {
   }
 }
 
+// Smallest plausible epoch-ms value for a future trigger. 1e12 ms ≈ Sep 2001;
+// anything smaller is almost certainly the wrong unit (seconds-since-epoch,
+// or a Date.getDate() day-of-month). We intercept the three common shapes
+// and emit targeted hints — see upstream invertase/notifee#872 for the
+// year-after-year UX pattern this guards against.
+const MIN_PLAUSIBLE_EPOCH_MS = 1e12;
+const MIN_PLAUSIBLE_EPOCH_SECONDS = 1e9;
+
 function validateTimestampTrigger(trigger: TimestampTrigger): TimestampTrigger {
   if (!isNumber(trigger.timestamp)) {
     throw new Error("'trigger.timestamp' expected a number value.");
   }
 
+  if (trigger.timestamp < MIN_PLAUSIBLE_EPOCH_MS) {
+    if (trigger.timestamp >= 1 && trigger.timestamp <= 31) {
+      throw new Error(
+        `'trigger.timestamp' looks like a day-of-month (${trigger.timestamp}). Did you mean \`date.getTime()\` instead of \`date.getDate()\`?`,
+      );
+    }
+    if (trigger.timestamp >= MIN_PLAUSIBLE_EPOCH_SECONDS) {
+      throw new Error(
+        `'trigger.timestamp' looks like seconds since epoch (${trigger.timestamp}). Notifee expects milliseconds — multiply by 1000, or use \`Date.now()\` / \`date.getTime()\`.`,
+      );
+    }
+    throw new Error(
+      `'trigger.timestamp' (${trigger.timestamp}) is too small to be a valid epoch millisecond value. Use \`Date.now()\` or \`someDate.getTime()\`.`,
+    );
+  }
+
   const now = Date.now();
   if (trigger.timestamp <= now) {
     throw new Error("'trigger.timestamp' date must be in the future.");

package/src/version.ts

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