banterbotapi 0.1.0__py3-none-any.whl

banterapi/__init__.py

@@ -0,0 +1,32 @@
+__version__ = "0.1.0"
+
+from .client import Bot
+from .intents import Intents
+from .embed import Embed
+from .models import User, Guild, Channel, Member, Role, Message
+from .errors import BanterError, HTTPException, Forbidden, NotFound, RateLimited, GatewayError, LoginFailure, MissingPermissions
+from .permissions import Permissions
+from .commands import has_permissions
+
+__all__ = [
+    "__version__",
+    "Bot",
+    "Intents",
+    "Embed",
+    "User",
+    "Guild",
+    "Channel",
+    "Member",
+    "Role",
+    "Message",
+    "Permissions",
+    "has_permissions",
+    "BanterError",
+    "HTTPException",
+    "Forbidden",
+    "NotFound",
+    "RateLimited",
+    "GatewayError",
+    "LoginFailure",
+    "MissingPermissions",
+]

banterapi/client.py

@@ -0,0 +1,202 @@
+import asyncio
+import inspect
+import logging
+
+from .commands import Command, CommandRegistry, Context, CommandError, CommandNotFound
+from .gateway import Gateway
+from .http import HTTPClient
+from .intents import Intents
+from .models import User, Guild, Channel, Member, Message
+from .errors import GatewayError
+
+log = logging.getLogger("banterapi")
+
+
+class Bot:
+    def __init__(self, intents=None, base_url="https://banterchat.org", ws_url=None, reconnect=True, command_prefix="!", application_id=""):
+        self.intents = intents if intents is not None else Intents.default()
+        self.base_url = base_url.rstrip("/")
+        self.ws_url = ws_url or self.base_url.replace("http://", "ws://").replace("https://", "wss://") + "/api/bot/ws"
+        self.reconnect = reconnect
+        self.command_prefix = command_prefix
+        self.application_id = application_id
+        self.user = None
+        self.guilds = {}
+        self._http = None
+        self._gateway = None
+        self._handlers = {}
+        self._commands = CommandRegistry()
+        self._slash_commands = []
+        self._loop = None
+
+    def event(self, fn):
+        name = fn.__name__
+        if not name.startswith("on_"):
+            raise ValueError("event handlers must be named on_<event>")
+        self._handlers[name] = fn
+        return fn
+
+    def command(self, name=None, aliases=None, help=None, slash=False, description=""):
+        def decorator(fn):
+            cmd = Command(fn, name=name, aliases=aliases, help=help)
+            self._commands.add(cmd)
+            if slash:
+                self._slash_commands.append({
+                    "name": cmd.name,
+                    "description": description or cmd.help or cmd.name,
+                })
+            return fn
+        return decorator
+
+    def slash_command(self, name=None, description=""):
+        def decorator(fn):
+            cmd = Command(fn, name=name, help=description)
+            self._commands.add(cmd)
+            self._slash_commands.append({
+                "name": cmd.name,
+                "description": description or cmd.help or cmd.name,
+            })
+            return fn
+        return decorator
+
+    async def sync_commands(self):
+        if not self.application_id or not self._slash_commands:
+            return 0
+        result = await self._http.register_commands(self.application_id, self._slash_commands)
+        return result.get("registered", len(self._slash_commands)) if result else 0
+
+    @property
+    def commands(self):
+        return self._commands.all()
+
+    async def process_commands(self, message):
+        if self.user is not None and message.user_id == self.user.id:
+            return
+        content = message.content or ""
+        if not content.startswith(self.command_prefix):
+            return
+        stripped = content[len(self.command_prefix):]
+        if not stripped:
+            return
+        parts = stripped.split(maxsplit=1)
+        name = parts[0]
+        args_raw = parts[1] if len(parts) > 1 else ""
+        cmd = self._commands.get(name)
+        if cmd is None:
+            return
+        ctx = Context(self, message, name, args_raw)
+        try:
+            await cmd.invoke(ctx)
+        except CommandError as e:
+            await self._fire("on_command_error", ctx, e)
+        except Exception as e:
+            await self._fire("on_command_error", ctx, e)
+
+    async def _dispatch(self, event_type, payload):
+        if event_type == "ready":
+            user_data = payload.get("user", {})
+            self.user = User.from_dict(user_data)
+            for g in payload.get("guilds", []) or []:
+                guild = Guild.from_dict(g)
+                self.guilds[guild.id] = guild
+            app_id_from_ready = payload.get("application_id", "")
+            if app_id_from_ready and not self.application_id:
+                self.application_id = app_id_from_ready
+            if self._slash_commands:
+                try:
+                    await self.sync_commands()
+                except Exception as e:
+                    log.warning("command sync failed: %s", e)
+            await self._fire("on_ready")
+            return
+
+        if event_type in ("channel_message", "message_create"):
+            msg = Message.from_dict(payload, client=self)
+            await self._fire("on_message", msg)
+            await self.process_commands(msg)
+            return
+
+        if event_type == "message_edit":
+            await self._fire("on_message_edit", payload)
+            return
+
+        if event_type == "message_delete":
+            await self._fire("on_message_delete", payload)
+            return
+
+        if event_type == "reaction_add":
+            await self._fire("on_reaction_add", payload)
+            return
+
+        if event_type == "reaction_remove":
+            await self._fire("on_reaction_remove", payload)
+            return
+
+        if event_type == "guild_member_add":
+            await self._fire("on_member_join", payload)
+            return
+
+        if event_type == "guild_member_remove":
+            await self._fire("on_member_remove", payload)
+            return
+
+        if event_type == "error":
+            await self._fire("on_error", payload)
+            return
+
+        await self._fire("on_raw_event", event_type, payload)
+
+    async def _fire(self, name, *args):
+        handler = self._handlers.get(name)
+        if handler is None:
+            return
+        try:
+            result = handler(*args)
+            if inspect.isawaitable(result):
+                await result
+        except Exception:
+            log.exception("handler %s raised", name)
+
+    async def send_message(self, channel_id, content="", embed=None, reply_to=""):
+        d = await self._http.send_message(channel_id, content=content, embed=embed, reply_to=reply_to)
+        return Message.from_dict(d, client=self) if d else None
+
+    async def get_user(self, user_id):
+        d = await self._http.get_user(user_id)
+        return User.from_dict(d) if d else None
+
+    async def get_guild(self, guild_id):
+        d = await self._http.get_guild(guild_id)
+        return Guild.from_dict(d) if d else None
+
+    async def get_member(self, guild_id, user_id):
+        d = await self._http.get_member(guild_id, user_id)
+        return Member.from_dict(d, guild_id=guild_id) if d else None
+
+    async def list_channels(self, guild_id):
+        d = await self._http.list_channels(guild_id)
+        return [Channel.from_dict(c, client=self) for c in (d or [])]
+
+    async def _start(self, token):
+        self._http = HTTPClient(token, base_url=self.base_url)
+        self._gateway = Gateway(token, self.intents, self.ws_url, self._dispatch)
+        try:
+            while True:
+                try:
+                    await self._gateway.connect()
+                    await self._gateway.run()
+                except GatewayError as e:
+                    log.warning("gateway error: %s", e)
+                if not self.reconnect:
+                    break
+                log.info("reconnecting in 5s")
+                await asyncio.sleep(5)
+        finally:
+            await self._gateway.close()
+            await self._http.close()
+
+    def run(self, token):
+        try:
+            asyncio.run(self._start(token))
+        except KeyboardInterrupt:
+            pass

