discordbots 1.0.0__tar.gz

discordbots-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DiscordBots
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

discordbots-1.0.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: discordbots
+Version: 1.0.0
+Summary: Official SDK for the DiscordBots bot API: vote checks, server stats and vote webhooks.
+Author: DiscordBots
+License: MIT
+Project-URL: Documentation, https://discordbots.in/docs
+Keywords: discord,bot,votes,webhook,discordbots
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: aiohttp
+Requires-Dist: aiohttp>=3.9; extra == "aiohttp"
+Dynamic: license-file
+
+# discordbots
+
+Check votes, post your server count and receive vote webhooks for bots listed on DiscordBots. Python 3.9+.
+
+```bash
+pip install "discordbots[aiohttp]"   # async client + webhook server (discord.py, nextcord, pycord)
+pip install discordbots              # blocking client only, no dependencies
+```
+
+Get a token from your bot's page on DiscordBots: **Manage → Webhooks & API → Generate token**.
+Put it in `DISCORDBOTS_TOKEN` and the SDK picks it up.
+
+## Vote-only command
+
+```python
+from discordbots import AsyncApi
+
+dbots = AsyncApi()  # reads DISCORDBOTS_TOKEN
+
+@bot.tree.command(name="daily")
+async def daily(interaction: discord.Interaction):
+    if not await dbots.has_voted(interaction.user.id):
+        url = await dbots.vote_url()
+        return await interaction.response.send_message(f"Vote first: {url}", ephemeral=True)
+    await interaction.response.send_message("Here is your daily reward.")
+```
+
+A vote lasts 12 hours. A "yes" is cached until the vote expires and a "no" for 30 seconds (`cache_seconds`), and parallel checks for one user share one request. After a 429 the SDK waits for `Retry-After`. Call `dbots.forget(user_id)` in your webhook to unlock a new voter instantly.
+
+Or use the decorator and choose what non-voters see:
+
+```python
+async def locked(interaction, vote_url):
+    await interaction.response.send_message(f"Vote first: {vote_url}", ephemeral=True)
+
+@bot.tree.command(name="daily")
+@dbots.require_vote(on_not_voted=locked)
+async def daily(interaction):
+    await interaction.response.send_message("You got 500 coins.")
+
+@bot.command()           # prefix commands work too
+@dbots.require_vote()
+async def rob(ctx, target: str):
+    await ctx.send(f"Robbing {target}")
+```
+
+If the API is down the command still runs. Pass `on_error=` to handle that yourself.
+
+## One setup for all commands
+
+```python
+from discordbots import AsyncApi, vote
+
+dbots = AsyncApi()
+dbots.setup(bot)                 # vote_all=True locks every command unless marked vote=False
+
+@vote(True)
+@bot.tree.command(name="daily")
+async def daily(interaction): ...
+
+@bot.command(extras={"vote": True})   # extras works too, slash and prefix
+async def rob(ctx): ...
+```
+
+Own handler? `guard = dbots.vote_guard()` then `if not await guard(ctx, command): return`.
+
+## Post your server count
+
+```python
+from discordbots import AutoPoster
+
+class MyBot(commands.Bot):
+    async def setup_hook(self):
+        AutoPoster(None, self, on_error=print).start()  # None = token from env
+```
+
+Waits for the bot to be ready, then sends servers, users and shards every 30 minutes (`interval_minutes=60`, at least 5).
+`AutoShardedBot` works the same. To post by hand: `await dbots.post_stats(server_count, user_count, shard_count)`.
+
+## Vote webhook
+
+```python
+from aiohttp import web
+from discordbots import Webhook
+
+webhook = Webhook()  # reads DISCORDBOTS_WEBHOOK_SECRET
+
+async def on_vote(vote):
+    if vote["type"] == "test":
+        return
+    await give_coins(int(vote["user"]), 100 * vote["weight"])  # weight is 2 on double-vote weekends
+
+app = web.Application()
+app.router.add_post("/votes", webhook.aiohttp_handler(on_vote))
+web.run_app(app, port=3000)
+```
+
+Flask or FastAPI: `vote = webhook.parse(request.headers, raw_body)` returns the vote, or `None` if it didn't come from us.
+
+## All methods
+
+`Api` (blocking) and `AsyncApi` have the same methods; on `AsyncApi` you `await` them.
+
+| Method | Returns |
+|---|---|
+| `has_voted(user_id)` | `bool` |
+| `check_vote(user_id)` | `{"voted", "voted_at", "expires_at"}` |
+| `require_vote(on_not_voted=, get_user_id=, on_error=)` | decorator (`AsyncApi`) |
+| `setup(bot, vote_all=False, on_not_voted=)` | checks every command's vote flag (`AsyncApi`) |
+| `vote_guard(vote_all=False, ...)` | `async (ctx, command) -> bool` (`AsyncApi`) |
+| `get_bot()` | your listing (name, votes, stats, `vote_url`) |
+| `vote_url()` | link to your vote page (`AsyncApi`) |
+| `get_votes(limit=100)` | recent voters |
+| `is_weekend()` | `True` when votes count double |
+| `post_stats(server_count, user_count=None, shard_count=None)` | saved stats |
+
+Errors are raised as `DiscordBotsError` with `.status`.
+
+Environment variables: `DISCORDBOTS_TOKEN`, `DISCORDBOTS_WEBHOOK_SECRET`, `DISCORDBOTS_API_URL` (testing only).
+
+Full docs: https://discordbots.in/docs

