Notifications API

Manage in-app notifications and read receipts for authenticated users.

• Base URL: /api/notifications
• Auth: Cookie-based JWT (token) created by the Auth API. All endpoints require an authenticated user.
• Audience Filtering: Each notification row stores an accessLevel JSON array (e.g., ["admin","sales"]). Responses are filtered to the caller's req.user.accessLevel. Read state is tracked per-user in read_notifications_receipts.

---

Data Models

Notification (response shape)

{
  "id": 123,
  "title": "New Payments Request",
  "message": "A new payment request...",
  "type": "info",                // free-form string set by the system (e.g., info, warning)
  "link": "/pendingPayments?...", // optional deep link for the UI
  "createdAt": "2025-01-01T12:34:56.000Z",
  "read": true                     // boolean — derived per-user from read receipts
}

Note: The read flag is computed by left-joining read_notifications_receipts; it is guaranteed to be a boolean in API responses.

---

Endpoints

GET /api/notifications/

Fetch notifications visible to the authenticated user (based on their accessLevel), newest first.

Authorization: Required (any authenticated user).

Query Params: None.

Response – 200 OK

[
  {
    "id": 42,
    "title": "Installment due",
    "message": "One or more installments are overdue.",
    "type": "warning",
    "link": "/installments/123",
    "createdAt": "2025-01-02T10:00:00.000Z",
    "read": false
  }
]

Errors

• 500 – Internal server error

cURL

curl -X GET \
  -b "token=<JWT>" \
  https://<HOST>/api/notifications

---

POST /api/notifications/

Mark all notifications visible to the current user as read (idempotent). The API determines the user from the auth cookie and inserts missing receipts.

Authorization: Required (any authenticated user).

Request Body: None.

Response – 200 OK

{ "message": "Notifications marked as read successfully" }

Errors

• 500 – Error marking notifications as read

cURL

curl -X POST \
  -b "token=<JWT>" \
  https://<HOST>/api/notifications

---

PATCH /api/notifications/:notificationId/read

Mark a single notification as read for the authenticated user. If it was already marked as read, the endpoint returns a success message indicating it was already read (idempotent behavior).

Authorization: Required (any authenticated user).

Path Params

• notificationId (number, required): Notification id to mark as read.

Request Body: None.

Responses

• 200 OK
  • { "message": "Notification marked as read" }
  • or { "message": "Notification already marked as read" }
• 400 Bad Request – Missing notificationId
• 500 Internal Server Error – Error marking notification as read

cURL

curl -X PATCH \
  -b "token=<JWT>" \
  https://<HOST>/api/notifications/42/read

---

Authorization & Visibility Rules

• Endpoints require a valid auth cookie (token).
• Queries restrict results to notifications whose accessLevel JSON array contains the caller's req.user.accessLevel.
• The API does not expose notifications to users whose access level is not listed in a notification's accessLevel field.

Sorting & Pagination

• Results are ordered by createdAt descending.
• No server-side pagination parameters are supported at present.

Status Codes Summary

Code	When
200	Successful fetch or marking read
400	Missing or invalid notificationId on PATCH /:notificationId/read
500	Unhandled server/database error

Notes for Integrators

• Treat the collection from GET / as immutable historical messages; use the read flag to render badges.
• Call POST / for a "Mark all as read" action in the UI.
• Call PATCH /:id/read when the user opens a specific notification.
• type is a free string (e.g., info, warning, success); use it as a UI hint only.