defmodule ApiBrasil.Messaging.Evolution do
  @moduledoc """
  Evolution API (device-based): `POST /evolution/{controller}/{action}`.

  Exige `Authorization: Bearer` + header `DeviceToken`.

      # controller + action
      {:ok, _envelope} =
        ApiBrasil.Messaging.Evolution.request(client, "message", "sendText", %{
          "number" => "5511999999999",
          "text" => "Olá!"
        })

      # caminho completo do catálogo
      {:ok, _envelope} = ApiBrasil.Messaging.Evolution.call(client, "instance/create", body)

      # a mesma chamada, por fila
      {:ok, _envelope} =
        ApiBrasil.Messaging.Evolution.queue(client, "message", "sendText", body)

  Exemplos de `controller/action`: `instance/create`, `message/sendText`. Os
  caminhos documentados estão em `ApiBrasil.Generated.Catalog.evolution_paths/0`
  e em <https://doc.apibrasil.io>.
  """

  use ApiBrasil.Core.Service

  @doc """
  Executa um caminho completo do catálogo: `POST /evolution/{path}`.

      ApiBrasil.Messaging.Evolution.call(client, "chat/findChats", body)
  """
  @spec call(Client.t(), String.t(), term(), keyword()) ::
          {:ok, DeviceResponse.t()} | {:error, Error.t()}
  def call(client, path, body \\ nil, opts \\ []) do
    full_path = "evolution/" <> String.trim(to_string(path), "/")

    with {:ok, json} <- Service.post(client, full_path, body, opts) do
      {:ok, DeviceResponse.new(json)}
    end
  end

  @doc "Como `call/4`, mas levanta `ApiBrasil.Core.Error` em caso de falha."
  @spec call!(Client.t(), String.t(), term(), keyword()) :: DeviceResponse.t()
  def call!(client, path, body \\ nil, opts \\ []) do
    Service.unwrap!(call(client, path, body, opts))
  end

  @doc "Executa `POST /evolution/{controller}/{action}`."
  @spec request(Client.t(), String.t(), String.t(), term(), keyword()) ::
          {:ok, DeviceResponse.t()} | {:error, Error.t()}
  def request(client, controller, action_name, body \\ nil, opts \\ []) do
    call(client, "#{controller}/#{action_name}", body, opts)
  end

  @doc "Como `request/5`, mas levanta `ApiBrasil.Core.Error` em caso de falha."
  @spec request!(Client.t(), String.t(), String.t(), term(), keyword()) :: DeviceResponse.t()
  def request!(client, controller, action_name, body \\ nil, opts \\ []) do
    Service.unwrap!(request(client, controller, action_name, body, opts))
  end

  @doc """
  Executa a mesma chamada de forma assíncrona, por fila:
  `POST /evolution/{controller}/{action}/queue`.
  """
  @spec queue(Client.t(), String.t(), String.t(), term(), keyword()) ::
          {:ok, DeviceResponse.t()} | {:error, Error.t()}
  def queue(client, controller, action_name, body \\ nil, opts \\ []) do
    call(client, "#{controller}/#{action_name}/queue", body, opts)
  end

  @doc "Como `queue/5`, mas levanta `ApiBrasil.Core.Error` em caso de falha."
  @spec queue!(Client.t(), String.t(), String.t(), term(), keyword()) :: DeviceResponse.t()
  def queue!(client, controller, action_name, body \\ nil, opts \\ []) do
    Service.unwrap!(queue(client, controller, action_name, body, opts))
  end
end