mailfloss 0.1.0__py3-none-any.whl

mailfloss/__init__.py

@@ -0,0 +1,22 @@
+"""Official Mailfloss Python SDK.
+
+Usage::
+
+    from mailfloss import Mailfloss
+
+    client = Mailfloss(api_key="mf_rk_...")  # or set MAILFLOSS_API_KEY
+    result = client.verify("jane@example.com")
+"""
+
+from .client import DEFAULT_BASE_URL, Mailfloss
+from .errors import MailflossConfigError, MailflossError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Mailfloss",
+    "MailflossError",
+    "MailflossConfigError",
+    "DEFAULT_BASE_URL",
+    "__version__",
+]

mailfloss/_transport.py

@@ -0,0 +1,38 @@
+"""Default HTTP transport built on the standard library only.
+
+A transport is any callable with the signature::
+
+    transport(method, url, headers, body, timeout) -> (status, headers, body)
+
+where ``body`` (request) is ``bytes`` or ``None``, the returned ``status`` is
+an ``int``, the returned ``headers`` is a ``dict`` (case as sent by the
+server), and the returned ``body`` is ``bytes``. HTTP-level error statuses
+(4xx/5xx) must be RETURNED, not raised; only network/connection failures may
+raise (``OSError`` and subclasses).
+"""
+
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from typing import Dict, Optional, Tuple
+
+__all__ = ["urllib_transport"]
+
+
+def urllib_transport(
+    method: str,
+    url: str,
+    headers: Dict[str, str],
+    body: Optional[bytes],
+    timeout: float,
+) -> Tuple[int, Dict[str, str], bytes]:
+    """Perform an HTTP request with ``urllib.request``."""
+    request = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return response.status, dict(response.headers.items()), response.read()
+    except urllib.error.HTTPError as exc:
+        # Non-2xx responses: surface as data, not as an exception.
+        payload = exc.read() if exc.fp is not None else b""
+        return exc.code, dict(exc.headers.items()), payload

mailfloss/client.py

