react-native-notify-kit 10.7.2 → 10.8.1

package/server/src/validation.ts

@@ -2,6 +2,17 @@ import type { NotifyKitPayloadInput } from './types';
 
 const PREFIX = '[react-native-notify-kit/server]';
 const RESERVED_DATA_KEYS = ['notifee_options', 'notifee_data'] as const;
+const BIG_TEXT_STYLE_KEYS = new Set(['type', 'text', 'title', 'summary']);
+const BIG_PICTURE_STYLE_KEYS = new Set(['type', 'picture', 'title', 'summary', 'largeIcon']);
+const PRESS_ACTION_KEYS = new Set(['id', 'launchActivity', 'mainComponent', 'launchActivityFlags']);
+const ACTION_KEYS = new Set(['title', 'pressAction', 'icon', 'input']);
+const INPUT_KEYS = new Set([
+  'allowFreeFormInput',
+  'allowGeneratedReplies',
+  'choices',
+  'editableChoices',
+  'placeholder',
+]);
 
 function err(category: string, message: string): Error {
   return new Error(`${PREFIX} ${category}: ${message}`);
@@ -11,6 +22,119 @@ function isNonEmptyString(value: unknown): value is string {
   return typeof value === 'string' && value.length > 0;
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function rejectUnsupportedKeys(
+  value: Record<string, unknown>,
+  supported: Set<string>,
+  path: string,
+): void {
+  for (const key of Object.keys(value)) {
+    if (!supported.has(key)) {
+      throw err('Android', `${path}.${key} is not supported`);
+    }
+  }
+}
+
+function validatePressAction(value: unknown, path: string): void {
+  if (!isPlainObject(value)) {
+    throw err('Android', `${path} must be an object`);
+  }
+  rejectUnsupportedKeys(value, PRESS_ACTION_KEYS, path);
+  if (!isNonEmptyString(value.id)) {
+    throw err('Android', `${path}.id must be a non-empty string`);
+  }
+  if (value.id === '__NOTIFEE_OPT_OUT__') {
+    throw err('Android', `${path}.id is reserved for explicit null`);
+  }
+  if (value.launchActivity !== undefined && typeof value.launchActivity !== 'string') {
+    throw err('Android', `${path}.launchActivity must be a string`);
+  }
+  if (value.mainComponent !== undefined && typeof value.mainComponent !== 'string') {
+    throw err('Android', `${path}.mainComponent must be a string`);
+  }
+  if (value.launchActivityFlags !== undefined) {
+    if (!Array.isArray(value.launchActivityFlags)) {
+      throw err(
+        'Android',
+        `${path}.launchActivityFlags must be an array of AndroidLaunchActivityFlag values`,
+      );
+    }
+    for (const flag of value.launchActivityFlags) {
+      if (typeof flag !== 'number' || !Number.isInteger(flag) || flag < 0 || flag > 20) {
+        throw err(
+          'Android',
+          `${path}.launchActivityFlags must be an array of AndroidLaunchActivityFlag values`,
+        );
+      }
+    }
+  }
+}
+
+function validateActionInput(value: unknown, path: string): void {
+  if (value === true) {
+    return;
+  }
+  if (!isPlainObject(value)) {
+    throw err('Android', `${path} must be true or an AndroidInput object`);
+  }
+  rejectUnsupportedKeys(value, INPUT_KEYS, path);
+
+  for (const key of ['allowFreeFormInput', 'allowGeneratedReplies', 'editableChoices'] as const) {
+    if (Object.prototype.hasOwnProperty.call(value, key) && typeof value[key] !== 'boolean') {
+      throw err('Android', `${path}.${key} must be a boolean`);
+    }
+  }
+  if (Object.prototype.hasOwnProperty.call(value, 'choices')) {
+    if (!Array.isArray(value.choices) || value.choices.length === 0) {
+      throw err('Android', `${path}.choices must be a non-empty array of strings`);
+    }
+    for (const choice of value.choices) {
+      if (typeof choice !== 'string') {
+        throw err('Android', `${path}.choices must be a non-empty array of strings`);
+      }
+    }
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(value, 'placeholder') &&
+    typeof value.placeholder !== 'string'
+  ) {
+    throw err('Android', `${path}.placeholder must be a string`);
+  }
+  if (
+    value.allowFreeFormInput === false &&
+    (!Array.isArray(value.choices) || value.choices.length === 0)
+  ) {
+    throw err('Android', `${path}.allowFreeFormInput requires choices when false`);
+  }
+  if (value.editableChoices === true && value.allowFreeFormInput === false) {
+    throw err('Android', `${path}.editableChoices requires allowFreeFormInput when true`);
+  }
+}
+
+function validateAction(value: unknown, path: string): void {
+  if (!isPlainObject(value)) {
+    throw err('Android', `${path} must be an AndroidAction object`);
+  }
+  rejectUnsupportedKeys(value, ACTION_KEYS, path);
+  if (!isNonEmptyString(value.title)) {
+    throw err('Android', `${path}.title must be a non-empty string`);
+  }
+  validatePressAction(value.pressAction, `${path}.pressAction`);
+  if (value.icon !== undefined && !isNonEmptyString(value.icon)) {
+    throw err('Android', `${path}.icon must be a non-empty string`);
+  }
+  if (value.input !== undefined) {
+    validateActionInput(value.input, `${path}.input`);
+  }
+}
+
 export function validateInput(input: NotifyKitPayloadInput): void {
   if (input === null || typeof input !== 'object') {
     throw err('Validation', 'input must be an object');
@@ -52,6 +176,9 @@ export function validateInput(input: NotifyKitPayloadInput): void {
   if (!isNonEmptyString(notification.body)) {
     throw err('Validation', 'notification.body is required and must be a non-empty string');
   }
+  if (notification.subtitle !== undefined && typeof notification.subtitle !== 'string') {
+    throw err('Validation', 'notification.subtitle must be a string when provided');
+  }
 
   if (notification.data !== undefined) {
     if (notification.data === null || typeof notification.data !== 'object') {
@@ -75,6 +202,59 @@ export function validateInput(input: NotifyKitPayloadInput): void {
     }
   }
 
+  if (notification.android !== undefined) {
+    if (!isPlainObject(notification.android)) {
+      throw err('Android', 'notification.android must be an object');
+    }
+    if (
+      notification.android.pressAction !== undefined &&
+      notification.android.pressAction !== null
+    ) {
+      validatePressAction(notification.android.pressAction, 'notification.android.pressAction');
+    }
+  }
+
+  const circularLargeIcon = notification.android?.circularLargeIcon;
+  if (circularLargeIcon !== undefined && typeof circularLargeIcon !== 'boolean') {
+    throw err('Android', 'notification.android.circularLargeIcon must be a boolean when provided');
+  }
+
+  const style = notification.android?.style;
+  if (style !== undefined) {
+    if (style === null || typeof style !== 'object' || Array.isArray(style)) {
+      throw err('Android', 'notification.android.style must be a supported style object');
+    }
+    if (style.type !== 'BIG_TEXT' && style.type !== 'BIG_PICTURE') {
+      throw err('Android', 'notification.android.style type must be BIG_TEXT or BIG_PICTURE');
+    }
+    const supportedKeys = style.type === 'BIG_TEXT' ? BIG_TEXT_STYLE_KEYS : BIG_PICTURE_STYLE_KEYS;
+    for (const key of Object.keys(style)) {
+      if (!supportedKeys.has(key)) {
+        throw err('Android', `notification.android.style.${key} is not supported`);
+      }
+    }
+    if (style.type === 'BIG_TEXT' && !isNonEmptyString(style.text)) {
+      throw err('Android', 'notification.android.style.text must be a non-empty string');
+    }
+    if (style.type === 'BIG_PICTURE' && !isNonEmptyString(style.picture)) {
+      throw err('Android', 'notification.android.style.picture must be a non-empty string');
+    }
+    if (style.title !== undefined && typeof style.title !== 'string') {
+      throw err('Android', 'notification.android.style.title must be a string when provided');
+    }
+    if (style.summary !== undefined && typeof style.summary !== 'string') {
+      throw err('Android', 'notification.android.style.summary must be a string when provided');
+    }
+    if (
+      style.type === 'BIG_PICTURE' &&
+      style.largeIcon !== undefined &&
+      style.largeIcon !== null &&
+      typeof style.largeIcon !== 'string'
+    ) {
+      throw err('Android', 'notification.android.style.largeIcon must be a string or null');
+    }
+  }
+
   const attachments = notification.ios?.attachments;
   if (attachments !== undefined) {
     if (!Array.isArray(attachments)) {
@@ -133,14 +313,15 @@ export function validateInput(input: NotifyKitPayloadInput): void {
   }
 
   const actions = notification.android?.actions;
-  if (Array.isArray(actions)) {
+  if (actions !== undefined) {
+    if (!Array.isArray(actions)) {
+      throw err('Android', 'notification.android.actions must be an array');
+    }
     const pressActionIds = new Set<string>();
 
-    for (const action of actions) {
-      const pressActionId = action?.pressAction?.id;
-      if (typeof pressActionId !== 'string') {
-        continue;
-      }
+    for (const [index, action] of actions.entries()) {
+      validateAction(action, `notification.android.actions[${index}]`);
+      const pressActionId = action.pressAction.id;
 
       if (pressActionIds.has(pressActionId)) {
         throw err(

package/src/fcm/parseFcmPayload.ts

@@ -7,6 +7,7 @@ const PREFIX = '[react-native-notify-kit]';
 export type ParsedPayload = {
   _v?: number;
   title?: string;
+  subtitle?: string;
   body?: string;
   android?: Record<string, unknown>;
   ios?: Record<string, unknown>;

package/src/fcm/reconstructNotification.ts

@@ -20,6 +20,46 @@ const STYLE_TYPE_MAP: Record<string, AndroidStyle | undefined> = {
   BIG_TEXT: AndroidStyle.BIGTEXT,
   BIG_PICTURE: AndroidStyle.BIGPICTURE,
 };
+const ANDROID_INPUT_KEYS = new Set([
+  'allowFreeFormInput',
+  'allowGeneratedReplies',
+  'choices',
+  'editableChoices',
+  'placeholder',
+]);
+
+function assertFcmPressAction(
+  value: unknown,
+  path: string,
+): asserts value is NonNullable<NotificationAndroid['pressAction']> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${PREFIX} ${path} must be an object`);
+  }
+
+  const pressAction = value as Record<string, unknown>;
+  if (typeof pressAction.id !== 'string' || pressAction.id.length === 0) {
+    throw new Error(`${PREFIX} ${path}.id must be a non-empty string`);
+  }
+  if (pressAction.id === '__NOTIFEE_OPT_OUT__') {
+    throw new Error(`${PREFIX} ${path}.id is reserved for explicit null`);
+  }
+  if (pressAction.launchActivity !== undefined && typeof pressAction.launchActivity !== 'string') {
+    throw new Error(`${PREFIX} ${path}.launchActivity must be a string`);
+  }
+  if (pressAction.mainComponent !== undefined && typeof pressAction.mainComponent !== 'string') {
+    throw new Error(`${PREFIX} ${path}.mainComponent must be a string`);
+  }
+  if (pressAction.launchActivityFlags !== undefined) {
+    if (!Array.isArray(pressAction.launchActivityFlags)) {
+      throw new Error(`${PREFIX} ${path}.launchActivityFlags must be an array`);
+    }
+    for (const flag of pressAction.launchActivityFlags) {
+      if (typeof flag !== 'number' || !Number.isInteger(flag) || flag < 0 || flag > 20) {
+        throw new Error(`${PREFIX} ${path}.launchActivityFlags contains an invalid flag`);
+      }
+    }
+  }
+}
 
 /**
  * Reconstructs a {@link Notification} object suitable for
@@ -47,6 +87,10 @@ export function reconstructNotification(
     body,
   };
 
+  if (typeof parsed?.subtitle === 'string') {
+    notification.subtitle = parsed.subtitle;
+  }
+
   if (Object.keys(data).length > 0) {
     notification.data = data;
   }
@@ -116,15 +160,21 @@ function buildAndroidConfig(
     android.channelId = channelId;
   }
 
-  // pressAction: payload > config default
-  const pressAction = raw?.pressAction ?? config.defaultPressAction;
-  if (pressAction && typeof pressAction === 'object') {
-    android.pressAction = pressAction as NotificationAndroid['pressAction'];
+  // Explicit null opts out of the body tap; only absence uses the configured default.
+  const pressAction = raw?.pressAction === undefined ? config.defaultPressAction : raw.pressAction;
+  if (pressAction === null) {
+    android.pressAction = null;
+  } else if (pressAction !== undefined) {
+    assertFcmPressAction(pressAction, 'android.pressAction');
+    android.pressAction = 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?.circularLargeIcon === 'boolean') {
+    android.circularLargeIcon = raw.circularLargeIcon;
+  }
   if (typeof raw?.color === 'string') android.color = raw.color;
 
   // Timestamp fields — preserve only values accepted by the canonical Android validator
@@ -133,21 +183,66 @@ function buildAndroidConfig(
     android.timestamp = raw.timestamp;
   }
 
-  // Actions array — pass through (trust server validation)
-  if (Array.isArray(raw?.actions)) {
-    android.actions = raw.actions as NotificationAndroid['actions'];
+  // Legacy input:false means no reply. Other malformed inputs must fail here:
+  // the normal validator accepts some of them as a default RemoteInput.
+  if (raw?.actions !== undefined) {
+    if (!Array.isArray(raw.actions)) {
+      throw new Error(`${PREFIX} android.actions must be an array`);
+    }
+    android.actions = raw.actions.map((action, index) => {
+      if (action === null || typeof action !== 'object' || Array.isArray(action)) {
+        return action;
+      }
+      if (action.pressAction !== undefined) {
+        assertFcmPressAction(action.pressAction, `android.actions[${index}].pressAction`);
+      }
+      const input = action.input;
+      if (input === false) {
+        const withoutInput = { ...action };
+        delete withoutInput.input;
+        return withoutInput;
+      }
+      if (
+        input !== undefined &&
+        input !== true &&
+        (input === null || typeof input !== 'object' || Array.isArray(input))
+      ) {
+        throw new Error(`${PREFIX} android.actions[${index}].input is invalid`);
+      }
+      if (input !== undefined && input !== true) {
+        for (const key of Object.keys(input)) {
+          if (!ANDROID_INPUT_KEYS.has(key)) {
+            throw new Error(`${PREFIX} android.actions[${index}].input.${key} is unsupported`);
+          }
+        }
+      }
+      return action;
+    }) as NonNullable<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 };
+    const style = raw.style as Record<string, unknown>;
     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 };
+          android.style = {
+            type: AndroidStyle.BIGTEXT,
+            text: style.text,
+            ...(typeof style.title === 'string' ? { title: style.title } : {}),
+            ...(typeof style.summary === 'string' ? { summary: style.summary } : {}),
+          };
         } else if (mappedType === AndroidStyle.BIGPICTURE && typeof style.picture === 'string') {
-          android.style = { type: AndroidStyle.BIGPICTURE, picture: style.picture };
+          android.style = {
+            type: AndroidStyle.BIGPICTURE,
+            picture: style.picture,
+            ...(typeof style.title === 'string' ? { title: style.title } : {}),
+            ...(typeof style.summary === 'string' ? { summary: style.summary } : {}),
+            ...(style.largeIcon === null || typeof style.largeIcon === 'string'
+              ? { largeIcon: style.largeIcon }
+              : {}),
+          };
         } else {
           const field = mappedType === AndroidStyle.BIGTEXT ? 'text' : 'picture';
           console.warn(

package/src/internal/fcmContract.d.ts

@@ -12,27 +12,69 @@
  * that are not for end users.
  */
 
+// Numeric wire values of the public AndroidLaunchActivityFlag enum (0 through 20).
+export type NotifyKitAndroidLaunchActivityFlag =
+  | 0
+  | 1
+  | 2
+  | 3
+  | 4
+  | 5
+  | 6
+  | 7
+  | 8
+  | 9
+  | 10
+  | 11
+  | 12
+  | 13
+  | 14
+  | 15
+  | 16
+  | 17
+  | 18
+  | 19
+  | 20;
+
 export type NotifyKitPressAction = {
   id: string;
   launchActivity?: string;
+  mainComponent?: string;
+  launchActivityFlags?: NotifyKitAndroidLaunchActivityFlag[];
+};
+
+export type NotifyKitAndroidInput = {
+  allowFreeFormInput?: boolean;
+  allowGeneratedReplies?: boolean;
+  choices?: string[];
+  editableChoices?: boolean;
+  placeholder?: string;
 };
 
 export type NotifyKitAndroidAction = {
   title: string;
   pressAction: NotifyKitPressAction;
-  input?: boolean;
+  icon?: string;
+  input?: true | NotifyKitAndroidInput;
 };
 
 export type NotifyKitAndroidStyle =
-  | { type: 'BIG_TEXT'; text: string }
-  | { type: 'BIG_PICTURE'; picture: string };
+  | { type: 'BIG_TEXT'; text: string; title?: string; summary?: string }
+  | {
+      type: 'BIG_PICTURE';
+      picture: string;
+      title?: string;
+      summary?: string;
+      largeIcon?: string | null;
+    };
 
 export type NotifyKitAndroidConfig = {
   channelId?: string;
   smallIcon?: string;
   largeIcon?: string;
+  circularLargeIcon?: boolean;
   color?: string;
-  pressAction?: NotifyKitPressAction;
+  pressAction?: NotifyKitPressAction | null;
   actions?: NotifyKitAndroidAction[];
   style?: NotifyKitAndroidStyle;
   showTimestamp?: boolean;
@@ -56,20 +98,21 @@ export type NotifyKitIosConfig = {
 
 export type NotifyKitNotification = {
   /**
-   * Optional notification identifier. When provided, it is also used as the
-   * FCM collapse key (Android `collapseKey`, iOS `apns-collapse-id`) unless
-   * `options.collapseKey` is explicitly set. Collapse key precedence (Rule 7):
+   * Optional public notification identifier. It is serialized in the _v:1
+   * options blob and used by NotifyKit display, events, readback and cancel.
+   * It also defaults the FCM transport collapse key (Android `collapseKey`,
+   * 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.
+   * Collapse controls transport coalescing. It does not guarantee replacement
+   * of a notification that has already been delivered.
    */
   id?: string;
   title: string;
+  subtitle?: string;
   body: string;
   data?: Record<string, string>;
   android?: NotifyKitAndroidConfig;
@@ -100,7 +143,7 @@ export type NotifyKitAndroidOutput = {
 };
 
 export type NotifyKitApnsAps = {
-  alert: { title: string; body: string };
+  alert: { title: string; body: string; subtitle?: string };
   sound?: string;
   category?: string;
   'mutable-content': 1;
@@ -141,7 +184,9 @@ export type NotifyKitPayloadOutput = NotifyKitPayloadTarget & {
 
 export type SerializedNotifeeOptions = {
   _v: 1;
+  id?: string;
   title: string;
+  subtitle?: string;
   body: string;
   android?: NotifyKitAndroidConfig;
   ios?: NotifyKitIosConfig;

package/src/types/Notification.ts

@@ -417,6 +417,17 @@ export enum EventType {
    * Event type is sent when a notification wants to start a foreground service but a foreground service is already started.
    */
   FG_ALREADY_EXIST = 8,
+
+  /**
+   * Event type for an Android Foreground Service timeout handled by the native timeout path.
+   *
+   * Delivery to JavaScript is best-effort; JavaScript execution is not guaranteed.
+   * This event does not confirm completed Android service teardown, guarantee cancellation of
+   * JavaScript work, or authorize a new Foreground Service start.
+   *
+   * @platform android
+   */
+  FG_TIMEOUT = 9,
 }
 
 /**
@@ -436,6 +447,7 @@ export interface EventDetail {
    *  - [`EventType.DELIVERED`](/react-native/reference/eventtype#delivered)
    *  - [`EventType.TRIGGER_NOTIFICATION_CREATED`](/react-native/reference/eventtype#trigger_notification_created)
    *  - [`EventType.FG_ALREADY_EXIST`](/react-native/reference/eventtype#fg_already_exist)
+   *  - [`EventType.FG_TIMEOUT`](/react-native/reference/eventtype#fg_timeout)
    */
   notification?: Notification;
 
@@ -494,6 +506,21 @@ export interface EventDetail {
    * @platform android API Level >= 28
    */
   blocked?: boolean;
+
+  /**
+   * The start command identifier reported by Android's timeout callback for `EventType.FG_TIMEOUT`.
+   *
+   * @platform android
+   */
+  startId?: number;
+
+  /**
+   * The Foreground Service type reported by Android's timeout callback for `EventType.FG_TIMEOUT`.
+   * A value of `-1` is preserved when the callback overload does not provide an explicit type.
+   *
+   * @platform android
+   */
+  fgsType?: number;
 }
 
 /**

package/src/validators/validateAndroidPressAction.ts

@@ -19,6 +19,10 @@ export default function validateAndroidPressAction(
     throw new Error("'id' expected a non-empty string value.");
   }
 
+  if (pressAction.id === '__NOTIFEE_OPT_OUT__') {
+    throw new Error("'id' is reserved for an explicit null pressAction.");
+  }
+
   const out: NotificationPressAction = {
     id: pressAction.id,
   };

package/src/validators/validateIOSNotification.ts

@@ -133,8 +133,13 @@ export default function validateIOSNotification(ios?: NotificationIOS): Notifica
   /**
    * badgeCount
    */
-  if (objectHasProperty(ios, 'badgeCount')) {
-    if (!isNumber(ios.badgeCount) || ios.badgeCount < 0) {
+  if (objectHasProperty(ios, 'badgeCount') && ios.badgeCount !== null) {
+    if (
+      !isNumber(ios.badgeCount) ||
+      !Number.isFinite(ios.badgeCount) ||
+      !Number.isInteger(ios.badgeCount) ||
+      ios.badgeCount < 0
+    ) {
       throw new Error("'notification.ios.badgeCount' expected a number value >=0.");
     }
 

package/src/version.ts

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