feat: Add the ability to manage channels and send broadcasts

README.md

@@ -21,6 +21,8 @@ A Node.js module for interfacing with the Apple Push Notification service.
     - [Connecting through an HTTP proxy](#connecting-through-an-http-proxy)
     - [Using a pool of http/2 connections](#using-a-pool-of-http2-connections)
   - [Sending a notification](#sending-a-notification)
+  - [Managing channels](#manage-channels)
+  - [Sending a broadcast notification](#sending-a-broadcast-notification)
 
 # Features
 
@@ -36,7 +38,7 @@ $ npm install @parse/node-apn --save
 
 # Quick Start
 
-This readme is a brief introduction, please refer to the full [documentation](doc/apn.markdown) in `doc/` for more details.
+This readme is a brief introduction; please refer to the full [documentation](doc/apn.markdown) in `doc/` for more details.
 
 If you have previously used v1.x and wish to learn more about what's changed in v2.0, please see [What's New](doc/whats-new.markdown)
 
@@ -59,15 +61,19 @@ var options = {
   production: false
 };
 
-var apnProvider = new apn.Provider(options);
+const apnProvider = new apn.Provider(options);
 ```
 
 By default, the provider will connect to the sandbox unless the environment variable `NODE_ENV=production` is set.
 
-For more information about configuration options consult the [provider documentation](doc/provider.markdown).
+For more information about configuration options, consult the [provider documentation](doc/provider.markdown).
 
 Help with preparing the key and certificate files for connection can be found in the [wiki][certificateWiki]
 
+⚠️ You should only create one `Provider` per-process for each certificate/key pair you have. You do not need to create a new `Provider` for each notification. If you are only sending notifications to one app, there is no need for more than one `Provider`.
+
+If you are constantly creating `Provider` instances in your app, make sure to call `Provider.shutdown()` when you are done with each provider to release its resources and memory.
+
 ### Connecting through an HTTP proxy
 
 If you need to connect through an HTTP proxy, you simply need to provide the `proxy: {host, port}` option when creating the provider. For example:
@@ -86,7 +92,7 @@ var options = {
   production: false
 };
 
-var apnProvider = new apn.Provider(options);
+const apnProvider = new apn.Provider(options);
 ```
 
 The provider will first send an HTTP CONNECT request to the specified proxy in order to establish an HTTP tunnel. Once established, it will create a new secure connection to the Apple Push Notification provider API through the tunnel.
@@ -111,11 +117,11 @@ var options = {
   production: false
 };
 
-var apnProvider = new apn.MultiProvider(options);
+const apnProvider = new apn.MultiProvider(options);
 ```
 
 ## Sending a notification
-To send a notification you will first need a device token from your app as a string
+To send a notification, you will first need a device token from your app as a string.
 
 ```javascript
 let deviceToken = "a9d0ed10e9cfd022a61cb08753f49c5a0b0dfb383697bf9f9d750a1003da19c7"
@@ -124,7 +130,7 @@ let deviceToken = "a9d0ed10e9cfd022a61cb08753f49c5a0b0dfb383697bf9f9d750a1003da1
 Create a notification object, configuring it with the relevant parameters (See the [notification documentation](doc/notification.markdown) for more details.)
 
 ```javascript
-var note = new apn.Notification();
+let note = new apn.Notification();
 
 note.expiry = Math.floor(Date.now() / 1000) + 3600; // Expires 1 hour from now.
 note.badge = 3;
@@ -137,29 +143,32 @@ note.topic = "<your-app-bundle-id>";
 Send the notification to the API with `send`, which returns a promise.
 
 ```javascript
-apnProvider.send(note, deviceToken).then( (result) => {
+try {
+  const result = apnProvider.send(note, deviceToken);
   // see documentation for an explanation of result
-});
+} catch(error) {
+  // Handle error...
+}
 ```
 
-This will result in the the following notification payload being sent to the device
+This will result in the following notification payload being sent to the device.
 
 ```json
 {"messageFrom":"John Appelseed","aps":{"badge":3,"sound":"ping.aiff","alert":"\uD83D\uDCE7 \u2709 You have a new message"}}
 ```
 
-Create a Live Activity notification object, configuring it with the relevant parameters (See the [notification documentation](doc/notification.markdown) for more details.)
+Create a Live Activity notification object and configure it with the relevant parameters (See the [notification documentation](doc/notification.markdown) for more details.)
 
 ```javascript
-var note = new apn.Notification();
+let note = new apn.Notification();
 
+note.topic = "<your-app-bundle-id>.push-type.liveactivity";
 note.expiry = Math.floor(Date.now() / 1000) + 3600; // Expires 1 hour from now.
+note.pushType = "liveactivity",
 note.badge = 3;
 note.sound = "ping.aiff";
 note.alert = "\uD83D\uDCE7 \u2709 You have a new message";
 note.payload = {'messageFrom': 'John Appleseed'};
-note.topic = "<your-app-bundle-id>";
-note.pushType = "liveactivity",
 note.relevanceScore = 75,
 note.timestamp = Math.floor(Date.now() / 1000); // Current time
 note.staleDate = Math.floor(Date.now() / 1000) + (8 * 3600); // Expires 8 hour from now.
@@ -170,18 +179,107 @@ note.contentState = {}
 Send the notification to the API with `send`, which returns a promise.
 
 ```javascript
-apnProvider.send(note, deviceToken).then( (result) => {
-  // see documentation for an explanation of result
-});
+try {
+  const result = await apnProvider.send(note, deviceToken);
+  // see the documentation for an explanation of the result
+} catch (error) {
+  // Handle error...
+}
 ```
 
-This will result in the the following notification payload being sent to the device
+This will result in the following notification payload being sent to the device.
 
 
 ```json
 {"messageFrom":"John Appleseed","aps":{"badge":3,"sound":"ping.aiff","alert":"\uD83D\uDCE7 \u2709 You have a new message", "relevance-score":75,"timestamp":1683129662,"stale-date":1683216062,"event":"update","content-state":{}}}
 ```
 
-You should only create one `Provider` per-process for each certificate/key pair you have. You do not need to create a new `Provider` for each notification. If you are only sending notifications to one app then there is no need for more than one `Provider`.
+## Manage Channels
+Starting in iOS 18 and iPadOS 18 Live Activities can be used to broadcast push notifications over channels. To do so, you will need your apps' `bundleId`. 
 
-If you are constantly creating `Provider` instances in your app, make sure to call `Provider.shutdown()` when you are done with each provider to release its resources and memory.
+```javascript
+let bundleId = "com.node.apn";
+```
+
+Create a notification object, configuring it with the relevant parameters (See the [notification documentation](doc/notification.markdown) for more details.)
+
+```javascript
+let note = new apn.Notification();
+
+note.requestId = "0309F412-AA57-46A8-9AC6-B5AECA8C4594"; // Optional
+note.payload = {'message-storage-policy': '1', 'push-type': 'liveactivity'}; // Required
+```
+
+Create a channel with `manageChannels` and the `create` action, which returns a promise.
+
+```javascript
+try {
+  const result = await apnProvider.manageChannels(note, bundleId, 'create');
+  // see the documentation for an explanation of the result
+} catch (error) {
+  // Handle error...
+}
+```
+
+If the channel is created successfully, the result will look like the following:
+```javascript
+{ 
+  apns-request-id: '0309F412-AA57-46A8-9AC6-B5AECA8C4594', 
+  apns-channel-id: 'dHN0LXNyY2gtY2hubA==' // The new channel
+}
+```
+
+Similarly, `manageChannels` has additional `action`s that allow you to `read`, `readAll`, and `delete` channels. The `read` and `delete` actions require similar information to the `create` example above, with the exception that they require `note.channelId` to be populated. To request all active channel id's, you can use the `readAll` action:
+
+```javascript
+try {
+  const result = await apnProvider.manageChannels(note, bundleId, 'readAll');
+  // see the documentation for an explanation of the result
+} catch (error) {
+  // Handle error...
+}
+```
+
+After the promise is fulfilled, `result` will look like the following:
+
+```javascript
+{ 
+  apns-request-id: 'some id value', 
+  channels: ['dHN0LXNyY2gtY2hubA==', 'eCN0LXNyY2gtY2hubA==' ...] // A list of active channels
+}
+```
+
+Further information about managing channels can be found in [Apple's documentation](https://developer.apple.com/documentation/usernotifications/sending-channel-management-requests-to-apns).
+
+## Sending A Broadcast Notification
+Starting in iOS 18 and iPadOS 18, after a channel is created using `manageChannels`, broadcast push notifications can be sent to any device subscribed to the respective `channelId` created for a `bundleId`. A broadcast notification looks similar to a standard Live Activity notification mentioned above but requires `note.channelId` to be populated. An example is below:
+
+```javascript
+let note = new apn.Notification();
+
+note.channelId = "dHN0LXNyY2gtY2hubA=="; // Required
+note.expiry = Math.floor(Date.now() / 1000) + 3600; // Expires 1 hour from now.
+note.pushType = "liveactivity",
+note.badge = 3;
+note.sound = "ping.aiff";
+note.alert = "\uD83D\uDCE7 \u2709 You have a new message";
+note.payload = {'messageFrom': 'John Appleseed'};
+note.relevanceScore = 75,
+note.timestamp = Math.floor(Date.now() / 1000); // Current time
+note.staleDate = Math.floor(Date.now() / 1000) + (8 * 3600); // Expires 8 hour from now.
+note.event = "update"
+note.contentState = {}
+```
+
+Send the broadcast notification to the API with `broadcast`, which returns a promise.
+
+```javascript
+try {
+  const result = await apnProvider.broadcast(note, bundleId);
+  // see documentation for an explanation of result
+} catch (error) {
+  // Handle error...
+}
+```
+
+Further information about broadcast notifications can be found in [Apple's documentation](https://developer.apple.com/documentation/usernotifications/sending-broadcast-push-notification-requests-to-apns).

doc/provider.markdown

@@ -65,7 +65,7 @@ When the returned `Promise` resolves, its value will be an Object containing two
 
 An array of device tokens to which the notification was successfully sent and accepted by Apple.
 
-Being `sent` does **not** guaranteed the notification will be _delivered_, other unpredictable factors - including whether the device is reachable - can ultimately prevent delivery.
+Being `sent` does **not** guarantee the notification will be _delivered_, other unpredictable factors - including whether the device is reachable - can ultimately prevent delivery.
 
 #### failed
 
@@ -103,7 +103,7 @@ If you wish to send notifications containing emoji or other multi-byte character
 
 Indicate to node-apn that it should close all open connections when the queue of pending notifications is fully drained. This will allow your application to terminate.
 
-**Note:** If notifications are pushed after the connection has started, an error will be thrown.
+**Note:** If notifications are pushed after the shutdown has started, an error will be thrown.
 
 [provider-api]: https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html
 [provider-auth-tokens]: https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html#//apple_ref/doc/uid/TP40008194-CH11-SW1