sendly-python 0.1.0__py3-none-any.whl

sendly/__init__.py

@@ -0,0 +1,62 @@
+"""Official Sendly Python SDK.
+
+Example:
+    >>> from sendly import Sendly
+    >>> sendly = Sendly()  # reads SENDLY_API_KEY
+    >>> sendly.emails.send(
+    ...     {"from": "a@b.com", "to": "c@d.com", "subject": "hi", "body": "<p>hi</p>"}
+    ... )
+"""
+
+from __future__ import annotations
+
+from sendly.client import DEFAULT_BASE_URL, SDK_VERSION, Sendly
+from sendly.errors import (
+    SendlyAuthenticationError,
+    SendlyConflictError,
+    SendlyConnectionError,
+    SendlyError,
+    SendlyNotFoundError,
+    SendlyPermissionError,
+    SendlyRateLimitError,
+    SendlyServerError,
+    SendlyValidationError,
+)
+from sendly.resources.contacts import ContactsResource
+from sendly.resources.domains import DomainsResource
+from sendly.resources.emails import EmailsResource
+from sendly.resources.events import EventsResource
+from sendly.resources.suppression import SuppressionResource
+from sendly.resources.templates import TemplatesResource
+from sendly.resources.verify import VerifyResource
+from sendly.resources.webhooks import WebhooksResource
+from sendly.webhook_utils import DEFAULT_TOLERANCE_MS, construct_event, verify_signature
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TOLERANCE_MS",
+    "SDK_VERSION",
+    "ContactsResource",
+    "DomainsResource",
+    "EmailsResource",
+    "EventsResource",
+    "Sendly",
+    "SendlyAuthenticationError",
+    "SendlyConflictError",
+    "SendlyConnectionError",
+    "SendlyError",
+    "SendlyNotFoundError",
+    "SendlyPermissionError",
+    "SendlyRateLimitError",
+    "SendlyServerError",
+    "SendlyValidationError",
+    "SuppressionResource",
+    "TemplatesResource",
+    "VerifyResource",
+    "WebhooksResource",
+    "__version__",
+    "construct_event",
+    "verify_signature",
+]

sendly/client.py

