sendly-python 0.1.0__py3-none-any.whl

sendly/resources/suppression.py

@@ -0,0 +1,52 @@
+"""Suppression 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,
+        Query,
+        SuppressionCheckResponse,
+        SuppressionListResponse,
+        SuppressionRecord,
+    )
+
+
+class SuppressionResource:
+    """Manage the project suppression list."""
+
+    def __init__(self, client: Sendly) -> None:
+        self._client = client
+
+    def add(self, body: Body) -> SuppressionRecord:
+        """Add an email to the project suppression list."""
+        envelope = self._client.request(method="POST", path="/api/suppression", body=body)
+        record: SuppressionRecord = self._client.unwrap(envelope)
+        return record
+
+    def list(self, query: Query | None = None) -> SuppressionListResponse:
+        """List suppressions with optional reason filter + cursor pagination."""
+        response: SuppressionListResponse = self._client.request(
+            method="GET", path="/api/suppression", query=query
+        )
+        return response
+
+    def get(self, email: str) -> SuppressionCheckResponse:
+        """Check whether a given email is suppressed."""
+        response: SuppressionCheckResponse = self._client.request(
+            method="GET", path=f"/api/suppression/{encode_path_segment(email)}"
+        )
+        return response
+
+    def remove(self, email: str) -> None:
+        """Remove an email from the suppression list. Returns 204."""
+        self._client.request(
+            method="DELETE",
+            path=f"/api/suppression/{encode_path_segment(email)}",
+            no_content=True,
+        )

sendly/resources/templates.py

@@ -0,0 +1,61 @@
+"""Templates 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,
+        Query,
+        TemplateListResponse,
+        TemplateRecord,
+    )
+
+
+class TemplatesResource:
+    """Create and manage reusable email templates."""
+
+    def __init__(self, client: Sendly) -> None:
+        self._client = client
+
+    def create(self, body: Body) -> TemplateRecord:
+        """Create a reusable email template."""
+        envelope = self._client.request(method="POST", path="/api/templates", body=body)
+        record: TemplateRecord = self._client.unwrap(envelope)
+        return record
+
+    def list(self, query: Query | None = None) -> TemplateListResponse:
+        """List templates with cursor pagination (``limit``/``cursor``) + optional
+        type filter."""
+        response: TemplateListResponse = self._client.request(
+            method="GET", path="/api/templates", query=query
+        )
+        return response
+
+    def get(self, id: str) -> TemplateRecord:
+        """Fetch a single template by id."""
+        envelope = self._client.request(
+            method="GET", path=f"/api/templates/{encode_path_segment(id)}"
+        )
+        record: TemplateRecord = self._client.unwrap(envelope)
+        return record
+
+    def update(self, id: str, body: Body) -> TemplateRecord:
+        """Patch an existing template."""
+        envelope = self._client.request(
+            method="PATCH", path=f"/api/templates/{encode_path_segment(id)}", body=body
+        )
+        record: TemplateRecord = self._client.unwrap(envelope)
+        return record
+
+    def delete(self, id: str) -> None:
+        """Delete a template. Returns ``None`` (the API responds 200 with the
+        deleted template's id); raises :class:`SendlyConflictError` if the
+        template is still referenced."""
+        self._client.request(
+            method="DELETE", path=f"/api/templates/{encode_path_segment(id)}", no_content=True
+        )

sendly/resources/verify.py

