@sunnoy/wecom 2.0.2 → 2.2.0

package/skills/wecom-doc/references/doc-api.md

@@ -0,0 +1,224 @@
+# 企业微信文档 API 参考
+
+## 文档类型
+
+| doc_type | 类型 | doc_id 前缀 | URL 路径 |
+|----------|------|------------|---------|
+| 3 | 文档 | `w3_` | `/doc/` |
+| 10 | 智能表格 | `s3_` | `/smartsheet/` |
+
+## URL 格式
+
+### 文档
+
+```
+https://doc.weixin.qq.com/doc/{doc_id}?scode=xxx
+```
+
+示例：
+```
+https://doc.weixin.qq.com/doc/w3_AMEA4QYkACkCNN7hNRzRzQkaElHbQ?scode=AJEAIQdfAAodYknI73AMEA4QYkACk
+→ doc_id = w3_AMEA4QYkACkCNN7hNRzRzQkaElHbQ
+```
+
+### 智能表格
+
+```
+https://doc.weixin.qq.com/smartsheet/{doc_id}
+```
+
+示例：
+```
+https://doc.weixin.qq.com/smartsheet/s3_ATAA_QaoAKQCNIQ6XYeEYQ3q5Rv05
+→ doc_id = s3_ATAA_QaoAKQCNIQ6XYeEYQ3q5Rv05
+```
+
+> 始终忽略 `?` 之后的查询参数。
+
+## 智能表格字段类型（FieldType）
+
+完整 16 种类型：
+
+| 枚举值 | 说明 |
+|--------|------|
+| `FIELD_TYPE_TEXT` | 文本 |
+| `FIELD_TYPE_NUMBER` | 数字 |
+| `FIELD_TYPE_CHECKBOX` | 复选框 |
+| `FIELD_TYPE_DATE_TIME` | 日期时间 |
+| `FIELD_TYPE_IMAGE` | 图片 |
+| `FIELD_TYPE_USER` | 成员 |
+| `FIELD_TYPE_URL` | 链接 |
+| `FIELD_TYPE_SELECT` | 多选 |
+| `FIELD_TYPE_SINGLE_SELECT` | 单选 |
+| `FIELD_TYPE_PROGRESS` | 进度 |
+| `FIELD_TYPE_PHONE_NUMBER` | 手机号 |
+| `FIELD_TYPE_EMAIL` | 邮箱 |
+| `FIELD_TYPE_LOCATION` | 位置 |
+| `FIELD_TYPE_CURRENCY` | 货币 |
+| `FIELD_TYPE_PERCENTAGE` | 百分比 |
+| `FIELD_TYPE_BARCODE` | 条码 |
+
+## CellValue 类型完整对照
+
+### CellTextValue — 文本字段
+
+```json
+[
+  {"type": "text", "text": "普通文本"},
+  {"type": "url", "text": "链接文本", "link": "https://example.com"}
+]
+```
+
+- `type`（必填）：`"text"` 或 `"url"`
+- `text`（必填）：文本内容
+- `link`（当 type 为 url 时）：链接跳转 URL
+
+适用：`FIELD_TYPE_TEXT`
+
+### 数字类 — number
+
+直接传 number 值。
+
+```json
+85
+```
+
+适用：`FIELD_TYPE_NUMBER`、`FIELD_TYPE_PROGRESS`、`FIELD_TYPE_CURRENCY`、`FIELD_TYPE_PERCENTAGE`
+
+### 布尔值 — boolean
+
+```json
+true
+```
+
+适用：`FIELD_TYPE_CHECKBOX`
+
+### 字符串类 — string
+
+直接传字符串。
+
+适用场景：
+- `FIELD_TYPE_DATE_TIME`：毫秒 unix 时间戳字符串，如 `"1672531200000"`
+- `FIELD_TYPE_PHONE_NUMBER`：手机号字符串，如 `"13800138000"`
+- `FIELD_TYPE_EMAIL`：邮箱字符串，如 `"user@example.com"`
+- `FIELD_TYPE_BARCODE`：条码字符串，如 `"978-3-16-148410-0"`
+
+### CellUrlValue — 链接字段
+
+```json
+[{"type": "url", "text": "显示文本", "link": "https://example.com"}]
+```
+
+- `type`（必填）：固定 `"url"`
+- `link`（必填）：链接跳转 URL
+- `text`（可选）：链接显示文本
+
+> 注意：字段名是 **`link`** 不是 `url`。数组为预留能力，目前只支持 1 个链接。
+
+适用：`FIELD_TYPE_URL`
+
+### CellUserValue — 成员字段
+
+```json
+[{"user_id": "zhangsan"}]
+```
+
+- `user_id`（必填）：成员 ID
+
+适用：`FIELD_TYPE_USER`
+
+### CellImageValue — 图片字段
+
+```json
+[{
+  "id": "img1",
+  "title": "截图",
+  "image_url": "https://...",
+  "width": 800,
+  "height": 600
+}]
+```
+
+- `id`：图片 ID（自定义）
+- `title`：图片标题
+- `image_url`：图片链接（通过上传图片接口获取）
+- `width` / `height`：图片尺寸
+
+适用：`FIELD_TYPE_IMAGE`
+
+### CellAttachmentValue — 文件字段
+
+```json
+[{
+  "name": "文件名",
+  "size": 1024,
+  "file_ext": "DOC",
+  "file_id": "xxx",
+  "file_url": "https://...",
+  "file_type": "50"
+}]
+```
+
+- `file_ext` 取值：`DOC`、`SHEET`、`SLIDE`、`MIND`、`FLOWCHART`、`SMARTSHEET`、`FORM`，或文件扩展名
+- `file_type` 取值：`Folder`（文件夹）、`Wedrive`（微盘文件）、`30`（收集表）、`50`（文档）、`51`（表格）、`52`（幻灯片）、`54`（思维导图）、`55`（流程图）、`70`（智能表）
+
+### Option — 选项（单选/多选字段）
+
+```json
+[{"text": "选项A", "style": 1}, {"text": "选项B", "style": 5}]
+```
+
+- `text`：选项内容。新增选项时填写，已存在时优先匹配
+- `id`（可选）：选项 ID，已存在的选项通过 ID 识别
+- `style`（可选）：选项颜色，1-27
+
+适用：`FIELD_TYPE_SELECT`（多选，可传多个）、`FIELD_TYPE_SINGLE_SELECT`（单选，建议传 1 个）
+
+### CellLocationValue — 位置字段
+
+```json
+[{
+  "source_type": 1,
+  "id": "地点ID",
+  "latitude": "39.9042",
+  "longitude": "116.4074",
+  "title": "北京天安门"
+}]
+```
+
+- `source_type`（必填）：固定 `1`（腾讯地图）
+- `id`（必填）：地点 ID
+- `latitude`（必填）：纬度（字符串）
+- `longitude`（必填）：经度（字符串）
+- `title`（必填）：地点名称
+
+> 数组长度不大于 1。
+
+适用：`FIELD_TYPE_LOCATION`
+
+## 选项样式（Style）
+
+取值 1-27 对应颜色：
+
+| 值 | 颜色 | 值 | 颜色 | 值 | 颜色 |
+|----|------|----|------|----|------|
+| 1 | 浅红 | 10 | 浅蓝 | 19 | 浅橙 |
+| 2 | 浅橙 | 11 | 浅蓝 | 20 | 橙 |
+| 3 | 浅天蓝 | 12 | 蓝 | 21 | 浅黄 |
+| 4 | 浅绿 | 13 | 浅天蓝 | 22 | 浅黄 |
+| 5 | 浅紫 | 14 | 天蓝 | 23 | 黄 |
+| 6 | 浅粉红 | 15 | 浅绿 | 24 | 浅紫 |
+| 7 | 浅灰 | 16 | 绿 | 25 | 紫 |
+| 8 | 白 | 17 | 浅红 | 26 | 浅粉红 |
+| 9 | 灰 | 18 | 红 | 27 | 粉红 |
+
+## 限制
+
+| 维度 | 限制 |
+|------|------|
+| 文档名称 | 最多 255 字符 |
+| 子表字段数 | 单表最多 150 个 |
+| 记录数 | 单表最多 100,000 行 |
+| 单元格数 | 单表最多 15,000,000 个 |
+| 单次添加记录 | 建议 500 行内 |
+| 不可写入字段 | 创建时间、最后编辑时间、创建人、最后编辑人 |

