Polished index.d.ts based on Arthur's feedback

zwu52 · zwu52 · commit 8aedf9282063 · 2020-07-07T13:47:21.000-07:00
diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts
@@ -6950,7 +6950,7 @@ declare namespace firebase.messaging {
    */
   interface Messaging {
     /**
-     * Deletes the only registration token associated with this messaging instance and unsubscribes
+     * Deletes the registration token associated with this messaging instance and unsubscribes
      * this messaging instance from the push subscription.
      *
      * @return The promise resolves when the token has been successfully deleted.
@@ -6970,19 +6970,26 @@ declare namespace firebase.messaging {
     deleteToken(token: string): Promise<boolean>;
 
     /**
-     * Subscribes the user to push notifications. Returns an FCM registration
+     * Subscribes the messaging instance to push notifications. Returns an FCM registration
      * token that can be used to send push messages to the user.
      *
      * If notification permission isn't already granted, this method asks the
      * user for permission. The returned promise rejects if the user does not
      * allow the app to show notifications.
      *
-     * @param options.vapidKey the public server key provided to push services. It is used to authenticate
-     * the push subscribers to receive push messages only from sending servers that holds the corresponding private key. If it is not provided, a default VAPID key will be be used. Note that some push services (Chrome Push Service) require a non-default VAPID key. Therefore, it is recommended to to generate and import a VAPID key for your project with {@link https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm Configure Web Credentials with FCM}. Also See {@link https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol The Web Push Protocol} for details on web push services.}
+     * @param options.vapidKey the public server key provided to push services. It is used to
+     * authenticate the push subscribers to receive push messages only from sending servers that
+     * holds the corresponding private key. If it is not provided, a default VAPID key will be used.
+     * Note that some push services (Chrome Push Service) require a non-default VAPID key.
+     * Therefore, it is recommended to generate and import a VAPID key for your project with
+     * {@link https://firebase.google.com/docs/cloud-messaging/js/client#configure_web_credentials_with_fcm Configure Web Credentials with FCM}.
+     * See {@link https://developers.google.com/web/fundamentals/push-notifications/web-push-protocol The Web Push Protocol}
+     * for details on web push services.}
      *
      * @param options.serviceWorkerRegistration the service worker registration for receiving push messaging.
      * If it is not provided explicitly, you need to have a `firebase-messaging-sw.js` at your root location.
-     * See {@link https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token Retrieve the current registration token} for more details.
+     * See {@link https://firebase.google.com/docs/cloud-messaging/js/client#retrieve-the-current-registration-token Retrieve the current registration token}
+     * for more details.
      *
      * @return The promise resolves with the FCM token string.
      *
@@ -7027,7 +7034,8 @@ declare namespace firebase.messaging {
     ): firebase.Unsubscribe;
 
     /**
-     * Called when a message is received while the app is in the background. An app is considered as a background app if no active window is displayed.
+     * Called when a message is received while the app is in the background. An app is considered
+     * as a background app if no active window is displayed.
      *
      * @param
      *     nextOrObserver This function, or observer object with `next` defined,
@@ -7115,7 +7123,10 @@ declare namespace firebase.messaging {
   }
 
   /**
-   * Message payload that contains the notification payload that is represented with {@link firebase.Messaging.NotificationPayload} and the data payload that contains an arbitrary number of key-value pairs sent by developers through the {@link https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification Send API}
+   * Message payload that contains the notification payload that is represented with
+   *  {@link firebase.Messaging.NotificationPayload} and the data payload that contains an
+   * arbitrary number of key-value pairs sent by developers through
+   * the {@link https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#notification Send API}
    */
   export interface MessagePayload {
     /**
@@ -7126,21 +7137,38 @@ declare namespace firebase.messaging {
     /**
      * Arbitrary key/value pairs.
      */
-
     data?: { [key: string]: string };
 
     /**
      * See {@link firebase.Messaging.FcmOptions}.
      */
-
     fcmOptions?: FcmOptions;
+
+    /**
+     * The sender of this message.
+     */
+    from: string;
+
+    /**
+     * The collapse key of this message. See more {@link https://firebase.google.com/docs/cloud-messaging/concept-options#collapsible_and_non-collapsible_messages}.
+     */
+    collapseKey: string;
   }
 
   /**
    * Options for features provided by the FCM SDK for Web. See more {@link https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushfcmoptions}.
    */
   export interface FcmOptions {
+    /**
+     * The link to open when the user clicks on the notification. For all URL values, HTTPS is required.
+     * For example, by setting this value to your app's URL, a notification click click event will
+     * put your app in focus for the user.
+     */
     link?: string;
+
+    /**
+     * Label associated with the message's analytics data.
+     */
     analyticsLabel?: string;
   }
 
diff --git a/packages/messaging/src/controllers/sw-controller.test.ts b/packages/messaging/src/controllers/sw-controller.test.ts
@@ -60,14 +60,20 @@ const DISPLAY_MESSAGE: MessagePayloadInternal = {
   },
   fcmOptions: {
     link: 'https://example.org'
-  }
+  },
+  from: 'from',
+  // eslint-disable-next-line camelcase
+  collapse_key: 'collapse'
 };
 
 // internal message payload (parsed directly from the push event) that contains and only contains data payload.
 const DATA_MESSAGE: MessagePayloadInternal = {
   data: {
     key: 'value'
-  }
+  },
+  from: 'from',
+  // eslint-disable-next-line camelcase
+  collapse_key: 'collapse'
 };
 
 describe('SwController', () => {
diff --git a/packages/messaging/src/controllers/sw-controller.ts b/packages/messaging/src/controllers/sw-controller.ts
@@ -105,7 +105,9 @@ export class SwController implements FirebaseMessaging, FirebaseService {
   // Calling this from an old SW can cause all kinds of trouble.
   async getToken(): Promise<string> {
     if (!this.vapidKey) {
-      // Call getToken using the current VAPID key if there already is a token. This is needed because usePublicVapidKey was not available in SW. It will be removed when vapidKey becomes a parameter of getToken, or when getToken is removed from SW.
+      // Call getToken using the current VAPID key if there already is a token. This is needed
+      // because usePublicVapidKey was not available in SW. It will be removed when vapidKey becomes
+      // a parameter of getToken, or when getToken is removed from SW.
       const tokenDetails = await dbGet(this.firebaseDependencies);
       this.vapidKey =
         tokenDetails?.subscriptionOptions?.vapidKey ?? DEFAULT_VAPID_KEY;
@@ -156,7 +158,9 @@ export class SwController implements FirebaseMessaging, FirebaseService {
    * A handler for push events that shows notifications based on the content of the payload.
    *
    * The payload must be a JSON-encoded Object with a `notification` key. The
-   * value of the `notification` property will be used as the NotificationOptions object passed to showNotification. Additionally, the `title` property of the notification object will be used as the title.
+   * value of the `notification` property will be used as the NotificationOptions object passed to
+   * showNotification. Additionally, the `title` property of the notification object will be used as
+   * the title.
    *
    * If there is no notification data in the payload then no notification will be shown.
    */
@@ -176,7 +180,7 @@ export class SwController implements FirebaseMessaging, FirebaseService {
       return sendMessagePayloadInternalToWindows(clientList, internalPayload);
     }
 
-    // background handling: display and pass to onBackgroundMessage
+    // background handling: display and pass to onBackgroundMessage hook
     if (!!internalPayload.notification) {
       await showNotification(wrapInternalPayload(internalPayload));
     } else if (this.bgMessageHandler) {
@@ -213,7 +217,8 @@ export class SwController implements FirebaseMessaging, FirebaseService {
     if (!internalPayload) {
       return;
     } else if (event.action) {
-      // User clicked on an action button. This will allow developers to act on action button clicks by using a custom onNotificationClick listener that they define.
+      // User clicked on an action button. This will allow developers to act on action button clicks
+      // by using a custom onNotificationClick listener that they define.
       return;
     }
 
@@ -230,7 +235,8 @@ export class SwController implements FirebaseMessaging, FirebaseService {
     if (!client) {
       // Unable to find window client so need to open one. This also focuses the opened client.
       client = await self.clients.openWindow(link);
-      // Wait three seconds for the client to initialize and set up the message handler so that it can receive the message.
+      // Wait three seconds for the client to initialize and set up the message handler so that it
+      // can receive the message.
       await sleep(3000);
     } else {
       client = await client.focus();
@@ -254,7 +260,9 @@ function wrapInternalPayload(
     ...((internalPayload.notification as unknown) as NotificationPayloadInternal)
   };
 
-  // Put the message payload under FCM_MSG name so we can identify the notification as being an FCM notification vs a notification from somewhere else (i.e. normal web push or developer generated notification).
+  // Put the message payload under FCM_MSG name so we can identify the notification as being an
+  // FCM notification vs a notification from somewhere else (i.e. normal web push or developer
+  // generated notification).
   wrappedInternalPayload.data = {
     [FCM_MSG]: internalPayload
   };
@@ -282,7 +290,8 @@ function getMessagePayloadInternal({
  * @return Returns an existing window client or a newly opened WindowClient.
  */
 async function getWindowClient(url: string): Promise<WindowClient | null> {
-  // Use URL to normalize the URL when comparing to windowClients. This at least handles whether to include trailing slashes or not
+  // Use URL to normalize the URL when comparing to windowClients. This at least handles whether
+  // to include trailing slashes or not
   const parsedURL = new URL(url, self.location.href);
 
   const clientList = await getClientList();
@@ -305,7 +314,8 @@ function hasVisibleClients(clientList: WindowClient[]): boolean {
   return clientList.some(
     client =>
       client.visibilityState === 'visible' &&
-      // Ignore chrome-extension clients as that matches the background pages of extensions, which are always considered visible for some reason.
+      // Ignore chrome-extension clients as that matches the background pages of extensions,
+      // which are always considered visible for some reason.
       !client.url.startsWith('chrome-extension://')
   );
 }
@@ -333,7 +343,8 @@ function getClientList(): Promise<WindowClient[]> {
 function showNotification(
   notificationPayloadInternal: NotificationPayloadInternal
 ): Promise<void> {
-  // Note: Firefox does not support the maxActions property. https://developer.mozilla.org/en-US/docs/Web/API/notification/maxActions
+  // Note: Firefox does not support the maxActions property.
+  // https://developer.mozilla.org/en-US/docs/Web/API/notification/maxActions
   const { actions } = notificationPayloadInternal;
   const { maxActions } = Notification;
   if (actions && maxActions && actions.length > maxActions) {
diff --git a/packages/messaging/src/controllers/window-controller.test.ts b/packages/messaging/src/controllers/window-controller.test.ts
@@ -382,7 +382,10 @@ describe('WindowController', () => {
       const internalPayload: MessagePayloadInternal = {
         notification: { title: 'hello', body: 'world' },
         messageType: MessageType.PUSH_RECEIVED,
-        isFirebaseMessaging: true
+        isFirebaseMessaging: true,
+        from: 'from',
+        // eslint-disable-next-line camelcase
+        collapse_key: 'collapse'
       };
 
       await messageEventListener(
@@ -403,7 +406,10 @@ describe('WindowController', () => {
       const internalPayload: MessagePayloadInternal = {
         notification: { title: 'hello', body: 'world' },
         messageType: MessageType.PUSH_RECEIVED,
-        isFirebaseMessaging: true
+        isFirebaseMessaging: true,
+        from: 'from',
+        // eslint-disable-next-line camelcase
+        collapse_key: 'collapse'
       };
 
       await messageEventListener(
@@ -421,7 +427,10 @@ describe('WindowController', () => {
       const internalPayload: MessagePayloadInternal = {
         notification: { title: 'hello', body: 'world' },
         messageType: MessageType.PUSH_RECEIVED,
-        isFirebaseMessaging: true
+        isFirebaseMessaging: true,
+        from: 'from',
+        // eslint-disable-next-line camelcase
+        collapse_key: 'collapse'
       };
 
       await messageEventListener(
@@ -512,7 +521,10 @@ describe('WindowController', () => {
       const internalPayload: MessagePayloadInternal = {
         notification: { title: 'hello', body: 'world' },
         messageType: MessageType.PUSH_RECEIVED,
-        isFirebaseMessaging: true
+        isFirebaseMessaging: true,
+        from: 'from',
+        // eslint-disable-next-line camelcase
+        collapse_key: 'collapse'
       };
 
       await messageEventListener(
@@ -529,7 +541,10 @@ describe('WindowController', () => {
       const internalPayload: MessagePayloadInternal = {
         notification: { title: 'hello', body: 'world' },
         messageType: MessageType.NOTIFICATION_CLICKED,
-        isFirebaseMessaging: true
+        isFirebaseMessaging: true,
+        from: 'from',
+        // eslint-disable-next-line camelcase
+        collapse_key: 'collapse'
       };
 
       await messageEventListener(
@@ -550,7 +565,10 @@ describe('WindowController', () => {
           [CONSOLE_CAMPAIGN_ANALYTICS_ENABLED]: '1'
         },
         messageType: MessageType.PUSH_RECEIVED,
-        isFirebaseMessaging: true
+        isFirebaseMessaging: true,
+        from: 'from',
+        // eslint-disable-next-line camelcase
+        collapse_key: 'collapse'
       };
 
       await messageEventListener(
@@ -583,7 +601,10 @@ describe('WindowController', () => {
           [CONSOLE_CAMPAIGN_ANALYTICS_ENABLED]: '1'
         },
         messageType: MessageType.NOTIFICATION_CLICKED,
-        isFirebaseMessaging: true
+        isFirebaseMessaging: true,
+        from: 'from',
+        // eslint-disable-next-line camelcase
+        collapse_key: 'collapse'
       };
 
       await messageEventListener(
diff --git a/packages/messaging/src/controllers/window-controller.ts b/packages/messaging/src/controllers/window-controller.ts
@@ -74,11 +74,16 @@ export class WindowController implements FirebaseMessaging, FirebaseService {
       return;
     }
 
+    // onMessageCallback is either a function or observer/subscriber.
     if (
       this.onMessageCallback &&
       internalPayload.messageType === MessageType.PUSH_RECEIVED
     ) {
-      this.onMessageCallback(externalizePayload(internalPayload));
+      if (typeof this.onMessageCallback === 'function') {
+        this.onMessageCallback(externalizePayload(internalPayload));
+      } else {
+        this.onMessageCallback.next(externalizePayload(internalPayload));
+      }
     }
 
     const dataPayload = internalPayload.data;
diff --git a/packages/messaging/src/helpers/externalizePayload.test.ts b/packages/messaging/src/helpers/externalizePayload.test.ts
@@ -31,11 +31,15 @@ describe('externalizePayload', () => {
         title: 'title',
         body: 'body',
         image: 'image'
-      }
+      },
+      from: 'from',
+      collapse_key: 'collapse'
     };
 
     const payload: MessagePayload = {
-      notification: { title: 'title', body: 'body', image: 'image' }
+      notification: { title: 'title', body: 'body', image: 'image' },
+      from: 'from',
+      collapseKey: 'collapse'
     };
     expect(externalizePayload(internalPayload)).to.deep.equal(payload);
   });
@@ -46,11 +50,15 @@ describe('externalizePayload', () => {
         foo: 'foo',
         bar: 'bar',
         baz: 'baz'
-      }
+      },
+      from: 'from',
+      collapse_key: 'collapse'
     };
 
     const payload: MessagePayload = {
-      data: { foo: 'foo', bar: 'bar', baz: 'baz' }
+      data: { foo: 'foo', bar: 'bar', baz: 'baz' },
+      from: 'from',
+      collapseKey: 'collapse'
     };
     expect(externalizePayload(internalPayload)).to.deep.equal(payload);
   });
@@ -70,7 +78,9 @@ describe('externalizePayload', () => {
       fcmOptions: {
         link: 'link',
         analytics_label: 'label'
-      }
+      },
+      from: 'from',
+      collapse_key: 'collapse'
     };
 
     const payload: MessagePayload = {
@@ -87,7 +97,9 @@ describe('externalizePayload', () => {
       fcmOptions: {
         link: 'link',
         analyticsLabel: 'label'
-      }
+      },
+      from: 'from',
+      collapseKey: 'collapse'
     };
     expect(externalizePayload(internalPayload)).to.deep.equal(payload);
   });
diff --git a/packages/messaging/src/helpers/externalizePayload.ts b/packages/messaging/src/helpers/externalizePayload.ts
@@ -27,7 +27,9 @@ export function externalizePayload(
   const payload: MessagePayload = {
     notification: {},
     data: {},
-    fcmOptions: {}
+    fcmOptions: {},
+    from: internalPayload.from,
+    collapseKey: internalPayload.collapse_key
   } as MessagePayload;
 
   propagateNotificationPayload(payload, internalPayload);
diff --git a/packages/messaging/src/interfaces/message-payload.ts b/packages/messaging/src/interfaces/message-payload.ts
