imchat 0.0.0__py3-none-any.whl

imchat/__init__.py

@@ -0,0 +1 @@
+from .version import __version__

imchat/version.py

@@ -0,0 +1 @@
+__version__ = '0.0.0'

imchat/wechat/__init__.py

@@ -0,0 +1,64 @@
+from .client import WeChatClient
+from .types import (
+    WeixinMessage,
+    MessageItem,
+    TextItem,
+    ImageItem,
+    VoiceItem,
+    FileItem,
+    VideoItem,
+    CDNMedia,
+    SendMessageReq,
+    SendTypingReq,
+    GetUpdatesReq,
+    GetUpdatesResp,
+    GetUploadUrlReq,
+    GetUploadUrlResp,
+    GetConfigResp,
+    BaseInfo,
+    UploadMediaType,
+    MessageType,
+    MessageItemType,
+    MessageState,
+    TypingStatus,
+)
+from .auth import WeChatAuth
+from .exceptions import (
+    WeChatError,
+    WeChatAPIError,
+    WeChatAuthError,
+    WeChatSessionExpired,
+    WeChatCDNError,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "WeChatClient",
+    "WeChatAuth",
+    "WeixinMessage",
+    "MessageItem",
+    "TextItem",
+    "ImageItem",
+    "VoiceItem",
+    "FileItem",
+    "VideoItem",
+    "CDNMedia",
+    "SendMessageReq",
+    "SendTypingReq",
+    "GetUpdatesReq",
+    "GetUpdatesResp",
+    "GetUploadUrlReq",
+    "GetUploadUrlResp",
+    "GetConfigResp",
+    "BaseInfo",
+    "UploadMediaType",
+    "MessageType",
+    "MessageItemType",
+    "MessageState",
+    "TypingStatus",
+    "WeChatError",
+    "WeChatAPIError",
+    "WeChatAuthError",
+    "WeChatSessionExpired",
+    "WeChatCDNError",
+]

imchat/wechat/api.py

