wechat-cli 0.1.0__py3-none-any.whl

wechat_cli/assets/profiles/4.1.15-270135.json

@@ -0,0 +1,194 @@
+{
+  "version": "4.1.15",
+  "build": "270135",
+  "arch": "arm64",
+  "payloadSha256": "5f5a81c4d8b000dec1c7203738fc4dba75ce752b55874fc1b6b5869f9dfb1027",
+  "taskContextTlsOffset": "0xa24de80",
+  "sessionServiceMarkerOffset": "0x9da18d0",
+  "voiceFrontDescriptorOffset": "0x9c03d80",
+  "enumeration": {
+    "offset": "0x2be0d64",
+    "signature": "fa67bba9f85f01a9f65702a9f44f03a9fd7b04a9fd030191ff0308d1f30308aa",
+    "scanPattern": "fa 67 bb a9 f8 5f 01 a9 f6 57 02 a9 f4 4f 03 a9 fd 7b 04 a9 fd 03 01 91 ff 03 08 d1 f3 03 08 aa f5 c3 02 91 a8 7a 03 d0 08 4d 46 f9 08 01 40 f9 a8 83 1b f8 fb 7b 15 95 f4 03 00 aa 00 e4 00 6f 60 02 00 ad 08 f0 a7 d2 48 55 d5 f2 48 55 f5 f2 68 12 00 f9 40 e5 05 4f a0 02 00 ad a8 aa ca 92 48 55 f5 f2 e8 6b 00 f9 6a 22 6a 94 08 00 40 f9 09 35 40 f9 e8 63 03 91 20 01 3f d6 e0 6f 40 f9 : ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff 1f 00 00 9f ff ff ff ff ff ff ff ff ff ff ff ff 00 00 00 fc ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff 00 00 00 fc ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff"
+  },
+  "initialMessages": {
+    "offset": "0x31c0484",
+    "signature": "fc6fbaa9fa6701a9f85f02a9f65703a9f44f04a9fd7b05a9fd430191ff830cd1"
+  },
+  "pagedMessages": {
+    "offset": "0x31c15e4",
+    "signature": "fc6fbaa9fa6701a9f85f02a9f65703a9f44f04a9fd7b05a9fd430191ff430cd1"
+  },
+  "mapNodeDestructor": {
+    "offset": "0x2be59e0",
+    "signature": "c10400b4f44fbea9fd7b01a9fd430091f30301aa06000014e00313aa010b8052"
+  },
+  "serviceRegistry": {
+    "offset": "0x44e6b1c",
+    "signature": "ffc302d1fa6706a9f85f07a9f65708a9f44f09a9fd7b0aa9fd830291f40301aa"
+  },
+  "cachedMessageService": {
+    "offset": "0x454182c",
+    "signature": "ff8301d1f85f02a9f65703a9f44f04a9fd7b05a9fd430191f40300aaf30308aa"
+  },
+  "createMessageServiceTask": {
+    "offset": "0x666ab58",
+    "signature": "ff4301d1f44f03a9fd7b04a9fd030191f40300aaf30308aae8f301b2e8a301a9"
+  },
+  "messageUiConversion": {
+    "offset": "0x31f808c",
+    "signature": "fc6fbaa9fa6701a9f85f02a9f65703a9f44f04a9fd7b05a9fd430191ff8315d1"
+  },
+  "messageUiDestructor": {
+    "offset": "0x396780",
+    "signature": "f44fbea9fd7b01a9fd430091f30300aa009841f9c00000b4140040f901038052"
+  },
+  "sendInfoConstructor": {
+    "offset": "0x69a714",
+    "signature": "f44fbea9fd7b01a9fd430091f40301aaf30300aae003679e0004186e0080803c"
+  },
+  "sendResultDestructor": {
+    "offset": "0x3189a68",
+    "signature": "f657bda9f44f01a9fd7b02a9fd830091f30300aa141040f9d40300b4751640f9"
+  },
+  "sendFailureCtor": {
+    "offset": "0x30f6640",
+    "signature": "1f0000391f00013901080929c0035fd6ff8302d1fa6705a9f85f06a9f65707a9"
+  },
+  "sessionService": {
+    "offset": "0x44e6b1c",
+    "signature": "ffc302d1fa6706a9f85f07a9f65708a9f44f09a9fd7b0aa9fd830291f40301aa"
+  },
+  "sessionDestructor": {
+    "offset": "0x1ef570",
+    "signature": "f657bda9f44f01a9fd7b02a9fd830091f30300aa085cc839c802f83768dec739"
+  },
+  "isMinimizedSession": {
+    "offset": "0x4d64628",
+    "signature": "f44fbea9fd7b01a9fd430091f30300aacf3cf99780000034683e41b908010412"
+  },
+  "makeUiSendInfo": {
+    "offset": "0x6f3990",
+    "signature": "f44fbea9fd7b01a9fd430091f30308aa008a8052a331a995e003679e0004186e"
+  },
+  "voiceAudioPath": {
+    "offset": "0x35c18f8",
+    "signature": "ff4303d1f6570aa9f44f0ba9fd7b0ca9fd030391f50302aaf40300aaf30308aa"
+  },
+  "voiceDataGetter": {
+    "offset": "0x31c4144",
+    "signature": "ff8302d1f65707a9f44f08a9fd7b09a9fd430291f30302aaf60301aaf40300aa"
+  },
+  "voiceTranscriptionStart": {
+    "offset": "0x412eb70",
+    "signature": "09fc40f9200540f99b200214fc6fbda9f44f01a9fd7b02a9fd830091ff030fd1"
+  },
+  "ocrLocalRecognition": {
+    "offset": "0x36ef0c4",
+    "signature": "ff0304d1fa670ba9f85f0ca9f6570da9f44f0ea9fd7b0fa9fdc30391f60302aa"
+  },
+  "makeVoiceSendInfo": {
+    "offset": "0x448a844",
+    "signature": "fa67bba9f85f01a9f65702a9f44f03a9fd7b04a9fd030191f50304aaf60303aa"
+  },
+  "dictationStart": {
+    "offset": "0x1d07c20",
+    "signature": "ff4306d1fc6f14a9f85f15a9f65716a9f44f17a9fd7b18a9fd030691f7c30291"
+  },
+  "migrationStopServices": {
+    "offset": "0x42a5ed0",
+    "signature": "ffc301d1f44f05a9fd7b06a9fd830191250e0f94080040f9093540f9e8230091"
+  },
+  "migrationCancelTransfer": {
+    "offset": "0x42a5ed0",
+    "signature": "ffc301d1f44f05a9fd7b06a9fd830191250e0f94080040f9093540f9e8230091"
+  },
+  "isPinnedSession": {
+    "offset": "0x4d6461c",
+    "signature": "08f44439000d0353c0035fd6f44fbea9fd7b01a9fd430091f30300aacf3cf997"
+  },
+  "messageFormatter": {
+    "offset": "0x4cbe4cc",
+    "signature": "ffc301d1f44f05a9fd7b06a9fd830191f40300aaf30308aae8630091d6ffff97"
+  },
+  "accountFactory": {
+    "offset": "0x466aca8",
+    "signature": "ffc300d1f44f01a9fd7b02a9fd830091f30308aa88ef02f0009d47f9080040f9"
+  },
+  "messageService": {
+    "offset": "0x268f370",
+    "signature": "ffc301d1f44f05a9fd7b06a9fd830191f40300aaf30308aa88b803f008010091"
+  },
+  "messageServiceResult": {
+    "offset": "0x21b3684",
+    "signature": "f44fbea9fd7b01a9fd430091000040f96cdc1295200300b4f30300aa000040f9"
+  },
+  "messageTaskResult": {
+    "offset": "0x3206474",
+    "signature": "f44fbea9fd7b01a9fd430091000040f9f090d194200300b4f30300aa000040f9"
+  },
+  "taskContextGuard": {
+    "offset": "0x6676adc",
+    "signature": "f44fbea9fd7b01a9fd430091f30300aaa0de01f000003a91080040f900013fd6"
+  },
+  "contactDisplayName": {
+    "offset": "0x2ac697c",
+    "signature": "ff0307d1f65719a9f44f1aa9fd7b1ba9fdc30691f50302aaf40301aaf30308aa"
+  },
+  "makeNativeUuid": {
+    "offset": "0x33e1c",
+    "signature": "ff0302d1f44f06a9fd7b07a9fdc30191f30308aa08d804f0084d46f9080140f9"
+  },
+  "sendInfoClone": {
+    "offset": "0x4d10630",
+    "signature": "f657bda9f44f01a9fd7b02a9fd830091f50301aaf40308aa00bc805279be9094"
+  },
+  "sendInfoDestructor": {
+    "offset": "0x69b42c",
+    "signature": "f44fbea9fd7b01a9fd430091f30300aaa8c004f00801199108410091080000f9"
+  },
+  "sendGroupMessages": {
+    "offset": "0x3183c08",
+    "signature": "e923b96dfc6f01a9fa6702a9f85f03a9f65704a9f44f05a9fd7b06a9fd830191"
+  },
+  "sendStageCtor": {
+    "offset": "0x304f1cc",
+    "signature": "f657bda9f44f01a9fd7b02a9fd830091f30300aa0108002900e4006f0080803c"
+  },
+  "sendContextConstructor": {
+    "offset": "0x30ef9e0",
+    "signature": "ff8301d1fa6701a9f85f02a9f65703a9f44f04a9fd7b05a9fd430191f90302aa"
+  },
+  "copySessions": {
+    "offset": "0x27f5434",
+    "signature": "f657bda9f44f01a9fd7b02a9fd830091f40301aaf30300aa00e4006f000000ad"
+  },
+  "sendProcessor": {
+    "offset": "0x319a6a8",
+    "signature": "f85fbca9f65701a9f44f02a9fd7b03a9fdc30091ff0309d1f40302aaf50301aa"
+  },
+  "voiceFrontRegistry": {
+    "offset": "0x456f244",
+    "signature": "ffc307d1fa671aa9f85f1ba9f6571ca9f44f1da9fd7b1ea9fd830791f30301aa"
+  },
+  "ocrService": {
+    "offset": "0x21e9898",
+    "signature": "ffc301d1f44f05a9fd7b06a9fd830191f40300aaf30308aae8dc039008210191"
+  },
+  "ocrInitialize": {
+    "offset": "0x36ec308",
+    "signature": "ffc306d1f65718a9f44f19a9fd7b1aa9fd830691f30300aab4a302d1482203d0"
+  },
+  "accountServices": {
+    "offset": "0x17e9ca4",
+    "signature": "0aa442a90a2500a9890000b428210091"
+  },
+  "contactService": {
+    "offset": "0x230000c",
+    "signature": "ffc301d1f44f05a9fd7b06a9fd830191"
+  },
+  "voiceTranscriptionAttach": {
+    "offset": "0x21d834",
+    "signature": "ff0303d1f85f08a9f65709a9f44f0aa9fd7b0ba9fdc30291f30304aaf40303aa"
+  }
+}

