wechaty-puppet-matrix 0.0.54 → 0.0.56

package/src/matrix/service/request.ts

@@ -275,6 +275,7 @@ export interface MessagePayload {
   atWxidList?: string[]; // 消息中艾特人wxid列表
   msg: string; // 消息内容
   listenerId: string; //
+  clientMsgId?: number; // 发送接口返回的 client_msg_id，撤回时需要
 }
 
 export interface BaseEvent {
@@ -285,12 +286,29 @@ export interface BaseEvent {
   robotInfo?: ContactPayload;
 }
 
+export interface CdnDownloadCandidate {
+  file_id: string;
+  file_size: string | number;
+  /** 与默认 aes_key 不同时才需要，例如原始视频 cdnrawvideoaeskey */
+  aes_key?: string;
+}
+
 export interface ImageMessagePayload {
   aes_key: string;
   auth_key: string;
   file_id: string;
   file_size?: string | number;
   file_name?: string;
+  /** 图片下载的候选 (file_id, file_size)，按顺序回落 */
+  candidates?: CdnDownloadCandidate[];
+}
+
+/**
+ * 解析后端 "download plaintext size differs: expected X, got Y"，返回实际大小 Y
+ */
+export function parseSizeMismatch (errmsg?: string): string | undefined {
+  const match = typeof errmsg === 'string' ? errmsg.match(/size differs: expected \d+, got (\d+)/) : null
+  return match && Number(match[1]) > 0 ? match[1] : undefined
 }
 
 export interface SnsImageMessagePayload {
@@ -336,6 +354,7 @@ export interface VideoMessagePayload {
   thumb_width: string;
   thumb_height: string;
   file_name: '';
+  candidates?: CdnDownloadCandidate[];
 }
 
 export enum FriendshipType {
@@ -669,6 +688,14 @@ export interface MomentInfo {
     parentId: string
 }
 
+/** 从发送接口响应中取 client_msg_id（撤回消息需要） */
+function pickClientMsgId (res: any): number | undefined {
+  const item = res?.list?.[0] || res
+  const v = item?.clientMsgId ?? item?.client_msg_id ?? item?.clientMsgid
+  const n = typeof v === 'string' ? parseInt(v, 10) : v
+  return typeof n === 'number' && !isNaN(n) ? n : undefined
+}
+
 class Client extends EventEmitter {
 
   private readonly options: PuppetMatrixOptions
@@ -1849,6 +1876,7 @@ class Client extends EventEmitter {
 
       return {
         id: res?.list?.[0].newMsgId || '',
+        clientMsgId: pickClientMsgId(res),
         timeStamp: res?.list?.[0].createTime || '',
         msgType: res?.list?.[0].type || '',
         talkerId: selfId || '',
@@ -1889,6 +1917,7 @@ class Client extends EventEmitter {
 
       return {
         id: res?.list?.[0].newMsgId || '',
+        clientMsgId: pickClientMsgId(res),
         timeStamp: res?.list?.[0].createTime || '',
         msgType: res?.list?.[0].type || '',
         talkerId: selfId || '',
@@ -1917,8 +1946,7 @@ class Client extends EventEmitter {
     })
   }
 
-  private async retryDownload (fn: () => Promise<any>): Promise<any> {
-    const maxRetries = 5
+  private async retryDownload (fn: () => Promise<any>, maxRetries = 5): Promise<any> {
     const delayMs = 5000
     for (let attempt = 1; attempt <= maxRetries; attempt++) {
       try {
@@ -1927,6 +1955,10 @@ class Client extends EventEmitter {
           return res
         }
         log.warn(PRE, 'download attempt %d/%d failed (no url in response): %s', attempt, maxRetries, JSON.stringify(res))
+        // size 不匹配是确定性错误，重试同一个 size 没有意义，交给调用方换 size
+        if (parseSizeMismatch(res?.errmsg)) {
+          return res
+        }
       } catch (e) {
         log.warn(PRE, 'download attempt %d/%d error: %s', attempt, maxRetries, e)
       }
@@ -1937,21 +1969,66 @@ class Client extends EventEmitter {
     return null
   }
 
+  /**
+   * 按候选 (file_id, file_size) 依次下载 CDN 文件。
+   * - 后端返回 "plaintext size differs: expected X, got Y" 时立即用 Y 重试同一个 file_id
+   * - 其它失败按 retriesPerCandidate 重试后回落到下一个候选
+   */
+  private async cdnDownloadWithFallback (
+    label: string,
+    baseParams: Record<string, any>,
+    candidates: CdnDownloadCandidate[],
+  ): Promise<string> {
+    const queue = [ ...candidates ]
+    const tried = new Set<string>()
+    // 只有一个候选时保持原来的 5 次重试；有多个候选时每个只试 2 次就回落
+    const retriesPerCandidate = candidates.length > 1 ? 2 : 5
+
+    while (queue.length) {
+      const candidate = queue.shift()!
+      const key = `${candidate.file_id}|${candidate.file_size}|${candidate.aes_key || ''}`
+      if (!candidate.file_id || tried.has(key)) {
+        continue
+      }
+      tried.add(key)
+
+      const params = {
+        ...baseParams,
+        file_id: candidate.file_id,
+        file_size: candidate.file_size,
+        ...(candidate.aes_key ? { aes_key: candidate.aes_key } : {}),
+      }
+      const res = await this.retryDownload(() => this.postData({ path: '/cloud/cdn_download', data: params }), retriesPerCandidate)
+      if (res?.url) {
+        if (tried.size > 1) {
+          log.info(PRE, '%s succeeded with fallback, file_size: %s', label, candidate.file_size)
+        }
+        return encodeURI(res.url) || ''
+      }
+
+      const actualSize = parseSizeMismatch(res?.errmsg)
+      if (actualSize) {
+        log.warn(PRE, '%s size mismatch (xml %s, actual %s), retry with actual size', label, candidate.file_size, actualSize)
+        queue.unshift({ ...candidate, file_size: actualSize })
+        continue
+      }
+      log.warn(PRE, '%s candidate failed, params: %s', label, JSON.stringify(params))
+    }
+
+    log.error(PRE, '%s failed for all candidates: %s', label, JSON.stringify(candidates))
+    return ''
+  }
+
   public async downloadImage (imageInfo: ImageMessagePayload): Promise<any> {
-    const params = {
+    const candidates = imageInfo.candidates?.length
+      ? imageInfo.candidates
+      : [ { file_id: imageInfo.file_id, file_size: imageInfo.file_size || '' } ]
+    return this.cdnDownloadWithFallback('downloadImage', {
       log_response: true,
       file_type: 2,
-      file_id: imageInfo.file_id,
       aes_key: imageInfo.aes_key,
-      file_size: imageInfo.file_size,
       file_name: `/微信图片_${format(new Date(), 'yyyyMMddHHmmss')}.png`,
-    }
-    const res = await this.retryDownload(() => this.postData({ path: '/cloud/cdn_download', data: params }))
-    if (res?.url) {
-      return encodeURI(res.url) || ''
-    }
-    log.error(PRE, 'downloadImage failed after %d retries, params: %s', 5, JSON.stringify(params))
-    return ''
+    }, candidates)
   }
 
   public async downloadWWMedia (imageInfo: ImageMessagePayload, type: number): Promise<any> {
@@ -1981,20 +2058,12 @@ class Client extends EventEmitter {
    * @param imageInfo
    */
   public async downloadFile (imageInfo: ImageMessagePayload): Promise<any> {
-    const params = {
+    return this.cdnDownloadWithFallback('downloadFile', {
       log_response: true,
       file_type: 5,
-      file_id: imageInfo.file_id.replace('@cdn_', ''),
       aes_key: imageInfo.aes_key,
-      file_size: imageInfo.file_size,
       file_name: '/' + sanitizeFilename(imageInfo.file_name),
-    }
-    const res = await this.retryDownload(() => this.postData({ path: '/cloud/cdn_download', data: params }))
-    if (res?.url) {
-      return encodeURI(res.url) || ''
-    }
-    log.error(PRE, 'downloadFile failed after %d retries, params: %s', 5, JSON.stringify(params))
-    return ''
+    }, [ { file_id: imageInfo.file_id.replace('@cdn_', ''), file_size: imageInfo.file_size || '' } ])
   }
 
   /**
@@ -2100,19 +2169,14 @@ class Client extends EventEmitter {
    * @param imageInfo
    */
   public async downloadVideo (videoInfo: VideoMessagePayload): Promise<any> {
-    const params = {
+    const candidates = videoInfo.candidates?.length
+      ? videoInfo.candidates
+      : [ { file_id: videoInfo.file_id, file_size: videoInfo.file_size } ]
+    return this.cdnDownloadWithFallback('downloadVideo', {
       file_type: 4,
-      file_id: videoInfo.file_id,
       aes_key: videoInfo.aes_key,
-      file_size: videoInfo.file_size,
       file_name: `/微信视频_${format(new Date(), 'yyyyMMddHHmmss')}.mp4`,
-    }
-    const res = await this.retryDownload(() => this.postData({ path: '/cloud/cdn_download', data: params }))
-    if (res?.url) {
-      return encodeURI(res.url) || ''
-    }
-    log.error(PRE, 'downloadVideo failed after %d retries, params: %s', 5, JSON.stringify(params))
-    return ''
+    }, candidates)
   }
 
   /**
@@ -2144,6 +2208,7 @@ class Client extends EventEmitter {
       })
       return {
         id: res?.newMsgId || '',
+        clientMsgId: pickClientMsgId(res),
         timeStamp: res?.createTime || '',
         msgType: WechatMessageType.Image,
         talkerId: selfId || '',
@@ -2187,6 +2252,7 @@ class Client extends EventEmitter {
 
       return {
         id: res?.newMsgId || '',
+        clientMsgId: pickClientMsgId(res),
         timeStamp: res?.createTime || getUnixTime(new Date()),
         msgType: WechatMessageType.Video,
         talkerId: selfId || '',
@@ -2227,6 +2293,7 @@ class Client extends EventEmitter {
       })
       return {
         id: res?.newMsgId || '',
+        clientMsgId: pickClientMsgId(res),
         timeStamp: res?.createTime || '',
         msgType: WechatMessageType.File,
         talkerId: selfId || '',
@@ -2277,6 +2344,7 @@ class Client extends EventEmitter {
       })
       return {
         id: res?.newMsgId || '',
+        clientMsgId: pickClientMsgId(res),
         timeStamp: res?.createTime || '',
         msgType: WechatMessageType.Text,
         talkerId: selfId || '',
@@ -2336,6 +2404,7 @@ class Client extends EventEmitter {
 
       return {
         id: res?.newMsgId || '',
+        clientMsgId: pickClientMsgId(res),
         timeStamp: res?.createTime || '',
         msgType: WechatMessageType.MiniProgram,
         talkerId: selfId || '',
@@ -2375,6 +2444,7 @@ class Client extends EventEmitter {
 
       return {
         id: res?.newMsgId || '',
+        clientMsgId: pickClientMsgId(res),
         timeStamp: res?.createTime || '',
         msgType: WechatMessageType.App,
         talkerId: selfId || '',
@@ -2616,6 +2686,7 @@ class Client extends EventEmitter {
       })
       return {
         id: res?.newMsgId || '',
+        clientMsgId: pickClientMsgId(res),
         timeStamp: res?.createTime || '',
         msgType: WechatMessageType.App,
         talkerId: selfId || '',
@@ -2629,6 +2700,177 @@ class Client extends EventEmitter {
     }
   }
 
+  /**
+   * 发送名片（无需 xml）
+   * @param toId 接收人/群 id
+   * @param shareId 被分享的联系人 wxid
+   * @param shareNickname 被分享人昵称
+   * @param shareHeadImg 被分享人头像
+   */
+  public async sendContact (
+    {
+      toId,
+      shareId,
+      shareNickname,
+      shareHeadImg,
+    }: {
+      toId: string;
+      shareId: string;
+      shareNickname?: string;
+      shareHeadImg?: string;
+    },
+    selfId: string | undefined,
+  ): Promise<MessagePayload | void> {
+    try {
+      const res = await this.postData({
+        path: '/msg/send_share_card',
+        data: {
+          to_username: toId,
+          share_username: shareId,
+          share_nickname: shareNickname || '',
+          share_head_img: shareHeadImg || '',
+        },
+      })
+      return {
+        id: res?.newMsgId || '',
+        clientMsgId: pickClientMsgId(res),
+        timeStamp: res?.createTime || '',
+        msgType: WechatMessageType.ShareCard,
+        talkerId: selfId || '',
+        text: shareId,
+        msg: shareId,
+        fromWxid: isRoomId(toId) ? toId : '',
+        listenerId: toId,
+      }
+    } catch (error) {
+      log.error(PRE, 'sendContact(%s, %s): %s', toId, shareId, error)
+    }
+  }
+
+  /**
+   * 通过 md5 发送表情（微信服务器已有该表情时可直接发送）
+   */
+  public async sendEmojiMd5 (
+    toId: string,
+    md5: string,
+    size: number,
+    selfId: string | undefined,
+  ): Promise<MessagePayload | void> {
+    try {
+      const res = await this.postData({
+        path: '/msg/send_emoji_md5',
+        data: {
+          to_username: toId,
+          file_md5: md5,
+          file_size: size,
+        },
+      })
+      log.verbose(PRE, 'sendEmojiMd5 res: %s', JSON.stringify(res))
+      return this.emojiResult(res, toId, md5, selfId)
+    } catch (error) {
+      log.error(PRE, 'sendEmojiMd5(%s, %s): %s', toId, md5, error)
+    }
+  }
+
+  /**
+   * 通过图片 url 发送表情
+   */
+  public async sendEmojiUrl (
+    toId: string,
+    url: string,
+    selfId: string | undefined,
+  ): Promise<MessagePayload | void> {
+    try {
+      const res = await this.postData({
+        path: '/msg/send_emoji_url',
+        data: {
+          to_username: toId,
+          url,
+        },
+      })
+      log.verbose(PRE, 'sendEmojiUrl res: %s', JSON.stringify(res))
+      return this.emojiResult(res, toId, url, selfId)
+    } catch (error) {
+      log.error(PRE, 'sendEmojiUrl(%s, %s): %s', toId, url, error)
+    }
+  }
+
+  private emojiResult (res: any, toId: string, text: string, selfId: string | undefined): MessagePayload | void {
+    // 返回格式: { baseResponse, emojiItem: [{ ret, msgId, newMsgId, md5, totalLen }] }
+    const item = res?.emojiItem?.[0] || res?.list?.[0] || res
+    const id = item?.newMsgId || item?.msgId
+    if (!id || (item?.ret !== undefined && item.ret !== 0)) {
+      log.warn(PRE, 'send emoji failed: %s', JSON.stringify(res))
+      return
+    }
+    return {
+      clientMsgId: pickClientMsgId(item),
+      fromWxid: isRoomId(toId) ? toId : '',
+      id: String(id),
+      listenerId: toId,
+      msg: text,
+      msgType: WechatMessageType.Emoticon,
+      talkerId: selfId || '',
+      text,
+      timeStamp: item?.createTime || '',
+    }
+  }
+
+  /**
+   * 拍一拍
+   * @param toId 会话 id（私聊为好友 wxid，群聊为群 id）
+   * @param pattedId 被拍的人 wxid
+   */
+  public async sendPat (toId: string, pattedId: string): Promise<boolean> {
+    try {
+      const res = await this.postData({
+        path: '/msg/send_pat',
+        data: {
+          to_username: toId,
+          patted_username: pattedId,
+        },
+      })
+      log.verbose(PRE, 'sendPat res: %s', JSON.stringify(res))
+      if (!res || res.errcode || (res.baseResponse?.ret !== undefined && res.baseResponse.ret !== 0)) {
+        log.warn(PRE, 'sendPat(%s, %s) failed: %s', toId, pattedId, JSON.stringify(res))
+        return false
+      }
+      return true
+    } catch (error) {
+      log.error(PRE, 'sendPat(%s, %s): %s', toId, pattedId, error)
+      return false
+    }
+  }
+
+  /**
+   * 撤回消息
+   * @param toId 消息所在会话（好友 wxid / 群 id）
+   * @param msgId 发送返回的 newMsgId
+   * @param clientMsgId 发送返回的 client_msg_id
+   */
+  public async revokeMsg (toId: string, msgId: string, clientMsgId: number | undefined): Promise<boolean> {
+    try {
+      const res = await this.postData({
+        path: '/msg/revoke_msg',
+        data: {
+          to_username: toId,
+          msg_id: msgId,
+          client_msg_id: clientMsgId || 0,
+        },
+      })
+      log.verbose(PRE, 'revokeMsg res: %s', JSON.stringify(res))
+      const ret = res?.baseResponse?.ret
+      if (ret !== undefined && ret !== 0) {
+        log.warn(PRE, 'revokeMsg(%s, %s) failed: %s', toId, msgId, JSON.stringify(res?.baseResponse))
+        return false
+      }
+      return !!res
+    } catch (error) {
+      log.error(PRE, 'revokeMsg(%s, %s): %s', toId, msgId, error)
+      return false
+    }
+  }
+
   /**
    * 发送群公告
    * @param roomId 群id

package/src/matrix/utils/file-type.spec.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env -S node -r ts-node/register
+import { test } from 'tstest'
+
+import { detectImageExt, replaceExt } from './file-type.js'
+
+const hex = (s: string) => Buffer.from(s, 'hex')
+
+test('detectImageExt recognizes common image headers', async t => {
+  // 实测微信图片下载结果的文件头
+  t.equal(detectImageExt(hex('ffd8fffe00104c61766335392e33372e')), 'jpg', 'jpeg')
+  t.equal(detectImageExt(hex('89504e470d0a1a0a0000000d49484452')), 'png', 'png')
+  t.equal(detectImageExt(Buffer.from('GIF89a......')), 'gif', 'gif')
+  t.equal(detectImageExt(Buffer.concat([ Buffer.from('RIFF'), hex('00000000'), Buffer.from('WEBPVP8 ') ])), 'webp', 'webp')
+  t.equal(detectImageExt(hex('424d000000000000')), 'bmp', 'bmp')
+  t.equal(detectImageExt(Buffer.concat([ hex('00000018'), Buffer.from('ftypheic'), hex('00000000') ])), 'heic', 'heic')
+  t.equal(detectImageExt(Buffer.concat([ hex('0000001c'), Buffer.from('ftypavif'), hex('00000000') ])), 'avif', 'avif')
+})
+
+test('detectImageExt returns undefined for unknown or short data', async t => {
+  t.equal(detectImageExt(hex('0000001c667479706d703432')), undefined, 'mp4 is not an image')
+  t.equal(detectImageExt(Buffer.from('<html>')), undefined, 'html')
+  t.equal(detectImageExt(Buffer.alloc(0)), undefined, 'empty')
+})
+
+test('replaceExt replaces or appends extension', async t => {
+  t.equal(replaceExt('微信图片_20261105234022.png', 'jpg'), '微信图片_20261105234022.jpg', 'replace')
+  t.equal(replaceExt('image', 'gif'), 'image.gif', 'append')
+  t.equal(replaceExt('.hidden', 'jpg'), '.hidden.jpg', 'dotfile')
+})

package/src/matrix/utils/file-type.ts

@@ -0,0 +1,59 @@
+import axios from 'axios'
+
+/**
+ * 根据文件头 (magic bytes) 判断图片扩展名，无法识别时返回 undefined
+ */
+export function detectImageExt (head: Buffer): string | undefined {
+  if (head.length >= 3 && head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff) {
+    return 'jpg'
+  }
+  if (head.length >= 8 && head.subarray(0, 8).equals(Buffer.from([ 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a ]))) {
+    return 'png'
+  }
+  if (head.length >= 6 && [ 'GIF87a', 'GIF89a' ].includes(head.subarray(0, 6).toString('ascii'))) {
+    return 'gif'
+  }
+  if (head.length >= 12 && head.subarray(0, 4).toString('ascii') === 'RIFF' && head.subarray(8, 12).toString('ascii') === 'WEBP') {
+    return 'webp'
+  }
+  if (head.length >= 2 && head[0] === 0x42 && head[1] === 0x4d) {
+    return 'bmp'
+  }
+  if (head.length >= 12 && head.subarray(4, 8).toString('ascii') === 'ftyp') {
+    const brand = head.subarray(8, 12).toString('ascii')
+    if ([ 'heic', 'heix', 'hevc', 'hevx', 'mif1', 'msf1' ].includes(brand)) {
+      return 'heic'
+    }
+    if ([ 'avif', 'avis' ].includes(brand)) {
+      return 'avif'
+    }
+  }
+  return undefined
+}
+
+/**
+ * 用 Range 请求读取远程文件开头若干字节，失败返回 undefined
+ */
+export async function fetchRemoteHead (url: string, bytes = 32, timeoutMs = 5000): Promise<Buffer | undefined> {
+  try {
+    const res = await axios.get<ArrayBuffer>(url, {
+      headers: { Range: `bytes=0-${bytes - 1}` },
+      responseType: 'arraybuffer',
+      timeout: timeoutMs,
+      // 服务端不支持 Range 时会返回整个文件，限制最大读取量
+      maxContentLength: 50 * 1024 * 1024,
+    })
+    return Buffer.from(res.data).subarray(0, bytes)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 把文件名的扩展名替换成 ext
+ */
+export function replaceExt (fileName: string, ext: string): string {
+  const dot = fileName.lastIndexOf('.')
+  const base = dot > 0 ? fileName.slice(0, dot) : fileName
+  return `${base}.${ext}`
+}