agim 0.0.1__py3-none-any.whl

agim/__init__.py

@@ -0,0 +1,45 @@
+"""agim: one stateless interface for IM login, receive, and send.
+
+The package is a plain SDK. It owns no storage, no plugin registry, and no
+host concepts: callers persist the login handshake and receive cursor
+themselves and hand them back on the next call.
+"""
+
+from .client import IMClient
+from .errors import MediaTooLargeError
+from .models import (
+    MAX_MEDIA_BYTES,
+    MAX_MEDIA_ITEMS,
+    InboundMedia,
+    InboundMessage,
+    JsonValue,
+    LoginCredentials,
+    LoginHandshake,
+    LoginState,
+    LoginStatus,
+    MediaKind,
+    MediaRejectionReason,
+    ReceiveResult,
+    RejectedMedia,
+)
+from .wechat import WeChatAuthClient, WeChatClient
+
+__all__ = [
+    "IMClient",
+    "InboundMessage",
+    "InboundMedia",
+    "JsonValue",
+    "LoginCredentials",
+    "LoginHandshake",
+    "LoginState",
+    "LoginStatus",
+    "MAX_MEDIA_BYTES",
+    "MAX_MEDIA_ITEMS",
+    "MediaKind",
+    "MediaRejectionReason",
+    "MediaTooLargeError",
+    "RejectedMedia",
+    "ReceiveResult",
+    "WeChatAuthClient",
+    "WeChatClient",
+]

agim/_compat.py

@@ -0,0 +1,32 @@
+"""Shims for standard-library features that are newer than Python 3.10.
+
+``agim`` supports Python 3.10 and newer, but a couple of pieces build on
+features that only exist from 3.11 onward. Collecting them here keeps the
+version checks in one place.
+"""
+
+from __future__ import annotations
+
+import sys
+
+if sys.version_info >= (3, 11):  # pragma: no cover - selected by the interpreter
+    from enum import StrEnum
+else:  # pragma: no cover - selected by the interpreter
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        """``enum.StrEnum`` for Python 3.10: members are their own string value."""
+
+        def __str__(self) -> str:
+            return str(self.value)
+
+        def __format__(self, format_spec: str) -> str:
+            return str.__format__(str(self), format_spec)
+
+
+if sys.version_info >= (3, 12):  # pragma: no cover - selected by the interpreter
+    from typing import TypeAliasType
+else:  # pragma: no cover - selected by the interpreter
+    from typing_extensions import TypeAliasType
+
+__all__ = ["StrEnum", "TypeAliasType"]

agim/client.py

@@ -0,0 +1,36 @@
+"""The one interface every agim platform client implements."""
+
+from abc import ABC, abstractmethod
+
+from .models import LoginHandshake, LoginState, ReceiveResult
+
+
+class IMClient(ABC):
+    """Unified login, receive, and send surface for one IM platform.
+
+    agim is stateless by design: callers own and persist the login handshake
+    and the receive cursor, then hand them back on the next call.
+    """
+
+    @abstractmethod
+    async def login(self) -> LoginHandshake:
+        """Begin a login flow and return the handshake the caller must store."""
+
+    @abstractmethod
+    async def is_login(self, handshake: LoginHandshake) -> LoginState:
+        """Poll one stored handshake and return the current login state."""
+
+    @abstractmethod
+    async def receive(self, cursor: str | None = None) -> ReceiveResult:
+        """Await the next inbound message and return its next cursor."""
+
+    @abstractmethod
+    async def send(self, chat_id: str, text: str, *, context_token: str | None = None) -> None:
+        """Send one outbound message, reusing the caller's stored token."""
+
+    async def aclose(self) -> None:
+        """Release transport resources; platforms without one keep the default."""
+        return None
+
+
+__all__ = ["IMClient"]

agim/errors.py

@@ -0,0 +1,13 @@
+"""Errors agim raises for platform payloads it refuses to hand back."""
+
+
+class MediaTooLargeError(ValueError):
+    """One attachment exceeded the payload size agim is willing to hold.
+
+    Callers decide what an oversized attachment means for their own surface: an
+    SDK caller may log it, and a chat host may answer the sender instead of
+    running a turn over bytes it never received.
+    """
+
+
+__all__ = ["MediaTooLargeError"]

agim/log.py

@@ -0,0 +1,19 @@
+"""Logging helpers for the standalone IM gateway."""
+
+import logging
+
+
+def configure_logging() -> None:
+    """Configure process-wide gateway logging once."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return one gateway logger."""
+    return logging.getLogger(name)
+
+
+__all__ = ["configure_logging", "get_logger"]

agim/models.py