discordbots-1.0.0/README.md

@@ -0,0 +1,121 @@
+# discordbots
+
+Check votes, post your server count and receive vote webhooks for bots listed on DiscordBots. Python 3.9+.
+
+```bash
+pip install "discordbots[aiohttp]"   # async client + webhook server (discord.py, nextcord, pycord)
+pip install discordbots              # blocking client only, no dependencies
+```
+
+Get a token from your bot's page on DiscordBots: **Manage → Webhooks & API → Generate token**.
+Put it in `DISCORDBOTS_TOKEN` and the SDK picks it up.
+
+## Vote-only command
+
+```python
+from discordbots import AsyncApi
+
+dbots = AsyncApi()  # reads DISCORDBOTS_TOKEN
+
+@bot.tree.command(name="daily")
+async def daily(interaction: discord.Interaction):
+    if not await dbots.has_voted(interaction.user.id):
+        url = await dbots.vote_url()
+        return await interaction.response.send_message(f"Vote first: {url}", ephemeral=True)
+    await interaction.response.send_message("Here is your daily reward.")
+```
+
+A vote lasts 12 hours. A "yes" is cached until the vote expires and a "no" for 30 seconds (`cache_seconds`), and parallel checks for one user share one request. After a 429 the SDK waits for `Retry-After`. Call `dbots.forget(user_id)` in your webhook to unlock a new voter instantly.
+
+Or use the decorator and choose what non-voters see:
+
+```python
+async def locked(interaction, vote_url):
+    await interaction.response.send_message(f"Vote first: {vote_url}", ephemeral=True)
+
+@bot.tree.command(name="daily")
+@dbots.require_vote(on_not_voted=locked)
+async def daily(interaction):
+    await interaction.response.send_message("You got 500 coins.")
+
+@bot.command()           # prefix commands work too
+@dbots.require_vote()
+async def rob(ctx, target: str):
+    await ctx.send(f"Robbing {target}")
+```
+
+If the API is down the command still runs. Pass `on_error=` to handle that yourself.
+
+## One setup for all commands
+
+```python
+from discordbots import AsyncApi, vote
+
+dbots = AsyncApi()
+dbots.setup(bot)                 # vote_all=True locks every command unless marked vote=False
+
+@vote(True)
+@bot.tree.command(name="daily")
+async def daily(interaction): ...
+
+@bot.command(extras={"vote": True})   # extras works too, slash and prefix
+async def rob(ctx): ...
+```
+
+Own handler? `guard = dbots.vote_guard()` then `if not await guard(ctx, command): return`.
+
+## Post your server count
+
+```python
+from discordbots import AutoPoster
+
+class MyBot(commands.Bot):
+    async def setup_hook(self):
+        AutoPoster(None, self, on_error=print).start()  # None = token from env
+```
+
+Waits for the bot to be ready, then sends servers, users and shards every 30 minutes (`interval_minutes=60`, at least 5).
+`AutoShardedBot` works the same. To post by hand: `await dbots.post_stats(server_count, user_count, shard_count)`.
+
+## Vote webhook
+
+```python
+from aiohttp import web
+from discordbots import Webhook
+
+webhook = Webhook()  # reads DISCORDBOTS_WEBHOOK_SECRET
+
+async def on_vote(vote):
+    if vote["type"] == "test":
+        return
+    await give_coins(int(vote["user"]), 100 * vote["weight"])  # weight is 2 on double-vote weekends
+
+app = web.Application()
+app.router.add_post("/votes", webhook.aiohttp_handler(on_vote))
+web.run_app(app, port=3000)
+```
+
+Flask or FastAPI: `vote = webhook.parse(request.headers, raw_body)` returns the vote, or `None` if it didn't come from us.
+
+## All methods
+
+`Api` (blocking) and `AsyncApi` have the same methods; on `AsyncApi` you `await` them.
+
+| Method | Returns |
+|---|---|
+| `has_voted(user_id)` | `bool` |
+| `check_vote(user_id)` | `{"voted", "voted_at", "expires_at"}` |
+| `require_vote(on_not_voted=, get_user_id=, on_error=)` | decorator (`AsyncApi`) |
+| `setup(bot, vote_all=False, on_not_voted=)` | checks every command's vote flag (`AsyncApi`) |
+| `vote_guard(vote_all=False, ...)` | `async (ctx, command) -> bool` (`AsyncApi`) |
+| `get_bot()` | your listing (name, votes, stats, `vote_url`) |
+| `vote_url()` | link to your vote page (`AsyncApi`) |
+| `get_votes(limit=100)` | recent voters |
+| `is_weekend()` | `True` when votes count double |
+| `post_stats(server_count, user_count=None, shard_count=None)` | saved stats |
+
+Errors are raised as `DiscordBotsError` with `.status`.
+
+Environment variables: `DISCORDBOTS_TOKEN`, `DISCORDBOTS_WEBHOOK_SECRET`, `DISCORDBOTS_API_URL` (testing only).
+
+Full docs: https://discordbots.in/docs

