Notification - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: Admin, mobile, and internal-facing APIs owned by the notification module, plus the admin operational feed that shares its noun.

Twenty-one routes across two delivery models. Ten admin routes manage templates, delivery history, dead letters and event cancellation. Eight mobile routes serve the consumer notification centre, push device registration and the preference matrix. Three admin routes serve the operational feed, which is a different feature — it fans out on read by permission, not on write to named people.

There is no public route in this module. Everything requires a session.

1. Documentation Evidence

2. Module Summary

Global request handling that applies to every route below:

• ValidationPipe runs with whitelist: true, forbidNonWhitelisted: true and transform: true. An unknown body or query property is rejected with 400, not silently stripped.
• The global prefix is api. URI versioning is enabled platform-wide, but no controller in this module declares a version, so every path is unversioned.
• ClassSerializerInterceptor is applied globally.

3. Concepts and Terminology

4. API Surface Map

Runtime path versus controller path. Every admin controller declares its own path with no prefix, so the runtime URL is the global api prefix plus the controller path. The three consumer leaves declare notifications, notification-devices and notification-preferences, and MOBILE_CHILDREN mounts each of them under mobile — so @Controller("notifications") in NotificationCentreController becomes /api/mobile/notifications, while @Controller("notifications") in NotificationFeedController becomes /api/notifications. Two different controllers declare the same local path and resolve to different runtime routes, and confusing them is the single most likely integration mistake in this module: one is a per-person centre, the other a permission-filtered operational feed.

Registration is by concrete leaf, never by aggregate. RouterModule.register() does not recurse, so listing an aggregate would mount its controllers at /api/<thing>/... instead — silently, with the routes existing at the wrong prefix and nothing reporting it.

Swagger membership. NotificationTemplateModule, NotificationHistoryModule, NotificationFailureModule, NotificationEventModule and NotificationFeedModule are named individually in ADMIN_MODULES, never through the admin aggregate, because Swagger's include does not recurse. The three consumer leaves are reflected from MOBILE_CHILDREN. Swagger tags in use: Notification Templates, Notification History, Notification Failures, Notification Events, Notifications, Shared — Notifications, Shared — Devices, Shared — Notification Preferences.

Status codes not stated by Swagger. POST handlers without an explicit @HttpCode return 201 at runtime, which is Nest's default. That applies to POST /api/notification-templates, both feed POSTs, both centre POSTs and POST /api/notification-failures/{publicId}/replay. Both DELETE handlers in this module carry an explicit @HttpCode(HttpStatus.OK) and return 200 with a body. PUT /api/mobile/notification-preferences returns 200.

5. Auth, Identity, and Permissions

Why several handlers declare no permission. RoleGuard normally refuses an admin route that declares none, precisely so a route cannot ship open by accident. Eleven handlers here are on its explicit allowlist, for two different reasons:

• The consumer surfaces are used by guardians and students, who hold no admin-catalogue permission at all. A permissioned handler would refuse them before any scoping ran.
• The operational feed has no single permission that means "notifications". Each row carries the permission of the screen its event belongs to, and the service returns only rows the caller's active role could already have read by opening that screen. A blanket permission would gate the whole feed behind the widest of them, or show every operator everything.

For all eleven, RoleGuard returns true before it ever reads request.user, so the service predicate is the only access control. Those predicates are documented per endpoint in section 8 and in full in the backend doc.

Active role, not the union of roles held. Both feeds resolve visibility from actor.activeRole. A teacher who is also a parent sees staff-audience notifications only while acting as staff. A session with no active role sees only rows that are not role-scoped (consumer centre) or nothing at all (operational feed), because an empty permission list becomes the SQL literal false.

No idempotency keys. No route in this module accepts one. Idempotency where it matters is structural: marking read twice is a no-op, registering the same token twice is a touch, and replay is guarded by a compare-and-set on job_failures.replayed_at.

No route-level rate limiting is declared in this module. Abuse is bounded by the caps listed in section 11.

6. DTO and Model Reference

6.1 ResponseDto — the envelope

Every route in this module returns it.

There is no success field. Consumers must branch on the HTTP status and on errorCode.

6.2 QueryDto — the shared list query

Inherited by ListNotificationTemplatesQueryDto, ListNotificationHistoryQueryDto, ListNotificationFailuresQueryDto and the centre's ListNotificationsQueryDto.

sort, order and search are inherited but unused by every list in this module. Each list has a fixed order chosen so offset pagination is stable — an unstable sort silently drops and duplicates rows across pages. They are accepted rather than rejected because forbidNonWhitelisted would otherwise 400 a client that sends the platform's standard query shape.

Every list in this module refuses pagination=false with 400 PAGINATION_LIMIT_INVALID. These tables only grow, and there is no ceiling small enough to make an unbounded read safe to buffer at once.

6.3 NotificationTemplateResponseDto

6.4 ListNotificationTemplatesQueryDto

Extends QueryDto.

6.5 CreateNotificationTemplateDto

subject is accepted for every channel by the DTO but is only meaningful for email; the renderer reads it as the title for email and ignores it elsewhere. updatedBy is server-set from the session and is not accepted in the body.

6.6 UpdateNotificationTemplateDto

An omitted field keeps its current value; subject distinguishes omitted from explicitly null, and only an explicit null clears it. version is always incremented server-side.

6.7 DeleteNotificationTemplateDto

A DELETE with a body is unusual and deliberate: without the version a delete could silently win over a concurrent edit.

6.8 ListNotificationHistoryQueryDto

Extends QueryDto.

6.9 NotificationHistoryListItemDto

Deliberately absent, permanently: variables, any rendered content, and any recipient name, email or phone. NotificationHistory_READ is not superadmin-only, and returning any of those would let one grant re-aggregate what StaffSalary and StudentMedical were split apart to keep separate. The service does not read those columns into memory at all, so there is nothing to accidentally spread.

6.10 NotificationHistoryDetailDto

Extends NotificationHistoryListItemDto and adds:

6.11 NotificationHistoryRecipientDto

6.12 NotificationHistoryDeliveryDto

renderedTitle and renderedBody exist on the table and are never exposed here.

6.13 CancelledNotificationEventDto