package/wecom/accounts.js

@@ -24,6 +24,7 @@ const RESERVED_KEYS = new Set([
   "webhooks",
   "network",
   "defaultAccount",
+  "deliveryMode",
 ]);
 
 const SHARED_MULTI_ACCOUNT_KEYS = new Set([
@@ -157,6 +158,14 @@ function buildAccount(accountId, config, meta = {}) {
   const configured = Boolean(botId && secret);
   const agentConfigured = Boolean(agent.corpId && agent.corpSecret && agent.agentId);
 
+  const callbackRaw = isPlainObject(agent.callback) ? agent.callback : {};
+  const callbackToken = String(callbackRaw.token ?? "").trim();
+  const callbackAESKey = String(callbackRaw.encodingAESKey ?? "").trim();
+  const callbackPath = String(callbackRaw.path ?? "").trim() || "/api/channels/wecom/callback";
+  const callbackConfigured = Boolean(callbackToken && callbackAESKey && agent.corpId);
+  // "markdown" enables WeCom markdown format for agent API replies; default "markdown"
+  const agentReplyFormat = String(agent.replyFormat ?? "markdown").trim() === "text" ? "text" : "markdown";
+
   return {
     accountId,
     name: String(safeConfig.name ?? accountId ?? DEFAULT_ACCOUNT_ID).trim() || accountId,
@@ -171,7 +180,9 @@ function buildAccount(accountId, config, meta = {}) {
     storageMode: meta.storageMode ?? "dictionary",
     entryKey: meta.entryKey ?? accountId,
     agentConfigured,
+    callbackConfigured,
     webhooksConfigured: isPlainObject(safeConfig.webhooks) && Object.keys(safeConfig.webhooks).length > 0,
+    agentReplyFormat,
     agentCredentials: agentConfigured
       ? {
           corpId: String(agent.corpId),
@@ -179,6 +190,14 @@ function buildAccount(accountId, config, meta = {}) {
           agentId: agent.agentId,
         }
       : null,
+    callbackConfig: callbackConfigured
+      ? {
+          token: callbackToken,
+          encodingAESKey: callbackAESKey,
+          path: callbackPath,
+          corpId: String(agent.corpId),
+        }
+      : null,
   };
 }
 

package/wecom/agent-api.js

@@ -76,7 +76,8 @@ export async function getAccessToken(agent) {
  * @param {string} params.text
  */
 export async function agentSendText(params) {
-  const { agent, toUser, toParty, toTag, chatId, text } = params;
+  const { agent, toUser, toParty, toTag, chatId, text, format = "text" } = params;
+  const msgtype = format === "markdown" ? "markdown" : "text";
   const token = await getAccessToken(agent);
 
   const useChat = Boolean(chatId);
@@ -85,14 +86,14 @@ export async function agentSendText(params) {
     : `${AGENT_API_ENDPOINTS.SEND_MESSAGE}?access_token=${encodeURIComponent(token)}`;
 
   const body = useChat
-    ? { chatid: chatId, msgtype: "text", text: { content: text } }
+    ? { chatid: chatId, msgtype, [msgtype]: { content: text } }
     : {
         touser: toUser,
         toparty: toParty,
         totag: toTag,
-        msgtype: "text",
+        msgtype,
         agentid: agent.agentId,
-        text: { content: text },
+        [msgtype]: { content: text },
       };
 
   const res = await wecomFetch(url, {
@@ -103,7 +104,7 @@ export async function agentSendText(params) {
   const json = await res.json();
 
   if (json?.errcode !== 0) {
-    throw new Error(`agent send text failed: ${json?.errcode} ${json?.errmsg}`);
+    throw new Error(`agent send ${msgtype} failed: ${json?.errcode} ${json?.errmsg}`);
   }
 
   if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
@@ -114,7 +115,7 @@ export async function agentSendText(params) {
     ]
       .filter(Boolean)
       .join(", ");
-    throw new Error(`agent send text partial failure: ${details}`);
+    throw new Error(`agent send ${msgtype} partial failure: ${details}`);
   }
 }
 

package/wecom/callback-crypto.js

@@ -0,0 +1,80 @@
+/**
+ * WeCom self-built app callback cryptography utilities.
+ *
+ * Implements the signature verification and AES-256-CBC decryption required
+ * by the WeCom callback protocol:
+ *   https://developer.work.weixin.qq.com/document/path/90239
+ */
+
+import crypto from "node:crypto";
+
+/**
+ * Verify a WeCom callback request signature.
+ *
+ * Signature algorithm:
+ *   SHA1( sort([token, timestamp, nonce, msgEncrypt]).join("") )
+ * The result must equal the `msg_signature` query parameter.
+ *
+ * @param {object} params
+ * @param {string} params.token          - Callback token from account config
+ * @param {string} params.timestamp      - `timestamp` query parameter
+ * @param {string} params.nonce          - `nonce` query parameter
+ * @param {string} params.msgEncrypt     - The ciphertext extracted from the XML body
+ * @param {string} params.signature      - `msg_signature` query parameter to verify against
+ * @returns {boolean}
+ */
+export function verifyCallbackSignature({ token, timestamp, nonce, msgEncrypt, signature }) {
+  const items = [String(token), String(timestamp), String(nonce), String(msgEncrypt)].sort();
+  const digest = crypto.createHash("sha1").update(items.join("")).digest("hex");
+  return digest === String(signature);
+}
+
+/**
+ * Decrypt a WeCom AES-256-CBC encrypted callback message.
+ *
+ * Key derivation:
+ *   key = Base64Decode(encodingAESKey + "=")  → 32 bytes
+ *   iv  = key.slice(0, 16)
+ *
+ * Plaintext layout (after PKCS7 unpad):
+ *   [ 16 random bytes | 4-byte msgLen (big-endian) | msgXml | corpId ]
+ *
+ * @param {object} params
+ * @param {string} params.encodingAESKey - 43-char key from WeCom config
+ * @param {string} params.encrypted      - Base64-encoded ciphertext
+ * @returns {{ xml: string, corpId: string }}
+ */
+export function decryptCallbackMessage({ encodingAESKey, encrypted }) {
+  const key = Buffer.from(encodingAESKey + "=", "base64"); // 32 bytes
+  const iv = key.subarray(0, 16);
+  const ciphertext = Buffer.from(encrypted, "base64");
+
+  const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
+  decipher.setAutoPadding(false);
+  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+
+  // Strip PKCS7 padding
+  const padLen = decrypted[decrypted.length - 1];
+  if (padLen < 1 || padLen > 32) {
+    throw new Error(`Invalid PKCS7 padding byte: ${padLen}`);
+  }
+  const content = decrypted.subarray(0, decrypted.length - padLen);
+
+  // Strip 16-byte random prefix
+  const withoutRandom = content.subarray(16);
+
+  // Read 4-byte big-endian message length
+  if (withoutRandom.length < 4) {
+    throw new Error("Decrypted content too short");
+  }
+  const msgLen = withoutRandom.readUInt32BE(0);
+
+  if (withoutRandom.length < 4 + msgLen) {
+    throw new Error(`Decrypted content shorter than declared msgLen (${msgLen})`);
+  }
+
+  const xml = withoutRandom.subarray(4, 4 + msgLen).toString("utf8");
+  const corpId = withoutRandom.subarray(4 + msgLen).toString("utf8");
+
+  return { xml, corpId };
+}