@openfin/cloud-notification-core-api 0.0.1-alpha.ff44012 → 0.0.1-alpha.ffa9f89

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 +254 -44
  2. package/index.cjs +85 -18
  3. package/index.mjs +85 -18
  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.
@@ -51,12 +95,20 @@ export declare class CloudNotificationAPI {
51
95
  category: string;
52
96
  type: string;
53
97
  payload?: unknown;
54
- }): Promise<void>;
98
+ }, options?: NotificationEventOptions): Promise<void>;
99
+ /**
100
+ * Removes a notification from the notification center for a given set of users or user groups.
101
+ *
102
+ * @param notificationId - The ID of the notification to remove.
103
+ * @param targets - The targets to remove the notification from.
104
+ * @returns A promise that resolves when the notification is removed.
105
+ */
106
+ removeFromNotificationCenter(notificationId: string, targets: NotificationTargets): Promise<void>;
55
107
  /**
56
108
  * Raises a notification to the Cloud Notification service.
57
109
  *
58
110
  * @param options - The options for the notification.
59
- * @param payload - The payload of the notification.
111
+ * @param payload - The payload of the notification which should generally conform to the notification center schema
60
112
  * @returns A promise that resolves with the notification raise result.
61
113
  * @throws {@link SessionNotConnectedError} If the session is not connected.
62
114
  * @throws {@link PublishError} If an error occurs during publishing.
@@ -67,7 +119,7 @@ export declare class CloudNotificationAPI {
67
119
  *
68
120
  * @param notificationId - The ID of the notification to update.
69
121
  * @param options - The options for the notification update.
70
- * @param payload - The new payload of the notification.
122
+ * @param payload - The new payload of the notification which should generally conform to the notification center update schema
71
123
  * @throws {@link SessionNotConnectedError} If the session is not connected.
72
124
  * @throws {@link PublishError} If an error occurs during publishing of the update.
73
125
  */