6.14 ListNotificationFailuresQueryDto

Extends QueryDto.

in_app is not a permitted value: it has no queue and therefore no dead letters. channel narrows within the three notification channel queues and can never widen past them, because the queue allowlist is ANDed unconditionally.

6.15 NotificationFailureDto

6.16 ReplayNotificationFailureResponseDto

Extends NotificationFailureDto and adds:

6.17 NotificationCentreItemDto — the consumer centre row

title and body are typed nullable because the columns are, but a row this endpoint returns always carries both: the template registry refuses at boot any kind declaring an in_app channel without persistRendered, and a kind whose template fails to render is recorded skipped_no_template and is excluded by the query. Consumers should still render defensively rather than assert.

Every field is listed explicitly in the DTO — no spread — because a spread would leak whatever the underlying SELECT happens to carry. The integration spec asserts Object.keys(response) against exactly this set.

6.18 UnreadNotificationCountDto and MarkAllNotificationsReadResultDto

6.19 RegisterNotificationDeviceDto and NotificationDeviceDto

The request DTO deliberately carries no userId and no deviceId. The row is bound to actor.id from the verified session; a body field here would let anyone bind a token to somebody else's account, and RoleGuard runs no permission check on this handler.

The token is never echoed back.

6.20 NotificationPreferencesDto and its children

NotificationPreferenceCategoryDto:

locked is computed from the template registry, not from UNSUPPRESSIBLE_CATEGORY: that constant names categories a kind is allowed to lock, not categories that are fully locked today. system permits an unsuppressible kind but currently holds none, so treating it as locked would show a switch that works for a category with nothing to switch.

6.21 UpdateNotificationPreferencesDto

NotificationPreferenceOverrideDto:

Accepted but not persisted: an override naming a locked category. isEnabled always returns true for an unsuppressible kind regardless of any stored row, so persisting one would be a switch with no effect on delivery. Duplicates on (category, channel) are de-duplicated last-write-wins.

There is no field for the global per-channel switch. notification_channel_preference exists and is honoured by the resolver as level 3, but no route in this module writes it — the PUT body carries per-category overrides only. The GET response does reflect any stored global value as the fallback beneath a per-category override.

6.22 NotificationDto and NotificationListDto — the operational feed

NotificationListDto wraps data: NotificationDto[] plus unreadCount: number, counted across everything visible to the caller rather than just the page — a badge that counted the page would cap at its size.

6.23 ListNotificationsQueryDto — the feed's own query

This is a different class from the centre's, despite the shared name.

The feed does not use QueryDto: it is a bounded newest-first window, not an offset-paginated list, so it returns no count, currentPage or totalPage. The service additionally clamps limit between 1 and 200.

7. Enum Reference

8. Endpoint Reference

8.1 GET /api/notification-templates

Purpose

Lists operator overrides of the notification template registry, newest first. The admin panel calls this to render the template management screen. Only rows somebody deliberately created appear — the table is never seeded, so an empty list is the correct and expected state on a fresh deployment, and it does not mean notifications have no copy. The shipped wording lives in code and is used whenever no active override matches.

Source Evidence

Auth and Permissions

• Auth: admin JWT.
• Guard chain: JwtAuthGuard then RoleGuard.
• Permission: NotificationTemplate_READ.
• Guest support: none.
• Rate limit: none declared.
• Idempotency: read-only.

Request

Response

200, ordered createdAt DESC, id DESC.

{
  "message": "Notification templates fetched.",
  "data": [
    {
      "publicId": "0192f3a1-9c4e-7a10-b3d2-6f1e0c5a7b44",
      "kind": "school.announcement",
      "channel": "email",
      "locale": "en",
      "subject": "A message from school",
      "body": "Hello {{name}}, {{message}}",
      "isActive": true,
      "version": 2,
      "updatedBy": "0192f0aa-1111-7000-8000-0123456789ab",
      "createdAt": "2026-09-01T04:15:22.311Z",
      "updatedAt": "2026-09-08T09:02:44.107Z"
    }
  ],
  "count": 1,
  "currentPage": 1,
  "totalPage": 1,
  "errorCode": null
}

Empty-list response:

{ "message": "Notification templates fetched.", "data": [], "count": 0, "currentPage": 1, "totalPage": 0, "errorCode": null }

Side Effects

• Database reads: notification_template, plus a COUNT(*) when pagination is enabled.
• Cache, jobs, realtime, analytics, notifications, external calls: none.
• Audit: the global activity interceptor records reads only where configured to; no explicit record is written here.

Error Cases

Edge Cases

• Empty input — no filters returns every override.
• Blank search — search is accepted and ignored.
• Invalid enum — a channel outside the four is a 400 from @IsIn.
• size above 100 — clamped to 100 rather than rejected.
• page beyond the end — an empty data array with a truthful count.
• Unstable sort — impossible: id DESC is the tie-break, because two overrides saved in the same millisecond share a createdAt.
• Unsupported sort option — sort and order do not change the ordering.

Example Requests

GET /api/notification-templates?kind=school.announcement&channel=email&page=1&size=20 HTTP/1.1
Authorization: Bearer TOKEN

curl -s "$API_URL/api/notification-templates?channel=sms" \
  -H "Authorization: Bearer TOKEN"

8.2 GET /api/notification-templates/{publicId}

Purpose

Reads one override, including the version that a subsequent PATCH or DELETE must echo back. The panel calls this when opening the edit form, and must not reuse a version cached from the list if any time has passed — reading immediately before editing is what keeps the optimistic-concurrency window short.

Source Evidence

Same files as 8.1.

Auth and Permissions

• Auth: admin JWT. Guard chain JwtAuthGuard, RoleGuard. Permission NotificationTemplate_READ. No guest support, no rate limit, read-only.

Request

Response

200 with a single NotificationTemplateResponseDto in data, and no pagination fields.

{
  "message": "Notification template fetched.",
  "data": {
    "publicId": "0192f3a1-9c4e-7a10-b3d2-6f1e0c5a7b44",
    "kind": "school.announcement",
    "channel": "sms",
    "locale": "ne",
    "subject": null,
    "body": "{{title}}: {{message}}",
    "isActive": true,
    "version": 1,
    "updatedBy": null,
    "createdAt": "2026-09-01T04:15:22.311Z",
    "updatedAt": "2026-09-01T04:15:22.311Z"
  },
  "errorCode": null
}

