beps: restore topic to the document

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

beps/0001-notifications-system/README.md

@@ -99,14 +99,15 @@ The notification backend stores notification using the [database service](https:
 - Done date
 - Saved status
 - Creation date
-- Updated date (optional, for topic notifications)
+- Updated date (optional, for scoped notifications)
 - Payload:
   - Title
-  - Description
-  - Priority
+  - Description (optional)
   - Origin
   - Link
   - Recipients
+  - Severity (optional, default normal)
+  - Topic (optional)
   - Scope (optional)
   - Icon (optional)
   - Image URL (optional)
@@ -117,10 +118,15 @@ The title is mandatory human-readable text shortly describing the notifications.
 
 The description is an optional human-readable text providing more details to the user.
 
-The priority is one of the predefined values to help with presentation of the notifications or their filtering. Allowed values are: `critical`, `high`, `normal` (default), and `low`.
+The severity is one of the predefined values to help with presentation of the notifications or their filtering. Allowed values are: `critical`, `high`, `normal` (default), and `low`.
 
 The origin is a string identifying the creator of the notification, i.e. the BE plugin or external system.
 
+The topic is an optional string helping to group notifications of particular context. Its use cases include:
+
+- Several notifications emitted by an asynchronous external task can be grouped by a single topic
+- A backend plugin can group several related messages to a particular processing, i.e. asynchronous progress monitoring
+
 If a scope is provided for a notification, it will either:
 
 - Create a new notification if user doesn't have existing notification in that scope and origin
@@ -130,7 +136,7 @@ The idea of scope is to be able to reuse notifications about same information fo
 
 The timestamp of notification creation is auto-generated by the notifications backend at the time of receiving a request to create the notification.
 
-The icon and image URL are optional and is meant to improve UX. A string referencing an icon name from MUI icon library of a defined version. If missing, it will be determined from the priority.
+The icon and image URL are optional and is meant to improve UX. A string referencing an icon name from MUI icon library of a defined version. If missing, it will be determined from the severity.
 
 The link is a relative or absolute URL. As an example, it can be used:
 
@@ -187,31 +193,33 @@ export type NotificationRecipients =
       type: 'broadcast'; // all users
     };
 
+export type NotificationSeverity = 'critical' | 'high' | 'normal' | 'low';
+
+export type NotificationPayload = {
+  title: string;
+  description?: string;
+  link: string;
+  additionalLinks?: string[];
+  severity: NotificationSeverity;
+  topic?: string;
+  scope?: string;
+  icon?: string;
+};
+
 export type Notification = {
   id: string;
   userRef: string;
-  title: string;
-  description: string;
-  origin: string;
-  link: string;
   created: Date;
-  saved: boolean;
+  saved?: Date;
   read?: Date;
-  scope?: string;
   updated?: Date;
-  icon?: string;
-  image?: string;
+  origin: string;
+  payload: NotificationPayload;
 };
 
 interface SendNotificationRequest {
   recipients: NotificationRecipients;
-  title: string;
-  description: string;
-  link: string;
-  origin: string;
-  scope?: string;
-  icon?: string;
-  image?: string;
+  payload: NotificationPayload;
 }
 
 interface NotificationService {
@@ -221,7 +229,7 @@ interface NotificationService {
 
 Each notification is always routed to individual users unless it's a broadcast. The `notification-backend` will figure out which users will receive a notification based on the `recipients` parameter, resolving it to the concrete list of users at the time of sending the notification.
 
-Each notification contains a `title`, a `description` and a `link` for further information. The `created`, `id`, `read` and `saved` properties are handled by the backend based and cannot be changed during the notification creation.
+Each notification contains a `title` and a `link` for user to see further information. The `created`, `id`, `read` and `saved` properties are handled by the backend based and cannot be changed during the notification creation.
 
 Calling `sendNotification` should never throw an error so that it doesn't block the current processing. Notifications should be considered as second-level citizens that are not critical if not delivered.
 
@@ -305,10 +313,6 @@ export type NotificationStatus = {
   read: number;
 };
 
-export type NotificationIds = {
-  ids: string[];
-};
-
 interface NotificationsApi {
   getNotifications(options?: GetNotificationsOptions): Promise<Notification[]>;
 
@@ -329,13 +333,7 @@ interface NotificationsApi {
 ```ts
 export type NotificationSignal = {
   action: string;
-  notification?: {
-    title: string;
-    description: string;
-    link: string;
-    icon?: string;
-    image?: string;
-  };
+  notification?: NotificationPayload;
 };
 
 const { lastSignal, isSignalsAvailable } =
@@ -362,7 +360,7 @@ interface SignalApi {
 - Unread notifications count is displayed in the title of the page
 - Configuration can be used to enable or disable features in the notification system (Web Notification API, title change, etc.)
 - Replace absent signal service with long polling. This requires changes to the `signals` plugin as well.
-- Notifications can have priority that is used to determine how notifications are shown to the user
+- Notifications can have severity that is used to determine how notifications are shown to the user
 
 ## Release Plan