08 — Form Specifications (Notifications Module)
- 1. Implicit Inputs (no form UI)
- 2. Admin Manual-Send Form
(planned) - 3. Notification Preferences Form
(planned) - 4. Form Rules Summary
Notifications are system-generated — there is no user-facing creation form in v1. The only user inputs are implicit (taps/actions) and two query params. This file documents those plus the (planned) admin form, since a send endpoint is named in the blueprint.
1. Implicit Inputs (no form UI)
1.1 List query — GET /api/v1/notifications
| Param | Type | Constraints | Default | Source |
|---|---|---|---|---|
page | int | ≥ 1 | 1 | list-notifications.dto.ts:6-11 |
limit | int | 1..100 | 20 | list-notifications.dto.ts:13-19 |
unreadOnly | bool | true/'true' coerced | absent | list-notifications.dto.ts:21-25 |
Invalid params → 400 via global validation pipe (main.ts). Client never sends
unreadOnly=false (omit instead).
1.2 Read actions (no payload)
PATCH /api/v1/notifications/:id/read—:idis a Mongo ObjectId.PATCH /api/v1/notifications/read-all— empty body.- Ownership: cross-user
:id→200 null(notifications.service.ts:54-59), treated as no-op client-side.
2. Admin Manual-Send Form (planned)
Endpoint exists only in the blueprint — POST /api/v1/notifications/send
(internal/service) (Notifications.md:24). Design when notification.send
enters ALL_PERMISSIONS (currently absent — permissions.constants.ts).
| Field | Type | Rules (proposed, from blueprint semantics) |
|---|---|---|
type | select | from server enum; unknown → 400 |
title | text | required, ≤ 120 chars |
body | textarea | required, ≤ 500 chars |
recipientIds | multi-select | ≥ 1 user; tenant-scoped |
data | JSON | optional, opaque (schema:28-29) |
| submit | — | async via BullMQ, never sync (Notifications.md:57) |
3. Notification Preferences Form (planned)
GET/PATCH /api/v1/notifications/preferences (Notifications.md:27-28); the
notification_preferences collection does not exist yet (Notifications.md:7).
| Field | Type | Rules (proposed) |
|---|---|---|
| channel toggles (email/push/in-app) | switches | per-user, per-type optionality |
| Save | — | PATCH with partial update; optimistic UI |
4. Form Rules Summary
- v1 shipped forms: none. All mutations are idempotent-ish actions; do not build form scaffolding for planned screens (01 §6, ponytail).
- Validation mirrors server DTOs — client pre-validates only
page/limitbounds to avoid 400 round-trips.