Side Effects

One SELECT. Nothing else.

Error Cases

Edge Cases

• subject is null for every non-email channel and is not an error.
• updatedBy is null for a row whose author has since been deleted.

Example Requests

curl -s "$API_URL/api/notification-templates/0192f3a1-9c4e-7a10-b3d2-6f1e0c5a7b44" \
  -H "Authorization: Bearer TOKEN"

8.3 POST /api/notification-templates

Purpose

Creates an override for one (kind, channel, locale). Use this when the shipped wording needs changing for a school — a different greeting, a translated body, a shorter SMS. The override layers on top of the code registry and never replaces it, so if the row is later deactivated, deleted, or fails to render, the notification still goes out with the built-in copy.

Source Evidence

Same files as 8.1.

Auth and Permissions

• Auth: admin JWT. Guards JwtAuthGuard, RoleGuard. Permission NotificationTemplate_CREATE. No guest support. No idempotency key — a second identical request violates the (kind, channel, locale) unique constraint.

Request

Minimal valid request:

{ "kind": "school.announcement", "channel": "sms", "body": "{{title}}: {{message}}" }

Full valid request:

{
  "kind": "school.announcement",
  "channel": "email",
  "locale": "ne",
  "subject": "विद्यालयबाट सूचना",
  "body": "नमस्ते {{name}}, {{message}}",
  "isActive": true
}

Response

201 with the created row.

{
  "message": "Notification template created.",
  "data": {
    "publicId": "0192f4b2-0000-7a10-b3d2-6f1e0c5a7b45",
    "kind": "school.announcement",
    "channel": "email",
    "locale": "ne",
    "subject": "विद्यालयबाट सूचना",
    "body": "नमस्ते {{name}}, {{message}}",
    "isActive": true,
    "version": 1,
    "updatedBy": "0192f0aa-1111-7000-8000-0123456789ab",
    "createdAt": "2026-09-10T06:11:03.982Z",
    "updatedAt": "2026-09-10T06:11:03.982Z"
  },
  "errorCode": null
}

Side Effects

• Database writes: one notification_template row. version starts at 1; updatedBy is set from the session.
• Audit: the global ActivityAuditInterceptor records the mutation from the handler's @Permissions().
• Rendering effect: takes effect on the next fan-out batch, because overrides are loaded once per batch. Messages already queued are unaffected.
• No jobs, no realtime, no cache invalidation, no external calls.

Error Cases

Edge Cases

• Whitespace-only body — a body of spaces is rejected by length(btrim(body)) > 0; a body of a single tab or newline passes, deliberately: the constraint exists to catch the empty string a form submits, not to be a whitespace validator.
• subject on a non-email channel — accepted and stored, ignored at render.
• Unknown placeholder — a {{whatever}} the kind never supplies makes the override unrenderable at send time, and the renderer silently falls back to the shipped copy with one warning per key. Nothing fails here.
• Duplicate action — the second create is a unique violation, not a no-op.

Example Requests

curl -s -X POST "$API_URL/api/notification-templates" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"school.announcement","channel":"sms","body":"{{title}}: {{message}}"}'

8.4 PATCH /api/notification-templates/{publicId}

Purpose

Edits an override under optimistic concurrency. Every field is optional except version, which must match the row's current value. Two operators editing the same template is a real scenario in a school office, and the alternative — last write wins — silently discards one of them. The response carries the incremented version, which the client must use for any further edit.

Source Evidence

Same files as 8.1.

Auth and Permissions

• Auth: admin JWT. Guards JwtAuthGuard, RoleGuard. Permission NotificationTemplate_UPDATE. The request object is read for the activity context.

Request

Minimal valid request:

{ "version": 2, "body": "Updated copy" }

Full valid request:

{
  "version": 2,
  "kind": "school.announcement",
  "channel": "email",
  "locale": "en",
  "subject": "A message from school",
  "body": "Hello {{name}}, {{message}}",
  "isActive": false
}

Response

200 with the updated row and version incremented by one.

Side Effects

• Database writes: the notification_template row, with version = version + 1 and updatedBy set from the session.
• Audit: two records. The global interceptor covers the mutation, and the service additionally calls ActivityRecordService.recordActivity with per-field changes for kind, channel, locale, subject, body and isActive. This is the one caller that computes changes by hand, because the interceptor has no before-value.
• Rendering effect: takes effect on the next fan-out batch.

Error Cases

Edge Cases

• Omitted versus null subject — omitting it keeps the current value; sending null clears it. Every other optional field only supports "omitted keeps".
• Race condition — two PATCHes with the same version: the first wins, the second is a 409. The response body of the winner carries the new version.
• Concurrent delete — a PATCH whose version was invalidated by a DELETE reports 409, not 404, because the compare-and-set matched zero rows before the row lookup could notice it had gone.
• No-op edit — sending only version succeeds, bumps version, and records an activity entry with an empty changes set.

Example Requests

curl -s -X PATCH "$API_URL/api/notification-templates/0192f3a1-9c4e-7a10-b3d2-6f1e0c5a7b44" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version":2,"isActive":false}'

Conflict response:

{
  "message": "This template was changed by someone else. Reload it and try again.",
  "errorCode": "NOTIFICATION_TEMPLATE_VERSION_CONFLICT"
}

8.5 DELETE /api/notification-templates/{publicId}

Purpose

Removes an override so the affected (kind, channel, locale) reverts to the shipped wording. This is the correct way to undo a bad edit: the code registry is always present, so there is nothing to restore afterwards. The request carries a body — the version — so a delete cannot silently win over a concurrent edit.

Source Evidence

Same files as 8.1.

Auth and Permissions

• Auth: admin JWT. Guards JwtAuthGuard, RoleGuard. Permission NotificationTemplate_DELETE. @HttpCode(HttpStatus.OK) overrides Nest's DELETE default.

Request

Response

200 with data: null.

