openilink-sdk-python 0.1.0__tar.gz

openilink_sdk_python-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: openilink-sdk-python
+Version: 0.1.0
+Summary: Python client for the Weixin iLink Bot API
+License: MIT
+Project-URL: Homepage, https://github.com/openilink/openilink-sdk-python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: qrcode>=7.0
+
+# openilink-sdk-python
+
+Python SDK for the Weixin iLink Bot API.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from openilink import Client, LoginCallbacks, MonitorOptions, extract_text
+
+client = Client()
+
+# QR code login
+result = client.login_with_qr(
+    callbacks=LoginCallbacks(
+        on_qrcode=lambda url: print(f"Scan: {url}"),
+        on_scanned=lambda: print("Scanned!"),
+    )
+)
+print(f"Connected: BotID={result.bot_id}")
+
+# Echo bot
+client.monitor(
+    lambda msg: client.push(msg.from_user_id, "echo: " + extract_text(msg)),
+    opts=MonitorOptions(
+        on_error=lambda e: print(f"Error: {e}"),
+    ),
+)
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `Client(token, base_url, ...)` | Create client |
+| `client.login_with_qr(callbacks)` | QR code login |
+| `client.monitor(handler, opts)` | Long-poll message loop |
+| `client.send_text(to, text, context_token)` | Send text message |
+| `client.push(to, text)` | Send with cached context token |
+| `client.send_typing(user_id, ticket, status)` | Typing indicator |
+| `client.get_config(user_id, context_token)` | Get bot config |
+| `client.get_upload_url(req)` | Get CDN upload URL |
+| `client.stop()` | Stop monitor loop |
+| `extract_text(msg)` | Extract first text from message |

openilink_sdk_python-0.1.0/README.md

@@ -0,0 +1,49 @@
+# openilink-sdk-python
+
+Python SDK for the Weixin iLink Bot API.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from openilink import Client, LoginCallbacks, MonitorOptions, extract_text
+
+client = Client()
+
+# QR code login
+result = client.login_with_qr(
+    callbacks=LoginCallbacks(
+        on_qrcode=lambda url: print(f"Scan: {url}"),
+        on_scanned=lambda: print("Scanned!"),
+    )
+)
+print(f"Connected: BotID={result.bot_id}")
+
+# Echo bot
+client.monitor(
+    lambda msg: client.push(msg.from_user_id, "echo: " + extract_text(msg)),
+    opts=MonitorOptions(
+        on_error=lambda e: print(f"Error: {e}"),
+    ),
+)
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `Client(token, base_url, ...)` | Create client |
+| `client.login_with_qr(callbacks)` | QR code login |
+| `client.monitor(handler, opts)` | Long-poll message loop |
+| `client.send_text(to, text, context_token)` | Send text message |
+| `client.push(to, text)` | Send with cached context token |
+| `client.send_typing(user_id, ticket, status)` | Typing indicator |
+| `client.get_config(user_id, context_token)` | Get bot config |
+| `client.get_upload_url(req)` | Get CDN upload URL |
+| `client.stop()` | Stop monitor loop |
+| `extract_text(msg)` | Extract first text from message |

openilink_sdk_python-0.1.0/openilink/__init__.py

