Initial commit: nick docs

03 - API Reference/Notification API.md

@@ -0,0 +1,110 @@
+---
+title: Notification API
+tags: [api, notification, reference]
+---
+
+# Notification API
+
+Endpoints live under `/api/notifications/*`. Two routers are mounted:
+
+- New controller pattern: [`notificationControllerRoutes.ts`](../../backend/src/services/notification/notificationControllerRoutes.ts) (controller-backed, requires auth)
+- Legacy: [`notification/routes.ts`](../../backend/src/services/notification/routes.ts) (no auth gate — userId is passed in query/body)
+
+Both routers are mounted at `/api`, so the paths collide; the controller router wins for the shared paths (it is mounted first). The legacy router is still used by background scripts and admin tools that have no JWT context.
+
+Model: [[Notification]]. Real-time delivery is via `new-notification` and `unread-count-update` Socket.IO events on `user-<userId>`. See [[Socket Events]].
+
+## List
+
+### GET /api/notifications
+
+**Description:** Paginated notifications for the caller.
+**Auth required:** Bearer JWT (controller route); legacy variant takes `?userId=...`.
+**Query params:**
+- `page` (default 1)
+- `limit` (default 20)
+- `unreadOnly` (`true` | `false`, default `false`)
+**Response 200:**
+```json
+{
+  "success": true,
+  "data": {
+    "notifications": [Notification, ...],
+    "pagination": { "page": 1, "limit": 20, "total": 42, "hasMore": true }
+  }
+}
+```
+
+### GET /api/notifications/unread-count
+
+**Description:** Just the integer unread count.
+**Auth required:** Bearer JWT
+**Response 200:** `{ "success": true, "data": { "unreadCount": 5 } }`
+
+### GET /api/notifications/:id
+
+**Description:** Single notification by id. Available on the controller router.
+**Auth required:** Bearer JWT
+**Errors:** `404` not found, `403` not owner.
+
+## Mutations
+
+### PATCH /api/notifications/:id/read
+
+**Description:** Mark one notification as read.
+**Auth required:** Bearer JWT (controller); legacy variant requires `{ userId }` in body.
+**Response 200:** `{ success: true, data: { /* updated notification */ } }`
+**Side effects:** Emits `unread-count-update` to `user-<userId>`.
+
+### PATCH /api/notifications/mark-all-read
+
+**Description:** Mark every notification for the caller as read.
+**Auth required:** Bearer JWT
+**Response 200:** `{ "success": true, "data": { "modifiedCount": 12 } }`
+
+### PATCH /api/notifications/bulk/mark-read
+
+**Description:** Mark a list of notifications as read.
+**Auth required:** Bearer JWT
+**Request body:** `{ ids: string[] }`
+**Response 200:** `{ success, data: { modifiedCount } }`
+
+### DELETE /api/notifications/:id
+
+**Description:** Delete a notification.
+**Auth required:** Bearer JWT
+**Errors:** `404` not found.
+
+### DELETE /api/notifications/bulk/delete
+
+**Description:** Bulk delete.
+**Auth required:** Bearer JWT
+**Request body:** `{ ids: string[] }`
+
+### POST /api/notifications
+
+**Description:** Create a notification. Primarily used by other services and admin tools.
+**Auth required:** Bearer JWT (controller); legacy variant is open.
+**Request body:**
+```ts
+{
+  userId: string;
+  type: string;                // e.g. "order_update", "chat_message", "payment_received"
+  title: string;
+  body?: string;
+  data?: Record<string, unknown>;
+  channel?: "in_app" | "email" | "push";
+}
+```
+**Response 201:** `{ success, data: { notification } }`
+**Side effects:** Emits `new-notification` to `user-<userId>`; also increments unread count via `unread-count-update`.
+
+## Preferences
+
+Notification preferences live on [[User]] (`preferences.notifications.email | sms | push`). They are read and written through the [[User API]] (`GET /api/user/profile`, `PUT /api/user/profile`).
+
+## Related
+
+- [[Notification]]
+- [[Notification Flow]]
+- [[Socket Events]]