fix(users): populate connected accounts and serve the spec's verbs

[gjtorikian]

Scoped out of #71 as a separate resource; this is that fix. Nothing wrote to the connected_accounts collection — its only reference outside the store was the one read in user-features.ts — so GET /user_management/users/{id}/connected_accounts/{slug} answered every user, in every state, with a 404. The shape it would have returned (provider/provider_id) also wasn't the spec's ConnectedAccount, and the spec defines three more verbs on this path that the emulator didn't serve at all.

What the endpoint now is

The spec's ConnectedAccount is the Pipes resource (a data installation): {object, id, user_id, organization_id, scopes, auth_method, api_key_last_4, state, created_at, updated_at} — no provider field (the URL names it), ids prefixed data_installation_. Accounts are keyed by (user, slug, organization scope): the optional organization_id query parameter on every verb selects an org-scoped account, and an unscoped lookup never resolves a scoped one.

Two facts the emulator can be told now create accounts, and both are write paths the spec itself defines — unlike identities in #71, this resource has a write API:

• POST (import). Takes the spec's ConnectedAccountDto (OAuth tokens, scopes, state). An omitted state is derived from the token combination the way the DTO describes: a token that still works — unexpired, or expired but refreshable — is connected; an expired access token with no refresh token is needs_reauthorization; neither state nor token is the 422 the spec reserves for an invalid combination. A duplicate for the same (user, provider, scope) answers 409.
• A connectedAccounts seed key. References users by email — the same join key memberships use, since seeded user ids are generated — and organizations by name, both cross-validated at startup. State defaults to connected: saying a user has a connected account is saying it is connected.

PUT updates tokens, scopes, or state; without an explicit state, only an update carrying tokens re-derives it, so a scopes-only update cannot silently reconnect a needs_reauthorization account. DELETE disconnects by removing the account and its stored tokens — the spec's enum value disconnected is observable only in the event a deletion emits, never on a stored row, so a fresh import after a disconnect is a 201 rather than a 409 against a dead link. Deleting a user disconnects their accounts the same way.

Events

The spec defines pipes.connected_account.connected / reauthorization_needed / disconnected, whose payloads carry two fields the REST shape does not (provider_slug, data_integration_id). They're emitted from collection hooks — the repo's pattern, so seeded accounts fire the same events — and only on state transitions. One data_integration_ id is shared by every account of a provider slug, matching the integration/installation split the id prefixes name.

Not covered

The hand-authored /pipes/connections routes and the data_providers endpoint (which serves pipe connections where the spec describes a provider catalog) are untouched — they model an adjacent, non-spec surface and deserve their own decision.

Verification

bun test (867 pass, 18 new in src/workos/routes/connected-accounts.spec.ts, including the empty-state 404s, derivation rules, 409/422, org scoping, event payloads, and the user-delete cascade), bun run typecheck, bun run lint, bun run fmt:check.

[greptile-apps]

Greptile Summary

The PR adds spec-compatible connected-account CRUD, seed configuration, organization scoping, response formatting, lifecycle events, and user-deletion cleanup.

• Connected accounts can be imported, retrieved, updated, disconnected, and seeded.
• PUT state derivation now evaluates the merged stored and submitted credentials.
• Coverage tooling recognizes routes registered through shared path constants.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/workos/routes/connected-accounts.ts	Implements scoped connected-account CRUD and correctly derives update state from merged retained and submitted credentials.
src/workos/routes/connected-accounts.spec.ts	Covers seed behavior, response shape, state derivation, organization scope, conflicts, events, disconnection, and user deletion.
src/workos/index.ts	Registers the route family, seeds connected accounts, and emits hook-driven lifecycle events.
src/workos/helpers.ts	Adds REST and event formatters that exclude stored OAuth credentials.
src/workos/config-validator.ts	Validates connected-account seed references, fields, states, and composite-key uniqueness.
src/workos/routes/users.ts	Extends user deletion cleanup to remove connected accounts through the hooked collection.
scripts/gen-supported-lib.ts	Extends static route discovery to resolve path constants used by route registrations.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Seed["connectedAccounts seed"] --> Store["Connected-account collection"]
  POST["POST import"] --> Store
  PUT["PUT merged credential update"] --> Store
  GET["GET account"] --> Store
  Store --> Format["Spec-compatible formatter"]
  Store --> Events["State-transition events"]
  DELETE["DELETE disconnect"] --> Store
  UserDelete["Delete user"] --> Store

Loading

_{Reviews (3): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}