@@ -0,0 +1,116 @@
+"""openilink-sdk-python - A Python client for the Weixin iLink Bot API.
+
+The SDK covers the full lifecycle: QR-code login, long-poll message
+monitoring, text/media sending, typing indicators, and proactive push.
+
+Basic usage::
+
+    from openilink import Client, LoginCallbacks, MonitorOptions, extract_text
+
+    client = Client()
+    result = client.login_with_qr()
+    client.monitor(lambda msg: client.push(msg.from_user_id, "echo: " + extract_text(msg)))
+"""
+
+from .types import (
+    BaseInfo,
+    CDNMedia,
+    FileItem,
+    GetConfigResp,
+    GetUpdatesResp,
+    GetUploadURLResp,
+    ImageItem,
+    LoginResult,
+    MessageItem,
+    MessageItemType,
+    MessageState,
+    MessageType,
+    QRCodeResponse,
+    QRStatusResponse,
+    RefMessage,
+    TextItem,
+    TypingStatus,
+    UploadMediaType,
+    VideoItem,
+    VoiceItem,
+    WeixinMessage,
+)
+from .errors import APIError, HTTPError, NoContextTokenError
+from .helpers import extract_text, print_qrcode
+from .auth import LoginCallbacks
+from .monitor import MonitorOptions
+
+# Import Client last and attach high-level methods
+from .client import Client as _Client
+from . import auth as _auth
+from . import monitor as _monitor
+
+
+class Client(_Client):
+    """Weixin iLink Bot API client with login and monitor support."""
+
+    def login_with_qr(
+        self,
+        callbacks: LoginCallbacks | None = None,
+        timeout: float = _auth.DEFAULT_LOGIN_TIMEOUT,
+    ) -> LoginResult:
+        """Perform the full QR code login flow.
+
+        On success the client's token and base_url are updated automatically.
+        """
+        return _auth.login_with_qr(self, callbacks, timeout)
+
+    def fetch_qr_code(self) -> QRCodeResponse:
+        """Request a new login QR code from the API."""
+        return _auth.fetch_qr_code(self)
+
+    def poll_qr_status(self, qrcode: str) -> QRStatusResponse:
+        """Poll the scan status of a QR code."""
+        return _auth.poll_qr_status(self, qrcode)
+
+    def monitor(
+        self,
+        handler,
+        opts: MonitorOptions | None = None,
+    ) -> None:
+        """Run a long-poll loop, invoking handler for each inbound message.
+
+        Blocks until client.stop() is called.
+        """
+        _monitor.monitor(self, handler, opts)
+
+
+__all__ = [
+    "Client",
+    "LoginCallbacks",
+    "MonitorOptions",
+    # types
+    "BaseInfo",
+    "CDNMedia",
+    "FileItem",
+    "GetConfigResp",
+    "GetUpdatesResp",
+    "GetUploadURLResp",
+    "ImageItem",
+    "LoginResult",
+    "MessageItem",
+    "MessageItemType",
+    "MessageState",
+    "MessageType",
+    "QRCodeResponse",
+    "QRStatusResponse",
+    "RefMessage",
+    "TextItem",
+    "TypingStatus",
+    "UploadMediaType",
+    "VideoItem",
+    "VoiceItem",
+    "WeixinMessage",
+    # errors
+    "APIError",
+    "HTTPError",
+    "NoContextTokenError",
+    # helpers
+    "extract_text",
+    "print_qrcode",
+]

openilink_sdk_python-0.1.0/openilink/auth.py

