coffeemail 0.1.0__py3-none-any.whl

coffeemail/__init__.py

@@ -0,0 +1,106 @@
+from coffeemail.async_client import AsyncCoffeeMail
+from coffeemail.client import CoffeeMail
+from coffeemail.core.errors import (
+    AuthenticationError,
+    CoffeeMailError,
+    ConflictError,
+    NetworkError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from coffeemail.core.types import ApiKeyIntrospection, CoffeeMailResponse
+from coffeemail.models import (
+    AudienceDetail,
+    BatchSendEmailResult,
+    BroadcastDetail,
+    BroadcastStatus,
+    BulkAddContactsResponse,
+    CheckSuppressionResponse,
+    ContactDetail,
+    CreateDomainResponse,
+    CreatedWebhookDetail,
+    DnsRecord,
+    DomainDetail,
+    DomainStatus,
+    EmailAttachment,
+    EmailDetail,
+    EmailParticipant,
+    EmailStats,
+    EmailStatus,
+    EmailTag,
+    ListAudiencesResponse,
+    ListBroadcastsResponse,
+    ListContactsResponse,
+    ListDomainsResponse,
+    ListEmailsResponse,
+    ListSuppressionsResponse,
+    ListTemplatesResponse,
+    ListWebhooksResponse,
+    PreviewTemplateResponse,
+    RotateWebhookSecretResult,
+    SendEmailPayload,
+    SendEmailResponse,
+    SuppressionDetail,
+    SuppressionReason,
+    TemplateDetail,
+    TestWebhookResult,
+    WebhookDetail,
+    WebhookEvent,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CoffeeMail",
+    "AsyncCoffeeMail",
+    "CoffeeMailResponse",
+    "ApiKeyIntrospection",
+    "CoffeeMailError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+    "NetworkError",
+    "BatchSendEmailResult",
+    "EmailAttachment",
+    "EmailDetail",
+    "EmailParticipant",
+    "EmailStatus",
+    "EmailTag",
+    "ListEmailsResponse",
+    "SendEmailPayload",
+    "SendEmailResponse",
+    "CreateDomainResponse",
+    "DnsRecord",
+    "DomainDetail",
+    "DomainStatus",
+    "ListDomainsResponse",
+    "ListTemplatesResponse",
+    "PreviewTemplateResponse",
+    "TemplateDetail",
+    "AudienceDetail",
+    "BulkAddContactsResponse",
+    "ContactDetail",
+    "ListAudiencesResponse",
+    "ListContactsResponse",
+    "BroadcastDetail",
+    "BroadcastStatus",
+    "ListBroadcastsResponse",
+    "CheckSuppressionResponse",
+    "ListSuppressionsResponse",
+    "SuppressionDetail",
+    "SuppressionReason",
+    "CreatedWebhookDetail",
+    "ListWebhooksResponse",
+    "RotateWebhookSecretResult",
+    "TestWebhookResult",
+    "WebhookDetail",
+    "WebhookEvent",
+    "EmailStats",
+]

coffeemail/async_client.py

@@ -0,0 +1,52 @@
+import os
+
+import httpx
+
+from coffeemail.core.http import DEFAULT_TIMEOUT_SECONDS, AsyncHttpTransport
+from coffeemail.core.i18n import Locale
+from coffeemail.core.types import ApiKeyIntrospection, CoffeeMailResponse
+from coffeemail.resources.audiences import AsyncAudiences
+from coffeemail.resources.broadcasts import AsyncBroadcasts
+from coffeemail.resources.domains import AsyncDomains
+from coffeemail.resources.emails import AsyncEmails
+from coffeemail.resources.stats import AsyncStats
+from coffeemail.resources.suppressions import AsyncSuppressions
+from coffeemail.resources.templates import AsyncTemplates
+from coffeemail.resources.webhooks import AsyncWebhooks
+
+
+class AsyncCoffeeMail:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        locale: Locale = "pt-BR",
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        resolved_key = api_key or os.getenv("COFFEEMAIL_API_KEY")
+        self._transport = AsyncHttpTransport(
+            api_key=resolved_key,
+            base_url=base_url,
+            timeout=timeout,
+            locale=locale,
+            client=http_client,
+        )
+
+        self.emails = AsyncEmails(self._transport)
+        self.domains = AsyncDomains(self._transport)
+        self.templates = AsyncTemplates(self._transport)
+        self.audiences = AsyncAudiences(self._transport)
+        self.broadcasts = AsyncBroadcasts(self._transport)
+        self.suppressions = AsyncSuppressions(self._transport)
+        self.webhooks = AsyncWebhooks(self._transport)
+        self.stats = AsyncStats(self._transport)
+
+    async def introspect(
+        self, force_refresh: bool = False
+    ) -> CoffeeMailResponse[ApiKeyIntrospection]:
+        return await self._transport.introspect(force_refresh=force_refresh)
+
+    def invalidate_introspection_cache(self) -> None:
+        self._transport.invalidate_introspection_cache()

coffeemail/client.py

@@ -0,0 +1,50 @@
+import os
+
+import httpx
+
+from coffeemail.core.http import DEFAULT_TIMEOUT_SECONDS, HttpTransport
+from coffeemail.core.i18n import Locale
+from coffeemail.core.types import ApiKeyIntrospection, CoffeeMailResponse
+from coffeemail.resources.audiences import Audiences
+from coffeemail.resources.broadcasts import Broadcasts
+from coffeemail.resources.domains import Domains
+from coffeemail.resources.emails import Emails
+from coffeemail.resources.stats import Stats
+from coffeemail.resources.suppressions import Suppressions
+from coffeemail.resources.templates import Templates
+from coffeemail.resources.webhooks import Webhooks
+
+
+class CoffeeMail:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        locale: Locale = "pt-BR",
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        resolved_key = api_key or os.getenv("COFFEEMAIL_API_KEY")
+        self._transport = HttpTransport(
+            api_key=resolved_key,
+            base_url=base_url,
+            timeout=timeout,
+            locale=locale,
+            client=http_client,
+        )
+
+        self.emails = Emails(self._transport)
+        self.domains = Domains(self._transport)
+        self.templates = Templates(self._transport)
+        self.audiences = Audiences(self._transport)
+        self.broadcasts = Broadcasts(self._transport)
+        self.suppressions = Suppressions(self._transport)
+        self.webhooks = Webhooks(self._transport)
+        self.stats = Stats(self._transport)
+
+    def introspect(self, force_refresh: bool = False) -> CoffeeMailResponse[ApiKeyIntrospection]:
+        return self._transport.introspect(force_refresh=force_refresh)
+
+    def invalidate_introspection_cache(self) -> None:
+        self._transport.invalidate_introspection_cache()

coffeemail/core/crypto.py

@@ -0,0 +1,19 @@
+import hashlib
+import hmac
+
+
+def verify_webhook_signature(
+    payload: str | bytes,
+    signature: str,
+    secret: str,
+) -> bool:
+    if not payload or not signature or not secret:
+        return False
+
+    try:
+        raw_bytes = payload.encode("utf-8") if isinstance(payload, str) else payload
+        secret_bytes = secret.encode("utf-8")
+        computed = hmac.new(secret_bytes, raw_bytes, hashlib.sha256).hexdigest()
+        return hmac.compare_digest(computed.lower(), signature.strip().lower())
+    except Exception:
+        return False

coffeemail/core/errors.py

@@ -0,0 +1,88 @@
+class CoffeeMailError(Exception):
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        code: str | None = None,
+        details: dict[str, object] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        if self.code:
+            return f"[{self.code}] {self.message}"
+        return self.message
+
+
+class AuthenticationError(CoffeeMailError):
+    pass
+
+
+class PermissionDeniedError(CoffeeMailError):
+    pass
+
+
+class NotFoundError(CoffeeMailError):
+    pass
+
+
+class ValidationError(CoffeeMailError):
+    pass
+
+
+class ConflictError(CoffeeMailError):
+    pass
+
+
+class RateLimitError(CoffeeMailError):
+    pass
+
+
+class ServerError(CoffeeMailError):
+    pass
+
+
+class NetworkError(CoffeeMailError):
+    pass
+
+
+def create_error_from_response(
+    status_code: int,
+    body: dict[str, object] | None = None,
+    default_message: str | None = None,
+) -> CoffeeMailError:
+    data = body or {}
+    message = str(
+        data.get("message") or data.get("error") or default_message or f"HTTP Error {status_code}"
+    )
+    code = data.get("code")
+    str_code = str(code) if code else None
+    details = data.get("details")
+    details_dict = details if isinstance(details, dict) else {}
+
+    if status_code == 401:
+        return AuthenticationError(
+            message, status_code=status_code, code=str_code, details=details_dict
+        )
+    if status_code == 403:
+        return PermissionDeniedError(
+            message, status_code=status_code, code=str_code, details=details_dict
+        )
+    if status_code == 404:
+        return NotFoundError(message, status_code=status_code, code=str_code, details=details_dict)
+    if status_code in (400, 422):
+        return ValidationError(
+            message, status_code=status_code, code=str_code, details=details_dict
+        )
+    if status_code == 409:
+        return ConflictError(message, status_code=status_code, code=str_code, details=details_dict)
+    if status_code == 429:
+        return RateLimitError(message, status_code=status_code, code=str_code, details=details_dict)
+    if status_code >= 500:
+        return ServerError(message, status_code=status_code, code=str_code, details=details_dict)
+
+    return CoffeeMailError(message, status_code=status_code, code=str_code, details=details_dict)

coffeemail/core/http.py

@@ -0,0 +1,243 @@
+import time
+from collections.abc import Mapping
+from typing import TypeVar
+
+import httpx
+
+from coffeemail.core.errors import (
+    AuthenticationError,
+    NetworkError,
+    create_error_from_response,
+)
+from coffeemail.core.i18n import Locale, get_message
+from coffeemail.core.types import ApiKeyIntrospection, CoffeeMailResponse
+
+SDK_VERSION = "0.1.0"
+DEFAULT_BASE_URL = "https://api.coffeemail.com.br"
+DEFAULT_TIMEOUT_SECONDS = 10.0
+
+T = TypeVar("T")
+
+
+class BaseTransport:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        locale: Locale = "pt-BR",
+    ) -> None:
+        clean_key = (api_key or "").strip()
+        if not clean_key:
+            raise AuthenticationError(get_message("missing_api_key", locale))
+
+        self.api_key = clean_key
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.locale = locale
+
+    def get_headers(self, custom_headers: dict[str, str] | None = None) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Accept-Language": self.locale,
+            "User-Agent": f"coffeemail-python/{SDK_VERSION}",
+        }
+        if custom_headers:
+            headers.update(custom_headers)
+        return headers
+
+
+class HttpTransport(BaseTransport):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        locale: Locale = "pt-BR",
+        client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, locale)
+        self.client = client or httpx.Client(timeout=self.timeout)
+        self._cached_introspection: ApiKeyIntrospection | None = None
+        self._introspection_expires_at: float = 0.0
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: Mapping[str, object] | None = None,
+        json_data: Mapping[str, object] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> CoffeeMailResponse[dict[str, object]]:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        req_headers = self.get_headers(headers)
+        clean_params = (
+            {k: str(v) for k, v in params.items() if v is not None} if params is not None else None
+        )
+
+        try:
+            response = self.client.request(
+                method=method,
+                url=url,
+                params=clean_params,
+                json=json_data,
+                headers=req_headers,
+            )
+        except httpx.TimeoutException as exc:
+            err = NetworkError(
+                get_message("timeout_error", self.locale), details={"original_error": str(exc)}
+            )
+            return CoffeeMailResponse(data=None, error=err, status_code=None)
+        except httpx.RequestError as exc:
+            err = NetworkError(
+                get_message("network_error", self.locale), details={"original_error": str(exc)}
+            )
+            return CoffeeMailResponse(data=None, error=err, status_code=None)
+
+        if not response.is_success:
+            body: dict[str, object] = {"message": response.text}
+            try:
+                parsed_body = response.json()
+                if isinstance(parsed_body, dict):
+                    body = parsed_body
+            except Exception:
+                pass
+            error = create_error_from_response(response.status_code, body)
+            return CoffeeMailResponse(data=None, error=error, status_code=response.status_code)
+
+        data: dict[str, object] = {}
+        if response.content:
+            try:
+                parsed_data = response.json()
+                if isinstance(parsed_data, dict):
+                    data = parsed_data
+            except Exception:
+                data = {}
+
+        return CoffeeMailResponse(data=data, error=None, status_code=response.status_code)
+
+    def introspect(self, force_refresh: bool = False) -> CoffeeMailResponse[ApiKeyIntrospection]:
+        now = time.time()
+        if (
+            not force_refresh
+            and self._cached_introspection
+            and now < self._introspection_expires_at
+        ):
+            return CoffeeMailResponse(data=self._cached_introspection, error=None, status_code=200)
+
+        raw_response = self.request("GET", "/v1/product/auth/me/api-key")
+        if raw_response.error or raw_response.data is None:
+            return CoffeeMailResponse(
+                data=None, error=raw_response.error, status_code=raw_response.status_code
+            )
+
+        introspection = ApiKeyIntrospection.model_validate(raw_response.data)
+        self._cached_introspection = introspection
+        self._introspection_expires_at = now + 300.0
+        return CoffeeMailResponse(
+            data=introspection, error=None, status_code=raw_response.status_code
+        )
+
+    def invalidate_introspection_cache(self) -> None:
+        self._cached_introspection = None
+        self._introspection_expires_at = 0.0
+
+
+class AsyncHttpTransport(BaseTransport):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        locale: Locale = "pt-BR",
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, locale)
+        self.client = client or httpx.AsyncClient(timeout=self.timeout)
+        self._cached_introspection: ApiKeyIntrospection | None = None
+        self._introspection_expires_at: float = 0.0
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        params: Mapping[str, object] | None = None,
+        json_data: Mapping[str, object] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> CoffeeMailResponse[dict[str, object]]:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        req_headers = self.get_headers(headers)
+        clean_params = (
+            {k: str(v) for k, v in params.items() if v is not None} if params is not None else None
+        )
+
+        try:
+            response = await self.client.request(
+                method=method,
+                url=url,
+                params=clean_params,
+                json=json_data,
+                headers=req_headers,
+            )
+        except httpx.TimeoutException as exc:
+            err = NetworkError(
+                get_message("timeout_error", self.locale), details={"original_error": str(exc)}
+            )
+            return CoffeeMailResponse(data=None, error=err, status_code=None)
+        except httpx.RequestError as exc:
+            err = NetworkError(
+                get_message("network_error", self.locale), details={"original_error": str(exc)}
+            )
+            return CoffeeMailResponse(data=None, error=err, status_code=None)
+
+        if not response.is_success:
+            body: dict[str, object] = {"message": response.text}
+            try:
+                parsed_body = response.json()
+                if isinstance(parsed_body, dict):
+                    body = parsed_body
+            except Exception:
+                pass
+            error = create_error_from_response(response.status_code, body)
+            return CoffeeMailResponse(data=None, error=error, status_code=response.status_code)
+
+        data: dict[str, object] = {}
+        if response.content:
+            try:
+                parsed_data = response.json()
+                if isinstance(parsed_data, dict):
+                    data = parsed_data
+            except Exception:
+                data = {}
+
+        return CoffeeMailResponse(data=data, error=None, status_code=response.status_code)
+
+    async def introspect(
+        self, force_refresh: bool = False
+    ) -> CoffeeMailResponse[ApiKeyIntrospection]:
+        now = time.time()
+        if (
+            not force_refresh
+            and self._cached_introspection
+            and now < self._introspection_expires_at
+        ):
+            return CoffeeMailResponse(data=self._cached_introspection, error=None, status_code=200)
+
+        raw_response = await self.request("GET", "/v1/product/auth/me/api-key")
+        if raw_response.error or raw_response.data is None:
+            return CoffeeMailResponse(
+                data=None, error=raw_response.error, status_code=raw_response.status_code
+            )
+
+        introspection = ApiKeyIntrospection.model_validate(raw_response.data)
+        self._cached_introspection = introspection
+        self._introspection_expires_at = now + 300.0
+        return CoffeeMailResponse(
+            data=introspection, error=None, status_code=raw_response.status_code
+        )
+
+    def invalidate_introspection_cache(self) -> None:
+        self._cached_introspection = None
+        self._introspection_expires_at = 0.0

