@yanhaidao/wecom 2.4.120 → 2.5.110

package/{src/target.ts → dist/src/target.js}

@@ -1,9 +1,9 @@
 /**
  * WeCom Target Resolver (企业微信目标解析器)
- * 
+ *
  * 解析 OpenClaw 的 `to` 字段（原始目标字符串），将其转换为企业微信支持的具体接收对象。
  * 支持显式前缀 (party:, tag: 等) 和基于规则的启发式推断。
- * 
+ *
  * **关于“目标发送”与“消息记录”的对应关系 (Target vs Inbound):**
  * - **发送 (Outbound)**: 支持一对多广播 (Party/Tag)。
  *   例如发送给 `party:1`，消息会触达该部门下所有成员。
@@ -12,24 +12,7 @@
  *   因此，Outbound Target (如 Party) 与 Inbound Source (User) 不需要也不可能 1:1 强匹配。
  *   广播是“发后即忘” (Fire-and-Forget) 的通知模式，而回复是具体的会话模式。
  */
-
-export interface WecomTarget {
-    touser?: string;
-    toparty?: string;
-    totag?: string;
-    chatid?: string;
-}
-
-export interface ScopedWecomTarget {
-    accountId?: string;
-    target: WecomTarget;
-    rawTarget: string;
-}
-
-function parseUpstreamScopedTarget(raw: string): {
-    accountId?: string;
-    userId: string;
-} | undefined {
+function parseUpstreamScopedTarget(raw) {
     const legacyScoped = raw.match(/^wecom-agent-upstream:([^:]+):([^:]+):(.+)$/i);
     if (legacyScoped) {
         return {
@@ -37,40 +20,35 @@ function parseUpstreamScopedTarget(raw: string): {
             userId: legacyScoped[3]?.trim() || "",
         };
     }
-
     const queryIndex = raw.indexOf("?upstream_corp=");
     if (queryIndex < 0 || !raw.startsWith("wecom-agent:")) {
         return undefined;
     }
-
     const pathPart = raw.slice(0, queryIndex);
     const match = pathPart.match(/^wecom-agent:([^:]+):user:(.+)$/i);
     if (!match) {
         return undefined;
     }
-
     return {
         accountId: match[1]?.trim(),
         userId: match[2]?.trim() || "",
     };
 }
-
-export function buildWecomContextTarget(contextToken: string): string {
+export function buildWecomContextTarget(contextToken) {
     return `wecom:context:${contextToken}`;
 }
-
-export function resolveWecomContextTarget(raw: string | undefined): { contextToken: string } | undefined {
+export function resolveWecomContextTarget(raw) {
     const trimmed = raw?.trim();
-    if (!trimmed) return undefined;
+    if (!trimmed)
+        return undefined;
     const match = trimmed.match(/^(?:wecom|wechatwork|wework|qywx):context:(.+)$/i);
     const contextToken = match?.[1]?.trim();
     return contextToken ? { contextToken } : undefined;
 }
-
 /**
  * Parses a raw target string into a WeComTarget object.
  * 解析原始目标字符串为 WeComTarget 对象。
- * 
+ *
  * 逻辑:
  * 1. 先检查显式类型前缀 (user:, group:, party:, tag:) —— 优先匹配，不受命名空间前缀影响
  * 2. 移除标准命名空间前缀 (wecom:, qywx: 等)
@@ -79,14 +57,13 @@ export function resolveWecomContextTarget(raw: string | undefined): { contextTok
  *    - 以 "wr" 或 "wc" 开头 -> Chat ID (群聊)
  *    - 纯数字 -> 默认 User ID (用户)，避免误判部门导致 81013 错误
  *    - 其他 -> User ID (用户)
- * 
+ *
  * @param raw - The raw target string (e.g. "party:1", "zhangsan", "wecom:user:xxx")
  */
-export function resolveWecomTarget(raw: string | undefined, options?: { preferUserForDigits?: boolean }): WecomTarget | undefined {
-    if (!raw?.trim()) return undefined;
-
+export function resolveWecomTarget(raw, options) {
+    if (!raw?.trim())
+        return undefined;
     const trimmed = raw.trim();
-
     // 1. 先检查原始字符串中的类型前缀（处理 user:xxx 无前缀格式）
     // 这样即使没有 wecom: 前缀，也能正确识别类型
     if (/^user:/i.test(trimmed)) {
@@ -101,10 +78,8 @@ export function resolveWecomTarget(raw: string | undefined, options?: { preferUs
     if (/^tag:/i.test(trimmed)) {
         return { totag: trimmed.replace(/^tag:/i, "").trim() };
     }
-
     // 2. Remove standard namespace prefixes (移除标准命名空间前缀)
     let clean = trimmed.replace(/^(wecom-agent|wecom|wechatwork|wework|qywx):/i, "");
-
     // 3. 再次检查类型前缀（处理 wecom:user:xxx 格式）
     if (/^user:/i.test(clean)) {
         return { touser: clean.replace(/^user:/i, "").trim() };
@@ -118,15 +93,12 @@ export function resolveWecomTarget(raw: string | undefined, options?: { preferUs
     if (/^tag:/i.test(clean)) {
         return { totag: clean.replace(/^tag:/i, "").trim() };
     }
-
     // 4. Heuristics (启发式规则)
-
     // Chat ID typically starts with 'wr' or 'wc'
     // 群聊 ID 通常以 'wr' (外部群) 或 'wc' 开头
     if (/^(wr|wc)/i.test(clean)) {
         return { chatid: clean };
     }
-
     // Pure digits: Default to User (纯数字默认为用户)
     // 原因：1) Bot WS 主动推送只接受 touser/chatid，不接受 toparty/totag
     //      2) 用户 ID 在企业微信中常为纯数字
@@ -138,16 +110,13 @@ export function resolveWecomTarget(raw: string | undefined, options?: { preferUs
         }
         return { touser: clean };
     }
-
     // Default to User (默认为用户)
     return { touser: clean };
 }
-
-export function resolveScopedWecomTarget(raw: string | undefined, defaultAccountId?: string): ScopedWecomTarget | undefined {
-    if (!raw?.trim()) return undefined;
-
+export function resolveScopedWecomTarget(raw, defaultAccountId) {
+    if (!raw?.trim())
+        return undefined;
     const trimmed = raw.trim();
-
     const upstreamScoped = parseUpstreamScopedTarget(trimmed);
     if (upstreamScoped) {
         const accountId = upstreamScoped.accountId || defaultAccountId;
@@ -157,7 +126,6 @@ export function resolveScopedWecomTarget(raw: string | undefined, defaultAccount
             rawTarget: upstreamScoped.userId,
         };
     }
-
     const agentScoped = trimmed.match(/^wecom-agent:([^:]+):(.+)$/i);
     if (agentScoped) {
         const accountId = agentScoped[1]?.trim() || defaultAccountId;
@@ -167,7 +135,6 @@ export function resolveScopedWecomTarget(raw: string | undefined, defaultAccount
         const target = resolveWecomTarget(rawTarget, { preferUserForDigits: true });
         return target ? { accountId, target, rawTarget } : undefined;
     }
-
     const target = resolveWecomTarget(trimmed);
     return target
         ? {

package/dist/src/transport/agent-api/client.js

@@ -0,0 +1,168 @@
+import { LIMITS } from "../../types/constants.js";
+import { downloadMedia as downloadLegacyMedia, getAccessToken as getLegacyAccessToken, getUpstreamAccessToken as getLegacyUpstreamAccessToken, sendMedia as sendLegacyMedia, sendText as sendLegacyText, } from "./core.js";
+export async function getAgentApiAccessToken(agent) {
+    return getLegacyAccessToken(agent);
+}
+export async function getUpstreamAgentApiAccessToken(params) {
+    return getLegacyUpstreamAccessToken(params);
+}
+export async function sendAgentApiText(params) {
+    await sendLegacyText(params);
+}
+export async function sendAgentApiMedia(params) {
+    await sendLegacyMedia(params);
+}
+export async function downloadAgentApiMedia(params) {
+    return downloadLegacyMedia(params);
+}
+export async function downloadUpstreamAgentApiMedia(params) {
+    const { upstreamAgent, primaryAgent, mediaId, maxBytes } = params;
+    const token = await getUpstreamAgentApiAccessToken({
+        primaryAgent,
+        upstreamCorpId: upstreamAgent.corpId,
+        upstreamAgentId: upstreamAgent.agentId,
+    });
+    const url = `https://qyapi.weixin.qq.com/cgi-bin/media/get?access_token=${encodeURIComponent(token)}&media_id=${encodeURIComponent(mediaId)}`;
+    const { wecomFetch, readResponseBodyAsBuffer } = await import("../../http.js");
+    const { resolveWecomEgressProxyUrlFromNetwork } = await import("../../config/index.js");
+    const res = await wecomFetch(url, undefined, {
+        proxyUrl: resolveWecomEgressProxyUrlFromNetwork(upstreamAgent.network),
+        timeoutMs: LIMITS.REQUEST_TIMEOUT_MS,
+    });
+    if (!res.ok) {
+        throw new Error(`download failed: ${res.status}`);
+    }
+    const contentType = res.headers.get("content-type") || "application/octet-stream";
+    const disposition = res.headers.get("content-disposition") || "";
+    const filename = (() => {
+        const mStar = disposition.match(/filename\*\s*=\s*([^;]+)/i);
+        if (mStar) {
+            const raw = mStar[1].trim().replace(/^"(.*)"$/, "$1");
+            const parts = raw.split("''");
+            const encoded = parts.length === 2 ? parts[1] : raw;
+            try {
+                return decodeURIComponent(encoded);
+            }
+            catch {
+                return encoded;
+            }
+        }
+        const m = disposition.match(/filename\s*=\s*([^;]+)/i);
+        if (!m)
+            return undefined;
+        return m[1].trim().replace(/^"(.*)"$/, "$1") || undefined;
+    })();
+    if (contentType.includes("application/json")) {
+        const json = (await res.json());
+        throw new Error(`download failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    const buffer = await readResponseBodyAsBuffer(res, maxBytes);
+    return { buffer, contentType, filename };
+}
+/**
+ * 发送文本消息给上下游用户
+ * 使用下游企业的 access_token 和 agentId
+ */
+export async function sendUpstreamAgentApiText(params) {
+    const { upstreamAgent, primaryAgent, toUser, toParty, toTag, chatId, text } = params;
+    // 获取下游企业的 access_token
+    const token = await getUpstreamAgentApiAccessToken({
+        primaryAgent,
+        upstreamCorpId: upstreamAgent.corpId,
+        upstreamAgentId: upstreamAgent.agentId,
+    });
+    const useChat = Boolean(chatId);
+    const url = useChat
+        ? `https://qyapi.weixin.qq.com/cgi-bin/appchat/send?access_token=${encodeURIComponent(token)}`
+        : `https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=${encodeURIComponent(token)}`;
+    const body = useChat
+        ? { chatid: chatId, msgtype: "text", text: { content: text } }
+        : {
+            touser: toUser,
+            toparty: toParty,
+            totag: toTag,
+            msgtype: "text",
+            agentid: upstreamAgent.agentId,
+            text: { content: text },
+        };
+    const { wecomFetch } = await import("../../http.js");
+    const { resolveWecomEgressProxyUrlFromNetwork } = await import("../../config/index.js");
+    const res = await wecomFetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }, {
+        proxyUrl: resolveWecomEgressProxyUrlFromNetwork(upstreamAgent.network),
+        timeoutMs: LIMITS.REQUEST_TIMEOUT_MS,
+    });
+    const json = (await res.json());
+    if (json?.errcode !== 0) {
+        throw new Error(`send failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
+        const details = [
+            json.invaliduser ? `invaliduser=${json.invaliduser}` : "",
+            json.invalidparty ? `invalidparty=${json.invalidparty}` : "",
+            json.invalidtag ? `invalidtag=${json.invalidtag}` : "",
+        ]
+            .filter(Boolean)
+            .join(", ");
+        throw new Error(`send partial failure: ${details}`);
+    }
+}
+/**
+ * 发送媒体消息给上下游用户
+ * 使用下游企业的 access_token 和 agentId
+ */
+export async function sendUpstreamAgentApiMedia(params) {
+    const { upstreamAgent, primaryAgent, toUser, toParty, toTag, chatId, mediaId, mediaType, title, description } = params;
+    // 获取下游企业的 access_token
+    const token = await getUpstreamAgentApiAccessToken({
+        primaryAgent,
+        upstreamCorpId: upstreamAgent.corpId,
+        upstreamAgentId: upstreamAgent.agentId,
+    });
+    console.log(`[wecom-upstream-api] sendMedia corpId=${upstreamAgent.corpId} agentId=${upstreamAgent.agentId} ` +
+        `toUser=${toUser ?? ""} mediaType=${mediaType}`);
+    const useChat = Boolean(chatId);
+    const url = useChat
+        ? `https://qyapi.weixin.qq.com/cgi-bin/appchat/send?access_token=${encodeURIComponent(token)}`
+        : `https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=${encodeURIComponent(token)}`;
+    const mediaPayload = mediaType === "video"
+        ? { media_id: mediaId, title: title ?? "Video", description: description ?? "" }
+        : { media_id: mediaId };
+    const body = useChat
+        ? { chatid: chatId, msgtype: mediaType, [mediaType]: mediaPayload }
+        : {
+            touser: toUser,
+            toparty: toParty,
+            totag: toTag,
+            msgtype: mediaType,
+            agentid: upstreamAgent.agentId,
+            [mediaType]: mediaPayload,
+        };
+    const { wecomFetch } = await import("../../http.js");
+    const { resolveWecomEgressProxyUrlFromNetwork } = await import("../../config/index.js");
+    const res = await wecomFetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }, {
+        proxyUrl: resolveWecomEgressProxyUrlFromNetwork(upstreamAgent.network),
+        timeoutMs: LIMITS.REQUEST_TIMEOUT_MS,
+    });
+    const json = (await res.json());
+    if (json?.errcode !== 0) {
+        throw new Error(`send ${mediaType} failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
+        const details = [
+            json.invaliduser ? `invaliduser=${json.invaliduser}` : "",
+            json.invalidparty ? `invalidparty=${json.invalidparty}` : "",
+            json.invalidtag ? `invalidtag=${json.invalidtag}` : "",
+        ]
+            .filter(Boolean)
+            .join(", ");
+        throw new Error(`send ${mediaType} partial failure: ${details}`);
+    }
+}

package/dist/src/transport/agent-api/core.js

@@ -0,0 +1,337 @@
+import crypto from "node:crypto";
+import { resolveWecomEgressProxyUrlFromNetwork } from "../../config/index.js";
+import { readResponseBodyAsBuffer, wecomFetch } from "../../http.js";
+import { API_ENDPOINTS, LIMITS } from "../../types/constants.js";
+const tokenCaches = new Map();
+function truncateForLog(raw, maxChars = 180) {
+    const compact = raw.replace(/\s+/g, " ").trim();
+    if (compact.length <= maxChars)
+        return compact;
+    return `${compact.slice(0, maxChars)}...(truncated)`;
+}
+export function normalizeUploadFilename(filename) {
+    const trimmed = filename.trim();
+    if (!trimmed)
+        return "file.bin";
+    const ext = trimmed.includes(".") ? `.${trimmed.split(".").pop().toLowerCase()}` : "";
+    const base = ext ? trimmed.slice(0, -ext.length) : trimmed;
+    const sanitizedBase = base
+        .replace(/[^\x20-\x7e]/g, "_")
+        .replace(/["\\/;=]/g, "_")
+        .replace(/\s+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    const safeBase = sanitizedBase || "file";
+    const safeExt = ext.replace(/[^a-z0-9.]/g, "");
+    return `${safeBase}${safeExt || ".bin"}`;
+}
+export function guessUploadContentType(filename) {
+    const ext = filename.split(".").pop()?.toLowerCase() || "";
+    const contentTypeMap = {
+        jpg: "image/jpg",
+        jpeg: "image/jpeg",
+        png: "image/png",
+        gif: "image/gif",
+        webp: "image/webp",
+        bmp: "image/bmp",
+        amr: "voice/amr",
+        mp3: "audio/mpeg",
+        wav: "audio/wav",
+        m4a: "audio/mp4",
+        ogg: "audio/ogg",
+        mp4: "video/mp4",
+        mov: "video/quicktime",
+        txt: "text/plain",
+        md: "text/markdown",
+        csv: "text/csv",
+        tsv: "text/tab-separated-values",
+        json: "application/json",
+        xml: "application/xml",
+        yaml: "application/yaml",
+        yml: "application/yaml",
+        pdf: "application/pdf",
+        doc: "application/msword",
+        docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        xls: "application/vnd.ms-excel",
+        xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ppt: "application/vnd.ms-powerpoint",
+        pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        rtf: "application/rtf",
+        odt: "application/vnd.oasis.opendocument.text",
+        zip: "application/zip",
+        rar: "application/vnd.rar",
+        "7z": "application/x-7z-compressed",
+        gz: "application/gzip",
+        tgz: "application/gzip",
+        tar: "application/x-tar",
+    };
+    return contentTypeMap[ext] || "application/octet-stream";
+}
+function requireAgentId(agent) {
+    if (typeof agent.agentId === "number" && Number.isFinite(agent.agentId))
+        return agent.agentId;
+    throw new Error(`wecom agent account=${agent.accountId} missing agentId; sending via cgi-bin/message/send requires agentId`);
+}
+/**
+ * 获取主企业的 access_token
+ * 使用 corpid + corpsecret
+ */
+export async function getAccessToken(agent) {
+    const cacheKey = `${agent.corpId}:${String(agent.agentId ?? "na")}`;
+    let cache = tokenCaches.get(cacheKey);
+    if (!cache) {
+        cache = { token: "", expiresAt: 0, refreshPromise: null };
+        tokenCaches.set(cacheKey, cache);
+    }
+    const now = Date.now();
+    if (cache.token && cache.expiresAt > now + LIMITS.TOKEN_REFRESH_BUFFER_MS) {
+        return cache.token;
+    }
+    if (cache.refreshPromise) {
+        return cache.refreshPromise;
+    }
+    cache.refreshPromise = (async () => {
+        try {
+            const url = `${API_ENDPOINTS.GET_TOKEN}?corpid=${encodeURIComponent(agent.corpId)}&corpsecret=${encodeURIComponent(agent.corpSecret)}`;
+            const res = await wecomFetch(url, undefined, {
+                proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network),
+                timeoutMs: LIMITS.REQUEST_TIMEOUT_MS,
+            });
+            const json = (await res.json());
+            if (!json?.access_token) {
+                throw new Error(`gettoken failed: ${json?.errcode} ${json?.errmsg}`);
+            }
+            cache.token = json.access_token;
+            cache.expiresAt = Date.now() + (json.expires_in ?? 7200) * 1000;
+            return cache.token;
+        }
+        finally {
+            cache.refreshPromise = null;
+        }
+    })();
+    return cache.refreshPromise;
+}
+/**
+ * 获取下游企业的 access_token
+ *
+ * 根据企业微信文档：https://developer.work.weixin.qq.com/document/path/95816
+ *
+ * 请求方式：POST（HTTPS）
+ * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/corpgroup/corp/gettoken?access_token=ACCESS_TOKEN
+ *
+ * 请求体：
+ * {
+ *   "corpid": "下游企业corpid",
+ *   "business_type": 1,  // 1 表示上下游企业
+ *   "agentid": 下游企业应用ID
+ * }
+ *
+ * 注意：需要使用上游企业的 access_token 作为调用凭证
+ */
+export async function getUpstreamAccessToken(params) {
+    const { primaryAgent, upstreamCorpId, upstreamAgentId } = params;
+    // 缓存 key 增加 primaryCorpId 维度，避免多主企业之间碰撞
+    const cacheKey = `upstream:${primaryAgent.corpId}:${upstreamCorpId}:${upstreamAgentId}`;
+    let cache = tokenCaches.get(cacheKey);
+    if (!cache) {
+        cache = { token: "", expiresAt: 0, refreshPromise: null };
+        tokenCaches.set(cacheKey, cache);
+    }
+    const now = Date.now();
+    if (cache.token && cache.expiresAt > now + LIMITS.TOKEN_REFRESH_BUFFER_MS) {
+        return cache.token;
+    }
+    if (cache.refreshPromise) {
+        return cache.refreshPromise;
+    }
+    cache.refreshPromise = (async () => {
+        try {
+            // 1. 先获取上游企业的 access_token
+            const primaryToken = await getAccessToken(primaryAgent);
+            // 2. 调用 corpgroup/corp/gettoken 获取下游企业的 access_token
+            const url = `https://qyapi.weixin.qq.com/cgi-bin/corpgroup/corp/gettoken?access_token=${encodeURIComponent(primaryToken)}`;
+            const requestBody = {
+                corpid: upstreamCorpId,
+                business_type: 1, // 1 表示上下游企业
+                agentid: upstreamAgentId,
+            };
+            const res = await wecomFetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(requestBody),
+            }, {
+                proxyUrl: resolveWecomEgressProxyUrlFromNetwork(primaryAgent.network),
+                timeoutMs: LIMITS.REQUEST_TIMEOUT_MS,
+            });
+            const json = (await res.json());
+            if (!json?.access_token) {
+                throw new Error(`get upstream token failed: ${json?.errcode} ${json?.errmsg}`);
+            }
+            cache.token = json.access_token;
+            cache.expiresAt = Date.now() + (json.expires_in ?? 7200) * 1000;
+            return cache.token;
+        }
+        finally {
+            cache.refreshPromise = null;
+        }
+    })();
+    return cache.refreshPromise;
+}
+export async function sendText(params) {
+    const { agent, toUser, toParty, toTag, chatId, text } = params;
+    console.log(`[wecom-agent-api] sendText request account=${agent.accountId} agentId=${String(agent.agentId ?? "N/A")} corpId=${agent.corpId} ` +
+        `toUser=${toUser ?? ""} toParty=${toParty ?? ""} toTag=${toTag ?? ""} chatId=${chatId ?? ""} ` +
+        `textLen=${text.length} textPreview=${JSON.stringify(truncateForLog(text))}`);
+    const token = await getAccessToken(agent);
+    const useChat = Boolean(chatId);
+    const url = useChat
+        ? `${API_ENDPOINTS.SEND_APPCHAT}?access_token=${encodeURIComponent(token)}`
+        : `${API_ENDPOINTS.SEND_MESSAGE}?access_token=${encodeURIComponent(token)}`;
+    const body = useChat
+        ? { chatid: chatId, msgtype: "text", text: { content: text } }
+        : {
+            touser: toUser,
+            toparty: toParty,
+            totag: toTag,
+            msgtype: "text",
+            agentid: requireAgentId(agent),
+            text: { content: text },
+        };
+    const res = await wecomFetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+    const json = (await res.json());
+    console.log(`[wecom-agent-api] sendText response account=${agent.accountId} agentId=${String(agent.agentId ?? "N/A")} corpId=${agent.corpId} ` +
+        `toUser=${toUser ?? ""} toParty=${toParty ?? ""} toTag=${toTag ?? ""} chatId=${chatId ?? ""} ` +
+        `errcode=${String(json?.errcode ?? "N/A")} errmsg=${json?.errmsg ?? ""} ` +
+        `invaliduser=${json?.invaliduser ?? ""} invalidparty=${json?.invalidparty ?? ""} invalidtag=${json?.invalidtag ?? ""}`);
+    if (json?.errcode !== 0) {
+        throw new Error(`send failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
+        const details = [
+            json.invaliduser ? `invaliduser=${json.invaliduser}` : "",
+            json.invalidparty ? `invalidparty=${json.invalidparty}` : "",
+            json.invalidtag ? `invalidtag=${json.invalidtag}` : "",
+        ]
+            .filter(Boolean)
+            .join(", ");
+        throw new Error(`send partial failure: ${details}`);
+    }
+}
+export async function uploadMedia(params) {
+    const { agent, type, buffer, filename } = params;
+    const safeFilename = normalizeUploadFilename(filename);
+    const token = await getAccessToken(agent);
+    const proxyUrl = resolveWecomEgressProxyUrlFromNetwork(agent.network);
+    const url = `${API_ENDPOINTS.UPLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&type=${encodeURIComponent(type)}&debug=1`;
+    console.log(`[wecom-upload] Uploading media: type=${type}, filename=${safeFilename}, size=${buffer.length} bytes, corpId=${agent.corpId}`);
+    const uploadOnce = async (fileContentType) => {
+        const boundary = `----WebKitFormBoundary${crypto.randomBytes(16).toString("hex")}`;
+        const header = Buffer.from(`--${boundary}\r\n` +
+            `Content-Disposition: form-data; name="media"; filename="${safeFilename}"; filelength=${buffer.length}\r\n` +
+            `Content-Type: ${fileContentType}\r\n\r\n`);
+        const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
+        const body = Buffer.concat([header, buffer, footer]);
+        console.log(`[wecom-upload] Multipart body size=${body.length}, boundary=${boundary}, fileContentType=${fileContentType}`);
+        const res = await wecomFetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": `multipart/form-data; boundary=${boundary}`,
+                "Content-Length": String(body.length),
+            },
+            body,
+        }, { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+        const json = (await res.json());
+        console.log(`[wecom-upload] Response:`, JSON.stringify(json));
+        return json;
+    };
+    const preferredContentType = guessUploadContentType(safeFilename);
+    let json = await uploadOnce(preferredContentType);
+    if (!json?.media_id && preferredContentType !== "application/octet-stream") {
+        console.warn(`[wecom-upload] Upload failed with ${preferredContentType}, retrying as application/octet-stream: ${json?.errcode} ${json?.errmsg}`);
+        json = await uploadOnce("application/octet-stream");
+    }
+    if (!json?.media_id) {
+        throw new Error(`upload failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    return json.media_id;
+}
+export async function sendMedia(params) {
+    const { agent, toUser, toParty, toTag, chatId, mediaId, mediaType, title, description } = params;
+    const token = await getAccessToken(agent);
+    const useChat = Boolean(chatId);
+    const url = useChat
+        ? `${API_ENDPOINTS.SEND_APPCHAT}?access_token=${encodeURIComponent(token)}`
+        : `${API_ENDPOINTS.SEND_MESSAGE}?access_token=${encodeURIComponent(token)}`;
+    const mediaPayload = mediaType === "video" ? { media_id: mediaId, title: title ?? "Video", description: description ?? "" } : { media_id: mediaId };
+    const body = useChat
+        ? { chatid: chatId, msgtype: mediaType, [mediaType]: mediaPayload }
+        : {
+            touser: toUser,
+            toparty: toParty,
+            totag: toTag,
+            msgtype: mediaType,
+            agentid: requireAgentId(agent),
+            [mediaType]: mediaPayload,
+        };
+    const res = await wecomFetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+    const json = (await res.json());
+    if (json?.errcode !== 0) {
+        throw new Error(`send ${mediaType} failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
+        const details = [
+            json.invaliduser ? `invaliduser=${json.invaliduser}` : "",
+            json.invalidparty ? `invalidparty=${json.invalidparty}` : "",
+            json.invalidtag ? `invalidtag=${json.invalidtag}` : "",
+        ]
+            .filter(Boolean)
+            .join(", ");
+        throw new Error(`send ${mediaType} partial failure: ${details}`);
+    }
+}
+export async function downloadMedia(params) {
+    const { agent, mediaId } = params;
+    const token = await getAccessToken(agent);
+    const url = `${API_ENDPOINTS.DOWNLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&media_id=${encodeURIComponent(mediaId)}`;
+    const res = await wecomFetch(url, undefined, {
+        proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network),
+        timeoutMs: LIMITS.REQUEST_TIMEOUT_MS,
+    });
+    if (!res.ok) {
+        throw new Error(`download failed: ${res.status}`);
+    }
+    const contentType = res.headers.get("content-type") || "application/octet-stream";
+    const disposition = res.headers.get("content-disposition") || "";
+    const filename = (() => {
+        const mStar = disposition.match(/filename\*\s*=\s*([^;]+)/i);
+        if (mStar) {
+            const raw = mStar[1].trim().replace(/^"(.*)"$/, "$1");
+            const parts = raw.split("''");
+            const encoded = parts.length === 2 ? parts[1] : raw;
+            try {
+                return decodeURIComponent(encoded);
+            }
+            catch {
+                return encoded;
+            }
+        }
+        const m = disposition.match(/filename\s*=\s*([^;]+)/i);
+        if (!m)
+            return undefined;
+        return m[1].trim().replace(/^"(.*)"$/, "$1") || undefined;
+    })();
+    if (contentType.includes("application/json")) {
+        const json = (await res.json());
+        throw new Error(`download failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    const buffer = await readResponseBodyAsBuffer(res, params.maxBytes);
+    return { buffer, contentType, filename };
+}