@@ -0,0 +1,146 @@
+"""Typed models shared by every agim client."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ._compat import StrEnum, TypeAliasType
+
+JsonValue = TypeAliasType("JsonValue", "str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]")
+
+#: Largest single attachment a platform client keeps in memory.
+MAX_MEDIA_BYTES = 256 * 1024 * 1024
+
+#: Most attachments one inbound message may carry.
+MAX_MEDIA_ITEMS = 16
+
+
+class LoginStatus(StrEnum):
+    """Lifecycle of one QR-assisted login flow."""
+
+    PENDING = "pending"
+    SCANNED = "scanned"
+    VERIFY_REQUIRED = "verify_required"
+    CONNECTED = "connected"
+    FAILED = "failed"
+    EXPIRED = "expired"
+
+
+class LoginHandshake(BaseModel):
+    """Opaque login state the caller must persist between login and is_login.
+
+    agim never stores anything itself, so the QR payload and whatever provider
+    state keeps the poll alive travel back to the caller in this object.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    qr_content: str = Field(min_length=1, max_length=10_000)
+    qr_url: str | None = Field(default=None, max_length=10_000)
+    state: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class LoginCredentials(BaseModel):
+    """Provider config and secrets returned once a login succeeds."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    config: dict[str, JsonValue] = Field(default_factory=dict)
+    secrets: dict[str, str] = Field(default_factory=dict)
+
+
+class LoginState(BaseModel):
+    """Current login status; ``is_login`` returns this to its caller."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status: LoginStatus
+    message: str = Field(min_length=1, max_length=2_000)
+    credentials: LoginCredentials | None = None
+
+
+class MediaKind(StrEnum):
+    """Attachment kinds an IM platform can deliver."""
+
+    IMAGE = "image"
+    VOICE = "voice"
+    FILE = "file"
+    VIDEO = "video"
+
+
+class MediaRejectionReason(StrEnum):
+    """Why an attachment did not arrive with its message."""
+
+    TOO_LARGE = "too_large"
+
+
+class RejectedMedia(BaseModel):
+    """One attachment the platform announced but this client refused to carry."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: MediaKind
+    reason: MediaRejectionReason
+
+
+class InboundMedia(BaseModel):
+    """One attachment of an inbound message, already downloaded and decrypted.
+
+    Callers receive the bytes so a host can store, forward, or hand them to a
+    model; whether a given model can read them is the caller's decision, not
+    agim's.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: MediaKind
+    media_type: str = Field(min_length=1, max_length=100)
+    name: str | None = Field(default=None, max_length=255)
+    data: bytes = Field(min_length=1, max_length=MAX_MEDIA_BYTES)
+
+
+class InboundMessage(BaseModel):
+    """One normalized inbound message: its text plus any attached media."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    event_id: str = Field(min_length=1, max_length=200)
+    chat_id: str = Field(min_length=1, max_length=500)
+    user_id: str = Field(min_length=1, max_length=500)
+    text: str = Field(default="", max_length=100_000)
+    media: list[InboundMedia] = Field(default_factory=list, max_length=MAX_MEDIA_ITEMS)
+    rejected_media: list[RejectedMedia] = Field(default_factory=list, max_length=MAX_MEDIA_ITEMS)
+    reply_token: str | None = Field(default=None, max_length=10_000)
+
+    @model_validator(mode="after")
+    def _require_text_or_media(self) -> InboundMessage:
+        """A message carries something: text, a delivered attachment, or a refusal."""
+        if not self.text.strip() and not self.media and not self.rejected_media:
+            raise ValueError("Inbound message requires text, media, or a media rejection")
+        return self
+
+
+class ReceiveResult(BaseModel):
+    """One inbound message plus the cursor the caller must persist next."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    message: InboundMessage
+    cursor: str = Field(default="", max_length=100_000)
+
+
+__all__ = [
+    "InboundMessage",
+    "InboundMedia",
+    "JsonValue",
+    "LoginCredentials",
+    "LoginHandshake",
+    "LoginState",
+    "LoginStatus",
+    "MAX_MEDIA_BYTES",
+    "MAX_MEDIA_ITEMS",
+    "MediaKind",
+    "MediaRejectionReason",
+    "RejectedMedia",
+    "ReceiveResult",
+]

agim/wechat/__init__.py

@@ -0,0 +1,17 @@
+"""Personal WeChat iLink/ClawBot implementation."""
+
+from .auth import ILINK_BASE_URL, WeChatAuthClient
+from .client import WeChatClient, attach_media, normalize_message
+from .media import CDN_BASE_URL, MediaRef, fetch_media, media_refs
+
+__all__ = [
+    "CDN_BASE_URL",
+    "ILINK_BASE_URL",
+    "MediaRef",
+    "WeChatAuthClient",
+    "WeChatClient",
+    "attach_media",
+    "fetch_media",
+    "media_refs",
+    "normalize_message",
+]

agim/wechat/auth.py

