agentmail

defmodule Agentmail do
  @moduledoc """
  Elixir client for the [AgentMail API](https://docs.agentmail.to/api-reference).

  AgentMail provides email infrastructure for AI agents — inboxes, sending,
  receiving via webhooks, and threading.

  ## Usage

      # Create a client
      client = Agentmail.client("am_your_api_key")

      # Create an inbox
      {:ok, inbox} = Agentmail.Inboxes.create(client, %{
        username: "support",
        display_name: "My Agent"
      })

      # Send an email
      {:ok, result} = Agentmail.Messages.send(client, inbox["inbox_id"], %{
        to: ["user@example.com"],
        subject: "Hello!",
        text: "Hi from my agent."
      })

  ## Configuration

  You can also configure a default API key via application config:

      config :agentmail,
        api_key: "am_..."

  Then use `Agentmail.client()` without arguments.
  """

  defstruct [:api_key, :base_url]

  @type t :: %__MODULE__{
          api_key: String.t(),
          base_url: String.t()
        }

  @default_base_url "https://api.agentmail.to/v0"

  @doc """
  Creates a new AgentMail client.

  ## Options

    * `:api_key` - AgentMail API key (prefix `am_`). Falls back to
      application config `:agentmail, :api_key` or `AGENTMAIL_API_KEY` env var.
    * `:base_url` - API base URL. Defaults to `#{@default_base_url}`.
      Use `https://api.agentmail.eu/v0` for the EU region.
  """
  @spec client(String.t() | keyword()) :: t()
  def client(api_key_or_opts \\ [])

  def client(api_key) when is_binary(api_key) do
    %__MODULE__{api_key: api_key, base_url: @default_base_url}
  end

  def client(opts) when is_list(opts) do
    api_key =
      Keyword.get(opts, :api_key) ||
        Application.get_env(:agentmail, :api_key) ||
        System.get_env("AGENTMAIL_API_KEY") ||
        raise ArgumentError, "AgentMail API key is required"

    base_url = Keyword.get(opts, :base_url, @default_base_url)

    %__MODULE__{api_key: api_key, base_url: base_url}
  end
end