feat(billing): API contract-first — OpenAPI spec + generated client types

[izzywdev]

Billing contract (api-contract-first skill)

Authors the frozen OpenAPI 3.1 contract for billing-service and binds the typed client to it.

What

• services/billing-service/openapi.yaml — OpenAPI 3.1 spec derived from the real route handlers (src/routes/*, src/app.ts), verified against the code: /plans, /subscriptions (POST/GET/PATCH/DELETE), /setup-intent, /credits, /webhooks/stripe, /health. Covers auth (internalToken bearer = BILLING_INTERNAL_TOKEN), the public routes (plans + webhook), error shapes (validation 400 / unauthorized 401 / stripe 502 / not-found 404), and documents the async Kafka surface (billing.subscription.changed, billing.usage.recorded, trial-ending / payment-failed).
• services/billing-service/.spectral.yaml — spectral ruleset (extends spectral:oas). Lint is clean (0 errors).
• @fuzefront/billing-client — generated src/schema.ts (openapi-typescript) exported as paths/components/operations; new src/contract.ts statically asserts the hand-authored public types are byte-for-byte equivalent to the generated schema, so contract drift becomes a tsc error. Added gen:types + lint:contract npm scripts and the codegen/lint devDeps.

Verification

• spectral lint openapi.yaml → No results with a severity of 'error' found!
• tsc --noEmit on billing-client passes with the contract-alignment guard (verified on Linux CI; the local Windows env has the os=linux npmrc pin that corrupts native installs).

Mock server

npx @stoplight/prism-cli mock services/billing-service/openapi.yaml stands up a mock for UI/test streams.

Per the skill, this is the contract PR — freeze/merge FIRST, then fan out backend/UI/test work gated only on the contract.

Base: feature/billing-payments (PR #66).

[izzywdev]

Superseded: @fuzefront/billing-client (contract + schema) shipped to master via #88; the live billing-client is built and consumed by billing-ui. Reopen if a divergent spec is needed.