@@ -0,0 +1,197 @@
+import json
+import base64
+import secrets
+from typing import Optional, Dict, Any
+import httpx
+
+from .types import (
+    BaseInfo,
+    GetUpdatesReq,
+    GetUpdatesResp,
+    GetUploadUrlReq,
+    GetUploadUrlResp,
+    SendMessageReq,
+    SendTypingReq,
+    GetConfigResp,
+)
+from .exceptions import WeChatAPIError, WeChatSessionExpired
+
+
+DEFAULT_LONG_POLL_TIMEOUT_MS = 35_000
+DEFAULT_API_TIMEOUT_MS = 15_000
+DEFAULT_CONFIG_TIMEOUT_MS = 10_000
+SESSION_EXPIRED_ERRCODE = -14
+
+
+class WeChatAPIClient:
+    """微信 ilink API 客户端"""
+
+    def __init__(
+        self,
+        base_url: str,
+        token: Optional[str] = None,
+        ilink_app_id: str = "bot",
+        channel_version: str = "1.0.0",
+        timeout_ms: int = DEFAULT_API_TIMEOUT_MS,
+        long_poll_timeout_ms: int = DEFAULT_LONG_POLL_TIMEOUT_MS,
+    ):
+        self.base_url = base_url.rstrip("/") + "/"
+        self.token = token
+        self.ilink_app_id = ilink_app_id
+        self.channel_version = channel_version
+        self.timeout_ms = timeout_ms
+        self.long_poll_timeout_ms = long_poll_timeout_ms
+        self._client = httpx.AsyncClient()
+
+    def _build_client_version(self) -> int:
+        """iLink-App-ClientVersion: uint32 encoded as 0x00MMNNPP"""
+        parts = self.channel_version.split(".")
+        major = int(parts[0]) if len(parts) > 0 else 0
+        minor = int(parts[1]) if len(parts) > 1 else 0
+        patch = int(parts[2]) if len(parts) > 2 else 0
+        return ((major & 0xFF) << 16) | ((minor & 0xFF) << 8) | (patch & 0xFF)
+
+    def _random_wechat_uin(self) -> str:
+        """X-WECHAT-UIN header: random uint32 -> decimal string -> base64"""
+        uint32 = secrets.randbits(32)
+        return base64.b64encode(str(uint32).encode("utf-8")).decode("utf-8")
+
+    def _build_common_headers(self) -> Dict[str, str]:
+        headers = {
+            "iLink-App-Id": self.ilink_app_id,
+            "iLink-App-ClientVersion": str(self._build_client_version()),
+        }
+        return headers
+
+    def _build_post_headers(self, body: str) -> Dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "AuthorizationType": "ilink_bot_token",
+            "Content-Length": str(len(body.encode("utf-8"))),
+            "X-WECHAT-UIN": self._random_wechat_uin(),
+            **self._build_common_headers(),
+        }
+        if self.token and self.token.strip():
+            headers["Authorization"] = f"Bearer {self.token.strip()}"
+        return headers
+
+    def _build_base_info(self) -> Dict[str, Any]:
+        return {"channel_version": self.channel_version}
+
+    async def _api_get(self, endpoint: str, timeout_ms: Optional[int] = None) -> str:
+        """GET 请求"""
+        url = self.base_url + endpoint.lstrip("/")
+        headers = self._build_common_headers()
+        timeout = timeout_ms or self.timeout_ms
+
+        try:
+            resp = await self._client.get(url, headers=headers, timeout=timeout / 1000)
+        except httpx.TimeoutException:
+            raise WeChatAPIError(f"GET {endpoint} timeout after {timeout}ms")
+
+        text = resp.text
+        if resp.status_code >= 400:
+            raise WeChatAPIError(
+                f"GET {endpoint} {resp.status_code}: {text}",
+                status_code=resp.status_code,
+                response_text=text,
+            )
+        return text
+
+    async def _api_post(
+        self, endpoint: str, body_dict: Dict[str, Any], timeout_ms: Optional[int] = None
+    ) -> str:
+        """POST JSON 请求"""
+        url = self.base_url + endpoint.lstrip("/")
+        body = json.dumps(body_dict, ensure_ascii=False)
+        headers = self._build_post_headers(body)
+        timeout = timeout_ms or self.timeout_ms
+
+        try:
+            resp = await self._client.post(
+                url, headers=headers, content=body.encode("utf-8"), timeout=timeout / 1000
+            )
+        except httpx.TimeoutException:
+            raise WeChatAPIError(f"POST {endpoint} timeout after {timeout}ms")
+
+        text = resp.text
+        if resp.status_code >= 400:
+            raise WeChatAPIError(
+                f"POST {endpoint} {resp.status_code}: {text}",
+                status_code=resp.status_code,
+                response_text=text,
+            )
+        return text
+
+    async def get_updates(self, get_updates_buf: str = "") -> GetUpdatesResp:
+        """长轮询获取消息更新"""
+        try:
+            text = await self._api_post(
+                "ilink/bot/getupdates",
+                {
+                    "get_updates_buf": get_updates_buf,
+                    "base_info": self._build_base_info(),
+                },
+                timeout_ms=self.long_poll_timeout_ms,
+            )
+            return GetUpdatesResp.from_dict(json.loads(text))
+        except httpx.TimeoutException:
+            # 长轮询超时是正常的,返回空响应让调用方重试
+            return GetUpdatesResp(
+                ret=0, msgs=[], get_updates_buf=get_updates_buf
+            )
+
+    async def get_upload_url(self, req: GetUploadUrlReq) -> GetUploadUrlResp:
+        """获取预签名的 CDN 上传 URL"""
+        body = req.to_dict()
+        body["base_info"] = self._build_base_info()
+        text = await self._api_post("ilink/bot/getuploadurl", body)
+        return GetUploadUrlResp.from_dict(json.loads(text))
+
+    async def send_message(self, req: SendMessageReq) -> None:
+        """发送单条消息"""
+        body = req.to_dict()
+        if body.get("msg"):
+            body["msg"]["base_info"] = self._build_base_info()
+        await self._api_post("ilink/bot/sendmessage", body)
+
+    async def get_config(
+        self, ilink_user_id: str, context_token: Optional[str] = None
+    ) -> GetConfigResp:
+        """获取用户配置 (包含 typing_ticket)"""
+        body = {
+            "ilink_user_id": ilink_user_id,
+            "base_info": self._build_base_info(),
+        }
+        if context_token:
+            body["context_token"] = context_token
+        text = await self._api_post(
+            "ilink/bot/getconfig", body, timeout_ms=DEFAULT_CONFIG_TIMEOUT_MS
+        )
+        return GetConfigResp.from_dict(json.loads(text))
+
+    async def send_typing(self, req: SendTypingReq) -> None:
+        """发送 typing 指示器"""
+        body = req.to_dict()
+        body["base_info"] = self._build_base_info()
+        await self._api_post("ilink/bot/sendtyping", body, timeout_ms=DEFAULT_CONFIG_TIMEOUT_MS)
+
+    async def get_bot_qrcode(self, bot_type: str = "3") -> Dict[str, Any]:
+        """获取登录 QR 码"""
+        endpoint = f"ilink/bot/get_bot_qrcode?bot_type={bot_type}"
+        text = await self._api_get(endpoint)
+        return json.loads(text)
+
+    async def get_qrcode_status(
+        self, qrcode: str, timeout_ms: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """轮询 QR 码状态"""
+        endpoint = f"ilink/bot/get_qrcode_status?qrcode={qrcode}"
+        try:
+            text = await self._api_get(endpoint, timeout_ms=timeout_ms or 35_000)
+            return json.loads(text)
+        except httpx.TimeoutException:
+            return {"status": "wait"}
+
+    async def close(self):
+        await self._client.aclose()

imchat/wechat/auth.py

@@ -0,0 +1,235 @@
+import asyncio
+import uuid
+from typing import Optional, Dict, Any, Callable
+from dataclasses import dataclass
+
+from .api import WeChatAPIClient
+from .exceptions import WeChatAuthError
+
+
+DEFAULT_ILINK_BOT_TYPE = "3"
+FIXED_BASE_URL = "https://ilinkai.weixin.qq.com"
+ACTIVE_LOGIN_TTL_MS = 5 * 60_000
+QR_LONG_POLL_TIMEOUT_MS = 35_000
+MAX_QR_REFRESH_COUNT = 3
+
+
+@dataclass
+class QRCodeResponse:
+    qrcode: str
+    qrcode_img_content: str
+
+
+@dataclass
+class QRStatusResponse:
+    status: str  # "wait" | "scaned" | "confirmed" | "expired" | "scaned_but_redirect"
+    bot_token: Optional[str] = None
+    ilink_bot_id: Optional[str] = None
+    baseurl: Optional[str] = None
+    ilink_user_id: Optional[str] = None
+    redirect_host: Optional[str] = None
+
+
+@dataclass
+class LoginResult:
+    connected: bool
+    bot_token: Optional[str] = None
+    account_id: Optional[str] = None
+    base_url: Optional[str] = None
+    user_id: Optional[str] = None
+    message: str = ""
+
+
+class WeChatAuth:
+    """微信扫码认证管理器"""
+
+    def __init__(self, bot_type: str = DEFAULT_ILINK_BOT_TYPE):
+        self.bot_type = bot_type
+        self._active_logins: Dict[str, Dict[str, Any]] = {}
+
+    async def start_login(self, account_id: Optional[str] = None) -> Dict[str, str]:
+        """
+        开始微信扫码登录
+        返回: {"qrcode_url": "...", "session_key": "...", "message": "..."}
+        """
+        session_key = account_id or str(uuid.uuid4())
+
+        # 清理过期登录
+        now = asyncio.get_event_loop().time() * 1000
+        expired = [
+            k for k, v in self._active_logins.items()
+            if now - v.get("started_at", 0) > ACTIVE_LOGIN_TTL_MS
+        ]
+        for k in expired:
+            del self._active_logins[k]
+
+        # 检查是否有活跃的登录
+        existing = self._active_logins.get(session_key)
+        if existing and (now - existing["started_at"] < ACTIVE_LOGIN_TTL_MS):
+            return {
+                "qrcode_url": existing["qrcode_url"],
+                "session_key": session_key,
+                "message": "二维码已就绪，请使用微信扫描。",
+            }
+
+        client = WeChatAPIClient(FIXED_BASE_URL)
+        try:
+            resp = await client.get_bot_qrcode(self.bot_type)
+            qr = QRCodeResponse(
+                qrcode=resp["qrcode"],
+                qrcode_img_content=resp["qrcode_img_content"],
+            )
+        except Exception as e:
+            raise WeChatAuthError(f"Failed to fetch QR code: {e}")
+        finally:
+            await client.close()
+
+        self._active_logins[session_key] = {
+            "session_key": session_key,
+            "id": str(uuid.uuid4()),
+            "qrcode": qr.qrcode,
+            "qrcode_url": qr.qrcode_img_content,
+            "started_at": now,
+            "current_api_base_url": FIXED_BASE_URL,
+        }
+
+        return {
+            "qrcode_url": qr.qrcode_img_content,
+            "session_key": session_key,
+            "message": "使用微信扫描以下二维码，以完成连接。",
+        }
+
+    async def wait_for_login(
+        self,
+        session_key: str,
+        timeout_ms: int = 480_000,
+        verbose: bool = False,
+        on_status_change: Optional[Callable[[str], None]] = None,
+    ) -> LoginResult:
+        """
+        等待扫码登录完成
+        轮询 QR 码状态直到确认或超时
+        """
+        active_login = self._active_logins.get(session_key)
+        if not active_login:
+            return LoginResult(
+                connected=False,
+                message="当前没有进行中的登录，请先发起登录。",
+            )
+
+        now = asyncio.get_event_loop().time() * 1000
+        if now - active_login["started_at"] > ACTIVE_LOGIN_TTL_MS:
+            del self._active_logins[session_key]
+            return LoginResult(
+                connected=False,
+                message="二维码已过期，请重新生成。",
+            )
+
+        timeout = max(timeout_ms, 1000)
+        deadline = asyncio.get_event_loop().time() * 1000 + timeout
+        scanned_printed = False
+        qr_refresh_count = 1
+
+        active_login["current_api_base_url"] = FIXED_BASE_URL
+
+        while asyncio.get_event_loop().time() * 1000 < deadline:
+            current_base_url = active_login.get("current_api_base_url", FIXED_BASE_URL)
+            client = WeChatAPIClient(current_base_url)
+
+            try:
+                status_resp = await client.get_qrcode_status(
+                    active_login["qrcode"], timeout_ms=QR_LONG_POLL_TIMEOUT_MS
+                )
+            except Exception as e:
+                # 网络错误视为等待状态继续轮询
+                if verbose:
+                    print(f".", end="", flush=True)
+                await asyncio.sleep(1)
+                continue
+            finally:
+                await client.close()
+
+            status = status_resp.get("status", "wait")
+
+            if on_status_change:
+                on_status_change(status)
+
+            if status == "wait":
+                if verbose:
+                    print(".", end="", flush=True)
+
+            elif status == "scaned":
+                if not scanned_printed:
+                    if verbose:
+                        print("\n已扫码，在微信继续操作...")
+                    scanned_printed = True
+
+            elif status == "expired":
+                qr_refresh_count += 1
+                if qr_refresh_count > MAX_QR_REFRESH_COUNT:
+                    del self._active_logins[session_key]
+                    return LoginResult(
+                        connected=False,
+                        message="登录超时：二维码多次过期，请重新开始登录流程。",
+                    )
+
+                if verbose:
+                    print(f"\n二维码已过期，正在刷新...({qr_refresh_count}/{MAX_QR_REFRESH_COUNT})")
+
+                try:
+                    client = WeChatAPIClient(FIXED_BASE_URL)
+                    resp = await client.get_bot_qrcode(self.bot_type)
+                    await client.close()
+
+                    active_login["qrcode"] = resp["qrcode"]
+                    active_login["qrcode_url"] = resp["qrcode_img_content"]
+                    active_login["started_at"] = asyncio.get_event_loop().time() * 1000
+                    scanned_printed = False
+
+                    if verbose:
+                        print(f"新二维码已生成，请重新扫描")
+                        print(f"URL: {resp['qrcode_img_content']}")
+                except Exception as e:
+                    del self._active_logins[session_key]
+                    return LoginResult(
+                        connected=False,
+                        message=f"刷新二维码失败: {e}",
+                    )
+
+            elif status == "scaned_but_redirect":
+                redirect_host = status_resp.get("redirect_host")
+                if redirect_host:
+                    active_login["current_api_base_url"] = f"https://{redirect_host}"
+                else:
+                    pass  # 继续用当前 host
+
+            elif status == "confirmed":
+                bot_token = status_resp.get("bot_token")
+                ilink_bot_id = status_resp.get("ilink_bot_id")
+                baseurl = status_resp.get("baseurl")
+                ilink_user_id = status_resp.get("ilink_user_id")
+
+                if not ilink_bot_id:
+                    del self._active_logins[session_key]
+                    return LoginResult(
+                        connected=False,
+                        message="登录失败：服务器未返回 ilink_bot_id。",
+                    )
+
+                del self._active_logins[session_key]
+                return LoginResult(
+                    connected=True,
+                    bot_token=bot_token,
+                    account_id=ilink_bot_id,
+                    base_url=baseurl or FIXED_BASE_URL,
+                    user_id=ilink_user_id,
+                    message="与微信连接成功！",
+                )
+
+            await asyncio.sleep(1)
+
+        del self._active_logins[session_key]
+        return LoginResult(
+            connected=False,
+            message="登录超时，请重试。",
+        )

imchat/wechat/cdn.py

@@ -0,0 +1,200 @@
+import os
+import hashlib
+import secrets
+from typing import Optional, Tuple
+import httpx
+
+from .api import WeChatAPIClient
+from .crypto import encrypt_aes_ecb, aes_ecb_padded_size, decrypt_aes_ecb, parse_aes_key
+from .types import UploadMediaType, GetUploadUrlReq
+from .exceptions import WeChatCDNError
+
+
+ENABLE_CDN_URL_FALLBACK = True
+UPLOAD_MAX_RETRIES = 3
+
+
+class WeChatCDNClient:
+    """微信 CDN 客户端"""
+
+    def __init__(
+        self,
+        api_client: WeChatAPIClient,
+        cdn_base_url: str = "https://novac2c.cdn.weixin.qq.com/c2c",
+    ):
+        self.api = api_client
+        self.cdn_base_url = cdn_base_url.rstrip("/")
+        self._http = httpx.AsyncClient()
+
+    def _build_download_url(self, encrypted_query_param: str) -> str:
+        return f"{self.cdn_base_url}/download?encrypted_query_param={encrypted_query_param}"
+
+    def _build_upload_url(self, upload_param: str, filekey: str) -> str:
+        return (
+            f"{self.cdn_base_url}/upload?"
+            f"encrypted_query_param={upload_param}&filekey={filekey}"
+        )
+
+    async def upload_file(
+        self,
+        file_path: str,
+        to_user_id: str,
+        media_type: UploadMediaType = UploadMediaType.FILE,
+    ) -> "UploadedFileInfo":
+        """
+        上传本地文件到微信 CDN
+        流程: 读取文件 → 计算 MD5 → 生成 AES key → 获取上传 URL → 加密上传
+        """
+        with open(file_path, "rb") as f:
+            plaintext = f.read()
+
+        rawsize = len(plaintext)
+        rawfilemd5 = hashlib.md5(plaintext).hexdigest()
+        filesize = aes_ecb_padded_size(rawsize)
+        filekey = secrets.token_hex(16)
+        aeskey = secrets.token_bytes(16)
+
+        req = GetUploadUrlReq(
+            filekey=filekey,
+            media_type=int(media_type),
+            to_user_id=to_user_id,
+            rawsize=rawsize,
+            rawfilemd5=rawfilemd5,
+            filesize=filesize,
+            no_need_thumb=True,
+            aeskey=aeskey.hex(),
+        )
+
+        upload_url_resp = await self.api.get_upload_url(req)
+
+        upload_full_url = upload_url_resp.upload_full_url
+        upload_param = upload_url_resp.upload_param
+
+        if not upload_full_url and not upload_param:
+            raise WeChatCDNError("getUploadUrl returned no upload URL")
+
+        ciphertext = encrypt_aes_ecb(plaintext, aeskey)
+
+        # 确定 CDN 上传 URL
+        if upload_full_url and upload_full_url.strip():
+            cdn_url = upload_full_url.strip()
+        elif upload_param:
+            cdn_url = self._build_upload_url(upload_param, filekey)
+        else:
+            raise WeChatCDNError("CDN upload URL missing")
+
+        download_param = await self._upload_to_cdn(cdn_url, ciphertext, filekey)
+
+        return UploadedFileInfo(
+            filekey=filekey,
+            download_encrypted_query_param=download_param,
+            aeskey=aeskey.hex(),
+            file_size=rawsize,
+            file_size_ciphertext=filesize,
+        )
+
+    async def _upload_to_cdn(
+        self, cdn_url: str, ciphertext: bytes, filekey: str
+    ) -> str:
+        """上传加密后的数据到 CDN,带重试"""
+        last_error = None
+
+        for attempt in range(1, UPLOAD_MAX_RETRIES + 1):
+            try:
+                resp = await self._http.post(
+                    cdn_url,
+                    headers={"Content-Type": "application/octet-stream"},
+                    content=ciphertext,
+                )
+
+                if 400 <= resp.status_code < 500:
+                    err_msg = resp.headers.get("x-error-message") or resp.text
+                    raise WeChatCDNError(f"CDN upload client error {resp.status_code}: {err_msg}")
+
+                if resp.status_code != 200:
+                    err_msg = resp.headers.get("x-error-message") or f"status {resp.status_code}"
+                    raise WeChatCDNError(f"CDN upload server error: {err_msg}")
+
+                download_param = resp.headers.get("x-encrypted-param")
+                if not download_param:
+                    raise WeChatCDNError("CDN upload response missing x-encrypted-param header")
+
+                return download_param
+
+            except WeChatCDNError as e:
+                last_error = e
+                if "client error" in str(e):
+                    raise
+                if attempt < UPLOAD_MAX_RETRIES:
+                    continue
+                else:
+                    raise WeChatCDNError(
+                        f"CDN upload failed after {UPLOAD_MAX_RETRIES} attempts: {e}"
+                    )
+
+        raise last_error or WeChatCDNError("CDN upload failed")
+
+    async def download_and_decrypt(
+        self,
+        encrypted_query_param: str,
+        aes_key_base64: str,
+        full_url: Optional[str] = None,
+    ) -> bytes:
+        """下载并解密 CDN 文件"""
+        key = parse_aes_key(aes_key_base64)
+
+        if full_url:
+            url = full_url
+        elif ENABLE_CDN_URL_FALLBACK:
+            url = self._build_download_url(encrypted_query_param)
+        else:
+            raise WeChatCDNError("full_url is required (CDN URL fallback is disabled)")
+
+        resp = await self._http.get(url)
+        if not resp.is_success:
+            body = resp.text or "(unreadable)"
+            raise WeChatCDNError(f"CDN download {resp.status_code} {resp.reason_phrase}: {body}")
+
+        encrypted = resp.content
+        return decrypt_aes_ecb(encrypted, key)
+
+    async def download_plain(
+        self,
+        encrypted_query_param: str,
+        full_url: Optional[str] = None,
+    ) -> bytes:
+        """下载未加密的 CDN 文件"""
+        if full_url:
+            url = full_url
+        elif ENABLE_CDN_URL_FALLBACK:
+            url = self._build_download_url(encrypted_query_param)
+        else:
+            raise WeChatCDNError("full_url is required (CDN URL fallback is disabled)")
+
+        resp = await self._http.get(url)
+        if not resp.is_success:
+            body = resp.text or "(unreadable)"
+            raise WeChatCDNError(f"CDN download {resp.status_code} {resp.reason_phrase}: {body}")
+
+        return resp.content
+
+    async def close(self):
+        await self._http.aclose()
+
+
+class UploadedFileInfo:
+    """上传后的文件信息"""
+
+    def __init__(
+        self,
+        filekey: str,
+        download_encrypted_query_param: str,
+        aeskey: str,
+        file_size: int,
+        file_size_ciphertext: int,
+    ):
+        self.filekey = filekey
+        self.download_encrypted_query_param = download_encrypted_query_param
+        self.aeskey = aeskey
+        self.file_size = file_size
+        self.file_size_ciphertext = file_size_ciphertext