broadcast-python 0.4.0__tar.gz → 0.6.0__tar.gz

{broadcast_python-0.4.0 → broadcast_python-0.6.0}/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-16
+
+### Added
+
+- `client.file_assets` for the File Assets API (Broadcast 2.48.0): `list(filter=,
+  limit=, offset=)`, `get(id)`, `upload(path_or_file_or_bytes, filename=,
+  content_type=, channel_restricted=, idempotency_key=)` (multipart),
+  `upload_base64(filename=, data=, ...)` (JSON) and `delete(id)`. The returned
+  `url` is what `channel_design.update({"brand": {"logo_url": ...}})` takes.
+  Deleting a brand kit logo raises `ValidationError` (422). Needs the new
+  `file_assets` permissions.
+- multipart/form-data requests in the transport, built on the standard
+  library (still no runtime dependencies). The debug log never shows the body.
+- `client.channel_settings.get()` and `client.channel_settings.update(settings)`
+  for `GET`/`PATCH /api/v1/channel/settings` (Broadcast 2.46.0): general,
+  sender, unsubscribe page (with the privacy policy and legal notice links),
+  confirmation page and opt-in forms (`opt_in_forms.match_brand_kit`) settings. Needs the new `channel_settings` permissions.
+- `client.channel_design.update(kit)` for `PATCH /api/v1/channel/design`
+  (Broadcast 2.46.0): change the brand kit. Needs `channel_settings_write`.
+  The logo is the `logo_url` of an image in the channel's file library.
+
+## [0.5.0] - 2026-10-10
+
+### Added
+
+- `email.send_delayed` and `broadcast.batch_completed` in `EVENT_TYPES` (and in
+  `EMAIL_EVENTS` / `BROADCAST_EVENTS`), matching the server (Broadcast 2.43.0).
+  `email.send_delayed` fires when a transactional email waits for room under
+  its server's hourly limit.
+- `excluded_segment_ids` on broadcasts, sequences and autopilots: segments a
+  send never reaches. The server refuses a segment that is both sent to and
+  excluded with 422.
+- `subscribers.create(unsubscribed_at=...)`: creates a subscriber who has
+  already unsubscribed, in one request, with any token. Before, the server
+  ignored the field and a migration had to create, then unsubscribe.
+
+- `TRIGGER_FREQUENCIES`: the words `trigger_settings["frequency"]` accepts
+  (`always`, `every_visit`, `once_per_session`, `once_per_day`,
+  `once_per_week`, `once`).
+
+### Changed
+
+- Opt-in forms: the server now refuses an unknown `trigger_settings`
+  frequency word with 422 (`ValidationError`). Before, it saved any word, and
+  an unknown one showed the popup on every visit. The client still sends what
+  it is given.
+
 ## [0.4.0] - 2026-10-06
 
 ### Added

