jjbrunton/RedditBot
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ac12a3146a194e67384cc1bbc4acd872156f2056
RedditBot/docs/api.md
T
Jamie BruntonandClaude Opus 5 725b5fc4e6 feat: application-level read state and inbox triage for conversations 
Conversations were hard to manage because "unread" came straight from
Matrix's notification_count, and nothing in the app ever sends a read
receipt — so opening a conversation in the dashboard could never clear it
and the unread set only ever grew. The list also collapsed three
orthogonal facts into one word, labelling "they spoke last and we have
not replied" as "Up to date".

Read state is now ours:

- conversation_read_state table (migration 19) plus
  ConversationReadStateRepository, kept separate from conversation_states
  so a read write can never be lost to mergeConversationState. The
  watermark is monotonic, so a stale poll cannot resurrect an unread
  badge.
- hasUnreadInbound and needsReply are derived server-side and returned on
  every conversation. Matrix's `unread` stays on the contract but the
  dashboard no longer reads it.
- POST /conversations/{id}/read|unread|status and
  POST /conversations/bulk-read, with optimistic cache updates.

Inbox rework:

- List rows are a real grid (checkbox, open button, chip strip) instead of
  a full-bleed absolute overlay button, which previously forced a
  pointer-events escape hatch for anything interactive in a row. Rows use
  aria-current rather than aria-pressed. Not a listbox: options must not
  contain interactive descendants.
- Counted filter pills replace the select, independent state chips replace
  the collapsed status word, plus a sort control (including oldest
  unanswered), a per-account filter, age-coloured timestamps, and an
  explicit count of rows hidden by the seller filter.
- Keyboard: j/k/arrows, Enter, u, e, / and Escape. Shortcuts yield to any
  open dialog so Escape dismisses the modal, not the conversation behind
  it. Multi-select with bulk mark-read and mark-done.
- Detail panel: auto-mark-read on open, a "New messages" divider pinned at
  mount (deriving it from the live watermark made it vanish a second after
  opening), triage actions in the header, the automation banner moved out
  of the composer, day dividers with time-only stamps, and a flex column
  so history scrolls in its own region instead of painting over the
  composer.
- Row order freezes while a conversation is open, with a "N new — refresh"
  pill, so a background poll cannot reorder rows mid-triage.

Two database tests rewound user_version by an offset from the latest
version, which silently re-targets a different migration whenever one is
appended. They now pin absolute versions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 10:06:03 +01:00

121 lines
7.4 KiB
Markdown
Raw Blame History