banterapi/commands.py

@@ -0,0 +1,181 @@
+import inspect
+import shlex
+
+from .errors import MissingPermissions
+from .permissions import has_perm, describe
+
+
+class CommandError(Exception):
+    pass
+
+
+class CommandNotFound(CommandError):
+    pass
+
+
+class MissingArgument(CommandError):
+    def __init__(self, name):
+        self.name = name
+        super().__init__(f"missing required argument: {name}")
+
+
+class BadArgument(CommandError):
+    def __init__(self, name, value, expected):
+        self.name = name
+        self.value = value
+        self.expected = expected
+        super().__init__(f"argument {name!r} expected {expected}, got {value!r}")
+
+
+_BOOL_TRUE = {"true", "yes", "y", "1", "on", "enable"}
+_BOOL_FALSE = {"false", "no", "n", "0", "off", "disable"}
+
+
+def _convert(value, annotation, name):
+    if annotation is inspect.Parameter.empty or annotation is str:
+        return value
+    if annotation is int:
+        try:
+            return int(value)
+        except ValueError:
+            raise BadArgument(name, value, "integer")
+    if annotation is float:
+        try:
+            return float(value)
+        except ValueError:
+            raise BadArgument(name, value, "number")
+    if annotation is bool:
+        v = value.lower()
+        if v in _BOOL_TRUE:
+            return True
+        if v in _BOOL_FALSE:
+            return False
+        raise BadArgument(name, value, "yes/no")
+    return value
+
+
+class Context:
+    def __init__(self, bot, message, invoked_with, args_raw):
+        self.bot = bot
+        self.message = message
+        self.invoked_with = invoked_with
+        self.args_raw = args_raw
+        self.author = message.author
+        self.author_perms = message.author_perms
+        self.channel = message.channel
+        self.channel_id = message.channel_id
+        self.guild_id = message.guild_id
+
+    def has_permissions(self, required):
+        return has_perm(self.author_perms, required)
+
+    async def send(self, content="", embed=None):
+        return await self.bot.send_message(self.channel_id, content=content, embed=embed)
+
+    async def reply(self, content="", embed=None):
+        return await self.message.reply(content=content, embed=embed)
+
+    async def trigger_typing(self):
+        await self.bot._http.trigger_typing(self.channel_id)
+
+
+def has_permissions(*required):
+    """Decorator: block command if invoker lacks any of the given perms.
+
+    Usage:
+        @bot.command(slash=True)
+        @has_permissions(Permissions.KICK_MEMBERS)
+        async def kick(ctx, target: str): ...
+    """
+    required_mask = 0
+    for r in required:
+        required_mask |= r
+    def decorator(fn):
+        existing = getattr(fn, "_required_perms", 0)
+        fn._required_perms = existing | required_mask
+        return fn
+    return decorator
+
+
+class Command:
+    def __init__(self, func, name=None, aliases=None, help=None):
+        self.callback = func
+        self.name = name or func.__name__
+        self.aliases = tuple(aliases or ())
+        self.help = help or (func.__doc__ or "").strip()
+        sig = inspect.signature(func)
+        params = list(sig.parameters.values())
+        if not params:
+            raise ValueError(f"command {self.name!r} must accept a context argument")
+        self.params = params[1:]
+
+    def _parse(self, ctx, args_raw):
+        try:
+            tokens = shlex.split(args_raw) if args_raw else []
+        except ValueError:
+            tokens = args_raw.split() if args_raw else []
+
+        positional = []
+        kwargs = {}
+        i = 0
+        for p in self.params:
+            if p.kind is inspect.Parameter.VAR_POSITIONAL:
+                remaining = tokens[i:]
+                positional.extend(_convert(t, p.annotation, p.name) for t in remaining)
+                i = len(tokens)
+                break
+            if p.kind is inspect.Parameter.KEYWORD_ONLY:
+                remaining = args_raw
+                for _ in range(i):
+                    remaining = remaining.split(maxsplit=1)[1] if " " in remaining else ""
+                remaining = remaining.strip()
+                if not remaining and p.default is inspect.Parameter.empty:
+                    raise MissingArgument(p.name)
+                kwargs[p.name] = remaining if remaining else p.default
+                i = len(tokens)
+                break
+            if i >= len(tokens):
+                if p.default is inspect.Parameter.empty:
+                    raise MissingArgument(p.name)
+                positional.append(p.default)
+            else:
+                positional.append(_convert(tokens[i], p.annotation, p.name))
+                i += 1
+        return positional, kwargs
+
+    @property
+    def required_perms(self):
+        return getattr(self.callback, "_required_perms", 0)
+
+    async def invoke(self, ctx):
+        req = self.required_perms
+        if req and not has_perm(ctx.author_perms, req):
+            missing_bits = req & ~ctx.author_perms
+            raise MissingPermissions(describe(missing_bits))
+        positional, kwargs = self._parse(ctx, ctx.args_raw)
+        result = self.callback(ctx, *positional, **kwargs)
+        if inspect.isawaitable(result):
+            await result
+
+
+class CommandRegistry:
+    def __init__(self):
+        self._commands = {}
+
+    def add(self, command):
+        self._commands[command.name] = command
+        for alias in command.aliases:
+            self._commands[alias] = command
+
+    def get(self, name):
+        return self._commands.get(name)
+
+    def all(self):
+        seen = set()
+        out = []
+        for cmd in self._commands.values():
+            if cmd.name in seen:
+                continue
+            seen.add(cmd.name)
+            out.append(cmd)
+        return out

