mirror of
https://github.com/rgrgogu/new_starr.git
synced 2026-09-27 00:12:54 +08:00
kennethobsequioandClaude Sonnet 5
eaa6d2276a
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
126 lines
2.5 KiB
Markdown
126 lines
2.5 KiB
Markdown
# Notifications Controller Documentation
|
|
|
|
**File:** `controllers/admin/notification.controller.js`
|
|
**Base URL:** `/api/admin/notifications`
|
|
**Guards:** `authenticate → requireAdmin() → adminLimiter`
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
- [Get All Notifications](#get-all-notifications)
|
|
- [Get Unseen Count](#get-unseen-count)
|
|
- [Mark One as Seen](#mark-one-as-seen)
|
|
- [Mark All as Seen](#mark-all-as-seen)
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- `admin_notifications` are **system-wide** — not scoped to a user. All admins see the same feed.
|
|
- Records are never deleted — seen/unseen state is toggled only.
|
|
- Notifications are created internally (e.g., task overdue events) — no POST endpoint is exposed.
|
|
|
|
---
|
|
|
|
## Get All Notifications
|
|
|
|
**`GET /api/admin/notifications`**
|
|
|
|
Returns paginated notifications, newest first.
|
|
|
|
### Query Parameters
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|--------|----------|-------------|
|
|
| `page` | number | No | Default: `1` |
|
|
| `limit` | number | No | Default: `20`, max: `50` |
|
|
|
|
### Response `200`
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"message": "Notifications fetched.",
|
|
"data": {
|
|
"notifications": [
|
|
{
|
|
"notification_id": 1,
|
|
"type": "task_overdue",
|
|
"title": "Tasks Overdue",
|
|
"message": "5 tasks are now overdue.",
|
|
"data": { "count": 5 },
|
|
"seen": false,
|
|
"seen_at": null,
|
|
"createdAt": "2026-06-19T10:00:00.000Z",
|
|
"updatedAt": "2026-06-19T10:00:00.000Z"
|
|
}
|
|
],
|
|
"pagination": {
|
|
"page": 1,
|
|
"limit": 20,
|
|
"total": 10,
|
|
"pages": 1
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Get Unseen Count
|
|
|
|
**`GET /api/admin/notifications/unseen`**
|
|
|
|
Returns a count of unseen notifications. Used for the bell badge.
|
|
|
|
### Response `200`
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"message": "Unseen count fetched.",
|
|
"data": { "count": 3 }
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Mark One as Seen
|
|
|
|
**`PATCH /api/admin/notifications/:id/seen`**
|
|
|
|
Marks a single notification as seen and sets `seen_at` to the current timestamp.
|
|
|
|
### Response `200`
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"message": "Notification marked as seen.",
|
|
"data": {
|
|
"notification_id": 1,
|
|
"seen": true,
|
|
"seen_at": "2026-06-21T10:00:00.000Z",
|
|
...
|
|
}
|
|
}
|
|
```
|
|
|
|
### Error Responses
|
|
| Status | Message |
|
|
|--------|---------|
|
|
| `404` | `Notification not found.` |
|
|
|
|
---
|
|
|
|
## Mark All as Seen
|
|
|
|
**`PATCH /api/admin/notifications/seen-all`**
|
|
|
|
Marks all unseen notifications as seen in a single update.
|
|
|
|
### Response `200`
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"message": "7 notification(s) marked as seen.",
|
|
"data": { "count": 7 }
|
|
}
|
|
```
|