# RedditBot API
This file is generated from `src/web/api-catalog.ts`. Run `npm run docs:api`
after changing the HTTP surface. The live OpenAPI 3.1 document is available at
`GET /api/openapi.json`, and compact agent discovery is available at
`GET /api/v1/capabilities`.
## Authentication
The dashboard token is an administrator credential. Browser users can exchange
it for an HttpOnly, SameSite=Strict session; API clients can send it as a bearer
token.
Optional least-privilege bearer credentials are configured with:
- `REDDIT_BOT_AGENT_READ_TOKEN`: GET, HEAD, SSE, and private-media reads except debug routes.
- `REDDIT_BOT_AGENT_CONTROL_TOKEN`: read access plus mutations under `/api/v1`.
Control credentials cannot send messages, import sessions, activate accounts,
or update legacy configuration endpoints. Those operations require the
administrator dashboard token.
## Agent entry points
- `GET /healthz`: unauthenticated process liveness with no private state.
- `GET /api/v1/readyz`: component readiness and authentication degradation.
- `GET /api/v1/overview`: bot, account, sync, rate-limit, and recent-error snapshot.
- `GET /api/v1/control`: current running state.
- `POST /api/v1/control/start`, `/stop`, or `POST /api/v1/control`: explicit bot control.
- `POST /api/v1/jobs`: tracked chat/media sync; poll `GET /api/v1/jobs/:id`.
- `GET /api/events/stream`: replayable typed SSE events.
## MCP server
Run the stdio MCP adapter with `npm run mcp`. It connects to
`REDDIT_BOT_API_URL` (default `http://127.0.0.1:3000`) and reads its bearer
credential from `REDDIT_BOT_AGENT_TOKEN`, then the scoped agent variables, and
finally `WEB_DASHBOARD_TOKEN`.
Read tools cover overview, readiness, accounts, activity, conversations,
errors, sync state, and performance. Control tools include `start_bot`,
`stop_bot`, `set_bot_running`, `trigger_sync`, and `get_job`. External
message tools are separately annotated as destructive/non-idempotent and need
an administrator credential.
## Operations
| Method | Path | Summary | Access | Mutates |
|---|---|---|---|---|
| `GET` | `/healthz` | Process liveness | read | no |
| `GET` | `/api/v1/overview` | Consolidated operational snapshot | read | no |
| `GET` | `/api/v1/readyz` | Component readiness | read | no |
| `GET` | `/api/v1/capabilities` | Discover API operations and safety attributes | read | no |
| `GET` | `/api/openapi.json` | OpenAPI 3.1 description | read | no |
| `GET` | `/api/v1/control` | Get bot running state | read | no |
| `POST` | `/api/v1/control` | Set bot running state | control | yes |
| `POST` | `/api/v1/control/start` | Start bot processing | control | yes |
| `POST` | `/api/v1/control/stop` | Stop bot processing | control | yes |
| `GET` | `/api/v1/jobs` | List recent asynchronous jobs | read | no |
| `GET` | `/api/v1/jobs/{id}` | Get asynchronous job state | read | no |
| `POST` | `/api/v1/jobs` | Start chat or media synchronisation | control | yes |
| `GET` | `/api/stats` | Get bot statistics | read | no |
| `GET` | `/api/analytics/candidate-funnel` | Get durable candidate funnel counts | read | no |
| `GET` | `/api/activity` | Get recent activity | read | no |
| `GET` | `/api/posts/by-author/{username}` | Get processed posts by author | read | no |
| `GET` | `/api/messages` | Get recent sent messages | read | no |
| `GET` | `/api/successful` | Get successful message examples | read | no |
| `GET` | `/api/chats` | Get active chats | read | no |
| `GET` | `/api/chats/sync` | Get chat sync state | read | no |
| `POST` | `/api/chats/sync/delta` | Trigger incremental chat sync | admin | yes |
| `POST` | `/api/chats/sync/full` | Trigger full chat sync | admin | yes |
| `POST` | `/api/chats/fetch-all` | Fetch all chats synchronously | admin | yes |
| `GET` | `/api/conversations` | List conversations | read | no |
| `GET` | `/api/conversations/{id}` | Get conversation detail | read | no |
| `POST` | `/api/conversations/{id}/suggest-reply` | Generate a reply suggestion | admin | yes |
| `POST` | `/api/conversations/{id}/suggest-media-ask` | Generate a media request suggestion | admin | yes |
| `POST` | `/api/conversations/{id}/send-reply` | Send a conversation reply | admin | yes |
| `GET` | `/api/conversations/{id}/shareable-media` | List every enabled exchange-library image not yet shared in this conversation | read | no |
| `POST` | `/api/conversations/{id}/share-media` | Send a selected exchange-library image | admin | yes |
| `POST` | `/api/conversations/start` | Start a new conversation | admin | yes |
| `POST` | `/api/conversations/{id}/read` | Advance the operator read watermark | admin | yes |
| `POST` | `/api/conversations/{id}/unread` | Return a conversation to the unread queue | admin | yes |
| `POST` | `/api/conversations/{id}/status` | Snooze, resolve or reopen a conversation | admin | yes |
| `POST` | `/api/conversations/bulk-read` | Mark many conversations read in one request | admin | yes |
| `GET` | `/api/media` | List received private media | read | no |
| `GET` | `/api/media/sync` | Get media sync state | read | no |
| `POST` | `/api/media/sync` | Trigger media sync | admin | yes |
| `POST` | `/api/media/sync/full` | Trigger full media sync | admin | yes |
| `GET` | `/api/media-library` | List operator-owned exchange images | read | no |
| `POST` | `/api/media-library` | Upload and classify an operator-owned exchange image | admin | yes |
| `PATCH` | `/api/media-library/{id}` | Correct tags or enable an exchange image | admin | yes |
| `DELETE` | `/api/media-library/{id}` | Delete an exchange image | admin | yes |
| `POST` | `/api/start` | Start bot processing (legacy) | admin | yes |
| `POST` | `/api/stop` | Stop bot processing (legacy) | admin | yes |
| `GET` | `/api/timers` | Get rate-limit timers | read | no |
| `GET` | `/api/analytics/by-subreddit` | Get performance by subreddit | read | no |
| `GET` | `/api/analytics/by-strategy` | Get performance by strategy | read | no |
| `GET` | `/api/analytics/funnel` | Get mature message outcome funnel | read | no |
| `GET` | `/api/analytics/trend` | Get daily performance trend | read | no |
| `GET` | `/api/analytics/ai-usage` | Get OpenRouter cost and model reliability | read | no |
| `GET` | `/api/attention` | Get operator attention items | read | no |
| `GET` | `/api/outreach` | Get active outreach candidates and funnel stages | read | no |
| `GET` | `/api/config` | Get non-secret application configuration | read | no |
| `PUT` | `/api/config` | Update application configuration | admin | yes |
| `GET` | `/api/login/status` | Get Reddit session state | read | no |
| `POST` | `/api/login/session-import` | Import Reddit and Matrix credentials | admin | yes |
| `GET` | `/api/accounts` | List Reddit accounts | read | no |
| `POST` | `/api/accounts/{accountId}/activate` | Activate a Reddit account | admin | yes |
| `GET` | `/api/logs/stream` | Stream legacy log events | read | no |
| `GET` | `/api/events/stream` | Stream typed application events | read | no |
| `GET` | `/api/logs` | Get recent structured logs | read | no |
| `GET` | `/api/debug/cookies` | Get redacted cookie diagnostics when enabled | admin | no |
| `POST` | `/api/debug/check-responses` | Run response check when enabled | admin | yes |
## Error model
Errors use JSON with an `error` string and optional `detail`. Authentication
failures are `401`; recognized but insufficient agent credentials receive
`403`; invalid inputs receive `400`; unavailable services receive `503`.
Long-running agent jobs expose failure text in the job resource.
Reference in new issue View Git Blame Copy Permalink