Openapi Node Sdk Generation: OpenAPI-Driven Clients LLMs Cannot Hallucinate

# package.json scripts
# ✅
"gen:sdk": "openapi-typescript openapi/payments.v3.yaml -o src/gen/payments.ts && node scripts/gen-client.mjs",
"check:sdk": "git diff --exit-code -- src/gen/"

# ❌ agents invent fetch('/v3/paymnets') typos forever

// src/gen/payments.ts — generated (illustrative)
export interface paths {
  "/v3/payments/{paymentId}": {
    get: {
      parameters: { path: { paymentId: string } };
      responses: { 200: { content: { "application/json": Payment } } };
    };
  };
}

// src/sdk/paymentsClient.ts — thin wrapper over generated types
import createClient from "openapi-fetch";
import type { paths } from "../gen/payments.js";

export const payments = createClient<paths>({ baseUrl: process.env.PAYMENTS_URL! });

// ✅ app code
const { data, error } = await payments.GET("/v3/payments/{paymentId}", {
  params: { path: { paymentId } },
});

// ❌ hallucinated
// await payments.GET("/v3/payments/by-email/{email}", ...)

# .github/workflows/sdk.yml
jobs:
  sdk:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm gen:sdk
      - run: pnpm check:sdk          # ✅ fail if gen/ dirty
      - run: pnpm tsc -p tsconfig.json --noEmit
      - name: Ban raw fetch to payments host
        run: |
          if rg -n "PAYMENTS_URL|payments\\.internal" src --glob '!src/sdk/**' --glob '!src/gen/**'; then
            echo "Use payments SDK only"; exit 1
          fi

// eslint rule — illustrative
// ❌ no-unsafe-call / ban @ts-expect-error on sdk imports
// ✅ agent proposes openapi patch + gen:sdk in the same PR