Follow-up to #37. Phase 1 shipped in #44 (CI contract validation of the website-mirrored docs/openapi/qveris-public-api.openapi.json). The tracking issue #37 was auto-closed on that merge, so Phases 2–3 were left untracked — this issue re-tracks Phase 2.
Scope — Generate types without replacing the public SDK models
Generated artifacts are a contract reference, not a public API replacement. Keep current hand-written MCP/SDK models in place.
MCP / TypeScript
- Use
openapi-typescript to generate a checked-in artifact, e.g. packages/mcp/src/generated/openapi.d.ts.
- Add CI that reruns generation and fails on
git diff --exit-code.
Python SDK
- Use
datamodel-code-generator (or equivalent) to generate a checked-in artifact, e.g. packages/python-sdk/qveris/generated/openapi_models.py.
- Add CI that reruns generation and fails on
git diff --exit-code.
Acceptance criteria
- Generated artifacts are reproducible from the checked-in
docs/openapi/qveris-public-api.openapi.json.
- CI catches drift between the OpenAPI spec and the generated MCP types / Python models.
- Existing MCP, CLI, and Python SDK public APIs remain backward compatible (no runtime/package behavior change in this PR).
- Implemented as small PRs (MCP and Python SDK may be separate PRs).
References
Re-tracking Phase 2 because #37 was auto-closed (COMPLETED) by #44 while only Phase 1 was delivered.
Follow-up to #37. Phase 1 shipped in #44 (CI contract validation of the website-mirrored
docs/openapi/qveris-public-api.openapi.json). The tracking issue #37 was auto-closed on that merge, so Phases 2–3 were left untracked — this issue re-tracks Phase 2.Scope — Generate types without replacing the public SDK models
Generated artifacts are a contract reference, not a public API replacement. Keep current hand-written MCP/SDK models in place.
MCP / TypeScript
openapi-typescriptto generate a checked-in artifact, e.g.packages/mcp/src/generated/openapi.d.ts.git diff --exit-code.Python SDK
datamodel-code-generator(or equivalent) to generate a checked-in artifact, e.g.packages/python-sdk/qveris/generated/openapi_models.py.git diff --exit-code.Acceptance criteria
docs/openapi/qveris-public-api.openapi.json.References
scripts/validate-openapi-contract.mjs,.github/workflows/openapi-contract.yml)Re-tracking Phase 2 because #37 was auto-closed (COMPLETED) by #44 while only Phase 1 was delivered.