wechatbot-sdk 0.1.0__py3-none-any.whl

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/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)

wechatbot/client.py

@@ -0,0 +1,372 @@
+"""Main WeChatBot client — orchestrates all SDK components."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Awaitable, Callable
+
+from .auth import clear_credentials, load_credentials, login
+from .errors import ApiError, NoContextError
+from .protocol import DEFAULT_BASE_URL, ILinkApi
+from .types import (
+    CDNMedia,
+    Credentials,
+    FileContent,
+    ImageContent,
+    IncomingMessage,
+    MessageItemType,
+    MessageType,
+    QuotedMessage,
+    VideoContent,
+    VoiceContent,
+)
+
+MessageHandler = Callable[[IncomingMessage], Any]
+
+
+class WeChatBot:
+    """WeChat iLink Bot client.
+
+    Usage::
+
+        bot = WeChatBot()
+        await bot.login()
+
+        @bot.on_message
+        async def handle(msg):
+            await bot.send_typing(msg.user_id)
+            await bot.reply(msg, f"Echo: {msg.text}")
+
+        await bot.start()
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        cred_path: str | None = None,
+        on_qr_url: Callable[[str], None] | None = None,
+        on_scanned: Callable[[], None] | None = None,
+        on_expired: Callable[[], None] | None = None,
+        on_error: Callable[[Exception], None] | None = None,
+    ) -> None:
+        self._base_url = base_url or DEFAULT_BASE_URL
+        self._cred_path = Path(cred_path) if cred_path else None
+        self._on_qr_url = on_qr_url
+        self._on_scanned = on_scanned
+        self._on_expired = on_expired
+        self._on_error = on_error
+
+        self._api = ILinkApi()
+        self._credentials: Credentials | None = None
+        self._context_tokens: dict[str, str] = {}
+        self._handlers: list[MessageHandler] = []
+        self._cursor = ""
+        self._stopped = False
+
+    # ── Auth ──────────────────────────────────────────────────────────
+
+    async def login(self, *, force: bool = False) -> Credentials:
+        """QR code login. Skips QR if stored credentials exist."""
+        creds = await login(
+            self._api,
+            base_url=self._base_url,
+            cred_path=self._cred_path,
+            force=force,
+            on_qr_url=self._on_qr_url,
+            on_scanned=self._on_scanned,
+            on_expired=self._on_expired,
+        )
+        self._credentials = creds
+        self._base_url = creds.base_url
+        self._log(f"Logged in as {creds.user_id}")
+        return creds
+
+    def get_credentials(self) -> Credentials | None:
+        return self._credentials
+
+    # ── Message Handlers ──────────────────────────────────────────────
+
+    def on_message(self, handler: MessageHandler) -> MessageHandler:
+        """Register a message handler. Can be used as a decorator."""
+        self._handlers.append(handler)
+        return handler
+
+    # ── Sending ───────────────────────────────────────────────────────
+
+    async def reply(self, msg: IncomingMessage, text: str) -> None:
+        """Reply to an incoming message. Auto context_token + auto stop typing."""
+        self._context_tokens[msg.user_id] = msg._context_token
+        await self._send_text(msg.user_id, text, msg._context_token)
+        try:
+            await self.stop_typing(msg.user_id)
+        except Exception:
+            pass
+
+    async def send(self, user_id: str, text: str) -> None:
+        """Send text to a user (requires prior context_token)."""
+        ct = self._context_tokens.get(user_id)
+        if not ct:
+            raise NoContextError(user_id)
+        await self._send_text(user_id, text, ct)
+
+    async def send_typing(self, user_id: str) -> None:
+        """Show 'typing...' indicator."""
+        ct = self._context_tokens.get(user_id)
+        if not ct:
+            return
+        creds = self._require_creds()
+        config = await self._api.get_config(creds.base_url, creds.token, user_id, ct)
+        ticket = config.get("typing_ticket")
+        if ticket:
+            await self._api.send_typing(creds.base_url, creds.token, user_id, ticket, 1)
+
+    async def stop_typing(self, user_id: str) -> None:
+        """Cancel 'typing...' indicator."""
+        ct = self._context_tokens.get(user_id)
+        if not ct:
+            return
+        creds = self._require_creds()
+        config = await self._api.get_config(creds.base_url, creds.token, user_id, ct)
+        ticket = config.get("typing_ticket")
+        if ticket:
+            await self._api.send_typing(creds.base_url, creds.token, user_id, ticket, 2)
+
+    # ── Lifecycle ─────────────────────────────────────────────────────
+
+    async def start(self) -> None:
+        """Start the long-poll loop. Blocks until stop() is called."""
+        creds = self._require_creds()
+        self._stopped = False
+        self._log("Long-poll started")
+        retry_delay = 1.0
+
+        while not self._stopped:
+            try:
+                creds = self._require_creds()
+                updates = await self._api.get_updates(
+                    creds.base_url, creds.token, self._cursor
+                )
+
+                buf = updates.get("get_updates_buf")
+                if buf:
+                    self._cursor = buf
+                retry_delay = 1.0
+
+                for raw in updates.get("msgs", []):
+                    self._remember_context(raw)
+                    msg = self._parse_message(raw)
+                    if msg:
+                        await self._dispatch(msg)
+
+            except ApiError as e:
+                if e.is_session_expired:
+                    self._log("Session expired — re-login")
+                    await clear_credentials(self._cred_path)
+                    self._context_tokens.clear()
+                    self._cursor = ""
+                    try:
+                        await self.login(force=True)
+                        retry_delay = 1.0
+                        continue
+                    except Exception as login_err:
+                        self._report_error(login_err)
+                else:
+                    self._report_error(e)
+
+                await asyncio.sleep(retry_delay)
+                retry_delay = min(retry_delay * 2, 10.0)
+
+            except asyncio.CancelledError:
+                break
+
+            except Exception as e:
+                if self._stopped:
+                    break
+                self._report_error(e)
+                await asyncio.sleep(retry_delay)
+                retry_delay = min(retry_delay * 2, 10.0)
+
+        self._log("Long-poll stopped")
+
+    def stop(self) -> None:
+        """Stop the long-poll loop."""
+        self._stopped = True
+
+    def run(self) -> None:
+        """Synchronous entry: login + start. Convenience for scripts."""
+        asyncio.run(self._run_sync())
+
+    async def _run_sync(self) -> None:
+        await self.login()
+        await self.start()
+
+    # ── Internal ──────────────────────────────────────────────────────
+
+    async def _send_text(self, user_id: str, text: str, context_token: str) -> None:
+        if not text:
+            raise ValueError("Message text cannot be empty")
+        creds = self._require_creds()
+        for chunk in _chunk_text(text, 2000):
+            msg = self._api.build_text_message(user_id, context_token, chunk)
+            await self._api.send_message(creds.base_url, creds.token, msg)
+
+    def _remember_context(self, raw: dict[str, Any]) -> None:
+        mt = raw.get("message_type")
+        uid = raw.get("from_user_id") if mt == MessageType.USER else raw.get("to_user_id")
+        ct = raw.get("context_token")
+        if uid and ct:
+            self._context_tokens[uid] = ct
+
+    def _parse_message(self, raw: dict[str, Any]) -> IncomingMessage | None:
+        if raw.get("message_type") != MessageType.USER:
+            return None
+
+        items = raw.get("item_list", [])
+        images, voices, files, videos = [], [], [], []
+        quoted = None
+
+        for item in items:
+            t = item.get("type")
+            if t == MessageItemType.IMAGE and item.get("image_item"):
+                ii = item["image_item"]
+                media = _parse_cdn_media(ii.get("media"))
+                images.append(ImageContent(
+                    media=media, thumb_media=_parse_cdn_media(ii.get("thumb_media")),
+                    aes_key=ii.get("aeskey"), url=ii.get("url"),
+                    width=ii.get("thumb_width"), height=ii.get("thumb_height"),
+                ))
+            elif t == MessageItemType.VOICE and item.get("voice_item"):
+                vi = item["voice_item"]
+                voices.append(VoiceContent(
+                    media=_parse_cdn_media(vi.get("media")),
+                    text=vi.get("text"), duration_ms=vi.get("playtime"),
+                    encode_type=vi.get("encode_type"),
+                ))
+            elif t == MessageItemType.FILE and item.get("file_item"):
+                fi = item["file_item"]
+                size = None
+                if fi.get("len"):
+                    try:
+                        size = int(fi["len"])
+                    except (ValueError, TypeError):
+                        pass
+                files.append(FileContent(
+                    media=_parse_cdn_media(fi.get("media")),
+                    file_name=fi.get("file_name"), md5=fi.get("md5"), size=size,
+                ))
+            elif t == MessageItemType.VIDEO and item.get("video_item"):
+                vi = item["video_item"]
+                videos.append(VideoContent(
+                    media=_parse_cdn_media(vi.get("media")),
+                    thumb_media=_parse_cdn_media(vi.get("thumb_media")),
+                    duration_ms=vi.get("play_length"),
+                ))
+            if item.get("ref_msg"):
+                ref = item["ref_msg"]
+                qt = ref.get("message_item", {}).get("text_item", {}).get("text")
+                quoted = QuotedMessage(title=ref.get("title"), text=qt)
+
+        return IncomingMessage(
+            user_id=raw["from_user_id"],
+            text=_extract_text(items),
+            type=_detect_type(items),
+            timestamp=datetime.fromtimestamp(
+                raw.get("create_time_ms", 0) / 1000, tz=timezone.utc
+            ),
+            images=images, voices=voices, files=files, videos=videos,
+            quoted_message=quoted, raw=raw,
+            _context_token=raw.get("context_token", ""),
+        )
+
+    async def _dispatch(self, msg: IncomingMessage) -> None:
+        for handler in self._handlers:
+            try:
+                result = handler(msg)
+                if asyncio.iscoroutine(result) or asyncio.isfuture(result):
+                    await result
+            except Exception as e:
+                self._report_error(e)
+
+    def _require_creds(self) -> Credentials:
+        if not self._credentials:
+            raise RuntimeError("Not logged in. Call login() first.")
+        return self._credentials
+
+    def _report_error(self, err: Any) -> None:
+        self._log(str(err))
+        if self._on_error and isinstance(err, Exception):
+            self._on_error(err)
+
+    def _log(self, msg: str) -> None:
+        print(f"[wechatbot] {msg}", file=sys.stderr)
+
+
+def _detect_type(items: list[dict[str, Any]]) -> str:
+    if not items:
+        return "text"
+    t = items[0].get("type")
+    return {
+        MessageItemType.IMAGE: "image",
+        MessageItemType.VOICE: "voice",
+        MessageItemType.FILE: "file",
+        MessageItemType.VIDEO: "video",
+    }.get(t, "text")
+
+
+def _extract_text(items: list[dict[str, Any]]) -> str:
+    parts = []
+    for item in items:
+        t = item.get("type")
+        if t == MessageItemType.TEXT:
+            parts.append(item.get("text_item", {}).get("text", ""))
+        elif t == MessageItemType.IMAGE:
+            parts.append(item.get("image_item", {}).get("url", "[image]"))
+        elif t == MessageItemType.VOICE:
+            parts.append(item.get("voice_item", {}).get("text", "[voice]"))
+        elif t == MessageItemType.FILE:
+            parts.append(item.get("file_item", {}).get("file_name", "[file]"))
+        elif t == MessageItemType.VIDEO:
+            parts.append("[video]")
+    return "\n".join(p for p in parts if p)
+
+
+def _chunk_text(text: str, limit: int) -> list[str]:
+    if len(text) <= limit:
+        return [text]
+    chunks = []
+    while text:
+        if len(text) <= limit:
+            chunks.append(text)
+            break
+        window = text[:limit]
+        cut = -1
+        idx = window.rfind("\n\n")
+        if idx > limit * 3 // 10:
+            cut = idx + 2
+        if cut == -1:
+            idx = window.rfind("\n")
+            if idx > limit * 3 // 10:
+                cut = idx + 1
+        if cut == -1:
+            idx = window.rfind(" ")
+            if idx > limit * 3 // 10:
+                cut = idx + 1
+        if cut == -1:
+            cut = limit
+        chunks.append(text[:cut])
+        text = text[cut:]
+    return chunks or [""]
+
+
+def _parse_cdn_media(data: dict[str, Any] | None) -> CDNMedia | None:
+    if not data:
+        return None
+    return CDNMedia(
+        encrypt_query_param=data.get("encrypt_query_param", ""),
+        aes_key=data.get("aes_key", ""),
+        encrypt_type=data.get("encrypt_type"),
+    )

