feat: Add the ability to manage channels and send broadcasts

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
 

index.d.ts

@@ -99,11 +99,34 @@ interface Aps {
   "mutable-content"?: undefined | 1
   "url-args"?: string[]
   category?: string
+  "thread-id"?: string
+  "interruption-level"?: string
+  "relevance-score"?: number
+  "filter-criteria"?: string
+  "stale-date"?: number
+  "content-state"?: Object
+  timestamp?: number
+  event?: string
+  "dismissal-date"?: number
+  "attributes-type"?: string
+  attributes?: Object
 }
 
 export interface ResponseSent {
   device: string;
 }
+
+export interface BroadcastResponse {
+  bundleId: string;
+  "apns-request-id"?: string;
+  "apns-channel-id"?: string;
+  "message-storage-policy"?: number;
+  "push-type"?: string;
+  "channels"?: string[];
+}
+
+export interface LoggerResponse extends Partial<ResponseSent>, Partial<BroadcastResponse> {}
+
 export interface ResponseFailure {
   device: string;
   error?: Error;
@@ -114,28 +137,56 @@ export interface ResponseFailure {
   };
 }
 
-export interface Responses {
-  sent:   ResponseSent[];
-  failed: ResponseFailure[];
+export interface BroadcastResponseFailure extends Omit<ResponseFailure, "device"> {
+  bundleId: string;
+}
+
+export interface LoggerResponseFailure extends Partial<ResponseFailure>, Partial<BroadcastResponseFailure> {}
+
+export interface Responses<R,F> {
+  sent: R[];
+  failed: F[];
 }
 
 export class Provider extends EventEmitter {
   constructor(options: ProviderOptions);
   /**
-   * This is main interface for sending notifications. Create a Notification object and pass it in, along with a single recipient or an array of them and node-apn will take care of the rest, delivering a copy of the notification to each recipient.
+   * This is main interface for sending notifications.
+   *  
+   * @remarks
+   * Create a Notification object and pass it in, along with a single recipient or an array of them and node-apn will take care of the rest, delivering a copy of the notification to each recipient.
+   *
+   * @param notification - The notification to send.
+   * @param recipients - A String or an Array of Strings containing the hex-encoded device token.
+   */
+  send(notification: Notification, recipients: string|string[]): Promise<Responses<ResponseSent,ResponseFailure>>;
+
+  /**
+   * Manage channels using a specific action.
+   *
+   * @param notifications - A Notification or an Array of Notifications to send. Each notification should specify the respective channelId it's directed to.
+   * @param bundleId - The bundleId for your application.
+   * @param action - Specifies the action to perform on the channel(s).
+   */
+  manageChannels(notifications: Notification|Notification[], bundleId: string, action: ChannelAction): Promise<Responses<BroadcastResponse,BroadcastResponseFailure>>;
+
+  /**
+   * Broadcast notificaitons to channel(s).
    *
-   * A "recipient" is a String containing the hex-encoded device token.
+   * @param notifications - A Notification or an Array of Notifications to send. Each notification should specify the respective channelId it's directed to.
+   * @param bundleId: The bundleId for your application.
    */
-  send(notification: Notification, recipients: string|string[]): Promise<Responses>;
+  broadcast(notifications: Notification|Notification[], bundleId: string): Promise<Responses<BroadcastResponse,BroadcastResponseFailure>>;
 
   /**
    * Set an info logger, and optionally an errorLogger to separately log errors.
    *
+   * @remarks
    * In order to log, these functions must have a property '.enabled' that is true.
    * (The default logger uses the npm 'debug' module which sets '.enabled'
    * based on the DEBUG environment variable)
    */
-  setLogger(logger: (msg: string) => void, errorLogger?: (msg: string) => void): Promise<Responses>;
+  setLogger(logger: (msg: string) => void, errorLogger?: (msg: string) => void): Promise<Responses<LoggerResponse,LoggerResponseFailure>>;
 
   /**
    * 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.
@@ -146,28 +197,35 @@ export class Provider extends EventEmitter {
 export class MultiProvider extends EventEmitter {
   constructor(options: MultiProviderOptions);
   /**
-   * This is main interface for sending notifications. Create a Notification object and pass it in, along with a single recipient or an array of them and node-apn will take care of the rest, delivering a copy of the notification to each recipient.
+   * This is main interface for sending notifications.
+   *  
+   * @remarks
+   * Create a Notification object and pass it in, along with a single recipient or an array of them and node-apn will take care of the rest, delivering a copy of the notification to each recipient.
    *
-   * A "recipient" is a String containing the hex-encoded device token.
+   * @param notification - The notification to send.
+   * @param recipients - A String or an Array of Strings containing the hex-encoded device token.
    */
-  send(notification: Notification, recipients: string|string[]): Promise<Responses>;
+  send(notification: Notification, recipients: string|string[]): Promise<Responses<ResponseSent,ResponseFailure>>;
 
   /**
    * Set an info logger, and optionally an errorLogger to separately log errors.
    *
+   * @remarks
    * In order to log, these functions must have a property '.enabled' that is true.
-   * (The default logger uses the npm 'debug' module which sets '.enabled' 
+   * (The default logger uses the npm 'debug' module which sets '.enabled'
    * based on the DEBUG environment variable)
    */
-  setLogger(logger: (msg: string) => void, errorLogger?: (msg: string) => void): Promise<Responses>;
+  setLogger(logger: (msg: string) => void, errorLogger?: (msg: string) => void): Promise<Responses<LoggerResponse,LoggerResponseFailure>>;
 
   /**
    * 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.
    */
   shutdown(callback?: () => void): void;
 }
 
-export type NotificationPushType = 'background' | 'alert' | 'voip' | 'pushtotalk' | 'liveactivity';
+export type NotificationPushType = 'background' | 'alert' | 'voip' | 'pushtotalk' | 'liveactivity' | 'location' | 'complication' | 'fileprovider' | 'mdm';
+
+export type ChannelAction = 'create' | 'read' | 'readAll' | 'delete';
 
 export interface NotificationAlertOptions {
   title?: string;
@@ -198,21 +256,22 @@ export class Notification {
    */
   public id: string;
   /**
-   * The UNIX timestamp representing when the notification should expire. This does not contribute to the 2048 byte payload size limit. An expiry of 0 indicates that the notification expires immediately.
+   * A UUID to identify this request.
    */
-  public expiry: number;
+  public requestId: string;
   /**
-   * Multiple notifications with same collapse identifier are displayed to the user as a single notification. The value should not exceed 64 bytes.
+   * A base64-encoded string that identifies the channel to publish the payload.
+     The channel ID is generated by sending channel creation request to APNs.
    */
-  public collapseId: string;
+  public channelId: string;
   /**
    * Multiple notifications with same collapse identifier are displayed to the user as a single notification. The value should not exceed 64 bytes.
    */
-  public requestId: string;
+  public collapseId: string;
   /**
-   * An optional custom request identifier that’s returned back in the response. The request identifier must be encoded as a UUID string.
+   * The UNIX timestamp representing when the notification should expire. This does not contribute to the 2048 byte payload size limit. An expiry of 0 indicates that the notification expires immediately.
    */
-  public channelId: string;
+  public expiry: number;
   /**
    * Provide one of the following values:
    *
@@ -225,7 +284,6 @@ export class Notification {
    * The type of the notification.
    */
   public pushType: NotificationPushType;
-
   /**
    * An app-specific identifier for grouping related notifications.
    */