@mailcore-hq/node 0.0.0-stage → 0.2.1-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Alterações
+
+## 0.2.1-alpha.1 — 14/11/2026
+
+Compatibiliza o transporte com runtimes Web que não aceitam o modo de
+redirecionamento `error`. O cliente usa `manual` e recusa respostas 3xx antes
+de processar o corpo, sem encaminhar credenciais a outro destino. O resultado
+preserva o status em `redirecionamento_recusado`.
+
+As integrações serverless reutilizam este cliente; exemplos, runtimes e alcance
+dos testes são mantidos no repositório próprio de integrações.
+
+## 0.2.0-alpha.1 — 14/11/2026
+
+Amplia a integração para campanhas, automações, eventos personalizados,
+recebimento, caixas de entrada e concessões da CLI. Inclui envio direto composto
+com Cc/Cco, cabeçalhos, remetente com nome e CID; capacidades/rastreamento de
+domínios; versões, pastas, prévias e teste de modelos; exportações de contatos.
+
+Downloads por fluxo mantêm prazo, cancelamento, backpressure e limite de bytes
+configurável. Os cabeçalhos base são privados e imutáveis, com cópia por operação.
+Os tipos de eventos de webhook acompanham os eventos atuais do servidor.
+
+Documentação passa a descrever somente o contrato e a identidade Mailcore.
+Inclui testes de integração com API/PostgreSQL TLS isolados e medição local de
+desempenho. Nenhuma publicação npm ou implantação.
+
+## 0.1.0-alpha.1 — 13/11/2026
+
+Primeira biblioteca Mailcore para Node.js/TypeScript, com implementação própria.
+Inclui e-mails e lotes, agendamento, anexos, domínios, chaves, contatos e catálogos,
+importações, modelos e webhooks conforme o contrato existente do Mailcore.
+
+Pacote ESM/CommonJS com tipos, renderização React opcional, HTTPS, cancelamento,
+prazo de requisição, idempotência explícita e verificação de assinatura Svix.
+Sem repetição automática. Versão local, sem publicação no npm.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mailcore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# SDK Mailcore para Node.js e TypeScript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cliente da API Mailcore com tipos TypeScript, módulos ESM/CommonJS e recursos organizados por domínio. Requer **Node.js 20.19.0 ou superior**, com chaves mantidas no servidor.
+
+Versão **`0.2.1-alpha.1`**, pacote **`@mailcore-hq/node`**. A publicação no registro está em preparação. O código-fonte é mantido em [mailcore-hq/mailcore-node](https://github.com/mailcore-hq/mailcore-node). Consulte a [cobertura dos métodos](docs/cobertura.md), o [contrato](docs/contrato-sdk.md), a [verificação executada](docs/verificacao.md) e o [roteiro dos próximos SDKs](docs/roteiro-sdks.md).
+
+## Instalação
+
+Após a publicação desta versão no npm:
+
+```bash
+npm install @mailcore-hq/node@alpha
+```
+
+A versão alpha identifica a distribuição inicial; fixe a versão quando precisar de builds reproduzíveis.
+
+### Desenvolver e instalar localmente
+
+No repositório da biblioteca:
+
+```bash
+npm ci
+npm run check
+npm pack --pack-destination /tmp
+```
+
+No projeto consumidor:
+
+```bash
+npm install /tmp/mailcore-hq-node-0.2.1-alpha.1.tgz
+```
+
+`check` verifica tipos, testes, build, instalação em consumidores separados e formatação. `pack` gera o artefato local sem publicar. A compatibilidade comprovada de runtimes e consumidores está em [verificacao.md](docs/verificacao.md); usar ESM ou CommonJS não comprova todos os frameworks ou ambientes serverless.
+
+## Enviar o primeiro e-mail
+
+Configure `MAILCORE_API_KEY` no ambiente protegido do servidor. Use um domínio verificado e uma chave com permissão de envio.
+
+```typescript
+import { Mailcore } from '@mailcore-hq/node';
+
+const mailcore = new Mailcore(); // Lê MAILCORE_API_KEY.
+const { dados, erro } = await mailcore.emails.enviar(
+  {
+    remetente: 'notificacoes@seudominio.com.br',
+    destinatarios: ['cliente@example.com'],
+    assunto: 'Pedido recebido',
+    html: '<p>Recebemos seu pedido.</p>',
+    texto: 'Recebemos seu pedido.',
+  },
+  { chaveIdempotencia: 'pedido-123-confirmacao' },
+);
+
+if (erro !== null) throw new Error(erro.mensagem);
+console.log(dados.id, dados.estado);
+```
+
+HTTP 202 confirma uma intenção persistida; acompanhe a entrega por consulta ou webhook. Também é possível fornecer a chave explicitamente ao construtor. Em CommonJS: `const { Mailcore } = require('@mailcore-hq/node')`.
+
+Rotas de servidor de frameworks JavaScript reutilizam esta biblioteca. Não exponha a chave em componentes de navegador, bundles públicos ou variáveis destinadas ao cliente. A detecção de navegador da biblioteca é uma proteção adicional, sem substituir a separação do código servidor.
+
+## Conteúdo, cópias e modelos
+
+O envio individual com HTML/texto ou `react` aceita `cc`, `cco`, `cabecalhos` de mensagem, nome de exibição no remetente e anexos com `id_conteudo` para imagens CID. Destinatários, Cc e Cco usam endereços sem nome de exibição. `cabecalhos` no pedido pertence ao e-mail; `opcoes.cabecalhos` pertence à requisição HTTP. O servidor valida os nomes permitidos e protege cabeçalhos reservados.
+
+```typescript
+const resultado = await mailcore.emails.enviar({
+  remetente: 'Equipe <notificacoes@seudominio.com.br>',
+  destinatarios: ['cliente@example.com'],
+  cc: ['equipe@example.com'],
+  cco: ['arquivo@example.com'],
+  assunto: 'Pedido acompanhado',
+  html: '<p>Seu pedido está em processamento.</p>',
+  cabecalhos: { 'X-Pedido': '123' },
+});
+```
+
+Anexos são enviados em `anexos: [{ nome, tipo_conteudo, conteudo_base64, id_conteudo? }]`. O conteúdo é Base64 padrão, sem prefixo `data:`. Para CID, use no HTML o mesmo identificador em `src="cid:identificador"`. O envio transacional não aceita anexos por URL.
+
+Um modelo publicado é enviado com `modelo: { id: 'boas-vindas', variaveis: { NOME: 'Ana' } }` e `destinatarios`. Remetente, assunto e resposta podem usar os padrões publicados ou overrides. **Modelo não combina com `html`, `texto`, `react`, Cc/Cco, cabeçalhos ou CID** no contrato atual. **Lotes não aceitam Cc/Cco, cabeçalhos ou anexos**. Os tipos distinguem essas modalidades; o SDK não apaga silenciosamente campos incompatíveis.
+
+Um lote contém de 1 a 100 mensagens, mantém a ordem e é aceito atomicamente. `mailcore.lotes.enviar(mensagens, opcoes?)` faz uma requisição, sem dividir a intenção.
+
+## React opcional
+
+Projetos que enviam apenas HTML/texto não precisam de React. Para componentes no servidor:
+
+```bash
+npm install react react-dom @react-email/render
+```
+
+```typescript
+import { createElement } from 'react';
+
+const resultado = await mailcore.emails.enviar({
+  remetente: 'notificacoes@seudominio.com.br',
+  destinatarios: ['cliente@example.com'],
+  assunto: 'Pedido recebido',
+  react: createElement('p', null, 'Recebemos seu pedido.'),
+});
+```
+
+O componente é renderizado localmente antes da requisição. Texto simples é gerado quando `texto` é omitido; `texto: ''` e `texto: null` são preservados. Para renderizar e persistir o conteúdo antes de enviá-lo, importe `renderizarEmail` de `@mailcore-hq/node/react`. O backend recebe HTML/texto e não executa React. A mesma opção funciona em lotes sem composição, renderizados em sequência.
+
+## Recursos e permissões
+
+`mailcore` oferece `emails`, `lotes`, `dominios`, `chavesApi`, `contatos`, `propriedadesContatos`, `segmentos`, `topicos`, `modelos`, `webhooks`, `campanhas`, `automacoes`, `eventos`, `recebimento`, `caixas` e `cli.concessoes`. A [cobertura](docs/cobertura.md) lista todos os métodos e suas limitações.
+
+Chaves `sending_access` atendem ao envio transacional, inclusive com modelos publicados, e podem ser restritas a um domínio. Consultas e gestão dependem de uma chave Full com escopos atuais; operações como exportar contatos e administrar concessões da CLI exigem também papel administrativo válido. O servidor revalida os direitos. O SDK não implementa sessão, autenticação interativa ou interfaces administrativas privadas.
+
+Edição/publicação de modelos, campanhas, automações, caixas, conversas e rascunhos seguem a revisão exigida pelo respectivo pedido. Um conflito 409 deve ser tratado pela aplicação; o SDK não atualiza a revisão nem sobrescreve a edição concorrente.
+
+## Resultados, opções e paginação
+
+Operações HTTP retornam `{ dados, erro, cabecalhos }`. Verifique `erro !== null`: falhas retornam `dados: null` e `erro: { codigo, mensagem, status }`; sucesso retorna `erro: null`. Exclusões sem corpo podem retornar `dados: null` com sucesso. Configuração inválida, renderização React e assinatura inválida podem lançar exceções.
+
+Todos os métodos HTTP aceitam `OpcoesRequisicao` no último argumento: `sinal`, `tempoLimiteMs`, `limiteRespostaBytes`, `chaveIdempotencia` e cabeçalhos HTTP adicionais permitidos. A origem padrão é `https://mailcore.com.br/v1`; o prazo padrão é **30 segundos** e o limite de resposta é **16 MiB**, ajustável por chamada. `urlBase`, prazo padrão e `fetch` controlado são configuráveis no construtor. HTTPS é obrigatório; `permitirHttpLocal` habilita somente loopback para testes.
+
+Falhas HTTP preservam o erro e status da API. Os códigos locais incluem `erro_http`, `resposta_invalida`, `falha_de_rede`, `requisicao_cancelada`, `resposta_excedida` e `redirecionamento_recusado`. Cabeçalhos de resposta permitem consultar identificadores de requisição. O cliente não envia cookies nem segue redirecionamentos.
+
+Cada listagem carrega uma página. O cursor pode ser `proximo` ou `proximo_cursor`, conforme o recurso; passe-o como `antes`. Recebimento também admite `depois`, excluindo `antes`. Consulte os [envelopes por recurso](docs/cobertura.md#paginação) e processe as páginas sem acumular toda a base em memória.
+
+## Exportações e downloads grandes
+
+`contatos.exportacoes` cria, consulta e baixa exportações autorizadas. `baixar` acumula bytes; `baixarFluxo` fornece um `ReadableStream<Uint8Array>` com backpressure. O exemplo grava uma exportação existente pela rota autenticada do Mailcore, com teto explícito de 64 MiB:
+
+```typescript
+import { createWriteStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import type { ReadableStream as FluxoWebNode } from 'node:stream/web';
+
+async function salvarExportacao(exportacaoId: string, destino: string) {
+  const download = await mailcore.contatos.exportacoes.baixarFluxo(exportacaoId, {
+    limiteRespostaBytes: 64 * 1024 * 1024,
+    tempoLimiteMs: 60_000,
+  });
+  if (download.erro !== null) throw new Error(download.erro.mensagem);
+
+  await pipeline(
+    Readable.fromWeb(download.dados as FluxoWebNode<Uint8Array>),
+    createWriteStream(destino, { flags: 'wx', mode: 0o600 }),
+  );
+}
+```
+
+O cast do exemplo concilia as declarações de fluxo Web do Node com as da biblioteca DOM em projetos TypeScript; não transforma o fluxo. Consuma ou cancele o fluxo. Falhas de leitura, cancelamento e excesso do teto depois da abertura são rejeições do fluxo; trate a falha de `pipeline` e o arquivo parcial na aplicação. O prazo continua válido durante o consumo.
+
+`recebimento.baixarOriginalFluxo` e `recebimento.baixarAnexoFluxo` também permitem consumo em fluxo. As variantes `baixarOriginal`/`baixarAnexo` retornam bytes em memória. Detalhes recebidos com HTML `data_uri` podem ultrapassar o teto padrão por expansão dos anexos: prefira `formato_html: 'cid'` ou informe um `limiteRespostaBytes` adequado ao seu orçamento e trate `resposta_excedida`. Um teto maior, como 32 MiB, não garante acomodar todo detalhe possível. URLs temporárias nos metadados são sensíveis: a biblioteca não as segue nem anexa Bearer a destinos externos.
+
+## Idempotência e webhooks
+
+O SDK **não repete requisições automaticamente**, inclusive em 429, 503 ou timeout. Interrupção não comprova rejeição no servidor. Persista corpo e chave da intenção antes de operações que suportam idempotência; preserve-os ao repetir explicitamente. Envios transacionais oferecem `emails.obterPorIdempotencia` e `lotes.obterPorIdempotencia`, sujeitos a permissão de leitura. A chave vale por 24 horas; reutilizá-la após expirar pode criar outra intenção. Renderizações dependentes de hora ou dados externos devem ter seu resultado persistido para uma repetição fiel.
+
+`verificarAssinatura(corpoBruto, cabecalhos, segredo)` é exportado pelo pacote principal. Usa o segredo `whsec_...`, HMAC-SHA256 e os cabeçalhos `svix-id`, `svix-timestamp` e `svix-signature`, com tolerância de cinco minutos. Passe o corpo bruto antes de qualquer parser JSON. Só processe eventos depois da verificação e deduplique `svix-id` em armazenamento durável; o verificador não guarda estado.
+
+## Desenvolvimento e validação
+
+Código modular em `src/recursos/`, transporte compartilhado, testes em `testes/` e exemplos em `exemplos/`. `npm run check` executa as verificações da distribuição. Resultados de integração estão em [verificacao.md](docs/verificacao.md); as [medições locais](docs/desempenho.md) descrevem seu cenário e seus limites. Não demonstram implantação nem capacidade de entrega SMTP em produção. Não registrar credenciais, corpos, destinatários ou URLs de capacidade.
+
+Licença [MIT](LICENSE).

package/SECURITY.md

@@ -0,0 +1,27 @@
+# Segurança
+
+Use a biblioteca no servidor, com uma chave de API guardada em variável de
+ambiente ou gerenciador de segredos. Prefira Sending quando a aplicação precisa
+somente enviar. Revogue chaves expostas pelo painel Mailcore.
+
+HTTPS e validação de certificados devem permanecer ativos. A biblioteca não
+persiste mensagens ou chaves, não envia cookies e não segue redirecionamentos.
+Não há repetição automática após falhas de comunicação. A chave e o corpo da
+intenção devem ser preservados pelo sistema chamador para reconciliação.
+
+Não publique chaves, conteúdo de mensagens ou dados pessoais em issues, logs
+e relatórios. Ao identificar uma vulnerabilidade, envie uma reprodução
+sanitizada para [github@mailcore.com.br](mailto:github@mailcore.com.br).
+Compartilhe inicialmente apenas o necessário para investigar o problema, sem
+credenciais ou dados de terceiros.
+
+O recebimento de webhooks exige validação da assinatura sobre o corpo bruto,
+controle temporal e deduplicação durável do identificador de entrega. A aplicação
+é responsável por limites, filas, retenção, criptografia de sua persistência e
+autorização das operações que disparam mensagens.
+
+Esta versão alpha tem validação local documentada em `docs/verificacao.md`.
+Durante a fase alpha, mantenha a versão instalada atualizada e consulte o
+changelog antes de atualizar. O workflow de verificação não publica pacotes ou deploys. A publicação npm
+exige acionamento manual do workflow separado e vínculo OIDC no registro,
+conforme [publicacao.md](docs/publicacao.md).