ringwire 0.1.0__tar.gz

ringwire-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Andrei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ringwire-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: ringwire
+Version: 0.1.0
+Summary: Typed Python client for the Ring Partner API (Amazon Vision API): devices, sensors, media, webhooks, account linking.
+Author: Jonathan Andrei
+License: MIT
+Project-URL: Homepage, https://github.com/JonathanSolvesProblems/ringwire
+Project-URL: Documentation, https://developer.amazon.com/docs/ring/api-documentation.html
+Keywords: ring,amazon,vision,api,webhooks,sensors,smart-home
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Dynamic: license-file
+
+# ringwire
+
+A typed Python client for the **Ring Partner API** (the `api.amazonvision.com` API behind the
+Ring Appstore), including the parts most samples skip: sensors, the two-step media
+downloads, chime playback, webhook verification, and the account-linking nonce.
+
+Built for [Watermark](../README.md) and published on its own so other Ring Appstore
+developers do not have to re-read the docs I already read.
+
+```bash
+pip install ringwire
+```
+
+## What it covers
+
+| Area | Calls |
+|---|---|
+| Auth | `RingClient.exchange_code`, `RingClient.refresh` (form-encoded, as Ring requires) |
+| Users and linking | `me()`, `confirm_account_link(nonce)`, `update_integration(status="completed")` |
+| Devices | `list_devices()`, `status()`, `capabilities()`, `configurations()`, `location()` |
+| Sensors | `status()` exposes `flood_faulted`, `freeze_faulted`, `contact_faulted`, `tamper_detected`, `temperature`, `humidity`; `reported_at` is `None` for the 1970 "never reported" epoch |
+| History | `event_history()`, `iter_event_history()` (follows `links.next`, stops on the empty page) |
+| Media | `download_image()` and `download_clip()` do the 303 two-step and read `X-Media-Timestamp` / `X-Media-Origin` |
+| Live | `create_whep_session()`, `close_whep_session()`, `rtsps_url()` |
+| Chimes | `play_chime(device_id, audio_ref)`, with slots read from `configurations()` |
+| Webhooks | `verify_signature`, `verify_and_parse`, `parse_event`, `make_event`, every documented event type including the Early Access sensor events |
+| Nonce | `compute_nonce`, `match_nonce` (URL-safe base64, no padding, 600 s window, constant-time) |
+
+## Things the docs say that this library enforces
+
+- The image and clip endpoints **never trigger a capture**. A `416` raises `MediaNotFound`
+  so the caller can start a live session first.
+- Sensor events have **no history endpoint**. Persist them on receipt.
+- Webhook signatures are computed over the **raw body bytes**. Pass the bytes, not the
+  parsed JSON.
+- Refresh tokens are not Bearer tokens.
+
+## Example
+
+```python
+from ringwire import RingClient, verify_and_parse
+
+client = RingClient(access_token)
+sensors = [d for d in client.list_devices() if client.status(d.id).flood_faulted is not None]
+
+# In your webhook handler (raw bytes, before any JSON parsing):
+event = verify_and_parse(raw_body, headers["X-Signature"], signing_key)
+if event.type == "flood_detected":
+    ...
+```
+
+## Tests
+
+```bash
+pip install -e ".[dev]" && pytest
+```
+
+MIT. Not affiliated with Ring or Amazon.

ringwire-0.1.0/README.md

