Metadata-Version: 2.4
Name: wechat-ilink-bot
Version: 0.1.0
Summary: Python SDK for WeChat iLink Bot API — send and receive WeChat messages programmatically.
Project-URL: Homepage, https://github.com/hkslover/wechat-ilink-bot
Project-URL: Repository, https://github.com/hkslover/wechat-ilink-bot
Project-URL: Issues, https://github.com/hkslover/wechat-ilink-bot/issues
Project-URL: Documentation, https://wechat-ilink-bot.readthedocs.io/en/latest/
Project-URL: Changelog, https://github.com/hkslover/wechat-ilink-bot/blob/main/CHANGELOG.md
Author: hkslover
License-Expression: MIT
License-File: LICENSE
Keywords: bot,ilink,sdk,wechat,weixin
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: fastapi>=0.111; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocs>=1.6; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pymdown-extensions>=10.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Requires-Dist: uvicorn>=0.30; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.8; extra == 'docs'
Provides-Extra: qrcode
Requires-Dist: qrcode[pil]; extra == 'qrcode'
Provides-Extra: socks
Requires-Dist: httpx[socks]; extra == 'socks'
Provides-Extra: webhook
Requires-Dist: fastapi>=0.111; extra == 'webhook'
Requires-Dist: uvicorn>=0.30; extra == 'webhook'
Description-Content-Type: text/markdown

# wechat-ilink-bot

轻量、实用的 Python SDK，用于接入 WeChat iLink Bot API。

支持扫码登录、长轮询收消息、文本/图片/视频/文件发送，以及一键 webhook 发送。

## 核心能力

- 收消息：长轮询 + handler
- 主动发送文本：`send_text`
- 主动发送图片/视频/文件：`send_image` / `send_video` / `send_file`
- 会话内回复文本：`ctx.reply`
- 会话内回复图片/视频/文件：`ctx.reply_image` / `ctx.reply_video` / `ctx.reply_file`
- Webhook 触发发送（当前为文本）

<p>
  <a href="https://wechat-ilink-bot.readthedocs.io/en/latest/" target="_blank">
    <strong>Read the Docs: https://wechat-ilink-bot.readthedocs.io/en/latest/</strong>
  </a>
</p>

## 安装

PyPI 安装：

```bash
pip install wechat-ilink-bot
```

源码安装（开发/调试推荐）：

```bash
git clone https://github.com/hkslover/wechat-ilink-bot.git
cd wechat-ilink-bot
pip install -e .
```

可选依赖：

```bash
# 终端二维码打印
pip install "wechat-ilink-bot[qrcode]"

# webhook
pip install "wechat-ilink-bot[webhook]"
```

## 快速开始

### 1) 扫码登录并持久化账号

```python
import asyncio

from wechat_bot import Bot


async def main() -> None:
    bot = Bot(use_current_user=False)
    result = await bot.login()
    print(f"login ok: account_id={result.account_id}, user_id={result.user_id}")
    await bot.stop()


if __name__ == "__main__":
    asyncio.run(main())
```

### 2) 最小 Echo Bot

```python
from wechat_bot import Bot, Filter

bot = Bot()


@bot.on_message(Filter.text())
async def echo(ctx):
    await ctx.reply(f"Echo: {ctx.text}")


if __name__ == "__main__":
    bot.run()
```

### 3) 主动发送（owner-default 或显式目标）

```python
import asyncio

from wechat_bot import Bot


async def main() -> None:
    bot = Bot()

    # owner-default（不传 to）
    await bot.send_text(text="Hello from wechat-ilink-bot!")

    # 或者显式目标
    # await bot.send_text(to="o9xxx@im.wechat", text="Hello")

    await bot.stop()


if __name__ == "__main__":
    asyncio.run(main())
```

### 4) 主动发送富媒体（图片 / 视频 / 文件）

```python
import asyncio

from wechat_bot import Bot


async def main() -> None:
    bot = Bot()

    # owner-default（不传 to）
    await bot.send_image(file_path="/path/to/image.png", caption="image")
    await bot.send_video(file_path="/path/to/video.mp4", caption="video")
    await bot.send_file(file_path="/path/to/file.pdf", caption="file")

    # 显式目标（需要时）
    # await bot.send_image(to="o9xxx@im.wechat", file_path="/path/to/image.png")

    await bot.stop()


if __name__ == "__main__":
    asyncio.run(main())
```

### 5) 会话内回复富媒体（ctx.reply_*）

```python
from wechat_bot import Bot, Filter

bot = Bot()


@bot.on_message(Filter.text_startswith("/image"))
async def reply_image(ctx):
    await ctx.reply_image("/path/to/image.png", caption="image")


@bot.on_message(Filter.text_startswith("/video"))
async def reply_video(ctx):
    await ctx.reply_video("/path/to/video.mp4", caption="video")


@bot.on_message(Filter.text_startswith("/file"))
async def reply_file(ctx):
    await ctx.reply_file("/path/to/file.pdf", caption="file")


if __name__ == "__main__":
    bot.run()
```

## Webhook 快速使用

启动：

```bash
wechat-bot webhook --api-key your-secret
```

请求示例：

```bash
# GET
curl "http://127.0.0.1:8787/send?text=hello&key=your-secret"

# POST
curl -X POST "http://127.0.0.1:8787/send" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Key: your-secret" \
  -d '{"text":"hello from webhook"}'
```

> Webhook `/send` 当前用于发送文本。  
> 图片/视频/文件发送请使用 `Bot.send_image` / `Bot.send_video` / `Bot.send_file`。

## Examples

更多完整脚本请查看：

- [examples/login_bot.py](examples/login_bot.py)
- [examples/echo_bot.py](examples/echo_bot.py)
- [examples/command_bot.py](examples/command_bot.py)
- [examples/media_bot.py](examples/media_bot.py)
- [examples/proactive_send.py](examples/proactive_send.py)
- [examples/account_switch.py](examples/account_switch.py)
- [examples/webhook_server.py](examples/webhook_server.py)

## 本地文档预览

```bash
pip install -r docs/requirements.txt
mkdocs serve
```

## 参与贡献

- [Contributing Guide](CONTRIBUTING.md)
- [Security Policy](SECURITY.md)
- [Changelog](CHANGELOG.md)

## License

MIT