banterapi/embed.py

@@ -0,0 +1,57 @@
+class Embed:
+    def __init__(self, title="", description="", color=None, url="", image="", thumbnail=""):
+        self._data = {}
+        if title:
+            self._data["title"] = title
+        if description:
+            self._data["description"] = description
+        if color is not None:
+            self._data["color"] = color if isinstance(color, str) else f"#{color:06x}"
+        if url:
+            self._data["url"] = url
+        if image:
+            self._data["image"] = image
+        if thumbnail:
+            self._data["thumbnail"] = thumbnail
+        self._data["fields"] = []
+
+    def add_field(self, name, value, inline=False):
+        self._data["fields"].append({"name": name, "value": value, "inline": inline})
+        return self
+
+    def set_footer(self, text):
+        self._data["footer"] = text
+        return self
+
+    def set_author(self, name):
+        self._data["author"] = name
+        return self
+
+    def set_image(self, url):
+        self._data["image"] = url
+        return self
+
+    def set_thumbnail(self, url):
+        self._data["thumbnail"] = url
+        return self
+
+    def add_button(self, label, style="secondary", url="", emoji="", disabled=False, id=""):
+        btn = {"label": label, "style": style}
+        if url:
+            btn["url"] = url
+        if emoji:
+            btn["emoji"] = emoji
+        if disabled:
+            btn["disabled"] = True
+        if id:
+            btn["id"] = id
+        self._data.setdefault("buttons", []).append(btn)
+        return self
+
+    def to_dict(self):
+        d = dict(self._data)
+        if not d.get("fields"):
+            d.pop("fields", None)
+        if not d.get("buttons"):
+            d.pop("buttons", None)
+        return d

