OpenAPI Workflow

packages/openapi-spec is the source of truth for the public API surface — not the NestJS route decorators, and not any hand-maintained Postman collection. The relationship is spec-first:

1. Add or change a resource in packages/openapi-spec/spec/*.yaml first.
2. Run npm run validate -w packages/openapi-spec (Redocly/Spectral lint against the shared docs/api/api-conventions.md rules — pagination shape, error envelope, idempotency header on mutating routes).
3. Regenerate SDK clients: npm run codegen -w tools/codegen (drives packages/sdk-js and packages/sdk-typescript off the spec; other SDK languages are stubbed until their own codegen target is wired up per docs/phase-plan/roadmap.md Phase 15).
4. Implement the actual NestJS route in the owning service so it matches the spec exactly — route drift from the spec is treated as a bug, not a spec update.
5. docs-site renders the spec live (Redoc) — no separately hand-written endpoint docs.

File layout

packages/openapi-spec/
  spec/
    openapi.yaml          root document, references the files below
    auth.yaml
    merchants.yaml
    api-keys.yaml
    sellers.yaml
    listings.yaml          (stub resource for now)
    wants.yaml              (stub resource for now)
    trade-sessions.yaml     (stub resource for now)
    offers.yaml              (stub resource for now)
    checkout.yaml            (stub resource for now)
    billing.yaml               (stub resource for now — the only TBBN-owned payment flow)
    webhooks.yaml              (stub resource for now)
    matching.yaml               (stub resource for now)
  components/
    schemas/               shared request/response schemas
    responses/              shared error responses

Internal vs. merchant-facing endpoints

Both live in the same spec for a single source of truth, but internal-only operations (ops console, TBBN-internal service calls) are tagged x-internal: true and excluded from the merchant-facing docs-site render and from public SDK generation.