coffeemail/core/i18n.py

@@ -0,0 +1,33 @@
+from typing import Literal
+
+Locale = Literal["pt-BR", "en"]
+
+MESSAGES: dict[str, dict[Locale, str]] = {
+    "missing_api_key": {
+        "pt-BR": "Chave de API ausente. Forneça a chave no construtor ou defina a variável COFFEEMAIL_API_KEY.",
+        "en": "Missing API key. Pass it to the constructor or define COFFEEMAIL_API_KEY environment variable.",
+    },
+    "timeout_error": {
+        "pt-BR": "Tempo limite de conexão esgotado ao contatar o servidor da CoffeeMail.",
+        "en": "Connection timed out while contacting CoffeeMail server.",
+    },
+    "network_error": {
+        "pt-BR": "Falha na comunicação de rede com o servidor da CoffeeMail.",
+        "en": "Network communication failure with CoffeeMail server.",
+    },
+    "invalid_webhook_signature": {
+        "pt-BR": "Assinatura de webhook inválida ou corrompida.",
+        "en": "Invalid or corrupted webhook signature.",
+    },
+    "webhook_timestamp_expired": {
+        "pt-BR": "Timestamp do webhook expirou em relação à tolerância configurada.",
+        "en": "Webhook timestamp expired according to configured tolerance.",
+    },
+}
+
+
+def get_message(key: str, locale: Locale = "pt-BR") -> str:
+    entry = MESSAGES.get(key)
+    if not entry:
+        return key
+    return entry.get(locale, entry.get("pt-BR", key))

