add ws token api

src/client.py

@@ -437,3 +437,54 @@ class Client:
             sw.stop(force)
             del self.sessions_watcher[id_]
             logging.info(f"session events (id: {id_}) watcher stopped")
+
+    @refresh()
+    def get_wstokens(self) -> list[dict[str, Any]] | WhereIsException:
+        wstoken_url = urljoin(self.base_url, "/auth/ws-token/")
+        logging.info(f"get ws token: {wstoken_url}")
+
+        res = self.session.get(wstoken_url)
+
+        if res.status_code == 401:
+            raise UnauthorizedException()
+
+        if res.status_code >= 400:
+            raise WhereIsException(wstoken_url, res)
+
+        return res.json()
+
+    @refresh()
+    def create_wstoken(self) -> dict[str, Any] | WhereIsException:
+        """
+        Create a websocket JWT to authenticate your real time connection.
+
+        NOTE: only one, and only one ws token per user is allowed.
+        If it expired, delete it and create a new one.
+        """
+        wstoken_url = urljoin(self.base_url, "/auth/ws-token/")
+        logging.info(f"create ws token: {wstoken_url}")
+
+        res = self.session.post(wstoken_url)
+
+        if res.status_code == 401:
+            raise UnauthorizedException()
+
+        if res.status_code >= 400:
+            raise WhereIsException(wstoken_url, res)
+
+        return res.json()
+
+    @refresh()
+    def delete_wstoken(self, id_: UUID) -> None | WhereIsException:
+        wstoken_url = urljoin(self.base_url, f"/auth/ws-token/{id_}/")
+        logging.info(f"delete ws token: {wstoken_url}")
+
+        res = self.session.delete(wstoken_url)
+
+        if res.status_code == 401:
+            raise UnauthorizedException()
+
+        if res.status_code >= 400:
+            raise WhereIsException(wstoken_url, res)
+
+        return None

src/exceptions.py

@@ -1,5 +1,7 @@
 from requests import Response
 
+__all__ = ["WhereIsException"]
+
 
 class WhereIsException(Exception):
     """Handle all WhereIs API errors."""