@@ -0,0 +1,141 @@
+"""Tencent iLink QR login for personal WeChat bots."""
+
+from typing import Any
+
+import httpx
+
+from ..models import LoginCredentials, LoginHandshake, LoginState, LoginStatus
+
+ILINK_BASE_URL = "https://ilinkai.weixin.qq.com"
+ILINK_APP_ID = "bot"
+ILINK_APP_CLIENT_VERSION = str((2 << 16) | (4 << 8) | 9)
+ILINK_BOT_TYPE = "3"
+
+
+def _build_headers(*, token: str | None = None, json_content: bool = False) -> dict[str, str]:
+    headers = {
+        "iLink-App-Id": ILINK_APP_ID,
+        "iLink-App-ClientVersion": ILINK_APP_CLIENT_VERSION,
+    }
+    if json_content:
+        headers["Content-Type"] = "application/json"
+    if token:
+        headers["AuthorizationType"] = "ilink_bot_token"
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+class WeChatAuthClient:
+    """Implement the official iLink QR-code login protocol."""
+
+    def __init__(
+        self,
+        *,
+        timeout_seconds: float = 40.0,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._timeout_seconds = timeout_seconds
+        self._client = client
+        self._owns_client = client is None
+
+    async def aclose(self) -> None:
+        """Close the HTTP client when this adapter created it."""
+        if self._owns_client and self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def create_login(self) -> LoginHandshake:
+        """Request one QR code and return the handshake the caller must store."""
+        response = await self._get_client().post(
+            f"{ILINK_BASE_URL}/ilink/bot/get_bot_qrcode",
+            params={"bot_type": ILINK_BOT_TYPE},
+            json={"local_token_list": []},
+            headers=_build_headers(json_content=True),
+        )
+        response.raise_for_status()
+        payload = response.json()
+        if not isinstance(payload, dict):
+            raise ValueError("WeChat QR login returned an invalid response")
+        qrcode = payload.get("qrcode")
+        qr_content = payload.get("qrcode_img_content")
+        if not isinstance(qrcode, str) or not qrcode:
+            raise ValueError("WeChat QR login response is missing qrcode")
+        if not isinstance(qr_content, str) or not qr_content:
+            raise ValueError("WeChat QR login response is missing qrcode_img_content")
+        return LoginHandshake(
+            qr_content=qr_content,
+            qr_url=qr_content if qr_content.startswith(("http://", "https://")) else None,
+            state={"qrcode": qrcode, "base_url": ILINK_BASE_URL},
+        )
+
+    async def poll_login(
+        self,
+        handshake: LoginHandshake,
+        *,
+        verify_code: str | None = None,
+    ) -> LoginState:
+        """Poll one stored handshake and normalize the platform status."""
+        qrcode = handshake.state.get("qrcode")
+        base_url = handshake.state.get("base_url") or ILINK_BASE_URL
+        if not isinstance(qrcode, str) or not qrcode or not isinstance(base_url, str):
+            return LoginState(status=LoginStatus.EXPIRED, message="Login session expired; request a new QR code.")
+        params: dict[str, str] = {"qrcode": qrcode}
+        if verify_code:
+            params["verify_code"] = verify_code
+        try:
+            response = await self._get_client().get(
+                f"{base_url.rstrip('/')}/ilink/bot/get_qrcode_status",
+                params=params,
+                headers=_build_headers(),
+            )
+            response.raise_for_status()
+            payload: Any = response.json()
+        except (httpx.TimeoutException, httpx.NetworkError):
+            return LoginState(status=LoginStatus.PENDING, message="Waiting for the WeChat QR code to be scanned.")
+        except httpx.HTTPError as error:
+            return LoginState(
+                status=LoginStatus.PENDING,
+                message=f"WeChat login service is temporarily unavailable: {error}",
+            )
+        if not isinstance(payload, dict):
+            raise ValueError("WeChat QR status returned an invalid response")
+        status = payload.get("status")
+        if status == "confirmed":
+            token = payload.get("bot_token")
+            if not isinstance(token, str) or not token:
+                raise ValueError("WeChat login confirmed without bot_token")
+            config: dict[str, Any] = {"base_url": base_url}
+            if isinstance(payload.get("ilink_bot_id"), str):
+                config["ilink_bot_id"] = payload["ilink_bot_id"]
+            if isinstance(payload.get("ilink_user_id"), str):
+                config["ilink_user_id"] = payload["ilink_user_id"]
+            return LoginState(
+                status=LoginStatus.CONNECTED,
+                message="WeChat bot connected.",
+                credentials=LoginCredentials(config=config, secrets={"bot_token": token}),
+            )
+        if status in {"scaned", "scaned_but_redirect"}:
+            return LoginState(status=LoginStatus.SCANNED, message="QR code scanned; confirm in WeChat.")
+        if status == "need_verifycode":
+            return LoginState(status=LoginStatus.VERIFY_REQUIRED, message="Enter the pairing code shown in WeChat.")
+        if status in {"expired", "verify_code_blocked"}:
+            return LoginState(status=LoginStatus.EXPIRED, message="QR code expired; request a new one.")
+        if status == "binded_redirect":
+            return LoginState(status=LoginStatus.CONNECTED, message="This WeChat bot is already linked.")
+        return LoginState(status=LoginStatus.PENDING, message="Scan the QR code with WeChat to finish signing in.")
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                timeout=self._timeout_seconds,
+                follow_redirects=True,
+            )
+        return self._client
+
+
+__all__ = [
+    "ILINK_APP_CLIENT_VERSION",
+    "ILINK_APP_ID",
+    "ILINK_BASE_URL",
+    "WeChatAuthClient",
+]

agim/wechat/client.py

