@mocrane/wecom 2026.2.5

package/src/types/account.ts

@@ -0,0 +1,76 @@
+/**
+ * WeCom 账号类型定义
+ */
+
+import type { WecomBotConfig, WecomAgentConfig, WecomDmConfig, WecomNetworkConfig } from "./config.js";
+
+/**
+ * 解析后的 Bot 账号
+ */
+export type ResolvedBotAccount = {
+    /** 账号 ID */
+    accountId: string;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 是否配置完整 */
+    configured: boolean;
+    /** 回调 Token */
+    token: string;
+    /** 回调加密密钥 */
+    encodingAESKey: string;
+    /** 接收者 ID */
+    receiveId: string;
+    /** 原始配置 */
+    config: WecomBotConfig;
+    /** 网络配置（来自 channels.wecom.network） */
+    network?: WecomNetworkConfig;
+};
+
+/**
+ * 解析后的 Agent 账号
+ */
+export type ResolvedAgentAccount = {
+    /** 账号 ID */
+    accountId: string;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 是否配置完整 */
+    configured: boolean;
+    /** 企业 ID */
+    corpId: string;
+    /** 应用 Secret */
+    corpSecret: string;
+    /** 应用 ID (数字) */
+    agentId: number;
+    /** 回调 Token */
+    token: string;
+    /** 回调加密密钥 */
+    encodingAESKey: string;
+    /** 原始配置 */
+    config: WecomAgentConfig;
+    /** 网络配置（来自 channels.wecom.network） */
+    network?: WecomNetworkConfig;
+};
+
+/**
+ * 已解析的模式状态
+ */
+export type ResolvedMode = {
+    /** Bot 模式是否已配置 */
+    bot: boolean;
+    /** Agent 模式是否已配置 */
+    agent: boolean;
+};
+
+/**
+ * 解析后的 WeCom 账号集合
+ */
+export type ResolvedWecomAccounts = {
+    /** Bot 模式账号 */
+    bot?: ResolvedBotAccount;
+    /** Agent 模式账号 */
+    agent?: ResolvedAgentAccount;
+};
+
+// Re-export 用于向后兼容
+export type { WecomDmConfig } from "./config.js";

package/src/types/config.ts

@@ -0,0 +1,88 @@
+/**
+ * WeCom 双模式配置类型定义
+ */
+
+/** DM 策略配置 - 与其他渠道保持一致，仅用 allowFrom */
+export type WecomDmConfig = {
+    /** DM 策略: 'open' 允许所有人, 'pairing' 需要配对, 'allowlist' 仅允许列表, 'disabled' 禁用 */
+    policy?: 'open' | 'pairing' | 'allowlist' | 'disabled';
+    /** 允许的用户列表，为空表示允许所有人 */
+    allowFrom?: Array<string | number>;
+};
+
+/** 媒体处理配置 */
+export type WecomMediaConfig = {
+    tempDir?: string;
+    retentionHours?: number;
+    cleanupOnStart?: boolean;
+    maxBytes?: number;
+};
+
+/** 网络配置 */
+export type WecomNetworkConfig = {
+    timeoutMs?: number;
+    retries?: number;
+    retryDelayMs?: number;
+    /**
+     * 出口代理（用于企业可信 IP 固定出口场景）。
+     * 示例: "http://proxy.company.local:3128"
+     */
+    egressProxyUrl?: string;
+};
+
+/**
+ * Bot 模式配置 (智能体)
+ * 用于接收 JSON 格式回调 + 流式回复
+ */
+export type WecomBotConfig = {
+    /** 回调 Token (企微后台生成) */
+    token: string;
+    /** 回调加密密钥 (企微后台生成) */
+    encodingAESKey: string;
+    /** 接收者 ID (可选，用于解密校验) */
+    receiveId?: string;
+    /** 流式消息占位符 */
+    streamPlaceholderContent?: string;
+    /** 欢迎语 */
+    welcomeText?: string;
+    /** DM 策略 */
+    dm?: WecomDmConfig;
+};
+
+/**
+ * Agent 模式配置 (自建应用)
+ * 用于接收 XML 格式回调 + API 主动发送
+ */
+export type WecomAgentConfig = {
+    /** 企业 ID */
+    corpId: string;
+    /** 应用 Secret */
+    corpSecret: string;
+    /** 应用 ID */
+    agentId: number | string;
+    /** 回调 Token (企微后台「设置API接收」) */
+    token: string;
+    /** 回调加密密钥 (企微后台「设置API接收」) */
+    encodingAESKey: string;
+    /** 欢迎语 */
+    welcomeText?: string;
+    /** DM 策略 */
+    dm?: WecomDmConfig;
+};
+
+/**
+ * 顶层 WeCom 配置
+ * 通过 bot / agent 字段隐式指定模式
+ */
+export type WecomConfig = {
+    /** 是否启用 */
+    enabled?: boolean;
+    /** Bot 模式配置 (智能体) */
+    bot?: WecomBotConfig;
+    /** Agent 模式配置 (自建应用) */
+    agent?: WecomAgentConfig;
+    /** 媒体处理配置 */
+    media?: WecomMediaConfig;
+    /** 网络配置 */
+    network?: WecomNetworkConfig;
+};