{ "message": "Notification template deleted.", "data": null, "errorCode": null }

Side Effects

• Database writes: one row deleted. Hard delete — there is no soft-delete column on this table, because the registry is the durable copy.
• Audit: the global interceptor records the mutation.
• Rendering effect: the next fan-out batch uses the shipped copy.

Error Cases

Edge Cases

• Deleting the last override for a kind — entirely safe. The shipped copy takes over.
• Deleting an inactive override — permitted; isActive is irrelevant to the delete.
• Duplicate action — the second DELETE answers 404.
• Concurrent edit — a PATCH that committed first makes this 409.

8.6 GET /api/notification-history

Purpose

Lists every notification event that was fanned out to real people, newest first by when the thing happened. This is the screen an operator opens to answer "did that announcement actually go out". It is deliberately event-level: the response carries counts and fan-out state, not recipients, so a large announcement is one row rather than three thousand.

Source Evidence

Auth and Permissions

• Auth: admin JWT. Guards JwtAuthGuard, RoleGuard. Permission NotificationHistory_READ. Read-only, no guest support, no rate limit.

Request

Response

200, ordered occurredAt DESC, id DESC.

{
  "message": "Notification history fetched.",
  "data": [
    {
      "publicId": "0192f5c3-1111-7a10-b3d2-6f1e0c5a7b46",
      "sourceModule": "auth",
      "kind": "auth.password_reset",
      "category": "security",
      "priority": "critical",
      "scheduledFor": null,
      "occurredAt": "2026-09-10T05:58:11.004Z",
      "cancelledAt": null,
      "fannedOutAt": "2026-09-10T05:58:12.220Z",
      "recipientCount": 1,
      "unresolvedCount": 0,
      "failedDeliveryCount": 0,
      "createdAt": "2026-09-10T05:58:11.010Z"
    }
  ],
  "count": 1,
  "currentPage": 1,
  "totalPage": 1,
  "errorCode": null
}

Side Effects

Reads notification_event, a COUNT(*) when paginated, and one grouped join across notification_delivery and notification_recipient to compute failedDeliveryCount for the page. Nothing is written.

Error Cases

Edge Cases

• A pending event — fannedOutAt, recipientCount and unresolvedCount are all null together, by constraint.
• A cancelled event — cancelledAt set, fannedOutAt null, and it will never fan out.
• A zero-recipient fan-out — fannedOutAt set with recipientCount: 0. Legal: the audience matched nobody.
• failedDeliveryCount versus visible failures — it counts only failed and dead. An event with every delivery skipped_unconfigured reports 0, which is correct: an unconfigured channel is not an outage.
• from after to — accepted; returns nothing.
• Empty result — data: [] with a truthful count.

Example Requests

curl -s "$API_URL/api/notification-history?category=announcement&from=2026-09-01T00:00:00.000Z&size=50" \
  -H "Authorization: Bearer TOKEN"

8.7 GET /api/notification-history/{publicId}

Purpose

Returns one event with every recipient and every delivery beneath it — the screen an operator opens to answer "what happened to this particular message, for this particular family". It is the only place the delivery state machine is visible in full: status, attempts, lease-expiry count, last error code, masked destination and every timestamp.

Source Evidence

Same files as 8.6.

Auth and Permissions

Admin JWT, JwtAuthGuard, RoleGuard, NotificationHistory_READ.

Request

Response

200. Recipients are ordered by internal id; deliveries within each recipient likewise.

{
  "message": "Notification event fetched.",
  "data": {
    "publicId": "0192f5c3-1111-7a10-b3d2-6f1e0c5a7b46",
    "sourceModule": "school",
    "kind": "school.announcement",
    "category": "announcement",
    "priority": "normal",
    "scheduledFor": null,
    "occurredAt": "2026-09-10T05:58:11.004Z",
    "cancelledAt": null,
    "fannedOutAt": "2026-09-10T05:58:12.220Z",
    "recipientCount": 2,
    "unresolvedCount": 0,
    "failedDeliveryCount": 1,
    "createdAt": "2026-09-10T05:58:11.010Z",
    "actionUrl": "/announcements/0192f5c3",
    "actionLabel": "Read it",
    "requestedChannels": ["email", "sms", "in_app"],
    "audience": { "kind": "guardians_of_class", "classPublicIds": ["0192aaaa-2222-7000-8000-000000000001"] },
    "recipients": [
      {
        "publicId": "0192f5c4-2222-7a10-b3d2-6f1e0c5a7b47",
        "audienceRoleId": 4,
        "readAt": null,
        "createdAt": "2026-09-10T05:58:12.100Z",
        "deliveries": [
          {
            "publicId": "0192f5c5-3333-7a10-b3d2-6f1e0c5a7b48",
            "channel": "in_app",
            "providerTargetId": null,
            "status": "delivered",
            "provider": "in_app",
            "providerMessageId": null,
            "destinationHint": null,
            "attempts": 0,
            "failureCount": 0,
            "leaseExpiryCount": 0,
            "lastError": null,
            "replayOfDeliveryId": null,
            "queuedAt": "2026-09-10T05:58:12.100Z",
            "sentAt": null,
            "deliveredAt": "2026-09-10T05:58:12.100Z",
            "failedAt": null,
            "skippedAt": null,
            "nextAttemptAt": null,
            "createdAt": "2026-09-10T05:58:12.100Z"
          },
          {
            "publicId": "0192f5c6-4444-7a10-b3d2-6f1e0c5a7b49",
            "channel": "sms",
            "providerTargetId": null,
            "status": "dead",
            "provider": "aakash",
            "providerMessageId": null,
            "destinationHint": "9779●●●●●123",
            "attempts": 1,
            "failureCount": 1,
            "leaseExpiryCount": 0,
            "lastError": "SMS_INSUFFICIENT_CREDIT",
            "replayOfDeliveryId": null,
            "queuedAt": "2026-09-10T05:58:12.100Z",
            "sentAt": null,
            "deliveredAt": null,
            "failedAt": "2026-09-10T05:58:15.441Z",
            "skippedAt": null,
            "nextAttemptAt": null,
            "createdAt": "2026-09-10T05:58:12.100Z"
          },
          {
            "publicId": "0192f5c7-5555-7a10-b3d2-6f1e0c5a7b4a",
            "channel": "email",
            "providerTargetId": null,
            "status": "skipped_preference",
            "provider": null,
            "providerMessageId": null,
            "destinationHint": null,
            "attempts": 0,
            "failureCount": 0,
            "leaseExpiryCount": 0,
            "lastError": null,
            "replayOfDeliveryId": null,
            "queuedAt": "2026-09-10T05:58:12.100Z",
            "sentAt": null,
            "deliveredAt": null,
            "failedAt": null,
            "skippedAt": "2026-09-10T05:58:12.100Z",
            "nextAttemptAt": null,
            "createdAt": "2026-09-10T05:58:12.100Z"
          }
        ]
      }
    ]
  },
  "errorCode": null
}

