Implemented APNs Critical Sound Support (#409)

* Implemented APNs Critical Sound Support

* Adding typeguard to isString()

Author: hiranya911

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Unreleased
 
+- [added] `messaging.Aps` type now supports configuring a critical sound.
+  A new `messaging.CriticalSound` type has been introduced for this purpose.
+- [added] `messaging.AndroidNotification` type now supports `channel_id`.
 - [added] `AppOptions` now accepts an optional `http.Agent` object. The
   `http.Agent` specified via this API is used when the SDK makes backend
   HTTP calls. This can be used when it is required to deploy the Admin SDK

src/index.d.ts

@@ -449,7 +449,7 @@ declare namespace admin.messaging {
   type Aps = {
     alert?: string | ApsAlert;
     badge?: number;
-    sound?: string;
+    sound?: string | CriticalSound;
     contentAvailable?: boolean;
     mutableContent?: boolean;
     category?: string;
@@ -471,6 +471,12 @@ declare namespace admin.messaging {
     launchImage?: string;
   };
 
+  type CriticalSound = {
+    critical?: boolean;
+    name?: string;
+    volume?: number;
+  }
+
   type Notification = {
     title?: string;
     body?: string;

src/messaging/messaging.ts

@@ -170,14 +170,20 @@ export interface ApnsPayload {
 export interface Aps {
   alert?: string | ApsAlert;
   badge?: number;
-  sound?: string;
+  sound?: string | CriticalSound;
   contentAvailable?: boolean;
   category?: string;
   threadId?: string;
   mutableContent?: boolean;
   [customData: string]: any;
 }
 
+export interface CriticalSound {
+  critical?: boolean;
+  name?: string;
+  volume?: number;
+}
+
 export interface ApsAlert {
   title?: string;
   subtitle?: string;
@@ -299,6 +305,7 @@ function validateAps(aps: Aps) {
       MessagingClientErrorCode.INVALID_PAYLOAD, 'apns.payload.aps must be a non-null object');
   }
   validateApsAlert(aps.alert);
+  validateApsSound(aps.sound);
 
   const propertyMappings: {[key: string]: string} = {
     contentAvailable: 'content-available',
@@ -332,6 +339,40 @@ function validateAps(aps: Aps) {
   }
 }
 
+function validateApsSound(sound: string | CriticalSound) {
+  if (typeof sound === 'undefined' || validator.isString(sound)) {
+    return;
+  } else if (!validator.isNonNullObject(sound)) {
+    throw new FirebaseMessagingError(
+      MessagingClientErrorCode.INVALID_PAYLOAD,
+      'apns.payload.aps.sound must be a string or a non-null object');
+  }
+
+  const volume = sound.volume;
+  if (typeof volume !== 'undefined') {
+    if (!validator.isNumber(volume)) {
+      throw new FirebaseMessagingError(
+        MessagingClientErrorCode.INVALID_PAYLOAD,
+        'apns.payload.aps.sound.volume must be a number');
+    }
+    if (volume < 0 || volume > 1) {
+      throw new FirebaseMessagingError(
+        MessagingClientErrorCode.INVALID_PAYLOAD,
+        'apns.payload.aps.sound.volume must be in the interval [0, 1]');
+    }
+  }
+  const soundObject = sound as {[key: string]: any};
+  const key = 'critical';
+  const critical = soundObject[key];
+  if (typeof critical !== 'undefined' && critical !== 1) {
+    if (critical === true) {
+      soundObject[key] = 1;
+    } else {
+      delete soundObject[key];
+    }
+  }
+}
+
 /**
  * Checks if the given alert object is valid. Alert could be a string or a complex object.
  * If specified as an object, it must have valid localization parameters. If successful, transforms

src/utils/validator.ts

@@ -75,7 +75,7 @@ export function isNumber(value: any): boolean {
  * @param {any} value The value to validate.
  * @return {boolean} Whether the value is a string or not.
  */
-export function isString(value: any): boolean {
+export function isString(value: any): value is string {
   return typeof value === 'string';
 }
 

test/unit/messaging/messaging.spec.ts

@@ -1719,6 +1719,27 @@ describe('Messaging', () => {
       }).to.throw('bodyLocKey is required when specifying bodyLocArgs');
     });
 
+    const invalidVolumes = [-0.1, 1.1];
+    invalidVolumes.forEach((volume) => {
+      it(`should throw given invalid apns sound volume: ${volume}`, () => {
+        const message: Message = {
+          condition: 'topic-name',
+          apns: {
+            payload: {
+              aps: {
+                sound: {
+                  volume,
+                },
+              },
+            },
+          },
+        };
+        expect(() => {
+          messaging.send(message);
+        }).to.throw('volume must be in the interval [0, 1]');
+      });
+    });
+
     it('should throw given apns titleLocArgs without titleLocKey', () => {
       const message: Message = {
         condition: 'topic-name',
@@ -1859,6 +1880,15 @@ describe('Messaging', () => {
         }).to.throw('apns.payload.aps.alert must be a string or a non-null object');
       });
     });
+
+    const invalidApnsSounds: any[] = [null, [], true, 1.23];
+    invalidApnsSounds.forEach((sound) => {
+      it(`should throw given APNS payload with invalid aps sound: ${JSON.stringify(sound)}`, () => {
+        expect(() => {
+          messaging.send({apns: {payload: {aps: {sound}}}, token: 'token'});
+        }).to.throw('apns.payload.aps.sound must be a string or a non-null object');
+      });
+    });
   });
 
   describe('Options validation', () => {
@@ -2344,6 +2374,63 @@ describe('Messaging', () => {
           },
         },
       },
+      {
+        label: 'APNS critical sound',
+        req: {
+          apns: {
+            payload: {
+              aps: {
+                sound: {
+                  critical: true,
+                  name: 'test.sound',
+                  volume: 0.5,
+                },
+              },
+            },
+          },
+        },
+        expectedReq: {
+          apns: {
+            payload: {
+              aps: {
+                sound: {
+                  critical: 1,
+                  name: 'test.sound',
+                  volume: 0.5,
+                },
+              },
+            },
+          },
+        },
+      },
+      {
+        label: 'APNS critical sound explicitly false',
+        req: {
+          apns: {
+            payload: {
+              aps: {
+                sound: {
+                  critical: false,
+                  name: 'test.sound',
+                  volume: 0.5,
+                },
+              },
+            },
+          },
+        },
+        expectedReq: {
+          apns: {
+            payload: {
+              aps: {
+                sound: {
+                  name: 'test.sound',
+                  volume: 0.5,
+                },
+              },
+            },
+          },
+        },
+      },
       {
         label: 'APNS contentAvailable explicitly false',
         req: {