Metadata-Version: 2.4
Name: wpsbot
Version: 0.3.1
Summary: WPS 365 开放平台 Python SDK —— OAuth2 登录 + 应用机器人消息发送
Author: wpsbot contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/wpsbot/wpsbot
Project-URL: Repository, https://github.com/wpsbot/wpsbot
Keywords: wps,wps365,oauth2,bot,messaging,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20
Dynamic: license-file

# wpsbot

WPS 365 开放平台 Python SDK —— OAuth2 登录 + 应用机器人消息发送 + 通讯录查询

## 安装

```bash
pip install wpsbot
```

## 快速开始

### 1. 发送消息

```python
from wpsbot.msg import WpsMsgSender

s = WpsMsgSender(
    client_id="YOUR_CLIENT_ID",        # 必填：应用的 client_id
    client_secret="YOUR_CLIENT_SECRET", # 必填：应用的 client_secret
)

# 发群聊消息
s.chat.send_text("群聊ID", "你好")
s.chat.send_markdown("群聊ID", "## 标题\n- 列表项")

# 发个人消息
s.user.send_text("用户ID", "你好")
s.user.send_markdown("用户ID", "## 标题\n- 列表项")
```

### 2. 发送图片和文件

```python
# 发送本地图片（自动读取尺寸和 MIME 类型）
s.chat.send_local_image("群聊ID", "./截图.png")
s.user.send_local_image("用户ID", "./截图.png")

# 发送本地文件
s.chat.send_local_file("群聊ID", "./报表.xlsx")
s.user.send_local_file("用户ID", "./报表.xlsx")
```

### 3. 查询用户信息

```python
# 按姓名搜索用户
users = s.search_users("张三")
# → [{'id': 'AbCdEf', 'user_name': '张三', 'def_dept_name': '技术部'}, ...]

# 带完整信息（岗位、部门路径、工号）
users = s.search_users("张三", with_detail=True)
# → [{'id': 'AbCdEf', 'user_name': '张三', 'title': '高级工程师',
#     'def_dept_name': '技术部', 'employee_id': '10001',
#     'depts': [{'name': '技术部', 'abs_path': '公司/技术部'}]}, ...]

# 获取应用可见范围内的所有用户（需要 kso.app.read 权限）
users = s.get_app_users()
# → [{'id': 'AbCdEf', 'name': '张三', 'user_name': '张三', 'type': 'user'}, ...]

# 带完整信息
users = s.get_app_users(with_detail=True)

# 查询单个用户详情
info = s.get_user_by_id("AbCdEf", with_dept=True)
# → {'user_name': '张三', 'title': '高级工程师', 'depts': [...], ...}
```

### 4. 获取群聊信息

```python
# 获取机器人所在群聊列表
chats = s.get_chats()
# → [{'id': '12345678', 'name': '项目群'}, ...]

# 获取群成员
members = s.get_chat_members_with_names("群聊ID")
# → [{'letter_id': 'AbCdEf', 'name': '张三', 'num_id': '10001'}, ...]
```

## API 参考

### WpsMsgSender

| 方法 | 说明 | 权限要求 |
|------|------|----------|
| `chat.send_text(receiver_id, text)` | 发送文本消息到群聊 | kso.message.send |
| `chat.send_markdown(receiver_id, markdown)` | 发送 Markdown 消息到群聊 | kso.message.send |
| `chat.send_local_image(receiver_id, path)` | 发送本地图片到群聊 | kso.message.send |
| `chat.send_local_file(receiver_id, path)` | 发送本地文件到群聊 | kso.message.send |
| `user.send_text(receiver_id, text)` | 发送文本消息到个人 | kso.message.send |
| `user.send_markdown(receiver_id, markdown)` | 发送 Markdown 消息到个人 | kso.message.send |
| `user.send_local_image(receiver_id, path)` | 发送本地图片到个人 | kso.message.send |
| `user.send_local_file(receiver_id, path)` | 发送本地文件到个人 | kso.message.send |
| `search_users(keyword, with_detail=False)` | 按姓名搜索用户 | kso.contact.read |
| `get_app_users(with_detail=False)` | 获取应用可见范围用户 | kso.app.read |
| `get_user_by_id(user_id, with_dept=False)` | 查询单个用户详情 | kso.contact.read |
| `get_chats()` | 获取机器人所在群聊列表 | kso.chat.read |
| `get_chat_members_with_names(chat_id)` | 获取群成员列表 | kso.chat.read |
| `upload_file(path)` | 上传文件，返回 storage_key | kso.message.send |

### WpsBot（OAuth2 登录）

```python
from wpsbot.client import WpsBot

bot = WpsBot(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    redirect_uri="YOUR_REDIRECT_URI",
)

# 获取授权 URL
auth_url = bot.build_authorize_url()

# 用户授权后，用 code 换取 token
token = bot.exchange_code(code)

# 获取用户信息
user_info = bot.fetch_complete_user()
```

## 权限申请

在 [WPS 开放平台](https://open.wps.cn) 开发者后台申请以下权限：

| 权限 | 作用 |
|------|------|
| `kso.message.send` | 发送消息 |
| `kso.contact.read` | 查询通讯录（搜索用户、查询用户详情） |
| `kso.app.read` | 查询应用信息（获取应用可见范围用户） |
| `kso.chat.read` | 查询群聊信息 |

## 注意事项

- **receiver_id 类型**：
  - `chat.send_*` 方法：receiver_id 为群聊 ID（可为纯数字，如 `12345678`）
  - `user.send_*` 方法：receiver_id 为用户字母 ID（形如 `AbCdEf`）
- ⚠️ 金山文档个人中心的数字账号 ID（如 `1602884839`）不是有效 user_id，会导致错误
- 应用机器人只能给**应用可见范围内**的用户发送消息

## License

Apache-2.0
