quorum-api 0.1.0__tar.gz

quorum_api-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: quorum-api
+Version: 0.1.0
+Summary: Typed Python client for the Quorum market evidence API. Errors are values, Retry-After is honoured, zero dependencies.
+Author: Quorum
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Godzilla-lab/Quorum-API
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# quorum-api (Python)
+
+The typed Python client for the Quorum market evidence API. Written against
+`spec/openapi.yaml`, which is the contract. Standard library only: no
+dependencies, and the transport is injectable so the tests run with no
+network at all.
+
+Errors are values, never raised. Retry-After is honoured, and
+`wait_for_report` implements the polling loop correctly once so every caller
+does not implement it wrongly.
+
+```python
+from quorum_api import QuorumClient
+
+client = QuorumClient("https://quorum-api-j15n.onrender.com", api_key="qk_...")
+
+accepted = client.create_report("running shoes", terms=["sizing"])
+if accepted.ok:
+    report = client.wait_for_report(accepted.data["id"])
+    if report.ok:
+        for finding in report.data["findings"]:
+            print(finding["term"], finding["records"], "records")
+
+# Every receipt id resolves back to the real record behind it.
+record = client.get_evidence("rc_4d6d444821b0044f")
+```
+
+Not yet published to PyPI. Install from the repo:
+
+```bash
+pip install packages/sdk-py
+```
+
+Tests: `python3 -m unittest discover -s packages/sdk-py/tests`

quorum_api-0.1.0/README.md

@@ -0,0 +1,34 @@
+# quorum-api (Python)
+
+The typed Python client for the Quorum market evidence API. Written against
+`spec/openapi.yaml`, which is the contract. Standard library only: no
+dependencies, and the transport is injectable so the tests run with no
+network at all.
+
+Errors are values, never raised. Retry-After is honoured, and
+`wait_for_report` implements the polling loop correctly once so every caller
+does not implement it wrongly.
+
+```python
+from quorum_api import QuorumClient
+
+client = QuorumClient("https://quorum-api-j15n.onrender.com", api_key="qk_...")
+
+accepted = client.create_report("running shoes", terms=["sizing"])
+if accepted.ok:
+    report = client.wait_for_report(accepted.data["id"])
+    if report.ok:
+        for finding in report.data["findings"]:
+            print(finding["term"], finding["records"], "records")
+
+# Every receipt id resolves back to the real record behind it.
+record = client.get_evidence("rc_4d6d444821b0044f")
+```
+
+Not yet published to PyPI. Install from the repo:
+
+```bash
+pip install packages/sdk-py
+```
+
+Tests: `python3 -m unittest discover -s packages/sdk-py/tests`

quorum_api-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quorum-api"
+version = "0.1.0"
+description = "Typed Python client for the Quorum market evidence API. Errors are values, Retry-After is honoured, zero dependencies."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Quorum" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://github.com/Godzilla-lab/Quorum-API"
+
+[tool.setuptools]
+packages = ["quorum_api"]

quorum_api-0.1.0/quorum_api/__init__.py

@@ -0,0 +1,30 @@
+"""quorum-api. The typed Python client for the hosted API.
+
+WRITTEN AGAINST spec/openapi.yaml, WHICH IS THE CONTRACT. Every method here is
+one operationId from that file, and the spec wins when they disagree.
+
+THE SAME TWO DECISIONS THE JAVASCRIPT SDK MADE, for the same reasons.
+
+ERRORS ARE VALUES, NEVER RAISED. The house rule everywhere a vendor can be
+down, and an SDK IS the place a vendor can be down. A caller gets a Result
+whose error carries the server's type, message and requestId rather than an
+exception, because the interesting failures here are a 429, a 503 with a
+Retry-After, and a report that is simply not finished, and none of those are
+exceptional.
+
+IT HONOURS RETRY-AFTER. The server sheds under load with a 503 and rate
+limits with a 429, both carrying the wait. wait_for_report implements the
+polling loop correctly once, so every caller does not implement it wrongly.
+
+ZERO DEPENDENCIES. The standard library's urllib is the transport, and the
+transport is injectable so the tests run with no network at all.
+"""
+
+from .client import (
+    ApiError,
+    QuorumClient,
+    Result,
+)
+
+__all__ = ["ApiError", "QuorumClient", "Result"]
+__version__ = "0.1.0"

