Skip to content

Correct the API coverage claim: 183/184, not 100% #621

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

Merged
jeremy merged 3 commits into from
Aug 5, 2026
Merged

Correct the API coverage claim: 183/184, not 100% #621

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c39164e
Correct the coverage claim, and file two upload-versions communiques
jeremy Aug 4, 2026
e458408
Don't equate every version event with a file replacement
jeremy Aug 4, 2026
b9a7195
Keep the communiques out of the source tree
jeremy Aug 4, 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
30 changes: 26 additions & 4 deletions API-COVERAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,30 @@ Coverage of Basecamp 3 API endpoints. Source: [bc3-api/sections](https://github.

| Status | Sections | Endpoints |
|--------|----------|-----------|
| ✅ Implemented | 50 | 184 |
| ✅ Implemented | 49 | 183 |
| ⚠️ Blocked | 1 | 1 |
| ⏭️ Out of scope | 4 | 12 |
| **Total tracked** | **54** | **196** |

**100% coverage of tracked in-scope API** (184/184 endpoints). This is not a
complete bc-api parity figure. The five BC5 sections introduced by bc-api#410
**183 of 184 tracked in-scope endpoints.** The one gap is `GET
/uploads/:id/versions.json` in the `uploads` section, and it is not a missing
command — the command is written. The SDK's `UploadsService.ListVersions`
Comment thread
jeremy marked this conversation as resolved.
decodes the response with the wrong type: the API returns version *events*
(`action`, `details`, `recording_id`), the OpenAPI spec models them as
`[]Upload`, so a caller gets Upload structs with blank `title`/`filename`/
`status` and an `id` that is the event id and does not resolve as an upload.
Shipping a command on that would mean shipping wrong data, so it is held.
Reported to the SDK; the command lands when `ListVersions` returns an event
type.

This file previously read "100% coverage of tracked in-scope API (184/184)".
That was wrong, and the matrix had no way to say so — with only ✅ and ⏭️
available, a partly-covered section had to be recorded as fully covered. Hence
the third status above. It is deliberately narrow: ⚠️ means the CLI cannot
faithfully cover an endpoint for a reason outside the CLI, and it names the
blocker.

This is not a complete bc-api parity figure. The five BC5 sections introduced by bc-api#410
that were previously untracked — `my_bookmarks`, `drafts`, `my_notes`,
`calendars`, and `question_reminders` — are now tracked and implemented. The
pinned SDK's `EverythingService` is fully reached — see [Account-wide
Expand Down Expand Up @@ -152,6 +170,10 @@ Design discussion: basecamp/basecamp-cli#585. Contract and invariants:

The **Since** column tags each row with the Basecamp version that introduced its section: `BC4` for sections that shipped before Basecamp 5, `BC5` for sections introduced in Basecamp 5. If a BC5 release adds endpoints to an existing BC4 section, split them into a new row tagged `BC5` rather than bumping the BC4 row's `Endpoints` count — that keeps the column unambiguous per row. Column dropped post-BC4 decommission.

**Status** is one of ✅ implemented, ⏭️ out of scope, or ⚠️ blocked — the CLI
cannot faithfully cover at least one endpoint for a reason outside the CLI. A
⚠️ row must name its blocker in Notes.

| Section | Endpoints | CLI Command | Status | Since | Priority | Notes |
|---------|-----------|-------------|--------|-------|----------|-------|
| **Core** |
Expand Down Expand Up @@ -190,7 +212,7 @@ The **Since** column tags each row with the Basecamp version that introduced its
| search | 2 | `search` | ✅ | BC4 | - | Full-text search + metadata. Filters: `--project`/`--in`, `--type`, `--creator`, `--since` (BC5-only), `--file-type`, `--exclude-chat`. Metadata lists recording/file search types |
| recordings | 4 | `recordings` | ✅ | BC4 | - | Browse by type/status, trash/archive/restore |
| **Files & Documents** |
| uploads | 8 | `files`, `uploads` | ✅ | BC4 | - | list, show, create. Create supports `--visible-to-clients` (root vault only) |
| uploads | 8 | `files`, `uploads` | ⚠️ | BC4 | - | list, show, create, update, download; trash/archive/restore go through `recordings`. Create supports `--visible-to-clients` (root vault only). **Blocked:** `GET /uploads/:id/versions.json` — the SDK's `ListVersions` types the response as `[]Upload`, but the API returns version *events*, so the data comes back blank and misleading. Command is written and held on `feat/files-versions`, pending an SDK fix. Replacing an upload's *file* has no API at all — a separate BC3 gap, tracked outside this repo |
| vaults | 8 | `files`, `vaults` | ✅ | BC4 | - | list, show, create |
| documents | 8 | `files`, `docs` | ✅ | BC4 | - | list, show, create, update. Create supports `--subscribe`/`--no-subscribe`, `--visible-to-clients` (root vault only) |
| attachments | 1 | `uploads`, `attachments` | ✅ | BC4 | - | Upload via `attach`; list embedded attachments via `attachments list` (parses `<bc-attachment>` from content) |
Expand Down
Loading