sendclipper 0.1.0__py3-none-any.whl

sendclipper/__init__.py

@@ -0,0 +1,65 @@
+"""
+The official Python SDK for the SendClipper email API.
+
+::
+
+    from sendclipper import SendClipper
+
+    sc = SendClipper("sc_live_...")
+    data, error = sc.emails.send({
+        "from": "hello@send.acme.io",
+        "to": "ada@lumen.io",
+        "subject": "Your receipt",
+        "html": "<p>Thanks for your order.</p>",
+    })
+"""
+
+from ._client import SendClipper
+from ._core import (
+    DEFAULT_BASE_URL,
+    DownloadedFile,
+    ErrorResponse,
+    RequestOptions,
+    Result,
+    Transport,
+    TransportRequest,
+    TransportResponse,
+    urllib_transport,
+)
+from ._errors import (
+    SendClipperApiError,
+    SendClipperConnectionError,
+    SendClipperError,
+    WebhookVerificationError,
+)
+from ._version import __version__
+from ._webhooks import (
+    WEBHOOK_TOLERANCE_SECONDS,
+    parse_signature_header,
+    sign_payload,
+    signature_header,
+    verify_webhook,
+)
+
+__all__ = [
+    "SendClipper",
+    "DEFAULT_BASE_URL",
+    "DownloadedFile",
+    "ErrorResponse",
+    "RequestOptions",
+    "Result",
+    "Transport",
+    "TransportRequest",
+    "TransportResponse",
+    "urllib_transport",
+    "SendClipperError",
+    "SendClipperApiError",
+    "SendClipperConnectionError",
+    "WebhookVerificationError",
+    "verify_webhook",
+    "sign_payload",
+    "signature_header",
+    "parse_signature_header",
+    "WEBHOOK_TOLERANCE_SECONDS",
+    "__version__",
+]

