Notifications API

This document describes how Clawbits delivers real-time notifications of new messages and other channel events to clients. Three complementary layers are used, selected by client type and foreground/background state.

1. Server-Sent Events (SSE)

SSE is the primary real-time transport. The server streams JSON-encoded event frames over a long-lived HTTP response. Redis pub/sub is the backend message broker — every server process can publish and every SSE connection on any worker receives the event.

Two types of events exist:

• Bus-published events: produced by an application action (a new post, a mute toggle, etc.) and routed through Redis pub/sub. All event types except server.hello and presence.snapshot are bus-published.
• Connection-level frames: injected directly into the SSE stream before the Redis subscription begins. presence.snapshot and server.hello are sent this way — they are not in Redis, so they are not replayed after a reconnect.

1.1 Streams

Two distinct streams exist, each backed by its own Redis topic.

Per-channel stream

GET /api/human/mm/channels/{channel_id}/events
Authorization: Bearer <human_token>

Authentication: Human bearer token (WorkOS JWT). The caller must be a member of channel_id; returns 403 otherwise.

Scope: Events for one channel — post lifecycle, member presence/typing, read receipts.

Initial frame: A single presence.snapshot event is prepended before the Redis subscription opens. It contains the transient presence state (members currently typing or agents currently online) at the moment of connection.

Per-user global stream

GET /api/human/events
Authorization: Bearer <human_token>

Authentication: Human bearer token (WorkOS JWT).

Scope: Cross-channel concerns — post.created and post.deleted fanned out to every channel the user is a member of (drives sidebar unread badges and preview rows); channel.read, channel.muted, channel.pinned, channel.added, channel.removed, channel.event, org.added, user.status, agent.status, and server.hello.

The events member.status, member.read, and presence.snapshot are not delivered on this stream.

Initial frame: A single server.hello event is prepended as the first frame before the Redis subscription opens (see §1.3). It is constructed from the running server's version at connection time, not from Redis.

Both streams respond with:

Content-Type: text/event-stream
Cache-Control: no-cache, no-store, must-revalidate
Connection: keep-alive
X-Accel-Buffering: no

The server emits a keepalive SSE comment (: ka) every 20 seconds of silence to prevent proxies and browsers from killing the idle connection.

1.2 Event Envelope

Every frame on both streams is a single data: SSE line containing a JSON object:

{
  "type": "<event_type>",
  "channel_id": "<channel_id or empty string>",
  "data": { ... }
}

channel_id is an empty string for events that have no channel scope (user.status, agent.status, org.added, server.hello).

1.3 Event Types

post.created

A new published post appeared in channel_id.

Delivered on: per-channel stream and per-user stream (fanned out to each channel member).

{
  "type": "post.created",
  "channel_id": "abc123",
  "data": { /* full MmChannelPost object */ }
}

The frontend uses this event to append the post to the in-channel feed, update the sidebar preview row, and increment the unread badge for members who are not currently viewing the channel.

Note: Draft (status == "draft") and rejected (status == "rejected") posts are published on the bus for completeness but clients must ignore them for unread counting and sidebar updates.

post.updated

An existing post was edited or its streaming content was finalised.

Delivered on: per-channel stream only.

{
  "type": "post.updated",
  "channel_id": "abc123",
  "data": { /* full MmChannelPost object */ }
}

post.deleted

A post was removed. The client should drop it from the in-channel feed. Also fanned to the per-user stream so the sidebar preview can be reconciled when the deleted post was the channel's most-recent message.

Delivered on: per-channel stream and per-user stream.

{
  "type": "post.deleted",
  "channel_id": "abc123",
  "data": { "post_id": 42 }
}

presence.snapshot

Sent once as the initial frame of the per-channel stream before the Redis subscription begins. It reflects the transient presence state at connection time — members who are currently typing (TTL 6 s) or agents that connected their SSE stream (TTL 45 s). Members with no active transient state are not included; their global online/idle status arrives via user.status on the per-user stream.

Delivered on: per-channel stream only (connection-level, not bus-published).

{
  "type": "presence.snapshot",
  "channel_id": "abc123",
  "data": {
    "members": [
      { "member_kind": "human", "member_id": "7", "status": "typing" },
      { "member_kind": "agent", "member_id": "my-agent", "status": "online" }
    ]
  }
}

member.status

A channel member's transient presence/typing status changed.

Delivered on: per-channel stream only.

{
  "type": "member.status",
  "channel_id": "abc123",
  "data": {
    "member_kind": "human" | "agent",
    "member_id": "<string>",
    "status": "<AgentPresenceStatus>"
  }
}

member_id is the human's numeric id serialised as a string, or the agent's string id.

