ringwire 0.1.0__py3-none-any.whl

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/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/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/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")

ringwire/types.py

@@ -0,0 +1,267 @@
+"""Plain dataclasses for the parts of Ring's JSON:API responses an app actually reads.
+
+The raw response is always kept on `.raw` so nothing is lost when Ring adds fields.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+EPOCH_NEVER_REPORTED = "1970-01-01T00:00:00Z"
+
+SensorKind = Literal["contact", "flood_freeze", "temperature_humidity", "air_quality"]
+
+
+@dataclass
+class TokenSet:
+    access_token: str
+    refresh_token: str
+    expires_in: int
+    scope: str | None = None
+    token_type: str = "Bearer"
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "TokenSet":
+        return cls(
+            access_token=data["access_token"],
+            refresh_token=data["refresh_token"],
+            expires_in=int(data.get("expires_in", 14400)),
+            scope=data.get("scope"),
+            token_type=data.get("token_type", "Bearer"),
+            raw=data,
+        )
+
+
+@dataclass
+class User:
+    account_id: str
+    name: str | None = None
+    email: str | None = None
+    phone: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "User":
+        d = data.get("data", data)
+        attrs = d.get("attributes", {}) or {}
+        return cls(
+            account_id=str(d.get("id")),
+            name=attrs.get("name") or attrs.get("first_name"),
+            email=attrs.get("email"),
+            phone=attrs.get("phone") or attrs.get("phone_number"),
+            raw=data,
+        )
+
+
+@dataclass
+class Device:
+    id: str
+    name: str
+    image_url: str | None = None
+    location_id: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, d: dict[str, Any]) -> "Device":
+        attrs = d.get("attributes", {}) or {}
+        rel = d.get("relationships", {}) or {}
+        loc = ((rel.get("location") or {}).get("data") or {}).get("id")
+        return cls(id=str(d["id"]), name=attrs.get("name", ""), image_url=attrs.get("image_url"),
+                   location_id=loc, raw=d)
+
+
+@dataclass
+class DeviceStatus:
+    """Attributes of `GET /v1/devices/{id}/status`, flattened.
+
+    Sensor detection attributes are booleans (`flood_faulted`, `freeze_faulted`,
+    `contact_faulted`, `tamper_detected`) and are None when the device does not
+    report them. `reported_at` is None when Ring returned the 1970 epoch, which
+    means the device has never checked in; do not compare it as a real time.
+    """
+
+    online: bool
+    reported_at: str | None
+    battery_percentage: int | None = None
+    signal_strength: str | None = None
+    flood_faulted: bool | None = None
+    freeze_faulted: bool | None = None
+    contact_faulted: bool | None = None
+    tamper_detected: bool | None = None
+    temperature: float | None = None
+    humidity: float | None = None
+    snooze_active: bool | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "DeviceStatus":
+        d = data.get("data", data)
+        a = d.get("attributes", {}) or {}
+
+        def faulted(key: str, sub: str = "faulted") -> bool | None:
+            v = a.get(key)
+            if not isinstance(v, dict) or sub not in v:
+                return None
+            return bool(v[sub])
+
+        reported = a.get("reported_at")
+        if reported == EPOCH_NEVER_REPORTED:
+            reported = None
+        batt = (a.get("battery_status") or {}).get("percentage") if isinstance(a.get("battery_status"), dict) else None
+        sig = (a.get("signal_strength") or {}).get("value") if isinstance(a.get("signal_strength"), dict) else None
+        snooze = ((a.get("audio") or {}).get("snooze") or {}).get("active") if isinstance(a.get("audio"), dict) else None
+        return cls(
+            online=bool(a.get("online", False)),
+            reported_at=reported,
+            battery_percentage=batt,
+            signal_strength=sig,
+            flood_faulted=faulted("flood_detection"),
+            freeze_faulted=faulted("freeze_detection"),
+            contact_faulted=faulted("contact_detection"),
+            tamper_detected=faulted("tamper_detection", "detected"),
+            temperature=a.get("temperature"),
+            humidity=a.get("humidity"),
+            snooze_active=snooze,
+            raw=data,
+        )
+
+    @property
+    def has_reported(self) -> bool:
+        return self.reported_at is not None
+
+
+@dataclass
+class DeviceCapabilities:
+    video_codecs: list[str] | None
+    chime_play: bool
+    audio_slots: int | None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "DeviceCapabilities":
+        d = data.get("data", data)
+        a = d.get("attributes", {}) or {}
+        video = a.get("video") or {}
+        audio = a.get("audio") or {}
+        actions = audio.get("supported_actions") or []
+        return cls(
+            video_codecs=video.get("codecs"),
+            chime_play="chime.play" in actions,
+            audio_slots=audio.get("customizable_slots") if isinstance(audio.get("customizable_slots"), int) else None,
+            raw=data,
+        )
+
+    @property
+    def has_camera(self) -> bool:
+        return bool(self.video_codecs)
+
+    @property
+    def hevc_only(self) -> bool:
+        return self.video_codecs == ["HEVC"]
+
+
+@dataclass
+class ChimeSlot:
+    event: str
+    audio_ref: str
+    audio_name: str | None
+    audio_url: str | None
+    disabled: bool
+
+
+@dataclass
+class DeviceConfigurations:
+    motion_detection_enabled: bool | None
+    chime_slots: list[ChimeSlot]
+    chime_volume: int | None
+    temperature_threshold: dict[str, float] | None
+    humidity_threshold: dict[str, float] | None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "DeviceConfigurations":
+        d = data.get("data", data)
+        a = d.get("attributes", {}) or {}
+        audio = a.get("audio") or {}
+        slots_raw = audio.get("customizable_slots")
+        slots: list[ChimeSlot] = []
+        if isinstance(slots_raw, list):
+            for s in slots_raw:
+                slots.append(ChimeSlot(
+                    event=s.get("event", ""), audio_ref=s.get("audio_ref", ""),
+                    audio_name=s.get("audio_name"), audio_url=s.get("audio_url"),
+                    disabled=bool(s.get("disabled", False)),
+                ))
+            # Ring does not return slots in event order.
+            slots.sort(key=lambda s: s.event)
+        md = a.get("motion_detection") or {}
+        return cls(
+            motion_detection_enabled=md.get("enabled") if isinstance(md, dict) else None,
+            chime_slots=slots,
+            chime_volume=audio.get("volume") if isinstance(audio, dict) else None,
+            temperature_threshold=a.get("temperature_threshold"),
+            humidity_threshold=a.get("humidity_threshold"),
+            raw=data,
+        )
+
+
+@dataclass
+class HistoryEvent:
+    id: str
+    event_type: str
+    start_ms: int
+    end_ms: int
+    device_id: str | None
+    third_party_reviewed: bool
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, d: dict[str, Any]) -> "HistoryEvent":
+        a = d.get("attributes", {}) or {}
+        src = (((d.get("relationships") or {}).get("source") or {}).get("data") or {}).get("id")
+        return cls(id=str(d["id"]), event_type=a.get("event_type", ""), start_ms=int(a.get("start", 0)),
+                   end_ms=int(a.get("end", 0)), device_id=src,
+                   third_party_reviewed=bool(a.get("is_third_party_reviewed", False)), raw=d)
+
+
+@dataclass
+class HistoryPage:
+    events: list[HistoryEvent]
+    next_path: str | None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class MediaImage:
+    data: bytes
+    content_type: str
+    media_timestamp_ms: int | None
+    media_origin: str | None  # "recording" or "snapshot"
+    requested_timestamp_ms: int | None = None
+
+    @property
+    def drift_ms(self) -> int | None:
+        """How far the frame Ring returned is from the timestamp asked for."""
+        if self.media_timestamp_ms is None or self.requested_timestamp_ms is None:
+            return None
+        return self.media_timestamp_ms - self.requested_timestamp_ms
+
+
+@dataclass
+class MediaClip:
+    data: bytes
+    media_timestamp_ms: int | None
+    media_duration_ms: int | None
+    partial: bool
+
+
+@dataclass
+class WhepSession:
+    session_url: str
+    sdp_answer: str
+    device_id: str
+
+    @property
+    def session_id(self) -> str:
+        return self.session_url.rstrip("/").rsplit("/", 1)[-1]

ringwire/webhooks.py

@@ -0,0 +1,162 @@
+"""Webhook verification and parsing.
+
+Ring signs every webhook with HMAC-SHA256 over the raw body bytes using the
+partner's HMAC signing key, hex encoded, sent as `X-Signature: sha256=<hex>`.
+Verify against the raw bytes exactly as received; re-serialising the JSON
+changes whitespace and breaks the signature.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import SignatureError
+
+SIGNATURE_HEADER = "X-Signature"
+
+CAMERA_EVENTS = frozenset({"motion_detected", "button_press"})
+DEVICE_EVENTS = frozenset({"device_added", "device_removed", "device_online", "device_offline"})
+ACCOUNT_EVENTS = frozenset({
+    "app_integration_added", "app_integration_removed",
+    "subscription_activated", "subscription_deactivated",
+})
+SENSOR_STATE_EVENTS = frozenset({
+    "contact_sensor_faulted", "contact_sensor_cleared",
+    "tamper_detected", "tamper_cleared",
+    "flood_detected", "flood_cleared",
+    "freeze_detected", "freeze_cleared",
+})
+SENSOR_THRESHOLD_EVENTS = frozenset({
+    "temperature_exceeded", "temperature_cleared",
+    "humidity_exceeded", "humidity_cleared",
+    "pm25_exceeded", "pm25_cleared",
+    "co_exceeded", "co_cleared",
+})
+SENSOR_EVENTS = SENSOR_STATE_EVENTS | SENSOR_THRESHOLD_EVENTS
+ALL_EVENTS = CAMERA_EVENTS | DEVICE_EVENTS | ACCOUNT_EVENTS | SENSOR_EVENTS
+
+
+def sign(raw_body: bytes, signing_key: str) -> str:
+    """Produce the `X-Signature` value Ring would send for this body. Used by tests
+    and by anyone replaying captured webhooks into a local server."""
+    digest = hmac.new(signing_key.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
+    return f"sha256={digest}"
+
+
+def verify_signature(raw_body: bytes, received: str | None, signing_key: str) -> bool:
+    """Constant-time check of `X-Signature` against the raw body."""
+    if not received:
+        return False
+    expected = sign(raw_body, signing_key)
+    return hmac.compare_digest(expected, received.strip())
+
+
+@dataclass
+class WebhookEvent:
+    """One webhook, flattened. `raw` keeps the full envelope."""
+
+    type: str
+    request_id: str
+    account_id: str | None
+    sent_at: str | None
+    event_id: str | None
+    device_id: str | None
+    timestamp_ms: int | None
+    sub_type: str | None = None
+    reading: float | None = None          # temperature / humidity / pm25 / co on threshold events
+    threshold_type: str | None = None     # "min" or "max" on *_exceeded events
+    version: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_sensor(self) -> bool:
+        return self.type in SENSOR_EVENTS
+
+    @property
+    def is_known(self) -> bool:
+        return self.type in ALL_EVENTS
+
+    @property
+    def device_path(self) -> str | None:
+        rel = ((self.raw.get("data") or {}).get("relationships") or {}).get("devices") or {}
+        return (rel.get("links") or {}).get("self")
+
+
+def parse_event(raw_body: bytes | str | dict[str, Any]) -> WebhookEvent:
+    """Turn a v1.1 webhook envelope into a `WebhookEvent`.
+
+    Reads the device from `data.attributes.source`, never by parsing `data.id`;
+    Ring documents the id's structure as not a contract.
+    """
+    if isinstance(raw_body, (bytes, bytearray)):
+        payload = json.loads(raw_body.decode("utf-8"))
+    elif isinstance(raw_body, str):
+        payload = json.loads(raw_body)
+    else:
+        payload = raw_body
+    meta = payload.get("meta") or {}
+    data = payload.get("data") or {}
+    attrs = data.get("attributes") or {}
+    reading = None
+    for key in ("temperature", "humidity", "pm25", "co"):
+        if key in attrs and isinstance(attrs[key], (int, float)):
+            reading = float(attrs[key])
+            break
+    ts = attrs.get("timestamp")
+    return WebhookEvent(
+        type=str(data.get("type", "")),
+        request_id=str(meta.get("request_id", "")),
+        account_id=meta.get("account_id"),
+        sent_at=meta.get("time"),
+        event_id=data.get("id"),
+        device_id=attrs.get("source"),
+        timestamp_ms=int(ts) if isinstance(ts, (int, float)) else None,
+        sub_type=data.get("subType") or attrs.get("sub_type"),
+        reading=reading,
+        threshold_type=attrs.get("threshold_type"),
+        version=meta.get("version"),
+        raw=payload,
+    )
+
+
+def verify_and_parse(raw_body: bytes, received_signature: str | None, signing_key: str) -> WebhookEvent:
+    """The one call a webhook handler needs. Raises `SignatureError` on a bad signature."""
+    if not verify_signature(raw_body, received_signature, signing_key):
+        raise SignatureError("X-Signature did not match the raw body")
+    return parse_event(raw_body)
+
+
+def make_event(event_type: str, device_id: str, *, account_id: str = "acct_test",
+               timestamp_ms: int | None = None, request_id: str | None = None,
+               extra_attributes: dict[str, Any] | None = None,
+               sub_type: str | None = None) -> dict[str, Any]:
+    """Build a webhook envelope in Ring's v1.1 shape. For tests, the sandbox
+    replay tool, and local development without a public webhook URL."""
+    import time
+    import uuid
+
+    ts = timestamp_ms if timestamp_ms is not None else int(time.time() * 1000)
+    rid = request_id or uuid.uuid4().hex
+    attrs: dict[str, Any] = {"source": device_id, "source_type": "devices", "timestamp": ts}
+    if extra_attributes:
+        attrs.update(extra_attributes)
+    data: dict[str, Any] = {
+        "id": f"{device_id}_{event_type}_{ts}",
+        "type": event_type,
+        "attributes": attrs,
+        "relationships": {"devices": {"links": {"self": f"/v1/devices/{device_id}"}}},
+    }
+    if sub_type:
+        data["subType"] = sub_type
+    return {
+        "meta": {
+            "version": "1.1",
+            "time": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(ts / 1000)),
+            "request_id": rid,
+            "account_id": account_id,
+        },
+        "data": data,
+    }

