Python middleware.py signatures

This page organizes the current public plugin/scripts/middleware.py SDK as .pyi-style signatures for IDE, MCP, and AI retrieval. Runtime behavior is still defined by middleware.py.
from typing import Any, Literal

JsonLike = Any
SendReceipt = dict[str, Any]
MediaItem = dict[str, Any]
FileDownloadResult = dict[str, Any]
WaitResult = str | dict[str, Any]
WaitPayResult = Literal["timeout", "busy"] | str | dict[str, Any]

# context
def getSenderID() -> str: ...
def printf(message: Any) -> None: ...

# files and media
def fileDownload(url: str, path: str | None = None) -> FileDownloadResult: ...
def downloadAdapterFile(file: MediaItem | dict[str, Any] | str, options: dict[str, Any] | int | float | None = None, timeout: int | float | None = None) -> FileDownloadResult: ...
def download_adapter_file(file: MediaItem | dict[str, Any] | str, options: dict[str, Any] | int | float | None = None, timeout: int | float | None = None) -> FileDownloadResult: ...
def getGroupMemberList(group_id_or_options: str | dict[str, Any] | None = None, options: dict[str, Any] | int | float | None = None, timeout: int | float | None = None) -> dict[str, Any]: ...
def get_group_member_list(group_id_or_options: str | dict[str, Any] | None = None, options: dict[str, Any] | int | float | None = None, timeout: int | float | None = None) -> dict[str, Any]: ...

# proactive push
def push(imType: str, groupCode: str, userID: str, title: str, content: str, options: dict[str, Any] | None = None, timeout: int | float | None = None) -> int: ...
def pushImage(imType: str, groupCode: str, userID: str, title: str, imageUrl: str, options: dict[str, Any] | None = None, timeout: int | float | None = None) -> int: ...
def pushVideo(imType: str, groupCode: str, userID: str, title: str, videoUrl: str, options: dict[str, Any] | None = None, timeout: int | float | None = None) -> int: ...
def pushVoice(imType: str, groupCode: str, userID: str, title: str, voiceUrl: str, options: dict[str, Any] | None = None, timeout: int | float | None = None) -> int: ...
def pushFile(imType: str, groupCode: str, userID: str, title: str, fileUrl: str, options: dict[str, Any] | None = None, timeout: int | float | None = None) -> int: ...
def pushMixed(imType: str, groupCode: str, userID: str, title: str, items: list[MediaItem], options: dict[str, Any] | None = None, timeout: int | float | None = None) -> int: ...

# system helpers
def render(template: str, selector: str, jsondata: JsonLike) -> Any: ...
def getActiveImtypes() -> list[str]: ...
def name() -> str: ...
def domain() -> str: ...
def port() -> str | int: ...
def getPort() -> str | int: ...
def machineId() -> str: ...
def version() -> str: ...
def versionInfo() -> dict[str, Any]: ...
def import_module(module: str, package: str = "", version: str = "", manager: str = "") -> Any: ...
def importModule(module: str, package: str = "", version: str = "", manager: str = "") -> Any: ...
def notifyMasters(content: str, imtypes: list[str] = []) -> int: ...
def coffee() -> bool: ...
def spread(msg: str) -> Any: ...
def getHistoryMessages(imtype: str = "") -> list[Any]: ...
def generateFromSinglePrompt(prompt: str) -> str: ...

# storage
def get(key: str) -> str: ...
def set(key: str, value: Any) -> bool: ...
def delete(key: str) -> bool: ...
def del_(key: str) -> bool: ...
def bucketGet(bucket: str, key: str) -> str: ...
def bucketSet(bucket: str, key: str, value: Any) -> bool: ...
def bucketDel(bucket: str, key: str) -> bool: ...
def bucketKeys(bucket: str | None = None, value: Any | None = None) -> list[str]: ...
def bucketAllKeys(bucket: str) -> list[str]: ...
def bucketAll(bucket: str) -> dict[str, str]: ...

# top-level router aliases
def getRouter() -> str: ...
def getMethod() -> str: ...
def getRouterData() -> str: ...

