apibrasil

# Changelog

## 0.0.1 — 2026-07-28

Primeira versão da SDK Elixir, cobrindo toda a plataforma APIBrasil — mesma
arquitetura e paridade de rotas com as SDKs de Go, Node.js, PHP, Ruby, Rust e
Dart/Flutter.

### Novidades

- **Cliente central `ApiBrasil`** (`new/1`, `from_env/0`, `login/2`) devolvendo
  um `ApiBrasil.Client` imutável, com um módulo por produto:
  `ApiBrasil.Messaging.WhatsApp`, `ApiBrasil.Messaging.Evolution`,
  `ApiBrasil.Messaging.WhatsMeow`, `ApiBrasil.Messaging.SMS`,
  `ApiBrasil.Data.Dados`, `ApiBrasil.Data.Vehicles`, `ApiBrasil.Data.Fipe`,
  `ApiBrasil.Data.Correios`, `ApiBrasil.Data.Cep`, `ApiBrasil.Data.Geolocation`,
  `ApiBrasil.Data.Geomatrix`, `ApiBrasil.Data.Recognize`, `ApiBrasil.Data.Ddd`,
  `ApiBrasil.Data.Holidays`, `ApiBrasil.Data.Translate`,
  `ApiBrasil.Data.Weather`, `ApiBrasil.Data.Loterias`,
  `ApiBrasil.Data.DatabaseIp`, `ApiBrasil.Data.Consulta` (créditos),
  `ApiBrasil.Data.Ura`, `ApiBrasil.Data.ChipVirtual`, `ApiBrasil.Data.Bulk`,
  `ApiBrasil.Platform.Auth` (login/2FA), `ApiBrasil.Platform.Devices`,
  `ApiBrasil.Platform.Catalog`, `ApiBrasil.Platform.Account`,
  `ApiBrasil.Platform.Payments` (PIX/boleto/cartão),
  `ApiBrasil.Platform.IpWhitelist`, `ApiBrasil.Platform.BearerRateLimit` e
  `ApiBrasil.Platform.Reports`.
- **Contrato uniforme**: toda função devolve `{:ok, resultado}` ou
  `{:error, %ApiBrasil.Core.Error{}}` e tem a variante `!`, que devolve o
  resultado direto e levanta em caso de falha. Todas aceitam uma keyword list
  final com as opções da requisição.
- **DSL de serviços** (`use ApiBrasil.Core.Service`): as rotas device-based,
  as consultas por crédito e as rotas da plataforma são declaradas em uma
  tabela (`action/3`, `credit/3`, `route_get/3`, `route_post/3`, `route_put/3`,
  `route_delete/3`, `route_empty/4`), que gera as duas variantes de cada
  função com `@doc` e `@spec`.
- **Zero dependências obrigatórias**: o transporte padrão é o `:httpc` do
  Erlang/OTP (`ApiBrasil.Core.Transport.Httpc`, com `verify_peer` e checagem
  de hostname) e o JSON usa o `JSON` nativo (Elixir 1.18+) ou o `:json`
  (OTP 27+). `Jason`, `Finch` e `CAStore` são usados automaticamente quando
  estiverem no projeto.
- **Transporte plugável** (`ApiBrasil.Core.Transport`): um módulo com o
  behaviour, uma tupla `{módulo, opções}` ou uma função de aridade 1 — o
  atalho para testes sem rede.
- **Retry com backoff exponencial e jitter** (`ApiBrasil.Core.Retry`; padrão:
  HTTP 429 e falhas de conexão; nunca timeouts nem erros de negócio), com
  suporte a `Retry-After` em segundos ou data HTTP.
- **Hooks de observabilidade** (`ApiBrasil.Core.Hooks`): `:request`,
  `:response` e `:retry`, via mapa/keyword de funções ou módulo com o
  behaviour — falhas dentro de um hook nunca derrubam a requisição.
- **Erros com categoria** em `%ApiBrasil.Core.Error{kind: ...}` (`:validation`,
  `:authentication`, `:insufficient_balance`, `:permission`, `:not_found`,
  `:rate_limit`, `:server`, `:network`, `:timeout`, `:api`), com predicados
  (`insufficient_balance?/1`, `rate_limit?/1`, `network?/1`...), `:status`,
  `:code`, `:response`, `:retry_after` e `:reason` preservando a causa. É uma
  exceção: as variantes `!` levantam o próprio struct.
- **Envelopes com acessores**: `ApiBrasil.Core.DeviceResponse` e
  `ApiBrasil.Core.CreditResponse` implementam `Access` — `error?/1`,
  `message/1`, `response/1`/`data/1`, `balance/1`, `api_limit/1`, `to_map/1` e
  acesso direto por chave (`envelope["response"]`).
- **Body flexível**: mapas, keyword lists, `nil` e o builder
  `ApiBrasil.Consulta` (com `tipo`, `homolog`, `lite`, `agrupados`, `extra` e
  os campos do produto) são aceitos por qualquer função de serviço.
- **Opções por escopo**: `ApiBrasil.with_options/2` fixa opções no cliente e
  toda chamada aceita `:query`, `:headers`, `:bearer_token`, `:device_token`,
  `:secret_key`, `:timeout` e `:response_type`.
- **Configuração** por `ApiBrasil.Core.Config`, por `config :apibrasil, ...`
  (inclusive `{:system, "VAR"}`) e pelas variáveis de ambiente
  `APIBRASIL_BEARER_TOKEN`, `APIBRASIL_DEVICE_TOKEN`, `APIBRASIL_SECRET_KEY` e
  `APIBRASIL_BASE_URL` — credenciais vazias contam como ausentes.
- **Catálogo gerado** (`mix apibrasil.codegen`) em
  `ApiBrasil.Generated.Catalog`: actions de WhatsApp/Evolution/WhatsMeow e os
  `tipo` de consulta com seus campos, por `service_actions/1`,
  `evolution_paths/0`, `consulta_servicos/0` e `consulta_tipos/0`.
- **Interface legada** em `ApiBrasil.Legacy` (`new/1`, `request/4`,
  `whatsapp/3`, `sms/3`, `cpf/3`, `cnpj/3` e as variantes `!`), mantendo o
  contrato das primeiras SDKs (`credentials`/`body`/`action` em uma string
  JSON) — inclusive devolver erros da API decodificados em `{:ok, mapa}` em
  vez de `{:error, ...}`.
- **Documentação em português** em todos os módulos, publicada no HexDocs, e
  exemplos executáveis em `examples/` (`elixir examples/basico.exs`).
- **Testes** com transporte falso (rotas, headers, query, envelopes, erros,
  retry, transporte, catálogo e interface legada) — a suíte não faz nenhuma
  chamada de rede.
- CI no GitHub Actions em matriz Elixir/OTP (1.15/26 a 1.18/27) com
  `mix format --check-formatted`, `mix compile --warnings-as-errors`,
  `mix test`, `mix credo --strict` e `mix hex.build`.

### Requisitos

- **Elixir >= 1.14** e **OTP >= 25** (`:public_key.cacerts_get/0`, usada na
  verificação de TLS do transporte padrão, exige OTP 25).
- Em Elixir < 1.18 / OTP < 27, adicione `{:jason, "~> 1.4"}` ao projeto para
  o codec JSON.