# `Humaans`
[🔗](https://github.com/sgerrand/ex_humaans/blob/v0.4.2/lib/humaans.ex#L1)

A HTTP client for the Humaans API.

This library provides an interface to the Humaans API, allowing you to manage
people, companies, bank accounts, compensations, timesheet entries, and more.
It follows a modular design where the main `Humaans` module serves as the
entry point for creating clients, while specific resource modules handle
operations for each resource type.

[Humaans API Documentation](https://docs.humaans.io/api/)

## Architecture

The library follows a layered architecture:
- `Humaans` - Main module that creates configured client instances
- Resource modules (`People`, `Companies`, etc.) - Handle operations specific to each resource type
- HTTP client - Abstracts the HTTP communication details in a configurable manner

## Configuration Options

When creating a client with `Humaans.new/1`, you can configure:

* `:access_token` - Your Humaans API access token (required)
* `:base_url` - The base URL for API requests (defaults to "https://app.humaans.io/api")
* `:http_client` - The HTTP client module to use (defaults to `Humaans.HTTPClient.Req`)

## Examples

    # Create a default client
    client = Humaans.new(access_token: "some-access-token")

    # Create a client with custom base URL
    client = Humaans.new(
      access_token: "some-access-token",
      base_url: "https://custom-instance.humaans.io/api"
    )

    # Create a client with custom HTTP client
    client = Humaans.new(
      access_token: "some-access-token",
      http_client: MyCustomHTTPClient
    )

    # Make API calls
    {:ok, people} = Humaans.People.list(client)
    {:ok, person} = Humaans.People.retrieve(client, "123")
    {:ok, companies} = Humaans.Companies.list(client)

    # Create a new person
    person_params = %{
      "firstName" => "Jane",
      "lastName" => "Doe",
      "email" => "jane.doe@example.com"
    }
    {:ok, new_person} = Humaans.People.create(client, person_params)

# `t`

```elixir
@type t() :: %Humaans{
  access_token: String.t(),
  base_url: String.t(),
  http_client: module()
}
```

# `bank_accounts`

Access the Bank Accounts API.

Returns the module that contains functions for working with bank account resources.

# `companies`

Access the Companies API.

Returns the module that contains functions for working with company resources.

# `compensation_types`

Access the Compensation Types API.

Returns the module that contains functions for working with compensation type resources.

# `compensations`

Access the Compensations API.

Returns the module that contains functions for working with compensation resources.

# `new`

```elixir
@spec new(opts :: keyword()) :: map()
```

Creates a new client with the given access token and optional parameters.

## Options
  * `:access_token` - The access token to use for authentication (required)
  * `:base_url` - The base URL for API requests (defaults to https://app.humaans.io/api)

## Examples
    iex> client = Humaans.new(access_token: "some-access-token")
    iex> is_map(client)
    true

# `people`

Access the People API.

Returns the module that contains functions for working with people resources.

# `timesheet_entries`

Access the Timesheet Entries API.

Returns the module that contains functions for working with timesheet entry resources.

# `timesheet_submissions`

Access the Timesheet Submissions API.

Returns the module that contains functions for working with timesheet submission resources.

---

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