Search documentation of polar_express

# PolarExpress.Client (polar_express v0.1.5)

Copy Markdown View Source

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/")

## Summary

### Types

server()
t()

### Functions

raw_request(client, method, path, opts \\ [])

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

request(client, method, path, opts \\ [])

Execute an API request.

stream_request(client, method, path, fun, acc, opts \\ [])

Execute a streaming API request.

## Types

# server()

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

# t()

    @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()
    }

## Functions

# raw_request(client, method, path, opts \\ [])

    @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(client, method, path, opts \\ [])

    @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(client, method, path, fun, acc, opts \\ [])

    @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: []
    )