# Hairfilter SDK for Elixir

`hairfilter_sdk` is the official Elixir SDK skeleton for the HairFilter API.
It provides a clean, publish-ready foundation for the official client while
the platform is still in MVP.

The package is intentionally small and opinionated:

- typed public structs for clients, responses, and errors
- a thin request layer built on `Req`
- JSON request and response handling via `Jason`
- package metadata prepared for Hex publishing
- docs and examples that can evolve alongside the API

## Installation

Add the dependency to your `mix.exs`:

```elixir
def deps do
  [
    {:hairfilter_sdk, "~> 0.1.0"}
  ]
end
```

Then fetch dependencies:

```bash
mix deps.get
```

## Quick Start

```elixir
client =
  HairfilterSDK.new(
    api_key: System.fetch_env!("HAIRFILTER_API_KEY")
  )

{:ok, response} =
  HairfilterSDK.get(client, "/v1/health")

response.status
response.body
```

## Configuration

The client accepts these options:

- `:api_key` - API key used for authenticated requests
- `:base_url` - defaults to `https://hairfilter.net`
- `:api_key_header` - defaults to `"authorization"`
- `:api_key_prefix` - defaults to `"Bearer"`
- `:headers` - additional request headers
- `:receive_timeout` - request timeout in milliseconds
- `:req_options` - raw `Req` options merged into each request

Example:

```elixir
client =
  HairfilterSDK.new(
    api_key: System.fetch_env!("HAIRFILTER_API_KEY"),
    base_url: "https://hairfilter.net",
    headers: [{"x-sdk-name", "hairfilter-elixir"}],
    receive_timeout: 15_000
  )
```

## Request Examples

GET request:

```elixir
HairfilterSDK.get(client, "/v1/images", params: %{limit: 10})
```

POST request:

```elixir
HairfilterSDK.post(client, "/v1/jobs", body: %{image_url: "https://example.com/me.png"})
```

Generic request:

```elixir
HairfilterSDK.request(client, :patch, "/v1/profile", body: %{display_name: "Taylor"})
```

## Publishing Notes

Before the first public release, update these items:

- replace the `@source_url_placeholder` in `mix.exs` with the public repository URL
- add real endpoint examples once the API is finalized
- expand tests around authentication, pagination, and domain objects
- publish generated docs with `mix docs`

## Official Links

- Homepage: [https://hairfilter.net/](https://hairfilter.net/)
- Official documentation and support: [https://hairfilter.net/](https://hairfilter.net/)

## License

MIT