wechat_cli/assets/startup-notice.js

@@ -0,0 +1,78 @@
+// Suppress only WeChat's installation-location notice. Installed before Gadget resumes main().
+// Returning the normal OK response lets WeChat persist its own suppression preference.
+(() => {
+  const policy = globalThis.WECHAT_INSTALL_NOTICE = {installed: false, suppressed: 0};
+  const keep = [];
+  policy.callbacks = keep;
+  try {
+    const exported = name => Module.getGlobalExportByName(name);
+    const getClass = new NativeFunction(exported('objc_getClass'), 'pointer', ['pointer']);
+    const getSelector = new NativeFunction(exported('sel_registerName'), 'pointer', ['pointer']);
+    const instanceMethod = new NativeFunction(exported('class_getInstanceMethod'), 'pointer', ['pointer', 'pointer']);
+    const implementation = new NativeFunction(exported('method_getImplementation'), 'pointer', ['pointer']);
+    const msg = new NativeFunction(exported('objc_msgSend'), 'pointer', ['pointer', 'pointer']);
+    const setState = new NativeFunction(exported('objc_msgSend'), 'void', ['pointer', 'pointer', 'long']);
+    const selector = name => getSelector(Memory.allocUtf8String(name));
+    const selectors = Object.fromEntries(['messageText', 'informativeText', 'UTF8String', 'suppressionButton'].map(name => [name, selector(name)]));
+    const stateSelector = selector('setState:');
+    const alertClass = getClass(Memory.allocUtf8String('NSAlert'));
+    if (alertClass.isNull()) return;
+    function text(object, field) {
+      const string = msg(object, selectors[field]);
+      if (string.isNull()) return '';
+      const bytes = msg(string, selectors.UTF8String);
+      return bytes.isNull() ? '' : bytes.readUtf8String();
+    }
+    function matches(alert) {
+      try {
+        const title = text(alert, 'messageText').replace(/Weixin/g, 'WeChat').trim();
+        const body = text(alert, 'informativeText').replace(/Weixin/g, 'WeChat').trim();
+        const english = title === 'WeChat was opened from the installation package'
+          && body === 'We recommend you move WeChat to the Applications folder before using it.';
+        const chinese = ['微信从安装包中打开', '微信是从安装包中打开的', '微信从安装包打开'].includes(title)
+          && /建议.*微信.*应用程序/.test(body);
+        if (!english && !chinese) return false;
+        const checkbox = msg(alert, selectors.suppressionButton);
+        if (!checkbox.isNull()) setState(checkbox, stateSelector, 1);
+        policy.suppressed++;
+        return true;
+      } catch (_) { return false; }
+    }
+    function method(name) {
+      const value = instanceMethod(alertClass, selector(name));
+      return value.isNull() ? null : implementation(value);
+    }
+    const modal = method('runModal');
+    if (modal) {
+      const original = new NativeFunction(modal, 'long', ['pointer', 'pointer']);
+      const replacement = new NativeCallback((self, cmd) => matches(self) ? 1000 : original(self, cmd),
+        'long', ['pointer', 'pointer']);
+      Interceptor.replace(modal, replacement); keep.push(replacement, original);
+    }
+    const sheet = method('beginSheetModalForWindow:completionHandler:');
+    if (sheet) {
+      const original = new NativeFunction(sheet, 'void', ['pointer', 'pointer', 'pointer', 'pointer']);
+      const copyBlock = new NativeFunction(exported('_Block_copy'), 'pointer', ['pointer']);
+      const releaseBlock = new NativeFunction(exported('_Block_release'), 'void', ['pointer']);
+      const queueGetter = Module.findGlobalExportByName('dispatch_get_main_queue');
+      const mainQueue = queueGetter ? new NativeFunction(queueGetter, 'pointer', []) : () => exported('_dispatch_main_q');
+      const dispatch = new NativeFunction(exported('dispatch_async_f'), 'void', ['pointer', 'pointer', 'pointer']);
+      const complete = new NativeCallback(block => {
+        try {
+          const callback = new NativeFunction(block.add(16).readPointer(), 'void', ['pointer', 'long']);
+          callback(block, 1000);
+        } finally { releaseBlock(block); }
+      }, 'void', ['pointer']);
+      const replacement = new NativeCallback((self, cmd, window, block) => {
+        if (!matches(self)) return original(self, cmd, window, block);
+        if (!block.isNull()) dispatch(mainQueue(), copyBlock(block), complete);
+      }, 'void', ['pointer', 'pointer', 'pointer', 'pointer']);
+      Interceptor.replace(sheet, replacement); keep.push(complete, replacement, original);
+    }
+    policy.installed = Boolean(modal || sheet);
+    // Keep callbacks alive for the lifetime of this script.
+    policy.callbacks = keep;
+  } catch (_) {
+    // If AppKit differs, preserve normal app behavior instead of dismissing an unknown alert.
+  }
+})();