wechatbot/crypto.py

@@ -0,0 +1,90 @@
+"""AES-128-ECB encryption for WeChat CDN media files."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import os
+import re
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.padding import PKCS7
+
+from .errors import MediaError
+
+_HEX_32 = re.compile(r"^[0-9a-fA-F]{32}$")
+
+
+def encrypt_aes_ecb(plaintext: bytes, key: bytes) -> bytes:
+    """Encrypt with AES-128-ECB + PKCS7 padding."""
+    if len(key) != 16:
+        raise MediaError(f"AES key must be 16 bytes, got {len(key)}")
+    padder = PKCS7(128).padder()
+    padded = padder.update(plaintext) + padder.finalize()
+    cipher = Cipher(algorithms.AES(key), modes.ECB())
+    enc = cipher.encryptor()
+    return enc.update(padded) + enc.finalize()
+
+
+def decrypt_aes_ecb(ciphertext: bytes, key: bytes) -> bytes:
+    """Decrypt AES-128-ECB and remove PKCS7 padding."""
+    if len(key) != 16:
+        raise MediaError(f"AES key must be 16 bytes, got {len(key)}")
+    if len(ciphertext) % 16 != 0:
+        raise MediaError(f"Ciphertext length {len(ciphertext)} is not a multiple of 16")
+    cipher = Cipher(algorithms.AES(key), modes.ECB())
+    dec = cipher.decryptor()
+    padded = dec.update(ciphertext) + dec.finalize()
+    unpadder = PKCS7(128).unpadder()
+    return unpadder.update(padded) + unpadder.finalize()
+
+
+def generate_aes_key() -> bytes:
+    """Generate a random 16-byte AES key."""
+    return os.urandom(16)
+
+
+def encrypted_size(raw_size: int) -> int:
+    """Calculate size after AES-128-ECB with PKCS7 padding."""
+    return ((raw_size + 1 + 15) // 16) * 16
+
+
+def decode_aes_key(encoded: str) -> bytes:
+    """Decode an aes_key from the protocol.
+
+    Handles all three formats:
+      - Direct hex string (32 hex chars) — from image_item.aeskey
+      - base64(raw 16 bytes) — Format A
+      - base64(hex string 32 chars) — Format B
+    """
+    # Direct hex
+    if _HEX_32.match(encoded):
+        return binascii.unhexlify(encoded)
+
+    # Base64 decode
+    try:
+        decoded = base64.b64decode(encoded)
+    except Exception as e:
+        raise MediaError(f"Cannot base64 decode aes_key: {e}") from e
+
+    if len(decoded) == 16:
+        return decoded
+
+    if len(decoded) == 32:
+        try:
+            hex_str = decoded.decode("ascii")
+            if _HEX_32.match(hex_str):
+                return binascii.unhexlify(hex_str)
+        except (UnicodeDecodeError, binascii.Error):
+            pass
+
+    raise MediaError(f"Decoded aes_key has unexpected length {len(decoded)} (want 16 or 32)")
+
+
+def encode_aes_key_hex(key: bytes) -> str:
+    """Encode key as hex string (for getuploadurl)."""
+    return key.hex()
+
+
+def encode_aes_key_base64(key: bytes) -> str:
+    """Encode key as base64(hex) (for CDNMedia.aes_key)."""
+    return base64.b64encode(key.hex().encode("utf-8")).decode("ascii")

wechatbot/errors.py

@@ -0,0 +1,56 @@
+"""Error hierarchy for the WeChat Bot SDK."""
+
+
+class WeChatBotError(Exception):
+    """Base error for all SDK errors."""
+
+    def __init__(self, message: str, code: str = "UNKNOWN") -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class ApiError(WeChatBotError):
+    """Returned when the iLink API returns an error."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        http_status: int = 0,
+        errcode: int = 0,
+        payload: object = None,
+    ) -> None:
+        super().__init__(message, "API_ERROR")
+        self.http_status = http_status
+        self.errcode = errcode
+        self.payload = payload
+
+    @property
+    def is_session_expired(self) -> bool:
+        return self.errcode == -14
+
+
+class AuthError(WeChatBotError):
+    """Authentication errors (QR expired, login failed, etc.)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, "AUTH_ERROR")
+
+
+class NoContextError(WeChatBotError):
+    """No context_token available for a user."""
+
+    def __init__(self, user_id: str) -> None:
+        super().__init__(
+            f"No context_token for user {user_id}. "
+            "A message from this user must be received first.",
+            "NO_CONTEXT",
+        )
+        self.user_id = user_id
+
+
+class MediaError(WeChatBotError):
+    """Media processing errors (encryption, upload, download)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, "MEDIA_ERROR")

