# Client

Create and configure the client, and read the metadata of every API response.

A `Synthient` client performs no network I/O until a method is called. Create one and reuse it for every request. It has no `close` method.

## Constructor

Creates a client.

```ts
constructor(options?: ClientOptions);
```

```ts
import { Synthient } from "@synthient/synthient";

export const client = new Synthient({
  maxRetries: 4,
  timeout: 30_000,
  userAgent: "my-app/1.0",
});
```

- **Auth:** The API key is `options.apiKey`, or the `SYNTHIENT_API_KEY` environment variable when `apiKey` is omitted or `undefined`. Surrounding whitespace is trimmed.
- **Input:** A missing or empty key, or a key with characters other than printable ASCII, throws a `TypeError`. An invalid option also throws: a bad `baseURL` or `userAgent` throws a `TypeError`, and a `maxRetries` or `timeout` out of range throws a `RangeError`.

## ClientOptions

- `apiKey?` `string | undefined` — The API key. Defaults to the `SYNTHIENT_API_KEY` environment variable. An explicit empty string does not fall back to the variable.
- `baseURL?` `string | undefined` — The API base URL, including the version path. Defaults to `DEFAULT_BASE_URL`. It must be an `http` or `https` URL without credentials, a query, or a fragment.
- `maxRetries?` `number | undefined` — How many times a failed request is retried. Defaults to `2`, and `0` disables retries. It must be a non-negative integer. See [Retries and timeouts](https://docs.synthient.com/sdks/node/errors#retries-and-timeouts).
- `timeout?` `number | undefined` — The longest time in milliseconds to wait for response headers or for the next part of a body, including streams and downloads. Defaults to `60_000`. It must be an integer from 1 to 2147483647. It does not limit a whole call; pass `AbortSignal.timeout(ms)` as a call's `signal` for that.
- `fetch?` `Fetch | undefined` — The fetch implementation. Defaults to the global `fetch`. A custom fetch must not follow redirects or replay requests itself, because the client relies on seeing each redirect to keep the API key away from other hosts, and on sending each billed lookup once. It must honor `init.signal`, which carries both the `timeout` and a call's `signal`. It also downloads exports from the storage host, without the API key.
- `userAgent?` `string | undefined` — Appended to the `User-Agent` header, such as `"my-app/1.2"`. The header starts with `synthient-node/` followed by the SDK version, `VERSION`.
- `onResponse?` `((metadata: ResponseMetadata) => void) | undefined` — Called synchronously when each API response's headers arrive. See [Response metadata](#response-metadata).

## RequestOptions

Every `Synthient` and `Feed` method takes an optional last argument that is a `RequestOptions` or extends it.

- `signal?` `AbortSignal | undefined` — Cancels the call. The call rejects with the signal's reason, as `fetch` does. Use `AbortSignal.timeout(ms)` to bound a whole call, including retries.

## Fetch

The subset of `fetch` the client uses, for the `fetch` option.

```ts
type Fetch = (input: string, init: RequestInit) => Promise<Response>;
```

## Constants

`DEFAULT_BASE_URL` is the base URL of the Synthient HTTP API. `VERSION` is the SDK version, such as `"2.0.0"`, which is sent in the `User-Agent` header.

```ts
const DEFAULT_BASE_URL = "https://api.synthient.com/api/v4";
declare const VERSION: string;
```

## Response metadata

`onResponse` is called synchronously when each API response's headers arrive, including retries, pages, stream handshakes, and responses that fail to decode.

```ts
import { Synthient } from "@synthient/synthient";

export const client = new Synthient({
  onResponse: (metadata) => {
    const remaining = metadata.headers.get("ratelimit-remaining");
    console.log(metadata.status, metadata.requestID, remaining);
  },
});
```

- **Coverage:** Storage download responses are excluded.
- **Async:** It must not be async.
- **Errors:** If it throws, the error is reported with `process.emitWarning` and the call continues.
- **Rate limits:** The SDK has no rate limit type. Read the `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers from `headers` instead. See [Rate Limits](https://docs.synthient.com/rate-limits).

### ResponseMetadata

- `status` `number` — The HTTP status code.
- `requestID` `string` — The `X-Request-ID` header, or `""`.
- `headers` `Headers` — A copy of the response headers, including `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` when present. Changing it does not affect the client. Headers can contain sensitive data, such as presigned download URLs.