perk-pushplus-sdk 1.2.0__tar.gz → 1.2.2__tar.gz

{perk_pushplus_sdk-1.2.0 → perk_pushplus_sdk-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: perk-pushplus-sdk
-Version: 1.2.0
+Version: 1.2.2
 Summary: pushplus(推送加) 官方接口的 Python SDK，覆盖消息发送接口与全部开放接口。
 Author: perk-net
 License: Apache-2.0
@@ -35,7 +35,7 @@ Requires-Dist: responses>=0.23; extra == "dev"
 [pushplus(推送加)](https://www.pushplus.plus) 官方接口的 Python SDK，覆盖 **消息接口** 与 **全部开放接口**。
 
 - **消息接口**（`/send`、`/batchSend`）：单渠道 + 多渠道发送，含 Builder API。
-- **开放接口**（`/api/open/...` 与 `/push/api/open/...`）：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、功能设置、预处理信息、图片服务、push 表单、push 文档、push 表格。
+- **开放接口**（`/api/open/...` 与 `/push/api/open/...`）：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、QQ 机器人、功能设置、预处理信息、图片服务、push 表单、push 文档、push 表格。
 - **AccessKey 自动管理**：缓存 + 过期前自动刷新；`code=401` 自动刷新并重试一次。
 - **本地限流守卫**：命中 `code=900` 后按 token 短路同 token 后续发送，避免被服务端长期封禁。
 - **回调解析**：`message_complate`、`add_topic_user`、`add_friend` 三类回调统一解析。
@@ -91,7 +91,7 @@ short_code = client.send(
     .build()
 )
 
-# push 表单：template=form 时需传 pushId（表单编码）
+# push 表单 / 文档 / 表格：template 为 form/doc/excel 时需传 pushId（对应编码）
 short_code = client.send(
     SendRequest.builder()
     .title("表单通知")
@@ -100,6 +100,22 @@ short_code = client.send(
     .push_id("表单编码")
     .build()
 )
+short_code = client.send(
+    SendRequest.builder()
+    .title("本周工作同步")
+    .content("请查收")
+    .template(Template.DOC)
+    .push_id("文档编码")
+    .build()
+)
+short_code = client.send(
+    SendRequest.builder()
+    .title("销售日报")
+    .content("请查收")
+    .template(Template.EXCEL)
+    .push_id("表格编码")
+    .build()
+)
 ```
 
 ### 3. 多渠道发送
@@ -141,12 +157,31 @@ topics = client.topic.list(TopicListQuery.of(1, 20, topic_type=0))
 detail = client.topic.detail(topic_id=123)
 
 # 好友
+from perk_pushplus import PageQuery, TopicUserListQuery
 qr = client.friend.get_qr_code(content="welcome")
 friends = client.friend.list()
+client.friend.add_blacklist(friends.list[0].friendId)
+friend_blacklist = client.friend.blacklist_list(PageQuery.of(1, 20))
+client.topic_user.add_blacklist(topic_relation_id=10)
+topic_blacklist = client.topic_user.blacklist_list(TopicUserListQuery.of(1, 20, topic_id=1))
 
 # webhook 渠道
 webhooks = client.webhook.list()
 
+# QQ 机器人：绑定 -> 认领群 -> 建配置 -> 发到群
+from perk_pushplus import QqBotSaveRequest
+link = client.qq_bot.get_bind_link()   # link.url 生成二维码，或私聊发送 link.bindCode
+bind = client.qq_bot.bot_info()        # bind.isBind == 1 表示已绑定
+qq_groups = client.qq_bot.group_list()
+client.qq_bot.add(QqBotSaveRequest(qqName="运维告警群", qqCode="ops-group", qqGroupId=qq_groups[0].id))
+client.send(SendRequest(
+    title="服务告警",
+    content="订单服务响应超时",
+    channel=Channel.QQ,
+    option="ops-group",  # 不传 option 则发给自己
+    template=Template.TXT,
+))
+
 # 设置
 client.setting.change_is_send(1)  # 启用发送
 
@@ -169,17 +204,34 @@ client.form.save(FormSaveRequest(
 ))
 published = client.form.publish(form.id)
 print(published.fillUrl)
+client.send(SendRequest(
+    title=published.title,
+    content="请花1分钟完成填写",
+    template=Template.FORM,
+    pushId=published.formCode,
+))
 
 # push 文档
-doc = client.doc.create("本周工作同步")
-client.doc.save_content(doc.docCode, "<h1>本周工作同步</h1><p>需求评审。</p>")
+doc = client.doc.import_word("本周工作同步.docx")
 client.doc.update_share(doc.docCode, 1, 0)
 client.doc.publish(doc.docCode)
+client.send(SendRequest(
+    title=doc.title,
+    content="请查收",
+    template=Template.DOC,
+    pushId=doc.docCode,
+))
 
 # push 表格
-sheet = client.excel.create("销售日报")
+sheet = client.excel.import_excel("销售日报.xlsx")
 client.excel.write_cells(sheet.docCode, "A1", [["日期", "销售额"], ["2026-08-13", 12800]], "Sheet1")
 client.excel.publish(sheet.docCode)
+client.send(SendRequest(
+    title=sheet.title,
+    content="请查收",
+    template=Template.EXCEL,
+    pushId=sheet.docCode,
+))
 ```
 
 ### 图片服务

{perk_pushplus_sdk-1.2.0 → perk_pushplus_sdk-1.2.2}/README.md

@@ -3,7 +3,7 @@
 [pushplus(推送加)](https://www.pushplus.plus) 官方接口的 Python SDK，覆盖 **消息接口** 与 **全部开放接口**。
 
 - **消息接口**（`/send`、`/batchSend`）：单渠道 + 多渠道发送，含 Builder API。
-- **开放接口**（`/api/open/...` 与 `/push/api/open/...`）：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、功能设置、预处理信息、图片服务、push 表单、push 文档、push 表格。
+- **开放接口**（`/api/open/...` 与 `/push/api/open/...`）：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、QQ 机器人、功能设置、预处理信息、图片服务、push 表单、push 文档、push 表格。
 - **AccessKey 自动管理**：缓存 + 过期前自动刷新；`code=401` 自动刷新并重试一次。
 - **本地限流守卫**：命中 `code=900` 后按 token 短路同 token 后续发送，避免被服务端长期封禁。
 - **回调解析**：`message_complate`、`add_topic_user`、`add_friend` 三类回调统一解析。
@@ -59,7 +59,7 @@ short_code = client.send(
     .build()
 )
 
-# push 表单：template=form 时需传 pushId（表单编码）
+# push 表单 / 文档 / 表格：template 为 form/doc/excel 时需传 pushId（对应编码）
 short_code = client.send(
     SendRequest.builder()
     .title("表单通知")
@@ -68,6 +68,22 @@ short_code = client.send(
     .push_id("表单编码")
     .build()
 )
+short_code = client.send(
+    SendRequest.builder()
+    .title("本周工作同步")
+    .content("请查收")
+    .template(Template.DOC)
+    .push_id("文档编码")
+    .build()
+)
+short_code = client.send(
+    SendRequest.builder()
+    .title("销售日报")
+    .content("请查收")
+    .template(Template.EXCEL)
+    .push_id("表格编码")
+    .build()
+)
 ```
 
 ### 3. 多渠道发送
@@ -109,12 +125,31 @@ topics = client.topic.list(TopicListQuery.of(1, 20, topic_type=0))
 detail = client.topic.detail(topic_id=123)
 
 # 好友
+from perk_pushplus import PageQuery, TopicUserListQuery
 qr = client.friend.get_qr_code(content="welcome")
 friends = client.friend.list()
+client.friend.add_blacklist(friends.list[0].friendId)
+friend_blacklist = client.friend.blacklist_list(PageQuery.of(1, 20))
+client.topic_user.add_blacklist(topic_relation_id=10)
+topic_blacklist = client.topic_user.blacklist_list(TopicUserListQuery.of(1, 20, topic_id=1))
 
 # webhook 渠道
 webhooks = client.webhook.list()
 
+# QQ 机器人：绑定 -> 认领群 -> 建配置 -> 发到群
+from perk_pushplus import QqBotSaveRequest
+link = client.qq_bot.get_bind_link()   # link.url 生成二维码，或私聊发送 link.bindCode
+bind = client.qq_bot.bot_info()        # bind.isBind == 1 表示已绑定
+qq_groups = client.qq_bot.group_list()
+client.qq_bot.add(QqBotSaveRequest(qqName="运维告警群", qqCode="ops-group", qqGroupId=qq_groups[0].id))
+client.send(SendRequest(
+    title="服务告警",
+    content="订单服务响应超时",
+    channel=Channel.QQ,
+    option="ops-group",  # 不传 option 则发给自己
+    template=Template.TXT,
+))
+
 # 设置
 client.setting.change_is_send(1)  # 启用发送
 
@@ -137,17 +172,34 @@ client.form.save(FormSaveRequest(
 ))
 published = client.form.publish(form.id)
 print(published.fillUrl)
+client.send(SendRequest(
+    title=published.title,
+    content="请花1分钟完成填写",
+    template=Template.FORM,
+    pushId=published.formCode,
+))
 
 # push 文档
-doc = client.doc.create("本周工作同步")
-client.doc.save_content(doc.docCode, "<h1>本周工作同步</h1><p>需求评审。</p>")
+doc = client.doc.import_word("本周工作同步.docx")
 client.doc.update_share(doc.docCode, 1, 0)
 client.doc.publish(doc.docCode)
+client.send(SendRequest(
+    title=doc.title,
+    content="请查收",
+    template=Template.DOC,
+    pushId=doc.docCode,
+))
 
 # push 表格
-sheet = client.excel.create("销售日报")
+sheet = client.excel.import_excel("销售日报.xlsx")
 client.excel.write_cells(sheet.docCode, "A1", [["日期", "销售额"], ["2026-08-13", 12800]], "Sheet1")
 client.excel.publish(sheet.docCode)
+client.send(SendRequest(
+    title=sheet.title,
+    content="请查收",
+    template=Template.EXCEL,
+    pushId=sheet.docCode,
+))
 ```
 
 ### 图片服务

{perk_pushplus_sdk-1.2.0 → perk_pushplus_sdk-1.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "perk-pushplus-sdk"
-version = "1.2.0"
+version = "1.2.2"
 description = "pushplus(推送加) 官方接口的 Python SDK，覆盖消息发送接口与全部开放接口。"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.8"

{perk_pushplus_sdk-1.2.0 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/__init__.py

@@ -65,6 +65,7 @@ from .models import (
     FormTheme,
     FriendItem,
     FriendQrCode,
+    FriendBlacklistItem,
     ImageItem,
     ImageUploadResult,
     ImageUploadToken,
@@ -83,6 +84,12 @@ from .models import (
     PreItem,
     PreSaveRequest,
     PreTestRequest,
+    QqBotBindInfo,
+    QqBotBindLink,
+    QqBotInfo,
+    QqBotItem,
+    QqBotSaveRequest,
+    QqGroupItem,
     SendCount,
     SendMessageResult,
     SendRequest,
@@ -95,6 +102,7 @@ from .models import (
     TopicUserInfo,
     TopicUserItem,
     TopicUserListQuery,
+    TopicUserBlacklistItem,
     UserDefaultDetail,
     UserDefaultItem,
     UserDefaultSaveRequest,
@@ -106,7 +114,7 @@ from .models import (
 )
 from .rate_limit import RateLimitGuard
 
-__version__ = "1.2.0"
+__version__ = "1.2.2"
 
 __all__ = [
     "__version__",
@@ -158,10 +166,12 @@ __all__ = [
     "TopicListQuery",
     "TopicUserListQuery",
     "TopicUserItem",
+    "TopicUserBlacklistItem",
     "TopicAddRequest",
     "TopicEditRequest",
     "FriendItem",
     "FriendQrCode",
+    "FriendBlacklistItem",
     "WebhookItem",
     "WebhookSaveRequest",
     "MpItem",
@@ -171,6 +181,12 @@ __all__ = [
     "ClawBotQrCode",
     "ClawBotInfo",
     "ClawBotMessage",
+    "QqBotBindLink",
+    "QqBotInfo",
+    "QqBotBindInfo",
+    "QqGroupItem",
+    "QqBotItem",
+    "QqBotSaveRequest",
     "UserDefaultItem",
     "UserDefaultDetail",
     "UserDefaultSaveRequest",

{perk_pushplus_sdk-1.2.0 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/api/__init__.py

@@ -12,6 +12,7 @@ from .message import MessageApi
 from .message_token import MessageTokenApi
 from .open_message import OpenMessageApi
 from .pre import PreApi
+from .qqbot import QqBotApi
 from .setting import SettingApi
 from .topic import TopicApi
 from .topic_user import TopicUserApi
@@ -32,6 +33,7 @@ __all__ = [
     "WebhookApi",
     "ChannelApi",
     "ClawBotApi",
+    "QqBotApi",
     "SettingApi",
     "PreApi",
     "ImageApi",

{perk_pushplus_sdk-1.2.0 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/api/base.py

@@ -7,7 +7,7 @@ from urllib.parse import quote
 
 from ..config import PushPlusConfig
 from ..exceptions import PushPlusError
-from ..http import HttpRequester, to_json
+from ..http import HttpRequester, call_execute_raw, to_json
 from ..models.base import ApiResponse, model_from_dict, model_to_dict
 
 if TYPE_CHECKING:
@@ -83,6 +83,25 @@ class AbstractApi:
             )
         return self._parse_api_response(resp.body, data_type)
 
+    def execute_raw(
+        self,
+        method: str,
+        path: str,
+        headers: Optional[Dict[str, str]],
+        body: Optional[bytes],
+        data_type: Optional[Type[T]] = None,
+    ) -> ApiResponse[T]:
+        """执行带二进制请求体的请求并返回原始 :class:`ApiResponse`。"""
+
+        url = self.resolve_url(path)
+        resp = call_execute_raw(self.http, method, url, headers, body)
+        if not resp.is_successful:
+            raise PushPlusError(
+                f"PushPlus 接口 HTTP 调用失败: status={resp.status_code}, body={resp.body}",
+                code=resp.status_code,
+            )
+        return self._parse_api_response(resp.body, data_type)
+
     def execute_for_data(
         self,
         method: str,
@@ -206,5 +225,50 @@ class OpenAbstractApi(AbstractApi):
             code=resp.code if resp.code is not None else -1,
         )
 
+    def execute_open_multipart(
+        self,
+        path: str,
+        content_type: str,
+        body: bytes,
+        data_type: Optional[Type[T]] = None,
+    ) -> Optional[T]:
+        """以 multipart 上传文件（自动携带 access-key；code=401 时刷新后重试一次）。"""
+
+        extra = {"Content-Type": content_type}
+        return self.execute_open_raw("POST", path, extra, body, data_type)
+
+    def execute_open_raw(
+        self,
+        method: str,
+        path: str,
+        extra_headers: Optional[Dict[str, str]],
+        body: Optional[bytes],
+        data_type: Optional[Type[T]] = None,
+    ) -> Optional[T]:
+        """执行带二进制 body 的开放接口请求；当返回 ``code=401`` 时自动刷新 key 并重试一次。"""
+
+        headers = self._headers_with_access_key()
+        if extra_headers:
+            headers.update(extra_headers)
+        resp = self.execute_raw(method, path, headers, body, data_type)
+        if resp.is_success():
+            return resp.data
+        if resp.code is not None and int(resp.code) == _CODE_ACCESS_KEY_INVALID:
+            self.access_key_manager.invalidate()
+            retry_headers = self._headers_with_access_key()
+            if extra_headers:
+                retry_headers.update(extra_headers)
+            retry = self.execute_raw(method, path, retry_headers, body, data_type)
+            if retry.is_success():
+                return retry.data
+            raise PushPlusError(
+                f"PushPlus 开放接口业务失败(重试后): code={retry.code}, msg={retry.msg}",
+                code=retry.code if retry.code is not None else -1,
+            )
+        raise PushPlusError(
+            f"PushPlus 开放接口业务失败: code={resp.code}, msg={resp.msg}",
+            code=resp.code if resp.code is not None else -1,
+        )
+
 
 __all__ = ["AbstractApi", "OpenAbstractApi", "HEADER_ACCESS_KEY"]

{perk_pushplus_sdk-1.2.0 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/api/doc.py

@@ -1,9 +1,15 @@
-"""开放接口 - push 文档（文档：https://www.pushplus.plus/doc/ecosystem/doc/）。"""
+"""开放接口 - push 文档（文档：https://www.pushplus.plus/doc/ecosystem/doc/）。
+
+文档开放接口不单独提供推送接口。发布后请通过 :class:`~perk_pushplus.api.message.MessageApi`
+推送分享页：``template=doc``，``pushId=docCode``。
+"""
 from __future__ import annotations
 
-from typing import Optional
+from pathlib import Path
+from typing import Optional, Union
 
 from ..models import DocContent, DocListItem, DocListQuery, DocVo, PageResult
+from ..multipart import build_file_multipart
 from .base import OpenAbstractApi
 
 
@@ -22,6 +28,17 @@ class DocApi(OpenAbstractApi):
 
         return self.execute_open("POST", "/push/api/open/doc/create", {"title": title}, DocVo)
 
+    def import_word(self, file: Union[str, Path, bytes], file_name: Optional[str] = None) -> DocVo:
+        """导入 Word（``.docx``）创建文档。
+
+        标题默认取文件名；创建后默认关闭分享，需再调用 :meth:`publish` 才会同步到分享页。
+        ``file`` 可为路径或文件字节。
+        """
+
+        data, name = _read_upload_file(file, file_name, "document.docx")
+        content_type, body = build_file_multipart(name, _guess_docx_content_type(name), data)
+        return self.execute_open_multipart("/push/api/open/doc/import", content_type, body, DocVo)
+
     def content(self, doc_code: str) -> DocContent:
         """获取文档元信息与 HTML 草稿正文。"""
 
@@ -67,4 +84,22 @@ class DocApi(OpenAbstractApi):
         return self.execute_open("POST", "/push/api/open/doc/updateShare", body, DocVo)
 
 
+def _read_upload_file(
+    file: Union[str, Path, bytes], file_name: Optional[str], default_name: str
+) -> tuple:
+    if isinstance(file, bytes):
+        name = file_name or default_name
+        return file, name
+    path = Path(file)
+    data = path.read_bytes()
+    name = file_name or path.name or default_name
+    return data, name
+
+
+def _guess_docx_content_type(name: str) -> str:
+    if name.lower().endswith(".docx"):
+        return "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+    return "application/octet-stream"
+
+
 __all__ = ["DocApi"]

{perk_pushplus_sdk-1.2.0 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/api/excel.py

@@ -1,10 +1,16 @@
-"""开放接口 - push 表格（文档：https://www.pushplus.plus/doc/ecosystem/sheet/）。"""
+"""开放接口 - push 表格（文档：https://www.pushplus.plus/doc/ecosystem/sheet/）。
+
+表格开放接口不单独提供推送接口。发布后请通过 :class:`~perk_pushplus.api.message.MessageApi`
+推送分享页：``template=excel``，``pushId=docCode``。
+"""
 from __future__ import annotations
 
 import json
-from typing import Any, Optional, Sequence
+from pathlib import Path
+from typing import Any, Optional, Sequence, Union
 
 from ..models import DocListItem, DocListQuery, ExcelContent, ExcelVo, PageResult
+from ..multipart import build_file_multipart
 from .base import OpenAbstractApi
 
 
@@ -25,6 +31,20 @@ class ExcelApi(OpenAbstractApi):
             "POST", "/push/api/open/excel/create", {"title": title}, ExcelVo
         )
 
+    def import_excel(
+        self, file: Union[str, Path, bytes], file_name: Optional[str] = None
+    ) -> ExcelVo:
+        """导入 Excel（``.xlsx`` / ``.xls``）创建表格。
+
+        标题默认取文件名；创建后默认关闭分享，需再调用 :meth:`publish` 才会同步到分享页。
+        """
+
+        data, name = _read_upload_file(file, file_name, "workbook.xlsx")
+        content_type, body = build_file_multipart(name, _guess_excel_content_type(name), data)
+        return self.execute_open_multipart(
+            "/push/api/open/excel/import", content_type, body, ExcelVo
+        )
+
     def content(self, doc_code: str) -> ExcelContent:
         """获取表格元信息与整表 JSON 草稿。"""
 
@@ -93,4 +113,25 @@ def _as_json_string(content: Any) -> str:
     return json.dumps(content, ensure_ascii=False)
 
 
+def _read_upload_file(
+    file: Union[str, Path, bytes], file_name: Optional[str], default_name: str
+) -> tuple:
+    if isinstance(file, bytes):
+        name = file_name or default_name
+        return file, name
+    path = Path(file)
+    data = path.read_bytes()
+    name = file_name or path.name or default_name
+    return data, name
+
+
+def _guess_excel_content_type(name: str) -> str:
+    lower = name.lower()
+    if lower.endswith(".xlsx"):
+        return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    if lower.endswith(".xls"):
+        return "application/vnd.ms-excel"
+    return "application/octet-stream"
+
+
 __all__ = ["ExcelApi"]

{perk_pushplus_sdk-1.2.0 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/api/form.py

@@ -1,4 +1,8 @@
-"""开放接口 - push 表单（文档：https://www.pushplus.plus/doc/ecosystem/form/）。"""
+"""开放接口 - push 表单（文档：https://www.pushplus.plus/doc/ecosystem/form/）。
+
+表单开放接口不单独提供推送接口。发布后请通过 :class:`~perk_pushplus.api.message.MessageApi`
+推送填写页：``template=form``，``pushId=formCode``。
+"""
 from __future__ import annotations
 
 from typing import Optional

{perk_pushplus_sdk-1.2.0 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/api/friend.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 from typing import Optional
 
-from ..models import FriendItem, FriendQrCode, PageQuery, PageResult
+from ..models import FriendBlacklistItem, FriendItem, FriendQrCode, PageQuery, PageResult
 from .base import OpenAbstractApi
 
 
@@ -54,5 +54,36 @@ class FriendApi(OpenAbstractApi):
         body = {"id": int(id_), "remark": remark}
         self.execute_open("POST", "/api/open/friend/editRemark", body, None)
 
+    def add_blacklist(self, friend_id: int) -> None:
+        """将好友加入黑名单。
+
+        加入后将解除双方好友关系，对方无法再添加你。不能将自己加入黑名单，仅可将已有好友加入黑名单。
+        """
+
+        path = self.append_query(
+            "/api/open/friend/addBlacklist", {"friendId": int(friend_id)}
+        )
+        self.execute_open("POST", path, None, None)
+
+    def blacklist_list(
+        self, query: Optional[PageQuery] = None
+    ) -> PageResult[FriendBlacklistItem]:
+        """好友黑名单列表。"""
+
+        body = query if query is not None else PageQuery()
+        result = self.execute_open(
+            "POST", "/api/open/friend/blacklistList", body, PageResult[FriendBlacklistItem]
+        )
+        return result or PageResult(list=[])
+
+    def remove_blacklist(self, id_: int) -> None:
+        """解除好友黑名单。
+
+        解除后不会自动恢复好友关系，需重新扫码添加。
+        """
+
+        path = self.append_query("/api/open/friend/removeBlacklist", {"id": int(id_)})
+        self.execute_open("POST", path, None, None)
+
 
 __all__ = ["FriendApi"]

perk_pushplus_sdk-1.2.2/src/perk_pushplus/api/qqbot.py

@@ -0,0 +1,89 @@
+"""开放接口 - QQ 机器人（文档「九. QQ机器人接口」）。"""
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import List, Optional
+
+from ..models import (
+    PageQuery,
+    PageResult,
+    QqBotBindInfo,
+    QqBotBindLink,
+    QqBotItem,
+    QqBotSaveRequest,
+    QqGroupItem,
+)
+from .base import OpenAbstractApi
+
+SEND_TYPE_QQ_GROUP = 2
+"""发送到 QQ 群，目前渠道配置仅支持该类型。"""
+
+
+class QqBotApi(OpenAbstractApi):
+    """QQ 机器人绑定与渠道配置相关接口。"""
+
+    def get_bind_link(self, refresh: bool = False) -> QqBotBindLink:
+        """获取绑定链接与绑定码；``refresh=True`` 时旧绑定码失效并重新生成。"""
+
+        path = "/api/open/qqBot/getBindLink"
+        if refresh:
+            path = self.append_query(path, {"refresh": "true"})
+        return self.execute_open("GET", path, None, QqBotBindLink)
+
+    def bot_info(self) -> QqBotBindInfo:
+        """查询绑定状态。"""
+
+        return self.execute_open(
+            "GET", "/api/open/qqBot/botInfo", None, QqBotBindInfo
+        )
+
+    def unbind(self) -> None:
+        """解绑 QQ 机器人。"""
+
+        self.execute_open("GET", "/api/open/qqBot/unbind", None, None)
+
+    def group_list(self) -> List[QqGroupItem]:
+        """获取机器人已加入的 QQ 群列表。"""
+
+        result = self.execute_open(
+            "GET", "/api/open/qqBot/groupList", None, List[QqGroupItem]
+        )
+        return result or []
+
+    def list(self, query: Optional[PageQuery] = None) -> PageResult[QqBotItem]:
+        """获取 QQ 机器人渠道配置列表。"""
+
+        body = query if query is not None else PageQuery()
+        result = self.execute_open(
+            "POST", "/api/open/qqBot/list", body, PageResult[QqBotItem]
+        )
+        return result or PageResult(list=[])
+
+    def add(self, request: QqBotSaveRequest) -> None:
+        """新增渠道配置，用于把消息发送到指定 QQ 群；发给自己无需创建配置。"""
+
+        self.execute_open(
+            "POST", "/api/open/qqBot/add", _with_default_send_type(request), None
+        )
+
+    def edit(self, request: QqBotSaveRequest) -> None:
+        """修改渠道配置；配置编码不可修改。"""
+
+        self.execute_open(
+            "POST", "/api/open/qqBot/edit", _with_default_send_type(request), None
+        )
+
+    def delete(self, config_id: int) -> None:
+        """删除渠道配置。"""
+
+        path = self.append_query("/api/open/qqBot/delete", {"id": int(config_id)})
+        self.execute_open("DELETE", path, None, None)
+
+
+def _with_default_send_type(request: QqBotSaveRequest) -> QqBotSaveRequest:
+    if request is None or request.sendType is not None:
+        return request
+    return replace(request, sendType=SEND_TYPE_QQ_GROUP)
+
+
+__all__ = ["QqBotApi", "SEND_TYPE_QQ_GROUP"]