banterapi/errors.py

@@ -0,0 +1,39 @@
+class BanterError(Exception):
+    pass
+
+
+class HTTPException(BanterError):
+    def __init__(self, status, code, message):
+        self.status = status
+        self.code = code
+        self.message = message
+        super().__init__(f"{status} {code}: {message}")
+
+
+class Forbidden(HTTPException):
+    pass
+
+
+class NotFound(HTTPException):
+    pass
+
+
+class RateLimited(HTTPException):
+    def __init__(self, status, code, message, retry_after):
+        super().__init__(status, code, message)
+        self.retry_after = retry_after
+
+
+class GatewayError(BanterError):
+    pass
+
+
+class LoginFailure(BanterError):
+    pass
+
+
+class MissingPermissions(BanterError):
+    def __init__(self, missing):
+        self.missing = missing
+        names = ", ".join(missing) if missing else "unknown"
+        super().__init__(f"Missing permissions: {names}")

banterapi/gateway.py

@@ -0,0 +1,134 @@
+import asyncio
+import json
+
+import websockets
+
+from .errors import GatewayError, LoginFailure
+
+
+OP_DISPATCH = 0
+OP_HEARTBEAT = 1
+OP_HELLO = 10
+OP_HEARTBEAT_ACK = 11
+
+
+def _headers_kwarg():
+    try:
+        from inspect import signature
+        params = signature(websockets.connect).parameters
+    except Exception:
+        return "additional_headers"
+    if "additional_headers" in params:
+        return "additional_headers"
+    if "extra_headers" in params:
+        return "extra_headers"
+    return "additional_headers"
+
+
+class Gateway:
+    def __init__(self, token, intents, ws_url, dispatcher):
+        self.token = token
+        self.intents = int(intents)
+        self.ws_url = ws_url
+        self.dispatcher = dispatcher
+        self._ws = None
+        self._closed = False
+        self._heartbeat_task = None
+        self._heartbeat_interval = None
+        self._last_ack = True
+
+    async def connect(self):
+        url = f"{self.ws_url}?intents={self.intents}"
+        kwargs = {
+            _headers_kwarg(): {
+                "Authorization": f"Bot {self.token}",
+                "User-Agent": "BanterPy/0.1",
+            },
+            "ping_interval": 20,
+            "ping_timeout": 20,
+        }
+        try:
+            self._ws = await websockets.connect(url, **kwargs)
+        except Exception as e:
+            name = type(e).__name__
+            if name in ("InvalidStatus", "InvalidStatusCode"):
+                status = 0
+                resp = getattr(e, "response", None)
+                if resp is not None:
+                    status = getattr(resp, "status_code", 0)
+                if status == 0:
+                    status = getattr(e, "status_code", 0)
+                if status == 401:
+                    raise LoginFailure("invalid bot token")
+                raise GatewayError(f"connect failed: HTTP {status}")
+            raise GatewayError(f"connect failed: {e}")
+
+    async def _heartbeat_loop(self):
+        try:
+            while not self._closed:
+                await asyncio.sleep(self._heartbeat_interval / 1000)
+                if not self._last_ack:
+                    try:
+                        await self._ws.close(code=4000, reason="missed heartbeat ack")
+                    except Exception:
+                        pass
+                    return
+                self._last_ack = False
+                try:
+                    await self._ws.send(json.dumps({"op": OP_HEARTBEAT, "d": None}))
+                except Exception:
+                    return
+        except asyncio.CancelledError:
+            return
+
+    async def run(self):
+        if self._ws is None:
+            raise GatewayError("not connected")
+        try:
+            async for raw in self._ws:
+                if self._closed:
+                    return
+                try:
+                    msg = json.loads(raw)
+                except json.JSONDecodeError:
+                    continue
+
+                if isinstance(msg, dict) and "op" in msg:
+                    op = msg.get("op")
+                    if op == OP_HELLO:
+                        d = msg.get("d") or {}
+                        self._heartbeat_interval = int(d.get("heartbeat_interval", 41250))
+                        self._last_ack = True
+                        if self._heartbeat_task is None or self._heartbeat_task.done():
+                            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+                        continue
+                    if op == OP_HEARTBEAT_ACK:
+                        self._last_ack = True
+                        continue
+                    if op == OP_DISPATCH:
+                        event_type = msg.get("t") or ""
+                        payload = msg.get("d") or {}
+                        await self.dispatcher(event_type, payload)
+                        continue
+
+                event_type = msg.get("type", "")
+                payload = msg.get("payload", {})
+                await self.dispatcher(event_type, payload)
+        except websockets.exceptions.ConnectionClosed:
+            return
+
+    async def close(self):
+        self._closed = True
+        if self._heartbeat_task is not None and not self._heartbeat_task.done():
+            self._heartbeat_task.cancel()
+        if self._ws is None:
+            return
+        closed = False
+        state = getattr(self._ws, "closed", None)
+        if state is not None:
+            closed = bool(state)
+        if not closed:
+            try:
+                await self._ws.close()
+            except Exception:
+                pass

