Firebase Cloud Messaging API (#187)

* New FCM API

* Adding FCM unit tests

* Added other FCM message types and tests

* Minor cleanup

* APNS message validation

* Cleaned up tests

* Improved error handling

* Updated typings and integration tests

* Updated typings

* Added APNS types in the impl

* Updated unit tests

* Implemented dry run mode

* Updated API; Implemented TTL numeric values; More test coverage

* Boosted test coverage to almost 100%

* Updated changelog

* Changing test data

* Adding some documentation; Addressing some code review feedback

* Accept prefixed topic names (#203)

* Accept prefixed topic names

* Further validating topic names

* Handling the New FCM Error Codes (#206)

* Using new FCM error codes

* Adding new SDK error code message-rate-exceeded

* Updated changelog

Author: hiranya911

CHANGELOG.md

@@ -1,6 +1,8 @@
 # Unrelased
 
--
+- [added] Added the `messaging.send()` method and the new `Message` type for
+  sending Cloud Messaging notifications via the
+  [new FCM REST endpoint](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages).
 
 # v5.8.2
 

src/index.d.ts

@@ -292,7 +292,99 @@ declare namespace admin.database.ServerValue {
   var TIMESTAMP: number;
 }
 
+type BaseMessage = {
+  data?: {[key: string]: string};
+  notification?: admin.messaging.Notification;
+  android?: admin.messaging.AndroidConfig;
+  webpush?: admin.messaging.WebpushConfig;
+  apns?: admin.messaging.ApnsConfig;
+};
+
+interface TokenMessage extends BaseMessage {
+  token: string;
+}
+
+interface TopicMessage extends BaseMessage {
+  topic: string;
+}
+
+interface ConditionMessage extends BaseMessage {
+  condition: string;
+}
+
 declare namespace admin.messaging {
+  type Message = TokenMessage | TopicMessage | ConditionMessage;
+
+  type AndroidConfig = {
+    collapseKey?: string;
+    priority?: ('high'|'normal');
+    ttl?: number;
+    restrictedPackageName?: string;
+    data?: {[key: string]: string};
+    notification?: AndroidNotification;
+  };
+
+  type AndroidNotification = {
+    title?: string;
+    body?: string;
+    icon?: string;
+    color?: string;
+    sound?: string;
+    tag?: string;
+    clickAction?: string;
+    bodyLocKey?: string;
+    bodyLocArgs?: string[];
+    titleLocKey?: string;
+    titleLocArgs?: string[];
+  };
+
+  type ApnsConfig = {
+    headers?: {[key: string]: string};
+    payload?: ApnsPayload;
+  };
+
+  type ApnsPayload = {
+    aps: Aps;
+    [customData: string]: object;
+  };
+
+  type Aps = {
+    alert?: string | ApsAlert;
+    badge?: number;
+    sound?: string;
+    contentAvailable?: boolean;
+    category?: string;
+    threadId?: string;
+  };
+
+  type ApsAlert = {
+    title?: string;
+    body?: string;
+    locKey?: string;
+    locArgs?: string[];
+    titleLocKey?: string;
+    titleLocArgs?: string[];
+    actionLocKey?: string;
+    launchImage?: string;
+  };
+
+  type Notification = {
+    title?: string;
+    body?: string;
+  };
+  
+  type WebpushConfig = {
+    headers?: {[key: string]: string};
+    data?: {[key: string]: string};
+    notification?: WebpushNotification;
+  };
+  
+  type WebpushNotification = {
+    title?: string;
+    body?: string;
+    icon?: string;
+  };
+
   type DataMessagePayload = {
     [key: string]: string;
   };
@@ -366,6 +458,7 @@ declare namespace admin.messaging {
   interface Messaging {
     app: admin.app.App;
 
+    send(message: admin.messaging.Message, dryRun?: boolean): Promise<string>;
     sendToDevice(
       registrationToken: string | string[],
       payload: admin.messaging.MessagingPayload,

src/messaging/messaging-api-request.ts

@@ -45,6 +45,8 @@ export class FirebaseMessagingRequestHandler {
     if (validator.isNonNullObject(response) && 'error' in response) {
       if (typeof response.error === 'string') {
         return response.error;
+      } else if ('status' in response.error) {
+        return response.error.status;
       } else {
         return response.error.message;
       }
@@ -53,6 +55,21 @@ export class FirebaseMessagingRequestHandler {
     return null;
   }
 
+  /**
+   * Extracts error message from the given response object.
+   *
+   * @param {object} response The response to check for errors.
+   * @return {string|null} The error message if present; null otherwise.
+   */
+  private static getErrorMessage(response: any): string | null {
+    if (validator.isNonNullObject(response) &&
+        'error' in response &&
+        validator.isNonEmptyString(response.error.message)) {
+      return response.error.message;
+    }
+    return null;
+  }
+
   /**
    * @param {FirebaseApp} app The app used to fetch access tokens to sign API requests.
    * @constructor
@@ -138,7 +155,8 @@ export class FirebaseMessagingRequestHandler {
 
       // For JSON responses, map the server response to a client-side error.
       const errorCode = FirebaseMessagingRequestHandler.getErrorCode(response.error);
-      throw FirebaseMessagingError.fromServerError(errorCode, /* message */ undefined, response.error);
+      const errorMessage = FirebaseMessagingRequestHandler.getErrorMessage(response.error);
+      throw FirebaseMessagingError.fromServerError(errorCode, errorMessage, response.error);
     });
   }
 }