nexobots 0.1.0__tar.gz

nexobots-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+node_modules
+dist
+.next
+.turbo
+coverage
+*.log
+*.tsbuildinfo
+next-env.d.ts
+.env
+.env.local
+.DS_Store
+__pycache__/
+*.pyc

nexobots-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,48 @@
+# 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/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/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nexobots"
+version = "0.1.0"
+description = "Post stats and check votes on Nexobots, the Discord bot directory."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = ["aiohttp>=3.8"]
+
+[project.urls]
+Homepage = "https://nexobots.app"

nexobots-0.1.0/tests/test_nexobots.py

@@ -0,0 +1,91 @@
+import asyncio
+import hashlib
+import hmac
+import json
+import unittest
+
+from nexobots import Nexobots, NexobotsError, parse_webhook, verify_webhook
+
+
+class FakeResponse:
+    def __init__(self, status, body):
+        self.status = status
+        self._body = body
+
+    async def json(self, content_type=None):
+        return self._body
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        return None
+
+
+class FakeSession:
+    def __init__(self, status=200, body=None):
+        self.status = status
+        self.body = body if body is not None else {}
+        self.calls = []
+
+    def request(self, method, url, **kwargs):
+        self.calls.append((method, url, kwargs))
+        return FakeResponse(self.status, self.body)
+
+
+def run(coroutine):
+    return asyncio.run(coroutine)
+
+
+class ClientTests(unittest.TestCase):
+    def client(self, session):
+        return Nexobots("nexo_token", 400000000000000001, base_url="https://api.test/v1/", session=session)
+
+    def test_posts_stats_in_the_apis_format(self):
+        session = FakeSession(body={"ok": True})
+        run(self.client(session).post_stats(12, shard_count=2))
+        method, url, kwargs = session.calls[0]
+        self.assertEqual(method, "POST")
+        self.assertEqual(url, "https://api.test/v1/bots/400000000000000001/stats")
+        self.assertEqual(kwargs["json"], {"server_count": 12, "shard_count": 2})
+        self.assertEqual(kwargs["headers"]["Authorization"], "nexo_token")
+
+    def test_turns_the_vote_check_into_a_bool(self):
+        self.assertTrue(run(self.client(FakeSession(body={"voted": 1})).has_voted(1)))
+        self.assertFalse(run(self.client(FakeSession(body={"voted": 0})).has_voted(1)))
+
+    def test_raises_a_readable_error(self):
+        session = FakeSession(status=429, body={"error": "rate_limited", "message": "Too many requests."})
+        with self.assertRaises(NexobotsError) as caught:
+            run(self.client(session).post_stats(1))
+        self.assertEqual(caught.exception.status, 429)
+        self.assertEqual(caught.exception.code, "rate_limited")
+
+    def test_needs_a_token_and_bot_id(self):
+        with self.assertRaises(ValueError):
+            Nexobots("", 1)
+        with self.assertRaises(ValueError):
+            Nexobots("x", "")
+
+
+class WebhookTests(unittest.TestCase):
+    secret = "whsec"
+    body = json.dumps({"bot": "1", "user": "2", "type": "upvote", "isWeekend": False})
+
+    def signature(self):
+        return hmac.new(self.secret.encode(), self.body.encode(), hashlib.sha256).hexdigest()
+
+    def test_accepts_a_good_signature(self):
+        self.assertTrue(verify_webhook(self.secret, self.body, self.signature()))
+        self.assertTrue(verify_webhook(self.secret, self.body.encode(), self.signature()))
+        self.assertEqual(parse_webhook(self.secret, self.body, self.signature())["user"], "2")
+
+    def test_refuses_a_bad_signature(self):
+        self.assertFalse(verify_webhook("other", self.body, self.signature()))
+        self.assertFalse(verify_webhook(self.secret, self.body + " ", self.signature()))
+        self.assertFalse(verify_webhook(self.secret, self.body, None))
+        self.assertIsNone(parse_webhook("other", self.body, self.signature()))
+
+
+if __name__ == "__main__":
+    unittest.main()