@@ -0,0 +1,131 @@
+"""QR code login flow for the iLink Bot API."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import TYPE_CHECKING, Callable, Optional
+from urllib.parse import urljoin, quote
+
+from .helpers import ensure_trailing_slash
+from .types import LoginResult, QRCodeResponse, QRStatusResponse
+
+if TYPE_CHECKING:
+    from .client import Client
+
+MAX_QR_REFRESH_COUNT = 3
+QR_LONG_POLL_TIMEOUT = 40  # seconds
+DEFAULT_LOGIN_TIMEOUT = 8 * 60  # 8 minutes
+
+
+class LoginCallbacks:
+    """Receives events during the QR login flow."""
+
+    def __init__(
+        self,
+        on_qrcode: Optional[Callable[[str], None]] = None,
+        on_scanned: Optional[Callable[[], None]] = None,
+        on_expired: Optional[Callable[[int, int], None]] = None,
+    ):
+        self.on_qrcode = on_qrcode
+        self.on_scanned = on_scanned
+        self.on_expired = on_expired
+
+
+def fetch_qr_code(client: Client) -> QRCodeResponse:
+    """Request a new login QR code from the API."""
+    base = ensure_trailing_slash(client.base_url)
+    bot_type = client.bot_type or "3"
+    url = urljoin(base, "ilink/bot/get_bot_qrcode") + "?bot_type=" + quote(bot_type)
+    data = client._do_get(url, timeout=15)
+    d = json.loads(data)
+    return QRCodeResponse(
+        qrcode=d.get("qrcode", ""),
+        qrcode_img_content=d.get("qrcode_img_content", ""),
+    )
+
+
+def poll_qr_status(client: Client, qrcode: str) -> QRStatusResponse:
+    """Poll the scan status of a QR code."""
+    base = ensure_trailing_slash(client.base_url)
+    url = urljoin(base, "ilink/bot/get_qrcode_status") + "?qrcode=" + quote(qrcode)
+    headers = {"iLink-App-ClientVersion": "1"}
+    try:
+        data = client._do_get(url, extra_headers=headers, timeout=QR_LONG_POLL_TIMEOUT)
+    except Exception:
+        return QRStatusResponse(status="wait")
+    d = json.loads(data)
+    return QRStatusResponse(
+        status=d.get("status", ""),
+        bot_token=d.get("bot_token", ""),
+        ilink_bot_id=d.get("ilink_bot_id", ""),
+        baseurl=d.get("baseurl", ""),
+        ilink_user_id=d.get("ilink_user_id", ""),
+    )
+
+
+def login_with_qr(
+    client: Client,
+    callbacks: Optional[LoginCallbacks] = None,
+    timeout: float = DEFAULT_LOGIN_TIMEOUT,
+) -> LoginResult:
+    """Perform the full QR code login flow.
+
+    On success the client's token and base_url are updated automatically.
+    """
+    if callbacks is None:
+        callbacks = LoginCallbacks()
+
+    deadline = time.monotonic() + timeout
+
+    qr = fetch_qr_code(client)
+    if callbacks.on_qrcode:
+        callbacks.on_qrcode(qr.qrcode_img_content)
+
+    scanned_notified = False
+    refresh_count = 1
+    current_qr = qr.qrcode
+
+    while True:
+        if time.monotonic() > deadline:
+            return LoginResult(message="login timeout")
+
+        status = poll_qr_status(client, current_qr)
+
+        if status.status == "wait":
+            pass
+
+        elif status.status == "scaned":
+            if not scanned_notified:
+                scanned_notified = True
+                if callbacks.on_scanned:
+                    callbacks.on_scanned()
+
+        elif status.status == "expired":
+            refresh_count += 1
+            if refresh_count > MAX_QR_REFRESH_COUNT:
+                return LoginResult(message="QR code expired too many times")
+            if callbacks.on_expired:
+                callbacks.on_expired(refresh_count, MAX_QR_REFRESH_COUNT)
+            new_qr = fetch_qr_code(client)
+            current_qr = new_qr.qrcode
+            scanned_notified = False
+            if callbacks.on_qrcode:
+                callbacks.on_qrcode(new_qr.qrcode_img_content)
+
+        elif status.status == "confirmed":
+            if not status.ilink_bot_id:
+                return LoginResult(message="server did not return bot ID")
+            client.token = status.bot_token
+            if status.baseurl:
+                client.base_url = status.baseurl
+            return LoginResult(
+                connected=True,
+                bot_token=status.bot_token,
+                bot_id=status.ilink_bot_id,
+                base_url=status.baseurl,
+                user_id=status.ilink_user_id,
+                message="connected",
+            )
+
+        time.sleep(1)

openilink_sdk_python-0.1.0/openilink/client.py

@@ -0,0 +1,336 @@
+"""Core client for the Weixin iLink Bot API."""
+
+from __future__ import annotations
+
+import json
+import time
+import threading
+from typing import Any, Optional
+from urllib.parse import urljoin, quote
+
+import requests
+
+from .errors import HTTPError, NoContextTokenError
+from .helpers import ensure_trailing_slash, random_wechat_uin
+from .types import (
+    GetConfigResp,
+    GetUpdatesResp,
+    GetUploadURLResp,
+    MessageState,
+    MessageType,
+    TypingStatus,
+)
+
+DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com"
+DEFAULT_CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c"
+DEFAULT_BOT_TYPE = "3"
+
+_DEFAULT_LONG_POLL_TIMEOUT = 35
+_DEFAULT_API_TIMEOUT = 15
+_DEFAULT_CONFIG_TIMEOUT = 10
+
+
+class Client:
+    """Communicates with the Weixin iLink Bot API.
+
+    Basic usage::
+
+        client = Client("")
+        result = client.login_with_qr()
+        client.monitor(handler)
+    """
+
+    def __init__(
+        self,
+        token: str = "",
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        cdn_base_url: str = DEFAULT_CDN_BASE_URL,
+        bot_type: str = DEFAULT_BOT_TYPE,
+        version: str = "1.0.0",
+        session: Optional[requests.Session] = None,
+    ):
+        self.base_url = base_url
+        self.cdn_base_url = cdn_base_url
+        self.token = token
+        self.bot_type = bot_type
+        self.version = version
+        self._session = session or requests.Session()
+        self._context_tokens: dict[str, str] = {}
+        self._ctx_lock = threading.Lock()
+        self._stop_event = threading.Event()
+
+    # --- context token cache ---
+
+    def set_context_token(self, user_id: str, token: str) -> None:
+        with self._ctx_lock:
+            self._context_tokens[user_id] = token
+
+    def get_context_token(self, user_id: str) -> Optional[str]:
+        with self._ctx_lock:
+            return self._context_tokens.get(user_id)
+
+    # --- internal helpers ---
+
+    def _build_base_info(self) -> dict:
+        return {"channel_version": self.version}
+
+    def _build_headers(self, body: bytes) -> dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "AuthorizationType": "ilink_bot_token",
+            "Content-Length": str(len(body)),
+            "X-WECHAT-UIN": random_wechat_uin(),
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        return headers
+
+    def _do_post(self, endpoint: str, body: Any, timeout: float) -> bytes:
+        data = json.dumps(body, ensure_ascii=False).encode("utf-8")
+        base = ensure_trailing_slash(self.base_url)
+        url = urljoin(base, endpoint)
+        headers = self._build_headers(data)
+        resp = self._session.post(url, data=data, headers=headers, timeout=timeout)
+        if resp.status_code >= 400:
+            raise HTTPError(resp.status_code, resp.content)
+        return resp.content
+
+    def _do_get(
+        self,
+        url: str,
+        extra_headers: Optional[dict[str, str]] = None,
+        timeout: float = 15,
+    ) -> bytes:
+        headers = extra_headers or {}
+        resp = self._session.get(url, headers=headers, timeout=timeout)
+        if resp.status_code >= 400:
+            raise HTTPError(resp.status_code, resp.content)
+        return resp.content
+
+    # --- API methods ---
+
+    def get_updates(self, get_updates_buf: str = "") -> GetUpdatesResp:
+        """Long-poll for new messages. Returns empty response on timeout."""
+        req_body = {
+            "get_updates_buf": get_updates_buf,
+            "base_info": self._build_base_info(),
+        }
+        timeout = _DEFAULT_LONG_POLL_TIMEOUT + 5
+        try:
+            data = self._do_post("ilink/bot/getupdates", req_body, timeout)
+        except (requests.Timeout, requests.ConnectionError):
+            return GetUpdatesResp(ret=0, get_updates_buf=get_updates_buf)
+
+        return _parse_get_updates_resp(data)
+
+    def send_message(self, msg: dict) -> None:
+        """Send a raw message request."""
+        msg["base_info"] = self._build_base_info()
+        self._do_post("ilink/bot/sendmessage", msg, _DEFAULT_API_TIMEOUT)
+
+    def send_text(self, to: str, text: str, context_token: str) -> str:
+        """Send a plain text message. Returns the client_id."""
+        client_id = f"sdk-{int(time.time() * 1000)}"
+        msg = {
+            "msg": {
+                "to_user_id": to,
+                "client_id": client_id,
+                "message_type": int(MessageType.BOT),
+                "message_state": int(MessageState.FINISH),
+                "context_token": context_token,
+                "item_list": [
+                    {"type": 1, "text_item": {"text": text}},
+                ],
+            },
+        }
+        self.send_message(msg)
+        return client_id
+
+    def get_config(self, user_id: str, context_token: str) -> GetConfigResp:
+        """Fetch bot config (includes typing_ticket) for a user."""
+        req_body = {
+            "ilink_user_id": user_id,
+            "context_token": context_token,
+            "base_info": self._build_base_info(),
+        }
+        data = self._do_post("ilink/bot/getconfig", req_body, _DEFAULT_CONFIG_TIMEOUT)
+        d = json.loads(data)
+        return GetConfigResp(
+            ret=d.get("ret", 0),
+            errmsg=d.get("errmsg", ""),
+            typing_ticket=d.get("typing_ticket", ""),
+        )
+
+    def send_typing(
+        self, user_id: str, typing_ticket: str, status: TypingStatus = TypingStatus.TYPING
+    ) -> None:
+        """Send or cancel a typing indicator."""
+        req_body = {
+            "ilink_user_id": user_id,
+            "typing_ticket": typing_ticket,
+            "status": int(status),
+            "base_info": self._build_base_info(),
+        }
+        self._do_post("ilink/bot/sendtyping", req_body, _DEFAULT_CONFIG_TIMEOUT)
+
+    def get_upload_url(self, req: dict) -> GetUploadURLResp:
+        """Request a pre-signed CDN upload URL."""
+        req["base_info"] = self._build_base_info()
+        data = self._do_post("ilink/bot/getuploadurl", req, _DEFAULT_API_TIMEOUT)
+        d = json.loads(data)
+        return GetUploadURLResp(
+            upload_param=d.get("upload_param", ""),
+            thumb_upload_param=d.get("thumb_upload_param", ""),
+        )
+
+    def push(self, to: str, text: str) -> str:
+        """Send a proactive text message using a cached context token.
+
+        The target user must have previously sent a message so that a context
+        token is available. Raises NoContextTokenError otherwise.
+        """
+        token = self.get_context_token(to)
+        if token is None:
+            raise NoContextTokenError()
+        return self.send_text(to, text, token)
+
+    # --- stop control ---
+
+    def stop(self) -> None:
+        """Signal the monitor loop to stop."""
+        self._stop_event.set()
+
+    @property
+    def stopped(self) -> bool:
+        return self._stop_event.is_set()
+
+
+# ---------- Parsing helpers ----------
+
+def _parse_cdn_media(d: Optional[dict]) -> Any:
+    if not d:
+        return None
+    from .types import CDNMedia
+    return CDNMedia(
+        encrypt_query_param=d.get("encrypt_query_param", ""),
+        aes_key=d.get("aes_key", ""),
+        encrypt_type=d.get("encrypt_type", 0),
+    )
+
+
+def _parse_message_item(d: dict) -> MessageItem:
+    from .types import (
+        MessageItemType, TextItem, ImageItem, VoiceItem, FileItem, VideoItem,
+        RefMessage, MessageItem as MI,
+    )
+    text_item = None
+    if d.get("text_item"):
+        text_item = TextItem(text=d["text_item"].get("text", ""))
+
+    image_item = None
+    if d.get("image_item"):
+        img = d["image_item"]
+        image_item = ImageItem(
+            media=_parse_cdn_media(img.get("media")),
+            thumb_media=_parse_cdn_media(img.get("thumb_media")),
+            aeskey=img.get("aeskey", ""),
+            url=img.get("url", ""),
+            mid_size=img.get("mid_size", 0),
+            thumb_size=img.get("thumb_size", 0),
+            thumb_height=img.get("thumb_height", 0),
+            thumb_width=img.get("thumb_width", 0),
+            hd_size=img.get("hd_size", 0),
+        )
+
+    voice_item = None
+    if d.get("voice_item"):
+        v = d["voice_item"]
+        voice_item = VoiceItem(
+            media=_parse_cdn_media(v.get("media")),
+            encode_type=v.get("encode_type", 0),
+            bits_per_sample=v.get("bits_per_sample", 0),
+            sample_rate=v.get("sample_rate", 0),
+            playtime=v.get("playtime", 0),
+            text=v.get("text", ""),
+        )
+
+    file_item = None
+    if d.get("file_item"):
+        f = d["file_item"]
+        file_item = FileItem(
+            media=_parse_cdn_media(f.get("media")),
+            file_name=f.get("file_name", ""),
+            md5=f.get("md5", ""),
+            len=f.get("len", ""),
+        )
+
+    video_item = None
+    if d.get("video_item"):
+        vi = d["video_item"]
+        video_item = VideoItem(
+            media=_parse_cdn_media(vi.get("media")),
+            video_size=vi.get("video_size", 0),
+            play_length=vi.get("play_length", 0),
+            video_md5=vi.get("video_md5", ""),
+            thumb_media=_parse_cdn_media(vi.get("thumb_media")),
+            thumb_size=vi.get("thumb_size", 0),
+            thumb_height=vi.get("thumb_height", 0),
+            thumb_width=vi.get("thumb_width", 0),
+        )
+
+    ref_msg = None
+    if d.get("ref_msg"):
+        r = d["ref_msg"]
+        ref_msg = RefMessage(
+            message_item=_parse_message_item(r["message_item"]) if r.get("message_item") else None,
+            title=r.get("title", ""),
+        )
+
+    return MI(
+        type=MessageItemType(d.get("type", 0)),
+        create_time_ms=d.get("create_time_ms", 0),
+        update_time_ms=d.get("update_time_ms", 0),
+        is_completed=d.get("is_completed", False),
+        msg_id=d.get("msg_id", ""),
+        ref_msg=ref_msg,
+        text_item=text_item,
+        image_item=image_item,
+        voice_item=voice_item,
+        file_item=file_item,
+        video_item=video_item,
+    )
+
+
+def _parse_weixin_message(d: dict) -> "WeixinMessage":
+    from .types import WeixinMessage, MessageType, MessageState
+    items = [_parse_message_item(i) for i in d.get("item_list", [])]
+    return WeixinMessage(
+        seq=d.get("seq", 0),
+        message_id=d.get("message_id", 0),
+        from_user_id=d.get("from_user_id", ""),
+        to_user_id=d.get("to_user_id", ""),
+        client_id=d.get("client_id", ""),
+        create_time_ms=d.get("create_time_ms", 0),
+        update_time_ms=d.get("update_time_ms", 0),
+        delete_time_ms=d.get("delete_time_ms", 0),
+        session_id=d.get("session_id", ""),
+        group_id=d.get("group_id", ""),
+        message_type=MessageType(d.get("message_type", 0)),
+        message_state=MessageState(d.get("message_state", 0)),
+        item_list=items,
+        context_token=d.get("context_token", ""),
+    )
+
+
+def _parse_get_updates_resp(data: bytes) -> GetUpdatesResp:
+    d = json.loads(data)
+    msgs = [_parse_weixin_message(m) for m in d.get("msgs", [])]
+    return GetUpdatesResp(
+        ret=d.get("ret", 0),
+        errcode=d.get("errcode", 0),
+        errmsg=d.get("errmsg", ""),
+        msgs=msgs,
+        get_updates_buf=d.get("get_updates_buf", ""),
+        longpolling_timeout_ms=d.get("longpolling_timeout_ms", 0),
+    )

openilink_sdk_python-0.1.0/openilink/errors.py

@@ -0,0 +1,30 @@
+"""Custom exceptions for the openilink SDK."""
+
+
+class APIError(Exception):
+    """Error response from the iLink API."""
+
+    def __init__(self, ret: int = 0, errcode: int = 0, errmsg: str = ""):
+        self.ret = ret
+        self.errcode = errcode
+        self.errmsg = errmsg
+        super().__init__(f"ilink: api error ret={ret} errcode={errcode} errmsg={errmsg}")
+
+    def is_session_expired(self) -> bool:
+        return self.errcode == -14 or self.ret == -14
+
+
+class HTTPError(Exception):
+    """Non-2xx HTTP response from the server."""
+
+    def __init__(self, status_code: int, body: bytes):
+        self.status_code = status_code
+        self.body = body
+        super().__init__(f"ilink: http {status_code}: {body.decode(errors='replace')}")
+
+
+class NoContextTokenError(Exception):
+    """No cached context token exists for the target user."""
+
+    def __init__(self):
+        super().__init__("ilink: no cached context token; user must send a message first")

openilink_sdk_python-0.1.0/openilink/helpers.py

@@ -0,0 +1,55 @@
+"""Utility functions for the openilink SDK."""
+
+from __future__ import annotations
+
+import base64
+import os
+import struct
+
+from .types import MessageItemType, WeixinMessage
+
+
+def ensure_trailing_slash(url: str) -> str:
+    return url if url.endswith("/") else url + "/"
+
+
+def random_wechat_uin() -> str:
+    n = struct.unpack(">I", os.urandom(4))[0]
+    return base64.b64encode(str(n).encode()).decode()
+
+
+def extract_text(msg: WeixinMessage) -> str:
+    """Return the first text body from a message's item list."""
+    for item in msg.item_list:
+        if item.type == MessageItemType.TEXT and item.text_item is not None:
+            return item.text_item.text
+    return ""
+
+
+def print_qrcode(url: str) -> None:
+    """Print a QR code to the terminal using ASCII blocks."""
+    import io
+    import sys
+    import qrcode
+
+    qr = qrcode.QRCode(
+        box_size=1,
+        border=1,
+        error_correction=qrcode.constants.ERROR_CORRECT_L,
+    )
+    qr.add_data(url)
+    qr.make(fit=True)
+
+    # Render to a UTF-8 StringIO to avoid Windows GBK encoding issues,
+    # then write with fallback.
+    buf = io.StringIO()
+    qr.print_ascii(out=buf, invert=True)
+    text = buf.getvalue()
+    try:
+        sys.stdout.write(text)
+    except UnicodeEncodeError:
+        # Fallback: use ## for dark and spaces for light
+        matrix = qr.get_matrix()
+        for row in matrix:
+            print("".join("##" if cell else "  " for cell in row))
+    sys.stdout.flush()

