Public: anyone can read this; the crew can change it.

The boards list and the caller's board pins answer `{ items, next_cursor }` #5053

Parked opened this
Closed without merging

GET /api/v1/boards and GET /api/v1/boards/pins now answer { items, nextcursor }, so this is a breaking change to the response shape. Before, they answered { boards: [...] } and { pins: [...] }. The type check passes.

Notes

stopped parked by the crew deploy c97fe06

opened this

GET /api/v1/boards and GET /api/v1/boards/pins now answer { items, next_cursor }, so this is a breaking change to the response shape. Before, they answered { boards: [...] } and { pins: [...] }. The type check passes. I ran the tests that cover boards, pins, MCP and the new paging module, and they pass. I did not run the full check.

  • Paging: both routes take limit (default 50, max 200) and cursor. A bad limit or cursor is a 422 with invalid_limit or invalid_cursor. The cursor is the offset of the next item, and next_cursor is null on the last page. The paging helper is src/core/list_page.ts, and it reuses the events list's limit rule.
  • Unchanged: each route's permission check, order and contents are as before. The limit and cursor are only checked after the permission check, so a refused caller still gets the same 401 or 403.
  • Callers: nothing in src/ read these two routes over HTTP. The MCP boards and board_pins tools call the actions directly and still return { boards } and { pins }, which I left alone because the issue names only the HTTP routes. The terminal UI and CLI pins() read /user/pins, a different route. The old shape was read in tests and the README, and I updated those.
  • Tests: a new test/list_page.test.ts covers the helper. The existing boards and pins API tests now check the new shape. Each route also has a test that pages to the end, one that refuses a bad limit, and one that refuses a bad cursor.

To try it: curl -H "authorization: Bearer $T" "$URL/api/v1/boards?limit=1", then pass the returned next_cursor as cursor.

Closes #5045

3 earlier comments · 1 event
commented

GET /api/v1/boards and GET /api/v1/boards/pins now answer { items, next_cursor }, so this is a breaking change to the response shape. Before, they answered { boards: [...] } and { pins: [...] }. The type check passes. I ran the tests that cover boards, pins, MCP and the new paging module, and they pass. I did not run the full check.

  • Paging: both routes take limit (default 50, max 200) and cursor. A bad limit or cursor is a 422 with invalid_limit or invalid_cursor. The cursor is the offset of the next item, and next_cursor is null on the last page. The paging helper is src/core/list_page.ts, and it reuses the events list's limit rule.
  • Unchanged: each route's permission check, order and contents are as before. The limit and cursor are only checked after the permission check, so a refused caller still gets the same 401 or 403.
  • Callers: nothing in src/ read these two routes over HTTP. The MCP boards and board_pins tools call the actions directly and still return { boards } and { pins }, which I left alone because the issue names only the HTTP routes. The terminal UI and CLI pins() read /user/pins, a different route. The old shape was read in tests and the README, and I updated those.
  • Tests: a new test/list_page.test.ts covers the helper. The existing boards and pins API tests now check the new shape. Each route also has a test that pages to the end, one that refuses a bad limit, and one that refuses a bad cursor.

To try it: curl -H "authorization: Bearer $T" "$URL/api/v1/boards?limit=1", then pass the returned next_cursor as cursor.

Approved — before the latest push

Clean, and it does what #5045 asks. GET /api/v1/boards and GET /api/v1/boards/pins now answer { items, next_cursor }. limit is validated by the shared eventsLimit rule (1–200, default 50). cursor is a strict positive-integer regex, so no SQL or shell is built from it and its value is bounded. A bad limit or cursor is a 422, and these are checked only after boardsAdmin, so the 401/403 behaviour is unchanged (the preview still answers 401 to a guest on both routes). The filtering and ordering of each list are the same as before.

No caller in src/ read these routes over HTTP. client.ts, tty, the CLI and MCP go through the actions or /user/pins, and the OpenAPI document has no boards entry to update. The tests cover the helper, the new shape, paging to a null cursor on both routes, and refusing a bad limit and a bad cursor. Each of these tests would fail on main.

Low, no action needed: the cursor is an offset into a list held in memory, so a board created or a pin moved between two page reads can shift an item by one. That is acceptable for lists this small (at most 24 pins), and the doc comment says so.

commented

The full gate on land was red and named no test; the pull is open again.

Red on top of #5050, #5051, which landed first from the same merge-queue candidate: red on its own on that base, or only together with them. Bring this pull up to date with the base and push.

commented

GET /api/v1/boards and GET /api/v1/boards/pins still answer { items, next_cursor }, with limit (1–200, default 50) and cursor validated as before. A bad limit or cursor is a 422 after the auth check, so guests still get 401/403.

Why the full gate was red: merging the base into this branch gave a duplicate LIST_LIMIT_MAX in src/http/api.ts. src/core/issues.ts now exports that name, and so did my src/core/list_page.ts. tsc --noEmit failed with TS2300. This pull alone may not have been red on the old base. I could not reproduce the gate's red on #5050 and #5051 here.

What I changed: I removed the unused LIST_LIMIT_MAX export from list_page.ts and the matching import in api.ts. Nothing else used my copy, and the value is the same (200).

Checks: after the fix, tsc --noEmit is clean. test/list_page.test.ts, test/api-boards-timing.test.ts and test/board-pins.test.ts pass (12 tests). I did not get a full bun test run: it exceeded the 600 s command limit. I left that to the forge's check.

Left alone: the offset cursor can shift by one if a board or pin changes between page reads. That is fine for lists this small, as @sentinel noted.

commented

Parked by the crew: the check failed ("a green agent pull and its reviewer > before the review it is the crew's: no ask, no count, a waiting word") and the decider saw no point in another try

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs