# Cobertura do SDK Elixir

A versão `0.1.0-alpha.1` oferece **16 recursos principais, 30 módulos de recursos e 151 operações**. Conveniências de argumentos opcionais e funções que retornam módulos subordinados não representam operações adicionais. O pacote usa o identificador `:mailcore`. Requer Elixir 1.16+ e Erlang/OTP 26+; a matriz usa 1.16/26, 1.17/27, 1.18/27, 1.19/28 e 1.20/29.

As funções usam nomes em `snake_case` e recebem o cliente como primeiro argumento. O corpo mantém os campos em português do contrato HTTP. Identificadores são codificados como um único segmento de URI, preservando o prefixo da API.

## Operações

Todos os módulos abaixo pertencem a `Mailcore.Recursos`. Operações HTTP retornam `{:ok, %Mailcore.Resposta{}}` ou `{:error, %Mailcore.Erro{}}`; opções são uma keyword list no último argumento.

| Módulo | Funções | Operações |
| --- | --- | ---: |
| `Emails` | `enviar`, `listar`, `obter`, `reagendar`, `cancelar`, `obter_por_idempotencia`, `eventos`, `baixar_anexo` | 8 |
| `Lotes` | `enviar`, `obter_por_idempotencia` | 2 |
| `Dominios` | `criar`, `listar`, `obter`, `atualizar`, `remover`, `registros_dns`, `verificar` | 7 |
| `ChavesApi` | `criar`, `listar`, `renomear`, `revogar` | 4 |
| `SegmentosContato` | `listar`, `adicionar`, `remover` | 3 |
| `TopicosContato` | `listar`, `atualizar` | 2 |
| `ImportacoesContatos` | `prever`, `criar`, `obter` | 3 |
| `ExportacoesContatos` | `criar`, `listar`, `obter`, `baixar`, `baixar_fluxo` | 5 |
| `Contatos` | `criar`, `listar`, `obter`, `atualizar`, `remover`, `adicionar_em_lote`, `alterar_em_lote` | 7 |
| `Segmentos` | `criar`, `listar`, `obter`, `atualizar`, `remover` | 5 |
| `Topicos` | `criar`, `listar`, `obter`, `atualizar`, `remover` | 5 |
| `PropriedadesContatos` | `criar`, `listar`, `obter`, `atualizar`, `remover` | 5 |
| `VersoesModelo` | `listar`, `obter`, `restaurar`, `prever` | 4 |
| `PastasModelo` | `listar`, `criar`, `atualizar`, `remover` | 4 |
| `Modelos` | `criar`, `listar`, `obter`, `atualizar`, `remover`, `prever`, `obter_previa`, `testar`, `publicar`, `duplicar` | 10 |
| `EventosWebhook` | `listar`, `obter`, `listar_tentativas`, `reenviar` | 4 |
| `Webhooks` | `criar`, `listar`, `obter`, `atualizar`, `remover` | 5 |
| `Campanhas` | `criar`, `listar`, `obter`, `atualizar`, `remover`, `duplicar`, `revisar`, `enviar`, `cancelar`, `prever`, `testar`, `ler_previa`, `obter_metricas`, `listar_destinatarios`, `listar_links_clicados` | 15 |
| `ExecucoesAutomacoes` | `listar`, `obter` | 2 |
| `Automacoes` | `criar`, `listar`, `obter`, `atualizar`, `remover`, `duplicar`, `parar` | 7 |
| `Eventos` | `criar`, `listar`, `obter`, `atualizar`, `remover`, `enviar` | 6 |
| `Recebimento` | `listar`, `obter`, `listar_anexos`, `obter_anexo`, `baixar_original`, `baixar_anexo`, `baixar_original_fluxo`, `baixar_anexo_fluxo` | 8 |
| `EmailsCaixa` | `listar`, `obter`, `responder`, `encaminhar` | 4 |
| `EtiquetasConversaCaixa` | `adicionar`, `substituir`, `remover` | 3 |
| `ConversasCaixa` | `listar`, `buscar`, `obter`, `atualizar`, `remover` | 5 |
| `EtiquetasCaixa` | `listar`, `obter`, `criar`, `atualizar`, `remover` | 5 |
| `RascunhosCaixa` | `listar`, `obter`, `criar`, `atualizar`, `remover`, `enviar` | 6 |
| `Caixas` | `criar`, `listar`, `obter`, `atualizar`, `remover` | 5 |
| `ConcessoesCli` | `listar`, `revogar` | 2 |
| `CliMailcore` | Agrega `ConcessoesCli`. | 0 |
| **Total** | **151 operações** | **151** |

