Add support for retrieving media from outdoor cameras (#708)

* Add Outdoor Camera media url support.

The WebsocketEvent now includes image, mp4 and hls media file urls extracted from outdoor camera motion events.
An api is added to fetch media urls, using the access token and retry logic already in place for api access.

* added tests for media urls and changes for pre-commit

* Remove an unused method

* Refactor api code to make it more reusable

* Refactor retry codes specification, and more strongly type request_func Callable

* Clean up some code and re-lint.

* Fix spelling in a comment

* Refactor is_fatal_error and how it is called

* Small cleanup

* Cleanup

* Fix websocket test after changing some attributes to snake_case

* Remove unreachable code and provide tests for coverage.

* Remove unreachable code and provide tests for coverage.

* Small docs cleanup

* Small docs update

* Include media fetch methods in disable/enable_request_retries()

* Update docs/websocket.md

* Update docs/websocket.md

* Update docs/websocket.md

---------

Co-authored-by: Aaron Bach <bachya1208@gmail.com>

Author: peebles

docs/websocket.md

@@ -105,6 +105,7 @@ The `event` argument provided to event callbacks is a
 - `sensor_type`: the type of the entity that triggered the event
 - `system_id`: the SimpliSafe™ system ID
 - `timestamp`: the UTC timestamp that the event occurred
+- `media_urls`: a dict containing media URLs if the `event_type` is "camera_motion_detected" (see below)
 
 The `event_type` property will be one of the following values:
 
@@ -137,6 +138,26 @@ The `event_type` property will be one of the following values:
 - `sensor_restored`
 - `user_initiated_test`
 
+If the `event_type` is `camera_motion_detected`, then the `event` attribute `media_urls`
+will be a dictionary that looks like this:
+
+```python
+{
+    "image_url": "https://xxx.us-east-1.prd.cam.simplisafe.com/xxx",
+    "clip_url": "https://xxx.us-east-1.prd.cam.simplisafe.com/xxx",
+}
+```
+
+The `image_url` is an absolute URL to a JPEG file. The `clip_url` is an absolute URL to
+a short MPEG4 video clip. Both refer to the motion detected by the camera. You can
+retrieve the raw bytes of the media files at these URLs with the following method:
+
+```python
+bytes = await api.async_media(url)
+```
+
+If the `event_type` is not `camera_motion_detected`, then `media_urls` will be set to None.
+
 If you should come across an event type that the library does not know about (and see
 a log message about it), please open an issue at
 <https://github.com/bachya/simplisafe-python/issues>.

simplipy/api.py

@@ -35,6 +35,7 @@
 API_URL_BASE = f"https://{API_URL_HOSTNAME}/v1"
 
 DEFAULT_REQUEST_RETRIES = 4
+DEFAULT_MEDIA_RETRIES = 4
 DEFAULT_TIMEOUT = 10
 DEFAULT_TOKEN_EXPIRATION_WINDOW = 5
 
@@ -49,12 +50,15 @@ class API:  # pylint: disable=too-many-instance-attributes
     Args:
         session: session: An optional ``aiohttp`` ``ClientSession``.
         request_retries: The default number of request retries to use.
+        media_retries: The default number of request retries to use to
+            fetch media files.
     """
 
     def __init__(
         self,
         *,
         request_retries: int = DEFAULT_REQUEST_RETRIES,
+        media_retries: int = DEFAULT_MEDIA_RETRIES,
         session: ClientSession,
     ) -> None:
         """Initialize.
@@ -67,6 +71,7 @@ def __init__(
             Callable[[str], Awaitable[None] | None]
         ] = []
         self._request_retries = request_retries
+        self._media_retries = media_retries
         self.session: ClientSession = session
 
         # These will get filled in after initial authentication:
@@ -78,7 +83,16 @@ def __init__(
         self.user_id: int | None = None
         self.websocket: WebsocketClient | None = None
 
-        self.async_request = self._wrap_request_method(self._request_retries)
+        self.async_request = self._wrap_request_method(
+            request_retries=self._request_retries,
+            retry_codes=[401, 409],
+            request_func=self._async_api_request,
+        )
+        self._async_media_data = self._wrap_request_method(
+            request_retries=self._media_retries,
+            retry_codes=[401, 404, 409],
+            request_func=self._async_media_request,
+        )
 
     @classmethod
     async def async_from_auth(
@@ -237,6 +251,38 @@ async def _async_api_request(
 
         return data
 
+    async def async_media(self, url: str) -> bytes | None:
+        """Fetch a media file and return raw bytes to caller.
+
+        Args:
+            url: An absolute url for the media file.
+
+        Returns:
+            The raw bytes of the media file.
+        """
+        data = await self._async_media_data(url)
+        return cast(bytes, data["bytes"])
+
+    async def _async_media_request(self, url: str) -> dict[str, Any]:
+        """Fetch a media file.
+
+        Args:
+            url: An absolute url for the media file.
+
+        Returns:
+            A dict that looks like { "bytes": <raw-bytes> }.
+        """
+        async with self.session.request(
+            "get",
+            url,
+            headers={
+                "User-Agent": DEFAULT_USER_AGENT,
+                "Authorization": f"Bearer {self.access_token}",
+            },
+        ) as resp:
+            resp.raise_for_status()
+            return {"bytes": await resp.read()}
+
     @staticmethod
     def _handle_on_giveup(_: dict[str, Any]) -> None:
         """Handle a give up after retries are exhausted.
@@ -260,60 +306,100 @@ def _save_token_data_from_response(self, token_data: dict[str, Any]) -> None:
             self.refresh_token = refresh_token
 
     @staticmethod
-    def is_fatal_error(err: ClientResponseError) -> bool:
+    def is_fatal_error(
+        retriable_error_codes: list[int],
+    ) -> Callable[[ClientResponseError], bool]:
         """Determine whether a ClientResponseError is fatal and shouldn't be retried.
 
-        In general, we retry anything outside of HTTP 4xx codes (client errors) with a
-        few exceptions:
+        When sending general API requests:
 
         1. 401: We catch this, refresh the access token, and retry the original request.
         2. 409: SimpliSafe base stations regular synchronize themselves with the API,
                 which is where this error can occur; we can't control when/how that
                 happens (e.g., we might query the API in the middle of a base station
                 update), so it should be viewed as retryable.
 
+        But when fetching media files:
+
+        3. 404: When fetching media files, you may get a 404 if the media file is not
+                yet available to read. Keep trying however, and it will eventually
+                return a 200.
+
         Args:
-            err: An ``aiohttp`` ``ClientResponseError``
+            retriable_error_codes: A list of retriable error status codes.
 
         Returns:
-            Whether the error is a fatal one.
+            A callable function used by backoff to check for errors.
         """
-        if err.status in (401, 409):
-            return False
-        return 400 <= err.status < 500
+
+        def check(err: ClientResponseError) -> bool:
+            """Perform the check.
+
+            Args:
+                err: An ``aiohttp`` ``ClientResponseError``
+
+            Returns:
+                Whether the error is a fatal one.
+            """
+            if err.status in retriable_error_codes:
+                return False
+            return 400 <= err.status < 500
+
+        return check
 
     def _wrap_request_method(
-        self, request_retries: int
+        self,
+        request_retries: int,
+        retry_codes: list[int],
+        request_func: Callable[..., Awaitable[dict[str, Any]]],
     ) -> Callable[..., Awaitable[dict[str, Any]]]:
-        """Wrap the request method in backoff/retry logic.
+        """Wrap a request method in backoff/retry logic.
 
         Args:
             request_retries: The number of retries to give a failed request.
+            retry_codes: A list of HTTP status codes that cause the retry
+                loop to continue.
+            request_func: A function that performs the request.
 
         Returns:
             A version of the request callable that can do retries.
         """
-        return cast(
-            Callable,
-            backoff.on_exception(
-                backoff.expo,
-                ClientResponseError,
-                giveup=self.is_fatal_error,  # type: ignore[arg-type]
-                jitter=backoff.random_jitter,
-                logger=LOGGER,
-                max_tries=request_retries,
-                on_backoff=self._async_handle_on_backoff,  # type: ignore[arg-type]
-                on_giveup=self._handle_on_giveup,  # type: ignore[arg-type]
-            )(self._async_api_request),
-        )
+        return backoff.on_exception(
+            backoff.expo,
+            ClientResponseError,
+            giveup=self.is_fatal_error(retry_codes),  # type: ignore[arg-type]
+            jitter=backoff.random_jitter,
+            logger=LOGGER,
+            max_tries=request_retries,
+            on_backoff=self._async_handle_on_backoff,  # type: ignore[arg-type]
+            on_giveup=self._handle_on_giveup,  # type: ignore[arg-type]
+        )(request_func)
 
     def disable_request_retries(self) -> None:
         """Disable the request retry mechanism."""
-        self.async_request = self._wrap_request_method(1)
+        self.async_request = self._wrap_request_method(
+            request_retries=1,
+            retry_codes=[401, 409],
+            request_func=self._async_api_request,
+        )
+        self._async_media_data = self._wrap_request_method(
+            request_retries=1,
+            retry_codes=[401, 404, 409],
+            request_func=self._async_media_request,
+        )
 
     def enable_request_retries(self) -> None:
         """Enable the request retry mechanism."""
-        self.async_request = self._wrap_request_method(self._request_retries)
+        self.async_request = self._wrap_request_method(
+            request_retries=self._request_retries,
+            retry_codes=[401, 409],
+            request_func=self._async_api_request,
+        )
+        self._async_media_data = self._wrap_request_method(
+            request_retries=self._media_retries,
+            retry_codes=[401, 404, 409],
+            request_func=self._async_media_request,
+        )
 
     def add_refresh_token_callback(
         self, callback: Callable[[str], Awaitable[None] | None]

simplipy/websocket.py

@@ -150,9 +150,12 @@ class WebsocketEvent:
     info: str
     system_id: int
     _raw_timestamp: float
+    _video: dict | None
+    _vid: str | None
 
     event_type: str | None = field(init=False)
     timestamp: datetime = field(init=False)
+    media_urls: dict[str, str] | None = field(init=False)
 
     changed_by: str | None = None
     sensor_name: str | None = None
@@ -190,6 +193,25 @@ def __post_init__(self, event_cid: int) -> None:
                 )
                 object.__setattr__(self, "sensor_type", None)
 
+        if self._vid is not None and self._video is not None:
+            object.__setattr__(
+                self,
+                "media_urls",
+                {
+                    "image_url": self._video[self._vid]["_links"]["snapshot/jpg"][
+                        "href"
+                    ],
+                    "clip_url": self._video[self._vid]["_links"]["download/mp4"][
+                        "href"
+                    ],
+                    "hls_url": self._video[self._vid]["_links"]["playback/hls"]["href"],
+                },
+            )
+            object.__setattr__(self, "_vid", None)
+            object.__setattr__(self, "_video", None)
+        else:
+            object.__setattr__(self, "media_urls", None)
+
 
 def websocket_event_from_payload(payload: dict[str, Any]) -> WebsocketEvent:
     """Create a Message object from a websocket event payload.
@@ -205,6 +227,8 @@ def websocket_event_from_payload(payload: dict[str, Any]) -> WebsocketEvent:
         payload["data"]["info"],
         payload["data"]["sid"],
         payload["data"]["eventTimestamp"],
+        payload["data"].get("video"),
+        payload["data"].get("videoStartedBy"),
         changed_by=payload["data"]["pinName"],
         sensor_name=payload["data"]["sensorName"],
         sensor_serial=payload["data"]["sensorSerial"],

tests/conftest.py

@@ -388,6 +388,37 @@ def ws_message_event_data_fixture() -> dict[str, Any]:
     return cast(dict[str, Any], json.loads(load_fixture("ws_message_event_data.json")))
 
 
+@pytest.fixture(name="ws_motion_event")
+def ws_motion_event_fixture(ws_motion_event_data: dict[str, Any]) -> dict[str, Any]:
+    """Define a fixture to represent an event response.
+
+    Args:
+        ws_motion_event_data: A mocked websocket response payload.
+
+    Returns:
+        A websocket response payload.
+    """
+    return {
+        "data": ws_motion_event_data,
+        "datacontenttype": "application/json",
+        "id": "id:16803409109",
+        "source": "messagequeue",
+        "specversion": "1.0",
+        "time": "2021-09-29T23:14:46.000Z",
+        "type": "com.simplisafe.event.standard",
+    }
+
+
+@pytest.fixture(name="ws_motion_event_data", scope="session")
+def ws_motion_event_data_fixture() -> dict[str, Any]:
+    """Define a fixture that returns the data payload from a data event.
+
+    Returns:
+        A API response payload.
+    """
+    return cast(dict[str, Any], json.loads(load_fixture("ws_motion_event_data.json")))
+
+
 @pytest.fixture(name="ws_message_hello")
 def ws_message_hello_fixture(ws_message_hello_data: dict[str, Any]) -> dict[str, Any]:
     """Define a fixture to represent the "hello" response.