mailcore-sdk 0.1.0a1__py3-none-any.whl

mailcore/__init__.py

@@ -0,0 +1,47 @@
+"""Cliente Python da API Mailcore para aplicações de servidor."""
+
+from .assinatura import verificar_assinatura
+from .cliente import Cliente, ClienteAsync
+from .erros import Erro, ErroApi, ErroAssinatura, ErroConfiguracao, ErroResposta, ErroTransporte
+from .tipos import (
+    AnexoCompostoEmail,
+    AnexoEmail,
+    ConfiguracaoCliente,
+    EmailComModelo,
+    EmailHtml,
+    EmailTexto,
+    EventoRecebido,
+    OpcoesRequisicao,
+    PedidoEmail,
+    PedidoEmailLote,
+    Resposta,
+    RespostaEnvio,
+    RespostaLote,
+)
+from .versao import VERSAO
+
+__all__ = [
+    "Cliente",
+    "ClienteAsync",
+    "Erro",
+    "ErroApi",
+    "ErroAssinatura",
+    "ErroConfiguracao",
+    "ErroResposta",
+    "ErroTransporte",
+    "Resposta",
+    "PedidoEmail",
+    "PedidoEmailLote",
+    "RespostaEnvio",
+    "RespostaLote",
+    "AnexoEmail",
+    "AnexoCompostoEmail",
+    "EmailHtml",
+    "EmailTexto",
+    "EmailComModelo",
+    "ConfiguracaoCliente",
+    "OpcoesRequisicao",
+    "EventoRecebido",
+    "verificar_assinatura",
+    "VERSAO",
+]

mailcore/assinatura.py

