docs: improve explanation of notification processors

Signed-off-by: Heikki Hellgren <heikki.hellgren@op.fi>

plugins/notifications-common/src/types.ts

@@ -19,32 +19,86 @@ export type NotificationSeverity = 'critical' | 'high' | 'normal' | 'low';
 
 /** @public */
 export type NotificationPayload = {
+  /**
+   * Notification title
+   */
   title: string;
+  /**
+   * Optional longer description for the notification
+   */
   description?: string;
+  /**
+   * Optional link where the notification is pointing to
+   */
   link?: string;
   // TODO: Add support for additional links
   // additionalLinks?: string[];
+  /**
+   * Notification severity, defaults to 'normal'
+   */
   severity?: NotificationSeverity;
+  /**
+   * Optional notification topic
+   */
   topic?: string;
+  /**
+   * Notification scope, can be used to re-send same notifications in case
+   * the scope and origin matches.
+   */
   scope?: string;
+  /**
+   * Optional notification icon
+   */
   icon?: string;
 };
 
 /** @public */
 export type Notification = {
+  /**
+   * Unique identifier for the notification
+   */
   id: string;
+  /**
+   * The user entity reference that the notification is targeted to or null
+   * for broadcast notifications
+   */
   user: string | null;
+  /**
+   * Notification creation date
+   */
   created: Date;
+  /**
+   * If user has saved the notification, the date when it was saved
+   */
   saved?: Date;
+  /**
+   * If user has read the notification, the date when it was read
+   */
   read?: Date;
+  /**
+   * If the notification has been updated due to it being in the same scope
+   * and from same origin as previous notification, the date when it was updated
+   */
   updated?: Date;
+  /**
+   * Origin of the notification as in the reference to sender
+   */
   origin: string;
+  /**
+   * Actual notification payload
+   */
   payload: NotificationPayload;
 };
 
 /** @public */
 export type NotificationStatus = {
+  /**
+   * Total number of unread notifications for the user
+   */
   unread: number;
+  /**
+   * Total number of read notifications for the user
+   */
   read: number;
 };
 

plugins/notifications-node/api-report.md

@@ -20,7 +20,7 @@ export class DefaultNotificationService implements NotificationService {
   send(notification: NotificationSendOptions): Promise<void>;
 }
 
-// @public (undocumented)
+// @public
 export interface NotificationProcessor {
   getName(): string;
   postProcess?(

plugins/notifications-node/src/extensions.ts

@@ -18,6 +18,21 @@ import { Notification } from '@backstage/plugin-notifications-common';
 import { NotificationSendOptions } from './service';
 
 /**
+ * Notification processors are used to modify the notification parameters or sending the notifications
+ * to external systems.
+ *
+ * Notification modules should utilize the `notificationsProcessingExtensionPoint` to add new processors
+ * to the system.
+ *
+ * Notification processing flow:
+ *
+ * 1. New notification send request is received
+ * 2. For all notification processors registered, processOptions function is called to process the notification options
+ * 3. Notification recipients are resolved from the options
+ * 4. For each recipient, preProcess function is called to pre-process the notification
+ * 5. Notification is saved to the database and sent to the Backstage UI
+ * 6. For each recipient, postProcess function is called to post-process the notification
+ *
  * @public
  */
 export interface NotificationProcessor {
@@ -29,8 +44,11 @@ export interface NotificationProcessor {
   /**
    * Process the notification options.
    *
-   * This can be used to modify the options before sending the notification or even sending the notification to
-   * external services. This function is called only once for each notification before processing it.
+   * Can be used to override the default recipient resolving, sending the notification to an
+   * external service or modify other notification options necessary.
+   *
+   * processOptions functions are called only once for each notification before the recipient resolving,
+   * pre-process, sending and post-process of the notification.
    *
    * @param options - The original options to send the notification
    */
@@ -42,10 +60,13 @@ export interface NotificationProcessor {
    * Pre-process notification before sending it to Backstage UI.
    *
    * Can be used to send the notification to external services or to decorate the notification with additional
-   * information. This function is called for each notification recipient individually or once for broadcast
-   * notification.
+   * information. The notification is saved to database and sent to Backstage UI after all pre-process functions
+   * have run. The notification options passed here are already processed by processOptions functionality.
    *
-   * @param notification - The notification to decorate
+   * preProcess functions are called for each notification recipient individually or once for broadcast
+   * notification BEFORE the notification has been sent to the Backstage UI.
+   *
+   * @param notification - The notification to send
    * @param options - The options to send the notification
    * @returns The same notification or a modified version of it
    */
@@ -57,8 +78,10 @@ export interface NotificationProcessor {
   /**
    * Post process notification after sending it to Backstage UI.
    *
-   * Can be used to send the notification to external services. This function is called for each notification
-   * recipient individually or once for broadcast notification.
+   * Can be used to send the notification to external services.
+   *
+   * postProcess functions are called for each notification recipient individually or once for
+   * broadcast notification AFTER the notification has been sent to the Backstage UI.
    *
    * @param notification - The notification to send
    * @param options - The options to send the notification