That single response demonstrates four things worth reading carefully: an in_app delivery legitimately delivered with sentAt null; a dead SMS carrying a redacted error code rather than a provider response; a skipped_preference row that exists precisely so the question "why did this parent not get the SMS" is answerable from the record; and a masked destination hint.

Side Effects

Three reads: the event, its recipients, and their deliveries. Nothing is written.

Error Cases

Edge Cases

• A very large event — recipients and deliveries are not paginated on this endpoint. An all_users announcement returns everything. Callers should expect a large payload and should reach for the list endpoint's counts where a summary suffices.
• A recipient whose user was hard-erased — the row survives with only its own publicId; the response never carried a user id in any case.
• A replayed delivery — appears as an additional row with replayOfDeliveryId set to the internal id of the original, which is not addressable through this API.
• Push — one delivery row per token, each with a providerTargetId.
• unresolvedCount — how many ids in the audience specification name nothing that exists. It is what separates the two causes of recipientCount: 0: a real class that happens to be empty, which is not a fault, and a stale or mistyped id, which means the announcement was never going to reach anyone. Written once when the fan-out completes, by one existence probe per audience kind. It asks only whether an id names a row — never whether the group has members, because an empty group is legitimate and marking it as a fault would be wrong.

Example Requests

curl -s "$API_URL/api/notification-history/0192f5c3-1111-7a10-b3d2-6f1e0c5a7b46" \
  -H "Authorization: Bearer TOKEN"

8.8 DELETE /api/notification-events/{publicId}

Purpose

Cancels a scheduled notification event before it fans out. A design that creates a scheduled, irreversible send to three thousand families has to provide the inverse, and this is it. It works only while the event has not been fanned out; once recipients exist the messages are already queued or gone, and cancelling would be a lie.

Source Evidence

Auth and Permissions

• Auth: admin JWT. Guards JwtAuthGuard, RoleGuard. Permission NotificationHistory_UPDATE, not a module of its own — this is the single write the history surface makes, on the same rows it reads.
• @HttpCode(HttpStatus.OK).

Request

Response

200.

{
  "message": "Notification event cancelled.",
  "data": {
    "publicId": "0192f5c3-1111-7a10-b3d2-6f1e0c5a7b46",
    "cancelledAt": "2026-09-10T06:20:03.115Z"
  },
  "errorCode": null
}

Side Effects

• Database writes: notification_event.cancelled_at, via a compare-and-set on fanned_out_at IS NULL AND cancelled_at IS NULL.
• Downstream effect: the fan-out worker's own claim carries cancelled_at IS NULL in its predicate, so a cancel landing between the worker's read and its claim wins. The orphan sweep also excludes cancelled events, so nothing re-dispatches it.
• Audit: the global interceptor records the mutation.
• No jobs, no realtime, no external calls.

Error Cases

The two 409s are distinguished by a deliberate re-read after the claim matches zero rows, so the operator learns which of the two happened rather than being told "conflict".

Edge Cases

• Race with the fan-out worker — a compare-and-set, not a read-then-write, so a cancel cannot appear to succeed a heartbeat after the worker committed.
• Cancelling an already-cancelled event — 409, never a silent success.
• A partially fanned-out event — fanned_out_at is written only on completion, so an event mid-fan-out is still cancellable by this predicate; the batches already committed have already queued their deliveries, and those are not withdrawn. Deliveries still queued at claim time will find the event cancelled only through the delivery status they are set to by other paths — the operator should treat a mid-fan-out cancel as partial.
• Cancelling an immediate event — technically possible in the seconds before the outbox relays it, and almost never useful.

Example Requests

curl -s -X DELETE "$API_URL/api/notification-events/0192f5c3-1111-7a10-b3d2-6f1e0c5a7b46" \
  -H "Authorization: Bearer TOKEN"

8.9 GET /api/notification-failures

Purpose

Lists notification channel jobs that failed while running — the processing dead-letter queue. This is not the same as a dead delivery: a delivery reaches dead through the row's own retry budget, while a row appears here when the BullMQ job threw on its final attempt. The two usually coincide, and the delivery row is the business record while this is the diagnostic one.

Source Evidence

Auth and Permissions

Admin JWT, JwtAuthGuard, RoleGuard, NotificationFailure_READ.

Request

Response

200, ordered failedAt DESC, id DESC.

{
  "message": "Notification failures fetched.",
  "data": [
    {
      "publicId": "0192f6d0-6666-7a10-b3d2-6f1e0c5a7b4b",
      "queueName": "notification_sms",
      "jobName": "notification_channel.send_sms",
      "jobId": "1042",
      "payloadRef": {
        "notificationDeliveryPublicId": "0192f5c6-4444-7a10-b3d2-6f1e0c5a7b49",
        "channel": "sms"
      },
      "actorId": null,
      "attempts": 1,
      "lastError": "notification delivery 0192f5c6-4444-7a10-b3d2-6f1e0c5a7b49 dead on sms: SMS_INSUFFICIENT_CREDIT",
      "replayedAt": null,
      "replayedBy": null,
      "replayJobId": null,
      "failedAt": "2026-09-10T05:58:15.500Z"
    }
  ],
  "count": 1,
  "currentPage": 1,
  "totalPage": 1,
  "errorCode": null
}

Side Effects

Reads job_failures filtered to the three notification channel queues, plus a COUNT(*) when paginated.