@@ -0,0 +1,318 @@
+"""Personal WeChat implementation of the unified agim client."""
+
+import asyncio
+import base64
+import random
+from collections import deque
+from typing import Any
+
+import httpx
+
+from ..client import IMClient
+from ..errors import MediaTooLargeError
+from ..log import get_logger
+from ..models import (
+    MAX_MEDIA_BYTES,
+    MAX_MEDIA_ITEMS,
+    InboundMedia,
+    InboundMessage,
+    LoginHandshake,
+    LoginState,
+    MediaRejectionReason,
+    ReceiveResult,
+    RejectedMedia,
+)
+from .auth import ILINK_APP_CLIENT_VERSION, ILINK_APP_ID, ILINK_BASE_URL, WeChatAuthClient
+from .media import CDN_BASE_URL, MediaRef, fetch_media, media_refs
+
+DEFAULT_LONG_POLL_TIMEOUT_MS = 35_000
+MIN_LONG_POLL_TIMEOUT_MS = 5_000
+MAX_LONG_POLL_TIMEOUT_MS = 60_000
+MIN_EMPTY_RESPONSE_DELAY_SECONDS = 0.25
+MAX_CONSECUTIVE_FAILURES = 3
+BACKOFF_SECONDS = 30.0
+
+logger = get_logger(__name__)
+
+
+def _headers(token: str) -> dict[str, str]:
+    random_uin = str(random.getrandbits(32)).encode()
+    return {
+        "Content-Type": "application/json",
+        "AuthorizationType": "ilink_bot_token",
+        "Authorization": f"Bearer {token}",
+        "X-WECHAT-UIN": base64.b64encode(random_uin).decode(),
+        "iLink-App-Id": ILINK_APP_ID,
+        "iLink-App-ClientVersion": ILINK_APP_CLIENT_VERSION,
+    }
+
+
+def _base_info() -> dict[str, str]:
+    return {"channel_version": "2.4.9", "bot_agent": "Zett"}
+
+
+def _next_timeout_ms(payload: dict[str, Any]) -> int:
+    """Honor the server's suggested long-poll timeout within safe bounds."""
+    suggested = payload.get("longpolling_timeout_ms")
+    if not isinstance(suggested, int):
+        return DEFAULT_LONG_POLL_TIMEOUT_MS
+    return min(MAX_LONG_POLL_TIMEOUT_MS, max(MIN_LONG_POLL_TIMEOUT_MS, suggested))
+
+
+def _text_from_message(message: dict[str, Any]) -> str:
+    """Collect the text one update already carries.
+
+    Text items contribute their text, voice items contribute the platform's
+    speech-to-text result when it exists, and every other media item contributes
+    a placeholder so a message is never empty before its bytes are downloaded.
+    """
+    pieces: list[str] = []
+    for item in message.get("item_list") or []:
+        if not isinstance(item, dict):
+            continue
+        if item.get("type") == 1:
+            text = item.get("text_item")
+            if isinstance(text, dict) and isinstance(text.get("text"), str):
+                pieces.append(text["text"])
+                continue
+        if item.get("type") == 3:
+            voice = item.get("voice_item")
+            if isinstance(voice, dict) and isinstance(voice.get("text"), str):
+                pieces.append(voice["text"])
+                continue
+        labels = {2: "[image]", 4: "[file]", 5: "[video]"}
+        if item.get("type") in labels:
+            pieces.append(labels[item["type"]])
+    return "\n".join(piece for piece in pieces if piece.strip())
+
+
+def normalize_message(message: dict[str, Any]) -> InboundMessage | None:
+    """Normalize one iLink update into the package message model.
+
+    Media is represented by placeholder text here; :func:`attach_media` replaces
+    that placeholder with the downloaded attachment when its bytes arrive.
+    """
+    text = _text_from_message(message)
+    if not text.strip():
+        return None
+    user_id = message.get("from_user_id")
+    event_id = message.get("message_id")
+    if not isinstance(user_id, str) or not user_id:
+        return None
+    if not isinstance(event_id, str) or not event_id:
+        event_id = str(message.get("seq") or "")
+    if not event_id:
+        return None
+    context_token = message.get("context_token")
+    return InboundMessage(
+        event_id=event_id,
+        chat_id=user_id,
+        user_id=user_id,
+        text=text.strip(),
+        reply_token=context_token if isinstance(context_token, str) else None,
+    )
+
+
+async def attach_media(
+    client: httpx.AsyncClient,
+    message: InboundMessage,
+    raw: dict[str, Any],
+    *,
+    cdn_base_url: str = CDN_BASE_URL,
+    max_bytes: int = MAX_MEDIA_BYTES,
+) -> InboundMessage:
+    """Download every attachment of one update onto its normalized message.
+
+    An item the CDN cannot deliver is logged and skipped: the message keeps its
+    placeholder text, so a caller still sees that the sender sent something and
+    the conversation does not stall on one unreachable object. An item over
+    ``max_bytes`` is instead reported as rejected, because a caller can only
+    answer the sender if it is told the attachment was refused rather than lost.
+    """
+    refs: list[MediaRef] = media_refs(raw, limit=MAX_MEDIA_ITEMS)
+    if not refs:
+        return message
+    media: list[InboundMedia] = []
+    rejected: list[RejectedMedia] = []
+    for ref in refs:
+        try:
+            media.append(await fetch_media(client, ref, cdn_base_url=cdn_base_url, max_bytes=max_bytes))
+        except MediaTooLargeError as error:
+            logger.warning("WeChat inbound media is too large; kind=%s error=%s", ref.kind.value, error)
+            rejected.append(RejectedMedia(kind=ref.kind, reason=MediaRejectionReason.TOO_LARGE))
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.exception("WeChat inbound media download failed; kind=%s", ref.kind.value)
+    if not media and not rejected:
+        return message
+    # ``model_copy`` skips validation, so the item cap is applied here instead of
+    # trusting the field constraint to catch a message with more attachments.
+    return message.model_copy(update={"media": media[:MAX_MEDIA_ITEMS], "rejected_media": rejected})
+
+
+class WeChatClient(IMClient):
+    """Login, long-poll, and send over the Tencent personal WeChat iLink API.
+
+    The client keeps no persistence: the caller stores the login handshake and
+    the ``get_updates_buf`` cursor, and passes the reply context token back on
+    each ``send``. One poll can carry several messages, so the rest of a batch
+    waits in memory and is handed over one :meth:`receive` call at a time.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: str | None = None,
+        base_url: str = ILINK_BASE_URL,
+        cdn_base_url: str = CDN_BASE_URL,
+        media_max_bytes: int = MAX_MEDIA_BYTES,
+        client: httpx.AsyncClient | None = None,
+        auth: WeChatAuthClient | None = None,
+    ) -> None:
+        self._token = token
+        self._base_url = base_url.rstrip("/")
+        self._cdn_base_url = cdn_base_url
+        self._media_max_bytes = media_max_bytes
+        self._client = client
+        self._owns_client = client is None
+        self._auth = auth or WeChatAuthClient()
+        self._queued: deque[tuple[InboundMessage, dict[str, Any]]] = deque()
+        self._queued_cursor = ""
+
+    async def aclose(self) -> None:
+        """Close the HTTP clients owned by this instance."""
+        self._queued.clear()
+        await self._auth.aclose()
+        if self._owns_client and self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def login(self) -> LoginHandshake:
+        """Request a QR code and return the handshake the caller must store."""
+        return await self._auth.create_login()
+
+    async def is_login(self, handshake: LoginHandshake, *, verify_code: str | None = None) -> LoginState:
+        """Poll one stored handshake, optionally with a pairing code."""
+        return await self._auth.poll_login(handshake, verify_code=verify_code)
+
+    async def receive(self, cursor: str | None = None) -> ReceiveResult:
+        """Long-poll until one normalized inbound message is available.
+
+        Only one message is returned per call, but a poll that carries a batch
+        hands over its remaining messages on the following calls; the cursor
+        only moves past the batch once its last message has been returned, so a
+        crash mid-batch re-delivers the batch instead of dropping its tail.
+        """
+        previous = cursor or ""
+        if self._queued:
+            return await self._hand_over(previous)
+        current = previous
+        failures = 0
+        long_poll_timeout_ms = DEFAULT_LONG_POLL_TIMEOUT_MS
+        while True:
+            try:
+                response = await self._get_client().post(
+                    f"{self._base_url}/ilink/bot/getupdates",
+                    json={"get_updates_buf": current, "base_info": _base_info()},
+                    headers=_headers(self._require_token()),
+                    timeout=(long_poll_timeout_ms / 1000) + 5,
+                )
+                response.raise_for_status()
+                payload = response.json()
+                if not isinstance(payload, dict):
+                    raise ValueError("WeChat getupdates returned an invalid response")
+                if payload.get("ret") not in (None, 0) or payload.get("errcode") not in (None, 0):
+                    raise RuntimeError(f"WeChat getupdates failed: {payload.get('errmsg') or payload.get('errcode')}")
+                next_cursor = payload.get("get_updates_buf")
+                if isinstance(next_cursor, str):
+                    current = next_cursor
+                long_poll_timeout_ms = _next_timeout_ms(payload)
+                messages = payload.get("msgs") or []
+                for raw in messages:
+                    if not isinstance(raw, dict):
+                        continue
+                    message = normalize_message(raw)
+                    if message is None:
+                        continue
+                    self._queued.append((message, raw))
+                if self._queued:
+                    self._queued_cursor = current
+                    return await self._hand_over(previous)
+                failures = 0
+                if not messages:
+                    # Some gateways return immediately on transient upstream
+                    # conditions. A tiny pause prevents a hot getupdates loop.
+                    await asyncio.sleep(MIN_EMPTY_RESPONSE_DELAY_SECONDS)
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                failures += 1
+                logger.exception(
+                    "WeChat getupdates failed; consecutive_failures=%d max=%d",
+                    failures,
+                    MAX_CONSECUTIVE_FAILURES,
+                )
+                if failures >= MAX_CONSECUTIVE_FAILURES:
+                    failures = 0
+                    await asyncio.sleep(BACKOFF_SECONDS)
+                else:
+                    await asyncio.sleep(2)
+
+    async def _hand_over(self, previous_cursor: str) -> ReceiveResult:
+        """Return the oldest queued message and the cursor the caller should keep."""
+        message, raw = self._queued.popleft()
+        attached = await attach_media(
+            self._get_client(),
+            message,
+            raw,
+            cdn_base_url=self._cdn_base_url,
+            max_bytes=self._media_max_bytes,
+        )
+        # Handing over the new cursor early would let a crash mid-batch skip the
+        # messages still queued behind this one.
+        cursor = self._queued_cursor if not self._queued else previous_cursor
+        return ReceiveResult(message=attached, cursor=cursor)
+
+    async def send(self, chat_id: str, text: str, *, context_token: str | None = None) -> None:
+        """Send one text message, reusing the caller's stored context token."""
+        message: dict[str, Any] = {
+            "from_user_id": "",
+            "to_user_id": chat_id,
+            "client_id": f"agim-{random.getrandbits(64):x}",
+            "message_type": 2,
+            "message_state": 2,
+            "item_list": [{"type": 1, "text_item": {"text": text}}],
+        }
+        if context_token:
+            message["context_token"] = context_token
+        response = await self._get_client().post(
+            f"{self._base_url}/ilink/bot/sendmessage",
+            json={"msg": message, "base_info": _base_info()},
+            headers=_headers(self._require_token()),
+        )
+        response.raise_for_status()
+        payload = response.json()
+        if isinstance(payload, dict) and payload.get("ret") not in (None, 0):
+            raise RuntimeError(f"WeChat sendmessage failed: {payload.get('errmsg') or payload.get('ret')}")
+
+    def _require_token(self) -> str:
+        if not self._token:
+            raise RuntimeError("WeChat client has no bot token; complete login first")
+        return self._token
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=20)
+        return self._client
+
+
+__all__ = [
+    "CDN_BASE_URL",
+    "DEFAULT_LONG_POLL_TIMEOUT_MS",
+    "MAX_LONG_POLL_TIMEOUT_MS",
+    "MIN_LONG_POLL_TIMEOUT_MS",
+    "WeChatClient",
+    "attach_media",
+    "normalize_message",
+]

