docs(iios): notifications — API guide §5.11 (endpoints + engine diagram), env, counts
- API guide §5.11 Notifications: vapid-public-key / subscribe / unsubscribe / thread mute endpoints, the focus_thread presence signal, the three gates, and the engine flow diagram; SDK reference (registerPush/muteThread/focus); VAPID env; tests 205. - DEPLOYMENT: VAPID env + the in-memory-presence → Redis (multi-replica) caveat. - CEO overview: counts (205 tests, 54 tables / 20 migrations) + notifications in the "P9 has begun" note. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -243,6 +243,54 @@ sequenceDiagram
|
||||
|
||||
---
|
||||
|
||||
### 5.11 Notifications (push, presence-gated)
|
||||
|
||||
The engine reacts to `message.sent` and pushes to **absent** recipients through a swappable
|
||||
**NotificationPort** (Web Push/VAPID now; email/FCM later). The DB holds only push
|
||||
subscriptions + a per-thread mute flag; the reusable "who has an unread" feed stays `IiosInboxItem`.
|
||||
|
||||
| Method | Path | Body | Returns |
|
||||
|---|---|---|---|
|
||||
| GET | `/v1/notifications/vapid-public-key` | — | `{key}` — the public VAPID key the client needs to subscribe |
|
||||
| POST | `/v1/notifications/subscribe` | `{kind?, endpoint, keys:{p256dh, auth}, userAgent?}` | `{ok:true}` — store/refresh the caller's push subscription |
|
||||
| DELETE | `/v1/notifications/subscribe` | `{endpoint}` | `{ok:true}` |
|
||||
| POST | `/v1/threads/:id/mute` · `/unmute` | — | `{threadId, muted}` — per-thread notification mute for the caller |
|
||||
|
||||
**Presence (socket):** the app emits `focus_thread` `{threadId | null}` on the `/message`
|
||||
namespace whenever the foreground conversation changes (or the tab blurs). This is how the
|
||||
engine knows you're *viewing* a thread — **room membership ≠ viewing**, because the sidebar
|
||||
joins every thread room for live updates. `GET /v1/threads` returns each thread's `muted`.
|
||||
|
||||
**The three gates (fail-closed, in the notification policy — not the kernel):**
|
||||
1. **Policy** — DM always; a group message only if you were `@`-mentioned **or** it's a reply to you.
|
||||
2. **Presence** — skip if you're currently focused on that thread (you saw it live).
|
||||
3. **Mute** — skip if you muted the thread.
|
||||
A dead subscription (Web Push `404/410`) is pruned. DM-vs-group is read from the opaque
|
||||
`membership` thread attribute here in the *notification policy*; the kernel never branches on it.
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
SENT["message.sent (outbox → bus)"] --> PROJ["NotificationProjector"]
|
||||
PROJ --> LOOP{{"for each recipient (never the sender)"}}
|
||||
LOOP --> G1{"POLICY: DM? · @mention? · reply-to-you?"}
|
||||
G1 -->|no| X1["skip"]
|
||||
G1 -->|yes| G2{"PRESENCE: focused on this thread?"}
|
||||
G2 -->|yes| X2["skip — seen live"]
|
||||
G2 -->|no| G3{"MUTE: thread muted?"}
|
||||
G3 -->|yes| X3["skip"]
|
||||
G3 -->|no| SUBS["load subscriptions"] --> PORT["NotificationPort.deliver()"]
|
||||
PORT --> WP["Web Push (VAPID)"]
|
||||
WP -->|sent| OUT["→ browser push service → service worker → OS notification"]
|
||||
WP -->|"gone (404/410)"| PRUNE["prune dead subscription"]
|
||||
```
|
||||
|
||||
**Client (SDK layer, `lib/notifications.ts` → belongs in `@insignia/iios-kernel-client`):**
|
||||
`registerPush()` (permission → register service worker → `PushManager.subscribe` with the
|
||||
VAPID key → POST the subscription), `muteThread(threadId, muted)`, and `MessageSocket.focus(threadId)`.
|
||||
A service worker renders the OS notification on `push` and deep-links to the thread on click.
|
||||
|
||||
---
|
||||
|
||||
## 6. SDK reference
|
||||
|
||||
Two layers: a low-level `RestClient` (+ socket) and per-domain React hook packages.
|
||||
@@ -256,6 +304,7 @@ Methods (all return typed promises):
|
||||
- **Messaging:** `listThreads()`, `createThread({membership?, creatorRole?, subject?})`, `addParticipant(threadId, userId, role?)`, `getThreadMessages(threadId)`, `sendMessage(threadId, content, {attachment?, parentInteractionId?, mentions?, idempotencyKey?})`
|
||||
- **Reactions / pins / saves (annotations):** `MessageSocket.react(threadId, interactionId, emoji)` · `pin(...)` · `save(...)` (generic `annotate` under the hood); `listMyAnnotated('save')` for a cross-thread saved list. Subscribe to the `annotation` event for live updates.
|
||||
- **Media:** `uploadMedia(file, {onProgress?}) → {contentRef, mimeType, sizeBytes, checksumSha256, kind}` (presign → PUT-with-progress → normalized ref); `mediaUrl(contentRef) → signed view URL` (cached, short-lived). *This plumbing is identical for every app, so it lives in the SDK; the app only renders by `kind`.*
|
||||
- **Notifications:** `registerPush()` (service worker + `PushManager.subscribe` + POST subscription), `muteThread(threadId, muted)`, `MessageSocket.focus(threadId)` (presence signal). The engine (projector + Web Push port) is server-side; the SDK/app own registration + rendering.
|
||||
- **Inbox:** `listInboxItems(state?)`, `patchInboxItem(id, {state, reason?})`
|
||||
- **Support:** `createTicket({subject, priority?, threadId?})`, `escalate(threadId, subject?)`, `listTickets('mine'|'assigned')`, `patchTicket(id, state)`, `requestCallback({...})`, `createQueue(name)`, `joinQueue(id)`, `joinDefaultQueue()`, `setAvailability(state)`
|
||||
- **Routing:** `createBinding(input)`, `listBindings()`, `simulateRoute({interactionId, originChannelType, originRef?})`, `listRouteDecisions(state?)`, `approveDecision(id)`, `denyDecision(id)`
|
||||
@@ -333,7 +382,7 @@ Run against a live service (from `packages/iios-service`, `node scripts/<name>`)
|
||||
| `smoke-capability.mjs` | governed egress + real HTTP provider (needs `IIOS_PROVIDER_URL_EMAIL`) |
|
||||
| `smoke-tenant.mjs` | cross-tenant 403 + list isolation |
|
||||
|
||||
Automated unit/integration suite: `pnpm test` (192 tests). Import-boundary check: `pnpm boundary`.
|
||||
Automated unit/integration suite: `pnpm test` (205 tests). Import-boundary check: `pnpm boundary`.
|
||||
|
||||
---
|
||||
|
||||
@@ -358,6 +407,7 @@ Automated unit/integration suite: `pnpm test` (192 tests). Import-boundary check
|
||||
| `MEDIA_DIR` | `<tmp>/iios-media` | local media storage dir (dev `StoragePort`) |
|
||||
| `MEDIA_SECRET` | `dev-media-secret` | signs media upload/download URLs |
|
||||
| `PUBLIC_URL` | `http://localhost:$PORT` | base used to build presigned media URLs |
|
||||
| `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY` / `VAPID_SUBJECT` | — | Web Push (notifications). Unset → push disabled (engine no-ops). Generate once: `node -e "console.log(require('web-push').generateVAPIDKeys())"` |
|
||||
| `IIOS_DEV_TOKENS` | `0` | set `1` to enable `/v1/dev/*` |
|
||||
| `ADAPTER_SECRETS` | `{}` | per-channel HMAC secrets (default `dev-adapter-secret`) |
|
||||
| `IIOS_OUTBOUND_LIMIT` / `_WINDOW_MS` | `5` / `60000` | per-(channel,target) rate limit |
|
||||
|
||||
Reference in New Issue
Block a user