# 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:

```sh
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:

```text
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.