@unlinearity/cli-wechat-bridge 1.0.0 → 1.0.2

package/dist/wechat/wechat-transport.js

@@ -0,0 +1,887 @@
+import crypto from "node:crypto";
+import { createCipheriv } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { CONTEXT_CACHE_FILE, CREDENTIALS_FILE, ensureChannelDataDir, INBOUND_MESSAGE_CLAIMS_DIR, migrateLegacyChannelFiles, SYNC_BUF_FILE, } from "./channel-config.js";
+export const DEFAULT_LONG_POLL_TIMEOUT_MS = 35_000;
+const CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c";
+const CHANNEL_VERSION = "0.3.0";
+const RECENT_MESSAGE_CACHE_SIZE = 500;
+const BYTES_PER_MB = 1024 * 1024;
+const SEND_TIMEOUT_MS = 15_000;
+const CDN_MAX_RETRIES = 3;
+const ERROR_CAUSE_DEPTH_LIMIT = 4;
+const INBOUND_MESSAGE_CLAIM_TTL_MS = 10 * 60 * 1000;
+const SYNC_SESSION_TIMEOUT_ERRCODE = -14;
+const MSG_TYPE_USER = 1;
+const MSG_TYPE_BOT = 2;
+const MSG_ITEM_TEXT = 1;
+const MSG_ITEM_IMAGE = 2;
+const MSG_ITEM_VOICE = 3;
+const MSG_ITEM_FILE = 4;
+const MSG_ITEM_VIDEO = 5;
+const MSG_STATE_FINISH = 2;
+const UPLOAD_MEDIA_TYPE_IMAGE = 1;
+const UPLOAD_MEDIA_TYPE_VIDEO = 2;
+const UPLOAD_MEDIA_TYPE_FILE = 3;
+const UPLOAD_MEDIA_TYPE_VOICE = 4;
+export function isWechatSyncSessionTimeout(response) {
+    return (response.errcode === SYNC_SESSION_TIMEOUT_ERRCODE &&
+        /session timeout/i.test(response.errmsg ?? ""));
+}
+const DEFAULT_MEDIA_UPLOAD_LIMIT_MB = {
+    image: 20,
+    file: 50,
+    voice: 20,
+    video: 100,
+};
+const MEDIA_UPLOAD_LIMIT_ENV_KEYS = {
+    image: "WECHAT_MAX_IMAGE_MB",
+    file: "WECHAT_MAX_FILE_MB",
+    voice: "WECHAT_MAX_VOICE_MB",
+    video: "WECHAT_MAX_VIDEO_MB",
+};
+const RETRYABLE_HTTP_STATUS_CODES = new Set([408, 425, 429]);
+const RETRYABLE_NETWORK_ERROR_CODES = new Set([
+    "ECONNABORTED",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "EPIPE",
+    "ETIMEDOUT",
+    "ENETUNREACH",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+const RETRYABLE_NETWORK_ERROR_HINTS = [
+    "connection closed",
+    "connection reset",
+    "connection refused",
+    "econnaborted",
+    "econnrefused",
+    "econnreset",
+    "ehostunreach",
+    "enetunreach",
+    "enotfound",
+    "eai_again",
+    "fetch failed",
+    "network error",
+    "request timeout",
+    "socket hang up",
+    "timed out",
+    "timeout",
+];
+function readJsonFile(filePath) {
+    try {
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function describeErrorNode(value) {
+    if (value instanceof Error) {
+        const error = value;
+        const parts = [];
+        if (error.name && error.message) {
+            parts.push(`${error.name}: ${error.message}`);
+        }
+        else if (error.message) {
+            parts.push(error.message);
+        }
+        else if (error.name) {
+            parts.push(error.name);
+        }
+        if (typeof error.code === "string" && error.code.trim()) {
+            parts.push(`code=${error.code}`);
+        }
+        if ((typeof error.errno === "string" && error.errno.trim()) ||
+            typeof error.errno === "number") {
+            parts.push(`errno=${error.errno}`);
+        }
+        if (typeof error.syscall === "string" && error.syscall.trim()) {
+            parts.push(`syscall=${error.syscall}`);
+        }
+        if (typeof error.hostname === "string" && error.hostname.trim()) {
+            parts.push(`host=${error.hostname}`);
+        }
+        if (typeof error.address === "string" && error.address.trim()) {
+            parts.push(`address=${error.address}`);
+        }
+        if ((typeof error.port === "string" && error.port.trim()) ||
+            typeof error.port === "number") {
+            parts.push(`port=${error.port}`);
+        }
+        return parts.filter(Boolean).join(" ");
+    }
+    if (isRecord(value)) {
+        const parts = [];
+        if (typeof value.message === "string" && value.message.trim()) {
+            parts.push(value.message);
+        }
+        if (typeof value.code === "string" && value.code.trim()) {
+            parts.push(`code=${value.code}`);
+        }
+        if ((typeof value.errno === "string" && value.errno.trim()) ||
+            typeof value.errno === "number") {
+            parts.push(`errno=${value.errno}`);
+        }
+        if (typeof value.syscall === "string" && value.syscall.trim()) {
+            parts.push(`syscall=${value.syscall}`);
+        }
+        if (typeof value.hostname === "string" && value.hostname.trim()) {
+            parts.push(`host=${value.hostname}`);
+        }
+        if (typeof value.address === "string" && value.address.trim()) {
+            parts.push(`address=${value.address}`);
+        }
+        if ((typeof value.port === "string" && value.port.trim()) ||
+            typeof value.port === "number") {
+            parts.push(`port=${value.port}`);
+        }
+        if (parts.length > 0) {
+            return parts.join(" ");
+        }
+    }
+    return String(value);
+}
+function getErrorCause(value) {
+    if (value instanceof Error) {
+        return value.cause;
+    }
+    if (isRecord(value) && "cause" in value) {
+        return value.cause;
+    }
+    return undefined;
+}
+function collectErrorCodes(value) {
+    const seen = new Set();
+    const codes = new Set();
+    let current = value;
+    let depth = 0;
+    while (current && depth < ERROR_CAUSE_DEPTH_LIMIT && !seen.has(current)) {
+        seen.add(current);
+        if (isRecord(current) && typeof current.code === "string" && current.code.trim()) {
+            codes.add(current.code.toUpperCase());
+        }
+        current = getErrorCause(current);
+        depth += 1;
+    }
+    return [...codes];
+}
+function extractHttpStatusCode(error) {
+    const match = /^HTTP (\d{3}):/.exec(error.message);
+    if (!match) {
+        return null;
+    }
+    const parsed = Number(match[1]);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+export function describeWechatTransportError(error) {
+    const seen = new Set();
+    const parts = [];
+    let current = error;
+    let depth = 0;
+    while (current && depth < ERROR_CAUSE_DEPTH_LIMIT && !seen.has(current)) {
+        seen.add(current);
+        const description = describeErrorNode(current);
+        if (description) {
+            parts.push(depth === 0 ? description : `cause: ${description}`);
+        }
+        current = getErrorCause(current);
+        depth += 1;
+    }
+    return parts.length > 0 ? parts.join(" | ") : String(error);
+}
+export function classifyWechatTransportError(error) {
+    if (error instanceof Error) {
+        if (/WeChat session timed out/i.test(error.message) ||
+            /errcode=-14\b.*session timeout/i.test(error.message)) {
+            return { kind: "auth", retryable: false };
+        }
+        if (error.name === "AbortError") {
+            return { kind: "timeout", retryable: true };
+        }
+        const statusCode = extractHttpStatusCode(error);
+        if (statusCode !== null) {
+            if (statusCode === 401 || statusCode === 403) {
+                return { kind: "auth", retryable: false, statusCode };
+            }
+            if (statusCode >= 500 || RETRYABLE_HTTP_STATUS_CODES.has(statusCode)) {
+                return { kind: "http", retryable: true, statusCode };
+            }
+            return { kind: "http", retryable: false, statusCode };
+        }
+    }
+    const errorCodes = collectErrorCodes(error);
+    if (errorCodes.some((code) => RETRYABLE_NETWORK_ERROR_CODES.has(code))) {
+        return { kind: "network", retryable: true };
+    }
+    const details = describeWechatTransportError(error).toLowerCase();
+    if (RETRYABLE_NETWORK_ERROR_HINTS.some((hint) => details.includes(hint))) {
+        return { kind: "network", retryable: true };
+    }
+    return { kind: "unknown", retryable: false };
+}
+function writeJsonFile(filePath, value) {
+    ensureChannelDataDir();
+    fs.writeFileSync(filePath, JSON.stringify(value, null, 2), "utf-8");
+}
+function randomWechatUin() {
+    const uint32 = crypto.randomBytes(4).readUInt32BE(0);
+    return Buffer.from(String(uint32), "utf-8").toString("base64");
+}
+function buildHeaders(token, body) {
+    const headers = {
+        "Content-Type": "application/json",
+        AuthorizationType: "ilink_bot_token",
+        "X-WECHAT-UIN": randomWechatUin(),
+    };
+    if (body) {
+        headers["Content-Length"] = String(Buffer.byteLength(body, "utf-8"));
+    }
+    if (token?.trim()) {
+        headers.Authorization = `Bearer ${token.trim()}`;
+    }
+    return headers;
+}
+async function apiFetch(params) {
+    const base = params.baseUrl.endsWith("/") ? params.baseUrl : `${params.baseUrl}/`;
+    const url = new URL(params.endpoint, base).toString();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), params.timeoutMs);
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: buildHeaders(params.token, params.body),
+            body: params.body,
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}: ${text}`);
+        }
+        return text;
+    }
+    catch (err) {
+        clearTimeout(timer);
+        throw err;
+    }
+}
+function encryptAesEcb(plaintext, key) {
+    const cipher = createCipheriv("aes-128-ecb", key, null);
+    return Buffer.concat([cipher.update(plaintext), cipher.final()]);
+}
+function aesEcbPaddedSize(plaintextSize) {
+    return Math.ceil((plaintextSize + 1) / 16) * 16;
+}
+export function formatByteSize(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0) {
+        return "0 B";
+    }
+    if (bytes >= BYTES_PER_MB) {
+        const value = bytes / BYTES_PER_MB;
+        return `${value.toFixed(value >= 100 ? 0 : 1)} MB`;
+    }
+    if (bytes >= 1024) {
+        const value = bytes / 1024;
+        return `${value.toFixed(value >= 100 ? 0 : 1)} KB`;
+    }
+    return `${bytes} B`;
+}
+export function resolveMediaUploadLimitBytes(label, env = process.env) {
+    const envKey = MEDIA_UPLOAD_LIMIT_ENV_KEYS[label];
+    const raw = env[envKey];
+    const fallbackMb = DEFAULT_MEDIA_UPLOAD_LIMIT_MB[label];
+    const parsedMb = raw ? Number(raw) : Number.NaN;
+    const limitMb = Number.isFinite(parsedMb) && parsedMb > 0 ? parsedMb : fallbackMb;
+    return Math.floor(limitMb * BYTES_PER_MB);
+}
+export function assertMediaUploadSizeAllowed(label, rawsize, env = process.env) {
+    const limitBytes = resolveMediaUploadLimitBytes(label, env);
+    if (rawsize <= limitBytes) {
+        return;
+    }
+    const envKey = MEDIA_UPLOAD_LIMIT_ENV_KEYS[label];
+    const labelName = label.charAt(0).toUpperCase() + label.slice(1);
+    throw new Error(`${labelName} too large: ${formatByteSize(rawsize)} exceeds ${formatByteSize(limitBytes)} limit. Set ${envKey} to override.`);
+}
+function encodeMessageAesKey(aeskey) {
+    return Buffer.from(aeskey.toString("hex")).toString("base64");
+}
+async function getUploadUrl(account, params) {
+    const raw = await apiFetch({
+        baseUrl: account.baseUrl,
+        endpoint: "ilink/bot/getuploadurl",
+        body: JSON.stringify({
+            ...params,
+            no_need_thumb: true,
+            base_info: { channel_version: CHANNEL_VERSION },
+        }),
+        token: account.token,
+        timeoutMs: SEND_TIMEOUT_MS,
+    });
+    return JSON.parse(raw);
+}
+function buildCdnUploadUrl(cdnBaseUrl, uploadParam, filekey) {
+    return `${cdnBaseUrl}/upload?encrypted_query_param=${encodeURIComponent(uploadParam)}&filekey=${encodeURIComponent(filekey)}`;
+}
+async function uploadBufferToCdn(params) {
+    const ciphertext = encryptAesEcb(params.buf, params.aeskey);
+    const cdnUrl = buildCdnUploadUrl(CDN_BASE_URL, params.uploadParam, params.filekey);
+    let downloadParam;
+    let lastError;
+    for (let attempt = 1; attempt <= CDN_MAX_RETRIES; attempt += 1) {
+        try {
+            const res = await fetch(cdnUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/octet-stream" },
+                body: new Uint8Array(ciphertext),
+            });
+            if (res.status >= 400 && res.status < 500) {
+                const errMsg = res.headers.get("x-error-message") ?? (await res.text());
+                throw new Error(`CDN client error ${res.status}: ${errMsg}`);
+            }
+            if (res.status !== 200) {
+                const errMsg = res.headers.get("x-error-message") ?? `status ${res.status}`;
+                throw new Error(`CDN server error: ${errMsg}`);
+            }
+            downloadParam = res.headers.get("x-encrypted-param") ?? undefined;
+            if (!downloadParam) {
+                throw new Error("CDN response missing x-encrypted-param header");
+            }
+            break;
+        }
+        catch (err) {
+            lastError = err;
+            if (err instanceof Error && err.message.includes("client error")) {
+                throw err;
+            }
+            if (attempt >= CDN_MAX_RETRIES) {
+                break;
+            }
+            params.onRetry?.(attempt);
+        }
+    }
+    if (!downloadParam) {
+        throw lastError instanceof Error ? lastError : new Error("CDN upload failed");
+    }
+    return { downloadParam };
+}
+function extractReferenceLabel(item) {
+    const ref = item.ref_msg;
+    if (!ref) {
+        return null;
+    }
+    const parts = [];
+    if (ref.title?.trim()) {
+        parts.push(ref.title.trim());
+    }
+    const quotedText = ref.message_item?.text_item?.text?.trim();
+    if (quotedText) {
+        parts.push(quotedText);
+    }
+    return parts.length ? `Quoted: ${parts.join(" | ")}` : null;
+}
+function extractTextFromMessage(message) {
+    if (!message.item_list?.length) {
+        return "";
+    }
+    const lines = [];
+    for (const item of message.item_list) {
+        const reference = extractReferenceLabel(item);
+        if (reference && !lines.includes(reference)) {
+            lines.push(reference);
+        }
+        if (item.type === MSG_ITEM_TEXT) {
+            const text = item.text_item?.text?.trim();
+            if (text) {
+                lines.push(text);
+            }
+        }
+        if (item.type === MSG_ITEM_VOICE) {
+            const transcript = item.voice_item?.text?.trim();
+            if (transcript) {
+                lines.push(transcript);
+            }
+        }
+    }
+    return lines.join("\n").trim();
+}
+function buildMessageKey(message) {
+    return [
+        message.from_user_id ?? "",
+        message.client_id ?? "",
+        String(message.create_time_ms ?? ""),
+        message.context_token ?? "",
+    ].join("|");
+}
+function buildScopedMessageClaimKey(accountId, messageKey) {
+    return `${accountId}|${messageKey}`;
+}
+export function buildInboundMessageClaimPath(messageKey, claimsDir = INBOUND_MESSAGE_CLAIMS_DIR) {
+    const fileName = `${crypto.createHash("sha1").update(messageKey).digest("hex")}.json`;
+    return path.join(claimsDir, fileName);
+}
+export function clearInboundMessageClaims(claimsDir = INBOUND_MESSAGE_CLAIMS_DIR) {
+    try {
+        fs.rmSync(claimsDir, { recursive: true, force: true });
+    }
+    catch {
+        // Best effort cleanup.
+    }
+}
+export function tryClaimInboundMessage(messageKey, options = {}) {
+    if (!messageKey) {
+        return false;
+    }
+    const claimsDir = options.claimsDir ?? INBOUND_MESSAGE_CLAIMS_DIR;
+    const nowMs = options.nowMs ?? Date.now();
+    const ttlMs = options.ttlMs ?? INBOUND_MESSAGE_CLAIM_TTL_MS;
+    const claimPath = buildInboundMessageClaimPath(messageKey, claimsDir);
+    const attemptClaim = () => {
+        fs.mkdirSync(claimsDir, { recursive: true });
+        const handle = fs.openSync(claimPath, "wx");
+        try {
+            fs.writeFileSync(handle, JSON.stringify({
+                key: messageKey,
+                claimedAt: new Date(nowMs).toISOString(),
+                pid: process.pid,
+            }, null, 2), "utf-8");
+        }
+        finally {
+            fs.closeSync(handle);
+        }
+        return true;
+    };
+    try {
+        return attemptClaim();
+    }
+    catch (error) {
+        const code = typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            typeof error.code === "string"
+            ? error.code
+            : "";
+        if (code !== "EEXIST") {
+            return true;
+        }
+    }
+    try {
+        const stat = fs.statSync(claimPath);
+        if (Number.isFinite(stat.mtimeMs) && nowMs - stat.mtimeMs > ttlMs) {
+            fs.rmSync(claimPath, { force: true });
+            return attemptClaim();
+        }
+    }
+    catch {
+        return attemptClaim();
+    }
+    return false;
+}
+function normalizeSender(senderId) {
+    return senderId.split("@")[0] || senderId;
+}
+function formatTimestamp(timestampMs) {
+    if (!timestampMs) {
+        return new Date().toISOString();
+    }
+    return new Date(timestampMs).toISOString();
+}
+export class WeChatTransport {
+    logger;
+    recentMessageKeys = new Set();
+    recentMessageOrder = [];
+    contextTokenCache = new Map(Object.entries(readJsonFile(CONTEXT_CACHE_FILE) ?? {}));
+    syncBuffer = "";
+    constructor(logger) {
+        this.logger = logger;
+        migrateLegacyChannelFiles((message) => this.logger.log(message));
+        this.syncBuffer = this.readSyncBuffer();
+    }
+    getCredentials() {
+        return readJsonFile(CREDENTIALS_FILE);
+    }
+    getStatusText() {
+        const account = this.getCredentials();
+        const syncExists = fs.existsSync(SYNC_BUF_FILE);
+        const contextExists = fs.existsSync(CONTEXT_CACHE_FILE);
+        return [
+            `credentials_file: ${CREDENTIALS_FILE}`,
+            `credentials_present: ${account ? "yes" : "no"}`,
+            `sync_state_file: ${SYNC_BUF_FILE}`,
+            `sync_state_present: ${syncExists ? "yes" : "no"}`,
+            `context_cache_file: ${CONTEXT_CACHE_FILE}`,
+            `context_cache_present: ${contextExists ? "yes" : "no"}`,
+            `cached_context_count: ${this.contextTokenCache.size}`,
+            `max_image_mb: ${resolveMediaUploadLimitBytes("image") / BYTES_PER_MB}`,
+            `max_file_mb: ${resolveMediaUploadLimitBytes("file") / BYTES_PER_MB}`,
+            `max_voice_mb: ${resolveMediaUploadLimitBytes("voice") / BYTES_PER_MB}`,
+            `max_video_mb: ${resolveMediaUploadLimitBytes("video") / BYTES_PER_MB}`,
+            `account_id: ${account?.accountId ?? "(none)"}`,
+            `user_id: ${account?.userId ?? "(none)"}`,
+            `saved_at: ${account?.savedAt ?? "(none)"}`,
+        ].join("\n");
+    }
+    resetSyncState(options = {}) {
+        this.clearSyncBuffer();
+        this.clearRecentMessages();
+        clearInboundMessageClaims();
+        if (options.clearContextCache) {
+            this.clearContextTokenCache();
+        }
+        return options.clearContextCache
+            ? "Reset sync state and cleared cached context tokens."
+            : "Reset sync state.";
+    }
+    async pollMessages(options = {}) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_LONG_POLL_TIMEOUT_MS;
+        const account = this.requireAccount();
+        let response = await this.getUpdates(account, timeoutMs);
+        if (isWechatSyncSessionTimeout(response) && this.syncBuffer) {
+            this.logger.log("WeChat sync session timed out. Clearing local sync cursor and retrying once.");
+            this.clearSyncBuffer();
+            response = await this.getUpdates(account, timeoutMs);
+        }
+        if (isWechatSyncSessionTimeout(response)) {
+            throw new Error('WeChat session timed out. Run "wechat-setup" to log in again.');
+        }
+        const isError = (response.ret !== undefined && response.ret !== 0) ||
+            (response.errcode !== undefined && response.errcode !== 0);
+        if (isError) {
+            throw new Error(`getUpdates failed: ret=${response.ret} errcode=${response.errcode} errmsg=${response.errmsg ?? ""}`);
+        }
+        if (response.get_updates_buf) {
+            this.syncBuffer = response.get_updates_buf;
+            this.saveSyncBuffer(this.syncBuffer);
+        }
+        const messages = [];
+        let ignoredBacklogCount = 0;
+        for (const rawMessage of response.msgs ?? []) {
+            if (rawMessage.message_type !== MSG_TYPE_USER) {
+                continue;
+            }
+            const text = extractTextFromMessage(rawMessage);
+            if (!text) {
+                continue;
+            }
+            const messageKey = buildMessageKey(rawMessage);
+            if (!this.rememberMessage(messageKey)) {
+                continue;
+            }
+            if (!tryClaimInboundMessage(buildScopedMessageClaimKey(account.accountId, messageKey))) {
+                continue;
+            }
+            const senderId = rawMessage.from_user_id ?? "unknown";
+            if (rawMessage.context_token) {
+                this.cacheContextToken(senderId, rawMessage.context_token);
+            }
+            const createdAtMs = rawMessage.create_time_ms;
+            if (typeof options.minCreatedAtMs === "number" &&
+                (!Number.isFinite(createdAtMs) || createdAtMs < options.minCreatedAtMs)) {
+                ignoredBacklogCount += 1;
+                continue;
+            }
+            messages.push({
+                senderId,
+                sender: normalizeSender(senderId),
+                sessionId: rawMessage.session_id ?? "",
+                text,
+                contextToken: rawMessage.context_token,
+                createdAt: formatTimestamp(rawMessage.create_time_ms),
+                createdAtMs,
+            });
+        }
+        return { messages, ignoredBacklogCount };
+    }
+    async sendText(senderId, text) {
+        const trimmed = text.trim();
+        if (!trimmed) {
+            return;
+        }
+        const resolved = this.resolveRecipient(senderId);
+        await this.sendTextWithContextToken(resolved.account, resolved.recipientId, trimmed, resolved.contextToken);
+    }
+    async sendNotification(message, recipientId) {
+        const trimmed = message.trim();
+        if (!trimmed) {
+            throw new Error("Notification text cannot be empty.");
+        }
+        const resolved = this.resolveRecipient(recipientId);
+        await this.sendTextWithContextToken(resolved.account, resolved.recipientId, trimmed, resolved.contextToken);
+        return resolved.recipientId;
+    }
+    async sendImage(imagePath, options = {}) {
+        const resolved = this.resolveRecipient(options.recipientId);
+        const caption = options.caption?.trim();
+        if (caption) {
+            await this.sendTextWithContextToken(resolved.account, resolved.recipientId, caption, resolved.contextToken);
+        }
+        const upload = await this.prepareUpload(resolved.account, resolved.recipientId, imagePath, UPLOAD_MEDIA_TYPE_IMAGE, "image");
+        await this.sendMessage(resolved.account, resolved.recipientId, resolved.contextToken, [
+            {
+                type: MSG_ITEM_IMAGE,
+                image_item: {
+                    media: {
+                        encrypt_query_param: upload.downloadParam,
+                        aes_key: encodeMessageAesKey(upload.aeskey),
+                        encrypt_type: 1,
+                    },
+                    mid_size: upload.filesize,
+                },
+            },
+        ]);
+        return resolved.recipientId;
+    }
+    async sendFile(filePath, options = {}) {
+        const resolved = this.resolveRecipient(options.recipientId);
+        const upload = await this.prepareUpload(resolved.account, resolved.recipientId, filePath, UPLOAD_MEDIA_TYPE_FILE, "file");
+        const fileName = options.title?.trim() || path.basename(filePath);
+        await this.sendMessage(resolved.account, resolved.recipientId, resolved.contextToken, [
+            {
+                type: MSG_ITEM_FILE,
+                file_item: {
+                    file_name: fileName,
+                    len: String(upload.rawsize),
+                    media: {
+                        encrypt_query_param: upload.downloadParam,
+                        aes_key: encodeMessageAesKey(upload.aeskey),
+                        encrypt_type: 1,
+                    },
+                },
+            },
+        ]);
+        return resolved.recipientId;
+    }
+    async sendVoice(voicePath, recipientId) {
+        const resolved = this.resolveRecipient(recipientId);
+        const upload = await this.prepareUpload(resolved.account, resolved.recipientId, voicePath, UPLOAD_MEDIA_TYPE_VOICE, "voice");
+        await this.sendMessage(resolved.account, resolved.recipientId, resolved.contextToken, [
+            {
+                type: MSG_ITEM_VOICE,
+                voice_item: {
+                    media: {
+                        encrypt_query_param: upload.downloadParam,
+                        aes_key: encodeMessageAesKey(upload.aeskey),
+                        encrypt_type: 1,
+                    },
+                },
+            },
+        ]);
+        return resolved.recipientId;
+    }
+    async sendVideo(videoPath, options = {}) {
+        const resolved = this.resolveRecipient(options.recipientId);
+        const title = options.title?.trim();
+        if (title) {
+            await this.sendTextWithContextToken(resolved.account, resolved.recipientId, title, resolved.contextToken);
+        }
+        const upload = await this.prepareUpload(resolved.account, resolved.recipientId, videoPath, UPLOAD_MEDIA_TYPE_VIDEO, "video");
+        await this.sendMessage(resolved.account, resolved.recipientId, resolved.contextToken, [
+            {
+                type: MSG_ITEM_VIDEO,
+                video_item: {
+                    media: {
+                        encrypt_query_param: upload.downloadParam,
+                        aes_key: encodeMessageAesKey(upload.aeskey),
+                        encrypt_type: 1,
+                    },
+                    video_size: upload.filesize,
+                },
+            },
+        ]);
+        return resolved.recipientId;
+    }
+    requireAccount() {
+        const account = this.getCredentials();
+        if (!account) {
+            throw new Error(`No saved WeChat credentials found. Start a bridge command in a terminal to log in automatically, or run "wechat-setup". Expected file: ${CREDENTIALS_FILE}`);
+        }
+        return account;
+    }
+    resolveRecipient(recipientId) {
+        const account = this.requireAccount();
+        let resolvedRecipientId = recipientId?.trim();
+        if (!resolvedRecipientId) {
+            const recipients = [...this.contextTokenCache.keys()];
+            resolvedRecipientId = recipients[recipients.length - 1];
+            if (!resolvedRecipientId) {
+                throw new Error("No cached context token is available. Fetch messages first or ask the user to send a new WeChat message.");
+            }
+        }
+        const contextToken = this.contextTokenCache.get(resolvedRecipientId);
+        if (!contextToken) {
+            throw new Error(`No cached context token for ${resolvedRecipientId}. Fetch messages first or ask the user to send a new WeChat message.`);
+        }
+        return { account, recipientId: resolvedRecipientId, contextToken };
+    }
+    async sendTextWithContextToken(account, recipientId, text, contextToken) {
+        const trimmed = text.trim();
+        if (!trimmed) {
+            return;
+        }
+        await this.sendMessage(account, recipientId, contextToken, [
+            { type: MSG_ITEM_TEXT, text_item: { text: trimmed } },
+        ]);
+    }
+    async sendMessage(account, recipientId, contextToken, itemList) {
+        await apiFetch({
+            baseUrl: account.baseUrl,
+            endpoint: "ilink/bot/sendmessage",
+            body: JSON.stringify({
+                msg: {
+                    from_user_id: "",
+                    to_user_id: recipientId,
+                    client_id: this.generateClientId(),
+                    message_type: MSG_TYPE_BOT,
+                    message_state: MSG_STATE_FINISH,
+                    item_list: itemList,
+                    context_token: contextToken,
+                },
+                base_info: { channel_version: CHANNEL_VERSION },
+            }),
+            token: account.token,
+            timeoutMs: SEND_TIMEOUT_MS,
+        });
+    }
+    async prepareUpload(account, recipientId, filePath, mediaType, label) {
+        const stat = this.requireExistingFile(filePath);
+        assertMediaUploadSizeAllowed(label, stat.size);
+        const plaintext = fs.readFileSync(filePath);
+        const rawsize = plaintext.length;
+        const rawfilemd5 = crypto.createHash("md5").update(plaintext).digest("hex");
+        const filesize = aesEcbPaddedSize(rawsize);
+        const filekey = crypto.randomBytes(16).toString("hex");
+        const aeskey = crypto.randomBytes(16);
+        this.logger.log(`Uploading ${label}: ${filePath} (${rawsize} bytes, md5=${rawfilemd5})`);
+        const uploadResp = await getUploadUrl(account, {
+            filekey,
+            media_type: mediaType,
+            to_user_id: recipientId,
+            rawsize,
+            rawfilemd5,
+            filesize,
+            aeskey: aeskey.toString("hex"),
+        });
+        if (!uploadResp.upload_param) {
+            throw new Error("getUploadUrl returned no upload_param");
+        }
+        const { downloadParam } = await uploadBufferToCdn({
+            buf: plaintext,
+            uploadParam: uploadResp.upload_param,
+            filekey,
+            aeskey,
+            onRetry: (attempt) => {
+                this.logger.log(`CDN upload attempt ${attempt} failed for ${label}, retrying...`);
+            },
+        });
+        this.logger.log(`${label} upload complete, downloadParam length=${downloadParam.length}`);
+        return {
+            rawsize,
+            filesize,
+            aeskey,
+            downloadParam,
+        };
+    }
+    requireExistingFile(filePath) {
+        let stat;
+        try {
+            stat = fs.statSync(filePath);
+        }
+        catch {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        if (!stat.isFile()) {
+            throw new Error(`Not a file: ${filePath}`);
+        }
+        return stat;
+    }
+    async getUpdates(account, timeoutMs) {
+        try {
+            const raw = await apiFetch({
+                baseUrl: account.baseUrl,
+                endpoint: "ilink/bot/getupdates",
+                body: JSON.stringify({
+                    get_updates_buf: this.syncBuffer,
+                    base_info: { channel_version: CHANNEL_VERSION },
+                }),
+                token: account.token,
+                timeoutMs,
+            });
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                return { ret: 0, msgs: [], get_updates_buf: this.syncBuffer };
+            }
+            throw err;
+        }
+    }
+    rememberMessage(key) {
+        if (!key || this.recentMessageKeys.has(key)) {
+            return false;
+        }
+        this.recentMessageKeys.add(key);
+        this.recentMessageOrder.push(key);
+        while (this.recentMessageOrder.length > RECENT_MESSAGE_CACHE_SIZE) {
+            const oldest = this.recentMessageOrder.shift();
+            if (oldest) {
+                this.recentMessageKeys.delete(oldest);
+            }
+        }
+        return true;
+    }
+    clearRecentMessages() {
+        this.recentMessageKeys.clear();
+        this.recentMessageOrder.length = 0;
+    }
+    readSyncBuffer() {
+        try {
+            if (!fs.existsSync(SYNC_BUF_FILE)) {
+                return "";
+            }
+            return fs.readFileSync(SYNC_BUF_FILE, "utf-8");
+        }
+        catch (err) {
+            this.logger.logError(`Failed to read sync state: ${String(err)}`);
+            return "";
+        }
+    }
+    saveSyncBuffer(syncBuffer) {
+        ensureChannelDataDir();
+        fs.writeFileSync(SYNC_BUF_FILE, syncBuffer, "utf-8");
+    }
+    clearSyncBuffer() {
+        this.syncBuffer = "";
+        if (fs.existsSync(SYNC_BUF_FILE)) {
+            fs.rmSync(SYNC_BUF_FILE, { force: true });
+        }
+    }
+    cacheContextToken(senderId, token) {
+        if (this.contextTokenCache.has(senderId)) {
+            this.contextTokenCache.delete(senderId);
+        }
+        this.contextTokenCache.set(senderId, token);
+        writeJsonFile(CONTEXT_CACHE_FILE, Object.fromEntries(this.contextTokenCache));
+    }
+    clearContextTokenCache() {
+        this.contextTokenCache.clear();
+        if (fs.existsSync(CONTEXT_CACHE_FILE)) {
+            fs.rmSync(CONTEXT_CACHE_FILE, { force: true });
+        }
+    }
+    generateClientId() {
+        return `wechat-bridge:${Date.now()}-${crypto.randomBytes(4).toString("hex")}`;
+    }
+}