wechatbot-sdk 0.1.0__tar.gz

wechatbot_sdk-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+dist/
+tmp/
+.DS_Store
+*.tsbuildinfo
+.next/
+next-env.d.ts
+target/
+package-lock.json
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/

wechatbot_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: wechatbot-sdk
+Version: 0.1.0
+Summary: WeChat iLink Bot SDK for Python — async, typed, production-grade
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: cryptography>=42.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# wechatbot-sdk — Python SDK
+
+WeChat iLink Bot SDK for Python — async, typed, production-grade.
+
+## Install
+
+```bash
+pip install wechatbot-sdk
+```
+
+Requires Python ≥ 3.11. Dependencies: `aiohttp`, `cryptography`.
+
+## Quick Start
+
+```python
+from wechatbot import WeChatBot
+
+bot = WeChatBot()
+
+@bot.on_message
+async def handle(msg):
+    await bot.send_typing(msg.user_id)
+    await bot.reply(msg, f"Echo: {msg.text}")
+
+bot.run()  # login + start in one call
+```
+
+Or with async control:
+
+```python
+import asyncio
+from wechatbot import WeChatBot
+
+async def main():
+    bot = WeChatBot()
+    await bot.login()
+
+    @bot.on_message
+    async def handle(msg):
+        await bot.reply(msg, f"Echo: {msg.text}")
+
+    await bot.start()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+bot = WeChatBot(
+    base_url="https://ilinkai.weixin.qq.com",   # default
+    cred_path="~/.wechatbot/credentials.json",   # default
+    on_qr_url=lambda url: print(f"Scan: {url}"),
+    on_scanned=lambda: print("Scanned!"),
+    on_expired=lambda: print("Expired..."),
+    on_error=lambda err: print(f"Error: {err}"),
+)
+```
+
+## API Reference
+
+| Method | Description |
+|---|---|
+| `await bot.login(force=False)` | QR login (auto-skips if creds exist) |
+| `await bot.start()` | Start long-poll loop |
+| `bot.run()` | Sync: login + start |
+| `bot.stop()` | Stop gracefully |
+| `bot.on_message(handler)` | Register handler (also works as decorator) |
+| `await bot.reply(msg, text)` | Reply (auto context_token + stop typing) |
+| `await bot.send(user_id, text)` | Send to user (needs prior context) |
+| `await bot.send_typing(user_id)` | Show "typing..." indicator |
+| `await bot.stop_typing(user_id)` | Cancel typing indicator |
+
+## Message Types
+
+```python
+@dataclass
+class IncomingMessage:
+    user_id: str
+    text: str
+    type: Literal["text", "image", "voice", "file", "video"]
+    timestamp: datetime
+    images: list[ImageContent]
+    voices: list[VoiceContent]
+    files: list[FileContent]
+    videos: list[VideoContent]
+    quoted_message: QuotedMessage | None
+    raw: dict
+```
+
+## AES-128-ECB Crypto
+
+```python
+from wechatbot import (
+    generate_aes_key, encrypt_aes_ecb, decrypt_aes_ecb, decode_aes_key
+)
+
+key = generate_aes_key()
+ct = encrypt_aes_ecb(b"Hello", key)
+pt = decrypt_aes_ecb(ct, key)
+
+# Decode protocol key (all 3 formats)
+k = decode_aes_key("ABEiM0RVZneImaq7zN3u/w==")       # base64(raw)
+k = decode_aes_key("00112233445566778899aabbccddeeff") # hex
+```
+
+## Project Structure
+
+```
+python/
+├── wechatbot/
+│   ├── __init__.py      ← Public exports
+│   ├── client.py        ← WeChatBot (login, start, reply, send)
+│   ├── protocol.py      ← Raw iLink API calls
+│   ├── auth.py          ← QR login + credential persistence
+│   ├── types.py         ← All types (dataclasses)
+│   ├── errors.py        ← Error hierarchy
+│   └── crypto.py        ← AES-128-ECB encrypt/decrypt
+├── examples/
+│   └── echo_bot.py
+├── tests/
+│   ├── test_crypto.py   ← 10 tests
+│   └── test_client.py   ← 8 tests
+└── pyproject.toml
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

wechatbot_sdk-0.1.0/README.md

@@ -0,0 +1,136 @@
+# wechatbot-sdk — Python SDK
+
+WeChat iLink Bot SDK for Python — async, typed, production-grade.
+
+## Install
+
+```bash
+pip install wechatbot-sdk
+```
+
+Requires Python ≥ 3.11. Dependencies: `aiohttp`, `cryptography`.
+
+## Quick Start
+
+```python
+from wechatbot import WeChatBot
+
+bot = WeChatBot()
+
+@bot.on_message
+async def handle(msg):
+    await bot.send_typing(msg.user_id)
+    await bot.reply(msg, f"Echo: {msg.text}")
+
+bot.run()  # login + start in one call
+```
+
+Or with async control:
+
+```python
+import asyncio
+from wechatbot import WeChatBot
+
+async def main():
+    bot = WeChatBot()
+    await bot.login()
+
+    @bot.on_message
+    async def handle(msg):
+        await bot.reply(msg, f"Echo: {msg.text}")
+
+    await bot.start()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+bot = WeChatBot(
+    base_url="https://ilinkai.weixin.qq.com",   # default
+    cred_path="~/.wechatbot/credentials.json",   # default
+    on_qr_url=lambda url: print(f"Scan: {url}"),
+    on_scanned=lambda: print("Scanned!"),
+    on_expired=lambda: print("Expired..."),
+    on_error=lambda err: print(f"Error: {err}"),
+)
+```
+
+## API Reference
+
+| Method | Description |
+|---|---|
+| `await bot.login(force=False)` | QR login (auto-skips if creds exist) |
+| `await bot.start()` | Start long-poll loop |
+| `bot.run()` | Sync: login + start |
+| `bot.stop()` | Stop gracefully |
+| `bot.on_message(handler)` | Register handler (also works as decorator) |
+| `await bot.reply(msg, text)` | Reply (auto context_token + stop typing) |
+| `await bot.send(user_id, text)` | Send to user (needs prior context) |
+| `await bot.send_typing(user_id)` | Show "typing..." indicator |
+| `await bot.stop_typing(user_id)` | Cancel typing indicator |
+
+## Message Types
+
+```python
+@dataclass
+class IncomingMessage:
+    user_id: str
+    text: str
+    type: Literal["text", "image", "voice", "file", "video"]
+    timestamp: datetime
+    images: list[ImageContent]
+    voices: list[VoiceContent]
+    files: list[FileContent]
+    videos: list[VideoContent]
+    quoted_message: QuotedMessage | None
+    raw: dict
+```
+
+## AES-128-ECB Crypto
+
+```python
+from wechatbot import (
+    generate_aes_key, encrypt_aes_ecb, decrypt_aes_ecb, decode_aes_key
+)
+
+key = generate_aes_key()
+ct = encrypt_aes_ecb(b"Hello", key)
+pt = decrypt_aes_ecb(ct, key)
+
+# Decode protocol key (all 3 formats)
+k = decode_aes_key("ABEiM0RVZneImaq7zN3u/w==")       # base64(raw)
+k = decode_aes_key("00112233445566778899aabbccddeeff") # hex
+```
+
+## Project Structure
+
+```
+python/
+├── wechatbot/
+│   ├── __init__.py      ← Public exports
+│   ├── client.py        ← WeChatBot (login, start, reply, send)
+│   ├── protocol.py      ← Raw iLink API calls
+│   ├── auth.py          ← QR login + credential persistence
+│   ├── types.py         ← All types (dataclasses)
+│   ├── errors.py        ← Error hierarchy
+│   └── crypto.py        ← AES-128-ECB encrypt/decrypt
+├── examples/
+│   └── echo_bot.py
+├── tests/
+│   ├── test_crypto.py   ← 10 tests
+│   └── test_client.py   ← 8 tests
+└── pyproject.toml
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

