···11+---
22+'@hey-api/openapi-ts': minor
33+---
44+55+feat: rename Hey API plugins
66+77+### Renamed `@hey-api/services` plugin
88+99+This plugin has been renamed to `@hey-api/sdk`.
1010+1111+### Changed `sdk.output` value
1212+1313+To align with the updated name, the `@hey-api/sdk` plugin will generate an `sdk.gen.ts` file. This will result in a breaking change if you're importing from `services.gen.ts`. Please update your imports to reflect this change.
1414+1515+```js
1616+import { client } from 'client/services.gen'; // [!code --]
1717+import { client } from 'client/sdk.gen'; // [!code ++]
1818+```
1919+2020+### Renamed `@hey-api/types` plugin
2121+2222+This plugin has been renamed to `@hey-api/typescript`.
+2-2
README.md
···44 <p align="center">🚀 The OpenAPI to TypeScript codegen. Generate clients, SDKs, validators, and more.</p>
55</div>
6677-[Live demo](https://stackblitz.com/edit/hey-api-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fservices.gen.ts,src%2Fclient%2Ftypes.gen.ts)
77+[Live demo](https://stackblitz.com/edit/hey-api-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fsdk.gen.ts,src%2Fclient%2Ftypes.gen.ts)
8899## Features
10101111- works with CLI, Node.js 18+, or npx
1212- supports OpenAPI 2.0, 3.0, and 3.1 specifications
1313- supports both JSON and YAML input files
1414-- generates TypeScript interfaces, REST clients, and JSON Schemas
1414+- generates TypeScript interfaces, SDKs, and JSON Schemas
1515- Fetch API, Axios, Angular, Node.js, and XHR clients available
1616- plugin ecosystem to reduce third-party boilerplate
1717
···57575858## Configuration
59596060-If you're using services, you will want to configure the internal client instance. You can do that with the `setConfig()` method. Call it at the beginning of your application.
6060+If you're using SDKs, you will want to configure the internal client instance. You can do that with the `setConfig()` method. Call it at the beginning of your application.
61616262```js
6363-import { client } from 'client/services.gen';
6363+import { client } from 'client/sdk.gen';
64646565client.setConfig({
6666 baseURL: 'https://example.com',
6767});
6868```
69697070-If you aren't using services, you can create your own client instance.
7070+If you aren't using SDKs, you can create your own client instance.
71717272```js
7373import { createClient } from '@hey-api/client-axios';
···8484We expose the Axios instance through the `instance` field.
85858686```js
8787-import { client } from 'client/services.gen';
8787+import { client } from 'client/sdk.gen';
88888989client.instance.interceptors.request.use((config) => {
9090 config.headers.set('Authorization', 'Bearer <my_token>');
···94949595## Customization
96969797-Our Axios client is built as a thin wrapper on top of Axios, extending its functionality to work with Hey API. If you're already familiar with Axios, customizing your client will feel like working directly with Axios. You can customize requests in three ways – through services, per client, or per request.
9797+Our Axios client is built as a thin wrapper on top of Axios, extending its functionality to work with Hey API. If you're already familiar with Axios, customizing your client will feel like working directly with Axios. You can customize requests in three ways – through SDKs, per client, or per request.
98989999-### Services
9999+### SDKs
100100101101-This is the most common requirement. Our generated services consume an internal Axios instance, so you will want to configure that.
101101+This is the most common requirement. Our generated SDKs consume an internal Axios instance, so you will want to configure that.
102102103103```js
104104-import { client } from 'client/services.gen';
104104+import { client } from 'client/sdk.gen';
105105106106client.setConfig({
107107 baseURL: 'https://example.com',
···122122});
123123```
124124125125-You can then pass this instance to any generated service through the `client` option. This will override the internal instance.
125125+You can then pass this instance to any SDK function through the `client` option. This will override the internal instance.
126126127127```js
128128const response = await getFoo({
···132132133133### Request
134134135135-Alternatively, you can pass the Axios configuration options to each service call directly. This is useful if you don't want to create a separate client for one-off use cases.
135135+Alternatively, you can pass the Axios configuration options to each SDK function. This is useful if you don't want to create a client instance for one-off use cases.
136136137137```js
138138const response = await getFoo({
+13-13
docs/openapi-ts/clients/fetch.md
···57575858## Configuration
59596060-If you're using services, you will want to configure the internal client instance. You can do that with the `setConfig()` method. Call it at the beginning of your application.
6060+If you're using SDKs, you will want to configure the internal client instance. You can do that with the `setConfig()` method. Call it at the beginning of your application.
61616262```js
6363-import { client } from 'client/services.gen';
6363+import { client } from 'client/sdk.gen';
64646565client.setConfig({
6666 baseUrl: 'https://example.com',
6767});
6868```
69697070-If you aren't using services, you can create your own client instance.
7070+If you aren't using SDKs, you can create your own client instance.
71717272```js
7373import { createClient } from '@hey-api/client-fetch';
···8484::: code-group
85858686```js [use]
8787-import { client } from 'client/services.gen';
8787+import { client } from 'client/sdk.gen';
88888989client.interceptors.request.use((request, options) => {
9090 request.headers.set('Authorization', 'Bearer <my_token>');
···9393```
94949595```js [eject]
9696-import { client } from 'client/services.gen';
9696+import { client } from 'client/sdk.gen';
97979898client.interceptors.request.eject((request, options) => {
9999 request.headers.set('Authorization', 'Bearer <my_token>');
···108108::: code-group
109109110110```js [use]
111111-import { client } from 'client/services.gen';
111111+import { client } from 'client/sdk.gen';
112112113113client.interceptors.response.use((response, request, options) => {
114114 trackAnalytics(response);
···117117```
118118119119```js [eject]
120120-import { client } from 'client/services.gen';
120120+import { client } from 'client/sdk.gen';
121121122122client.interceptors.response.eject((response, request, options) => {
123123 trackAnalytics(response);
···133133134134## Customization
135135136136-Our Fetch client is built as a thin wrapper on top of Fetch API, extending its functionality to work with Hey API. If you're already familiar with Fetch, customizing your client will feel like working directly with Fetch API. You can customize requests in three ways – through services, per client, or per request.
136136+Our Fetch client is built as a thin wrapper on top of Fetch API, extending its functionality to work with Hey API. If you're already familiar with Fetch, customizing your client will feel like working directly with Fetch API. You can customize requests in three ways – through SDKs, per client, or per request.
137137138138-### Services
138138+### SDKs
139139140140-This is the most common requirement. Our generated services consume an internal Fetch instance, so you will want to configure that.
140140+This is the most common requirement. The generated SDKs consume an internal Fetch instance, so you will want to configure that.
141141142142```js
143143-import { client } from 'client/services.gen';
143143+import { client } from 'client/sdk.gen';
144144145145client.setConfig({
146146 baseUrl: 'https://example.com',
···161161});
162162```
163163164164-You can then pass this instance to any generated service through the `client` option. This will override the internal instance.
164164+You can then pass this instance to any SDK function through the `client` option. This will override the internal instance.
165165166166```js
167167const response = await getFoo({
···171171172172### Request
173173174174-Alternatively, you can pass the Fetch API configuration options to each service call directly. This is useful if you don't want to create a separate client for one-off use cases.
174174+Alternatively, you can pass the Fetch API configuration options to each SDK function. This is useful if you don't want to create a client instance for one-off use cases.
175175176176```js
177177const response = await getFoo({
+2-2
docs/openapi-ts/configuration.md
···194194195195## Clients
196196197197-Clients are responsible for sending the actual HTTP requests. The `client` value is not required, but you must define it if you're generating the service layer (enabled by default).
197197+Clients are responsible for sending the actual HTTP requests. The `client` value is not required, but you must define it if you're generating SDKs (enabled by default).
198198199199You can learn more on the [Clients](/openapi-ts/clients) page.
200200···225225226226## Plugins
227227228228-Plugins are responsible for generating artifacts from your input. By default, Hey API will generate TypeScript interfaces, JSON Schemas, and services from your OpenAPI specification. You can add, remove, or customize any of the plugins. In fact, we highly encourage you to do so!
228228+Plugins are responsible for generating artifacts from your input. By default, Hey API will generate TypeScript interfaces, an SDK, and JSON Schemas from your OpenAPI specification. You can add, remove, or customize any of the plugins. In fact, we highly encourage you to do so!
229229230230You can learn more on the [Output](/openapi-ts/output) page.
231231
+1-1
docs/openapi-ts/fastify.md
···50505151## Route Handlers
52525353-Route handlers are generated from all endpoints. The generated interface follows the naming convention of services.
5353+Route handlers are generated from all endpoints. The generated interface follows the naming convention of SDK functions.
54545555```ts
5656const fastify = Fastify();
+1-1
docs/openapi-ts/get-started.md
···2424- works with CLI, Node.js 18+, or npx
2525- supports OpenAPI 2.0, 3.0, and 3.1 specifications
2626- supports both JSON and YAML input files
2727-- generates TypeScript interfaces, REST clients, and JSON Schemas
2727+- generates TypeScript interfaces, SDKs, and JSON Schemas
2828- Fetch API, Axios, Angular, Node.js, and XHR clients available
2929- plugin ecosystem to reduce third-party boilerplate
3030
+1-1
docs/openapi-ts/integrations.md
···13131414## Upload OpenAPI Spec
15151616-First, you need to configure your API services to send us OpenAPI specifications. This can be done by adding our [hey-api/upload-openapi-spec](https://github.com/marketplace/actions/upload-openapi-spec-by-hey-api) GitHub Action into your CI workflow.
1616+First, you need to configure your API build workflow to send us OpenAPI specifications. This can be done by adding our [hey-api/upload-openapi-spec](https://github.com/marketplace/actions/upload-openapi-spec-by-hey-api) GitHub Action into your CI workflow.
17171818```yaml
1919name: Upload OpenAPI Specification
+19-23
docs/openapi-ts/migrating.md
···11111212These changes haven't been released yet. However, you can migrate your code today to save time on migration once they're released.
13131414-### Deprecated exports from `index.ts`
1515-1616-Currently, `index.ts` file exports all generated artifacts. We will be slowly moving away from this practice as it increases the chance of export conflicts.
1717-1818-```js
1919-export { ApiError } from './core/ApiError';
2020-export { CancelablePromise, CancelError } from './core/CancelablePromise';
2121-export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
2222-export * from './schemas.gen'; // [!code --]
2323-export * from './services.gen'; // [!code --]
2424-export * from './types.gen'; // [!code --]
2525-```
2626-2727-Any non-core related imports should be imported as
2828-2929-```js
3030-import { $Schema } from 'client/schemas.gen';
3131-import { DefaultService } from 'client/services.gen';
3232-import type { Model } from 'client/types.gen';
3333-```
3434-3535-You don't have to update imports from `core` folder. These will be addressed in later releases.
3636-3714### Deprecated `base`
38153916This config option is deprecated and will be removed in favor of [clients](./clients).
···4926### Deprecated `useOptions`
50275128This config option is deprecated and will be removed.
2929+3030+## v0.57.0
3131+3232+### Renamed `@hey-api/services` plugin
3333+3434+This plugin has been renamed to `@hey-api/sdk`.
3535+3636+### Changed `sdk.output` value
3737+3838+To align with the updated name, the `@hey-api/sdk` plugin will generate an `sdk.gen.ts` file. This will result in a breaking change if you're importing from `services.gen.ts`. Please update your imports to reflect this change.
3939+4040+```js
4141+import { client } from 'client/services.gen'; // [!code --]
4242+import { client } from 'client/sdk.gen'; // [!code ++]
4343+```
4444+4545+### Renamed `@hey-api/types` plugin
4646+4747+This plugin has been renamed to `@hey-api/typescript`.
52485349## v0.56.0
5450
+41-42
docs/openapi-ts/output.md
···13131414## Overview
15151616-If you use the default configuration, your [project](https://stackblitz.com/edit/hey-api-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fservices.gen.ts,src%2Fclient%2Ftypes.gen.ts) might look like this.
1616+If you use the default configuration, your [project](https://stackblitz.com/edit/hey-api-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fsdk.gen.ts,src%2Fclient%2Ftypes.gen.ts) might look like this.
17171818```md
1919my-app/
···2222│ ├── client/
2323│ │ ├── index.ts
2424│ │ ├── schemas.gen.ts
2525-│ │ ├── services.gen.ts
2525+│ │ ├── sdk.gen.ts
2626│ │ └── types.gen.ts
2727│ └── index.ts
2828└── package.json
···32323333Let's go through each file in the `src/client` folder and explain what it looks like, what it does, and how to use it.
34343535-## TypeScript Interfaces
3535+## TypeScript
36363737TypeScript interfaces are located in the `types.gen.ts` file. This is the only file that does not impact your bundle size and runtime performance. It will get discarded during build time, unless you configured to emit runtime [enums](/openapi-ts/output#enums).
38383939-This file contains three different categories of interfaces created from your OpenAPI specification:
3939+This file contains three different categories of interfaces created from your input:
40404141- reusable components
4242- operation request, response, and error data
···65656666### Configuration
67676868-You can modify the contents of `types.gen.ts` by configuring the `@hey-api/types` plugin. Note that you must specify the other default plugins to preserve the default output.
6868+You can modify the contents of `types.gen.ts` by configuring the `@hey-api/typescript` plugin. Note that you must specify the other default plugins to preserve the default output.
69697070```js
7171export default {
···7373 input: 'path/to/openapi.json',
7474 output: 'src/client',
7575 plugins: [
7676- '@hey-api/schemas', // preserves default output
7777- '@hey-api/services', // preserves default output
7676+ '@hey-api/schemas', // preserve default output
7777+ '@hey-api/sdk', // preserve default output
7878 {
7979- name: '@hey-api/types',
7979+ name: '@hey-api/typescript',
8080 // ...custom options // [!code ++]
8181 },
8282 ],
···9898 // ...default plugins
9999 {
100100 enums: false, // default // [!code ++]
101101- name: '@hey-api/types',
101101+ name: '@hey-api/typescript',
102102 },
103103 ],
104104};
···113113 // ...default plugins
114114 {
115115 enums: 'javascript', // [!code ++]
116116- name: '@hey-api/types',
116116+ name: '@hey-api/typescript',
117117 },
118118 ],
119119};
···128128 // ...default plugins
129129 {
130130 enums: 'typescript', // [!code ++]
131131- name: '@hey-api/types',
131131+ name: '@hey-api/typescript',
132132 },
133133 ],
134134};
···138138139139We recommend exporting enums as plain JavaScript objects. [TypeScript enums](https://www.typescriptlang.org/docs/handbook/enums.html) are not a type-level extension of JavaScript and pose [typing challenges](https://dev.to/ivanzm123/dont-use-enums-in-typescript-they-are-very-dangerous-57bh).
140140141141-## API Services
141141+## SDKs
142142143143-Services are located in the `services.gen.ts` file. Services are abstractions on top of clients and serve the same purpose. By default, `@hey-api/openapi-ts` will generate a flat service layer. Your choice to use services comes down to personal preferences and bundle size considerations.
143143+SDKs are located in the `sdk.gen.ts` file. SDKs are abstractions on top of clients and serve the same purpose. By default, `@hey-api/openapi-ts` will generate a flat SDK layer. Your choice to use SDKs depends on personal preferences and bundle size considerations.
144144145145-### Flat Services
145145+### Flat SDKs
146146147147-This is the default setting. Flat services support tree-shaking and can lead to reduced bundle size over duplicated client calls. The function names are generated from operation IDs or operation location.
147147+This is the default setting. Flat SDKs support tree-shaking and can lead to reduced bundle size over duplicated client calls. The function names are generated from operation IDs or operation location.
148148149149-### Class Services
149149+### Class SDKs
150150151151-Class services do not support tree-shaking which will lead to increased bundle sizes, but some people prefer this option for syntax reasons. The class names are generated from operation tags and method names are generated from operation IDs or operation location.
151151+Class SDKs do not support tree-shaking which will lead to increased bundle sizes, but some people prefer this option for syntax reasons. The class names are generated from operation tags and method names are generated from operation IDs or operation location.
152152153153-### No Services
153153+### No SDKs
154154155155-If you prefer to use clients directly or do not need the service layer, define `plugins` manually and omit the `@hey-api/services` plugin. Type support for clients is currently limited due to popularity of other options. If you'd like to use this option and need better types, [open an issue](https://github.com/hey-api/openapi-ts/issues).
155155+If you prefer to use clients directly or do not need the SDK layer, define `plugins` manually and omit the `@hey-api/sdk` plugin. Type support for clients is currently limited due to popularity of other options. If you'd like to use this option and need better types, [open an issue](https://github.com/hey-api/openapi-ts/issues).
156156157157### Configuration
158158159159-You can modify the contents of `services.gen.ts` by configuring the `@hey-api/services` plugin. Note that you must specify the other default plugins to preserve the default output.
159159+You can modify the contents of `sdk.gen.ts` by configuring the `@hey-api/sdk` plugin. Note that you must specify the other default plugins to preserve the default output.
160160161161::: code-group
162162···166166 input: 'path/to/openapi.json',
167167 output: 'src/client',
168168 plugins: [
169169- '@hey-api/schemas', // preserves default output
170170- '@hey-api/types', // preserves default output
169169+ '@hey-api/schemas', // preserve default output
170170+ '@hey-api/typescript', // preserve default output
171171 {
172172 asClass: false, // default // [!code ++]
173173- name: '@hey-api/services',
173173+ name: '@hey-api/sdk',
174174 },
175175 ],
176176};
···182182 input: 'path/to/openapi.json',
183183 output: 'src/client',
184184 plugins: [
185185- '@hey-api/schemas', // preserves default output
186186- '@hey-api/types', // preserves default output
185185+ '@hey-api/schemas', // preserve default output
186186+ '@hey-api/typescript', // preserve default output
187187 {
188188 asClass: true, // [!code ++]
189189- name: '@hey-api/services',
189189+ name: '@hey-api/sdk',
190190 },
191191 ],
192192};
···198198 input: 'path/to/openapi.json',
199199 output: 'src/client',
200200 plugins: [
201201- '@hey-api/schemas', // preserves default output
202202- '@hey-api/types', // preserves default output
203203- '@hey-api/services', // [!code --]
201201+ '@hey-api/schemas', // preserve default output
202202+ '@hey-api/typescript', // preserve default output
203203+ '@hey-api/sdk', // [!code --]
204204 ],
205205};
206206```
···209209210210### Output
211211212212-Below are different outputs depending on your chosen style. No services approach will not generate the `services.gen.ts` file.
212212+Below are different outputs depending on your chosen style. No SDKs approach will not generate the `sdk.gen.ts` file.
213213214214::: code-group
215215···249249::: code-group
250250251251```ts [flat]
252252-import { addPet } from './client/services.gen';
252252+import { addPet } from './client/sdk.gen';
253253254254addPet({
255255 body: {
···259259```
260260261261```ts [class]
262262-import { PetService } from './client/services.gen';
262262+import { PetService } from './client/sdk.gen';
263263264264PetService.addPet({
265265 body: {
···297297 input: 'path/to/openapi.json',
298298 output: 'src/client',
299299 plugins: [
300300- '@hey-api/services', // preserves default output
301301- '@hey-api/types', // preserves default output
300300+ '@hey-api/sdk', // preserve default output
301301+ '@hey-api/typescript', // preserve default output
302302 {
303303 name: '@hey-api/schemas',
304304 type: 'json', // [!code ++]
···313313 input: 'path/to/openapi.json',
314314 output: 'src/client',
315315 plugins: [
316316- '@hey-api/services', // preserves default output
317317- '@hey-api/types', // preserves default output
316316+ '@hey-api/sdk', // preserve default output
317317+ '@hey-api/typescript', // preserve default output
318318 {
319319 name: '@hey-api/schemas',
320320 type: 'form', // [!code ++]
···329329 input: 'path/to/openapi.json',
330330 output: 'src/client',
331331 plugins: [
332332- '@hey-api/services', // preserves default output
333333- '@hey-api/types', // preserves default output
332332+ '@hey-api/sdk', // preserve default output
333333+ '@hey-api/typescript', // preserve default output
334334 '@hey-api/schemas', // [!code --]
335335 ],
336336};
···376376377377## Index
378378379379-For convenience, every default generated artifact is re-exported from `index.ts`. This file is deprecated and will be removed in future releases. We recommend importing types, services, and schemas from their respective files to avoid ambiguity.
379379+For convenience, every artifact generated by Hey API plugins is re-exported from `index.ts`. However, we recommend importing artifacts from their files to avoid ambiguity.
380380381381```ts
382382-import type { Pet } from './client/types.gen';
383383-// or
384384-import type { Pet } from './client';
382382+import type { Pet } from './client'; // [!code --] // 👎
383383+import type { Pet } from './client/types.gen'; // [!code ++] // 👍
385384```
386385387386## Client
+5-5
docs/openapi-ts/plugins.md
···1212Apart from being responsible for the default output, Hey API plugins are the foundation for other plugins. Instead of creating their own primitives, other plugins can reuse the artifacts from Hey API plugins. This results in smaller output and a better user experience.
13131414- `@hey-api/schemas` - export OpenAPI definitions as JavaScript objects
1515-- `@hey-api/services` - robust and polished SDKs
1515+- `@hey-api/sdk` - robust and polished SDKs
1616- `@hey-api/transformers` - response data transformer functions
1717-- `@hey-api/types` - TypeScript interfaces and enums
1717+- `@hey-api/typescript` - TypeScript interfaces and enums
18181919## Third Party
20202121These plugins help reduce boilerplate associated with third-party dependencies. Hey API natively supports the most popular packages. Please open an issue on [GitHub](https://github.com/hey-api/openapi-ts/issues) if you'd like us to support your favorite package.
22222323-- [`fastify`](/openapi-ts/fastify) - TypeScript interface for Fastify route handlers
2423- [`@tanstack/angular-query-experimental`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys
2524- [`@tanstack/react-query`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys
2625- [`@tanstack/solid-query`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys
2726- [`@tanstack/svelte-query`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys
2827- [`@tanstack/vue-query`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys
2828+- [`fastify`](/openapi-ts/fastify) - TypeScript interface for Fastify route handlers
2929- [`zod`](/openapi-ts/zod) - Zod schemas to validate your data
30303131## Community
···9090import type { Config } from './types';
91919292export const defaultConfig: PluginConfig<Config> = {
9393- _dependencies: ['@hey-api/types'],
9393+ _dependencies: ['@hey-api/typescript'],
9494 _handler: handler,
9595 _handlerLegacy: () => {},
9696 name: 'my-plugin',
···108108109109:::
110110111111-In the `config.ts` above, we define a `my-plugin` plugin which will generate a `my-plugin.gen.ts` output file. We also demonstrate declaring `@hey-api/types` as a dependency for our plugin, so we can safely import artifacts from `types.gen.ts`.
111111+In the `config.ts` above, we define a `my-plugin` plugin which will generate a `my-plugin.gen.ts` output file. We also demonstrate declaring `@hey-api/typescript` as a dependency for our plugin, so we can safely import artifacts from `types.gen.ts`.
112112113113Lastly, we define the `_handler` method which will be responsible for generating our custom output. We just need to create the remaining `plugin.ts` file.
114114
+3-3
docs/openapi-ts/tanstack-query.md
···102102103103## Queries
104104105105-Queries are generated from GET and POST endpoints. The generated functions follow the naming convention of services and append `Options`, e.g. `getPetByIdOptions()`.
105105+Queries are generated from GET and POST endpoints. The generated functions follow the naming convention of SDK functions and append `Options`, e.g. `getPetByIdOptions()`.
106106107107```ts
108108const { data, error } = useQuery({
···116116117117## Infinite Queries
118118119119-Infinite queries are generated from GET and POST endpoints if we detect a pagination parameter. The generated functions follow the naming convention of services and append `InfiniteOptions`, e.g. `getFooInfiniteOptions()`.
119119+Infinite queries are generated from GET and POST endpoints if we detect a pagination parameter. The generated functions follow the naming convention of SDK functions and append `InfiniteOptions`, e.g. `getFooInfiniteOptions()`.
120120121121```ts
122122const { data, error } = useInfiniteQuery({
···132132133133## Mutations
134134135135-Mutations are generated from DELETE, PATCH, POST, and PUT endpoints. The generated functions follow the naming convention of services and append `Mutation`, e.g. `addPetMutation()`.
135135+Mutations are generated from DELETE, PATCH, POST, and PUT endpoints. The generated functions follow the naming convention of SDK functions and append `Mutation`, e.g. `addPetMutation()`.
136136137137```ts
138138const addPet = useMutation({
+2-2
docs/openapi-ts/transformers.md
···15151616## Considerations
17171818-Before deciding whether transformers are right for you, let's explain how they work. Transformers are generated on the [service layer](/openapi-ts/output#api-services), therefore they impact the bundle size. We generate a single transformer per operation response for the most efficient result, just like a human engineer would.
1818+Before deciding whether transformers are right for you, let's explain how they work. Transformers generate a runtime file, therefore they impact the bundle size. We generate a single transformer per operation response for the most efficient result, just like a human engineer would.
19192020### Limitations
21212222-Transformers currently handle the most common scenarios. Some of the known limitations are:
2222+Transformers handle only the most common scenarios. Some of the known limitations are:
23232424- union types are not transformed (e.g. if you have multiple possible response shapes)
2525- only types defined through `$ref` are transformed
···1818import { useState } from 'react';
19192020import { PetSchema } from './client/schemas.gen';
2121-import { addPet, getPetById, updatePet } from './client/services.gen';
2121+import { addPet, getPetById, updatePet } from './client/sdk.gen';
2222import type { Pet } from './client/types.gen';
23232424const localClient = createClient({
+1-1
examples/openapi-ts-axios/src/client/index.ts
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './schemas.gen';
33-export * from './services.gen';
33+export * from './sdk.gen';
44export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···1818import { useState } from 'react';
19192020import { PetSchema } from './client/schemas.gen';
2121-import { addPet, getPetById, updatePet } from './client/services.gen';
2121+import { addPet, getPetById, updatePet } from './client/sdk.gen';
2222import type { Pet } from './client/types.gen';
23232424const localClient = createClient({
+1-1
examples/openapi-ts-fetch/src/client/index.ts
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './schemas.gen';
33-export * from './services.gen';
33+export * from './sdk.gen';
44export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './schemas.gen';
33-export * from './services.gen';
33+export * from './sdk.gen';
44export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './schemas.gen';
33-export * from './services.gen';
33+export * from './sdk.gen';
44export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './schemas.gen';
33-export * from './services.gen';
33+export * from './sdk.gen';
44export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './schemas.gen'
33-export * from './services.gen'
33+export * from './sdk.gen'
44export * from './types.gen'
···8899/**
1010 * Construct a relative import path to modules. This is used for example
1111- * in plugins to import types or services module.
1111+ * in plugins to import types or SDK module.
1212 */
1313export const relativeModulePath = ({
1414 moduleOutput,
···4455/**
66 * Returns an operation ID to use across the application. By default, we try
77- * to use the provided ID. If it's not provided or the services are configured
77+ * to use the provided ID. If it's not provided or the SDK is configured
88 * to exclude it, we generate operation ID from its location.
99 */
1010export const operationToId = ({
···2020}): string => {
2121 if (
2222 id &&
2323- (!context.config.plugins['@hey-api/services'] ||
2424- context.config.plugins['@hey-api/services'].operationId)
2323+ (!context.config.plugins['@hey-api/sdk'] ||
2424+ context.config.plugins['@hey-api/sdk'].operationId)
2525 ) {
2626 return camelCase({
2727 input: sanitizeNamespaceIdentifier(id),
···22import type { Operation } from '../../../types/client';
33import type { PluginName } from '../../types';
4455-export interface Config extends PluginName<'@hey-api/services'> {
55+export interface Config extends PluginName<'@hey-api/sdk'> {
66 /**
77- * Group operation methods into service classes? When enabled, you can
88- * select which classes to export with `services.include` and/or
99- * transform their names with `services.name`.
77+ * Group operation methods into classes? When enabled, you can
88+ * select which classes to export with `sdk.include` and/or
99+ * transform their names with `sdk.serviceNameBuilder`.
1010 *
1111- * Note that by enabling this option, your services will **NOT**
1111+ * Note that by enabling this option, your SDKs will **NOT**
1212 * support {@link https://developer.mozilla.org/docs/Glossary/Tree_shaking tree-shaking}.
1313 * For this reason, it is disabled by default.
1414 * @default false
1515 */
1616 asClass?: boolean;
1717 /**
1818- * Filter endpoints to be included in the generated services.
1919- * The provided string should be a regular expression where matched
2020- * results will be included in the output. The input pattern this
2121- * string will be tested against is `{method} {path}`. For example,
2222- * you can match `POST /api/v1/foo` with `^POST /api/v1/foo$`.
1818+ * Filter endpoints to be included in the generated SDK. The provided
1919+ * string should be a regular expression where matched results will be
2020+ * included in the output. The input pattern this string will be tested
2121+ * against is `{method} {path}`. For example, you can match
2222+ * `POST /api/v1/foo` with `^POST /api/v1/foo$`.
2323 *
2424 * This option does not work with the experimental parser.
2525 *
···2929 /**
3030 * Include only service classes with names matching regular expression
3131 *
3232- * This option has no effect if `services.asClass` is `false`.
3232+ * This option has no effect if `sdk.asClass` is `false`.
3333 */
3434 include?: string;
3535 /**
···4444 operationId?: boolean;
4545 /**
4646 * Name of the generated file.
4747- * @default 'services'
4747+ * @default 'sdk'
4848 */
4949 output?: string;
5050 /**
···5757 * Customize the generated service class names. The name variable is
5858 * obtained from your OpenAPI specification tags.
5959 *
6060- * This option has no effect if `services.asClass` is `false`.
6060+ * This option has no effect if `sdk.asClass` is `false`.
6161 * @default '{{name}}Service'
6262 */
6363 serviceNameBuilder?: string;
···1010 modelResponseTransformerTypeName,
1111 operationResponseTransformerTypeName,
1212 operationResponseTypeName,
1313-} from '../services/plugin-legacy';
1414-import { generateType, type TypesProps } from '../types/plugin-legacy';
1313+} from '../sdk/plugin-legacy';
1414+import { generateType, type TypesProps } from '../typescript/plugin-legacy';
1515import type { Config } from './types';
16161717interface ModelProps extends TypesProps {
···55import type { IROperationObject } from '../../ir/ir';
66import { operationResponsesMap } from '../../ir/operation';
77import { hasParameterGroupObjectRequired } from '../../ir/parameter';
88-import { operationIrRef } from '../@hey-api/services/plugin';
88+import { operationIrRef } from '../@hey-api/sdk/plugin';
99import type { PluginHandler } from '../types';
1010import type { Config } from './types';
1111
+12-12
packages/openapi-ts/src/plugins/index.ts
···33 defaultConfig as heyApiSchemas,
44} from './@hey-api/schemas';
55import {
66- type Config as HeyApiServices,
77- defaultConfig as heyApiServices,
88-} from './@hey-api/services';
66+ type Config as HeyApiSdk,
77+ defaultConfig as heyApiSdk,
88+} from './@hey-api/sdk';
99import {
1010 type Config as HeyApiTransformers,
1111 defaultConfig as heyApiTransformers,
1212} from './@hey-api/transformers';
1313import {
1414- type Config as HeyApiTypes,
1515- defaultConfig as heyApiTypes,
1616-} from './@hey-api/types';
1414+ type Config as HeyApiTypeScript,
1515+ defaultConfig as heyApiTypeScript,
1616+} from './@hey-api/typescript';
1717import {
1818 type Config as TanStackAngularQueryExperimental,
1919 defaultConfig as tanStackAngularQueryExperimental,
···4747 */
4848export type UserPlugins =
4949 | UserConfig<HeyApiSchemas>
5050- | UserConfig<HeyApiServices>
5050+ | UserConfig<HeyApiSdk>
5151 | UserConfig<HeyApiTransformers>
5252- | UserConfig<HeyApiTypes>
5252+ | UserConfig<HeyApiTypeScript>
5353 | UserConfig<TanStackAngularQueryExperimental>
5454 | UserConfig<TanStackReactQuery>
5555 | UserConfig<TanStackSolidQuery>
···60606161export type ClientPlugins =
6262 | PluginConfig<HeyApiSchemas>
6363- | PluginConfig<HeyApiServices>
6363+ | PluginConfig<HeyApiSdk>
6464 | PluginConfig<HeyApiTransformers>
6565- | PluginConfig<HeyApiTypes>
6565+ | PluginConfig<HeyApiTypeScript>
6666 | PluginConfig<TanStackAngularQueryExperimental>
6767 | PluginConfig<TanStackReactQuery>
6868 | PluginConfig<TanStackSolidQuery>
···73737474export const defaultPluginConfigs: DefaultPluginConfigsMap<ClientPlugins> = {
7575 '@hey-api/schemas': heyApiSchemas,
7676- '@hey-api/services': heyApiServices,
7676+ '@hey-api/sdk': heyApiSdk,
7777 '@hey-api/transformers': heyApiTransformers,
7878- '@hey-api/types': heyApiTypes,
7878+ '@hey-api/typescript': heyApiTypeScript,
7979 '@tanstack/angular-query-experimental': tanStackAngularQueryExperimental,
8080 '@tanstack/react-query': tanStackReactQuery,
8181 '@tanstack/solid-query': tanStackSolidQuery,
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export * from './types.gen';
33-export * from './services.gen';33+export * from './sdk.gen';
···33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55export * from './schemas.gen';
66-export * from './services.gen';
66+export * from './sdk.gen';
77export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···22export { ApiError } from './core/ApiError';
33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55-export * from './services.gen';
55+export * from './sdk.gen';
66export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export { ApiError } from './core/ApiError';
33export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
44-export * from './services.gen';
44+export * from './sdk.gen';
55export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export { ApiError } from './core/ApiError';
33export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
44-export * from './services.gen';
44+export * from './sdk.gen';
55export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export { ApiError } from './core/ApiError';
33export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
44-export * from './services.gen';
44+export * from './sdk.gen';
55export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22export { ApiError } from './core/ApiError';
33export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
44-export * from './services.gen';
44+export * from './sdk.gen';
55export * from './types.gen';
···22export { ApiError } from './core/ApiError';
33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55-export * from './services.gen';
55+export * from './sdk.gen';
66export * from './types.gen';
···22export { ApiError } from './core/ApiError';
33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55-export * from './services.gen';
55+export * from './sdk.gen';
66export * from './types.gen';
···44export { BaseHttpRequest } from './core/BaseHttpRequest';
55export { CancelablePromise, CancelError } from './core/CancelablePromise';
66export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
77-export * from './services.gen';
77+export * from './sdk.gen';
88export * from './types.gen';
···44export { BaseHttpRequest } from './core/BaseHttpRequest';
55export { CancelablePromise, CancelError } from './core/CancelablePromise';
66export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
77-export * from './services.gen';
77+export * from './sdk.gen';
88export * from './types.gen';
···22export { ApiError } from './core/ApiError';
33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55-export * from './services.gen';
55+export * from './sdk.gen';
66export * from './types.gen';
···22export { ApiError } from './core/ApiError';
33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55-export * from './services.gen';
55+export * from './sdk.gen';
66export * from './types.gen';
···22export { ApiError } from './core/ApiError';
33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55-export * from './services.gen';
55+export * from './sdk.gen';
66export * from './types.gen';
···22export { ApiError } from './core/ApiError';
33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55-export * from './services.gen';
55+export * from './sdk.gen';
66export * from './types.gen';
···22export { ApiError } from './core/ApiError';
33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55-export * from './services.gen';
55+export * from './sdk.gen';
66export * from './types.gen';
···22export { ApiError } from './core/ApiError';
33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55-export * from './services.gen';
55+export * from './sdk.gen';
66export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···22export { ApiError } from './core/ApiError';
33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55-export * from './services.gen';
55+export * from './sdk.gen';
66export * from './types.gen';
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './services.gen';
22+export * from './sdk.gen';
33export * from './types.gen';
···22export { ApiError } from './core/ApiError';
33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55-export * from './services.gen';
55+export * from './sdk.gen';
66export * from './types.gen';
···22export { ApiError } from './core/ApiError';
33export { CancelablePromise, CancelError } from './core/CancelablePromise';
44export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
55-export * from './services.gen';
55+export * from './sdk.gen';
66export * from './types.gen';