# Client

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

A `Client` is safe for concurrent use. Create one and reuse it for every request. It has no `Close` method.

## NewClient

Returns a client that authenticates with `apiKey`.

```go
func NewClient(apiKey string, opts ...Option) (*Client, error)
```

```go
client, err := synthient.NewClient(os.Getenv("SYNTHIENT_API_KEY"),
	synthient.WithMaxRetries(4),
	synthient.WithUserAgent("my-app/1.0"),
)
if err != nil {
	log.Fatal(err)
}
```

- **Input:** Surrounding whitespace is trimmed from the key, and an empty key returns `ErrMissingAPIKey`. An invalid option, such as a malformed base URL or a negative retry count, also returns an error.
- **Network:** It performs no network I/O.

## Options

- `WithBaseURL` `func(u string) Option` — Sets the API base URL, including the version path. The default is `DefaultBaseURL`. It must be an `http` or `https` URL with a host and no query or fragment.
- `WithHTTPClient` `func(hc *http.Client) Option` — Sets the HTTP client used to send requests. The client is copied and never modified. Don't set `http.Client.Timeout` on it, because that would also cut off streams and downloads; use context deadlines instead. The default client bounds the wait for response headers to one minute. Custom transports must not replay requests whose bodies cannot be rewound.
- `WithMaxRetries` `func(n int) Option` — Sets how many times a failed request is retried. The default is `2`, and `0` disables retries. See [Retries and timeouts](https://docs.synthient.com/sdks/go/errors#retries-and-timeouts).
- `WithUserAgent` `func(s string) Option` — Appends `s`, such as `"my-app/1.2"`, to the `User-Agent` header, which starts with `synthient-go/` followed by the SDK version.
- `WithResponseHook` `func(hook func(context.Context, ResponseMetadata)) Option` — Calls `hook` after each API response's headers arrive. See [Response metadata](#response-metadata).

## Constants and variables

- `DefaultBaseURL` `const string` — `"https://api.synthient.com/api/v4"`, the base URL of the Synthient HTTP API.
- `Version` `const string` — The SDK version, such as `"1.0.0"`. It is sent in the `User-Agent` header.
- `ErrMissingAPIKey` `error` — Returned by `NewClient` when the API key is empty or all whitespace.

## Response metadata

`WithResponseHook` calls a function synchronously after each API response's headers arrive.

```go
client, err := synthient.NewClient(os.Getenv("SYNTHIENT_API_KEY"),
	synthient.WithResponseHook(func(_ context.Context, meta synthient.ResponseMetadata) {
		if meta.RateLimit != nil {
			fmt.Println(meta.StatusCode, meta.RequestID, meta.RateLimit.Remaining, meta.RateLimit.Reset)
		}
	}),
)
if err != nil {
	log.Fatal(err)
}
```

- **Coverage:** The hook sees retries, pages, stream handshakes, and decoding failures. Storage download responses are excluded.
- **Context:** The context belongs to the caller's operation.
- **Concurrency:** The hook must be safe for concurrent use, and it may retain or modify the metadata without affecting the client.
- **Disabling:** A `nil` hook disables the callback.

### ResponseMetadata

- `StatusCode` `int` — The HTTP status code of the response.
- `RequestID` `string` — The `X-Request-ID` header.
- `RateLimit` `*RateLimit` — The rate limit that applies to the operation, or `nil` if the response does not report one, as on `Health`.
- `Header` `http.Header` — An independent copy of the response headers. Headers can contain sensitive data, such as presigned download URLs.

### RateLimit

The state of an operation's rate limit, from the `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers. Limits are shared by every key of a team. See [Rate Limits](https://docs.synthient.com/rate-limits).

- `Limit` `int` — The bucket size, which is the burst the operation allows.
- `Remaining` `int` — The number of requests left in the bucket.
- `Reset` `time.Duration` — How long until the bucket is full again.