@@ -0,0 +1,105 @@
+"""Verificação local interoperável de webhooks HMAC-SHA256."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import math
+import re
+import time
+from collections.abc import Mapping
+from typing import cast
+
+from .erros import ErroAssinatura
+from .tipos import EventoRecebido
+
+
+def _constante_invalida(_valor: str) -> None:
+    raise ValueError
+
+
+def verificar_assinatura(
+    corpo_bruto: bytes | str,
+    cabecalhos: Mapping[str, str],
+    segredo: str,
+    *,
+    agora: float | None = None,
+    tolerancia: int = 300,
+) -> EventoRecebido:
+    """Verifique o corpo recebido antes de interpretar JSON ou executar ações."""
+    try:
+        if not isinstance(corpo_bruto, (str, bytes)):
+            raise ValueError
+        corpo = corpo_bruto.encode("utf-8") if isinstance(corpo_bruto, str) else corpo_bruto
+        if (
+            len(corpo) > 8 * 1024 * 1024
+            or type(tolerancia) is not int
+            or not 1 <= tolerancia <= 300
+        ):
+            raise ValueError
+        if not isinstance(segredo, str) or not segredo.startswith("whsec_") or len(segredo) > 1024:
+            raise ValueError
+        normalizados: dict[str, str] = {}
+        for nome, valor in cabecalhos.items():
+            nome = nome.lower().replace("_", "-").removeprefix("http-")
+            if nome not in {"svix-id", "svix-timestamp", "svix-signature"}:
+                continue
+            if nome in normalizados or not isinstance(valor, str):
+                raise ValueError
+            normalizados[nome] = valor
+        identificador = normalizados["svix-id"]
+        instante = normalizados["svix-timestamp"]
+        assinaturas = normalizados["svix-signature"]
+        if not re.fullmatch(r"[\x21-\x7e]{1,256}", identificador) or not re.fullmatch(
+            r"[1-9][0-9]{0,15}", instante
+        ):
+            raise ValueError
+        momento = time.time() if agora is None else agora
+        if (
+            isinstance(momento, bool)
+            or not math.isfinite(momento)
+            or len(assinaturas) > 4096
+            or abs(momento - int(instante)) > tolerancia
+        ):
+            raise ValueError
+        chave = base64.b64decode(segredo[6:], validate=True)
+        if len(chave) < 16:
+            raise ValueError
+        esperado = hmac.digest(
+            chave, f"{identificador}.{instante}.".encode("ascii") + corpo, hashlib.sha256
+        )
+        valido = False
+        for assinatura in assinaturas.split()[:32]:
+            versao, separador, valor = assinatura.partition(",")
+            if versao != "v1" or not separador:
+                continue
+            try:
+                valido |= hmac.compare_digest(esperado, base64.b64decode(valor, validate=True))
+            except (ValueError, binascii.Error):
+                continue
+        if not valido:
+            raise ValueError
+        evento = json.loads(corpo.decode("utf-8"), parse_constant=_constante_invalida)
+        if (
+            not isinstance(evento, dict)
+            or not isinstance(evento.get("type"), str)
+            or not isinstance(evento.get("created_at"), str)
+            or "data" not in evento
+        ):
+            raise ValueError
+        return cast(EventoRecebido, evento)
+    except (
+        ValueError,
+        TypeError,
+        KeyError,
+        AttributeError,
+        UnicodeError,
+        OverflowError,
+        RecursionError,
+    ):
+        raise ErroAssinatura(
+            "Não foi possível verificar a autenticidade do webhook.", codigo="assinatura_invalida"
+        ) from None

mailcore/cliente.py

@@ -0,0 +1,105 @@
+"""Clientes por instância: reutilize durante a vida da aplicação ou tarefa."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Unpack
+
+import httpx
+
+from . import recursos
+from .tipos import ConfiguracaoCliente
+from .transporte import ChaveApi, Transporte, TransporteAsync
+
+
+class Cliente:
+    def __init__(
+        self,
+        chave_api: ChaveApi = None,
+        *,
+        transporte_http: httpx.BaseTransport | None = None,
+        **configuracao: Unpack[ConfiguracaoCliente],
+    ) -> None:
+        self._transporte = Transporte(chave_api, transporte_http=transporte_http, **configuracao)
+        self.emails = recursos.Emails(self._transporte)
+        self.lotes = recursos.Lotes(self._transporte)
+        self.dominios = recursos.Dominios(self._transporte)
+        self.chaves_api = recursos.ChavesApi(self._transporte)
+        self.contatos = recursos.Contatos(self._transporte)
+        self.segmentos = recursos.Segmentos(self._transporte)
+        self.topicos = recursos.Topicos(self._transporte)
+        self.propriedades_contatos = recursos.PropriedadesContatos(self._transporte)
+        self.modelos = recursos.Modelos(self._transporte)
+        self.webhooks = recursos.Webhooks(self._transporte)
+        self.campanhas = recursos.Campanhas(self._transporte)
+        self.automacoes = recursos.Automacoes(self._transporte)
+        self.eventos = recursos.Eventos(self._transporte)
+        self.recebimento = recursos.Recebimento(self._transporte)
+        self.caixas = recursos.Caixas(self._transporte)
+        self.cli = recursos.CliMailcore(self._transporte)
+
+    def __enter__(self) -> Cliente:
+        return self
+
+    def __exit__(
+        self,
+        tipo: type[BaseException] | None,
+        valor: BaseException | None,
+        rastreamento: TracebackType | None,
+    ) -> None:
+        self.fechar()
+
+    def fechar(self) -> None:
+        self._transporte.fechar()
+
+    def __repr__(self) -> str:
+        return "<Cliente credenciais=protegidas>"
+
+
+class ClienteAsync:
+    def __init__(
+        self,
+        chave_api: ChaveApi = None,
+        *,
+        transporte_http: httpx.AsyncBaseTransport | None = None,
+        **configuracao: Unpack[ConfiguracaoCliente],
+    ) -> None:
+        self._transporte = TransporteAsync(
+            chave_api, transporte_http=transporte_http, **configuracao
+        )
+        self.emails = recursos.EmailsAsync(self._transporte)
+        self.lotes = recursos.LotesAsync(self._transporte)
+        self.dominios = recursos.DominiosAsync(self._transporte)
+        self.chaves_api = recursos.ChavesApiAsync(self._transporte)
+        self.contatos = recursos.ContatosAsync(self._transporte)
+        self.segmentos = recursos.SegmentosAsync(self._transporte)
+        self.topicos = recursos.TopicosAsync(self._transporte)
+        self.propriedades_contatos = recursos.PropriedadesContatosAsync(self._transporte)
+        self.modelos = recursos.ModelosAsync(self._transporte)
+        self.webhooks = recursos.WebhooksAsync(self._transporte)
+        self.campanhas = recursos.CampanhasAsync(self._transporte)
+        self.automacoes = recursos.AutomacoesAsync(self._transporte)
+        self.eventos = recursos.EventosAsync(self._transporte)
+        self.recebimento = recursos.RecebimentoAsync(self._transporte)
+        self.caixas = recursos.CaixasAsync(self._transporte)
+        self.cli = recursos.CliMailcoreAsync(self._transporte)
+
+    async def __aenter__(self) -> ClienteAsync:
+        return self
+
+    async def __aexit__(
+        self,
+        tipo: type[BaseException] | None,
+        valor: BaseException | None,
+        rastreamento: TracebackType | None,
+    ) -> None:
+        await self.fechar()
+
+    async def fechar(self) -> None:
+        await self._transporte.fechar()
+
+    async def fechar_async(self) -> None:
+        await self.fechar()
+
+    def __repr__(self) -> str:
+        return "<ClienteAsync credenciais=protegidas>"