wechatbot/protocol.py

@@ -0,0 +1,151 @@
+"""Raw iLink Bot API HTTP calls."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import struct
+from typing import Any
+from urllib.parse import quote
+from uuid import uuid4
+
+import aiohttp
+
+from .errors import ApiError
+from .types import MessageItemType, MessageState, MessageType
+
+DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com"
+CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c"
+CHANNEL_VERSION = "2.0.0"
+
+
+def random_wechat_uin() -> str:
+    val = struct.unpack(">I", os.urandom(4))[0]
+    return base64.b64encode(str(val).encode("utf-8")).decode("ascii")
+
+
+def auth_headers(token: str) -> dict[str, str]:
+    return {
+        "Content-Type": "application/json",
+        "AuthorizationType": "ilink_bot_token",
+        "Authorization": f"Bearer {token}",
+        "X-WECHAT-UIN": random_wechat_uin(),
+    }
+
+
+def _base_info() -> dict[str, str]:
+    return {"channel_version": CHANNEL_VERSION}
+
+
+async def _parse_response(resp: aiohttp.ClientResponse, label: str) -> dict[str, Any]:
+    text = await resp.text()
+    payload: dict[str, Any] = json.loads(text) if text else {}
+
+    if resp.status >= 400:
+        msg = payload.get("errmsg") or f"{label} failed with HTTP {resp.status}"
+        raise ApiError(
+            msg,
+            http_status=resp.status,
+            errcode=payload.get("errcode", 0),
+            payload=payload,
+        )
+
+    ret = payload.get("ret")
+    if isinstance(ret, int) and ret != 0:
+        code = payload.get("errcode", ret)
+        msg = payload.get("errmsg") or f"{label} failed (ret={ret})"
+        raise ApiError(msg, http_status=resp.status, errcode=code, payload=payload)
+
+    return payload
+
+
+class ILinkApi:
+    """Low-level iLink API client. Each method maps 1:1 to an endpoint."""
+
+    def __init__(self) -> None:
+        self._timeout = aiohttp.ClientTimeout(total=45)
+
+    async def get_qr_code(self, base_url: str) -> dict[str, Any]:
+        url = f"{base_url}/ilink/bot/get_bot_qrcode?bot_type=3"
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url) as resp:
+                return await _parse_response(resp, "get_bot_qrcode")
+
+    async def poll_qr_status(self, base_url: str, qrcode: str) -> dict[str, Any]:
+        url = f"{base_url}/ilink/bot/get_qrcode_status?qrcode={quote(qrcode, safe='')}"
+        async with aiohttp.ClientSession() as session:
+            async with session.get(
+                url, headers={"iLink-App-ClientVersion": "1"}
+            ) as resp:
+                return await _parse_response(resp, "get_qrcode_status")
+
+    async def get_updates(
+        self, base_url: str, token: str, cursor: str
+    ) -> dict[str, Any]:
+        body = {"get_updates_buf": cursor, "base_info": _base_info()}
+        return await self._post(base_url, "/ilink/bot/getupdates", token, body, 45)
+
+    async def send_message(
+        self, base_url: str, token: str, msg: dict[str, Any]
+    ) -> dict[str, Any]:
+        body = {"msg": msg, "base_info": _base_info()}
+        return await self._post(base_url, "/ilink/bot/sendmessage", token, body)
+
+    async def get_config(
+        self, base_url: str, token: str, user_id: str, context_token: str
+    ) -> dict[str, Any]:
+        body = {
+            "ilink_user_id": user_id,
+            "context_token": context_token,
+            "base_info": _base_info(),
+        }
+        return await self._post(base_url, "/ilink/bot/getconfig", token, body)
+
+    async def send_typing(
+        self,
+        base_url: str,
+        token: str,
+        user_id: str,
+        ticket: str,
+        status: int,
+    ) -> dict[str, Any]:
+        body = {
+            "ilink_user_id": user_id,
+            "typing_ticket": ticket,
+            "status": status,
+            "base_info": _base_info(),
+        }
+        return await self._post(base_url, "/ilink/bot/sendtyping", token, body)
+
+    async def _post(
+        self,
+        base_url: str,
+        endpoint: str,
+        token: str,
+        body: dict[str, Any],
+        timeout_secs: int = 15,
+    ) -> dict[str, Any]:
+        url = f"{base_url.rstrip('/')}{endpoint}"
+        timeout = aiohttp.ClientTimeout(total=timeout_secs)
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            async with session.post(
+                url, headers=auth_headers(token), json=body
+            ) as resp:
+                return await _parse_response(resp, endpoint)
+
+    @staticmethod
+    def build_text_message(
+        user_id: str, context_token: str, text: str
+    ) -> dict[str, Any]:
+        return {
+            "from_user_id": "",
+            "to_user_id": user_id,
+            "client_id": str(uuid4()),
+            "message_type": MessageType.BOT,
+            "message_state": MessageState.FINISH,
+            "context_token": context_token,
+            "item_list": [
+                {"type": MessageItemType.TEXT, "text_item": {"text": text}}
+            ],
+        }

wechatbot/types.py

@@ -0,0 +1,110 @@
+"""Type definitions for the WeChat Bot SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import IntEnum
+from typing import Any, Literal
+
+
+class MessageType(IntEnum):
+    USER = 1
+    BOT = 2
+
+
+class MessageState(IntEnum):
+    NEW = 0
+    GENERATING = 1
+    FINISH = 2
+
+
+class MessageItemType(IntEnum):
+    TEXT = 1
+    IMAGE = 2
+    VOICE = 3
+    FILE = 4
+    VIDEO = 5
+
+
+class MediaType(IntEnum):
+    IMAGE = 1
+    VIDEO = 2
+    FILE = 3
+    VOICE = 4
+
+
+ContentType = Literal["text", "image", "voice", "file", "video"]
+
+
+@dataclass
+class CDNMedia:
+    encrypt_query_param: str
+    aes_key: str
+    encrypt_type: int | None = None
+
+
+@dataclass
+class ImageContent:
+    media: CDNMedia | None = None
+    thumb_media: CDNMedia | None = None
+    aes_key: str | None = None
+    url: str | None = None
+    width: int | None = None
+    height: int | None = None
+
+
+@dataclass
+class VoiceContent:
+    media: CDNMedia | None = None
+    text: str | None = None
+    duration_ms: int | None = None
+    encode_type: int | None = None
+
+
+@dataclass
+class FileContent:
+    media: CDNMedia | None = None
+    file_name: str | None = None
+    md5: str | None = None
+    size: int | None = None
+
+
+@dataclass
+class VideoContent:
+    media: CDNMedia | None = None
+    thumb_media: CDNMedia | None = None
+    duration_ms: int | None = None
+    width: int | None = None
+    height: int | None = None
+
+
+@dataclass
+class QuotedMessage:
+    title: str | None = None
+    text: str | None = None
+    type: ContentType | None = None
+
+
+@dataclass
+class Credentials:
+    token: str
+    base_url: str
+    account_id: str
+    user_id: str
+    saved_at: str | None = None
+
+
+@dataclass
+class IncomingMessage:
+    user_id: str
+    text: str
+    type: ContentType
+    timestamp: datetime
+    images: list[ImageContent] = field(default_factory=list)
+    voices: list[VoiceContent] = field(default_factory=list)
+    files: list[FileContent] = field(default_factory=list)
+    videos: list[VideoContent] = field(default_factory=list)
+    quoted_message: QuotedMessage | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+    _context_token: str = ""

