Nexus Contract — Machine-readable OpenAPI 3.0.3 contracts for Nexus.

Machine-readable API contracts for the Nexus platform. Single source of truth for all service boundaries.

Spec	Service	Role
nexus-core.yaml	nexus-core	Headless WhatsApp backend — auth-unaware by design (PRD F1–F8)
nexus-api.yaml	nexus-api (no service yet)	Publicly hosted API for the Nexus app — auth-aware public edge; scaffold awaiting PRD

Both specs target OpenAPI 3.0.3 — oapi-codegen v2 does not support 3.1.

Files

• nexus-core.yaml — source of truth for the Core REST API
• nexus-api.yaml — public API scaffold (do not build consumers against it yet)
• oapi-codegen.yaml — Core codegen config (chi-server + models + embedded-spec) → nexus-core/internal/contracts/api.gen.go
• redocly.yaml — lint rules; security-defined disabled because Core is auth-unaware per PRD

Workflow

1. Edit the spec — Modify nexus-core.yaml for Core changes; never hand-edit api.gen.go. Every operation requires a camelCase operationId — it becomes the Go method on contracts.ServerInterface.
2. Lint — npm run contracts:lint (or :core / :api for a single spec).
3. Generate — npm run contracts:gen regenerates nexus-core/internal/contracts/api.gen.go. The generated file is committed so drift is visible in PR diffs.
4. Reconcile handlers — internal/handlers/http.Handler must satisfy contracts.ServerInterface (compile-time check in handler.go). Routes are mounted once via contracts.HandlerWithOptions in cmd/api/main.go; no hand-rolled route table.
5. Drift guard — npm run contracts:gen:check regenerates and diffs; fails if the committed stub is stale. Run in CI alongside go build ./....

Validate

npm run contracts:lint        # lint both specs
npm run contracts:gen:check   # fail if generated stub is stale

License

MIT — see LICENSE.