broadcast-python 0.1.0__py3-none-any.whl

broadcast_python/resources/subscribers.py

@@ -0,0 +1,72 @@
+from typing import Any, Dict, List
+
+from .base import BaseResource
+
+
+class Subscribers(BaseResource):
+    def list(self, **params: Any) -> Any:
+        """List subscribers, 250 per page with ``pagination`` metadata.
+
+        Filters, all optional and combinable: ``is_active``, ``source``,
+        ``created_after``, ``created_before``, ``tags`` (AND logic), ``email``
+        (partial, case-insensitive), ``confirmation_status``, ``custom_data``
+        (JSONB containment).
+
+        An unparseable ``created_after``/``created_before`` is *ignored* by the
+        server rather than rejected, and comes back as a ``parameter_ignored``
+        warning — so a bad timestamp silently widens the result set unless you
+        check ``result.warnings``.
+        """
+        return self._get("/api/v1/subscribers.json", params)
+
+    def find(self, email: str) -> Any:
+        return self._get("/api/v1/subscribers/find.json", {"email": email})
+
+    def create(self, **attrs: Any) -> Any:
+        """Create or upsert a subscriber.
+
+        Attributes are wrapped under ``subscriber:`` on the wire, except
+        ``double_opt_in`` and ``confirmation_template_id``, which the API
+        expects at the top level.
+
+        ``confirmed_at`` is admin-token only — it backdates the confirmation
+        timestamp when migrating an already-confirmed list off another provider.
+        It is ignored (with a warning) on update.
+
+        ``unsubscribed_at`` is never settable here; use :meth:`unsubscribe`.
+        """
+        double_opt_in = attrs.pop("double_opt_in", None)
+        confirmation_template_id = attrs.pop("confirmation_template_id", None)
+
+        payload: Dict[str, Any] = {"subscriber": attrs}
+        if double_opt_in is not None:
+            payload["double_opt_in"] = double_opt_in
+        if confirmation_template_id is not None:
+            payload["confirmation_template_id"] = confirmation_template_id
+
+        return self._post("/api/v1/subscribers.json", payload)
+
+    def update(self, email: str, **attrs: Any) -> Any:
+        return self._patch("/api/v1/subscribers.json", {"email": email, "subscriber": attrs})
+
+    def add_tags(self, email: str, tags: List[str]) -> Any:
+        return self._post("/api/v1/subscribers/add_tag.json", {"email": email, "tags": tags})
+
+    def remove_tags(self, email: str, tags: List[str]) -> Any:
+        return self._delete("/api/v1/subscribers/remove_tag.json", {"email": email, "tags": tags})
+
+    def activate(self, email: str) -> Any:
+        return self._post("/api/v1/subscribers/activate.json", {"email": email})
+
+    def deactivate(self, email: str) -> Any:
+        return self._post("/api/v1/subscribers/deactivate.json", {"email": email})
+
+    def unsubscribe(self, email: str) -> Any:
+        return self._post("/api/v1/subscribers/unsubscribe.json", {"email": email})
+
+    def resubscribe(self, email: str) -> Any:
+        return self._post("/api/v1/subscribers/resubscribe.json", {"email": email})
+
+    def redact(self, email: str) -> Any:
+        """Irreversible: scrubs personal data while keeping aggregate counts."""
+        return self._post("/api/v1/subscribers/redact.json", {"email": email})

broadcast_python/resources/templates.py

@@ -0,0 +1,34 @@
+from typing import Any, Union
+
+from .base import BaseResource
+
+Id = Union[str, int]
+
+
+class Templates(BaseResource):
+    def list(self, **params: Any) -> Any:
+        return self._get("/api/v1/templates", params)
+
+    def get(self, id: Id) -> Any:  # noqa: A002
+        return self._get("/api/v1/templates/{}".format(id))
+
+    def create(self, **attrs: Any) -> Any:
+        """Create a template. Attributes are wrapped under ``template:``.
+
+        Content: ``label``, ``subject``, ``preheader``, ``body``, ``html_body``.
+
+        Confirmation templates (double opt-in): ``template_purpose``,
+        ``confirmation_text``, ``default_confirmation``, and
+        ``confirmation_page_settings`` — per-state page copy keyed by state,
+        each taking ``{"heading": ..., "body": ...}``.
+
+        Anything the server does not recognise comes back as an
+        ``unrecognized_parameter`` warning rather than an error.
+        """
+        return self._post("/api/v1/templates", {"template": attrs})
+
+    def update(self, id: Id, **attrs: Any) -> Any:  # noqa: A002
+        return self._patch("/api/v1/templates/{}".format(id), {"template": attrs})
+
+    def delete(self, id: Id) -> Any:  # noqa: A002
+        return self._delete("/api/v1/templates/{}".format(id))

