chatboty 0.1.0

package/src/entity/message.ts

@@ -0,0 +1,147 @@
+import type { BotApi, MessagePayload, Sayable, FileBox } from '../types.js'
+import { MessageType } from '../types.js'
+import { Contact } from './contact.js'
+import { Room } from './room.js'
+
+/** 消息实体。 */
+export class Message {
+  constructor (private readonly bot: BotApi, readonly payload: MessagePayload) {}
+
+  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 }
+  miniProgram (): Record<string, any> | null | undefined { return this.payload.miniProgram }
+  urlLink (): Record<string, any> | null | undefined { return this.payload.urlLink }
+
+  /** 发送者(完整 Contact; 群消息识别客户用)。 */
+  talker (): Contact | undefined {
+    if (this.payload.talker) return new Contact(this.bot, this.payload.talker)
+    if (this.payload.talkerId) return new Contact(this.bot, { id: this.payload.talkerId })
+    return undefined
+  }
+
+  /** 所在群(单聊为 undefined)。 */
+  room (): Room | undefined {
+    return this.payload.roomId ? new Room(this.bot, { id: this.payload.roomId }) : undefined
+  }
+
+  /** 回复到原会话(群消息回群, 单聊回该人)。 */
+  async say (sayable: Sayable): Promise<any> {
+    const target = this.payload.roomId || this.payload.conversationId
+    return this.bot.sayTo(target, sayable)
+  }
+
+  /* ---------------- @ 提及 ---------------- */
+
+  /**
+   * 从消息正文解析出的 @ 提及显示名(不含 "@所有人"/"@all")。
+   * 说明: 企微群 @ 消息正文形如 `@张三 内容`, 名字后接普通空格或 U+2005(four-per-em space)分隔。
+   * 这是"从消息 payload 解析"的诚实实现——只用真实的正文文本; 结构化的被@ vid 需进一步逆向(见 RE 计划)。
+   */
+  private mentionNames (): string[] {
+    const text = this.payload.text ?? ''
+    if (!text.includes('@')) return []
+    const out: string[] = []
+    const re = /@([^\s @]+)/g
+    let m: RegExpExecArray | null
+    while ((m = re.exec(text)) !== null) {
+      const n = m[1]
+      if (n && n !== '所有人' && n.toLowerCase() !== 'all') out.push(n)
+    }
+    return out
+  }
+
+  /**
+   * 消息中被 @ 的联系人列表(best-effort)。
+   * 先从正文解析出 @显示名, 再用一次 contactList 拉全量通讯录按 name/alias 就近解析成完整 Contact;
+   * 未在已加载通讯录中的成员回退为仅含名字的 Contact(其 id() 为空串)。
+   * @returns 被 @ 的 Contact 数组(无 @ 时为空数组)。
+   */
+  async mentionList (): Promise<Contact[]> {
+    const names = this.mentionNames()
+    if (names.length === 0) return []
+    let pool: any[] = []
+    try {
+      const r = await this.bot.command('contactList')
+      pool = (r && (r.contacts || r.list || (Array.isArray(r) ? r : []))) || []
+    } catch { /* 解析失败不致命: 退回仅名字的 Contact */ }
+    return names.map((nm) => {
+      const u = pool.find((x: any) => x && (x.name === nm || x.alias === nm || x.realName === nm))
+      if (u) {
+        return new Contact(this.bot, {
+          id: u.userId ?? u.id ?? '', name: u.name ?? u.realName, alias: u.alias, avatar: u.avatar,
+          phone: u.phone, title: u.title, corpId: u.corpId, unionId: u.unionId, conversationId: u.conversationId,
+        })
+      }
+      return new Contact(this.bot, { id: '', name: nm })
+    })
+  }
+
+  /**
+   * 本条消息是否 @ 了当前登录者(self)或 @所有人。
+   * 判定: 正文含 `@所有人`/`@all`(全体含自己) → true; 或含 `@{self 显示名}` → true。
+   * (纯本机文本判定, 不发起网络请求; 依赖 bot 已知 self 名。)
+   */
+  mentionSelf (): boolean {
+    const text = this.payload.text ?? ''
+    if (!text.includes('@')) return false
+    if (/@所有人|@all\b/i.test(text)) return true
+    const selfName = this.bot.selfContact?.()?.name
+    return !!selfName && this.mentionNames().includes(selfName)
+  }
+
+  /* ---------------- 媒体下载 ---------------- */
+
+  private toFileBoxFromResult (r: any): FileBox | 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 }
+  }
+
+  /**
+   * 取本条消息的媒体/文件字节(图片/文件/音视频), 返回 {@link FileBox}(含 base64 data URL)。
+   * - 收到的图片/文件事件通常已附带 file(探针后台已下载解密) → 直接返回。
+   * - 否则按类型冷调探针下载: 图片走 downloadImage, 文件/音视频走 downloadFile(按 msgid+会话+文件名定位缓存)。
+   * @returns FileBox(dataUrl/mime/name/size); 非媒体消息或下载失败返回 null。
+   */
+  async toFileBox (): Promise<FileBox | null> {
+    if (this.payload.file) return 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)
+    }
+    if (t === MessageType.File || t === MessageType.Video || t === MessageType.Audio) {
+      const r = await this.bot.command('downloadFile', {
+        msgid,
+        conversationId: this.payload.conversationId,
+        timestamp: this.payload.timestamp,
+        name: this.payload.text,
+      })
+      return this.toFileBoxFromResult(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 计划')
+  }
+
+  toString (): string { return `Message<${MessageType[this.type()]}:${this.text().slice(0, 30)}>` }
+}