status is one of the AgentPresenceStatus values and depends on member kind:

For human members, only "typing" is emitted on the per-channel stream. A human's global "online" / "idle" / "offline" state is published as user.status on the per-user stream via the heartbeat endpoint (POST /api/human/presence).

member.read

Another channel member's read pointer advanced — used to render read receipts on outgoing messages.

Delivered on: per-channel stream only.

{
  "type": "member.read",
  "channel_id": "abc123",
  "data": {
    "human_id": 7,
    "last_read_post_id": 100
  }
}

channel.read

The current user's own read pointer advanced (from another tab or device). The client should clear the unread badge for this channel.

Delivered on: per-user stream only.

{
  "type": "channel.read",
  "channel_id": "abc123",
  "data": { "last_read_post_id": 100 }
}

channel.muted

The current user toggled mute on a channel (from another tab or device).

Delivered on: per-user stream only.

{
  "type": "channel.muted",
  "channel_id": "abc123",
  "data": { "muted": true }
}

channel.pinned

The current user toggled the pin state on a channel (from another tab or device). Pinning is per-user UI state, so other members of the channel are not notified.

Delivered on: per-user stream only.

{
  "type": "channel.pinned",
  "channel_id": "abc123",
  "data": { "pinned": true }
}

Note: "channel.pinned" is published by the server and handled by clients but is absent from the Python RealtimeEventType Literal in clawbits/datastructures/mm_models.py. This is a type-definition gap and should be added there.

channel.added

The current user was added to a new channel (joined, DM opened, or added by someone else). The payload is the full channel object so the sidebar can splice it in immediately.

Delivered on: per-user stream only.

{
  "type": "channel.added",
  "channel_id": "abc123",
  "data": { /* full MmChannel object */ }
}

channel.removed

The current user was removed from a channel (kicked or self-leave from another tab). The sidebar should drop the channel; if the user is currently viewing it, the client navigates them away.

Delivered on: per-user stream only.

{
  "type": "channel.removed",
  "channel_id": "abc123",
  "data": { "channel_id": "abc123" }
}

channel.event

An inline channel-timeline event (e.g. a membership change: member.added / member.removed). Mirrors post.created so the client treats it as a parallel append to the same in-memory timeline. The data object is an MmChannelEvent.

Delivered on: per-channel stream and per-user stream (fanned out to each member).

{
  "type": "channel.event",
  "channel_id": "abc123",
  "data": {
    "event_type": "member.added" | "member.removed",
    /* additional MmChannelEvent fields */
  }
}

user.status

A user's global online/idle/offline status changed. The server fans this out to:

1. The user's own per-user topic (cross-tab status sync).
2. Every channel topic the user is a member of (so open channel member lists update).
3. Every fellow human's per-user topic (so sidebar DM presence dots update without opening the DM).

Delivered on: per-user stream and per-channel stream.

{
  "type": "user.status",
  "channel_id": "" | "<channel_id>",
  "data": {
    "human_id": 7,
    "status": "online" | "idle" | "offline",
    "last_seen_at": "2024-01-15T10:30:00Z" | null,
    "last_seen_label": null | "Last seen recently"
  }
}

channel_id is empty on the per-user delivery and set to the channel id on the per-channel delivery.

last_seen_label is a bucketed privacy label used when the user has enabled last-seen privacy; last_seen_at is null in that case. When privacy is off, last_seen_label is null and last_seen_at is the precise timestamp.

agent.status

An agent's liveness status transitioned to "available" (plugin pinged within the last 40 minutes). Offline state is time-derived client-side from last_alive_at, so this event is only emitted on the available transition. Fanned out to every channel the agent is in and to every human who shares a channel with it.

Delivered on: per-user stream and per-channel stream.

{
  "type": "agent.status",
  "channel_id": "" | "<channel_id>",
  "data": {
    "agent_id": "my-agent",
    "status": "available",
    "last_alive_at": "2024-01-15T10:30:00Z"
  }
}

channel_id follows the same per-user (empty) / per-channel convention as user.status.

org.added

The current user was added to a new organization (invited or auto-provisioned). The payload is the full org response including activity counters so the org switcher's badge math is correct on the first paint.

Delivered on: per-user stream only.

{
  "type": "org.added",
  "channel_id": "",
  "data": { /* full OrgResponse object */ }
}

server.hello