coffeemail/core/types.py

@@ -0,0 +1,50 @@
+from collections.abc import Iterator
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from coffeemail.core.errors import CoffeeMailError
+
+T = TypeVar("T")
+
+
+class CoffeeMailResponse(Generic[T]):
+    def __init__(
+        self,
+        data: T | None = None,
+        error: CoffeeMailError | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        self.data = data
+        self.error = error
+        self.status_code = status_code
+
+    @property
+    def is_success(self) -> bool:
+        return self.error is None
+
+    def unwrap(self) -> T:
+        if self.error is not None:
+            raise self.error
+        if self.data is None:
+            raise ValueError("Resposta sem dados disponíveis.")
+        return self.data
+
+    def __iter__(self) -> Iterator[object | None]:
+        yield self.data
+        yield self.error
+
+    def __repr__(self) -> str:
+        return f"CoffeeMailResponse(data={self.data!r}, error={self.error!r}, status_code={self.status_code})"
+
+
+class ApiKeyIntrospection(BaseModel):
+    id: str
+    name: str
+    environment: str
+    scopes: list[str] = Field(default_factory=list)
+    rate_limit: dict[str, object] = Field(default_factory=dict, alias="rateLimit")
+    created_at: str = Field(alias="createdAt")
+    expires_at: str | None = Field(default=None, alias="expiresAt")
+
+    model_config = ConfigDict(populate_by_name=True)