Updated Owncast clients to v0.2.5 and added spec-coverage and integration tests to enforce parity with the OpenAPI spec.

owlbot/api/owncast_client.py

@@ -21,7 +21,7 @@ from typing import TYPE_CHECKING, Any
 
 from markupsafe import escape as _escape_html
 
-from owlbot.owncast_http import get_json, post_with_envelope
+from owlbot.owncast_http import get_json, request_with_envelope
 
 if TYPE_CHECKING:
     import aiohttp
@@ -59,35 +59,6 @@ class OwncastClient:
         """The Owncast server base URL (e.g., "https://stream.logal.dev")."""
         return self._base_url
 
-    async def get_status(self) -> dict[str, Any]:
-        """Get the public server status.
-
-        This is a public endpoint that does not require authentication.
-        Returns server info including version, online status, and viewer count.
-
-        :return: Status dict with ``versionNumber``, ``online``, ``viewerCount``, etc.
-        """
-        self._logger.debug("Fetching server status.")
-        return dict(await self._get("/api/status"))
-
-    async def send_message(self, body: str, *, unsanitized: bool = False) -> str:
-        """Send a chat message visible to all viewers.
-
-        The message body is HTML-escaped by default to prevent injection
-        when echoing user-originated content. Markdown syntax is unaffected
-        by escaping and will be rendered normally by Owncast.
-
-        :param body: The message text (supports markdown).
-        :param unsanitized: If ``True``, skip HTML escaping and send the body
-            as-is. Only use this when the content is fully controlled by the
-            module and intentionally contains HTML.
-        :return: Success message from the server.
-        """
-        if not unsanitized:
-            body = str(_escape_html(body))
-        self._logger.info("Sending chat message: %s", body)
-        return await self._post("/api/integrations/chat/send", {"body": body})
-
     async def send_system_message(self, body: str, *, unsanitized: bool = False) -> str:
         """Send a system message visible to all viewers.
 
@@ -106,24 +77,6 @@ class OwncastClient:
         self._logger.info("Sending system message: %s", body)
         return await self._post("/api/integrations/chat/system", {"body": body})
 
-    async def send_action(self, body: str, *, unsanitized: bool = False) -> str:
-        """Send an action message (like IRC /me).
-
-        Action messages display as "*BotName does something*" and are used
-        for describing actions rather than speech.
-
-        The message body is HTML-escaped by default. Pass
-        ``unsanitized=True`` to send raw HTML intentionally.
-
-        :param body: The action text (displayed after the bot name).
-        :param unsanitized: If ``True``, skip HTML escaping.
-        :return: Success message from the server.
-        """
-        if not unsanitized:
-            body = str(_escape_html(body))
-        self._logger.info("Sending action: %s", body)
-        return await self._post("/api/integrations/chat/action", {"body": body})
-
     async def send_system_message_to_client(
         self, client_id: int, body: str, *, unsanitized: bool = False
     ) -> str:
@@ -147,6 +100,55 @@ class OwncastClient:
             f"/api/integrations/chat/system/client/{client_id}", {"body": body}
         )
 
+    async def send_user_message(self) -> str:
+        """Send a chat message on behalf of a user (deprecated by Owncast).
+
+        Owncast no longer supports this endpoint as of v0.2.5: it always returns
+        HTTP 400 with a message directing callers to :meth:`send_message`. The
+        wrapper is provided for spec parity. Use :meth:`send_message` instead.
+
+        :return: Success message from the server (never returned in practice).
+        :raises OwncastError: Always, with status 400.
+        """
+        self._logger.info("Calling deprecated /integrations/chat/user endpoint.")
+        return await self._post("/api/integrations/chat/user")
+
+    async def send_message(self, body: str, *, unsanitized: bool = False) -> str:
+        """Send a chat message visible to all viewers.
+
+        The message body is HTML-escaped by default to prevent injection
+        when echoing user-originated content. Markdown syntax is unaffected
+        by escaping and will be rendered normally by Owncast.
+
+        :param body: The message text (supports markdown).
+        :param unsanitized: If ``True``, skip HTML escaping and send the body
+            as-is. Only use this when the content is fully controlled by the
+            module and intentionally contains HTML.
+        :return: Success message from the server.
+        """
+        if not unsanitized:
+            body = str(_escape_html(body))
+        self._logger.info("Sending chat message: %s", body)
+        return await self._post("/api/integrations/chat/send", {"body": body})
+
+    async def send_action(self, body: str, *, unsanitized: bool = False) -> str:
+        """Send an action message (like IRC /me).
+
+        Action messages display as "*BotName does something*" and are used
+        for describing actions rather than speech.
+
+        The message body is HTML-escaped by default. Pass
+        ``unsanitized=True`` to send raw HTML intentionally.
+
+        :param body: The action text (displayed after the bot name).
+        :param unsanitized: If ``True``, skip HTML escaping.
+        :return: Success message from the server.
+        """
+        if not unsanitized:
+            body = str(_escape_html(body))
+        self._logger.info("Sending action: %s", body)
+        return await self._post("/api/integrations/chat/action", {"body": body})
+
     async def set_message_visibility(
         self, message_ids: list[str], *, visible: bool
     ) -> str:
@@ -167,6 +169,26 @@ class OwncastClient:
             {"idArray": message_ids, "visible": visible},
         )
 
+    async def get_status(self) -> dict[str, Any]:
+        """Get the public server status.
+
+        This is a public endpoint that does not require authentication.
+        Returns server info including version, online status, and viewer count.
+
+        :return: Status dict with ``versionNumber``, ``online``, ``viewerCount``, etc.
+        """
+        self._logger.debug("Fetching server status.")
+        return dict(await self._get("/api/status"))
+
+    async def set_stream_title(self, title: str) -> str:
+        """Update the stream title.
+
+        :param title: The new stream title.
+        :return: Success message from the server.
+        """
+        self._logger.info("Setting stream title: %s", title)
+        return await self._post("/api/integrations/streamtitle", {"value": title})
+
     async def get_chat_history(self) -> list[dict[str, Any]]:
         """Fetch recent chat messages.
 
@@ -183,21 +205,23 @@ class OwncastClient:
         self._logger.debug("Fetching connected clients.")
         return list(await self._get("/api/integrations/clients"))
 
-    async def set_stream_title(self, title: str) -> str:
-        """Update the stream title.
+    async def get_user_details(self, user_id: str) -> dict[str, Any]:
+        """Get details for a chat user.
 
-        :param title: The new stream title.
-        :return: Success message from the server.
+        :param user_id: The user ID to look up.
+        :return: Dict with ``user``, ``connectedClients``, and ``messages`` fields.
         """
-        self._logger.info("Setting stream title: %s", title)
-        return await self._post("/api/integrations/streamtitle", {"value": title})
+        self._logger.debug("Fetching user details for %s.", user_id)
+        return dict(
+            await self._get(f"/api/integrations/moderation/chat/user/{user_id}")
+        )
 
     async def _post(self, endpoint: str, data: dict[str, Any] | None = None) -> str:
         """Send a POST request to the Owncast API.
 
         :raises OwncastError: If the request fails.
         """
-        return await post_with_envelope(
+        return await request_with_envelope(
             self._http,
             self._base_url,
             endpoint,