Notices - API Reference

Audience: Frontend engineers, mobile/panel engineers, backend engineers, QA, and API consumers. Scope: Admin CRUD, publication, delivery/recipients, attachments, categories, templates, and the audience-facing Notice Centre (/api/mobile/portal/notices).

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

This list is exhaustive against apps/api/test/structure/structure.baseline.json — 34 concrete routes, no aliases omitted. notices and notice-delivery share the notices root path across two separate controllers (NoticeController, NoticePublicationController, NoticeDeliveryController); none of their sub-paths collide.

5. Auth, Identity, and Permissions

There is no guest or public access anywhere in this module — every route sits behind the global JwtAuthGuard with an explicit permission. NoticeCentreController needs no entry in NO_PERMISSION_ADMIN_HANDLERS because every one of its handlers carries @Permissions().

Every :publicId, :attachmentPublicId, and :deliveryPublicId route parameter across every controller in this module is decorated with ParseUUIDPipe, so a malformed id fails validation as a 400 before the handler runs, rather than reaching a query that could never match.

6. DTO and Model Reference

6.1 NoticeListItemDto / NoticeDto (response)

6.2 CreateNoticeDto (request body)

6.3 UpdateNoticeDto (request body)

Same content fields as create, all optional, plus version (required — the concurrency token). audience/channels/priority/publishAt are accepted structurally but rejected by the service with NOTICE_PUBLICATION_PARAMS_IMMUTABLE unless the notice is still draft.

6.4 UpdateNoticeExpiryDto

6.5 AudiencePreviewRequestDto / NoticeAudiencePreviewDto

Request: { audience: object } (same AudienceSpec shape). Response: { total, capped, byKind: [{ kind, count, capped }] } — writes nothing.

6.6 NoticePeopleQueryDto / NoticePersonDto

Query: search (string, 2-100 chars, required), kind (optional, student|guardian|staff). Response array item: { userPublicId, name, kind, detail } — at most 20 rows.

6.7 PublishNoticeDto / NoticePublicationResultDto

Request: { version: string, publishAt?: Date, expiresAt?: Date }. version is required — the row version the caller loaded the notice at (digits only, ^\d{1,19}$); a stale value refuses with 409 NOTICE_VERSION_CONFLICT. Absent publishAt means "now" (within ~5s via the outbox). Response: { publicId, publishAt, dispatchSeq }.

6.8 NotifyNoticeUpdateDto