quorum_api-0.1.0/quorum_api/client.py

@@ -0,0 +1,314 @@
+"""The client. See the package docstring for the two decisions that shape it."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple
+from urllib.parse import quote
+
+# What a transport returns: status, lowercased headers, body bytes.
+TransportResponse = Tuple[int, Dict[str, str], bytes]
+# (method, url, headers, body bytes or None, timeout seconds) -> response.
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], TransportResponse]
+
+
+@dataclass
+class ApiError:
+    """The server's machine readable failure, or the absence of a server.
+
+    type is the server's class: rate_limited, not_found, queue_saturated,
+    unauthorized, bad_request, conflict; or this client's own two, network
+    and timeout, when the request never got an answer. status is the HTTP
+    status, or 0 when nothing answered at all, which is a different problem
+    from any status code and a caller should be able to tell them apart.
+    """
+
+    type: str
+    message: str
+    request_id: Optional[str] = None
+    # Present on 429 and 503. Seconds. Honour it.
+    retry_after_seconds: Optional[float] = None
+    status: int = 0
+
+
+@dataclass
+class Result:
+    """ok with data, or not ok with error. Never both, never neither."""
+
+    ok: bool
+    data: Any = None
+    error: Optional[ApiError] = None
+
+
+def _failure(status: int, kind: str, message: str,
+             request_id: Optional[str] = None,
+             retry_after: Optional[float] = None) -> Result:
+    return Result(ok=False, error=ApiError(
+        type=kind, message=message, request_id=request_id,
+        retry_after_seconds=retry_after, status=status,
+    ))
+
+
+def _default_transport(method: str, url: str, headers: Dict[str, str],
+                       body: Optional[bytes], timeout: float) -> TransportResponse:
+    request = urllib.request.Request(url, data=body, method=method)
+    for name, value in headers.items():
+        request.add_header(name, value)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return (response.status,
+                    {k.lower(): v for k, v in response.headers.items()},
+                    response.read())
+    except urllib.error.HTTPError as err:
+        # urllib raises on any non-2xx. The status and body are still the
+        # server speaking, so they travel back as a response, not an error.
+        return (err.code,
+                {k.lower(): v for k, v in (err.headers or {}).items()},
+                err.read())
+
+
+class QuorumClient:
+    """One instance per base URL and key.
+
+    The base URL is supplied by the caller and never hardcoded. That is what
+    makes this a client for YOUR instance rather than a vendor client: the
+    address is configuration, hosted or self hosted alike.
+    """
+
+    def __init__(self, base_url: str, api_key: Optional[str] = None,
+                 timeout_seconds: float = 30.0,
+                 transport: Optional[Transport] = None) -> None:
+        self._base = base_url.rstrip("/") + "/v1"
+        # Trimmed for the reason learned three times on 2026-08-24: a pasted
+        # key carries a newline, and an untrimmed one dies at the header.
+        self._api_key = api_key.strip() if api_key else None
+        self._timeout = timeout_seconds
+        self._transport = transport or _default_transport
+
+    def _headers(self, has_body: bool) -> Dict[str, str]:
+        headers = {"accept": "application/json"}
+        if has_body:
+            headers["content-type"] = "application/json"
+        if self._api_key:
+            headers["authorization"] = "Bearer " + self._api_key
+        return headers
+
+    def _call(self, method: str, path: str, body: Any = None) -> Result:
+        payload = None if body is None else json.dumps(body).encode("utf-8")
+        try:
+            status, headers, raw = self._transport(
+                method, self._base + path, self._headers(payload is not None),
+                payload, self._timeout)
+        except Exception as cause:  # noqa: BLE001 - errors are values here.
+            kind = "timeout" if "timed out" in str(cause).lower() else "network"
+            return _failure(0, kind, str(cause))
+
+        text = raw.decode("utf-8", errors="replace") if raw else ""
+        try:
+            parsed = json.loads(text) if text else None
+        except ValueError:
+            # A proxy returning HTML is the common case here, and a raw json
+            # parse error would send somebody debugging this client.
+            return _failure(status, "bad_response",
+                            "the server returned %d with a body that is not json" % status)
+
+        if 200 <= status < 300:
+            return Result(ok=True, data=parsed)
+
+        err = (parsed or {}).get("error") if isinstance(parsed, dict) else None
+        err = err if isinstance(err, dict) else {}
+        # The header wins over the body: a proxy may add one the app did not.
+        header = headers.get("retry-after")
+        retry = None
+        if header is not None:
+            try:
+                retry = float(header)
+            except ValueError:
+                retry = None
+        if retry is None:
+            retry = err.get("retryAfterSeconds")
+        return _failure(status,
+                        err.get("type") or "http_error",
+                        err.get("message") or ("the server returned %d" % status),
+                        err.get("requestId"),
+                        retry)
+
+    # --- reports, the slow path ---
+
+    def create_report(self, subject: str, *, terms: Optional[List[str]] = None,
+                      communities: Optional[List[str]] = None,
+                      sources: Optional[List[str]] = None,
+                      include_ads: Optional[bool] = None,
+                      offline: Optional[bool] = None,
+                      cap_usd: Optional[float] = None,
+                      deadline_ms: Optional[int] = None,
+                      webhook_url: Optional[str] = None) -> Result:
+        body: Dict[str, Any] = {"subject": subject}
+        for key, value in (("terms", terms), ("communities", communities),
+                           ("sources", sources), ("includeAds", include_ads),
+                           ("offline", offline), ("capUsd", cap_usd),
+                           ("deadlineMs", deadline_ms), ("webhookUrl", webhook_url)):
+            if value is not None:
+                body[key] = value
+        return self._call("POST", "/reports", body)
+
+    def get_report(self, report_id: str) -> Result:
+        return self._call("GET", "/reports/" + quote(report_id, safe=""))
+
+    def cancel_report(self, report_id: str) -> Result:
+        return self._call("DELETE", "/reports/" + quote(report_id, safe=""))
+
+    # --- evidence, the fast path ---
+
+    def get_evidence(self, receipt_id: str) -> Result:
+        return self._call("GET", "/evidence/" + quote(receipt_id, safe=""))
+
+    def get_evidence_batch(self, receipt_ids: List[str]) -> Result:
+        return self._call("POST", "/evidence/batch", {"receiptIds": receipt_ids})
+
+    def search_evidence(self, query: str, *, category: Optional[str] = None,
+                        limit: Optional[int] = None) -> Result:
+        body: Dict[str, Any] = {"query": query}
+        if category is not None:
+            body["category"] = category
+        if limit is not None:
+            body["limit"] = limit
+        return self._call("POST", "/evidence/search", body)
+
+    def get_ad_evidence(self, ad_id: str) -> Result:
+        return self._call("GET", "/evidence/ads/" + quote(ad_id, safe=""))
+
+    def get_category(self, slug: str) -> Result:
+        return self._call("GET", "/categories/" + quote(slug, safe=""))
+
+    def list_categories(self) -> Result:
+        return self._call("GET", "/categories")
+
+    # --- verification and account ---
+
+    def verify_claims(self, claims: List[Dict[str, Any]]) -> Result:
+        """Re-resolve every cited id against the corpus, ours or anybody's.
+
+        A claim citing an id that does not exist is reported rather than
+        quietly passed, which is the point of the whole product.
+        """
+        return self._call("POST", "/verify", {"claims": claims})
+
+    def get_usage(self) -> Result:
+        return self._call("GET", "/usage")
+
+    def healthz(self) -> Result:
+        return self._call("GET", "/healthz")
+
+    # --- the loop every caller would otherwise write badly ---
+
+    def wait_for_report(self, report_id: str, *,
+                        timeout_seconds: float = 900.0,
+                        poll_seconds: float = 2.0,
+                        on_poll: Optional[Callable[[Any], None]] = None,
+                        sleep: Callable[[float], None] = time.sleep,
+                        clock: Callable[[], float] = time.monotonic) -> Result:
+        """Poll a report to completion, honouring the server's own pacing.
+
+        Three things this gets right that a naive loop does not: a 503 is the
+        load shedder speaking, not a failure; the server sets the pace through
+        Retry-After rather than the client guessing; and on timeout it returns
+        the last status it saw rather than pretending the report failed.
+        """
+        deadline = clock() + timeout_seconds
+        last_status: Optional[str] = None
+
+        while True:
+            result = self.get_report(report_id)
+
+            if result.ok:
+                data = result.data if isinstance(result.data, dict) else {}
+                last_status = data.get("status")
+                if on_poll is not None:
+                    on_poll(result.data)
+                if last_status not in ("queued", "running"):
+                    return result
+                suggested = None
+            elif result.error is not None and result.error.status in (429, 503):
+                suggested = result.error.retry_after_seconds
+            else:
+                # A real error. Anything else was the server asking us to wait.
+                return result
+
+            wait = max(poll_seconds, float(suggested or 0))
+            if clock() + wait > deadline:
+                message = ("gave up after the deadline with the report still %s" % last_status
+                           if last_status else
+                           "gave up after the deadline without reaching the server")
+                return _failure(0, "timeout", message)
+            sleep(wait)
+
+    def stream_report(self, report_id: str,
+                      opener: Optional[Callable[[urllib.request.Request, float], Any]] = None,
+                      ) -> Iterator[Dict[str, Any]]:
+        """Yield a running report's server sent events as dicts.
+
+        Parsed by hand for the same reason the JavaScript SDK parses by hand:
+        the frame is id, event and data lines terminated by a blank line, and
+        a chunk boundary can fall anywhere, so the buffer is drained on
+        complete frames only. A transport level failure ends the stream
+        rather than raising, because a dropped stream is a normal way for a
+        finished report to say goodbye.
+        """
+        request = urllib.request.Request(
+            self._base + "/reports/" + quote(report_id, safe="") + "/stream")
+        for name, value in self._headers(False).items():
+            request.add_header(name, "text/event-stream" if name == "accept" else value)
+
+        open_stream = opener or (lambda req, timeout: urllib.request.urlopen(req, timeout=timeout))
+        try:
+            response = open_stream(request, self._timeout)
+        except Exception:  # noqa: BLE001 - a stream that never opened is empty.
+            return
+
+        buffer = ""
+        try:
+            while True:
+                chunk = response.read(1024)
+                if not chunk:
+                    break
+                buffer += chunk.decode("utf-8", errors="replace")
+                while "\n\n" in buffer:
+                    frame, buffer = buffer.split("\n\n", 1)
+                    event = _parse_frame(frame)
+                    if event is not None:
+                        yield event
+        except Exception:  # noqa: BLE001
+            return
+        finally:
+            close = getattr(response, "close", None)
+            if close is not None:
+                close()
+
+
+def _parse_frame(frame: str) -> Optional[Dict[str, Any]]:
+    event_id = 0
+    kind = "message"
+    data: List[str] = []
+    for line in frame.split("\n"):
+        if line.startswith("id:"):
+            try:
+                event_id = int(line[3:].strip())
+            except ValueError:
+                event_id = 0
+        elif line.startswith("event:"):
+            kind = line[6:].strip()
+        elif line.startswith("data:"):
+            # Multiple data lines in one frame concatenate, per the SSE spec.
+            data.append(line[5:].strip())
+    if not data:
+        return None
+    joined = "\n".join(data)
+    try:
+        return {"id": event_id, "type": kind, "data": json.loads(joined)}
+    except ValueError:
+        return {"id": event_id, "type": kind, "data": joined}

quorum_api-0.1.0/quorum_api.egg-info/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: quorum-api
+Version: 0.1.0
+Summary: Typed Python client for the Quorum market evidence API. Errors are values, Retry-After is honoured, zero dependencies.
+Author: Quorum
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Godzilla-lab/Quorum-API
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# quorum-api (Python)
+
+The typed Python client for the Quorum market evidence API. Written against
+`spec/openapi.yaml`, which is the contract. Standard library only: no
+dependencies, and the transport is injectable so the tests run with no
+network at all.
+
+Errors are values, never raised. Retry-After is honoured, and
+`wait_for_report` implements the polling loop correctly once so every caller
+does not implement it wrongly.
+
+```python
+from quorum_api import QuorumClient
+
+client = QuorumClient("https://quorum-api-j15n.onrender.com", api_key="qk_...")
+
+accepted = client.create_report("running shoes", terms=["sizing"])
+if accepted.ok:
+    report = client.wait_for_report(accepted.data["id"])
+    if report.ok:
+        for finding in report.data["findings"]:
+            print(finding["term"], finding["records"], "records")
+
+# Every receipt id resolves back to the real record behind it.
+record = client.get_evidence("rc_4d6d444821b0044f")
+```
+
+Not yet published to PyPI. Install from the repo:
+
+```bash
+pip install packages/sdk-py
+```
+
+Tests: `python3 -m unittest discover -s packages/sdk-py/tests`

quorum_api-0.1.0/quorum_api.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+quorum_api/__init__.py
+quorum_api/client.py
+quorum_api.egg-info/PKG-INFO
+quorum_api.egg-info/SOURCES.txt
+quorum_api.egg-info/dependency_links.txt
+quorum_api.egg-info/top_level.txt
+tests/test_client.py

quorum_api-0.1.0/quorum_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

quorum_api-0.1.0/quorum_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+quorum_api

quorum_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

quorum_api-0.1.0/tests/test_client.py

@@ -0,0 +1,179 @@
+"""The Python client, tested with no network at all.
+
+Every test injects a transport, so the suite runs inside the same egress
+blocked CI namespace as everything else. The behaviours under test are the
+two decisions the client is built on: errors are values, and the server's
+Retry-After sets the pace.
+"""
+
+import io
+import json
+import unittest
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from quorum_api import ApiError, QuorumClient, Result  # noqa: E402
+
+
+def transport_returning(status, body, headers=None):
+    calls = []
+
+    def transport(method, url, request_headers, payload, timeout):
+        calls.append({
+            "method": method, "url": url, "headers": request_headers,
+            "body": payload, "timeout": timeout,
+        })
+        raw = body if isinstance(body, bytes) else json.dumps(body).encode("utf-8")
+        return status, headers or {}, raw
+
+    transport.calls = calls
+    return transport
+
+
+class CallShape(unittest.TestCase):
+    def test_paths_headers_and_encoding(self):
+        transport = transport_returning(200, {"ok": True})
+        client = QuorumClient("https://api.example/", api_key="qk_test\n",
+                              transport=transport)
+        client.get_evidence("rc_abc/def")
+        call = transport.calls[0]
+        self.assertEqual(call["url"], "https://api.example/v1/evidence/rc_abc%2Fdef")
+        self.assertEqual(call["headers"]["authorization"], "Bearer qk_test",
+                         "a pasted newline never reaches the header")
+        self.assertNotIn("content-type", call["headers"], "no body, no content type")
+
+    def test_create_report_sends_only_what_was_given(self):
+        transport = transport_returning(202, {"id": "rep_1", "status": "queued"})
+        client = QuorumClient("https://api.example", transport=transport)
+        result = client.create_report("running shoes", terms=["sizing"], offline=True)
+        self.assertTrue(result.ok)
+        sent = json.loads(transport.calls[0]["body"].decode("utf-8"))
+        self.assertEqual(sent, {"subject": "running shoes", "terms": ["sizing"],
+                                "offline": True},
+                         "absent options are absent, not null")
+
+    def test_keyless_sends_no_authorization(self):
+        transport = transport_returning(200, {"ok": True})
+        QuorumClient("https://api.example", transport=transport).healthz()
+        self.assertNotIn("authorization", transport.calls[0]["headers"])
+
+
+class ErrorsAreValues(unittest.TestCase):
+    def test_server_error_body_travels_back(self):
+        transport = transport_returning(429, {"error": {
+            "type": "rate_limited", "message": "too many",
+            "requestId": "req-1", "retryAfterSeconds": 30,
+        }})
+        result = QuorumClient("https://api.example", transport=transport).get_usage()
+        self.assertFalse(result.ok)
+        self.assertEqual(result.error.type, "rate_limited")
+        self.assertEqual(result.error.status, 429)
+        self.assertEqual(result.error.request_id, "req-1")
+        self.assertEqual(result.error.retry_after_seconds, 30)
+
+    def test_retry_after_header_wins_over_the_body(self):
+        transport = transport_returning(
+            503, {"error": {"type": "overloaded", "message": "shed",
+                            "retryAfterSeconds": 99}},
+            headers={"retry-after": "7"})
+        result = QuorumClient("https://api.example", transport=transport).healthz()
+        self.assertEqual(result.error.retry_after_seconds, 7,
+                         "a proxy may add a header the app did not")
+
+    def test_html_from_a_proxy_is_named_not_raised(self):
+        transport = transport_returning(502, b"<html>bad gateway</html>")
+        result = QuorumClient("https://api.example", transport=transport).healthz()
+        self.assertFalse(result.ok)
+        self.assertEqual(result.error.type, "bad_response")
+        self.assertEqual(result.error.status, 502)
+
+    def test_no_answer_at_all_is_status_zero(self):
+        def transport(method, url, headers, body, timeout):
+            raise OSError("connection refused")
+
+        result = QuorumClient("https://api.example", transport=transport).healthz()
+        self.assertFalse(result.ok)
+        self.assertEqual(result.error.status, 0,
+                         "no server is a different problem from any status code")
+        self.assertEqual(result.error.type, "network")
+
+
+class WaitForReport(unittest.TestCase):
+    def test_polls_until_terminal_and_honours_retry_after(self):
+        answers = [
+            (503, {"error": {"type": "overloaded", "message": "shed"}}, {"retry-after": "5"}),
+            (200, {"id": "rep_1", "status": "running"}, {}),
+            (200, {"id": "rep_1", "status": "complete"}, {}),
+        ]
+        slept = []
+
+        def transport(method, url, headers, body, timeout):
+            status, payload, response_headers = answers.pop(0)
+            return status, response_headers, json.dumps(payload).encode("utf-8")
+
+        client = QuorumClient("https://api.example", transport=transport)
+        result = client.wait_for_report("rep_1", poll_seconds=1.0,
+                                        sleep=slept.append,
+                                        clock=lambda: 0.0)
+        self.assertTrue(result.ok)
+        self.assertEqual(result.data["status"], "complete")
+        self.assertEqual(slept[0], 5.0, "the 503's Retry-After set the first wait")
+        self.assertEqual(slept[1], 1.0, "then the floor took over")
+
+    def test_gives_up_honestly_with_the_last_status_seen(self):
+        transport = transport_returning(200, {"id": "rep_1", "status": "running"})
+        ticks = iter([0.0, 0.0, 1000.0])
+
+        client = QuorumClient("https://api.example", transport=transport)
+        result = client.wait_for_report("rep_1", timeout_seconds=10.0,
+                                        sleep=lambda seconds: None,
+                                        clock=lambda: next(ticks))
+        self.assertFalse(result.ok)
+        self.assertEqual(result.error.type, "timeout")
+        self.assertIn("still running", result.error.message)
+
+    def test_a_real_error_returns_immediately(self):
+        transport = transport_returning(404, {"error": {
+            "type": "not_found", "message": "no report carries this id"}})
+        result = QuorumClient("https://api.example", transport=transport) \
+            .wait_for_report("rep_x", sleep=lambda seconds: None)
+        self.assertFalse(result.ok)
+        self.assertEqual(result.error.type, "not_found")
+
+
+class StreamReport(unittest.TestCase):
+    def test_frames_survive_chunk_boundaries(self):
+        raw = (b"id: 1\nevent: phase\ndata: {\"name\": \"retrieve\"}\n\n"
+               b"id: 2\ndata: plain text\n\n")
+
+        class Response(io.BytesIO):
+            pass
+
+        client = QuorumClient("https://api.example", api_key="k")
+        events = list(client.stream_report(
+            "rep_1", opener=lambda request, timeout: Response(raw)))
+        self.assertEqual(events[0], {"id": 1, "type": "phase",
+                                     "data": {"name": "retrieve"}})
+        self.assertEqual(events[1], {"id": 2, "type": "message",
+                                     "data": "plain text"})
+
+    def test_a_stream_that_never_opens_is_empty_not_an_exception(self):
+        def opener(request, timeout):
+            raise OSError("refused")
+
+        client = QuorumClient("https://api.example")
+        self.assertEqual(list(client.stream_report("rep_1", opener=opener)), [])
+
+
+class Shapes(unittest.TestCase):
+    def test_result_and_error_are_plain_data(self):
+        error = ApiError(type="x", message="y")
+        self.assertEqual(error.status, 0)
+        self.assertIsNone(Result(ok=True, data=1).error)
+
+
+if __name__ == "__main__":
+    unittest.main()