{broadcast_python-0.4.0 → broadcast_python-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: broadcast-python
-Version: 0.4.0
+Version: 0.6.0
 Summary: Python client for the Broadcast email platform. Subscribers, sequences, broadcasts, segments, templates, autopilot, webhooks, and transactional email.
 Project-URL: Homepage, https://sendbroadcast.net
 Project-URL: Repository, https://github.com/send-broadcast/broadcast-python
@@ -26,7 +26,7 @@ Description-Content-Type: text/markdown
 
 Official Python client for [Broadcast](https://sendbroadcast.net), the self-hosted email marketing platform.
 
-Works with any Broadcast instance — self-hosted or SaaS. Covers **117/117 API operations**, verified against the API's generated OpenAPI document.
+Works with any Broadcast instance — self-hosted or SaaS. Covers **143/143 API operations**, verified against the API's generated OpenAPI document.
 
 📖 **[Python SDK documentation](https://sendbroadcast.net/docs/python-sdk)** · [API reference](https://sendbroadcast.net/docs/api-authentication) · [All docs](https://sendbroadcast.net/docs)
 
@@ -240,6 +240,8 @@ client.sequences.move_step(id, step_id, under_id)
 client.segments.create(name="VIPs")
 client.templates.create(label="Welcome", subject="Hi", body="...")
 client.opt_in_forms.analytics(id, start_date=date(2026, 1, 1))
+# How often the same visitor sees a popup: one of TRIGGER_FREQUENCIES, or ValidationError (422).
+client.opt_in_forms.update(id, trigger_settings={"frequency": "once_per_day"})
 client.opt_in_forms.create_variant(id, name="B", weight=50)
 client.opt_in_forms.duplicate(id, label="Copy")
 ```
@@ -264,6 +266,12 @@ client.topics.delete(topic["id"])  # 422 while a broadcast or sequence uses it
 # Send to a topic: (segments) AND topic
 client.broadcasts.create(subject="Webinar", body="...", segment_ids=[2], topic_id=topic["id"])
 
+# Send to everyone except a segment (also on sequences and autopilots)
+client.broadcasts.create(subject="Offer", body="...", excluded_segment_ids=[competitors["id"]])
+
+# Migrate someone who already unsubscribed, in one request
+client.subscribers.create(email="opted-out@example.com", unsubscribed_at="2025-03-14T09:30:00Z")
+
 # Change only the keys you send (None deletes a key); the default replaces custom_data
 client.subscribers.update("jane@example.com", custom_data={"sub_webinars": False}, custom_data_mode="merge")
 ```
@@ -281,9 +289,87 @@ kit["typography"]["font_stack"] # email-safe CSS font stack
 kit["brand"]["logo_url"]        # public URL, or None
 ```
 
-Read-only, for the token's own channel, fully resolved (defaults filled in).
-Needs `templates_read`. Block emails built with the drag-and-drop editor inherit
-these values.
+For the token's own channel, fully resolved (defaults filled in). Reading
+needs `templates_read` (or, from Broadcast 2.46.0, `channel_settings_read`).
+Block emails built with the drag-and-drop editor inherit these values.
+
+From Broadcast 2.46.0 you can change it. This needs `channel_settings_write`:
+
+```python
+kit = client.channel_design.update({
+    "colors": {"accent": "#ff5500"},
+    "typography": {"font": "georgia"},
+    "brand": {"logo_url": "https://your-broadcast.example/files/eyJ...-logo.png"},
+})
+kit.warnings   # e.g. a key the server did not recognize
+```
+
+Send only what changes, in the shape `get()` returns. An empty string or
+`None` puts a value back to its default, and `social_links` replaces the list.
+`font_stack` and `width` are read-only. The logo must be the `logo_url` of an
+image in the channel's file library; the server never fetches a URL. A value
+the Brand Kit page would refuse raises `ValidationError` (422), and nothing is
+saved.
+
+### Channel settings
+
+```python
+settings = client.channel_settings.get()
+settings["unsubscribe_page"]["legal_notice_url"]   # "https://example.com/impressum"
+
+updated = client.channel_settings.update({
+    "unsubscribe_page": {
+        "privacy_policy_url": "https://example.com/privacy",
+        "legal_notice_url": "https://example.com/impressum",
+    },
+})
+updated.warnings
+```
+
+Broadcast 2.46.0 or later. The settings are grouped like the Settings pages:
+`general`, `sender`, `unsubscribe_page` (with the legal links),
+`confirmation_page` and `opt_in_forms` (`match_brand_kit`: whether new opt-in
+forms start from the brand kit). Updates are partial: nested text and colours merge, an
+empty string or `None` removes a value, and `languages` replaces the list.
+Reading needs `channel_settings_read`, changing needs `channel_settings_write`;
+both are off on every token until you tick them.
+
+The `match_brand_kit` switches (`unsubscribe_page`, `confirmation_page`
+and `opt_in_forms`) decide where the brand kit is used. They are set
+here, not with the brand kit update.
+
+### File assets
+
+The channel's file library (Broadcast 2.48.0 or later): PNG, JPEG and GIF
+images under 10 MB, each with a public URL that never expires. Use the URL in
+emails, or as the brand kit logo.
+
+```python
+# Upload from a path (multipart). The content type follows the extension.
+file = client.file_assets.upload("logo.png")
+file["url"]   # "https://your-broadcast.example/files/eyJ...-logo.png"
+
+# From a file object or bytes, with a filename; link it to this channel only; safe to retry
+client.file_assets.upload(png_bytes, filename="banner.gif", channel_restricted=True,
+                          idempotency_key="banner-{}".format(campaign_id))
+
+# Already have base64? Send it as JSON.
+client.file_assets.upload_base64(filename="logo.png", content_type="image/png",
+                                 data=base64.b64encode(png_bytes).decode())
+
+# Use it as the brand kit logo
+client.channel_design.update({"brand": {"logo_url": file["url"]}})
+
+client.file_assets.list(filter="logo", limit=20)   # {"data": [...], "total": n}
+client.file_assets.get(file["id"])
+client.file_assets.delete(file["id"])
+```
+
+A file that is not a PNG, JPEG or GIF, a file of 10 MB or more, or invalid
+base64 raises `ValidationError` (422). So does deleting a file that is a
+channel's brand kit logo: set another logo first. The server never fetches a
+URL; upload the bytes. Reading needs `file_assets_read`; uploading and
+deleting need `file_assets_write`.
 
 ### Email servers
 
@@ -439,7 +525,7 @@ every rejection rather than distinguishing them.
 Pass the **raw** request body. Re-serialising a parsed dict changes the bytes
 and verification will fail.
 
-`broadcast_python.EVENT_TYPES` lists all 35 event names. `SUBSCRIBER_EVENTS`
+`broadcast_python.EVENT_TYPES` lists all 37 event names. `SUBSCRIBER_EVENTS`
 includes `subscribers.purged` and `subscribers.purge_failed`: a purge of the
 whole list sends one of these instead of a `subscriber.deleted` per subscriber.
 
@@ -462,6 +548,8 @@ integration requires.
 | Email Servers | `email_servers_read` -- list, get | `email_servers_write` -- create, update, delete, test_connection, copy_to_channel (admin) |
 | Webhook Endpoints | `webhook_endpoints_read` -- list, get, deliveries | `webhook_endpoints_write` -- create, update, delete, test |
 | Autopilot | `autopilot_read` -- list, get, runs | `autopilot_write` -- create, update, delete, activate, pause, deactivate, trigger_run |
+| Channel Settings | `channel_settings_read` -- channel_settings.get, channel_design.get | `channel_settings_write` -- channel_settings.update, channel_design.update |
+| File Assets | `file_assets_read` -- list, get | `file_assets_write` -- upload, upload_base64, delete |
 | Users (admin token only) | `users_read` -- list, get, channel_permissions, system_permissions | `users_write` -- create, update, deactivate, activate, delete, permission writes |
 
 ---

{broadcast_python-0.4.0 → broadcast_python-0.6.0}/README.md

@@ -2,7 +2,7 @@
 
 Official Python client for [Broadcast](https://sendbroadcast.net), the self-hosted email marketing platform.
 
-Works with any Broadcast instance — self-hosted or SaaS. Covers **117/117 API operations**, verified against the API's generated OpenAPI document.
+Works with any Broadcast instance — self-hosted or SaaS. Covers **143/143 API operations**, verified against the API's generated OpenAPI document.
 
 📖 **[Python SDK documentation](https://sendbroadcast.net/docs/python-sdk)** · [API reference](https://sendbroadcast.net/docs/api-authentication) · [All docs](https://sendbroadcast.net/docs)
 
@@ -216,6 +216,8 @@ client.sequences.move_step(id, step_id, under_id)
 client.segments.create(name="VIPs")
 client.templates.create(label="Welcome", subject="Hi", body="...")
 client.opt_in_forms.analytics(id, start_date=date(2026, 1, 1))
+# How often the same visitor sees a popup: one of TRIGGER_FREQUENCIES, or ValidationError (422).
+client.opt_in_forms.update(id, trigger_settings={"frequency": "once_per_day"})
 client.opt_in_forms.create_variant(id, name="B", weight=50)
 client.opt_in_forms.duplicate(id, label="Copy")
 ```
@@ -240,6 +242,12 @@ client.topics.delete(topic["id"])  # 422 while a broadcast or sequence uses it
 # Send to a topic: (segments) AND topic
 client.broadcasts.create(subject="Webinar", body="...", segment_ids=[2], topic_id=topic["id"])
 
+# Send to everyone except a segment (also on sequences and autopilots)
+client.broadcasts.create(subject="Offer", body="...", excluded_segment_ids=[competitors["id"]])
+
+# Migrate someone who already unsubscribed, in one request
+client.subscribers.create(email="opted-out@example.com", unsubscribed_at="2025-03-14T09:30:00Z")
+
 # Change only the keys you send (None deletes a key); the default replaces custom_data
 client.subscribers.update("jane@example.com", custom_data={"sub_webinars": False}, custom_data_mode="merge")
 ```
@@ -257,9 +265,87 @@ kit["typography"]["font_stack"] # email-safe CSS font stack
 kit["brand"]["logo_url"]        # public URL, or None
 ```
 
-Read-only, for the token's own channel, fully resolved (defaults filled in).
-Needs `templates_read`. Block emails built with the drag-and-drop editor inherit
-these values.
+For the token's own channel, fully resolved (defaults filled in). Reading
+needs `templates_read` (or, from Broadcast 2.46.0, `channel_settings_read`).
+Block emails built with the drag-and-drop editor inherit these values.
+
+From Broadcast 2.46.0 you can change it. This needs `channel_settings_write`:
+
+```python
+kit = client.channel_design.update({
+    "colors": {"accent": "#ff5500"},
+    "typography": {"font": "georgia"},
+    "brand": {"logo_url": "https://your-broadcast.example/files/eyJ...-logo.png"},
+})
+kit.warnings   # e.g. a key the server did not recognize
+```
+
+Send only what changes, in the shape `get()` returns. An empty string or
+`None` puts a value back to its default, and `social_links` replaces the list.
+`font_stack` and `width` are read-only. The logo must be the `logo_url` of an
+image in the channel's file library; the server never fetches a URL. A value
+the Brand Kit page would refuse raises `ValidationError` (422), and nothing is
+saved.
+
+### Channel settings
+
+```python
+settings = client.channel_settings.get()
+settings["unsubscribe_page"]["legal_notice_url"]   # "https://example.com/impressum"
+
+updated = client.channel_settings.update({
+    "unsubscribe_page": {
+        "privacy_policy_url": "https://example.com/privacy",
+        "legal_notice_url": "https://example.com/impressum",
+    },
+})
+updated.warnings
+```
+
+Broadcast 2.46.0 or later. The settings are grouped like the Settings pages:
+`general`, `sender`, `unsubscribe_page` (with the legal links),
+`confirmation_page` and `opt_in_forms` (`match_brand_kit`: whether new opt-in
+forms start from the brand kit). Updates are partial: nested text and colours merge, an
+empty string or `None` removes a value, and `languages` replaces the list.
+Reading needs `channel_settings_read`, changing needs `channel_settings_write`;
+both are off on every token until you tick them.
+
+The `match_brand_kit` switches (`unsubscribe_page`, `confirmation_page`
+and `opt_in_forms`) decide where the brand kit is used. They are set
+here, not with the brand kit update.
+
+### File assets
+
+The channel's file library (Broadcast 2.48.0 or later): PNG, JPEG and GIF
+images under 10 MB, each with a public URL that never expires. Use the URL in
+emails, or as the brand kit logo.
+
+```python
+# Upload from a path (multipart). The content type follows the extension.
+file = client.file_assets.upload("logo.png")
+file["url"]   # "https://your-broadcast.example/files/eyJ...-logo.png"
+
+# From a file object or bytes, with a filename; link it to this channel only; safe to retry
+client.file_assets.upload(png_bytes, filename="banner.gif", channel_restricted=True,
+                          idempotency_key="banner-{}".format(campaign_id))
+
+# Already have base64? Send it as JSON.
+client.file_assets.upload_base64(filename="logo.png", content_type="image/png",
+                                 data=base64.b64encode(png_bytes).decode())
+
+# Use it as the brand kit logo
+client.channel_design.update({"brand": {"logo_url": file["url"]}})
+
+client.file_assets.list(filter="logo", limit=20)   # {"data": [...], "total": n}
+client.file_assets.get(file["id"])
+client.file_assets.delete(file["id"])
+```
+
+A file that is not a PNG, JPEG or GIF, a file of 10 MB or more, or invalid
+base64 raises `ValidationError` (422). So does deleting a file that is a
+channel's brand kit logo: set another logo first. The server never fetches a
+URL; upload the bytes. Reading needs `file_assets_read`; uploading and
+deleting need `file_assets_write`.
 
 ### Email servers
 
@@ -415,7 +501,7 @@ every rejection rather than distinguishing them.
 Pass the **raw** request body. Re-serialising a parsed dict changes the bytes
 and verification will fail.
 
-`broadcast_python.EVENT_TYPES` lists all 35 event names. `SUBSCRIBER_EVENTS`
+`broadcast_python.EVENT_TYPES` lists all 37 event names. `SUBSCRIBER_EVENTS`
 includes `subscribers.purged` and `subscribers.purge_failed`: a purge of the
 whole list sends one of these instead of a `subscriber.deleted` per subscriber.
 
@@ -438,6 +524,8 @@ integration requires.
 | Email Servers | `email_servers_read` -- list, get | `email_servers_write` -- create, update, delete, test_connection, copy_to_channel (admin) |
 | Webhook Endpoints | `webhook_endpoints_read` -- list, get, deliveries | `webhook_endpoints_write` -- create, update, delete, test |
 | Autopilot | `autopilot_read` -- list, get, runs | `autopilot_write` -- create, update, delete, activate, pause, deactivate, trigger_run |
+| Channel Settings | `channel_settings_read` -- channel_settings.get, channel_design.get | `channel_settings_write` -- channel_settings.update, channel_design.update |
+| File Assets | `file_assets_read` -- list, get | `file_assets_write` -- upload, upload_base64, delete |
 | Users (admin token only) | `users_read` -- list, get, channel_permissions, system_permissions | `users_write` -- create, update, deactivate, activate, delete, permission writes |
 
 ---

{broadcast_python-0.4.0 → broadcast_python-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "broadcast-python"
-version = "0.4.0"
+version = "0.6.0"
 description = "Python client for the Broadcast email platform. Subscribers, sequences, broadcasts, segments, templates, autopilot, webhooks, and transactional email."
 readme = "README.md"
 requires-python = ">=3.9"

{broadcast_python-0.4.0 → broadcast_python-0.6.0}/src/broadcast_python/__init__.py

@@ -28,6 +28,7 @@ from .errors import (
 )
 from .resources.email_servers import REDACTED_FIELDS
 from .resources.migration import COLLECTIONS
+from .resources.opt_in_forms import TRIGGER_FREQUENCIES
 from .resources.transactionals import MAX_IDEMPOTENCY_KEY_LENGTH
 from .response import RateLimit, Response, Warning_
 from .version import VERSION
@@ -42,6 +43,7 @@ __all__ = [
     "EVENT_TYPES",
     "MAX_IDEMPOTENCY_KEY_LENGTH",
     "REDACTED_FIELDS",
+    "TRIGGER_FREQUENCIES",
     "VERSION",
     "WARNINGS_MODES",
     "APIError",

{broadcast_python-0.4.0 → broadcast_python-0.6.0}/src/broadcast_python/client.py

@@ -6,8 +6,10 @@ from .connection import Connection
 from .resources.autopilots import Autopilots
 from .resources.broadcasts import Broadcasts
 from .resources.channel_design import ChannelDesign
+from .resources.channel_settings import ChannelSettings
 from .resources.discovery import Discovery
 from .resources.email_servers import EmailServers
+from .resources.file_assets import FileAssets
 from .resources.global_suppressions import GlobalSuppressions
 from .resources.migration import Migration
 from .resources.opt_in_forms import OptInForms
@@ -43,8 +45,13 @@ class Broadcast:
         self.segments = Segments(self)
         self.topics = Topics(self)
         self.templates = Templates(self)
-        #: The channel's brand kit (Settings -> Design). Read-only.
+        #: The channel's brand kit (Settings -> Brand Kit). Update needs Broadcast 2.46.0.
         self.channel_design = ChannelDesign(self)
+        #: The channel's settings (Broadcast 2.46.0 or later).
+        self.channel_settings = ChannelSettings(self)
+        #: The channel's file library: upload images and get their public URLs
+        #: (Broadcast 2.48.0 or later).
+        self.file_assets = FileAssets(self)
         self.webhook_endpoints = WebhookEndpoints(self)
         self.transactionals = Transactionals(self)
         self.opt_in_forms = OptInForms(self)
@@ -126,9 +133,10 @@ class Broadcast:
         body_or_params: Any = None,
         headers: Optional[Dict[str, Any]] = None,
         raw: bool = False,
+        multipart: bool = False,
     ) -> Any:
         payload = self._inject_channel_scope(body_or_params)
-        return self._connection.request(method, path, payload, headers=headers, raw=raw)
+        return self._connection.request(method, path, payload, headers=headers, raw=raw, multipart=multipart)
 
     @property
     def _active_channel_id(self) -> Optional[Id]:

{broadcast_python-0.4.0 → broadcast_python-0.6.0}/src/broadcast_python/connection.py

@@ -17,6 +17,7 @@ from typing import Any, Dict, List, Optional, Tuple
 from urllib.error import HTTPError, URLError
 from urllib.parse import urlencode, urljoin, urlparse
 
+from . import multipart as multipart_body
 from .configuration import Configuration
 from .errors import (
     APIError,
@@ -66,10 +67,13 @@ class Connection:
         payload: Any = None,
         headers: Optional[Dict[str, Any]] = None,
         raw: bool = False,
+        multipart: bool = False,
     ) -> Any:
+        """``multipart=True`` sends the payload as multipart/form-data
+        (``FilePart`` values become file parts) instead of JSON."""
         url = self._build_url(path, method, payload)
         return self._retry_with_backoff(
-            lambda: self._execute(method, url, payload, headers or {}, raw, 0)
+            lambda: self._execute(method, url, payload, headers or {}, raw, 0, multipart)
         )
 
     # --- Request building ---------------------------------------------------
@@ -81,15 +85,25 @@ class Connection:
         return url
 
     def _execute(
-        self, method: str, url: str, payload: Any, extra_headers: Dict[str, Any], raw: bool, redirects: int
+        self,
+        method: str,
+        url: str,
+        payload: Any,
+        extra_headers: Dict[str, Any],
+        raw: bool,
+        redirects: int,
+        multipart: bool = False,
     ) -> Any:
         body = None
-        if method != "GET" and _present(payload):
+        content_type = "application/json"
+        if multipart:
+            body, content_type = multipart_body.build(payload or {})
+        elif method != "GET" and _present(payload):
             body = json.dumps(payload).encode("utf-8")
 
         request = urllib.request.Request(url, data=body, method=method)
         request.add_header("Authorization", "Bearer {}".format(self.config.api_token))
-        request.add_header("Content-Type", "application/json")
+        request.add_header("Content-Type", content_type)
         request.add_header("User-Agent", "broadcast-python/{}".format(VERSION))
         for key, value in (extra_headers or {}).items():
             if value is None:

broadcast_python-0.6.0/src/broadcast_python/multipart.py

@@ -0,0 +1,59 @@
+"""multipart/form-data bodies, built by hand on the standard library.
+
+urllib has no multipart encoder, and the package takes no runtime
+dependencies, so the body is assembled here. It is built from bytes (not a
+stream) on every attempt, which keeps a retry safe.
+"""
+
+import uuid
+from typing import Any, Dict, NamedTuple, Tuple
+
+
+class FilePart(NamedTuple):
+    """A file in a multipart request: the bytes, and the filename and content
+    type sent with them."""
+
+    data: bytes
+    filename: str
+    content_type: str
+
+    def __repr__(self) -> str:
+        # Never the bytes: a repr ends up in logs and tracebacks.
+        return "FilePart({!r}, {}, {} bytes)".format(self.filename, self.content_type, len(self.data))
+
+
+def build(fields: Dict[str, Any]) -> Tuple[bytes, str]:
+    """Returns the body and the Content-Type header. ``None`` values are left
+    out; booleans are sent as ``true``/``false``, as Rails reads them."""
+    boundary = "BroadcastPython{}".format(uuid.uuid4().hex)
+    body = bytearray()
+
+    for name, value in fields.items():
+        if value is None:
+            continue
+
+        body += "--{}\r\n".format(boundary).encode("ascii")
+        if isinstance(value, FilePart):
+            body += 'Content-Disposition: form-data; name="{}"; filename="{}"\r\n'.format(
+                _quote(name), _quote(value.filename)
+            ).encode("utf-8")
+            body += "Content-Type: {}\r\n\r\n".format(value.content_type).encode("utf-8")
+            body += value.data
+        else:
+            body += 'Content-Disposition: form-data; name="{}"\r\n\r\n'.format(_quote(name)).encode("utf-8")
+            body += _stringify(value).encode("utf-8")
+        body += b"\r\n"
+
+    body += "--{}--\r\n".format(boundary).encode("ascii")
+    return bytes(body), "multipart/form-data; boundary={}".format(boundary)
+
+
+def _quote(value: Any) -> str:
+    """A quote or a line break in a name would end the header early."""
+    return str(value).replace("\r", " ").replace("\n", " ").replace('"', "%22")
+
+
+def _stringify(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)

{broadcast_python-0.4.0 → broadcast_python-0.6.0}/src/broadcast_python/resources/autopilots.py

@@ -36,7 +36,8 @@ class Autopilots(BaseResource):
         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.
+        newsletter's audience; ``excluded_segment_ids`` lists segments its
+        drafts never reach.
         """
         return self._post("/api/v1/autopilots", {"autopilot": attrs})
 

broadcast_python-0.6.0/src/broadcast_python/resources/channel_design.py

@@ -0,0 +1,39 @@
+from typing import Any, Dict
+
+from .base import BaseResource
+
+
+class ChannelDesign(BaseResource):
+    """The brand kit of the token's channel (Settings -> Brand Kit).
+
+    Reading requires the ``templates_read`` permission (the kit is design
+    metadata for templates) or, from Broadcast 2.46.0, ``channel_settings_read``.
+    Changing it requires ``channel_settings_write`` (Broadcast 2.46.0 or later).
+    There is no channel argument; the server reads the channel the token
+    resolves to (for an admin token, the one set with ``with_channel`` or
+    ``broadcast_channel_id``).
+    """
+
+    def get(self) -> Any:
+        """The channel's brand kit, fully resolved (defaults filled in).
+
+        Returns ``colors``, ``typography`` (``font`` key and the email-safe
+        ``font_stack``), ``layout`` (``width``, ``radius``), and ``brand``
+        (``logo_url`` as a public URL or None, ``logo_width``, ``website_url``,
+        ``social_links``, ``social_icon_style``). Block emails built with the
+        drag-and-drop editor inherit these values.
+        """
+        return self._get("/api/v1/channel/design")
+
+    def update(self, design: Dict[str, Any]) -> Any:
+        """Change the brand kit (Broadcast 2.46.0 or later).
+
+        Partial: send only what changes, in the shape ``get()`` returns. An
+        empty string or None puts a value back to its default;
+        ``social_links`` replaces the list; ``font_stack`` and ``width`` are
+        read-only. Set the logo with the ``logo_url`` of an image in the
+        channel's file library (the server never fetches a URL). Returns the
+        whole kit after the change; read ``result.warnings`` for anything the
+        server ignored.
+        """
+        return self._patch("/api/v1/channel/design", {"channel_design": design})

broadcast_python-0.6.0/src/broadcast_python/resources/channel_settings.py

@@ -0,0 +1,31 @@
+from typing import Any, Dict
+
+from .base import BaseResource
+
+
+class ChannelSettings(BaseResource):
+    """The settings of the token's channel (Broadcast 2.46.0 or later).
+
+    Grouped like the Settings pages: ``general``, ``sender``,
+    ``unsubscribe_page`` (with the privacy policy and legal notice links),
+    ``confirmation_page`` and ``opt_in_forms`` (``match_brand_kit``: whether
+    new opt-in forms start from the brand kit). The brand kit switches are set
+    here, not with ``channel_design.update()``. Reading requires ``channel_settings_read`` and
+    changing requires ``channel_settings_write``. There is no channel
+    argument; the server reads the channel the token resolves to.
+    """
+
+    def get(self) -> Any:
+        """Every channel setting, with defaults resolved."""
+        return self._get("/api/v1/channel/settings")
+
+    def update(self, settings: Dict[str, Any]) -> Any:
+        """Change channel settings.
+
+        Partial: send only the groups and keys that change. Nested text and
+        colours merge, an empty string or None removes a value, and
+        ``languages`` replaces the list. Returns every setting after the
+        change; read ``result.warnings`` for anything the server ignored or
+        changed.
+        """
+        return self._patch("/api/v1/channel/settings", {"channel_settings": settings})

broadcast_python-0.6.0/src/broadcast_python/resources/file_assets.py

@@ -0,0 +1,112 @@
+import os
+from typing import IO, Any, Optional, Tuple, Union
+
+from ..multipart import FilePart
+from .base import BaseResource, compact
+from .transactionals import _idempotency_headers
+
+Id = Union[str, int]
+
+CONTENT_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+}
+
+
+class FileAssets(BaseResource):
+    """The channel's file library (Broadcast 2.48.0 or later): images (PNG,
+    JPEG, GIF, under 10 MB) with public URLs that never expire. Use a file's
+    ``url`` in emails, or as the brand kit logo::
+
+        file = client.file_assets.upload("logo.png")
+        client.channel_design.update({"brand": {"logo_url": file["url"]}})
+
+    Reading needs ``file_assets_read``; uploading and deleting need
+    ``file_assets_write``.
+    """
+
+    def list(self, **params: Any) -> Any:
+        """Files the channel can see, newest first. ``filter`` searches file
+        names (closest matches first); ``limit`` and ``offset`` page.
+
+        Returns ``{"data": [...], "total": n}``.
+        """
+        return self._get("/api/v1/file_assets", params)
+
+    def get(self, id: Id) -> Any:  # noqa: A002
+        return self._get("/api/v1/file_assets/{}".format(id), {})
+
+    def upload(
+        self,
+        file: Union[str, "os.PathLike[str]", bytes, IO[bytes]],
+        filename: Optional[str] = None,
+        content_type: Optional[str] = None,
+        channel_restricted: Optional[bool] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        """Upload a file as multipart/form-data.
+
+        ``file`` is a path, a binary file object, or bytes. Bytes, and a file
+        object without a ``name``, need ``filename``. The content type follows
+        the file extension unless ``content_type`` is given.
+
+        ``channel_restricted=True`` links the file to this channel only (the
+        default is every channel, as in the web app). ``idempotency_key``
+        makes a retry safe; see ``transactionals.create``.
+        """
+        data, name = _read_file(file, filename)
+        part = FilePart(data, name, content_type or _content_type_for(name))
+        fields = compact({"file": part, "channel_restricted": channel_restricted})
+
+        headers = _idempotency_headers(idempotency_key)
+        return self._client.request("POST", "/api/v1/file_assets", fields, headers=headers, multipart=True)
+
+    def upload_base64(
+        self,
+        filename: str,
+        data: str,
+        content_type: Optional[str] = None,
+        channel_restricted: Optional[bool] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        """Upload base64-encoded bytes in a JSON body, for callers that
+        already hold base64 (or cannot send multipart)."""
+        payload = compact(
+            {
+                "filename": filename,
+                "data": data,
+                "content_type": content_type,
+                "channel_restricted": channel_restricted,
+            }
+        )
+        return self._post("/api/v1/file_assets", payload, headers=_idempotency_headers(idempotency_key))
+
+    def delete(self, id: Id) -> Any:  # noqa: A002
+        """A file that is a channel's brand kit logo is refused with
+        ``ValidationError`` (422): choose another logo first."""
+        return self._delete("/api/v1/file_assets/{}".format(id))
+
+
+def _read_file(file: Any, filename: Optional[str]) -> Tuple[bytes, str]:
+    if isinstance(file, (bytes, bytearray)):
+        if filename is None:
+            raise ValueError("filename is required when uploading bytes")
+        return bytes(file), filename
+
+    if hasattr(file, "read"):
+        name = filename
+        if name is None and isinstance(getattr(file, "name", None), str):
+            name = os.path.basename(file.name)
+        if name is None:
+            raise ValueError("filename is required when uploading from a file object without a name")
+        return file.read(), name
+
+    path = os.fspath(file)
+    with open(path, "rb") as f:
+        return f.read(), filename or os.path.basename(path)
+
+
+def _content_type_for(name: str) -> str:
+    return CONTENT_TYPES.get(os.path.splitext(name)[1].lower(), "application/octet-stream")

{broadcast_python-0.4.0 → broadcast_python-0.6.0}/src/broadcast_python/resources/opt_in_forms.py

@@ -5,6 +5,12 @@ from .base import BaseResource, compact
 
 Id = Union[str, int]
 
+#: The words ``trigger_settings["frequency"]`` accepts: how often the same
+#: visitor sees a popup. ``always`` and ``every_visit`` mean the same. The server
+#: refuses any other word with 422 (:class:`ValidationError`); the client does
+#: not check, so an older server is never refused a word it would take.
+TRIGGER_FREQUENCIES = ("always", "every_visit", "once_per_session", "once_per_day", "once_per_week", "once")
+
 
 class OptInForms(BaseResource):
     def list(self, **params: Any) -> Any:
@@ -23,6 +29,9 @@ class OptInForms(BaseResource):
         Nested settings dicts (``theme_settings``, ``automation_settings``,
         ``security_settings``, ``trigger_settings``, ``widget_settings``) and
         the block arrays are passed through verbatim.
+        ``trigger_settings["frequency"]`` must be one of
+        :data:`TRIGGER_FREQUENCIES`; any other word raises
+        :class:`ValidationError` (422).
         """
         return self._post("/api/v1/opt_in_forms", {"opt_in_form": attrs})
 

{broadcast_python-0.4.0 → broadcast_python-0.6.0}/src/broadcast_python/resources/subscribers.py

@@ -33,7 +33,11 @@ class Subscribers(BaseResource):
         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`.
+        ``unsubscribed_at`` (any token, create only, ISO 8601) stores the
+        subscriber as unsubscribed in the same request, for migrating a list
+        with its opt-outs intact: no confirmation email, 422 if it is in the
+        future or sent with ``is_active=True``. To unsubscribe an existing
+        subscriber, use :meth:`unsubscribe`.
         """
         double_opt_in = attrs.pop("double_opt_in", None)
         confirmation_template_id = attrs.pop("confirmation_template_id", None)

{broadcast_python-0.4.0 → broadcast_python-0.6.0}/src/broadcast_python/version.py

@@ -1,3 +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.4.0"
+VERSION = "0.6.0"

{broadcast_python-0.4.0 → broadcast_python-0.6.0}/src/broadcast_python/webhook.py

@@ -15,6 +15,7 @@ EMAIL_EVENTS = (
     "email.sent",
     "email.delivered",
     "email.delivery_delayed",
+    "email.send_delayed",
     "email.complained",
     "email.bounced",
     "email.opened",
@@ -45,6 +46,7 @@ BROADCAST_EVENTS = (
     "broadcast.partial_failure",
     "broadcast.aborted",
     "broadcast.paused",
+    "broadcast.batch_completed",
 )
 
 SEQUENCE_EVENTS = (

broadcast_python-0.4.0/src/broadcast_python/resources/channel_design.py

@@ -1,24 +0,0 @@
-from typing import Any
-
-from .base import BaseResource
-
-
-class ChannelDesign(BaseResource):
-    """The brand kit of the token's channel (Settings -> Design). Read-only.
-
-    Requires the ``templates_read`` permission: the kit is design metadata for
-    templates. There is no channel argument; the server reads the channel the
-    token resolves to (for an admin token, the one set with ``with_channel`` or
-    ``broadcast_channel_id``).
-    """
-
-    def get(self) -> Any:
-        """The channel's brand kit, fully resolved (defaults filled in).
-
-        Returns ``colors``, ``typography`` (``font`` key and the email-safe
-        ``font_stack``), ``layout`` (``width``, ``radius``), and ``brand``
-        (``logo_url`` as a public URL or None, ``logo_width``, ``website_url``,
-        ``social_links``, ``social_icon_style``). Block emails built with the
-        drag-and-drop editor inherit these values.
-        """
-        return self._get("/api/v1/channel/design")