starr-philproperties/apps/api/controllers/admin/documentation/notifications.md

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 Unseen Count
• Mark One 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

{
  "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

{
  "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

{
  "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

{
  "status": "success",
  "message": "7 notification(s) marked as seen.",
  "data": { "count": 7 }
}