react-native-notify-kit 9.7.0 → 10.0.0

package/server/dist/validation.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateInput = validateInput;
+const PREFIX = '[react-native-notify-kit/server]';
+const RESERVED_DATA_KEYS = ['notifee_options', 'notifee_data'];
+function err(category, message) {
+    return new Error(`${PREFIX} ${category}: ${message}`);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function validateInput(input) {
+    if (input === null || typeof input !== 'object') {
+        throw err('Validation', 'input must be an object');
+    }
+    const routingCount = (input.token !== undefined ? 1 : 0) +
+        (input.topic !== undefined ? 1 : 0) +
+        (input.condition !== undefined ? 1 : 0);
+    if (routingCount !== 1) {
+        throw err('Routing', `exactly one of 'token', 'topic', or 'condition' must be provided. Got: ${routingCount}`);
+    }
+    if (input.token !== undefined && !isNonEmptyString(input.token)) {
+        throw err('Routing', "'token' must be a non-empty string");
+    }
+    if (input.topic !== undefined && !isNonEmptyString(input.topic)) {
+        throw err('Routing', "'topic' must be a non-empty string");
+    }
+    if (input.condition !== undefined && !isNonEmptyString(input.condition)) {
+        throw err('Routing', "'condition' must be a non-empty string");
+    }
+    const { notification } = input;
+    if (notification === null || typeof notification !== 'object') {
+        throw err('Validation', "'notification' is required and must be an object");
+    }
+    if (notification.id !== undefined && !isNonEmptyString(notification.id)) {
+        throw err('Validation', 'notification.id must be a non-empty string when provided');
+    }
+    if (!isNonEmptyString(notification.title)) {
+        throw err('Validation', 'notification.title is required and must be a non-empty string');
+    }
+    if (!isNonEmptyString(notification.body)) {
+        throw err('Validation', 'notification.body is required and must be a non-empty string');
+    }
+    if (notification.data !== undefined) {
+        if (notification.data === null || typeof notification.data !== 'object') {
+            throw err('Validation', "'notification.data' must be an object");
+        }
+        for (const reserved of RESERVED_DATA_KEYS) {
+            if (Object.prototype.hasOwnProperty.call(notification.data, reserved)) {
+                throw err('Validation', "'notifee_options' and 'notifee_data' are reserved keys and cannot be used in notification.data");
+            }
+        }
+        for (const [key, value] of Object.entries(notification.data)) {
+            if (typeof value !== 'string') {
+                throw err('Validation', `FCM data values must be strings. Got ${typeof value} for key '${key}'. Use JSON.stringify() if you need to pass complex values.`);
+            }
+        }
+    }
+    const attachments = notification.ios?.attachments;
+    if (attachments !== undefined) {
+        if (!Array.isArray(attachments)) {
+            throw err('iOS', "'notification.ios.attachments' must be an array");
+        }
+        for (const attachment of attachments) {
+            if (attachment === null ||
+                typeof attachment !== 'object' ||
+                typeof attachment.url !== 'string') {
+                throw err('iOS', "each attachment must be an object with a string 'url' field");
+            }
+            if (!attachment.url.startsWith('https://')) {
+                throw err('iOS', `iOS attachments require https:// URLs. Got: ${attachment.url}`);
+            }
+        }
+    }
+    if (input.options !== undefined) {
+        const { options } = input;
+        if (options === null || typeof options !== 'object') {
+            throw err('Validation', "'options' must be an object");
+        }
+        if (options.androidPriority !== undefined &&
+            options.androidPriority !== 'high' &&
+            options.androidPriority !== 'normal') {
+            throw err('Validation', `'options.androidPriority' must be 'high' or 'normal'. Got: ${String(options.androidPriority)}`);
+        }
+        if (options.iosBadgeCount !== undefined &&
+            (typeof options.iosBadgeCount !== 'number' ||
+                !Number.isFinite(options.iosBadgeCount) ||
+                options.iosBadgeCount < 0 ||
+                !Number.isInteger(options.iosBadgeCount))) {
+            throw err('Validation', "'options.iosBadgeCount' must be a non-negative integer");
+        }
+        if (options.ttl !== undefined &&
+            (typeof options.ttl !== 'number' || !Number.isInteger(options.ttl) || options.ttl <= 0)) {
+            throw err('Validation', `options.ttl must be a positive integer (seconds). Got: ${String(options.ttl)}`);
+        }
+        if (options.collapseKey !== undefined && !isNonEmptyString(options.collapseKey)) {
+            throw err('Validation', "'options.collapseKey' must be a non-empty string");
+        }
+    }
+}
+//# sourceMappingURL=validation.js.map

package/server/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/server/package.json

@@ -0,0 +1,5 @@
+{
+  "private": true,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/server/src/android.ts

@@ -0,0 +1,27 @@
+import type { NotifyKitAndroidOutput, NotifyKitOptions, NotifyKitPayloadInput } from './types';
+
+type BuildAndroidContext = {
+  collapseKey?: string;
+  ttlSeconds?: number;
+};
+
+function toAndroidPriority(priority: NotifyKitOptions['androidPriority']): 'HIGH' | 'NORMAL' {
+  return priority === 'normal' ? 'NORMAL' : 'HIGH';
+}
+
+export function buildAndroidPayload(
+  input: NotifyKitPayloadInput,
+  context: BuildAndroidContext,
+): NotifyKitAndroidOutput {
+  const options: NotifyKitOptions = input.options ?? {};
+  const output: NotifyKitAndroidOutput = {
+    priority: toAndroidPriority(options.androidPriority),
+  };
+  if (context.collapseKey !== undefined) {
+    output.collapse_key = context.collapseKey;
+  }
+  if (context.ttlSeconds !== undefined) {
+    output.ttl = `${context.ttlSeconds}s`;
+  }
+  return output;
+}

package/server/src/buildPayload.ts

@@ -0,0 +1,91 @@
+import { buildAndroidPayload } from './android';
+import { buildIosApnsPayload } from './ios';
+import { serializeData, serializeNotifeeOptions } from './serialize';
+import type { NotifyKitPayloadInput, NotifyKitPayloadOutput } from './types';
+import { validateInput } from './validation';
+
+const SIZE_WARN_THRESHOLD_BYTES = 3500;
+const PREFIX = '[react-native-notify-kit/server]';
+
+export function buildNotifyKitPayload(input: NotifyKitPayloadInput): NotifyKitPayloadOutput {
+  validateInput(input);
+
+  const { notification } = input;
+  const options = input.options ?? {};
+
+  const collapseKey: string | undefined = options.collapseKey ?? notification.id ?? undefined;
+
+  let expiration: string | undefined;
+  if (options.ttl !== undefined) {
+    expiration = String(Math.floor(Date.now() / 1000) + options.ttl);
+  }
+
+  const notifeeOptions = serializeNotifeeOptions({
+    title: notification.title,
+    body: notification.body,
+    ...(notification.android !== undefined ? { android: notification.android } : {}),
+    ...(notification.ios !== undefined ? { ios: notification.ios } : {}),
+  });
+  const notifeeData = serializeData(notification.data);
+
+  // Android path: top-level `data` carries `notification.data` keys verbatim
+  // plus `notifee_options`. `notifee_data` is intentionally NOT duplicated here —
+  // the client can read the original keys directly from `data`. iOS NSE still
+  // receives `notifee_data` inside `apns.payload` because APNs does not expose
+  // arbitrary top-level keys to the extension.
+  const data: Record<string, string> = {
+    ...(notification.data ?? {}),
+    notifee_options: notifeeOptions,
+  };
+
+  const android = buildAndroidPayload(input, {
+    ...(collapseKey !== undefined ? { collapseKey } : {}),
+    ...(options.ttl !== undefined ? { ttlSeconds: options.ttl } : {}),
+  });
+
+  const apns = buildIosApnsPayload(input, {
+    notifeeOptions,
+    ...(notifeeData !== undefined ? { notifeeData } : {}),
+    ...(collapseKey !== undefined ? { collapseKey } : {}),
+    ...(expiration !== undefined ? { expiration } : {}),
+  });
+
+  // Build the FCM-bound payload first (without sizeBytes — that's metadata for
+  // the caller, not part of the wire format).
+  const fcmPayload: Omit<NotifyKitPayloadOutput, 'sizeBytes'> = {
+    data,
+    android,
+    apns,
+  };
+  if (input.token !== undefined) {
+    (fcmPayload as NotifyKitPayloadOutput).token = input.token;
+  } else if (input.topic !== undefined) {
+    (fcmPayload as NotifyKitPayloadOutput).topic = input.topic;
+  } else if (input.condition !== undefined) {
+    (fcmPayload as NotifyKitPayloadOutput).condition = input.condition;
+  }
+
+  // FCM's 4 KB limit is measured in UTF-8 bytes, not JS code units, so emoji
+  // and non-ASCII characters consume more than one byte each. Deviation from
+  // the spec's literal `JSON.stringify(output).length` to avoid underestimating
+  // payload size under such characters. sizeBytes measures the FCM-relevant
+  // fields only (excludes the sizeBytes field itself).
+  const sizeBytes = Buffer.byteLength(JSON.stringify(fcmPayload), 'utf8');
+  if (sizeBytes > SIZE_WARN_THRESHOLD_BYTES) {
+    console.warn(
+      `${PREFIX} Payload size ${sizeBytes} bytes approaches FCM 4KB limit. Consider reducing notifee_options.`,
+    );
+  }
+
+  // Attach sizeBytes as non-enumerable so JSON.stringify and object spread
+  // never include it — consumers can safely pass the output directly to
+  // admin.messaging().send() without stripping metadata fields.
+  const output = { ...fcmPayload } as NotifyKitPayloadOutput;
+  Object.defineProperty(output, 'sizeBytes', {
+    value: sizeBytes,
+    enumerable: false,
+    writable: false,
+    configurable: false,
+  });
+  return output;
+}

package/server/src/index.ts

@@ -0,0 +1,12 @@
+export { buildNotifyKitPayload } from './buildPayload';
+export { buildIosApnsPayload } from './ios';
+export { buildAndroidPayload } from './android';
+export { serializeNotifeeOptions } from './serialize';
+export type {
+  NotifyKitPayloadInput,
+  NotifyKitPayloadOutput,
+  NotifyKitNotification,
+  NotifyKitOptions,
+  NotifyKitAndroidConfig,
+  NotifyKitIosConfig,
+} from './types';

package/server/src/ios.ts

@@ -0,0 +1,88 @@
+import type {
+  ApnsInterruptionLevel,
+  NotifyKitApnsAps,
+  NotifyKitApnsHeaders,
+  NotifyKitApnsOutput,
+  NotifyKitIosInterruptionLevel,
+  NotifyKitNotification,
+  NotifyKitOptions,
+  NotifyKitPayloadInput,
+} from './types';
+
+const INTERRUPTION_LEVEL_MAP: Record<NotifyKitIosInterruptionLevel, ApnsInterruptionLevel> = {
+  passive: 'passive',
+  active: 'active',
+  timeSensitive: 'time-sensitive',
+  critical: 'critical',
+};
+
+const PREFIX = '[react-native-notify-kit/server]';
+
+export function toApnsInterruptionLevel(
+  level: NotifyKitIosInterruptionLevel,
+): ApnsInterruptionLevel {
+  const mapped = INTERRUPTION_LEVEL_MAP[level as NotifyKitIosInterruptionLevel];
+  if (mapped === undefined) {
+    throw new Error(
+      `${PREFIX} Validation: invalid interruptionLevel '${String(level)}'. Expected one of: passive, active, timeSensitive, critical`,
+    );
+  }
+  return mapped;
+}
+
+type BuildIosContext = {
+  notifeeOptions: string;
+  notifeeData?: string;
+  collapseKey?: string;
+  expiration?: string;
+};
+
+export function buildIosApnsPayload(
+  input: NotifyKitPayloadInput,
+  context: BuildIosContext,
+): NotifyKitApnsOutput {
+  const notification: NotifyKitNotification = input.notification;
+  const options: NotifyKitOptions = input.options ?? {};
+  const ios = notification.ios;
+
+  const headers: NotifyKitApnsHeaders = {
+    'apns-push-type': 'alert',
+    'apns-priority': '10',
+  };
+  if (context.collapseKey !== undefined) {
+    headers['apns-collapse-id'] = context.collapseKey;
+  }
+  if (context.expiration !== undefined) {
+    headers['apns-expiration'] = context.expiration;
+  }
+
+  const aps: NotifyKitApnsAps = {
+    alert: { title: notification.title, body: notification.body },
+    'mutable-content': 1,
+  };
+  if (ios?.sound !== undefined) {
+    aps.sound = ios.sound;
+  }
+  if (ios?.categoryId !== undefined) {
+    aps.category = ios.categoryId;
+  }
+  if (ios?.threadId !== undefined) {
+    aps['thread-id'] = ios.threadId;
+  }
+  if (ios?.interruptionLevel !== undefined) {
+    aps['interruption-level'] = toApnsInterruptionLevel(ios.interruptionLevel);
+  }
+  if (options.iosBadgeCount !== undefined) {
+    aps.badge = options.iosBadgeCount;
+  }
+
+  const payload: NotifyKitApnsOutput['payload'] = {
+    aps,
+    notifee_options: context.notifeeOptions,
+  };
+  if (context.notifeeData !== undefined) {
+    payload.notifee_data = context.notifeeData;
+  }
+
+  return { headers, payload };
+}

package/server/src/serialize.ts

@@ -0,0 +1,39 @@
+import type { NotifyKitAndroidConfig, NotifyKitIosConfig, SerializedNotifeeOptions } from './types';
+
+type SerializeInput = {
+  title: string;
+  body: string;
+  android?: NotifyKitAndroidConfig;
+  ios?: NotifyKitIosConfig;
+};
+
+const PREFIX = '[react-native-notify-kit/server]';
+
+export function serializeNotifeeOptions(input: SerializeInput): string {
+  const payload: SerializedNotifeeOptions = { _v: 1, title: input.title, body: input.body };
+  if (input.android !== undefined) {
+    payload.android = input.android;
+  }
+  if (input.ios !== undefined) {
+    payload.ios = input.ios;
+  }
+  try {
+    return JSON.stringify(payload);
+  } catch (e: unknown) {
+    const detail = e instanceof Error ? `: ${e.message}` : `: ${String(e)}`;
+    throw new Error(
+      `${PREFIX} Serialization: notifee_options contains circular references or non-serializable values. Check for circular object references in android/ios config${detail}`,
+    );
+  }
+}
+
+export function serializeData(data?: Record<string, string>): string | undefined {
+  if (!data) {
+    return undefined;
+  }
+  const keys = Object.keys(data);
+  if (keys.length === 0) {
+    return undefined;
+  }
+  return JSON.stringify(data);
+}

package/server/src/types.ts

@@ -0,0 +1,24 @@
+// Source of truth: packages/react-native/src/internal/fcmContract.ts
+// Re-exported here so the server SDK can be consumed via
+// `react-native-notify-kit/server` without a deep import of the internal path.
+// The shared file is included in the server tsconfig via a relative path.
+export type {
+  NotifyKitPressAction,
+  NotifyKitAndroidAction,
+  NotifyKitAndroidStyle,
+  NotifyKitAndroidConfig,
+  NotifyKitIosAttachment,
+  NotifyKitIosInterruptionLevel,
+  NotifyKitIosConfig,
+  NotifyKitNotification,
+  NotifyKitOptions,
+  NotifyKitPayloadInput,
+  ApnsInterruptionLevel,
+  NotifyKitAndroidOutput,
+  NotifyKitApnsAps,
+  NotifyKitApnsHeaders,
+  NotifyKitApnsPayload,
+  NotifyKitApnsOutput,
+  NotifyKitPayloadOutput,
+  SerializedNotifeeOptions,
+} from '../../src/internal/fcmContract';

package/server/src/validation.ts

@@ -0,0 +1,134 @@
+import type { NotifyKitPayloadInput } from './types';
+
+const PREFIX = '[react-native-notify-kit/server]';
+const RESERVED_DATA_KEYS = ['notifee_options', 'notifee_data'] as const;
+
+function err(category: string, message: string): Error {
+  return new Error(`${PREFIX} ${category}: ${message}`);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+export function validateInput(input: NotifyKitPayloadInput): void {
+  if (input === null || typeof input !== 'object') {
+    throw err('Validation', 'input must be an object');
+  }
+
+  const routingCount =
+    (input.token !== undefined ? 1 : 0) +
+    (input.topic !== undefined ? 1 : 0) +
+    (input.condition !== undefined ? 1 : 0);
+
+  if (routingCount !== 1) {
+    throw err(
+      'Routing',
+      `exactly one of 'token', 'topic', or 'condition' must be provided. Got: ${routingCount}`,
+    );
+  }
+
+  if (input.token !== undefined && !isNonEmptyString(input.token)) {
+    throw err('Routing', "'token' must be a non-empty string");
+  }
+  if (input.topic !== undefined && !isNonEmptyString(input.topic)) {
+    throw err('Routing', "'topic' must be a non-empty string");
+  }
+  if (input.condition !== undefined && !isNonEmptyString(input.condition)) {
+    throw err('Routing', "'condition' must be a non-empty string");
+  }
+
+  const { notification } = input;
+  if (notification === null || typeof notification !== 'object') {
+    throw err('Validation', "'notification' is required and must be an object");
+  }
+
+  if (notification.id !== undefined && !isNonEmptyString(notification.id)) {
+    throw err('Validation', 'notification.id must be a non-empty string when provided');
+  }
+  if (!isNonEmptyString(notification.title)) {
+    throw err('Validation', 'notification.title is required and must be a non-empty string');
+  }
+  if (!isNonEmptyString(notification.body)) {
+    throw err('Validation', 'notification.body is required and must be a non-empty string');
+  }
+
+  if (notification.data !== undefined) {
+    if (notification.data === null || typeof notification.data !== 'object') {
+      throw err('Validation', "'notification.data' must be an object");
+    }
+    for (const reserved of RESERVED_DATA_KEYS) {
+      if (Object.prototype.hasOwnProperty.call(notification.data, reserved)) {
+        throw err(
+          'Validation',
+          "'notifee_options' and 'notifee_data' are reserved keys and cannot be used in notification.data",
+        );
+      }
+    }
+    for (const [key, value] of Object.entries(notification.data)) {
+      if (typeof value !== 'string') {
+        throw err(
+          'Validation',
+          `FCM data values must be strings. Got ${typeof value} for key '${key}'. Use JSON.stringify() if you need to pass complex values.`,
+        );
+      }
+    }
+  }
+
+  const attachments = notification.ios?.attachments;
+  if (attachments !== undefined) {
+    if (!Array.isArray(attachments)) {
+      throw err('iOS', "'notification.ios.attachments' must be an array");
+    }
+    for (const attachment of attachments) {
+      if (
+        attachment === null ||
+        typeof attachment !== 'object' ||
+        typeof attachment.url !== 'string'
+      ) {
+        throw err('iOS', "each attachment must be an object with a string 'url' field");
+      }
+      if (!attachment.url.startsWith('https://')) {
+        throw err('iOS', `iOS attachments require https:// URLs. Got: ${attachment.url}`);
+      }
+    }
+  }
+
+  if (input.options !== undefined) {
+    const { options } = input;
+    if (options === null || typeof options !== 'object') {
+      throw err('Validation', "'options' must be an object");
+    }
+    if (
+      options.androidPriority !== undefined &&
+      options.androidPriority !== 'high' &&
+      options.androidPriority !== 'normal'
+    ) {
+      throw err(
+        'Validation',
+        `'options.androidPriority' must be 'high' or 'normal'. Got: ${String(options.androidPriority)}`,
+      );
+    }
+    if (
+      options.iosBadgeCount !== undefined &&
+      (typeof options.iosBadgeCount !== 'number' ||
+        !Number.isFinite(options.iosBadgeCount) ||
+        options.iosBadgeCount < 0 ||
+        !Number.isInteger(options.iosBadgeCount))
+    ) {
+      throw err('Validation', "'options.iosBadgeCount' must be a non-negative integer");
+    }
+    if (
+      options.ttl !== undefined &&
+      (typeof options.ttl !== 'number' || !Number.isInteger(options.ttl) || options.ttl <= 0)
+    ) {
+      throw err(
+        'Validation',
+        `options.ttl must be a positive integer (seconds). Got: ${String(options.ttl)}`,
+      );
+    }
+    if (options.collapseKey !== undefined && !isNonEmptyString(options.collapseKey)) {
+      throw err('Validation', "'options.collapseKey' must be a non-empty string");
+    }
+  }
+}

package/server/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "types": ["node"],
+    "allowJs": false,
+    "isolatedModules": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "listEmittedFiles": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/__tests__/**/*", "dist", "node_modules"]
+}

package/src/NotifeeApiModule.ts

@@ -2,7 +2,7 @@
  * Copyright (c) 2016-present Invertase Limited
  */
 
-import { AppRegistry, Platform } from 'react-native';
+import { AppRegistry, AppState, Platform } from 'react-native';
 import { Module } from './types/Module';
 import {
   AndroidChannel,
@@ -48,8 +48,12 @@ import {
 } from './types/NotificationIOS';
 import validateIOSCategory from './validators/validateIOSCategory';
 import validateIOSPermissions from './validators/validateIOSPermissions';
+import type { FcmConfig, FcmRemoteMessage } from './fcm/types';
+import { parseFcmPayload } from './fcm/parseFcmPayload';
+import { reconstructNotification } from './fcm/reconstructNotification';
 
 let backgroundEventHandler: (event: Event) => Promise<void>;
+let fcmConfig: FcmConfig = {};
 
 let registeredForegroundServiceTask: (notification: Notification) => Promise<void>;
 
@@ -839,4 +843,79 @@ export default class NotifeeApiModule extends NotifeeNativeModule implements Mod
     }
     return this.native.hideNotificationDrawer();
   };
+
+  /**
+   * 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`.
+   */
+  public handleFcmMessage = async (remoteMessage: FcmRemoteMessage): Promise<string | null> => {
+    if (remoteMessage == null || typeof remoteMessage !== 'object') {
+      throw new Error("notifee.handleFcmMessage(*) 'remoteMessage' expected an object.");
+    }
+
+    // Snapshot config at entry — Rule C10 (mid-flight setFcmConfig won't affect this call).
+    // Deep-copy nested ios sub-object to prevent caller mutation leaking through.
+    const config: FcmConfig = {
+      ...fcmConfig,
+      ios: fcmConfig.ios ? { ...fcmConfig.ios } : undefined,
+    };
+
+    const parsed = parseFcmPayload(remoteMessage.data);
+
+    // Fallback path — no notifee_options present
+    if (parsed === null && config.fallbackBehavior === 'ignore') {
+      return null;
+    }
+
+    const notification = reconstructNotification(parsed, remoteMessage, config);
+
+    // iOS background/killed no-op — Rule C3 (NSE already displayed)
+    if (isIOS) {
+      const state = AppState.currentState;
+      if (state !== 'active') {
+        return null;
+      }
+      // iOS foreground suppress — Rule C2 exception
+      if (config.ios?.suppressForegroundBanner === true) {
+        return null;
+      }
+    }
+
+    // Diagnostic warnings before display
+    if (!notification.title && !notification.body) {
+      console.warn(
+        '[react-native-notify-kit] handleFcmMessage: displaying notification with empty title and body. Check your FCM payload.',
+      );
+    }
+    if (isAndroid && !notification.android?.channelId) {
+      console.warn(
+        '[react-native-notify-kit] handleFcmMessage: Android fallback path has no channelId (no payload channelId, no defaultChannelId configured). Notification may be dropped by the OS.',
+      );
+    }
+
+    // Android always displays (Rule C1), iOS foreground displays (Rule C2)
+    return this.displayNotification(notification);
+  };
+
+  /**
+   * 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 (AsyncStorage / MMKV), which would be async.
+   * Currently resolves synchronously.
+   */
+  public setFcmConfig = (config: FcmConfig): Promise<void> => {
+    if (config == null || typeof config !== 'object' || Array.isArray(config)) {
+      const got = config === null ? 'null' : Array.isArray(config) ? 'array' : typeof config;
+      throw new Error(`notifee.setFcmConfig(*) config must be a plain object. Got: ${got}`);
+    }
+    fcmConfig = {
+      ...config,
+      ios: config.ios ? { ...config.ios } : undefined,
+    };
+    return Promise.resolve();
+  };
 }

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';