# Client

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

A `Client` is cheap to clone, and clones share one connection pool. Create one and reuse it for every request. Every future and stream it returns is `Send`. It has no `close` method, and its `Debug` output never includes the API key.

## new

Returns a client that authenticates with `api_key` and uses the default configuration.

```rust
pub fn new(api_key: impl Into<String>) -> Result<Self>
```

- **Input:** Surrounding whitespace is trimmed from the key. An empty key, or one with characters that are not allowed in an HTTP header, returns `Error::InvalidInput`. The SDK never reads the API key from the environment. Pass it explicitly, as [Getting started](https://docs.synthient.com/sdks/rust#getting-started) does with `SYNTHIENT_API_KEY`.
- **Errors:** `Error::Http` is returned if the TLS backend cannot be initialized.
- **Network:** It performs no network I/O.

## builder

Returns a `ClientBuilder` for a client that authenticates with `api_key`.

```rust
pub fn builder(api_key: impl Into<String>) -> ClientBuilder
```

```rust
use std::time::Duration;

use synthient::Client;

let client = Client::builder(std::env::var("SYNTHIENT_API_KEY")?)
    .max_retries(4)
    .timeout(Duration::from_secs(30))
    .user_agent("my-app/1.0")
    .build()?;
let account = client.account().await?;
println!("{} credits left", account.lookup_quota.credits);
```

- **Use:** Call its methods to change the configuration, then `build`.

## ClientBuilder

```rust
pub fn base_url(self, url: impl Into<String>) -> Self
pub fn max_retries(self, retries: u32) -> Self
pub fn timeout(self, timeout: Duration) -> Self
pub fn user_agent(self, product: impl Into<String>) -> Self
pub fn http_client(self, builder: reqwest::ClientBuilder) -> Self
pub fn on_response(self, hook: impl Fn(&ResponseMetadata) + Send + Sync + 'static) -> Self
pub fn build(self) -> Result<Client>
```

- `base_url` — Sets the API base URL, including the version path. The default is `DEFAULT_BASE_URL`. It must be an `http` or `https` URL with a host and no credentials, query, or fragment. Trailing slashes are removed.
- `max_retries` — 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/rust/errors#retries-and-timeouts).
- `timeout` — Sets a time limit for each operation, covering every attempt and the waits between them. For streams and downloads, it covers opening them but not reading their bodies. There is no limit by default. An operation that runs out of time returns `Error::Timeout`.
- `user_agent` — Appends a product token, such as `my-app/1.2`, to the `User-Agent` header, which starts with `synthient-rust/` followed by the crate version.
- `http_client` — Builds the HTTP client from a `reqwest::ClientBuilder`, for settings such as proxies, TLS roots, and connection timeouts. The SDK turns off its redirects, so the API key never reaches the storage host, and its retries, so billed lookups are never resent. Don't set a total `timeout` on it, because that would also cut off streams and downloads; use a read timeout instead. The default client gives up connecting after 30 seconds and fails a read that stalls for 60 seconds. A builder passed here replaces those defaults.
- `on_response` — Calls `hook` after each API response's headers arrive. See [Response metadata](#response-metadata).
- `build` — Builds the client. It performs no network I/O. Returns `Error::InvalidInput` if the API key is empty or contains characters not allowed in a header, or if the base URL or `User-Agent` is invalid, and `Error::Http` if the HTTP client cannot be built.

## Constants

- `DEFAULT_BASE_URL` `&str` — `"https://api.synthient.com/api/v4"`, the base URL of the Synthient HTTP API.
- `VERSION` `&str` — The version of the crate, such as `"1.0.0"`. It is sent in the `User-Agent` header.

## Response metadata

`ClientBuilder::on_response` calls a function synchronously after each API response's headers arrive.

```rust
use synthient::Client;

let client = Client::builder(std::env::var("SYNTHIENT_API_KEY")?)
    .on_response(|meta| {
        if let Some(rate_limit) = &meta.rate_limit {
            println!(
                "{} {:?} {} {:?}",
                meta.status, meta.request_id, rate_limit.remaining, rate_limit.reset
            );
        }
    })
    .build()?;
let account = client.account().await?;
println!("{}", account.email);
```

- **Coverage:** The hook sees retries, pages, stream handshakes, and error responses, but not download responses from the storage host.
- **Concurrency:** The hook must be `Send + Sync + 'static`.
- **Lifetime:** It receives a reference, so clone the `ResponseMetadata` to keep it.

### ResponseMetadata

- `status` `StatusCode` — The HTTP status of the response.
- `request_id` `Option<String>` — The `X-Request-ID` header, which identifies the request when contacting Synthient support.
- `rate_limit` `Option<RateLimit>` — The rate limit that applies to the operation, or `None` if the response does not report one, as on `health`.
- `headers` `HeaderMap` — A 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. It is present only when all three headers hold non-negative integers. Limits are shared by every key of a team. See [Rate Limits](https://docs.synthient.com/rate-limits).

- `limit` `u64` — The bucket size, which is the burst the operation allows.
- `remaining` `u64` — The number of requests left in the bucket.
- `reset` `Duration` — How long until the bucket is full again.