feat(fcm): Enable fid and deprecate token for Send API (#3145)

* Add FidMessage and deprecate TokenMessage

* Add fids to MulticastMessage interface

* Add integration tests

* Extract API docstring

* Change tokens back to required field, add extra docstrings and refactor the messages array construction in MulticastMessage

* Fix the lint error

* Add FidMulticastMessage and Implement Function Overloads on sendEachForMulticast

* Extract API doc and remove hyperlink due to duplicate names from function overload

* Update sendEachForMulticast docstring

* Add token deprecation documentation

* Update integration tests error code for invalid fid target

* Register new installation-id-not-registered Error Code

* Extract api docstring

* Resolve gemini review comments and add a unit test

* Add explicit note in FidMulticastMessage interface to avoid confusion

Author: yvonnep165

etc/firebase-admin.messaging.api.md

@@ -162,6 +162,16 @@ export interface FcmOptions {
     analyticsLabel?: string;
 }
 
+// @public
+export interface FidMessage extends BaseMessage {
+    fid: string;
+}
+
+// @public
+export interface FidMulticastMessage extends BaseMessage {
+    fids: string[];
+}
+
 // Warning: (ae-forgotten-export) The symbol "FirebaseError" needs to be exported by the entry point index.d.ts
 //
 // @public
@@ -183,7 +193,7 @@ export interface LightSettings {
 }
 
 // @public
-export type Message = TokenMessage | TopicMessage | ConditionMessage;
+export type Message = FidMessage | TokenMessage | TopicMessage | ConditionMessage;
 
 // @public
 export class Messaging {
@@ -192,7 +202,9 @@ export class Messaging {
     enableLegacyHttpTransport(): void;
     send(message: Message, dryRun?: boolean): Promise<string>;
     sendEach(messages: Message[], dryRun?: boolean): Promise<BatchResponse>;
+    // @deprecated
     sendEachForMulticast(message: MulticastMessage, dryRun?: boolean): Promise<BatchResponse>;
+    sendEachForMulticast(message: FidMulticastMessage, dryRun?: boolean): Promise<BatchResponse>;
     subscribeToTopic(registrationTokenOrTokens: string | string[], topic: string): Promise<MessagingTopicManagementResponse>;
     unsubscribeFromTopic(registrationTokenOrTokens: string | string[], topic: string): Promise<MessagingTopicManagementResponse>;
 }
@@ -207,6 +219,7 @@ export const MessagingErrorCode: {
     readonly INVALID_OPTIONS: "invalid-options";
     readonly INVALID_REGISTRATION_TOKEN: "invalid-registration-token";
     readonly REGISTRATION_TOKEN_NOT_REGISTERED: "registration-token-not-registered";
+    readonly INSTALLATION_ID_NOT_REGISTERED: "installation-id-not-registered";
     readonly MISMATCHED_CREDENTIAL: "mismatched-credential";
     readonly INVALID_PACKAGE_NAME: "invalid-package-name";
     readonly DEVICE_MESSAGE_RATE_EXCEEDED: "device-message-rate-exceeded";
@@ -232,9 +245,10 @@ export interface MessagingTopicManagementResponse {
     successCount: number;
 }
 
-// @public
+// @public @deprecated
 export interface MulticastMessage extends BaseMessage {
-    // (undocumented)
+    fids?: string[];
+    // @deprecated
     tokens: string[];
 }
 
@@ -252,7 +266,7 @@ export interface SendResponse {
     success: boolean;
 }
 
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export interface TokenMessage extends BaseMessage {
     // (undocumented)
     token: string;

src/messaging/error.ts

@@ -30,6 +30,7 @@ export const MessagingErrorCode = {
   INVALID_OPTIONS: 'invalid-options',
   INVALID_REGISTRATION_TOKEN: 'invalid-registration-token',
   REGISTRATION_TOKEN_NOT_REGISTERED: 'registration-token-not-registered',
+  INSTALLATION_ID_NOT_REGISTERED: 'installation-id-not-registered',
   MISMATCHED_CREDENTIAL: 'mismatched-credential',
   INVALID_PACKAGE_NAME: 'invalid-package-name',
   DEVICE_MESSAGE_RATE_EXCEEDED: 'device-message-rate-exceeded',
@@ -91,6 +92,12 @@ export const messagingClientErrorCode: { readonly [K in keyof typeof MessagingEr
       'error documentation for more details. Remove this registration token and stop using it to ' +
       'send messages.',
   },
+  INSTALLATION_ID_NOT_REGISTERED: {
+    code: MessagingErrorCode.INSTALLATION_ID_NOT_REGISTERED,
+    message: 'The provided installation ID is not registered. A previously valid installation ' +
+      'ID can be unregistered for a variety of reasons. See the error documentation for more ' +
+      'details. Remove this installation ID and stop using it to send messages.',
+  },
   MISMATCHED_CREDENTIAL: {
     code: MessagingErrorCode.MISMATCHED_CREDENTIAL,
     message: 'The credential used to authenticate this SDK does not have permission ' +
@@ -202,6 +209,7 @@ const MESSAGING_SERVER_TO_CLIENT_CODE: Record<string, keyof typeof MessagingErro
   THIRD_PARTY_AUTH_ERROR: 'THIRD_PARTY_AUTH_ERROR',
   UNAVAILABLE: 'SERVER_UNAVAILABLE',
   UNREGISTERED: 'REGISTRATION_TOKEN_NOT_REGISTERED',
+  UNREGISTERED_FID: 'INSTALLATION_ID_NOT_REGISTERED',
   UNSPECIFIED_ERROR: 'UNKNOWN_ERROR',
 };
 

src/messaging/index.ts

@@ -42,6 +42,8 @@ export {
   CriticalSound,
   ConditionMessage,
   FcmOptions,
+  FidMessage,
+  FidMulticastMessage,
   LightSettings,
   Message,
   MessagingTopicManagementResponse,

src/messaging/messaging-api.ts

@@ -26,6 +26,19 @@ export interface BaseMessage {
   fcmOptions?: FcmOptions;
 }
 
+/**
+ * Interface representing a message that targets a Firebase Installation ID (FID).
+ */
+export interface FidMessage extends BaseMessage {
+  /**
+   * The Firebase Installation ID (FID) to which the message should be sent.
+   */
+  fid: string;
+}
+
+/**
+ * @deprecated Use {@link FidMessage} instead.
+ */
 export interface TokenMessage extends BaseMessage {
   token: string;
 }
@@ -40,18 +53,44 @@ export interface ConditionMessage extends BaseMessage {
 
 /**
  * Payload for the {@link Messaging.send} operation. The payload contains all the fields
- * in the BaseMessage type, and exactly one of token, topic or condition.
+ * in the BaseMessage type, and exactly one of fid, token (deprecated, use fid instead),
+ * topic or condition.
  */
-export type Message = TokenMessage | TopicMessage | ConditionMessage;
+export type Message = FidMessage | TokenMessage | TopicMessage | ConditionMessage;
 
 /**
- * Payload for the {@link Messaging.sendEachForMulticast} method. The payload contains all the fields
- * in the BaseMessage type, and a list of tokens.
+ * Payload for the `sendEachForMulticast` method.
+ *
+ * @deprecated Use {@link FidMulticastMessage} instead.
  */
 export interface MulticastMessage extends BaseMessage {
+  /**
+   * A list of Firebase Installation IDs (FIDs) to target.
+   */
+  fids?: string[];
+  /**
+   * A list of registration tokens to target.
+   *
+   * @deprecated Use `fids` in {@link FidMulticastMessage} instead.
+   */
   tokens: string[];
 }
 
+/**
+ * Payload for the `sendEachForMulticast` method containing only FIDs.
+ *
+ * @remarks
+ * Note: This is a temporary interface. In the next major version, this will be
+ * renamed back to `MulticastMessage` once the old token-based `MulticastMessage`
+ * is fully deprecated and removed.
+ */
+export interface FidMulticastMessage extends BaseMessage {
+  /**
+   * A list of Firebase Installation IDs (FIDs) to target.
+   */
+  fids: string[];
+}
+
 /**
    * A notification that can be included in {@link Message}.
    */
@@ -698,7 +737,7 @@ export interface MessagingTopicManagementResponse {
 
 /**
  * Interface representing the server response from the
- * {@link Messaging.sendEach} and {@link Messaging.sendEachForMulticast} methods.
+ * {@link Messaging.sendEach} and `sendEachForMulticast` methods.
  */
 export interface BatchResponse {
 

src/messaging/messaging-errors-internal.ts

@@ -30,8 +30,23 @@ export function createFirebaseError(err: RequestResponseError): FirebaseMessagin
   if (err.response.isJson()) {
     // For JSON responses, map the server response to a client-side error.
     const json = err.response.data;
-    const errorCode = getErrorCode(json);
+    let errorCode = getErrorCode(json);
     const errorMessage = getErrorMessage(json);
+    if (errorCode === 'UNREGISTERED' || errorCode === 'NOT_FOUND') {
+      let requestData = err.response.config && err.response.config.data;
+      if (requestData && (typeof requestData === 'string' || Buffer.isBuffer(requestData))) {
+        try {
+          const strData = typeof requestData === 'string' ? requestData : requestData.toString('utf-8');
+          requestData = JSON.parse(strData);
+        } catch (e) {
+          // Ignore parsing errors.
+        }
+      }
+      const messageObj = requestData && requestData.message;
+      if (messageObj && typeof messageObj.fid === 'string') {
+        errorCode = 'UNREGISTERED_FID';
+      }
+    }
     return FirebaseMessagingError.fromServerError(errorCode, errorMessage, err);
   }
 

src/messaging/messaging-internal.ts

@@ -58,11 +58,11 @@ export function validateMessage(message: Message): void {
     }
   }
 
-  const targets = [anyMessage.token, anyMessage.topic, anyMessage.condition];
+  const targets = [anyMessage.fid, anyMessage.token, anyMessage.topic, anyMessage.condition];
   if (targets.filter((v) => validator.isNonEmptyString(v)).length !== 1) {
     throw new FirebaseMessagingError(
       messagingClientErrorCode.INVALID_PAYLOAD,
-      'Exactly one of topic, token or condition is required');
+      'Exactly one of fid, topic, token or condition is required');
   }
 
   validateStringMap(message.data, 'data');

src/messaging/messaging.ts

@@ -28,6 +28,7 @@ import { FirebaseMessagingRequestHandler } from './messaging-api-request-interna
 
 import {
   BatchResponse,
+  FidMulticastMessage,
   Message,
   MessagingTopicManagementResponse,
   MulticastMessage,
@@ -274,50 +275,84 @@ export class Messaging {
   }
 
   /**
-   * Sends the given multicast message to all the FCM registration tokens
+   * Sends the given multicast message to all the FCM registration tokens or fids
    * specified in it.
    *
    * This method uses the {@link Messaging.sendEach} API under the hood to send the given
    * message to all the target recipients. The responses list obtained from the
-   * return value corresponds to the order of tokens in the `MulticastMessage`.
+   * return value corresponds to the order of tokens/fids in the `MulticastMessage`.
+   * If both `tokens` and `fids` are provided, `tokens` are processed first, followed by `fids`.
    * An error from this method or a `BatchResponse` with all failures indicates a total
-   * failure, meaning that the messages in the list could be sent. Partial failures or
-   * failures are only indicated by a `BatchResponse` return value.
+   * failure, meaning that the messages in the list could not be sent. Partial failures
+   * are only indicated by a `BatchResponse` return value.
    *
-   * @param message - A multicast message
-   *   containing up to 500 tokens.
+   * @deprecated Use the overload accepting {@link FidMulticastMessage} instead.
+   *
+   * @param message - A multicast message containing up to 500 tokens and/or fids.
    * @param dryRun - Whether to send the message in the dry-run
    *   (validation only) mode.
    * @returns A Promise fulfilled with an object representing the result of the
    *   send operation.
    */
-  public sendEachForMulticast(message: MulticastMessage, dryRun?: boolean): Promise<BatchResponse> {
-    const copy: MulticastMessage = deepCopy(message);
+  public sendEachForMulticast(message: MulticastMessage, dryRun?: boolean): Promise<BatchResponse>;
+
+  /**
+   * Sends the given multicast message to all the FCM fids specified in it.
+   *
+   * This method uses the {@link Messaging.sendEach} API under the hood to send the given
+   * message to all the target recipients. The responses list obtained from the
+   * return value corresponds to the order of fids in the `FidMulticastMessage`.
+   * An error from this method or a `BatchResponse` with all failures indicates a total
+   * failure, meaning that the messages in the list could not be sent. Partial failures
+   * are only indicated by a `BatchResponse` return value.
+   *
+   * @param message - A multicast message containing up to 500 fids.
+   * @param dryRun - Whether to send the message in the dry-run (validation only) mode.
+   * @returns A Promise fulfilled with an object representing the result of the send operation.
+   */
+  public sendEachForMulticast(message: FidMulticastMessage, dryRun?: boolean): Promise<BatchResponse>;
+
+  public sendEachForMulticast(
+    message: MulticastMessage | FidMulticastMessage,
+    dryRun?: boolean,
+  ): Promise<BatchResponse> {
+    const copy: any = deepCopy(message);
     if (!validator.isNonNullObject(copy)) {
       throw new FirebaseMessagingError(
         messagingClientErrorCode.INVALID_ARGUMENT, 'MulticastMessage must be a non-null object');
     }
-    if (!validator.isNonEmptyArray(copy.tokens)) {
+
+    const { tokens, fids, ...baseMessage } = copy;
+
+    if (tokens !== undefined && !validator.isArray(tokens)) {
+      throw new FirebaseMessagingError(
+        messagingClientErrorCode.INVALID_ARGUMENT, 'tokens must be a valid array');
+    }
+    if (fids !== undefined && !validator.isArray(fids)) {
+      throw new FirebaseMessagingError(
+        messagingClientErrorCode.INVALID_ARGUMENT, 'fids must be a valid array');
+    }
+
+    const tokenList: string[] = tokens || [];
+    const fidList: string[] = fids || [];
+
+    if (tokenList.length === 0 && fidList.length === 0) {
       throw new FirebaseMessagingError(
-        messagingClientErrorCode.INVALID_ARGUMENT, 'tokens must be a non-empty array');
+        messagingClientErrorCode.INVALID_ARGUMENT, 'Either tokens or fids must be a non-empty array');
     }
-    if (copy.tokens.length > FCM_MAX_BATCH_SIZE) {
+
+    const totalLength = tokenList.length + fidList.length;
+    if (totalLength > FCM_MAX_BATCH_SIZE) {
       throw new FirebaseMessagingError(
         messagingClientErrorCode.INVALID_ARGUMENT,
-        `tokens list must not contain more than ${FCM_MAX_BATCH_SIZE} items`);
+        `The total number of tokens and fids must not exceed ${FCM_MAX_BATCH_SIZE}.`);
     }
 
-    const messages: Message[] = copy.tokens.map((token) => {
-      return {
-        token,
-        android: copy.android,
-        apns: copy.apns,
-        data: copy.data,
-        notification: copy.notification,
-        webpush: copy.webpush,
-        fcmOptions: copy.fcmOptions,
-      };
-    });
+    const messages: Message[] = [
+      ...tokenList.map((token) => ({ ...baseMessage, token } as Message)),
+      ...fidList.map((fid) => ({ ...baseMessage, fid } as Message)),
+    ];
+
     return this.sendEach(messages, dryRun);
   }
 

src/utils/api-request.ts

@@ -77,6 +77,8 @@ export interface RequestResponse {
   readonly data?: any;
   /** For multipart responses, the payloads of individual parts. */
   readonly multipart?: Buffer[];
+  /** Optional request config used to send this request. */
+  readonly config?: any;
   /**
    * Indicates if the response content is JSON-formatted or not. If true, data field can be used
    * to retrieve the content as a parsed JSON object.
@@ -129,6 +131,7 @@ class DefaultRequestResponse implements RequestResponse {
   public readonly status: number;
   public readonly headers: any;
   public readonly text?: string;
+  public readonly config?: RequestConfig;
 
   private readonly parsedData: any;
   private readonly parseError: Error;
@@ -140,6 +143,7 @@ class DefaultRequestResponse implements RequestResponse {
     this.status = resp.status;
     this.headers = resp.headers;
     this.text = resp.data;
+    this.config = resp.config;
     try {
       if (!resp.data) {
         throw new FirebaseAppError({ code: AppErrorCode.INTERNAL_ERROR, message: 'HTTP response missing data.' });
@@ -177,11 +181,13 @@ class MultipartRequestResponse implements RequestResponse {
   public readonly status: number;
   public readonly headers: any;
   public readonly multipart?: Buffer[];
+  public readonly config?: any;
 
   constructor(resp: LowLevelResponse) {
     this.status = resp.status;
     this.headers = resp.headers;
     this.multipart = resp.multipart;
+    this.config = resp.config;
   }
 
   get text(): string {