@spec build_query_string(map() | keyword() | nil) :: String.t()

Monta a query string a partir de um mapa/keyword, ignorando valores nulos.

As chaves saem ordenadas, o que torna a URL determinística. Devolve "" quando não há nada a enviar.

iex> ApiBrasil.Core.Utils.build_query_string(%{"search" => "cep", "page" => 2})
"?page=2&search=cep"

@spec encode_path(String.t()) :: String.t()

Codifica um segmento de caminho de URL (mantém /).

@spec join_url(String.t(), String.t()) :: String.t()

Junta a base da API com o caminho, sem barras duplicadas.

iex> ApiBrasil.Core.Utils.join_url("https://gateway.apibrasil.io/api/v2/", "/whatsapp/sendText")
"https://gateway.apibrasil.io/api/v2/whatsapp/sendText"

@spec merge_headers(map(), map()) :: map()

Mescla dois conjuntos de headers sem diferenciar maiúsculas de minúsculas — os de override vencem, inclusive quando só a caixa difere.

@spec normalize_headers(map() | keyword() | nil) :: map()

Normaliza headers para um mapa %{"nome" => "valor"}, preservando o nome original mas removendo duplicatas por comparação sem diferenciar caixa.

@spec presence(term()) :: term()

Devolve nil para strings vazias — credenciais vazias contam como ausentes.

@spec stringify_keys(map()) :: map()

Converte as chaves de um mapa (um nível) em strings — aceita átomos e strings misturados.

@spec to_body(term()) :: map() | list() | nil

Normaliza o corpo de uma requisição.

Aceita mapas, keyword lists, structs ApiBrasil.Consulta, nil e [] — devolve um mapa ou nil quando não há corpo.

@spec to_json_object(term()) :: map()

Normaliza a resposta em um mapa JSON.

Respostas vazias viram %{}; respostas que não são objetos (listas, texto) são embrulhadas em %{"data" => ...}.