banterapi/http.py

@@ -0,0 +1,124 @@
+import asyncio
+from http import HTTPStatus
+
+import aiohttp
+
+from .errors import HTTPException, Forbidden, NotFound, RateLimited, LoginFailure
+
+
+class HTTPClient:
+    def __init__(self, token, base_url="https://banterchat.org"):
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self._session = None
+
+    async def _ensure_session(self):
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                headers={
+                    "Authorization": f"Bot {self.token}",
+                    "User-Agent": "BanterPy/0.1",
+                }
+            )
+
+    async def close(self):
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def request(self, method, path, json_body=None, params=None):
+        await self._ensure_session()
+        url = self.base_url + path
+        for attempt in range(2):
+            async with self._session.request(method, url, json=json_body, params=params) as resp:
+                if resp.status == HTTPStatus.NO_CONTENT:
+                    return None
+                text = await resp.text()
+                data = None
+                if text:
+                    try:
+                        data = await resp.json(content_type=None)
+                    except Exception:
+                        data = {"message": text}
+                if HTTPStatus.OK <= resp.status < HTTPStatus.MULTIPLE_CHOICES:
+                    return data
+                code = (data or {}).get("code", 0)
+                message = (data or {}).get("message", text or "unknown error")
+                if resp.status == HTTPStatus.TOO_MANY_REQUESTS:
+                    retry_after = float(resp.headers.get("X-RateLimit-Reset-After", "1"))
+                    if attempt == 0:
+                        await asyncio.sleep(retry_after)
+                        continue
+                    raise RateLimited(resp.status, code, message, retry_after)
+                if resp.status == HTTPStatus.UNAUTHORIZED:
+                    raise LoginFailure(message)
+                if resp.status == HTTPStatus.FORBIDDEN:
+                    raise Forbidden(resp.status, code, message)
+                if resp.status == HTTPStatus.NOT_FOUND:
+                    raise NotFound(resp.status, code, message)
+                raise HTTPException(resp.status, code, message)
+        raise HTTPException(0, 0, "request failed")
+
+    async def me(self):
+        return await self.request("GET", "/api/me")
+
+    async def get_user(self, user_id):
+        return await self.request("GET", f"/api/users/{user_id}")
+
+    async def get_guild(self, guild_id):
+        return await self.request("GET", f"/api/guilds/{guild_id}")
+
+    async def get_member(self, guild_id, user_id):
+        return await self.request("GET", f"/api/guilds/{guild_id}/members/{user_id}")
+
+    async def list_channels(self, guild_id):
+        return await self.request("GET", f"/api/guilds/{guild_id}/channels")
+
+    async def list_roles(self, guild_id):
+        return await self.request("GET", f"/api/guilds/{guild_id}/roles")
+
+    async def list_messages(self, channel_id, before="", limit=50):
+        params = {"limit": limit}
+        if before:
+            params["before"] = before
+        return await self.request("GET", f"/api/channels/{channel_id}/messages", params=params)
+
+    async def send_message(self, channel_id, content="", embed=None, reply_to=""):
+        body = {"content": content}
+        if embed is not None:
+            body["embed"] = embed.to_dict() if hasattr(embed, "to_dict") else embed
+        if reply_to:
+            body["reply_to"] = reply_to
+        return await self.request("POST", f"/api/channels/{channel_id}/messages", json_body=body)
+
+    async def edit_message(self, message_id, content):
+        return await self.request("PATCH", f"/api/messages/{message_id}", json_body={"content": content})
+
+    async def delete_message(self, message_id):
+        return await self.request("DELETE", f"/api/messages/{message_id}")
+
+    async def trigger_typing(self, channel_id):
+        return await self.request("POST", f"/api/channels/{channel_id}/typing")
+
+    async def add_reaction(self, channel_id, message_id, emoji):
+        return await self.request("PUT", f"/api/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/@me")
+
+    async def remove_reaction(self, channel_id, message_id, emoji):
+        return await self.request("DELETE", f"/api/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/@me")
+
+    async def add_role(self, guild_id, user_id, role_id):
+        return await self.request("PUT", f"/api/guilds/{guild_id}/members/{user_id}/roles/{role_id}")
+
+    async def remove_role(self, guild_id, user_id, role_id):
+        return await self.request("DELETE", f"/api/guilds/{guild_id}/members/{user_id}/roles/{role_id}")
+
+    async def kick_member(self, guild_id, user_id):
+        return await self.request("POST", f"/api/guilds/{guild_id}/members/{user_id}/kick")
+
+    async def ban_member(self, guild_id, user_id, reason=""):
+        return await self.request("POST", f"/api/guilds/{guild_id}/members/{user_id}/ban", json_body={"reason": reason})
+
+    async def unban_member(self, guild_id, user_id):
+        return await self.request("DELETE", f"/api/guilds/{guild_id}/members/{user_id}/ban")
+
+    async def register_commands(self, app_id, commands):
+        return await self.request("PUT", f"/api/applications/{app_id}/commands", json_body={"commands": commands})

