defmodule ApiBrasil.Messaging.SMS do
  @moduledoc """
  API de SMS (device-based): `POST /sms/{action}`.

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

  Campos aceitos por `send/3` e `send_with_credits/3`: `number`, `message`,
  `operator` (padrão do gateway: `claro`), `user_reply` e `webhook_url`.

      # pelo device
      {:ok, _envelope} =
        ApiBrasil.Messaging.SMS.send(client, %{
          "number" => "5511999999999",
          "message" => "Seu código é 1234"
        })

      # debitando créditos da conta, sem DeviceToken
      {:ok, _envelope} =
        ApiBrasil.Messaging.SMS.send_with_credits(client, %{
          "number" => "5511999999999",
          "message" => "Seu código é 1234"
        })
  """

  use ApiBrasil.Core.Service, device: "sms"

  # `send/2`, gerada pelos valores padrão de `send/3`, tem a mesma assinatura
  # de `Kernel.send/2`; sem esta linha as duas entram em conflito.
  import Kernel, except: [send: 2]

  action(:send, "send", "Envia um SMS pelo device: `POST /sms/send`.")

  @doc """
  Envia um SMS debitando créditos da conta, sem `DeviceToken`:
  `POST /sms/send/credits`.
  """
  @spec send_with_credits(Client.t(), term(), keyword()) ::
          {:ok, CreditResponse.t()} | {:error, Error.t()}
  def send_with_credits(client, body \\ nil, opts \\ []) do
    Service.credit_post(client, "sms/send/credits", body, opts)
  end

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