discordbots-1.0.0/discordbots/__init__.py

@@ -0,0 +1,487 @@
+"""DiscordBots SDK for Python (3.9+). Standard library only; aiohttp optional for the async client."""
+
+from __future__ import annotations
+
+import os
+import hashlib
+import hmac
+import json
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Mapping, Optional
+
+__all__ = ["Api", "AsyncApi", "AutoPoster", "Webhook", "DiscordBotsError", "DiscoveryError", "VoteRequired", "vote", "needs_vote"]
+__version__ = "1.0.0"
+
+DEFAULT_BASE = "https://api.discordbots.in/api/v1"
+_TOKEN_RE = re.compile(r"^hcd_[A-Za-z0-9]{48}$")
+
+
+class DiscoveryError(Exception):
+    def __init__(self, status: int, message: str):
+        super().__init__(message)
+        self.status = status
+
+async def _call(fn, *args):
+    import inspect
+    r = fn(*args)
+    return await r if inspect.isawaitable(r) else r
+
+
+def needs_vote(command, vote_all=False) -> bool:
+    """Reads the vote flag from a discord.py command (extras["vote"]) or a function marked with @vote()."""
+    if command is None:
+        return vote_all
+    extras = getattr(command, "extras", None) or {}
+    flag = extras.get("vote") if isinstance(extras, dict) else None
+    if flag is None:
+        flag = getattr(getattr(command, "callback", command), "__discordbots_vote__", None)
+    return flag if isinstance(flag, bool) else vote_all
+
+
+def vote(required: bool = True):
+    """Mark a command as voters-only (True) or never locked (False). Put it above or below the command decorator.
+
+        @vote(True)
+        @bot.tree.command(name="daily")
+        async def daily(interaction): ...
+    """
+    def deco(obj):
+        extras = getattr(obj, "extras", None)
+        if isinstance(extras, dict):
+            extras["vote"] = required
+        target = getattr(obj, "callback", obj)
+        try:
+            setattr(target, "__discordbots_vote__", required)
+        except Exception:
+            pass
+        return obj
+    return deco
+
+
+try:
+    from discord import app_commands as _ac
+    from discord.ext import commands as _ext
+
+    class VoteRequired(_ac.CheckFailure, _ext.CheckFailure):
+        """Raised by setup() checks when a non-voter uses a locked command. Already handled; ignore it."""
+except Exception:  # discord.py not installed: the blocking client still works
+    class VoteRequired(Exception):
+        pass
+
+
+
+def _check_token(token: str) -> None:
+    if not _TOKEN_RE.match(token or ""):
+        raise ValueError("Invalid DiscordBots API token.")
+
+
+class _VoteCache:
+    """Voters cached until their vote expires (max 12h), non-voters for `ttl` seconds. Bounded (oldest dropped)."""
+
+    def __init__(self, ttl: int, max_size: int):
+        from collections import OrderedDict
+        self.ttl, self.max_size = ttl, max_size
+        self.data: "OrderedDict[str, tuple[bool, float]]" = OrderedDict()
+        self.blocked_until = 0.0
+
+    def get(self, uid: str):
+        hit = self.data.get(uid)
+        return hit[0] if hit and hit[1] > time.time() else None
+
+    def put(self, uid: str, voted: bool, expires_at: Optional[str]):
+        now = time.time()
+        until = now + self.ttl
+        if voted:
+            until = now + 12 * 3600
+            if expires_at:
+                try:
+                    from datetime import datetime
+                    until = min(until, datetime.fromisoformat(expires_at.replace("Z", "+00:00")).timestamp())
+                except ValueError:
+                    pass
+        self.data.pop(uid, None)
+        self.data[uid] = (voted, until)
+        if len(self.data) > self.max_size:
+            for k in [k for k, v in self.data.items() if v[1] <= now]:
+                del self.data[k]
+            while len(self.data) > self.max_size:
+                self.data.popitem(last=False)
+
+    def check_blocked(self):
+        if time.time() < self.blocked_until:
+            raise DiscoveryError(429, f"Rate limited, retry in {int(self.blocked_until - time.time()) + 1}s")
+
+    def block(self, retry_after):
+        try:
+            wait = int(float(retry_after or 60))
+        except ValueError:
+            wait = 60
+        self.blocked_until = time.time() + min(max(wait, 1), 3600)
+
+
+class Api:
+    """Blocking client (fine for scripts, or call from a thread)."""
+
+    def __init__(self, token: Optional[str] = None, base_url: Optional[str] = None, cache_seconds: int = 30,
+                 max_cache_size: int = 50_000):
+        token = token or os.environ.get("DISCORDBOTS_TOKEN")
+        base_url = base_url or os.environ.get("DISCORDBOTS_API_URL") or DEFAULT_BASE
+        _check_token(token)
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self.cache_seconds = cache_seconds
+        self._cache = _VoteCache(cache_seconds, max_cache_size)
+
+    def _request(self, method: str, path: str, body: Optional[dict] = None) -> Any:
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(self.base_url + path, data=data, method=method)
+        req.add_header("Authorization", self.token)
+        req.add_header("Accept", "application/json")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        self._cache.check_blocked()
+        try:
+            with urllib.request.urlopen(req, timeout=10) as res:
+                return json.loads(res.read() or b"{}")
+        except urllib.error.HTTPError as e:
+            if e.code == 429:
+                self._cache.block(e.headers.get("Retry-After"))
+            try:
+                msg = json.loads(e.read()).get("message", str(e))
+            except Exception:
+                msg = str(e)
+            raise DiscoveryError(e.code, msg) from None
+
+    def has_voted(self, user_id: int | str) -> bool:
+        """Has this Discord user voted in the last 12 hours? Voters are cached until the vote expires."""
+        uid = str(user_id)
+        hit = self._cache.get(uid)
+        if hit is not None:
+            return hit
+        r = self.check_vote(uid)
+        self._cache.put(uid, bool(r["voted"]), r.get("expires_at"))
+        return bool(r["voted"])
+
+    def forget(self, user_id: int | str) -> None:
+        """Drop a cached answer, e.g. when your vote webhook fires for this user."""
+        self._cache.data.pop(str(user_id), None)
+
+    def check_vote(self, user_id: int | str) -> dict:
+        return self._request("GET", "/bot/check?userId=" + urllib.parse.quote(str(user_id)))
+
+    def get_bot(self) -> dict:
+        return self._request("GET", "/bot")
+
+    def get_votes(self, limit: int = 100) -> list:
+        return self._request("GET", f"/bot/votes?limit={int(limit)}")["data"]
+
+    def is_weekend(self) -> bool:
+        return bool(self._request("GET", "/bot/weekend")["double_votes"])
+
+    def post_stats(self, server_count: int, user_count: Optional[int] = None, shard_count: Optional[int] = None) -> dict:
+        return self._request("POST", "/bot/stats", {"server_count": server_count, "user_count": user_count, "shard_count": shard_count})
+
+
+class AsyncApi:
+    """asyncio client for discord.py / nextcord / pycord. Needs `pip install discordbots[aiohttp]`."""
+
+    def __init__(self, token: Optional[str] = None, base_url: Optional[str] = None, cache_seconds: int = 30,
+                 max_cache_size: int = 50_000):
+        token = token or os.environ.get("DISCORDBOTS_TOKEN")
+        base_url = base_url or os.environ.get("DISCORDBOTS_API_URL") or DEFAULT_BASE
+        _check_token(token)
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self.cache_seconds = cache_seconds
+        self._cache = _VoteCache(cache_seconds, max_cache_size)
+        self._session = None
+        self._inflight: dict = {}
+
+    async def _request(self, method: str, path: str, body: Optional[dict] = None) -> Any:
+        import aiohttp
+
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                headers={"Authorization": self.token, "Accept": "application/json"},
+                timeout=aiohttp.ClientTimeout(total=10),
+            )
+        self._cache.check_blocked()
+        async with self._session.request(method, self.base_url + path, json=body) as res:
+            if res.status == 429:
+                self._cache.block(res.headers.get("Retry-After"))
+            data = await res.json(content_type=None) if res.content_length != 0 else {}
+            if res.status >= 400:
+                raise DiscoveryError(res.status, (data or {}).get("message", f"Request failed ({res.status})"))
+            return data
+
+    async def has_voted(self, user_id: int | str) -> bool:
+        """Voters are cached until the vote expires; parallel checks for one user share one request."""
+        import asyncio
+
+        uid = str(user_id)
+        hit = self._cache.get(uid)
+        if hit is not None:
+            return hit
+        if uid in self._inflight:
+            return await asyncio.shield(self._inflight[uid])
+
+        async def fetch():
+            try:
+                r = await self._request("GET", "/bot/check?userId=" + urllib.parse.quote(uid))
+                self._cache.put(uid, bool(r["voted"]), r.get("expires_at"))
+                return bool(r["voted"])
+            finally:
+                self._inflight.pop(uid, None)
+
+        task = asyncio.ensure_future(fetch())
+        self._inflight[uid] = task
+        return await asyncio.shield(task)
+
+    def forget(self, user_id: int | str) -> None:
+        """Drop a cached answer, e.g. when your vote webhook fires for this user."""
+        self._cache.data.pop(str(user_id), None)
+
+    async def check_vote(self, user_id: int | str) -> dict:
+        """{"voted", "voted_at", "expires_at"} for this user, not cached."""
+        return await self._request("GET", "/bot/check?userId=" + urllib.parse.quote(str(user_id)))
+
+    async def get_bot(self) -> dict:
+        return await self._request("GET", "/bot")
+
+    async def vote_url(self) -> str:
+        if not getattr(self, "_vote_url", None):
+            self._vote_url = (await self.get_bot())["vote_url"]
+        return self._vote_url
+
+    async def _allowed(self, ctx, on_not_voted=None, get_user_id=None, on_error=None) -> bool:
+        """True if the command may run. When it may not, the user has already been told."""
+        if get_user_id:
+            uid = get_user_id(ctx)
+        else:
+            u = getattr(ctx, "user", None) or getattr(ctx, "author", None)
+            uid = getattr(u, "id", None)
+        try:
+            if await self.has_voted(uid):
+                return True
+        except Exception as err:
+            if on_error:
+                await _call(on_error, ctx, err)
+                return False
+            # Only fail open when our API is unreachable (network / 5xx). Bad ids or token stay locked.
+            if not isinstance(err, DiscoveryError) or err.status >= 500 or err.status == 429:
+                return True
+        try:
+            url = await self.vote_url()
+        except Exception:
+            url = None
+        if on_not_voted:
+            await _call(on_not_voted, ctx, url)
+            return False
+        msg = f"You need to vote to use this command: {url}"
+        resp = getattr(ctx, "response", None)
+        if resp is not None and not resp.is_done():
+            await resp.send_message(msg, ephemeral=True)
+        elif hasattr(ctx, "send"):
+            await ctx.send(msg)
+        return False
+
+    def require_vote(self, on_not_voted=None, get_user_id=None, on_error=None):
+        """Decorator for a single command: it only runs for voters.
+
+            @tree.command(name="daily")
+            @dbots.require_vote(on_not_voted=my_vote_embed)
+            async def daily(interaction): ...
+        """
+        import functools
+
+        def deco(func):
+            @functools.wraps(func)
+            async def wrapper(ctx, *args, **kwargs):
+                if await self._allowed(ctx, on_not_voted, get_user_id, on_error):
+                    return await func(ctx, *args, **kwargs)
+            return wrapper
+        return deco
+
+    def vote_guard(self, vote_all=False, on_not_voted=None, get_user_id=None, on_error=None):
+        """Returns `async guard(ctx, command) -> bool` for your own command handler.
+
+        A command needs a vote when it is marked `vote=True` (see `vote()` / extras={"vote": True}),
+        or when vote_all=True and it isn't marked `vote=False`.
+        """
+        async def guard(ctx, command=None) -> bool:
+            if not needs_vote(command, vote_all):
+                return True
+            return await self._allowed(ctx, on_not_voted, get_user_id, on_error)
+        return guard
+
+    def setup(self, bot, vote_all=False, on_not_voted=None, on_error=None):
+        """One line in your main file. Every slash and prefix command is checked:
+
+            dbots.setup(bot)                  # only commands marked vote=True are locked
+            dbots.setup(bot, vote_all=True)   # everything is locked unless marked vote=False
+
+        Mark commands with `@vote(True)` / `@vote(False)` or `extras={"vote": True}`.
+        """
+        from discord import app_commands
+        from discord.ext import commands as ext
+
+        guard = self.vote_guard(vote_all, on_not_voted, None, on_error)
+
+        tree = getattr(bot, "tree", None)
+        if tree is not None:
+            original_check = tree.interaction_check
+            original_error = tree.on_error
+
+            async def interaction_check(interaction):
+                if not await original_check(interaction):
+                    return False
+                if not await guard(interaction, interaction.command):
+                    raise VoteRequired()
+                return True
+
+            async def on_error(interaction, error):
+                if isinstance(error, VoteRequired):
+                    return  # the user was already told to vote
+                await original_error(interaction, error)
+
+            tree.interaction_check = interaction_check
+            tree.on_error = on_error
+
+        if isinstance(bot, ext.Bot):
+            async def prefix_check(ctx):
+                if not await guard(ctx, ctx.command):
+                    raise VoteRequired()
+                return True
+
+            original_cmd_error = bot.on_command_error
+
+            async def on_command_error(ctx, error):
+                if isinstance(error, VoteRequired):
+                    return
+                await original_cmd_error(ctx, error)
+
+            bot.add_check(prefix_check)
+            bot.on_command_error = on_command_error
+        return guard
+
+    async def get_votes(self, limit: int = 100) -> list:
+        return (await self._request("GET", f"/bot/votes?limit={int(limit)}"))["data"]
+
+    async def is_weekend(self) -> bool:
+        return bool((await self._request("GET", "/bot/weekend"))["double_votes"])
+
+    async def post_stats(self, server_count: int, user_count: Optional[int] = None, shard_count: Optional[int] = None) -> dict:
+        return await self._request("POST", "/bot/stats", {"server_count": server_count, "user_count": user_count, "shard_count": shard_count})
+
+    async def close(self) -> None:
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+
+class AutoPoster:
+    """Posts servers, users and shards automatically for discord.py / nextcord / pycord bots.
+
+        poster = AutoPoster(os.environ["DISCORDBOTS_TOKEN"], bot)   # create once, e.g. in setup_hook
+        poster.start()
+
+    Waits until the bot is ready, then posts every `interval_minutes` (minimum 5, default 30).
+    For AutoShardedBot the totals across all shards are posted.
+    """
+
+    def __init__(self, token: Optional[str], bot, interval_minutes: int = 30, api: "Optional[AsyncApi]" = None,
+                 on_success=None, on_error=None):
+        self.api = api or AsyncApi(token)
+        self.bot = bot
+        self.interval = max(5, int(interval_minutes)) * 60
+        self.on_success = on_success
+        self.on_error = on_error
+        self._task = None
+
+    def stats(self) -> dict:
+        guilds = list(getattr(self.bot, "guilds", []))
+        return {
+            "server_count": len(guilds),
+            "user_count": sum((getattr(g, "member_count", None) or 0) for g in guilds),
+            "shard_count": getattr(self.bot, "shard_count", None) or 1,
+        }
+
+    async def post_once(self) -> dict:
+        s = self.stats()
+        await self.api.post_stats(**s)
+        return s
+
+    async def _loop(self):
+        import asyncio
+
+        wait = getattr(self.bot, "wait_until_ready", None)
+        if wait:
+            await wait()
+        while True:
+            try:
+                s = await self.post_once()
+                if self.on_success:
+                    self.on_success(s)
+            except Exception as e:  # never crash the bot because stats failed
+                if self.on_error:
+                    self.on_error(e)
+            await asyncio.sleep(self.interval)
+
+    def start(self):
+        import asyncio
+
+        if self._task is None or self._task.done():
+            self._task = asyncio.get_event_loop().create_task(self._loop())
+        return self._task
+
+    def stop(self):
+        if self._task and not self._task.done():
+            self._task.cancel()
+
+
+class Webhook:
+    """Verifies vote webhooks: Authorization == secret, and the X-DiscordBots-Signature HMAC when present."""
+
+    def __init__(self, secret: Optional[str] = None):
+        secret = secret or os.environ.get("DISCORDBOTS_WEBHOOK_SECRET")
+        if not secret:
+            raise ValueError("Webhook secret is required.")
+        self.secret = secret
+
+    def verify(self, headers: Mapping[str, str], raw_body: bytes) -> bool:
+        h = {k.lower(): v for k, v in headers.items()}
+        if not hmac.compare_digest(h.get("authorization", ""), self.secret):
+            return False
+        sig = h.get("x-discordbots-signature")
+        if sig:
+            expected = "sha256=" + hmac.new(self.secret.encode(), raw_body, hashlib.sha256).hexdigest()
+            if not hmac.compare_digest(sig, expected):
+                return False
+        return True
+
+    def parse(self, headers: Mapping[str, str], raw_body: bytes) -> Optional[dict]:
+        """Returns the vote dict if the request is genuine, otherwise None."""
+        if not self.verify(headers, raw_body):
+            return None
+        try:
+            return json.loads(raw_body)
+        except ValueError:
+            return None
+
+    def aiohttp_handler(self, on_vote):
+        """aiohttp route handler: app.router.add_post('/votes', webhook.aiohttp_handler(on_vote))"""
+        from aiohttp import web
+
+        async def handler(request):
+            vote = self.parse(request.headers, await request.read())
+            if vote is None:
+                return web.json_response({"error": "Unauthorized"}, status=401)
+            await on_vote(vote)
+            return web.Response(status=204)
+
+        return handler
+
+DiscordBotsError = DiscoveryError  # new name, same class

