@parse/push-adapter 6.2.0 → 6.4.0

package/README.md

@@ -5,46 +5,29 @@
 [![Coverage](https://img.shields.io/codecov/c/github/parse-community/parse-server-push-adapter/master.svg)](https://codecov.io/github/parse-community/parse-server-push-adapter?branch=master)
 [![auto-release](https://img.shields.io/badge/%F0%9F%9A%80-auto--release-9e34eb.svg)](https://github.com/parse-community/parse-server-push-adapter/releases)
 
-[![Node Version](https://img.shields.io/badge/nodejs-18,_20-green.svg?logo=node.js&style=flat)](https://nodejs.org)
+[![Node Version](https://img.shields.io/badge/nodejs-18,_20,_22-green.svg?logo=node.js&style=flat)](https://nodejs.org)
 
 [![npm latest version](https://img.shields.io/npm/v/@parse/push-adapter.svg)](https://www.npmjs.com/package/@parse/push-adapter)
 
 ---
 
-The official Push Notification adapter for Parse Server. See [Parse Server Push Configuration](http://docs.parseplatform.org/parse-server/guide/#push-notifications) for more details. 
+The official Push Notification adapter for Parse Server. See [Parse Server Push Configuration](http://docs.parseplatform.org/parse-server/guide/#push-notifications) for more details.
 
 ---
 
-- [Silent Notifications](#silent-notifications)
+- [Installation](#installation)
+- [Configure Parse Server](#configure-parse-server)
+  - [Apple Push Options](#apple-push-options)
+  - [Android Push Options](#android-push-options)
+    - [Google Cloud Service Account Key](#google-cloud-service-account-key)
+    - [Migration to FCM HTTP v1 API (June 2024)](#migration-to-fcm-http-v1-api-june-2024)
+  - [Expo Push Options](#expo-push-options)
+- [Bundled with Parse Server](#bundled-with-parse-server)
 - [Logging](#logging)
-- [Using a Custom Version on Parse Server](#using-a-custom-version-on-parse-server)
-  - [Install Push Adapter](#install-push-adapter)
-  - [Configure Parse Server](#configure-parse-server)
-    - [Expo Push Options](#expo-push-options)
 
-# Silent Notifications
+## Installation
 
-If you have migrated from parse.com and you are seeing situations where silent (newsstand-like presentless) notifications are failing to deliver please ensure that your payload is setting the content-available attribute to Int(1) and not "1" This value will be explicitly checked.
-
-# Logging
-
-You can enable verbose logging with environment variables:
-
-```
-VERBOSE=1
-
-or 
-
-VERBOSE_PARSE_SERVER_PUSH_ADAPTER=1
-```
-
-This will produce a more verbose output for all the push sending attempts
-
-# Using a Custom Version on Parse Server
-
-## Install Push Adapter
-
-```
+```shell
 npm install --save @parse/push-adapter@<VERSION>
 ```
 
@@ -53,25 +36,106 @@ Replace `<VERSION>` with the version you want to install.
 ## Configure Parse Server
 
 ```js
-const PushAdapter = require('@parse/push-adapter').default;
+import { ParsePushAdapter } from '@parse/push-adapter';
+
+// For CommonJS replace the import statemtent above with the following line:
+// const ParsePushAdapter = require('@parse/push-adapter').default;
+
 const parseServerOptions = {
   push: {
-    adapter: new PushAdapter({
+    adapter: new ParsePushAdapter({
       ios: {
-        /* Apple push options */
+        // Apple push options
       },
       android: {
-        /* Android push options */
+        // Android push options
       },
       web: {
-        /* Web push options */
+        // Web push options
       },
       expo: {
-        /* Expo push options */
-      },
-    }),
+        // Expo push options
+      }
+    })
+  }
+  // Other Parse Server options
+};
+```
+
+### Apple Push Options
+
+Parse Server Push Adapter currently supports these types of Apple ecosystems:
+
+- `ios`: iPhone, iPad, and iPod touch apps
+- `osx`: macOS, and macCatalyst apps
+- `tvos`: tvOS apps
+
+Delivering push notifications to Apple devices can be done either via Apple Push Notification Service (APNS), or via Firebase Cloud Messaging (FMC). Note that each category of Apple devices require their own configuration section:
+
+- APNS requires a private key that can be downloaded from the Apple Developer Center at https://developer.apple.com/account under _Certificates > Identifiers & Profiles._ The adapter options also require the app ID and team ID which can be found there.
+- FCM requires a private key that can be downloaded from the Firebase Console at https://console.firebase.google.com in your project under _Settings > Cloud Messaging._
+
+Example options:
+
+Both services (APNS, FCM) can be used in combination for different Apple ecosystems.
+
+```js
+ios: {
+  // Deliver push notifications to iOS devices via APNS
+  token: {
+    key: __dirname + '/apns.p8',
+    keyId: '<APNS_KEY_ID>',
+    teamId: '<APNS_TEAM_ID>'
   },
-  /* Other Parse Server options */
+  topic: '<BUNDLE_IDENTIFIER>',
+  production: true
+},
+osx: {
+  // Deliver push notifications to macOS devices via FCM
+  firebaseServiceAccount: __dirname + '/firebase.json'
+}
+```
+
+### Android Push Options
+
+Delivering push notifications to Android devices can be done via Firebase Cloud Messaging (FCM):
+
+- FCM requires a private key that can be downloaded from the Firebase Console at https://console.firebase.google.com in your project under _Settings > Cloud Messaging._
+
+Example options:
+
+```js
+android: {
+  firebaseServiceAccount: __dirname + '/firebase.json'
+}
+```
+
+#### Google Cloud Service Account Key
+
+The Firebase console allows to easily create and download a Google Cloud service account key JSON file with the required permissions. Instead of setting `firebaseServiceAccount` to the path of the JSON file, you can provide an object representing a Google Cloud service account key:
+
+```js
+android: {
+  firebaseServiceAccount: {
+    projectId: '<PROJECT_ID>',
+    clientEmail: 'example@<PROJECT_ID>.iam.gserviceaccount.com',
+    privateKey: '-----BEGIN PRIVATE KEY-----<KEY>-----END PRIVATE KEY-----\n'
+  }
+}
+```
+
+This can be helpful if you are already managing credentials to Google Cloud APIs in other parts of your code and you want to reuse these credentials, or if you want to manage credentials on a more granular level directly in Google Cloud. Make sure that the service account has the permission `cloudmessaging.messages.create` which is for example part of role `Firebase Cloud Messaging API Admin`.
+
+#### Migration to FCM HTTP v1 API (June 2024)
+
+⚠️ Sending push notifications to Android devices via the FCM legacy API was deprecated on June 20 2023 and was announced to be decommissioned in June 2024. See [Google docs](https://firebase.google.com/docs/cloud-messaging/migrate-v1). To send push notifications to the newer FCM HTTP v1 API you need to update your existing push configuration for Android by replacing the key `apiKey` with `firebaseServiceAccount`.
+
+Example options (deprecated):
+
+```js
+android: {
+  // Deliver push notifications via FCM legacy API (deprecated)
+  apiKey: '<API_KEY>'
 }
 ```
 
@@ -81,9 +145,40 @@ Example options:
 
 ```js
 expo: {
-  accessToken: '<EXPO_ACCESS_TOKEN>',
-},
+  accessToken: '<EXPO_ACCESS_TOKEN>'
+}
 ```
 
 For more information see the [Expo docs](https://docs.expo.dev/push-notifications/overview/).
-         
+
+## Bundled with Parse Server
+
+Parse Server already comes bundled with a specific version of the push adapter. This installation is only necessary when customizing the push adapter version that should be used by Parse Server. When using a customized version of the push adapter, ensure that it's compatible with the version of Parse Server you are using.
+
+When using the bundled version, it is not necessary to initialize the push adapter in code and the push options are configured directly in the `push` key, without the nested `adapter` key:
+
+```js
+const parseServerOptions = {
+  push: {
+    ios: {
+      // Apple push options
+    }
+    // Other push options
+  }
+  // Other Parse Server options
+};
+```
+
+## Logging
+
+You can enable verbose logging to produce a more detailed output for all push sending attempts with the following environment variables:
+
+```js
+VERBOSE=1
+```
+
+or
+
+```js
+VERBOSE_PARSE_SERVER_PUSH_ADAPTER=1
+```

package/package.json

@@ -1,15 +1,14 @@
 {
   "name": "@parse/push-adapter",
-  "version": "6.2.0",
+  "version": "6.4.0",
   "description": "Base parse-server-push-adapter",
-  "main": "lib/index.js",
+  "main": "src/index.js",
+  "type": "module",
   "files": [
-    "lib/"
+    "src/"
   ],
   "scripts": {
-    "build": "./node_modules/.bin/babel src/ -d lib/",
-    "test": "TESTING=1 nyc ./node_modules/.bin/jasmine",
-    "prepare": "npm run build"
+    "test": "TESTING=1 c8 ./node_modules/.bin/jasmine"
   },
   "keywords": [
     "parse-server",
@@ -26,29 +25,25 @@
     "@parse/node-apn": "6.0.1",
     "@parse/node-gcm": "1.0.2",
     "expo-server-sdk": "3.10.0",
-    "firebase-admin": "12.1.0",
+    "firebase-admin": "12.1.1",
     "npmlog": "7.0.1",
-    "parse": "5.0.0",
+    "parse": "5.1.0",
     "web-push": "3.6.7"
   },
   "devDependencies": {
-    "@semantic-release/changelog": "5.0.1",
-    "@semantic-release/commit-analyzer": "8.0.1",
-    "@semantic-release/git": "9.0.0",
-    "@semantic-release/github": "7.2.3",
-    "@semantic-release/npm": "7.1.3",
-    "@semantic-release/release-notes-generator": "9.0.3",
-    "babel-cli": "6.26.0",
-    "babel-core": "6.26.3",
-    "babel-preset-es2015": "6.24.1",
-    "babel-preset-stage-0": "6.24.1",
-    "codecov": "3.7.1",
-    "jasmine": "2.8.0",
-    "jasmine-spec-reporter": "4.0.0",
-    "nyc": "14.1.1",
-    "semantic-release": "17.4.6"
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/commit-analyzer": "13.0.0",
+    "@semantic-release/git": "10.0.1",
+    "@semantic-release/github": "10.0.7",
+    "@semantic-release/npm": "12.0.1",
+    "@semantic-release/release-notes-generator": "14.0.1",
+    "c8": "10.1.2",
+    "codecov": "3.8.0",
+    "jasmine": "5.1.0",
+    "jasmine-spec-reporter": "7.0.0",
+    "semantic-release": "24.0.0"
   },
   "engines": {
-    "node": ">=18.0.0 <21"
+    "node": "18 || 20 || 22"
   }
 }

package/src/APNS.js

@@ -0,0 +1,323 @@
+'use strict';
+import apn from '@parse/node-apn';
+import Parse from 'parse';
+import log from 'npmlog';
+
+const LOG_PREFIX = 'parse-server-push-adapter APNS';
+
+export class APNS {
+
+  /**
+   * Create a new provider for the APN service.
+   * @constructor
+   * @param {Object|Array} args An argument or a list of arguments to config APNS provider
+   * @param {Object} args.token {Object} Configuration for Provider Authentication Tokens. (Defaults to: null i.e. fallback to Certificates)
+   * @param {Buffer|String} args.token.key The filename of the provider token key (as supplied by Apple) to load from disk, or a Buffer/String containing the key data.
+   * @param {String} args.token.keyId The ID of the key issued by Apple
+   * @param {String} args.token.teamId ID of the team associated with the provider token key
+   * @param {Buffer|String} args.cert The filename of the connection certificate to load from disk, or a Buffer/String containing the certificate data.
+   * @param {Buffer|String} args.key {Buffer|String} The filename of the connection key to load from disk, or a Buffer/String containing the key data.
+   * @param {Buffer|String} args.pfx path for private key, certificate and CA certs in PFX or PKCS12 format, or a Buffer containing the PFX data. If supplied will always be used instead of certificate and key above.
+   * @param {String} args.passphrase The passphrase for the provider key, if required
+   * @param {Boolean} args.production Specifies which environment to connect to: Production (if true) or Sandbox
+   * @param {String} args.topic Specififies an App-Id for this Provider
+   * @param {String} args.bundleId DEPRECATED: Specifies an App-ID for this Provider
+   * @param {Number} args.connectionRetryLimit  The maximum number of connection failures that will be tolerated before apn.Provider will "give up". (Defaults to: 3)
+   */
+  constructor(args) {
+    // Define class members
+    this.providers = [];
+
+    // Since for ios, there maybe multiple cert/key pairs, typePushConfig can be an array.
+    let apnsArgsList = [];
+    if (Array.isArray(args)) {
+      apnsArgsList = apnsArgsList.concat(args);
+    } else if (typeof args === 'object') {
+      apnsArgsList.push(args);
+    } else {
+      throw new Parse.Error(Parse.Error.PUSH_MISCONFIGURED, 'APNS Configuration is invalid');
+    }
+
+    // Create Provider from each arg-object
+    for (let apnsArgs of apnsArgsList) {
+
+      // rewrite bundleId to topic for backward-compatibility
+      if (apnsArgs.bundleId) {
+        log.warn(LOG_PREFIX, 'bundleId is deprecated, use topic instead');
+        apnsArgs.topic = apnsArgs.bundleId
+      }
+
+      let provider = APNS._createProvider(apnsArgs);
+      this.providers.push(provider);
+    }
+
+    // Sort the providers based on priority ascending, high pri first
+    this.providers.sort((s1, s2) => {
+      return s1.priority - s2.priority;
+    });
+
+    // Set index-property of providers
+    for (let index = 0; index < this.providers.length; index++) {
+      this.providers[index].index = index;
+    }
+  }
+
+  /**
+   * Send apns request.
+   *
+   * @param {Object} data The data we need to send, the format is the same with api request body
+   * @param {Array} allDevices An array of devices
+   * @returns {Object} A promise which is resolved immediately
+   */
+  send(data, allDevices) {
+    let coreData = data && data.data;
+    if (!coreData || !allDevices || !Array.isArray(allDevices)) {
+      log.warn(LOG_PREFIX, 'invalid push payload');
+      return;
+    }
+    let expirationTime = data['expiration_time'] || coreData['expiration_time'];
+    let collapseId = data['collapse_id'] || coreData['collapse_id'];
+    let pushType = data['push_type'] || coreData['push_type'];
+    let priority = data['priority'] || coreData['priority'];
+    let allPromises = [];
+
+    let devicesPerAppIdentifier = {};
+
+    // Start by clustering the devices per appIdentifier
+    allDevices.forEach(device => {
+      let appIdentifier = device.appIdentifier;
+      devicesPerAppIdentifier[appIdentifier] = devicesPerAppIdentifier[appIdentifier] || [];
+      devicesPerAppIdentifier[appIdentifier].push(device);
+    });
+
+    for (let key in devicesPerAppIdentifier) {
+      let devices = devicesPerAppIdentifier[key];
+      let appIdentifier = devices[0].appIdentifier;
+      let providers = this._chooseProviders(appIdentifier);
+
+      // No Providers found
+      if (!providers || providers.length === 0) {
+        let errorPromises = devices.map(device => APNS._createErrorPromise(device.deviceToken, 'No Provider found'));
+        allPromises = allPromises.concat(errorPromises);
+        continue;
+      }
+
+      let headers = { expirationTime: expirationTime, topic: appIdentifier, collapseId: collapseId, pushType: pushType, priority: priority }
+      let notification = APNS._generateNotification(coreData, headers);
+      const deviceIds = devices.map(device => device.deviceToken);
+      let promise = this.sendThroughProvider(notification, deviceIds, providers);
+      allPromises.push(promise.then(this._handlePromise.bind(this)));
+    }
+
+    return Promise.all(allPromises).then((results) => {
+      // flatten all
+      return [].concat.apply([], results);
+    });
+  }
+
+  sendThroughProvider(notification, devices, providers) {
+    return providers[0]
+        .send(notification, devices)
+        .then((response) => {
+          if (response.failed
+              && response.failed.length > 0
+              && providers && providers.length > 1) {
+            let devices = response.failed.map((failure) => { return failure.device; });
+            // Reset the failures as we'll try next connection
+            response.failed = [];
+            return this.sendThroughProvider(notification,
+                            devices,
+                            providers.slice(1, providers.length)).then((retryResponse) => {
+                              response.failed = response.failed.concat(retryResponse.failed);
+                              response.sent = response.sent.concat(retryResponse.sent);
+                              return response;
+                            });
+          } else {
+            return response;
+          }
+        });
+  }
+
+  static _validateAPNArgs(apnsArgs) {
+    if (apnsArgs.topic) {
+      return true;
+    }
+    return !(apnsArgs.cert || apnsArgs.key || apnsArgs.pfx);
+  }
+
+  /**
+   * Creates an Provider base on apnsArgs.
+   */
+  static _createProvider(apnsArgs) {
+    // if using certificate, then topic must be defined
+    if (!APNS._validateAPNArgs(apnsArgs)) {
+      throw new Parse.Error(Parse.Error.PUSH_MISCONFIGURED, 'topic is mssing for %j', apnsArgs);
+    }
+
+    let provider = new apn.Provider(apnsArgs);
+
+    // Sets the topic on this provider
+    provider.topic = apnsArgs.topic;
+
+    // Set the priority of the providers, prod cert has higher priority
+    if (apnsArgs.production) {
+      provider.priority = 0;
+    } else {
+      provider.priority = 1;
+    }
+
+    return provider;
+  }
+
+  /**
+   * Generate the apns Notification from the data we get from api request.
+   * @param {Object} coreData The data field under api request body
+   * @param {Object} headers The header properties for the notification (topic, expirationTime, collapseId, pushType, priority)
+   * @returns {Object} A apns Notification
+   */
+  static _generateNotification(coreData, headers) {
+    let notification = new apn.Notification();
+    let payload = {};
+    for (let key in coreData) {
+      switch (key) {
+        case 'aps':
+          notification.aps = coreData.aps;
+          break;
+        case 'alert':
+          notification.setAlert(coreData.alert);
+          break;
+        case 'title':
+          notification.setTitle(coreData.title);
+        break;
+        case 'badge':
+          notification.setBadge(coreData.badge);
+          break;
+        case 'sound':
+          notification.setSound(coreData.sound);
+          break;
+        case 'content-available':
+          let isAvailable = coreData['content-available'] === 1;
+          notification.setContentAvailable(isAvailable);
+          break;
+        case 'mutable-content':
+          let isMutable = coreData['mutable-content'] === 1;
+          notification.setMutableContent(isMutable);
+          break;
+        case 'targetContentIdentifier':
+          notification.setTargetContentIdentifier(coreData.targetContentIdentifier);
+          break;
+        case 'interruptionLevel':
+          notification.setInterruptionLevel(coreData.interruptionLevel);
+          break;
+        case 'category':
+          notification.setCategory(coreData.category);
+          break;
+        case 'threadId':
+          notification.setThreadId(coreData.threadId);
+          break;
+        default:
+          payload[key] = coreData[key];
+          break;
+      }
+    }
+
+    notification.payload = payload;
+
+    notification.topic = headers.topic;
+    notification.expiry = Math.round(headers.expirationTime / 1000);
+    notification.collapseId = headers.collapseId;
+    // set alert as default push type. If push type is not set notifications are not delivered to devices running iOS 13, watchOS 6 and later.
+    notification.pushType = 'alert';
+    if (headers.pushType) {
+      notification.pushType = headers.pushType;
+    }
+    if (headers.priority) {
+      // if headers priority is not set 'node-apn' defaults it to 5 which is min. required value for background pushes to launch the app in background.
+      notification.priority = headers.priority
+    }
+    return notification;
+  }
+
+  /**
+   * Choose appropriate providers based on device appIdentifier.
+   *
+   * @param {String} appIdentifier appIdentifier for required provider
+   * @returns {Array} Returns Array with appropriate providers
+   */
+  _chooseProviders(appIdentifier) {
+    // If the device we need to send to does not have appIdentifier, any provider could be a qualified provider
+    /*if (!appIdentifier || appIdentifier === '') {
+        return this.providers.map((provider) => provider.index);
+    }*/
+
+    // Otherwise we try to match the appIdentifier with topic on provider
+    let qualifiedProviders = this.providers.filter((provider) => appIdentifier === provider.topic);
+
+    if (qualifiedProviders.length > 0) {
+      return qualifiedProviders;
+    }
+
+    // If qualifiedProviders empty, add all providers without topic
+    return this.providers
+      .filter((provider) => !provider.topic || provider.topic === '');
+  }
+
+  _handlePromise(response) {
+    let promises = [];
+    response.sent.forEach((token) => {
+      log.verbose(LOG_PREFIX, 'APNS transmitted to %s', token.device);
+      promises.push(APNS._createSuccesfullPromise(token.device));
+    });
+    response.failed.forEach((failure) => {
+      promises.push(APNS._handlePushFailure(failure));
+    });
+    return Promise.all(promises);
+  }
+
+  static _handlePushFailure(failure) {
+    if (failure.error) {
+      log.error(LOG_PREFIX, 'APNS error transmitting to device %s with error %s', failure.device, failure.error);
+      return APNS._createErrorPromise(failure.device, failure.error);
+    } else if (failure.status && failure.response && failure.response.reason) {
+      log.error(LOG_PREFIX, 'APNS error transmitting to device %s with status %s and reason %s', failure.device, failure.status, failure.response.reason);
+      return APNS._createErrorPromise(failure.device, failure.response.reason);
+    } else {
+       log.error(LOG_PREFIX, 'APNS error transmitting to device with unkown error');
+       return APNS._createErrorPromise(failure.device, 'Unkown status');
+    }
+  }
+
+  /**
+   * Creates an errorPromise for return.
+   *
+   * @param {String} token Device-Token
+   * @param {String} errorMessage ErrrorMessage as string
+   */
+  static _createErrorPromise(token, errorMessage) {
+    return Promise.resolve({
+      transmitted: false,
+      device: {
+        deviceToken: token,
+        deviceType: 'ios'
+      },
+      response: { error: errorMessage }
+    });
+  }
+
+  /**
+   * Creates an successfulPromise for return.
+   *
+   * @param {String} token Device-Token
+   */
+  static _createSuccesfullPromise(token) {
+    return Promise.resolve({
+      transmitted: true,
+      device: {
+        deviceToken: token,
+        deviceType: 'ios'
+      }
+    });
+  }
+}
+
+export default APNS;