nexobots 0.1.0__py3-none-any.whl

nexobots/__init__.py

@@ -0,0 +1,100 @@
+"""Post stats and check votes on Nexobots, the Discord bot directory."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Any, Dict, List, Optional, Union
+
+__all__ = ["Nexobots", "NexobotsError", "verify_webhook", "parse_webhook"]
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.nexobots.app/v1"
+
+
+class NexobotsError(Exception):
+    """An error response from the Nexobots API."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+
+
+class Nexobots:
+    """A client for one bot. Use it with ``async with``, or pass your own aiohttp session."""
+
+    def __init__(self, token: str, bot_id: Union[int, str], *, base_url: str = DEFAULT_BASE_URL, session: Any = None) -> None:
+        if not token:
+            raise ValueError("A Nexobots API token is required.")
+        if not bot_id:
+            raise ValueError("Your bot's client ID is required.")
+        self._token = token
+        self._bot_id = str(bot_id)
+        self._base_url = base_url.rstrip("/")
+        self._session = session
+        self._owns_session = False
+
+    async def __aenter__(self) -> "Nexobots":
+        if self._session is None:
+            import aiohttp
+
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+            self._owns_session = False
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        if self._session is None:
+            raise RuntimeError('Use "async with Nexobots(...)" or pass a session.')
+        headers = {"Authorization": self._token}
+        async with self._session.request(method, f"{self._base_url}{path}", headers=headers, **kwargs) as res:
+            try:
+                body = await res.json(content_type=None)
+            except ValueError:
+                body = {}
+            if res.status >= 400:
+                raise NexobotsError(res.status, body.get("error", "error"), body.get("message", f"Nexobots returned {res.status}"))
+            return body
+
+    async def post_stats(self, server_count: int, shard_count: Optional[int] = None) -> None:
+        """Posts your server count. The API allows one post per 5 minutes."""
+        payload: Dict[str, int] = {"server_count": server_count}
+        if shard_count is not None:
+            payload["shard_count"] = shard_count
+        await self._request("POST", f"/bots/{self._bot_id}/stats", json=payload)
+
+    async def has_voted(self, user_id: Union[int, str]) -> bool:
+        """Whether this user voted for your bot in the last 12 hours."""
+        body = await self._request("GET", f"/bots/{self._bot_id}/votes/check", params={"userId": str(user_id)})
+        return body.get("voted") == 1
+
+    async def recent_voters(self) -> List[Dict[str, Any]]:
+        """The most recent voters, up to 1,000."""
+        return await self._request("GET", f"/bots/{self._bot_id}/votes")
+
+
+def verify_webhook(secret: str, raw_body: Union[bytes, str], signature: Optional[str]) -> bool:
+    """Checks a vote webhook really came from Nexobots. Pass the raw request body and the X-Nexo-Signature header."""
+    if not signature:
+        return False
+    body = raw_body.encode() if isinstance(raw_body, str) else raw_body
+    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature)
+
+
+def parse_webhook(secret: str, raw_body: Union[bytes, str], signature: Optional[str]) -> Optional[Dict[str, Any]]:
+    """Verifies a webhook and returns the vote, or None if the signature is wrong."""
+    if not verify_webhook(secret, raw_body, signature):
+        return None
+    return json.loads(raw_body)

nexobots-0.1.0.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: nexobots
+Version: 0.1.0
+Summary: Post stats and check votes on Nexobots, the Discord bot directory.
+Project-URL: Homepage, https://nexobots.app
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: aiohttp>=3.8
+Description-Content-Type: text/markdown
+
+# nexobots
+
+Post stats and check votes on [Nexobots](https://nexobots.app), the Discord bot directory.
+
+```bash
+pip install nexobots
+```
+
+Get your API token from your bot's page in the Nexobots dashboard, and keep it in your `.env` file.
+
+## Post your server count
+
+```python
+import os
+
+from discord.ext import tasks
+from nexobots import Nexobots
+
+@tasks.loop(minutes=30)
+async def post_stats():
+    async with Nexobots(os.environ["NEXOBOTS_TOKEN"], bot.user.id) as nexobots:
+        await nexobots.post_stats(server_count=len(bot.guilds), shard_count=bot.shard_count)
+```
+
+The API allows one post per 5 minutes.
+
+## Check a vote
+
+```python
+async with Nexobots(os.environ["NEXOBOTS_TOKEN"], bot.user.id) as nexobots:
+    if await nexobots.has_voted(user.id):
+        ...  # Thank them.
+```
+
+## Receive vote webhooks
+
+Pass the raw request body, before any JSON parsing.
+
+```python
+from nexobots import parse_webhook
+
+vote = parse_webhook(os.environ["NEXOBOTS_WEBHOOK_SECRET"], raw_body, request.headers.get("X-Nexo-Signature"))
+if vote is None:
+    return Response(status=401)
+print(f"{vote['user']} voted")
+```
+
+Errors from the API are raised as `NexobotsError`, with `status`, `code` and `message`.

nexobots-0.1.0.dist-info/RECORD

@@ -0,0 +1,4 @@
+nexobots/__init__.py,sha256=qxXLOGTTfzh-K0TQW5ge8Aj1onpGV_kBYd5CgzmRaDc,4043
+nexobots-0.1.0.dist-info/METADATA,sha256=RiKTMQj4Ls-Xo9ciciBGqKFJtd06PDzZW7GGY_Me0hw,1488
+nexobots-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+nexobots-0.1.0.dist-info/RECORD,,

nexobots-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any