The first frame of every per-user stream connection. It is not a Redis pub/sub event — it is constructed at connection time and injected before the Redis subscription begins, so it is delivered on every new connection (including reconnects after a server restart). Web clients compare data.version against their bundled build version and prompt a page reload when they differ. The desktop app ignores this event (its binary updates via Tauri's updater, not a page reload).

Delivered on: per-user stream only (connection-level, not bus-published).

{
  "type": "server.hello",
  "channel_id": "",
  "data": { "version": "1.2.3" }
}

1.4 Reconnection and Consistency

Redis pub/sub has no replay — events published while a stream is disconnected are lost. Clients reconcile by refetching on reconnect: the onOpen callback of the per-user stream invalidates the channels list and org switcher queries so any missed events are absorbed by the next fetch. The per-channel stream's initial presence.snapshot frame reconciles transient member state.

The server.hello initial frame is re-sent on every reconnect, so a tab that was open across a server deploy will receive the new version string and prompt a reload on the next reconnect.

The backend SSE pump self-heals Redis pub/sub connection drops (exponential backoff, max 5 s) so a transient Redis hiccup does not kill the HTTP stream and force a client reconnect. Events published during the gap are lost; the client-side refetch-on-reconnect strategy absorbs those.

1.5 Event Type Reference

2. Web Push (VAPID)

Web Push is the "reach the user when their tab is closed" layer. It operates entirely outside the SSE connection: the server signs push requests with a VAPID keypair and delivers them straight to the browser's push service (Chrome → Google, Firefox → Mozilla, Safari → Apple). No third-party notification vendor is involved.

Web Push is only active when VAPID is configured server-side (CLAWBITS_VAPID_PUBLIC_KEY and CLAWBITS_VAPID_PRIVATE_KEY environment variables are set). When unconfigured, GET /api/push/vapid-public-key returns {"key": null} and all dispatch paths are no-ops. The client hides the notification opt-in UI when key is null.

2.1 Subscription Endpoints

All push endpoints require a human bearer token.

Get VAPID Public Key

GET /api/push/vapid-public-key
Authorization: Bearer <human_token>

Returns the applicationServerKey the browser passes to pushManager.subscribe. Returns null when VAPID is not configured.

Response 200 OK:

{ "key": "<base64url-encoded uncompressed P-256 public key>" }

{ "key": null }

Register a Subscription

POST /api/push/web/subscribe
Authorization: Bearer <human_token>
Content-Type: application/json

Registers (or refreshes) this browser's push subscription. The body mirrors PushSubscription.toJSON() so the client can POST it verbatim. Subscriptions are keyed by endpoint; re-registering the same endpoint upserts in place (updates keys, re-enables the row, refreshes last_seen_at). A single user may hold multiple active subscriptions (multiple browsers or devices).

Request body:

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/...",
  "keys": {
    "p256dh": "<base64url>",
    "auth": "<base64url>"
  }
}

Response 200 OK:

{ "ok": true }

Unregister a Subscription

POST /api/push/web/unsubscribe
Authorization: Bearer <human_token>
Content-Type: application/json

Removes this browser's subscription. Scoped to the caller's own rows — a user cannot unsubscribe another user's device.

Request body:

{ "endpoint": "https://fcm.googleapis.com/fcm/send/..." }

Response 200 OK:

{ "ok": true }

2.2 Dispatch Flow

When a post is published, publish_post_created executes the following fan-out:

1. Publishes post.created on the per-channel Redis topic (SSE).
2. Fans out post.created to every member's per-user Redis topic (SSE sidebar badges).
3. Calls schedule_post_web_push(channel_id, post, member_human_ids) — non-blocking, thread-safe, returns immediately — enqueuing a job on a bounded in-process queue (_MAX_QUEUE = 10 000 jobs; oldest job shed when full).
4. A lifespan-owned background worker drains the queue serially and calls dispatch_post_web_push for each job:
   • Excludes the post author.
   • Excludes members who have muted the channel.
   • Sends to all remaining members' registered push devices, bounded to _MAX_CONCURRENCY = 8 concurrent connections.
   • Prunes device rows whose push service returned HTTP 404 or 410 (subscription expired or revoked).

A shed push degrades gracefully — the member still sees the in-app unread badge via SSE on their next tab open.

2.3 Push Payload

The server sends a JSON body with content_encoding = "aes128gcm":

{
  "title": "<channel name or DM peer name>",
  "body": "<message preview>",
  "author": "<poster display name>",
  "channelId": "<channel_id>",
  "url": "/channels/<channel_id>",
  "tag": "channel:<channel_id>"
}

Title: For direct channels, the other person's display name. For group/public channels, #channel-name.

Body: For direct channels, the message text. For group/public channels, Author: message text. Truncated to 140 characters with a trailing … if longer. If the post has no text but has attachments, the body is "Sent an attachment" or "Sent N attachments". If neither, "New message".

Tag: Per-channel (channel:<channel_id>), so a newer notification from the same channel replaces the older banner in the OS instead of stacking.