@@ -0,0 +1,264 @@
+"""The Mailfloss client: configuration, auth, retries, and the HTTP core."""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+import uuid
+from typing import Any, Callable, Dict, Mapping, Optional, Tuple, Union
+
+from ._transport import urllib_transport
+from .errors import MailflossConfigError, MailflossError
+from .resources import (
+    AccountResource,
+    BatchVerifyResource,
+    ErasuresResource,
+    IntegrationsResource,
+    JobsResource,
+    OrganizationResource,
+    ReportsResource,
+    UsersResource,
+)
+from .types import CheckKeyResult, VerifyResult
+
+__all__ = ["Mailfloss", "DEFAULT_BASE_URL"]
+
+VERSION = "0.1.0"
+DEFAULT_BASE_URL = "https://api.mailfloss.com/v1"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+
+_BACKOFF_BASE = 0.5
+_BACKOFF_FACTOR = 2.0
+_BACKOFF_CAP = 8.0
+
+Transport = Callable[
+    [str, str, Dict[str, str], Optional[bytes], float],
+    Tuple[int, Dict[str, str], bytes],
+]
+
+_ENV_API_KEY = "MAILFLOSS_API_KEY"
+
+
+def _urlencode(params: Mapping[str, Any]) -> str:
+    from urllib.parse import quote
+
+    parts = []
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            value = "true" if value else "false"
+        parts.append(f"{quote(str(key), safe='')}={quote(str(value), safe='')}")
+    return "&".join(parts)
+
+
+class Mailfloss:
+    """Client for the Mailfloss v1 API.
+
+    Args:
+        api_key: Your Mailfloss API key. Falls back to the
+            ``MAILFLOSS_API_KEY`` environment variable when omitted.
+        base_url: API base URL (defaults to ``https://api.mailfloss.com/v1``).
+        max_retries: How many times to retry a request that failed with 429,
+            a 5xx status, or a connection error (default 3).
+        timeout: Per-request socket timeout in seconds (default 30).
+        transport: Optional low-level transport callable
+            ``(method, url, headers, body, timeout) -> (status, headers, body)``
+            — injectable for testing. Defaults to a ``urllib``-based transport.
+        sleep: Optional sleep function (defaults to ``time.sleep``) —
+            injectable so retry tests run instantly.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: Optional[Transport] = None,
+        sleep: Optional[Callable[[float], None]] = None,
+    ) -> None:
+        resolved_key = api_key or os.environ.get(_ENV_API_KEY)
+        if not resolved_key:
+            raise MailflossConfigError(
+                "No API key provided. Pass api_key=... to Mailfloss(), or set "
+                f"the {_ENV_API_KEY} environment variable."
+            )
+        self.api_key = resolved_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self._transport: Transport = transport or urllib_transport
+        self._sleep: Callable[[float], None] = sleep or time.sleep
+
+        # Resource namespaces
+        self.batch_verify = BatchVerifyResource(self)
+        self.jobs = JobsResource(self)
+        self.users = UsersResource(self)
+        self.reports = ReportsResource(self)
+        self.account = AccountResource(self)
+        self.organization = OrganizationResource(self)
+        self.integrations = IntegrationsResource(self)
+        self.erasures = ErasuresResource(self)
+
+    # ------------------------------------------------------------------
+    # Top-level endpoints
+    # ------------------------------------------------------------------
+
+    def verify(
+        self,
+        email: str,
+        timeout: Optional[Union[int, float]] = None,
+    ) -> VerifyResult:
+        """Verify a single email address (GET /verify).
+
+        Args:
+            email: The email address to verify.
+            timeout: Optional per-request verification timeout, in seconds
+                (sent to the API — distinct from the client socket timeout).
+        """
+        return self.request(
+            "GET", "/verify", query={"email": email, "timeout": timeout}
+        )
+
+    def check_key(
+        self,
+        api_key: Optional[str] = None,
+        public_key: Optional[str] = None,
+        check_plan: Optional[str] = None,
+        get_token: Optional[str] = None,
+        check_credits: Optional[str] = None,
+    ) -> CheckKeyResult:
+        """Validate an API key and return its account info (GET /check-key)."""
+        return self.request(
+            "GET",
+            "/check-key",
+            query={
+                "api_key": api_key,
+                "public_key": public_key,
+                "check_plan": check_plan,
+                "get_token": get_token,
+                "check_credits": check_credits,
+            },
+        )
+
+    # ------------------------------------------------------------------
+    # HTTP core
+    # ------------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Mapping[str, Any]] = None,
+        json_body: Optional[Any] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        """Send an authenticated request and return the decoded JSON body.
+
+        Retries on 429 / 5xx (honoring ``Retry-After``) and on connection
+        errors, up to ``max_retries`` times. Raises :class:`MailflossError`
+        for any other non-2xx response (or once retries are exhausted).
+        """
+        method = method.upper()
+        url = self.base_url + path
+        if query:
+            encoded = _urlencode(query)
+            if encoded:
+                url = f"{url}?{encoded}"
+
+        headers: Dict[str, str] = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"mailfloss-python/{VERSION}",
+        }
+
+        body: Optional[bytes] = None
+        if json_body is not None:
+            body = json.dumps(json_body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        if method == "POST":
+            # Generated once, so every retry replays the SAME key and the
+            # server can deduplicate.
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+
+        attempt = 0
+        while True:
+            try:
+                status, resp_headers, resp_body = self._transport(
+                    method, url, headers, body, self.timeout
+                )
+            except OSError:
+                # Connection-level failure (urllib.error.URLError is an
+                # OSError subclass). Retry with backoff if budget remains.
+                if attempt >= self.max_retries:
+                    raise
+                self._sleep(self._backoff_delay(attempt, None))
+                attempt += 1
+                continue
+
+            if 200 <= status < 300:
+                return self._decode_success(resp_body)
+
+            if (status == 429 or status >= 500) and attempt < self.max_retries:
+                self._sleep(self._backoff_delay(attempt, resp_headers))
+                attempt += 1
+                continue
+
+            raise self._build_error(status, resp_body)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _decode_success(body: bytes) -> Any:
+        if not body:
+            return None
+        try:
+            return json.loads(body.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return None
+
+    @staticmethod
+    def _build_error(status: int, body: bytes) -> MailflossError:
+        code = "unknown_error"
+        message = ""
+        error_type: Optional[str] = None
+        request_id: Optional[str] = None
+        try:
+            payload = json.loads(body.decode("utf-8"))
+            error = payload["error"]
+            code = error.get("code") or "unknown_error"
+            message = error.get("message") or ""
+            error_type = error.get("type")
+            request_id = error.get("request_id")
+        except (ValueError, UnicodeDecodeError, KeyError, TypeError, AttributeError):
+            message = body.decode("utf-8", errors="replace").strip() or f"HTTP {status}"
+        return MailflossError(
+            status=status,
+            code=code,
+            message=message,
+            type=error_type,
+            request_id=request_id,
+        )
+
+    @staticmethod
+    def _backoff_delay(attempt: int, headers: Optional[Mapping[str, str]]) -> float:
+        if headers:
+            retry_after = None
+            for key, value in headers.items():
+                if key.lower() == "retry-after":
+                    retry_after = value
+                    break
+            if retry_after is not None:
+                try:
+                    return max(0.0, float(int(retry_after.strip())))
+                except (ValueError, AttributeError):
+                    pass  # Non-integer Retry-After → fall back to backoff.
+        ceiling = min(_BACKOFF_CAP, _BACKOFF_BASE * (_BACKOFF_FACTOR ** attempt))
+        return random.uniform(0.0, ceiling)  # Full jitter.

mailfloss/errors.py

@@ -0,0 +1,39 @@
+"""Exception types for the Mailfloss SDK."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+__all__ = ["MailflossError", "MailflossConfigError"]
+
+
+class MailflossConfigError(Exception):
+    """Raised when the client is misconfigured (e.g. no API key available)."""
+
+
+class MailflossError(Exception):
+    """Raised when the Mailfloss API returns a non-2xx response.
+
+    Attributes:
+        status: HTTP status code of the response.
+        code: Stable machine-readable error code (``unknown_error`` when the
+            body could not be parsed as the standard error envelope).
+        message: Human-readable error message.
+        type: Coarse error category (e.g. ``invalid_request_error``).
+        request_id: The ``X-Request-Id`` echoed in the error envelope, if any.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        type: Optional[str] = None,  # noqa: A002 - mirrors the API field name
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(f"[{status}] {code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.type = type
+        self.request_id = request_id