Notification contract

Publishing a notification

A publisher sends one request per event. NovaBell fans it out to the requested channels.

{
  "channel": ["email", "in_app"],
  "to": {
    "subscriberId": "b6f2c1de-4a55-4a1e-9a3c-2f0e5d7a1c44",
    "email": "user@example.com"
  },
  "scope": "user",
  "severity": "info",
  "template": "iam/account-created",
  "data": { "accountName": "my-account" },
  "actionUrl": "/admincenter/accounts/b6f2c1de-4a55-4a1e-9a3c-2f0e5d7a1c44"
}

Field

Type

Required

Meaning

channel

string[]

yes

Any of email, in_app.

to.subscriberId

string

yes

The recipient. For scope: "user" this is the human’s subject identifier; for scope: "tenant" it is the Account identifier the notification belongs to.

to.email

string

when channel includes email

Destination address.

scope

"user" | "tenant"

no — defaults to user

user addresses one person. tenant addresses everyone who reads that Account’s feed.

severity

"info" | "warning" | "error" | "critical"

no — defaults to info

Drives severity routing and filtering in the reader. It is NOT a priority: severity alone never makes a notification mandatory.

canonicalRef

{publicationId, revisionId}

no

Source-owned canonical identity for a linked article/bulletin. The reader syncs its news read state on these ids — never on title or URL text. Stored with the record; reading or dismissing a notification never resolves or mutates the source item.

required

boolean

no — defaults to false

Source-declared mandatory classification. A required notification ALWAYS persists its in-app record — the recipient’s global mute, category opt-out and quiet hours cannot silence it out of the inbox. The email channel stays user-suppressible either way. Only the workflow that owns the underlying action should set this.

template

string

yes

A template identifier in <namespace>/<name> form — see Templates.

data

object

no

Variables interpolated into the subject, the in-app title, and the email body. Must be an OBJECT of variables — a string, number, array or null is refused with 400 (passed through, it would reach the renderer as a context of indexes/characters and fabricate values).

actionUrl

string

no

Where the notification leads. A console-relative path is correct here; NovaBell absolutizes it against the console base when it renders the email. Checked against the link policy below.

eventId

string

no

Source-owned identity for THIS logical event. Supplying it makes the send idempotent under the key (eventId, recipient, requested channel set): a retry replays the first attempt’s outcome instead of delivering again. See below.

Categories and locale

GET /api/notifications/categories lists the notification categories the console’s filter UI offers. Each row carries the stored display_name map ({"en": …, "zh-CN": …, "ja": …}) and a server-resolved displayName string, so every reader applies the same fallback instead of its own:

  1. the requested locale — ?locale=<tag>, else the first Accept-Language tag;

  2. that tag’s primary subtag (zh-TW → zh);

  3. en;

  4. the first usable value in the map;

  5. the category id.

Steps 4–5 exist so that a category with an incomplete or malformed name is still listed — under its id — rather than turning the filter UI into an error.

Correlation, region and versioning