Os módulos subordinados usam a mesma configuração do cliente. Helpers como `Contatos.exportacoes/0` apenas retornam o módulo; não fazem requisições nem criam processos. `CliMailcore` é um agregador e suas duas operações estão em `ConcessoesCli`.

## Pedidos e respostas

- Pedidos JSON aceitam mapas com as propriedades do contrato HTTP. Envio de lotes exige lista na raiz. `nil` explícito na raiz não substitui mapa; funções com corpo opcional usam `%{}` como padrão.
- Campos `nil` e `false` são preservados dentro dos pedidos. Filtros `nil` são omitidos da query; `false` é enviado como `false`. O SDK não cria átomos a partir das chaves de uma resposta.
- Respostas conservam bytes originais, status, cabeçalhos e quantidade lida. `Mailcore.Resposta.json/1` interpreta o binário sob decisão do chamador. Respostas sem conteúdo conservam `dados: ""`.
- Inteiros decodificados são bignums, até 1.024 dígitos pelo limite do Jason; decimais são `%Decimal{}`. Os bytes originais permanecem disponíveis e a configuração global do parser da aplicação é preservada.
- A paginação é explícita: cada operação consulta uma página e mantém o envelope e os cursores do recurso. Não há varredura automática de todas as páginas.

## Contratos de negócio

O servidor valida permissões, escopos, formatos, revisões e estados. Envio direto aceita composição e anexos Base64/CID. Envio individual por modelo aceita anexos Base64 sem CID e não combina com HTML/texto, Cc/Cco, cabeçalhos ou nome de exibição no remetente. Lotes contêm de 1 a 100 mensagens e não aceitam Cc/Cco, cabeçalhos, nome de exibição no remetente ou anexos. A aceitação de uma intenção não comprova entrega SMTP.

Atualizações e ações em modelos, campanhas, automações, caixas e rascunhos mantêm os campos de revisão exigidos pela API. Um conflito HTTP 409 é devolvido à aplicação; a biblioteca não inventa revisões nem refaz a edição.

Importações recebem CSV UTF-8 no pedido JSON. O limite de negócio é 8 MiB; limites de serialização não ampliam os limites específicos de cada endpoint. A chave secreta de API é devolvida somente na criação. Concessões CLI permitem consulta e revogação, sem iniciar autenticação interativa ou renovar credenciais. O SDK não utiliza rotas privadas de sessão ou dashboard.

## Conteúdo recebido e fluxo

`Recebimento` consulta mensagens, anexos e original MIME por rotas autenticadas. `baixar_original_fluxo`, `baixar_anexo_fluxo` e `ExportacoesContatos.baixar_fluxo` entregam blocos ao consumidor. O consumidor recebe binário e retorna `:ok` ou `{:error, %Mailcore.Erro{}}`; a próxima leitura depende do retorno. Sucesso mantém `dados: ""` e informa `total_bytes`.

Downloads comuns acumulam a resposta em memória. Ajuste o limite de resposta e o prazo por operação conforme o orçamento da aplicação. Detalhes HTML com `data_uri` podem crescer pela expansão dos anexos; consulte com `formato_html: "cid"` quando apropriado.

URLs temporárias em metadados são capacidades sensíveis. O SDK não as segue automaticamente nem envia Bearer para destinos extraídos das respostas. A retenção e disponibilidade dos conteúdos pertencem ao contrato do servidor.

## Transporte e ciclo de vida

A execução padrão usa `Req.Request` de baixo nível com `Req.Finch`, TLS verificado e pool HTTP/1.1 compartilhado. As opções são independentes de `Req.default_options` da aplicação, sem passos automáticos de retentativa, redirecionamento, descompressão ou decodificação, e sem manutenção de cookies. Clientes Req injetados mantêm as políticas da aplicação.

O prazo total inclui preparação, credenciais, rede, leitura e consumidor. O controle de prazo encerra a tarefa de transporte ao expirar; um monitor supervisionado encerra essa tarefa quando o processo chamador termina. Callbacks executam nessa tarefa e precisam tratar seus efeitos externos e arquivos parciais.

Cabeçalhos e comprimento declarado são validados quando Req os disponibiliza ao SDK. Uma interrupção de I/O anterior pode resultar em falha de rede sem status. Os limites configurados continuam aplicados durante a leitura dos bytes disponíveis.

## Verificação

Os 151 contratos têm casos independentes da especificação do gerador. Cada caso chama uma função pública sobre HTTP local real e verifica método, caminho codificado, query, corpo, opções, resposta e variantes de download. Os dados são sintéticos. Esses testes não constituem implantação, entrega SMTP ou medição de desempenho em produção.

As fontes dos recursos são estáticas. `python3 scripts/gerar_recursos.py --verificar` confere a correspondência com a especificação local, sem depender de outro projeto. O gerador não participa da execução do SDK.