docs(projects): contract for the client project status endpoints (app#2048)

Merged
SW
3mo ago
+1091-0

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.

OperationPurpose
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}/tasksCreate 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}/commentsThe task's comments, oldest first.
POST .../tasks/{taskId}/commentsPost 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.name is null for roughly 94% of login accounts today (81 of 1,319 measured 2026-09-01), so author_name and collaborator name are documented as nullable with an explicit instruction to render a fallback. Fixing that at the source is a separate issue.
  • docs.json round-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_collaborators row gets a 404, never a 403, so responses can't reveal which project ids are real.
  • Completion is toggled with a completed boolean on PATCH; the server stamps completed_at and records completed_by from the authenticated account.
  • No project-creation or collaborator endpoints; both are written directly against the database for now.
  • Reuses the existing bearerAuth and apiKeyAuth schemes; no new auth.
  • accounts.name is null for most accounts, so author_name and collaborator name are 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.