@@ -0,0 +1,58 @@
+# ringwire
+
+A typed Python client for the **Ring Partner API** (the `api.amazonvision.com` API behind the
+Ring Appstore), including the parts most samples skip: sensors, the two-step media
+downloads, chime playback, webhook verification, and the account-linking nonce.
+
+Built for [Watermark](../README.md) and published on its own so other Ring Appstore
+developers do not have to re-read the docs I already read.
+
+```bash
+pip install ringwire
+```
+
+## What it covers
+
+| Area | Calls |
+|---|---|
+| Auth | `RingClient.exchange_code`, `RingClient.refresh` (form-encoded, as Ring requires) |
+| Users and linking | `me()`, `confirm_account_link(nonce)`, `update_integration(status="completed")` |
+| Devices | `list_devices()`, `status()`, `capabilities()`, `configurations()`, `location()` |
+| Sensors | `status()` exposes `flood_faulted`, `freeze_faulted`, `contact_faulted`, `tamper_detected`, `temperature`, `humidity`; `reported_at` is `None` for the 1970 "never reported" epoch |
+| History | `event_history()`, `iter_event_history()` (follows `links.next`, stops on the empty page) |
+| Media | `download_image()` and `download_clip()` do the 303 two-step and read `X-Media-Timestamp` / `X-Media-Origin` |
+| Live | `create_whep_session()`, `close_whep_session()`, `rtsps_url()` |
+| Chimes | `play_chime(device_id, audio_ref)`, with slots read from `configurations()` |
+| Webhooks | `verify_signature`, `verify_and_parse`, `parse_event`, `make_event`, every documented event type including the Early Access sensor events |
+| Nonce | `compute_nonce`, `match_nonce` (URL-safe base64, no padding, 600 s window, constant-time) |
+
+## Things the docs say that this library enforces
+
+- The image and clip endpoints **never trigger a capture**. A `416` raises `MediaNotFound`
+  so the caller can start a live session first.
+- Sensor events have **no history endpoint**. Persist them on receipt.
+- Webhook signatures are computed over the **raw body bytes**. Pass the bytes, not the
+  parsed JSON.
+- Refresh tokens are not Bearer tokens.
+
+## Example
+
+```python
+from ringwire import RingClient, verify_and_parse
+
+client = RingClient(access_token)
+sensors = [d for d in client.list_devices() if client.status(d.id).flood_faulted is not None]
+
+# In your webhook handler (raw bytes, before any JSON parsing):
+event = verify_and_parse(raw_body, headers["X-Signature"], signing_key)
+if event.type == "flood_detected":
+    ...
+```
+
+## Tests
+
+```bash
+pip install -e ".[dev]" && pytest
+```
+
+MIT. Not affiliated with Ring or Amazon.