banterapi/intents.py

@@ -0,0 +1,57 @@
+class Intents:
+    GUILDS = 1 << 0
+    GUILD_MEMBERS = 1 << 1
+    GUILD_MODERATION = 1 << 2
+    GUILD_PRESENCES = 1 << 3
+    GUILD_MESSAGES = 1 << 4
+    GUILD_REACTIONS = 1 << 5
+    GUILD_TYPING = 1 << 6
+    GUILD_VOICE_STATES = 1 << 7
+    DIRECT_MESSAGES = 1 << 8
+    DIRECT_REACTIONS = 1 << 9
+    DIRECT_TYPING = 1 << 10
+    MESSAGE_CONTENT = 1 << 11
+    BOT_EVENTS = 1 << 12
+
+    def __init__(self, value=0):
+        self.value = value
+
+    def __or__(self, other):
+        if isinstance(other, Intents):
+            return Intents(self.value | other.value)
+        return Intents(self.value | int(other))
+
+    def __int__(self):
+        return self.value
+
+    @classmethod
+    def default(cls):
+        return cls(
+            cls.GUILDS
+            | cls.GUILD_MESSAGES
+            | cls.GUILD_REACTIONS
+            | cls.GUILD_MEMBERS
+            | cls.BOT_EVENTS
+        )
+
+    @classmethod
+    def all(cls):
+        return cls(
+            cls.GUILDS
+            | cls.GUILD_MEMBERS
+            | cls.GUILD_MODERATION
+            | cls.GUILD_PRESENCES
+            | cls.GUILD_MESSAGES
+            | cls.GUILD_REACTIONS
+            | cls.GUILD_TYPING
+            | cls.GUILD_VOICE_STATES
+            | cls.DIRECT_MESSAGES
+            | cls.DIRECT_REACTIONS
+            | cls.DIRECT_TYPING
+            | cls.MESSAGE_CONTENT
+            | cls.BOT_EVENTS
+        )
+
+    @classmethod
+    def none(cls):
+        return cls(0)

banterapi/models.py

