# `DocRaptor.Client`
[🔗](https://github.com/ruskenberry/docraptor/blob/v0.1.2/lib/doc_raptor/client.ex#L1)

Configured DocRaptor HTTP client (Req-backed).

Create with `new/1`, then pass into `DocRaptor` helpers, or attach to a custom
`%Req.Request{}` with `attach/2`.

## Options for `new/1`

| Key | Required | Default | Notes |
| --- | --- | --- | --- |
| `:api_key` | **yes** | — | DocRaptor API key |
| `:test` | no | `true` | Merged into docs unless overridden per request |
| `:base_url` | no | `"https://api.docraptor.com"` | Override for stubs/proxies |
| `:req_options` | no | `[]` | Extra [Req](https://hex.pm/packages/req) options (e.g. `plug:`) |

Prefer `document_content` (with inlined CSS/assets) over `document_url` when
developing against localhost — DocRaptor cannot fetch private hosts without a
tunnel.

# `t`

```elixir
@type t() :: %DocRaptor.Client{
  api_key: String.t(),
  base_url: String.t(),
  req_options: keyword(),
  test: boolean()
}
```

# `attach`

```elixir
@spec attach(Req.Request.t(), t()) :: Req.Request.t()
```

Attaches DocRaptor auth and defaults to a `%Req.Request{}`.

Merges `base_url`, basic auth (`api_key` as username), `receive_timeout: 60_000`,
`decode_body: false`, `retry: false`, plus any `client.req_options`.

High-level APIs call this; advanced callers can build custom Req pipelines:

    body = %{
      "name" => "hello.pdf",
      "document_type" => "pdf",
      "document_content" => "<html/>",
      "test" => true
    }

    Req.new(method: :post, url: "/docs", json: body, decode_body: false)
    |> DocRaptor.Client.attach(client)
    |> Req.request()

# `new`

```elixir
@spec new(keyword() | map()) :: {:ok, t()} | {:error, DocRaptor.Error.t()}
```

Builds a client. `:api_key` is required. `:test` defaults to `true`.

Pass Req options (for example `plug: {Req.Test, MyStub}`) via `:req_options`.

## Examples

    {:ok, client} = DocRaptor.Client.new(api_key: "YOUR_API_KEY")
    {:ok, client} = DocRaptor.Client.new(api_key: key, test: false)
    {:error, %DocRaptor.Error{reason: :missing_api_key}} = DocRaptor.Client.new([])

---

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