oibot 2026.2.25__tar.gz

oibot-2026.2.25/.github/workflows/pypi.yml

@@ -0,0 +1,18 @@
+name: pypi
+
+on: push
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: actions/setup-python@master
+        with:
+          python-version: 3.x
+      - run: |
+          python -m pip install build --user
+          python -m build --sdist --wheel --outdir dist
+      - uses: pypa/gh-action-pypi-publish@master
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

oibot-2026.2.25/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: oibot
+Version: 2026.2.25
+Summary: a lightweight bot framework
+Requires-Python: >=3
+Requires-Dist: aiohttp
+Requires-Dist: cryptography
+Description-Content-Type: text/markdown
+
+# OiBot
+
+A lightweight bot framework built on [aiohttp](https://github.com/aio-libs/aiohttp) and the official protocol.

oibot-2026.2.25/README.md

@@ -0,0 +1,3 @@
+# OiBot
+
+A lightweight bot framework built on [aiohttp](https://github.com/aio-libs/aiohttp) and the official protocol.

oibot-2026.2.25/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "oibot"
+version = "2026.2.25"
+description = "a lightweight bot framework"
+readme = "README.md"
+requires-python = ">=3"
+dependencies = [
+    "aiohttp",
+    "cryptography",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

oibot-2026.2.25/src/oibot/bot.py

@@ -0,0 +1,147 @@
+import asyncio
+import logging
+from contextvars import ContextVar
+from enum import IntEnum
+from http import HTTPStatus
+from os import environ
+from typing import Any, Iterable, Literal, NamedTuple, Optional
+
+from aiohttp import ClientSession, web
+from aiohttp.web_request import Request
+from aiohttp.web_response import Response
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from oibot.mixin.access_token import AccessTokenMixin
+from oibot.mixin.recall_message import RecallMessageMixin
+from oibot.mixin.send_message import SendMessageMixin
+from oibot.mixin.upload_file import UploadFileMixin
+
+
+class OP(IntEnum):
+    MESSAGE = 0
+    VERIFICATION = 13
+
+
+class Bot(NamedTuple):
+    app_id: str
+    app_token: str
+    app_secret: str
+
+
+class Singleton(type):
+    instance: Optional["OiBot"] = None
+
+    def __call__(cls, *args, **kwargs) -> "OiBot":
+        if not (instance := cls.instance):
+            cls.instance = instance = super().__call__(*args, **kwargs)
+
+        return instance
+
+
+class OiBot(
+    AccessTokenMixin,
+    RecallMessageMixin,
+    SendMessageMixin,
+    UploadFileMixin,
+    metaclass=Singleton,
+):
+    __slots__ = ("app", "plugin_manager", "bot")
+
+    def __init__(self, plugins: str | Iterable[str] | None = None, **kwargs) -> None:
+        from oibot.plugin import PluginManager
+
+        self.plugin_manager = plugin_manager = PluginManager(self)
+
+        if isinstance(plugins, str):
+            plugin_manager.import_from(plugins)
+
+        elif isinstance(plugins, Iterable):
+            for plugin in plugins:
+                plugin_manager.import_from(plugin)
+
+        self.app = app = web.Application(**kwargs)
+
+        app.router.add_post(path="/", handler=self.handler)
+
+        self.bot: ContextVar[Bot] = ContextVar("bot")
+
+    async def __call__(
+        self,
+        method: Literal[
+            "GET",
+            "POST",
+            "PUT",
+            "DELETE",
+            "PATCH",
+            "HEAD",
+            "OPTIONS",
+            "TRACE",
+            "CONNECT",
+        ],
+        url: str,
+        **kwargs,
+    ) -> Any:
+        logging.debug(f"{method=} {url=} {kwargs=}")
+
+        async with ClientSession(
+            base_url="https://api.sgroup.qq.com",  # "https://sandbox.api.sgroup.qq.com"
+        ) as session:
+            async with session.request(method, url, **kwargs) as resp:
+                resp.raise_for_status()
+
+                return await resp.json()
+
+    async def handler(
+        self, request: Request, *, background_tasks: set[asyncio.Task] = set()
+    ) -> Response:
+        ctx = await request.json()
+
+        logging.debug(ctx)
+
+        self.bot.set(
+            bot := Bot(
+                app_id=request.query.get("id", environ["OIBOT_APP_ID"]),
+                app_token=request.query.get("token", environ["OIBOT_APP_TOKEN"]),
+                app_secret=request.query.get("secret", environ["OIBOT_APP_SECRET"]),
+            )
+        )
+
+        match ctx["op"]:
+            case OP.MESSAGE:
+                background_tasks.add(
+                    task := asyncio.create_task(self.plugin_manager(ctx))
+                )
+
+                task.add_done_callback(background_tasks.discard)
+
+            case OP.VERIFICATION:
+                logging.info("webhook verification request received")
+
+                if not (secret := bot.app_secret):
+                    raise ValueError("parameter `app_secret` must be specified")
+
+                secret = secret.encode("utf-8")
+
+                while len(secret) < 32:
+                    secret *= 2
+
+                d = ctx["d"]
+
+                return web.json_response(
+                    {
+                        "plain_token": d["plain_token"],
+                        "signature": (
+                            Ed25519PrivateKey.from_private_bytes(secret[:32])
+                            .sign(f"{d['event_ts']}{d['plain_token']}".encode("utf-8"))
+                            .hex()
+                        ),
+                    }
+                )
+
+            case _:
+                logging.warning(f"invalid type received {ctx=}")
+
+        return web.Response(body=None, status=HTTPStatus.OK)
+
+    def run(self, *args, **kwargs) -> None:
+        web.run_app(self.app, *args, **kwargs)

oibot-2026.2.25/src/oibot/event/__init__.py

@@ -0,0 +1,117 @@
+import logging
+from enum import StrEnum
+from typing import ClassVar, TypedDict
+
+from oibot.bot import OiBot
+
+
+class EventType(StrEnum):
+    AT_MESSAGE_CREATE = "AT_MESSAGE_CREATE"
+    AUDIO_FINISH = "AUDIO_FINISH"
+    AUDIO_OR_LIVE_CHANNEL_MEMBER_ENTER = "AUDIO_OR_LIVE_CHANNEL_MEMBER_ENTER"
+    AUDIO_OR_LIVE_CHANNEL_MEMBER_EXIT = "AUDIO_OR_LIVE_CHANNEL_MEMBER_EXIT"
+    AUDIO_START = "AUDIO_START"
+    C2C_MESSAGE_CREATE = "C2C_MESSAGE_CREATE"
+    C2C_MSG_RECEIVE = "C2C_MSG_RECEIVE"
+    C2C_MSG_REJECT = "C2C_MSG_REJECT"
+    CHANNEL_CREATE = "CHANNEL_CREATE"
+    CHANNEL_DELETE = "CHANNEL_DELETE"
+    CHANNEL_UPDATE = "CHANNEL_UPDATE"
+    DIRECT_MESSAGE_CREATE = "DIRECT_MESSAGE_CREATE"
+    DIRECT_MESSAGE_DELETE = "DIRECT_MESSAGE_DELETE"
+    FORUM_POST_CREATE = "FORUM_POST_CREATE"
+    FORUM_POST_DELETE = "FORUM_POST_DELETE"
+    FORUM_PUBLISH_AUDIT_RESULT = "FORUM_PUBLISH_AUDIT_RESULT"
+    FORUM_REPLY_CREATE = "FORUM_REPLY_CREATE"
+    FORUM_REPLY_DELETE = "FORUM_REPLY_DELETE"
+    FORUM_THREAD_CREATE = "FORUM_THREAD_CREATE"
+    FORUM_THREAD_DELETE = "FORUM_THREAD_DELETE"
+    FORUM_THREAD_UPDATE = "FORUM_THREAD_UPDATE"
+    FRIEND_ADD = "FRIEND_ADD"
+    FRIEND_DEL = "FRIEND_DEL"
+    GROUP_ADD_ROBOT = "GROUP_ADD_ROBOT"
+    GROUP_AT_MESSAGE_CREATE = "GROUP_AT_MESSAGE_CREATE"
+    GROUP_DEL_ROBOT = "GROUP_DEL_ROBOT"
+    GROUP_MSG_RECEIVE = "GROUP_MSG_RECEIVE"
+    GROUP_MSG_REJECT = "GROUP_MSG_REJECT"
+    GUILD_CREATE = "GUILD_CREATE"
+    GUILD_DELETE = "GUILD_DELETE"
+    GUILD_MEMBER_ADD = "GUILD_MEMBER_ADD"
+    GUILD_MEMBER_REMOVE = "GUILD_MEMBER_REMOVE"
+    GUILD_MEMBER_UPDATE = "GUILD_MEMBER_UPDATE"
+    GUILD_UPDATE = "GUILD_UPDATE"
+    INTERACTION_CREATE = "INTERACTION_CREATE"
+    MESSAGE_AUDIT_PASS = "MESSAGE_AUDIT_PASS"
+    MESSAGE_AUDIT_REJECT = "MESSAGE_AUDIT_REJECT"
+    MESSAGE_CREATE = "MESSAGE_CREATE"
+    MESSAGE_DELETE = "MESSAGE_DELETE"
+    MESSAGE_REACTION_ADD = "MESSAGE_REACTION_ADD"
+    MESSAGE_REACTION_REMOVE = "MESSAGE_REACTION_REMOVE"
+    OFF_MIC = "OFF_MIC"
+    ON_MIC = "ON_MIC"
+    OPEN_FORUM_POST_CREATE = "OPEN_FORUM_POST_CREATE"
+    OPEN_FORUM_POST_DELETE = "OPEN_FORUM_POST_DELETE"
+    OPEN_FORUM_REPLY_CREATE = "OPEN_FORUM_REPLY_CREATE"
+    OPEN_FORUM_REPLY_DELETE = "OPEN_FORUM_REPLY_DELETE"
+    OPEN_FORUM_THREAD_CREATE = "OPEN_FORUM_THREAD_CREATE"
+    OPEN_FORUM_THREAD_DELETE = "OPEN_FORUM_THREAD_DELETE"
+    OPEN_FORUM_THREAD_UPDATE = "OPEN_FORUM_THREAD_UPDATE"
+    PUBLIC_MESSAGE_DELETE = "PUBLIC_MESSAGE_DELETE"
+
+
+class Context(TypedDict):
+    d: dict
+    id: str
+    op: int
+    s: int
+    t: str
+
+
+class Event:
+    __slots__ = ("bot", "_d", "_id", "_op", "_s", "_t")
+
+    _d: dict
+    _id: str
+    _op: int
+    _s: int
+    _t: str
+
+    event_type: ClassVar[EventType]
+
+    event: ClassVar[dict[str, type["Event"]]] = {}
+
+    def __new__(cls, bot: OiBot, ctx: Context) -> "Event":
+        return (
+            event.__new__(event, bot, ctx)
+            if (event := cls.dispatch(ctx)) is not cls
+            else super().__new__(cls)
+        )
+
+    def __init__(self, bot: OiBot, ctx: Context) -> None:
+        self.bot = bot
+
+        self._d = ctx["d"]
+        self._id = ctx["id"]
+        self._op = ctx["op"]
+        # self._s = ctx["s"]
+        self._t = ctx["t"]
+
+        logging.info(self.__repr__())
+
+    def __init_subclass__(cls, *args, **kwargs) -> None:
+        logging.debug(f"registered {cls} as type {cls._t}")
+
+        Event.event[cls.event_type] = cls
+
+    def __repr__(self) -> str:
+        return f"""{self.__class__.__name__}({
+            ", ".join(
+                f"{item}={value}"
+                for item in self.__slots__
+                if (not item.startswith("__")) and (value := getattr(self, item, None))
+            )
+        })"""
+
+    @classmethod
+    def dispatch(cls, ctx: Context) -> type["Event"]:
+        return cls.event.get(ctx["t"], cls)

oibot-2026.2.25/src/oibot/event/c2c_message_create.py

@@ -0,0 +1,159 @@
+import asyncio
+from datetime import datetime
+from itertools import count
+from typing import ClassVar, Literal, NamedTuple
+
+from oibot.bot import OiBot
+from oibot.event import Context, Event
+from oibot.mixin.send_message import (
+    Ark,
+    Embed,
+    Keyboard,
+    Markdown,
+    Media,
+    MessageReference,
+    SendMessageResponse,
+)
+
+
+class C2CMessageCreateEvent(Event):
+    __slots__ = (
+        "id",
+        "content",
+        "timestamp",
+        "author",
+        "attachments",
+        "message_scene",
+        "message_type",
+        "msg_seq",
+    )
+
+    class Author(NamedTuple):
+        id: str
+        user_openid: str
+        union_openid: str
+
+    class Attachment(NamedTuple):
+        content_type: str
+        filename: str
+        height: int
+        size: int
+        url: str
+        width: int
+
+    class MessageScene(NamedTuple):
+        source: str
+        callback_data: str
+
+    event_type: ClassVar[Literal["C2C_MESSAGE_CREATE"]] = "C2C_MESSAGE_CREATE"
+
+    id: str
+    content: str
+    timestamp: datetime
+    author: Author
+    attachments: list[Attachment]
+
+    message_scene: MessageScene
+    message_type: int
+
+    def __init__(self, bot: OiBot, ctx: Context) -> None:
+        d = ctx["d"]
+
+        self.id = d["id"]
+        self.content = d["content"]
+        self.timestamp = d["timestamp"]
+
+        self.author = self.Author(
+            id=d["author"]["id"],
+            user_openid=d["author"]["user_openid"],
+            union_openid=d["author"]["union_openid"],
+        )
+
+        self.attachments = [
+            self.Attachment(
+                content_type=attachment["content_type"],
+                filename=attachment["filename"],
+                height=attachment["height"],
+                size=attachment["size"],
+                url=attachment["url"],
+                width=attachment["width"],
+            )
+            for attachment in d.get("attachments", [])
+        ]
+
+        self.message_scene = self.MessageScene(
+            source=d["message_scene"]["source"],
+            callback_data=d["message_scene"]["callback_data"],
+        )
+        self.message_type = d["message_type"]
+
+        super().__init__(bot, ctx)
+
+        self.msg_seq = count()
+
+    async def reply(
+        self,
+        content: str | None = None,
+        markdown: Markdown | None = None,
+        keyboard: Keyboard | None = None,
+        embed: Embed | None = None,
+        ark: Ark | None = None,
+        media: Media | None = None,
+        message_reference: MessageReference | None = None,
+        event_id: str | None = None,
+        msg_seq: int = 0,
+    ) -> SendMessageResponse:
+        return await self.bot.send_private_message(
+            openid=self.author.union_openid,
+            content=content,
+            markdown=markdown,
+            keyboard=keyboard,
+            embed=embed,
+            ark=ark,
+            media=media,
+            message_reference=message_reference,
+            event_id=event_id,
+            msg_id=self.id,
+            msg_seq=msg_seq or next(self.msg_seq),
+        )
+
+    async def defer(
+        self,
+        content: str | None = None,
+        markdown: Markdown | None = None,
+        keyboard: Keyboard | None = None,
+        embed: Embed | None = None,
+        ark: Ark | None = None,
+        media: Media | None = None,
+        message_reference: MessageReference | None = None,
+        event_id: str | None = None,
+        msg_seq: int = 0,
+    ) -> "C2CMessageCreateEvent":
+        self.bot.plugin_manager.sessions[
+            key := (
+                self.bot.bot.get(),
+                getattr(self, "group_openid", None),
+                (
+                    getattr(self, "author.member_openid", None)
+                    or getattr(self, "author.user_openid", None)
+                ),
+            )
+        ] = future = asyncio.get_running_loop().create_future()
+
+        await self.reply(
+            content=content,
+            markdown=markdown,
+            keyboard=keyboard,
+            embed=embed,
+            ark=ark,
+            media=media,
+            message_reference=message_reference,
+            event_id=event_id,
+            msg_seq=msg_seq,
+        )
+
+        try:
+            return await future
+
+        finally:
+            self.bot.plugin_manager.sessions.pop(key, None)

oibot-2026.2.25/src/oibot/event/friend_add.py

@@ -0,0 +1,63 @@
+from datetime import datetime
+from typing import ClassVar, Literal, NamedTuple
+
+from oibot.bot import OiBot
+from oibot.event import Context, Event
+from oibot.mixin.send_message import (
+    Ark,
+    Embed,
+    Keyboard,
+    Markdown,
+    Media,
+    MessageReference,
+    SendMessageResponse,
+)
+
+
+class FriendAddEvent(Event):
+    __slots__ = ("timestamp", "openid", "author")
+
+    class Author(NamedTuple):
+        union_openid: str
+
+    event_type: ClassVar[Literal["FRIEND_ADD"]] = "FRIEND_ADD"
+
+    timestamp: datetime
+    openid: str
+    author: Author
+
+    def __init__(self, bot: OiBot, ctx: Context) -> None:
+        d = ctx["d"]
+
+        self.timestamp = d["timestamp"]
+        self.openid = d["openid"]
+        self.author = self.Author(union_openid=d["author"]["union_openid"])
+
+        super().__init__(bot, ctx)
+
+    async def reply(
+        self,
+        content: str | None = None,
+        markdown: Markdown | None = None,
+        keyboard: Keyboard | None = None,
+        embed: Embed | None = None,
+        ark: Ark | None = None,
+        media: Media | None = None,
+        message_reference: MessageReference | None = None,
+        event_id: str | None = None,
+        msg_id: str | None = None,
+        msg_seq: int = 0,
+    ) -> SendMessageResponse:
+        return await self.bot.send_private_message(
+            openid=self.author.union_openid,
+            content=content,
+            markdown=markdown,
+            keyboard=keyboard,
+            embed=embed,
+            ark=ark,
+            media=media,
+            message_reference=message_reference,
+            event_id=event_id,
+            msg_id=msg_id,
+            msg_seq=msg_seq,
+        )

oibot-2026.2.25/src/oibot/event/friend_del.py

@@ -0,0 +1,27 @@
+from datetime import datetime
+from typing import ClassVar, Literal, NamedTuple
+
+from oibot.bot import OiBot
+from oibot.event import Context, Event
+
+
+class FriendDelEvent(Event):
+    __slots__ = ("timestamp", "openid", "author")
+
+    class Author(NamedTuple):
+        union_openid: str
+
+    event_type: ClassVar[Literal["FRIEND_DEL"]] = "FRIEND_DEL"
+
+    timestamp: datetime
+    openid: str
+    author: Author
+
+    def __init__(self, bot: OiBot, ctx: Context) -> None:
+        d = ctx["d"]
+
+        self.timestamp = d["timestamp"]
+        self.openid = d["openid"]
+        self.author = self.Author(union_openid=d["author"]["union_openid"])
+
+        super().__init__(bot, ctx)

oibot-2026.2.25/src/oibot/event/group_add_robot.py

@@ -0,0 +1,60 @@
+from datetime import datetime
+from typing import ClassVar, Literal
+
+from oibot.bot import OiBot
+from oibot.event import Context, Event
+from oibot.mixin.send_message import (
+    Ark,
+    Embed,
+    Keyboard,
+    Markdown,
+    Media,
+    MessageReference,
+    SendMessageResponse,
+)
+
+
+class GroupAddRobotEvent(Event):
+    __slots__ = ("timestamp", "group_openid", "op_member_openid")
+
+    event_type: ClassVar[Literal["GROUP_ADD_ROBOT"]] = "GROUP_ADD_ROBOT"
+
+    timestamp: datetime
+    group_openid: str
+    op_member_openid: str
+
+    def __init__(self, bot: OiBot, ctx: Context) -> None:
+        d = ctx["d"]
+
+        self.timestamp = d["timestamp"]
+        self.group_openid = d["group_openid"]
+        self.op_member_openid = d["op_member_openid"]
+
+        super().__init__(bot, ctx)
+
+    async def reply(
+        self,
+        content: str | None = None,
+        markdown: Markdown | None = None,
+        keyboard: Keyboard | None = None,
+        embed: Embed | None = None,
+        ark: Ark | None = None,
+        media: Media | None = None,
+        message_reference: MessageReference | None = None,
+        event_id: str | None = None,
+        msg_id: str | None = None,
+        msg_seq: int = 0,
+    ) -> SendMessageResponse:
+        return await self.bot.send_group_message(
+            group_openid=self.group_openid,
+            content=content,
+            markdown=markdown,
+            keyboard=keyboard,
+            embed=embed,
+            ark=ark,
+            media=media,
+            message_reference=message_reference,
+            event_id=event_id,
+            msg_id=msg_id,
+            msg_seq=msg_seq,
+        )