@@ -0,0 +1,252 @@
+"""Sendly SDK client — request core and resource wiring.
+
+Ported from the reference TypeScript SDK's ``client.ts``. Behavioural parity:
+
+* ``Authorization: Bearer <key>``, ``Accept`` and ``User-Agent`` on every request.
+* ``{success, data}`` envelope unwrap (see :meth:`Sendly.unwrap`).
+* Error envelope ``{error: {code, message}}`` mapped to typed exceptions.
+* Query params skip ``None``/empty-string; list values append repeated keys.
+* 204 / No-Content -> ``None``; non-JSON success body -> raw text.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import TYPE_CHECKING, Any, NoReturn
+from urllib.parse import urlencode
+
+import httpx
+
+from sendly.errors import SendlyConnectionError, SendlyError, error_from_response
+from sendly.resources.contacts import ContactsResource
+from sendly.resources.domains import DomainsResource
+from sendly.resources.emails import EmailsResource
+from sendly.resources.events import EventsResource
+from sendly.resources.suppression import SuppressionResource
+from sendly.resources.templates import TemplatesResource
+from sendly.resources.verify import VerifyResource
+from sendly.resources.webhooks import WebhooksResource
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from types import TracebackType
+
+    from sendly.types import Body, Query
+
+__all__ = ["DEFAULT_BASE_URL", "SDK_VERSION", "Sendly"]
+
+#: Package version. Kept in sync with ``pyproject.toml``.
+SDK_VERSION = "0.1.0"
+
+#: Default production API base. Override via ``base_url`` for staging/self-hosted.
+DEFAULT_BASE_URL = "https://api.sendly.now"
+
+#: Sent as the ``User-Agent`` on every request.
+USER_AGENT = f"sendly-python/{SDK_VERSION}"
+
+
+def _stringify(value: Any) -> str:
+    """Render a query value the way the TS SDK's ``String(value)`` does."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+class Sendly:
+    """Sendly SDK entry point.
+
+    Construct once with an API key and reuse the resource accessors
+    (``emails``, ``contacts``, ``events``, ``domains``, ``templates``,
+    ``verify``, ``webhooks``, ``suppression``) for all calls.
+
+    Args:
+        api_key: Project API key (``sk_*`` for full access, ``pk_*`` for
+            sending-only). If omitted, falls back to the ``SENDLY_API_KEY``
+            environment variable; if neither is set, a :class:`SendlyError` is
+            raised (fail-loud — there is no degraded mode).
+        base_url: Override API base URL. Trailing slashes are stripped.
+        timeout: Per-request timeout in seconds (default 30). ``0`` or ``None``
+            disables the timeout. Applied per request, even for an injected client.
+        client: Inject a custom :class:`httpx.Client` (for testing, custom
+            transports, proxies, etc.). If omitted, one is created and owned by
+            this instance.
+        default_headers: Extra headers merged into every request.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | None = 30.0,
+        client: httpx.Client | None = None,
+        default_headers: Mapping[str, str] | None = None,
+    ) -> None:
+        resolved_key = api_key if api_key is not None else os.environ.get("SENDLY_API_KEY")
+        if not resolved_key:
+            raise SendlyError(
+                0,
+                "invalid_options",
+                "Sendly: `api_key` is required. Pass it explicitly or set the "
+                "SENDLY_API_KEY environment variable.",
+            )
+
+        self._api_key = resolved_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout: float | None = timeout if timeout and timeout > 0 else None
+        self._default_headers: dict[str, str] = dict(default_headers or {})
+
+        if client is not None:
+            self._client = client
+            self._owns_client = False
+        else:
+            self._client = httpx.Client()
+            self._owns_client = True
+
+        self.emails = EmailsResource(self)
+        self.contacts = ContactsResource(self)
+        self.events = EventsResource(self)
+        self.domains = DomainsResource(self)
+        self.templates = TemplatesResource(self)
+        self.verify = VerifyResource(self)
+        self.webhooks = WebhooksResource(self)
+        self.suppression = SuppressionResource(self)
+
+    def request(
+        self,
+        *,
+        method: str,
+        path: str,
+        body: Body | None = None,
+        query: Query | None = None,
+        headers: Mapping[str, str] | None = None,
+        no_content: bool = False,
+    ) -> Any:
+        """Low-level request helper.
+
+        Resources call this; consumers can call it directly for endpoints not
+        yet wrapped by a resource. Returns the parsed JSON body of a successful
+        response (the ``{success, data}`` envelope), raw text for a non-JSON
+        success body, or ``None`` for 204 / ``no_content``. Errors are raised as
+        :class:`SendlyError` subclasses based on status.
+        """
+        url = self._build_url(path, query)
+        request_headers: dict[str, str] = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+            **self._default_headers,
+            **(dict(headers) if headers else {}),
+        }
+
+        content: str | None = None
+        if body is not None:
+            request_headers["Content-Type"] = "application/json"
+            content = json.dumps(body)
+
+        try:
+            response = self._client.request(
+                method,
+                url,
+                content=content,
+                headers=request_headers,
+                timeout=self._timeout,
+            )
+        except httpx.HTTPError as exc:
+            raise SendlyConnectionError(f"Sendly request failed: {exc}", exc) from exc
+
+        # 204 No Content or caller-forced no-content (DELETE endpoints, which
+        # now respond 200 with an id body the SDK intentionally discards).
+        if response.status_code == 204 or no_content:
+            if not response.is_success:
+                self._raise_for_error(response)
+            return None
+
+        parsed: Any = None
+        text = response.text
+        if len(text) > 0:
+            try:
+                parsed = json.loads(text)
+            except json.JSONDecodeError:
+                if not response.is_success:
+                    raise error_from_response(
+                        response.status_code,
+                        "invalid_response",
+                        f"Sendly returned non-JSON {response.status_code}: {text[:200]}",
+                        text,
+                    ) from None
+                # Non-JSON success response; caller expects the raw text.
+                return text
+
+        if not response.is_success:
+            self._raise_from_body(response.status_code, parsed)
+
+        return parsed
+
+    def unwrap(self, envelope: Any) -> Any:
+        """Return the ``data`` field of a ``{success, data}`` envelope, else the
+        value unchanged. Centralizing this keeps resource code clean.
+        """
+        if isinstance(envelope, dict) and "data" in envelope:
+            return envelope["data"]
+        return envelope
+
+    def close(self) -> None:
+        """Close the underlying HTTP client, if this instance owns it."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> Sendly:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def _build_url(self, path: str, query: Query | None = None) -> str:
+        if not path.startswith("/"):
+            raise SendlyError(
+                0, "invalid_path", f'Sendly: path must start with "/" (got "{path}").'
+            )
+        url = f"{self._base_url}{path}"
+        if query:
+            params: list[tuple[str, str]] = []
+            for key, value in query.items():
+                if value is None or value == "":
+                    continue
+                if isinstance(value, list | tuple):
+                    for item in value:
+                        if item is None or item == "":
+                            continue
+                        params.append((key, _stringify(item)))
+                else:
+                    params.append((key, _stringify(value)))
+            if params:
+                url = f"{url}?{urlencode(params)}"
+        return url
+
+    def _raise_for_error(self, response: httpx.Response) -> NoReturn:
+        body: Any = None
+        text = response.text
+        if text:
+            try:
+                body = json.loads(text)
+            except json.JSONDecodeError:
+                body = None
+        self._raise_from_body(response.status_code, body)
+
+    def _raise_from_body(self, status_code: int, body: Any) -> NoReturn:
+        error = body.get("error") if isinstance(body, dict) else None
+        error = error if isinstance(error, dict) else {}
+        raw_message = error.get("message")
+        message = (
+            str(raw_message) if raw_message else f"Sendly request failed with status {status_code}"
+        )
+        raw_code = error.get("code")
+        code = str(raw_code) if raw_code else f"http_{status_code}"
+        raise error_from_response(status_code, code, message, body)