broadcast_python/resources/transactionals.py

@@ -0,0 +1,85 @@
+from typing import Any, Dict, Optional, Union
+
+from .base import BaseResource
+
+Id = Union[str, int]
+
+MAX_IDEMPOTENCY_KEY_LENGTH = 255
+
+
+class Transactionals(BaseResource):
+    def create(
+        self,
+        to: str,
+        subject: Optional[str] = None,
+        body: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        preheader: Optional[str] = None,
+        template_id: Optional[Id] = None,
+        include_unsubscribe_link: Optional[bool] = None,
+        double_opt_in: Optional[Any] = None,
+        confirmation_template_id: Optional[Id] = None,
+        subscriber: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        **extra: Any
+    ) -> Any:
+        """Send a transactional email.
+
+        One of ``subject``/``body`` or ``template_id`` is required;
+        ``template_id`` resolves subject and body server-side, and
+        ``subject``/``body`` override the template.
+
+        Idempotency
+        -----------
+        Pass ``idempotency_key`` to make a retry safe. The server stores the
+        response for 24 hours keyed on (token, key) and replays it rather than
+        sending a second email. Check ``result.idempotent_replay`` to tell a
+        replay from a fresh send.
+
+        The key is part of a fingerprint over method + full path + body:
+
+        - same key, same payload, still running -> :class:`ConflictError` (409)
+        - same key, *different* payload         -> :class:`ValidationError` (422)
+
+        That 422 means "this key was already used for something else", not that
+        the email was invalid — do not retry it with the same key.
+        """
+        payload: Dict[str, Any] = {"to": to}
+        for key, value in (
+            ("subject", subject),
+            ("body", body),
+            ("preheader", preheader),
+            ("reply_to", reply_to),
+            ("template_id", template_id),
+            ("include_unsubscribe_link", include_unsubscribe_link),
+            ("double_opt_in", double_opt_in),
+            ("confirmation_template_id", confirmation_template_id),
+            ("subscriber", subscriber),
+        ):
+            if value is not None:
+                payload[key] = value
+        payload.update(extra)
+
+        headers = _idempotency_headers(idempotency_key)
+        return self._post("/api/v1/transactionals.json", payload, headers=headers)
+
+    def get(self, id: Id) -> Any:  # noqa: A002
+        return self._get("/api/v1/transactionals/{}.json".format(id))
+
+
+def _idempotency_headers(key: Optional[str]) -> Dict[str, str]:
+    if key is None:
+        return {}
+
+    trimmed = str(key).strip()
+    if trimmed == "":
+        return {}
+
+    if len(trimmed) > MAX_IDEMPOTENCY_KEY_LENGTH:
+        raise ValueError(
+            "idempotency_key must be {} characters or fewer (got {})".format(
+                MAX_IDEMPOTENCY_KEY_LENGTH, len(trimmed)
+            )
+        )
+
+    return {"Idempotency-Key": trimmed}

broadcast_python/resources/webhook_endpoints.py

@@ -0,0 +1,29 @@
+from typing import Any, Union
+
+from .base import BaseResource
+
+Id = Union[str, int]
+
+
+class WebhookEndpoints(BaseResource):
+    def list(self, **params: Any) -> Any:
+        return self._get("/api/v1/webhook_endpoints", params)
+
+    def get(self, id: Id) -> Any:  # noqa: A002
+        return self._get("/api/v1/webhook_endpoints/{}".format(id))
+
+    def create(self, **attrs: Any) -> Any:
+        """The ``secret`` is returned once, on create, and never again."""
+        return self._post("/api/v1/webhook_endpoints", {"webhook_endpoint": attrs})
+
+    def update(self, id: Id, **attrs: Any) -> Any:  # noqa: A002
+        return self._patch("/api/v1/webhook_endpoints/{}".format(id), {"webhook_endpoint": attrs})
+
+    def delete(self, id: Id) -> Any:  # noqa: A002
+        return self._delete("/api/v1/webhook_endpoints/{}".format(id))
+
+    def test(self, id: Id, event_type: str = "test.webhook") -> Any:  # noqa: A002
+        return self._post("/api/v1/webhook_endpoints/{}/test".format(id), {"event_type": event_type})
+
+    def deliveries(self, id: Id, **params: Any) -> Any:  # noqa: A002
+        return self._get("/api/v1/webhook_endpoints/{}/deliveries".format(id), params)

broadcast_python/response.py

