Initial user notification backend

[knolleary]

Closes #4158

Description

Implements the backend design for user notifications - as detailed in #4113

Database

New Notification model added, including db migration to create the table:

CREATE TABLE Notifications (
    id        INTEGER       PRIMARY KEY AUTOINCREMENT,
    type      VARCHAR (255) NOT NULL,
    reference VARCHAR(255),
    read      TINYINT (1)   DEFAULT 0,
    data      TEXT,
    createdAt DATETIME      NOT NULL,
    UserId    INTEGER       REFERENCES Users (id) ON DELETE CASCADE
                                                  ON UPDATE CASCADE
);

External API

• GET /api/v1/user/notifications - returns notifications, most recent first. Uses pagination as per standard design
• PUT /api/v1/user/notifications/:id - mark notification read
  • body params:
    • read - true/false
• DELETE /api/v1/user/notifications/:id - delete a notification

Not included

The spec in #4113 included bulk end points - I haven't implemented them in this PR as unnecessary for first iteration where we can make individual api requests to update individual notifications

• PUT /api/v1/user/notifications - bulk mark notifications read. Will mark all read by default
• DELETE /api/v1/user/notifications - bulk delete

Runtime API

A bare bones API is provided to send a notification to a user. Not going to over specify this until work is done to start adding real notifications.

app.notifications.send(user, type, data, reference)

• user - the User to send the notification to (a full app.db.models.User object)
• type - string - the type of notification. This will be one from a well-defined list. How they get defined (and whether we add convenience functions like we have for the auditLog) can be determined as we start adopting it.
• data - object - contextual data needed for the notification. This will get exposed on the API, so must not include raw database ids - only hashids.
• reference - (optional) string - a reference that can be used to clear this notification later

app.notifications.remove(user, reference)

• user - the User to remove the notification for (a full app.db.models.User object)
• reference - string - the notification reference to remove

The idea behind reference is that we can associate the notification with something - such as the hashid of an invitation. When that invitation is processed, we can remove the notification.

[codecov]

Codecov Report

Attention: Patch coverage is 73.68421% with 25 lines in your changes missing coverage. Please review.

Project coverage is 78.13%. Comparing base (559c6b3) to head (1b8a0f2).

Files	Patch %	Lines
forge/routes/api/userNotifications.js	40.00%	15 Missing ⚠️
forge/db/models/Notification.js	75.86%	7 Missing ⚠️
forge/db/controllers/Invitation.js	84.61%	2 Missing ⚠️
.../migrations/20240711-01-add-Notifications-table.js	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4164      +/-   ##
==========================================
- Coverage   78.17%   78.13%   -0.04%     
==========================================
  Files         287      292       +5     
  Lines       13310    13403      +93     
  Branches     2986     3000      +14     
==========================================
+ Hits        10405    10473      +68     
- Misses       2905     2930      +25     

Flag	Coverage Δ
backend	78.13% <73.68%> (-0.04%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Steve-Mcl]

pulled and tested with curls locally. works as expected.

One suggestion would be to consider the read field - Is the a possibility of a future where notifications could be "paused", or "forwarded" or something other than read: true/false? Implementing this now would save a future migration. The original proposal did request a status field which would cater for such instances?

However, that said, not gonna block this.

One other suggestion, since this is very early days, it might be wise to mark the API as private to avoid any lock in (however unlikely that is at this early stage)

[knolleary]

Is the a possibility of a future where notifications could be "paused", or "forwarded" or something other than read: true/false

None of the apis I've researched around notifications have multiple states like this. A notification is either read or unread. If we find a need for other states, they can be a new field that is independent of whether the user has 'seen' a notification or not.

[knolleary]

Not going to merge this until I make a bit more progress with #4165 to help validate the assumptions in this PR

[knolleary]

Updated to include the new reference field to allow clearing of notifications.