# apigenie-generator client fetch

Source: https://apigenie.pl/docs/reference/generator/client-fetch
Part of the reference of [apigenie-generator](https://apigenie.pl/docs/reference/generator.md).
Its other pages: [Conformance results](https://apigenie.pl/docs/reference/generator/conformance.md), [docs](https://apigenie.pl/docs/reference/generator/docs.md), [data](https://apigenie.pl/docs/reference/generator/data.md), [schema zod](https://apigenie.pl/docs/reference/generator/schema-zod.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir.md), [client go](https://apigenie.pl/docs/reference/generator/client-go.md), [client java](https://apigenie.pl/docs/reference/generator/client-java.md), [client python](https://apigenie.pl/docs/reference/generator/client-python.md), [client rust](https://apigenie.pl/docs/reference/generator/client-rust.md), [client swift](https://apigenie.pl/docs/reference/generator/client-swift.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet.md), [server axum](https://apigenie.pl/docs/reference/generator/server-axum.md), [server express](https://apigenie.pl/docs/reference/generator/server-express.md), [server fastapi](https://apigenie.pl/docs/reference/generator/server-fastapi.md), [server go](https://apigenie.pl/docs/reference/generator/server-go.md), [server hummingbird](https://apigenie.pl/docs/reference/generator/server-hummingbird.md), [server mcp](https://apigenie.pl/docs/reference/generator/server-mcp.md), [server orpc](https://apigenie.pl/docs/reference/generator/server-orpc.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring.md), [server vapor](https://apigenie.pl/docs/reference/generator/server-vapor.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp-asyncapi.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-asyncapi.md), [client go](https://apigenie.pl/docs/reference/generator/client-go-asyncapi.md), [client java](https://apigenie.pl/docs/reference/generator/client-java-asyncapi.md), [client kafkajs](https://apigenie.pl/docs/reference/generator/client-kafkajs.md), [client python](https://apigenie.pl/docs/reference/generator/client-python-asyncapi.md), [client ws](https://apigenie.pl/docs/reference/generator/client-ws.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet-asyncapi.md), [server faststream](https://apigenie.pl/docs/reference/generator/server-faststream.md), [server go](https://apigenie.pl/docs/reference/generator/server-go-asyncapi.md), [server kafkajs](https://apigenie.pl/docs/reference/generator/server-kafkajs.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix-asyncapi.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring-asyncapi.md), [server ws](https://apigenie.pl/docs/reference/generator/server-ws.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-protobuf.md), [server elixir-grpc](https://apigenie.pl/docs/reference/generator/server-elixir-grpc.md), [server absinthe](https://apigenie.pl/docs/reference/generator/server-absinthe.md).

[Tier 1](/docs/reference/generator/conformance#tiers) · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · [Verification](#verification)

Generate a TypeScript client for the Fetch API from an OpenAPI document.

## Usage

```sh
apigenie-generator client fetch [...OPTIONS] INPUT_FILE
```

## Description

The generator writes TypeScript sources with no runtime dependencies: requests go through the
global `fetch()` (or one you pass), so the client runs in browsers and in Node.js 18 or later. The
input is an OpenAPI 3.0, 3.1 or 3.2 document or, since 0.12.0, a Swagger 2.0 document (see
[Swagger 2.0 input](/docs/reference/generator#swagger-20-input)).

| File | Contents |
| ---- | -------- |
| `src/types.ts` | a type per component schema, the `...Params` interface of each operation, and the named types of inline bodies |
| `src/operations.ts` | an `async` function per operation, and a function per streamed response format |
| `src/metadata.ts` | `DEFAULT_BASE_URL`, the `AuthCredentials` interface and `SECURITY_SCHEMES` |
| `src/runtime.ts` | `configure()`, `ApiError`, parameter serialization, authentication, body encoding |
| `src/index.ts` | exports the types, the operations and the public part of the runtime |
| `package.json`, `tsconfig.json` | an ES module package built with `tsc` into `dist/` (`layout: package` only) |

With `layout: sources`, the five files are written directly to the output directory, to be
compiled as part of your own project. A client of a shipping API, generated with `layout: sources`
into `api/`:

```ts
import { configure, ApiError, listShipments, getShipment, downloadLabelFile } from "./api/index.js";

configure({
  baseUrl: "https://eu.api.carpetexpress.example/v2",
  auth: {
    apiKey: "ce_live_123", // sent in the X-Api-Key header
    oauth2: () => fetchAccessToken(), // called before every request that needs it
  },
});

try {
  const page = await listShipments({ status: ["in_transit", "delivered"], limit: 20 });
  const shipment = await getShipment(
    { shipmentId: "shp_01J9Z", expand: ["labels"] },
    { signal: AbortSignal.timeout(5000), headers: { "X-Request-Id": "req-1" } },
  );
  const label: Blob = await downloadLabelFile({ labelId: "lbl_1", extension: "pdf" });
} catch (error) {
  if (error instanceof ApiError) {
    console.error(error.status, error.body); // status 0: no response was received
  }
}
```

### Configuration at run time

`configure(settings)` sets the client-wide settings; settings it doesn't give keep their values.
Every operation function also takes an optional last argument, `RequestOptions`, with the same
settings for that call only, and an `AbortSignal`.

| Setting | Meaning |
| ------- | ------- |
| `baseUrl` | Base URL of the API. Defaults to `DEFAULT_BASE_URL`: the URL of the document's first server when it is absolute and has no variables, otherwise empty. A call without a base URL throws an `ApiError`, unless the operation has an absolute server of its own (see Servers). |
| `fetch` | The `fetch()` implementation; the global one by default. |
| `headers` | Headers sent with every request. |
| `auth` | Credentials, by security scheme name (`AuthCredentials`). |
| `operationServers` | Since 0.12.0. Whether an operation with servers of its own is sent to the first of them; `true` by default. With `false`, every request goes to `baseUrl`, for example to a mock server. |
| `signal` | `RequestOptions` only: aborts the request. |

### Operations

Every operation is an exported `async` function named after its `operationId` in camel case
(`list_shipments` becomes `listShipments`), or after its method and path when it has none
(`GET /pets/{id}` becomes `getPetsId`); see `action_naming`. The summary and the description
become its JSDoc comment, and deprecated operations are marked `@deprecated`.

```ts
export async function getShipment(params: GetShipmentParams, options?: RequestOptions): Promise<Shipment>
export async function listShipments(params: ListShipmentsParams = {}, options?: RequestOptions): Promise<ShipmentPage>
export async function getAccount(options?: RequestOptions): Promise<Account>
```

- **Parameters** of all locations (path, query, header, cookie) are properties of one
  `...Params` object, under their names in the document (`params["If-Match"]`). A name used in two
  locations gets the location as a prefix for the second one (`queryId`). `Accept`, `Content-Type`
  and `Authorization` header parameters are left out. When no parameter is required, the object
  defaults to `{}`.
- **Serialization** follows each parameter's `style` and `explode`: `simple`, `label` and `matrix`
  path parameters; `form`, `spaceDelimited`, `pipeDelimited` and `deepObject` query parameters.
  Values that are `undefined` or `null` are not sent; `Date` values are sent in ISO 8601 form.
  Since 0.12.0, a parameter described by `content` in a JSON media type instead of a `schema` is
  sent as its JSON text, URL-encoded in a query (`near=%7B%22type%22%3A%22Point%22...`) or a path.
- **The request body** is the `body` property of the params (`requestBody` when a parameter is
  already named `body`). An operation with several request media types gets one: JSON first, then
  `application/x-www-form-urlencoded`, `multipart/form-data`, `text/*`, and other types.
  JSON bodies are typed by their schema and sent with `JSON.stringify`; form bodies are objects
  (or `URLSearchParams`), multipart bodies `FormData`, text bodies `string`, and other media types
  `Blob`. Since 0.12.0, an operation with several request media types of the preferred one's kind
  (two JSON types, for example) can send any of them. The params get a `contentType` property
  (`bodyContentType` when a parameter has that name): a union of those media types that defaults
  to the preferred one. A JSON or form body is typed as the union of their schemas' types, and
  the type check doesn't tie the body to the media type. Media ranges such as `image/*` are not
  offered. Multipart bodies are always sent as `multipart/form-data`, the type `fetch` gives a
  `FormData` body.

  ```ts
  await updateShipment({
    shipmentId,
    "If-Match": etag,
    body: [{ op: "remove", path: "/metadata" }],
    contentType: "application/json-patch+json",
  });
  ```
- **Servers.** Since 0.12.0, an operation with `servers` of its own, or whose path item has them,
  is sent to the first of them, unless it is the document's first server. Each server variable
  takes its default value. An absolute server URL is used in place of `baseUrl`, even when
  `baseUrl` is configured. A relative one is resolved against `baseUrl` as a URL reference, so
  one starting with `/` replaces the path of `baseUrl`. In a browser, a relative `baseUrl` is
  itself resolved against the page's address. Without a `baseUrl`, or with a relative `baseUrl`
  outside a browser, the call fails with an `ApiError`. `operationServers: false` sends every
  request to `baseUrl`.
- **Left-out operations.** Since 0.12.0, an operation marked `x-internal: true`, or whose path
  item is, is left out unless `internal_operations` is `true`. One marked
  `x-apigenie.codegen.disabled: true` is always left out.
- **The result** is the body of the success response (`2XX`, or `default` when no success
  response is documented): its schema's type for JSON, `string` for `text/*`, `Blob` for other
  media types. Several success responses give a union (`Promise<Shipment | Job>`), and a response
  without content adds `undefined`; an operation whose responses have no content returns
  `Promise<void>`. The `Accept` header is set from the media type of the response.
- **Streams.** Since 0.12.0, an operation with a success response in `text/event-stream` or JSON
  Lines (`application/jsonl`, `application/x-ndjson`, `application/x-jsonlines`) also gets a
  function per format. It is named after the operation with `EventStream` or `Jsonl` appended,
  with a number when that name is taken. It takes the same arguments and returns an
  `AsyncIterable` of the items typed by `itemSchema` (`x-itemSchema` in OpenAPI 3.0 and 3.1
  documents). JSON Lines yield one parsed value per non-blank line; a line that isn't JSON throws
  an `ApiError` whose `body` is the line. Server-sent events yield an object with the event's
  `data`, `event`, `id` and `retry` fields, a `ServerSentEvent` when no `itemSchema` describes
  them. `data` is the text of its `data:` lines joined by line feeds, not parsed, and events
  without data are skipped. The request is sent when the iteration starts, and leaving the loop
  early closes the connection. The operation's own function keeps reading its preferred media
  type as a whole.

  ```ts
  for await (const event of getTrackingEventsJsonl({ shipmentId: "shp_01J9Z" })) {
    console.log(event.status); // a TrackingEvent
  }
  ```
- **Security** is the operation's requirements, or the document's when the operation declares
  none. Before the request is sent, the first alternative whose credentials are all configured
  is applied; when none is, the request goes out without credentials.

### Types

Component schemas become exported interfaces (plain objects) or type aliases, named in Pascal case
(`user_profile` becomes `UserProfile`, `x-apigenie.codegen.name` overrides the name):

| Schema | TypeScript |
| ------ | ---------- |
| object with properties | `interface`; optional properties are marked `?`, deprecated ones `@deprecated` |
| `additionalProperties` | `Record<string, T>`, or an index signature next to properties; `false` without `patternProperties`: no index signature, or `Record<string, never>` without properties |
| `patternProperties` | with `additionalProperties: false` or a schema object: the union of the pattern schemas' types (and `T`) in the `Record` or the index signature, since 0.12.0; ignored without `additionalProperties` or with `true` |
| `enum`, `const` | union of literals (`"available" \| "sold"`, `1 \| 2 \| 3`) |
| `oneOf`, `anyOf` | union (`Circle \| Square`) |
| `allOf` | intersection (`Shape & { name?: string }`) |
| `prefixItems` | tuple (`[number, number]`) |
| `type: [T, "null"]`, OpenAPI 3.0 `nullable: true` | `T \| null` |
| `format: binary` string | `Blob` |
| other strings, `date-time` included | `string` |
| `integer`, `number` | `number` |
| `{}` | `unknown` |

Recursive schemas refer to themselves (`children?: Tree[]`). The client doesn't validate values
against their schemas: constraints such as `minimum`, `pattern` or `if`/`then`/`else` generate no
code.

### Authentication

`AuthCredentials` has an optional property per security scheme of the document. A credential is
a string, or a function returning a string or a promise of one, called before every request that
needs it (to refresh tokens).

| Scheme | Sent as |
| ------ | ------- |
| `apiKey` | the header, query parameter or cookie the scheme names |
| `http` with `scheme: basic` | `Authorization: Basic ...`, the credential being `user:password` |
| `http` with `scheme: bearer` | `Authorization: Bearer <credential>` |
| other `http` schemes | `Authorization: <scheme> <credential>` |
| `oauth2`, `openIdConnect` | `Authorization: Bearer <credential>` |

The client implements no OAuth 2.0 flow: it sends the access token you supply.

### Errors

Every failure is an `ApiError` (a subclass of `Error`) with:

| Property | Value |
| -------- | ----- |
| `status` | the HTTP status, or `0` when no response was received |
| `body` | the response body: parsed JSON for JSON media types, otherwise text, `undefined` when empty |
| `response` | the `Response`, when there was one |
| `cause` | the underlying error, e.g. a network error or a `SyntaxError` of invalid JSON |

A response with a status outside 200-299 throws, as does a success response whose JSON can't be
parsed. So do a network failure, a missing path parameter, and a missing base URL for an
operation without an absolute server of its own. A stream function throws them from the first
iteration.

### Extensions

| Extension | Effect |
| --------- | ------ |
| `x-apigenie.codegen.name` | name of the type of a component schema |
| `x-apigenie.codegen.action-name` | name of the function of an operation, when `action_naming` lists `extension` |
| `x-defaultMapping` | `defaultMapping` of a discriminator in OpenAPI 3.0 and 3.1 documents: the schema of the values whose discriminator value isn't mapped |
| `x-itemSchema` | `itemSchema` of a media type in OpenAPI 3.0 and 3.1 documents: the type of the items of a streamed response |
| `x-apigenie.codegen.disabled` | since 0.12.0, `true` on an operation or its path item leaves the operation out |
| `x-internal` | since 0.12.0, `true` on an operation or its path item leaves the operation out, unless `internal_operations` is `true` |

The extensions can live in an overlay for this target instead of in the document, e.g.
`fetch.overlay.yaml`:

```yaml
overlay: 1.0.0
info:
  title: TypeScript names
  version: 1.0.0
actions:
  - target: $.components.schemas.Pet
    update:
      x-apigenie:
        codegen:
          name: Animal
```

```sh
apigenie-generator client fetch openapi.yaml --overlay fetch.overlay.yaml -o out
```

### Limitations

The features of the conformance fixture the client doesn't support yet are listed under
[Verification](#verification). Beyond them:

- Form-encoded bodies don't apply the `encoding` styles of their properties: an object property
  is sent as `[object Object]`.
- Callbacks, webhooks and links aren't generated: they describe requests the server makes, or
  documentation.
- Documents referencing other files must be bundled first with
  [`apigenie bundle`](/docs/reference/cli/bundle).

## Options

### -c, --config

Path to the configuration file to use. See the "Configuration" section for more information.

### --overlay OVERLAY

Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the
extensions of the "Extensions" section. Can be repeated: the overlays apply in order, after those
listed under `commands.generate.client_fetch.overlay` in the configuration file (with paths relative
to it). Warnings and errors about a value an overlay set point to the overlay.

### --strict

Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated)
instead of a warning (`OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.`).

### --check

Writes nothing: compares what the generator would write with the output directory, prints the
files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See
[Check that generated code is up to date](/docs/reference/generator#check-that-generated-code-is-up-to-date).

### -o, --output

Required. Directory where the client is generated.

### --package-name

Name of the npm package in `package.json`. Defaults to the document's `info.title` in lower case
with hyphens between words (`Carpet Express Shipping API` becomes `carpet-express-shipping-api`),
or `api-client` when the title has no letters or digits.

### --package-version

Version of the npm package in `package.json`. Defaults to the document's `info.version`, or
`0.0.0` when it is empty.

## Configuration

```yaml
version: '1.0'
commands:
  generate:
    client_fetch:
      layout: sources
      import_extension: ''
      action_naming: [id, extension, url]
      internal_operations: true
```

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `layout` | `package` or `sources` | `package` | `package` writes an npm package (`package.json`, `tsconfig.json`, sources in `src/`); `sources` writes only the sources, directly in the output directory. |
| `import_extension` | `.js` or `''` | `.js` | Extension of relative imports between the generated files: `.js` for Node.js ES modules (`NodeNext` resolution), `''` for bundlers. |
| `action_naming` | `id`, `extension`, `url`, or a list of them | `[id, url]` | Where function names come from, in order of preference: the `operationId`, the `x-apigenie.codegen.action-name` extension, or the method and path. |
| `internal_operations` | boolean | `false` | Since 0.12.0. Also generates the operations marked `x-internal: true` on the operation or its path item. |

## Verification

The [codegen conformance suite](/docs/reference/generator#conformance-checks) runs this target on the Carpet Express OpenAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. [All targets](/docs/reference/generator/conformance#openapi).

This target's support tier is [Tier 1](/docs/reference/generator/conformance#tiers). It goes through all three levels before every release, with the goal of supporting every feature of the fixture. Its unsupported features are worked on first.

| Results | Level 1 | Level 2 | Level 3 |
| --- | --- | --- | --- |
| Release 0.12.0 | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 29 supported, 0 not yet, 5 not checked | ✓ pass (Version 6.0.3, ESLint 10 + typescript-eslint 8) | ✓ 40 of 40 operations pass (node) |
| Development version | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 29 supported, 0 not yet, 5 not checked | runs before a release | runs before a release |