Error Cases

Edge Cases

• in_app is not a valid channel — it has no queue, so it can never appear here.
• Widening is impossible — the three-queue allowlist is ANDed unconditionally. A row from backup_restore or any other queue is unreachable from this surface regardless of what the caller sends, which matters because a database restore's failure must not be visible to, or re-runnable by, a clerk holding NotificationFailure_READ.
• actorId is always null — the recorder writes null; the failing job had no human actor.
• payloadRef may be null — for a job whose payload carried no delivery id. Such a row cannot be replayed.
• lastError is the thrown message, truncated to 4000 characters. It carries the delivery id, the terminal state, the channel and the redacted provider code — never a provider response body.
• Operational-email failures do not appear here — they are on notification_operational, which is outside the allowlist, and their payloadRef has a different shape.

Example Requests

curl -s "$API_URL/api/notification-failures?channel=sms&unreplayedOnly=true" \
  -H "Authorization: Bearer TOKEN"

8.10 POST /api/notification-failures/{publicId}/replay

Purpose

Re-sends a failed notification. It does not re-enqueue the original job. Instead it inserts a fresh notification_delivery row pointing at the original and schedules that through the outbox, so the original's failedAt, lastError and providerMessageId — the evidence the operator opened the screen to read — survive intact. Use it after fixing the cause: topping up SMS credit, supplying a provider key, correcting an address.

Source Evidence

Same files as 8.9, plus apps/api/src/modules/outbox/shared/outbox.service.ts and packages/db/src/schema/notification/notification-delivery.ts.

Auth and Permissions

• Auth: admin JWT. Guards JwtAuthGuard, RoleGuard. Permission NotificationFailure_UPDATE.
• actor.id is recorded as replayedBy.
• Idempotency: structural. The job_failures.replayed_at compare-and-set happens inside the same transaction, so two concurrent replays cannot both succeed.

Request

Response

201 with the claimed failure row plus the new delivery's public id.

{
  "message": "Notification failure replayed.",
  "data": {
    "publicId": "0192f6d0-6666-7a10-b3d2-6f1e0c5a7b4b",
    "queueName": "notification_sms",
    "jobName": "notification_channel.send_sms",
    "jobId": "1042",
    "payloadRef": {
      "notificationDeliveryPublicId": "0192f5c6-4444-7a10-b3d2-6f1e0c5a7b49",
      "channel": "sms"
    },
    "actorId": null,
    "attempts": 1,
    "lastError": "notification delivery 0192f5c6-4444-7a10-b3d2-6f1e0c5a7b49 dead on sms: SMS_INSUFFICIENT_CREDIT",
    "replayedAt": "2026-09-10T06:30:01.777Z",
    "replayedBy": "0192f0aa-1111-7000-8000-0123456789ab",
    "replayJobId": "0192f700-7777-7a10-b3d2-6f1e0c5a7b4c",
    "failedAt": "2026-09-10T05:58:15.500Z",
    "newDeliveryPublicId": "0192f700-7777-7a10-b3d2-6f1e0c5a7b4c"
  },
  "errorCode": null
}

replayJobId carries the new delivery's public id, not a BullMQ job id — the column is generic across the platform and this surface uses it as its own reference.

Side Effects

All inside one transaction:

• Insert a notification_delivery row: same recipientId, channel, providerTargetId, destinationHint, renderedTitle, renderedBody; status: "queued"; replayOfDeliveryId pointing at the original. Both delivery uniqueness indexes carry AND replay_of_delivery_id IS NULL, which is exactly what permits this insert even though the original still occupies the same (recipient, channel) slot.
• Insert an outbox_events row with dedupeKey: "<newDeliveryPublicId>:replay", distinct from the original enqueue's key and from a backfill's — three different dedupe keys can legitimately exist for one delivery public id, one per code path that schedules it.
• Update job_failures: replayedAt, replayedBy, replayJobId, guarded by replayed_at IS NULL.
• The original delivery row is not touched.
• Downstream: the outbox dispatcher relays the job to the channel queue, and the normal send path runs.

Error Cases

Edge Cases

• Duplicate action — the second replay is 409, and because the claim is the last statement in the transaction, the loser's delivery and outbox inserts are rolled back with it. Exactly one new delivery exists per failure row.
• Replaying a skipped_* delivery — cannot happen: a skip raises no dead letter, so no failure row exists to replay.
• Replaying after retention deleted the delivery — 404 NOTIFICATION_DELIVERY_NOT_FOUND. Retention refuses to delete an event with an unreplayed dead letter, so this only arises for an already-replayed chain or a manual deletion.
• Replaying a push delivery whose token has since been invalidated — the new delivery is created and then records skipped_no_destination, because the send path re-reads the token and requires is_active.
• The cause is not fixed — the replay fails the same way and writes a second failure row.
• Race condition — the compare-and-set is inside the transaction and last, which is what makes the rollback correct.

Example Requests

curl -s -X POST "$API_URL/api/notification-failures/0192f6d0-6666-7a10-b3d2-6f1e0c5a7b4b/replay" \
  -H "Authorization: Bearer TOKEN"

8.11 GET /api/notifications

Purpose

The admin operational feed — what the bell in the panel header reads. One row per operational event, filtered to what the caller's active role may see, newest first, with an unread count across everything visible. This is not the consumer notification centre: nothing here is addressed to a person, and the same row is seen by every operator holding its permission.

Source Evidence

Auth and Permissions

• Auth: admin JWT. Guards JwtAuthGuard, RoleGuard.
• Permission: none declared. The handler is on NO_PERMISSION_ADMIN_HANDLERS, and the service's per-row permission filter is the access control.
• A superadmin active role means no filter at all; a session with no active role sees nothing.

Request

Response

200, ordered occurredAt DESC, id DESC. No count, currentPage or totalPage.

{
  "message": "Notifications fetched.",
  "data": {
    "data": [
      {
        "publicId": "0192f810-8888-7a10-b3d2-6f1e0c5a7b4d",
        "kind": "feedback.submitted",
        "summary": "A bug report was submitted.",
        "soundClass": "soft",
        "aggregateId": "0192f7ff-9999-7a10-b3d2-6f1e0c5a7b4e",
        "occurredAt": "2026-09-10T06:41:10.220Z",
        "read": false
      }
    ],
    "unreadCount": 1
  },
  "errorCode": null
}

