certctl/web/CODEGEN.md

Generated API Client

Last reviewed: 2026-05-13

Phase 5 of the certctl architecture diligence remediation introduced orval-based code generation for the frontend API client. The hand-rolled web/src/api/client.ts (1,396 lines, 161 exported functions) is staged to be retired in favor of the generated TanStack-Query-shaped surface emitted by orval from api/openapi.yaml.

Where things live

Path	What
api/openapi.yaml	Source of truth — 158 operations
api/openapi-handler-exceptions.yaml	64 routes intentionally NOT in OpenAPI (35 wire-protocol carve-outs + 29 REST-deferred)
web/orval.config.ts	Codegen config — emits react-query hooks
web/src/api/generated/	Output tree (regenerated, git-tracked)
web/src/api/client.ts	Legacy hand-rolled client (TO BE DELETED in follow-up PR)
web/src/api/mutator.ts	Fetch wrapper used by the generated client (CSRF, auth)
scripts/ci-guards/openapi-handler-parity.sh	Verifies every router route is in OpenAPI OR exceptions
scripts/ci-guards/openapi-codegen-drift.sh	Blocks the build when openapi.yaml changes but generated/ wasn't regenerated

First-time setup

Run from the repo root:

cd web
npm install                                    # installs orval as a devDep
npm run generate                               # regenerates web/src/api/generated/
git add web/src/api/generated/ web/src/api/mutator.ts
git commit -m "feat(web): initial generated API client"

The mutator at web/src/api/mutator.ts is operator-authored (orval references it from orval.config.ts); it must export a certctlFetch<T>(config: AxiosRequestConfig): Promise<T> function that the generated code calls for every HTTP request. The mutator is where CSRF + bearer-token + retry policy + 401-redirect logic lives in one place.

Migration pattern (per consumer)

The generated client emits one hook per OpenAPI operation. Migrate consumers one page at a time; the hand-rolled client and generated client coexist until the last consumer migrates.

// Legacy (web/src/api/client.ts → web/src/pages/CertificatesPage.tsx):
import { useQuery } from '@tanstack/react-query';
import { getCertificates } from '../api/client';

const certs = useQuery({
  queryKey: ['certificates'],
  queryFn: getCertificates,
});

// Generated (web/src/api/generated/certificates/certificates.ts):
import { useGetCertificates } from '../api/generated/certificates/certificates';

const certs = useGetCertificates();   // wires queryKey + queryFn automatically

The generated useGetCertificates() honors the QueryClient defaults set in main.tsx (frontend-design-audit Phase 2 TQ-H2 / TQ-M1 tier model). Per-call overrides (staleTime, refetchInterval, etc.) pass through as the second argument:

const certs = useGetCertificates({
  query: { staleTime: STALE_TIME.REAL_TIME },
});

When the OpenAPI burn-down completes

Today 29 router routes are deferred from openapi.yaml (see the "REST-shaped" group in api/openapi-handler-exceptions.yaml). The generated client only covers what's in openapi.yaml — those 29 routes still go through web/src/api/client.ts until their OpenAPI ops land. The burn-down plan:

Sprint A — Cluster 1 (auth/sessions + auth/oidc): 12 ops
Sprint B — Cluster 2 (auth/breakglass + auth/users + runtime-config): 8 ops
Sprint C — Cluster 3 (auth/logout + audit/export + misc): 9 ops

After Sprint C, every router route is either an OpenAPI operation or a wire-protocol carve-out. The last consumer migrates off web/src/api/client.ts and the file gets deleted in a follow-up PR.

CI guards

• openapi-handler-parity.sh blocks any new router route that isn't in openapi.yaml AND isn't in the exceptions YAML.
• openapi-codegen-drift.sh blocks any openapi.yaml change that doesn't regenerate web/src/api/generated/ alongside.

Both run automatically as part of the per-PR CI guard sweep at .github/workflows/ci.yml.