🔔 Notification Service

The Notification Service (notificationService) provides endpoints for listing notifications and updating read state for an identity. There is no HTTP API in this service to create notifications — your application (or other blocks) writes notification documents directly.

---

🚀 Quickstart

import express from 'express';
import {middlewares, services, drivers} from '@nodeblocks/backend-sdk';

const {nodeBlocksErrorMiddleware} = middlewares;
const {notificationService} = services;
const {withMongo} = drivers;

const connectToDatabase = withMongo('mongodb://localhost:27017/?authSource=admin', 'dev', 'user', 'password');

express()
  .use(
    notificationService(
      {
        ...(await connectToDatabase('identities')),
        ...(await connectToDatabase('notifications')),
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        authMode: 'bearer', // or 'cookie'
      },
    ),
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

🍪 Cookie auth: When authMode: 'cookie', protected routes read the access token from cookies. Host apps must register cookie-parser.

---

📋 Endpoint Summary

Method	Path	Description	Authorization
POST	/notifications/:notificationId/read	Mark a single notification as read	Bearer/cookie auth; must own the notification
GET	/notifications/identities/:identityId	List notifications for an identity	Bearer/cookie auth; self only
POST	/notifications/identities/:identityId/read	Mark notifications as read up to an anchor	Bearer/cookie auth; self only

The service does not expose an HTTP endpoint for creating notifications; applications create notification records through their own internal logic.

---

🗄️ Entity Schema

{
  "id": "string",
  "receiverId": "string",
  "isRead": "boolean",
  "createdAt": "string (datetime)",
  "updatedAt": "string (datetime)"
}

Field	Type	Description
id	string	Notification identifier
receiverId	string	Identity that receives the notification
isRead	boolean	Whether the notification has been read
createdAt	datetime	Creation timestamp
updatedAt	datetime	Last update timestamp

Additional payload fields may be present depending on how notifications are created by your application.

---

🔐 Authentication Headers

Authorization: Bearer <access_token>
x-nb-fingerprint: <device_fingerprint>

The x-nb-fingerprint header is required for authenticated requests when fingerprint was specified during login.

---

🔧 API Endpoints

1. Mark Notification as Read

Request:

• Method: POST
• Path: /notifications/:notificationId/read
• Authorization: Authenticated owner of the notification

Path Parameters:

Field	Type	Required	Description
notificationId	string	✅	Notification ID

Response: 204 No Content

Errors: The ownership validator runs before the handler. A notification without a valid receiverId returns 403 Invalid owner ID; other ownership failures also return 403.

Example:

curl -X POST {{host}}/notifications/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2/read \
  -H "Authorization: Bearer <access-token>"

---

2. List Notifications for Identity

Request:

• Method: GET
• Path: /notifications/identities/:identityId
• Authorization: Authenticated self (identityId must match the token subject)

Path Parameters:

Field	Type	Required	Description
identityId	string	✅	Receiver identity ID

Query Parameters:

Field	Type	Required	Description
page	number	❌	Page number (1–1000)
limit	number	❌	Page size (1–50)

Response: 200 OK with paginated envelope:

{
  "data": [
    {
      "id": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
      "receiverId": "f792cde5-958b-49e9-bf83-13d59c1e35c0",
      "isRead": false,
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

Example:

curl "{{host}}/notifications/identities/f792cde5-958b-49e9-bf83-13d59c1e35c0?page=1&limit=20" \
  -H "Authorization: Bearer <access-token>"

Errors: 403 Identity ID does not match when identityId differs from the authenticated identity; invalid authentication returns 401.

---

3. Batch Mark Notifications as Read

Marks unread notifications for an identity as read up to (and including) the given anchor notification.

Request:

• Method: POST
• Path: /notifications/identities/:identityId/read
• Authorization: Authenticated self

Path Parameters:

Field	Type	Required	Description
identityId	string	✅	Receiver identity ID

Request Body:

Field	Type	Required	Description
lastReadNotificationId	string	✅	Anchor notification ID

Response: 204 No Content

Errors: 404 when the anchor notification is not found; unexpected failures may return 500.

Example:

curl -X POST {{host}}/notifications/identities/f792cde5-958b-49e9-bf83-13d59c1e35c0/read \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"lastReadNotificationId":"7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2"}'

---

⚙️ Configuration Options

interface NotificationServiceConfiguration {
  authSecrets: {
    authEncSecret: string;
    authSignSecret: string;
  };
  authMode?: 'bearer' | 'cookie';
}

Datastore

Collection	Required	Description
identities	✅	Required by the service type; these routes do not query it
notifications	✅	Notification documents

---

🔗 Related Documentation

• Authentication Service - Login and token management
• Identity Service - Identity lifecycle
• Profile Service - Profile management
• Error Handling - Error patterns