chatboty 0.1.0 → 0.2.1

package/src/chatboty.ts

@@ -5,7 +5,8 @@
  */
 import { ChatbotyClient, type ChatbotyClientOptions } from './client.js'
 import {
-  type BotApi, type Sayable, type MessagePayload, type ContactPayload, type ContactQueryFilter,
+  type BotApi, type Sayable, type MessagePayload, type ContactPayload,
+  type ContactQueryFilter, type RoomQueryFilter,
   toMessageType, isRoomId,
 } from './types.js'
 import { Message } from './entity/message.js'
@@ -32,6 +33,9 @@ export class Chatboty implements BotApi {
   /** 当前登录者(self)。start 后异步热身; 未就绪时 undefined(用 {@link currentUser} 主动拉取)。 */
   get self (): Contact | undefined { return this._self }
 
+  /** 是否已登录(在线)。等价于 self 已就绪。 */
+  get isLoggedIn (): boolean { return this._self !== undefined }
+
   async start (): Promise<void> {
     this.wire()
     await this.client.start()
@@ -47,12 +51,13 @@ export class Chatboty implements BotApi {
   on (event: 'friendship', l: (f: Friendship) => void): this
   on (event: 'room-join' | 'room-leave', l: (p: { room: Room, contactList: Contact[], idList: string[], timestamp?: number }) => void): this
   on (event: 'room-topic', l: (p: { room: Room, topic?: string, oldTopic?: string, timestamp?: number }) => void): this
-  on (event: 'login', l: (self?: any) => void): this
+  // 登录成功: 回调收到 typed 的当前登录者 Contact(已从 payload 构造并缓存到 bot.self)。
+  on (event: 'login', l: (self: Contact) => void): this
   on (event: 'scan', l: (p: { qrcode?: string, status?: any }) => void): this
   // 登录阶段(扫码/验证码全流程): phase = scan|scanned|need-verify|verifying|verify-ok|verify-fail|online...
   on (event: 'login-phase', l: (p: { phase: string, label?: string }) => void): this
-  // 探针/代理侧错误信号(不中断运行, 仅上报): { error }。
-  on (event: 'error', l: (p: { error: string }) => void): this
+  // 探针/代理侧错误信号(不中断运行, 仅上报): 回调收到一个真正的 Error 对象。
+  on (event: 'error', l: (err: Error) => void): this
   // 探针心跳(~30s 一次), 供上层做存活/掉线判定: { state }。
   on (event: 'heartbeat', l: (p: { state?: string }) => void): this
   on (event: 'logout' | 'ready' | 'stop' | 'disconnected', l: () => void): this
@@ -74,12 +79,17 @@ export class Chatboty implements BotApi {
       room: new Room(this, { id: w.roomId, topic: w.topic }), topic: w.topic, oldTopic: w.oldTopic, timestamp: w.timestamp,
     }))
     this.client.on('friendship', (w) => this.emit('friendship', this.toFriendship(w)))
-    this.client.on('login', (w) => this.emit('login', w.self))
+    this.client.on('login', (w) => {
+      // 把 payload 构造成 typed self Contact, 缓存并向上抛(供 message.mentionSelf/self 判定)。
+      const self = new Contact(this, this.toContactPayload(w.self ?? w))
+      this._self = self
+      this.emit('login', self)
+    })
     this.client.on('logout', () => { this._self = undefined; this.emit('logout') })
     this.client.on('scan', (w) => this.emit('scan', { qrcode: w.qrcode, status: w.status }))
     this.client.on('login-phase', (w) => this.emit('login-phase', { phase: w.phase, label: w.label }))
     this.client.on('disconnected', () => this.emit('disconnected'))
-    this.client.on('error', (w) => this.emit('error', { error: w.error }))
+    this.client.on('error', (w) => this.emit('error', new Error(w.error ?? '未知错误')))
     this.client.on('heartbeat', (w) => this.emit('heartbeat', { state: w.state }))
   }
 
@@ -143,6 +153,11 @@ export class Chatboty implements BotApi {
     return this.client.command('enterVerifyCode', { code })
   }
 
+  /** 刷新登录二维码(仅未登录/扫码态有效): 令探针重新取一张新码, 旧码作废。 */
+  async refreshQrCode (): Promise<any> {
+    return this.command('refreshQr')
+  }
+
   /** BotApi: 当前登录者 payload(供实体做本机 self 判定, 如 Message.mentionSelf)。 */
   selfContact (): ContactPayload | undefined { return this._self?.payload }
 
