Skip to content

feat(api): Page the conversation list with a signed cursor #2232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
sentry-junior wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

feat(api): Page the conversation list with a signed cursor #2232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
31d06e1
feat(api): Page the conversation list with a signed cursor
sentry-junior[bot] Oct 26, 2026
9afc633
docs(api): Say that list cursors need the same filters
sentry-junior[bot] Oct 26, 2026
c0835e7
ref(api): Move conversation stats schemas to their own module
sentry-junior[bot] Oct 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 26 additions & 26 deletions packages/docs/src/content/docs/operate/dashboard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,32 +108,32 @@ corresponding System routes.

The current authenticated product API slices are:

| Endpoint | Purpose |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/health` | Dashboard-safe health metadata. |
| `/api/runtime` | Runtime paths, providers, skills, and packages. |
| `/api/plugins` | Loaded plugin list. |
| `/api/plugins/:plugin/*` | Authenticated, namespaced API routes contributed by enabled plugins. |
| `/api/user-pages` | Safe navigation metadata for registered plugin pages. |
| `/api/user-pages/:plugin/:page` | Viewer-authorized metrics and records for one plugin page. |
| `/api/automations` | Viewer-owned scheduled and event automations. |
| `/api/automations/:id` | Deletes one viewer-owned scheduled or event automation. |
| `/api/skills` | Discovered skill list. |
| `/api/conversations` | Recent SQL conversation feed; optional `actorEmail` is a normalized presentation filter, not authorization; optional `codeRepositoryId` lists conversations linked to that repository's code changes. |
| `/api/conversations/stats` | Complete 90-day conversation stats and people/place leaderboards aggregated by SQL. |
| `/api/code` | Native code-change overview across repositories. |
| `/api/code/repositories/:repository` | One repository's code-change summary, recent changes, and Workspaces. |
| `/api/people` | Actor directory. |
| `/api/people/:email` | Actor profile and recent conversation resources. |
| `/api/people/:email/code` | Person-scoped native code-change summary for one profile. |
| `/api/people/:email/plugin-reports` | Person-scoped sanitized plugin operational summaries. |
| `/api/locations` | Public location directory and generic private-activity totals. |
| `/api/locations/:location` | Activity, actors, and recent conversations for one public location. |
| `/api/plugin-reports` | Sanitized plugin operational summaries. |
| `/api/conversations/:conversation` | Conversation header metadata and expiring transcript; private transcripts are participant-authorized. |
| `/api/conversations/:conversation/events` | Earlier transcript event pages selected with a signed `before` cursor. |
| `/api/config` | Safe dashboard config signals and feature readiness. |
| `/api/me` | Signed-in dashboard identity. |
| Endpoint | Purpose |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/health` | Dashboard-safe health metadata. |
| `/api/runtime` | Runtime paths, providers, skills, and packages. |
| `/api/plugins` | Loaded plugin list. |
| `/api/plugins/:plugin/*` | Authenticated, namespaced API routes contributed by enabled plugins. |
| `/api/user-pages` | Safe navigation metadata for registered plugin pages. |
| `/api/user-pages/:plugin/:page` | Viewer-authorized metrics and records for one plugin page. |
| `/api/automations` | Viewer-owned scheduled and event automations. |
| `/api/automations/:id` | Deletes one viewer-owned scheduled or event automation. |
| `/api/skills` | Discovered skill list. |
| `/api/conversations` | Recent SQL conversation feed; optional `actorEmail` is a normalized presentation filter, not authorization; optional `codeRepositoryId` lists conversations linked to that repository's code changes; `nextCursor` pages past 50 rows via `cursor`. |
| `/api/conversations/stats` | Complete 90-day conversation stats and people/place leaderboards aggregated by SQL. |
| `/api/code` | Native code-change overview across repositories. |
| `/api/code/repositories/:repository` | One repository's code-change summary, recent changes, and Workspaces. |
| `/api/people` | Actor directory. |
| `/api/people/:email` | Actor profile and recent conversation resources. |
| `/api/people/:email/code` | Person-scoped native code-change summary for one profile. |
| `/api/people/:email/plugin-reports` | Person-scoped sanitized plugin operational summaries. |
| `/api/locations` | Public location directory and generic private-activity totals. |
| `/api/locations/:location` | Activity, actors, and recent conversations for one public location. |
| `/api/plugin-reports` | Sanitized plugin operational summaries. |
| `/api/conversations/:conversation` | Conversation header metadata and expiring transcript; private transcripts are participant-authorized. |
| `/api/conversations/:conversation/events` | Earlier transcript event pages selected with a signed `before` cursor. |
| `/api/config` | Safe dashboard config signals and feature readiness. |
| `/api/me` | Signed-in dashboard identity. |

For a private conversation, the transcript is available only when the signed-in verified email matches the owning root conversation actor's persisted verified email. Conversation summary resources report that match through `isParticipant`; event-page resources apply the same authorization decision through their projected events and `eventHistory`. Other viewers receive redacted metadata. Top-level conversation resources and System, People, and Location statistics include descendant duration and usage even when child resources are loaded separately. A directly requested child reports only its own metrics.

Expand Down
13 changes: 11 additions & 2 deletions packages/junior/src/api/conversations/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,17 @@ resources:
- `/events` reads strictly before a `before` cursor and returns the next older
bounded page.

Cursors are opaque, HMAC-signed, and bound to one conversation and canonical
event sequence. Callers must not derive or modify cursor positions.
Event cursors are bound to one conversation and canonical event sequence.

The conversation list returns at most 50 root conversations. `nextCursor` is
present when more remain. Send it back as `cursor` to read the next page. A
list cursor holds the `lastActivityAt` and `conversationId` of the last row, in
the same order as the list. A conversation with new activity moves above the
cursor, so later pages do not show it. The cursor holds only a position. Send
the same filters with `cursor` as in the first request.

All cursors are opaque and HMAC-signed. Callers must not derive or modify
cursor positions.

Canonical storage contains runtime and Pi-shaped events that are not a suitable
REST contract. The reporting adapter projects those facts into normalized
Expand Down
Loading
Loading