chatboty 0.1.0 → 0.2.0

package/src/entity/friendship.ts

@@ -1,7 +1,12 @@
 import type { BotApi, FriendshipPayload, FriendshipKind } from '../types.js'
 import { Contact } from './contact.js'
 
-/** 好友关系事件实体。 */
+/**
+ * 好友关系事件实体。
+ *
+ * 【同步 vs 异步约定】本实体全部数据来自事件 payload, 故 kind()/hello()/contact() 均为同步。
+ * (Friendship 无自身 id; 相关联系人 id 见 contact().id。)
+ */
 export class Friendship {
   constructor (private readonly bot: BotApi, readonly payload: FriendshipPayload) {}
 

package/src/entity/message.ts

@@ -1,18 +1,33 @@
-import type { BotApi, MessagePayload, Sayable, FileBox } from '../types.js'
+import type { BotApi, MessagePayload, Sayable } from '../types.js'
 import { MessageType } from '../types.js'
 import { Contact } from './contact.js'
 import { Room } from './room.js'
-
-/** 消息实体。 */
+import { ReceivedFile } from './received-file.js'
+
+/**
+ * 消息实体。
+ *
+ * 【同步 vs 异步约定】实体已持有的数据(来自事件 payload / 缓存)用【同步】方法直接读取;
+ * 任何需要回连接器/企微(下载、拉通讯录、发送)的操作一律 async。
+ *   - 同步(缓存): id / type() / text() / self() / talker() / room() / mentionSelf() / timestamp()
+ *   - 异步(round-trip/动作): say() / toFileBox() / download() / mentionList()
+ */
 export class Message {
-  constructor (private readonly bot: BotApi, readonly payload: MessagePayload) {}
+  /** 消息 id(来自事件 payload; 同步只读属性)。未知时为空串。 */
+  readonly id: string
+
+  constructor (private readonly bot: BotApi, readonly payload: MessagePayload) {
+    this.id = payload.id ?? ''
+  }
 
-  id (): string | undefined { return this.payload.id }
   type (): MessageType { return this.payload.type }
   text (): string { return this.payload.text ?? '' }
   self (): boolean { return !!this.payload.self }
   timestamp (): number | undefined { return this.payload.timestamp }
-  file (): FileBox | null | undefined { return this.payload.file }
+  /** 随事件附带的媒体(若探针已下载); 无则 undefined。取字节请用 {@link toFileBox}。 */
+  file (): ReceivedFile | null | undefined {
+    return this.payload.file ? new ReceivedFile(this.payload.file) : this.payload.file
+  }
   miniProgram (): Record<string, any> | null | undefined { return this.payload.miniProgram }
   urlLink (): Record<string, any> | null | undefined { return this.payload.urlLink }
 
@@ -57,7 +72,7 @@ export class Message {
   /**
    * 消息中被 @ 的联系人列表(best-effort)。
    * 先从正文解析出 @显示名, 再用一次 contactList 拉全量通讯录按 name/alias 就近解析成完整 Contact;
-   * 未在已加载通讯录中的成员回退为仅含名字的 Contact(其 id() 为空串)。
+   * 未在已加载通讯录中的成员回退为仅含名字的 Contact(其 id 为空串)。
    * @returns 被 @ 的 Contact 数组(无 @ 时为空数组)。
    */
   async mentionList (): Promise<Contact[]> {
@@ -95,27 +110,28 @@ export class Message {
 
   /* ---------------- 媒体下载 ---------------- */
 
-  private toFileBoxFromResult (r: any): FileBox | null {
+  private toFileFromResult (r: any): ReceivedFile | null {
     if (!r) return null
     const dataUrl = r.dataUrl || r.base64
     if (!dataUrl) return null
-    return { dataUrl, mime: r.mime, name: r.name, size: r.size }
+    return new ReceivedFile({ dataUrl, mime: r.mime, name: r.name, size: r.size })
   }
 
   /**
-   * 取本条消息的媒体/文件字节(图片/文件/音视频), 返回 {@link FileBox}(含 base64 data URL)。
+   * 取本条消息的媒体/文件字节(图片/文件/音视频), 返回 {@link ReceivedFile}(含 base64 data URL,
+   * 并带 toBuffer()/save() 便捷方法)。
    * - 收到的图片/文件事件通常已附带 file(探针后台已下载解密) → 直接返回。
    * - 否则按类型冷调探针下载: 图片走 downloadImage, 文件/音视频走 downloadFile(按 msgid+会话+文件名定位缓存)。
-   * @returns FileBox(dataUrl/mime/name/size); 非媒体消息或下载失败返回 null。
+   * @returns ReceivedFile; 非媒体消息或下载失败返回 null。
    */
-  async toFileBox (): Promise<FileBox | null> {
-    if (this.payload.file) return this.payload.file
+  async toFileBox (): Promise<ReceivedFile | null> {
+    if (this.payload.file) return new ReceivedFile(this.payload.file)
     const msgid = this.payload.id
     if (!msgid) return null
     const t = this.payload.type
     if (t === MessageType.Image) {
       const r = await this.bot.command('downloadImage', { msgid })
-      return this.toFileBoxFromResult(r)
+      return this.toFileFromResult(r)
     }
     if (t === MessageType.File || t === MessageType.Video || t === MessageType.Audio) {
       const r = await this.bot.command('downloadFile', {
@@ -124,24 +140,13 @@ export class Message {
         timestamp: this.payload.timestamp,
         name: this.payload.text,
       })
-      return this.toFileBoxFromResult(r)
+      return this.toFileFromResult(r)
     }
     return null
   }
 
   /** {@link toFileBox} 的别名(下载本条消息的媒体字节)。 */
-  async download (): Promise<FileBox | null> { return this.toFileBox() }
-
-  /* ---------------- 转发(RE 待定) ---------------- */
-
-  /**
-   * 转发本条消息到另一会话(群/单聊 conversationId, 或 Room/Contact)。
-   * ⚠️ 未实现: 企微转发需逆向定位并冷调"转发消息"服务(见 puppet-wework 交付说明的 RE 计划)。
-   * 当前会抛错, 以免静默失败。
-   */
-  async forward (_to: string | Room | Contact): Promise<never> {
-    throw new Error('Message.forward 未实现: 需逆向定位企微转发消息服务(ForwardMessage), 见 RE 计划')
-  }
+  async download (): Promise<ReceivedFile | null> { return this.toFileBox() }
 
   toString (): string { return `Message<${MessageType[this.type()]}:${this.text().slice(0, 30)}>` }
 }

package/src/entity/received-file.ts

@@ -0,0 +1,44 @@
+import { writeFile } from 'node:fs/promises'
+import type { FileBox } from '../types.js'
+
+/**
+ * 收到的媒体/文件(图片/文件/音视频)。自包含, 零外部依赖。
+ *
+ * 除原始字段(dataUrl/mime/name/size)外, 额外提供便捷方法:
+ *   - toBuffer(): 同步, 把 dataUrl/base64 解码成原始字节(Buffer)。
+ *   - save(path): 异步, 把字节写到磁盘。
+ */
+export class ReceivedFile {
+  /** base64 data URL(形如 `data:<mime>;base64,<...>`)。 */
+  readonly dataUrl?: string
+  /** MIME 类型(如 image/png)。 */
+  readonly mime?: string
+  /** 文件名(若探针可解析)。 */
+  readonly name?: string
+  /** 字节数(若已知)。 */
+  readonly size?: number
+
+  constructor (init: FileBox) {
+    this.dataUrl = init.dataUrl
+    this.mime = init.mime
+    this.name = init.name
+    this.size = init.size
+  }
+
+  /** 解出原始字节(从 dataUrl / 裸 base64 解码)。同步。 */
+  toBuffer (): Buffer {
+    const s = this.dataUrl ?? ''
+    const comma = s.indexOf(',')
+    const b64 = s.startsWith('data:') && comma >= 0 ? s.slice(comma + 1) : s
+    return Buffer.from(b64, 'base64')
+  }
+
+  /** 写盘到指定路径(需 round-trip 到磁盘, 故为 async)。 */
+  async save (path: string): Promise<void> {
+    // 用 Uint8Array 包一层: 新版 @types/node 的 writeFile 形参要求 Uint8Array<ArrayBuffer>,
+    // 而 Buffer 的底层可能是 SharedArrayBuffer(方差不兼容); 复制成纯 ArrayBuffer 视图即可。
+    await writeFile(path, new Uint8Array(this.toBuffer()))
+  }
+
+  toString (): string { return `ReceivedFile<${this.name ?? this.mime ?? 'unknown'}>` }
+}

package/src/entity/room.ts

@@ -1,25 +1,43 @@
 import type { BotApi, RoomPayload, Sayable } from '../types.js'
 import { Contact } from './contact.js'
 
-/** 群实体。 */
+/**
+ * 群实体。
+ *
+ * 【同步 vs 异步约定】实体已持有的数据(来自事件 payload / 缓存)用【同步】读取;
+ * 需要回连接器/企微(拉成员、改名、发送)的操作一律 async。
+ *   - 同步(缓存): id / topic() / owner()
+ *   - 异步(round-trip/动作): say() / rename() / memberAll()
+ */
 export class Room {
-  constructor (private readonly bot: BotApi, readonly payload: RoomPayload) {}
+  /** 群 id(R:..; 同步只读属性)。 */
+  readonly id: string
+
+  constructor (private readonly bot: BotApi, readonly payload: RoomPayload) {
+    this.id = payload.id
+  }
 
-  id (): string { return this.payload.id }
   topic (): string | undefined { return this.payload.topic }
-  ownerId (): string | undefined { return this.payload.ownerId }
 
-  /** 群发消息。 */
+  /**
+   * 群主(同步; 由缓存的 ownerId 构造)。
+   * 事件/列表未携带 ownerId 时返回 undefined; 需完整群主资料请用 {@link memberAll} 定位。
+   */
+  owner (): Contact | undefined {
+    return this.payload.ownerId ? new Contact(this.bot, { id: this.payload.ownerId }) : undefined
+  }
+
+  /** 群发消息(动作)。 */
   async say (sayable: Sayable): Promise<any> {
     return this.bot.sayTo(this.payload.id, sayable)
   }
 
-  /** 改群名(冷改, 内外群通用)。 */
+  /** 改群名(冷改, 内外群通用; round-trip)。 */
   async rename (topic: string): Promise<any> {
     return this.bot.command('roomTopic', { conversationId: this.payload.id, topic })
   }
 
-  /** 群成员(完整 Contact 对象; 受探针成员枚举局限)。 */
+  /** 群成员(完整 Contact 对象; 受探针成员枚举局限; round-trip)。 */
   async memberAll (): Promise<Contact[]> {
     const r = await this.bot.command('roomMembers', { conversationId: this.payload.id })
     const list = (r && (r.memberList || [])) as any[]
@@ -30,13 +48,5 @@ export class Room {
     }))
   }
 
-  /** 群主(若可解析)。 */
-  async owner (): Promise<Contact | undefined> {
-    const r = await this.bot.command('roomMembers', { conversationId: this.payload.id })
-    const u = r && r.ownerUser
-    if (!u || !u.userId) return undefined
-    return new Contact(this.bot, { id: u.userId, name: u.name, alias: u.alias, avatar: u.avatar, conversationId: u.conversationId })
-  }
-
-  toString (): string { return `Room<${this.topic() || this.id()}>` }
+  toString (): string { return `Room<${this.topic() || this.id}>` }
 }

package/src/mod.ts

@@ -13,6 +13,7 @@ export { Message } from './entity/message.js'
 export { Contact } from './entity/contact.js'
 export { Room } from './entity/room.js'
 export { Friendship } from './entity/friendship.js'
+export { ReceivedFile } from './entity/received-file.js'
 
 export * from './types.js'
 

package/src/types.ts

@@ -42,11 +42,16 @@ export interface ContactPayload {
   // 注: 企微企业通讯录未采集"性别"字段(探针 dump 的 User 结构无此项), 故 SDK 不暴露 gender()。
 }
 
-/** Contact.find/findAll 查询条件: 关键词字符串, 或按字段精确匹配。 */
+/** contactFind/contactFindAll 查询条件: 关键词字符串, 或按字段精确匹配。 */
 export type ContactQueryFilter =
   | string
   | { name?: string, alias?: string, id?: string }
 
+/** roomFind/roomFindAll 查询条件: 关键词字符串(匹配 topic/id 子串), 或按字段精确匹配。 */
+export type RoomQueryFilter =
+  | string
+  | { topic?: string, id?: string }
+
 /** 群。 */
 export interface RoomPayload {
   id: string                 // R:..