@openfin/cloud-notification-core-api 0.0.1-alpha.f995a04 → 0.0.1-alpha.fe79c9b

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/bundle.d.ts +203 -43
  2. package/index.cjs +57 -17
  3. package/index.mjs +57 -17
  4. package/package.json +1 -1
package/bundle.d.ts CHANGED
@@ -4,13 +4,38 @@ export declare class AuthorizationError extends CloudNotificationAPIError {
4
4
  constructor(message?: string, code?: string);
5
5
  }
6
6
 
7
+ /**
8
+ * Represents common properties for all notification events
9
+ */
7
10
  export declare type BaseNotificationReceivedEvent = {
11
+ /**
12
+ * The action that was performed on the notification
13
+ */
8
14
  action: 'new' | 'update' | 'delete';
15
+ /**
16
+ * The unique identifier for the notification
17
+ */
9
18
  notificationId: string;
19
+ /**
20
+ * The correlation identifier for the notification
21
+ */
10
22
  correlationId?: string;
23
+ /**
24
+ * The identifier of the target of the notification
25
+ */
11
26
  target: string;
27
+ /**
28
+ * The name of the target i.e, the group or user that the notification was sent to
29
+ */
12
30
  targetName?: string;
31
+ /**
32
+ * The type of the target i.e, 'group' or 'user'
33
+ */
13
34
  targetType: string;
35
+ /**
36
+ * The payload of the notification.
37
+ * See the documentation for the notification center events for more information on the payload
38
+ */
14
39
  payload: unknown;
15
40
  };
16
41
 
