# `PolarExpress.Client`
[🔗](https://github.com/jeffhuen/polar_express/blob/main/lib/polar_express/client.ex#L1)

Polar API client. Holds configuration and executes HTTP requests.

Create a client via `PolarExpress.client/1` or `PolarExpress.client/2`:

    # From application config
    client = PolarExpress.client()

    # With explicit API key
    client = PolarExpress.client("pk_test_...", server: :sandbox)

    # Execute a request
    {:ok, org} = PolarExpress.Client.request(client, :get, "/v1/organizations/")

# `server`

```elixir
@type server() :: :production | :sandbox
```

# `t`

```elixir
@type t() :: %PolarExpress.Client{
  api_key: String.t(),
  base_url: String.t(),
  finch: atom(),
  max_retries: non_neg_integer(),
  server: server(),
  timeout_ms: pos_integer()
}
```

# `raw_request`

```elixir
@spec raw_request(t(), atom(), String.t(), keyword()) ::
  {:ok, %{status: integer(), headers: list(), body: binary()}}
  | {:error, PolarExpress.Error.t()}
```

Execute an API request and return the raw response without deserialization.

Returns `{:ok, %{status: integer, headers: list, body: binary}}` on success,
or `{:error, Error.t()}` on failure.

# `request`

```elixir
@spec request(t(), atom(), String.t(), keyword()) ::
  {:ok, struct() | map()} | {:error, PolarExpress.Error.t()}
```

Execute an API request.

## Options

  * `:params` - Request parameters (map)

# `stream_request`

```elixir
@spec stream_request(t(), atom(), String.t(), (term(), acc -> acc), acc, keyword()) ::
  {:ok, acc} | {:error, PolarExpress.Error.t()}
when acc: term()
```

Execute a streaming API request.

Streams the response body through `fun`, which receives chunks as they arrive.
The function signature is `(chunk, acc -> acc)` where chunk is one of:

  * `{:status, integer()}` — HTTP status code
  * `{:headers, [{String.t(), String.t()}]}` — response headers
  * `{:data, binary()}` — body chunk

Returns `{:ok, acc}` with the final accumulator, or `{:error, Error.t()}`.

## Example

    PolarExpress.Client.stream_request(client, :post, "/v1/organizations/",
      params: %{...},
      fun: fn chunk, acc -> [chunk | acc] end,
      acc: []
    )

---

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