@openfin/cloud-notification-core-api 0.0.1-alpha.2049c34

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,288 @@
+import z from 'zod';
+
+export declare class AuthorizationError extends CloudNotificationAPIError {
+    constructor(message?: string, code?: string);
+}
+
+export declare type BaseNotificationReceivedEvent = {
+    action: 'new' | 'update';
+    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;
+    constructor(cloudNotificationSettings: CloudNotificationSettings);
+    /**
+     * Connects and creates a session on the Cloud Notifications service
+     *
+     * @param {ConnectParameters} parameters - The parameters to use to connect
+     * @returns {*} {Promise<void>}
+     * @memberof CloudNotificationAPI
+     * @throws {CloudNotificationAPIError} - If an error occurs during connection
+     * @throws {AuthorizationError} - If the connection is unauthorized
+     */
+    connect(parameters: ConnectParameters): Promise<ConnectionResult>;
+    /**
+     * Disconnects from the Cloud Notification service
+     *
+     * @returns {*} {Promise<void>}
+     * @memberof CloudNotificationAPI
+     * @throws {CloudNotificationAPIError} - If an error occurs during disconnection
+     */
+    disconnect(): Promise<void>;
+    postNotificationEvent(notificationId: string, event: {
+        category: string;
+        type: string;
+        payload?: unknown;
+    }): Promise<void>;
+    /**
+     * Raises a notification to the Cloud Notification service
+     *
+     * @param {NotificationOptions} options - The options for the notification
+     * @param {unknown} payload - The payload of the notification
+     * @returns {*} {Promise<NotificationRaiseResult>}
+     * @memberof CloudNotificationAPI
+     * @throws {SessionNotConnectedError} - If the session is not connected
+     * @throws {PublishError} - If an error occurs during publishing
+     */
+    raiseNotification(options: NotificationOptions_2, payload: unknown): Promise<NotificationRaiseResult>;
+    updateNotification(): Promise<void>;
+    deleteNotification(): Promise<void>;
+    addEventListener<K extends keyof EventMap>(type: K, callback: EventMap[K]): void;
+    removeEventListener<K extends keyof EventMap>(type: K, callback: EventMap[K]): void;
+    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;
+};
+
+/**
+ * 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;
+    /**
+     * 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;
+    /**
+     * Calculates the time offset between the local machine and the notification server
+     * defaults to true
+     */
+    syncTime?: boolean;
+    /**
+     * Optional function to call with any logging messages to allow integration with the host application's logging
+     *
+     * defaults to console.log
+     */
+    logger?: CloudNotificationLogger;
+    /**
+     * 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 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;
+    'notification-event': (event: NotificationEvent) => void;
+};
+
+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;
+};
+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;
+};
+
+/**
+ * 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[];
+};
+
+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);
+}
+
+export declare type UpdateNotificationEvent = BaseNotificationReceivedEvent & {
+    action: 'update';
+};
+
+export declare type UserGroupWithTopic = {
+    uuid: string;
+    name: string;
+    topic?: string;
+};
+
+export { }