The payload is nested — data.data and data.unreadCount — because NotificationListDto is itself the envelope's data.

Side Effects

• Reads the caller's active-role permission set through RoleService, then notification left-joined to this caller's notification_read receipts.
• A second query for unreadCount.
• Nothing is written.

Error Cases

Edge Cases

• A session with no active role — the permission list is empty, which becomes the SQL literal false rather than "no filter". The feed is empty, matching what GET /auth/permissions reports, and the panel should send such a user to the role chooser.
• A superadmin — no permission filter at all, rather than materialising the whole catalogue into an IN (...).
• read is per caller — the left join carries userId = actor.id. Joining without it would mark a row read because somebody else read it.
• unreadCount versus the page — counted across everything visible, so it can exceed limit.
• A newly granted permission — rows that already existed become visible immediately, and unread, because the feed fans out on read. That is the property the design exists for.
• A revoked permission — those rows disappear from both the list and the count.

Example Requests

curl -s "$API_URL/api/notifications?limit=20" -H "Authorization: Bearer TOKEN"

8.12 POST /api/notifications/{publicId}/read

Purpose

Marks one operational-feed row read for the signed-in user. Read state is per person, held in a join table rather than a column, because one row is seen by everyone holding its permission — a column would let the first admin to open the bell clear it for the whole office.

Source Evidence

Same files as 8.11.

Auth and Permissions

Admin JWT, JwtAuthGuard, RoleGuard, no permission declared, allowlisted. Visibility is re-checked before the write.

Request

Response

201 with data: null.

{ "message": "Notification marked read.", "data": null, "errorCode": null }

Side Effects

Inserts a notification_read row with onConflictDoNothing on (notification_id, user_id).

Error Cases

Edge Cases

• A visible-to-someone-else row answers 404, exactly as an absent one does. Without that check anyone could mark any notification read by public id and — because the id is a uuid — confirm that a notification they may not see exists.
• Reading twice is not an error, and a race between two browser tabs is not one either.
• Marking read then losing the permission — the receipt survives; the row simply stops being visible.

Example Requests

curl -s -X POST "$API_URL/api/notifications/0192f810-8888-7a10-b3d2-6f1e0c5a7b4d/read" \
  -H "Authorization: Bearer TOKEN"

8.13 POST /api/notifications/read-all

Purpose

Clears the bell. Marks every row currently visible to this caller read, scoped by the same permission filter the list uses, so clearing never creates a receipt for a notification the caller was not shown.

Source Evidence

Same files as 8.11.

Auth and Permissions

Admin JWT, JwtAuthGuard, RoleGuard, no permission declared, allowlisted.

Request

Headers only. No params, query or body.

Response

201.

{ "message": "Notifications marked read.", "data": { "marked": 14 }, "errorCode": null }

Side Effects

Selects every visible notification.id, then a multi-row insert into notification_read with onConflictDoNothing. marked counts rows actually inserted, so already-read rows are excluded.

Error Cases

Edge Cases

• Nothing visible — returns { "marked": 0 } without issuing an insert.
• Everything already read — returns { "marked": 0 }.
• Scoping matters — a row the caller cannot see gets no receipt, which is what stops it being silently hidden if they gain the permission later.
• Unbounded write — this is the one write in the feed that touches every visible row; the table is retention-swept, which is what keeps it bounded.

Example Requests

curl -s -X POST "$API_URL/api/notifications/read-all" -H "Authorization: Bearer TOKEN"

8.14 GET /api/mobile/notifications

Purpose

The consumer notification centre — every audience, one screen. Guardians, students, teachers and staff all read the same endpoint, and the service scopes it by ownership, active role and staff liveness. Rows are the person's own notification_recipient records, rendered with the content frozen at fan-out, and only rows that actually had an in-app delivery appear.

Source Evidence

Auth and Permissions

• Auth: JWT. Guards JwtAuthGuard, RoleGuard. No permission declared, allowlisted.
• The service predicate is the only control, and it has four parts: ownership, active-role scoping, a staff-liveness re-check, and an in-app delivery EXISTS.

Request

Response

200, ordered occurredAt DESC, recipientId DESC.

{
  "message": "Notifications fetched.",
  "data": [
    {
      "publicId": "0192f5c4-2222-7a10-b3d2-6f1e0c5a7b47",
      "kind": "school.announcement",
      "category": "announcement",
      "priority": "normal",
      "title": "Sports day moved",
      "body": "It is now on Friday.",
      "actionUrl": "/announcements/0192f5c3",
      "actionLabel": "Read it",
      "occurredAt": "2026-09-10T05:58:11.004Z",
      "readAt": null
    }
  ],
  "count": 1,
  "currentPage": 1,
  "totalPage": 1,
  "errorCode": null
}

Side Effects

Two reads: the page, and a COUNT(*) over the same predicate. Nothing is written.

Error Cases

Edge Cases

• Fixed order — sort and order are accepted and ignored. The order is fixed so two events fanned out in one transaction cannot be dropped or duplicated under offset paging.
• size above 100 — clamped to 100.
• A teacher who is also a parent — viewing as Guardian, staff-audience rows are excluded, because audience_role_id must be null or equal the active role.
• A session with no active role — x = NULL is never true in SQL, so the predicate correctly narrows to rows that are not role-scoped, with no extra branch.
• A dismissed teacher who is still a parent — keeps a live users row, so ownership and active-role scoping alone would keep serving them disciplinary and roster notifications. The staff-liveness EXISTS is what stops that.
• Email-only and SMS-only notifications never appear, and neither do channels the person suppressed — the in-app EXISTS excludes skipped_preference and cancelled.
• title and body are typed nullable but are always present on a returned row; render defensively rather than asserting.
• A template edited after delivery — the row keeps the wording it was delivered with. Content is frozen at fan-out and never re-rendered here.
• Empty state — data: [], count: 0.

Example Requests

curl -s "$API_URL/api/mobile/notifications?page=1&size=20" -H "Authorization: Bearer TOKEN"