sendly/errors.py

@@ -0,0 +1,92 @@
+"""Error hierarchy raised by the Sendly SDK.
+
+Mirrors the TypeScript SDK's ``errors.ts``: a single :class:`SendlyError` base with
+one subclass per meaningful HTTP status so callers can ``except`` a narrow type
+without inspecting the response body.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class SendlyError(Exception):
+    """Base error for any non-2xx HTTP response or transport failure.
+
+    Attributes:
+        status_code: HTTP status (``0`` for client-side/transport failures).
+        error_code: Machine-readable code from the API error envelope, or a
+            synthesized ``http_<status>`` / ``invalid_response`` / ``connection_error``.
+        message: Human-readable message.
+        body: The parsed (or raw) response body, when available.
+    """
+
+    def __init__(self, status_code: int, error_code: str, message: str, body: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.message = message
+        self.body = body
+
+
+class SendlyValidationError(SendlyError):
+    """400 / 422 — request body or query failed validation.
+
+    Migrated routes return ``422`` with a ``VALIDATION_ERROR`` code (and an
+    ``error.details.errors`` list); legacy/malformed-request paths still use
+    ``400``. Both map here so ``except SendlyValidationError`` catches either.
+    """
+
+
+class SendlyAuthenticationError(SendlyError):
+    """401 — missing or invalid ``Authorization`` header."""
+
+
+class SendlyPermissionError(SendlyError):
+    """403 — authenticated but lacks permission for the operation."""
+
+
+class SendlyNotFoundError(SendlyError):
+    """404 — resource does not exist or is not visible to the caller."""
+
+
+class SendlyConflictError(SendlyError):
+    """409 — conflict (already exists, immutable, etc.)."""
+
+
+class SendlyRateLimitError(SendlyError):
+    """429 — rate limited. Honor ``Retry-After`` if present."""
+
+
+class SendlyServerError(SendlyError):
+    """5xx — server-side failure. Generally retryable with backoff."""
+
+
+class SendlyConnectionError(SendlyError):
+    """Transport-level failure (DNS, connect, timeout, parse)."""
+
+    def __init__(self, message: str, body: Any = None) -> None:
+        super().__init__(0, "connection_error", message, body)
+
+
+def error_from_response(
+    status_code: int, error_code: str, message: str, body: Any = None
+) -> SendlyError:
+    """Map an HTTP status + error envelope to the appropriate error subclass."""
+    if status_code == 400:
+        return SendlyValidationError(status_code, error_code, message, body)
+    if status_code == 401:
+        return SendlyAuthenticationError(status_code, error_code, message, body)
+    if status_code == 403:
+        return SendlyPermissionError(status_code, error_code, message, body)
+    if status_code == 404:
+        return SendlyNotFoundError(status_code, error_code, message, body)
+    if status_code == 422:
+        return SendlyValidationError(status_code, error_code, message, body)
+    if status_code == 409:
+        return SendlyConflictError(status_code, error_code, message, body)
+    if status_code == 429:
+        return SendlyRateLimitError(status_code, error_code, message, body)
+    if status_code >= 500:
+        return SendlyServerError(status_code, error_code, message, body)
+    return SendlyError(status_code, error_code, message, body)

sendly/resources/__init__.py

@@ -0,0 +1 @@
+"""Resource accessors for the Sendly SDK, one module per API surface."""

sendly/resources/_helpers.py

@@ -0,0 +1,17 @@
+"""Shared helpers for resource classes."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+
+def encode_path_segment(segment: str) -> str:
+    """Percent-encode a single URL path segment (mirrors JS ``encodeURIComponent``)."""
+    return quote(str(segment), safe="")
+
+
+def idempotency_headers(idempotency_key: str | None) -> dict[str, str] | None:
+    """Build the optional ``Idempotency-Key`` header dict, or ``None`` when unset."""
+    if not idempotency_key:
+        return None
+    return {"Idempotency-Key": idempotency_key}

