mailcore 0.1.0.alpha.1

data/docs/rails.md

@@ -0,0 +1,185 @@
+# Rails: envio e recebimento
+
+O gem `mailcore` integra o cliente HTTP com Action Mailer e Action Mailbox. Rails
+e Mail são dependências opcionais: o cliente Ruby funciona sem esses componentes.
+A combinação verificada é Ruby 3.4, Rails/Action Mailer/Action Mailbox `8.1.3.1`,
+Mail `2.9.1` e JSON `>= 2.7, < 3`. Consulte o relatório geral do SDK para as outras
+versões Ruby efetivamente exercitadas. Esta faixa de JSON preserva a integração
+com o decodificador do Active Support dessa versão Rails.
+
+## Action Mailer
+
+Configure a chave em runtime. O bloco permite um `Proc`, resolvido ao fazer cada
+pedido, para carregar a credencial pelo mecanismo de segredos da aplicação:
+
+```ruby
+# config/initializers/mailcore.rb
+Mailcore.configurar do |configuracao|
+  configuracao.chave_api = -> { ENV.fetch('MAILCORE_API_KEY') }
+end
+```
+
+Ative o método de entrega:
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :mailcore
+```
+
+O carregamento padrão do Rails registra esse método pelo Railtie. Se o cliente
+Ruby foi carregado antes do framework, carregue explicitamente
+`require 'mailcore/railtie'` antes de inicializar a aplicação.
+
+Os mailers e templates continuam sendo os do Rails:
+
+```ruby
+class AvisoMailer < ApplicationMailer
+  default from: 'Equipe <avisos@seu-dominio.example>'
+
+  def confirmacao
+    headers['mailcore_opcoes'] = {
+      chave_idempotencia: "pedido-#{params.fetch(:pedido_id)}-confirmacao",
+      tags: { tipo: 'confirmacao' }
+    }
+    mail(to: params.fetch(:destinatario), subject: 'Pedido confirmado')
+  end
+end
+```
+
+Use `deliver_now` para aguardar a aceitação HTTP ou `deliver_later` para entregar a
+execução ao Active Job configurado pela aplicação. O gem não cria uma fila. A
+aceitação da API não comprova entrega SMTP.
+
+A conversão inclui remetente com nome, destinatários, cópias, cópias ocultas, um
+endereço de resposta, texto, HTML, multipart, cabeçalhos personalizados e anexos.
+Anexos mantêm os bytes em base64 estrito, o tipo MIME e o Content-ID quando inline.
+Cabeçalhos estruturais e reservados pelo Mailcore são filtrados; os demais seguem
+as validações da API.
+
+`mailcore_opcoes` aceita `chave_idempotencia`, `tags` e `agendada_em`. Esta última
+usa o formato ISO 8601 com fuso aceito pela API. Essas opções são metadados do
+adaptador e não se tornam cabeçalhos do email. Uma chave estável identifica a mesma
+intenção de negócio, inclusive quando a aplicação decide repetir um job. O gem não
+repete um envio automaticamente após falhas ambíguas.
+
+Para uma configuração específica, use `config.action_mailer.mailcore_settings` ou
+`delivery_method_options` do Rails. São aceitas as opções do cliente
+`chave_api`, `url_base`, `tempo_limite`, `tempo_conexao`, `certificado_ca` e
+`limite_resposta_bytes`, além de `chave_idempotencia`. A opção `cliente` permite
+fornecer uma instância isolada já configurada; ela prevalece sobre as demais opções
+de conexão. Configure cada organização com seu próprio cliente, sem trocar a
+configuração global durante pedidos concorrentes.
+
+O identificador retornado pela API é colocado no `message_id` do objeto Mail
+somente após sucesso. Erros do cliente são propagados para o mecanismo normal de
+falhas do Rails, sem substituir o identificador anterior.
+
+## Action Mailbox
+
+A aplicação precisa ter Action Mailbox, Active Record, Active Storage e Active
+Job configurados. Faça a instalação e as migrações próprias do Rails no ambiente
+da aplicação. O gem não altera o banco nem escolhe armazenamento ou filas.
+
+Carregue o ingress e habilite-o:
+
+```ruby
+# config/application.rb, depois de carregar os componentes Rails
+require 'mailcore/engine'
+
+# config/environments/production.rb
+config.action_mailbox.ingress = :mailcore
+```
+
+Cadastre no Mailcore um webhook do evento `email.received` apontando para:
+
+```text
+https://sua-aplicacao.example/rails/action_mailbox/mailcore/inbound_emails
+```
+
+Guarde o segredo de assinatura nas credenciais criptografadas do Rails:
+
+```yaml
+action_mailbox:
+  mailcore_segredo: segredo_fornecido_pelo_webhook
+```
+
+Como alternativa, configure `Mailcore.configuracao.segredo_webhook` pelo bloco
+`Mailcore.configurar`; o padrão consulta `MAILCORE_WEBHOOK_SECRET`. A credencial
+Rails tem precedência. Configure também uma chave de API com permissão para ler
+o original recebido. A chave da API e o segredo do webhook têm funções distintas.
+
+O endpoint aceita POST e exige assinatura válida do corpo bruto. Para corpos
+dentro do limite, sem o ingress habilitado responde `404`; assinatura inválida resulta em `401`; configuração do
+segredo ausente resulta em `503`. Eventos assinados de outros tipos recebem `204`
+sem buscar conteúdo. O evento de recebimento deve conter `data.email_id` e um
+array não vazio de endereços SMTP em `data.to`; envelope inválido resulta em
+`422`. Corpos acima de 256 KiB são recusados com `413`.
+
+Um middleware atua antes dos parsers e da instrumentação do Rails, somente no
+POST desse ingress. Ele lê no máximo 256 KiB mais um byte, inclusive quando a
+requisição não informa Content-Length. Um corpo permitido é recolocado em um
+StringIO com os mesmos bytes e tamanho correto; o controller verifica a assinatura
+desse conteúdo sem normalizar ou reserializar o JSON.
+
+Nessa rota, o corpo não é convertido automaticamente em parâmetros Rails antes
+da autenticação. Assim, os metadados de email não entram no campo de parâmetros
+da instrumentação, e o parser Rails não registra o corpo de um JSON malformado.
+Filtros adicionais para `data`, `_json` e credenciais são aplicados somente ao
+ambiente da requisição, preservando os filtros da aplicação. Outras rotas e
+métodos seguem seu processamento habitual.
+
+Após validar a assinatura, o ingress baixa o original pela rota autenticada do
+cliente, `recebimento.baixar_original`. Ele não visita URLs fornecidas no webhook
+e não reconstrói anexos a partir de metadados incompletos. A falha desse download
+retorna `503`, preservando a possibilidade de entrega posterior do webhook.
+Falhas internas do banco ou armazenamento seguem o tratamento de erros do Rails.
+
+Os bytes MIME do original são preservados. O ingress acrescenta cabeçalhos
+`X-Original-To` com os destinatários validados do envelope assinado. Isso permite
+que o roteamento normal do Action Mailbox também encontre cópias ocultas ou
+destinos de encaminhamento ausentes do cabeçalho `To`. Esses endereços fazem parte
+do conteúdo armazenado pela aplicação e devem receber a mesma proteção dos emails.
+
+```ruby
+class ApplicationMailbox < ActionMailbox::Base
+  routing /^suporte@/i => :suporte
+end
+```
+
+O Action Mailbox armazena a mensagem e encaminha o processamento pelo Active Job.
+A deduplicação nativa considera o par Message-ID e checksum do conteúdo. A
+repetição do mesmo original com Message-ID e o mesmo envelope recebe `204` sem
+criar uma nova mensagem. Quando o original não contém Message-ID, o Rails gera um
+identificador que inclui o hostname; não há garantia de deduplicação entre réplicas
+nesse caso. Isso não transforma o webhook em uma entrega exatamente uma vez: um
+original ou envelope diferente pode gerar outro registro, e os efeitos do mailbox
+da aplicação também precisam ser idempotentes. Os prazos de replay e retenção são
+responsabilidade do Mailcore e da aplicação, respectivamente.
+
+Configure armazenamento protegido, a retenção do Action Mailbox e filtros de logs
+na aplicação. Não registre o corpo bruto, endereços de destinatários, credenciais
+ou cabeçalhos de assinatura. Os adaptadores não registram esses valores.
+
+## Verificação local
+
+Os testes do adaptador usam Action Mailer e Mail reais para converter mensagens,
+com um cliente sintético no ponto de chamada HTTP. Os testes do ingress executam
+uma aplicação Rails em memória, com SQLite, Active Storage em pasta temporária e
+Active Job de teste. Eles verificam a assinatura por um vetor HMAC independente,
+persistência do original, destinatário oculto, replay, acesso recusado e falha de
+consulta. Esses testes não abrem portas, chamam produção ou enviam SMTP.
+
+Uma entrada virtual de 4 GiB, sem Content-Length, comprova que a aplicação Rails
+solicita uma única leitura de 262.145 bytes antes de recusar o corpo, sem alocar
+os 4 GiB. Outros casos verificam os bytes assinados com espaços e quebras de linha,
+a ausência de metadados de email nos parâmetros instrumentados, os filtros locais
+e a propagação de erros de I/O posteriores à leitura.
+
+Os arquivos `testes/testes_action_mailer.rb` e
+`testes/testes_action_mailbox.rb` são executados em processos separados, usando as
+dependências do ambiente Docker de testes do projeto. A configuração de banco e
+armazenamento desses testes é descartável e exclusiva do processo.
+
+Contratos Rails utilizados:
+[Action Mailer](https://guides.rubyonrails.org/action_mailer_basics.html) e
+[Action Mailbox](https://guides.rubyonrails.org/action_mailbox_basics.html).

data/docs/ruby-3.3.13-http-padrao.json

@@ -0,0 +1,22 @@
+{
+  "data_utc": "2026-11-14T14:01:36Z",
+  "ruby": "3.3.13",
+  "plataforma": "x86_64-linux",
+  "imagem": "sha256:e9e5e257301b57271cfde1fcbe2c800bd16b153dd9deb8e5c18aa637e7658b26",
+  "resultado": "aprovado",
+  "suites": [
+    {
+      "arquivo": "testes/testes_transporte.rb",
+      "aprovado": true,
+      "testes": 42,
+      "assercoes": 280,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    }
+  ],
+  "perfil": "net_http_padrao_do_ruby",
+  "net_http": "0.4.1",
+  "total_testes": 42,
+  "total_assercoes": 280
+}

data/docs/ruby-3.3.13.json

@@ -0,0 +1,66 @@
+{
+  "data_utc": "2026-11-14T14:01:29Z",
+  "ruby": "3.3.13",
+  "plataforma": "x86_64-linux",
+  "imagem": "sha256:e9e5e257301b57271cfde1fcbe2c800bd16b153dd9deb8e5c18aa637e7658b26",
+  "resultado": "aprovado",
+  "suites": [
+    {
+      "arquivo": "testes/testes_action_mailbox.rb",
+      "aprovado": true,
+      "testes": 13,
+      "assercoes": 67,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_action_mailer.rb",
+      "aprovado": true,
+      "testes": 9,
+      "assercoes": 37,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_core.rb",
+      "aprovado": true,
+      "testes": 5,
+      "assercoes": 66,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_recursos.rb",
+      "aprovado": true,
+      "testes": 156,
+      "assercoes": 513,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_sinatra.rb",
+      "aprovado": true,
+      "testes": 11,
+      "assercoes": 250,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_transporte.rb",
+      "aprovado": true,
+      "testes": 42,
+      "assercoes": 280,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    }
+  ],
+  "perfil": "dependencias_lockfile",
+  "total_testes": 236,
+  "total_assercoes": 1213
+}

data/docs/ruby-3.4.12-http-padrao.json

@@ -0,0 +1,22 @@
+{
+  "data_utc": "2026-11-14T14:01:46Z",
+  "ruby": "3.4.12",
+  "plataforma": "x86_64-linux",
+  "imagem": "sha256:92daa531a314ef9bef6bd11fcf8fab79f76f3b3a26191785198f1749c5c40989",
+  "resultado": "aprovado",
+  "suites": [
+    {
+      "arquivo": "testes/testes_transporte.rb",
+      "aprovado": true,
+      "testes": 42,
+      "assercoes": 280,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    }
+  ],
+  "perfil": "net_http_padrao_do_ruby",
+  "net_http": "0.6.0",
+  "total_testes": 42,
+  "total_assercoes": 280
+}

data/docs/ruby-3.4.12.json

@@ -0,0 +1,66 @@
+{
+  "data_utc": "2026-11-14T14:01:40Z",
+  "ruby": "3.4.12",
+  "plataforma": "x86_64-linux",
+  "imagem": "sha256:92daa531a314ef9bef6bd11fcf8fab79f76f3b3a26191785198f1749c5c40989",
+  "resultado": "aprovado",
+  "suites": [
+    {
+      "arquivo": "testes/testes_action_mailbox.rb",
+      "aprovado": true,
+      "testes": 13,
+      "assercoes": 67,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_action_mailer.rb",
+      "aprovado": true,
+      "testes": 9,
+      "assercoes": 37,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_core.rb",
+      "aprovado": true,
+      "testes": 5,
+      "assercoes": 66,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_recursos.rb",
+      "aprovado": true,
+      "testes": 156,
+      "assercoes": 513,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_sinatra.rb",
+      "aprovado": true,
+      "testes": 11,
+      "assercoes": 250,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_transporte.rb",
+      "aprovado": true,
+      "testes": 42,
+      "assercoes": 280,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    }
+  ],
+  "perfil": "dependencias_lockfile",
+  "total_testes": 236,
+  "total_assercoes": 1213
+}

data/docs/ruby-4.0.9-http-padrao.json

@@ -0,0 +1,22 @@
+{
+  "data_utc": "2026-11-14T14:01:58Z",
+  "ruby": "4.0.9",
+  "plataforma": "x86_64-linux",
+  "imagem": "sha256:650e4570a7b60591ee3f9ca2d17509e686f798261702b1b92d7e82a086117ab1",
+  "resultado": "aprovado",
+  "suites": [
+    {
+      "arquivo": "testes/testes_transporte.rb",
+      "aprovado": true,
+      "testes": 42,
+      "assercoes": 286,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    }
+  ],
+  "perfil": "net_http_padrao_do_ruby",
+  "net_http": "0.9.1",
+  "total_testes": 42,
+  "total_assercoes": 286
+}

data/docs/ruby-4.0.9.json

@@ -0,0 +1,66 @@
+{
+  "data_utc": "2026-11-14T14:01:50Z",
+  "ruby": "4.0.9",
+  "plataforma": "x86_64-linux",
+  "imagem": "sha256:650e4570a7b60591ee3f9ca2d17509e686f798261702b1b92d7e82a086117ab1",
+  "resultado": "aprovado",
+  "suites": [
+    {
+      "arquivo": "testes/testes_action_mailbox.rb",
+      "aprovado": true,
+      "testes": 13,
+      "assercoes": 67,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_action_mailer.rb",
+      "aprovado": true,
+      "testes": 9,
+      "assercoes": 37,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_core.rb",
+      "aprovado": true,
+      "testes": 5,
+      "assercoes": 66,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_recursos.rb",
+      "aprovado": true,
+      "testes": 156,
+      "assercoes": 513,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_sinatra.rb",
+      "aprovado": true,
+      "testes": 11,
+      "assercoes": 250,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    },
+    {
+      "arquivo": "testes/testes_transporte.rb",
+      "aprovado": true,
+      "testes": 42,
+      "assercoes": 280,
+      "falhas": 0,
+      "erros": 0,
+      "ignorados": 0
+    }
+  ],
+  "perfil": "dependencias_lockfile",
+  "total_testes": 236,
+  "total_assercoes": 1213
+}

data/docs/sinatra.md

@@ -0,0 +1,94 @@
+# Integração com Sinatra
+
+O [exemplo Sinatra](../exemplos/sinatra.rb) usa o mesmo cliente `mailcore` da
+integração Ruby. Sinatra é uma dependência da aplicação e do ambiente de testes;
+não é uma dependência de runtime do gem Mailcore. A combinação verificada usa
+Sinatra `4.2.1` e Rack `3.2.8`, compatível com o conjunto Rails `8.1.3.1` usado nos
+testes do projeto.
+
+O exemplo é uma aplicação modular `Sinatra::Base`. Ele oferece apenas
+`POST /enviar`, que envia uma mensagem fixa para o endereço configurado no boot.
+O corpo e a query da requisição não escolhem destinatários, conteúdo, chave da
+API, URL da API ou cliente.
+
+## Configurar na aplicação
+
+Forneça estas variáveis pelo mecanismo de segredos do seu ambiente Docker:
+
+| Variável                | Uso                                                                 |
+| ----------------------- | ------------------------------------------------------------------- |
+| `MAILCORE_API_KEY`      | Chave usada pelo SDK para falar com a API                           |
+| `TOKEN_APLICACAO`       | Token separado que autoriza chamadas ao exemplo                     |
+| `MAILCORE_REMETENTE`    | Remetente fixo em domínio autorizado                                |
+| `MAILCORE_DESTINATARIO` | Destinatário fixo                                                   |
+| `MAILCORE_API_URL`      | Opcional: URL base HTTPS da API; usa o padrão do SDK quando ausente |
+
+O token precisa ser uma String de 32 a 256 caracteres em Base64URL, usando letras,
+números, `_` e `-`, e deve ser diferente da chave da API. Gere-o com uma fonte
+criptograficamente segura, por exemplo `SecureRandom.urlsafe_base64(32)`. O exemplo
+recusa configuração incompleta ou ambígua no boot. Ele guarda um resumo SHA256 do
+token e compara resumos de tamanho fixo com a operação de tempo constante do
+OpenSSL.
+
+Em um `config.ru` da aplicação, carregue o exemplo e construa uma instância:
+
+```ruby
+require_relative 'exemplos/sinatra'
+
+run ExemploMailcoreSinatra.construir
+```
+
+Execute esse arquivo pelo servidor Rack da sua aplicação, dentro do ambiente
+Docker configurado. O exemplo não inicia um servidor ao ser carregado. Configure
+HTTPS na entrada da aplicação e preserve a comunicação verificada por HTTPS entre
+o SDK e a API. Os testes deste projeto não publicam portas.
+
+A fábrica também aceita `ambiente:` e `cliente:` no boot. Isso permite fornecer um
+Hash de configuração isolado e um cliente já configurado, inclusive para testes.
+Esses argumentos não são lidos dos parâmetros HTTP. A configuração global do gem
+e o carregamento do cliente Ruby continuam independentes do Sinatra.
+
+## Chamar a rota
+
+```sh
+curl --request POST "$URL_APLICACAO/enviar" \
+  --header "Authorization: Bearer $TOKEN_APLICACAO" \
+  --header 'Idempotency-Key: pedido-123-confirmacao' \
+  --header 'Content-Type: application/json' \
+  --data '{}'
+```
+
+O corpo precisa ser um objeto JSON válido em UTF-8, com até 4 KiB. Seus campos são
+ignorados pelo envio fixo. A chave de idempotência é obrigatória, contém de 1 a 256
+caracteres ASCII visíveis e não aceita vírgulas. Preserve a mesma chave para uma
+repetição explícita da mesma intenção de negócio.
+
+A resposta de aceitação é `202`, contendo apenas `id` e `estado`. A aceitação da
+API não comprova entrega SMTP. Autenticação inválida retorna `401`; chave de
+idempotência ou JSON inválido, `400`; conteúdo acima do limite, `413`; tipo de
+conteúdo diferente de JSON, `415`. Rotas e métodos sem implementação recebem
+`404` sem chamar o SDK.
+
+Falhas da API preservam um status de erro HTTP aplicável, com mensagem genérica.
+Falhas de comunicação, redirecionamentos recusados e respostas de aceitação
+incompletas resultam em `502`. O exemplo não devolve mensagens privadas de erro,
+cabeçalhos da API, chaves ou detalhes internos, e não faz repetição automática.
+
+## Verificação
+
+O arquivo `testes/testes_sinatra.rb`, no repositório de fontes, usa Sinatra e
+`Rack::MockRequest` reais, com um cliente sintético injetado no boot. A verificação
+local concluiu 11 testes e 250 asserções em Ruby 3.4, sem falhas. Ela exercita
+roteamento, autorização, configuração, corpo malicioso, JSON/UTF-8, limites,
+idempotência repassada, respostas sanitizadas e falhas sem repetição.
+
+Os testes não abrem um listener, não chamam a API externa e não enviam SMTP. A
+repetição com a mesma chave confirma que o exemplo a preserva; a deduplicação na
+API real depende do contrato do servidor. A matriz geral pode ser executada pelo
+verificador Docker do projeto, `sh scripts/verificar.sh`, sem instalar Ruby ou
+gems no host.
+
+Fontes dos componentes:
+[documentação do Sinatra](https://sinatrarb.com/intro.html),
+[Sinatra 4.2.1](https://rubygems.org/gems/sinatra/versions/4.2.1) e
+[Rack](https://github.com/rack/rack).

data/docs/verificacao.md

@@ -0,0 +1,100 @@
+# Verificação da gem Ruby
+
+A verificação é local e utiliza dados sintéticos. Não publica pacotes, não faz
+deploy e não envia SMTP. Os relatórios JSON registram resultados observados,
+versões, imagens e alcance de cada execução.
+
+Em 14/11/2026, a matriz principal passou em Ruby **3.3.13, 3.4.12 e 4.0.9**.
+O ensaio da API real local também passou nos dez grupos descritos abaixo, com
+23 migrações, TLS verificado e limpeza concluída. Os números e revisões completos
+permanecem nos relatórios JSON correspondentes.
+
+## Matriz e distribuição
+
+Execute na raiz do repositório:
+
+```sh
+sh scripts/verificar.sh
+```
+
+O host precisa de shell POSIX e Docker Linux. Ruby, Bundler, Rails, Sinatra e
+ferramentas de compilação ficam nas imagens. As bases Ruby 3.3, 3.4 e 4.0 estão
+fixadas por digest, e as dependências de desenvolvimento pelo `Gemfile.lock`.
+Não há instalação de ferramentas no host.
+
+Além do lockfile, a suíte HTTPS é repetida com o `net-http` original de cada Ruby
+(0.4.1, 0.6.0 e 0.9.1, respectivamente). Seus relatórios terminam em
+`-http-padrao.json`. Isso exercita também o caminho de detecção de resposta
+incompleta nas versões anteriores do transporte HTTP.
+
+As suítes são executadas em processos separados, sem rede externa, com checkout
+somente leitura e diretório temporário para Rails/SQLite/Active Storage. O
+servidor HTTPS de teste escuta somente dentro do container e não publica portas.
+Os relatórios `ruby-*.json` contêm as contagens por suíte; uma execução válida
+precisa de `resultado: "aprovado"`, sem falhas, erros ou testes ignorados.
+
+- Contrato: método, caminho, filtros e corpo das 151 operações, recursos filhos,
+  identificadores escapados e preservação de `nil`/`false`.
+- Protocolo HTTPS real: certificado/hostname, CAs, redirecionamentos, HTTP de erro,
+  idempotência, desconexões sem retry, prazo total, limites, respostas truncadas,
+  bytes binários, consumo em fluxo e isolamento entre threads.
+- Assinatura: vetor HMAC independente, UTF-8, rotação, alteração do corpo e janela
+  temporal de cinco minutos.
+- Rails: Action Mailer/Mail reais e aplicação Action Mailbox com SQLite,
+  armazenamento temporário e Active Job de teste. A fronteira HTTP desses
+  adaptadores usa um cliente sintético, conforme [o guia Rails](rails.md).
+- Sinatra: aplicação Rack real, autenticação, idempotência, limites de corpo,
+  separação de credenciais e tratamento sanitizado dos erros.
+
+O mesmo comando constrói a gem em `pkg/`, instala o artefato localmente dentro de
+containers Ruby mínimos e verifica que o cliente puro carrega sem Rails/Sinatra.
+O arquivo SHA-256 acompanha a gem. Os pacotes contêm código/documentação próprios,
+sem testes, credenciais, arquivos de ambiente ou dependências vendorizadas.
+
+## API e PostgreSQL reais locais
+
+O ensaio adicional é separado por precisar do checkout backend e de imagens e
+cache de compilação já preparados:
+
+```sh
+sh scripts/verificar_api.sh
+```
+
+São usados o checkout `mailcore` ao lado de `libs-mailcore`, a imagem
+`mailcore/ruby-testes:3.4`, um runtime local da API, uma imagem Rust e o cache
+público Cargo. O controlador compila a API com `--offline --locked` em Docker e
+registra revisão, hash dos fontes e binário. O cache não inclui credenciais Cargo.
+Consulte `python3 testes/integracao_api.py --help` dentro da imagem para informar
+outros caminhos/imagens; `MAILCORE_BACKEND` e `MAILCORE_IMAGEM_CLIENTE` ajustam o
+wrapper. Nenhum compilador deve ser instalado no host para esse ensaio.
+
+O controlador usa o socket Docker para criar rede interna exclusiva, configurações
+efêmeras em memória e instâncias novas da API e PostgreSQL. A API usa HTTPS e
+PostgreSQL usa TLS `verify-full`; não são publicadas portas. Chaves de dados,
+certificados, usuários e organização são sintéticos e exclusivos. Não são
+iniciados worker, Postal ou SMTP.
+
+Os cenários aprovados incluem chaves Full/Sending e negação por escopo; envio
+composto com Cc/Cco/CID, replay e conflito de idempotência; lote atômico; domínios;
+contatos, catálogos e exportação CSV por fluxo; modelos/pastas/versões/publicação
+com controle de revisão; CRUD de marketing sem disparo; caixas/etiquetas/rascunhos;
+recebimento MIME real pendente de processamento; concessões CLI e revogação.
+O recebimento usa um callback privado sintético assinado, sem iniciar Postal.
+
+O resultado e a limpeza ficam em [integracao-api.json](integracao-api.json).
+`resultado: "aprovado"` e `limpeza_concluida: true` são necessários para considerar
+o ensaio aprovado. Credenciais, corpos e mensagens de email não são gravados no
+relatório. O controlador trata SIGINT/SIGTERM e remove apenas seus recursos.
+
+A [interrupção por SIGTERM](integracao-api-interrupcao.json) também foi exercitada:
+a saída de falha era esperada e a limpeza foi concluída, sem recursos rotulados
+restantes. Esse ensaio não verifica SIGKILL nem desfaz intenções já aceitas.
+
+## Limites das conclusões
+
+Uma API real local comprova os contratos exercitados no binário/backend registrado,
+sem simular entrega SMTP. Os testes Rails não comprovam a configuração da fila,
+banco, armazenamento ou segredos de uma aplicação de produção. A matriz Docker
+não garante todos os sistemas operacionais, versões Rails ou ambientes hospedados.
+Não foi medido desempenho em produção nem equivalência de latência com outro
+serviço. Uma publicação ou implantação futura exige validação própria.

data/exemplos/enviar.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'mailcore'
+
+cliente = Mailcore::Cliente.new(chave_api: ENV.fetch('MAILCORE_API_KEY'))
+pedido = {
+  remetente: ENV.fetch('MAILCORE_REMETENTE'),
+  destinatarios: [ENV.fetch('MAILCORE_DESTINATARIO')],
+  assunto: 'Integração Ruby Mailcore',
+  texto: 'Sua integração Ruby está pronta.',
+  html: '<p>Sua integração Ruby está pronta.</p>'
+}
+resposta = cliente.emails.enviar(pedido, chave_idempotencia: ENV.fetch('CHAVE_IDEMPOTENCIA'))
+puts resposta[:id]