@@ -0,0 +1,26 @@
+"""Verify resource."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sendly.client import Sendly
+    from sendly.types import Body, VerifyEmailData
+
+
+class VerifyResource:
+    """Validate email addresses (syntax, MX, disposable, plus-addressing)."""
+
+    def __init__(self, client: Sendly) -> None:
+        self._client = client
+
+    def email(self, body: Body) -> VerifyEmailData:
+        """Validate a single email address.
+
+        The endpoint is open (no auth required server-side); the SDK still sends
+        its usual ``Authorization`` header, which the API harmlessly ignores.
+        """
+        envelope = self._client.request(method="POST", path="/api/verify", body=body)
+        data: VerifyEmailData = self._client.unwrap(envelope)
+        return data

sendly/resources/webhooks.py

@@ -0,0 +1,76 @@
+"""Webhooks 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,
+        Query,
+        WebhookCallsListResponse,
+        WebhookCreateResponse,
+        WebhookGetResponse,
+        WebhookListResponse,
+        WebhookRecord,
+        WebhookRotateSecretResponse,
+    )
+
+
+class WebhooksResource:
+    """Manage outbound webhook subscriptions and inspect deliveries."""
+
+    def __init__(self, client: Sendly) -> None:
+        self._client = client
+
+    def create(self, body: Body) -> WebhookCreateResponse:
+        """Create a new outbound webhook subscription.
+
+        The response includes the signing secret — store it now, it is only
+        returned in full at creation and rotation time.
+        """
+        response: WebhookCreateResponse = self._client.request(
+            method="POST", path="/api/webhooks", body=body
+        )
+        return response
+
+    def list(self) -> WebhookListResponse:
+        """List all webhooks for the project."""
+        response: WebhookListResponse = self._client.request(method="GET", path="/api/webhooks")
+        return response
+
+    def get(self, id: str) -> WebhookGetResponse:
+        """Fetch a single webhook (without its signing secret)."""
+        response: WebhookGetResponse = self._client.request(
+            method="GET", path=f"/api/webhooks/{encode_path_segment(id)}"
+        )
+        return response
+
+    def update(self, id: str, body: Body) -> WebhookRecord:
+        """Patch a webhook (URL, event types, active flag)."""
+        envelope = self._client.request(
+            method="PATCH", path=f"/api/webhooks/{encode_path_segment(id)}", body=body
+        )
+        record: WebhookRecord = self._client.unwrap(envelope)
+        return record
+
+    def delete(self, id: str) -> None:
+        """Delete a webhook."""
+        self._client.request(method="DELETE", path=f"/api/webhooks/{encode_path_segment(id)}")
+
+    def rotate_secret(self, id: str) -> WebhookRotateSecretResponse:
+        """Rotate the webhook signing secret. The response contains the new secret."""
+        response: WebhookRotateSecretResponse = self._client.request(
+            method="POST", path=f"/api/webhooks/{encode_path_segment(id)}/rotate-secret"
+        )
+        return response
+
+    def list_calls(self, id: str, query: Query | None = None) -> WebhookCallsListResponse:
+        """List recent delivery attempts for a webhook."""
+        response: WebhookCallsListResponse = self._client.request(
+            method="GET", path=f"/api/webhooks/{encode_path_segment(id)}/calls", query=query
+        )
+        return response

sendly/types.py