@@ -0,0 +1,172 @@
+import functools
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+def _requires_client(fn):
+    @functools.wraps(fn)
+    async def wrapper(self, *args, **kwargs):
+        if self._client is None:
+            raise RuntimeError(f"{type(self).__name__} detached from client")
+        return await fn(self, *args, **kwargs)
+    return wrapper
+
+
+@dataclass
+class User:
+    id: str
+    username: str
+    display_name: str = ""
+    avatar_id: str = ""
+    bot: bool = False
+
+    @classmethod
+    def from_dict(cls, d):
+        return cls(
+            id=d.get("id", ""),
+            username=d.get("username", ""),
+            display_name=d.get("display_name", ""),
+            avatar_id=d.get("avatar", "") or d.get("avatar_id", ""),
+            bot=d.get("is_bot", False) or d.get("bot", False),
+        )
+
+
+@dataclass
+class Role:
+    id: str
+    name: str
+    color: str = ""
+    position: int = 0
+    permissions: int = 0
+
+    @classmethod
+    def from_dict(cls, d):
+        return cls(
+            id=d.get("id", ""),
+            name=d.get("name", ""),
+            color=d.get("color", ""),
+            position=d.get("position", 0),
+            permissions=int(d.get("permissions", 0)),
+        )
+
+
+@dataclass
+class Channel:
+    id: str
+    name: str
+    guild_id: str = ""
+    type: str = "text"
+    description: str = ""
+
+    _client: object = field(default=None, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, d, client=None):
+        return cls(
+            id=d.get("id", ""),
+            name=d.get("name", ""),
+            guild_id=d.get("guild_id", ""),
+            type=d.get("type", "text"),
+            description=d.get("description", ""),
+            _client=client,
+        )
+
+    @_requires_client
+    async def send(self, content="", embed=None, reply_to=""):
+        return await self._client.send_message(self.id, content=content, embed=embed, reply_to=reply_to)
+
+    @_requires_client
+    async def trigger_typing(self):
+        await self._client._http.trigger_typing(self.id)
+
+
+@dataclass
+class Member:
+    user: User
+    guild_id: str
+    roles: List[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d, guild_id=""):
+        return cls(
+            user=User.from_dict(d),
+            guild_id=guild_id or d.get("guild_id", ""),
+            roles=d.get("roles", []) or [],
+        )
+
+
+@dataclass
+class Guild:
+    id: str
+    name: str
+    owner_id: str = ""
+    icon: str = ""
+    description: str = ""
+    member_count: int = 0
+
+    @classmethod
+    def from_dict(cls, d):
+        return cls(
+            id=d.get("id", ""),
+            name=d.get("name", ""),
+            owner_id=d.get("owner_id", ""),
+            icon=d.get("icon", ""),
+            description=d.get("description", ""),
+            member_count=d.get("member_count", 0),
+        )
+
+
+@dataclass
+class Message:
+    id: str
+    channel_id: str
+    user_id: str
+    content: str
+    author: Optional[User] = None
+    guild_id: str = ""
+    type: str = "message"
+    reply_to: str = ""
+    edited: bool = False
+    created_at: str = ""
+    author_perms: int = 0
+
+    _client: object = field(default=None, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, d, client=None):
+        return cls(
+            id=d.get("id", ""),
+            channel_id=d.get("channel_id", ""),
+            user_id=d.get("user_id", ""),
+            content=d.get("content", ""),
+            author=User.from_dict(d) if d.get("username") else None,
+            guild_id=d.get("guild_id", ""),
+            type=d.get("type", "message"),
+            reply_to=d.get("reply_to", ""),
+            edited=d.get("edited", False),
+            created_at=d.get("created_at", ""),
+            author_perms=int(d.get("author_perms", 0)),
+            _client=client,
+        )
+
+    @property
+    def channel(self):
+        if self._client is None:
+            raise RuntimeError("Message detached from client")
+        return Channel(id=self.channel_id, name="", guild_id=self.guild_id, _client=self._client)
+
+    @_requires_client
+    async def reply(self, content="", embed=None):
+        return await self._client.send_message(self.channel_id, content=content, embed=embed, reply_to=self.id)
+
+    @_requires_client
+    async def edit(self, content):
+        return await self._client._http.edit_message(self.id, content)
+
+    @_requires_client
+    async def delete(self):
+        return await self._client._http.delete_message(self.id)
+
+    @_requires_client
+    async def add_reaction(self, emoji):
+        return await self._client._http.add_reaction(self.channel_id, self.id, emoji)

banterapi/permissions.py