@@ -177,10 +192,36 @@ export class Chatboty implements BotApi {
   }
 
   /* ---------------- 查询/工厂 ---------------- */
-  async roomList (): Promise<Room[]> {
+
+  /**
+   * 查找群列表。无 query 时返回全部已加载群; 传 query 则在其上本地过滤。
+   * @param query 关键词字符串(匹配 topic/id 子串), 或 { topic?, id? } 精确匹配。
+   * @returns 命中的 Room 列表(可能为空)。
+   */
+  async roomFindAll (query?: RoomQueryFilter): Promise<Room[]> {
     const r = await this.command('roomList')
     const arr = (r && (r.rooms || r.list || (Array.isArray(r) ? r : []))) || []
-    return arr.map((x: any) => new Room(this, { id: x.conversationId || x.id, topic: x.name || x.topic }))
+    let list: Room[] = arr.map((x: any) => new Room(this, { id: x.conversationId || x.id, topic: x.name || x.topic }))
+    if (query !== undefined) {
+      if (typeof query === 'string') {
+        const kw = query.toLowerCase()
+        list = list.filter((rm) => (rm.topic() ?? '').toLowerCase().includes(kw) || rm.id.toLowerCase().includes(kw))
+      } else {
+        if (query.id) list = list.filter((rm) => rm.id === query.id)
+        if (query.topic) list = list.filter((rm) => rm.topic() === query.topic)
+      }
+    }
+    return list
+  }
+
+  /**
+   * 查找单个群(取 {@link roomFindAll} 第一个命中)。
+   * @param query 关键词字符串或 { topic?, id? }。
+   * @returns 命中的第一个 Room; 无则 undefined。
+   */
+  async roomFind (query: RoomQueryFilter): Promise<Room | undefined> {
+    const all = await this.roomFindAll(query)
+    return all[0]
   }
 
   async contactList (): Promise<Contact[]> {
@@ -202,7 +243,7 @@ export class Chatboty implements BotApi {
     const arr = (r && (r.contacts || r.list || (Array.isArray(r) ? r : []))) || []
     let list = arr.map((u: any) => new Contact(this, this.toContactPayload(u)))
     if (query && typeof query !== 'string') {   // 对象条件: 在子串命中基础上再做精确收窄
-      if (query.id) list = list.filter((c: Contact) => c.id() === query.id)
+      if (query.id) list = list.filter((c: Contact) => c.id === query.id)
       if (query.alias) list = list.filter((c: Contact) => c.alias() === query.alias)
       if (query.name) list = list.filter((c: Contact) => c.name() === query.name)
     }

package/src/entity/contact.ts

@@ -1,11 +1,22 @@
 import type { BotApi, ContactPayload, Sayable } from '../types.js'
 import { ContactType } from '../types.js'
 
-/** 联系人实体(含外部客户)。 */
+/**
+ * 联系人实体(含外部客户)。
+ *
+ * 【同步 vs 异步约定】实体已持有的数据(来自事件 payload / 缓存)用【同步】读取;
+ * 需要回连接器/企微的操作一律 async。
+ *   - 同步(缓存): id / name() / alias() / avatar() / phone() / title() / type() / conversationId()
+ *   - 异步(动作): say()
+ */
 export class Contact {
-  constructor (private readonly bot: BotApi, readonly payload: ContactPayload) {}
+  /** 联系人 id(vid; 同步只读属性)。 */
+  readonly id: string
+
+  constructor (private readonly bot: BotApi, readonly payload: ContactPayload) {
+    this.id = payload.id
+  }
 
-  id (): string { return this.payload.id }
   name (): string { return this.payload.name ?? '' }
   alias (): string | undefined { return this.payload.alias }
   avatar (): string | undefined { return this.payload.avatar }
@@ -24,9 +35,9 @@ export class Contact {
   /** 给该联系人发消息(单聊)。 */
   async say (sayable: Sayable): Promise<any> {
     const conv = this.payload.conversationId
-    if (!conv) throw new Error(`Contact ${this.id()} 无单聊会话 id, 无法发送`)
+    if (!conv) throw new Error(`Contact ${this.id} 无单聊会话 id, 无法发送`)
     return this.bot.sayTo(conv, sayable)
   }
 
-  toString (): string { return `Contact<${this.name() || this.id()}>` }
+  toString (): string { return `Contact<${this.name() || this.id}>` }
 }

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:..