docketeer-atproto 0.0.17__tar.gz

docketeer_atproto-0.0.17/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.envrc.private
+.claude/settings.local.json
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+workspace/
+.coverage
+.loq_cache
+.python-version

docketeer_atproto-0.0.17/CLAUDE.md

@@ -0,0 +1,18 @@
+# docketeer-atproto
+
+ATProto Jetstream band plugin. Registers a `docketeer.bands` entry point that
+streams ATProto events from a Jetstream relay via WebSocket.
+
+## Structure
+
+- **`band.py`** — `JetstreamBand` implementation. Connects to a Jetstream
+  relay's `/subscribe` WebSocket endpoint, parses JSON messages into `Signal`
+  objects. Handles all three Jetstream event types (commit, identity, account)
+  with per-type signal conversion. Supports server-side filtering via
+  `wantedCollections` and `wantedDids` query params.
+
+## Testing
+
+WebSocket connections are mocked with a `FakeWebSocket` async iterable.
+Tests verify URL construction, cursor handling, filter hints, and signal
+parsing for all three event types without any network access.

docketeer_atproto-0.0.17/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: docketeer-atproto
+Version: 0.0.17
+Summary: ATProto Jetstream band plugin for Docketeer
+Project-URL: Homepage, https://github.com/chrisguidry/docketeer
+Project-URL: Repository, https://github.com/chrisguidry/docketeer
+Project-URL: Issues, https://github.com/chrisguidry/docketeer/issues
+Author-email: Chris Guidry <guid@omg.lol>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: docketeer
+Requires-Dist: websockets
+Description-Content-Type: text/markdown
+
+# docketeer-atproto
+
+ATProto Jetstream band plugin for
+[Docketeer](https://pypi.org/project/docketeer/). Streams real-time ATProto
+events from a [Jetstream](https://docs.bsky.app/blog/jetstream) relay via
+WebSocket and produces `Signal` objects for the antenna system.
+
+Install `docketeer-atproto` alongside `docketeer` and the band is
+automatically available.
+
+## Configuration
+
+| Variable                       | Default                              | Description                        |
+|--------------------------------|--------------------------------------|------------------------------------|
+| `DOCKETEER_ATPROTO_RELAY_URL`  | _(round-robin, see below)_           | Override with a single Jetstream relay URL. |
+
+By default, the band round-robins between the two public Jetstream relays on
+each reconnect:
+- `wss://jetstream1.us-east.bsky.network/subscribe`
+- `wss://jetstream2.us-east.bsky.network/subscribe`
+
+Setting `DOCKETEER_ATPROTO_RELAY_URL` pins to a single relay.
+
+## Event types
+
+The band handles all three Jetstream event types:
+
+- **commit** — record creates, updates, and deletes. Topic is the collection
+  NSID (e.g. `app.bsky.feed.post`). This is the main event type for posts,
+  likes, follows, etc.
+- **identity** — handle or DID document changes. Topic is `identity`.
+- **account** — account status changes (activation, deactivation, takedown).
+  Topic is `account`.
+
+## Server-side filtering
+
+The band pushes compatible filters to the relay as query parameters:
+
+- `collection` with `eq` or `startswith` op maps to `wantedCollections`
+- `did` with `eq` op maps to `wantedDids`

docketeer_atproto-0.0.17/README.md

@@ -0,0 +1,40 @@
+# docketeer-atproto
+
+ATProto Jetstream band plugin for
+[Docketeer](https://pypi.org/project/docketeer/). Streams real-time ATProto
+events from a [Jetstream](https://docs.bsky.app/blog/jetstream) relay via
+WebSocket and produces `Signal` objects for the antenna system.
+
+Install `docketeer-atproto` alongside `docketeer` and the band is
+automatically available.
+
+## Configuration
+
+| Variable                       | Default                              | Description                        |
+|--------------------------------|--------------------------------------|------------------------------------|
+| `DOCKETEER_ATPROTO_RELAY_URL`  | _(round-robin, see below)_           | Override with a single Jetstream relay URL. |
+
+By default, the band round-robins between the two public Jetstream relays on
+each reconnect:
+- `wss://jetstream1.us-east.bsky.network/subscribe`
+- `wss://jetstream2.us-east.bsky.network/subscribe`
+
+Setting `DOCKETEER_ATPROTO_RELAY_URL` pins to a single relay.
+
+## Event types
+
+The band handles all three Jetstream event types:
+
+- **commit** — record creates, updates, and deletes. Topic is the collection
+  NSID (e.g. `app.bsky.feed.post`). This is the main event type for posts,
+  likes, follows, etc.
+- **identity** — handle or DID document changes. Topic is `identity`.
+- **account** — account status changes (activation, deactivation, takedown).
+  Topic is `account`.
+
+## Server-side filtering
+
+The band pushes compatible filters to the relay as query parameters:
+
+- `collection` with `eq` or `startswith` op maps to `wantedCollections`
+- `did` with `eq` op maps to `wantedDids`

docketeer_atproto-0.0.17/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "docketeer-atproto"
+dynamic = ["version"]
+description = "ATProto Jetstream band plugin for Docketeer"
+readme = "README.md"
+authors = [
+    { name = "Chris Guidry", email = "guid@omg.lol" }
+]
+license = "MIT"
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "docketeer",
+    "websockets",
+]
+
+[project.urls]
+Homepage = "https://github.com/chrisguidry/docketeer"
+Repository = "https://github.com/chrisguidry/docketeer"
+Issues = "https://github.com/chrisguidry/docketeer/issues"
+
+[project.entry-points."docketeer.bands"]
+atproto = "docketeer_atproto:create_band"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+raw-options.root = ".."
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docketeer_atproto"]
+
+[tool.uv.sources]
+docketeer = { workspace = true }
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+timeout = 1
+addopts = [
+    "--import-mode=importlib",
+    "--cov=docketeer_atproto",
+    "--cov=tests",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+asyncio_mode = "auto"
+filterwarnings = [
+    "error",
+]

docketeer_atproto-0.0.17/src/docketeer_atproto/__init__.py

@@ -0,0 +1,7 @@
+"""ATProto Jetstream band plugin for Docketeer."""
+
+from docketeer_atproto.band import JetstreamBand
+
+
+def create_band() -> JetstreamBand:
+    return JetstreamBand()

docketeer_atproto-0.0.17/src/docketeer_atproto/band.py

@@ -0,0 +1,199 @@
+"""ATProto Jetstream WebSocket band."""
+
+import json
+import logging
+import os
+from collections.abc import AsyncGenerator
+from datetime import UTC, datetime
+from typing import Any
+from urllib.parse import urlencode
+
+import websockets
+
+from docketeer.antenna import Band, Signal, SignalFilter
+
+log = logging.getLogger(__name__)
+
+DEFAULT_RELAY_URLS = [
+    "wss://jetstream1.us-east.bsky.network/subscribe",
+    "wss://jetstream2.us-east.bsky.network/subscribe",
+]
+
+
+class JetstreamBand(Band):
+    """Streams ATProto events from a Jetstream relay via WebSocket."""
+
+    name = "atproto"
+    description = (
+        "ATProto Jetstream — real-time Bluesky/AT Protocol events via WebSocket.\n"
+        "\n"
+        "topic: the collection NSID to subscribe to\n"
+        '  e.g. "app.bsky.feed.post" for posts,\n'
+        '       "app.bsky.feed.like" for likes,\n'
+        '       "app.bsky.graph.follow" for follows\n'
+        "\n"
+        "filters: narrow the stream by DID or collection\n"
+        '  {path: "did", op: "eq", value: "did:plc:..."} — single account\n'
+        '  {path: "collection", op: "startswith", value: "app.bsky.feed"}\n'
+        "  did and collection eq/startswith filters are pushed server-side\n"
+        "\n"
+        "secrets: not used (Jetstream is a public firehose)\n"
+        "\n"
+        "Signals produced:\n"
+        "  Three event kinds, distinguished by topic:\n"
+        "  commit: topic = collection NSID\n"
+        "    payload.did, payload.operation, payload.collection, payload.rkey\n"
+        "    payload.record = the AT Protocol record (post text, like, follow, etc.)\n"
+        "    For posts: payload.record.text contains the post text\n"
+        '    summary = "{did} {operation} {collection}: {post text}"\n'
+        '  identity: topic = "identity" (handle/DID changes)\n'
+        '    summary = "{did} is now @{handle}"\n'
+        '  account: topic = "account" (activation/deactivation)\n'
+        '    summary = "{did} account active/deactivated"\n'
+        "\n"
+        "Filtering tips:\n"
+        "  To filter posts by content, use:\n"
+        '    {path: "payload.record.text", op: "icontains", value: "cat"}'
+    )
+
+    def __init__(self) -> None:
+        env_url = os.environ.get("DOCKETEER_ATPROTO_RELAY_URL")
+        if env_url:
+            self._relay_urls = [env_url]
+        else:
+            self._relay_urls = list(DEFAULT_RELAY_URLS)
+        self._next_relay = 0
+
+    def _pick_relay(self) -> str:
+        url = self._relay_urls[self._next_relay % len(self._relay_urls)]
+        self._next_relay += 1
+        return url
+
+    async def __aenter__(self) -> "JetstreamBand":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        pass
+
+    async def listen(
+        self,
+        topic: str,
+        filters: list[SignalFilter],
+        last_signal_id: str = "",
+        secrets: dict[str, str] | None = None,
+    ) -> AsyncGenerator[Signal, None]:
+        params: dict[str, str] = {"wantedCollections": topic}
+
+        for hint in self.remote_filter_hints(filters):
+            if hint.path == "did" and hint.op == "eq":
+                params["wantedDids"] = hint.value
+
+        if last_signal_id:
+            params["cursor"] = last_signal_id
+
+        relay = self._pick_relay()
+        url = f"{relay}?{urlencode(params, doseq=True)}"
+        log.info("Connecting to Jetstream relay: %s", relay)
+
+        async with websockets.connect(url) as ws:
+            async for raw in ws:
+                message: dict[str, Any] = json.loads(raw)
+                signal = _message_to_signal(message)
+                yield signal
+
+    def remote_filter_hints(
+        self,
+        filters: list[SignalFilter],
+    ) -> list[SignalFilter]:
+        hints: list[SignalFilter] = []
+        for f in filters:
+            if (f.path == "collection" and f.op in ("eq", "startswith")) or (
+                f.path == "did" and f.op == "eq"
+            ):
+                hints.append(f)
+        return hints
+
+
+def _message_to_signal(message: dict[str, Any]) -> Signal:
+    time_us = message.get("time_us", 0)
+    timestamp = datetime.fromtimestamp(time_us / 1_000_000, tz=UTC)
+    did = message.get("did", "")
+    kind = message.get("kind", "commit")
+
+    if kind == "commit":
+        return _commit_to_signal(message, did, timestamp)
+    if kind == "identity":
+        return _identity_to_signal(message, did, timestamp)
+    return _account_to_signal(message, did, timestamp)
+
+
+def _commit_to_signal(
+    message: dict[str, Any],
+    did: str,
+    timestamp: datetime,
+) -> Signal:
+    commit = message.get("commit", {})
+    collection = commit.get("collection", "")
+    operation = commit.get("operation", "unknown")
+    record = commit.get("record", {})
+
+    summary = f"{did} {operation} {collection}"
+    text = record.get("text", "") if isinstance(record, dict) else ""
+    if text:
+        summary = f"{summary}: {text}"
+
+    payload: dict[str, Any] = {
+        "did": did,
+        "operation": operation,
+        "collection": collection,
+        "rkey": commit.get("rkey", ""),
+        "rev": commit.get("rev", ""),
+    }
+    if isinstance(record, dict):
+        payload["record"] = record
+
+    return Signal(
+        band="atproto",
+        signal_id=str(message.get("time_us", 0)),
+        timestamp=timestamp,
+        topic=collection,
+        payload=payload,
+        summary=summary,
+    )
+
+
+def _identity_to_signal(
+    message: dict[str, Any],
+    did: str,
+    timestamp: datetime,
+) -> Signal:
+    identity = message.get("identity", {})
+    handle = identity.get("handle", "")
+
+    return Signal(
+        band="atproto",
+        signal_id=str(message.get("time_us", 0)),
+        timestamp=timestamp,
+        topic="identity",
+        payload=message,
+        summary=f"{did} is now @{handle}" if handle else f"{did} identity updated",
+    )
+
+
+def _account_to_signal(
+    message: dict[str, Any],
+    did: str,
+    timestamp: datetime,
+) -> Signal:
+    account = message.get("account", {})
+    active = account.get("active", True)
+    status = "active" if active else "deactivated"
+
+    return Signal(
+        band="atproto",
+        signal_id=str(message.get("time_us", 0)),
+        timestamp=timestamp,
+        topic="account",
+        payload=message,
+        summary=f"{did} account {status}",
+    )

docketeer_atproto-0.0.17/tests/test_band.py

@@ -0,0 +1,494 @@
+"""Tests for the ATProto Jetstream band."""
+
+import json
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+from typing import Any
+from unittest.mock import patch
+
+from docketeer.antenna import SignalFilter
+from docketeer_atproto import create_band
+from docketeer_atproto.band import (
+    DEFAULT_RELAY_URLS,
+    JetstreamBand,
+    _account_to_signal,
+    _commit_to_signal,
+    _identity_to_signal,
+    _message_to_signal,
+)
+
+
+def test_create_band() -> None:
+    band = create_band()
+    assert isinstance(band, JetstreamBand)
+    assert band.name == "atproto"
+
+
+# --- Sample message builders ---
+
+
+def _sample_commit(
+    *,
+    time_us: int = 1_700_000_000_000_000,
+    did: str = "did:plc:abc123",
+    collection: str = "app.bsky.feed.post",
+    operation: str = "create",
+) -> dict[str, Any]:
+    return {
+        "time_us": time_us,
+        "did": did,
+        "kind": "commit",
+        "commit": {
+            "collection": collection,
+            "operation": operation,
+        },
+    }
+
+
+def _sample_identity(
+    *,
+    time_us: int = 1_700_000_000_000_000,
+    did: str = "did:plc:abc123",
+    handle: str = "alice.bsky.social",
+) -> dict[str, Any]:
+    return {
+        "time_us": time_us,
+        "did": did,
+        "kind": "identity",
+        "identity": {
+            "did": did,
+            "handle": handle,
+            "seq": 12345,
+            "time": "2023-11-14T22:13:20Z",
+        },
+    }
+
+
+def _sample_account(
+    *,
+    time_us: int = 1_700_000_000_000_000,
+    did: str = "did:plc:abc123",
+    active: bool = False,
+) -> dict[str, Any]:
+    return {
+        "time_us": time_us,
+        "did": did,
+        "kind": "account",
+        "account": {
+            "active": active,
+            "did": did,
+            "seq": 12346,
+            "time": "2023-11-14T22:13:20Z",
+        },
+    }
+
+
+# --- Remote filter hints ---
+
+
+class TestRemoteFilterHints:
+    def test_collection_eq(self) -> None:
+        band = JetstreamBand()
+        filters = [SignalFilter(path="collection", op="eq", value="app.bsky.feed.post")]
+        hints = band.remote_filter_hints(filters)
+        assert hints == filters
+
+    def test_collection_startswith(self) -> None:
+        band = JetstreamBand()
+        filters = [
+            SignalFilter(path="collection", op="startswith", value="app.bsky.feed")
+        ]
+        hints = band.remote_filter_hints(filters)
+        assert hints == filters
+
+    def test_did_eq(self) -> None:
+        band = JetstreamBand()
+        filters = [SignalFilter(path="did", op="eq", value="did:plc:abc123")]
+        hints = band.remote_filter_hints(filters)
+        assert hints == filters
+
+    def test_excludes_non_matching(self) -> None:
+        band = JetstreamBand()
+        filters = [
+            SignalFilter(path="payload.action", op="eq", value="create"),
+            SignalFilter(path="did", op="contains", value="plc"),
+            SignalFilter(path="collection", op="ne", value="app.bsky.feed.post"),
+        ]
+        hints = band.remote_filter_hints(filters)
+        assert hints == []
+
+    def test_mixed_filters(self) -> None:
+        band = JetstreamBand()
+        collection_filter = SignalFilter(
+            path="collection", op="eq", value="app.bsky.feed.post"
+        )
+        did_filter = SignalFilter(path="did", op="eq", value="did:plc:abc123")
+        unrelated = SignalFilter(path="payload.action", op="eq", value="create")
+        hints = band.remote_filter_hints([collection_filter, did_filter, unrelated])
+        assert hints == [collection_filter, did_filter]
+
+
+# --- Message to signal conversion ---
+
+
+class TestCommitToSignal:
+    def test_basic_commit(self) -> None:
+        msg = _sample_commit()
+        signal = _commit_to_signal(
+            msg, "did:plc:abc123", datetime(2023, 11, 14, 22, 13, 20, tzinfo=UTC)
+        )
+
+        assert signal.band == "atproto"
+        assert signal.signal_id == "1700000000000000"
+        assert signal.topic == "app.bsky.feed.post"
+        assert signal.payload["did"] == "did:plc:abc123"
+        assert signal.payload["operation"] == "create"
+        assert signal.payload["collection"] == "app.bsky.feed.post"
+        assert signal.summary == "did:plc:abc123 create app.bsky.feed.post"
+
+    def test_commit_with_record_text(self) -> None:
+        msg = _sample_commit()
+        msg["commit"]["record"] = {"$type": "app.bsky.feed.post", "text": "hello world"}
+        signal = _commit_to_signal(
+            msg, "did:plc:abc123", datetime(2023, 11, 14, 22, 13, 20, tzinfo=UTC)
+        )
+
+        assert "hello world" in signal.summary
+        assert signal.payload["record"]["text"] == "hello world"
+
+    def test_commit_with_non_dict_record(self) -> None:
+        msg = _sample_commit()
+        msg["commit"]["record"] = "just a string"
+        signal = _commit_to_signal(
+            msg, "did:plc:abc123", datetime(2023, 11, 14, 22, 13, 20, tzinfo=UTC)
+        )
+
+        assert "record" not in signal.payload
+        assert "just a string" not in signal.summary
+
+    def test_missing_commit_fields(self) -> None:
+        msg: dict[str, Any] = {"kind": "commit"}
+        signal = _commit_to_signal(msg, "", datetime(1970, 1, 1, tzinfo=UTC))
+
+        assert signal.signal_id == "0"
+        assert signal.topic == ""
+        assert signal.summary == " unknown "
+        assert signal.payload["rkey"] == ""
+        assert signal.payload["rev"] == ""
+
+
+class TestIdentityToSignal:
+    def test_handle_change(self) -> None:
+        msg = _sample_identity(handle="alice.newdomain.com")
+        signal = _identity_to_signal(
+            msg, "did:plc:abc123", datetime(2023, 11, 14, 22, 13, 20, tzinfo=UTC)
+        )
+
+        assert signal.topic == "identity"
+        assert signal.summary == "did:plc:abc123 is now @alice.newdomain.com"
+        assert signal.payload == msg
+
+    def test_missing_handle(self) -> None:
+        msg = _sample_identity()
+        msg["identity"] = {"did": "did:plc:abc123", "seq": 1, "time": ""}
+        signal = _identity_to_signal(
+            msg, "did:plc:abc123", datetime(2023, 11, 14, 22, 13, 20, tzinfo=UTC)
+        )
+
+        assert signal.summary == "did:plc:abc123 identity updated"
+
+    def test_missing_identity_block(self) -> None:
+        msg: dict[str, Any] = {"kind": "identity", "time_us": 0}
+        signal = _identity_to_signal(msg, "", datetime(1970, 1, 1, tzinfo=UTC))
+
+        assert signal.topic == "identity"
+        assert signal.summary == " identity updated"
+
+
+class TestAccountToSignal:
+    def test_deactivated(self) -> None:
+        msg = _sample_account(active=False)
+        signal = _account_to_signal(
+            msg, "did:plc:abc123", datetime(2023, 11, 14, 22, 13, 20, tzinfo=UTC)
+        )
+
+        assert signal.topic == "account"
+        assert signal.summary == "did:plc:abc123 account deactivated"
+        assert signal.payload == msg
+
+    def test_active(self) -> None:
+        msg = _sample_account(active=True)
+        signal = _account_to_signal(
+            msg, "did:plc:abc123", datetime(2023, 11, 14, 22, 13, 20, tzinfo=UTC)
+        )
+
+        assert signal.summary == "did:plc:abc123 account active"
+
+    def test_missing_account_block(self) -> None:
+        msg: dict[str, Any] = {"kind": "account", "time_us": 0}
+        signal = _account_to_signal(msg, "", datetime(1970, 1, 1, tzinfo=UTC))
+
+        assert signal.topic == "account"
+        assert signal.summary == " account active"
+
+
+class TestMessageToSignal:
+    def test_dispatches_commit(self) -> None:
+        msg = _sample_commit()
+        signal = _message_to_signal(msg)
+        assert signal.topic == "app.bsky.feed.post"
+
+    def test_dispatches_identity(self) -> None:
+        msg = _sample_identity()
+        signal = _message_to_signal(msg)
+        assert signal.topic == "identity"
+        assert "alice.bsky.social" in signal.summary
+
+    def test_dispatches_account(self) -> None:
+        msg = _sample_account()
+        signal = _message_to_signal(msg)
+        assert signal.topic == "account"
+        assert "deactivated" in signal.summary
+
+    def test_unknown_kind_treated_as_account(self) -> None:
+        msg: dict[str, Any] = {"kind": "unknown_future_type", "time_us": 0, "did": ""}
+        signal = _message_to_signal(msg)
+        assert signal.topic == "account"
+
+    def test_missing_kind_defaults_to_commit(self) -> None:
+        msg: dict[str, Any] = {"time_us": 0}
+        signal = _message_to_signal(msg)
+        assert signal.topic == ""
+        assert "unknown" in signal.summary
+
+    def test_timestamp_parsing(self) -> None:
+        msg = _sample_commit(time_us=1_700_000_000_000_000)
+        signal = _message_to_signal(msg)
+        assert signal.timestamp == datetime(2023, 11, 14, 22, 13, 20, tzinfo=UTC)
+
+
+# --- Context manager ---
+
+
+class TestContextManager:
+    async def test_aenter_aexit(self) -> None:
+        band = JetstreamBand()
+        async with band as b:
+            assert b is band
+
+
+# --- WebSocket listen ---
+
+
+class FakeWebSocket:
+    """Simulates an async iterable WebSocket connection."""
+
+    def __init__(self, messages: list[dict[str, Any]]) -> None:
+        self._messages = messages
+
+    def __aiter__(self) -> AsyncIterator[str]:
+        return self._iter()
+
+    async def _iter(self) -> AsyncIterator[str]:
+        for msg in self._messages:
+            yield json.dumps(msg)
+
+
+@asynccontextmanager
+async def fake_connect(
+    url: str,
+    messages: list[dict[str, Any]] | None = None,
+) -> AsyncIterator[FakeWebSocket]:
+    """Drop-in replacement for websockets.connect as an async context manager."""
+    yield FakeWebSocket(messages or [])
+
+
+class TestListen:
+    async def test_yields_commit_signals(self) -> None:
+        messages = [_sample_commit(), _sample_commit(operation="delete")]
+
+        with patch(
+            "docketeer_atproto.band.websockets.connect",
+            return_value=fake_connect("unused", messages),
+        ):
+            band = JetstreamBand()
+            signals = []
+            async for signal in band.listen("app.bsky.feed.post", []):
+                signals.append(signal)
+
+        assert len(signals) == 2
+        assert signals[0].summary == "did:plc:abc123 create app.bsky.feed.post"
+        assert signals[1].summary == "did:plc:abc123 delete app.bsky.feed.post"
+
+    async def test_yields_mixed_event_types(self) -> None:
+        messages = [
+            _sample_commit(),
+            _sample_identity(),
+            _sample_account(),
+        ]
+
+        with patch(
+            "docketeer_atproto.band.websockets.connect",
+            return_value=fake_connect("unused", messages),
+        ):
+            band = JetstreamBand()
+            signals = []
+            async for signal in band.listen("app.bsky.feed.post", []):
+                signals.append(signal)
+
+        assert len(signals) == 3
+        assert signals[0].topic == "app.bsky.feed.post"
+        assert signals[1].topic == "identity"
+        assert signals[2].topic == "account"
+
+    async def test_cursor_from_last_signal_id(self) -> None:
+        captured_urls: list[str] = []
+
+        original_fake = fake_connect
+
+        def capturing_connect(url: str) -> Any:
+            captured_urls.append(url)
+            return original_fake(url, [])
+
+        with patch(
+            "docketeer_atproto.band.websockets.connect",
+            side_effect=capturing_connect,
+        ):
+            band = JetstreamBand()
+            async for _ in band.listen(
+                "app.bsky.feed.post",
+                [],
+                last_signal_id="1700000000000000",
+            ):
+                pass  # pragma: no cover
+
+        assert len(captured_urls) == 1
+        assert "cursor=1700000000000000" in captured_urls[0]
+
+    async def test_did_filter_in_url(self) -> None:
+        captured_urls: list[str] = []
+
+        original_fake = fake_connect
+
+        def capturing_connect(url: str) -> Any:
+            captured_urls.append(url)
+            return original_fake(url, [])
+
+        band = JetstreamBand()
+        filters = [
+            SignalFilter(path="did", op="eq", value="did:plc:abc123"),
+            SignalFilter(path="collection", op="eq", value="app.bsky.feed.post"),
+        ]
+        with patch(
+            "docketeer_atproto.band.websockets.connect",
+            side_effect=capturing_connect,
+        ):
+            async for _ in band.listen("app.bsky.feed.post", filters):
+                pass  # pragma: no cover
+
+        assert len(captured_urls) == 1
+        assert "wantedDids=did%3Aplc%3Aabc123" in captured_urls[0]
+
+    async def test_collection_filter_skipped_in_url(self) -> None:
+        captured_urls: list[str] = []
+
+        original_fake = fake_connect
+
+        def capturing_connect(url: str) -> Any:
+            captured_urls.append(url)
+            return original_fake(url, [])
+
+        band = JetstreamBand()
+        filters = [SignalFilter(path="collection", op="eq", value="app.bsky.feed.post")]
+        with patch(
+            "docketeer_atproto.band.websockets.connect",
+            side_effect=capturing_connect,
+        ):
+            async for _ in band.listen("app.bsky.feed.post", filters):
+                pass  # pragma: no cover
+
+        assert len(captured_urls) == 1
+        assert captured_urls[0].count("wantedCollections") == 1
+
+    async def test_no_cursor_without_last_signal_id(self) -> None:
+        captured_urls: list[str] = []
+
+        original_fake = fake_connect
+
+        def capturing_connect(url: str) -> Any:
+            captured_urls.append(url)
+            return original_fake(url, [])
+
+        band = JetstreamBand()
+        with patch(
+            "docketeer_atproto.band.websockets.connect",
+            side_effect=capturing_connect,
+        ):
+            async for _ in band.listen("app.bsky.feed.post", []):
+                pass  # pragma: no cover
+
+        assert len(captured_urls) == 1
+        assert "cursor" not in captured_urls[0]
+
+
+# --- Relay URL config ---
+
+
+class TestRelayUrlConfig:
+    def test_default_relay_urls(self) -> None:
+        band = JetstreamBand()
+        assert len(band._relay_urls) == 2
+        assert "jetstream1" in band._relay_urls[0]
+        assert "jetstream2" in band._relay_urls[1]
+
+    def test_custom_relay_url(self) -> None:
+        with patch.dict(
+            "os.environ",
+            {"DOCKETEER_ATPROTO_RELAY_URL": "wss://custom.example.com/subscribe"},
+        ):
+            band = JetstreamBand()
+            assert band._relay_urls == ["wss://custom.example.com/subscribe"]
+
+    def test_round_robin_across_calls(self) -> None:
+        band = JetstreamBand()
+        first = band._pick_relay()
+        second = band._pick_relay()
+        third = band._pick_relay()
+
+        assert first == DEFAULT_RELAY_URLS[0]
+        assert second == DEFAULT_RELAY_URLS[1]
+        assert third == DEFAULT_RELAY_URLS[0]
+
+    def test_round_robin_single_relay(self) -> None:
+        with patch.dict(
+            "os.environ",
+            {"DOCKETEER_ATPROTO_RELAY_URL": "wss://only.one/subscribe"},
+        ):
+            band = JetstreamBand()
+            assert band._pick_relay() == "wss://only.one/subscribe"
+            assert band._pick_relay() == "wss://only.one/subscribe"
+
+    async def test_listen_uses_picked_relay(self) -> None:
+        captured_urls: list[str] = []
+
+        original_fake = fake_connect
+
+        def capturing_connect(url: str) -> Any:
+            captured_urls.append(url)
+            return original_fake(url, [])
+
+        band = JetstreamBand()
+        with patch(
+            "docketeer_atproto.band.websockets.connect",
+            side_effect=capturing_connect,
+        ):
+            async for _ in band.listen("app.bsky.feed.post", []):
+                pass  # pragma: no cover
+
+            async for _ in band.listen("app.bsky.feed.post", []):
+                pass  # pragma: no cover
+
+        assert len(captured_urls) == 2
+        assert "jetstream1" in captured_urls[0]
+        assert "jetstream2" in captured_urls[1]