class Sender:
    def __init__(self, senderID: str | int) -> None: ...

    # storage
    def bucketGet(self, bucket: str, key: str) -> str: ...
    def bucketSet(self, bucket: str, key: str, value: Any) -> bool: ...
    def bucketDel(self, bucket: str, key: str) -> bool: ...
    def bucketKeys(self, bucket: str | None = None, value: Any | None = None) -> list[str]: ...
    def bucketAllKeys(self, bucket: str) -> list[str]: ...
    def bucketAll(self, bucket: str) -> dict[str, str]: ...

    # router
    def setContinue(self) -> bool: ...
    def getRouterPath(self) -> str: ...
    def getRouter(self) -> str: ...
    def getRouterParams(self) -> dict[str, str]: ...
    def getRouterMethod(self) -> str: ...
    def getMethod(self) -> str: ...
    def getRouterHeaders(self) -> dict[str, Any]: ...
    def getRouterCookies(self) -> dict[str, Any]: ...
    def getRouterBody(self) -> JsonLike: ...
    def getRouterData(self) -> str: ...
    def response(self, data: JsonLike) -> Any: ...

    # message context
    def getImtype(self) -> str: ...
    def getUserID(self) -> str: ...
    def getUserName(self) -> str: ...
    def getUserAvatarUrl(self) -> str: ...
    def getChatID(self) -> str: ...
    def getChatName(self) -> str: ...
    def getGroupName(self) -> str: ...
    def isAdmin(self) -> bool: ...
    def isAI(self) -> bool: ...
    def getAIParam(self) -> str: ...
    def getMessage(self) -> str: ...
    def getMessageID(self) -> str: ...
    def getHistoryMessageIDs(self, number: int) -> list[str]: ...
    def param(self, i: int) -> str: ...

    # message actions
    def recallMessage(self, messageid: str) -> SendReceipt: ...
    def breakIn(self, content: str) -> Any: ...
    def reply(self, text: str) -> SendReceipt: ...
    def replyMarkdown(self, markdown: str) -> SendReceipt: ...
    def replyImage(self, imageUrl: str, options: dict[str, Any] | None = None) -> SendReceipt: ...
    def replyVoice(self, voiceUrl: str, options: dict[str, Any] | None = None) -> SendReceipt: ...
    def replyVideo(self, videoUrl: str, options: dict[str, Any] | None = None) -> SendReceipt: ...
    def replyFile(self, fileUrl: str, options: dict[str, Any] | None = None) -> SendReceipt: ...
    def replyMixed(self, items: list[MediaItem], options: dict[str, Any] | None = None) -> SendReceipt: ...
    def returnValue(self, text: str) -> Any: ...

    # wait and payment
    def listen(self, waitTime: int, recallTime: int | Literal["group"] = 0, scope: Literal["group"] | str = "") -> WaitResult: ...
    def input(self, waitTime: int, recallTime: int | Literal["group"] = 0, scope: Literal["group"] | str = "") -> WaitResult: ...
    def waitPay(self, exitcode: str, timeout: int, amount: str | int | float | None = None) -> WaitPayResult: ...
    def atWaitPay(self) -> bool: ...

    # group management
    def groupInviteIn(self, friend: str, group: str) -> Any: ...
    def groupKick(self, userid: str) -> Any: ...
    def groupBan(self, userid: str, timeout: int) -> Any: ...
    def groupUnban(self, userid: str) -> Any: ...
    def groupWholeBan(self) -> Any: ...
    def groupWholeUnban(self) -> Any: ...
    def groupNoticeSend(self, notice: str) -> Any: ...

    # event
    def getPluginName(self) -> str: ...
    def getPluginVersion(self) -> str: ...
    def getEventType(self) -> str: ...
    def setEventType(self, eventType: str) -> bool: ...
    def getEventData(self) -> JsonLike: ...
    def getMediaItems(self) -> list[MediaItem]: ...
    def setEventData(self, eventData: JsonLike) -> bool: ...

class Cron:
    def __init__(self, cronID: int | str | None = None) -> None: ...
    def getCrons(self) -> list[Any]: ...
    def getCronByID(self, id: int | str) -> Any: ...
    def getCron(self, id: int | str) -> Any: ...
    def addCron(self, cron: str, isOnce: bool = False, cmd: str | None = None, isToSelf: bool | None = None, toOthers: Any | None = None, memo: str | None = None, disguiseImtype: str | None = None, disguiseGroup: str | None = None, disguiseUser: str | None = None) -> Any: ...
    def updateCron(self, id: int | str, cron: str | None = None, isOnce: bool | None = None, cmd: str | None = None, isToSelf: bool | None = None, toOthers: Any | None = None, memo: str | None = None, disguiseImtype: str | None = None, disguiseGroup: str | None = None, disguiseUser: str | None = None) -> Any: ...
    def deleteCron(self, id: int | str) -> Any: ...
    def delCron(self, id: int | str) -> Any: ...
del is a Python keyword. Do not write from middleware import del or middleware.del(...). Use delete(...) or del_(...) for default storage deletion.