From 0d76430b5c2268046cbd5d1b89a9c7fbd74fd7c0 Mon Sep 17 00:00:00 2001 From: jonaslagoni Date: Wed, 15 Jul 2026 18:13:57 +0000 Subject: [PATCH] chore(release): v0.76.0 --- docs/README.md | 1 + docs/contributing.md | 1 + docs/migrations/v0.md | 1 + docs/usage.md | 10 +- mcp-server/lib/resources/bundled-docs.ts | 10 +- package-lock.json | 4 +- package.json | 2 +- src/codegen/generators/typescript/headers.ts | 5 +- website/static/codegen.browser.mjs | 829 +++++++------------ 9 files changed, 316 insertions(+), 547 deletions(-) diff --git a/docs/README.md b/docs/README.md index 0e60b0b3..94a1b2e6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -94,5 +94,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 610402b7..1e2c7aea 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -212,5 +212,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 721a9101..e6fcc654 100644 --- a/docs/migrations/v0.md +++ b/docs/migrations/v0.md @@ -242,3 +242,4 @@ import * as NodeFetch from 'node-fetch'; + diff --git a/docs/usage.md b/docs/usage.md index ac385a82..699ce202 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.74.3 linux-x64 node-v22.23.1 +@the-codegen-project/cli/0.76.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.74.3/src/commands/base.ts)_ +_See code: [src/commands/base.ts](https://github.com/the-codegen-project/cli/blob/v0.76.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.74.3/src/commands/generate.ts)_ +_See code: [src/commands/generate.ts](https://github.com/the-codegen-project/cli/blob/v0.76.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.74.3/src/commands/init.ts)_ +_See code: [src/commands/init.ts](https://github.com/the-codegen-project/cli/blob/v0.76.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.74.3/src/commands/telemetry.ts)_ +_See code: [src/commands/telemetry.ts](https://github.com/the-codegen-project/cli/blob/v0.76.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 66b39310..87bf2381 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-14T14:52:52.551Z + * Generated at: 2026-07-15T18:13:56.747Z */ export interface DocEntry { @@ -44,7 +44,7 @@ export const docs: Record = { }, "generators/client": { title: "Client", - content: "# Client\n\n```js\nexport default {\n ...,\n generators: [\n {\n preset: 'client',\n outputPath: './src/__gen__/', \n language: 'typescript',\n protocols: ['nats']\n }\n ]\n};\n```\n\n`client` preset generates a class that makes it easier to interact with a protocol. For message brokers (`nats`) this is a `{Protocol}Client` that manages the connection; for `http` it is a single API client class whose name is derived from the input document title (see [HTTP](#http)).\n\nIt will generate;\n- Support function for connecting to the protocol (message brokers) or holding shared request configuration (HTTP)\n- Simpler functions then those generated by [`channels`](./channels.md) to interact with the given protocols\n- Exporting all generated [`parameters`](./parameters.md)\n- Exporting all generated [`payloads`](./payloads.md)\n\nThis generator uses `channels` generators, in case you dont have any defined, it will automatically include them with default values and dependencies. When a configured protocol has no matching channel functions in the input document, no client is emitted for it.\n\nThis is supported through the following inputs: [`asyncapi`](../inputs/asyncapi.md), [`openapi`](../inputs/openapi.md) (HTTP only)\n\nIt supports the following languages; [`typescript`](#typescript)\n\nIt supports the following protocols; [`nats`](../protocols/nats.md), [`http`](../protocols/http_client.md)\n\n## TypeScript\n\n### Nats\n\nDependencies;\n- `NATS`: https://github.com/nats-io/nats.js v2\n\nFor Nats the `NatsClient` is generated that setups the correct [Nats.js](https://github.com/nats-io/nats.js) clients, marshalling codex, and provide simplier functions to improve DX.\n\nExample;\n```ts\n//Import and export payload models\nimport {Payload} from './payload/Payload';\nexport {Payload};\n\n//Import and export parameter models\nimport {Parameters} from './parameters/Parameters';\n\n//Import channel functions\nimport { Protocols } from './channels/index';\nconst { nats } = Protocols;\n\nimport * as Nats from 'nats';\n\n/**\n * @class NatsClient\n */\nexport class NatsClient {\n /**\n * Disconnect all clients from the server\n */\n async disconnect() {\n ...\n }\n /**\n * Returns whether or not any of the clients are closed\n */\n isClosed() {\n ...\n }\n /**\n * Try to connect to the NATS server with user credentials\n */\n async connectWithUserCreds(userCreds: string, options ? : Nats.ConnectionOptions, codec ? : Nats.Codec < any > ) {\n ...\n }\n /**\n * Try to connect to the NATS server with user and password\n */\n async connectWithUserPass(user: string, pass: string, options ? : Nats.ConnectionOptions, codec ? : Nats.Codec < any > ) {\n ...\n }\n /**\n * Try to connect to the NATS server which has no authentication\n */\n async connectToHost(host: string, options ? : Nats.ConnectionOptions, codec ? : Nats.Codec < any > ) {\n ...\n }\n\n /**\n * Try to connect to the NATS server with the different payloads.\n */\n connect(options: Nats.ConnectionOptions, codec?: Nats.Codec): Promise {\n ...\n }\n \n public async jetStreamPublishToChannel(\n message: Payload, \n parameters: Parameters, \n options: Partial = {}\n ): Promise {\n ...\n }\n jetStreamPullSubscribeToChannel\n jetStreamPushSubscriptionFromChannel\n publishToChannel\n subscribeToChannel\n}\n```\n\n### HTTP\n\nFor `http` a single API client class is generated that wraps the standalone [`http_client`](../protocols/http_client.md) channel functions. You construct it once with the shared request configuration (`server`, `auth`, `hooks`, retry, pagination, ...) and every operation becomes a method that reuses that configuration; any field can still be overridden per call.\n\n```js\nexport default {\n inputType: 'openapi',\n inputPath: './my-api.json',\n generators: [\n {\n preset: 'client',\n outputPath: './src/__gen__/client',\n language: 'typescript',\n protocols: ['http']\n }\n ]\n};\n```\n\nThe class name is derived from the input document title (a `\"Safepay Nordic API\"` title yields `SafepayNordicClient`), falling back to `HttpClient`. Override it explicitly with the `clientName` option.\n\nExample generated usage:\n```ts\nimport {SafepayNordicClient} from './__gen__/client/SafepayNordicClient';\n\nconst safepay = new SafepayNordicClient({\n server: 'https://api.example.com',\n auth: {type: 'bearer', token: process.env.API_TOKEN ?? ''}\n});\n\n// Shared server/auth are reused; the call only supplies what is operation-specific.\nconst response = await safepay.getV2Documents();\nconsole.log(response.status, response.data);\n```\n\nEach method returns the same `HttpClientResponse` as the underlying channel function, so response metadata (status, headers, pagination helpers) is preserved.", + content: "# Client\n\n```js\nexport default {\n ...,\n generators: [\n {\n preset: 'client',\n outputPath: './src/__gen__/', \n language: 'typescript',\n protocols: ['nats']\n }\n ]\n};\n```\n\n`client` preset generates a class that makes it easier to interact with a protocol. For message brokers (`nats`) this is a `{Protocol}Client` that manages the connection; for `http` it is a single API client class whose name is derived from the input document title (see [HTTP](#http)).\n\nIt will generate;\n- Support function for connecting to the protocol (message brokers) or holding shared request configuration (HTTP)\n- Simpler functions then those generated by [`channels`](./channels.md) to interact with the given protocols\n- Exporting all generated [`parameters`](./parameters.md)\n- Exporting all generated [`payloads`](./payloads.md)\n\nThis generator uses `channels` generators, in case you dont have any defined, it will automatically include them with default values and dependencies. When a configured protocol has no matching channel functions in the input document, no client is emitted for it.\n\nThis is supported through the following inputs: [`asyncapi`](../inputs/asyncapi.md), [`openapi`](../inputs/openapi.md) (HTTP only)\n\nIt supports the following languages; [`typescript`](#typescript)\n\nIt supports the following protocols; [`nats`](../protocols/nats.md), [`http`](../protocols/http_client.md)\n\n## TypeScript\n\n### Nats\n\nDependencies;\n- `NATS`: https://github.com/nats-io/nats.js v2\n\nFor Nats the `NatsClient` is generated that setups the correct [Nats.js](https://github.com/nats-io/nats.js) clients, marshalling codex, and provide simplier functions to improve DX.\n\nExample;\n```ts\n//Import and export payload models\nimport {Payload} from './payload/Payload';\nexport {Payload};\n\n//Import and export parameter models\nimport {Parameters} from './parameters/Parameters';\n\n//Import channel functions\nimport { Protocols } from './channels/index';\nconst { nats } = Protocols;\n\nimport * as Nats from 'nats';\n\n/**\n * @class NatsClient\n */\nexport class NatsClient {\n /**\n * Disconnect all clients from the server\n */\n async disconnect() {\n ...\n }\n /**\n * Returns whether or not any of the clients are closed\n */\n isClosed() {\n ...\n }\n /**\n * Try to connect to the NATS server with user credentials\n */\n async connectWithUserCreds(userCreds: string, options ? : Nats.ConnectionOptions, codec ? : Nats.Codec < any > ) {\n ...\n }\n /**\n * Try to connect to the NATS server with user and password\n */\n async connectWithUserPass(user: string, pass: string, options ? : Nats.ConnectionOptions, codec ? : Nats.Codec < any > ) {\n ...\n }\n /**\n * Try to connect to the NATS server which has no authentication\n */\n async connectToHost(host: string, options ? : Nats.ConnectionOptions, codec ? : Nats.Codec < any > ) {\n ...\n }\n\n /**\n * Try to connect to the NATS server with the different payloads.\n */\n connect(options: Nats.ConnectionOptions, codec?: Nats.Codec): Promise {\n ...\n }\n \n public async jetStreamPublishToChannel(\n message: Payload, \n parameters: Parameters, \n options: Partial = {}\n ): Promise {\n ...\n }\n jetStreamPullSubscribeToChannel\n jetStreamPushSubscriptionFromChannel\n publishToChannel\n subscribeToChannel\n}\n```\n\n### HTTP\n\nFor `http` a single API client class is generated that wraps the standalone [`http_client`](../protocols/http_client.md) channel functions. You construct it once with the shared request configuration (`baseUrl`, `auth`, `hooks`, retry, ...) and every operation becomes a method that reuses that configuration; any field can still be overridden per call.\n\n```js\nexport default {\n inputType: 'openapi',\n inputPath: './my-api.json',\n generators: [\n {\n preset: 'client',\n outputPath: './src/__gen__/client',\n language: 'typescript',\n protocols: ['http']\n }\n ]\n};\n```\n\nThe class name is derived from the input document title (a `\"Safepay Nordic API\"` title yields `SafepayNordicClient`), falling back to `HttpClient`. Override it explicitly with the `clientName` option.\n\nExample generated usage:\n```ts\nimport {SafepayNordicClient} from './__gen__/client/SafepayNordicClient';\n\nconst safepay = new SafepayNordicClient({\n baseUrl: 'https://api.example.com',\n auth: {type: 'bearer', token: process.env.API_TOKEN ?? ''}\n});\n\n// Shared server/auth are reused; the call only supplies what is operation-specific.\nconst response = await safepay.getV2Documents();\nconsole.log(response.status, response.data);\n```\n\nEach method returns the same `HttpClientResponse` as the underlying channel function, so response metadata (status, headers) is preserved.", }, "generators/custom": { title: "Custom generator", @@ -60,7 +60,7 @@ export const docs: Record = { }, "generators/parameters": { title: "Parameters", - content: "# Parameters\n\n```js\nexport default {\n ...,\n generators: [\n {\n preset: 'parameters',\n outputPath: './src/parameters',\n serializationType: 'json',\n language: 'typescript',\n }\n ]\n};\n```\n\n`parameters` preset is for generating models that represent typed models for parameters used in API operations.\n\nThis is supported through the following inputs: [`asyncapi`](#inputs), [`openapi`](#inputs)\n\nIt supports the following languages; `typescript`\n\n## Inputs\n\n### `asyncapi`\nThe `parameters` preset with `asyncapi` input generates all the parameters for each channel in the AsyncAPI document.\n\nThe return type is a map of channels and the model that represent the parameters.\n\n### `openapi`\nThe `parameters` preset with `openapi` input generates all the parameters for each operation in the OpenAPI document, including both path and query parameters.\n\nThe return type is a map of operations and the model that represent the parameters.\n\n## Typescript\n\n### AsyncAPI Functions\n\nEach generated AsyncAPI parameter class includes the following methods:\n\n#### Channel Parameter Substitution\n- `getChannelWithParameters(channel: string): string`: Replaces parameter placeholders in the channel/topic string with actual parameter values.\n\n```typescript\n// Example\nconst params = new UserSignedupParameters({\n myParameter: 'test',\n enumParameter: 'openapi'\n});\nconst channel = params.getChannelWithParameters('user/{my_parameter}/signup/{enum_parameter}');\n// Result: 'user/test/signup/openapi'\n```\n\n#### Static Factory Method\n- `static createFromChannel(msgSubject: string, channel: string, regex: RegExp): ParameterClass`: Creates a parameter instance by extracting values from a message subject using the provided channel template and regex.\n\n```typescript\n// Example\nconst params = UserSignedupParameters.createFromChannel(\n 'user.test.signup.openapi',\n 'user/{my_parameter}/signup/{enum_parameter}',\n /user\\.(.+)\\.signup\\.(.+)/\n);\n```\n\n### OpenAPI Functions\n\nEach generated OpenAPI parameter class includes comprehensive serialization and deserialization capabilities:\n\n#### Path Parameter Serialization\n- `serializePathParameters(): Record`: Serializes path parameters according to OpenAPI 2.0/3.x specification for URL path substitution.\n\n```typescript\n// Example\nconst params = new FindPetsByStatusParameters({\n status: 'available',\n categoryId: 123\n});\nconst pathParams = params.serializePathParameters();\n// Result: { status: 'available', categoryId: '123' }\n```\n\n#### Query Parameter Serialization\n- `serializeQueryParameters(): URLSearchParams`: Serializes query parameters according to OpenAPI specification with proper encoding and style handling.\n\n```typescript\n// Example\nconst queryParams = params.serializeQueryParameters();\nconst queryString = queryParams.toString();\n// Result: 'limit=10&offset=0&tags=dog,cat'\n```\n\n#### Complete URL Serialization\n- `serializeUrl(basePath: string): string`: Generates the complete URL with both path and query parameters properly serialized.\n\n```typescript\n// Example\nconst url = params.serializeUrl('/pet/findByStatus/{status}/{categoryId}');\n// Result: '/pet/findByStatus/available/123?limit=10&offset=0&tags=dog,cat'\n```\n\n#### URL Deserialization\n- `deserializeUrl(url: string): void`: Parses a URL and populates the instance properties from query parameters.\n\n```typescript\n// Example\nconst params = new FindPetsByStatusParameters({ status: 'available', categoryId: 123 });\nparams.deserializeUrl('/pet/findByStatus/available/123?limit=5&tags=dog,cat');\n// params.limit is now 5, params.tags is now ['dog', 'cat']\n```\n\n#### Static Factory Methods\n- `static fromUrl(url: string, basePath: string, ...requiredDefaults): ParameterClass`: Creates a new parameter instance from a complete URL by extracting both path and query parameters.\n\n```typescript\n// Example\nconst params = FindPetsByStatusParameters.fromUrl(\n '/pet/findByStatus/available/123?limit=5&tags=dog',\n '/pet/findByStatus/{status}/{categoryId}'\n);\n// params.status is 'available', params.categoryId is 123, params.limit is 5\n```\n\n### Parameter Style Support\n\nThe OpenAPI generator supports all OpenAPI parameter styles and serialization formats:\n\n#### Path Parameters\n- **simple** (default): `value1,value2` or `key1,value1,key2,value2`\n- **label**: `.value1.value2` or `.key1.value1.key2.value2`\n- **matrix**: `;param=value1,value2` or `;key1=value1;key2=value2`\n\n#### Query Parameters\n- **form** (default): `param=value1¶m=value2` (exploded) or `param=value1,value2`\n- **spaceDelimited**: `param=value1 value2`\n- **pipeDelimited**: `param=value1|value2`\n- **deepObject**: `param[key1]=value1¶m[key2]=value2`\n\n### Type Safety\n\nAll parameter classes are fully typed with:\n- Enum parameter types for restricted values\n- Required vs optional parameter distinction\n- Proper TypeScript casting for different parameter types (string, number, boolean, arrays)\n- Support for complex parameter schemas including nested objects and arrays\n\n### OpenAPI 2.0 Compatibility\n\nThe generator supports OpenAPI 2.0 `collectionFormat` parameter serialization:\n- `csv`: Comma-separated values\n- `ssv`: Space-separated values \n- `tsv`: Tab-separated values (treated as CSV)\n- `pipes`: Pipe-separated values\n- `multi`: Multiple parameter instances\n\nThese are automatically converted to equivalent OpenAPI 3.0 style/explode combinations for consistent handling.", + content: "# Parameters\n\n```js\nexport default {\n ...,\n generators: [\n {\n preset: 'parameters',\n outputPath: './src/parameters',\n serializationType: 'json',\n language: 'typescript',\n }\n ]\n};\n```\n\n`parameters` preset is for generating models that represent typed models for parameters used in API operations.\n\nThis is supported through the following inputs: [`asyncapi`](#inputs), [`openapi`](#inputs)\n\nIt supports the following languages; `typescript`\n\n## Companion Interface\n\nEvery generated parameter model file exports **two** symbols: the parameter\nclass (`Parameters`) and a plain-data companion interface\n(`ParametersInterface`) declared above it. The class constructor takes the\ninterface (`constructor(input: ParametersInterface)`), so the two always\nstay in sync.\n\n```typescript\nexport { FindPetsByStatusParameters, FindPetsByStatusParametersInterface };\n```\n\nThis lets you pass a **plain object** wherever a channel expects parameters —\nyou do not have to construct the class yourself:\n\n```typescript\n// Both of these are accepted by every generated channel helper:\nawait publishToUserSignedup({ message, parameters: { myParameter: 'test', enumParameter: 'openapi' }, nc });\nawait publishToUserSignedup({ message, parameters: new UserSignedupParameters({ myParameter: 'test', enumParameter: 'openapi' }), nc });\n```\n\nChannel consumers type their parameter argument as the union\n`ParametersInterface | Parameters` and normalize it to a class\ninstance internally (via an `instanceof` guard) before using the rich class\nbehavior (`getChannelWithParameters`, serialization, etc.). The plain-object\nform is purely an ergonomic convenience; the generated code always operates on a\nclass instance. See the [protocols documentation](../protocols) for how each\nchannel accepts parameters.\n\n## Inputs\n\n### `asyncapi`\nThe `parameters` preset with `asyncapi` input generates all the parameters for each channel in the AsyncAPI document.\n\nThe return type is a map of channels and the model that represent the parameters.\n\n### `openapi`\nThe `parameters` preset with `openapi` input generates all the parameters for each operation in the OpenAPI document, including both path and query parameters.\n\nThe return type is a map of operations and the model that represent the parameters.\n\n## Typescript\n\n### AsyncAPI Functions\n\nEach generated AsyncAPI parameter class includes the following methods:\n\n#### Channel Parameter Substitution\n- `getChannelWithParameters(channel: string): string`: Replaces parameter placeholders in the channel/topic string with actual parameter values.\n\n```typescript\n// Example\nconst params = new UserSignedupParameters({\n myParameter: 'test',\n enumParameter: 'openapi'\n});\nconst channel = params.getChannelWithParameters('user/{my_parameter}/signup/{enum_parameter}');\n// Result: 'user/test/signup/openapi'\n```\n\n#### Static Factory Method\n- `static createFromChannel(msgSubject: string, channel: string, regex: RegExp): ParameterClass`: Creates a parameter instance by extracting values from a message subject using the provided channel template and regex.\n\n```typescript\n// Example\nconst params = UserSignedupParameters.createFromChannel(\n 'user.test.signup.openapi',\n 'user/{my_parameter}/signup/{enum_parameter}',\n /user\\.(.+)\\.signup\\.(.+)/\n);\n```\n\n### OpenAPI Functions\n\nEach generated OpenAPI parameter class includes comprehensive serialization and deserialization capabilities:\n\n#### Path Parameter Serialization\n- `serializePathParameters(): Record`: Serializes path parameters according to OpenAPI 2.0/3.x specification for URL path substitution.\n\n```typescript\n// Example\nconst params = new FindPetsByStatusParameters({\n status: 'available',\n categoryId: 123\n});\nconst pathParams = params.serializePathParameters();\n// Result: { status: 'available', categoryId: '123' }\n```\n\n#### Query Parameter Serialization\n- `serializeQueryParameters(): URLSearchParams`: Serializes query parameters according to OpenAPI specification with proper encoding and style handling.\n\n```typescript\n// Example\nconst queryParams = params.serializeQueryParameters();\nconst queryString = queryParams.toString();\n// Result: 'limit=10&offset=0&tags=dog,cat'\n```\n\n#### Complete URL Serialization\n- `serializeUrl(basePath: string): string`: Generates the complete URL with both path and query parameters properly serialized.\n\n```typescript\n// Example\nconst url = params.serializeUrl('/pet/findByStatus/{status}/{categoryId}');\n// Result: '/pet/findByStatus/available/123?limit=10&offset=0&tags=dog,cat'\n```\n\n#### URL Deserialization\n- `deserializeUrl(url: string): void`: Parses a URL and populates the instance properties from query parameters.\n\n```typescript\n// Example\nconst params = new FindPetsByStatusParameters({ status: 'available', categoryId: 123 });\nparams.deserializeUrl('/pet/findByStatus/available/123?limit=5&tags=dog,cat');\n// params.limit is now 5, params.tags is now ['dog', 'cat']\n```\n\n#### Static Factory Methods\n- `static fromUrl(url: string, basePath: string, ...requiredDefaults): ParameterClass`: Creates a new parameter instance from a complete URL by extracting both path and query parameters.\n\n```typescript\n// Example\nconst params = FindPetsByStatusParameters.fromUrl(\n '/pet/findByStatus/available/123?limit=5&tags=dog',\n '/pet/findByStatus/{status}/{categoryId}'\n);\n// params.status is 'available', params.categoryId is 123, params.limit is 5\n```\n\n### Parameter Style Support\n\nThe OpenAPI generator supports all OpenAPI parameter styles and serialization formats:\n\n#### Path Parameters\n- **simple** (default): `value1,value2` or `key1,value1,key2,value2`\n- **label**: `.value1.value2` or `.key1.value1.key2.value2`\n- **matrix**: `;param=value1,value2` or `;key1=value1;key2=value2`\n\n#### Query Parameters\n- **form** (default): `param=value1¶m=value2` (exploded) or `param=value1,value2`\n- **spaceDelimited**: `param=value1 value2`\n- **pipeDelimited**: `param=value1|value2`\n- **deepObject**: `param[key1]=value1¶m[key2]=value2`\n\n### Type Safety\n\nAll parameter classes are fully typed with:\n- Enum parameter types for restricted values\n- Required vs optional parameter distinction\n- Proper TypeScript casting for different parameter types (string, number, boolean, arrays)\n- Support for complex parameter schemas including nested objects and arrays\n\n### OpenAPI 2.0 Compatibility\n\nThe generator supports OpenAPI 2.0 `collectionFormat` parameter serialization:\n- `csv`: Comma-separated values\n- `ssv`: Space-separated values \n- `tsv`: Tab-separated values (treated as CSV)\n- `pipes`: Pipe-separated values\n- `multi`: Multiple parameter instances\n\nThese are automatically converted to equivalent OpenAPI 3.0 style/explode combinations for consistent handling.", }, "generators/payloads": { title: "🐔 Payloads", @@ -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, pagination, 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| Offset based Pagination | ✅ |\n| Cursor based Pagination | ✅ |\n| Page based Pagination | ✅ |\n| Range based Pagination | ✅ |\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 server: '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 server: '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 server: '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 server: '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 server: '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 server: '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 server: '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 server: '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 server: '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 server: '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## Pagination\n\nThe HTTP client supports multiple pagination strategies. Pagination parameters can be placed in query parameters or headers.\n\n### Offset-based Pagination\n\n```typescript\nconst response = await getItemsRequest({\n server: 'https://api.example.com',\n pagination: {\n type: 'offset',\n offset: 0,\n limit: 25,\n in: 'query', // 'query' or 'header'\n offsetParam: 'offset', // Query param name (default: 'offset')\n limitParam: 'limit' // Query param name (default: 'limit')\n }\n});\n\n// Navigate pages\nif (response.hasNextPage?.()) {\n const nextPage = await response.getNextPage?.();\n}\n```\n\n### Cursor-based Pagination\n\n```typescript\nconst response = await getItemsRequest({\n server: 'https://api.example.com',\n pagination: {\n type: 'cursor',\n cursor: undefined, // First page\n limit: 25,\n cursorParam: 'cursor'\n }\n});\n\n// Get next page using cursor from response\nif (response.pagination?.nextCursor) {\n const nextPage = await response.getNextPage?.();\n}\n```\n\n### Page-based Pagination\n\n```typescript\nconst response = await getItemsRequest({\n server: 'https://api.example.com',\n pagination: {\n type: 'page',\n page: 1,\n pageSize: 25,\n pageParam: 'page',\n pageSizeParam: 'per_page'\n }\n});\n```\n\n### Range-based Pagination (RFC 7233)\n\n```typescript\nconst response = await getItemsRequest({\n server: 'https://api.example.com',\n pagination: {\n type: 'range',\n start: 0,\n end: 24,\n unit: 'items', // Range unit (default: 'items')\n rangeHeader: 'Range' // Header name (default: 'Range')\n }\n});\n// Sends: Range: items=0-24\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 server: '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 server: '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 server: '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 server: '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 server: 'https://api.example.com',\n additionalHeaders: {\n 'X-Custom-Header': 'value',\n 'Accept-Language': 'en-US'\n },\n queryParams: {\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 server: '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## 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.74.3 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.74.3/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.74.3/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=