package/src/entity/room.ts

@@ -0,0 +1,42 @@
+import type { BotApi, RoomPayload, Sayable } from '../types.js'
+import { Contact } from './contact.js'
+
+/** 群实体。 */
+export class Room {
+  constructor (private readonly bot: BotApi, readonly payload: RoomPayload) {}
+
+  id (): string { return this.payload.id }
+  topic (): string | undefined { return this.payload.topic }
+  ownerId (): string | undefined { return this.payload.ownerId }
+
+  /** 群发消息。 */
+  async say (sayable: Sayable): Promise<any> {
+    return this.bot.sayTo(this.payload.id, sayable)
+  }
+
+  /** 改群名(冷改, 内外群通用)。 */
+  async rename (topic: string): Promise<any> {
+    return this.bot.command('roomTopic', { conversationId: this.payload.id, topic })
+  }
+
+  /** 群成员(完整 Contact 对象; 受探针成员枚举局限)。 */
+  async memberAll (): Promise<Contact[]> {
+    const r = await this.bot.command('roomMembers', { conversationId: this.payload.id })
+    const list = (r && (r.memberList || [])) as any[]
+    return list.map((u) => new Contact(this.bot, {
+      id: u.userId, name: u.name, alias: u.alias, avatar: u.avatar,
+      phone: u.phone, title: u.title, corpId: u.corpId, unionId: u.unionId,
+      conversationId: u.conversationId,
+    }))
+  }
+
+  /** 群主(若可解析)。 */
+  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()}>` }
+}

package/src/mod.ts

@@ -0,0 +1,19 @@
+/**
+ * chatboty 公共入口。自研 IM 自动化框架(企业微信), 零外部框架依赖。
+ *
+ *   import { Chatboty } from 'chatboty'
+ *   const bot = new Chatboty({ token: 'cbt_...' })
+ *   bot.on('message', m => { if (!m.self()) m.say('收到: ' + m.text()) })
+ *   await bot.start()
+ */
+export { Chatboty, type ChatbotyOptions } from './chatboty.js'
+export { ChatbotyClient, type ChatbotyClientOptions, type EventHandler } from './client.js'
+
+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 * from './types.js'
+
+export { Chatboty as default } from './chatboty.js'

package/src/types.ts

@@ -0,0 +1,142 @@
+/**
+ * chatboty 自研类型(零外部框架依赖)。这些 payload 是实体类的数据底座,
+ * 由网关下发的 wire 事件/命令结果映射而来。
+ */
+
+/** 消息类型。 */
+export enum MessageType {
+  Unknown = 0,
+  Text,
+  Image,
+  Audio,
+  Video,
+  File,
+  Url,        // 链接卡片
+  MiniProgram,
+  System,     // 系统/通知(群事件等)
+}
+
+/**
+ * 联系人类别。企微现实: 通讯录里都是"真人"(个人/同事/外部客户), 没有微信那种"公众号/服务号"构造,
+ * 故探针默认给 Individual。Official/Corporation 预留给未来能可靠区分"应用/机器人/企业主体"时使用。
+ */
+export enum ContactType {
+  Unknown = 0,
+  Individual,   // 真人(默认; 企微通讯录成员/外部客户)
+  Official,     // 应用/机器人号(企微暂无可靠信号, 预留)
+  Corporation,  // 企业主体(预留)
+}
+
+/** 联系人(含外部客户)。 */
+export interface ContactPayload {
+  id: string                 // vid
+  name?: string
+  alias?: string             // 备注
+  avatar?: string
+  phone?: string
+  title?: string             // 职务/部门
+  corpId?: string
+  unionId?: string
+  conversationId?: string    // 单聊会话 id(S:..), 发消息目标
+  type?: ContactType         // 类别(探针未标注时由 Contact.type() 兜底 Individual)
+  // 注: 企微企业通讯录未采集"性别"字段(探针 dump 的 User 结构无此项), 故 SDK 不暴露 gender()。
+}
+
+/** Contact.find/findAll 查询条件: 关键词字符串, 或按字段精确匹配。 */
+export type ContactQueryFilter =
+  | string
+  | { name?: string, alias?: string, id?: string }
+
+/** 群。 */
+export interface RoomPayload {
+  id: string                 // R:..
+  topic?: string
+  ownerId?: string
+  memberIdList?: string[]
+}
+
+/** 媒体附件(图片/文件)。 */
+export interface FileBox {
+  dataUrl?: string
+  mime?: string
+  name?: string
+  size?: number
+}
+
+/** 消息。 */
+export interface MessagePayload {
+  id?: string
+  type: MessageType
+  text?: string
+  talkerId?: string
+  roomId?: string            // 群消息所在群(单聊为空)
+  conversationId: string     // 消息会话(R: 群 / S: 单聊)
+  timestamp?: number
+  self?: boolean
+  talker?: ContactPayload    // 完整发送者(已对象化)
+  file?: FileBox | null
+  miniProgram?: Record<string, any> | null
+  urlLink?: Record<string, any> | null
+}
+
+/** 好友关系事件。 */
+export type FriendshipKind = 'receive' | 'confirm' | 'add' | 'delete'
+export interface FriendshipPayload {
+  contactId: string
+  contact?: ContactPayload
+  kind: FriendshipKind
+  hello?: string
+}
+
+/** 群事件(成员变动/改名) payload。 */
+export interface RoomMemberEventPayload {
+  roomId: string
+  idList: string[]                 // 进/退群成员 vid
+  contactList?: ContactPayload[]   // 完整成员对象
+  operatorId?: string | null       // 操作者(系统消息常缺)
+  timestamp?: number
+}
+export interface RoomTopicEventPayload {
+  roomId: string
+  topic?: string
+  oldTopic?: string
+  changerId?: string | null
+  timestamp?: number
+}
+
+/** 可发送内容。文本=字符串; 媒体=带类型的对象(路径/URL/base64 由探针侧解析)。 */
+export type Sayable =
+  | string
+  | { image: string }                                   // 图片(URL/本地路径/base64)
+  | { file: string }                                    // 文件
+  | { url: string, title?: string, description?: string, thumbUrl?: string }   // 链接卡片
+  | { miniProgram: Record<string, any> }                // 小程序卡片
+
+/** 实体类回引 bot 的最小接口(避免循环依赖)。Chatboty 主类实现之。 */
+export interface BotApi {
+  command (cmd: string, args?: Record<string, any>): Promise<any>
+  sayTo (conversationId: string, sayable: Sayable): Promise<any>
+  /** 当前登录者(self)payload(供 Message.mentionSelf 等做本机判定); 未就绪时 undefined。 */
+  selfContact? (): ContactPayload | undefined
+}
+
+/** 会话 id 类型判定(R: 群 / S: 单聊 / 其它)。 */
+export function isRoomId (conversationId?: string): boolean {
+  return !!conversationId && conversationId.startsWith('R:')
+}
+
+/** wire 事件里的字符串/数字消息类型 → MessageType。 */
+export function toMessageType (typeStr?: string, typeRaw?: number): MessageType {
+  switch ((typeStr || '').toLowerCase()) {
+    case 'text': return MessageType.Text
+    case 'image': return MessageType.Image
+    case 'image/file': return MessageType.Image
+    case 'voice': case 'audio': return MessageType.Audio
+    case 'video': return MessageType.Video
+    case 'file': return MessageType.File
+    case 'url': return MessageType.Url
+    case 'miniprogram': return MessageType.MiniProgram
+    case 'sys': case 'system': return MessageType.System
+    default: return typeRaw ? MessageType.Unknown : MessageType.Unknown
+  }
+}