@openfin/cloud-notification-core-api 0.0.1-alpha.856abf3 → 0.0.1-alpha.85addcf

package/bundle.d.ts

@@ -4,13 +4,38 @@ export declare class AuthorizationError extends CloudNotificationAPIError {
     constructor(message?: string, code?: string);
 }
 
+/**
+ * Represents common properties for all notification events
+ */
 export declare type BaseNotificationReceivedEvent = {
+    /**
+     * The action that was performed on the notification
+     */
     action: 'new' | 'update' | 'delete';
+    /**
+     * The unique identifier for the notification
+     */
     notificationId: string;
+    /**
+     * The correlation identifier for the notification
+     */
     correlationId?: string;
+    /**
+     * The identifier of the target of the notification
+     */
     target: string;
+    /**
+     * The name of the target i.e, the group or user that the notification was sent to
+     */
     targetName?: string;
+    /**
+     * The type of the target i.e, 'group' or 'user'
+     */
     targetType: string;
+    /**
+     * The payload of the notification.
+     * See the documentation for the notification center events for more information on the payload
+     */
     payload: unknown;
 };
 
@@ -20,11 +45,30 @@ export declare type BaseNotificationReceivedEvent = {
  */
 export declare class CloudNotificationAPI {
     #private;
-    deDuplicator: SetWithTTL<string>;
+    /**
+     * Constructs a new instance of the CloudNotificationAPI
+     *
+     * @param cloudNotificationSettings - The settings for the Cloud Notification API.
+     */
     constructor(cloudNotificationSettings: CloudNotificationSettings);
     /**
      * Connects and creates a session on the Cloud Notifications service.
      *
+     * @example
+     * ```typescript
+     * const notificationApi = new CloudNotificationAPI({
+     *     url: process.env.NOTIFICATION_SERVER_HOST
+     * });
+     *
+     * let connectionResult: ConnectionResult;
+     * try {
+     *     connectionResult = await notificationApi.connect(connectSettings);
+     * } catch (errorConnect) {
+     *     terminal.write(chalk.red(`\nError connecting to notification server: ${errorConnect}\n`));
+     *     process.exit(1);
+     * }
+     * ```
+     *
      * @param parameters - The parameters to use to connect.
      * @returns A promise that resolves when the connection is established.
      * @throws {@link CloudNotificationAPIError} If an error occurs during connection.
@@ -56,7 +100,7 @@ export declare class CloudNotificationAPI {
                 * Raises a notification to the Cloud Notification service.
                 *
                 * @param options - The options for the notification.
-                * @param payload - The payload of the notification.
+                * @param payload - The payload of the notification which should generally conform to the notification center schema
                 * @returns A promise that resolves with the notification raise result.
                 * @throws {@link SessionNotConnectedError} If the session is not connected.
                     * @throws {@link PublishError} If an error occurs during publishing.
@@ -67,7 +111,7 @@ export declare class CloudNotificationAPI {
                      *
                      * @param notificationId - The ID of the notification to update.
                      * @param options - The options for the notification update.
-                     * @param payload - The new payload of the notification.
+                     * @param payload - The new payload of the notification which should generally conform to the notification center update schema
                      * @throws {@link SessionNotConnectedError} If the session is not connected.
                          * @throws {@link PublishError} If an error occurs during publishing of the update.
                              */
@@ -75,6 +119,8 @@ export declare class CloudNotificationAPI {
                          /**
                           * Marks a notification as deleted in the Cloud Notification service.
                           *
+                          * This in turn causes notification events to be raised for the notification
+                          *
                           * @param notificationId - The ID of the notification to delete.
                           * @returns A promise that resolves when the notification is deleted.
                           * @throws {@link SessionNotConnectedError} If the session is not connected.
@@ -83,8 +129,10 @@ export declare class CloudNotificationAPI {
                           /**
                            * Replays notifications from the Cloud Notification service.
                            *
+                           * This is called at platform startup to populate the notification center with notifications that were missed since the last time the platform was started.
+                           *
                            * @param pageItemLimit - The maximum number of items per page.
-                           * @param pageStartCursor - The cursor to start the page from.
+                           * @param pageStartCursor - The cursor to start the page from.  This is retrieved from the pageInfo property.
                            * @returns A promise that resolves with the notifications replay details.
                            * @throws {@link SessionNotConnectedError} If the session is not connected.
                                * @throws {@link NotificationRetrievalError} If an error occurs during retrieval.
@@ -126,6 +174,8 @@ export declare class CloudNotificationAPI {
                            export declare type CloudNotificationSettings = {
                                /**
                                 * The URL of the notification server to connect to
+                                *
+                                * @example 'https://the-environment.example.com/notifications'
                                 */
                                url: string;
                                /**
@@ -141,7 +191,7 @@ export declare class CloudNotificationAPI {
                                /**
                                 * Optional function to call with any logging messages to allow integration with the host application's logging
                                 *
-                                * defaults to console.log
+                                * Defaults to console.log
                                 */
                                logger?: CloudNotificationLogger;
                                /**
@@ -156,7 +206,7 @@ export declare class CloudNotificationAPI {
                            };
 
                            /**
-                            * Repesents the result of a successful connection to the server
+                            * Represents the result of a successful connection to the server
                             */
                            export declare type ConnectionResult = {
                                /**
@@ -190,7 +240,10 @@ export declare class CloudNotificationAPI {
                            export declare type ConnectParameters = {
                                /**
                                 * ID for a group of shared applications.
+                                *
                                 * This acts as a namespace for the notification messages that allows separation of messages between different groups of applications for the same user
+                                *
+                                * This, in general, should be the uuid of the platform that you are communicating
                                 */
                                platformId: string;
                                /**
@@ -199,11 +252,10 @@ export declare class CloudNotificationAPI {
                                sourceId: string;
                                /**
                                 * Determines the type of authentication to use with the service gateway
-                                * defaults to 'none'
                                 *
-                                * 'jwt' - Use JWT authentication, in this case jwtAuthenticationParameters must also be provided
-                                * 'basic' - Use basic authentication, in this case basicAuthenticationParameters must also be provided
-                                * 'default' - Authentication will be inherited from the current session
+                                * - 'jwt' - Use JWT authentication, in this case jwtAuthenticationParameters must also be provided
+                                * - 'basic' - Use basic authentication, in this case basicAuthenticationParameters must also be provided
+                                * - 'default' - Authentication will be inherited from the current session
                                 */
                                authenticationType?: 'jwt' | 'basic' | 'default';
                                /**
@@ -225,6 +277,15 @@ export declare class CloudNotificationAPI {
                                jwtAuthenticationParameters?: {
                                    /**
                                     * When JWT authentication is being used, this will be invoked just whenever a JWT token is required for a request
+                                    *
+                                    * This token should be conform to the configuration set within your environment.  Contact Here support for more details
+                                    *
+                                    * @example
+                                    * ```typescript
+                                    * const jwtRequestCallback = () => {
+                                    *     return 'your-jwt-token';
+                                    * };
+                                    * ```
                                     */
                                    jwtRequestCallback: () => string | object;
                                    /**
@@ -240,19 +301,62 @@ export declare class CloudNotificationAPI {
                                action: 'delete';
                            };
 
-                           export declare type EventListenersMap = Map<keyof EventMap, Array<(...args: Parameters<EventMap[keyof EventMap]>) => void>>;
-
                            export declare type EventMap = {
+                               /**
+                                * Emitted when the connection has been re-established
+                                * @returns void
+                                */
                                reconnected: () => void;
-                               disconnected: () => void;
+                               /**
+                                * Emitted when the connection has been disconnected
+                                * @returns void
+                                */
                                reconnecting: (attemptNo: number) => void;
+                               /**
+                                * Emitted when the connection has been disconnected
+                                * @returns void
+                                */
+                               disconnected: () => void;
+                               /**
+                                * Emitted when an error occurs
+                                * @returns void
+                                */
                                error: (error: Error) => void;
+                               /**
+                                * Emitted when the session has expired
+                                * @returns void
+                                */
                                'session-expired': () => void;
+                               /**
+                                * Emitted when the session has been extended
+                                * @returns void
+                                */
                                'session-extended': () => void;
+                               /**
+                                * Emitted when a new notification is received
+                                * @returns void
+                                */
                                'new-notification': (event: NewNotificationEvent) => void;
+                               /**
+                                * Emitted when an update to a notification is received
+                                * @returns void
+                                */
                                'update-notification': (event: UpdateNotificationEvent) => void;
+                               /**
+                                * Emitted when a notification is deleted
+                                * @returns void
+                                */
                                'delete-notification': (event: DeleteNotificationEvent) => void;
+                               /**
+                                * Emitted when a notification event is received for this specific session
+                                * @returns void
+                                */
                                'notification-event': (event: NotificationEvent) => void;
+                               /**
+                                * Emitted when a notification event is received for all sessions
+                                * @returns void
+                                */
+                               'global-notification-event': (event: NotificationEvent) => void;
                            };
 
                            export declare class EventPublishError extends CloudNotificationAPIError {
@@ -273,11 +377,32 @@ export declare class CloudNotificationAPI {
                                action: 'new';
                            };
 
+                           /**
+                            * Represents a notification event
+                            */
                            export declare type NotificationEvent = {
+                               /**
+                                * The unique identifier for the notification
+                                */
                                notificationId: string;
+                               /**
+                                * The correlation identifier for the notification
+                                */
                                correlationId?: string;
+                               /**
+                                * The category of the notification.
+                                * For notification center events this will be 'notification-center-event'
+                                */
                                category: string;
+                               /**
+                                * The type of the notification.
+                                * For example 'notification-close' when a user closes a notification in the notification center
+                                */
                                type: string;
+                               /**
+                                * The payload of the notification.
+                                * See the documentation for the notification center events for more information on the payload
+                                */
                                payload?: unknown;
                            };
 
@@ -287,16 +412,29 @@ export declare class CloudNotificationAPI {
                            declare type NotificationOptions_2 = {
                                /**
                                 * A caller specified identifier for the notification
+                                *
                                 * This is used to identify the notification in the system when events and responses are received
                                 */
                                correlationId?: string;
                                /**
                                 * The targets to send the notification to
+                                *
                                 * This is a set of groups and users that the notification will be sent to
+                                *
+                                * @example
+                                * ```typescript
+                                * const notificationOptions: NotificationOptions = {
+                                *     targets: {
+                                *         groups: ['all-users'],
+                                *         users: ['someuser@company.com']
+                                *     }
+                                * };
+                                * ```
                                 */
                                targets: NotificationTargets;
                                /**
                                 * Optional number of seconds to keep the notification alive
+                                *
                                 * After this time the notification will be expired and a delete update will be raised
                                 */
                                ttlSeconds?: number;
@@ -321,22 +459,67 @@ export declare class CloudNotificationAPI {
                                constructor(message?: string, code?: string, cause?: unknown);
                            }
 
+                           /**
+                            * Represents a single notification replay detail.
+                            */
                            export declare type NotificationsReplayDetail = {
+                               /**
+                                * The cursor of the notification.
+                                */
                                cursor: string;
+                               /**
+                                * The session ID of the notification.
+                                */
                                sessionId: string;
+                               /**
+                                * The notification ID.
+                                */
                                notificationId: string;
+                               /**
+                                * The version of the notification.
+                                */
                                version: number;
+                               /**
+                                * The type of notification record.
+                                */
                                action: 'new' | 'update' | 'delete';
+                               /**
+                                * The payload of the notification.
+                                */
                                payload?: unknown;
+                               /**
+                                * The original correlation ID of the notification if specified.
+                                */
                                correlationId?: string | null;
+                               /**
+                                * The timestamp of the notification.
+                                */
                                timestamp: Date;
                            };
 
+                           /**
+                            * Represents the results of a notifications replay request.
+                            */
                            export declare type NotificationsReplayDetails = {
+                               /**
+                                * The list of notifications replay details.
+                                */
                                data: NotificationsReplayDetail[];
+                               /**
+                                * The pagination information for the notifications replay request.
+                                */
                                pageInfo: {
+                                   /**
+                                    * The cursor of the first notification in the page.
+                                    */
                                    pageStart?: string;
+                                   /**
+                                    * The cursor of the next page.
+                                    */
                                    nextPage?: string;
+                                   /**
+                                    * Whether there is a next page of notifications.
+                                    */
                                    hasNextPage: boolean;
                                };
                            };
@@ -346,11 +529,16 @@ export declare class CloudNotificationAPI {
                             */
                            export declare type NotificationTargets = {
                                /**
-                                * The groups to send the notification to
+                                * The optional groups to send the notification to
+                                *
+                                * This can be a collection of either group names e.g. all-users which can be retrieved from the admin console or the
+                                * UUID of the group itself
                                 */
                                groups: string[];
                                /**
-                                * The users to send the notification to
+                                * The optional specific users to send the notification to
+                                *
+                                * This can be the username e.g. someuser\@company.com or the UUID of the user itself
                                 */
                                users: string[];
                            };
@@ -370,40 +558,12 @@ export declare class CloudNotificationAPI {
                                constructor(message?: string, code?: string, cause?: unknown);
                            }
 
-                           export declare type PublishResult = {
-                               notificationId: string;
-                               correlationId: string | undefined;
-                           };
-
                            export declare class SessionNotConnectedError extends CloudNotificationAPIError {
                                constructor(message?: string, code?: string);
                            }
 
-                           /**
-                            * Simple set-like structure that allows you to add values with a TTL (time to live).
-                            * Values are automatically removed from the set after the TTL expires.
-                            */
-                           declare class SetWithTTL<T> {
-                               #private;
-                               private ttl;
-                               private store;
-                               private nextCollection;
-                               private collectionDelay;
-                               constructor(ttl: number, collectionCheckInterval?: number);
-                               get size(): number;
-                               add(value: T, customTtl?: number): this;
-                               has(value: T): boolean;
-                               delete(value: T): this;
-                           }
-
                            export declare type UpdateNotificationEvent = BaseNotificationReceivedEvent & {
                                action: 'update';
                            };
 
-                           export declare type UserGroupWithTopic = {
-                               uuid: string;
-                               name: string;
-                               topic?: string;
-                           };
-
                            export { }

package/index.cjs

@@ -108,13 +108,14 @@ function handleAPIException(logger, error, message, exceptionConstructor) {
     }
     throw new exceptionConstructor(undefined, undefined, error);
 }
-function checkResponse(logger, response, failMessage, failCode) {
+async function checkResponse(logger, response, failMessage, failCode) {
     if (!response.ok) {
         if (response.status === 401 || response.status === 403) {
             throw new AuthorizationError();
         }
-        logger('error', `Response check failure ${failMessage} - ${response.status}: ${response.statusText}`);
-        throw new CloudNotificationAPIError(`${failMessage} (HTTP ${response.status}: ${response.statusText})`, failCode);
+        const responseBody = await response.text();
+        logger('error', `Response check failure ${failMessage} - ${response.status}: ${response.statusText} : ${responseBody}`);
+        throw new CloudNotificationAPIError(`${failMessage} (HTTP ${response.status}: ${response.statusText})`, failCode, responseBody);
     }
 }
 function getRequestHeaders(connectionParameters) {
@@ -284,7 +285,7 @@ class CloudNotificationAPI {
     #keepAliveIntervalSeconds = 30;
     #syncTime = true;
     #timeDifferenceTracker;
-    deDuplicator;
+    #deDuplicator;
     #reconnectRetries = 0;
     #connectionParams;
     #attemptingToReconnect = false;
@@ -292,9 +293,14 @@ class CloudNotificationAPI {
     #defaultSubscriptionOptions = { qos: 2, nl: true };
     #logger = (level, message) => console[level](message);
     #getCurrentTimeOffset = () => this.#timeDifferenceTracker?.currentOffset || 0;
+    /**
+     * Constructs a new instance of the CloudNotificationAPI
+     *
+     * @param cloudNotificationSettings - The settings for the Cloud Notification API.
+     */
     constructor(cloudNotificationSettings) {
         this.#cloudNotificationSettings = cloudNotificationSettings;
-        this.deDuplicator = new SetWithTTL(cloudNotificationSettings?.deduplicationTTLms || 10_000);
+        this.#deDuplicator = new SetWithTTL(cloudNotificationSettings?.deduplicationTTLms || 10_000);
         this.#reconnectRetryLimit = cloudNotificationSettings.reconnectRetryLimit || this.#reconnectRetryLimit;
         this.#keepAliveIntervalSeconds = cloudNotificationSettings.keepAliveIntervalSeconds || this.#keepAliveIntervalSeconds;
         this.#logger = cloudNotificationSettings.logger || this.#logger;
@@ -303,6 +309,21 @@ class CloudNotificationAPI {
     /**
      * Connects and creates a session on the Cloud Notifications service.
      *
+     * @example
+     * ```typescript
+     * const notificationApi = new CloudNotificationAPI({
+     *     url: process.env.NOTIFICATION_SERVER_HOST
+     * });
+     *
+     * let connectionResult: ConnectionResult;
+     * try {
+     *     connectionResult = await notificationApi.connect(connectSettings);
+     * } catch (errorConnect) {
+     *     terminal.write(chalk.red(`\nError connecting to notification server: ${errorConnect}\n`));
+     *     process.exit(1);
+     * }
+     * ```
+     *
      * @param parameters - The parameters to use to connect.
      * @returns A promise that resolves when the connection is established.
      * @throws {@link CloudNotificationAPIError} If an error occurs during connection.
@@ -330,7 +351,7 @@ class CloudNotificationAPI {
                 isFullApi: true,
             }),
         });
-        checkResponse(this.#logger, createSessionResponse, 'Error creating session', 'ERR_CREATE_SESSION');
+        await checkResponse(this.#logger, createSessionResponse, 'Error creating session', 'ERR_CREATE_SESSION');
         if (createSessionResponse.status !== 201) {
             throw new CloudNotificationAPIError(`Failed to connect to the Cloud Notification service: ${this.#cloudNotificationSettings.url}`, 'ERR_CONNECT', new Error(createSessionResponse.statusText));
         }
@@ -374,7 +395,7 @@ class CloudNotificationAPI {
                 headers: getRequestHeaders(this.#connectionParams),
                 body: JSON.stringify(publishPayload),
             });
-            checkResponse(this.#logger, publishResponse, 'Error posting notification event', 'ERR_POST_NOTIFICATION_EVENT');
+            await checkResponse(this.#logger, publishResponse, 'Error posting notification event', 'ERR_POST_NOTIFICATION_EVENT');
         }
         catch (error) {
             handleAPIException(this.#logger, error, 'Error posting notification event', PublishError);
@@ -384,7 +405,7 @@ class CloudNotificationAPI {
      * Raises a notification to the Cloud Notification service.
      *
      * @param options - The options for the notification.
-     * @param payload - The payload of the notification.
+     * @param payload - The payload of the notification which should generally conform to the notification center schema
      * @returns A promise that resolves with the notification raise result.
      * @throws {@link SessionNotConnectedError} If the session is not connected.
      * @throws {@link PublishError} If an error occurs during publishing.
@@ -410,7 +431,7 @@ class CloudNotificationAPI {
                 headers: getRequestHeaders(this.#connectionParams),
                 body: JSON.stringify(publishPayload),
             });
-            checkResponse(this.#logger, publishResponse, 'Error publishing notification', 'ERR_PUBLISH_NOTIFICATION');
+            await checkResponse(this.#logger, publishResponse, 'Error publishing notification', 'ERR_PUBLISH_NOTIFICATION');
             const publishResponseBody = (await publishResponse.json());
             return publishResponseBody;
         }
@@ -423,7 +444,7 @@ class CloudNotificationAPI {
      *
      * @param notificationId - The ID of the notification to update.
      * @param options - The options for the notification update.
-     * @param payload - The new payload of the notification.
+     * @param payload - The new payload of the notification which should generally conform to the notification center update schema
      * @throws {@link SessionNotConnectedError} If the session is not connected.
      * @throws {@link PublishError} If an error occurs during publishing of the update.
      */
@@ -444,7 +465,7 @@ class CloudNotificationAPI {
                 headers: getRequestHeaders(this.#connectionParams),
                 body: JSON.stringify(updatePayload),
             });
-            checkResponse(this.#logger, updateResponse, 'Error updating notification', 'ERR_UPDATING_NOTIFICATION');
+            await checkResponse(this.#logger, updateResponse, 'Error updating notification', 'ERR_UPDATING_NOTIFICATION');
         }
         catch (error) {
             handleAPIException(this.#logger, error, 'Error updating notification', PublishError);
@@ -453,6 +474,8 @@ class CloudNotificationAPI {
     /**
      * Marks a notification as deleted in the Cloud Notification service.
      *
+     * This in turn causes notification events to be raised for the notification
+     *
      * @param notificationId - The ID of the notification to delete.
      * @returns A promise that resolves when the notification is deleted.
      * @throws {@link SessionNotConnectedError} If the session is not connected.
@@ -467,7 +490,7 @@ class CloudNotificationAPI {
                 method: 'DELETE',
                 headers: getRequestHeaders(this.#connectionParams),
             });
-            checkResponse(this.#logger, deleteResponse, 'Error deleting notification', 'ERR_DELETE_NOTIFICATION');
+            await checkResponse(this.#logger, deleteResponse, 'Error deleting notification', 'ERR_DELETE_NOTIFICATION');
         }
         catch (error) {
             handleAPIException(this.#logger, error, 'Error deleting notification', PublishError);
@@ -476,8 +499,10 @@ class CloudNotificationAPI {
     /**
      * Replays notifications from the Cloud Notification service.
      *
+     * This is called at platform startup to populate the notification center with notifications that were missed since the last time the platform was started.
+     *
      * @param pageItemLimit - The maximum number of items per page.
-     * @param pageStartCursor - The cursor to start the page from.
+     * @param pageStartCursor - The cursor to start the page from.  This is retrieved from the pageInfo property.
      * @returns A promise that resolves with the notifications replay details.
      * @throws {@link SessionNotConnectedError} If the session is not connected.
      * @throws {@link NotificationRetrievalError} If an error occurs during retrieval.
@@ -506,7 +531,7 @@ class CloudNotificationAPI {
                     sessionId: this.#sessionDetails.sessionId,
                 }),
             });
-            checkResponse(this.#logger, replayResponse, 'Error replaying notifications', 'ERR_REPLAY_NOTIFICATIONS');
+            await checkResponse(this.#logger, replayResponse, 'Error replaying notifications', 'ERR_REPLAY_NOTIFICATIONS');
             const body = (await replayResponse.json());
             return body;
         }
@@ -648,6 +673,10 @@ class CloudNotificationAPI {
         this.#mqttClient?.subscribeAsync(this.#sessionDetails.mqtt.userNotificationTopic, this.#defaultSubscriptionOptions), 
         // The users notifications status updates
         this.#mqttClient?.subscribeAsync(this.#sessionDetails.mqtt.userNotificationEventsTopic, this.#defaultSubscriptionOptions));
+        // Global notification events
+        if (this.#sessionDetails.mqtt.allNotificationEventsTopic) {
+            subscribePromises.push(this.#mqttClient?.subscribeAsync(this.#sessionDetails.mqtt.allNotificationEventsTopic, this.#defaultSubscriptionOptions));
+        }
         await Promise.all(subscribePromises);
     }
     async #extendSession() {
@@ -731,6 +760,9 @@ class CloudNotificationAPI {
             else if (topic === sessionDetails.mqtt.userNotificationEventsTopic) {
                 this.#handleUserNotificationEventMessage(messagePayload);
             }
+            else if (topic === sessionDetails.mqtt.allNotificationEventsTopic) {
+                this.#handleAllNotificationEventMessage(messagePayload);
+            }
             else {
                 this.#logger('warn', `Received message on unknown topic ${topic}`);
                 this.#events.emitEvent('error', new CloudNotificationAPIError(`Received message on unknown topic ${topic}`, 'ERR_UNKNOWN_TOPIC'));
@@ -753,10 +785,10 @@ class CloudNotificationAPI {
             return;
         }
         // We might have received this update from a different group or user topic so de-dupe
-        if (this.deDuplicator.has(txInstanceId)) {
+        if (this.#deDuplicator.has(txInstanceId)) {
             return;
         }
-        this.deDuplicator.add(txInstanceId);
+        this.#deDuplicator.add(txInstanceId);
         this.#sendNotificationDeliveredStatus(notificationId);
         let targetName = target;
         if (targetType === 'group') {
@@ -786,6 +818,14 @@ class CloudNotificationAPI {
         }
         this.#events.emitEvent('notification-event', parseResult.data);
     }
+    #handleAllNotificationEventMessage(messagePayload) {
+        const parseResult = f.safeParse(messagePayload);
+        if (!parseResult.success) {
+            this.#logger('warn', `Received invalid notification event message payload format ${parseResult.error?.toString()}`);
+            throw new InvalidMessageFormatError(parseResult);
+        }
+        this.#events.emitEvent('global-notification-event', parseResult.data);
+    }
     #lookupGroupNameByUuid(uuid) {
         if (!this.#sessionDetails) {
             return undefined;

package/index.mjs

@@ -106,13 +106,14 @@ function handleAPIException(logger, error, message, exceptionConstructor) {
     }
     throw new exceptionConstructor(undefined, undefined, error);
 }
-function checkResponse(logger, response, failMessage, failCode) {
+async function checkResponse(logger, response, failMessage, failCode) {
     if (!response.ok) {
         if (response.status === 401 || response.status === 403) {
             throw new AuthorizationError();
         }
-        logger('error', `Response check failure ${failMessage} - ${response.status}: ${response.statusText}`);
-        throw new CloudNotificationAPIError(`${failMessage} (HTTP ${response.status}: ${response.statusText})`, failCode);
+        const responseBody = await response.text();
+        logger('error', `Response check failure ${failMessage} - ${response.status}: ${response.statusText} : ${responseBody}`);
+        throw new CloudNotificationAPIError(`${failMessage} (HTTP ${response.status}: ${response.statusText})`, failCode, responseBody);
     }
 }
 function getRequestHeaders(connectionParameters) {
@@ -282,7 +283,7 @@ class CloudNotificationAPI {
     #keepAliveIntervalSeconds = 30;
     #syncTime = true;
     #timeDifferenceTracker;
-    deDuplicator;
+    #deDuplicator;
     #reconnectRetries = 0;
     #connectionParams;
     #attemptingToReconnect = false;
@@ -290,9 +291,14 @@ class CloudNotificationAPI {
     #defaultSubscriptionOptions = { qos: 2, nl: true };
     #logger = (level, message) => console[level](message);
     #getCurrentTimeOffset = () => this.#timeDifferenceTracker?.currentOffset || 0;
+    /**
+     * Constructs a new instance of the CloudNotificationAPI
+     *
+     * @param cloudNotificationSettings - The settings for the Cloud Notification API.
+     */
     constructor(cloudNotificationSettings) {
         this.#cloudNotificationSettings = cloudNotificationSettings;
-        this.deDuplicator = new SetWithTTL(cloudNotificationSettings?.deduplicationTTLms || 10_000);
+        this.#deDuplicator = new SetWithTTL(cloudNotificationSettings?.deduplicationTTLms || 10_000);
         this.#reconnectRetryLimit = cloudNotificationSettings.reconnectRetryLimit || this.#reconnectRetryLimit;
         this.#keepAliveIntervalSeconds = cloudNotificationSettings.keepAliveIntervalSeconds || this.#keepAliveIntervalSeconds;
         this.#logger = cloudNotificationSettings.logger || this.#logger;
@@ -301,6 +307,21 @@ class CloudNotificationAPI {
     /**
      * Connects and creates a session on the Cloud Notifications service.
      *
+     * @example
+     * ```typescript
+     * const notificationApi = new CloudNotificationAPI({
+     *     url: process.env.NOTIFICATION_SERVER_HOST
+     * });
+     *
+     * let connectionResult: ConnectionResult;
+     * try {
+     *     connectionResult = await notificationApi.connect(connectSettings);
+     * } catch (errorConnect) {
+     *     terminal.write(chalk.red(`\nError connecting to notification server: ${errorConnect}\n`));
+     *     process.exit(1);
+     * }
+     * ```
+     *
      * @param parameters - The parameters to use to connect.
      * @returns A promise that resolves when the connection is established.
      * @throws {@link CloudNotificationAPIError} If an error occurs during connection.
@@ -328,7 +349,7 @@ class CloudNotificationAPI {
                 isFullApi: true,
             }),
         });
-        checkResponse(this.#logger, createSessionResponse, 'Error creating session', 'ERR_CREATE_SESSION');
+        await checkResponse(this.#logger, createSessionResponse, 'Error creating session', 'ERR_CREATE_SESSION');
         if (createSessionResponse.status !== 201) {
             throw new CloudNotificationAPIError(`Failed to connect to the Cloud Notification service: ${this.#cloudNotificationSettings.url}`, 'ERR_CONNECT', new Error(createSessionResponse.statusText));
         }
@@ -372,7 +393,7 @@ class CloudNotificationAPI {
                 headers: getRequestHeaders(this.#connectionParams),
                 body: JSON.stringify(publishPayload),
             });
-            checkResponse(this.#logger, publishResponse, 'Error posting notification event', 'ERR_POST_NOTIFICATION_EVENT');
+            await checkResponse(this.#logger, publishResponse, 'Error posting notification event', 'ERR_POST_NOTIFICATION_EVENT');
         }
         catch (error) {
             handleAPIException(this.#logger, error, 'Error posting notification event', PublishError);
@@ -382,7 +403,7 @@ class CloudNotificationAPI {
      * Raises a notification to the Cloud Notification service.
      *
      * @param options - The options for the notification.
-     * @param payload - The payload of the notification.
+     * @param payload - The payload of the notification which should generally conform to the notification center schema
      * @returns A promise that resolves with the notification raise result.
      * @throws {@link SessionNotConnectedError} If the session is not connected.
      * @throws {@link PublishError} If an error occurs during publishing.
@@ -408,7 +429,7 @@ class CloudNotificationAPI {
                 headers: getRequestHeaders(this.#connectionParams),
                 body: JSON.stringify(publishPayload),
             });
-            checkResponse(this.#logger, publishResponse, 'Error publishing notification', 'ERR_PUBLISH_NOTIFICATION');
+            await checkResponse(this.#logger, publishResponse, 'Error publishing notification', 'ERR_PUBLISH_NOTIFICATION');
             const publishResponseBody = (await publishResponse.json());
             return publishResponseBody;
         }
@@ -421,7 +442,7 @@ class CloudNotificationAPI {
      *
      * @param notificationId - The ID of the notification to update.
      * @param options - The options for the notification update.
-     * @param payload - The new payload of the notification.
+     * @param payload - The new payload of the notification which should generally conform to the notification center update schema
      * @throws {@link SessionNotConnectedError} If the session is not connected.
      * @throws {@link PublishError} If an error occurs during publishing of the update.
      */
@@ -442,7 +463,7 @@ class CloudNotificationAPI {
                 headers: getRequestHeaders(this.#connectionParams),
                 body: JSON.stringify(updatePayload),
             });
-            checkResponse(this.#logger, updateResponse, 'Error updating notification', 'ERR_UPDATING_NOTIFICATION');
+            await checkResponse(this.#logger, updateResponse, 'Error updating notification', 'ERR_UPDATING_NOTIFICATION');
         }
         catch (error) {
             handleAPIException(this.#logger, error, 'Error updating notification', PublishError);
@@ -451,6 +472,8 @@ class CloudNotificationAPI {
     /**
      * Marks a notification as deleted in the Cloud Notification service.
      *
+     * This in turn causes notification events to be raised for the notification
+     *
      * @param notificationId - The ID of the notification to delete.
      * @returns A promise that resolves when the notification is deleted.
      * @throws {@link SessionNotConnectedError} If the session is not connected.
@@ -465,7 +488,7 @@ class CloudNotificationAPI {
                 method: 'DELETE',
                 headers: getRequestHeaders(this.#connectionParams),
             });
-            checkResponse(this.#logger, deleteResponse, 'Error deleting notification', 'ERR_DELETE_NOTIFICATION');
+            await checkResponse(this.#logger, deleteResponse, 'Error deleting notification', 'ERR_DELETE_NOTIFICATION');
         }
         catch (error) {
             handleAPIException(this.#logger, error, 'Error deleting notification', PublishError);
@@ -474,8 +497,10 @@ class CloudNotificationAPI {
     /**
      * Replays notifications from the Cloud Notification service.
      *
+     * This is called at platform startup to populate the notification center with notifications that were missed since the last time the platform was started.
+     *
      * @param pageItemLimit - The maximum number of items per page.
-     * @param pageStartCursor - The cursor to start the page from.
+     * @param pageStartCursor - The cursor to start the page from.  This is retrieved from the pageInfo property.
      * @returns A promise that resolves with the notifications replay details.
      * @throws {@link SessionNotConnectedError} If the session is not connected.
      * @throws {@link NotificationRetrievalError} If an error occurs during retrieval.
@@ -504,7 +529,7 @@ class CloudNotificationAPI {
                     sessionId: this.#sessionDetails.sessionId,
                 }),
             });
-            checkResponse(this.#logger, replayResponse, 'Error replaying notifications', 'ERR_REPLAY_NOTIFICATIONS');
+            await checkResponse(this.#logger, replayResponse, 'Error replaying notifications', 'ERR_REPLAY_NOTIFICATIONS');
             const body = (await replayResponse.json());
             return body;
         }
@@ -646,6 +671,10 @@ class CloudNotificationAPI {
         this.#mqttClient?.subscribeAsync(this.#sessionDetails.mqtt.userNotificationTopic, this.#defaultSubscriptionOptions), 
         // The users notifications status updates
         this.#mqttClient?.subscribeAsync(this.#sessionDetails.mqtt.userNotificationEventsTopic, this.#defaultSubscriptionOptions));
+        // Global notification events
+        if (this.#sessionDetails.mqtt.allNotificationEventsTopic) {
+            subscribePromises.push(this.#mqttClient?.subscribeAsync(this.#sessionDetails.mqtt.allNotificationEventsTopic, this.#defaultSubscriptionOptions));
+        }
         await Promise.all(subscribePromises);
     }
     async #extendSession() {
@@ -729,6 +758,9 @@ class CloudNotificationAPI {
             else if (topic === sessionDetails.mqtt.userNotificationEventsTopic) {
                 this.#handleUserNotificationEventMessage(messagePayload);
             }
+            else if (topic === sessionDetails.mqtt.allNotificationEventsTopic) {
+                this.#handleAllNotificationEventMessage(messagePayload);
+            }
             else {
                 this.#logger('warn', `Received message on unknown topic ${topic}`);
                 this.#events.emitEvent('error', new CloudNotificationAPIError(`Received message on unknown topic ${topic}`, 'ERR_UNKNOWN_TOPIC'));
@@ -751,10 +783,10 @@ class CloudNotificationAPI {
             return;
         }
         // We might have received this update from a different group or user topic so de-dupe
-        if (this.deDuplicator.has(txInstanceId)) {
+        if (this.#deDuplicator.has(txInstanceId)) {
             return;
         }
-        this.deDuplicator.add(txInstanceId);
+        this.#deDuplicator.add(txInstanceId);
         this.#sendNotificationDeliveredStatus(notificationId);
         let targetName = target;
         if (targetType === 'group') {
@@ -784,6 +816,14 @@ class CloudNotificationAPI {
         }
         this.#events.emitEvent('notification-event', parseResult.data);
     }
+    #handleAllNotificationEventMessage(messagePayload) {
+        const parseResult = f.safeParse(messagePayload);
+        if (!parseResult.success) {
+            this.#logger('warn', `Received invalid notification event message payload format ${parseResult.error?.toString()}`);
+            throw new InvalidMessageFormatError(parseResult);
+        }
+        this.#events.emitEvent('global-notification-event', parseResult.data);
+    }
     #lookupGroupNameByUuid(uuid) {
         if (!this.#sessionDetails) {
             return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfin/cloud-notification-core-api",
-  "version": "0.0.1-alpha.856abf3",
+  "version": "0.0.1-alpha.85addcf",
   "type": "module",
   "description": "",
   "main": "./index.cjs",