Metadata-Version: 2.4
Name: mecat-sdk
Version: 0.1.1
Summary: MeChat 开放世界即时通讯服务 Python SDK
Author: MeChat SDK Authors
License: MIT
Keywords: mechat,im,socketio,open-world
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Requires-Dist: python-socketio>=5.8
Provides-Extra: async
Requires-Dist: aiohttp>=3.8; extra == "async"
Provides-Extra: all
Requires-Dist: aiohttp>=3.8; extra == "all"

# mecat-sdk

MeChat 开放世界即时通讯服务 Python SDK。同步阻塞风格，基于 `requests` + `python-socketio`，
覆盖全部 REST 端点与 Socket.IO 实时事件。

- **Python ≥ 3.9**
- 双通道：REST（一次性业务）+ WebSocket（实时推送）
- 事件回调用 `@client.on("event")` 装饰器注册

## 安装

```bash
pip install mecat-sdk
# 本地开发
pip install -e .
```

## 快速上手

```python
from mecat import MecatClient

with MecatClient("http://localhost:3000") as c:
    # 注册并上线
    c.register_account("alice", "pass1234", nickname="Alice")
    c.connect_socket()

    # 也可以在注册前直接游客进入
    # c.quick_join(nickname="游客一号")

    # 订阅事件
    @c.on("new_message")
    def on_msg(data):
        print(f"{data['author']}: {data['content']}")

    c.send_message("大家好")
```

## REST 接口

| 方法 | 端点 | 描述 |
|---|---|---|
| `health()` | GET /api/health | 健康检查 |
| `register_account(u,p,...)` | POST /api/register | 注册 |
| `login(u,p)` | POST /api/login | 登录 |
| `get_users()` | GET /api/users | 在线用户（5 分钟活跃窗口） |
| `get_user(id)` | GET /api/user/:id | 用户详情 |
| `get_messages(limit,x,y,radius)` | GET /api/messages | 世界消息（服务端只回最新一页） |
| `clear_messages()` | POST /api/clear-messages | **公开无鉴权**，慎用 |

## Socket 事件

### 输入（客户端→服务端）

| 方法 | 说明 |
|---|---|
| `connect_socket(...)` / `quick_join(...)` | register（含游客、重连） |
| `move(x,y)` | 位置移动 |
| `send_message(content,x,y,friend_only)` | 世界消息 |
| `send_private_message(target,content)` | 私信（需互为好友） |
| `update_profile(...)` | 更新资料 |
| `send_friend_request / accept / reject / remove_friend` | 好友申请链 |
| `get_friends / get_pending_requests` | 列表查询 |
| `block_user / unblock_user` | 拉黑 / 解除 |
| `get_dm_history / clear_dm_history` | 私信历史 |

### 管理员事件（16 个，需要 isAdmin / isSuperAdmin）

`admin_delete_message` `admin_mute_user` `admin_unmute_user` `admin_broadcast`
`admin_kick_user` `admin_kick_guests` `admin_ban_user` `admin_unban_user`
`admin_get_user_info` `admin_clear_messages` `admin_cleanup` `admin_update_user`
`admin_set_admin` `admin_unset_admin` `admin_get_lists` `admin_get_all_users`

### 输出（服务端→客户端）

通过 `@client.on("event_name")` 订阅。常用：`registered` `new_message`
`private_message` `friend_request` `friend_accepted` `user_joined` `user_left`
`user_moved` `kicked` `banned` `admin_result` …

## 算法

`mecat.algorithms` 提供与服务端一致的实现：
`hash_password` `generate_id` `generate_session_token` `get_random_name` `get_random_color`。

## 测试

```bash
python -m pytest tests/ -v
```

`tests/test_integration.py` 会自动拉起本机 `X:\Project\Local\mecat` 服务端做联调；
可通过环境变量 `MECAT_SERVER_DIR` 指向其他路径。若未安装 Node.js，联调测试会自动 skip。
