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 |
|---|---|---|---|
|
|
yes |
Any of |
|
|
yes |
The recipient. For |
|
|
when |
Destination address. |
|
|
no — defaults to |
|
|
|
no — defaults to |
Drives severity routing and filtering in the reader. It is NOT a priority: severity alone never makes a notification mandatory. |
|
|
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. |
|
|
no — defaults to |
Source-declared mandatory classification. A |
|
|
yes |
A template identifier in |
|
|
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 |
|
|
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. |
|
|
no |
Source-owned identity for THIS logical event. Supplying it makes the send idempotent under the key ( |
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:
the requested locale —
?locale=<tag>, else the firstAccept-Languagetag;that tag’s primary subtag (
zh-TW→zh);en;the first usable value in the map;
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 iseventId’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 nocorrelationIdmember 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 with422 {"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.
Link destinations¶
An actionUrl is clicked by a signed-in human, so it is policy-checked before
dispatch. A refused URL is a publisher error with a structured 422 —
{"error":"Action URL rejected","issue":{"code":"unsafe_action_url","url":…,"reason":…}} —
and nothing is sent (and no event claim is consumed, so a corrected retry may
reuse the same eventId).
Refused ( |
Because |
|---|---|
|
Absolute URLs must be |
|
|
|
A credential-shaped parameter ( |
|
A path segment or an |
|
Not a usable URL at all (including an empty string or a bare query). |
Relative paths are the normal form and are checked for the same query/segment rules. The console’s authorization and confirmation steps remain the real control — this is the publisher-error boundary, not the security boundary.
Live updates (SSE)¶
The console keeps an open stream for new notifications. Two calls, in order:
POST /api/notifications/stream/auth— with the caller’s normal bearer (and theX-Account-Idmarker a tenant sends). Answers204withSet-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:EventSourcecannot set headers, which is exactly why this short-lived cookie exists.GET /api/notifications/stream— replays the cookie, receivesevent: notificationframes.
Frame |
Meaning |
|---|---|
|
A new notification. |
|
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 |
|---|---|---|
|
the FIRST attempt’s status and body ( |
Nothing was dispatched again; the outcome is the first attempt’s. |
— |
|
A first attempt for this exact key is still in flight. Do not record an outcome; retry later. |
— |
|
|
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 |
|---|---|
|
An inbox record exists. This is NOT “read”, and NOT task completion — the owning workflow remains the authority for resolution. |
|
The channel’s transport accepted the payload. Delivery itself is not guaranteed. |
|
Suppressed by an explicit rule; |
|
The channel errored; |
The response status summarises them:
Status |
Body |
Meaning |
|---|---|---|
|
|
The request produced a durable effect — an inbox record and/or a channel dispatch. A sibling channel may still be |
|
|
Every requested channel was suppressed by a preference. A normal result, not an error — do not retry. |
|
|
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 |
|---|---|
|
Missing |
|
Missing, invalid or expired token. |
|
The caller is not an authorized publisher, or the authorization decision denied the send. |
|
Nothing was persisted and nothing was dispatched; |
|
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 |
|---|---|
|
Paginated inbox. |
|
ONE notification the caller may see: their own record, or one of the active account’s records. Anything else is a plain |
|
Unread count for the caller in this account. |
|
Mark one / all-visible as read. |
|
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>— inclusivecreatedAt <= 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 |
|---|---|---|
|
|
1–100. |
|
|
Rows to skip. |
|
all |
|
|
all |
Comma-separated subset of |
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.