{ note?: string } (≤200 chars) — internal only, never sent to recipients. Response: { dispatchSeq } wrapped in the same NoticePublicationResultDto shape by the controller (with publishAt reflecting the notice's existing schedule).

6.9 NoticeCategoryDto / Create/UpdateNoticeCategoryDto

Response additionally carries publicId, isSystem (never accepted from a caller), createdAt/updatedAt/deletedAt.

6.10 NoticeTemplateDto / Create/UpdateNoticeTemplateDto

NoticeTemplateRenderDto (response of the render endpoint): { title, contentHtml, summary, priority, categoryId, defaultChannels } — tokens substituted, sanitised.

6.11 NoticeAttachmentDto / NoticeAttachmentUploadDto

Upload is multipart/form-data, field file. Response: { publicId, kind, originalName, mimeType, sizeBytes, isPrimary, sortOrder, createdAt } — never storageKey.

6.12 Notice Centre DTOs

ListNoticeCentreQueryDto: unreadOnly?, categoryId?, priority?, includeExpired? (default excludes expired/archived). NoticeCentreListItemDto: { publicId, title, summary, priority, category: {publicId,name,colorToken}, publishAt, expiresAt, isRead, matchedFor: MatchedForDto[], primaryAttachmentPublicId }. NoticeCentreDetailDto extends it with contentHtml, contentText, actionUrl, actionLabel, channels, publishedAt, readAt, attachments: NoticeCentreAttachmentDto[]. UnreadCountDto: { count }.

6.13 Delivery DTOs

ListNoticeRecipientsQueryDto: pagination only. NoticeRecipientsPageDto: { retained: boolean, recipients: NoticeRecipientDto[] }. NoticeRecipientDto: { recipientPublicId, userPublicIdSnapshot, name (nullable), readAt (nullable), deliveries: NoticeRecipientDeliveryDto[] }. NoticeRecipientDeliveryDto: { publicId, channel, status }. NoticeDeliveryStatsDto: { noticePublicId, dispatchPublicId (nullable), source: "live"|"snapshot", recipientsAtPublish, readCount, unread, channels: ChannelDeliveryStatsDto[] }. ChannelDeliveryStatsDto: { channel, sent, delivered, failed, skipped }.

7. Enum Reference

8. Endpoint Reference

Representative endpoints are detailed below; every route in §4 follows the same guard/DTO/error pattern documented in the backend doc.

8.1 GET /api/notices

Purpose

Lists notices for the admin authoring surface, with status/priority/category/audience-kind/creator-name/publish-date filters. Used by the notices list screen.

Source Evidence

Auth and Permissions

• Auth: JWT — Guard chain: JwtAuthGuard, RoleGuard — Permission: Notices_READ — Guest support: No — Idempotency: N/A (read)

Request

Query: status?, priority?, categoryId? (category's publicId), audienceKind?, createdByName?, publishedFrom?/publishedTo? (ISO 8601; a date-only YYYY-MM-DD is the whole school day in Asia/Kathmandu — from its first instant, to its last — while a full timestamp is used as given), deleted? (boolean), plus inherited pagination/search/sort.

deleted=true lists only soft-deleted notices — the view a restore is made from. Omitting it, or passing false, lists live notices only; the two views never overlap. This is the list an admin screen drives a "Deleted notices" tab from: filter with ?deleted=true, then call POST /notices/:publicId/restore on the row to bring it back. The admin-list cache key includes the flag, so the two views never share a cached page.

Response

{
  "success": true,
  "message": "Notices fetched.",
  "data": [{ "publicId": "...", "title": "...", "status": "published" }],
  "metadata": { "count": 42, "page": 1, "size": 20 }
}

Side Effects

None — a read.

Edge Cases

Empty result set returns data: [] with count: 0. pagination=false (not the module's default and not forbidden here — see backend cache/pagination notes) is bounded by PaginationUtil.UNPAGINATED_HARD_CAP.

8.2 GET /api/notices/summary

Dashboard tiles: { total, draft, scheduled, published, archived, recipientsToday, readCount, recipientsAtPublish }. Every figure is a fresh aggregate, never a stored counter. Declared before :publicId in the controller so Nest does not resolve summary as a uuid param.

8.3 GET /api/notices/audience/people

Name search (≥2 characters) over pupils, parents, and staff, returning each match's userPublicId for use in a users audience. At most 20 rows. kind optionally narrows to student|guardian|staff.

8.4 POST /api/notices/audience/preview

Writes nothing. Resolves an AudienceSpec to per-kind counts and a total, each with its own capped flag when the walk hit its bound before exhausting a kind.

8.5 POST /api/notices

Purpose

Creates a notice. Always a draft, regardless of whether publishAt is supplied.

Auth and Permissions

Notices_CREATE.

Request

{
  "title": "Exam Schedule Released",
  "contentHtml": "<p>The mid-term schedule is now available.</p>",
  "categoryId": "6f1a...-uuid",
  "priority": "high",
  "audience": { "kind": "all_users" },
  "channels": ["in_app", "push"]
}

Response

201, body is a full NoticeDto.

Side Effects

Writes notices and notice_audience_targets; invalidates the admin list cache.

Error Cases

Example Requests

curl -X POST "$API_URL/api/notices" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Exam Schedule","contentHtml":"<p>...</p>","categoryId":"...","priority":"high","audience":{"kind":"all_users"},"channels":["in_app"]}'

8.6 GET /api/notices/:publicId

Returns the full NoticeDto, including audience, attachments, and every content field. Notices_READ. 404 NOTICE_NOT_FOUND if missing or soft-deleted.

8.7 PATCH /api/notices/:publicId

Notices_UPDATE. Requires version. Content fields editable on any non-archived notice; audience/channels/priority/publishAt editable only while draft.

8.8 DELETE /api/notices/:publicId

Notices_DELETE. Soft delete. 204-equivalent envelope with data: null. Refused with 409 (assertNoLivePublishClaim) while a publish lease is currently held. When the notice is scheduled, its pending publish outbox row is marked dead and its status is reset to draft in the same transaction as the soft delete, so a deleted notice never has a live publish job racing it.

8.9 POST /api/notices/:publicId/restore

Notices_RESTORE. Clears deletedAt. Returns the restored NoticeDto. The panel drives a restore from the ?deleted=true list view. A notice that was scheduled when it was deleted comes back as a draft — remove reset its status and cancelled its pending publish outbox row before soft-deleting it, so a restore never resurrects a publish that was already withdrawn.

8.10 POST /api/notices/:publicId/archive

Notices_UPDATE. Legal only from status = published. 409 NOTICE_NOT_PUBLISHED for any other status — a scheduled notice, a draft that was never published, or an already-archived notice — with a message naming the specific reason. Also refused while a publish lease is currently held.

8.11 POST /api/notices/:publicId/duplicate

Notices_CREATE. 201. New draft; every publication field cleared; duplicatedFromId set.

8.12 PATCH /api/notices/:publicId/expiry

Notices_UPDATE. Requires version. An archived notice returns to published only when all three hold: it is currently archived, its publishedAt is set (proof it was actually delivered), and the new expiresAt is in the future.

8.13 POST /api/notices/:publicId/publish

Purpose

Publishes immediately or schedules for later. Frontend calls this after a draft is complete and reviewed.

Auth and Permissions

NoticePublish_CREATE.

Request

{ "version": "3", "publishAt": "2026-10-01T03:15:00.000Z", "expiresAt": "2026-10-15T03:15:00.000Z" }

version is required — the row version the caller loaded the notice at. publishAt/expiresAt are optional; absent publishAt publishes as soon as the outbox dispatches (within ~5s).

Response

{
  "success": true,
  "message": "Notice queued for delivery.",
  "data": { "publicId": "...", "publishAt": "2026-10-01T03:15:00.000Z", "dispatchSeq": 1 }
}

Side Effects

notices.status → scheduled, dispatch_seq incremented, outbox_events row written, notice_runtime row created (unclaimed). The worker later flips status to published, resolves the audience, calls NotificationService.send(), and writes one notice_dispatches row.

Error Cases

The version check runs first, inside the row lock, before any other publish rule — the version mismatch and the caller's stale copy both need surfacing before spending a check on rules that only matter if the caller's copy is current.

8.14 POST /api/notices/:publicId/unpublish

NoticePublish_CREATE. Legal only before delivery. 409 NOTICE_ALREADY_DELIVERED once resolved; 409 NOTICE_NOT_PUBLISHED for a draft. On success, data: null.

8.15 POST /api/notices/:publicId/notify-update

NoticePublish_UPDATE. Legal only for status = published. Optional { note? } (internal only). Response mirrors the publish result shape with the incremented dispatchSeq. 409 NOTICE_NOT_PUBLISHED otherwise.

All three attachment-write endpoints below resolve the notice through requireEditableNotice, which refuses 409 NOTICE_ARCHIVED_IMMUTABLE once the notice is archived — an archived notice's content is frozen, and its attachments are part of that content.

8.16 POST /api/notices/:publicId/attachments

Notices_UPDATE. multipart/form-data, field file. 201, body is NoticeAttachmentDto. 409 NOTICE_ATTACHMENT_LIMIT_EXCEEDED past 20 attachments — checked once as a fast refusal before the upload, and again inside the insert transaction under a row lock on the notice, so two concurrent uploads to the same notice cannot both insert the 20th. 400 NOTICE_ATTACHMENT_TYPE_FORBIDDEN on a rejected or empty file. 409 NOTICE_ARCHIVED_IMMUTABLE on an archived notice.

8.17 DELETE /api/notices/:publicId/attachments/:attachmentPublicId

Notices_UPDATE. 404 NOTICE_ATTACHMENT_NOT_FOUND unless the pair (notice, attachment) both resolve. 409 NOTICE_ARCHIVED_IMMUTABLE on an archived notice.

8.18 PATCH /api/notices/:publicId/attachments/:attachmentPublicId/primary

Notices_UPDATE. 409 NOTICE_PRIMARY_IMAGE_NOT_AN_IMAGE for a document. 409 NOTICE_ARCHIVED_IMMUTABLE on an archived notice. Clears any prior primary and sets the new one under a row lock on the notice in the same transaction — two concurrent primary-swap requests are serialised by the lock; the rare case where both still collide on notice_attachments_primary_unique is mapped to 409 NOTICE_VERSION_CONFLICT rather than a bare, unnamed constraint error.

8.19 GET /api/notice-attachments/:attachmentPublicId

Purpose

Streams an attachment's raw bytes. Used for both the admin editor preview and every Notice Centre inline image/document link.

Auth and Permissions

• Auth: JWT — Permission: NoticeView_READ — Guest support: No.
• Never signed. Authorized per-request by NoticeVisibilityService.requireVisibleNotice, or bypassed for a caller who separately holds Notices_READ (administrator preview).

Response

Raw bytes, Content-Type from the stored mime type, Cache-Control: private, max-age=3600, Content-Disposition: inline.

Error Cases

8.20-8.25 Notice Categories

Standard CRUD at /api/notice-categories (NoticeCategories_READ/_CREATE/_UPDATE/_DELETE/_RESTORE), plus GET /:publicId. remove refuses a system default (NOTICE_CATEGORY_SYSTEM_IMMUTABLE) or one still referenced by a notice (NOTICE_CATEGORY_IN_USE, since the FK is ON DELETE RESTRICT). Slugs are unique only among live rows, so a retired slug is reusable — but restore can then collide, surfaced as 409 NOTICE_CATEGORY_SLUG_ALREADY_EXISTS rather than a bare 500. GET /api/notice-categories orders by sortOrder ascending (then id) by default; pass sort=name or sort=sortOrder explicitly to override. The Redis reference cache is used only for the default, unsorted listing — an explicit sort bypasses it.

8.26-8.32 Notice Templates

Standard CRUD at /api/notice-templates (NoticeTemplates_READ/_CREATE/_UPDATE/_DELETE/_RESTORE), plus GET /:publicId/render.

GET /api/notice-templates/:publicId/render substitutes {{schoolName}}, {{sessionName}} and {{date}} (in the school's own timezone) in both the title and content, sanitises the result with the identical configuration notice content uses, and derives a summary the same way a new notice would. An unresolvable token (outside that closed set) is left literal rather than stripped or erroring. remove refuses a system default with NOTICE_TEMPLATE_SYSTEM_IMMUTABLE. GET /api/notice-templates orders by sortOrder ascending (then id) by default, overridable with sort=name/sort=sortOrder, on the same caching rule as categories.

Both GET /api/notices/:publicId/recipients and GET /api/notices/:publicId/delivery below report on the latest dispatch whose reason = 'published' — never a notify-update dispatch, which carries no recipient count or delivery rows of its own.

8.33 GET /api/notices/:publicId/recipients

NoticeDelivery_READ. Returns { retained, recipients } — retained: false with an empty array once the dispatch's notification_event has been pruned at the 30-day retention horizon, distinct from "nobody was addressed".

8.34 GET /api/notices/:publicId/delivery

NoticeDelivery_READ. Returns NoticeDeliveryStatsDto. source: "live" reads notification_delivery directly; source: "snapshot" reads the frozen delivery_stats captured before the retention prune. Zeros (not a 404) for a notice never dispatched.

8.35 POST /api/notices/:publicId/deliveries/:deliveryPublicId/retry

NoticeDelivery_UPDATE. Resolves the delivery through this notice's own dispatches first — 404 NOTICE_DELIVERY_NOT_FOUND if the delivery does not belong to this notice — then delegates to the shared dead-letter replay. 409 NOTICE_DELIVERY_NOT_RETRYABLE when no matching un-replayed job_failures row exists on QueueName.NOTIFICATION_EMAIL/_SMS/_PUSH.

8.36 GET /api/mobile/portal/notices

Purpose

The Notice Centre list — every audience (staff, teacher, pupil, guardian) reads their own notices through this one endpoint.

Auth and Permissions

NoticeView_READ. The WHERE clause, built from NoticeVisibilityService.membershipsFor, is the actual control — not the permission.

Request

Query: unreadOnly?, categoryId?, priority?, includeExpired? (default excludes archived/expired), plus pagination.

Response

{
  "success": true,
  "message": "Notices fetched.",
  "data": [{
    "publicId": "...",
    "title": "Exam Schedule Released",
    "isRead": false,
    "matchedFor": [],
    "category": { "publicId": "...", "name": "Academic", "colorToken": "primary" }
  }],
  "metadata": { "count": 3, "page": 1, "size": 20 }
}

Edge Cases

Deliberately not cached — read-your-writes matters more here than a cache hit, since a reader typically opens a notice (which marks it read) and returns to the same list immediately.

8.37 GET /api/mobile/portal/notices/unread-count

NoticeView_READ. { count }. Cached (CACHE_TTL.VOLATILE), invalidated on every mark-read/mark-unread for that user.

8.38 GET /api/mobile/portal/notices/:publicId

NoticeView_READ. Full NoticeCentreDetailDto. Never marks the notice read — the client fires the separate read call on mount. 404 NOTICE_NOT_FOUND if the caller cannot see it (never 403 — the id space must not become an enumeration oracle).

8.39 POST /api/mobile/portal/notices/:publicId/read

NoticeView_READ. Writes notice_reads (durable) and best-effort mirrors notification_recipient.read_at so the notification bell agrees, in one transaction that re-runs the visibility check.

8.40 DELETE /api/mobile/portal/notices/:publicId/read

NoticeView_READ. Symmetric mark-unread; deletes the notice_reads row and clears the mirrored read_at.

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence (publish)

9.3 Error Branch

10. Pagination, Sorting, Filtering, and Search

GET /api/notices/audience/people and POST /api/notices/audience/preview are not paginated list endpoints — the former is hard-capped at 20 rows, the latter returns aggregates only.

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

See §4 (API Surface Map) for the full route list with controller, permission, and purpose; §8 for the per-endpoint detail including DTOs, cache/job/error behaviour. Every @Get/@Post/@Patch/@Delete in every controller listed in §1's Documentation Evidence table is represented — 34 routes total, matching jq -r '.routes.all[]' apps/api/test/structure/structure.baseline.json | grep -i notice.

13.2 Request/Response Exhaustiveness

Minimal and full request bodies are shown for the create, publish, and update-category endpoints in §8 as representative examples; every other endpoint's body shape is fully enumerated in §6. Empty-list responses follow the standard pagination envelope with data: []. Validation errors follow the framework's standard 400 shape with errorCode from ErrorCodes. Domain errors are enumerated per-endpoint in §8 and exhaustively in the backend doc's §13.

13.3 API Diagram Pack

Covered in §9 (route ownership, request sequence, error branch). A dedicated cache-flow and async-flow diagram for the publish path is in the backend doc §8-9.

13.4 Consumer Integration Notes

13.5 API Tradeoffs and Rationale

See features/flows doc §12.4 for the full tradeoff table (async publication, live-spec audience vs. snapshot, dual read-state writes, single Notice Centre permission).

13.6 API Change Impact

14. Zero-Omission API Checklist

• Every controller route is documented (§4, §8).
• Every parent route prefix and runtime URL is documented.
• Every DTO field, enum, default, and validator is documented (§6-7).
• Every response field and omitted raw field (storageKey) is documented.
• Every auth, guard, and permission is documented (§5).
• Every success, validation, auth, not-found, and conflict branch is documented (§8, backend §13).
• Every DB write, cache effect, queue job, and notification is documented (§9, §11).
• Representative examples are given for create, publish, and category flows.
• Route, sequence, and error diagrams are included (§9).
• Tradeoffs are documented (§13.5, cross-referenced).
• Links to backend and features/flows docs are present.

15. Integration Checklist

• Every route from controllers is documented.
• Every DTO field is documented.
• Every enum value is documented.
• Every response envelope is documented.
• Every error code is documented (backend §13, cross-referenced).
• Every auth guard and permission is documented.
• Every cache key, queue job, and external call is documented.
• Diagrams match the current code.
• Links to backend and features/flows docs are present.

See Also

• Backend doc: /docs/developer/notices/backend
• Features and flows doc: /docs/developer/notices/feature