@@ -0,0 +1,84 @@
+"""Type aliases for the Sendly SDK.
+
+The Sendly API speaks JSON. The reference TypeScript SDK layers precise
+OpenAPI-generated types over that JSON but performs no runtime validation — the
+request core simply serializes the body and returns the parsed response. This
+Python port keeps the same thin-client contract: request inputs are accepted as
+loose mappings (so any valid API field flows through without the SDK rejecting
+it) and responses are returned as parsed ``dict`` objects.
+
+The response aliases below are intentionally ``dict[str, Any]`` but are named to
+mirror the TypeScript SDK's ``types.ts`` exports, so the public surface reads the
+same across both SDKs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+# ---------- Generic JSON ----------
+
+JSONValue = Any
+JSONDict = dict[str, Any]
+
+# ---------- Request inputs (typed loosely, like the TS request core) ----------
+
+Body = Mapping[str, Any]
+Query = Mapping[str, Any]
+Headers = Mapping[str, str]
+
+# ---------- Generic envelopes ----------
+
+SuccessEmpty = JSONDict
+Pagination = JSONDict
+
+# ---------- Emails ----------
+
+SendEmailData = JSONDict
+SendEmailResponse = JSONDict
+BatchSendResponse = JSONDict
+EmailRecord = JSONDict
+EmailListResponse = JSONDict
+EmailGetResponse = JSONDict
+
+# ---------- Contacts ----------
+
+ContactRecord = JSONDict
+ContactListResponse = JSONDict
+
+# ---------- Domains ----------
+
+DomainRecord = JSONDict
+DomainListResponse = JSONDict
+DomainVerificationStatus = JSONDict
+
+# ---------- Templates ----------
+
+TemplateRecord = JSONDict
+TemplateListResponse = JSONDict
+
+# ---------- Webhooks ----------
+
+WebhookRecord = JSONDict
+WebhookCreateResponse = JSONDict
+WebhookGetResponse = JSONDict
+WebhookListResponse = JSONDict
+WebhookRotateSecretResponse = JSONDict
+WebhookCallsListResponse = JSONDict
+
+# ---------- Suppression ----------
+
+SuppressionRecord = JSONDict
+SuppressionListResponse = JSONDict
+SuppressionCheckResponse = JSONDict
+
+# ---------- Events ----------
+
+TrackEventData = JSONDict
+TrackEventResponse = JSONDict
+
+# ---------- Verify ----------
+
+VerifyEmailData = JSONDict
+VerifyEmailResponse = JSONDict

sendly/webhook_utils.py

@@ -0,0 +1,127 @@
+"""Sendly webhook signature verification.
+
+Ported 1:1 from the reference implementation (``webhook-utils.ts``). Every
+Sendly webhook delivery is signed and carries two headers:
+
+* ``X-Sendly-Signature`` — the bare (no ``sha256=`` prefix) lowercase hex
+  HMAC-SHA256 of ``f"{timestamp}.{body}"`` using your signing secret.
+* ``X-Sendly-Timestamp`` — the signing time as a **millisecond** Unix epoch
+  (decimal string).
+
+Verification recomputes the HMAC and, by default, rejects deliveries whose
+timestamp is more than :data:`DEFAULT_TOLERANCE_MS` away from now (replay
+protection). Always pass the RAW request body — do not parse JSON first.
+
+Usage::
+
+    from sendly import verify_signature, construct_event
+
+    @app.route("/webhook", methods=["POST"])
+    def webhook():
+        payload = request.get_data()  # raw bytes
+        signature = request.headers.get("X-Sendly-Signature", "")
+        timestamp = request.headers.get("X-Sendly-Timestamp", "")
+        secret = os.environ["SENDLY_WEBHOOK_SECRET"]
+        try:
+            event = construct_event(payload, signature, timestamp, secret)
+        except ValueError:
+            return "Invalid signature", 400
+        if event["event"] == "email.sent":
+            ...
+        return "", 200
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any, Final
+
+#: Default replay-protection window: a delivery whose ``X-Sendly-Timestamp`` is
+#: more than this many milliseconds from now is rejected. Pass ``math.inf`` for
+#: ``tolerance_ms`` to disable the freshness check.
+DEFAULT_TOLERANCE_MS: Final = 5 * 60 * 1000
+
+_TIMESTAMP_PATTERN: Final = re.compile(r"[0-9]+")
+
+
+def verify_signature(
+    payload: bytes | str,
+    signature: str,
+    timestamp: str,
+    secret: str,
+    *,
+    tolerance_ms: float = DEFAULT_TOLERANCE_MS,
+) -> bool:
+    """Return ``True`` if *signature* is valid and *timestamp* is fresh.
+
+    Verification order: reject a non-numeric timestamp, then reject a timestamp
+    outside *tolerance_ms* of now, then constant-time compare the recomputed
+    HMAC. A length mismatch (e.g. a legacy ``sha256=``-prefixed value) compares
+    as ``False``, as does any non-ASCII value — this function returns ``bool``
+    for every str input and never raises on malformed headers.
+
+    Args:
+        payload: Raw request body (``bytes`` or ``str``). Do NOT parse JSON
+            first — pass the body exactly as received.
+        signature: Value of the ``X-Sendly-Signature`` header (bare hex).
+        timestamp: Value of the ``X-Sendly-Timestamp`` header (ms Unix epoch).
+        secret: Webhook signing secret from your Sendly dashboard.
+        tolerance_ms: Maximum allowed difference, in milliseconds, between the
+            timestamp and now. Defaults to :data:`DEFAULT_TOLERANCE_MS`. Pass
+            ``math.inf`` to disable the freshness check.
+    """
+    if _TIMESTAMP_PATTERN.fullmatch(timestamp) is None:
+        return False
+
+    now_ms = int(time.time() * 1000)
+    if abs(now_ms - int(timestamp)) > tolerance_ms:
+        return False
+
+    body = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+    expected = hmac.new(
+        secret.encode(),
+        f"{timestamp}.{body}".encode(),
+        hashlib.sha256,
+    ).hexdigest()
+    # Compare as bytes: `hmac.compare_digest` on *str* raises TypeError for any
+    # non-ASCII character, and the signature is attacker-controlled header data.
+    expected_bytes = expected.encode()
+    try:
+        signature_bytes = signature.encode()
+    except UnicodeEncodeError:  # lone surrogates can never be a valid hex digest
+        return False
+    return hmac.compare_digest(signature_bytes, expected_bytes)
+
+
+def construct_event(
+    payload: bytes | str,
+    signature: str,
+    timestamp: str,
+    secret: str,
+    *,
+    tolerance_ms: float = DEFAULT_TOLERANCE_MS,
+) -> dict[str, Any]:
+    """Verify the signature + timestamp, then parse *payload* as JSON.
+
+    Args:
+        payload: Raw request body (``bytes`` or ``str``). Do NOT parse JSON first.
+        signature: Value of the ``X-Sendly-Signature`` header.
+        timestamp: Value of the ``X-Sendly-Timestamp`` header (ms Unix epoch).
+        secret: Webhook signing secret from your Sendly dashboard.
+        tolerance_ms: See :func:`verify_signature`.
+
+    Returns:
+        The decoded event object.
+
+    Raises:
+        ValueError: If the signature or timestamp does not verify.
+    """
+    if not verify_signature(payload, signature, timestamp, secret, tolerance_ms=tolerance_ms):
+        raise ValueError("Invalid webhook signature")
+    text = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+    event: dict[str, Any] = json.loads(text)
+    return event