agim/wechat/media.py

@@ -0,0 +1,288 @@
+"""Download, decrypt, and type the media items of one iLink update.
+
+Media arrives as a CDN reference plus an AES-128 key. The wire format and the
+decryption rules follow Tencent's ``openclaw-weixin`` channel plugin: fields are
+read from ``media`` (``encrypt_query_param``, ``aes_key``, ``full_url``), images
+may carry a hex ``aeskey`` instead, and the fetched payload is AES-128-ECB with
+PKCS#7 padding.
+"""
+
+import base64
+import binascii
+from dataclasses import dataclass
+from mimetypes import guess_type
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+from ..errors import MediaTooLargeError
+from ..log import get_logger
+from ..models import MAX_MEDIA_BYTES, MAX_MEDIA_ITEMS, InboundMedia, MediaKind
+
+logger = get_logger(__name__)
+
+#: Where the iLink API serves encrypted media from.
+CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c"
+
+#: How long one CDN download may take before the item is skipped.
+MEDIA_DOWNLOAD_TIMEOUT_SECONDS = 60.0
+
+_AES_BLOCK_BYTES = 16
+
+#: iLink item types that carry a download reference.
+_IMAGE_ITEM = 2
+_VOICE_ITEM = 3
+_FILE_ITEM = 4
+_VIDEO_ITEM = 5
+
+#: Item type to the kind and payload field that carry its CDN reference.
+_MEDIA_ITEM_FIELDS = {
+    _IMAGE_ITEM: (MediaKind.IMAGE, "image_item"),
+    _VOICE_ITEM: (MediaKind.VOICE, "voice_item"),
+    _FILE_ITEM: (MediaKind.FILE, "file_item"),
+    _VIDEO_ITEM: (MediaKind.VIDEO, "video_item"),
+}
+
+_DEFAULT_MEDIA_TYPES = {
+    MediaKind.IMAGE: "image/jpeg",
+    MediaKind.VOICE: "audio/silk",
+    MediaKind.FILE: "application/octet-stream",
+    MediaKind.VIDEO: "video/mp4",
+}
+
+#: Voice encodings named by iLink, keyed by ``voice_item.encode_type``.
+_VOICE_MEDIA_TYPES = {
+    1: "audio/pcm",
+    2: "audio/adpcm",
+    3: "audio/feature",
+    4: "audio/speex",
+    5: "audio/amr",
+    6: "audio/silk",
+    7: "audio/mpeg",
+    8: "audio/ogg",
+}
+
+#: Leading bytes of the image formats iLink forwards.
+_IMAGE_SIGNATURES: tuple[tuple[bytes, str], ...] = (
+    (b"\x89PNG\r\n\x1a\n", "image/png"),
+    (b"\xff\xd8\xff", "image/jpeg"),
+    (b"GIF87a", "image/gif"),
+    (b"GIF89a", "image/gif"),
+    (b"BM", "image/bmp"),
+)
+
+
+@dataclass(frozen=True, slots=True)
+class MediaRef:
+    """One CDN reference found in an inbound message item."""
+
+    kind: MediaKind
+    #: MIME type known before the download, refined from the bytes when possible.
+    media_type: str
+    encrypt_query_param: str | None = None
+    full_url: str | None = None
+    aes_key: str | None = None
+    name: str | None = None
+
+
+def _media_ref(item: dict[str, Any], *, kind: MediaKind, field: str) -> MediaRef | None:
+    """Read one item's media reference, or ``None`` when nothing is downloadable."""
+    payload = item.get(field)
+    if not isinstance(payload, dict):
+        return None
+    media = payload.get("media")
+    if not isinstance(media, dict):
+        return None
+    encrypted = media.get("encrypt_query_param")
+    full_url = media.get("full_url")
+    if not isinstance(encrypted, str) or not encrypted:
+        encrypted = None
+    if not isinstance(full_url, str) or not full_url:
+        full_url = None
+    if encrypted is None and full_url is None:
+        return None
+    aes_key = media.get("aes_key")
+    aes_key = aes_key if isinstance(aes_key, str) and aes_key else None
+    if kind is MediaKind.IMAGE:
+        # Images may publish the key as hex on the item itself; that form wins.
+        hex_key = payload.get("aeskey")
+        if isinstance(hex_key, str) and hex_key:
+            try:
+                aes_key = base64.b64encode(bytes.fromhex(hex_key)).decode("ascii")
+            except ValueError:
+                logger.warning("WeChat image item carries an invalid hex aeskey; ignoring it")
+    return MediaRef(
+        kind=kind,
+        media_type=_declared_media_type(item, kind=kind, field=field),
+        encrypt_query_param=encrypted,
+        full_url=full_url,
+        aes_key=aes_key,
+        name=_item_name(item, field=field),
+    )
+
+
+def _declared_media_type(item: dict[str, Any], *, kind: MediaKind, field: str) -> str:
+    """Name the MIME type from the item's own metadata, before any bytes exist."""
+    payload = item.get(field)
+    if not isinstance(payload, dict):
+        return _DEFAULT_MEDIA_TYPES[kind]
+    if kind is MediaKind.VOICE:
+        encode_type = payload.get("encode_type")
+        if isinstance(encode_type, int):
+            named = _VOICE_MEDIA_TYPES.get(encode_type)
+            if named is not None:
+                return named
+    if kind is MediaKind.FILE:
+        guessed, _ = guess_type(str(payload.get("file_name") or ""))
+        if guessed:
+            return guessed
+    return _DEFAULT_MEDIA_TYPES[kind]
+
+
+def _item_name(item: dict[str, Any], *, field: str) -> str | None:
+    """Return the sender-visible file name when the item carries one."""
+    payload = item.get(field)
+    if not isinstance(payload, dict):
+        return None
+    name = payload.get("file_name")
+    return name if isinstance(name, str) and name else None
+
+
+def media_refs(message: dict[str, Any], *, limit: int = MAX_MEDIA_ITEMS) -> list[MediaRef]:
+    """Return the downloadable media references of one raw iLink update.
+
+    The list stops at ``limit``: an update is untrusted input, and downloading
+    every reference an oversized payload names would cost memory the receiver
+    never agreed to hold.
+    """
+    refs: list[MediaRef] = []
+    for item in message.get("item_list") or []:
+        if not isinstance(item, dict):
+            continue
+        item_type = item.get("type")
+        fields = _MEDIA_ITEM_FIELDS.get(item_type) if isinstance(item_type, int) else None
+        ref = _media_ref(item, kind=fields[0], field=fields[1]) if fields is not None else None
+        if ref is not None:
+            refs.append(ref)
+            if len(refs) >= limit:
+                logger.warning("WeChat update names more than %d attachments; ignoring the rest", limit)
+                break
+    return refs
+
+
+def build_cdn_download_url(encrypt_query_param: str, cdn_base_url: str) -> str:
+    """Build the CDN download URL used when the server sent no ``full_url``."""
+    return f"{cdn_base_url.rstrip('/')}/download?encrypted_query_param={quote(encrypt_query_param, safe='')}"
+
+
+def parse_aes_key(aes_key_base64: str) -> bytes:
+    """Decode a wire ``aes_key`` into its raw 16 bytes.
+
+    Images publish ``base64(raw 16 bytes)``; files, voice, and video publish
+    ``base64(hex string of 16 bytes)``. Both encodings are accepted.
+    """
+    try:
+        decoded = base64.b64decode(aes_key_base64, validate=True)
+    except (binascii.Error, ValueError) as error:
+        raise ValueError("WeChat media aes_key is not valid base64") from error
+    if len(decoded) == _AES_BLOCK_BYTES:
+        return decoded
+    if len(decoded) == 2 * _AES_BLOCK_BYTES:
+        try:
+            return bytes.fromhex(decoded.decode("ascii"))
+        except (UnicodeDecodeError, ValueError) as error:
+            raise ValueError("WeChat media aes_key is neither 16 raw bytes nor 32 hex characters") from error
+    raise ValueError(f"WeChat media aes_key decodes to {len(decoded)} bytes instead of 16")
+
+
+def decrypt_aes_ecb(ciphertext: bytes, key: bytes) -> bytes:
+    """Decrypt one AES-128-ECB payload and drop its PKCS#7 padding when present."""
+    if len(key) != _AES_BLOCK_BYTES:
+        raise ValueError("WeChat media AES key must be 16 bytes")
+    if not ciphertext or len(ciphertext) % _AES_BLOCK_BYTES:
+        raise ValueError("WeChat media payload is not a whole number of AES blocks")
+    decryptor = Cipher(algorithms.AES(key), modes.ECB()).decryptor()
+    plaintext = decryptor.update(ciphertext) + decryptor.finalize()
+    return _strip_pkcs7(plaintext)
+
+
+def _strip_pkcs7(plaintext: bytes) -> bytes:
+    """Remove PKCS#7 padding, tolerating payloads that were never padded."""
+    padding = plaintext[-1]
+    if 1 <= padding <= _AES_BLOCK_BYTES and plaintext[-padding:] == bytes([padding]) * padding:
+        return plaintext[:-padding]
+    return plaintext
+
+
+def _image_media_type(data: bytes, fallback: str) -> str:
+    """Prefer the image format the bytes actually are."""
+    for signature, media_type in _IMAGE_SIGNATURES:
+        if data.startswith(signature):
+            return media_type
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    return fallback
+
+
+async def fetch_media(
+    client: httpx.AsyncClient,
+    ref: MediaRef,
+    *,
+    cdn_base_url: str = CDN_BASE_URL,
+    max_bytes: int = MAX_MEDIA_BYTES,
+) -> InboundMedia:
+    """Download, decrypt, and describe one referenced attachment.
+
+    Raises:
+        MediaTooLargeError: when the payload declares or delivers more than
+            ``max_bytes``.
+        ValueError: when the reference carries no download URL or cannot be
+            decrypted with its declared key.
+        httpx.HTTPError: when the CDN request itself fails.
+    """
+    if ref.full_url:
+        url = ref.full_url
+    elif ref.encrypt_query_param:
+        url = build_cdn_download_url(ref.encrypt_query_param, cdn_base_url)
+    else:
+        raise ValueError("WeChat media reference has neither full_url nor encrypt_query_param")
+    payload = await _download(client, url, max_bytes=max_bytes)
+    if ref.aes_key:
+        payload = decrypt_aes_ecb(payload, parse_aes_key(ref.aes_key))
+    if not payload:
+        raise ValueError("WeChat media payload is empty")
+    media_type = _image_media_type(payload, ref.media_type) if ref.kind is MediaKind.IMAGE else ref.media_type
+    return InboundMedia(kind=ref.kind, media_type=media_type, name=ref.name, data=payload)
+
+
+async def _download(client: httpx.AsyncClient, url: str, *, max_bytes: int) -> bytes:
+    """Read one CDN object, refusing to hold more than ``max_bytes`` of it.
+
+    The body is streamed, so a server that ignores the size contract cannot make
+    this process buffer an unbounded payload before the check runs.
+    """
+    async with client.stream("GET", url, timeout=MEDIA_DOWNLOAD_TIMEOUT_SECONDS, follow_redirects=True) as response:
+        response.raise_for_status()
+        declared = response.headers.get("content-length")
+        if declared is not None and declared.isdigit() and int(declared) > max_bytes:
+            raise MediaTooLargeError(f"WeChat media payload declares {declared} bytes, over the {max_bytes} byte limit")
+        payload = bytearray()
+        async for chunk in response.aiter_bytes():
+            payload.extend(chunk)
+            if len(payload) > max_bytes:
+                raise MediaTooLargeError(f"WeChat media payload exceeds the {max_bytes} byte limit")
+        return bytes(payload)
+
+
+__all__ = [
+    "CDN_BASE_URL",
+    "MEDIA_DOWNLOAD_TIMEOUT_SECONDS",
+    "MediaRef",
+    "build_cdn_download_url",
+    "decrypt_aes_ecb",
+    "fetch_media",
+    "media_refs",
+    "parse_aes_key",
+]

