broadcast-python 0.1.0__py3-none-any.whl

broadcast_python/errors.py

@@ -0,0 +1,76 @@
+"""Error hierarchy, mirroring broadcast-ruby's lib/broadcast/errors.rb.
+
+Note the shape: ``ValidationError`` and ``TimeoutError`` descend from
+``BroadcastError``, NOT from ``APIError``. That is deliberate and matches the
+Ruby gem — catching ``APIError`` gets you transport and status failures and
+leaves validation to be handled explicitly.
+"""
+
+from typing import Any, List, Optional
+
+
+class BroadcastError(Exception):
+    """Base class for everything this package raises."""
+
+
+class ConfigurationError(BroadcastError):
+    pass
+
+
+class APIError(BroadcastError):
+    pass
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class AuthorizationError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class ConflictError(APIError):
+    """409 — an in-flight request is already using this Idempotency-Key.
+
+    The original request is still processing; retrying after a short pause will
+    either replay its stored response or run fresh if it failed.
+    """
+
+
+class RateLimitError(APIError):
+    """429. ``retry_after`` is the seconds the server asked us to wait."""
+
+    def __init__(self, message: Optional[str] = None, retry_after: Optional[int] = None):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class ValidationError(BroadcastError):
+    pass
+
+
+class TimeoutError(BroadcastError):  # noqa: A001 - mirrors the Ruby gem's name
+    pass
+
+
+class DeliveryError(BroadcastError):
+    pass
+
+
+class WarningError(BroadcastError):
+    """Raised instead of returning when ``warnings_mode`` is ``"raise"`` and a
+    2xx response carried warnings.
+
+    The request DID succeed — the write happened. Callers catching this must
+    not assume anything was rolled back.
+    """
+
+    def __init__(self, warnings: List[Any], response: Any = None):
+        self.warnings = warnings
+        self.response = response
+        joined = "; ".join(str(w) for w in warnings)
+        super().__init__("API returned {} warning(s): {}".format(len(warnings), joined))

broadcast_python/resources/autopilots.py

@@ -0,0 +1,83 @@
+import re
+from typing import Any, Dict, Union
+
+from .base import BaseResource
+
+Id = Union[str, int]
+
+#: The API renders a configured key bullet-masked and never returns the real
+#: value. Writing a masked value back would replace a working credential with
+#: bullets, so :meth:`Autopilots.update` strips it — the same guard as
+#: :mod:`email_servers`.
+REDACTED_KEY_PATTERN = re.compile(r"\A•+\Z")
+
+
+class Autopilots(BaseResource):
+    """Autopilot — AI-generated newsletters.
+
+    Requires the ``autopilot_read`` / ``autopilot_write`` token permissions.
+
+    Sources and tone samples have no API endpoints; they are configured in the
+    web UI. Since :meth:`activate` requires an active source, an autopilot
+    created entirely over the API cannot be activated until a source is added
+    there.
+    """
+
+    def list(self, **params: Any) -> Any:
+        return self._get("/api/v1/autopilots", params)
+
+    def get(self, id: Id) -> Any:  # noqa: A002
+        return self._get("/api/v1/autopilots/{}".format(id))
+
+    def create(self, **attrs: Any) -> Any:
+        """Attributes are wrapped under ``autopilot:``.
+
+        ``name`` is required and unique per channel. ``openrouter_api_key`` is
+        write-only. Scheduling takes ``schedule_frequency`` (daily, weekly,
+        biweekly, monthly), ``schedule_day_of_week``, ``schedule_day_of_month``,
+        ``schedule_time``, ``schedule_timezone``. ``segment_ids`` restricts the
+        newsletter's audience.
+        """
+        return self._post("/api/v1/autopilots", {"autopilot": attrs})
+
+    def update(self, id: Id, **attrs: Any) -> Any:  # noqa: A002
+        """Pass the real key to rotate it, or omit the field. A masked key is dropped."""
+        return self._patch("/api/v1/autopilots/{}".format(id), {"autopilot": self._scrub_key(attrs)})
+
+    def delete(self, id: Id) -> Any:  # noqa: A002
+        return self._delete("/api/v1/autopilots/{}".format(id))
+
+    # --- Lifecycle ---
+
+    def activate(self, id: Id) -> Any:  # noqa: A002
+        """Requires at least one active source, an API key, and a model.
+
+        Raises :class:`ValidationError` naming the missing prerequisites
+        otherwise, comma-joined.
+        """
+        return self._post("/api/v1/autopilots/{}/activate".format(id))
+
+    def pause(self, id: Id) -> Any:  # noqa: A002
+        return self._post("/api/v1/autopilots/{}/pause".format(id))
+
+    def deactivate(self, id: Id) -> Any:  # noqa: A002
+        return self._post("/api/v1/autopilots/{}/deactivate".format(id))
+
+    def trigger_run(self, id: Id) -> Any:  # noqa: A002
+        """Returns 202 — generation is asynchronous, so poll :meth:`runs`."""
+        return self._post("/api/v1/autopilots/{}/trigger_run".format(id))
+
+    def runs(self, id: Id, **params: Any) -> Any:  # noqa: A002
+        """Generation runs, most recent first. Supports ``limit`` and ``offset``."""
+        return self._get("/api/v1/autopilots/{}/runs".format(id), params)
+
+    def _scrub_key(self, attrs: Dict[str, Any]) -> Dict[str, Any]:
+        key = attrs.get("openrouter_api_key")
+        if not isinstance(key, str) or not REDACTED_KEY_PATTERN.match(key):
+            return attrs
+
+        self._warn(
+            "[broadcast-python] Dropped redacted openrouter_api_key from update payload — "
+            "pass the real key or omit the field"
+        )
+        return {k: v for k, v in attrs.items() if k != "openrouter_api_key"}

