Metadata-Version: 2.4
Name: wx-channel
Version: 1.0.0
Summary: WeChat iLink bot channel — async Python SDK for WeChat messaging
Author: manymore13
License: MIT
Project-URL: Homepage, https://github.com/manymore13/wx_channel
Project-URL: Repository, https://github.com/manymore13/wx_channel
Project-URL: Issues, https://github.com/manymore13/wx_channel/issues
Keywords: wechat,ilink,bot,messaging,async,sdk
Classifier: Development Status :: 4 - Beta
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: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: qrcode>=7.4.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: cryptography>=41.0.0
Dynamic: license-file

# wx-channel

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
[![PyPI](https://img.shields.io/pypi/v/wx-channel)](https://pypi.org/project/wx-channel/)

[中文文档](./README_CN.md)

**wx-channel** is an async Python SDK for the WeChat iLink bot channel.
It lets you log in via QR code, send/receive messages (text, image, file, video, voice), and build WeChat bots with just a few lines of code.

---

## Features

- QR code login with account persistence
- Receive real-time messages via long-polling (text, image, file, video, voice)
- Send text, image, file messages
- CDN upload/download with AES-ECB encryption
- Multi-handler subscription and async message iterator
- Session management (connect/disconnect with auto-reconnect)

## Installation

```bash
pip install wx-channel
```

Or from source:

```bash
pip install git+https://github.com/manymore13/wx_channel.git
```

## Quick Start

### Login

```python
import asyncio
from wx_channel import WxChannel

async def login():
    # Generates a QR code in terminal. Scan with WeChat.
    channel = await WxChannel.from_login(timeout_sec=300)
    print(f"Logged in as: {channel.bot_id}")
    print(f"Wx user: {channel.wx_user_id}")

asyncio.run(login())
```

### Receive messages

```python
import asyncio
from wx_channel import WxChannel, WeixinMessage

async def listen():
    channel = await WxChannel.from_saved("your_bot_id")
    await channel.connect()

    async for msg in channel.messages():
        if msg.is_user and msg.is_finished:
            print(f"[{msg.from_user_id}] {msg.text}")

asyncio.run(listen())
```

### Send messages

```python
await channel.send_text(to_user_id="wx_user_id", text="Hello from bot!")
await channel.send_image(to_user_id="wx_user_id", file_path="./cat.jpg")
await channel.send_file(to_user_id="wx_user_id", file_path="./doc.pdf")
```

### Handler mode

```python
def on_msg(msg: WeixinMessage):
    if msg.is_user and msg.is_finished:
        print(f"[{msg.from_user_id}] {msg.text}")

channel.on_message(on_msg)
await channel.connect()
# Messages arrive in real-time via the callback
```

## API Overview

### WxChannel

| Method | Description |
|--------|-------------|
| `WxChannel.from_login()` | QR code login, returns a new channel |
| `WxChannel.from_saved(bot_id)` | Load saved account by bot_id |
| `WxChannel.list_accounts()` | List all saved accounts |
| `channel.connect()` | Start long-polling message loop |
| `channel.disconnect()` | Stop loop and close connection |
| `channel.send_text(to, text)` | Send a text message |
| `channel.send_image(to, path)` | Upload and send an image |
| `channel.send_file(to, path)` | Upload and send a file |
| `channel.save_media(item)` | Download and decrypt media from a message |
| `channel.on_message(handler)` | Subscribe to incoming messages |
| `channel.messages()` | Async iterator over incoming messages |

### Message Types

- `TextItem` — text content
- `ImageItem` — image with CDN media
- `FileItem` — file with CDN media
- `VoiceItem` — voice recording
- `VideoItem` — video with CDN media

### Error Types

- `LoginFailed` — QR login failed
- `LoginTimeout` — QR login timed out
- `SessionTimeout` — session expired, re-login needed
- `NetworkError` — HTTP or CDN error
- `ApiError` — iLink API returned an error

## Requirements

- Python >= 3.10
- aiohttp >= 3.9.0
- qrcode >= 7.4.0
- Pillow >= 10.0.0
- cryptography >= 41.0.0

## License

MIT © manymore13