sendly/resources/contacts.py

@@ -0,0 +1,93 @@
+"""Contacts resource."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sendly.resources._helpers import encode_path_segment, idempotency_headers
+
+if TYPE_CHECKING:
+    from sendly.client import Sendly
+    from sendly.types import (
+        Body,
+        ContactListResponse,
+        ContactRecord,
+        JSONDict,
+        Query,
+    )
+
+
+class ContactsResource:
+    """Create, query, and manage contacts."""
+
+    def __init__(self, client: Sendly) -> None:
+        self._client = client
+
+    def create(self, body: Body, *, idempotency_key: str | None = None) -> ContactRecord:
+        """Create a new contact (fails on duplicate)."""
+        envelope = self._client.request(
+            method="POST",
+            path="/api/contacts",
+            body=body,
+            headers=idempotency_headers(idempotency_key),
+        )
+        record: ContactRecord = self._client.unwrap(envelope)
+        return record
+
+    def upsert(self, body: Body, *, idempotency_key: str | None = None) -> ContactRecord:
+        """Insert or update a contact identified by email."""
+        envelope = self._client.request(
+            method="POST",
+            path="/api/contacts/upsert",
+            body=body,
+            headers=idempotency_headers(idempotency_key),
+        )
+        record: ContactRecord = self._client.unwrap(envelope)
+        return record
+
+    def bulk_create(self, body: Body, *, idempotency_key: str | None = None) -> JSONDict:
+        """Bulk-create contacts (up to API limit). Returns per-row results."""
+        response: JSONDict = self._client.request(
+            method="POST",
+            path="/api/contacts/bulk",
+            body=body,
+            headers=idempotency_headers(idempotency_key),
+        )
+        return response
+
+    def bulk_delete(self, body: Body) -> JSONDict:
+        """Bulk-delete contacts by id or email."""
+        response: JSONDict = self._client.request(
+            method="DELETE", path="/api/contacts/bulk", body=body
+        )
+        return response
+
+    def list(self, query: Query | None = None) -> ContactListResponse:
+        """List contacts with search + cursor pagination."""
+        response: ContactListResponse = self._client.request(
+            method="GET", path="/api/contacts", query=query
+        )
+        return response
+
+    def get(self, id: str) -> ContactRecord:
+        """Fetch a single contact by id."""
+        envelope = self._client.request(
+            method="GET", path=f"/api/contacts/{encode_path_segment(id)}"
+        )
+        record: ContactRecord = self._client.unwrap(envelope)
+        return record
+
+    def update(self, id: str, body: Body) -> ContactRecord:
+        """Patch a contact (partial update of ``data``, ``subscribed``, etc.)."""
+        envelope = self._client.request(
+            method="PATCH", path=f"/api/contacts/{encode_path_segment(id)}", body=body
+        )
+        record: ContactRecord = self._client.unwrap(envelope)
+        return record
+
+    def delete(self, id: str) -> None:
+        """Delete a contact. Returns ``None`` (the API responds 200 with the
+        deleted contact's id)."""
+        self._client.request(
+            method="DELETE", path=f"/api/contacts/{encode_path_segment(id)}", no_content=True
+        )

sendly/resources/domains.py

@@ -0,0 +1,67 @@
+"""Domains resource."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sendly.resources._helpers import encode_path_segment
+
+if TYPE_CHECKING:
+    from sendly.client import Sendly
+    from sendly.types import (
+        Body,
+        DomainListResponse,
+        DomainRecord,
+        DomainVerificationStatus,
+    )
+
+
+class DomainsResource:
+    """Register and verify sending domains."""
+
+    def __init__(self, client: Sendly) -> None:
+        self._client = client
+
+    def create(self, body: Body) -> DomainRecord:
+        """Register a new sending domain.
+
+        Pass ``region`` to pin this domain to a specific AWS SES region. On the
+        first domain for a project this also locks the project's region;
+        subsequent calls must match. The response includes DNS records to set.
+        """
+        envelope = self._client.request(method="POST", path="/api/domains", body=body)
+        record: DomainRecord = self._client.unwrap(envelope)
+        return record
+
+    def list(self) -> DomainListResponse:
+        """List all domains for the project."""
+        response: DomainListResponse = self._client.request(method="GET", path="/api/domains")
+        return response
+
+    def get(self, id: str) -> DomainRecord:
+        """Fetch a single domain."""
+        envelope = self._client.request(
+            method="GET", path=f"/api/domains/{encode_path_segment(id)}"
+        )
+        record: DomainRecord = self._client.unwrap(envelope)
+        return record
+
+    def verify(self, id: str) -> DomainVerificationStatus:
+        """Trigger SES verification for a domain."""
+        envelope = self._client.request(
+            method="POST", path=f"/api/domains/{encode_path_segment(id)}/verify"
+        )
+        status: DomainVerificationStatus = self._client.unwrap(envelope)
+        return status
+
+    def get_verification(self, id: str) -> DomainVerificationStatus:
+        """Read current SES verification status for a domain."""
+        envelope = self._client.request(
+            method="GET", path=f"/api/domains/{encode_path_segment(id)}/verify"
+        )
+        status: DomainVerificationStatus = self._client.unwrap(envelope)
+        return status
+
+    def delete(self, id: str) -> None:
+        """Delete a domain."""
+        self._client.request(method="DELETE", path=f"/api/domains/{encode_path_segment(id)}")

sendly/resources/emails.py

@@ -0,0 +1,73 @@
+"""Emails resource."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sendly.resources._helpers import encode_path_segment, idempotency_headers
+
+if TYPE_CHECKING:
+    from sendly.client import Sendly
+    from sendly.types import (
+        BatchSendResponse,
+        Body,
+        EmailGetResponse,
+        EmailListResponse,
+        Query,
+        SendEmailData,
+        SuccessEmpty,
+    )
+
+
+class EmailsResource:
+    """Send and manage transactional emails."""
+
+    def __init__(self, client: Sendly) -> None:
+        self._client = client
+
+    def send(
+        self, body: Body, *, idempotency_key: str | None = None
+    ) -> SendEmailData | list[SendEmailData]:
+        """Send a single transactional email.
+
+        Pass ``idempotency_key`` (1-255 chars) to dedupe replays for 24h.
+        """
+        envelope = self._client.request(
+            method="POST",
+            path="/api/emails",
+            body=body,
+            headers=idempotency_headers(idempotency_key),
+        )
+        data: SendEmailData | list[SendEmailData] = self._client.unwrap(envelope)
+        return data
+
+    def batch(self, body: Body, *, idempotency_key: str | None = None) -> BatchSendResponse:
+        """Send a batch (up to 100) of transactional emails in one call."""
+        response: BatchSendResponse = self._client.request(
+            method="POST",
+            path="/api/emails/batch",
+            body=body,
+            headers=idempotency_headers(idempotency_key),
+        )
+        return response
+
+    def list(self, query: Query | None = None) -> EmailListResponse:
+        """List emails with cursor-based pagination + filters."""
+        response: EmailListResponse = self._client.request(
+            method="GET", path="/api/emails", query=query
+        )
+        return response
+
+    def get(self, id: str) -> EmailGetResponse:
+        """Fetch a single email and its delivery events."""
+        response: EmailGetResponse = self._client.request(
+            method="GET", path=f"/api/emails/{encode_path_segment(id)}"
+        )
+        return response
+
+    def cancel_schedule(self, id: str) -> SuccessEmpty:
+        """Cancel a scheduled (PENDING) email before it fires."""
+        response: SuccessEmpty = self._client.request(
+            method="DELETE", path=f"/api/emails/{encode_path_segment(id)}/schedule"
+        )
+        return response

sendly/resources/events.py

@@ -0,0 +1,26 @@
+"""Events resource."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sendly.client import Sendly
+    from sendly.types import Body, TrackEventData
+
+
+class EventsResource:
+    """Record custom events for contacts."""
+
+    def __init__(self, client: Sendly) -> None:
+        self._client = client
+
+    def track(self, body: Body) -> TrackEventData:
+        """Record a custom event for a contact.
+
+        Both full (``sk_*``) and sending-only (``pk_*``) keys are accepted.
+        Reserved system event names (e.g. ``email.sent``) are rejected by the API.
+        """
+        envelope = self._client.request(method="POST", path="/api/track", body=body)
+        data: TrackEventData = self._client.unwrap(envelope)
+        return data