openilink_sdk_python-0.1.0/openilink/monitor.py

@@ -0,0 +1,105 @@
+"""Long-poll message monitor for the iLink Bot API."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Callable, Optional
+
+from .errors import APIError
+
+if TYPE_CHECKING:
+    from .client import Client
+    from .types import WeixinMessage
+
+MAX_CONSECUTIVE_FAILURES = 3
+BACKOFF_DELAY = 30  # seconds
+RETRY_DELAY = 2
+
+
+class MonitorOptions:
+    """Configures the long-poll monitor loop."""
+
+    def __init__(
+        self,
+        initial_buf: str = "",
+        on_buf_update: Optional[Callable[[str], None]] = None,
+        on_error: Optional[Callable[[Exception], None]] = None,
+        on_session_expired: Optional[Callable[[], None]] = None,
+    ):
+        self.initial_buf = initial_buf
+        self.on_buf_update = on_buf_update
+        self.on_error = on_error or (lambda e: None)
+        self.on_session_expired = on_session_expired
+
+
+def monitor(
+    client: Client,
+    handler: Callable[[WeixinMessage], None],
+    opts: Optional[MonitorOptions] = None,
+) -> None:
+    """Run a long-poll loop, invoking handler for each inbound message.
+
+    Blocks until client.stop() is called. Handles retries/backoff automatically.
+    Context tokens are cached automatically for use with client.push().
+    """
+    if opts is None:
+        opts = MonitorOptions()
+
+    buf = opts.initial_buf
+    failures = 0
+
+    while not client.stopped:
+        try:
+            resp = client.get_updates(buf)
+        except Exception as exc:
+            if client.stopped:
+                return
+            failures += 1
+            opts.on_error(Exception(f"getUpdates ({failures}/{MAX_CONSECUTIVE_FAILURES}): {exc}"))
+            if failures >= MAX_CONSECUTIVE_FAILURES:
+                failures = 0
+                _sleep_or_stop(client, BACKOFF_DELAY)
+            else:
+                _sleep_or_stop(client, RETRY_DELAY)
+            continue
+
+        # API-level error
+        if resp.ret != 0 or resp.errcode != 0:
+            api_err = APIError(ret=resp.ret, errcode=resp.errcode, errmsg=resp.errmsg)
+
+            if api_err.is_session_expired():
+                if opts.on_session_expired:
+                    opts.on_session_expired()
+                opts.on_error(api_err)
+                _sleep_or_stop(client, 300)  # 5 minutes
+                continue
+
+            failures += 1
+            opts.on_error(Exception(f"getUpdates ({failures}/{MAX_CONSECUTIVE_FAILURES}): {api_err}"))
+            if failures >= MAX_CONSECUTIVE_FAILURES:
+                failures = 0
+                _sleep_or_stop(client, BACKOFF_DELAY)
+            else:
+                _sleep_or_stop(client, RETRY_DELAY)
+            continue
+
+        failures = 0
+
+        # Update sync cursor
+        if resp.get_updates_buf:
+            buf = resp.get_updates_buf
+            if opts.on_buf_update:
+                opts.on_buf_update(buf)
+
+        # Dispatch messages
+        for msg in resp.msgs:
+            if msg.context_token and msg.from_user_id:
+                client.set_context_token(msg.from_user_id, msg.context_token)
+            handler(msg)
+
+
+def _sleep_or_stop(client: Client, seconds: float) -> None:
+    """Sleep in small increments so we can respond to stop quickly."""
+    end = time.monotonic() + seconds
+    while time.monotonic() < end and not client.stopped:
+        time.sleep(min(0.5, end - time.monotonic()))

openilink_sdk_python-0.1.0/openilink/types.py

@@ -0,0 +1,195 @@
+"""Data types for the openilink SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Optional
+
+
+# ---------- Enums ----------
+
+class UploadMediaType(IntEnum):
+    IMAGE = 1
+    VIDEO = 2
+    FILE = 3
+    VOICE = 4
+
+
+class MessageType(IntEnum):
+    NONE = 0
+    USER = 1
+    BOT = 2
+
+
+class MessageItemType(IntEnum):
+    NONE = 0
+    TEXT = 1
+    IMAGE = 2
+    VOICE = 3
+    FILE = 4
+    VIDEO = 5
+
+
+class MessageState(IntEnum):
+    NEW = 0
+    GENERATING = 1
+    FINISH = 2
+
+
+class TypingStatus(IntEnum):
+    TYPING = 1
+    CANCEL = 2
+
+
+# ---------- Data classes ----------
+
+@dataclass
+class BaseInfo:
+    channel_version: str = ""
+
+
+@dataclass
+class CDNMedia:
+    encrypt_query_param: str = ""
+    aes_key: str = ""
+    encrypt_type: int = 0
+
+
+@dataclass
+class TextItem:
+    text: str = ""
+
+
+@dataclass
+class ImageItem:
+    media: Optional[CDNMedia] = None
+    thumb_media: Optional[CDNMedia] = None
+    aeskey: str = ""
+    url: str = ""
+    mid_size: int = 0
+    thumb_size: int = 0
+    thumb_height: int = 0
+    thumb_width: int = 0
+    hd_size: int = 0
+
+
+@dataclass
+class VoiceItem:
+    media: Optional[CDNMedia] = None
+    encode_type: int = 0
+    bits_per_sample: int = 0
+    sample_rate: int = 0
+    playtime: int = 0
+    text: str = ""
+
+
+@dataclass
+class FileItem:
+    media: Optional[CDNMedia] = None
+    file_name: str = ""
+    md5: str = ""
+    len: str = ""
+
+
+@dataclass
+class VideoItem:
+    media: Optional[CDNMedia] = None
+    video_size: int = 0
+    play_length: int = 0
+    video_md5: str = ""
+    thumb_media: Optional[CDNMedia] = None
+    thumb_size: int = 0
+    thumb_height: int = 0
+    thumb_width: int = 0
+
+
+@dataclass
+class RefMessage:
+    message_item: Optional[MessageItem] = None
+    title: str = ""
+
+
+@dataclass
+class MessageItem:
+    type: MessageItemType = MessageItemType.NONE
+    create_time_ms: int = 0
+    update_time_ms: int = 0
+    is_completed: bool = False
+    msg_id: str = ""
+    ref_msg: Optional[RefMessage] = None
+    text_item: Optional[TextItem] = None
+    image_item: Optional[ImageItem] = None
+    voice_item: Optional[VoiceItem] = None
+    file_item: Optional[FileItem] = None
+    video_item: Optional[VideoItem] = None
+
+
+# Fix forward reference
+RefMessage.__dataclass_fields__["message_item"].default = None
+
+
+@dataclass
+class WeixinMessage:
+    seq: int = 0
+    message_id: int = 0
+    from_user_id: str = ""
+    to_user_id: str = ""
+    client_id: str = ""
+    create_time_ms: int = 0
+    update_time_ms: int = 0
+    delete_time_ms: int = 0
+    session_id: str = ""
+    group_id: str = ""
+    message_type: MessageType = MessageType.NONE
+    message_state: MessageState = MessageState.NEW
+    item_list: list[MessageItem] = field(default_factory=list)
+    context_token: str = ""
+
+
+@dataclass
+class GetUpdatesResp:
+    ret: int = 0
+    errcode: int = 0
+    errmsg: str = ""
+    msgs: list[WeixinMessage] = field(default_factory=list)
+    get_updates_buf: str = ""
+    longpolling_timeout_ms: int = 0
+
+
+@dataclass
+class GetConfigResp:
+    ret: int = 0
+    errmsg: str = ""
+    typing_ticket: str = ""
+
+
+@dataclass
+class GetUploadURLResp:
+    upload_param: str = ""
+    thumb_upload_param: str = ""
+
+
+@dataclass
+class QRCodeResponse:
+    qrcode: str = ""
+    qrcode_img_content: str = ""
+
+
+@dataclass
+class QRStatusResponse:
+    status: str = ""  # wait, scaned, confirmed, expired
+    bot_token: str = ""
+    ilink_bot_id: str = ""
+    baseurl: str = ""
+    ilink_user_id: str = ""
+
+
+@dataclass
+class LoginResult:
+    connected: bool = False
+    bot_token: str = ""
+    bot_id: str = ""
+    base_url: str = ""
+    user_id: str = ""
+    message: str = ""