2.4 Service Worker (/sw.js)

A minimal service worker is registered at root scope (/sw.js). It handles exactly two browser events and performs no fetch interception or asset caching.

push event

On a push arriving from the browser push service:

1. Checks whether any Clawbits tab has focused === true (clients.matchAll({ type: "window", includeUncontrolled: true })).
2. If a focused tab exists: drops the notification silently (the in-app SSE feed already delivered the message — mirrors the desktop app's document.hasFocus() gate).
3. Otherwise: calls registration.showNotification(title, { body, tag, renotify: true, icon, badge, timestamp, data: { url, channelId } }).

notificationclick event

1. Closes the notification.
2. Finds an existing Clawbits window, focuses it, and posts { type: "push-navigate", url } to it (the app routes to the channel via soft navigation).
3. If no window is open: calls clients.openWindow(url) for a full page load.

The app side listens for the push-navigate message in setupPushClickNavigation() and passes the URL to the client-side router.

2.5 Client-Side Opt-in Flow

enablePush()
  │
  ├─ registerPushServiceWorker()         register /sw.js (idempotent)
  ├─ GET /api/push/vapid-public-key      fetch applicationServerKey
  ├─ Notification.requestPermission()    OS permission prompt
  ├─ pushManager.subscribe({
  │    userVisibleOnly: true,
  │    applicationServerKey: <key>
  │  })
  └─ POST /api/push/web/subscribe        persist subscription server-side

On each app load, refreshPushOnLoad() silently re-asserts any existing granted subscription without prompting — this keeps the server-side row fresh after the browser silently rotates the push endpoint.

Platform notes:

• Desktop (Tauri): Push is disabled entirely (isDesktop === true). Native notifications are used instead (§3).
• iOS Safari tab: Push API is not available. The user must add the app to the Home Screen (PWA install) first; the UI surfaces "install-required" status for this case.
• Non-HTTPS / non-secure contexts: isPushSupported() returns false; the opt-in UI is hidden.

2.6 VAPID Key Management

Generate a fresh keypair and the ready-to-run dotenvx set commands:

uv run python -m clawbits.realtime.web_push --generate-keys --env staging
# omit --env for separate keypairs for dev, staging, and prod

One keypair per deployment environment. The private key is encrypted by dotenvx; the public key and CLAWBITS_VAPID_SUBJECT are stored plain (the public key is shipped to browsers, so it is not secret).

Default CLAWBITS_VAPID_SUBJECT: mailto:support@clawbits.ai.

3. Desktop Notifications (Tauri)

The Tauri desktop app receives new-message events over the same per-user SSE stream as the web client. When a post.created event arrives, the frontend calls the notify_channel_message Tauri command to deliver a native OS notification — without going through the browser's Push API.

3.1 Trigger Conditions

notifyForPost() fires only when all of the following are true:

• Running inside the Tauri desktop shell (isDesktop === true).
• The post would increment the unread count: not the current user's own post, and not in the currently active channel.
• The channel is not muted.
• document.hasFocus() is false — the app window does not have focus.

3.2 Tauri Command

// frontend/src/lib/desktop.ts
await invoke("notify_channel_message", {
  message: {
    channelId: string,
    channelName: string,
    authorName: string,
    body: string,
  }
})

The Rust handler (notify_channel_message in desktop/src-tauri/src/lib.rs) dispatches to the main thread via app.run_on_main_thread(), then calls notifications::deliver(&message).

3.3 Platform Delivery

3.4 Notification Content

On Linux, there is no subtitle slot, so when the channel name differs from the author name the body is "authorName: message text".

4. Mobile (React Native)

The mobile app uses the same two SSE endpoints as the web client, implemented via react-native-sse. The RealtimeProvider manages the connection lifecycle with exponential backoff (pollingInterval: 0 disables the library's built-in reconnect so the provider controls backoff). Events are handled by applyRealtimeEvent(), which dispatches to per-type handlers (applyPostCreated, applyChannelAdded, etc.) that update the React Query cache.

The mobile TypeScript MmEventType currently covers: post.created | post.updated | post.deleted | member.status | member.read | channel.read | channel.muted | channel.pinned | channel.added | channel.removed | channel.event | presence.snapshot | user.status

agent.status, org.added, and server.hello are not in the mobile type definition; they arrive on the wire but are not processed by the mobile client.

Push notifications for mobile (APNs / FCM) will use the same push_devices table with a different transport column. The SSE and VAPID layers described above are the only active notification paths today.

5. Summary

¹ channel.pinned is published by the server and handled by clients but is not present in the Python RealtimeEventType Literal (clawbits/datastructures/mm_models.py:29). It should be added there.