broadcast_python/resources/base.py

@@ -0,0 +1,44 @@
+"""Shared plumbing for resource classes.
+
+The HTTP helpers are underscore-prefixed so a resource can expose ``get`` and
+``delete`` as its public API without shadowing them.
+"""
+
+from typing import Any, Dict, Optional
+
+
+class BaseResource:
+    def __init__(self, client: Any):
+        self._client = client
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None, raw: bool = False) -> Any:
+        return self._client.request("GET", path, params or {}, raw=raw)
+
+    def _post(
+        self,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        return self._client.request("POST", path, body or {}, headers=headers)
+
+    def _patch(self, path: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        return self._client.request("PATCH", path, body or {})
+
+    def _delete(self, path: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        return self._client.request("DELETE", path, body)
+
+    def _warn(self, message: str) -> None:
+        """Emit through the configured logger, else stderr."""
+        logger = self._client.config.logger
+        if logger is not None:
+            logger.warning(message)
+        else:
+            import sys
+
+            print(message, file=sys.stderr)
+
+
+def compact(mapping: Dict[str, Any]) -> Dict[str, Any]:
+    """Drop None values so an omitted argument never reaches the wire."""
+    return {k: v for k, v in mapping.items() if v is not None}

broadcast_python/resources/broadcasts.py

@@ -0,0 +1,44 @@
+from typing import Any, Union
+
+from .base import BaseResource
+
+Id = Union[str, int]
+
+
+class Broadcasts(BaseResource):
+    def list(self, **params: Any) -> Any:
+        return self._get("/api/v1/broadcasts", params)
+
+    def get(self, id: Id) -> Any:  # noqa: A002 - mirrors the API's parameter name
+        return self._get("/api/v1/broadcasts/{}".format(id))
+
+    def create(self, **attrs: Any) -> Any:
+        return self._post("/api/v1/broadcasts", attrs)
+
+    def update(self, id: Id, **attrs: Any) -> Any:  # noqa: A002
+        return self._patch("/api/v1/broadcasts/{}".format(id), attrs)
+
+    def delete(self, id: Id) -> Any:  # noqa: A002
+        return self._delete("/api/v1/broadcasts/{}".format(id))
+
+    def send(self, id: Id) -> Any:  # noqa: A002
+        """Sends immediately. There is no undo — the API has no unsend."""
+        return self._post("/api/v1/broadcasts/{}/send_broadcast".format(id))
+
+    def schedule(self, id: Id, scheduled_send_at: str, scheduled_timezone: str) -> Any:  # noqa: A002
+        body = {"scheduled_send_at": scheduled_send_at, "scheduled_timezone": scheduled_timezone}
+        # Verb and path stay on one line: the coverage scanner is line-based,
+        # and wrapping the path onto its own line reads as unimplemented.
+        return self._post("/api/v1/broadcasts/{}/schedule_broadcast".format(id), body)
+
+    def cancel_schedule(self, id: Id) -> Any:  # noqa: A002
+        return self._post("/api/v1/broadcasts/{}/cancel_schedule".format(id))
+
+    def statistics(self, id: Id) -> Any:  # noqa: A002
+        return self._get("/api/v1/broadcasts/{}/statistics".format(id))
+
+    def statistics_timeline(self, id: Id, **params: Any) -> Any:  # noqa: A002
+        return self._get("/api/v1/broadcasts/{}/statistics/timeline".format(id), params)
+
+    def statistics_links(self, id: Id, **params: Any) -> Any:  # noqa: A002
+        return self._get("/api/v1/broadcasts/{}/statistics/links".format(id), params)

broadcast_python/resources/discovery.py

@@ -0,0 +1,35 @@
+from typing import Any
+
+from .base import BaseResource
+
+
+class Discovery(BaseResource):
+    """Introspection endpoints.
+
+    Built for agents and CLIs that need to discover what a token can do before
+    acting, and equally useful as a deploy-time smoke check.
+    """
+
+    def whoami(self) -> Any:
+        """Token label, type (channel_scoped or admin_cross_channel), per-resource
+        permissions, and the resolved channel."""
+        return self._get("/api/v1/whoami")
+
+    def status(self) -> Any:
+        """Channel sender config, subscriber counts, and per-feature transmission
+        readiness. Worth calling before a send — ``readiness["broadcasts"]`` false
+        means the channel has no usable email server or sender identity."""
+        return self._get("/api/v1/status")
+
+    def prime(self) -> Any:
+        """Full capability manifest: platform version, token permissions, channel
+        status, the endpoint list the token can reach, rate limit, and usage tips."""
+        return self._get("/api/v1/prime")
+
+    def skill(self) -> str:
+        """Plain-text agent skill manifest (Markdown with YAML front matter),
+        including the safety rules agents are expected to follow.
+
+        Returns a ``str``, not a dict — this endpoint serves ``text/plain``.
+        """
+        return self._get("/api/v1/skill", raw=True)

broadcast_python/resources/email_servers.py

@@ -0,0 +1,68 @@
+import re
+from typing import Any, Dict, Optional, Union
+
+from .base import BaseResource, compact
+
+Id = Union[str, int]
+
+#: Fields the API returns bullet-masked. Round-tripping one of these from a
+#: fetch into an update would replace a working credential with bullets, so
+#: :meth:`EmailServers.update` strips them. This is a data-loss guard.
+REDACTED_FIELDS = (
+    "smtp_password",
+    "aws_access_key_id",
+    "aws_secret_access_key",
+    "outbound_aws_access_key_id",
+    "outbound_aws_secret_access_key",
+    "postmark_api_token",
+    "inboxroad_api_token",
+    "smtp_com_api_key",
+)
+
+#: Matches the API's redaction shape: 8 bullets, or 4-char prefix + bullets + 4-char suffix.
+REDACTED_PATTERN = re.compile(r"\A(?:•{8}|.{0,4}•+.{0,4})\Z")
+
+
+class EmailServers(BaseResource):
+    def list(self, limit: Optional[int] = None, offset: Optional[int] = None) -> Any:
+        return self._get("/api/v1/email_servers", compact({"limit": limit, "offset": offset}))
+
+    def get(self, id: Id) -> Any:  # noqa: A002
+        return self._get("/api/v1/email_servers/{}".format(id))
+
+    def create(self, **attrs: Any) -> Any:
+        return self._post("/api/v1/email_servers", {"email_server": attrs})
+
+    def update(self, id: Id, **attrs: Any) -> Any:  # noqa: A002
+        """Update an email server.
+
+        CAUTION: API responses redact credential fields with bullet characters.
+        Never echo a fetched response back into update — this method scrubs
+        values matching the redaction pattern, but you should pass only the
+        fields you actually want to change.
+        """
+        return self._patch("/api/v1/email_servers/{}".format(id), {"email_server": self._scrub(attrs)})
+
+    def delete(self, id: Id) -> Any:  # noqa: A002
+        return self._delete("/api/v1/email_servers/{}".format(id))
+
+    def test_connection(self, id: Id) -> Any:  # noqa: A002
+        return self._post("/api/v1/email_servers/{}/test_connection".format(id))
+
+    def copy_to_channel(self, id: Id, target_channel_id: Id) -> Any:  # noqa: A002
+        """Requires an admin/system token. In SaaS mode the target channel is
+        scoped to the token creator's account."""
+        body = {"target_channel_id": target_channel_id}
+        return self._post("/api/v1/email_servers/{}/copy_to_channel".format(id), body)
+
+    def _scrub(self, attrs: Dict[str, Any]) -> Dict[str, Any]:
+        scrubbed = {}
+        for key, value in attrs.items():
+            if key in REDACTED_FIELDS and isinstance(value, str) and REDACTED_PATTERN.match(value):
+                self._warn(
+                    "[broadcast-python] Dropped redacted {} from update payload — "
+                    "pass the real credential or omit the field".format(key)
+                )
+                continue
+            scrubbed[key] = value
+        return scrubbed

broadcast_python/resources/migration.py

@@ -0,0 +1,113 @@
+"""Read-only export endpoints under ``/api/migration/v1``.
+
+Two things differ from the v1 API:
+
+1. **Admin tokens only.** Channel-scoped tokens are rejected outright.
+2. **broadcast_channel_id is required on every call.** Set it once via
+   ``Broadcast(broadcast_channel_id=...)`` or ``client.with_channel(id)`` and it
+   is attached automatically; otherwise pass it per call.
+
+On a demo instance (``DEMO_MODE``) this entire API returns 403 for every
+request, valid token or not, so a public demo cannot be used as a token oracle.
+That surfaces here as :class:`AuthorizationError`.
+
+Every list endpoint pages with ``limit`` (1..250, default 250) and ``offset``,
+returning ``{"data": [...], "pagination": {...}}``.
+"""
+
+from typing import Any, Iterator, Union
+
+from .base import BaseResource
+
+Id = Union[str, int]
+
+#: Endpoints that are a plain paginated list of the channel's records.
+COLLECTIONS = (
+    "channels",
+    "subscribers",
+    "templates",
+    "segments",
+    "sequences",
+    "email_servers",
+    "opt_in_forms",
+    "broadcasts",
+    "outbound_receipts",
+    "webhook_endpoints",
+    "tokens",
+    "suppressions",
+    "tags",
+    "users",
+    "link_redirects",
+    "link_clicks",
+    "subscriber_histories",
+    "file_assets",
+)
+
+
+class Migration(BaseResource):
+    def manifest(self, **params: Any) -> Any:
+        """Export summary: format version, channel identity, per-resource counts,
+        and recent-history totals. Call this first to size an export.
+
+        ``days_history`` windows the time-bounded counts; the server clamps to 1..365.
+        """
+        return self._get("/api/migration/v1/manifest", params)
+
+    def download_file_asset(self, id: Id, **params: Any) -> bytes:  # noqa: A002
+        """Binary contents of a stored file asset — bytes, not JSON."""
+        return self._get("/api/migration/v1/file_assets/{}/download".format(id), params, raw=True)
+
+    def each_record(self, collection: str, limit: int = 250, **params: Any) -> Iterator[Any]:
+        """Page through a collection, yielding each record.
+
+            for sub in client.migration.each_record("subscribers"):
+                ...
+
+        Stops when the server reports ``has_more: False``, and advances by the
+        limit the server actually applied rather than the one requested — the
+        server clamps to 250, so trusting the request would skip records.
+        """
+        offset = 0
+        while True:
+            page = getattr(self, collection)(limit=limit, offset=offset, **params)
+            records = page.get("data") or []
+            yield from records
+
+            pagination = page.get("pagination") or {}
+            if not pagination.get("has_more"):
+                return
+
+            # `pagination.get("limit") or len(records)` would be wrong: Python's
+            # `or` falls back on any falsy value, so a server-reported limit of
+            # 0 would become len(records) and the loop would never terminate.
+            # Ruby's `||` only falls back on nil, which is why the reference
+            # implementation can spell it that way and this one cannot.
+            advanced = pagination.get("limit")
+            if advanced is None:
+                advanced = len(records)
+
+            try:
+                advanced = int(advanced)
+            except (TypeError, ValueError):
+                return
+            if advanced <= 0:
+                return
+
+            offset += advanced
+
+
+def _make_collection_method(name: str):
+    def method(self, **params: Any) -> Any:
+        return self._get("/api/migration/v1/{}".format(name), params)
+
+    method.__name__ = name
+    method.__qualname__ = "Migration.{}".format(name)
+    method.__doc__ = "Paginated export of the channel's {}.".format(name.replace("_", " "))
+    return method
+
+
+# Generated rather than hand-written: 18 near-identical methods invite the kind
+# of copy-paste drift this whole SDK family exists to prevent. Declared in
+# .api-coverage.yml so the coverage report still counts them.
+for _collection in COLLECTIONS:
+    setattr(Migration, _collection, _make_collection_method(_collection))

broadcast_python/resources/opt_in_forms.py

@@ -0,0 +1,62 @@
+from datetime import date, datetime
+from typing import Any, Optional, Union
+
+from .base import BaseResource, compact
+
+Id = Union[str, int]
+
+
+class OptInForms(BaseResource):
+    def list(self, **params: Any) -> Any:
+        """Up to 250 per page with ``pagination`` metadata. Variants are excluded.
+
+        Optional filters: ``filter`` (label substring), ``widget_type``, ``enabled``.
+        """
+        return self._get("/api/v1/opt_in_forms", params)
+
+    def get(self, id: Id) -> Any:  # noqa: A002
+        return self._get("/api/v1/opt_in_forms/{}".format(id))
+
+    def create(self, **attrs: Any) -> Any:
+        """Attributes are wrapped under ``opt_in_form:``.
+
+        Nested settings dicts (``theme_settings``, ``automation_settings``,
+        ``security_settings``, ``trigger_settings``, ``widget_settings``) and
+        the block arrays are passed through verbatim.
+        """
+        return self._post("/api/v1/opt_in_forms", {"opt_in_form": attrs})
+
+    def update(self, id: Id, **attrs: Any) -> Any:  # noqa: A002
+        return self._patch("/api/v1/opt_in_forms/{}".format(id), {"opt_in_form": attrs})
+
+    def delete(self, id: Id) -> Any:  # noqa: A002
+        return self._delete("/api/v1/opt_in_forms/{}".format(id))
+
+    def analytics(
+        self,
+        id: Id,  # noqa: A002
+        start_date: Optional[Union[str, date, datetime]] = None,
+        end_date: Optional[Union[str, date, datetime]] = None,
+    ) -> Any:
+        """Performance analytics. Dates accept ``date``, ``datetime``, or ISO-8601
+        strings; the server defaults to the last 30 days."""
+        params = compact(
+            {
+                "start_date": _coerce_date(start_date) if start_date is not None else None,
+                "end_date": _coerce_date(end_date) if end_date is not None else None,
+            }
+        )
+        return self._get("/api/v1/opt_in_forms/{}/analytics".format(id), params)
+
+    def create_variant(self, id: Id, name: Optional[str] = None, weight: Optional[int] = None) -> Any:  # noqa: A002
+        body = compact({"name": name, "weight": weight})
+        return self._post("/api/v1/opt_in_forms/{}/variants".format(id), body)
+
+    def duplicate(self, id: Id, label: Optional[str] = None) -> Any:  # noqa: A002
+        return self._post("/api/v1/opt_in_forms/{}/duplicate".format(id), compact({"label": label}))
+
+
+def _coerce_date(value: Union[str, date, datetime]) -> str:
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    return str(value)

broadcast_python/resources/segments.py

@@ -0,0 +1,23 @@
+from typing import Any, Optional, Union
+
+from .base import BaseResource
+
+Id = Union[str, int]
+
+
+class Segments(BaseResource):
+    def list(self, **params: Any) -> Any:
+        return self._get("/api/v1/segments.json", params)
+
+    def get(self, id: Id, page: Optional[int] = None) -> Any:  # noqa: A002
+        """Reading a segment recounts its members server-side, so this is not free."""
+        return self._get("/api/v1/segments/{}.json".format(id), {"page": page} if page else {})
+
+    def create(self, **attrs: Any) -> Any:
+        return self._post("/api/v1/segments", {"segment": attrs})
+
+    def update(self, id: Id, **attrs: Any) -> Any:  # noqa: A002
+        return self._patch("/api/v1/segments/{}".format(id), {"segment": attrs})
+
+    def delete(self, id: Id) -> Any:  # noqa: A002
+        return self._delete("/api/v1/segments/{}".format(id))

broadcast_python/resources/sequences.py

@@ -0,0 +1,58 @@
+from typing import Any, Union
+
+from .base import BaseResource
+
+Id = Union[str, int]
+
+
+class Sequences(BaseResource):
+    def list(self, **params: Any) -> Any:
+        return self._get("/api/v1/sequences", params)
+
+    def get(self, id: Id, include_steps: bool = False) -> Any:  # noqa: A002
+        return self._get("/api/v1/sequences/{}".format(id), {"include_steps": True} if include_steps else {})
+
+    def create(self, **attrs: Any) -> Any:
+        return self._post("/api/v1/sequences", attrs)
+
+    def update(self, id: Id, **attrs: Any) -> Any:  # noqa: A002
+        return self._patch("/api/v1/sequences/{}".format(id), attrs)
+
+    def delete(self, id: Id) -> Any:  # noqa: A002
+        return self._delete("/api/v1/sequences/{}".format(id))
+
+    # --- Subscriber enrollment ---
+
+    def add_subscriber(self, sequence_id: Id, **attrs: Any) -> Any:
+        return self._post("/api/v1/sequences/{}/add_subscriber".format(sequence_id), attrs)
+
+    def remove_subscriber(self, sequence_id: Id, email: str) -> Any:
+        return self._delete("/api/v1/sequences/{}/remove_subscriber".format(sequence_id), {"email": email})
+
+    def list_subscribers(self, sequence_id: Id, page: int = 1) -> Any:
+        return self._get("/api/v1/sequences/{}/list_subscribers".format(sequence_id), {"page": page})
+
+    # --- Steps ---
+    #
+    # Steps hang off the sequences resource rather than a top-level one,
+    # matching the nested routes.
+
+    def list_steps(self, sequence_id: Id) -> Any:
+        return self._get("/api/v1/sequences/{}/steps".format(sequence_id))
+
+    def get_step(self, sequence_id: Id, step_id: Id) -> Any:
+        return self._get("/api/v1/sequences/{}/steps/{}".format(sequence_id, step_id))
+
+    def create_step(self, sequence_id: Id, **attrs: Any) -> Any:
+        return self._post("/api/v1/sequences/{}/steps".format(sequence_id), attrs)
+
+    def update_step(self, sequence_id: Id, step_id: Id, **attrs: Any) -> Any:
+        return self._patch("/api/v1/sequences/{}/steps/{}".format(sequence_id, step_id), attrs)
+
+    def move_step(self, sequence_id: Id, step_id: Id, under_id: Id) -> Any:
+        """Reorders a step to sit directly after ``under_id``."""
+        body = {"under_id": under_id}
+        return self._post("/api/v1/sequences/{}/steps/{}/move".format(sequence_id, step_id), body)
+
+    def delete_step(self, sequence_id: Id, step_id: Id) -> Any:
+        return self._delete("/api/v1/sequences/{}/steps/{}".format(sequence_id, step_id))