@@ -0,0 +1,160 @@
+"""The value returned by every JSON API call.
+
+``Response`` subclasses ``dict`` rather than wrapping it, so everything that
+works against a parsed body still works — ``result["id"]``, ``isinstance(...,
+dict)``, ``**result``, equality against a plain dict. Transport metadata the API
+sends alongside the body is exposed as attributes.
+
+Python keeps item access and attribute access separate, so this reproduces the
+Ruby gem's design exactly: ``result["status"]`` is the body's field and
+``result.status`` is the HTTP status. (The Node client cannot do this — see its
+README.)
+
+    result = client.subscribers.create(email="a@b.com", foo="bar")
+    result["id"]                   # 42
+    result.warnings                # [Warning_(code='unrecognized_parameter', ...)]
+    result.rate_limit.remaining    # 118
+    result.status                  # 201
+"""
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, NamedTuple, Optional
+
+
+class Warning_(NamedTuple):
+    """A single entry from the API's ``warnings`` array.
+
+    The API raises these on successful 2xx responses when it accepted the
+    request but ignored part of it — an unrecognised parameter, a parameter that
+    only applies in another mode, a value the server overrode.
+
+    ``param`` is a dot-path to the offending parameter (e.g. ``subscriber.foo``).
+    The API never includes submitted values, so a warning is safe to log.
+
+    Named with a trailing underscore to avoid shadowing the builtin ``Warning``.
+    """
+
+    code: Optional[str]
+    param: Optional[str]
+    message: Optional[str]
+
+    def __str__(self) -> str:
+        if self.param:
+            return "[{}] {}: {}".format(self.code, self.param, self.message)
+        return "[{}] {}".format(self.code, self.message)
+
+
+class RateLimit(NamedTuple):
+    """Parsed ``X-RateLimit-*`` headers.
+
+    ``reset`` is the time the current window rolls over, not a duration.
+    """
+
+    limit: int
+    remaining: Optional[int]
+    reset: Optional[datetime]
+
+
+class Response(dict):
+    """A parsed JSON object body plus its transport metadata."""
+
+    __slots__ = ("_rate_limit", "_warnings", "headers", "status")
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.status: Optional[int] = None
+        self.headers: Dict[str, str] = {}
+        self._warnings: Optional[List[Warning_]] = None
+        self._rate_limit: Any = _UNSET
+
+    def _attach(self, status: int, headers: Dict[str, str]) -> "Response":
+        self.status = status
+        # Lower-cased once here so every lookup below is case-insensitive.
+        self.headers = {str(k).lower(): v for k, v in (headers or {}).items()}
+        return self
+
+    @property
+    def warnings(self) -> List[Warning_]:
+        if self._warnings is None:
+            entries = self.get("warnings")
+            entries = entries if isinstance(entries, list) else []
+            self._warnings = [
+                Warning_(code=e.get("code"), param=e.get("param"), message=e.get("message"))
+                for e in entries
+                if isinstance(e, dict)
+            ]
+        return self._warnings
+
+    @property
+    def has_warnings(self) -> bool:
+        return len(self.warnings) > 0
+
+    @property
+    def rate_limit(self) -> Optional[RateLimit]:
+        if self._rate_limit is _UNSET:
+            # A present-but-unparseable limit means the whole block is
+            # untrustworthy, so report no rate limit rather than a RateLimit
+            # whose `limit` is None despite being typed int.
+            limit = _int_or_none(self.headers.get("x-ratelimit-limit"))
+            if limit is None:
+                self._rate_limit = None
+            else:
+                self._rate_limit = RateLimit(
+                    limit=limit,
+                    remaining=_int_or_none(self.headers.get("x-ratelimit-remaining")),
+                    reset=_parse_time(self.headers.get("x-ratelimit-reset")),
+                )
+        return self._rate_limit
+
+    @property
+    def idempotent_replay(self) -> bool:
+        """True when the API replayed a stored response for a repeated
+        Idempotency-Key rather than performing the write again."""
+        return self.headers.get("idempotency-replayed") == "true"
+
+
+class _Unset:
+    pass
+
+
+_UNSET = _Unset()
+
+
+def build_response(parsed: Any, status: int, headers: Dict[str, str]) -> Any:
+    """Wrap a parsed JSON body when it is an object; pass anything else through.
+
+    A bare array body is returned as a plain list and carries no metadata,
+    matching the Ruby gem.
+    """
+    if not isinstance(parsed, dict):
+        return parsed
+
+    return Response(parsed)._attach(status, headers)
+
+
+def _int_or_none(value: Optional[str]) -> Optional[int]:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _parse_time(value: Optional[str]) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        # fromisoformat did not accept a trailing Z until 3.11.
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        pass
+    try:
+        return datetime.strptime(value, "%Y-%m-%dT%H:%M:%S%z")
+    except (TypeError, ValueError):
+        pass
+    # Some proxies send a unix timestamp instead of ISO-8601.
+    try:
+        return datetime.fromtimestamp(int(value), tz=timezone.utc)
+    except (TypeError, ValueError, OSError, OverflowError):
+        return None