wechatbot_sdk-0.1.0/examples/echo_bot.py

@@ -0,0 +1,37 @@
+"""Echo bot example — receives messages and replies with 'Echo: <text>'."""
+
+import asyncio
+from wechatbot import WeChatBot
+
+
+async def main():
+    bot = WeChatBot(
+        on_qr_url=lambda url: print(f"\nScan this URL in WeChat:\n{url}\n"),
+        on_error=lambda err: print(f"Error: {err}"),
+    )
+
+    creds = await bot.login()
+    print(f"Logged in: {creds.account_id} ({creds.user_id})")
+
+    count = 0
+
+    @bot.on_message
+    async def handle(msg):
+        nonlocal count
+        count += 1
+        print(f"[{count}] {msg.user_id}: {msg.text}")
+
+        await bot.send_typing(msg.user_id)
+        await asyncio.sleep(0.5)
+        await bot.reply(msg, f"Echo: {msg.text}")
+
+    print("Listening for messages (Ctrl+C to stop)")
+    try:
+        await bot.start()
+    except KeyboardInterrupt:
+        bot.stop()
+    print(f"Stopped. Processed {count} messages.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

wechatbot_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "wechatbot-sdk"
+version = "0.1.0"
+description = "WeChat iLink Bot SDK for Python — async, typed, production-grade"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = [
+    "aiohttp>=3.9",
+    "cryptography>=42.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["wechatbot"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

wechatbot_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,46 @@
+"""Tests for client utilities."""
+
+from wechatbot.client import _chunk_text, _detect_type, _extract_text
+
+
+def test_chunk_short():
+    assert _chunk_text("hello", 2000) == ["hello"]
+
+
+def test_chunk_empty():
+    assert _chunk_text("", 2000) == [""]
+
+
+def test_chunk_at_paragraph():
+    text = "A" * 1500 + "\n\n" + "B" * 1000
+    chunks = _chunk_text(text, 2000)
+    assert len(chunks) == 2
+    assert chunks[0] == "A" * 1500 + "\n\n"
+
+
+def test_chunk_hard_cut():
+    text = "A" * 5000
+    chunks = _chunk_text(text, 2000)
+    assert len(chunks) == 3
+    assert "".join(chunks) == text
+
+
+def test_detect_type_text():
+    assert _detect_type([{"type": 1}]) == "text"
+
+
+def test_detect_type_image():
+    assert _detect_type([{"type": 2}]) == "image"
+
+
+def test_detect_type_empty():
+    assert _detect_type([]) == "text"
+
+
+def test_extract_text():
+    items = [
+        {"type": 1, "text_item": {"text": "Hello"}},
+        {"type": 2, "image_item": {"url": "https://img.com/1.jpg"}},
+    ]
+    result = _extract_text(items)
+    assert result == "Hello\nhttps://img.com/1.jpg"

wechatbot_sdk-0.1.0/tests/test_crypto.py

@@ -0,0 +1,77 @@
+"""Tests for AES-128-ECB crypto."""
+
+import pytest
+from wechatbot.crypto import (
+    decrypt_aes_ecb,
+    decode_aes_key,
+    encrypt_aes_ecb,
+    encrypted_size,
+    encode_aes_key_base64,
+    encode_aes_key_hex,
+    generate_aes_key,
+)
+from wechatbot.errors import MediaError
+
+
+def test_round_trip():
+    key = generate_aes_key()
+    plaintext = b"Hello, WeChat!"
+    ciphertext = encrypt_aes_ecb(plaintext, key)
+    decrypted = decrypt_aes_ecb(ciphertext, key)
+    assert decrypted == plaintext
+
+
+def test_encrypted_size():
+    assert encrypted_size(14) == 16
+    assert encrypted_size(16) == 32
+    assert encrypted_size(100) == 112
+
+
+def test_actual_encrypted_sizes():
+    key = generate_aes_key()
+    assert len(encrypt_aes_ecb(b"\x00" * 14, key)) == 16
+    assert len(encrypt_aes_ecb(b"\x00" * 16, key)) == 32
+    assert len(encrypt_aes_ecb(b"\x00" * 100, key)) == 112
+
+
+def test_wrong_key_length():
+    with pytest.raises(MediaError, match="16 bytes"):
+        encrypt_aes_ecb(b"test", b"\x00" * 8)
+    with pytest.raises(MediaError, match="16 bytes"):
+        decrypt_aes_ecb(b"\x00" * 16, b"\x00" * 8)
+
+
+def test_decode_format_a_base64_raw():
+    raw = bytes.fromhex("00112233445566778899aabbccddeeff")
+    import base64
+    encoded = base64.b64encode(raw).decode()  # ABEiM0RVZneImaq7zN3u/w==
+    decoded = decode_aes_key(encoded)
+    assert decoded == raw
+
+
+def test_decode_format_b_base64_hex():
+    hex_str = "00112233445566778899aabbccddeeff"
+    import base64
+    encoded = base64.b64encode(hex_str.encode()).decode()
+    decoded = decode_aes_key(encoded)
+    assert decoded == bytes.fromhex(hex_str)
+
+
+def test_decode_direct_hex():
+    hex_str = "00112233445566778899aabbccddeeff"
+    decoded = decode_aes_key(hex_str)
+    assert decoded == bytes.fromhex(hex_str)
+    assert len(decoded) == 16
+
+
+def test_encode_aes_key_hex():
+    key = bytes.fromhex("00112233445566778899aabbccddeeff")
+    assert encode_aes_key_hex(key) == "00112233445566778899aabbccddeeff"
+
+
+def test_encode_aes_key_base64():
+    key = bytes.fromhex("00112233445566778899aabbccddeeff")
+    result = encode_aes_key_base64(key)
+    import base64
+    decoded = base64.b64decode(result).decode("ascii")
+    assert decoded == "00112233445566778899aabbccddeeff"

wechatbot_sdk-0.1.0/wechatbot/__init__.py

@@ -0,0 +1,49 @@
+"""WeChat iLink Bot SDK for Python."""
+
+from .types import (
+    Credentials,
+    IncomingMessage,
+    ImageContent,
+    VoiceContent,
+    FileContent,
+    VideoContent,
+    QuotedMessage,
+    ContentType,
+)
+from .client import WeChatBot
+from .errors import (
+    WeChatBotError,
+    ApiError,
+    AuthError,
+    NoContextError,
+    MediaError,
+)
+from .crypto import (
+    encrypt_aes_ecb,
+    decrypt_aes_ecb,
+    generate_aes_key,
+    decode_aes_key,
+    encrypted_size,
+)
+
+__all__ = [
+    "WeChatBot",
+    "Credentials",
+    "IncomingMessage",
+    "ImageContent",
+    "VoiceContent",
+    "FileContent",
+    "VideoContent",
+    "QuotedMessage",
+    "ContentType",
+    "WeChatBotError",
+    "ApiError",
+    "AuthError",
+    "NoContextError",
+    "MediaError",
+    "encrypt_aes_ecb",
+    "decrypt_aes_ecb",
+    "generate_aes_key",
+    "decode_aes_key",
+    "encrypted_size",
+]

wechatbot_sdk-0.1.0/wechatbot/auth.py

@@ -0,0 +1,125 @@
+"""QR code login and credential persistence."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any, Callable
+
+from .errors import AuthError
+from .protocol import DEFAULT_BASE_URL, ILinkApi
+from .types import Credentials
+
+DEFAULT_CRED_DIR = Path.home() / ".wechatbot"
+DEFAULT_CRED_PATH = DEFAULT_CRED_DIR / "credentials.json"
+QR_POLL_INTERVAL = 2.0
+
+
+async def load_credentials(path: Path | None = None) -> Credentials | None:
+    target = path or DEFAULT_CRED_PATH
+    try:
+        data = json.loads(target.read_text("utf-8"))
+        return Credentials(
+            token=data["token"],
+            base_url=data.get("base_url") or data.get("baseUrl", ""),
+            account_id=data.get("account_id") or data.get("accountId", ""),
+            user_id=data.get("user_id") or data.get("userId", ""),
+            saved_at=data.get("saved_at") or data.get("savedAt"),
+        )
+    except FileNotFoundError:
+        return None
+    except (json.JSONDecodeError, KeyError) as e:
+        raise AuthError(f"Invalid credentials file: {e}") from e
+
+
+async def save_credentials(creds: Credentials, path: Path | None = None) -> None:
+    target = path or DEFAULT_CRED_PATH
+    target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    payload = {
+        "token": creds.token,
+        "baseUrl": creds.base_url,
+        "accountId": creds.account_id,
+        "userId": creds.user_id,
+        "savedAt": creds.saved_at,
+    }
+    target.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    target.chmod(0o600)
+
+
+async def clear_credentials(path: Path | None = None) -> None:
+    target = path or DEFAULT_CRED_PATH
+    target.unlink(missing_ok=True)
+
+
+async def login(
+    api: ILinkApi,
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    cred_path: Path | None = None,
+    force: bool = False,
+    on_qr_url: Callable[[str], None] | None = None,
+    on_scanned: Callable[[], None] | None = None,
+    on_expired: Callable[[], None] | None = None,
+) -> Credentials:
+    """QR code login. Returns stored credentials if available and force=False."""
+    if not force:
+        stored = await load_credentials(cred_path)
+        if stored:
+            return stored
+
+    while True:
+        qr = await api.get_qr_code(base_url)
+        qr_url = qr["qrcode_img_content"]
+
+        if on_qr_url:
+            on_qr_url(qr_url)
+        else:
+            print(f"[wechatbot] Scan this URL in WeChat: {qr_url}", file=sys.stderr)
+
+        last_status = ""
+        while True:
+            status = await api.poll_qr_status(base_url, qr["qrcode"])
+            current = status["status"]
+
+            if current != last_status:
+                last_status = current
+                if current == "scaned":
+                    if on_scanned:
+                        on_scanned()
+                    else:
+                        print("[wechatbot] QR scanned — confirm in WeChat", file=sys.stderr)
+                elif current == "expired":
+                    if on_expired:
+                        on_expired()
+                    else:
+                        print("[wechatbot] QR expired — requesting new one", file=sys.stderr)
+                elif current == "confirmed":
+                    print("[wechatbot] Login confirmed", file=sys.stderr)
+
+            if current == "confirmed":
+                token = status.get("bot_token")
+                bot_id = status.get("ilink_bot_id")
+                user_id = status.get("ilink_user_id")
+                if not token or not bot_id or not user_id:
+                    raise AuthError("Login confirmed but missing credentials")
+
+                from datetime import datetime, timezone
+
+                creds = Credentials(
+                    token=token,
+                    base_url=status.get("baseurl") or base_url,
+                    account_id=bot_id,
+                    user_id=user_id,
+                    saved_at=datetime.now(timezone.utc).isoformat(),
+                )
+                await save_credentials(creds, cred_path)
+                return creds
+
+            if current == "expired":
+                break
+
+            await asyncio.sleep(QR_POLL_INTERVAL)