wechat_cli/assets/style.css

@@ -0,0 +1 @@
+:root{font:15px system-ui,-apple-system,sans-serif;color:#192d28;background:#f6f8f7}*{box-sizing:border-box}body{margin:0}header{background:#163f34;color:white;padding:18px 26px;display:flex;align-items:center;gap:12px}header div{flex:1}header strong{font-size:22px}header span{display:block;opacity:.7;font-size:12px;margin-top:4px}button,input,textarea,select{font:inherit}button{background:white;border:1px solid #c7d7d0;border-radius:6px;padding:8px 12px;cursor:pointer;color:#163f34}button:hover{background:#edf5f0}button:disabled{opacity:.5;cursor:default}button:focus-visible,input:focus,textarea:focus{outline:2px solid #298667;outline-offset:2px}#status{padding:12px 26px;margin:0;min-height:46px;white-space:pre-wrap;border-bottom:1px solid #dce4df;font-size:13px}main{display:grid;grid-template-columns:300px 1fr;min-height:70vh}aside{padding:18px;border-right:1px solid #dce4df}label{display:block;font-size:13px;font-weight:600;margin-bottom:8px}input[type=search],textarea{width:100%;padding:10px;border:1px solid #c7d7d0;border-radius:6px;background:white}nav{display:flex;flex-direction:column;gap:6px;margin-top:14px;max-height:75vh;overflow:auto}nav button{text-align:left;padding:12px}nav button[aria-current=true]{background:#dceee4;border-color:#298667}nav small{display:block;color:#65776d;margin-top:5px;overflow-wrap:anywhere}.conversation-title{display:flex;align-items:center;gap:12px;padding:0 0 18px}h1{flex:1;font-size:20px;margin:0}.conversation-title label{margin:0}section{padding:22px;min-width:0}#messages{display:flex;flex-direction:column;gap:12px;max-height:60vh;overflow:auto}article{background:white;border:1px solid #dce4df;border-radius:8px;padding:14px;overflow-wrap:anywhere}article small{color:#65776d}article p{white-space:pre-wrap;line-height:1.6}article button{margin:4px 6px 0 0}article img,article video{max-width:100%;max-height:400px;display:block;margin-top:12px}article audio{display:block;margin-top:12px}form{border-top:1px solid #dce4df;padding-top:16px;margin-top:20px}#compose button{display:block;margin:10px 0 0 auto;background:#1b6d50;color:white}#upload{display:flex;flex-wrap:wrap;gap:8px;align-items:center}#upload label{width:100%}footer{padding:16px 26px;color:#65776d;font-size:12px}@media(max-width:750px){main{grid-template-columns:1fr}aside{border-right:0;border-bottom:1px solid #dce4df}nav{max-height:220px}.conversation-title{flex-wrap:wrap}header{padding:14px}section{padding:16px}}

wechat_cli/cli.py

@@ -0,0 +1,238 @@
+"""uvx wechat-cli: lifecycle commands and API subcommands with JSON output."""
+
+import argparse
+import base64
+import json
+import sys
+import time
+import uuid
+import webbrowser
+from pathlib import Path
+from urllib.parse import urlencode
+
+from . import __version__
+from .client import ApiClient
+from .config import data_directory
+from .errors import AppError
+from .lifecycle import configured_port, ensure_server, health, serve
+from .setup import WECHAT_URL, doctor, setup
+
+
+def port_number(value):
+    try:
+        port = int(value)
+        if not 1 <= port <= 65535:
+            raise ValueError()
+        return port
+    except ValueError:
+        raise argparse.ArgumentTypeError("port must be between 1 and 65535") from None
+
+
+def parser():
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "--data-dir", default=argparse.SUPPRESS, help="Persistent app, token and service directory"
+    )
+    common.add_argument(
+        "--port", type=port_number, default=argparse.SUPPRESS, help="Local API port (default: 8787)"
+    )
+    root = argparse.ArgumentParser(
+        prog="wechat-cli",
+        parents=[common],
+        description="Python CLI, local API and web interface for macOS WeChat",
+    )
+    root.add_argument("--version", action="version", version=__version__)
+    commands = root.add_subparsers(dest="command")
+
+    def add(name, description):
+        return commands.add_parser(name, help=description, description=description, parents=[common])
+
+    init = add("setup", "Download and patch a separate compatible WeChat copy, or register an existing one")
+    sources = init.add_mutually_exclusive_group()
+    sources.add_argument("--app", help="Register an already patched app")
+    sources.add_argument("--source", help="Copy and patch a local stock WeChat.app")
+    init.add_argument("--destination", help="New patched app location (must not already exist)")
+    init.add_argument("--gadget", help="Use a local Frida Gadget dylib instead of downloading it")
+    init.add_argument(
+        "--wechat-url", default=WECHAT_URL, help="HTTPS installer URL (payload must be supported)"
+    )
+    add("doctor", "Check app, payload, Gadget and Frida installation")
+    start = add("start", "Start the patched WeChat and persistent local API")
+    start.add_argument("--foreground", action="store_true", help="Keep the service in this terminal")
+    add("serve", "Run WeChat and the API in the foreground")
+    add("stop", "Stop the local API; keep WeChat signed in and running")
+    web = add("web", "Start the service and open its web interface")
+    web.add_argument("--no-open", action="store_true", help="Print the URL without opening a browser")
+    add("status", "Read native WeChat connection status")
+    add("chats", "List native conversations")
+    messages = add("messages", "Read recent messages, newest first")
+    messages.add_argument("chat_id")
+    messages.add_argument("--limit", type=int, choices=range(1, 101), default=50, metavar="1..100")
+    send = add("send", "Send a text message")
+    send.add_argument("chat_id")
+    send.add_argument("text")
+    send.add_argument(
+        "--dry-run", action="store_true", help="Validate native text preparation without sending"
+    )
+    send.add_argument("--key", help="Reuse this idempotency key for retries (retained for 24 hours)")
+    for name in ["send-file", "send-voice"]:
+        command = add(
+            name, "Send a local file" if name == "send-file" else "Send SILK, mono PCM WAV or raw PCM audio"
+        )
+        command.add_argument("chat_id")
+        command.add_argument("file", type=Path)
+        command.add_argument("--key")
+        if name == "send-voice":
+            command.add_argument("--format", choices=["silk", "wav", "pcm_s16le"], default="wav")
+            command.add_argument("--sample-rate", type=int)
+    for name, description in [
+        ("media", "Download media for a recent message"),
+        ("ocr", "Extract text from an image"),
+        ("transcribe", "Start WeChat voice-to-text"),
+        ("transcript", "Read voice-to-text status"),
+        ("download", "Ask the active WeChat chat to download an attachment"),
+    ]:
+        command = add(name, description)
+        command.add_argument("chat_id")
+        command.add_argument("message_id", help="Exact string ID from messages")
+        if name == "media":
+            command.add_argument("--output", required=True, type=Path)
+            command.add_argument("--variant", choices=["full", "preview"], default="full")
+        if name in {"transcribe", "download"}:
+            command.add_argument("--key")
+    request = add("api", "Call any local /api/ route")
+    request.add_argument("path")
+    request.add_argument("--method", choices=["GET", "POST", "DELETE", "PUT", "PATCH"], default="GET")
+    request.add_argument("--json", dest="body", help="JSON object body")
+    request.add_argument("--key")
+    request.add_argument("--output", type=Path, help="Save the response as binary")
+    return root
+
+
+def upload(path):
+    if path.stat().st_size > 8 * 1024**2:
+        raise AppError("file_too_large", "CLI uploads must be at most 8 MiB", 413)
+    return base64.b64encode(path.read_bytes()).decode()
+
+
+def run(args):
+    directory = data_directory(getattr(args, "data_dir", None))
+    command = args.command or "start"
+    port = configured_port(directory, getattr(args, "port", None))
+    if command == "setup":
+        if args.app and (args.destination or args.gadget):
+            raise AppError("invalid_options", "--destination and --gadget apply to preparing a new copy")
+        return setup(
+            directory,
+            app=args.app,
+            source=args.source,
+            destination=args.destination,
+            gadget=args.gadget,
+            wechat_url=args.wechat_url,
+        )
+    if command == "doctor":
+        return doctor(directory)
+    if command == "serve" or command == "start" and getattr(args, "foreground", False):
+        return serve(directory, port)
+    if command == "stop":
+        result = ApiClient(directory, port).request("/api/server/stop", method="POST", data={})
+        for _ in range(100):
+            try:
+                health(directory, port)
+            except AppError:
+                return result
+            time.sleep(0.05)
+        raise AppError("server_stop_timeout", "Service shutdown is still in progress", 504)
+    ensure_server(directory, port)
+    if command in {"start", "web"}:
+        url = f"http://127.0.0.1:{port}/"
+        if command == "web" and not args.no_open:
+            webbrowser.open(url)
+        return {"running": True, "url": url, "tokenFile": str(directory / "api-token")}
+    client = ApiClient(directory, port)
+    if command == "status":
+        return client.request("/api/native/status")
+    if command == "chats":
+        return client.chats()
+    if command == "messages":
+        return client.messages(args.chat_id, args.limit)
+    key = getattr(args, "key", None)
+    mutation = (
+        command in {"send", "send-file", "send-voice", "transcribe", "download"}
+        or command == "api"
+        and args.method == "POST"
+    )
+    mutation = mutation and not (command == "send" and args.dry_run)
+    if mutation:
+        key = key or str(uuid.uuid4())
+        print(f"Idempotency-Key: {key} (reuse --key for retries)", file=sys.stderr)
+    if command == "send" and args.dry_run:
+        return client.request(
+            "/api/messages/prepare", method="POST", data={"chatId": args.chat_id, "text": args.text}
+        )
+    if command == "send":
+        return client.send(args.chat_id, args.text, idempotency_key=key)
+    if command in {"send-file", "send-voice"}:
+        input = {"chatId": args.chat_id, "dataBase64": upload(args.file)}
+        if command == "send-file":
+            input["name"] = args.file.name
+        else:
+            input["format"] = args.format
+            if args.sample_rate is not None:
+                input["sampleRate"] = args.sample_rate
+        return client.request(
+            "/api/messages/file" if command == "send-file" else "/api/messages/voice",
+            method="POST",
+            data=input,
+            key=key,
+        )
+    if command in {"media", "ocr", "transcribe", "transcript", "download"}:
+        input = {"chatId": args.chat_id, "id": args.message_id}
+        paths = {
+            "media": "/api/native/media",
+            "ocr": "/api/native/images/text",
+            "transcribe": "/api/native/voice/transcribe",
+            "transcript": "/api/native/voice/transcript",
+            "download": "/api/native/attachments/download",
+        }
+        if command in {"media", "transcript"}:
+            if command == "media":
+                input["variant"] = args.variant
+            result = client.request(paths[command] + "?" + urlencode(input), binary=command == "media")
+            if command == "media":
+                with args.output.open("xb") as output:
+                    output.write(result)
+                return {"saved": str(args.output.resolve()), "bytes": len(result)}
+            return result
+        return client.request(paths[command], method="POST", data=input, key=key)
+    if command == "api":
+        try:
+            input = json.loads(args.body) if args.body is not None else {} if args.method == "POST" else None
+            if input is not None and not isinstance(input, dict):
+                raise ValueError()
+        except ValueError:
+            raise AppError("invalid_json", "--json must be a JSON object") from None
+        result = client.request(args.path, method=args.method, data=input, key=key, binary=bool(args.output))
+        if args.output:
+            with args.output.open("xb") as output:
+                output.write(result)
+            return {"saved": str(args.output.resolve()), "bytes": len(result)}
+        return result
+    raise AppError("unknown_command", command)
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    try:
+        result = run(args)
+        if result is not None:
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    except AppError as error:
+        print(json.dumps(error.as_dict(), ensure_ascii=False), file=sys.stderr)
+        return 1
+    except OSError as error:
+        print(json.dumps({"error": "filesystem_error", "message": str(error)}), file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130

wechat_cli/client.py

@@ -0,0 +1,59 @@
+"""Small synchronous HTTP client used by the CLI and available to Python callers."""
+
+import http.client
+import json
+import urllib.error
+import urllib.request
+from urllib.parse import urlencode
+
+from .config import api_token
+from .errors import AppError
+from .media import NoRedirect
+
+
+class ApiClient:
+    def __init__(self, directory, port=8787, timeout=100):
+        self.base = f"http://127.0.0.1:{port}"
+        self.token = api_token(directory)
+        self.timeout = timeout
+        self.opener = urllib.request.build_opener(urllib.request.ProxyHandler({}), NoRedirect())
+
+    def request(self, path, *, method="GET", data=None, key=None, binary=False):
+        if not path.startswith("/api/") or "#" in path or "\r" in path or "\n" in path:
+            raise AppError("invalid_api_path", "Use a local /api/ path")
+        headers = {"Authorization": "Bearer " + self.token}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        if key:
+            headers["Idempotency-Key"] = key
+        request = urllib.request.Request(
+            self.base + path,
+            data=None if data is None else json.dumps(data).encode(),
+            headers=headers,
+            method=method,
+        )
+        try:
+            with self.opener.open(request, timeout=self.timeout) as response:
+                raw = response.read(128 * 1024**2 + 1)
+                if len(raw) > 128 * 1024**2:
+                    raise AppError("response_too_large", "API response exceeds 128 MiB", 413)
+                return raw if binary else json.loads(raw)
+        except urllib.error.HTTPError as error:
+            try:
+                value = json.loads(error.read(65536))
+                raise AppError(value["error"], value.get("message", value["error"]), error.code) from None
+            except (ValueError, KeyError):
+                raise AppError("api_http_error", f"API returned HTTP {error.code}", error.code) from None
+        except (urllib.error.URLError, TimeoutError, ConnectionError, http.client.HTTPException):
+            raise AppError("api_unavailable", "Local API is unavailable; run wechat-cli start", 503) from None
+
+    def chats(self):
+        return self.request("/api/native/chats")
+
+    def messages(self, chat_id, limit=50):
+        return self.request("/api/native/messages?" + urlencode({"chatId": chat_id, "limit": limit}))
+
+    def send(self, chat_id, text, *, idempotency_key):
+        return self.request(
+            "/api/messages/send", method="POST", data={"chatId": chat_id, "text": text}, key=idempotency_key
+        )

wechat_cli/codec.py

@@ -0,0 +1,14 @@
+"""Isolated optional SILK codec process (bounded by the parent process timeout)."""
+
+import sys
+
+import pilk
+
+if __name__ == "__main__":
+    action, source, destination, rate = sys.argv[1:]
+    if action == "decode":
+        pilk.decode(source, destination, pcm_rate=int(rate))
+    elif action == "encode":
+        pilk.encode(source, destination, pcm_rate=int(rate), tencent=True)
+    else:
+        raise SystemExit(2)