ringwire-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+ringwire/__init__.py,sha256=w00cHRMhVIQYX-8rflEqx4yzO1NwlwoCFxAhlnQWxRI,1685
+ringwire/client.py,sha256=GXhtDMg3_mOaLXEkoaISPLxDi6MpENUpMG4Mc6v-Ljg,16851
+ringwire/errors.py,sha256=_wNrlyU_XmLNwO9RDqR1_oi-82wy8eiWRb_cQRKorK0,1863
+ringwire/nonce.py,sha256=zenJnplB7JXStS8v2nHv69EqZKm4Vy1dZ9mA-V3FML4,1874
+ringwire/types.py,sha256=5WT8bsYWsg0IfiuuGqpC677LKClwPNjfDsFfEOeit8o,8744
+ringwire/webhooks.py,sha256=_GeCV3my4PWC_f6rlkTYhkWYVdC6KikWpzrOUv39yKs,5994
+ringwire-0.1.0.dist-info/licenses/LICENSE,sha256=jchmxv6LImPyoRSz6vD2Gp4kA2bZtayrd8vegR6W8J0,1072
+ringwire-0.1.0.dist-info/METADATA,sha256=4ZYvbZ1xAnsptS5Sa3O4_SM2X6YRq5L-XN3yL1ZyHFA,3497
+ringwire-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+ringwire-0.1.0.dist-info/top_level.txt,sha256=ij8lqlBNLOgSgPlv03n658l7izFLXua5hfrxA7DmTLI,9
+ringwire-0.1.0.dist-info/RECORD,,

ringwire-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ringwire-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+ringwire