wechatbot_sdk-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+wechatbot/__init__.py,sha256=zZ0eqRuol473U_pGxWEeGwFmSQOLsmjMMde7FQteueQ,877
+wechatbot/auth.py,sha256=O61lP3Zy297Zu92NxKeEm8PFTDAm_YmMRLbFLPeiuD8,4249
+wechatbot/client.py,sha256=aWxW86I1C6ONF-ZUa_m83_oANq8YdNf2UQq0yYty1Z4,13708
+wechatbot/crypto.py,sha256=_vfwQRB8-QHABSzgzg258uuDYxsdAvG1HKNZtkhw85w,2847
+wechatbot/errors.py,sha256=tuV_IXDBYffM1fwfiaTGmuoNW4N06m9bWE2MP7knvVs,1490
+wechatbot/protocol.py,sha256=qx6GANMZ1RXvHKl-W1TftveLcAHFQka3it65Xs9L3rE,4929
+wechatbot/types.py,sha256=vJeV8Sr1RKH8hhdK3RfSJD6F1OCOvnuw7WfQk1dGm6I,2198
+wechatbot_sdk-0.1.0.dist-info/METADATA,sha256=M7U8mcmJU1vS9xpqWgIHQPvNzT5AxAzKaPNB4TiTWkw,3600
+wechatbot_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+wechatbot_sdk-0.1.0.dist-info/RECORD,,

wechatbot_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any