sendclipper/_client.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Mapping, Optional
+
+from ._core import HttpClient, Transport
+from .resources.audience import Audiences, Contacts, Suppressions
+from .resources.domains import Domains
+from .resources.emails import Batch, Emails
+from .resources.mailboxes import Mailboxes
+from .resources.sandboxes import Sandboxes
+from .resources.templates import Templates
+from .resources.webhooks import Webhooks
+from .resources.workspace import ApiKeys, Automations, WorkspaceResource
+
+__all__ = ["SendClipper"]
+
+
+class SendClipper:
+    """
+    The SendClipper API client.
+
+    ::
+
+        from sendclipper import SendClipper
+
+        sc = SendClipper("sc_live_...")  # or SendClipper(): reads SENDCLIPPER_API_KEY
+        data, error = sc.emails.send({
+            "from": "hello@acme.io",
+            "to": "ada@lumen.io",
+            "subject": "Hi",
+            "html": "<p>Hi</p>",
+        })
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        default_headers: Optional[Mapping[str, str]] = None,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        """
+        :param api_key: A ``sc_live_...`` key. Defaults to ``SENDCLIPPER_API_KEY``.
+        :param base_url: Defaults to ``SENDCLIPPER_BASE_URL``, then ``https://sendclipper.com``. No ``/v1``.
+        :param timeout: Per attempt, in seconds.
+        :param max_retries: Retries after a network error, a 429 or a 5xx. A write is
+            only retried with an ``Idempotency-Key``, which the SDK adds to every JSON
+            write, so a retried send can never go out twice.
+        :param default_headers: Sent on every request.
+        :param transport: Your own HTTP sender (a proxy, a test double). Defaults to the standard library.
+        """
+        http = HttpClient(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            transport=transport,
+        )
+        self._http = http
+        #: The API origin requests go to, without ``/v1``.
+        self.base_url = http.base_url
+        self.emails = Emails(http)
+        self.batch = Batch(http)
+        self.domains = Domains(http)
+        self.templates = Templates(http)
+        self.sandboxes = Sandboxes(http)
+        self.webhooks = Webhooks(http)
+        self.contacts = Contacts(http)
+        self.audiences = Audiences(http)
+        self.suppressions = Suppressions(http)
+        self.mailboxes = Mailboxes(http)
+        self.automations = Automations(http)
+        self.workspace = WorkspaceResource(http)
+        self.api_keys = ApiKeys(http)
+
+    def __repr__(self) -> str:
+        return f"SendClipper(base_url={self.base_url!r})"

sendclipper/_core.py

@@ -0,0 +1,454 @@
+from __future__ import annotations
+
+import json
+import os
+import random
+import re
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from dataclasses import dataclass, field
+from email.utils import parsedate_to_datetime
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Generic,
+    Iterator,
+    List,
+    Mapping,
+    Optional,
+    Tuple,
+    TypedDict,
+    TypeVar,
+    Union,
+)
+
+from ._errors import SendClipperApiError, SendClipperConnectionError, to_api_error
+from ._version import __version__
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DownloadedFile",
+    "ErrorResponse",
+    "Query",
+    "RequestOptions",
+    "Result",
+    "Transport",
+    "TransportRequest",
+    "TransportResponse",
+    "urllib_transport",
+]
+
+DEFAULT_BASE_URL = "https://sendclipper.com"
+
+T = TypeVar("T")
+
+Query = Mapping[str, Union[str, int, float, bool, None]]
+
+
+class RequestOptions(TypedDict, total=False):
+    """Keyword arguments every API method takes after its own parameters."""
+
+    #: Your own key, reused when YOU retry the same logical call later.
+    idempotency_key: str
+    #: Override the client's per-attempt timeout (seconds) for this call.
+    timeout: float
+    #: Override the client's retry count for this call.
+    max_retries: int
+    #: Extra headers for this call.
+    headers: Mapping[str, str]
+
+
+@dataclass(frozen=True)
+class ErrorResponse:
+    """What an API refusal or a network failure looks like."""
+
+    #: SendClipper's machine-readable code: ``domain_not_verified``, ``validation_failed``,
+    #: ``rate_limited``, ``network_error``, ...
+    name: str
+    #: A sentence meant for a person.
+    message: str
+    #: The HTTP status, or ``None`` when no answer arrived (network, timeout).
+    status_code: Optional[int]
+    #: Extra, code-specific facts (e.g. the missing template tags).
+    detail: Any = None
+
+
+class Result(Generic[T]):
+    """
+    Every API method returns one. Exactly one of ``data`` and ``error`` is set.
+
+    It unpacks to ``(data, error)``::
+
+        data, error = sc.emails.send({...})
+    """
+
+    __slots__ = ("data", "error", "headers")
+
+    def __init__(self, data: Optional[T], error: Optional[ErrorResponse], headers: Optional[Dict[str, str]]) -> None:
+        self.data = data
+        self.error = error
+        #: The response headers (lower-case names), or ``None`` when no answer arrived.
+        self.headers = headers
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+    def unwrap(self) -> T:
+        """Return ``data``, or raise the error as ``SendClipperApiError``."""
+        if self.error is not None:
+            e = self.error
+            raise SendClipperApiError(e.status_code or 0, e.name, e.message, e.detail, self.headers)
+        return self.data  # type: ignore[return-value]
+
+    def __iter__(self) -> Iterator[Any]:
+        yield self.data
+        yield self.error
+
+    def __repr__(self) -> str:
+        if self.error is not None:
+            return f"Result(error={self.error!r})"
+        return f"Result(data={self.data!r})"
+
+
+@dataclass(frozen=True)
+class DownloadedFile:
+    """What a download returns."""
+
+    content: bytes
+    content_type: Optional[str]
+    filename: Optional[str]
+
+
+@dataclass
+class TransportRequest:
+    method: str
+    url: str
+    headers: Dict[str, str]
+    body: Optional[bytes]
+    #: Seconds.
+    timeout: float
+
+
+@dataclass
+class TransportResponse:
+    status: int
+    #: Lower-case header names.
+    headers: Dict[str, str] = field(default_factory=dict)
+    body: bytes = b""
+
+
+#: Sends one request. Raise ``TimeoutError`` for a timeout and any other
+#: exception when no answer arrived; return the response for every status.
+Transport = Callable[[TransportRequest], TransportResponse]
+
+
+class _SameHostRedirects(urllib.request.HTTPRedirectHandler):
+    """Follow redirects, but never carry the API key to another host."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        new = super().redirect_request(req, fp, code, msg, headers, newurl)
+        if new is not None and urllib.parse.urlsplit(newurl).netloc != urllib.parse.urlsplit(req.full_url).netloc:
+            new.remove_header("Authorization")
+        return new
+
+
+_opener = urllib.request.build_opener(_SameHostRedirects())
+
+
+def urllib_transport(req: TransportRequest) -> TransportResponse:
+    """The default transport: the standard library, no dependencies."""
+    r = urllib.request.Request(req.url, data=req.body, method=req.method, headers=req.headers)
+    try:
+        with _opener.open(r, timeout=req.timeout) as resp:
+            return TransportResponse(resp.status, _lower_headers(resp.headers.items()), resp.read())
+    except urllib.error.HTTPError as e:
+        try:
+            body = e.read()
+        finally:
+            e.close()
+        return TransportResponse(e.code, _lower_headers(e.headers.items() if e.headers else []), body)
+    except urllib.error.URLError as e:
+        if isinstance(e.reason, (socket.timeout, TimeoutError)):
+            raise TimeoutError(str(e.reason)) from e
+        raise ConnectionError(str(e.reason)) from e
+    except socket.timeout as e:  # a read that stalled after the headers
+        raise TimeoutError(str(e)) from e
+
+
+_RETRYABLE_STATUS = {408, 429, 500, 502, 503, 504}
+_MAX_RETRY_AFTER_SECONDS = 60.0
+
+
+class HttpClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        default_headers: Optional[Mapping[str, str]] = None,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        self.api_key = api_key if api_key is not None else os.environ.get("SENDCLIPPER_API_KEY")
+        raw = base_url or os.environ.get("SENDCLIPPER_BASE_URL") or DEFAULT_BASE_URL
+        self.base_url = re.sub(r"/v1$", "", raw.rstrip("/"))
+        self.timeout = timeout
+        self.max_retries = max(0, max_retries)
+        self.default_headers = dict(default_headers or {})
+        self.transport: Transport = transport or urllib_transport
+
+    def call(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Query] = None,
+        body: Any = None,
+        form: Optional[Tuple[bytes, str]] = None,
+        as_: str = "json",
+        bearer: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Result[Any]:
+        """The public face of every API method: never raises for an API refusal or a network failure."""
+        try:
+            data, response_headers = self.request(
+                method,
+                path,
+                query=query,
+                body=body,
+                form=form,
+                as_=as_,
+                bearer=bearer,
+                idempotency_key=idempotency_key,
+                timeout=timeout,
+                max_retries=max_retries,
+                headers=headers,
+            )
+            return Result(data, None, response_headers)
+        except SendClipperApiError as err:
+            return Result(
+                None,
+                ErrorResponse(err.code, err.message, err.status, err.detail),
+                dict(err.headers) if err.headers else None,
+            )
+        except SendClipperConnectionError as err:
+            return Result(None, ErrorResponse("network_error", err.message, None), None)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Query] = None,
+        body: Any = None,
+        form: Optional[Tuple[bytes, str]] = None,
+        as_: str = "json",
+        bearer: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Tuple[Any, Dict[str, str]]:
+        """Like ``call()``, but raises ``SendClipperApiError`` / ``SendClipperConnectionError``."""
+        token = bearer or self.api_key
+        if not token:
+            raise SendClipperApiError(
+                401,
+                "api_key_missing",
+                'No SendClipper API key. Pass one to SendClipper("sc_live_...") or set SENDCLIPPER_API_KEY.',
+            )
+
+        url = f"{self.base_url}/v1{path if path.startswith('/') else '/' + path}"
+        pairs = [(k, _query_value(v)) for k, v in (query or {}).items() if v is not None and v != ""]
+        if pairs:
+            url += "?" + urllib.parse.urlencode(pairs)
+
+        out_headers: Dict[str, str] = {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json" if as_ == "json" else "*/*",
+            "User-Agent": f"sendclipper-python/{__version__}",
+            **self.default_headers,
+            **dict(headers or {}),
+        }
+
+        payload: Optional[bytes] = None
+        if form is not None:
+            payload, out_headers["Content-Type"] = form
+        elif body is not None:
+            out_headers["Content-Type"] = "application/json"
+            payload = json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+
+        is_read = method in ("GET", "HEAD")
+        # The API de-duplicates every JSON mutation on this header for 24 hours.
+        # A multipart body is not fingerprinted server-side, so it gets no key
+        # and is never retried.
+        if not is_read and form is None:
+            out_headers["Idempotency-Key"] = idempotency_key or f"sc-python-{uuid.uuid4()}"
+        elif idempotency_key:
+            out_headers["Idempotency-Key"] = idempotency_key
+        can_retry = is_read or "Idempotency-Key" in out_headers
+        retries = max(0, self.max_retries if max_retries is None else max_retries) if can_retry else 0
+        per_attempt = self.timeout if timeout is None else timeout
+
+        attempt = 0
+        while True:
+            try:
+                res = self.transport(TransportRequest(method, url, out_headers, payload, per_attempt))
+            except TimeoutError as err:
+                if attempt < retries:
+                    time.sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise SendClipperConnectionError(
+                    f"SendClipper did not answer within {per_attempt:g} s ({method} {urllib.parse.urlsplit(url).path}).",
+                    err,
+                ) from err
+            except Exception as err:  # noqa: BLE001 - any transport failure is "no answer"
+                if attempt < retries:
+                    time.sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise SendClipperConnectionError(f"Could not reach SendClipper at {self.base_url}: {err}", err) from err
+
+            res_headers = {k.lower(): v for k, v in res.headers.items()}
+            ok = 200 <= res.status < 300
+
+            if not ok and res.status in _RETRYABLE_STATUS and attempt < retries:
+                wait = _retry_after(res_headers)
+                time.sleep(wait if wait is not None else _backoff(attempt))
+                attempt += 1
+                continue
+
+            if not ok:
+                api_err = to_api_error(res.status, _decode(res.body, res_headers), res_headers)
+                # Our own earlier attempt is still running server-side (a timeout
+                # that was not a failure). Its result is replayed once it finishes.
+                if api_err.code == "idempotency_key_in_flight" and attempt < retries:
+                    wait = _retry_after(res_headers)
+                    time.sleep(wait if wait is not None else _backoff(attempt))
+                    attempt += 1
+                    continue
+                raise api_err
+
+            if as_ == "bytes":
+                return (
+                    DownloadedFile(
+                        res.body,
+                        res_headers.get("content-type"),
+                        _filename_of(res_headers.get("content-disposition")),
+                    ),
+                    res_headers,
+                )
+            text = _decode(res.body, res_headers)
+            if as_ == "text":
+                return text, res_headers
+            if not text:
+                return None, res_headers
+            try:
+                return json.loads(text), res_headers
+            except ValueError:
+                return text, res_headers
+
+
+def _query_value(v: Union[str, int, float, bool]) -> str:
+    # The API reads booleans the way JavaScript writes them.
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return str(v)
+
+
+def _backoff(attempt: int) -> float:
+    base = min(8.0, 0.5 * 2.0**attempt)
+    return base / 2 + random.random() * (base / 2)
+
+
+def _retry_after(headers: Mapping[str, str]) -> Optional[float]:
+    raw = headers.get("retry-after")
+    if not raw:
+        return None
+    try:
+        seconds = float(raw)
+        if seconds >= 0:
+            return min(_MAX_RETRY_AFTER_SECONDS, seconds)
+    except ValueError:
+        pass
+    try:
+        at = parsedate_to_datetime(raw).timestamp()
+    except (TypeError, ValueError, IndexError):
+        return None
+    return min(_MAX_RETRY_AFTER_SECONDS, max(0.0, at - time.time()))
+
+
+def _decode(body: bytes, headers: Mapping[str, str]) -> str:
+    m = re.search(r"charset=([\w-]+)", headers.get("content-type", ""), re.I)
+    try:
+        return body.decode(m.group(1) if m else "utf-8", errors="replace")
+    except LookupError:
+        return body.decode("utf-8", errors="replace")
+
+
+def _filename_of(disposition: Optional[str]) -> Optional[str]:
+    if not disposition:
+        return None
+    star = re.search(r"filename\*\s*=\s*(?:UTF-8'')?([^;]+)", disposition, re.I)
+    if star:
+        try:
+            return urllib.parse.unquote(star.group(1).strip().strip('"'), errors="strict")
+        except UnicodeDecodeError:
+            pass
+    plain = re.search(r'filename\s*=\s*"?([^";]+)"?', disposition, re.I)
+    return plain.group(1).strip() if plain else None
+
+
+def _lower_headers(items: Any) -> Dict[str, str]:
+    out: Dict[str, str] = {}
+    for k, v in items:
+        key = k.lower()
+        out[key] = f"{out[key]}, {v}" if key in out else v
+    return out
+
+
+def seg(value: str) -> str:
+    """Percent-encode one path segment."""
+    return urllib.parse.quote(str(value), safe="")
+
+
+def strip_none(params: Optional[Mapping[str, Any]]) -> Dict[str, Any]:
+    return {k: v for k, v in (params or {}).items() if v is not None}
+
+
+def multipart(fields: List[Tuple[str, str]], files: List[Tuple[str, str, str, bytes]]) -> Tuple[bytes, str]:
+    """``multipart/form-data``: ``fields`` are (name, value), ``files`` are (name, filename, type, bytes)."""
+    boundary = f"----sendclipper{uuid.uuid4().hex}"
+    parts: List[bytes] = []
+    for name, value in fields:
+        parts.append(
+            f'--{boundary}\r\nContent-Disposition: form-data; name="{_quote(name)}"\r\n\r\n'.encode("utf-8")
+            + value.encode("utf-8")
+            + b"\r\n"
+        )
+    for name, filename, ctype, content in files:
+        parts.append(
+            (
+                f'--{boundary}\r\nContent-Disposition: form-data; name="{_quote(name)}"; filename="{_quote(filename)}"\r\n'
+                f"Content-Type: {ctype}\r\n\r\n"
+            ).encode("utf-8")
+            + content
+            + b"\r\n"
+        )
+    parts.append(f"--{boundary}--\r\n".encode("utf-8"))
+    return b"".join(parts), f"multipart/form-data; boundary={boundary}"
+
+
+def _quote(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("\r", " ").replace("\n", " ")