ilink-sdk 2.4.10__py3-none-win_amd64.whl

ilink_sdk-2.4.10.data/purelib/ilink_sdk/__init__.py

@@ -0,0 +1,56 @@
+"""Python bindings for the iLink (Weixin) SDK.
+
+The bindings are a dependency-free (``ctypes``) wrapper around the Rust
+library's JSON C ABI. The top-level :func:`call` returns decoded Python data,
+while :class:`Client` returns typed :mod:`ilink_sdk.models` objects and carries
+default routing parameters for every call:
+
+>>> import ilink_sdk
+>>> ilink_sdk.version()
+'2.4.10'
+>>> ilink_sdk.call("mime.info", {"path": "photo.png"})["mime"]
+'image/png'
+>>> client = ilink_sdk.Client(account_id="cfe9a2017e77-im-bot")
+>>> client.send_text("someone@im.wechat", "hi").message_id
+'...'
+
+Set ``ILINK_SDK_LIB`` to the full path of ``ilink_sdk.dll`` /
+``libilink_sdk.so`` / ``libilink_sdk.dylib`` if it is not on the loader path.
+"""
+
+from . import models
+from ._call import IlinkError, call, version
+from ._ffi import library
+from .client import Client
+from .models import (
+    Account,
+    InboundMedia,
+    LoginResult,
+    LoginStart,
+    MessageItem,
+    MsgContext,
+    SendResult,
+    Updates,
+    UploadedFile,
+    WeixinMessage,
+)
+
+__all__ = [
+    "Account",
+    "Client",
+    "IlinkError",
+    "InboundMedia",
+    "LoginResult",
+    "LoginStart",
+    "MessageItem",
+    "MsgContext",
+    "SendResult",
+    "Updates",
+    "UploadedFile",
+    "WeixinMessage",
+    "call",
+    "library",
+    "models",
+    "version",
+]
+__version__ = "2.4.10"

ilink_sdk-2.4.10.data/purelib/ilink_sdk/_call.py

@@ -0,0 +1,62 @@
+"""Low-level, language-neutral access to the iLink SDK C ABI.
+
+Everything the SDK can do is reachable through :func:`call`: pass an operation
+name and a JSON-serialisable parameter mapping, get the operation result back as
+a decoded Python object. Failures raise :class:`IlinkError` carrying the
+``kind`` reported by the Rust error type.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import json
+from typing import Any, Mapping, Optional
+
+from ._ffi import library
+
+
+class IlinkError(Exception):
+    """An operation failed. ``kind`` mirrors ``ilink_sdk::ErrorKind``."""
+
+    def __init__(self, message: str, kind: str = "unknown") -> None:
+        super().__init__(message)
+        self.message = message
+        self.kind = kind
+
+
+def _take_string(ptr: int) -> str:
+    """Copy a ``char*`` returned by the library and release it."""
+    lib = library()
+    try:
+        return ctypes.string_at(ptr).decode("utf-8")
+    finally:
+        lib.ilink_string_free(ptr)
+
+
+def version() -> str:
+    """The SDK version string."""
+    ptr = library().ilink_version()
+    if not ptr:
+        raise IlinkError("ilink_version returned NULL")
+    return _take_string(ptr)
+
+
+def call(op: str, params: Optional[Mapping[str, Any]] = None) -> Any:
+    """Run one SDK operation and return its decoded ``result``.
+
+    >>> call("mime.info", {"path": "photo.png"})["mime"]
+    'image/png'
+    """
+    lib = library()
+    params_json = None if params is None else json.dumps(params)
+    raw = lib.ilink_call(
+        op.encode("utf-8"),
+        None if params_json is None else params_json.encode("utf-8"),
+    )
+    if not raw:
+        raise IlinkError("ilink_call returned NULL")
+
+    envelope = json.loads(_take_string(raw))
+    if envelope.get("ok"):
+        return envelope.get("result")
+    raise IlinkError(envelope.get("error", "operation failed"), envelope.get("kind", "unknown"))

ilink_sdk-2.4.10.data/purelib/ilink_sdk/_ffi.py

@@ -0,0 +1,84 @@
+"""ctypes loader for the iLink SDK shared library.
+
+The Rust crate builds `ilink_sdk.dll` / `libilink_sdk.so` / `libilink_sdk.dylib`
+with a single JSON-in / JSON-out C ABI (see `include/ilink_sdk.h`). This module
+finds and loads that library once, and exposes thin wrappers around the three
+exported symbols.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import os
+import sys
+from typing import Optional
+
+_LIB_ENV = "ILINK_SDK_LIB"
+
+
+def _library_filenames() -> list[str]:
+    if sys.platform == "win32":
+        return ["ilink_sdk.dll"]
+    if sys.platform == "darwin":
+        return ["libilink_sdk.dylib"]
+    return ["libilink_sdk.so"]
+
+
+def _candidate_paths() -> list[str]:
+    candidates: list[str] = []
+    override = os.environ.get(_LIB_ENV)
+    if override:
+        candidates.append(override)
+
+    names = _library_filenames()
+    here = os.path.dirname(os.path.abspath(__file__))
+    # 1. next to this package (installed wheel / copied library)
+    # 2. the repository's cargo output (development checkout)
+    roots = [
+        here,
+        os.path.join(here, "..", "..", "..", "target", "release"),
+        os.path.join(os.getcwd(), "target", "release"),
+    ]
+    for root in roots:
+        for name in names:
+            candidates.append(os.path.normpath(os.path.join(root, name)))
+
+    # 3. whatever the OS loader knows about
+    found = ctypes.util.find_library("ilink_sdk")
+    if found:
+        candidates.append(found)
+    candidates.extend(names)
+    return candidates
+
+
+_lib: Optional[ctypes.CDLL] = None
+
+
+def library() -> ctypes.CDLL:
+    """Load (once) and return the shared library."""
+    global _lib
+    if _lib is not None:
+        return _lib
+
+    errors: list[str] = []
+    for path in _candidate_paths():
+        try:
+            lib = ctypes.CDLL(path)
+        except OSError as exc:  # pragma: no cover - depends on host layout
+            errors.append(f"{path}: {exc}")
+            continue
+        lib.ilink_call.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
+        lib.ilink_call.restype = ctypes.c_void_p
+        lib.ilink_version.argtypes = []
+        lib.ilink_version.restype = ctypes.c_void_p
+        lib.ilink_string_free.argtypes = [ctypes.c_void_p]
+        lib.ilink_string_free.restype = None
+        _lib = lib
+        return lib
+
+    tried = "\n  ".join(errors) if errors else "(no candidates)"
+    raise OSError(
+        f"could not load the iLink SDK library; set {_LIB_ENV} to its full path.\n"
+        f"Tried:\n  {tried}"
+    )

