docs(projects): contract for the client project status endpoints (app#2048)
Implements the docs row of recoupable/app#2048 — the client project status page at /projects/{projectId}.
This is the contract the database, api and app PRs are built against, written before any of them exists.
What this adds
A new api-reference/openapi/projects.json with seven operations, seven page stubs under api-reference/projects/, and a Projects group in the Accounts tab.
| Operation | Purpose |
|---|---|
GET /api/projects/{projectId} | The project, every task on it, and its collaborators. What the project page renders. |
GET /api/projects/{projectId}/tasks/{taskId} | One task with its comment feed. What the task detail page renders. |
POST /api/projects/{projectId}/tasks | Create a task. |
PATCH /api/projects/{projectId}/tasks/{taskId} | Update a task, including the completion toggle. |
DELETE /api/projects/{projectId}/tasks/{taskId} | Delete a task and its comments. |
GET .../tasks/{taskId}/comments | The task's comments, oldest first. |
POST .../tasks/{taskId}/comments | Post a comment, attributed to the caller. |
Three things the contract states deliberately
Access is by collaboration, not ownership, and the failure is a 404. A caller with no project_collaborators row for the project gets 404, never 403. A 403 would confirm the project id is real, which is exactly what an unguessable-id URL must not do. Every operation documents its 404 in those terms.
Completion is a boolean, not a timestamp. PATCH takes completed: true|false; the server stamps completed_at and records completed_by from the authenticated account. completed_at is not writable directly, so who closed an item is never ambiguous. Any collaborator may toggle any task, the client included.
No project-creation and no collaborator endpoints. Both are written directly against the database for now — one project does not justify the surface area — so this is seven operations rather than nine.
Auth
No new scheme. bearerAuth + apiKeyAuth, exactly as every other endpoint in this reference, because lib/auth/getAuthenticatedAccountId.ts already accepts either a Recoup API key or a Privy access token on the same Bearer header. That is what lets the browser and a CLI use one documented credential.
Notes for review
accounts.nameis null for roughly 94% of login accounts today (81 of 1,319 measured 2026-09-01), soauthor_nameand collaboratornameare documented as nullable with an explicit instruction to render a fallback. Fixing that at the source is a separate issue.docs.jsonround-tripped cleanly, so the nav change is a purely additive 12-line diff.
Verification with rendered screenshots follows in a comment.
🤖 Generated with Claude Code
https://claude.ai/code/session_01BTaK5sDuryYsQG5W56mR5n
Summary by cubic
Implements the docs row of recoupable/app#2048: the API contract for the client project status page at /projects/{projectId}, written before any backend code exists. Adds a new api-reference/openapi/projects.json with seven operations (read project with tasks, read a task with its comments, create/update/delete a task, list/post comments), seven page stubs under api-reference/projects/, and a Projects group in the Accounts tab.
Contract decisions
- Access is by collaboration, not ownership; a caller without a
project_collaboratorsrow gets a 404, never a 403, so responses can't reveal which project ids are real. - Completion is toggled with a
completedboolean on PATCH; the server stampscompleted_atand recordscompleted_byfrom the authenticated account. - No project-creation or collaborator endpoints; both are written directly against the database for now.
- Reuses the existing
bearerAuthandapiKeyAuthschemes; no new auth. accounts.nameis null for most accounts, soauthor_nameand collaboratornameare documented as nullable with a render-fallback instruction.- The GET project description no longer restates the access-control rule, and the create-task description links its completion note to the update operation.
Summary by CodeRabbit
- New Features
- Added documented API operations for viewing projects, creating and managing tasks, and listing or adding task comments.
- Documented authentication, collaboration-based access controls, task completion tracking, and standardized error responses.
- Documentation
- Added comprehensive reference pages for project, task, and comment operations.
- Added a Projects section under the Accounts documentation navigation.