ringwire-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ringwire"
+version = "0.1.0"
+description = "Typed Python client for the Ring Partner API (Amazon Vision API): devices, sensors, media, webhooks, account linking."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Jonathan Andrei" }]
+keywords = ["ring", "amazon", "vision", "api", "webhooks", "sensors", "smart-home"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Home Automation",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "respx>=0.21"]
+
+[project.urls]
+Homepage = "https://github.com/JonathanSolvesProblems/ringwire"
+Documentation = "https://developer.amazon.com/docs/ring/api-documentation.html"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ringwire-0.1.0/setup.cfg

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

ringwire-0.1.0/src/ringwire/__init__.py

@@ -0,0 +1,33 @@
+"""ringwire: a typed Python client for the Ring Partner API.
+
+    from ringwire import RingClient, verify_and_parse
+
+    client = RingClient(access_token)
+    for d in client.list_devices():
+        s = client.status(d.id)
+        if s.flood_faulted:
+            ...
+
+    event = verify_and_parse(raw_body, request.headers["X-Signature"], signing_key)
+    if event.type == "flood_detected": ...
+"""
+from .client import API_BASE, OAUTH_TOKEN_URL, RingClient
+from .errors import (Forbidden, MediaNotFound, NonceError, NotFound, RateLimited, RingAPIError, RingError,
+                     SignatureError, Unauthorized)
+from .nonce import compute_nonce, is_fresh, match_nonce
+from .types import (Device, DeviceCapabilities, DeviceConfigurations, DeviceStatus, HistoryEvent, HistoryPage,
+                    MediaClip, MediaImage, TokenSet, User, WhepSession)
+from .webhooks import (ALL_EVENTS, SENSOR_EVENTS, SENSOR_STATE_EVENTS, SENSOR_THRESHOLD_EVENTS, WebhookEvent,
+                       make_event, parse_event, sign, verify_and_parse, verify_signature)
+
+__version__ = "0.1.0"
+__all__ = [
+    "API_BASE", "OAUTH_TOKEN_URL", "RingClient",
+    "RingError", "RingAPIError", "Unauthorized", "Forbidden", "NotFound", "MediaNotFound", "RateLimited",
+    "SignatureError", "NonceError",
+    "compute_nonce", "is_fresh", "match_nonce",
+    "TokenSet", "User", "Device", "DeviceStatus", "DeviceCapabilities", "DeviceConfigurations",
+    "HistoryEvent", "HistoryPage", "MediaImage", "MediaClip", "WhepSession",
+    "WebhookEvent", "parse_event", "verify_signature", "verify_and_parse", "sign", "make_event",
+    "ALL_EVENTS", "SENSOR_EVENTS", "SENSOR_STATE_EVENTS", "SENSOR_THRESHOLD_EVENTS",
+]

ringwire-0.1.0/src/ringwire/client.py

@@ -0,0 +1,332 @@
+"""Synchronous client for the Ring Partner API (api.amazonvision.com).
+
+Covers everything a partner app calls: OAuth token exchange and refresh, users,
+devices (cameras, doorbells, chimes, sensors), event history, image and clip
+download (the two-step 303 flow), WHEP live sessions, chime playback, and the
+app-integrations calls that finish account linking.
+
+Retries 429 (honouring Retry-After) and 5xx with backoff. Never follows the 303
+on media downloads automatically, because the redirect target must be fetched
+without the Bearer header.
+"""
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Iterator
+from typing import Any
+
+import httpx
+
+from .errors import Forbidden, MediaNotFound, NotFound, RateLimited, RingAPIError, Unauthorized
+from .types import (Device, DeviceCapabilities, DeviceConfigurations, DeviceStatus, HistoryEvent,
+                    HistoryPage, MediaClip, MediaImage, TokenSet, User, WhepSession)
+
+API_BASE = "https://api.amazonvision.com"
+OAUTH_TOKEN_URL = "https://oauth.ring.com/oauth/token"
+RTSPS_HOST = "video.rtsp.amazonvision.com"
+RTSPS_PORT = 322
+
+TokenProvider = Callable[[], str]
+
+
+def _error_from_response(r: httpx.Response) -> RingAPIError:
+    code = detail = None
+    try:
+        body = r.json()
+        errs = body.get("errors") or []
+        if errs:
+            code = errs[0].get("code")
+            detail = errs[0].get("detail") or errs[0].get("title")
+        elif "error" in body:
+            code = body.get("error")
+            detail = body.get("error_description") or body.get("message")
+    except Exception:
+        detail = r.text[:200] if r.text else None
+    rid = r.headers.get("X-Request-ID")
+    kw = dict(code=code, detail=detail, request_id=rid)
+    if r.status_code == 401:
+        return Unauthorized(401, **kw)
+    if r.status_code == 403:
+        return Forbidden(403, **kw)
+    if r.status_code == 404:
+        return NotFound(404, **kw)
+    if r.status_code == 416:
+        return MediaNotFound(416, **kw)
+    if r.status_code == 429:
+        ra = r.headers.get("Retry-After")
+        return RateLimited(retry_after=float(ra) if ra else None, **kw)
+    return RingAPIError(r.status_code, **kw)
+
+
+class RingClient:
+    """One client per Ring user. Tokens are user-scoped.
+
+    Pass either a static `access_token` or a `token_provider` callable that
+    returns a currently valid access token (so the caller owns refresh).
+    """
+
+    def __init__(self, access_token: str | None = None, *, token_provider: TokenProvider | None = None,
+                 base_url: str = API_BASE, timeout: float = 20.0, max_retries: int = 3,
+                 transport: httpx.BaseTransport | None = None, user_agent: str = "ringwire-py/0.1"):
+        if not access_token and not token_provider:
+            raise ValueError("access_token or token_provider is required")
+        self._token = access_token
+        self._provider = token_provider
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._http = httpx.Client(timeout=timeout, transport=transport,
+                                  headers={"User-Agent": user_agent}, follow_redirects=False)
+
+    # ---------- auth (static, no token needed) ----------
+
+    @staticmethod
+    def exchange_code(code: str, client_id: str, client_secret: str, code_verifier: str | None = None,
+                      *, token_url: str = OAUTH_TOKEN_URL, transport: httpx.BaseTransport | None = None) -> TokenSet:
+        """Exchange the authorization code Ring POSTed to the Token Exchange URL.
+        One-way codes expire in 60 seconds; partner-initiated in 10 minutes."""
+        form = {"grant_type": "authorization_code", "code": code, "client_id": client_id,
+                "client_secret": client_secret}
+        if code_verifier:
+            form["code_verifier"] = code_verifier
+        with httpx.Client(transport=transport, timeout=20.0) as c:
+            r = c.post(token_url, data=form)
+        if r.status_code != 200:
+            raise _error_from_response(r)
+        return TokenSet.from_json(r.json())
+
+    @staticmethod
+    def refresh(refresh_token: str, client_id: str, client_secret: str, *, token_url: str = OAUTH_TOKEN_URL,
+                transport: httpx.BaseTransport | None = None) -> TokenSet:
+        """Refresh tokens are valid ~30 days and rotate on every exchange; store the new pair."""
+        form = {"grant_type": "refresh_token", "refresh_token": refresh_token, "client_id": client_id,
+                "client_secret": client_secret}
+        with httpx.Client(transport=transport, timeout=20.0) as c:
+            r = c.post(token_url, data=form)
+        if r.status_code != 200:
+            raise _error_from_response(r)
+        return TokenSet.from_json(r.json())
+
+    # ---------- plumbing ----------
+
+    def _auth(self) -> dict[str, str]:
+        token = self._provider() if self._provider else self._token
+        return {"Authorization": f"Bearer {token}"}
+
+    def _request(self, method: str, path: str, *, json: Any = None, params: dict[str, Any] | None = None,
+                 content: bytes | str | None = None, headers: dict[str, str] | None = None,
+                 ok: tuple[int, ...] = (200, 201)) -> httpx.Response:
+        url = path if path.startswith("http") else f"{self.base_url}{path}"
+        attempt = 0
+        while True:
+            h = {**self._auth(), **(headers or {})}
+            r = self._http.request(method, url, json=json, params=params, content=content, headers=h)
+            if r.status_code in ok:
+                return r
+            err = _error_from_response(r)
+            retryable = isinstance(err, RateLimited) or 500 <= r.status_code < 600
+            if retryable and attempt < self.max_retries:
+                delay = err.retry_after if isinstance(err, RateLimited) and err.retry_after else (2 ** attempt) * 0.5
+                time.sleep(delay)
+                attempt += 1
+                continue
+            raise err
+
+    def _get_json(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._request("GET", path, params=params).json()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "RingClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # ---------- users / account ----------
+
+    def me(self) -> User:
+        return User.from_json(self._get_json("/v1/users/me"))
+
+    def confirm_account_link(self, nonce: str, account_identifier: str | None = None) -> dict[str, Any]:
+        """One-way linking step 1: POST the nonce. Status becomes `awaiting`."""
+        body: dict[str, Any] = {"nonce": nonce}
+        if account_identifier:
+            body["account_identifier"] = account_identifier
+        return self._request("POST", "/v1/accounts/me/app-integrations", json=body).json()
+
+    def update_integration(self, status: str | None = None, account_identifier: str | None = None) -> dict[str, Any]:
+        """Step 2, mandatory: PATCH `status: completed`. Without it the integration
+        stays `awaiting`, device consents stay inactive and no webhooks arrive."""
+        body: dict[str, Any] = {}
+        if status:
+            body["status"] = status
+        if account_identifier:
+            body["account_identifier"] = account_identifier
+        if not body:
+            raise ValueError("status or account_identifier is required")
+        return self._request("PATCH", "/v1/accounts/me/app-integrations", json=body).json()
+
+    def subscriptions(self) -> dict[str, Any]:
+        return self._get_json("/v1/accounts/me/subscriptions")
+
+    # ---------- devices ----------
+
+    def list_devices(self, include: list[str] | None = None) -> list[Device]:
+        params = {"include": ",".join(include)} if include else None
+        body = self._get_json("/v1/devices", params=params)
+        return [Device.from_json(d) for d in body.get("data", [])]
+
+    def list_devices_raw(self, include: list[str] | None = None) -> dict[str, Any]:
+        params = {"include": ",".join(include)} if include else None
+        return self._get_json("/v1/devices", params=params)
+
+    def get_device(self, device_id: str) -> Device:
+        body = self._get_json(f"/v1/devices/{device_id}")
+        return Device.from_json(body.get("data", body))
+
+    def status(self, device_id: str, component_id: int | None = None) -> DeviceStatus:
+        params = {"component_id": component_id} if component_id is not None else None
+        return DeviceStatus.from_json(self._get_json(f"/v1/devices/{device_id}/status", params=params))
+
+    def capabilities(self, device_id: str, component_id: int | None = None) -> DeviceCapabilities:
+        params = {"component_id": component_id} if component_id is not None else None
+        return DeviceCapabilities.from_json(self._get_json(f"/v1/devices/{device_id}/capabilities", params=params))
+
+    def configurations(self, device_id: str, component_id: int | None = None) -> DeviceConfigurations:
+        params = {"component_id": component_id} if component_id is not None else None
+        return DeviceConfigurations.from_json(self._get_json(f"/v1/devices/{device_id}/configurations", params=params))
+
+    def location(self, device_id: str) -> dict[str, Any]:
+        return self._get_json(f"/v1/devices/{device_id}/location")
+
+    # ---------- event history (cameras and doorbells only; sensors have none) ----------
+
+    def event_history(self, device_id: str, event_types: str | list[str] | None = None,
+                      page_key: str | None = None) -> HistoryPage:
+        params: dict[str, Any] = {}
+        if event_types:
+            params["event_types"] = ",".join(event_types) if isinstance(event_types, list) else event_types
+        if page_key:
+            params["page[key]"] = page_key
+        body = self._get_json(f"/v1/history/devices/{device_id}/events", params=params or None)
+        events = [HistoryEvent.from_json(d) for d in body.get("data", [])]
+        return HistoryPage(events=events, next_path=(body.get("links") or {}).get("next"), raw=body)
+
+    def iter_event_history(self, device_id: str, event_types: str | list[str] | None = None,
+                           max_pages: int = 50) -> Iterator[HistoryEvent]:
+        """Follows `links.next` until a page comes back empty. Ring keeps sending a
+        `next` link even on the last page, so an empty page is the stop signal."""
+        page = self.event_history(device_id, event_types)
+        pages = 1
+        while True:
+            yield from page.events
+            if not page.events or not page.next_path or pages >= max_pages:
+                return
+            key = _page_key_from_path(page.next_path)
+            page = self.event_history(device_id, event_types, page_key=key)
+            pages += 1
+
+    # ---------- media ----------
+
+    def download_image(self, device_id: str, *, at_timestamp_ms: int | None = None,
+                       start_ms: int | None = None, end_ms: int | None = None,
+                       fmt: str = "jpeg", width: int = 1920, height: int = 1080,
+                       component_id: int | None = None) -> MediaImage:
+        """Two-step download. Pass `at_timestamp_ms` (±10 s tolerance) or a
+        `start_ms`/`end_ms` window of at most 24 h for the latest frame in it.
+
+        This never captures. If nothing was recorded near that time Ring returns
+        416 and this raises `MediaNotFound`.
+        """
+        if at_timestamp_ms is not None:
+            payload: dict[str, Any] = {"type": "at_timestamp", "timestamp": int(at_timestamp_ms)}
+        elif start_ms is not None:
+            payload = {"type": "latest_in_range", "start_timestamp": int(start_ms)}
+            if end_ms is not None:
+                payload["end_timestamp"] = int(end_ms)
+        else:
+            raise ValueError("at_timestamp_ms or start_ms is required")
+        payload["image_options"] = {"format": fmt, "resolution": {"width": width, "height": height}}
+        params = {"component_id": component_id} if component_id is not None else None
+        r = self._request("POST", f"/v1/devices/{device_id}/media/image/download", json=payload,
+                          params=params, ok=(303,))
+        presigned = r.headers.get("Location")
+        if not presigned:
+            raise RingAPIError(r.status_code, code="NO_LOCATION", detail="303 without Location header")
+        dl = self._http.get(presigned, follow_redirects=True)
+        if dl.status_code != 200:
+            raise _error_from_response(dl)
+        ts = dl.headers.get("X-Media-Timestamp")
+        return MediaImage(
+            data=dl.content,
+            content_type=dl.headers.get("Content-Type", "application/octet-stream"),
+            media_timestamp_ms=int(ts) if ts and ts.isdigit() else None,
+            media_origin=dl.headers.get("X-Media-Origin"),
+            requested_timestamp_ms=at_timestamp_ms,
+        )
+
+    def download_clip(self, device_id: str, *, timestamp_ms: int, duration_ms: int = 5000,
+                      codec: str = "avc", frame_rate: int = 5, width: int = 1080, height: int = 720,
+                      audio: bool = False, component_id: int | None = None) -> MediaClip:
+        """MP4 of already-recorded footage (up to 15 minutes). 206 means Ring had
+        only part of the window; `partial` is set and the headers say what came back."""
+        payload = {
+            "timestamp": int(timestamp_ms), "duration": int(duration_ms),
+            "video_options": {"codec": codec, "frame_rate": frame_rate,
+                              "resolution": {"width": width, "height": height}},
+            "audio_options": {"audio_enabled": bool(audio)},
+        }
+        params = {"component_id": component_id} if component_id is not None else None
+        r = self._request("POST", f"/v1/devices/{device_id}/media/video/download", json=payload,
+                          params=params, ok=(303,))
+        presigned = r.headers.get("Location")
+        if not presigned:
+            raise RingAPIError(r.status_code, code="NO_LOCATION", detail="303 without Location header")
+        dl = self._http.get(presigned, follow_redirects=True)
+        if dl.status_code not in (200, 206):
+            raise _error_from_response(dl)
+        ts = dl.headers.get("X-Media-Timestamp")
+        dur = dl.headers.get("X-Media-Duration")
+        return MediaClip(data=dl.content, media_timestamp_ms=int(ts) if ts and ts.isdigit() else None,
+                         media_duration_ms=int(dur) if dur and dur.isdigit() else None,
+                         partial=dl.status_code == 206)
+
+    # ---------- live view ----------
+
+    def create_whep_session(self, device_id: str, sdp_offer: str, component_id: int | None = None) -> WhepSession:
+        """POST an SDP offer, get the answer and the session URL. Battery devices
+        stream 30 s, line-powered 60 s. Starting a session forces a recording on
+        supported devices, which is what makes a later image download possible."""
+        params = {"component_id": component_id} if component_id is not None else None
+        r = self._request("POST", f"/v1/devices/{device_id}/media/streaming/whep/sessions",
+                          content=sdp_offer, headers={"Content-Type": "application/sdp"},
+                          params=params, ok=(201,))
+        return WhepSession(session_url=r.headers.get("Location", ""), sdp_answer=r.text, device_id=device_id)
+
+    def close_whep_session(self, session: WhepSession | str) -> None:
+        url = session.session_url if isinstance(session, WhepSession) else session
+        self._request("DELETE", url, ok=(200, 202, 204))
+
+    @staticmethod
+    def rtsps_url(device_id: str, access_token: str | None = None) -> str:
+        """RTSPS URL for server-side clients (ffmpeg, VLC). With a token it uses the
+        Basic-auth-in-URL form Ring documents (empty user, token as password)."""
+        auth = f":{access_token}@" if access_token else ""
+        return f"rtsps://{auth}{RTSPS_HOST}:{RTSPS_PORT}/v1/devices/{device_id}/stream"
+
+    # ---------- chimes (the only write in the API) ----------
+
+    def play_chime(self, device_id: str, audio_ref: str) -> str:
+        """Play the audio in one of the app's slots. Read `audio_ref` from
+        `configurations(device_id).chime_slots`; the request carries no slot name."""
+        body = {"data": {"type": "audio", "attributes": {"audio_ref": audio_ref}}}
+        r = self._request("POST", f"/v1/devices/{device_id}/media/audio/playback", json=body)
+        return ((r.json().get("data") or {}).get("attributes") or {}).get("status", "unknown")
+
+
+def _page_key_from_path(path: str) -> str | None:
+    from urllib.parse import parse_qs, urlparse
+    q = parse_qs(urlparse(path).query)
+    vals = q.get("page[key]") or q.get("page%5Bkey%5D")
+    return vals[0] if vals else None

ringwire-0.1.0/src/ringwire/errors.py

@@ -0,0 +1,58 @@
+"""Exceptions raised by the client. Every HTTP failure maps to one of these."""
+from __future__ import annotations
+
+
+class RingError(Exception):
+    """Base class for anything this package raises."""
+
+
+class RingAPIError(RingError):
+    """A non-2xx response from the Ring API.
+
+    `code` and `detail` come from Ring's JSON:API error body when present.
+    """
+
+    def __init__(self, status: int, code: str | None = None, detail: str | None = None,
+                 request_id: str | None = None):
+        self.status = status
+        self.code = code
+        self.detail = detail
+        self.request_id = request_id
+        super().__init__(f"HTTP {status}" + (f" {code}" if code else "") + (f": {detail}" if detail else ""))
+
+
+class Unauthorized(RingAPIError):
+    """401. The access token is missing, expired, or is a refresh token used as a Bearer."""
+
+
+class Forbidden(RingAPIError):
+    """403. The token is valid but not authorized for this device or scope."""
+
+
+class NotFound(RingAPIError):
+    """404. Device, integration, or resource does not exist for this token."""
+
+
+class MediaNotFound(RingAPIError):
+    """416 MEDIA_NOT_FOUND. No recording or snapshot exists at the requested time.
+
+    The image and clip download endpoints never trigger a capture. Start a live
+    session (which forces a recording on supported devices) or wait for a motion
+    event, then download.
+    """
+
+
+class RateLimited(RingAPIError):
+    """429. `retry_after` is seconds, from the Retry-After header when Ring sends one."""
+
+    def __init__(self, retry_after: float | None = None, **kw):
+        self.retry_after = retry_after
+        super().__init__(429, **kw)
+
+
+class SignatureError(RingError):
+    """A webhook body failed HMAC verification."""
+
+
+class NonceError(RingError):
+    """An account-linking nonce was stale or did not match any unclaimed token."""

ringwire-0.1.0/src/ringwire/nonce.py

@@ -0,0 +1,43 @@
+"""One-way (Ring-driven) account linking nonce helpers.
+
+Ring redirects the user to the partner's Account Link URL with `nonce` and `time`.
+The nonce is HMAC-SHA256(signing_key, "<time_ms>:<account_id>") encoded as URL-safe
+Base64 without padding. Same key as webhooks, different encoding: webhooks are hex.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import time
+from collections.abc import Iterable
+
+from .errors import NonceError
+
+DEFAULT_WINDOW_SECONDS = 600
+
+
+def compute_nonce(signing_key: str, time_ms: int, account_id: str) -> str:
+    mac = hmac.new(signing_key.encode("utf-8"), f"{time_ms}:{account_id}".encode("utf-8"), hashlib.sha256).digest()
+    return base64.urlsafe_b64encode(mac).rstrip(b"=").decode("ascii")
+
+
+def is_fresh(time_ms: int, now_ms: int | None = None, window_seconds: int = DEFAULT_WINDOW_SECONDS) -> bool:
+    now = now_ms if now_ms is not None else int(time.time() * 1000)
+    return (now - int(time_ms)) / 1000.0 <= window_seconds and int(time_ms) <= now + 5000
+
+
+def match_nonce(signing_key: str, nonce: str, time_ms: int, candidate_account_ids: Iterable[str],
+                now_ms: int | None = None, window_seconds: int = DEFAULT_WINDOW_SECONDS) -> str:
+    """Return the account id whose recomputed nonce matches, constant-time per candidate.
+
+    `candidate_account_ids` is the set of unclaimed tokens' account ids (from
+    `GET /v1/users/me` on each token). Raises `NonceError` if stale or unmatched.
+    """
+    if not is_fresh(time_ms, now_ms, window_seconds):
+        raise NonceError("nonce timestamp is outside the validation window")
+    for account_id in candidate_account_ids:
+        expected = compute_nonce(signing_key, time_ms, account_id)
+        if hmac.compare_digest(expected, nonce):
+            return account_id
+    raise NonceError("nonce did not match any unclaimed token")