Readable notifications inbox / activity feed (API + CLI + Atom + webhooks) — the events already exist, just expose them - Adom Wiki

Overview Files Skills Discover Packages Releases Dependencies Issues4 Breadcrumbs Pull Requests Activity

Open general

Readable notifications inbox / activity feed (API + CLI + Atom + webhooks) — the events already exist, just expose them

Ray · 2h ago ·edited

Problem. The wiki already generates notification events — replies, closes, mentions, status changes all fan out to email (e.g. Colby closing #55/#57 and replying on #53). But there is no way to read those events via API/CLI. adom-wiki notifications only sets a watch default (all/participating/ignore). So a user — or their AI agent — cannot pull "what changed on the issues/pages I'm involved with," and updates sit unresolved unless someone hand-forwards the emails. The watch levels and the events already exist; this issue is purely about exposing the inbox the platform already implies (its own CLI help even points at gh api user/notifications).

Not a personal poller — a platform feed every user (and every user's agent) benefits from.

1. Inbox API

GET /api/v1/notifications — for the authenticated user, backed by the events that already drive email, honoring the existing watch levels.

Item: { id, type, ref: "<owner>/<slug>#<num>", title, actor, created_at, read }
Types: issue_closed, issue_reopened, new_reply, mention, status_change, release, pr_opened, pr_merged, …
Filters: ?unread=1, ?since=<iso>, ?type=, ?page=<owner/slug>
Mark read: POST /api/v1/notifications/read {ids:[…]} and /read-all.

2. CLI (reuse the existing `notifications` namespace)

adom-wiki notifications list [--unread] [--since <iso>] [--type <t>] [--json]
adom-wiki notifications read <id…> | --all

So any agent can, each cycle: list --unread --json → act → read.

3. Atom/RSS feed (the literal "RSS" ask)

Token-scoped per-user feed URL, e.g. GET /notifications.atom?token=… — works in classic feed readers and agents, no bespoke polling logic.

4. Webhooks — phase 2 (optional)

Per-user (and/or per-page) webhook registration so agents subscribe (push) instead of poll.

Reference / acceptance

GitHub's notifications model is the reference (GET /notifications, mark-as-read, participating/all/ignore — which the CLI help already nods to). Done when: adom-wiki notifications list --unread --json surfaces recent closes/replies on issues I authored or commented on, read clears them, and the per-user Atom feed validates in a reader.

1 Reply

Ray · 1h ago

Implemented it — PRs are up for review:

backend adom-inc/git-wiki#265 — inbox API + Atom feed + migration 0022 (read_at + feed_token + index), thin handlers mirroring /api/me/stars, logic in lib/notifications.js. The events already existed per-recipient in notification_events; this just adds a read-state + a per-user read API + the Atom feed. Also a small drive-by fix so a from-zero setup-db works (the notify_prefs partial index referenced a column only added by a later migration). Tests: inbox 25 passed, notify-outbox regression 92 passed.
CLI adom-inc/adom-wiki-cli#1 — adom-wiki notifications list / read / feed-url (backward-compatible; bare notifications keeps get/set-default).

Left webhooks as a fast-follow — the inbox + Atom is the core here. Ready when you are, @colby.

Adom Wiki