Notifications

[david-rocca]

Add basic user notifications for new conversations

Summary

Introduce a notification system that alerts users when a conversation is added to their organization or directed to them individually.

Notifications should normally be created automatically as part of conversation creation. Provide endpoints to retrieve notifications, dismiss an individual notification, and allow Secretariat users to create generic notifications.

Data Model

Create a collection containing a notification list for each recipient user UUID:

{
  "<user_uuid>": {
    "notifications": [
      {
        "UUID": "<notification_uuid>",
        "body": "ORG XYZ has sent a message.",
        "links": {
          "org_shortname": "",
          "user_shortname": ""
        },
        "type": "PUBLIC_MESSAGE",
        "created_at": "2026-09-21T14:00:00Z"
      }
    ]
  }
}

• user_uuid identifies the recipient.
• Each notification has a unique UUID so it can be dismissed individually.
• body contains the notification text.
• links identifies the relevant organization or user for navigation. Unused values may remain empty.
• type accepts either PRIVATE_MESSAGE or PUBLIC_MESSAGE.
• created_at supports chronological ordering.

The notification UUID and timestamp are proposed additions to the supplied structure.

Proposed Endpoints

Method	Endpoint	Behavior
GET	/api/notification	Return the authenticated user’s notifications, newest first.
DELETE	/api/notification/:uuid	Dismiss one notification belonging to the authenticated user.
POST	/api/notification/target/:user_uuid	Create a generic notification for an existing user. Secretariat only.

Retrieve Notifications

• Require authentication.
• Return only the authenticated user’s notifications.
• Return 200 with an empty notifications array when none exist.

Dismiss a Notification

• Require authentication.
• Remove the specified notification from the authenticated user’s list.
• Return 204 when successfully dismissed.
• Return 404 if the notification is absent from that user’s list.
• Dismissing a notification must not affect another user’s copy.

Create a Generic Notification

• Require authentication and the Secretariat role.
• Accept body, links, and type.
• Generate the notification UUID and timestamp.
• Validate that the recipient exists.
• Return 201 with the created notification.
• Return 403 for non-Secretariat callers.

Automatic Notification Behavior

• For an organization recipient, create a separate notification for each eligible user in that organization.
• For an individual recipient, create a notification only for that user.
• Populate the notification body and navigation links from the conversation context.
• Apply existing conversation access rules when selecting recipients. Private conversations currently have Secretariat-only visibility; notifications must preserve that restriction.
• Create notifications through the shared conversation creation path so both direct conversation creation and conversations added through organization updates are covered.
• Persist conversation and notification writes within the same transaction so a failed operation leaves neither partially saved.
• Editing an existing conversation does not generate a new notification.

Implementation Plan

1. Add the notification model, validation, and repository using existing repository patterns.
2. Add authenticated retrieval and dismissal endpoints and the Secretariat-only creation endpoint.
3. Add shared recipient resolution and notification creation to ConversationRepository.createConversation().
4. Document the endpoints and add integration coverage.

Acceptance Criteria

• Organization notifications are delivered once to each eligible recipient.
• Individual notifications are delivered only to the specified user.
• Both existing conversation creation paths generate notifications automatically.
• Editing an existing conversation does not generate a new notification.
• Users can retrieve and individually dismiss their own notifications.
• Users with no notifications receive an empty notifications array.
• Users cannot retrieve or dismiss another user’s notifications.
• Dismissing a notification does not affect another user’s copy.
• Only Secretariat users can create generic notifications.
• Invalid payloads and nonexistent recipients return documented errors.
• Private conversation notifications respect existing visibility restrictions.
• Failed transactions leave no partial conversation or notification writes.
• OpenAPI documentation and integration tests cover successful operations, authorization, validation, and rollback behavior.