@openfin/cloud-notification-core-api 0.0.1-alpha.04fd21d

package/LICENSE.md

@@ -0,0 +1,4 @@
+Learn more about OpenFin licensing at the links listed below or email us at support@openfin.co with questions.
+
+- [Developer agreement](https://openfin.co/developer-agreement)
+

package/README.md

@@ -0,0 +1,14 @@
+# @openfin/cloud-notification-core-api
+
+This package contains the core notification library that handles all interactions with the Here™ Cloud Notification Service.
+
+It is callable via browser or node applications.
+
+
+## Authentication
+
+The library supports authentication with the Here™ Cloud Notification Service using the following methods:
+ - Basic Authentication
+ - JWT Token Authentication
+ - Default Authentication i.e. Interactive session based authentication using cookies
+

package/bundle.d.ts

@@ -0,0 +1,409 @@
+import z from 'zod';
+
+export declare class AuthorizationError extends CloudNotificationAPIError {
+    constructor(message?: string, code?: string);
+}
+
+export declare type BaseNotificationReceivedEvent = {
+    action: 'new' | 'update' | 'delete';
+    notificationId: string;
+    correlationId?: string;
+    target: string;
+    targetName?: string;
+    targetType: string;
+    payload: unknown;
+};
+
+/**
+ * Represents a single connection to the Cloud Notification service
+ *
+ */
+export declare class CloudNotificationAPI {
+    #private;
+    deDuplicator: SetWithTTL<string>;
+    constructor(cloudNotificationSettings: CloudNotificationSettings);
+    /**
+     * Connects and creates a session on the Cloud Notifications service.
+     *
+     * @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.
+         * @throws {@link AuthorizationError} If the connection is unauthorized.
+             */
+         connect(parameters: ConnectParameters): Promise<ConnectionResult>;
+         /**
+          * Disconnects from the Cloud Notification service.
+          *
+          * @returns A promise that resolves when disconnected.
+          * @throws {@link CloudNotificationAPIError} If an error occurs during disconnection.
+              */
+          disconnect(): Promise<void>;
+          /**
+           * Posts a notification event to the Cloud Notification service.
+           *
+           * @param notificationId - The ID of the notification.
+           * @param event - The event details, including category, type, and optional payload.
+           * @returns A promise that resolves when the event is posted.
+           * @throws {@link SessionNotConnectedError} If the session is not connected.
+               * @throws {@link PublishError} If an error occurs during publishing.
+                   */
+               postNotificationEvent(notificationId: string, event: {
+                   category: string;
+                   type: string;
+                   payload?: unknown;
+               }): Promise<void>;
+               /**
+                * Raises a notification to the Cloud Notification service.
+                *
+                * @param options - The options for the notification.
+                * @param payload - The payload of the notification.
+                * @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.
+                        */
+                    raiseNotification(options: NotificationOptions_2, payload: unknown): Promise<NotificationRaiseResult>;
+                    /**
+                     * Raises a notification update to the Cloud Notification service.
+                     *
+                     * @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.
+                     * @throws {@link SessionNotConnectedError} If the session is not connected.
+                         * @throws {@link PublishError} If an error occurs during publishing of the update.
+                             */
+                         updateNotification(notificationId: string, options: NotificationUpdateOptions, payload: unknown): Promise<void>;
+                         /**
+                          * Marks a notification as deleted in the Cloud Notification service.
+                          *
+                          * @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.
+                              */
+                          deleteNotification(notificationId: string): Promise<void>;
+                          /**
+                           * Replays notifications from the Cloud Notification service.
+                           *
+                           * @param pageItemLimit - The maximum number of items per page.
+                           * @param pageStartCursor - The cursor to start the page from.
+                           * @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.
+                                   */
+                               replayNotifications(pageItemLimit: number | undefined, pageStartCursor: string | undefined): Promise<NotificationsReplayDetails>;
+                               /**
+                                * Adds an event listener for a specific event type.
+                                *
+                                * @param type - The event type.
+                                * @param callback - The callback function to invoke when the event occurs.
+                                */
+                               addEventListener<K extends keyof EventMap>(type: K, callback: EventMap[K]): void;
+                               /**
+                                * Removes an event listener for a specific event type.
+                                *
+                                * @param type - The event type.
+                                * @param callback - The callback function to remove.
+                                */
+                               removeEventListener<K extends keyof EventMap>(type: K, callback: EventMap[K]): void;
+                               /**
+                                * Adds a one-time event listener for a specific event type.
+                                *
+                                * @param type - The event type.
+                                * @param callback - The callback function to invoke once when the event occurs.
+                                */
+                               once<K extends keyof EventMap>(type: K, callback: EventMap[K]): void;
+                           }
+
+                           export declare class CloudNotificationAPIError extends Error {
+                               code: string;
+                               constructor(message?: string, code?: string, cause?: unknown);
+                           }
+
+                           /**
+                            * Represents a logging function to be used by the cloud notification client
+                            */
+                           export declare type CloudNotificationLogger = (level: LogLevel, message: string) => void;
+
+                           export declare type CloudNotificationSettings = {
+                               /**
+                                * The URL of the notification server to connect to
+                                */
+                               url: string;
+                               /**
+                                * The maximum number of times to retry connecting to the cloud notification service when the connection is dropped
+                                * defaults to 30
+                                */
+                               reconnectRetryLimit?: number;
+                               /**
+                                * Specifies how often keep alive messages should be sent to the cloud notification service in seconds
+                                * defaults to 30
+                                */
+                               keepAliveIntervalSeconds?: number;
+                               /**
+                                * Optional function to call with any logging messages to allow integration with the host application's logging
+                                *
+                                * defaults to console.log
+                                */
+                               logger?: CloudNotificationLogger;
+                               /**
+                                * The time used to deduplicate notifications
+                                */
+                               deduplicationTTLms?: number;
+                               /**
+                                * Will cause the api to calculate the time offset between the local machine and the notification server
+                                * defaults to true
+                                */
+                               syncTime?: boolean;
+                           };
+
+                           /**
+                            * Repesents the result of a successful connection to the server
+                            */
+                           export declare type ConnectionResult = {
+                               /**
+                                * The unique identifier for the session
+                                */
+                               sessionId: string;
+                               /**
+                                * The platform identifier
+                                */
+                               platformId: string;
+                               /**
+                                * The source identifier
+                                */
+                               sourceId: string;
+                               /**
+                                * The user identifier
+                                */
+                               userId: string;
+                               /**
+                                * A collection of groups that the user is either a direct or indirect member of
+                                */
+                               groups: {
+                                   uuid: string;
+                                   name: string;
+                               }[];
+                           };
+
+                           /**
+                            * Represents the parameters to use to connect to an notification server
+                            */
+                           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
+                                */
+                               platformId: string;
+                               /**
+                                * A value that distinguishes the host the application is running in. For example this could be the hostname of the current machine
+                                */
+                               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
+                                */
+                               authenticationType?: 'jwt' | 'basic' | 'default';
+                               /**
+                                * Optional parameters for basic authentication
+                                */
+                               basicAuthenticationParameters?: {
+                                   /**
+                                    * The username to use for basic authentication
+                                    */
+                                   username: string;
+                                   /**
+                                    * The password to use for basic authentication
+                                    */
+                                   password: string;
+                               };
+                               /**
+                                * Optional parameters for JWT authentication
+                                */
+                               jwtAuthenticationParameters?: {
+                                   /**
+                                    * When JWT authentication is being used, this will be invoked just whenever a JWT token is required for a request
+                                    */
+                                   jwtRequestCallback: () => string | object;
+                                   /**
+                                    * The id of the service gateway JWT authentication definition to use
+                                    *
+                                    * Note: Contact Here support to to get your organization's authentication id
+                                    */
+                                   authenticationId: string;
+                               };
+                           };
+
+                           export declare type DeleteNotificationEvent = BaseNotificationReceivedEvent & {
+                               action: 'delete';
+                           };
+
+                           export declare type EventListenersMap = Map<keyof EventMap, Array<(...args: Parameters<EventMap[keyof EventMap]>) => void>>;
+
+                           export declare type EventMap = {
+                               reconnected: () => void;
+                               disconnected: () => void;
+                               reconnecting: (attemptNo: number) => void;
+                               error: (error: Error) => void;
+                               'session-expired': () => void;
+                               'session-extended': () => void;
+                               'new-notification': (event: NewNotificationEvent) => void;
+                               'update-notification': (event: UpdateNotificationEvent) => void;
+                               'delete-notification': (event: DeleteNotificationEvent) => void;
+                               'notification-event': (event: NotificationEvent) => void;
+                           };
+
+                           export declare class EventPublishError extends CloudNotificationAPIError {
+                               constructor(message?: string, code?: string, cause?: unknown);
+                           }
+
+                           export declare class EventRetrievalError extends CloudNotificationAPIError {
+                               constructor(message?: string, code?: string, cause?: unknown);
+                           }
+
+                           export declare class InvalidMessageFormatError extends CloudNotificationAPIError {
+                               constructor(zodParseResult: z.SafeParseReturnType<unknown, unknown>);
+                           }
+
+                           export declare type LogLevel = 'log' | 'debug' | 'info' | 'warn' | 'error';
+
+                           export declare type NewNotificationEvent = BaseNotificationReceivedEvent & {
+                               action: 'new';
+                           };
+
+                           export declare type NotificationEvent = {
+                               notificationId: string;
+                               correlationId?: string;
+                               category: string;
+                               type: string;
+                               payload?: unknown;
+                           };
+
+                           /**
+                            * Represents the options for a notification publish
+                            */
+                           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
+                                */
+                               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;
+                           };
+                           export { NotificationOptions_2 as NotificationOptions }
+
+                           /**
+                            * Represents the response from raising a notification
+                            */
+                           export declare type NotificationRaiseResult = {
+                               /**
+                                * The unique identifier for the notification
+                                */
+                               notificationId: string;
+                               /**
+                                * The correlation ID that was provided when raising the notification
+                                */
+                               correlationId?: string;
+                           };
+
+                           export declare class NotificationRetrievalError extends CloudNotificationAPIError {
+                               constructor(message?: string, code?: string, cause?: unknown);
+                           }
+
+                           export declare type NotificationsReplayDetail = {
+                               cursor: string;
+                               sessionId: string;
+                               notificationId: string;
+                               version: number;
+                               action: 'new' | 'update' | 'delete';
+                               payload?: unknown;
+                               correlationId?: string | null;
+                               timestamp: Date;
+                           };
+
+                           export declare type NotificationsReplayDetails = {
+                               data: NotificationsReplayDetail[];
+                               pageInfo: {
+                                   pageStart?: string;
+                                   nextPage?: string;
+                                   hasNextPage: boolean;
+                               };
+                           };
+
+                           /**
+                            * Represents a set of targets for a notification publish
+                            */
+                           export declare type NotificationTargets = {
+                               /**
+                                * The groups to send the notification to
+                                */
+                               groups: string[];
+                               /**
+                                * The users to send the notification to
+                                */
+                               users: string[];
+                           };
+
+                           /**
+                            * Represents the options for a notification update
+                            */
+                           export declare type NotificationUpdateOptions = {
+                               /**
+                                * 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;
+                           };
+
+                           export declare class PublishError extends CloudNotificationAPIError {
+                               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 { }