openilink_sdk_python-0.1.0/openilink_sdk_python.egg-info/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: openilink-sdk-python
+Version: 0.1.0
+Summary: Python client for the Weixin iLink Bot API
+License: MIT
+Project-URL: Homepage, https://github.com/openilink/openilink-sdk-python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: qrcode>=7.0
+
+# openilink-sdk-python
+
+Python SDK for the Weixin iLink Bot API.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from openilink import Client, LoginCallbacks, MonitorOptions, extract_text
+
+client = Client()
+
+# QR code login
+result = client.login_with_qr(
+    callbacks=LoginCallbacks(
+        on_qrcode=lambda url: print(f"Scan: {url}"),
+        on_scanned=lambda: print("Scanned!"),
+    )
+)
+print(f"Connected: BotID={result.bot_id}")
+
+# Echo bot
+client.monitor(
+    lambda msg: client.push(msg.from_user_id, "echo: " + extract_text(msg)),
+    opts=MonitorOptions(
+        on_error=lambda e: print(f"Error: {e}"),
+    ),
+)
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `Client(token, base_url, ...)` | Create client |
+| `client.login_with_qr(callbacks)` | QR code login |
+| `client.monitor(handler, opts)` | Long-poll message loop |
+| `client.send_text(to, text, context_token)` | Send text message |
+| `client.push(to, text)` | Send with cached context token |
+| `client.send_typing(user_id, ticket, status)` | Typing indicator |
+| `client.get_config(user_id, context_token)` | Get bot config |
+| `client.get_upload_url(req)` | Get CDN upload URL |
+| `client.stop()` | Stop monitor loop |
+| `extract_text(msg)` | Extract first text from message |

openilink_sdk_python-0.1.0/openilink_sdk_python.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+openilink/__init__.py
+openilink/auth.py
+openilink/client.py
+openilink/errors.py
+openilink/helpers.py
+openilink/monitor.py
+openilink/types.py
+openilink_sdk_python.egg-info/PKG-INFO
+openilink_sdk_python.egg-info/SOURCES.txt
+openilink_sdk_python.egg-info/dependency_links.txt
+openilink_sdk_python.egg-info/requires.txt
+openilink_sdk_python.egg-info/top_level.txt

openilink_sdk_python-0.1.0/openilink_sdk_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openilink_sdk_python-0.1.0/openilink_sdk_python.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests>=2.28
+qrcode>=7.0

openilink_sdk_python-0.1.0/openilink_sdk_python.egg-info/top_level.txt

@@ -0,0 +1 @@
+openilink

openilink_sdk_python-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openilink-sdk-python"
+version = "0.1.0"
+description = "Python client for the Weixin iLink Bot API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+dependencies = [
+    "requests>=2.28",
+    "qrcode>=7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/openilink/openilink-sdk-python"
+
+[tool.setuptools.packages.find]
+include = ["openilink*"]

openilink_sdk_python-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+