mailcore/erros.py

@@ -0,0 +1,42 @@
+"""Erros públicos com metadados e sem reprodução de corpos de transporte."""
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+
+class Erro(Exception):
+    def __init__(
+        self,
+        mensagem: str = "Não foi possível concluir a operação.",
+        *,
+        codigo: str = "erro_mailcore",
+        status: int | None = None,
+        cabecalhos: Mapping[str, str] | None = None,
+    ) -> None:
+        super().__init__(mensagem)
+        self.codigo = codigo
+        self.status = status
+        self.cabecalhos: Mapping[str, str] = MappingProxyType(dict(cabecalhos or {}))
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(codigo={self.codigo!r}, status={self.status!r})"
+
+
+class ErroApi(Erro):
+    """Rejeição HTTP; código/mensagem públicos são preservados quando válidos."""
+
+
+class ErroConfiguracao(ValueError):
+    """Opções, identificadores ou JSON de entrada inválidos."""
+
+
+class ErroTransporte(Erro):
+    """Conexão, protocolo incompleto ou prazo de atividade excedido."""
+
+
+class ErroResposta(Erro):
+    """JSON inválido, codificação inesperada ou limite de resposta excedido."""
+
+
+class ErroAssinatura(Erro):
+    """Webhook não autenticado; nenhum detalhe do segredo é exposto."""

mailcore/recursos/__init__.py

@@ -0,0 +1,93 @@
+"""Recursos síncronos e assíncronos do cliente Mailcore."""
+
+from .automacoes import (
+    Automacoes,
+    AutomacoesAsync,
+)
+from .caixas import (
+    Caixas,
+    CaixasAsync,
+)
+from .campanhas import (
+    Campanhas,
+    CampanhasAsync,
+)
+from .chaves_api import (
+    ChavesApi,
+    ChavesApiAsync,
+)
+from .cli import (
+    CliMailcore,
+    CliMailcoreAsync,
+)
+from .contatos import (
+    Contatos,
+    ContatosAsync,
+    PropriedadesContatos,
+    PropriedadesContatosAsync,
+    Segmentos,
+    SegmentosAsync,
+    Topicos,
+    TopicosAsync,
+)
+from .dominios import (
+    Dominios,
+    DominiosAsync,
+)
+from .emails import (
+    Emails,
+    EmailsAsync,
+    Lotes,
+    LotesAsync,
+)
+from .eventos import (
+    Eventos,
+    EventosAsync,
+)
+from .modelos import (
+    Modelos,
+    ModelosAsync,
+)
+from .recebimento import (
+    Recebimento,
+    RecebimentoAsync,
+)
+from .webhooks import (
+    Webhooks,
+    WebhooksAsync,
+)
+
+__all__ = [
+    "Emails",
+    "EmailsAsync",
+    "Lotes",
+    "LotesAsync",
+    "Dominios",
+    "DominiosAsync",
+    "ChavesApi",
+    "ChavesApiAsync",
+    "Contatos",
+    "ContatosAsync",
+    "Segmentos",
+    "SegmentosAsync",
+    "Topicos",
+    "TopicosAsync",
+    "PropriedadesContatos",
+    "PropriedadesContatosAsync",
+    "Modelos",
+    "ModelosAsync",
+    "Webhooks",
+    "WebhooksAsync",
+    "Campanhas",
+    "CampanhasAsync",
+    "Automacoes",
+    "AutomacoesAsync",
+    "Eventos",
+    "EventosAsync",
+    "Recebimento",
+    "RecebimentoAsync",
+    "Caixas",
+    "CaixasAsync",
+    "CliMailcore",
+    "CliMailcoreAsync",
+]

