# 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 }
}
```