agim-0.0.1.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: agim
+Version: 0.0.1
+Summary: Standalone plugin toolkit for IM platform login, receive, and send
+Requires-Python: >=3.10
+Requires-Dist: cryptography<45,>=43
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<2.13,>=2.12
+Requires-Dist: typing-extensions<5,>=4.12; python_version < '3.12'
+Description-Content-Type: text/markdown
+
+# agim
+
+One stateless interface for IM login, receive, and send. agim is a plain SDK:
+it owns no storage, no plugin registry, and no host concepts. Callers persist
+the login handshake and receive cursor themselves and hand them back on the
+next call.
+
+## Interface
+
+```python
+class IMClient(ABC):
+    async def login(self) -> LoginHandshake: ...
+    async def is_login(self, handshake: LoginHandshake) -> LoginState: ...
+    async def receive(self, cursor: str | None = None) -> ReceiveResult: ...
+    async def send(self, chat_id: str, text: str, *, context_token: str | None = None) -> None: ...
+    async def aclose(self) -> None: ...
+```
+
+Because nothing is stored inside agim:
+
+- `login()` returns the QR payload **and** the provider state needed to poll it.
+  Persist the whole `LoginHandshake`, then pass it back to `is_login()`.
+- `receive()` returns the message **and** the next cursor. Persist the cursor,
+  then pass it to the next `receive()`.
+- `send()` takes the context token the caller stored from the inbound message.
+
+One `getupdates` poll can carry several messages. `receive()` still hands over
+exactly one message per call: the rest of the batch waits in memory (oldest
+first), and the returned cursor only advances past the batch once its last
+message has been handed over, so a restart mid-batch re-delivers that batch
+instead of dropping the messages behind the first one.
+
+## Platform clients
+
+`WeChatClient` implements the Tencent personal WeChat iLink/ClawBot protocol
+used by Tencent's official `openclaw-weixin` project: QR login, `getupdates`
+long polling, and `sendmessage`. More platforms (for example Discord)
+implement the same `IMClient` surface.
+
+Inbound messages carry their attachments on `InboundMessage.media`, one
+`InboundMedia` per image, voice note, file, or video. The client downloads the
+CDN reference and removes the AES-128-ECB encryption before returning, so a
+caller receives usable bytes; whether a given consumer reads an image, plays a
+voice note, or ignores both is the caller's decision. An item that cannot be
+downloaded or decrypted is logged and skipped: the message keeps the
+`[image]`/`[voice]`/`[file]`/`[video]` placeholder in its text. An item over
+`MAX_MEDIA_BYTES` raises `MediaTooLargeError` from `fetch_media` and is reported
+on `InboundMessage.rejected_media`, so a caller can tell the sender that the
+attachment was refused instead of losing it quietly.
+
+## Storage
+
+None. Whoever calls agim owns persistence.

