[alukach]

Part of #588. Takes the account endpoints of #592 that exist today, plus every other /api/v1 route not already claimed by an open PR, onto the operations layer from #642 and #651, so /api/docs documents them from the schemas they parse.

What

/api/docs listed 15 of the 34 handlers under /api/v1. With this branch it lists 27 operations, and the route-coverage allowlist holds only the six endpoints open PRs already port: the five data-connection endpoints (#657) and DELETE /accounts/{account_id} (#665). Once those merge, the allowlist is empty and the reference describes every deployed endpoint.

Endpoint	Before	Now
GET /accounts/{account_id}	undocumented	getAccount; 403 (was 401) to a signed-in caller who may not read it
HEAD /accounts/{account_id}	undocumented, and not counted by the coverage test	documented; the coverage test now counts HEAD
GET /accounts/{account_id}/profile	401 for any organization	getAccountProfile: organizations too; a disabled or service account is a 404; the profile carries name
PUT /accounts/{account_id}/profile	overwrote metadata_public wholesale	replaced by PATCH (updateAccountProfile), which the edit-profile form also uses: fields given change, "" clears one; a service account's is a 404, as GET is
GET /accounts/{account_id}/flags	returned the caller's flags, whatever the path said	getAccountFlags reads the account named
PUT /accounts/{account_id}/flags		updateAccountFlags, shared with the admin form
GET /whoami	the whole session, Ory session included	identity_id, account, memberships
GET /products/{a}/{p}/permissions		getProductPermissions; still a bare ["read","write"] list
GET /products/featured	the first ten public products, featured or not	up to ten actually featured products, same {products} shape, through listProducts; documented as deprecated in favor of GET /products?featured=true
PUT /products/{a}/{p}/featured	always 501	removed
POST /accounts/{id}/trusts/exchanges	undocumented	documented under Internal
POST /service-account-keys/exchanges	undocumented	documented under Internal
POST /secret-scanning/github	undocumented	documented under Internal
POST /service-account-keys/revocations	undocumented	documented, public

Internal endpoints

The data proxy's two exchanges and GitHub's secret-scanning callback are in the reference so it matches what is deployed, but no client can authenticate as the proxy or as GitHub. They carry an Internal tag, whose description opens with Not for public use, and x-internal: true, which tools such as Redocly use to hide an operation from a public build. The document declares every tag, in the order routes register, with Internal last, so Swagger UI and Redoc, which list declared tags first and in order, render it at the bottom of the page. Their statuses and success bodies are unchanged. The proxy reads only the status and, on a 200, trusted or active/account_id/key_id (checked in data.source.coop/src/source_api/cache.rs), so a 403 {"trusted": false} and a 200 {"active": false} for an unknown key stay as they are.

Behavior that changed

• Error bodies on every endpoint here are { "error": { "code", "message", "field_errors"? } }, as everywhere since feat(api): operations layer, generated OpenAPI docs, and the memberships API #642. The CLI already parses that shape (source-coop-cli/src/api.rs), so its messages improve; the data proxy never reads error bodies.
• A malformed body is a 400 with field errors, not the 500 a thrown ZodError produced.
• PUT /accounts/{id}/profile is gone. No caller in the org's repositories uses it; the web form goes through the same operation as PATCH.
• PUT /products/{a}/{p}/featured is gone. It always answered 501. GET /products/featured stays: no code in the org calls it, but production saw 18 requests to it in a day, from browsers, curl and GeoLibre Desktop.
• GET /whoami drops orySession. The CLI reads only account and memberships.
• A profile's profile_image is the uploaded image, else an individual's identicon Gravatar, from src/lib/avatar.ts, which ProfileAvatar and OGAvatar now share with it, rather than a Gravatar built from an Ory admin lookup. getEmail and getProfileImage had no other caller and are removed.
• Profile and flag edits write only the fields they change. The old route and action read the account and wrote the whole record back, so a profile save could restore flags or disabled that an admin changed in the meantime. Both edits are logged with who made them.
• An ORCID iD on an organization, or a ROR ID on a person, is a 400. The forms only ever send the one that fits.
• Saving a profile keeps an unchanged website's record, verification state included, rather than recreating every website as unverified.

The stale @openapi JSDoc blocks on the routes touched here are removed; nothing read them since #642.

Not here

The rest of #592: account search, POST /accounts for organizations, and DELETE /accounts/{id} (#665).

Docs, ADRs and llms.txt

• public/llms.txt gains a line for the public profile, now that an organization's can be read.
• Checked docs.source.coop: using-source/upload/with-service-account.md shows POST /service-account-keys/revocations and promises a 204 for any well-formed key, which still holds. No other page names these endpoints.
• Reviewed data.source.coop at 8d02d47 for anything this branch could break. The proxy calls six source.coop endpoints (src/source_api/cache.rs), all through cached_fetch, which reads only the status (200 succeeds, 404 is a missing bucket, 401/403 are AccessDenied, anything else is an internal error) and parses a 200 body. Three are touched here, and each keeps what the proxy relies on: GET .../permissions still answers its proxy-signed GET, through the same getApiSession, with a bare ["read","write"] list or a 404; POST /service-account-keys/exchanges still answers 200 with {active, account_id?, key_id?} for every well-formed hash; POST /accounts/{id}/trusts/exchanges still answers 200 {trusted: true}, 403 for no and 401 for an unresolved account. Only their error bodies change, which the proxy never reads. The other three, GET /products/{a}/{p}, GET /products/{a}?limit=100 and GET /data-connections/{id}, are untouched. - Checked the data-proxy ADRs that name these endpoints: 005 and 007 (/permissions as the write gate, answered with the caller's identity), 013 (service-account-keys/exchanges as the proxy itself, {account_id, key_id, active}, active: false for an unknown hash) and 014 (trusts/exchanges as the account). This branch keeps each of those contracts, so all four still hold.

UI

No visual change. The edit-profile and account-flags forms call the same server actions, which now adapt the operations. ProfileAvatar and OGAvatar take their URL from avatarUrl and render the same image as before, so their stories are unchanged.

Testing

• npm run type-check passes.
• Full npx jest: 93 suites, 1,001 tests pass.
• route-coverage.test.ts validates the generated document as OpenAPI 3, checks every handler but the six allowlisted ones is in it, and checks every tag is declared with Internal last.
• New src/lib/operations/accounts.test.ts takes over the organization-email tests from actions/account.test.ts, and adds tests for the flags path-id fix, the profile PATCH semantics and websites, both edits writing only their own fields, the per-type identifiers, a service account's missing profile, and whoami dropping the Ory session; getProductPermissions is tested in products.test.ts.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
source-coop-ui	Ready	Preview	Oct 15, 2026 11:28pm UTC
source-cooperative	Ready	Preview	Oct 15, 2026 11:28pm UTC

[claude]

Claude finished @alukach's task in 19s —— View job

---

✅ No blocking issues — safe to merge.

I read the new src/lib/operations/accounts.ts, the featured route and avatar.ts against accountsTable.update and the authz actions. I didn't run the tests.

• Partial writes: accountsTable.update only sets emails, flags, disabled and metadata_public when they are defined. The profile and flag edits therefore don't overwrite each other's fields, as the description says.
• Authorization: the check runs before body validation, and a 403 goes to a signed-in caller while a 401 goes to an anonymous one. A disabled or service account's profile is a 404, and PATCH has the same 404 for a service account.
• Per-type identifiers: ORCID on an organization and ROR on a person are rejected with a 400. The email edit only applies to organizations.
• Hidden Internal operations: the x-internal operations stay in the public document, which is intended. They are tagged and listed last.

Description is stale (advisory)

Commit 2847a05 keeps GET /products/featured as a deprecated route, backed by listProducts({ featured: "true", limit: "10" }) and with a new route.test.ts. The description still says the following:

• The table row for GET /products/featured says "removed".
• The "Behavior that changed" section says "Both featured endpoints are gone".
• The docs section says "Removing GET /products/featured lets that path fall through to GET /products/{account_id}".

It also still says 27 operations, which probably needs recounting. CLAUDE.md says a description is read as the spec, so please rewrite those lines. The route is now documented as deprecated, and its response is { "products": [...] } for the first ten featured products. PUT .../featured is still removed.

Simplify (ponytail)

• src/lib/operations/accounts.ts:105: accountExists is a one-line wrapper over fetchAccount(...). If it has a single caller, call the table directly.
• src/lib/operations/accounts.ts:52: clearable is used by only one schema. Inlining .or(z.literal("")) is fine, but this one is borderline, so keep or cut as you prefer.

Docs

• The description names the docs.source.coop page it checked (using-source/upload/with-service-account.md) and says why it still holds.
• It also names the data.source.coop ADRs 005, 007, 013 and 014 and says why they hold.
• It covers the public/llms.txt line.
• Nothing to flag, apart from re-checking the featured text above, since the featured change affects what it says about llms.txt and the proxy.

---

💰 Estimated review cost: $0.16 · 0m19s · 7 turns