discordbots-1.0.0/discordbots.egg-info/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: discordbots
+Version: 1.0.0
+Summary: Official SDK for the DiscordBots bot API: vote checks, server stats and vote webhooks.
+Author: DiscordBots
+License: MIT
+Project-URL: Documentation, https://discordbots.in/docs
+Keywords: discord,bot,votes,webhook,discordbots
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: aiohttp
+Requires-Dist: aiohttp>=3.9; extra == "aiohttp"
+Dynamic: license-file
+
+# discordbots
+
+Check votes, post your server count and receive vote webhooks for bots listed on DiscordBots. Python 3.9+.
+
+```bash
+pip install "discordbots[aiohttp]"   # async client + webhook server (discord.py, nextcord, pycord)
+pip install discordbots              # blocking client only, no dependencies
+```
+
+Get a token from your bot's page on DiscordBots: **Manage → Webhooks & API → Generate token**.
+Put it in `DISCORDBOTS_TOKEN` and the SDK picks it up.
+
+## Vote-only command
+
+```python
+from discordbots import AsyncApi
+
+dbots = AsyncApi()  # reads DISCORDBOTS_TOKEN
+
+@bot.tree.command(name="daily")
+async def daily(interaction: discord.Interaction):
+    if not await dbots.has_voted(interaction.user.id):
+        url = await dbots.vote_url()
+        return await interaction.response.send_message(f"Vote first: {url}", ephemeral=True)
+    await interaction.response.send_message("Here is your daily reward.")
+```
+
+A vote lasts 12 hours. A "yes" is cached until the vote expires and a "no" for 30 seconds (`cache_seconds`), and parallel checks for one user share one request. After a 429 the SDK waits for `Retry-After`. Call `dbots.forget(user_id)` in your webhook to unlock a new voter instantly.
+
+Or use the decorator and choose what non-voters see:
+
+```python
+async def locked(interaction, vote_url):
+    await interaction.response.send_message(f"Vote first: {vote_url}", ephemeral=True)
+
+@bot.tree.command(name="daily")
+@dbots.require_vote(on_not_voted=locked)
+async def daily(interaction):
+    await interaction.response.send_message("You got 500 coins.")
+
+@bot.command()           # prefix commands work too
+@dbots.require_vote()
+async def rob(ctx, target: str):
+    await ctx.send(f"Robbing {target}")
+```
+
+If the API is down the command still runs. Pass `on_error=` to handle that yourself.
+
+## One setup for all commands
+
+```python
+from discordbots import AsyncApi, vote
+
+dbots = AsyncApi()
+dbots.setup(bot)                 # vote_all=True locks every command unless marked vote=False
+
+@vote(True)
+@bot.tree.command(name="daily")
+async def daily(interaction): ...
+
+@bot.command(extras={"vote": True})   # extras works too, slash and prefix
+async def rob(ctx): ...
+```
+
+Own handler? `guard = dbots.vote_guard()` then `if not await guard(ctx, command): return`.
+
+## Post your server count
+
+```python
+from discordbots import AutoPoster
+
+class MyBot(commands.Bot):
+    async def setup_hook(self):
+        AutoPoster(None, self, on_error=print).start()  # None = token from env
+```
+
+Waits for the bot to be ready, then sends servers, users and shards every 30 minutes (`interval_minutes=60`, at least 5).
+`AutoShardedBot` works the same. To post by hand: `await dbots.post_stats(server_count, user_count, shard_count)`.
+
+## Vote webhook
+
+```python
+from aiohttp import web
+from discordbots import Webhook
+
+webhook = Webhook()  # reads DISCORDBOTS_WEBHOOK_SECRET
+
+async def on_vote(vote):
+    if vote["type"] == "test":
+        return
+    await give_coins(int(vote["user"]), 100 * vote["weight"])  # weight is 2 on double-vote weekends
+
+app = web.Application()
+app.router.add_post("/votes", webhook.aiohttp_handler(on_vote))
+web.run_app(app, port=3000)
+```
+
+Flask or FastAPI: `vote = webhook.parse(request.headers, raw_body)` returns the vote, or `None` if it didn't come from us.
+
+## All methods
+
+`Api` (blocking) and `AsyncApi` have the same methods; on `AsyncApi` you `await` them.
+
+| Method | Returns |
+|---|---|
+| `has_voted(user_id)` | `bool` |
+| `check_vote(user_id)` | `{"voted", "voted_at", "expires_at"}` |
+| `require_vote(on_not_voted=, get_user_id=, on_error=)` | decorator (`AsyncApi`) |
+| `setup(bot, vote_all=False, on_not_voted=)` | checks every command's vote flag (`AsyncApi`) |
+| `vote_guard(vote_all=False, ...)` | `async (ctx, command) -> bool` (`AsyncApi`) |
+| `get_bot()` | your listing (name, votes, stats, `vote_url`) |
+| `vote_url()` | link to your vote page (`AsyncApi`) |
+| `get_votes(limit=100)` | recent voters |
+| `is_weekend()` | `True` when votes count double |
+| `post_stats(server_count, user_count=None, shard_count=None)` | saved stats |
+
+Errors are raised as `DiscordBotsError` with `.status`.
+
+Environment variables: `DISCORDBOTS_TOKEN`, `DISCORDBOTS_WEBHOOK_SECRET`, `DISCORDBOTS_API_URL` (testing only).
+
+Full docs: https://discordbots.in/docs

discordbots-1.0.0/discordbots.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+discordbots/__init__.py
+discordbots.egg-info/PKG-INFO
+discordbots.egg-info/SOURCES.txt
+discordbots.egg-info/dependency_links.txt
+discordbots.egg-info/requires.txt
+discordbots.egg-info/top_level.txt

discordbots-1.0.0/discordbots.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

discordbots-1.0.0/discordbots.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[aiohttp]
+aiohttp>=3.9

discordbots-1.0.0/discordbots.egg-info/top_level.txt

@@ -0,0 +1 @@
+discordbots

discordbots-1.0.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "discordbots"
+version = "1.0.0"
+description = "Official SDK for the DiscordBots bot API: vote checks, server stats and vote webhooks."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = []
+keywords = ["discord", "bot", "votes", "webhook", "discordbots"]
+
+authors = [{ name = "DiscordBots" }]
+
+[project.urls]
+Documentation = "https://discordbots.in/docs"
+
+[project.optional-dependencies]
+aiohttp = ["aiohttp>=3.9"]

discordbots-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+