# `Weavr.HTTP`
[🔗](https://github.com/iamkanishka/weavr/blob/main/lib/weavr/http.ex#L1)

Low-level HTTP transport for the Weavr client.

This module wraps Erlang's built-in `:httpc` so that `weavr` ships
with zero runtime dependencies. It is responsible for:

  * building request URLs against a configured base URL
  * serializing/deserializing JSON bodies
  * attaching the `api-key` header (and `auth_token` / `Authorization`
    header, supplied by `Weavr.Client`)
  * retrying idempotent requests on transient failures with
    exponential backoff and jitter
  * emitting `:telemetry` events around every request
  * normalizing every outcome into `{:ok, status, headers, body}` or
    `{:error, Weavr.Error.t()}`

This module is intentionally unaware of Weavr *resources* (accounts,
cards, identities, ...). Resource modules call into this layer; this
layer never calls back out to them.

# `headers`

```elixir
@type headers() :: [{String.t(), String.t()}]
```

# `method`

```elixir
@type method() :: :get | :post | :put | :patch | :delete
```

# `result`

```elixir
@type result() :: {:ok, pos_integer(), headers(), term()} | {:error, Weavr.Error.t()}
```

# `request`

```elixir
@spec request(keyword()) :: result()
```

Performs an HTTP request and returns a normalized result.

## Options

  * `:base_url` (required) - e.g. `"https://sandbox.weavr.io/multi"`
  * `:method` (required) - one of `[:get, :post, :put, :patch, :delete]`
  * `:path` (required) - e.g. `"/bulks/123"` (joined onto `:base_url`)
  * `:headers` - additional headers, merged with internally-added ones
  * `:query` - a map or keyword list of query parameters
  * `:body` - a term to be JSON-encoded as the request body
  * `:idempotency_key` - sent as the `idempotency-ref` header on
    `POST`/`PATCH` requests that support it
  * `:max_retries` - defaults to `2`
  * `:connect_timeout` - milliseconds, defaults to `5000`
  * `:recv_timeout` - milliseconds, defaults to `30000`
  * `:telemetry_metadata` - extra metadata merged into emitted telemetry events

---

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