feat(client): add generated typescript client

Author: AlisinaDevelo

.github/workflows/ci.yml

@@ -37,6 +37,9 @@ jobs:
       - name: OpenAPI contract
         run: npm run contract
 
+      - name: Generated client
+        run: npm run client:check
+
       - name: Test
         run: npm test
 

CHANGELOG.md

@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Versioned `/api/v1/*` endpoints with `{ data, meta }` response envelopes, cache metadata, and structured error bodies.
 - OpenAPI-backed response contract tests for the v1 success and structured error envelopes.
 - Provider circuit breaker for repeated GNews failures, including Prometheus circuit event metrics and `503` short-circuit responses.
+- OpenAPI-generated TypeScript client types, a small v1 `NewsApiClient` wrapper, and CI drift checks for generated client output.
 
 ### Changed
 

README.md

@@ -25,7 +25,7 @@ Full diagram and component notes live in [docs/ARCHITECTURE.md](docs/ARCHITECTUR
 - **Container:** multi-stage [Dockerfile](Dockerfile) (non-root user, healthcheck).
 - **Deploy:** Example [Kubernetes manifests](deploy/k8s/).
 
-**Automation:** [CI](.github/workflows/ci.yml) (Node **20**/**22**), [CodeQL](.github/workflows/codeql.yml), [Codecov](https://codecov.io) upload, [dependency review](.github/workflows/dependency-review.yml), [SBOM](.github/workflows/supply-chain.yml), [provenance attest](.github/workflows/provenance.yml), [releases on tags](.github/workflows/release.yml), and [Dependabot](.github/dependabot.yml) (npm, Docker, Actions). Details: [docs/CI.md](docs/CI.md). Operations: [docs/OPERATIONS.md](docs/OPERATIONS.md). Security: [SECURITY.md](SECURITY.md).
+**Automation:** [CI](.github/workflows/ci.yml) (Node **20**/**22**), [CodeQL](.github/workflows/codeql.yml), [Codecov](https://codecov.io) upload, [dependency review](.github/workflows/dependency-review.yml), [SBOM](.github/workflows/supply-chain.yml), [provenance attest](.github/workflows/provenance.yml), [releases on tags](.github/workflows/release.yml), and [Dependabot](.github/dependabot.yml) (npm, Docker, Actions). Details: [docs/CI.md](docs/CI.md). Operations: [docs/OPERATIONS.md](docs/OPERATIONS.md). TypeScript client: [docs/CLIENT.md](docs/CLIENT.md). Security: [SECURITY.md](SECURITY.md).
 
 Deployment guide: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) covers safe public-demo settings and Render/Fly/Railway Docker paths.
 
@@ -132,6 +132,8 @@ Legacy errors: `{ "error": "message" }`. Versioned `/api/v1/*` errors: `{ "error
 | `npm run test:coverage` | Tests + coverage. |
 | `npm run lint` | ESLint. |
 | `npm run contract` | Validate `docs/openapi.yaml` with Redocly CLI. |
+| `npm run client:generate` | Generate TypeScript client types from `docs/openapi.yaml`. |
+| `npm run client:check` | Regenerate client types and fail if checked-in output is stale. |
 | `npm run smoke` | Curl-based smoke test against a running instance (`BASE_URL`, `QUERY`, `COUNT`, optional `CLIENT_API_KEY`). |
 | `npm run smoke:docker` | Compose smoke test: boot the image against a fake GNews provider and run `npm run smoke`. |
 | `npm run benchmark:local` | Builds the app, starts a fake GNews provider, and measures cold searches vs warm cache hits. See [docs/BENCHMARKS.md](docs/BENCHMARKS.md). |
@@ -144,6 +146,7 @@ Legacy errors: `{ "error": "message" }`. Versioned `/api/v1/*` errors: `{ "error
 - `src/logger.ts` — Pino + request logging.
 - `src/middleware/` — Security headers, rate limit, trust proxy, metrics observer, optional client API key, errors.
 - `src/http/responses.ts` — Versioned response envelope helpers.
+- `src/client/` — OpenAPI-generated TypeScript types and small v1 client wrapper.
 - `src/cache/store.ts` — Pluggable cache: memory or Redis.
 - `src/metrics/register.ts` — Prometheus registry: HTTP, cache, and upstream provider metrics.
 - `src/providers/gnewsProvider.ts` — GNews adapter: provider params, payload validation, timeouts, upstream instrumentation.

docs/CI.md

@@ -10,27 +10,28 @@ The [workflow](../.github/workflows/ci.yml) runs on `ubuntu-latest` with **Node.
 2. **`npm audit --audit-level=high`** — fails the job if high or critical advisories remain.
 3. **`npm run lint`** — [ESLint](https://eslint.org/) on `src/`, `test/`, and `vitest.config.ts`.
 4. **`npm run contract`** — [Redocly CLI](https://redocly.com/docs/cli) validates `docs/openapi.yaml` so the published API contract stays parseable and policy-compliant.
-5. **`npm test`** — [Vitest](https://vitest.dev/). GNews is **not** called: tests mock `axios`; no API key in GitHub Actions. Response contract tests compile selected `docs/openapi.yaml` schemas and validate real HTTP responses.
-6. **`npm run test:coverage`** — **Node 22 only**; uploads the `coverage/` directory (including `lcov.info`) as a workflow artifact named `coverage-lcov`.
-7. **[Codecov](https://codecov.io)** — **Node 22 only**; uploads `coverage/lcov.info`. For private repos set repository secret `CODECOV_TOKEN`. `fail_ci_if_error` is off so missing token does not break the build.
-8. **`npm run build`** — TypeScript compile to `dist/`.
+5. **`npm run client:check`** — regenerates OpenAPI TypeScript client types and fails if checked-in generated output is stale.
+6. **`npm test`** — [Vitest](https://vitest.dev/). GNews is **not** called: tests mock `axios`; no API key in GitHub Actions. Response contract tests compile selected `docs/openapi.yaml` schemas and validate real HTTP responses.
+7. **`npm run test:coverage`** — **Node 22 only**; uploads the `coverage/` directory (including `lcov.info`) as a workflow artifact named `coverage-lcov`.
+8. **[Codecov](https://codecov.io)** — **Node 22 only**; uploads `coverage/lcov.info`. For private repos set repository secret `CODECOV_TOKEN`. `fail_ci_if_error` is off so missing token does not break the build.
+9. **`npm run build`** — TypeScript compile to `dist/`.
 
 ### Container (`docker` job)
 
-9. **`npm run smoke:docker`** — Compose boots the production image against a GNews-compatible fake provider, waits for readiness, then runs `npm run smoke` against the exposed API.
-10. **Buildx build** — [Dockerfile](../Dockerfile) with **`provenance: mode=max`** and **SBOM** (no registry push). Validates supply-chain metadata generation in CI.
+10. **`npm run smoke:docker`** — Compose boots the production image against a GNews-compatible fake provider, waits for readiness, then runs `npm run smoke` against the exposed API.
+11. **Buildx build** — [Dockerfile](../Dockerfile) with **`provenance: mode=max`** and **SBOM** (no registry push). Validates supply-chain metadata generation in CI.
 
 ### Pull requests only
 
-11. **[Dependency review](../.github/workflows/dependency-review.yml)** — flags vulnerable or blocked dependencies introduced by the PR.
+12. **[Dependency review](../.github/workflows/dependency-review.yml)** — flags vulnerable or blocked dependencies introduced by the PR.
 
 ### Every push / PR (supply chain)
 
-12. **[SBOM](../.github/workflows/supply-chain.yml)** — [Anchore SBOM Action](https://github.com/anchore/sbom-action) produces SPDX JSON and uploads it as a workflow artifact.
+13. **[SBOM](../.github/workflows/supply-chain.yml)** — [Anchore SBOM Action](https://github.com/anchore/sbom-action) produces SPDX JSON and uploads it as a workflow artifact.
 
 ### `main` branch pushes only
 
-13. **[Provenance](../.github/workflows/provenance.yml)** — [build provenance attestation](https://github.com/actions/attest-build-provenance) for `package-lock.json` (best-effort; `continue-on-error` if attestations are unavailable on the plan).
+14. **[Provenance](../.github/workflows/provenance.yml)** — [build provenance attestation](https://github.com/actions/attest-build-provenance) for `package-lock.json` (best-effort; `continue-on-error` if attestations are unavailable on the plan).
 
 ### Code scanning (`CodeQL` workflow)
 
@@ -51,6 +52,7 @@ npm ci
 npm audit --audit-level=high
 npm run lint
 npm run contract
+npm run client:check
 npm test
 npm run build
 docker build .

docs/CLIENT.md

@@ -0,0 +1,54 @@
+# TypeScript Client
+
+The repository includes a tiny typed client wrapper for the versioned API plus generated
+types from `docs/openapi.yaml`.
+
+## Regenerate types
+
+```bash
+npm run client:generate
+```
+
+CI runs:
+
+```bash
+npm run client:check
+```
+
+That command regenerates `src/client/openapi-types.ts` and fails if the checked-in generated
+types drift from the OpenAPI contract.
+
+## Usage
+
+```ts
+import { NewsApiClient, NewsApiClientError } from "./src/client/newsApiClient";
+
+const client = new NewsApiClient({
+  baseUrl: "https://your-news-api.example",
+  apiKey: process.env.NEWS_API_CLIENT_KEY,
+});
+
+const result = await client.searchArticles({
+  query: "postgres",
+  count: 5,
+  lang: "en",
+  sortBy: "relevance",
+});
+
+console.log(result.meta.cache, result.data.map((article) => article.title));
+```
+
+Structured errors from `/api/v1/*` become `NewsApiClientError` instances:
+
+```ts
+try {
+  await client.searchArticles({ query: "" });
+} catch (err) {
+  if (err instanceof NewsApiClientError) {
+    console.error(err.status, err.code, err.requestId);
+  }
+}
+```
+
+The wrapper intentionally targets `/api/v1/*` only. Legacy `/api/articles*` routes remain
+available for backward compatibility, but new consumers should use v1 envelopes.

eslint.config.mjs

@@ -5,7 +5,7 @@ export default tseslint.config(
   eslint.configs.recommended,
   ...tseslint.configs.recommended,
   {
-    ignores: ["dist/**", "node_modules/**", "coverage/**"],
+    ignores: ["dist/**", "node_modules/**", "coverage/**", "src/client/openapi-types.ts"],
   },
   {
     rules: {