diff --git a/docs/README.md b/docs/README.md index aa8ffa20..69f702a1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -98,5 +98,6 @@ Connect AI assistants like Claude Code, Cursor, and Windsurf to The Codegen Proj + diff --git a/docs/contributing.md b/docs/contributing.md index c0fd6fd5..05711334 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -216,5 +216,6 @@ Prefix that follows specification is not enough though. Remember that the title + diff --git a/docs/migrations/v0.md b/docs/migrations/v0.md index bb036369..7567262c 100644 --- a/docs/migrations/v0.md +++ b/docs/migrations/v0.md @@ -244,5 +244,6 @@ import * as NodeFetch from 'node-fetch'; + diff --git a/docs/usage.md b/docs/usage.md index d6874370..f516bca5 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -9,7 +9,7 @@ $ npm install -g @the-codegen-project/cli $ codegen COMMAND running command... $ codegen (--version) -@the-codegen-project/cli/0.78.1 linux-x64 node-v22.23.1 +@the-codegen-project/cli/0.79.0 linux-x64 node-v22.23.1 $ codegen --help [COMMAND] USAGE $ codegen COMMAND @@ -80,7 +80,7 @@ FLAGS --silent Suppress all output except fatal errors ``` -_See code: [src/commands/base.ts](https://github.com/the-codegen-project/cli/blob/v0.78.1/src/commands/base.ts)_ +_See code: [src/commands/base.ts](https://github.com/the-codegen-project/cli/blob/v0.79.0/src/commands/base.ts)_ ## `codegen generate [FILE]` @@ -111,7 +111,7 @@ DESCRIPTION configuration. ``` -_See code: [src/commands/generate.ts](https://github.com/the-codegen-project/cli/blob/v0.78.1/src/commands/generate.ts)_ +_See code: [src/commands/generate.ts](https://github.com/the-codegen-project/cli/blob/v0.79.0/src/commands/generate.ts)_ ## `codegen help [COMMAND]` @@ -180,7 +180,7 @@ DESCRIPTION Initialize The Codegen Project in your project ``` -_See code: [src/commands/init.ts](https://github.com/the-codegen-project/cli/blob/v0.78.1/src/commands/init.ts)_ +_See code: [src/commands/init.ts](https://github.com/the-codegen-project/cli/blob/v0.79.0/src/commands/init.ts)_ ## `codegen telemetry ACTION` @@ -213,7 +213,7 @@ EXAMPLES $ codegen telemetry disable ``` -_See code: [src/commands/telemetry.ts](https://github.com/the-codegen-project/cli/blob/v0.78.1/src/commands/telemetry.ts)_ +_See code: [src/commands/telemetry.ts](https://github.com/the-codegen-project/cli/blob/v0.79.0/src/commands/telemetry.ts)_ ## `codegen version` diff --git a/mcp-server/lib/resources/bundled-docs.ts b/mcp-server/lib/resources/bundled-docs.ts index f44631dc..fc436dd1 100644 --- a/mcp-server/lib/resources/bundled-docs.ts +++ b/mcp-server/lib/resources/bundled-docs.ts @@ -1,7 +1,7 @@ /** * Auto-generated documentation bundle. * DO NOT EDIT - regenerate with: npm run bundle-docs - * Generated at: 2026-07-22T20:35:56.073Z + * Generated at: 2026-07-23T16:19:30.085Z */ export interface DocEntry { @@ -120,7 +120,7 @@ export const docs: Record = { }, "protocols/http_client": { title: "HTTP(S)", - content: "# HTTP(S)\n\nHTTP client generator creates type-safe functions for making HTTP requests based on your API specification. It supports various authentication methods, retry logic, and extensibility hooks.\n\nIt is currently available through the generators ([channels](../generators/channels.md)):\n\nThis is available through [AsyncAPI](../inputs/asyncapi.md) ([requires the HTTP `method` binding for operations and `statusCode` for messages](../inputs/asyncapi.md#http-client)) and directly from [OpenAPI](../inputs/openapi.md) documents (see [From OpenAPI](#from-openapi) below).\n\n## TypeScript\n\n| **Feature** | Is supported? |\n|---|---|\n| Download | ❌ |\n| Upload | ❌ |\n| Retry with backoff | ✅ |\n| OAuth2 Authorization code | ❌ (browser-only) |\n| OAuth2 Implicit | ❌ (browser-only) |\n| OAuth2 Password | ✅ |\n| OAuth2 Client Credentials | ✅ |\n| OAuth2 Token Refresh | ✅ |\n| Username/password Authentication | ✅ |\n| Bearer Authentication | ✅ |\n| Basic Authentication | ✅ |\n| API Key Authentication | ✅ |\n| Request/Response Hooks | ✅ |\n| XML Based API | ❌ |\n| JSON Based API | ✅ |\n| POST | ✅ |\n| GET | ✅ |\n| PATCH | ✅ |\n| DELETE | ✅ |\n| PUT | ✅ |\n| HEAD | ✅ |\n| OPTIONS | ✅ |\n\n## Channels\n\nRead more about the [channels generator here](../generators/channels.md).\n\n\n\n \n \n \n \n\n\n \n \n \n \n\n
Input (AsyncAPI)Using the code
\n\n```yaml\nasyncapi: 3.0.0\ninfo:\n title: User API\n version: 1.0.0\nchannels:\n ping:\n address: /ping\n messages:\n pingRequest:\n $ref: '#/components/messages/PingRequest'\n pongResponse:\n $ref: '#/components/messages/PongResponse'\noperations:\n postPing:\n action: send\n channel:\n $ref: '#/channels/ping'\n bindings:\n http:\n method: POST\n reply:\n channel:\n $ref: '#/channels/ping'\n messages:\n - $ref: '#/channels/ping/messages/pongResponse'\ncomponents:\n messages:\n PingRequest:\n payload:\n type: object\n properties:\n message:\n type: string\n PongResponse:\n payload:\n type: object\n properties:\n response:\n type: string\n bindings:\n http:\n statusCode: 200\n```\n\n\n```ts\n// Location depends on the payload generator configurations\nimport { Ping } from './__gen__/payloads/Ping';\nimport { Pong } from './__gen__/payloads/Pong';\n// Location depends on the channel generator configurations\nimport { Protocols } from './__gen__/channels';\nconst { http_client } = Protocols;\nconst { postPingPostRequest } = http_client;\n\n// Create a request payload\nconst pingMessage = new Ping({ message: 'Hello!' });\n\n// Make a simple request\nconst response = await postPingPostRequest({\n payload: pingMessage,\n baseUrl: 'https://api.example.com'\n});\n\n// Access the response\nconsole.log(response.data.response); // The deserialized Pong\nconsole.log(response.status); // 200\nconsole.log(response.headers); // Response headers\nconsole.log(response.rawData); // Raw JSON response\n```\n
\n\n### From OpenAPI\n\nThe `http_client` protocol is also generated directly from an OpenAPI document (2.0/3.0/3.1). Each path + method becomes one function. Configure the `channels` generator with `inputType: 'openapi'` and `protocols: ['http_client']`.\n\nFunction names come from each operation's `operationId` (camel-cased). When an operation has **no** `operationId`, a name is synthesized from the method and path, e.g. `GET /v2/connect/{referenceId}` → `getV2ConnectReferenceId`. Give your operations `operationId`s for the cleanest client.\n\nAs a consumer you work with three generated pieces: the **call functions** (`http_client.ts`), the **request/response body models** (`payload/`), and the **path/query parameter models** (`parameter/`):\n\n```ts\nimport { http_client } from './__gen__/channels';\nimport { PostV2ConnectRequest } from './__gen__/channels/payload/PostV2ConnectRequest';\nimport { GetV2ConnectReferenceIdParameters } from './__gen__/channels/parameter/GetV2ConnectReferenceIdParameters';\n\n// Request with a body: build the model, pass it as `payload`.\nconst created = await http_client.postV2Connect({\n baseUrl: 'https://api.example.com',\n payload: new PostV2ConnectRequest({ returnUrl: 'https://shop.example/return' })\n});\nconsole.log(created.data.connectUrl); // typed response model\n\n// Request with a path parameter: supply it through the parameter model.\nconst connect = await http_client.getV2ConnectReferenceId({\n baseUrl: 'https://api.example.com',\n parameters: new GetV2ConnectReferenceIdParameters({ referenceId: 'ref_123' })\n});\nconsole.log(connect.data.safepayAccountId);\n```\n\nSee the runnable [`openapi-http-client` example](https://github.com/the-codegen-project/cli/tree/main/examples/openapi-http-client) for a complete, self-contained setup.\n\n## Authentication\n\nThe HTTP client uses a discriminated union for authentication, providing excellent TypeScript autocomplete support.\n\n### Bearer Token\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'bearer',\n token: 'your-jwt-token'\n }\n});\n```\n\n### Basic Authentication\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'basic',\n username: 'user',\n password: 'pass'\n }\n});\n```\n\n### API Key\n\n```typescript\n// API Key in header (default)\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'apiKey',\n key: 'your-api-key',\n name: 'X-API-Key', // Header name (default: 'X-API-Key')\n in: 'header' // 'header' or 'query'\n }\n});\n\n// API Key in query parameter\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'apiKey',\n key: 'your-api-key',\n name: 'api_key',\n in: 'query'\n }\n});\n```\n\n### OAuth2 Client Credentials\n\nFor server-to-server authentication:\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'oauth2',\n flow: 'client_credentials',\n clientId: 'your-client-id',\n clientSecret: 'your-client-secret',\n tokenUrl: 'https://auth.example.com/oauth/token',\n scopes: ['read', 'write'],\n onTokenRefresh: (tokens) => {\n // Called when tokens are obtained/refreshed\n console.log('New access token:', tokens.accessToken);\n }\n }\n});\n```\n\n### OAuth2 Password Flow\n\nFor legacy applications requiring username/password:\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'oauth2',\n flow: 'password',\n clientId: 'your-client-id',\n username: 'user@example.com',\n password: 'user-password',\n tokenUrl: 'https://auth.example.com/oauth/token',\n onTokenRefresh: (tokens) => {\n // Store tokens for future use\n saveTokens(tokens);\n }\n }\n});\n```\n\n### OAuth2 with Pre-obtained Token\n\nFor tokens obtained via browser-based flows (implicit, authorization code):\n\n```typescript\n// Token obtained from browser OAuth flow\nconst accessToken = getTokenFromBrowserFlow();\n\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'oauth2',\n accessToken: accessToken,\n refreshToken: refreshToken, // Optional: for auto-refresh on 401\n tokenUrl: 'https://auth.example.com/oauth/token',\n clientId: 'your-client-id',\n onTokenRefresh: (tokens) => {\n // Update stored tokens\n updateStoredTokens(tokens);\n }\n }\n});\n```\n\n## Retry with Exponential Backoff\n\nConfigure automatic retry for failed requests:\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n retry: {\n maxRetries: 3, // Maximum retry attempts (default: 3)\n initialDelayMs: 1000, // Initial delay before first retry (default: 1000)\n maxDelayMs: 30000, // Maximum delay between retries (default: 30000)\n backoffMultiplier: 2, // Exponential backoff multiplier (default: 2)\n retryableStatusCodes: [408, 429, 500, 502, 503, 504], // Status codes to retry\n retryOnNetworkError: true, // Retry on network failures\n onRetry: (attempt, delay, error) => {\n console.log(`Retry attempt ${attempt} after ${delay}ms: ${error.message}`);\n }\n }\n});\n```\n\n## Request/Response Hooks\n\nCustomize request behavior with hooks:\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n hooks: {\n // Modify request before sending\n beforeRequest: async (params) => {\n console.log('Making request to:', params.url);\n // Add custom header\n return {\n ...params,\n headers: {\n ...params.headers,\n 'X-Request-ID': generateRequestId()\n }\n };\n },\n\n // Replace the default fetch implementation\n makeRequest: async (params) => {\n // Use axios, got, or any HTTP client\n const axiosResponse = await axios({\n url: params.url,\n method: params.method,\n headers: params.headers,\n data: params.body\n });\n return {\n ok: axiosResponse.status >= 200 && axiosResponse.status < 300,\n status: axiosResponse.status,\n statusText: axiosResponse.statusText,\n headers: axiosResponse.headers,\n json: () => axiosResponse.data\n };\n },\n\n // Process response after receiving\n afterResponse: async (response, params) => {\n console.log(`Response ${response.status} from ${params.url}`);\n return response;\n },\n\n // Handle errors\n onError: async (error, params) => {\n console.error(`Request failed: ${error.message}`);\n // Optionally transform the error\n return error;\n }\n }\n});\n```\n\n## Path Parameters\n\nFor operations with path parameters, the generator creates typed parameter classes:\n\n```typescript\nimport { UserItemsParameters } from './__gen__/parameters/UserItemsParameters';\n\n// Create parameters with type safety\nconst params = new UserItemsParameters({\n userId: 'user-123',\n itemId: 456\n});\n\nconst response = await getGetUserItem({\n baseUrl: 'https://api.example.com',\n parameters: params // Replaces {userId} and {itemId} in path\n});\n```\n\n## Typed Headers\n\nFor operations with defined headers, the generator creates typed header classes:\n\n```typescript\nimport { ItemRequestHeaders } from './__gen__/headers/ItemRequestHeaders';\n\nconst headers = new ItemRequestHeaders({\n xCorrelationId: 'corr-123',\n xRequestId: 'req-456'\n});\n\nconst response = await putUpdateUserItem({\n baseUrl: 'https://api.example.com',\n parameters: params,\n payload: itemData,\n requestHeaders: headers // Type-safe headers\n});\n```\n\n## Additional Headers and Query Parameters\n\nAdd custom headers or query parameters to any request:\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n additionalHeaders: {\n 'X-Custom-Header': 'value',\n 'Accept-Language': 'en-US'\n },\n additionalQueryParams: {\n include: 'metadata',\n format: 'detailed'\n }\n});\n```\n\n## Multi-Status Responses\n\nFor operations that return different payloads based on status code, the generator creates union types:\n\n```yaml\n# AsyncAPI spec with multiple response types\noperations:\n getItem:\n reply:\n messages:\n - $ref: '#/components/messages/ItemResponse' # 200\n - $ref: '#/components/messages/NotFoundError' # 404\n```\n\n```typescript\nconst response = await getItemRequest({\n baseUrl: 'https://api.example.com',\n parameters: params\n});\n\n// Response type is union: ItemResponse | NotFoundError\n// Use response.status to discriminate\nif (response.status === 200) {\n console.log('Item:', response.data); // ItemResponse\n} else if (response.status === 404) {\n console.log('Not found:', response.data); // NotFoundError\n}\n```", + content: "# HTTP(S)\n\nHTTP client generator creates type-safe functions for making HTTP requests based on your API specification. It supports various authentication methods, retry logic, and extensibility hooks.\n\nIt is currently available through the generators ([channels](../generators/channels.md)):\n\nThis is available through [AsyncAPI](../inputs/asyncapi.md) ([requires the HTTP `method` binding for operations and `statusCode` for messages](../inputs/asyncapi.md#http-client)) and directly from [OpenAPI](../inputs/openapi.md) documents (see [From OpenAPI](#from-openapi) below).\n\n## TypeScript\n\n| **Feature** | Is supported? |\n|---|---|\n| Download | ❌ |\n| Upload | ❌ |\n| Retry with backoff | ✅ |\n| OAuth2 Authorization code | ❌ (browser-only) |\n| OAuth2 Implicit | ❌ (browser-only) |\n| OAuth2 Password | ✅ |\n| OAuth2 Client Credentials | ✅ |\n| OAuth2 Token Refresh | ✅ |\n| Username/password Authentication | ✅ |\n| Bearer Authentication | ✅ |\n| Basic Authentication | ✅ |\n| API Key Authentication | ✅ |\n| Request/Response Hooks | ✅ |\n| XML Based API | ❌ |\n| JSON Based API | ✅ |\n| POST | ✅ |\n| GET | ✅ |\n| PATCH | ✅ |\n| DELETE | ✅ |\n| PUT | ✅ |\n| HEAD | ✅ |\n| OPTIONS | ✅ |\n\n## Channels\n\nRead more about the [channels generator here](../generators/channels.md).\n\n\n\n \n \n \n \n\n\n \n \n \n \n\n
Input (AsyncAPI)Using the code
\n\n```yaml\nasyncapi: 3.0.0\ninfo:\n title: User API\n version: 1.0.0\nchannels:\n ping:\n address: /ping\n messages:\n pingRequest:\n $ref: '#/components/messages/PingRequest'\n pongResponse:\n $ref: '#/components/messages/PongResponse'\noperations:\n postPing:\n action: send\n channel:\n $ref: '#/channels/ping'\n bindings:\n http:\n method: POST\n reply:\n channel:\n $ref: '#/channels/ping'\n messages:\n - $ref: '#/channels/ping/messages/pongResponse'\ncomponents:\n messages:\n PingRequest:\n payload:\n type: object\n properties:\n message:\n type: string\n PongResponse:\n payload:\n type: object\n properties:\n response:\n type: string\n bindings:\n http:\n statusCode: 200\n```\n\n\n```ts\n// Location depends on the payload generator configurations\nimport { Ping } from './__gen__/payloads/Ping';\nimport { Pong } from './__gen__/payloads/Pong';\n// Location depends on the channel generator configurations\nimport { Protocols } from './__gen__/channels';\nconst { http_client } = Protocols;\nconst { postPingPostRequest } = http_client;\n\n// Create a request payload\nconst pingMessage = new Ping({ message: 'Hello!' });\n\n// Make a simple request\nconst response = await postPingPostRequest({\n payload: pingMessage,\n baseUrl: 'https://api.example.com'\n});\n\n// Access the response\nconsole.log(response.data.response); // The deserialized Pong\nconsole.log(response.status); // 200\nconsole.log(response.headers); // Response headers\nconsole.log(response.rawData); // Raw JSON response\n```\n
\n\n### From OpenAPI\n\nThe `http_client` protocol is also generated directly from an OpenAPI document (2.0/3.0/3.1). Each path + method becomes one function. Configure the `channels` generator with `inputType: 'openapi'` and `protocols: ['http_client']`.\n\nFunction names come from each operation's `operationId` (camel-cased). When an operation has **no** `operationId`, a name is synthesized from the method and path, e.g. `GET /v2/connect/{referenceId}` → `getV2ConnectReferenceId`. Give your operations `operationId`s for the cleanest client.\n\nAs a consumer you work with three generated pieces: the **call functions** (`http_client.ts`), the **request/response body models** (`payload/`), and the **path/query parameter models** (`parameter/`):\n\n```ts\nimport { http_client } from './__gen__/channels';\nimport { PostV2ConnectRequest } from './__gen__/channels/payload/PostV2ConnectRequest';\nimport { GetV2ConnectReferenceIdParameters } from './__gen__/channels/parameter/GetV2ConnectReferenceIdParameters';\n\n// Request with a body: build the model, pass it as `payload`.\nconst created = await http_client.postV2Connect({\n baseUrl: 'https://api.example.com',\n payload: new PostV2ConnectRequest({ returnUrl: 'https://shop.example/return' })\n});\nconsole.log(created.data.connectUrl); // typed response model\n\n// Request with a path parameter: supply it through the parameter model.\nconst connect = await http_client.getV2ConnectReferenceId({\n baseUrl: 'https://api.example.com',\n parameters: new GetV2ConnectReferenceIdParameters({ referenceId: 'ref_123' })\n});\nconsole.log(connect.data.safepayAccountId);\n```\n\nSee the runnable [`openapi-http-client` example](https://github.com/the-codegen-project/cli/tree/main/examples/openapi-http-client) for a complete, self-contained setup.\n\n## Authentication\n\nThe HTTP client uses a discriminated union for authentication, providing excellent TypeScript autocomplete support.\n\n### Bearer Token\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'bearer',\n token: 'your-jwt-token'\n }\n});\n```\n\n### Basic Authentication\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'basic',\n username: 'user',\n password: 'pass'\n }\n});\n```\n\n### API Key\n\n```typescript\n// API Key in header (default)\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'apiKey',\n key: 'your-api-key',\n name: 'X-API-Key', // Header name (default: 'X-API-Key')\n in: 'header' // 'header' or 'query'\n }\n});\n\n// API Key in query parameter\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'apiKey',\n key: 'your-api-key',\n name: 'api_key',\n in: 'query'\n }\n});\n```\n\n### OAuth2 Client Credentials\n\nFor server-to-server authentication:\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'oauth2',\n flow: 'client_credentials',\n clientId: 'your-client-id',\n clientSecret: 'your-client-secret',\n tokenUrl: 'https://auth.example.com/oauth/token',\n scopes: ['read', 'write'],\n onTokenRefresh: (tokens) => {\n // Called when tokens are obtained/refreshed\n console.log('New access token:', tokens.accessToken);\n }\n }\n});\n```\n\n### OAuth2 Password Flow\n\nFor legacy applications requiring username/password:\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'oauth2',\n flow: 'password',\n clientId: 'your-client-id',\n username: 'user@example.com',\n password: 'user-password',\n tokenUrl: 'https://auth.example.com/oauth/token',\n onTokenRefresh: (tokens) => {\n // Store tokens for future use\n saveTokens(tokens);\n }\n }\n});\n```\n\n### OAuth2 with Pre-obtained Token\n\nFor tokens obtained via browser-based flows (implicit, authorization code):\n\n```typescript\n// Token obtained from browser OAuth flow\nconst accessToken = getTokenFromBrowserFlow();\n\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'oauth2',\n accessToken: accessToken,\n refreshToken: refreshToken, // Optional: for auto-refresh on 401\n tokenUrl: 'https://auth.example.com/oauth/token',\n clientId: 'your-client-id',\n onTokenRefresh: (tokens) => {\n // Update stored tokens\n updateStoredTokens(tokens);\n }\n }\n});\n```\n\n## Retry with Exponential Backoff\n\nConfigure automatic retry for failed requests:\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n retry: {\n maxRetries: 3, // Maximum retry attempts (default: 3)\n initialDelayMs: 1000, // Initial delay before first retry (default: 1000)\n maxDelayMs: 30000, // Maximum delay between retries (default: 30000)\n backoffMultiplier: 2, // Exponential backoff multiplier (default: 2)\n retryableStatusCodes: [408, 429, 500, 502, 503, 504], // Status codes to retry\n retryOnNetworkError: true, // Retry on network failures\n onRetry: (attempt, delay, error) => {\n console.log(`Retry attempt ${attempt} after ${delay}ms: ${error.message}`);\n }\n }\n});\n```\n\n## Error Handling\n\nNon-OK HTTP responses **throw** a typed `HttpError` instead of returning. `HttpError` extends the built-in `Error` and carries the HTTP `status`, `statusText`, and the parsed response `body`:\n\n```typescript\nexport class HttpError extends Error {\n status: number;\n statusText: string;\n body?: unknown; // the parsed JSON error body, when present\n}\n```\n\nConsume it with an `instanceof` check:\n\n```typescript\nimport { getGetUser, HttpError } from './__gen__/channels/http_client';\n\ntry {\n const response = await getGetUser({ baseUrl: 'https://api.example.com' });\n // response.data is the typed, unmarshalled success payload\n} catch (error) {\n if (error instanceof HttpError) {\n console.error(error.status); // e.g. 404\n console.error(error.statusText); // e.g. 'Not Found'\n console.error(error.body); // parsed error body (unknown)\n }\n}\n```\n\n## Request/Response Hooks\n\nCustomize request behavior with hooks:\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n hooks: {\n // Modify request before sending\n beforeRequest: async (params) => {\n console.log('Making request to:', params.url);\n // Add custom header\n return {\n ...params,\n headers: {\n ...params.headers,\n 'X-Request-ID': generateRequestId()\n }\n };\n },\n\n // Replace the default fetch implementation\n makeRequest: async (params) => {\n // Use axios, got, or any HTTP client\n const axiosResponse = await axios({\n url: params.url,\n method: params.method,\n headers: params.headers,\n data: params.body\n });\n return {\n ok: axiosResponse.status >= 200 && axiosResponse.status < 300,\n status: axiosResponse.status,\n statusText: axiosResponse.statusText,\n headers: axiosResponse.headers,\n json: () => axiosResponse.data\n };\n },\n\n // Process response after receiving\n afterResponse: async (response, params) => {\n console.log(`Response ${response.status} from ${params.url}`);\n return response;\n },\n\n // Handle errors\n onError: async (error, params) => {\n console.error(`Request failed: ${error.message}`);\n // Optionally transform the error\n return error;\n }\n }\n});\n```\n\n## Path Parameters\n\nFor operations with path parameters, the generator creates typed parameter classes:\n\n```typescript\nimport { UserItemsParameters } from './__gen__/parameters/UserItemsParameters';\n\n// Create parameters with type safety\nconst params = new UserItemsParameters({\n userId: 'user-123',\n itemId: 456\n});\n\nconst response = await getGetUserItem({\n baseUrl: 'https://api.example.com',\n parameters: params // Replaces {userId} and {itemId} in path\n});\n```\n\n## Typed Headers\n\nFor operations with defined headers, the generator creates typed header classes:\n\n```typescript\nimport { ItemRequestHeaders } from './__gen__/headers/ItemRequestHeaders';\n\nconst headers = new ItemRequestHeaders({\n xCorrelationId: 'corr-123',\n xRequestId: 'req-456'\n});\n\nconst response = await putUpdateUserItem({\n baseUrl: 'https://api.example.com',\n parameters: params,\n payload: itemData,\n requestHeaders: headers // Type-safe headers\n});\n```\n\n## Additional Headers and Query Parameters\n\nAdd custom headers or query parameters to any request:\n\n```typescript\nconst response = await postPingPostRequest({\n payload: message,\n baseUrl: 'https://api.example.com',\n additionalHeaders: {\n 'X-Custom-Header': 'value',\n 'Accept-Language': 'en-US'\n },\n additionalQueryParams: {\n include: 'metadata',\n format: 'detailed'\n }\n});\n```\n\n## Multi-Status Responses\n\nFor operations that return different payloads based on status code, the generator creates union types:\n\n```yaml\n# AsyncAPI spec with multiple response types\noperations:\n getItem:\n reply:\n messages:\n - $ref: '#/components/messages/ItemResponse' # 200\n - $ref: '#/components/messages/NotFoundError' # 404\n```\n\n```typescript\nconst response = await getItemRequest({\n baseUrl: 'https://api.example.com',\n parameters: params\n});\n\n// Response type is union: ItemResponse | NotFoundError\n// Use response.status to discriminate\nif (response.status === 200) {\n console.log('Item:', response.data); // ItemResponse\n} else if (response.status === 404) {\n console.log('Not found:', response.data); // NotFoundError\n}\n```", }, "protocols/kafka": { title: "Kafka", @@ -144,7 +144,7 @@ export const docs: Record = { }, "usage": { title: "CLI Usage", - content: "# CLI Usage\n\n\n```sh-session\n$ npm install -g @the-codegen-project/cli\n$ codegen COMMAND\nrunning command...\n$ codegen (--version)\n@the-codegen-project/cli/0.78.1 linux-x64 node-v22.23.1\n$ codegen --help [COMMAND]\nUSAGE\n $ codegen COMMAND\n...\n```\n\n\n## Table of contents\n\n\n* [CLI Usage](#cli-usage)\n\n\n## Commands\n\n\n* [`codegen autocomplete [SHELL]`](#codegen-autocomplete-shell)\n* [`codegen base`](#codegen-base)\n* [`codegen generate [FILE]`](#codegen-generate-file)\n* [`codegen help [COMMAND]`](#codegen-help-command)\n* [`codegen init`](#codegen-init)\n* [`codegen telemetry ACTION`](#codegen-telemetry-action)\n* [`codegen version`](#codegen-version)\n\n## `codegen autocomplete [SHELL]`\n\nDisplay autocomplete installation instructions.\n\n```\nUSAGE\n $ codegen autocomplete [SHELL] [-r]\n\nARGUMENTS\n SHELL (zsh|bash|powershell) Shell type\n\nFLAGS\n -r, --refresh-cache Refresh cache (ignores displaying instructions)\n\nDESCRIPTION\n Display autocomplete installation instructions.\n\nEXAMPLES\n $ codegen autocomplete\n\n $ codegen autocomplete bash\n\n $ codegen autocomplete zsh\n\n $ codegen autocomplete powershell\n\n $ codegen autocomplete --refresh-cache\n```\n\n_See code: [@oclif/plugin-autocomplete](https://github.com/oclif/plugin-autocomplete/blob/v3.2.45/src/commands/autocomplete/index.ts)_\n\n## `codegen base`\n\n```\nUSAGE\n $ codegen base [--json] [--no-color] [--debug | [-q | -v | --silent] | ]\n\nFLAGS\n -q, --quiet Only show errors and warnings\n -v, --verbose Show detailed output\n --debug Show debug information\n --json Output results as JSON for scripting\n --no-color Disable colored output\n --silent Suppress all output except fatal errors\n```\n\n_See code: [src/commands/base.ts](https://github.com/the-codegen-project/cli/blob/v0.78.1/src/commands/base.ts)_\n\n## `codegen generate [FILE]`\n\nGenerate code based on your configuration, use `init` to get started, `generate` to generate code from the configuration.\n\n```\nUSAGE\n $ codegen generate [FILE] [--json] [--no-color] [--debug | [-q | -v | --silent] | ] [--help] [-w] [-p\n ]\n\nARGUMENTS\n FILE Path or URL to the configuration file, defaults to root of where the command is run\n\nFLAGS\n -p, --watchPath= Optional path to watch for changes when --watch flag is used. If not provided, watches the\n input file from configuration\n -q, --quiet Only show errors and warnings\n -v, --verbose Show detailed output\n -w, --watch Watch for file changes and regenerate code automatically\n --debug Show debug information\n --help Show CLI help.\n --json Output results as JSON for scripting\n --no-color Disable colored output\n --silent Suppress all output except fatal errors\n\nDESCRIPTION\n Generate code based on your configuration, use `init` to get started, `generate` to generate code from the\n configuration.\n```\n\n_See code: [src/commands/generate.ts](https://github.com/the-codegen-project/cli/blob/v0.78.1/src/commands/generate.ts)_\n\n## `codegen help [COMMAND]`\n\nDisplay help for codegen.\n\n```\nUSAGE\n $ codegen help [COMMAND...] [-n]\n\nARGUMENTS\n COMMAND... Command to show help for.\n\nFLAGS\n -n, --nested-commands Include all nested commands in the output.\n\nDESCRIPTION\n Display help for codegen.\n```\n\n_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.0.22/src/commands/help.ts)_\n\n## `codegen init`\n\nInitialize The Codegen Project in your project\n\n```\nUSAGE\n $ codegen init [--json] [--no-color] [--debug | | [--silent | -v | -q]] [--help] [--input-file ]\n [--config-name ] [--input-type asyncapi|openapi|jsonschema] [--output-directory ] [--config-type\n esm|json|yaml|ts] [--languages typescript] [--no-tty] [--include-payloads] [--include-headers] [--include-client]\n [--include-parameters] [--include-channels] [--include-types] [--include-models] [--gitignore-generated]\n\nFLAGS\n -q, --quiet Only show errors and warnings\n -v, --verbose Show detailed output\n --config-name= [default: codegen] The name to use for the configuration file (dont include file\n extension)\n --config-type=