pyyapper 1.0.0__py3-none-any.whl

pyyapper/bot.py

@@ -0,0 +1,769 @@
+"""The :class:`Bot` class - the heart of PyYapper."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import re
+from typing import Any, Callable, Optional
+
+from .errors import ConfigurationError, Unauthorized
+from .http import HTTPClient, _backoff
+from .models import (
+    Category,
+    Channel,
+    Member,
+    Message,
+    Role,
+    Server,
+    User,
+)
+from .embeds import Embed
+from .buttons import Button, Row
+
+# Event names that are valid.
+EVENTS = {
+    "message", "command", "member_join", "member_leave",
+    "reaction_add", "reaction_remove", "interaction", "test",
+    "ready", "error",
+}
+
+# Helper to coerce embeds/buttons to dicts.
+def _plain(x: Any) -> Any:
+    if hasattr(x, "to_dict"):
+        return x.to_dict()
+    if hasattr(x, "toJSON"):
+        return x.toJSON()
+    return x
+
+
+def _list(v: Any) -> Any:
+    if v is None:
+        return None
+    if isinstance(v, (list, tuple)):
+        return [_plain(x) for x in v]
+    return [_plain(v)]
+
+
+class Context:
+    """Wraps a message event, adding helpers like ``reply`` / ``say``.
+
+    A ``Context`` is what command callbacks and ``on_message`` handlers receive.
+    """
+
+    def __init__(self, bot: "Bot", data: dict[str, Any]) -> None:
+        self._bot = bot
+        self.raw = dict(data)
+        self.id = data.get("id", "")
+        self.channel_id = data.get("channel_id")
+        self.channel_name = data.get("channel_name")
+        self.server_id = data.get("server_id")
+        self.author_id = data.get("author_id", "")
+        self.author = data.get("author")
+        self.content = data.get("content", "") or ""
+        self.attachment = data.get("attachment")
+        self.reply_to_id = data.get("reply_to_id")
+        self.created_at = data.get("created_at")
+        self.mentioned = bool(data.get("mentioned", False))
+        # command info (filled in by Bot.handle for commands)
+        self.command: Optional[str] = data.get("command")
+        self.args: str = data.get("args") or ""
+        self.argv: list[str] = self.args.split() if self.args else []
+        # message model
+        self.message = Message.from_dict(data)
+
+    @property
+    def author_mention(self) -> str:
+        return f"<@{self.author_id}>"
+
+    async def reply(self, content: Any = "", **opts: Any) -> Any:
+        return await self._bot.send(
+            self.channel_id, content, reply_to=self.id, **opts
+        )
+
+    async def say(self, content: Any = "", **opts: Any) -> Any:
+        return await self._bot.send(self.channel_id, content, **opts)
+
+    def __repr__(self) -> str:
+        return f"Context(id={self.id!r}, author={self.author!r})"
+
+
+class InteractionContext:
+    """Wraps a button-click (interaction) event."""
+
+    def __init__(self, bot: "Bot", data: dict[str, Any]) -> None:
+        self._bot = bot
+        self.raw = dict(data)
+        self.id = data.get("id", "")
+        self.token = data.get("token", "")
+        self.type = data.get("type", "button")
+        self.custom_id = data.get("custom_id", "")
+        self.message_id = data.get("message_id")
+        self.channel_id = data.get("channel_id")
+        self.server_id = data.get("server_id")
+        self.user_id = data.get("user_id", "")
+        self.username = data.get("username", "")
+        self.expires_at = data.get("expires_at")
+
+    @property
+    def user_mention(self) -> str:
+        return f"<@{self.user_id}>"
+
+    async def respond(self, kind: str, **opts: Any) -> Any:
+        body: dict[str, Any] = {"type": kind}
+        if "content" in opts and opts["content"] is not None:
+            body["content"] = "" if opts["content"] is None else str(opts["content"])
+        if "embeds" in opts:
+            body["embeds"] = _list(opts["embeds"])
+        if "components" in opts:
+            body["components"] = _list(opts["components"])
+        # allow passing content positionally via first kw
+        return await self._bot.api(
+            "POST", f"/interactions/{self.id}/{self.token}/callback", body
+        )
+
+    async def reply(self, content: Any = "", **opts: Any) -> Any:
+        return await self.respond("reply", content=content, **opts)
+
+    async def ephemeral(self, content: Any = "", **opts: Any) -> Any:
+        return await self.respond("ephemeral", content=content, **opts)
+
+    async def update(self, changes: Any = None, **kw: Any) -> Any:
+        if isinstance(changes, dict):
+            kw = {**changes, **kw}
+            changes = None
+        body = {"type": "update"}
+        if "content" in kw:
+            c = kw.pop("content")
+            body["content"] = None if c is None else str(c)
+        if "embeds" in kw:
+            body["embeds"] = _list(kw.pop("embeds"))
+        if "components" in kw:
+            body["components"] = _list(kw.pop("components"))
+        for k, v in kw.items():
+            body[k] = v
+        return await self._bot.api(
+            "POST", f"/interactions/{self.id}/{self.token}/callback", body
+        )
+
+    async def ack(self) -> Any:
+        return await self.respond("ack")
+
+    def __repr__(self) -> str:
+        return f"InteractionContext(custom_id={self.custom_id!r}, user={self.username!r})"
+
+
+class Bot:
+    """A Yapper bot.
+
+    Parameters
+    ----------
+    token:
+        Bot token (starts with ``yb_``).
+    base_url:
+        Override the API base URL.
+    prefixes:
+        Command prefixes in addition to slash commands. Defaults to ``['/', '!']``.
+    log:
+        Whether to print log lines. Defaults to ``True``.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = "https://www.yapper.website/api/bot/v1",
+        prefixes: Optional[list[str]] = None,
+        log: bool = True,
+    ) -> None:
+        self.token = str(token).strip() if token else ""
+        self.base_url = base_url
+        self.prefixes = prefixes if prefixes is not None else ["/", "!"]
+        self.log = log
+
+        self.http = HTTPClient(self.token, base_url=base_url, log=log)
+        # convenience: keep .api working
+        self.handlers: dict[str, list[Callable]] = {}
+        self.commands: dict[str, dict[str, Any]] = {}
+        self.buttons: list[dict[str, Any]] = []
+        self.last: int = 0
+        self.running: bool = False
+        self.me: Optional[User] = None
+        self._task: Optional[asyncio.Task] = None
+
+        # Lazy validation happens in start(); keep construction permissive for tests.
+
+    # ------------------------------------------------------------------ #
+    # Registration
+    # ------------------------------------------------------------------ #
+    def on(self, event: str, fn: Optional[Callable] = None) -> Any:
+        """Register an event handler.
+
+        Can be used as a decorator::
+
+            @bot.on("message")
+            async def handle(msg):
+                ...
+
+        or directly::
+
+            bot.on("message", handle)
+        """
+        if event not in EVENTS:
+            raise ValueError(f"Unknown event {event!r}. Valid: {sorted(EVENTS)}")
+        if fn is None:
+            def decorator(f: Callable) -> Callable:
+                self.handlers.setdefault(event, []).append(f)
+                return f
+            return decorator
+        self.handlers.setdefault(event, []).append(fn)
+        return fn
+
+    def event(self, fn: Optional[Callable] = None) -> Any:
+        """Decorator that registers a handler based on its name.
+
+        The function name must start with ``on_`` (e.g. ``on_ready``,
+        ``on_message``). The remainder is used as the event name, with
+        underscores accepted (``on_member_join`` -> ``member_join``).
+        """
+        def _register(f):
+            name = f.__name__
+            if not name.startswith("on_"):
+                raise ValueError("event handler name must start with 'on_'")
+            event = name[3:]
+            if event not in EVENTS:
+                raise ValueError(f"Unknown event {event!r}")
+            self.handlers.setdefault(event, []).append(f)
+            return f
+        if fn is None:
+            return _register
+        return _register(fn)
+
+    def command(
+        self,
+        name: Any = None,
+        description: Any = "",
+        fn: Optional[Callable] = None,
+        *,
+        aliases: Optional[list[str]] = None,
+    ) -> Any:
+        """Register a slash/prefix command.
+
+        Decorator form::
+
+            @bot.command("ping", description="Is the bot alive?")
+            async def ping(ctx):
+                await ctx.reply("pong")
+
+        Direct form::
+
+            bot.command("ping", "Is the bot alive?", handler)
+        """
+        # Bare decorator usage: bot.command(fn)
+        if callable(name) and description == "" and fn is None:
+            f = name
+            name = f.__name__
+
+            def _reg0():
+                clean = str(name).lower().lstrip("/!").strip()
+                if not re.fullmatch(r"[a-z0-9_-]{1,32}", clean):
+                    raise ValueError(f'Bad command name "{name}": letters, numbers, - and _ only')
+                self.commands[clean] = {"description": "", "fn": f}
+            _reg0()
+            return f
+
+        # Resolve when description is actually the handler
+        if callable(description) and fn is None:
+            fn = description
+            description = ""
+
+        def _register(n, d, f):
+            clean = f.__name__.lower().lstrip("/!").strip() if n is None else str(n).lower().lstrip("/!").strip()
+            if not re.fullmatch(r"[a-z0-9_-]{1,32}", clean):
+                raise ValueError(f'Bad command name "{n}": letters, numbers, - and _ only')
+            self.commands[clean] = {"description": str(d or "")[:100], "fn": f}
+            for a in (aliases or []):
+                self.commands[str(a).lower().lstrip("/!").strip()] = {
+                    "description": str(d or "")[:100], "fn": f,
+                }
+            return f
+
+        if fn is not None:
+            return _register(name, description, fn)
+
+        desc = description
+
+        def decorator(f: Callable) -> Callable:
+            n = name if name is not None else f.__name__
+            return _register(n, desc, f)
+
+        return decorator
+
+    def button(self, match: Any, fn: Optional[Callable] = None) -> Any:
+        """Register a handler for button clicks.
+
+        ``match`` can be a string (exact custom_id) or a compiled/str regex.
+        Decorator form supported.
+        """
+        import re as _re
+
+        # Bare decorator: bot.button(fn) with no match -> match everything
+        if callable(match) and fn is None:
+            f = match
+            matcher = _re.compile(".*")
+
+            def _reg():
+                self.buttons.append({"match": matcher, "fn": f})
+            _reg()
+            return f
+
+        if isinstance(match, str):
+            # Allow "/pattern/" or "re:pattern" to mean regex
+            s = match
+            if s.startswith("/") and s.endswith("/") and len(s) > 2:
+                matcher = _re.compile(s[1:-1])
+            elif s.startswith("re:"):
+                matcher = _re.compile(s[3:])
+            else:
+                matcher = s
+        elif hasattr(match, "pattern"):
+            matcher = match
+        else:
+            matcher = _re.compile(str(match))
+
+        if fn is None:
+            def decorator(f: Callable) -> Callable:
+                self.buttons.append({"match": matcher, "fn": f})
+                return f
+            return decorator
+        self.buttons.append({"match": matcher, "fn": fn})
+        return fn
+
+    on_button = button  # alias
+
+    # ------------------------------------------------------------------ #
+    # HTTP shortcuts
+    # ------------------------------------------------------------------ #
+    async def api(self, method: str, path: str, body: Any = None, **kw: Any) -> Any:
+        return await self.http.request(method, path, body=body, **kw)
+
+    # ------------------------------------------------------------------ #
+    # Messaging
+    # ------------------------------------------------------------------ #
+    async def send(
+        self,
+        channel_id: Any,
+        content: Any = "",
+        *,
+        reply_to: Optional[str] = None,
+        embeds: Any = None,
+        components: Any = None,
+        **opts: Any,
+    ) -> Any:
+        body: dict[str, Any] = {"content": "" if content is None else str(content)}
+        if reply_to is not None:
+            body["reply_to"] = reply_to
+        if embeds is not None:
+            body["embeds"] = _list(embeds)
+        if components is not None:
+            body["components"] = _list(components)
+        # merge opts
+        for k, v in opts.items():
+            if k in ("embeds", "components"):
+                body[k] = _list(v)
+            else:
+                body[k] = v
+        out = await self.api("POST", f"/channels/{channel_id}/messages", body)
+        msg = out.get("message") if isinstance(out, dict) else None
+        return msg if msg is not None else out
+
+    def send_embed(self, channel_id: Any, embed: Any, content: str = "") -> Any:
+        return self.send(channel_id, content, embeds=[embed])
+
+    async def delete(self, channel_id: Any, message_id: Any) -> Any:
+        return await self.api("DELETE", f"/channels/{channel_id}/messages/{message_id}")
+
+    # ------------------------------------------------------------------ #
+    # Servers / channels / members
+    # ------------------------------------------------------------------ #
+    async def servers(self) -> list[Server]:
+        out = await self.api("GET", "/servers")
+        return [Server.from_dict(s) for s in (out.get("servers") or [])]
+
+    async def channels(self, server_id: Any = None, *, type: Optional[str] = None) -> list[Channel]:
+        q = f"?type={type}" if type else ""
+        path = f"/servers/{server_id}/channels{q}" if server_id else f"/channels{q}"
+        out = await self.api("GET", path)
+        return [Channel.from_dict(c) for c in (out.get("channels") or [])]
+
+    async def categories(self, server_id: Any) -> list[Category]:
+        out = await self.api("GET", f"/servers/{server_id}/channels")
+        return [Category.from_dict(c) for c in (out.get("categories") or [])]
+
+    async def channel(self, channel_id: Any) -> Optional[Channel]:
+        try:
+            out = await self.api("GET", f"/channels/{channel_id}")
+        except Exception:
+            return None
+        c = out.get("channel") if isinstance(out, dict) else None
+        return Channel.from_dict(c) if c else None
+
+    async def members(self, server_id: Any, after: Any = None) -> list[Member]:
+        path = f"/servers/{server_id}/members?limit=200"
+        if after:
+            path += f"&after={after}"
+        out = await self.api("GET", path)
+        return [Member.from_dict(m) for m in (out.get("members") or [])]
+
+    async def messages(self, channel_id: Any, limit: int = 50) -> list[Message]:
+        out = await self.api("GET", f"/channels/{channel_id}/messages?limit={limit}")
+        return [Message.from_dict(m) for m in (out.get("messages") or [])]
+
+    async def user(self, user_id: Any) -> User:
+        out = await self.api("GET", f"/users/{user_id}")
+        u = out.get("user") if isinstance(out, dict) else out
+        return User.from_dict(u)
+
+    # ------------------------------------------------------------------ #
+    # Profile
+    # ------------------------------------------------------------------ #
+    async def set_avatar(self, image: Any, type: Optional[str] = None) -> Any:
+        return await self.http.upload("PUT", "/me/avatar", image, type)
+
+    async def set_profile(self, *, display_name: Optional[str] = None, bio: Optional[str] = None) -> Any:
+        body: dict[str, Any] = {}
+        if display_name is not None:
+            body["display_name"] = display_name
+        if bio is not None:
+            body["bio"] = bio
+        return await self.api("PATCH", "/me", body)
+
+    async def set_banner(self, image: Any, type: Optional[str] = None) -> Any:
+        return await self.http.upload("PUT", "/me/banner", image, type)
+
+    async def set_status(self, status: str = "online", activity: Optional[str] = None) -> Any:
+        return await self.api("PUT", "/me/status", {"status": status, "activity": activity})
+
+    # ------------------------------------------------------------------ #
+    # Messages advanced
+    # ------------------------------------------------------------------ #
+    async def edit(
+        self,
+        channel_id: Any,
+        message_id: Any,
+        content: Any = None,
+        *,
+        embeds: Any = None,
+        components: Any = None,
+    ) -> Any:
+        body: dict[str, Any] = {}
+        if content is not None:
+            body["content"] = str(content)
+        if embeds is not None:
+            body["embeds"] = _list(embeds)
+        if components is not None:
+            body["components"] = _list(components)
+        out = await self.api("PATCH", f"/channels/{channel_id}/messages/{message_id}", body)
+        return out.get("message") if isinstance(out, dict) else out
+
+    async def message(self, channel_id: Any, message_id: Any) -> Any:
+        return await self.api("GET", f"/channels/{channel_id}/messages/{message_id}")
+
+    async def messages_after(self, channel_id: Any, after: Any, limit: int = 50) -> list[Message]:
+        if hasattr(after, "isoformat"):
+            ts = after.isoformat()
+        else:
+            ts = str(after)
+        from urllib.parse import quote
+        out = await self.api(
+            "GET", f"/channels/{channel_id}/messages?limit={limit}&after={quote(ts, safe='')}"
+        )
+        return [Message.from_dict(m) for m in (out.get("messages") or [])]
+
+    async def bulk_delete(self, channel_id: Any, message_ids: Any) -> Any:
+        return await self.api("POST", f"/channels/{channel_id}/messages/bulk-delete", {"ids": list(message_ids)})
+
+    async def pin(self, channel_id: Any, message_id: Any) -> Any:
+        return await self.api("PUT", f"/channels/{channel_id}/messages/{message_id}/pin")
+
+    async def unpin(self, channel_id: Any, message_id: Any) -> Any:
+        return await self.api("DELETE", f"/channels/{channel_id}/messages/{message_id}/pin")
+
+    async def react(self, channel_id: Any, message_id: Any, emoji: str) -> Any:
+        from urllib.parse import quote
+        return await self.api("PUT", f"/channels/{channel_id}/messages/{message_id}/reactions/{quote(emoji, safe='')}")
+
+    async def unreact(self, channel_id: Any, message_id: Any, emoji: str) -> Any:
+        from urllib.parse import quote
+        return await self.api("DELETE", f"/channels/{channel_id}/messages/{message_id}/reactions/{quote(emoji, safe='')}")
+
+    async def reactions(self, channel_id: Any, message_id: Any) -> Any:
+        out = await self.api("GET", f"/channels/{channel_id}/messages/{message_id}/reactions")
+        return out.get("reactions") if isinstance(out, dict) else out
+
+    # ------------------------------------------------------------------ #
+    # Moderation
+    # ------------------------------------------------------------------ #
+    async def server(self, server_id: Any) -> Any:
+        out = await self.api("GET", f"/servers/{server_id}")
+        return out.get("server") if isinstance(out, dict) else out
+
+    async def roles(self, server_id: Any) -> list[Role]:
+        out = await self.api("GET", f"/servers/{server_id}/roles")
+        return [Role.from_dict(r) for r in (out.get("roles") or [])]
+
+    async def member(self, server_id: Any, user_id: Any) -> Member:
+        out = await self.api("GET", f"/servers/{server_id}/members/{user_id}")
+        m = out.get("member") if isinstance(out, dict) else out
+        return Member.from_dict(m)
+
+    async def add_role(self, server_id: Any, user_id: Any, role_id: Any) -> Any:
+        return await self.api("PUT", f"/servers/{server_id}/members/{user_id}/roles/{role_id}")
+
+    async def remove_role(self, server_id: Any, user_id: Any, role_id: Any) -> Any:
+        return await self.api("DELETE", f"/servers/{server_id}/members/{user_id}/roles/{role_id}")
+
+    async def set_nickname(self, server_id: Any, user_id: Any, nickname: str) -> Any:
+        return await self.api("PATCH", f"/servers/{server_id}/members/{user_id}", {"nickname": nickname})
+
+    async def kick(self, server_id: Any, user_id: Any) -> Any:
+        return await self.api("POST", f"/servers/{server_id}/kick", {"user_id": user_id})
+
+    async def ban(self, server_id: Any, user_id: Any) -> Any:
+        return await self.api("POST", f"/servers/{server_id}/bans", {"user_id": user_id})
+
+    async def unban(self, server_id: Any, user_id: Any) -> Any:
+        return await self.api("DELETE", f"/servers/{server_id}/bans/{user_id}")
+
+    async def bans(self, server_id: Any) -> Any:
+        out = await self.api("GET", f"/servers/{server_id}/bans")
+        return out.get("bans") if isinstance(out, dict) else out
+
+    async def timeout(self, server_id: Any, user_id: Any, minutes: int, reason: str = "") -> Any:
+        return await self.api("POST", f"/servers/{server_id}/timeouts", {
+            "user_id": user_id, "minutes": minutes, "reason": reason,
+        })
+
+    # ------------------------------------------------------------------ #
+    # Channels management
+    # ------------------------------------------------------------------ #
+    async def create_channel(self, server_id: Any, name: str, *, kind: str = "text", category_id: Any = None) -> Any:
+        out = await self.api("POST", f"/servers/{server_id}/channels", {
+            "name": name, "kind": kind, "category_id": category_id,
+        })
+        return out.get("channel") if isinstance(out, dict) else out
+
+    async def edit_channel(self, channel_id: Any, **changes: Any) -> Any:
+        body: dict[str, Any] = {}
+        mapping = {
+            "name": "name",
+            "category_id": "category_id",
+            "categoryId": "category_id",
+            "private": "private",
+            "role_ids": "role_ids",
+            "roleIds": "role_ids",
+            "read_only": "read_only",
+            "readOnly": "read_only",
+            "post_role_ids": "post_role_ids",
+            "postRoleIds": "post_role_ids",
+            "slowmode": "slowmode",
+        }
+        for k, v in changes.items():
+            key = mapping.get(k, k)
+            body[key] = v
+        out = await self.api("PATCH", f"/channels/{channel_id}", body)
+        return out.get("channel") if isinstance(out, dict) else out
+
+    async def delete_channel(self, channel_id: Any) -> Any:
+        return await self.api("DELETE", f"/channels/{channel_id}")
+
+    async def create_category(self, server_id: Any, name: str) -> Any:
+        out = await self.api("POST", f"/servers/{server_id}/categories", {"name": name})
+        return out.get("category") if isinstance(out, dict) else out
+
+    async def delete_category(self, server_id: Any, category_id: Any) -> Any:
+        return await self.api("DELETE", f"/servers/{server_id}/categories/{category_id}")
+
+    # ------------------------------------------------------------------ #
+    # DMs
+    # ------------------------------------------------------------------ #
+    async def dm(self, user_id: Any) -> Any:
+        out = await self.api("POST", f"/users/{user_id}/dm")
+        return out.get("channel_id") if isinstance(out, dict) else out
+
+    async def dm_send(self, user_id: Any, content: Any = "", **opts: Any) -> Any:
+        cid = await self.dm(user_id)
+        return await self.send(cid, content, **opts)
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle
+    # ------------------------------------------------------------------ #
+    async def _start(self) -> None:
+        if self.running:
+            return
+        if not self.token.startswith("yb_"):
+            raise ConfigurationError("Pass your bot token (starts with yb_). Get one in Settings -> Developer.")
+        # Catch obvious placeholders early with a helpful message instead of a 401.
+        if ("..." in self.token) or len(self.token) < 20 or self.token.lower() in {"yb_", "yb_your_token", "yb_your_token_here"}:
+            raise ConfigurationError(
+                "That looks like a placeholder token, not a real one. "
+                "Create a bot in Yapper -> Settings -> Developer, copy the token "
+                "(shown once), and paste it in place of \"yb_...\"."
+            )
+        self.running = True
+        if self.log:
+            print("[pyyapper] connecting…")
+
+        # startup with retries
+        cmd_list = [{"name": n, "description": c.get("description", "")} for n, c in self.commands.items()]
+        for attempt in range(1, 100):
+            try:
+                self.me = User.from_dict(await self.api("GET", "/me"))
+                await self.api("PUT", "/commands", {"commands": cmd_list})
+                first = await self.api("GET", "/events?after=0&wait=0")
+                break
+            except Exception as e:
+                status = getattr(e, "status", None)
+                if status in (401, 400, 403):
+                    self.running = False
+                    raise
+                await self._fail(e)
+                await asyncio.sleep(_backoff(attempt))
+                if not self.running:
+                    return
+        else:
+            self.running = False
+            return
+
+        self.last = first.get("last", 0) if isinstance(first, dict) else 0
+        if self.log:
+            print(f"[pyyapper] {self.me.username} is online"
+                  + (f" with {len(cmd_list)} command{'s' if len(cmd_list) != 1 else ''}" if cmd_list else ""))
+        await self._emit("ready", self.me)
+
+        failures = 0
+        while self.running:
+            try:
+                out = await self.api("GET", f"/events?after={self.last}&wait=25", timeout=45.0)
+                failures = 0
+            except Exception as e:
+                failures += 1
+                status = getattr(e, "status", None)
+                if status == 401:
+                    await self._fail(Exception("Token rejected: make a new one in Settings -> Developer"))
+                    self.running = False
+                    break
+                await self._fail(e)
+                wait = getattr(e, "retry_after", None)
+                await asyncio.sleep(wait if wait else _backoff(failures))
+                continue
+            events = out.get("events", []) if isinstance(out, dict) else []
+            for ev in events:
+                eid = ev.get("id", 0)
+                if not (eid > self.last):
+                    continue
+                self.last = eid
+                await self._handle(ev)
+            last = out.get("last") if isinstance(out, dict) else None
+            if isinstance(last, int) and last > self.last:
+                self.last = last
+
+        await self.http.close()
+
+    async def start(self) -> None:
+        try:
+            await self._start()
+        finally:
+            await self.http.close()
+            self.running = False
+
+    def run(self) -> None:
+        """Synchronous entry point: ``bot.run()``."""
+        try:
+            asyncio.run(self.start())
+        except KeyboardInterrupt:
+            self.running = False
+
+    def stop(self) -> None:
+        self.running = False
+
+    # ------------------------------------------------------------------ #
+    # Internals
+    # ------------------------------------------------------------------ #
+    async def _emit(self, event: str, payload: Any) -> None:
+        for fn in list(self.handlers.get(event, [])):
+            try:
+                if asyncio.iscoroutinefunction(fn):
+                    await fn(payload)
+                else:
+                    fn(payload)
+            except Exception as e:  # noqa: BLE001
+                await self._fail(e)
+
+    async def _fail(self, e: Exception) -> None:
+        if self.handlers.get("error"):
+            await self._emit("error", e)
+        elif self.log:
+            print("[pyyapper]", getattr(e, "message", None) or str(e))
+
+    async def _handle(self, ev: dict[str, Any]) -> None:
+        etype = ev.get("type")
+        data = ev.get("data") or {}
+        if etype == "message":
+            ctx = Context(self, data)
+            # resolve command
+            name = data.get("command")
+            args = data.get("args")
+            if not name:
+                content = data.get("content", "") or ""
+                m = re.match(r"^(\S)([a-z0-9_-]{1,32})(?:\s+([\s\S]*))?$", content, re.IGNORECASE)
+                if m and m.group(1) in self.prefixes and m.group(2).lower() in self.commands:
+                    name = m.group(2).lower()
+                    args = (m.group(3) or "").strip()
+            if name and name in self.commands:
+                ctx.command = name
+                ctx.args = args or ""
+                ctx.argv = ctx.args.split() if ctx.args else []
+                cmd = self.commands[name]
+                try:
+                    res = cmd["fn"](ctx)
+                    if asyncio.iscoroutine(res):
+                        await res
+                except Exception as e:  # noqa: BLE001
+                    await self._fail(e)
+                await self._emit("command", ctx)
+            await self._emit("message", ctx)
+        elif etype == "interaction":
+            ic = InteractionContext(self, data)
+            for b in self.buttons:
+                match = b["match"]
+                hit = False
+                if isinstance(match, str):
+                    hit = match == data.get("custom_id")
+                elif hasattr(match, "pattern"):
+                    hit = bool(match.search(data.get("custom_id", "")))
+                elif hasattr(match, "test"):
+                    # compiled regex in JS style; python re has search/match
+                    try:
+                        hit = bool(match.search(data.get("custom_id", "")))
+                    except Exception:
+                        hit = match == data.get("custom_id")
+                else:
+                    hit = match == data.get("custom_id")
+                if hit:
+                    try:
+                        res = b["fn"](ic)
+                        if asyncio.iscoroutine(res):
+                            await res
+                    except Exception as e:  # noqa: BLE001
+                        await self._fail(e)
+            await self._emit("interaction", ic)
+        else:
+            payload = dict(data)
+            payload.setdefault("type", etype)
+            await self._emit(etype, payload)
+
+    # allow attribute-style access for embed/button classes
+    Embed = Embed
+    Button = Button
+    Row = Row