broadcast_python/version.py

@@ -0,0 +1,3 @@
+# Kept in sync with pyproject.toml by tests/test_package.py — a User-Agent that
+# lies about its version misattributes server-side client analytics.
+VERSION = "0.1.0"

broadcast_python/webhook.py

@@ -0,0 +1,121 @@
+"""Inbound webhook verification."""
+
+import base64
+import hashlib
+import hmac
+import time
+from typing import Optional
+
+TIMESTAMP_TOLERANCE = 300  # 5 minutes
+
+#: Every event type a webhook endpoint can subscribe to, mirroring
+#: WebhookEndpoint::AVAILABLE_EVENT_TYPES server-side. Use these when creating
+#: an endpoint — an unknown event type is dropped silently.
+EMAIL_EVENTS = (
+    "email.sent",
+    "email.delivered",
+    "email.delivery_delayed",
+    "email.complained",
+    "email.bounced",
+    "email.opened",
+    "email.clicked",
+    "email.failed",
+)
+
+SUBSCRIBER_EVENTS = (
+    "subscriber.created",
+    "subscriber.updated",
+    "subscriber.deleted",
+    "subscriber.subscribed",
+    "subscriber.unsubscribed",
+    "subscriber.bounced",
+    "subscriber.complained",
+)
+
+BROADCAST_EVENTS = (
+    "broadcast.scheduled",
+    "broadcast.queueing",
+    "broadcast.sending",
+    "broadcast.sent",
+    "broadcast.failed",
+    "broadcast.partial_failure",
+    "broadcast.aborted",
+    "broadcast.paused",
+)
+
+SEQUENCE_EVENTS = (
+    "sequence.subscriber_added",
+    "sequence.subscriber_completed",
+    "sequence.subscriber_moved",
+    "sequence.subscriber_removed",
+    "sequence.subscriber_paused",
+    "sequence.subscriber_resumed",
+    "sequence.subscriber_error",
+)
+
+#: Delivery-machinery events, not content events.
+SYSTEM_EVENTS = ("message.attempt.exhausted", "test.webhook")
+
+EVENT_TYPES = EMAIL_EVENTS + SUBSCRIBER_EVENTS + BROADCAST_EVENTS + SEQUENCE_EVENTS + SYSTEM_EVENTS
+
+
+def verify(
+    payload: str,
+    signature_header: Optional[str],
+    timestamp_header: Optional[str],
+    secret: Optional[str],
+    now: Optional[int] = None,
+) -> bool:
+    """Verify an inbound webhook.
+
+    Returns ``False`` rather than raising for every rejection — a missing
+    header, a stale timestamp, a bad signature. A handler should answer 401 for
+    all of them identically, and distinguishing them invites leaking which check
+    failed.
+
+    ``payload`` must be the raw request body, exactly as received.
+    Re-serialising a parsed object changes the bytes and verification fails.
+    """
+    if payload is None or signature_header is None or timestamp_header is None or secret is None:
+        return False
+
+    try:
+        timestamp = int(timestamp_header)
+    except (TypeError, ValueError):
+        return False
+
+    current_time = int(time.time()) if now is None else int(now)
+    if not timestamp_valid(timestamp, current_time):
+        return False
+
+    actual = extract_signature(signature_header)
+    if actual is None:
+        return False
+
+    return secure_compare(compute_signature(payload, timestamp, secret), actual)
+
+
+def compute_signature(payload: str, timestamp: int, secret: str) -> str:
+    signed_content = "{}.{}".format(timestamp, payload)
+    digest = hmac.new(
+        secret.encode("utf-8") if isinstance(secret, str) else secret,
+        signed_content.encode("utf-8") if isinstance(signed_content, str) else signed_content,
+        hashlib.sha256,
+    ).digest()
+    return base64.b64encode(digest).decode("ascii")
+
+
+def timestamp_valid(timestamp: int, current_time: Optional[int] = None) -> bool:
+    current_time = int(time.time()) if current_time is None else current_time
+    return abs(current_time - timestamp) <= TIMESTAMP_TOLERANCE
+
+
+def extract_signature(header: str) -> Optional[str]:
+    if not header.startswith("v1,"):
+        return None
+    signature = header[len("v1,"):]
+    return signature or None
+
+
+def secure_compare(a: str, b: str) -> bool:
+    return hmac.compare_digest(a, b)