agim-0.0.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+agim/__init__.py,sha256=R4lpeSr2bA88n-gzZNati6lZ9_1KItbD9OddE_8av7Q,1033
+agim/_compat.py,sha256=_0xpKWQWjDaAJO_cDYLm_9KrDUwvEMIKRncpO5ILFSg,1059
+agim/client.py,sha256=2hGlGh1voqC8bDhG9_s1UeT56S0uUViIpRdIfST8Ilo,1247
+agim/errors.py,sha256=1U_3BAfPd1FCTx5YVA9eJu0CldaPyDFPYDU3Rp5Bcto,434
+agim/log.py,sha256=GDkhUiRgkVi2FIcg-A3aardiS3IrObAiDZbskAKpmi8,450
+agim/models.py,sha256=C9pwDc3wTI7qJKUX9gnKIBAo7uD3la7dBBucKs9Jras,4382
+agim/wechat/__init__.py,sha256=bBhP5d8Ce-Pebn5A_N5i85YthUMDkcJ9bNT4ucBYIn4,436
+agim/wechat/auth.py,sha256=TQrYS3F5mWy-PtWWfYEM74DaQqDz47hyUAxKWxpA1Fo,5934
+agim/wechat/client.py,sha256=01EsbLfAhRvsKl2ztrsvDkJOP3U4Vst4cttJR9ZM5vk,12801
+agim/wechat/media.py,sha256=w5vVoOIz-GqIMPWWcNVCByRYnNRPWSK-S_bLtyzfeYM,10885
+agim-0.0.1.dist-info/METADATA,sha256=J1z3JpWWFwp7aqhnsk6o5CCIofhrvZJqui1tj4N4evQ,2837
+agim-0.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agim-0.0.1.dist-info/RECORD,,

agim-0.0.1.dist-info/WHEEL

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