Daily build

core/api/group.py

@@ -0,0 +1,190 @@
+"""
+群组相关 API 模块
+"""
+from typing import List, Dict, Any, Optional
+from .base import BaseAPI
+from models.objects import GroupInfo, GroupMemberInfo, GroupHonorInfo
+
+
+class GroupAPI(BaseAPI):
+    """
+    群组相关 API Mixin
+    """
+
+    async def set_group_kick(self, group_id: int, user_id: int, reject_add_request: bool = False) -> Dict[str, Any]:
+        """
+        群组踢人
+
+        :param group_id: 群号
+        :param user_id: 要踢的 QQ 号
+        :param reject_add_request: 拒绝此人的加群请求
+        :return: API 响应结果
+        """
+        return await self.call_api("set_group_kick", {"group_id": group_id, "user_id": user_id, "reject_add_request": reject_add_request})
+
+    async def set_group_ban(self, group_id: int, user_id: int, duration: int = 30 * 60) -> Dict[str, Any]:
+        """
+        群组单人禁言
+
+        :param group_id: 群号
+        :param user_id: 要禁言的 QQ 号
+        :param duration: 禁言时长（秒），0 表示解除禁言
+        :return: API 响应结果
+        """
+        return await self.call_api("set_group_ban", {"group_id": group_id, "user_id": user_id, "duration": duration})
+
+    async def set_group_anonymous_ban(self, group_id: int, anonymous: Dict[str, Any] = None, duration: int = 30 * 60, flag: str = None) -> Dict[str, Any]:
+        """
+        群组匿名禁言
+
+        :param group_id: 群号
+        :param anonymous: 可选，要禁言的匿名用户对象（群消息事件的 anonymous 字段）
+        :param duration: 禁言时长（秒）
+        :param flag: 可选，要禁言的匿名用户的 flag（需从群消息事件的 anonymous 字段中获取）
+        :return: API 响应结果
+        """
+        params = {"group_id": group_id, "duration": duration}
+        if anonymous:
+            params["anonymous"] = anonymous
+        if flag:
+            params["flag"] = flag
+        return await self.call_api("set_group_anonymous_ban", params)
+
+    async def set_group_whole_ban(self, group_id: int, enable: bool = True) -> Dict[str, Any]:
+        """
+        群组全员禁言
+
+        :param group_id: 群号
+        :param enable: 是否开启
+        :return: API 响应结果
+        """
+        return await self.call_api("set_group_whole_ban", {"group_id": group_id, "enable": enable})
+
+    async def set_group_admin(self, group_id: int, user_id: int, enable: bool = True) -> Dict[str, Any]:
+        """
+        群组设置管理员
+
+        :param group_id: 群号
+        :param user_id: 要设置的 QQ 号
+        :param enable: True 为设置，False 为取消
+        :return: API 响应结果
+        """
+        return await self.call_api("set_group_admin", {"group_id": group_id, "user_id": user_id, "enable": enable})
+
+    async def set_group_anonymous(self, group_id: int, enable: bool = True) -> Dict[str, Any]:
+        """
+        群组匿名
+
+        :param group_id: 群号
+        :param enable: 是否开启
+        :return: API 响应结果
+        """
+        return await self.call_api("set_group_anonymous", {"group_id": group_id, "enable": enable})
+
+    async def set_group_card(self, group_id: int, user_id: int, card: str = "") -> Dict[str, Any]:
+        """
+        设置群名片（群备注）
+
+        :param group_id: 群号
+        :param user_id: 要设置的 QQ 号
+        :param card: 群名片内容，不填或空字符串表示删除群名片
+        :return: API 响应结果
+        """
+        return await self.call_api("set_group_card", {"group_id": group_id, "user_id": user_id, "card": card})
+
+    async def set_group_name(self, group_id: int, group_name: str) -> Dict[str, Any]:
+        """
+        设置群名
+
+        :param group_id: 群号
+        :param group_name: 新群名
+        :return: API 响应结果
+        """
+        return await self.call_api("set_group_name", {"group_id": group_id, "group_name": group_name})
+
+    async def set_group_leave(self, group_id: int, is_dismiss: bool = False) -> Dict[str, Any]:
+        """
+        退出群组
+
+        :param group_id: 群号
+        :param is_dismiss: 是否解散，如果登录号是群主，则仅在此项为 True 时能够解散
+        :return: API 响应结果
+        """
+        return await self.call_api("set_group_leave", {"group_id": group_id, "is_dismiss": is_dismiss})
+
+    async def set_group_special_title(self, group_id: int, user_id: int, special_title: str = "", duration: int = -1) -> Dict[str, Any]:
+        """
+        设置群组专属头衔
+
+        :param group_id: 群号
+        :param user_id: 要设置的 QQ 号
+        :param special_title: 专属头衔，不填或空字符串表示删除
+        :param duration: 有效期（秒），-1 表示永久
+        :return: API 响应结果
+        """
+        return await self.call_api("set_group_special_title", {"group_id": group_id, "user_id": user_id, "special_title": special_title, "duration": duration})
+
+    async def get_group_info(self, group_id: int, no_cache: bool = False) -> GroupInfo:
+        """
+        获取群信息
+
+        :param group_id: 群号
+        :param no_cache: 是否不使用缓存
+        :return: 群信息对象
+        """
+        res = await self.call_api("get_group_info", {"group_id": group_id, "no_cache": no_cache})
+        return GroupInfo(**res)
+
+    async def get_group_list(self) -> List[GroupInfo]:
+        """
+        获取群列表
+
+        :return: 群信息对象列表
+        """
+        res = await self.call_api("get_group_list")
+        return [GroupInfo(**item) for item in res]
+
+    async def get_group_member_info(self, group_id: int, user_id: int, no_cache: bool = False) -> GroupMemberInfo:
+        """
+        获取群成员信息
+
+        :param group_id: 群号
+        :param user_id: QQ 号
+        :param no_cache: 是否不使用缓存
+        :return: 群成员信息对象
+        """
+        res = await self.call_api("get_group_member_info", {"group_id": group_id, "user_id": user_id, "no_cache": no_cache})
+        return GroupMemberInfo(**res)
+
+    async def get_group_member_list(self, group_id: int) -> List[GroupMemberInfo]:
+        """
+        获取群成员列表
+
+        :param group_id: 群号
+        :return: 群成员信息对象列表
+        """
+        res = await self.call_api("get_group_member_list", {"group_id": group_id})
+        return [GroupMemberInfo(**item) for item in res]
+
+    async def get_group_honor_info(self, group_id: int, type: str) -> GroupHonorInfo:
+        """
+        获取群荣誉信息
+
+        :param group_id: 群号
+        :param type: 要获取的群荣誉类型，可传入 talkative, performer, legend, strong_newbie, emotion 等
+        :return: 群荣誉信息对象
+        """
+        res = await self.call_api("get_group_honor_info", {"group_id": group_id, "type": type})
+        return GroupHonorInfo(**res)
+
+    async def set_group_add_request(self, flag: str, sub_type: str, approve: bool = True, reason: str = "") -> Dict[str, Any]:
+        """
+        处理加群请求/邀请
+
+        :param flag: 加群请求的 flag（需从上报的数据中获取）
+        :param sub_type: add 或 invite，请求类型（需要与上报消息中的 sub_type 字段相符）
+        :param approve: 是否同意请求/邀请
+        :param reason: 拒绝理由（仅在拒绝时有效）
+        :return: API 响应结果
+        """
+        return await self.call_api("set_group_add_request", {"flag": flag, "sub_type": sub_type, "approve": approve, "reason": reason})