# `Tinkex.Config`
[🔗](https://github.com/North-Shore-AI/tinkex/blob/v0.4.0/lib/tinkex/config.ex#L1)

Client configuration for the Tinkex SDK.

Instances of this struct are passed through every API call to support
multi-tenant usage (different API keys, base URLs, timeouts, and retry policies
within the same BEAM VM). Construction is the only place where we consult
`Application.get_env/3`; the request hot path only works with the struct that
callers provide.

# `poll_backoff_policy`

```elixir
@type poll_backoff_policy() ::
  nil
  | :none
  | :exponential
  | boolean()
  | {:exponential, pos_integer(), pos_integer()}
  | (non_neg_integer() -> non_neg_integer())
```

# `proxy`

```elixir
@type proxy() ::
  {:http | :https, host :: String.t(), port :: 1..65535, opts :: keyword()}
  | nil
```

# `t`

```elixir
@type t() :: %Tinkex.Config{
  api_key: String.t(),
  base_url: String.t(),
  cf_access_client_id: String.t() | nil,
  cf_access_client_secret: String.t() | nil,
  default_headers: map(),
  default_query: map(),
  dump_headers?: boolean(),
  feature_gates: [String.t()] | nil,
  http_client: module(),
  http_pool: atom(),
  log_level: :debug | :info | :warn | :error | nil,
  max_retries: non_neg_integer(),
  otel_propagate: boolean(),
  poll_backoff: poll_backoff_policy(),
  project_id: String.t() | nil,
  proxy: proxy(),
  proxy_headers: [{String.t(), String.t()}],
  recovery: Tinkex.Recovery.Policy.t() | nil,
  tags: [String.t()] | nil,
  telemetry_enabled?: boolean(),
  timeout: pos_integer(),
  user_metadata: map() | nil
}
```

# `default_max_retries`

```elixir
@spec default_max_retries() :: non_neg_integer()
```

Return BEAM-conservative default max_retries (2).

# `default_timeout`

```elixir
@spec default_timeout() :: pos_integer()
```

Return BEAM-conservative default timeout (120s).

# `new`

```elixir
@spec new(keyword()) :: t()
```

Build a config struct using runtime options + application/env defaults.

`max_retries` is the number of additional attempts after the initial request.
With the default of 10, the SDK will perform up to eleven total attempts.

## Parity Mode

Tinkex defaults to Python SDK parity values to ease cross-language migration:
  * `timeout: 60_000` (1 minute)
  * `max_retries: 10` (11 total attempts)

To opt into BEAM-conservative defaults instead, set parity mode to `:beam`:

    # Via options
    config = Tinkex.Config.new(parity_mode: :beam)

    # Via application config
    config :tinkex, parity_mode: :beam

    # Via environment variable
    export TINKEX_PARITY=beam

Explicit timeout/max_retries options always override parity defaults.

# `python_max_retries`

```elixir
@spec python_max_retries() :: non_neg_integer()
```

Return Python SDK parity max_retries (10).

# `python_timeout`

```elixir
@spec python_timeout() :: pos_integer()
```

Return Python SDK parity timeout (60s).

# `validate!`

```elixir
@spec validate!(t()) :: t()
```

Validate an existing config struct.

---

*Consult [api-reference.md](api-reference.md) for complete listing*