@@ -20,11 +45,30 @@ export declare type BaseNotificationReceivedEvent = {
20
45
  */
21
46
  export declare class CloudNotificationAPI {
22
47
  #private;
23
- deDuplicator: SetWithTTL<string>;
48
+ /**
49
+ * Constructs a new instance of the CloudNotificationAPI
50
+ *
51
+ * @param cloudNotificationSettings - The settings for the Cloud Notification API.
52
+ */
24
53
  constructor(cloudNotificationSettings: CloudNotificationSettings);
25
54
  /**
26
55
  * Connects and creates a session on the Cloud Notifications service.
27
56
  *
57
+ * @example
58
+ * ```typescript
59
+ * const notificationApi = new CloudNotificationAPI({
60
+ * url: process.env.NOTIFICATION_SERVER_HOST
61
+ * });
62
+ *
63
+ * let connectionResult: ConnectionResult;
64
+ * try {
65
+ * connectionResult = await notificationApi.connect(connectSettings);
66
+ * } catch (errorConnect) {
67
+ * terminal.write(chalk.red(`\nError connecting to notification server: ${errorConnect}\n`));
68
+ * process.exit(1);
69
+ * }
70
+ * ```
71
+ *
28
72
  * @param parameters - The parameters to use to connect.
29
73
  * @returns A promise that resolves when the connection is established.
30
74
  * @throws {@link CloudNotificationAPIError} If an error occurs during connection.
@@ -56,7 +100,7 @@ export declare class CloudNotificationAPI {
56
100
  * Raises a notification to the Cloud Notification service.
57
101
  *
58
102
  * @param options - The options for the notification.
59
- * @param payload - The payload of the notification.
103
+ * @param payload - The payload of the notification which should generally conform to the notification center schema
60
104
  * @returns A promise that resolves with the notification raise result.
61
105
  * @throws {@link SessionNotConnectedError} If the session is not connected.
62
106
  * @throws {@link PublishError} If an error occurs during publishing.
@@ -67,7 +111,7 @@ export declare class CloudNotificationAPI {
67
111
  *
68
112
  * @param notificationId - The ID of the notification to update.
69
113
  * @param options - The options for the notification update.
70
- * @param payload - The new payload of the notification.
114
+ * @param payload - The new payload of the notification which should generally conform to the notification center update schema
71
115
  * @throws {@link SessionNotConnectedError} If the session is not connected.
72
116
  * @throws {@link PublishError} If an error occurs during publishing of the update.
73
117
  */
@@ -75,6 +119,8 @@ export declare class CloudNotificationAPI {
75
119
  /**
76
120
  * Marks a notification as deleted in the Cloud Notification service.
77
121
  *
122
+ * This in turn causes notification events to be raised for the notification
123
+ *
78
124
  * @param notificationId - The ID of the notification to delete.
79
125
  * @returns A promise that resolves when the notification is deleted.
80
126
  * @throws {@link SessionNotConnectedError} If the session is not connected.
@@ -83,8 +129,10 @@ export declare class CloudNotificationAPI {
83
129
  /**
84
130
  * Replays notifications from the Cloud Notification service.
85
131
  *
132
+ * This is called at platform startup to populate the notification center with notifications that were missed since the last time the platform was started.
133
+ *
86
134
  * @param pageItemLimit - The maximum number of items per page.
87
- * @param pageStartCursor - The cursor to start the page from.
135
+ * @param pageStartCursor - The cursor to start the page from. This is retrieved from the pageInfo property.
88
136
  * @returns A promise that resolves with the notifications replay details.
89
137
  * @throws {@link SessionNotConnectedError} If the session is not connected.
90
138
  * @throws {@link NotificationRetrievalError} If an error occurs during retrieval.
@@ -126,6 +174,8 @@ export declare class CloudNotificationAPI {
126
174
  export declare type CloudNotificationSettings = {
127
175
  /**
128
176
  * The URL of the notification server to connect to
177
+ *
178
+ * @example 'https://the-environment.example.com/notifications'
129
179
  */
130
180
  url: string;
131
181
  /**
@@ -141,7 +191,7 @@ export declare class CloudNotificationAPI {
141
191
  /**
142
192
  * Optional function to call with any logging messages to allow integration with the host application's logging
143
193
  *
144
- * defaults to console.log
194
+ * Defaults to console.log
145
195
  */
146
196
  logger?: CloudNotificationLogger;
147
197
  /**
@@ -156,7 +206,7 @@ export declare class CloudNotificationAPI {
156
206
  };
157
207
 
158
208
  /**
159
- * Repesents the result of a successful connection to the server
209
+ * Represents the result of a successful connection to the server
160
210
  */
161
211
  export declare type ConnectionResult = {
162
212
  /**
@@ -190,7 +240,10 @@ export declare class CloudNotificationAPI {
190
240
  export declare type ConnectParameters = {
191
241
  /**
192
242
  * ID for a group of shared applications.
243
+ *
193
244
  * This acts as a namespace for the notification messages that allows separation of messages between different groups of applications for the same user
245
+ *
246
+ * This, in general, should be the uuid of the platform that you are communicating
194
247
  */
195
248
  platformId: string;
196
249
  /**
@@ -199,11 +252,10 @@ export declare class CloudNotificationAPI {
199
252
  sourceId: string;
200
253
  /**
201
254
  * Determines the type of authentication to use with the service gateway
202
- * defaults to 'none'
203
255
  *
204
- * 'jwt' - Use JWT authentication, in this case jwtAuthenticationParameters must also be provided
205
- * 'basic' - Use basic authentication, in this case basicAuthenticationParameters must also be provided
206
- * 'default' - Authentication will be inherited from the current session
256
+ * - 'jwt' - Use JWT authentication, in this case jwtAuthenticationParameters must also be provided
257
+ * - 'basic' - Use basic authentication, in this case basicAuthenticationParameters must also be provided
258
+ * - 'default' - Authentication will be inherited from the current session
207
259
  */
208
260
  authenticationType?: 'jwt' | 'basic' | 'default';
209
261
  /**
@@ -225,6 +277,15 @@ export declare class CloudNotificationAPI {
225
277
  jwtAuthenticationParameters?: {
226
278
  /**
227
279
  * When JWT authentication is being used, this will be invoked just whenever a JWT token is required for a request
280
+ *
281
+ * This token should be conform to the configuration set within your environment. Contact Here support for more details
282
+ *
283
+ * @example
284
+ * ```typescript
285
+ * const jwtRequestCallback = () => {
286
+ * return 'your-jwt-token';
287
+ * };
288
+ * ```
228
289
  */
229
290
  jwtRequestCallback: () => string | object;
230
291
  /**
@@ -240,19 +301,62 @@ export declare class CloudNotificationAPI {
240
301
  action: 'delete';
241
302
  };
242
303
 
243
- export declare type EventListenersMap = Map<keyof EventMap, Array<(...args: Parameters<EventMap[keyof EventMap]>) => void>>;
244
-
245
304
  export declare type EventMap = {
305
+ /**
306
+ * Emitted when the connection has been re-established
307
+ * @returns void
308
+ */
246
309
  reconnected: () => void;
247
- disconnected: () => void;
310
+ /**
311
+ * Emitted when the connection has been disconnected
312
+ * @returns void
313
+ */
248
314
  reconnecting: (attemptNo: number) => void;
315
+ /**
316
+ * Emitted when the connection has been disconnected
317
+ * @returns void
318
+ */
319
+ disconnected: () => void;
320
+ /**
321
+ * Emitted when an error occurs
322
+ * @returns void
323
+ */
249
324
  error: (error: Error) => void;
325
+ /**
326
+ * Emitted when the session has expired
327
+ * @returns void
328
+ */
250
329
  'session-expired': () => void;
330
+ /**
331
+ * Emitted when the session has been extended
332
+ * @returns void
333
+ */
251
334
  'session-extended': () => void;
335
+ /**
336
+ * Emitted when a new notification is received
337
+ * @returns void
338
+ */
252
339
  'new-notification': (event: NewNotificationEvent) => void;
340
+ /**
341
+ * Emitted when an update to a notification is received
342
+ * @returns void
343
+ */
253
344
  'update-notification': (event: UpdateNotificationEvent) => void;
345
+ /**
346
+ * Emitted when a notification is deleted
347
+ * @returns void
348
+ */
254
349
  'delete-notification': (event: DeleteNotificationEvent) => void;
350
+ /**
351
+ * Emitted when a notification event is received for this specific session
352
+ * @returns void
353
+ */
255
354
  'notification-event': (event: NotificationEvent) => void;
355
+ /**
356
+ * Emitted when a notification event is received for all sessions
357
+ * @returns void
358
+ */
359
+ 'global-notification-event': (event: NotificationEvent) => void;
256
360
  };
257
361
 
258
362
  export declare class EventPublishError extends CloudNotificationAPIError {
@@ -273,11 +377,32 @@ export declare class CloudNotificationAPI {
273
377
  action: 'new';
274
378
  };
275
379
 
380
+ /**
381
+ * Represents a notification event
382
+ */
276
383
  export declare type NotificationEvent = {
384
+ /**
385
+ * The unique identifier for the notification
386
+ */
277
387
  notificationId: string;
388
+ /**
389
+ * The correlation identifier for the notification
390
+ */
278
391
  correlationId?: string;
392
+ /**
393
+ * The category of the notification.
394
+ * For notification center events this will be 'notification-center-event'
395
+ */
279
396
  category: string;
397
+ /**
398
+ * The type of the notification.
399
+ * For example 'notification-close' when a user closes a notification in the notification center
400
+ */
280
401
  type: string;
402
+ /**
403
+ * The payload of the notification.
404
+ * See the documentation for the notification center events for more information on the payload
405
+ */
281
406
  payload?: unknown;
282
407
  };
283
408
 
@@ -287,16 +412,29 @@ export declare class CloudNotificationAPI {
287
412
  declare type NotificationOptions_2 = {
288
413
  /**
289
414
  * A caller specified identifier for the notification
415
+ *
290
416
  * This is used to identify the notification in the system when events and responses are received
291
417
  */
292
418
  correlationId?: string;
293
419
  /**
294
420
  * The targets to send the notification to
421
+ *
295
422
  * This is a set of groups and users that the notification will be sent to
423
+ *
424
+ * @example
425
+ * ```typescript
426
+ * const notificationOptions: NotificationOptions = {
427
+ * targets: {
428
+ * groups: ['all-users'],
429
+ * users: ['someuser@company.com']
430
+ * }
431
+ * };
432
+ * ```
296
433
  */
297
434
  targets: NotificationTargets;
298
435
  /**
299
436
  * Optional number of seconds to keep the notification alive
437
+ *
300
438
  * After this time the notification will be expired and a delete update will be raised
301
439
  */
302
440
  ttlSeconds?: number;
@@ -321,22 +459,67 @@ export declare class CloudNotificationAPI {
321
459
  constructor(message?: string, code?: string, cause?: unknown);
322
460
  }
323
461
 
462
+ /**
463
+ * Represents a single notification replay detail.
464
+ */
324
465
  export declare type NotificationsReplayDetail = {
466
+ /**
467
+ * The cursor of the notification.
468
+ */
325
469
  cursor: string;
470
+ /**
471
+ * The session ID of the notification.
472
+ */
326
473
  sessionId: string;
474
+ /**
475
+ * The notification ID.
476
+ */
327
477
  notificationId: string;
478
+ /**
479
+ * The version of the notification.
480
+ */
328
481
  version: number;
482
+ /**
483
+ * The type of notification record.
484
+ */
329
485
  action: 'new' | 'update' | 'delete';
486
+ /**
487
+ * The payload of the notification.
488
+ */
330
489
  payload?: unknown;
490
+ /**
491
+ * The original correlation ID of the notification if specified.
492
+ */
331
493
  correlationId?: string | null;
494
+ /**
495
+ * The timestamp of the notification.
496
+ */
332
497
  timestamp: Date;
333
498
  };
334
499
 
500
+ /**
501
+ * Represents the results of a notifications replay request.
502
+ */
335
503
  export declare type NotificationsReplayDetails = {
504
+ /**
505
+ * The list of notifications replay details.
506
+ */
336
507
  data: NotificationsReplayDetail[];
508
+ /**
509
+ * The pagination information for the notifications replay request.
510
+ */
337
511
  pageInfo: {
512
+ /**
513
+ * The cursor of the first notification in the page.
514
+ */
338
515
  pageStart?: string;
516
+ /**
517
+ * The cursor of the next page.
518
+ */
339
519
  nextPage?: string;
520
+ /**
521
+ * Whether there is a next page of notifications.
522
+ */
340
523
  hasNextPage: boolean;
341
524
  };
342
525
  };
@@ -346,11 +529,16 @@ export declare class CloudNotificationAPI {
346
529
  */
347
530
  export declare type NotificationTargets = {
348
531
  /**
349
- * The groups to send the notification to
532
+ * The optional groups to send the notification to
533
+ *
534
+ * This can be a collection of either group names e.g. all-users which can be retrieved from the admin console or the
535
+ * UUID of the group itself
350
536
  */
351
537
  groups: string[];
352
538
  /**
353
- * The users to send the notification to
539
+ * The optional specific users to send the notification to
540
+ *
541
+ * This can be the username e.g. someuser\@company.com or the UUID of the user itself
354
542
  */
355
543
  users: string[];
356
544
  };
@@ -370,40 +558,12 @@ export declare class CloudNotificationAPI {
370
558
  constructor(message?: string, code?: string, cause?: unknown);
371
559
  }
372
560
 
373
- export declare type PublishResult = {
374
- notificationId: string;
375
- correlationId: string | undefined;
376
- };
377
-
378
561
  export declare class SessionNotConnectedError extends CloudNotificationAPIError {
379
562
  constructor(message?: string, code?: string);
380
563
  }
381
564
 
382
- /**
383
- * Simple set-like structure that allows you to add values with a TTL (time to live).
384
- * Values are automatically removed from the set after the TTL expires.
385
- */
386
- declare class SetWithTTL<T> {
387
- #private;
388
- private ttl;
389
- private store;
390
- private nextCollection;
391
- private collectionDelay;
392
- constructor(ttl: number, collectionCheckInterval?: number);
393
- get size(): number;
394
- add(value: T, customTtl?: number): this;
395
- has(value: T): boolean;
396
- delete(value: T): this;
397
- }
398
-
399
565
  export declare type UpdateNotificationEvent = BaseNotificationReceivedEvent & {
400
566
  action: 'update';
401
567
  };
402
568
 
403
- export declare type UserGroupWithTopic = {
404
- uuid: string;
405
- name: string;
406
- topic?: string;
407
- };
408
-
409
569
  export { }