sendly-python 0.1.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

sendly/__init__.py

@@ -3,9 +3,17 @@
 Example:
     >>> from sendly import Sendly
     >>> sendly = Sendly()  # reads SENDLY_API_KEY
-    >>> sendly.emails.send(
+    >>> receipt = sendly.emails.send(
     ...     {"from": "a@b.com", "to": "c@d.com", "subject": "hi", "body": "<p>hi</p>"}
     ... )
+    >>> receipt["status"]  # a real delivery state; poll emails.get(receipt["id"])
+    'PENDING'
+
+The same client also speaks the ``/api/v1`` surface — campaigns, segments,
+workflows, analytics, usage, and the v1 event methods:
+
+    >>> for campaign in sendly.campaigns.iter_list({"limit": 100}):
+    ...     print(campaign["name"], campaign["status"])
 """
 
 from __future__ import annotations
@@ -22,14 +30,22 @@ from sendly.errors import (
     SendlyServerError,
     SendlyValidationError,
 )
+from sendly.resources.analytics import AnalyticsResource
+from sendly.resources.campaigns import CampaignsResource
 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.lists import ListsResource
+from sendly.resources.mailboxes import MailboxesResource
+from sendly.resources.projects import ProjectsResource
+from sendly.resources.segments import SegmentsResource
 from sendly.resources.suppression import SuppressionResource
 from sendly.resources.templates import TemplatesResource
+from sendly.resources.usage import UsageResource
 from sendly.resources.verify import VerifyResource
 from sendly.resources.webhooks import WebhooksResource
+from sendly.resources.workflows import WorkflowsResource
 from sendly.webhook_utils import DEFAULT_TOLERANCE_MS, construct_event, verify_signature
 
 __version__ = SDK_VERSION
@@ -38,10 +54,16 @@ __all__ = [
     "DEFAULT_BASE_URL",
     "DEFAULT_TOLERANCE_MS",
     "SDK_VERSION",
+    "AnalyticsResource",
+    "CampaignsResource",
     "ContactsResource",
     "DomainsResource",
     "EmailsResource",
     "EventsResource",
+    "ListsResource",
+    "MailboxesResource",
+    "ProjectsResource",
+    "SegmentsResource",
     "Sendly",
     "SendlyAuthenticationError",
     "SendlyConflictError",
@@ -54,8 +76,10 @@ __all__ = [
     "SendlyValidationError",
     "SuppressionResource",
     "TemplatesResource",
+    "UsageResource",
     "VerifyResource",
     "WebhooksResource",
+    "WorkflowsResource",
     "__version__",
     "construct_event",
     "verify_signature",

sendly/client.py

@@ -7,6 +7,14 @@ Ported from the reference TypeScript SDK's ``client.ts``. Behavioural parity:
 * 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.
+
+One client, two response dialects. The legacy ``/api/*`` resources wrap results
+in ``{success, data}`` and report failures as ``{error: {code, message}}``. The
+``/api/v1/*`` resources (``campaigns``, ``segments``, ``workflows``,
+``analytics``, ``usage``, and the v1 methods on ``events``) return the resource
+body directly — no envelope, so they never call :meth:`Sendly.unwrap` — and
+report failures as RFC 9457 problem documents. Both dialects raise the same
+:class:`~sendly.errors.SendlyError` subclasses.
 """
 
 from __future__ import annotations
@@ -18,15 +26,29 @@ from urllib.parse import urlencode
 
 import httpx
 
-from sendly.errors import SendlyConnectionError, SendlyError, error_from_response
+from sendly.errors import (
+    SendlyConnectionError,
+    SendlyError,
+    error_from_problem,
+    error_from_response,
+    is_problem_document,
+)
+from sendly.resources.analytics import AnalyticsResource
+from sendly.resources.campaigns import CampaignsResource
 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.lists import ListsResource
+from sendly.resources.mailboxes import MailboxesResource
+from sendly.resources.projects import ProjectsResource
+from sendly.resources.segments import SegmentsResource
 from sendly.resources.suppression import SuppressionResource
 from sendly.resources.templates import TemplatesResource
+from sendly.resources.usage import UsageResource
 from sendly.resources.verify import VerifyResource
 from sendly.resources.webhooks import WebhooksResource
+from sendly.resources.workflows import WorkflowsResource
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -37,7 +59,7 @@ if TYPE_CHECKING:
 __all__ = ["DEFAULT_BASE_URL", "SDK_VERSION", "Sendly"]
 
 #: Package version. Kept in sync with ``pyproject.toml``.
-SDK_VERSION = "0.1.0"
+SDK_VERSION = "1.0.0"
 
 #: Default production API base. Override via ``base_url`` for staging/self-hosted.
 DEFAULT_BASE_URL = "https://api.sendly.now"
@@ -56,9 +78,11 @@ def _stringify(value: Any) -> str:
 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.
+    Construct once with an API key and reuse the resource accessors for all
+    calls: ``emails``, ``contacts``, ``events``, ``domains``, ``templates``,
+    ``verify``, ``webhooks``, ``suppression`` and ``lists`` on the legacy
+    surface, plus ``campaigns``, ``segments``, ``workflows``, ``analytics`` and
+    ``usage`` on ``/api/v1``.
 
     Args:
         api_key: Project API key (``sk_*`` for full access, ``pk_*`` for
@@ -112,6 +136,17 @@ class Sendly:
         self.verify = VerifyResource(self)
         self.webhooks = WebhooksResource(self)
         self.suppression = SuppressionResource(self)
+        self.lists = ListsResource(self)
+        # Reads only -- the mailbox writes need a user, which an API key is not.
+        self.mailboxes = MailboxesResource(self)
+        # /api/v1 surface. Same client, same auth; bare resource bodies instead
+        # of the legacy {success, data} envelope, and RFC 9457 problem errors.
+        self.campaigns = CampaignsResource(self)
+        self.segments = SegmentsResource(self)
+        self.workflows = WorkflowsResource(self)
+        self.analytics = AnalyticsResource(self)
+        self.usage = UsageResource(self)
+        self.projects = ProjectsResource(self)
 
     def request(
         self,
@@ -180,7 +215,9 @@ class Sendly:
                 return text
 
         if not response.is_success:
-            self._raise_from_body(response.status_code, parsed)
+            self._raise_from_body(
+                response.status_code, parsed, response.headers.get("content-type")
+            )
 
         return parsed
 
@@ -238,9 +275,16 @@ class Sendly:
                 body = json.loads(text)
             except json.JSONDecodeError:
                 body = None
-        self._raise_from_body(response.status_code, body)
+        self._raise_from_body(response.status_code, body, response.headers.get("content-type"))
+
+    def _raise_from_body(
+        self, status_code: int, body: Any, content_type: str | None = None
+    ) -> NoReturn:
+        # /api/v1 speaks RFC 9457; the legacy surface speaks {success, error}.
+        # Both land on the same exception classes, keyed off the status.
+        if is_problem_document(body, content_type):
+            raise error_from_problem(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")

sendly/errors.py

@@ -3,30 +3,63 @@
 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.
+
+The API speaks two error dialects and both land on the same exception classes:
+
+* legacy ``/api/*`` — ``{success: false, error: {code, message}}``;
+* ``/api/v1/*`` — an RFC 9457 problem document served as
+  ``application/problem+json``. Its ``code`` becomes :attr:`SendlyError.error_code`
+  and its ``detail`` (falling back to ``title``) becomes the message, so
+  ``except SendlyValidationError`` behaves identically across both surfaces.
+  Two problem-only fields are surfaced additively: :attr:`SendlyError.request_id`
+  and :attr:`SendlyError.field_errors`.
 """
 
 from __future__ import annotations
 
 from typing import Any
 
+#: Media type of an RFC 9457 problem document.
+PROBLEM_CONTENT_TYPE = "application/problem+json"
+
 
 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``.
+        error_code: Machine-readable code from the API error envelope (legacy
+            ``error.code`` or v1 problem ``code``), or a synthesized
+            ``http_<status>`` / ``invalid_response`` / ``connection_error``.
         message: Human-readable message.
-        body: The parsed (or raw) response body, when available.
+        body: The parsed (or raw) response body, when available. For a v1
+            failure this is the whole problem document, so ``type``, ``title``,
+            ``instance`` and any other member stays reachable.
+        request_id: Correlation id from a v1 problem document (``request_id``);
+            ``None`` on the legacy surface. Quote it in support requests.
+        field_errors: Field-level failures from a v1 ``validation_error``
+            problem (``errors``), each ``{pointer, code, message}``; ``None``
+            when the response carried none. The legacy surface puts its own
+            breakdown at ``body["error"]["details"]["errors"]`` instead.
     """
 
-    def __init__(self, status_code: int, error_code: str, message: str, body: Any = None) -> None:
+    def __init__(
+        self,
+        status_code: int,
+        error_code: str,
+        message: str,
+        body: Any = None,
+        *,
+        request_id: str | None = None,
+        field_errors: list[dict[str, Any]] | None = None,
+    ) -> None:
         super().__init__(message)
         self.status_code = status_code
         self.error_code = error_code
         self.message = message
         self.body = body
+        self.request_id = request_id
+        self.field_errors = field_errors
 
 
 class SendlyValidationError(SendlyError):
@@ -69,24 +102,95 @@ class SendlyConnectionError(SendlyError):
         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)
+def _error_class(status_code: int) -> type[SendlyError]:
+    """The exception class a status maps to. Shared by both error dialects."""
+    if status_code in (400, 422):
+        return SendlyValidationError
     if status_code == 401:
-        return SendlyAuthenticationError(status_code, error_code, message, body)
+        return SendlyAuthenticationError
     if status_code == 403:
-        return SendlyPermissionError(status_code, error_code, message, body)
+        return SendlyPermissionError
     if status_code == 404:
-        return SendlyNotFoundError(status_code, error_code, message, body)
-    if status_code == 422:
-        return SendlyValidationError(status_code, error_code, message, body)
+        return SendlyNotFoundError
     if status_code == 409:
-        return SendlyConflictError(status_code, error_code, message, body)
+        return SendlyConflictError
     if status_code == 429:
-        return SendlyRateLimitError(status_code, error_code, message, body)
+        return SendlyRateLimitError
     if status_code >= 500:
-        return SendlyServerError(status_code, error_code, message, body)
-    return SendlyError(status_code, error_code, message, body)
+        return SendlyServerError
+    return SendlyError
+
+
+def error_from_response(
+    status_code: int,
+    error_code: str,
+    message: str,
+    body: Any = None,
+    *,
+    request_id: str | None = None,
+    field_errors: list[dict[str, Any]] | None = None,
+) -> SendlyError:
+    """Map an HTTP status + error envelope to the appropriate error subclass."""
+    return _error_class(status_code)(
+        status_code,
+        error_code,
+        message,
+        body,
+        request_id=request_id,
+        field_errors=field_errors,
+    )
+
+
+def is_problem_document(body: Any, content_type: str | None = None) -> bool:
+    """Is this response body an RFC 9457 problem document?
+
+    Trusts the ``application/problem+json`` content type when present, and
+    otherwise falls back to the document shape (``type`` + ``title`` + ``code``),
+    so a proxy that rewrites the media type cannot downgrade a v1 error into the
+    generic ``http_<status>`` path. The legacy ``{success, error}`` envelope
+    carries none of those members, so it can never match.
+    """
+    if not isinstance(body, dict):
+        return False
+    if content_type and PROBLEM_CONTENT_TYPE in content_type.lower():
+        return True
+    return all(isinstance(body.get(key), str) for key in ("type", "title", "code"))
+
+
+def error_from_problem(status_code: int, problem: dict[str, Any]) -> SendlyError:
+    """Map an RFC 9457 problem document to the exception class for its status.
+
+    ``code`` supplies the machine-readable :attr:`SendlyError.error_code` and
+    ``detail`` the message, falling back to ``title`` — a problem document always
+    carries a title but only sometimes an occurrence-specific detail.
+    """
+    raw_code = problem.get("code")
+    code = raw_code if isinstance(raw_code, str) and raw_code else f"http_{status_code}"
+
+    message = ""
+    for key in ("detail", "title"):
+        value = problem.get(key)
+        if isinstance(value, str) and value:
+            message = value
+            break
+    if not message:
+        message = f"Sendly request failed with status {status_code}"
+
+    raw_request_id = problem.get("request_id")
+    request_id = raw_request_id if isinstance(raw_request_id, str) else None
+
+    raw_errors = problem.get("errors")
+    field_errors = (
+        [item for item in raw_errors if isinstance(item, dict)]
+        if isinstance(raw_errors, list)
+        else None
+    )
+
+    return error_from_response(
+        status_code,
+        code,
+        message,
+        problem,
+        request_id=request_id,
+        field_errors=field_errors,
+    )

sendly/resources/_pagination.py

@@ -0,0 +1,49 @@
+"""Auto-pagination over the ``/api/v1`` cursor envelope.
+
+Every v1 list endpoint answers with ``{data, has_more, next_cursor}``: an opaque
+forward-only cursor and no total (deliberately — counting a project's rows is a
+scan the API refuses to pay for on every page). :func:`iterate_cursor` walks that
+shape so callers can treat a multi-page listing as one stream of items.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator
+
+    from sendly.types import JSONDict, Query
+
+
+def iterate_cursor(
+    fetch: Callable[[dict[str, Any]], Any],
+    query: Query | None = None,
+) -> Iterator[JSONDict]:
+    """Yield every item across the pages ``fetch`` returns.
+
+    ``fetch`` receives the query for one page — the caller's own filters, plus
+    the ``after`` cursor from page two onward — and returns the raw cursor
+    envelope. Iteration stops when ``has_more`` is false or ``next_cursor`` is
+    ``None``, and also when a page carries no ``data`` list, so a malformed
+    response ends the walk instead of looping forever.
+
+    The caller's filters are held fixed for the whole walk on purpose: changing
+    them mid-pagination invalidates the cursor and the API answers ``422
+    validation_error`` telling you to restart from the first page.
+    """
+    params = dict(query or {})
+    while True:
+        page = fetch(params)
+        if not isinstance(page, dict):
+            return
+        items = page.get("data")
+        if not isinstance(items, list):
+            return
+        yield from items
+        if not page.get("has_more"):
+            return
+        cursor = page.get("next_cursor")
+        if not cursor:
+            return
+        params = {**params, "after": cursor}

sendly/resources/analytics.py

@@ -0,0 +1,49 @@
+"""Analytics resource (``/api/v1``)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sendly.client import Sendly
+    from sendly.types import (
+        AnalyticsTimeseries,
+        CampaignAnalytics,
+        Query,
+        TopCampaignList,
+    )
+
+
+class AnalyticsResource:
+    """Aggregate sending and engagement metrics.
+
+    Every method takes an optional ``from`` / ``to`` window (ISO 8601) and echoes
+    the resolved window back as ``window``, so a caller can tell what the API
+    actually measured when it defaulted the range. None of these are
+    cursor-paginated — they answer a bounded aggregate, not a listing — so there
+    are no iterators here.
+    """
+
+    def __init__(self, client: Sendly) -> None:
+        self._client = client
+
+    def timeseries(self, query: Query | None = None) -> AnalyticsTimeseries:
+        """Per-day sending and engagement counts over the window."""
+        response: AnalyticsTimeseries = self._client.request(
+            method="GET", path="/api/v1/analytics/timeseries", query=query
+        )
+        return response
+
+    def campaigns(self, query: Query | None = None) -> CampaignAnalytics:
+        """Campaign totals for the window: counts plus average open/click rates."""
+        response: CampaignAnalytics = self._client.request(
+            method="GET", path="/api/v1/analytics/campaigns", query=query
+        )
+        return response
+
+    def top_campaigns(self, query: Query | None = None) -> TopCampaignList:
+        """Best-performing campaigns in the window. Accepts ``limit``."""
+        response: TopCampaignList = self._client.request(
+            method="GET", path="/api/v1/analytics/top-campaigns", query=query
+        )
+        return response

sendly/resources/campaigns.py

@@ -0,0 +1,135 @@
+"""Campaigns resource (``/api/v1``)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sendly.resources._helpers import encode_path_segment, idempotency_headers
+from sendly.resources._pagination import iterate_cursor
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from sendly.client import Sendly
+    from sendly.types import (
+        Body,
+        CampaignDeleted,
+        CampaignList,
+        CampaignRecord,
+        CampaignStats,
+        JSONDict,
+        Query,
+    )
+
+
+class CampaignsResource:
+    """Create, schedule, and run bulk email campaigns.
+
+    A campaign moves through ``DRAFT`` -> ``SENDING`` -> ``SENT``; :meth:`send`
+    starts it (optionally at a future time), and :meth:`pause` / :meth:`resume` /
+    :meth:`cancel` steer it while in flight. Responses are bare v1 resource
+    bodies — there is no ``{success, data}`` envelope to unwrap.
+    """
+
+    def __init__(self, client: Sendly) -> None:
+        self._client = client
+
+    def list(self, query: Query | None = None) -> CampaignList:
+        """List campaigns, newest first.
+
+        Accepts ``limit`` (1-100, default 20) and ``after`` (opaque cursor), and
+        answers ``{data, has_more, next_cursor}``. Keep the filters identical for
+        every page of one walk — changing them invalidates the cursor and the API
+        answers 422 ``validation_error`` telling you to restart from the first
+        page. :meth:`iter_list` does that bookkeeping for you.
+        """
+        response: CampaignList = self._client.request(
+            method="GET", path="/api/v1/campaigns", query=query
+        )
+        return response
+
+    def iter_list(self, query: Query | None = None) -> Iterator[JSONDict]:
+        """Iterate every campaign across pages, following the cursor for you."""
+        return iterate_cursor(self.list, query)
+
+    def create(self, body: Body, *, idempotency_key: str | None = None) -> CampaignRecord:
+        """Create a campaign in ``DRAFT``.
+
+        Requires ``name``, ``subject``, ``body``, ``from`` and ``audience_type``.
+        Pass ``idempotency_key`` (1-255 chars) to make a replayed create return
+        the original campaign instead of a second one.
+        """
+        response: CampaignRecord = self._client.request(
+            method="POST",
+            path="/api/v1/campaigns",
+            body=body,
+            headers=idempotency_headers(idempotency_key),
+        )
+        return response
+
+    def get(self, id: str) -> CampaignRecord:
+        """Fetch a single campaign, including its delivery ``stats``."""
+        response: CampaignRecord = self._client.request(
+            method="GET", path=f"/api/v1/campaigns/{encode_path_segment(id)}"
+        )
+        return response
+
+    def update(self, id: str, body: Body) -> CampaignRecord:
+        """Patch a draft campaign's content or audience."""
+        response: CampaignRecord = self._client.request(
+            method="PATCH", path=f"/api/v1/campaigns/{encode_path_segment(id)}", body=body
+        )
+        return response
+
+    def delete(self, id: str) -> CampaignDeleted:
+        """Delete a campaign. Returns the ``{id, deleted}`` confirmation body."""
+        response: CampaignDeleted = self._client.request(
+            method="DELETE", path=f"/api/v1/campaigns/{encode_path_segment(id)}"
+        )
+        return response
+
+    def send(
+        self, id: str, body: Body | None = None, *, idempotency_key: str | None = None
+    ) -> CampaignRecord:
+        """Send a campaign now, or schedule it.
+
+        Pass ``{"scheduled_for": "<ISO 8601>"}`` as ``body`` to queue it for a
+        future time instead of sending immediately. ``idempotency_key`` is the
+        guard that matters most on this call: a replayed send must not mail the
+        audience twice.
+        """
+        response: CampaignRecord = self._client.request(
+            method="POST",
+            path=f"/api/v1/campaigns/{encode_path_segment(id)}/send",
+            body=body,
+            headers=idempotency_headers(idempotency_key),
+        )
+        return response
+
+    def cancel(self, id: str) -> CampaignRecord:
+        """Cancel a scheduled or in-flight campaign. Already-sent mail stays sent."""
+        response: CampaignRecord = self._client.request(
+            method="POST", path=f"/api/v1/campaigns/{encode_path_segment(id)}/cancel"
+        )
+        return response
+
+    def pause(self, id: str) -> CampaignRecord:
+        """Pause an in-flight campaign, holding the remaining recipients."""
+        response: CampaignRecord = self._client.request(
+            method="POST", path=f"/api/v1/campaigns/{encode_path_segment(id)}/pause"
+        )
+        return response
+
+    def resume(self, id: str) -> CampaignRecord:
+        """Resume a paused campaign from where it stopped."""
+        response: CampaignRecord = self._client.request(
+            method="POST", path=f"/api/v1/campaigns/{encode_path_segment(id)}/resume"
+        )
+        return response
+
+    def stats(self, id: str) -> CampaignStats:
+        """Delivery and engagement counters plus derived rates for one campaign."""
+        response: CampaignStats = self._client.request(
+            method="GET", path=f"/api/v1/campaigns/{encode_path_segment(id)}/stats"
+        )
+        return response

sendly/resources/domains.py

@@ -12,6 +12,7 @@ if TYPE_CHECKING:
         Body,
         DomainListResponse,
         DomainRecord,
+        DomainSetupSession,
         DomainVerificationStatus,
     )
 
@@ -62,6 +63,21 @@ class DomainsResource:
         status: DomainVerificationStatus = self._client.unwrap(envelope)
         return status
 
+    def start_setup(self, id: str) -> DomainSetupSession:
+        """Start the guided DNS setup hand-off for a domain.
+
+        Returns the session as the route returns it: a ``connectUrl`` to open in
+        a browser, the ``token`` that url carries, and ``expiresAt``. Nothing is
+        derived or reshaped -- finishing setup means a person visiting that url
+        and authorising the change at their registrar, so the SDK's job is to
+        hand back the link, not to model the flow behind it.
+        """
+        envelope = self._client.request(
+            method="POST", path=f"/api/domains/{encode_path_segment(id)}/dodomain-session"
+        )
+        session: DomainSetupSession = self._client.unwrap(envelope)
+        return session
+
     def delete(self, id: str) -> None:
         """Delete a domain."""
         self._client.request(method="DELETE", path=f"/api/domains/{encode_path_segment(id)}")