package/src/types/constants.ts

@@ -0,0 +1,42 @@
+/**
+ * WeCom 双模式常量定义
+ */
+
+/** 固定 Webhook 路径 */
+export const WEBHOOK_PATHS = {
+    /** Bot 模式 (智能体) - 兼容原有路径 */
+    BOT: "/wecom",
+    /** Bot 模式备用路径 */
+    BOT_ALT: "/wecom/bot",
+    /** Agent 模式 (自建应用) */
+    AGENT: "/wecom/agent",
+} as const;
+
+/** 企业微信 API 端点 */
+export const API_ENDPOINTS = {
+    GET_TOKEN: "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
+    SEND_MESSAGE: "https://qyapi.weixin.qq.com/cgi-bin/message/send",
+    SEND_APPCHAT: "https://qyapi.weixin.qq.com/cgi-bin/appchat/send",
+    UPLOAD_MEDIA: "https://qyapi.weixin.qq.com/cgi-bin/media/upload",
+    DOWNLOAD_MEDIA: "https://qyapi.weixin.qq.com/cgi-bin/media/get",
+} as const;
+
+/** 各类限制常量 */
+export const LIMITS = {
+    /** 文本消息最大字节数 */
+    TEXT_MAX_BYTES: 2048,
+    /** Token 刷新缓冲时间 (提前刷新) */
+    TOKEN_REFRESH_BUFFER_MS: 60_000,
+    /** HTTP 请求超时 */
+    REQUEST_TIMEOUT_MS: 15_000,
+    /** 最大请求体大小 */
+    MAX_REQUEST_BODY_SIZE: 1024 * 1024,
+} as const;
+
+/** AES 加密常量 */
+export const CRYPTO = {
+    /** PKCS#7 块大小 */
+    PKCS7_BLOCK_SIZE: 32,
+    /** AES Key 长度 */
+    AES_KEY_LENGTH: 32,
+} as const;

package/src/types/global.d.ts

@@ -0,0 +1,9 @@
+
+declare global {
+    var Buffer: any;
+    namespace NodeJS {
+        interface Timeout { }
+    }
+}
+
+export { };

package/src/types/index.ts

@@ -0,0 +1,38 @@
+/**
+ * WeCom 类型统一导出
+ */
+
+// 常量
+export * from "./constants.js";
+
+// 配置类型
+export type {
+    WecomDmConfig,
+    WecomMediaConfig,
+    WecomNetworkConfig,
+    WecomBotConfig,
+    WecomAgentConfig,
+    WecomConfig,
+} from "./config.js";
+
+// 账号类型
+export type {
+    ResolvedBotAccount,
+    ResolvedAgentAccount,
+    ResolvedMode,
+    ResolvedWecomAccounts,
+} from "./account.js";
+
+// 消息类型
+export type {
+    WecomBotInboundBase,
+    WecomBotInboundText,
+    WecomBotInboundVoice,
+    WecomBotInboundStreamRefresh,
+    WecomBotInboundEvent,
+    WecomBotInboundMessage,
+    WecomAgentInboundMessage,
+    WecomInboundQuote,
+    WecomTemplateCard,
+    WecomOutboundMessage,
+} from "./message.js";

package/src/types/message.ts

