Take a page on the overdue to-dos report

Merged
TH
4d ago
+360-43

Written by @thehalebot

The Reports service's overdue to-dos report (GetOverdueTodos) took no page. Since basecamp/bc3#14519, Basecamp answers GET /reports/todos/overdue.json one page at a time: 15, 30, 50, then 100 to-dos, latest first. Each page holds the same four lateness groups, filled with that page's to-dos only. So every SDK returned page 1 as if it were the whole report, and nothing showed that more existed. Every SDK's overdue report now takes an optional page. In Go, the report also says whether another page follows.

What changes for callers

  • spec/basecamp.smithy: GetOverdueTodosInput gains page, and the operation's doc states the paging. All seven SDKs are regenerated from it.
  • No SDK follows the pages. The operation carries no @basecampPagination trait. Its response is an object holding four arrays, and the trait's key can name only one. GetMyNotifications is the same case and is handled the same way. SPEC §8's carve-out now names both.
  • Go: ReportsService.OverdueTodos(ctx) becomes OverdueTodos(ctx, page int32), and 0 means the first page. OverdueTodosResponse gains Meta ListMeta. Truncated is true while the response carries Link: rel="next", and TotalCount comes from X-Total-Count.
  • Breaking, pre-1.0: the Go signature changes with no alias. Without page, a caller now gets the first page, not every overdue to-do. MIGRATING.md covers both under Unreleased.

Invariants

  • A page is fetched with exactly one request, and the next link isn't followed. In the Go, TypeScript and Ruby tests, the server answers page 2 with a rel="next" link to page 3. Each test asserts one request, to ?page=2.
  • Go reports whether more pages exist. That page reads back with Meta{TotalCount: 21, Truncated: true}. A last page with no Link reads back Truncated: false, and a call with page 0 sends no page param.
  • Generated files match the spec. Everything was regenerated with make generate. make check passes. On Linux, the Swift checks skip without a toolchain, and the Swift services were regenerated with the swift:6.2 image.

Rejected Alternatives

  • Merge every page into one report. The trait's key names one array. Merging four arrays would need a new pagination variant in six generators and in Go's hand-written wrapper. It would also bring back the unbounded read on the client that bc3#14519 removed from the server.

Further Work

  • basecamp/basecamp-mcp-server#384 pages get_overdue_todos on this change. It pins overdue-todos-paging-on-v0.35.0, which is v0.35.0 plus this commit, until a release carries it.