[PBI] REST API — notification history and inbox management

[cjlapao]

Description

Implement the REST API endpoints that allow the UI to retrieve a user's notification history, retrieve unread counts, mark notifications as read (individually and in bulk), and delete notifications. This is the mechanism the UI uses to hydrate the inbox on reconnect and to manage notification state.

User Story

As a user returning to the application after being offline, I want to be able to retrieve all notifications I missed, see which ones are unread, and manage my inbox (mark as read, delete), so that I have a complete picture of what happened while I was away.

Acceptance Criteria

• GET /notifications: Returns a paginated, chronologically descending list of notifications for the authenticated user. Supports query parameters: type (filter by enum value), is_read (filter by read state), correlation_id (filter by correlation group), limit, offset.
• GET /notifications/unread-count: Returns { "count": N } — the number of unread notifications for the authenticated user. Intended for badge display.
• PATCH /notifications/:id/read: Marks a single notification as read. Returns 404 if the notification does not exist or does not belong to the authenticated user.
• PATCH /notifications/read-all: Marks all of the authenticated user's notifications as read. Returns the count of rows updated.
• DELETE /notifications/:id: Permanently deletes a single notification for the authenticated user. Returns 404 if not found or not owned. Does not affect other users' copies.
• Auth enforcement: All endpoints require authentication. A user can only read, update, or delete their own notifications — no cross-user access.
• Consistent error format: All error responses follow the project's existing error envelope convention.
• Unit + integration tests: All endpoints are covered by tests including auth enforcement, not-found cases, and pagination boundary conditions.

Definition of Done

• Code implemented following best practices.
• Unit tests written and passing.
• Code reviewed and approved.
• Merged into the main branch.
• Documentation updated (if applicable).
• Deployed to staging/production environment.

Assumptions and Constraints

No response

Dependencies

• Assumption: Authentication middleware is already in place and injects the authenticated user_id into the request context.
• Constraint: Deletion is soft from the perspective of other users — deleting a notification removes only the calling user's row. Since rows are already per-user, a standard row delete is correct.

Additional Notes

No response