amazon_creators_api

defmodule AmazonCreatorsAPI.HTTPClient do
  @moduledoc """
  Behaviour for HTTP client adapters.

  This module defines the contract that all HTTP client implementations must follow.
  It provides a pluggable interface for making HTTP requests, enabling easy mocking
  and testing without relying on external mocking libraries.

  ## Configuration

  The HTTP client can be configured in your application config:

      # config/config.exs
      config :amazon_creators_api,
        http_client: AmazonCreatorsAPI.HTTPClient.HTTPoison

  If not configured, it defaults to `AmazonCreatorsAPI.HTTPClient.HTTPoison`.

  ## Testing

  For testing, you can configure a mock implementation:

      # config/test.exs
      config :amazon_creators_api,
        http_client: AmazonCreatorsAPI.HTTPClientMock

  ## Custom Implementations

  To implement a custom HTTP client, create a module that implements this behaviour:

      defmodule MyApp.CustomHTTPClient do
        @behaviour AmazonCreatorsAPI.HTTPClient

        @impl true
        def post(url, body, headers) do
          # Your custom implementation
          {:ok, %{status_code: 200, body: "{}"}}
        end
      end
  """

  @type url :: String.t()
  @type body :: String.t()
  @type headers :: [{String.t(), String.t()}]
  @type status_code :: integer()
  @type response_body :: String.t()
  @type reason :: atom() | term()

  @doc """
  Sends a POST request to the given URL with the specified body and headers.

  ## Parameters

    - `url` - The URL to send the request to
    - `body` - The request body as a string
    - `headers` - A list of tuples containing header name and value pairs

  ## Returns

    - `{:ok, %{status_code: integer(), body: String.t()}}` on successful request
    - `{:error, %{reason: term()}}` on failure

  ## Examples

      iex> post("https://example.com", "data", [{"Content-Type", "application/json"}])
      {:ok, %{status_code: 200, body: "response"}}

      iex> post("https://invalid", "", [])
      {:error, %{reason: :nxdomain}}
  """
  @callback post(url, body, headers) ::
              {:ok, %{status_code: status_code(), body: response_body()}}
              | {:error, %{reason: reason()}}

  @doc """
  Returns the configured HTTP client module.

  Defaults to `AmazonCreatorsAPI.HTTPClient.HTTPoison` if not configured.
  """
  @spec client() :: module()
  def client do
    Application.get_env(
      :amazon_creators_api,
      :http_client,
      AmazonCreatorsAPI.HTTPClient.HTTPoison
    )
  end

  @doc """
  Makes a POST request using the configured HTTP client.

  This is a convenience wrapper around the configured HTTP client's `post/3` function.

  ## Parameters

    - `url` - The URL to send the request to
    - `body` - The request body as a string
    - `headers` - A list of tuples containing header name and value pairs

  ## Returns

    - `{:ok, %{status_code: integer(), body: String.t()}}` on successful request
    - `{:error, %{reason: term()}}` on failure

  ## Examples

      iex> AmazonCreatorsAPI.HTTPClient.post("https://example.com", "data", [])
      {:ok, %{status_code: 200, body: "response"}}
  """
  @spec post(url, body, headers) ::
          {:ok, %{status_code: status_code(), body: response_body()}}
          | {:error, %{reason: reason()}}
  def post(url, body, headers) do
    client().post(url, body, headers)
  end
end