@@ -0,0 +1,185 @@
+/**
+ * WeCom 消息类型定义
+ * Bot 和 Agent 模式共用
+ */
+
+/**
+ * Bot 模式入站消息基础结构 (JSON)
+ */
+/**
+ * **WecomBotInboundBase (Bot 入站消息基类)**
+ * 
+ * Bot 模式下 JSON 格式回调的基础字段。
+ * @property msgid 消息 ID
+ * @property aibotid 机器人 ID
+ * @property chattype 会话类型: "single" | "group"
+ * @property chatid 群聊 ID (仅群组时存在)
+ * @property response_url 下行回复 URL (用于被动响应转主动推送)
+ * @property from 发送者信息
+ */
+export type WecomBotInboundBase = {
+    msgid?: string;
+    aibotid?: string;
+    chattype?: "single" | "group";
+    chatid?: string;
+    response_url?: string;
+    from?: { userid?: string; corpid?: string };
+    msgtype?: string;
+    /** 附件数量 (部分消息存在) */
+    attachment_count?: number;
+};
+
+export type WecomBotInboundText = WecomBotInboundBase & {
+    msgtype: "text";
+    text?: { content?: string };
+    quote?: WecomInboundQuote;
+};
+
+export type WecomBotInboundVoice = WecomBotInboundBase & {
+    msgtype: "voice";
+    voice?: { content?: string };
+    quote?: WecomInboundQuote;
+};
+
+export type WecomBotInboundStreamRefresh = WecomBotInboundBase & {
+    msgtype: "stream";
+    stream?: { id?: string };
+};
+
+export type WecomBotInboundEvent = WecomBotInboundBase & {
+    msgtype: "event";
+    create_time?: number;
+    event?: {
+        eventtype?: string;
+        [key: string]: unknown;
+    };
+};
+
+/**
+ * **WecomInboundQuote (引用消息)**
+ * 
+ * 消息中引用的原始内容（如回复某条消息）。
+ * 支持引用文本、图片、混合类型、语音、文件等。
+ */
+export type WecomInboundQuote = {
+    msgtype?: "text" | "image" | "mixed" | "voice" | "file";
+    /** 引用文本内容 */
+    text?: { content?: string };
+    /** 引用图片 URL */
+    image?: { url?: string };
+    /** 引用混合消息 (图文) */
+    mixed?: {
+        msg_item?: Array<{
+            msgtype: "text" | "image";
+            text?: { content?: string };
+            image?: { url?: string };
+        }>;
+    };
+    /** 引用语音 */
+    voice?: { content?: string };
+    /** 引用文件 */
+    file?: { url?: string };
+};
+
+export type WecomBotInboundMessage =
+    | WecomBotInboundText
+    | WecomBotInboundVoice
+    | WecomBotInboundStreamRefresh
+    | WecomBotInboundEvent
+    | (WecomBotInboundBase & { quote?: WecomInboundQuote } & Record<string, unknown>);
+
+/**
+ * Agent 模式入站消息结构 (解析自 XML)
+ */
+/**
+ * **WecomAgentInboundMessage (Agent 入站消息)**
+ * 
+ * Agent 模式下解析自 XML 的扁平化消息结构。
+ * 键名保持 PascalCase (如 `ToUserName`)。
+ */
+export type WecomAgentInboundMessage = {
+    ToUserName?: string;
+    FromUserName?: string;
+    CreateTime?: number;
+    MsgType?: string;
+    MsgId?: string;
+    AgentID?: number;
+    // 文本消息
+    Content?: string;
+    // 图片消息
+    PicUrl?: string;
+    MediaId?: string;
+    // 文件消息
+    FileName?: string;
+    // 语音消息
+    Format?: string;
+    Recognition?: string;
+    // 视频消息
+    ThumbMediaId?: string;
+    // 位置消息
+    Location_X?: number;
+    Location_Y?: number;
+    Scale?: number;
+    Label?: string;
+    // 链接消息
+    Title?: string;
+    Description?: string;
+    Url?: string;
+    // 事件消息
+    Event?: string;
+    EventKey?: string;
+    // 群聊
+    ChatId?: string;
+};
+
+/**
+ * 模板卡片类型
+ */
+/**
+ * **WecomTemplateCard (模板卡片)**
+ * 
+ * 复杂的交互式卡片结构。
+ * @property card_type 卡片类型: "text_notice" | "news_notice" | "button_interaction" ...
+ * @property source 来源信息
+ * @property main_title 主标题
+ * @property sub_title_text 副标题
+ * @property horizontal_content_list 水平排列的键值列表
+ * @property button_list 按钮列表
+ */
+export type WecomTemplateCard = {
+    card_type: "text_notice" | "news_notice" | "button_interaction" | "vote_interaction" | "multiple_interaction";
+    source?: { icon_url?: string; desc?: string; desc_color?: number };
+    main_title?: { title?: string; desc?: string };
+    task_id?: string;
+    button_list?: Array<{ text: string; style?: number; key: string }>;
+    sub_title_text?: string;
+    horizontal_content_list?: Array<{
+        keyname: string;
+        value?: string;
+        type?: number;
+        url?: string;
+        userid?: string;
+    }>;
+    card_action?: { type: number; url?: string; appid?: string; pagepath?: string };
+    action_menu?: { desc: string; action_list: Array<{ text: string; key: string }> };
+    select_list?: Array<{
+        question_key: string;
+        title?: string;
+        selected_id?: string;
+        option_list: Array<{ id: string; text: string }>;
+    }>;
+    submit_button?: { text: string; key: string };
+    checkbox?: {
+        question_key: string;
+        option_list: Array<{ id: string; text: string; is_checked?: boolean }>;
+        mode?: number;
+    };
+};
+
+/**
+ * 出站消息类型
+ */
+export type WecomOutboundMessage =
+    | { msgtype: "text"; text: { content: string } }
+    | { msgtype: "markdown"; markdown: { content: string } }
+    | { msgtype: "template_card"; template_card: WecomTemplateCard };