@@ -75,6 +127,8 @@ export declare class CloudNotificationAPI {
75
127
  /**
76
128
  * Marks a notification as deleted in the Cloud Notification service.
77
129
  *
130
+ * This in turn causes notification events to be raised for the notification
131
+ *
78
132
  * @param notificationId - The ID of the notification to delete.
79
133
  * @returns A promise that resolves when the notification is deleted.
80
134
  * @throws {@link SessionNotConnectedError} If the session is not connected.
@@ -83,8 +137,10 @@ export declare class CloudNotificationAPI {
83
137
  /**
84
138
  * Replays notifications from the Cloud Notification service.
85
139
  *
140
+ * This is called at platform startup to populate the notification center with notifications that were missed since the last time the platform was started.
141
+ *
86
142
  * @param pageItemLimit - The maximum number of items per page.
87
- * @param pageStartCursor - The cursor to start the page from.
143
+ * @param pageStartCursor - The cursor to start the page from. This is retrieved from the pageInfo property.
88
144
  * @returns A promise that resolves with the notifications replay details.
89
145
  * @throws {@link SessionNotConnectedError} If the session is not connected.
90
146
  * @throws {@link NotificationRetrievalError} If an error occurs during retrieval.
@@ -126,6 +182,8 @@ export declare class CloudNotificationAPI {
126
182
  export declare type CloudNotificationSettings = {
127
183
  /**
128
184
  * The URL of the notification server to connect to
185
+ *
186
+ * @example 'https://the-environment.example.com/notifications'
129
187
  */
130
188
  url: string;
131
189
  /**
@@ -141,7 +199,7 @@ export declare class CloudNotificationAPI {
141
199
  /**
142
200
  * Optional function to call with any logging messages to allow integration with the host application's logging
143
201
  *
144
- * defaults to console.log
202
+ * Defaults to console.log
145
203
  */
146
204
  logger?: CloudNotificationLogger;
147
205
  /**
@@ -156,7 +214,7 @@ export declare class CloudNotificationAPI {
156
214
  };
157
215
 
158
216
  /**
159
- * Repesents the result of a successful connection to the server
217
+ * Represents the result of a successful connection to the server
160
218
  */
161
219
  export declare type ConnectionResult = {
162
220
  /**
@@ -190,7 +248,10 @@ export declare class CloudNotificationAPI {
190
248
  export declare type ConnectParameters = {
191
249
  /**
192
250
  * ID for a group of shared applications.
251
+ *
193
252
  * This acts as a namespace for the notification messages that allows separation of messages between different groups of applications for the same user
253
+ *
254
+ * This, in general, should be the uuid of the platform that you are communicating
194
255
  */
195
256
  platformId: string;
196
257
  /**
@@ -199,11 +260,10 @@ export declare class CloudNotificationAPI {
199
260
  sourceId: string;
200
261
  /**
201
262
  * Determines the type of authentication to use with the service gateway
202
- * defaults to 'none'
203
263
  *
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
264
+ * - 'jwt' - Use JWT authentication, in this case jwtAuthenticationParameters must also be provided
265
+ * - 'basic' - Use basic authentication, in this case basicAuthenticationParameters must also be provided
266
+ * - 'default' - Authentication will be inherited from the current session
207
267
  */
208
268
  authenticationType?: 'jwt' | 'basic' | 'default';
209
269
  /**
@@ -225,6 +285,15 @@ export declare class CloudNotificationAPI {
225
285
  jwtAuthenticationParameters?: {
226
286
  /**
227
287
  * When JWT authentication is being used, this will be invoked just whenever a JWT token is required for a request
288
+ *
289
+ * This token should be conform to the configuration set within your environment. Contact Here support for more details
290
+ *
291
+ * @example
292
+ * ```typescript
293
+ * const jwtRequestCallback = () => {
294
+ * return 'your-jwt-token';
295
+ * };
296
+ * ```
228
297
  */
229
298
  jwtRequestCallback: () => string | object;
230
299
  /**
@@ -240,19 +309,62 @@ export declare class CloudNotificationAPI {
240
309
  action: 'delete';
241
310
  };
242
311
 
243
- export declare type EventListenersMap = Map<keyof EventMap, Array<(...args: Parameters<EventMap[keyof EventMap]>) => void>>;
244
-
245
312
  export declare type EventMap = {
313
+ /**
314
+ * Emitted when the connection has been re-established
315
+ * @returns void
316
+ */
246
317
  reconnected: () => void;
247
- disconnected: () => void;
318
+ /**
319
+ * Emitted when the connection has been disconnected
320
+ * @returns void
321
+ */
248
322
  reconnecting: (attemptNo: number) => void;
323
+ /**
324
+ * Emitted when the connection has been disconnected
325
+ * @returns void
326
+ */
327
+ disconnected: () => void;
328
+ /**
329
+ * Emitted when an error occurs
330
+ * @returns void
331
+ */
249
332
  error: (error: Error) => void;
333
+ /**
334
+ * Emitted when the session has expired
335
+ * @returns void
336
+ */
250
337
  'session-expired': () => void;
338
+ /**
339
+ * Emitted when the session has been extended
340
+ * @returns void
341
+ */
251
342
  'session-extended': () => void;
343
+ /**
344
+ * Emitted when a new notification is received
345
+ * @returns void
346
+ */
252
347
  'new-notification': (event: NewNotificationEvent) => void;
348
+ /**
349
+ * Emitted when an update to a notification is received
350
+ * @returns void
351
+ */
253
352
  'update-notification': (event: UpdateNotificationEvent) => void;
353
+ /**
354
+ * Emitted when a notification is deleted
355
+ * @returns void
356
+ */
254
357
  'delete-notification': (event: DeleteNotificationEvent) => void;
358
+ /**
359
+ * Emitted when a notification event is received for this specific session
360
+ * @returns void
361
+ */
255
362
  'notification-event': (event: NotificationEvent) => void;
363
+ /**
364
+ * Emitted when a notification event is received for all sessions
365
+ * @returns void
366
+ */
367
+ 'global-notification-event': (event: NotificationEvent) => void;
256
368
  };
257
369
 
258
370
  export declare class EventPublishError extends CloudNotificationAPIError {
@@ -273,30 +385,106 @@ export declare class CloudNotificationAPI {
273
385
  action: 'new';
274
386
  };
275
387
 
388
+ /**
389
+ * Represents a notification event
390
+ */
276
391
  export declare type NotificationEvent = {
392
+ /**
393
+ * The unique identifier for the notification
394
+ */
277
395
  notificationId: string;
396
+ /**
397
+ * The correlation identifier for the notification
398
+ */
278
399
  correlationId?: string;
400
+ /**
401
+ * The source identifier
402
+ */
403
+ sourceId: string;
404
+ /**
405
+ * The platform identifier
406
+ */
407
+ platformId: string;
408
+ /**
409
+ * The unique platform identifier for the user
410
+ */
411
+ userId: string;
412
+ /**
413
+ * The resolved username of the user
414
+ */
415
+ userName?: string;
416
+ /**
417
+ * The category of the notification.
418
+ * For notification center events this will be 'notification-center-event'
419
+ */
279
420
  category: string;
421
+ /**
422
+ * The type of the notification.
423
+ * For example 'notification-close' when a user closes a notification in the notification center
424
+ */
280
425
  type: string;
426
+ /**
427
+ * The payload of the notification.
428
+ * See the documentation for the notification center events for more information on the payload
429
+ */
281
430
  payload?: unknown;
282
431
  };
283
432
 
433
+ /**
434
+ * Represents the options for a notification event publish
435
+ */
436
+ export declare type NotificationEventOptions = {
437
+ /**
438
+ * The targets to send the event to
439
+ *
440
+ * This is a set of groups and users that the notification event will direct to. You may use to explicitly remove the notification
441
+ * from a subset of the original targets that received it.
442
+ *
443
+ * For example you send a notification to *all-users* and then want to remove the notification from a specific group. You can do this by
444
+ * specifying the group name in the targets.
445
+ *
446
+ * @example
447
+ * ```typescript
448
+ * const notificationEventOptions: NotificationEventOptions = {
449
+ * targets: {
450
+ * groups: ['all-users'],
451
+ * users: ['someuser@company.com']
452
+ * }
453
+ * };
454
+ * ```
455
+ */
456
+ targets: NotificationTargets;
457
+ };
458
+
284
459
  /**
285
460
  * Represents the options for a notification publish
286
461
  */
287
462
  declare type NotificationOptions_2 = {
288
463
  /**
289
464
  * A caller specified identifier for the notification
465
+ *
290
466
  * This is used to identify the notification in the system when events and responses are received
291
467
  */
292
468
  correlationId?: string;
293
469
  /**
294
470
  * The targets to send the notification to
471
+ *
295
472
  * This is a set of groups and users that the notification will be sent to
473
+ *
474
+ * @example
475
+ * ```typescript
476
+ * const notificationOptions: NotificationOptions = {
477
+ * targets: {
478
+ * groups: ['all-users'],
479
+ * users: ['someuser@company.com']
480
+ * }
481
+ * };
482
+ * ```
296
483
  */
297
484
  targets: NotificationTargets;
298
485
  /**
299
486
  * Optional number of seconds to keep the notification alive
487
+ *
300
488
  * After this time the notification will be expired and a delete update will be raised
301
489
  */
302
490
  ttlSeconds?: number;
@@ -321,22 +509,67 @@ export declare class CloudNotificationAPI {
321
509
  constructor(message?: string, code?: string, cause?: unknown);
322
510
  }
323
511
 
512
+ /**
513
+ * Represents a single notification replay detail.
514
+ */
324
515
  export declare type NotificationsReplayDetail = {
516
+ /**
517
+ * The cursor of the notification.
518
+ */
325
519
  cursor: string;
520
+ /**
521
+ * The session ID of the notification.
522
+ */
326
523
  sessionId: string;
524
+ /**
525
+ * The notification ID.
526
+ */
327
527
  notificationId: string;
528
+ /**
529
+ * The version of the notification.
530
+ */
328
531
  version: number;
532
+ /**
533
+ * The type of notification record.
534
+ */
329
535
  action: 'new' | 'update' | 'delete';
536
+ /**
537
+ * The payload of the notification.
538
+ */
330
539
  payload?: unknown;
540
+ /**
541
+ * The original correlation ID of the notification if specified.
542
+ */
331
543
  correlationId?: string | null;
544
+ /**
545
+ * The timestamp of the notification.
546
+ */
332
547
  timestamp: Date;
333
548
  };
334
549
 
550
+ /**
551
+ * Represents the results of a notifications replay request.
552
+ */
335
553
  export declare type NotificationsReplayDetails = {
554
+ /**
555
+ * The list of notifications replay details.
556
+ */
336
557
  data: NotificationsReplayDetail[];
558
+ /**
559
+ * The pagination information for the notifications replay request.
560
+ */
337
561
  pageInfo: {
562
+ /**
563
+ * The cursor of the first notification in the page.
564
+ */
338
565
  pageStart?: string;
566
+ /**
567
+ * The cursor of the next page.
568
+ */
339
569
  nextPage?: string;
570
+ /**
571
+ * Whether there is a next page of notifications.
572
+ */
340
573
  hasNextPage: boolean;
341
574
  };
342
575
  };
@@ -346,11 +579,16 @@ export declare class CloudNotificationAPI {
346
579
  */
347
580
  export declare type NotificationTargets = {
348
581
  /**
349
- * The groups to send the notification to
582
+ * The optional groups to send the notification to
583
+ *
584
+ * This can be a collection of either group names e.g. all-users which can be retrieved from the admin console or the
585
+ * UUID of the group itself
350
586
  */
351
587
  groups: string[];
352
588
  /**
353
- * The users to send the notification to
589
+ * The optional specific users to send the notification to
590
+ *
591
+ * This can be the username e.g. someuser\@company.com or the UUID of the user itself
354
592
  */
355
593
  users: string[];
356
594
  };
@@ -370,40 +608,12 @@ export declare class CloudNotificationAPI {
370
608
  constructor(message?: string, code?: string, cause?: unknown);
371
609
  }
372
610
 
373
- export declare type PublishResult = {
374
- notificationId: string;
375
- correlationId: string | undefined;
376
- };
377
-
378
611
  export declare class SessionNotConnectedError extends CloudNotificationAPIError {
379
612
  constructor(message?: string, code?: string);
380
613
  }
381
614
 
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
615
  export declare type UpdateNotificationEvent = BaseNotificationReceivedEvent & {
400
616
  action: 'update';
401
617
  };
402
618
 
403
- export declare type UserGroupWithTopic = {
404
- uuid: string;
405
- name: string;
406
- topic?: string;
407
- };
408
-
409
619
  export { }