wechatbot-sdk 0.2.0__tar.gz → 0.3.0__tar.gz

{wechatbot_sdk-0.2.0 → wechatbot_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wechatbot-sdk
-Version: 0.2.0
+Version: 0.3.0
 Summary: WeChat iLink Bot SDK for Python — async, typed, production-grade
 License: MIT
 Requires-Python: >=3.9

{wechatbot_sdk-0.2.0 → wechatbot_sdk-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wechatbot-sdk"
-version = "0.2.0"
+version = "0.3.0"
 description = "WeChat iLink Bot SDK for Python — async, typed, production-grade"
 readme = "README.md"
 license = { text = "MIT" }

wechatbot_sdk-0.3.0/tests/test_bot_agent.py

@@ -0,0 +1,42 @@
+"""Tests for bot_agent sanitization."""
+
+from wechatbot.protocol import DEFAULT_BOT_AGENT, sanitize_bot_agent
+
+
+def test_empty_input_falls_back_to_default():
+    assert sanitize_bot_agent(None) == DEFAULT_BOT_AGENT
+    assert sanitize_bot_agent("") == DEFAULT_BOT_AGENT
+    assert sanitize_bot_agent("   ") == DEFAULT_BOT_AGENT
+
+
+def test_single_product():
+    assert sanitize_bot_agent("MyApp/1.2") == "MyApp/1.2"
+
+
+def test_product_with_comment():
+    assert sanitize_bot_agent("MyApp/1.2 (prod build)") == "MyApp/1.2 (prod build)"
+
+
+def test_multiple_products():
+    assert sanitize_bot_agent("MyApp/1.2 (prod) Lib/0.3") == "MyApp/1.2 (prod) Lib/0.3"
+
+
+def test_normalizes_whitespace():
+    assert sanitize_bot_agent("  MyApp/1.2   Lib/0.3 ") == "MyApp/1.2 Lib/0.3"
+
+
+def test_invalid_input_falls_back_wholesale():
+    assert sanitize_bot_agent("no-slash") == DEFAULT_BOT_AGENT
+    assert sanitize_bot_agent("bad name/1.0 !!!") == DEFAULT_BOT_AGENT
+    assert sanitize_bot_agent("(orphan comment)") == DEFAULT_BOT_AGENT
+    assert sanitize_bot_agent("App/1.0 (unclosed") == DEFAULT_BOT_AGENT
+    assert sanitize_bot_agent("App/1.0 (nested (comment))") == DEFAULT_BOT_AGENT
+
+
+def test_overlong_tokens_rejected():
+    assert sanitize_bot_agent("a" * 33 + "/1.0") == DEFAULT_BOT_AGENT
+    assert sanitize_bot_agent("App/" + "1" * 33) == DEFAULT_BOT_AGENT
+
+
+def test_over_byte_cap_rejected():
+    assert sanitize_bot_agent(("App/1.0 " * 40).strip()) == DEFAULT_BOT_AGENT

{wechatbot_sdk-0.2.0 → wechatbot_sdk-0.3.0}/wechatbot/auth.py

@@ -57,6 +57,17 @@ async def clear_credentials(path: Path | None = None) -> None:
     target.unlink(missing_ok=True)
 
 
+async def _read_verify_code(is_retry: bool) -> str:
+    """Default pairing-code prompt: read a line from stdin."""
+    prompt = (
+        "Code mismatch — enter the pairing code shown in WeChat again: "
+        if is_retry
+        else "Enter the pairing code shown in WeChat on your phone: "
+    )
+    code = await asyncio.to_thread(input, prompt)
+    return code.strip()
+
+
 async def login(
     api: ILinkApi,
     *,
@@ -66,12 +77,16 @@ async def login(
     on_qr_url: Callable[[str], None] | None = None,
     on_scanned: Callable[[], None] | None = None,
     on_expired: Callable[[], None] | None = None,
+    on_verify_code: Callable[[bool], str] | 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
+    stored = await load_credentials(cred_path)
+    if not force and stored:
+        return stored
+
+    # Send known local tokens so the server can answer binded_redirect
+    # instead of issuing a duplicate session for an already-bound bot.
+    local_token_list = [stored.token] if stored and stored.token else []
 
     qr_refresh_count = 0
     while True:
@@ -81,7 +96,7 @@ async def login(
                 f"QR code expired {MAX_QR_REFRESH_COUNT} times — login aborted"
             )
 
-        qr = await api.get_qr_code(FIXED_QR_BASE_URL)
+        qr = await api.get_qr_code(FIXED_QR_BASE_URL, local_token_list)
         qr_url = qr["qrcode_img_content"]
 
         if on_qr_url:
@@ -91,13 +106,19 @@ async def login(
 
         last_status = ""
         current_poll_base_url = FIXED_QR_BASE_URL
+        # Pairing code awaiting server verification (pair-code login flow)
+        pending_verify_code: str | None = None
         while True:
-            status = await api.poll_qr_status(current_poll_base_url, qr["qrcode"])
+            status = await api.poll_qr_status(
+                current_poll_base_url, qr["qrcode"], pending_verify_code
+            )
             current = status["status"]
 
             if current != last_status:
                 last_status = current
                 if current == "scaned":
+                    # A pending pairing code that leads back to scaned was accepted
+                    pending_verify_code = None
                     if on_scanned:
                         on_scanned()
                     else:
@@ -129,6 +150,38 @@ async def login(
                 await save_credentials(creds, cred_path)
                 return creds
 
+            # Pair-code challenge: ask the user for the digits shown in WeChat
+            if current == "need_verifycode":
+                is_retry = pending_verify_code is not None
+                if on_verify_code:
+                    pending_verify_code = on_verify_code(is_retry)
+                else:
+                    pending_verify_code = await _read_verify_code(is_retry)
+                continue  # Re-poll immediately with the code attached
+
+            # Too many wrong pairing codes: server blocked this QR — get a new one
+            if current == "verify_code_blocked":
+                print(
+                    "[wechatbot] Pairing code blocked after repeated mismatches "
+                    "— requesting new QR",
+                    file=sys.stderr,
+                )
+                pending_verify_code = None
+                break  # Outer loop requests a new QR (counts toward refresh limit)
+
+            # Already bound to this client: reuse existing local credentials
+            if current == "binded_redirect":
+                if stored:
+                    print(
+                        "[wechatbot] Bot already bound — reusing stored credentials",
+                        file=sys.stderr,
+                    )
+                    return stored
+                raise AuthError(
+                    "Server reports this bot is already bound to this client "
+                    "(binded_redirect), but no local credentials were found"
+                )
+
             # Handle IDC redirect
             if current == "scaned_but_redirect":
                 redirect_host = status.get("redirect_host")

{wechatbot_sdk-0.2.0 → wechatbot_sdk-0.3.0}/wechatbot/client.py

@@ -77,6 +77,8 @@ class WeChatBot:
         on_scanned: Callable[[], None] | None = None,
         on_expired: Callable[[], None] | None = None,
         on_error: Callable[[Exception], None] | None = None,
+        on_verify_code: Callable[[bool], str] | None = None,
+        bot_agent: str | None = None,
     ) -> None:
         self._base_url = base_url or DEFAULT_BASE_URL
         self._cred_path = Path(cred_path) if cred_path else None
@@ -84,8 +86,9 @@ class WeChatBot:
         self._on_scanned = on_scanned
         self._on_expired = on_expired
         self._on_error = on_error
+        self._on_verify_code = on_verify_code
 
-        self._api = ILinkApi()
+        self._api = ILinkApi(bot_agent=bot_agent)
         self._credentials: Credentials | None = None
         self._context_tokens: dict[str, str] = {}
         self._handlers: list[MessageHandler] = []
@@ -104,6 +107,7 @@ class WeChatBot:
             on_qr_url=self._on_qr_url,
             on_scanned=self._on_scanned,
             on_expired=self._on_expired,
+            on_verify_code=self._on_verify_code,
         )
         self._credentials = creds
         self._base_url = creds.base_url
@@ -252,6 +256,13 @@ class WeChatBot:
         """Start the long-poll loop. Blocks until stop() is called."""
         creds = self._require_creds()
         self._stopped = False
+
+        # Tell the server we're coming online (non-fatal)
+        try:
+            await self._api.notify_start(creds.base_url, creds.token)
+        except Exception as e:
+            self._log(f"notify_start failed (ignored): {e}")
+
         self._log("Long-poll started")
         retry_delay = 1.0
 
@@ -301,6 +312,14 @@ class WeChatBot:
                 await asyncio.sleep(retry_delay)
                 retry_delay = min(retry_delay * 2, 10.0)
 
+        # Tell the server we're going offline (non-fatal).
+        # Credentials may have rotated after a mid-poll re-login, so re-read them.
+        try:
+            creds = self._require_creds()
+            await self._api.notify_stop(creds.base_url, creds.token)
+        except Exception as e:
+            self._log(f"notify_stop failed (ignored): {e}")
+
         self._log("Long-poll stopped")
 
     def stop(self) -> None:

{wechatbot_sdk-0.2.0 → wechatbot_sdk-0.3.0}/wechatbot/protocol.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import base64
 import json
 import os
+import re
 import struct
 from importlib.metadata import version as pkg_version
 from typing import Any
@@ -67,8 +68,32 @@ def auth_headers(token: str) -> dict[str, str]:
     }
 
 
-def _base_info() -> dict[str, str]:
-    return {"channel_version": CHANNEL_VERSION}
+# Default bot_agent when none is configured or the configured value is invalid.
+DEFAULT_BOT_AGENT = f"WeChatBot/{CHANNEL_VERSION}"
+
+# Maximum length (bytes) of the sanitized bot_agent string.
+_BOT_AGENT_MAX_LEN = 256
+
+# UA-style grammar (matches openclaw-weixin):
+#   bot_agent = product *( SP product )
+#   product   = name "/" version [ SP "(" comment ")" ]
+_PRODUCT = r"[A-Za-z0-9_.\-]{1,32}/[A-Za-z0-9_.+\-]{1,32}(?: \([\x20-\x27\x2A-\x7E]{1,64}\))?"
+_BOT_AGENT_RE = re.compile(rf"^{_PRODUCT}(?: {_PRODUCT})*$")
+
+
+def sanitize_bot_agent(raw: str | None) -> str:
+    """Validate a user-supplied bot_agent into a wire-safe string.
+
+    Unlike upstream openclaw-weixin (which salvages the valid tokens out of a
+    partially invalid string), any invalid input falls back to
+    DEFAULT_BOT_AGENT wholesale — simpler and just as safe on the wire.
+    """
+    if not raw:
+        return DEFAULT_BOT_AGENT
+    normalized = " ".join(raw.split())
+    if not normalized or len(normalized.encode("utf-8")) > _BOT_AGENT_MAX_LEN:
+        return DEFAULT_BOT_AGENT
+    return normalized if _BOT_AGENT_RE.match(normalized) else DEFAULT_BOT_AGENT
 
 
 async def _parse_response(resp: aiohttp.ClientResponse, label: str) -> dict[str, Any]:
@@ -85,9 +110,10 @@ async def _parse_response(resp: aiohttp.ClientResponse, label: str) -> dict[str,
         )
 
     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})"
+    errcode = payload.get("errcode")
+    if (isinstance(ret, int) and ret != 0) or (isinstance(errcode, int) and errcode != 0):
+        code = errcode if isinstance(errcode, int) and errcode != 0 else (ret or 0)
+        msg = payload.get("errmsg") or f"{label} failed (ret={ret} errcode={errcode})"
         raise ApiError(msg, http_status=resp.status, errcode=code, payload=payload)
 
     return payload
@@ -96,17 +122,41 @@ async def _parse_response(resp: aiohttp.ClientResponse, label: str) -> dict[str,
 class ILinkApi:
     """Low-level iLink API client. Each method maps 1:1 to an endpoint."""
 
-    def __init__(self) -> None:
+    def __init__(self, *, bot_agent: str | None = None) -> None:
         self._timeout = aiohttp.ClientTimeout(total=45)
+        self._bot_agent = sanitize_bot_agent(bot_agent)
+
+    def _base_info(self) -> dict[str, str]:
+        return {"channel_version": CHANNEL_VERSION, "bot_agent": self._bot_agent}
+
+    async def get_qr_code(
+        self, base_url: str, local_token_list: list[str] | None = None
+    ) -> dict[str, Any]:
+        """Request a login QR code.
 
-    async def get_qr_code(self, base_url: str) -> dict[str, Any]:
+        local_token_list carries up to 10 known local bot tokens (newest
+        first) so the server can answer binded_redirect for an already-bound
+        bot instead of issuing a duplicate session.
+        """
         url = f"{base_url}/ilink/bot/get_bot_qrcode?bot_type=3"
+        body = {"local_token_list": local_token_list or []}
         async with aiohttp.ClientSession() as session:
-            async with session.get(url, headers=_common_headers()) as resp:
+            async with session.post(
+                url, headers=_common_headers(), json=body
+            ) as resp:
                 return await _parse_response(resp, "get_bot_qrcode")
 
-    async def poll_qr_status(self, base_url: str, qrcode: str) -> dict[str, Any]:
+    async def poll_qr_status(
+        self, base_url: str, qrcode: str, verify_code: str | None = None
+    ) -> dict[str, Any]:
+        """Poll the QR scan status.
+
+        verify_code submits a pairing code after the server answered
+        need_verifycode (the digits shown in WeChat on the user's phone).
+        """
         url = f"{base_url}/ilink/bot/get_qrcode_status?qrcode={quote(qrcode, safe='')}"
+        if verify_code:
+            url += f"&verify_code={quote(verify_code, safe='')}"
         async with aiohttp.ClientSession() as session:
             async with session.get(
                 url, headers=_common_headers()
@@ -116,13 +166,13 @@ class ILinkApi:
     async def get_updates(
         self, base_url: str, token: str, cursor: str
     ) -> dict[str, Any]:
-        body = {"get_updates_buf": cursor, "base_info": _base_info()}
+        body = {"get_updates_buf": cursor, "base_info": self._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()}
+        body = {"msg": msg, "base_info": self._base_info()}
         return await self._post(base_url, "/ilink/bot/sendmessage", token, body)
 
     async def get_config(
@@ -131,7 +181,7 @@ class ILinkApi:
         body = {
             "ilink_user_id": user_id,
             "context_token": context_token,
-            "base_info": _base_info(),
+            "base_info": self._base_info(),
         }
         return await self._post(base_url, "/ilink/bot/getconfig", token, body)
 
@@ -147,10 +197,20 @@ class ILinkApi:
             "ilink_user_id": user_id,
             "typing_ticket": ticket,
             "status": status,
-            "base_info": _base_info(),
+            "base_info": self._base_info(),
         }
         return await self._post(base_url, "/ilink/bot/sendtyping", token, body)
 
+    async def notify_start(self, base_url: str, token: str) -> dict[str, Any]:
+        """Notify the server that this client is starting (coming online)."""
+        body = {"base_info": self._base_info()}
+        return await self._post(base_url, "/ilink/bot/msg/notifystart", token, body)
+
+    async def notify_stop(self, base_url: str, token: str) -> dict[str, Any]:
+        """Notify the server that this client is stopping (going offline)."""
+        body = {"base_info": self._base_info()}
+        return await self._post(base_url, "/ilink/bot/msg/notifystop", token, body)
+
     @staticmethod
     def build_media_message(
         user_id: str,
@@ -206,7 +266,7 @@ class ILinkApi:
             "filesize": filesize,
             "no_need_thumb": no_need_thumb,
             "aeskey": aeskey,
-            "base_info": _base_info(),
+            "base_info": self._base_info(),
         }
         return await self._post(base_url, "/ilink/bot/getuploadurl", token, body)