package/src/types.ts

@@ -0,0 +1,159 @@
+export type WecomDmConfig = {
+  policy?: "pairing" | "allowlist" | "open" | "disabled";
+  allowFrom?: Array<string | number>;
+};
+
+export type WecomAccountConfig = {
+  name?: string;
+  enabled?: boolean;
+
+  webhookPath?: string;
+  token?: string;
+  encodingAESKey?: string;
+  receiveId?: string;
+
+  streamPlaceholderContent?: string;
+
+  dm?: WecomDmConfig;
+  welcomeText?: string;
+};
+
+export type WecomConfig = WecomAccountConfig & {
+  accounts?: Record<string, WecomAccountConfig>;
+  defaultAccount?: string;
+};
+
+export type ResolvedWecomAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  configured: boolean;
+  token?: string;
+  encodingAESKey?: string;
+  receiveId: string;
+  config: WecomAccountConfig;
+};
+
+export type WecomInboundBase = {
+  msgid?: string;
+  aibotid?: string;
+  chattype?: "single" | "group";
+  chatid?: string;
+  response_url?: string;
+  from?: { userid?: string; corpid?: string };
+  msgtype?: string;
+};
+
+export type WecomInboundText = WecomInboundBase & {
+  msgtype: "text";
+  text?: { content?: string };
+  quote?: unknown;
+};
+
+export type WecomInboundVoice = WecomInboundBase & {
+  msgtype: "voice";
+  voice?: { content?: string };
+  quote?: unknown;
+};
+
+export type WecomInboundStreamRefresh = WecomInboundBase & {
+  msgtype: "stream";
+  stream?: { id?: string };
+};
+
+export type WecomInboundEvent = WecomInboundBase & {
+  msgtype: "event";
+  create_time?: number;
+  event?: {
+    eventtype?: string;
+    [key: string]: unknown;
+  };
+};
+
+export type WecomInboundQuote = {
+  msgtype?: "text" | "image" | "mixed" | "voice" | "file";
+  text?: { content?: string };
+  image?: { url?: string };
+  mixed?: {
+    msg_item?: Array<{
+      msgtype: "text" | "image";
+      text?: { content?: string };
+      image?: { url?: string };
+    }>;
+  };
+  voice?: { content?: string };
+  file?: { url?: string };
+};
+
+export type WecomInboundMessage =
+  | (WecomInboundText & { quote?: WecomInboundQuote })
+  | WecomInboundVoice
+  | WecomInboundStreamRefresh
+  | WecomInboundEvent
+  | (WecomInboundBase & { quote?: WecomInboundQuote } & Record<string, unknown>);
+
+export type WecomTemplateCard = {
+  card_type: "text_notice" | "news_notice" | "button_interaction" | "vote_interaction" | "multiple_interaction";
+  source?: { icon_url?: string; desc?: string; desc_color?: number };
+  main_title?: { title?: string; desc?: string };
+  task_id?: string;
+  button_list?: Array<{ text: string; style?: number; key: string }>;
+  sub_title_text?: string;
+  horizontal_content_list?: Array<{ keyname: string; value?: string; type?: number; url?: string; userid?: string }>;
+  card_action?: { type: number; url?: string; appid?: string; pagepath?: string };
+  action_menu?: { desc: string; action_list: Array<{ text: string; key: string }> };
+  select_list?: Array<{
+    question_key: string;
+    title?: string;
+    selected_id?: string;
+    option_list: Array<{ id: string; text: string }>;
+  }>;
+  submit_button?: { text: string; key: string };
+  checkbox?: {
+    question_key: string;
+    option_list: Array<{ id: string; text: string; is_checked?: boolean }>;
+    mode?: number;
+  };
+};
+
+export type WecomInboundTemplateCardEvent = WecomInboundBase & {
+  msgtype: "event";
+  event: {
+    eventtype: "template_card_event";
+    template_card_event: {
+      card_type: string;
+      event_key: string;
+      task_id: string;
+      selected_items?: {
+        selected_item: Array<{
+          question_key: string;
+          option_ids: { option_id: string[] };
+        }>;
+      };
+    };
+  };
+};
+
+
+/**
+ * Template card event payload (button click, checkbox, select)
+ */
+export type WecomTemplateCardEventPayload = {
+  card_type: string;
+  event_key: string;
+  task_id: string;
+  response_code?: string;
+  selected_items?: {
+    question_key?: string;
+    option_ids?: string[];
+  };
+};
+
+/**
+ * Outbound message types that can be sent via response_url
+ */
+export type WecomOutboundMessage =
+  | { msgtype: "text"; text: { content: string } }
+  | { msgtype: "markdown"; markdown: { content: string } }
+  | { msgtype: "template_card"; template_card: WecomTemplateCard };
+