Three things the contract DEFINES rather than leaves implied:

  • correlationId (optional) — the caller’s own handle for this request (a workflow run id, a request id, a ticket key). Opaque to NovaBell: it is never parsed, never stored on the row, and never used for authorization or deduplication (that is eventId’s job — the two are deliberately separate). When supplied, it is echoed verbatim in the response body ({…, correlationId}) and carried on this request’s log lines, so an operator can join the publisher’s record to NovaBell’s. Omit it and the response has no correlationId member at all — absent, not null.

  • sourceRegion (optional) — the region the publisher declares as its source. The platform is single-region today (ap-northeast-1, Tokyo): this field is the declaration of that fact, not a routing table — nothing routes on it. A sender that omits it is assumed local; a sender that declares a region outside the platform’s allow-list is refused with 422 {"error":"Unsupported source region","issue":{"code":"unknown_region", "field":"sourceRegion","region":…,"allowed":[…]}} — because a region claim that silently passes is a claim nobody can trust.

  • Versioning — the wire schema fragments are v1 (notifications/v1/* in the schemas repo, regenerated, never hand-edited). Templates are identified by source-controlled name (<namespace>/<name>, e.g. iam/account-created) and a template’s change ships with the service release, so there is no runtime template-version axis to negotiate; templates live in NovaBell’s own source (kept separate from OrbitCast content and ThingLab Templates) and there is no template-editor surface.

Who may list categories

GET /api/notifications/categories is a console surface: the caller is either a signed-in console user (validated against their account context — a platform-admin’s realm IS its scope, so it needs no marker) or an allow-listed service caller (a workload has no human account context to declare). Both shapes answer the same listing.

Live updates (SSE)

The console keeps an open stream for new notifications. Two calls, in order:

  1. POST /api/notifications/stream/auth — with the caller’s normal bearer (and the X-Account-Id marker a tenant sends). Answers 204 with Set-Cookie: novabell_stream=…; HttpOnly; Secure; SameSite=Strict; Path=/api/notifications/stream (one-hour TTL). The cookie is signed and bound to the resolved context — the subject, the account scope, and the audience — so a cookie minted for one account cannot open a stream for another. Never put a token in a URL: EventSource cannot set headers, which is exactly why this short-lived cookie exists.

  2. GET /api/notifications/stream — replays the cookie, receives event: notification frames.

Frame

Meaning

{"type":"created","scope":"user"|"tenant","notification":{…}}

A new notification. scope tells the reader whether it belongs to them alone or to the account.

{"type":"dismiss","scope":"user","id":"<uuid>"}

A dismissal by the reader themselves (dismissal is per-user state, so it is never sent to anyone else).

Reconnect and missed events. The stream is a convenience, not a source of truth: it does not retry, buffer or replay. On reconnect — and whenever a frame carries an id you have not seen — the authoritative recovery is a feed + unseen/count refetch, and deduplication is by notification id. A dropped frame therefore shows up as a gap the next refetch closes, never as a stale inbox presented as empty.

Retries and idempotency

A publisher that retries — its own loop, an at-least-once queue, a crash between send and record — should send an eventId and reuse it for every retry of the same logical event. The channel set is a SET: ["in_app","email"] and ["email","in_app"] are the same key, so a reordered retry replays.

The retry sees

Status

Meaning

X-Event-Replay: true

the FIRST attempt’s status and body (201 sent / 200 dropped / 500 failed)

Nothing was dispatched again; the outcome is the first attempt’s.

—

409

A first attempt for this exact key is still in flight. Do not record an outcome; retry later.

—

400

eventId present but not a non-empty string.

Omitting eventId keeps the pre-150-W18 behaviour exactly (nothing is deduplicated, no receipt is written). A send that fails and is retried with the same eventId replays the failure rather than silently re-sending — a retry that must re-attempt has to be a NEW logical event with a new id.

Delivery outcomes

The response reports the outcome of EACH requested channel under channels. The vocabulary is exact and the values are never conflated:

Outcome

Meaning

persisted

An inbox record exists. This is NOT “read”, and NOT task completion — the owning workflow remains the authority for resolution.

dispatched

The channel’s transport accepted the payload. Delivery itself is not guaranteed.

dropped

Suppressed by an explicit rule; reason names it (globalMute, category-disabled, quiet-hours, no-recipient).

failed

The channel errored; reason names the stage (smtp, db, render).

The response status summarises them:

Status

Body

Meaning

201

{"status": "sent", "channels": {…}}

The request produced a durable effect — an inbox record and/or a channel dispatch. A sibling channel may still be failed; read channels.

200

{"status": "dropped", "reason": "…", "channels": {…}}

Every requested channel was suppressed by a preference. A normal result, not an error — do not retry.

500

{"error": "…", "channels": {…}}

Nothing was persisted and nothing was dispatched.

Preferences are consulted only for scope: "user": one person’s mute cannot silence a tenant-wide notification.

When preferences cannot be READ, delivery wins. An unreadable preferences lookup (timeout, network failure, a 4xx/5xx, or a misconfigured client) DELIVERS the notification and reports the failure: suppression is a preference, and losing a notification to a preferences outage is the worse outcome. The polarity is part of the contract — it is pinned by an arm, so a future change to fail-closed is a deliberate, visible decision rather than a side effect. A persistent failure is counted and reported, because the failure mode this guards against is not a notification too many — it is a user’s mute quietly ceasing to work with nothing saying so. A required notification is exempt for its in-app record: under mute, category opt-out or quiet hours the 201 still carries in_app.outcome: "persisted" while the email channel reports its dropped reason. Quiet hours discard an optional send rather than delaying it — there is no delay queue, so a delayed-delivery option must not be offered in any interface.

Failures

Status

Meaning

400

Missing channel, to.subscriberId or template; or an invalid scope, severity or required value.

401

Missing, invalid or expired token.

403

The caller is not an authorized publisher, or the authorization decision denied the send.

500

Nothing was persisted and nothing was dispatched; channels names each channel’s failure.

502

The authorization service could not be reached. NovaBell fails closed: it denies rather than delivers.

An invalid severity rejects the whole request rather than silently dropping the filter. A partially applied filter is worse than a rejected one, because the reader’s severity routing cannot tell the difference between “no matches” and “the filter was ignored”.

Reading the feed

A console client calls these paths with the signed-in human’s bearer token and an X-Account-Id header carrying the current context. Every route below is available under the /api/notifications prefix; a browser client reaches the same family through /browser/shared/v1/notifications/..., which the console gateway rewrites to it.

Method and path

Purpose

GET …/feed

Paginated inbox. ?limit=1..100, ?cursor=<opaque> (below), ?read=, ?severity=, ?include_dismissed=.

GET …/feed/:id

ONE notification the caller may see: their own record, or one of the active account’s records. Anything else is a plain 404 — the endpoint never reveals whether a foreign id exists.

GET …/unseen/count

Unread count for the caller in this account.

PATCH …/feed/:id/read, PATCH …/read-all

Mark one / all-visible as read.

PATCH …/feed/:id/dismiss, PATCH …/dismiss-all

Dismiss one / all-visible (per-user; other members of the account are unaffected).

Paging

The envelope depends on the surface (PLT-0098). The browser family (/browser/shared/v1/notifications/feed) answers {"items": [...], "next_cursor": "…" | null} — one envelope for every browser collection, with no bare arrays. The PUBLIC developer route (/notifications/v1/notifications) keeps {"data": [...], "nextCursor": "…" | null} as documented here. total is omitted on both: it is only allowed when the count is exact, and a filtered feed page is not a population.

A feed response is {"data": [...], "nextCursor": "…" | null}. Order is createdAt DESC, id DESC — a total order. Copy nextCursor back verbatim as ?cursor=; it SUPERSEDES offset, and a row arriving between two requests is never skipped and never re-shown. A full page emits the boundary; a short page ends null. An unreadable cursor is 400 {"error":"Invalid cursor"}.

Bulk operations and cutoffs

read-all / dismiss-all accept a snapshot boundary so “everything up to here” cannot swallow later arrivals:

  • ?beforeCursor=<feed cursor> — the EXACT boundary, verbatim from a feed page;

  • ?before=<RFC3339> — inclusive createdAt <= T, for callers whose own timeline boundary is not one of our ids. Not a substitute for feed paging.

The response echoes the effective cutoff: {"status":"ok","cutoff":{…}|null} for read-all, {"data":{"count":N,"cutoff":{…}|null}} for dismiss-all. | GET /api/notifications/feed | Paginated feed, newest first. | | GET /api/notifications/unseen/count | Badge count of unread notifications. | | PATCH /api/notifications/{id}/read | Mark one notification read. | | PATCH /api/notifications/read-all | Mark every unread notification read. | | PATCH /api/notifications/{id}/dismiss | Hide one notification from the default feed. | | PATCH /api/notifications/dismiss-all | Hide every notification from the default feed. | | GET /api/notifications/categories | Registered service categories with localized display names. |

Categories are served at the /api/notifications/categories spelling (the one the console gateway forwards), and that static path must be matched before the detail route’s /:id wildcard — mount order is what decides.

Feed query parameters:

Parameter

Default

Meaning

limit

20

1–100.

offset

0

Rows to skip.

read

all

true for read only, false for unread only.

severity

all

Comma-separated subset of info,warning,error,critical. An unrecognized value returns 400.

Access is enforced per row: a request returns the caller’s own user-scope notifications plus the tenant-scope notifications of the Account named in X-Account-Id, and nothing else. A dismiss or mark-read of a notification the caller does not own returns 404 rather than 403, so probing cannot confirm that a row exists.

Dismiss is a distinct state from read. A dismissed notification is retained but hidden from the default feed; marking one read leaves it in place.

Live updates

Notification Center receives new notifications over Server-Sent Events instead of polling. EventSource cannot set an Authorization header, so the client exchanges its bearer token for a short-lived stream cookie first:

# 1. Exchange the session token for a stream cookie (204, Set-Cookie).
curl -X POST https://console.flexgalaxy.ai/api/notifications/stream/auth \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Account-Id: ${ACCOUNT_ID}" \
  --cookie-jar stream.cookies

# 2. Open the stream with that cookie.
curl -N https://console.flexgalaxy.ai/api/notifications/stream \
  --cookie stream.cookies

The cookie is HttpOnly, Secure, SameSite=Strict, scoped to the stream path only, and expires after one hour. The stream emits a comment heartbeat every 25 seconds and an event: notification frame when a notification is created or dismissed for that user. Re-run the exchange when the cookie expires.