mailcore/recursos/automacoes.py

@@ -0,0 +1,252 @@
+"""Operações de automacoes do contrato público Mailcore."""
+
+from __future__ import annotations
+
+# Fonte estática; manutenção em scripts/gerar_recursos.py.
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Unpack
+
+from ..tipos import (
+    OpcoesRequisicao,
+    Resposta,
+)
+from .base import RecursoBase, RecursoBaseAsync, segmento
+
+if TYPE_CHECKING:
+    from ..transporte import Transporte, TransporteAsync
+
+
+class ExecucoesAutomacoes(RecursoBase):
+    def listar(
+        self,
+        automacao_id: str,
+        filtros: Mapping[str, Any] | None = None,
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return self._executar(
+            "GET",
+            f"/automations/{segmento(automacao_id)}/runs",
+            consulta=filtros,
+            **opcoes,
+        )
+
+    def obter(
+        self,
+        automacao_id: str,
+        execucao_id: str,
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return self._executar(
+            "GET",
+            f"/automations/{segmento(automacao_id)}/runs/{segmento(execucao_id)}",
+            **opcoes,
+        )
+
+
+class Automacoes(RecursoBase):
+    def __init__(self, transporte: Transporte) -> None:
+        super().__init__(transporte)
+        self.execucoes: ExecucoesAutomacoes = ExecucoesAutomacoes(transporte)
+
+    def criar(
+        self,
+        pedido: Mapping[str, Any],
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return self._executar(
+            "POST",
+            "/automations",
+            corpo=pedido,
+            **opcoes,
+        )
+
+    def listar(
+        self,
+        filtros: Mapping[str, Any] | None = None,
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return self._executar(
+            "GET",
+            "/automations",
+            consulta=filtros,
+            **opcoes,
+        )
+
+    def obter(
+        self,
+        id: str,
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return self._executar(
+            "GET",
+            f"/automations/{segmento(id)}",
+            **opcoes,
+        )
+
+    def atualizar(
+        self,
+        id: str,
+        pedido: Mapping[str, Any],
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return self._executar(
+            "PATCH",
+            f"/automations/{segmento(id)}",
+            corpo=pedido,
+            **opcoes,
+        )
+
+    def remover(
+        self,
+        id: str,
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return self._executar(
+            "DELETE",
+            f"/automations/{segmento(id)}",
+            **opcoes,
+        )
+
+    def duplicar(
+        self,
+        id: str,
+        pedido: Mapping[str, Any] | None = None,
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return self._executar(
+            "POST",
+            f"/automations/{segmento(id)}/duplicate",
+            corpo={} if pedido is None else pedido,
+            **opcoes,
+        )
+
+    def parar(
+        self,
+        id: str,
+        pedido: Mapping[str, Any],
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return self._executar(
+            "POST",
+            f"/automations/{segmento(id)}/stop",
+            corpo=pedido,
+            **opcoes,
+        )
+
+
+class ExecucoesAutomacoesAsync(RecursoBaseAsync):
+    async def listar(
+        self,
+        automacao_id: str,
+        filtros: Mapping[str, Any] | None = None,
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return await self._executar(
+            "GET",
+            f"/automations/{segmento(automacao_id)}/runs",
+            consulta=filtros,
+            **opcoes,
+        )
+
+    async def obter(
+        self,
+        automacao_id: str,
+        execucao_id: str,
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return await self._executar(
+            "GET",
+            f"/automations/{segmento(automacao_id)}/runs/{segmento(execucao_id)}",
+            **opcoes,
+        )
+
+
+class AutomacoesAsync(RecursoBaseAsync):
+    def __init__(self, transporte: TransporteAsync) -> None:
+        super().__init__(transporte)
+        self.execucoes: ExecucoesAutomacoesAsync = ExecucoesAutomacoesAsync(transporte)
+
+    async def criar(
+        self,
+        pedido: Mapping[str, Any],
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return await self._executar(
+            "POST",
+            "/automations",
+            corpo=pedido,
+            **opcoes,
+        )
+
+    async def listar(
+        self,
+        filtros: Mapping[str, Any] | None = None,
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return await self._executar(
+            "GET",
+            "/automations",
+            consulta=filtros,
+            **opcoes,
+        )
+
+    async def obter(
+        self,
+        id: str,
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return await self._executar(
+            "GET",
+            f"/automations/{segmento(id)}",
+            **opcoes,
+        )
+
+    async def atualizar(
+        self,
+        id: str,
+        pedido: Mapping[str, Any],
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return await self._executar(
+            "PATCH",
+            f"/automations/{segmento(id)}",
+            corpo=pedido,
+            **opcoes,
+        )
+
+    async def remover(
+        self,
+        id: str,
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return await self._executar(
+            "DELETE",
+            f"/automations/{segmento(id)}",
+            **opcoes,
+        )
+
+    async def duplicar(
+        self,
+        id: str,
+        pedido: Mapping[str, Any] | None = None,
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return await self._executar(
+            "POST",
+            f"/automations/{segmento(id)}/duplicate",
+            corpo={} if pedido is None else pedido,
+            **opcoes,
+        )
+
+    async def parar(
+        self,
+        id: str,
+        pedido: Mapping[str, Any],
+        **opcoes: Unpack[OpcoesRequisicao],
+    ) -> Resposta[Any]:
+        return await self._executar(
+            "POST",
+            f"/automations/{segmento(id)}/stop",
+            corpo=pedido,
+            **opcoes,
+        )

mailcore/recursos/base.py

@@ -0,0 +1,51 @@
+"""Base fina: um método do recurso corresponde a uma operação HTTP."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any, Unpack
+from urllib.parse import quote
+
+from ..erros import ErroConfiguracao
+from ..tipos import GestorFluxo, GestorFluxoAsync, OpcoesRequisicao, Resposta
+
+if TYPE_CHECKING:
+    from ..transporte import Transporte, TransporteAsync
+
+
+def segmento(valor: str) -> str:
+    if (
+        not isinstance(valor, str)
+        or not valor
+        or valor in {".", ".."}
+        or re.search(r"[\x00-\x1f\x7f]", valor)
+    ):
+        raise ErroConfiguracao("Informe um identificador não vazio e sem controles.")
+    try:
+        return quote(valor, safe="-._~")
+    except UnicodeError:
+        raise ErroConfiguracao("O identificador deve ser UTF-8 válido.") from None
+
+
+class RecursoBase:
+    def __init__(self, transporte: Transporte) -> None:
+        self._transporte = transporte
+
+    def _executar(self, metodo: str, caminho: str, **opcoes: Any) -> Resposta[Any]:
+        return self._transporte.executar(metodo, caminho, **opcoes)
+
+    def _fluxo(self, metodo: str, caminho: str, **opcoes: Unpack[OpcoesRequisicao]) -> GestorFluxo:
+        return self._transporte.fluxo(metodo, caminho, formato="fluxo", **opcoes)
+
+
+class RecursoBaseAsync:
+    def __init__(self, transporte: TransporteAsync) -> None:
+        self._transporte = transporte
+
+    async def _executar(self, metodo: str, caminho: str, **opcoes: Any) -> Resposta[Any]:
+        return await self._transporte.executar(metodo, caminho, **opcoes)
+
+    def _fluxo(
+        self, metodo: str, caminho: str, **opcoes: Unpack[OpcoesRequisicao]
+    ) -> GestorFluxoAsync:
+        return self._transporte.fluxo(metodo, caminho, formato="fluxo", **opcoes)