ilink_sdk-2.4.10.data/purelib/ilink_sdk/client.py

@@ -0,0 +1,444 @@
+"""An ergonomic client that carries default routing parameters.
+
+``Client`` is a convenience layer over :func:`ilink_sdk.call`. Every method
+returns a typed :mod:`ilink_sdk.models` object rather than a bare ``dict``, and
+accepts an optional override of the routing parameters (``account_id``,
+``base_url``, ``cdn_base_url``, ``route_tag``, ``bot_agent``, ``timeout_ms``);
+the ones set on the client are applied to every call.
+
+>>> client = Client(account_id="cfe9a2017e77-im-bot")
+>>> result = client.send_text("someone@im.wechat", "hi")
+>>> result.message_id
+'...'
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any, List, Mapping, Optional, Type, TypeVar, Union
+
+from . import models
+from ._call import call as _call
+from .models import from_dict
+
+T = TypeVar("T")
+
+_ROUTING = ("account_id", "base_url", "cdn_base_url", "route_tag", "bot_agent", "timeout_ms")
+
+
+class Client:
+    def __init__(
+        self,
+        account_id: Optional[str] = None,
+        base_url: Optional[str] = None,
+        cdn_base_url: Optional[str] = None,
+        route_tag: Optional[str] = None,
+        bot_agent: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+    ) -> None:
+        defaults: dict[str, Any] = {
+            "account_id": account_id,
+            "base_url": base_url,
+            "cdn_base_url": cdn_base_url,
+            "route_tag": route_tag,
+            "bot_agent": bot_agent,
+            "timeout_ms": timeout_ms,
+        }
+        self._defaults = {k: v for k, v in defaults.items() if v is not None}
+
+    # -- plumbing -----------------------------------------------------------
+    def call(self, op: str, params: Optional[Mapping[str, Any]] = None) -> Any:
+        """Run any operation with the client's routing parameters merged in.
+
+        Returns the decoded ``result`` as plain Python data. Use
+        :meth:`call_into` when you want a typed model.
+        """
+        merged: dict[str, Any] = dict(self._defaults)
+        if params:
+            merged.update(params)
+        return _call(op, merged)
+
+    def call_into(
+        self,
+        op: str,
+        model: Type[T],
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> T:
+        """Run any operation and decode the result into ``model``."""
+        return from_dict(model, self.call(op, params))
+
+    # -- meta ---------------------------------------------------------------
+    def version(self) -> str:
+        return self.call("version")
+
+    def paths(self) -> models.Paths:
+        return self.call_into("paths", models.Paths)
+
+    # -- accounts -----------------------------------------------------------
+    def accounts(self) -> List[models.Account]:
+        return [from_dict(models.Account, item) for item in self.call("accounts.list")]
+
+    def resolve_account(self, account_id: str) -> models.Account:
+        return self.call_into("account.resolve", models.Account, {"account_id": account_id})
+
+    def save_account(
+        self,
+        account_id: str,
+        token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> models.Account:
+        return self.call_into(
+            "account.save",
+            models.Account,
+            {"account_id": account_id, "token": token, "base_url": base_url, "user_id": user_id},
+        )
+
+    def clear_account(self, account_id: str) -> None:
+        """Forget an account and all of its local state."""
+        self.call("account.clear", {"account_id": account_id})
+
+    # -- QR login -----------------------------------------------------------
+    def login_start(
+        self, base_url: Optional[str] = None, bot_type: Optional[str] = None
+    ) -> models.LoginStart:
+        """Begin a QR login; display ``qrcode_url`` to the user."""
+        return self.call_into(
+            "login.start", models.LoginStart, {"base_url": base_url, "bot_type": bot_type}
+        )
+
+    def login_poll(self, session_key: str) -> models.LoginPoll:
+        """Non-blocking status check for a login session."""
+        return self.call_into("login.poll", models.LoginPoll, {"session_key": session_key})
+
+    def login_submit_verify_code(self, session_key: str, code: str) -> None:
+        self.call("login.submit_verify_code", {"session_key": session_key, "code": code})
+
+    def login_refresh(self, session_key: str) -> models.LoginStart:
+        return self.call_into("login.refresh", models.LoginStart, {"session_key": session_key})
+
+    def login_wait(
+        self,
+        session_key: str,
+        timeout_secs: int = 480,
+        verify_code: Optional[str] = None,
+    ) -> models.LoginResult:
+        """Wait for confirmation without persisting the credentials."""
+        return self.call_into(
+            "login.wait",
+            models.LoginResult,
+            {
+                "session_key": session_key,
+                "timeout_secs": timeout_secs,
+                "verify_code": verify_code,
+            },
+        )
+
+    def login_complete(
+        self,
+        session_key: str,
+        timeout_secs: int = 480,
+        verify_code: Optional[str] = None,
+    ) -> models.LoginResult:
+        """Wait for confirmation and persist the credentials."""
+        return self.call_into(
+            "login.complete",
+            models.LoginResult,
+            {
+                "session_key": session_key,
+                "timeout_secs": timeout_secs,
+                "verify_code": verify_code,
+            },
+        )
+
+    # -- outbound -----------------------------------------------------------
+    def send_text(
+        self,
+        to: str,
+        text: str,
+        context_token: Optional[str] = None,
+        run_id: Optional[str] = None,
+    ) -> models.SendResult:
+        return self.call_into(
+            "send.text",
+            models.SendResult,
+            {"to": to, "text": text, "context_token": context_token, "run_id": run_id},
+        )
+
+    def send_file(
+        self,
+        to: str,
+        path: str,
+        caption: Optional[str] = None,
+        context_token: Optional[str] = None,
+    ) -> models.SendResult:
+        """Send a local image / video / file, chosen by its MIME type."""
+        return self.call_into(
+            "send.file",
+            models.SendResult,
+            {"to": to, "path": path, "caption": caption, "context_token": context_token},
+        )
+
+    def send_bytes(
+        self,
+        to: str,
+        file_name: str,
+        data: Union[bytes, bytearray, str],
+        caption: Optional[str] = None,
+        context_token: Optional[str] = None,
+    ) -> models.SendResult:
+        """Send in-memory bytes; ``data`` is base64 encoded for the wire."""
+        if isinstance(data, str):
+            encoded = data
+        else:
+            encoded = base64.b64encode(bytes(data)).decode("ascii")
+        return self.call_into(
+            "send.bytes",
+            models.SendResult,
+            {
+                "to": to,
+                "file_name": file_name,
+                "data_base64": encoded,
+                "caption": caption,
+                "context_token": context_token,
+            },
+        )
+
+    def send_item(
+        self,
+        to: str,
+        item: Union[Mapping[str, Any], models.MessageItem],
+        context_token: Optional[str] = None,
+    ) -> models.SendResult:
+        """Send a raw protocol item (advanced)."""
+        raw = item if isinstance(item, Mapping) else _dataclass_to_dict(item)
+        return self.call_into(
+            "send.item",
+            models.SendResult,
+            {"to": to, "item": raw, "context_token": context_token},
+        )
+
+    # -- inbound / API ------------------------------------------------------
+    def get_updates(
+        self, get_updates_buf: Optional[str] = None, timeout_ms: Optional[int] = None
+    ) -> models.Updates:
+        """Long-poll for inbound messages; pass the previous cursor back in."""
+        return self.call_into(
+            "get_updates",
+            models.Updates,
+            {"get_updates_buf": get_updates_buf, "timeout_ms": timeout_ms},
+        )
+
+    def get_config(self, user_id: str, context_token: Optional[str] = None) -> models.GetConfig:
+        return self.call_into(
+            "get_config",
+            models.GetConfig,
+            {"user_id": user_id, "context_token": context_token},
+        )
+
+    def send_typing(
+        self, user_id: str, typing_ticket: str, status: str = "typing"
+    ) -> None:
+        self.call(
+            "send_typing",
+            {"user_id": user_id, "typing_ticket": typing_ticket, "status": status},
+        )
+
+    def notify(self, action: str = "start") -> None:
+        """Lifecycle ping (``start`` or ``stop``)."""
+        self.call("notify", {"action": action})
+
+    def context_to_message(
+        self, message: Union[Mapping[str, Any], models.WeixinMessage], account_id: Optional[str] = None
+    ) -> models.MsgContext:
+        """Parse a raw inbound message into a :class:`MsgContext`."""
+        raw = message if isinstance(message, Mapping) else _dataclass_to_dict(message)
+        return self.call_into(
+            "context.to_message", models.MsgContext, {"message": raw, "account_id": account_id}
+        )
+
+    def message_body(self, items: List[Union[Mapping[str, Any], models.MessageItem]]) -> str:
+        """Extract the display body from a list of message items."""
+        raw = [i if isinstance(i, Mapping) else _dataclass_to_dict(i) for i in items]
+        return self.call("message.body", {"items": raw})["body"]
+
+    # -- media --------------------------------------------------------------
+    def upload(self, to: str, path: str, media_type: str = "file") -> models.UploadedFile:
+        """Upload a file to the CDN and return its reference."""
+        return self.call_into(
+            "media.upload",
+            models.UploadedFile,
+            {"to": to, "path": path, "media_type": media_type},
+        )
+
+    def download(
+        self,
+        media: Union[Mapping[str, Any], models.CdnMedia],
+        aes_key: Optional[str] = None,
+        dest_path: Optional[str] = None,
+    ) -> models.MediaFetch:
+        """Download a CDN reference, decrypting it when ``aes_key`` is given."""
+        raw = media if isinstance(media, Mapping) else _dataclass_to_dict(media)
+        return self.call_into(
+            "media.download",
+            models.MediaFetch,
+            {"media": raw, "aes_key": aes_key, "dest_path": dest_path},
+        )
+
+    def fetch(self, url: str, dest_path: Optional[str] = None) -> models.MediaFetch:
+        return self.call_into(
+            "media.fetch", models.MediaFetch, {"url": url, "dest_path": dest_path}
+        )
+
+    def download_item(
+        self,
+        item: Union[Mapping[str, Any], models.MessageItem],
+        dest_dir: Optional[str] = None,
+    ) -> models.InboundMedia:
+        """Download every media referenced by an inbound message item."""
+        raw = item if isinstance(item, Mapping) else _dataclass_to_dict(item)
+        return self.call_into(
+            "media.download_item", models.InboundMedia, {"item": raw, "dest_dir": dest_dir}
+        )
+
+    # -- quote cache --------------------------------------------------------
+    def quote_policy(self) -> models.QuotePolicy:
+        return self.call_into("quote.policy", models.QuotePolicy)
+
+    def quote_find(
+        self, account_id: str, conversation_id: str, message_id: str
+    ) -> Optional[models.QuoteRecord]:
+        result = self.call(
+            "quote.find",
+            {
+                "account_id": account_id,
+                "conversation_id": conversation_id,
+                "message_id": message_id,
+            },
+        )
+        return None if result is None else from_dict(models.QuoteRecord, result)
+
+    def quote_put(
+        self,
+        account_id: str,
+        conversation_id: str,
+        message_id: str,
+        body: str = "",
+        direction: str = "inbound",
+        source_media_path: Optional[str] = None,
+        media_mime: Optional[str] = None,
+        media_name: Optional[str] = None,
+        created_at: int = 0,
+    ) -> None:
+        self.call(
+            "quote.put",
+            {
+                "account_id": account_id,
+                "conversation_id": conversation_id,
+                "message_id": message_id,
+                "body": body,
+                "direction": direction,
+                "source_media_path": source_media_path,
+                "media_mime": media_mime,
+                "media_name": media_name,
+                "created_at": created_at,
+            },
+        )
+
+    def quote_gc(self) -> None:
+        self.call("quote.gc")
+
+    def quote_media_dir(self, account_id: str) -> str:
+        return self.call("quote.media_dir", {"account_id": account_id})["path"]
+
+    # -- context tokens -----------------------------------------------------
+    def context_get(self, account_id: str, user_id: str) -> Optional[str]:
+        result = self.call("context.get", {"account_id": account_id, "user_id": user_id})
+        return None if result is None else result["token"]
+
+    def context_set(self, account_id: str, user_id: str, token: str) -> None:
+        self.call("context.set", {"account_id": account_id, "user_id": user_id, "token": token})
+
+    def context_clear(self, account_id: str) -> None:
+        self.call("context.clear", {"account_id": account_id})
+
+    def context_restore(self, account_id: str) -> int:
+        return self.call("context.restore", {"account_id": account_id})["restored"]
+
+    # -- sync cursor --------------------------------------------------------
+    def sync_load(self, account_id: str) -> str:
+        return self.call("sync.load", {"account_id": account_id})["get_updates_buf"]
+
+    def sync_save(self, account_id: str, buf: str) -> None:
+        self.call("sync.save", {"account_id": account_id, "buf": buf})
+
+    def sync_clear(self, account_id: str) -> None:
+        self.call("sync.clear", {"account_id": account_id})
+
+    # -- session guard ------------------------------------------------------
+    def session_status(self, account_id: Optional[str] = None) -> models.SessionStatus:
+        return self.call_into(
+            "session.status",
+            models.SessionStatus,
+            {"account_id": account_id} if account_id else None,
+        )
+
+    def session_pause(self, account_id: str) -> None:
+        self.call("session.pause", {"account_id": account_id})
+
+    def session_resume(self, account_id: str) -> None:
+        self.call("session.resume", {"account_id": account_id})
+
+    def session_assert(self, account_id: str) -> None:
+        """Raise :class:`IlinkError` when the session is paused."""
+        self.call("session.assert", {"account_id": account_id})
+
+    # -- helpers ------------------------------------------------------------
+    def mime_info(self, path: str) -> models.MimeInfo:
+        return self.call_into("mime.info", models.MimeInfo, {"path": path})
+
+    def mime_extension(self, mime: str) -> str:
+        return self.call("mime.extension", {"mime": mime})["extension"]
+
+    def generate_id(self, prefix: str = "ilink-sdk") -> str:
+        return self.call("util.generate_id", {"prefix": prefix})["id"]
+
+    def file_key(self) -> str:
+        return self.call("util.file_key")["file_key"]
+
+    def temp_name(self, prefix: str = "ilink-sdk", ext: str = "") -> str:
+        return self.call("util.temp_name", {"prefix": prefix, "ext": ext})["name"]
+
+    def config_load(self) -> models.ConfigLoad:
+        return self.call_into("config.load", models.ConfigLoad)
+
+    # -- crypto -------------------------------------------------------------
+    def crypto_encrypt(self, key_hex: str, data: Union[bytes, bytearray, str]) -> models.CryptoResult:
+        encoded = data if isinstance(data, str) else base64.b64encode(bytes(data)).decode("ascii")
+        return self.call_into(
+            "crypto.encrypt",
+            models.CryptoResult,
+            {"key_hex": key_hex, "data_base64": encoded},
+        )
+
+    def crypto_decrypt(self, key_hex: str, data_base64: str) -> bytes:
+        result = self.call("crypto.decrypt", {"key_hex": key_hex, "data_base64": data_base64})
+        return base64.b64decode(result["data_base64"])
+
+
+def _dataclass_to_dict(obj: Any) -> Mapping[str, Any]:
+    """Convert a model instance back into the wire dictionary."""
+    import dataclasses
+
+    out: dict[str, Any] = {}
+    for f in dataclasses.fields(obj):
+        value = getattr(obj, f.name)
+        if value is None:
+            continue
+        key = f.metadata.get("json", f.name)
+        if dataclasses.is_dataclass(value):
+            value = _dataclass_to_dict(value)
+        elif isinstance(value, list):
+            value = [_dataclass_to_dict(v) if dataclasses.is_dataclass(v) else v for v in value]
+        out[key] = value
+    return out

ilink_sdk-2.4.10.data/purelib/ilink_sdk/models.py

@@ -0,0 +1,471 @@
+"""Typed result models for the iLink SDK Python bindings.
+
+Every operation result is decoded into a :mod:`dataclasses` instance so callers
+get attribute access and type hints instead of poking at dictionaries. The
+models are tolerant: unknown JSON keys are ignored and missing keys fall back
+to the declared defaults, so a newer server never breaks an older binding.
+
+>>> from ilink_sdk import Client
+>>> client = Client(account_id="cfe9a2017e77-im-bot")
+>>> client.send_text("someone@im.wechat", "hi").message_id
+'...'
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import types
+from dataclasses import dataclass, field
+from typing import Any, List, Mapping, Optional, Union, get_args, get_origin, get_type_hints
+
+__all__ = [
+    "Account",
+    "CdnMedia",
+    "ConfigLoad",
+    "CryptoResult",
+    "FileItem",
+    "GetConfig",
+    "ImageItem",
+    "InboundMedia",
+    "LoginPoll",
+    "LoginResult",
+    "LoginStart",
+    "MediaEntry",
+    "MediaFetch",
+    "MessageItem",
+    "MimeInfo",
+    "MsgContext",
+    "PartialText",
+    "Paths",
+    "QrSession",
+    "QuotePolicy",
+    "QuoteRecord",
+    "RefMessage",
+    "SendResult",
+    "SessionStatus",
+    "TextItem",
+    "Updates",
+    "UploadedFile",
+    "VideoItem",
+    "VoiceItem",
+    "WeixinMessage",
+    "from_dict",
+]
+
+_UNION_TYPES = (Union, types.UnionType)
+
+
+def _coerce(value: Any, hint: Any) -> Any:
+    """Convert a decoded JSON value into the type described by ``hint``."""
+    if value is None:
+        return None
+    origin = get_origin(hint)
+    if origin is not None:
+        args = get_args(hint)
+        if origin in _UNION_TYPES:
+            non_none = [a for a in args if a is not type(None)]
+            return _coerce(value, non_none[0]) if non_none else value
+        if origin in (list, List):
+            item_hint = args[0] if args else Any
+            return [_coerce(item, item_hint) for item in value]
+        return value
+    if dataclasses.is_dataclass(hint):
+        return from_dict(hint, value)
+    return value
+
+
+def from_dict(cls: type, data: Optional[Mapping[str, Any]]) -> Any:
+    """Build ``cls`` from a decoded JSON object, ignoring unknown keys.
+
+    A field may declare the JSON key it maps to through dataclass metadata, so
+    Python keywords such as ``from`` can be exposed as ``from_``::
+
+        from_: Optional[str] = field(default=None, metadata={"json": "from"})
+    """
+    if data is None:
+        return None
+    hints = get_type_hints(cls)
+    kwargs: dict[str, Any] = {}
+    for f in dataclasses.fields(cls):
+        key = f.metadata.get("json", f.name)
+        if key in data:
+            kwargs[f.name] = _coerce(data[key], hints.get(f.name, Any))
+    return cls(**kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Meta
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Paths:
+    state_dir: str = ""
+    sdk_state_dir: str = ""
+    accounts_dir: str = ""
+    config_path: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Accounts
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Account:
+    account_id: str = ""
+    base_url: str = ""
+    cdn_base_url: str = ""
+    configured: bool = False
+    enabled: bool = False
+    user_id: Optional[str] = None
+    name: Optional[str] = None
+    route_tag: Optional[str] = None
+    token_present: bool = False
+
+
+@dataclass
+class QrSession:
+    token: str = ""
+    bot_id: str = ""
+    base_url: str = ""
+    user_id: str = ""
+
+
+@dataclass
+class LoginStart:
+    qrcode: str = ""
+    qrcode_url: str = ""
+    session_key: str = ""
+
+
+@dataclass
+class LoginPoll:
+    kind: str = ""
+    retry: Optional[int] = None
+    session: Optional[QrSession] = None
+
+
+@dataclass
+class LoginResult:
+    connected: bool = False
+    already_connected: bool = False
+    message: str = ""
+    account_id: Optional[str] = None
+    session: Optional[QrSession] = None
+
+
+# ---------------------------------------------------------------------------
+# Outbound
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SendResult:
+    message_id: str = ""
+    server_message_id: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Wire types
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class TextItem:
+    text: Optional[str] = None
+
+
+@dataclass
+class CdnMedia:
+    encrypt_query_param: Optional[str] = None
+    aes_key: Optional[str] = None
+    encrypt_type: Optional[int] = None
+    full_url: Optional[str] = None
+
+
+@dataclass
+class ImageItem:
+    media: Optional[CdnMedia] = None
+    thumb_media: Optional[CdnMedia] = None
+    aeskey: Optional[str] = None
+    url: Optional[str] = None
+    mid_size: Optional[int] = None
+    thumb_size: Optional[int] = None
+    thumb_height: Optional[int] = None
+    thumb_width: Optional[int] = None
+    hd_size: Optional[int] = None
+
+
+@dataclass
+class VoiceItem:
+    media: Optional[CdnMedia] = None
+    encode_type: Optional[int] = None
+    bits_per_sample: Optional[int] = None
+    sample_rate: Optional[int] = None
+    playtime: Optional[int] = None
+    text: Optional[str] = None
+
+
+@dataclass
+class FileItem:
+    media: Optional[CdnMedia] = None
+    file_name: Optional[str] = None
+    md5: Optional[str] = None
+    len: Optional[str] = None
+
+
+@dataclass
+class VideoItem:
+    media: Optional[CdnMedia] = None
+    video_size: Optional[int] = None
+    play_length: Optional[int] = None
+    video_md5: Optional[str] = None
+    thumb_media: Optional[CdnMedia] = None
+    thumb_size: Optional[int] = None
+    thumb_height: Optional[int] = None
+    thumb_width: Optional[int] = None
+
+
+@dataclass
+class PartialText:
+    start: str = ""
+    end: str = ""
+    startindex: int = 0
+    endindex: int = 0
+    quotemd5: str = ""
+
+
+@dataclass
+class RefMessage:
+    message_item: Optional["MessageItem"] = None
+    title: Optional[str] = None
+    svr_id: Optional[str] = None
+    partial_text: Optional[PartialText] = None
+
+
+@dataclass
+class MessageItem:
+    type: Optional[int] = None
+    msg_id: Optional[str] = None
+    create_time_ms: Optional[int] = None
+    update_time_ms: Optional[int] = None
+    is_completed: Optional[bool] = None
+    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
+
+    @property
+    def text(self) -> Optional[str]:
+        """The text of a text item, when this is one."""
+        return self.text_item.text if self.text_item else None
+
+
+@dataclass
+class WeixinMessage:
+    seq: Optional[int] = None
+    message_id: Optional[str] = None
+    from_user_id: Optional[str] = None
+    to_user_id: Optional[str] = None
+    client_id: Optional[str] = None
+    create_time_ms: Optional[int] = None
+    update_time_ms: Optional[int] = None
+    delete_time_ms: Optional[int] = None
+    session_id: Optional[str] = None
+    group_id: Optional[str] = None
+    message_type: Optional[int] = None
+    message_state: Optional[int] = None
+    item_list: List[MessageItem] = field(default_factory=list)
+    context_token: Optional[str] = None
+    run_id: Optional[str] = None
+
+
+@dataclass
+class Updates:
+    """Result of :meth:`Client.get_updates`."""
+
+    ret: Optional[int] = None
+    errcode: Optional[int] = None
+    errmsg: Optional[str] = None
+    msgs: List[WeixinMessage] = field(default_factory=list)
+    get_updates_buf: Optional[str] = None
+    longpolling_timeout_ms: Optional[int] = None
+
+    @property
+    def messages(self) -> List[WeixinMessage]:
+        """Alias for :attr:`msgs`."""
+        return self.msgs
+
+    @property
+    def is_error(self) -> bool:
+        """``True`` when the server reported a business-level failure."""
+        return bool(self.ret) or bool(self.errcode)
+
+
+# ---------------------------------------------------------------------------
+# Inbound context
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class MediaEntry:
+    path: str = ""
+    content_type: Optional[str] = None
+    file_name: Optional[str] = None
+    message_id: Optional[str] = None
+
+
+@dataclass
+class MsgContext:
+    body: str = ""
+    from_: Optional[str] = field(default=None, metadata={"json": "from"})
+    to: str = ""
+    account_id: str = ""
+    originating_channel: str = ""
+    originating_to: str = ""
+    message_sid: str = ""
+    message_sid_full: Optional[str] = None
+    timestamp: Optional[int] = None
+    provider: str = ""
+    chat_type: str = ""
+    session_key: Optional[str] = None
+    context_token: Optional[str] = None
+    media_path: Optional[str] = None
+    media_type: Optional[str] = None
+    media_paths: List[str] = field(default_factory=list)
+    media_types: List[str] = field(default_factory=list)
+    media: List[MediaEntry] = field(default_factory=list)
+    channel_prompt_context: List[str] = field(default_factory=list)
+    reply_to_id: Optional[str] = None
+    reply_to_body: Optional[str] = None
+    reply_to_quote_text: Optional[str] = None
+    reply_to_is_quote: Optional[bool] = None
+
+
+# ---------------------------------------------------------------------------
+# Media
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class UploadedFile:
+    filekey: str = ""
+    download_param: str = ""
+    aeskey_hex: str = ""
+    aes_key_base64: str = ""
+    file_size: int = 0
+    file_size_ciphertext: int = 0
+
+
+@dataclass
+class InboundMedia:
+    image_path: Optional[str] = None
+    voice_path: Optional[str] = None
+    voice_mime: Optional[str] = None
+    file_path: Optional[str] = None
+    file_mime: Optional[str] = None
+    video_path: Optional[str] = None
+    referenced: bool = False
+    is_empty: bool = False
+
+    @property
+    def paths(self) -> List[str]:
+        """Every downloaded local path, in a stable order."""
+        return [p for p in (self.image_path, self.voice_path, self.file_path, self.video_path) if p]
+
+
+@dataclass
+class MediaFetch:
+    bytes: int = 0
+    path: Optional[str] = None
+    data_base64: Optional[str] = None
+
+    def data(self) -> Optional[bytes]:
+        """The fetched payload when it was returned inline (base64 decoded)."""
+        if self.data_base64 is None:
+            return None
+        import base64
+
+        return base64.b64decode(self.data_base64)
+
+
+# ---------------------------------------------------------------------------
+# Quote cache
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class QuotePolicy:
+    enabled: bool = False
+    retention_ms: int = 0
+    max_messages_per_account: int = 0
+    media_retention_ms: int = 0
+    max_media_bytes_per_account: int = 0
+    max_single_media_bytes: int = 0
+
+
+@dataclass
+class QuoteRecord:
+    account_id: str = ""
+    conversation_id: str = ""
+    message_id: str = ""
+    direction: str = "inbound"
+    body: str = ""
+    media_path: Optional[str] = None
+    media_mime: Optional[str] = None
+    media_name: Optional[str] = None
+    media_size: Optional[int] = None
+    created_at: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Session / helpers
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SessionStatus:
+    paused: bool = False
+    remaining_ms: int = 0
+
+
+@dataclass
+class GetConfig:
+    ret: Optional[int] = None
+    errmsg: Optional[str] = None
+    typing_ticket: Optional[str] = None
+
+    @property
+    def is_ok(self) -> bool:
+        return self.ret == 0
+
+
+@dataclass
+class MimeInfo:
+    mime: str = ""
+    kind: str = ""
+    extension: str = ""
+    is_image: bool = False
+    is_video: bool = False
+    is_audio: bool = False
+
+
+@dataclass
+class ConfigLoad:
+    config: Mapping[str, Any] = field(default_factory=dict)
+    quote_cache_policy: Optional[QuotePolicy] = None
+
+
+@dataclass
+class CryptoResult:
+    data_base64: str = ""
+    padded_size: Optional[int] = None
+
+    def data(self) -> bytes:
+        """The ciphertext, base64 decoded."""
+        import base64
+
+        return base64.b64decode(self.data_base64)

ilink_sdk-2.4.10.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: ilink-sdk
+Version: 2.4.10
+Summary: Python bindings for the iLink (Weixin) SDK, with the native library bundled
+Author: iLink SDK contributors
+License: MIT
+Project-URL: Homepage, https://github.com/x500x/iLink-SDK-rs
+Project-URL: Repository, https://github.com/x500x/iLink-SDK-rs
+Project-URL: Documentation, https://github.com/x500x/iLink-SDK-rs/blob/main/bindings/python/README.md
+Keywords: weixin,ilink,im,sdk,bot,wechat
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Rust
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# iLink SDK — Python
+
+> 中文版: [README.zh.md](README.zh.md)
+
+Dependency-free (`ctypes`) Python bindings for the Rust `ilink-sdk` library.
+The platform wheels on PyPI bundle the native library, so `pip install` works
+with no Rust toolchain and no manual library setup.
+
+## Install
+
+```bash
+pip install ilink-sdk
+```
+
+Published on PyPI: <https://pypi.org/project/ilink-sdk/>.
+
+That installs a platform wheel (`ilink_sdk.dll` / `libilink_sdk.so` /
+`libilink_sdk.dylib` is inside the package). The loader looks for the library in
+this order, so you can override it when needed:
+
+1. `$ILINK_SDK_LIB` (full path to the shared library),
+2. next to the installed package (this is where the wheel puts it),
+3. `target/release/` of a source checkout,
+4. the system loader path.
+
+### From source
+
+Building the wheel yourself requires a Rust toolchain, because the native
+library is compiled from the crate in this repository:
+
+```bash
+cargo build --release            # from the repository root, produces the library
+pip install ./bindings/python    # copies it into the wheel
+```
+
+`setup.py` finds the library at `target/release/` (or `$ILINK_SDK_LIB`) and
+copies it into `ilink_sdk/`; the resulting wheel is tagged for the current
+platform (`py3-none-<plat>`). To build one wheel per platform, run this on each
+OS/arch (which is what CI does).
+
+## Usage
+
+```python
+import ilink_sdk
+
+print(ilink_sdk.version())                              # '2.4.10'
+print(ilink_sdk.call("mime.info", {"path": "a.png"}))   # decoded result object
+
+client = ilink_sdk.Client(account_id="cfe9a2017e77-im-bot")
+
+# Typed helpers return dataclasses from ilink_sdk.models.
+info = client.mime_info("a.png")            # models.MimeInfo
+print(info.mime, info.is_image)
+
+# QR login
+start = client.login_start()                # models.LoginStart
+print(start.qrcode_url)
+result = client.login_complete(start.session_key)   # blocks until scanned
+account_id = result.account_id
+
+# Send a message
+sent = client.send_text("someone@im.wechat", "hello from Python")
+print(sent.message_id)
+
+# Long-poll for inbound messages
+updates = client.get_updates()              # models.Updates
+for message in updates.messages:
+    print(message.message_id)
+```
+
+## Common workflows
+
+### Media
+
+```python
+# Upload a file to the CDN (media_type: image | video | file | voice)
+uploaded = client.upload("someone@im.wechat", "big.png", media_type="image")
+print(uploaded.filekey, uploaded.aes_key_base64)
+
+# Download and decrypt a CDN reference, writing it to disk
+got = client.download({"encrypt_query_param": "...", "aes_key": "..."},
+                      dest_path="/tmp/out.png")
+print(got.bytes, got.path)
+
+# Fetch a URL; without dest_path the bytes come back inline, base64 decoded
+inline = client.fetch("https://example.com/a.bin")
+raw = inline.data()                      # bytes | None
+
+# Download every media referenced by an inbound message item
+media = client.download_item(msg.item_list[1], dest_dir="/tmp")
+print(media.paths())                     # ['/tmp/...']
+```
+
+### Context tokens & sync cursor
+
+```python
+client.context_set(account_id, user_id, token)
+token = client.context_get(account_id, user_id)   # str | None
+client.context_clear(account_id)
+client.context_restore(account_id)                # -> int (restored count)
+
+cursor = client.sync_load(account_id)
+client.sync_save(account_id, cursor)
+client.sync_clear(account_id)
+```
+
+### Session guard
+
+```python
+client.session_pause(account_id)
+status = client.session_status(account_id)        # models.SessionStatus
+print(status.paused, status.remaining_ms)
+client.session_resume(account_id)
+client.session_assert(account_id)                 # raises when paused
+```
+
+### Quote cache
+
+```python
+policy = client.quote_policy()                    # models.QuotePolicy
+client.quote_put(account_id, conversation_id, message_id, body="hi")
+record = client.quote_find(account_id, conversation_id, message_id)  # models.QuoteRecord | None
+client.quote_gc()
+print(client.quote_media_dir(account_id))
+```
+
+### Any operation, typed
+
+```python
+paths = client.call_into("paths", ilink_sdk.models.Paths)
+config = client.config_load()                     # models.ConfigLoad
+raw = client.call("mime.extension", {"mime": "image/png"})   # plain dict
+```
+
+## Errors
+
+Failures raise `ilink_sdk.IlinkError` with the Rust `kind` attached:
+
+```python
+try:
+    client.send_text("someone@im.wechat", "hi")
+except ilink_sdk.IlinkError as err:
+    if err.kind in ("timeout", "cancelled"):
+        ...   # retry or stop cleanly
+    raise
+```
+
+## API
+
+`call(op, params=None)` reaches **every** operation (see
+[`docs/reference/ffi.md`](../../docs/reference/ffi.md)) and returns decoded
+Python data. `Client` adds typed helpers for the common flows, returning
+[`ilink_sdk.models`](ilink_sdk/models.py) dataclasses (`Account`, `LoginStart`,
+`LoginResult`, `SendResult`, `Updates`, `MsgContext`, `UploadedFile`,
+`InboundMedia`, `MimeInfo`, ...), and applies default routing parameters
+(`account_id`, `base_url`, `cdn_base_url`, `route_tag`, `bot_agent`,
+`timeout_ms`) to every call. Use `Client.call_into(op, Model, params)` to decode
+any operation into a model.
+
+## Test
+
+```bash
+ILINK_SDK_LIB=../../target/release/ilink_sdk.dll python -m pytest
+# or, with no pytest:
+ILINK_SDK_LIB=../../target/release/ilink_sdk.dll python tests/test_smoke.py
+```

ilink_sdk-2.4.10.dist-info/RECORD

@@ -0,0 +1,10 @@
+ilink_sdk-2.4.10.data/purelib/ilink_sdk/__init__.py,sha256=LCEa6zJ-j_BvK6FsMf7CGh2xbRAeM-Gl0bNOMP7UOZQ,1397
+ilink_sdk-2.4.10.data/purelib/ilink_sdk/_call.py,sha256=WNJRAMUT4Lol5Ml72XOfN4n1en5ncPFGqmIUiTrjJe8,1940
+ilink_sdk-2.4.10.data/purelib/ilink_sdk/_ffi.py,sha256=CQGmlp7yeEh8mxnqPk3eCL39Hm9wgPSHqhIobYu1Z8U,2597
+ilink_sdk-2.4.10.data/purelib/ilink_sdk/client.py,sha256=evVfpm9eym4hGBKDaiyGW9nx4gAdUSiHjP-TGI1QckY,17249
+ilink_sdk-2.4.10.data/purelib/ilink_sdk/ilink_sdk.dll,sha256=iynyPy5waGY13v6GRIN9rOxwmEdIHPw-4tZdgeviImw,5021696
+ilink_sdk-2.4.10.data/purelib/ilink_sdk/models.py,sha256=DuGSs9WcdAqEQp68pLw5p7OiivBFqkU9alpdMrHPhmQ,12758
+ilink_sdk-2.4.10.dist-info/METADATA,sha256=ZyzvXaY_n8vTeBLjFynoPe8-nTvKKP2NUUiBHs4W_RY,6428
+ilink_sdk-2.4.10.dist-info/WHEEL,sha256=Zx98gwb_dQKckJK3HEOVKnxxD52EfU_PXDG_usMJ2ng,98
+ilink_sdk-2.4.10.dist-info/top_level.txt,sha256=PW33uuWdgGTQw1pG2lPvCY1KXw5nisOTHJKl6vMO5fE,10
+ilink_sdk-2.4.10.dist-info/RECORD,,

ilink_sdk-2.4.10.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64
+

ilink_sdk-2.4.10.dist-info/top_level.txt

@@ -0,0 +1 @@
+ilink_sdk