# Python Server SDK

XuqmGroup 服务端 Python SDK，提供 IM 消息发送、群管理、Push 推送等能力。

---

## 安装

```bash
pip install xuqm-im-server-sdk
```

---

## 初始化

```python
from xuqm_im_server_sdk import XuqmImServerSdk

sdk = XuqmImServerSdk(
    base_url="https://dev.xuqinmin.com",
    app_id="your_app_id",
    app_secret="your_app_secret",
)
```

> 服务端 SDK 需要 `app_secret` 用于 HMAC 签名，`app_secret` 绝不下发到客户端。

---

## 发送消息

```python
msg = sdk.send_message(
    to_id="user_002",
    chat_type="SINGLE",
    msg_type="TEXT",
    content="Hello from Python SDK!",
)
print(f"消息已发送: {msg['id']}")
```

### 发送群消息

```python
msg = sdk.send_message(
    to_id="group_xxx",
    chat_type="GROUP",
    msg_type="TEXT",
    content="大家好",
)
```

### 撤回消息

```python
sdk.revoke_message("message_id")
```

---

## 群管理

```python
# 创建群组
group = sdk.create_group(
    name="项目讨论",
    member_ids=["user_001", "user_002"],
)

# 添加群成员
sdk.add_group_member("group_xxx", "user_003")

# 移除群成员
sdk.remove_group_member("group_xxx", "user_003")

# 获取群列表
groups = sdk.list_groups()

# 获取群成员
members = sdk.list_group_members("group_xxx")
```

---

## Push 推送

```python
sdk.send_push(
    user_id="user_001",
    title="新消息",
    body="你有一条未读消息",
    payload={"chatId": "user_002"},
)
```

---

## 错误处理

SDK 在请求失败时会抛出 `XuqmAPIError` 异常：

```python
from xuqm_im_server_sdk import XuqmAPIError

try:
    msg = sdk.send_message(to_id="user_002", chat_type="SINGLE", msg_type="TEXT", content="Hello")
except XuqmAPIError as e:
    print(f"API 错误: status={e.status}, code={e.code}, message={e.message}")
```

[→ Server API 文档 →](/server/api)