@@ -0,0 +1,50 @@
+"""Permission bits — mirror modules/permissions/perms.go exactly."""
+
+
+class Permissions:
+    SEND_MESSAGES      = 1 << 0
+    MANAGE_CHANNELS    = 1 << 1
+    MANAGE_ROLES       = 1 << 2
+    MANAGE_MESSAGES    = 1 << 3
+    ADMINISTRATOR      = 1 << 4
+    MENTION_EVERYONE   = 1 << 5
+    VIEW_CHANNELS      = 1 << 6
+    ATTACH_FILES       = 1 << 7
+    BAN_MEMBERS        = 1 << 8
+    USE_SLASH_COMMANDS = 1 << 9
+    MANAGE_GUILD       = 1 << 10
+    KICK_MEMBERS       = 1 << 11
+
+    ALL = (
+        SEND_MESSAGES | MANAGE_CHANNELS | MANAGE_ROLES | MANAGE_MESSAGES
+        | ADMINISTRATOR | MENTION_EVERYONE | VIEW_CHANNELS | ATTACH_FILES
+        | BAN_MEMBERS | USE_SLASH_COMMANDS | MANAGE_GUILD | KICK_MEMBERS
+    )
+
+
+_NAMES = {
+    Permissions.SEND_MESSAGES:      "send_messages",
+    Permissions.MANAGE_CHANNELS:    "manage_channels",
+    Permissions.MANAGE_ROLES:       "manage_roles",
+    Permissions.MANAGE_MESSAGES:    "manage_messages",
+    Permissions.ADMINISTRATOR:      "administrator",
+    Permissions.MENTION_EVERYONE:   "mention_everyone",
+    Permissions.VIEW_CHANNELS:      "view_channels",
+    Permissions.ATTACH_FILES:       "attach_files",
+    Permissions.BAN_MEMBERS:        "ban_members",
+    Permissions.USE_SLASH_COMMANDS: "use_slash_commands",
+    Permissions.MANAGE_GUILD:       "manage_guild",
+    Permissions.KICK_MEMBERS:       "kick_members",
+}
+
+
+def has_perm(bitmask, required):
+    """True if bitmask has every bit in required (or Administrator)."""
+    if bitmask & Permissions.ADMINISTRATOR:
+        return True
+    return (bitmask & required) == required
+
+
+def describe(bitmask):
+    """Return a sorted list of permission names present in a bitmask."""
+    return sorted(name for bit, name in _NAMES.items() if bitmask & bit)

banterbotapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: banterbotapi
+Version: 0.1.0
+Summary: Python SDK for building bots on Banter (banterchat.org) — discord.py-style.
+Author-email: Banter <contact@banterchat.org>
+License-Expression: MIT
+Project-URL: Homepage, https://banterchat.org
+Project-URL: Repository, https://banterchat.org
+Keywords: banter,bot,chat,sdk,discord-py-style
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: websockets>=12
+Dynamic: license-file
+
+# banterbotapi
+
+Python SDK for building bots on [Banter](https://banterchat.org).
+
+```bash
+pip install banterbotapi
+```
+
+```python
+from banterapi import Bot, Intents
+
+bot = Bot(intents=Intents.default() | Intents.MESSAGE_CONTENT)
+bot.run("YOUR_TOKEN")
+```
+
+Install name is `banterbotapi`, import name is `banterapi` (same pattern as Pillow/PIL).

banterbotapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+banterapi/__init__.py,sha256=pmeTX7WSfv8MPmmQGuQ8UUTRuRTWFSDL-JrivOHlBOI,722
+banterapi/client.py,sha256=vpOxj5TulowKEL4ECoVIs9b3S9SinEvpSBQr2fYwYhI,7307
+banterapi/commands.py,sha256=XJAyA3OFe91YQasvB05CNufuRu6KWolbRrKl5bc-TF0,5678
+banterapi/embed.py,sha256=KEBqhwQRJgqjbpnOXkeXrPz6SibIo39XrH60ZiBPDxk,1726
+banterapi/errors.py,sha256=3F39ixbGWM1jgGyKDsILtUAyTW1ecDRYQbrr4RZ5KmU,842
+banterapi/gateway.py,sha256=UfDHGhPiIn8_Bq5fn3mcPMt0ptlAGeaqFILtT-ZH8no,4560
+banterapi/http.py,sha256=19_7P86dA4t_05I1EYpy-DoNHwuX9vziLlYTF-QzlrQ,5546
+banterapi/intents.py,sha256=mKyX3xjJokfN44RCW7YtqxHdCjXfTxhmngMR8_ovqQY,1427
+banterapi/models.py,sha256=h7ZF0xT19AeG1LENDsbXID9xfaKvVZbomOFvDyX4ijA,4637
+banterapi/permissions.py,sha256=v5ejXI-WIDCFWi02lUmbgBewBOMVSblRXWrBCkIDNn4,1759
+banterbotapi-0.1.0.dist-info/licenses/LICENSE,sha256=mx5Ya5ys00JkaDHrHlsLRDbY5aVV2d7UBj6iLQiZP5E,1063
+banterbotapi-0.1.0.dist-info/METADATA,sha256=St-NcBW7pwL-uNhocG5VtuSOdFhun2E9cJ9bpQ-RwAE,1322
+banterbotapi-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+banterbotapi-0.1.0.dist-info/top_level.txt,sha256=bxmO_qHXaY7yZU8W3msDRKvPYPh__AOleanD4ci7CKs,10
+banterbotapi-0.1.0.dist-info/RECORD,,

banterbotapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

banterbotapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Banter
+
+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.

banterbotapi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+banterapi