#Browser OpenAPI client

The web application uses Orval 8 with its Fetch and TanStack Query v5 client. The Go API's assembled OpenAPI document is authoritative. Generate the document and browser client together:

pnpm generate:http

pnpm generate:contracts includes the same step. Generated browser files are committed under services/web/src/adaptors/generated/http/. pnpm check:http regenerates them in isolation and checks added, removed and changed files. These commands use the frozen devops Python environment, including PyYAML.

#Layout and use

Every browser operation has one tag. Orval creates one client module per tag:

services/web/src/adaptors/generated/http/
├── project/project.ts
├── party-governance/party-governance.ts
├── session/session.ts
├── model/
├── operations.ts
├── index.msw.ts
└── index.fixtures.ts

Feature code imports request functions or query hooks from the owning tag module. The root web providers own one TanStack Query client with polling and automatic focus/reconnect refetch disabled. For example, the Project screen uses useGetProjects from project/project.ts. The generated return value contains the decoded body in data and the HTTP status and headers alongside it. The shared Fetch adaptor reports unsuccessful HTTP statuses before decoding the body, including plain-text or HTML upstream errors. This preserves the 404 status needed by the isolated development stack's operator-login fallback.

The AAI login start remains a native top-level form submission. This preserves the browser navigation to the configured identity provider and the callback cookie rules. Generated clients handle session status, logout and ordinary API requests. The development-only operator endpoints remain in the handwritten HTTP adaptor because they are outside the active AAI contract.

The API callback uses the web application's public origin. Login binding and session cookies are host-only, so the API selects an exact enrolled callback from the login request's origin and preserves it through token exchange. The dev-box API-auth overlay and local Keycloak client enrol both themelio.localtest.me and platform.localtest.me callbacks.

Generated MSW handlers, Faker factories and typed fixtures support browser tests. Error scenarios and stateful journeys should put handwritten handlers before the generated defaults.

#Change workflow

1. Edit the owning contract fragment or authentication browser specification.
2. Run pnpm generate:http and review the assembled Go document and browser tree.
3. Update browser callers and tests.
4. Run pnpm check:http, the web tests, type check and build.
5. Run pnpm verify and the applicable browser and infrastructure lanes before hand-off.