8.15 GET /api/mobile/notifications/unread-count

Purpose

The badge number. Counted across everything visible to the caller under the same four-part predicate the list uses, with read_at IS NULL added — so the badge and the list can never disagree about what counts.

Source Evidence

Same files as 8.14.

Auth and Permissions

JWT, JwtAuthGuard, RoleGuard, no permission declared, allowlisted.

Request

Headers only.

Response

200.

{ "message": "Unread count fetched.", "data": { "count": 3 }, "errorCode": null }

Side Effects

One COUNT(*). It is served by the partial index on notification_recipient (user_id) WHERE read_at IS NULL.

Error Cases

401 / 403 only.

Edge Cases

• Switching active role changes the count, because role scoping is part of the predicate.
• Zero is the normal steady state and is not an error.
• It is not capped by any page size.
• Redis being unreachable does not affect it — Postgres is the authoritative unread store; the realtime stream is only an enhancement that saves polling.

Example Requests

curl -s "$API_URL/api/mobile/notifications/unread-count" -H "Authorization: Bearer TOKEN"

8.16 POST /api/mobile/notifications/read-all

Purpose

Marks every notification currently visible to the caller read, under the same predicate as the list. Returns how many rows actually changed.

Source Evidence

Same files as 8.14.

Auth and Permissions

JWT, allowlisted, service-scoped.

Request

Headers only.

Response

201.

{ "message": "Notifications marked read.", "data": { "marked": 3 }, "errorCode": null }

Side Effects

One bounded UPDATE ... SET read_at = now() over the visible, currently-unread rows, returning their ids.

Error Cases

401 / 403 only.

Edge Cases

• Already-read rows are not touched and are not counted — the UPDATE carries read_at IS NULL.
• Nothing visible returns { "marked": 0 }.
• Role-scoped rows for a role the caller is not currently acting as are not marked, so switching role afterwards still shows them unread. That is intentional: clearing a badge in one role must not clear another's.

Example Requests

curl -s -X POST "$API_URL/api/mobile/notifications/read-all" -H "Authorization: Bearer TOKEN"

8.17 POST /api/mobile/notifications/{publicId}/read

Purpose

Marks one notification read and returns the row as the centre renders it, so a client can update a list item in place without refetching the page.

Source Evidence

Same files as 8.14.

Auth and Permissions

JWT, allowlisted. The write is scoped by the full visibility predicate, not merely user_id = actor.id.

Request

Response

201 with a NotificationCentreItemDto.

{
  "message": "Notification marked read.",
  "data": {
    "publicId": "0192f5c4-2222-7a10-b3d2-6f1e0c5a7b47",
    "kind": "school.announcement",
    "category": "announcement",
    "priority": "normal",
    "title": "Sports day moved",
    "body": "It is now on Friday.",
    "actionUrl": "/announcements/0192f5c3",
    "actionLabel": "Read it",
    "occurredAt": "2026-09-10T05:58:11.004Z",
    "readAt": "2026-09-10T07:02:19.660Z"
  },
  "errorCode": null
}

Side Effects

UPDATE notification_recipient SET read_at = coalesce(read_at, now()) scoped by the predicate, then a re-read to build the response.

Error Cases

Zero rows is a 404, never a 403: a 403 would confirm the row exists for someone else, or under a role the caller is not currently acting as.

Edge Cases

• Marking read twice — coalesce keeps the original timestamp, so readAt does not move.
• A row whose only channels were email or SMS — invisible to the centre, so 404.
• A row the person suppressed — skipped_preference is excluded by the predicate, so 404.
• Race between two devices — both succeed; the first timestamp wins.

Example Requests

curl -s -X POST "$API_URL/api/mobile/notifications/0192f5c4-2222-7a10-b3d2-6f1e0c5a7b47/read" \
  -H "Authorization: Bearer TOKEN"

8.18 POST /api/mobile/notification-devices

Purpose

Registers a push credential for the signed-in session. Mobile apps call this on launch and after every token rotation; a browser calls it with platform: "web" after the user grants notification permission. The token is bound to the session's user, never to anything in the body, and registering a token that already belongs to somebody else invalidates their row rather than moving it.

Source Evidence

Auth and Permissions

• Auth: JWT. Guards JwtAuthGuard, RoleGuard. No permission declared, allowlisted.
• user_id is never taken from the body. RoleGuard runs no permission check here, so keying every write on actor.id is the only remaining control.

Request

{ "token": "fcm-registration-token-value", "platform": "android" }

Web push:

{ "token": "BNc9...browser-subscription-token", "platform": "web" }

Response

201.

{
  "message": "Device registered.",
  "data": {
    "publicId": "0192f900-aaaa-7a10-b3d2-6f1e0c5a7b50",
    "platform": "android",
    "createdAt": "2026-09-10T07:10:44.019Z"
  },
  "errorCode": null
}

The token is never echoed back.

Side Effects

One transaction, with three cases:

No jobs, no realtime, no external calls. Future push sends read the active tokens for a user, so the effect on delivery is immediate for the next fan-out.

Error Cases

Edge Cases

• Re-registering the same token — a touch, and a 201 with the original createdAt. Not a new device.
• The cap is a refusal, not an eviction — the caller learns the limit rather than losing a device it never asked to remove.
• A token arriving for a second user is invalidated with reason replaced, never reassigned in place. Reassignment would destroy the record that the first user ever held it and would, on its own, be a denial of service: anyone who learns a victim's token — a shared school tablet, a resold device, a sibling — could POST it and silently stop the victim's push, including the security notifications that cannot otherwise be switched off.
• Web push has no user_device row, so user_device_id is null. A browser has no installation.
• Platform matters at send time: web gets FCM's webpush block with a TTL header and, when the notification's action URL is https, fcmOptions.link — the only thing that decides what a click opens when every tab is closed. android and ios get the plain notification block and read data.actionUrl in their own handler.
• A token FCM later declares dead is deactivated automatically by the send path with reason unregistered or invalid_argument; the app should simply re-register on next launch.
• Long-invalidated rows are pruned after NOTIFICATION_PUSH_TOKEN_RETENTION_DAYS (180).