Module notifications 

notifications.* method types — paginated history + ack + push for incoming notifications.

The notification lifecycle (SPEC §2.12.8 emergency example):

1. Operator publishes via backend HTTP API → backend writes to NATS NOTIFICATIONS JetStream.
2. Agent consumes the stream, fans out to connected clients via notifications.new push.
3. User clicks “確認” → client sends notifications.ack → agent writes notifications_read KV (keyed by {pc_id}.{user_sid}.{notification_id}) AND publishes events.notifications.acked.{pc_id}.{user_sid}.{notification_id} so the SPA can show per-user confirmation status.
4. Past notifications stay queryable via notifications.list — that’s the recovery path when the agent missed a push during a network blip.

Structs

Notification

Notification body — used both for NotificationsListResult entries and the NotificationNewParams push.

NotificationAckEntry

One recipient’s confirmation record for a notification.

NotificationAckStatus

Response of GET /api/notifications/{id}/ack_status — every (pc_id, user_sid, acked_at) tuple recorded for the notification, powering the SPA’s “who confirmed when” view.

NotificationAcked

Body of the events.notifications.acked.{pc_id}.{user_sid}.{notif_id} event the agent publishes when a user acks a notification. The backend’s notification-acks projector reads these fields from the JSON body (not by parsing the subject) so an id / SID containing a . can’t desync the projected row from its subject tokens.

NotificationDetail

Response of GET /api/notifications/{id} — one sent notification’s full content (so the SPA can show “what was sent”, including the body the history table truncates away) paired with its per-recipient confirmation list. Powers the deep-linkable /notifications/{id} detail page, which an operator opens in a new tab from the history list (Ctrl/⌘ click), mirroring the Activity → result-detail deep link.

NotificationNewParams

Push payload for notifications.new. The full notification body inline — no second round-trip needed.

NotificationsAckParams

notifications.ack params — mark this notification read for the caller’s user (SID derived from the OS at connect time, NOT from the payload). SPEC §2.12.4 forbids ack-ing other users’ notifications even on a shared PC — the agent rejects with Unauthorized if the notification’s audience doesn’t include the caller.

NotificationsAckResult

notifications.ack response — confirms the agent persisted the ack and published the events.notifications.acked.> event.

NotificationsListParams

notifications.list params — paginated history of notifications this user has received (per-user, scoped via OS SID).

NotificationsListResult

notifications.list response.

NotificationsSubscribeParams

NotificationsSubscribeResult

NotificationsUnsubscribeParams

PublishNotificationRequest

Operator-facing request body for POST /api/notifications (and the equivalent notifications/*.yaml manifest, SPEC §2.4.1). The backend mints the Notification::id (when id is omitted) and Notification::issued_at, resolves target into the notifications.{all|group.X|pc.Y} fan-out subjects, and publishes one Notification per resolved subject into the NOTIFICATIONS stream.

PublishNotificationResponse

Response of POST /api/notifications — the minted/echoed id plus the subjects the notification fanned out to, so the operator UI can confirm the resolved audience.

Enums

NotificationPriority

Severity ladder. Drives the SPA color, toast/dialog choice, and whether the Client App grabs window focus on push arrival. #[non_exhaustive] so a future SPEC can add severities (e.g. Critical above Emergency) without a wire bump.

NotificationsFilter

History-list filter selector.