Metadata-Version: 2.4
Name: wps-webhook-bot
Version: 0.1.1
Summary: WPS 协作（xz.wps.cn）群机器人 Webhook 通知 SDK，支持文本 / Markdown / 卡片三种消息格式
Author-email: wps-webhook-bot developers <wps-webhook-bot@example.com>
License: MIT
Project-URL: Documentation, http://open.wps.cn/documents/app-integration-dev/guide/robot/webhook
Keywords: wps,webhook,bot,robot,notification,协作机器人
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20
Dynamic: license-file

# wps-webhook-bot

WPS 协作（xz.wps.cn）群机器人 Webhook 通知 SDK，支持 **文本 / Markdown / 卡片** 三种消息格式。

协议参考：[WPS 开放平台 - webhook 机器人](http://open.wps.cn/documents/app-integration-dev/guide/robot/webhook)

## 安装

```bash
pip install wps-webhook-bot
```

## 快速开始

在 WPS 协作群聊中添加自定义机器人，复制 Webhook 地址（形如 `https://xz.wps.cn/api/v1/webhook/send?key=xxxx`），然后：

```python
from wps_webhook_bot import WebhookBot

bot = WebhookBot("https://xz.wps.cn/api/v1/webhook/send?key=YOUR_KEY")

# 1. 文本消息（支持 @ 指定成员 / 所有人）
bot.send_text("部署完成", at_all=True)
bot.send_text("请查收报告", at_user_ids=["17856"], at_emails=["somebody@wps.cn"])

# 2. Markdown 消息（标题/加粗/引用/颜色/链接）
bot.send_markdown(
    "### 构建通知\n"
    "> 分支：main\n\n"
    "状态：<font color='#07C160'>成功</font>  "
    "[查看详情](https://xz.wps.cn)"
)

# 3. 卡片消息（主/副标题 + 组件 + 整卡跳转）
bot.send_card(
    title="nightly 构建 #123 完成",
    subtitle="2026-08-26",
    elements=[
        WebhookBot.text_element("**通过率**：<font color='#07C160'>100%</font>"),
        WebhookBot.hr_element(),
        WebhookBot.text_element("耗时：3 分 25 秒", markdown=False),
    ],
    link="https://xz.wps.cn",
)
```

## API 一览

| 方法 | 说明 |
|---|---|
| `send_text(content, at_user_ids=None, at_emails=None, at_all=False)` | 文本消息，支持 `<at>` 标签 @ 人 |
| `send_markdown(text, at_user_ids=None, at_emails=None, at_all=False)` | Markdown 消息 |
| `send_card(title, subtitle="", elements=None, link="", pc_url="", ios_url="", android_url="")` | 卡片消息，支持分端跳转链接 |
| `WebhookBot.text_element(text, markdown=True)` | 构造卡片文本组件 |
| `WebhookBot.hr_element()` | 构造卡片分割线组件 |

发送失败会抛出 `WebhookBotError`，异常信息中包含服务端返回内容，便于排查。

## Markdown 语法子集

标题（`#` ~ `######`）、加粗（`**`）、斜体（`*` / `_`）、引用（`>`）、链接（`[文字](url)`）、
颜色（`<font color='#FF0000'>文字</font>`）、@人（`<at user_id="12345">姓名</at>`）。
换行使用「双空格 + `\n`」或「`\n\n`」。

## 平台限制

- 每个机器人发送频率不超过 **20 条/分钟**
- 每条消息不超过 **5000 个字符**
- 卡片组件总数不超过 20 个；Webhook 卡片暂不支持回传型交互组件（回传按钮、列表选择器、日期选择器、输入框）

## License

MIT
