chatboty 0.1.0 → 0.2.0

package/dist/esm/src/entity/message.d.ts

@@ -1,18 +1,28 @@
-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 declare class Message {
     private readonly bot;
     readonly payload: MessagePayload;
+    /** 消息 id(来自事件 payload; 同步只读属性)。未知时为空串。 */
+    readonly id: string;
     constructor(bot: BotApi, payload: MessagePayload);
-    id(): string | undefined;
     type(): MessageType;
     text(): string;
     self(): boolean;
     timestamp(): number | undefined;
-    file(): FileBox | null | undefined;
+    /** 随事件附带的媒体(若探针已下载); 无则 undefined。取字节请用 {@link toFileBox}。 */
+    file(): ReceivedFile | null | undefined;
     miniProgram(): Record<string, any> | null | undefined;
     urlLink(): Record<string, any> | null | undefined;
     /** 发送者(完整 Contact; 群消息识别客户用)。 */
@@ -30,7 +40,7 @@ export declare class Message {
     /**
      * 消息中被 @ 的联系人列表(best-effort)。
      * 先从正文解析出 @显示名, 再用一次 contactList 拉全量通讯录按 name/alias 就近解析成完整 Contact;
-     * 未在已加载通讯录中的成员回退为仅含名字的 Contact(其 id() 为空串)。
+     * 未在已加载通讯录中的成员回退为仅含名字的 Contact(其 id 为空串)。
      * @returns 被 @ 的 Contact 数组(无 @ 时为空数组)。
      */
     mentionList(): Promise<Contact[]>;
@@ -40,22 +50,17 @@ export declare class Message {
      * (纯本机文本判定, 不发起网络请求; 依赖 bot 已知 self 名。)
      */
     mentionSelf(): boolean;
-    private toFileBoxFromResult;
+    private toFileFromResult;
     /**
-     * 取本条消息的媒体/文件字节(图片/文件/音视频), 返回 {@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。
      */
-    toFileBox(): Promise<FileBox | null>;
+    toFileBox(): Promise<ReceivedFile | null>;
     /** {@link toFileBox} 的别名(下载本条消息的媒体字节)。 */
-    download(): Promise<FileBox | null>;
-    /**
-     * 转发本条消息到另一会话(群/单聊 conversationId, 或 Room/Contact)。
-     * ⚠️ 未实现: 企微转发需逆向定位并冷调"转发消息"服务(见 puppet-wework 交付说明的 RE 计划)。
-     * 当前会抛错, 以免静默失败。
-     */
-    forward(_to: string | Room | Contact): Promise<never>;
+    download(): Promise<ReceivedFile | null>;
     toString(): string;
 }
 //# sourceMappingURL=message.d.ts.map

package/dist/esm/src/entity/message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../../../src/entity/message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,YAAY;AACZ,qBAAa,OAAO;IACL,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAU,QAAQ,CAAC,OAAO,EAAE,cAAc;gBAA7C,GAAG,EAAE,MAAM,EAAW,OAAO,EAAE,cAAc;IAE3E,EAAE,IAAK,MAAM,GAAG,SAAS;IACzB,IAAI,IAAK,WAAW;IACpB,IAAI,IAAK,MAAM;IACf,IAAI,IAAK,OAAO;IAChB,SAAS,IAAK,MAAM,GAAG,SAAS;IAChC,IAAI,IAAK,OAAO,GAAG,IAAI,GAAG,SAAS;IACnC,WAAW,IAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS;IACtD,OAAO,IAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS;IAElD,iCAAiC;IACjC,MAAM,IAAK,OAAO,GAAG,SAAS;IAM9B,0BAA0B;IAC1B,IAAI,IAAK,IAAI,GAAG,SAAS;IAIzB,4BAA4B;IACtB,GAAG,CAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAO1C;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAapB;;;;;OAKG;IACG,WAAW,IAAK,OAAO,CAAC,OAAO,EAAE,CAAC;IAoBxC;;;;OAIG;IACH,WAAW,IAAK,OAAO;IAUvB,OAAO,CAAC,mBAAmB;IAO3B;;;;;OAKG;IACG,SAAS,IAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAqB3C,0CAA0C;IACpC,QAAQ,IAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAI1C;;;;OAIG;IACG,OAAO,CAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC;IAI5D,QAAQ,IAAK,MAAM;CACpB"}
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../../../src/entity/message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD;;;;;;;GAOG;AACH,qBAAa,OAAO;IAIL,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAU,QAAQ,CAAC,OAAO,EAAE,cAAc;IAH3E,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;gBAEW,GAAG,EAAE,MAAM,EAAW,OAAO,EAAE,cAAc;IAI3E,IAAI,IAAK,WAAW;IACpB,IAAI,IAAK,MAAM;IACf,IAAI,IAAK,OAAO;IAChB,SAAS,IAAK,MAAM,GAAG,SAAS;IAChC,8DAA8D;IAC9D,IAAI,IAAK,YAAY,GAAG,IAAI,GAAG,SAAS;IAGxC,WAAW,IAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS;IACtD,OAAO,IAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS;IAElD,iCAAiC;IACjC,MAAM,IAAK,OAAO,GAAG,SAAS;IAM9B,0BAA0B;IAC1B,IAAI,IAAK,IAAI,GAAG,SAAS;IAIzB,4BAA4B;IACtB,GAAG,CAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAO1C;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAapB;;;;;OAKG;IACG,WAAW,IAAK,OAAO,CAAC,OAAO,EAAE,CAAC;IAoBxC;;;;OAIG;IACH,WAAW,IAAK,OAAO;IAUvB,OAAO,CAAC,gBAAgB;IAOxB;;;;;;OAMG;IACG,SAAS,IAAK,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAqBhD,0CAA0C;IACpC,QAAQ,IAAK,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAE/C,QAAQ,IAAK,MAAM;CACpB"}

package/dist/esm/src/entity/message.js

@@ -1,18 +1,29 @@
 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(bot, payload) {
         this.bot = bot;
         this.payload = payload;
+        this.id = payload.id ?? '';
     }
-    id() { return this.payload.id; }
     type() { return this.payload.type; }
     text() { return this.payload.text ?? ''; }
     self() { return !!this.payload.self; }
     timestamp() { return this.payload.timestamp; }
-    file() { return this.payload.file; }
+    /** 随事件附带的媒体(若探针已下载); 无则 undefined。取字节请用 {@link toFileBox}。 */
+    file() {
+        return this.payload.file ? new ReceivedFile(this.payload.file) : this.payload.file;
+    }
     miniProgram() { return this.payload.miniProgram; }
     urlLink() { return this.payload.urlLink; }
     /** 发送者(完整 Contact; 群消息识别客户用)。 */
@@ -55,7 +66,7 @@ export class Message {
     /**
      * 消息中被 @ 的联系人列表(best-effort)。
      * 先从正文解析出 @显示名, 再用一次 contactList 拉全量通讯录按 name/alias 就近解析成完整 Contact;
-     * 未在已加载通讯录中的成员回退为仅含名字的 Contact(其 id() 为空串)。
+     * 未在已加载通讯录中的成员回退为仅含名字的 Contact(其 id 为空串)。
      * @returns 被 @ 的 Contact 数组(无 @ 时为空数组)。
      */
     async mentionList() {
@@ -94,30 +105,31 @@ export class Message {
         return !!selfName && this.mentionNames().includes(selfName);
     }
     /* ---------------- 媒体下载 ---------------- */
-    toFileBoxFromResult(r) {
+    toFileFromResult(r) {
         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() {
         if (this.payload.file)
-            return 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', {
@@ -126,21 +138,12 @@ 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() { return this.toFileBox(); }
-    /* ---------------- 转发(RE 待定) ---------------- */
-    /**
-     * 转发本条消息到另一会话(群/单聊 conversationId, 或 Room/Contact)。
-     * ⚠️ 未实现: 企微转发需逆向定位并冷调"转发消息"服务(见 puppet-wework 交付说明的 RE 计划)。
-     * 当前会抛错, 以免静默失败。
-     */
-    async forward(_to) {
-        throw new Error('Message.forward 未实现: 需逆向定位企微转发消息服务(ForwardMessage), 见 RE 计划');
-    }
     toString() { return `Message<${MessageType[this.type()]}:${this.text().slice(0, 30)}>`; }
 }
 //# sourceMappingURL=message.js.map

package/dist/esm/src/entity/message.js.map

@@ -1 +1 @@
-{"version":3,"file":"message.js","sourceRoot":"","sources":["../../../../src/entity/message.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"message.js","sourceRoot":"","sources":["../../../../src/entity/message.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/entity/received-file.d.ts

@@ -0,0 +1,25 @@
+import type { FileBox } from '../types.js';
+/**
+ * 收到的媒体/文件(图片/文件/音视频)。自包含, 零外部依赖。
+ *
+ * 除原始字段(dataUrl/mime/name/size)外, 额外提供便捷方法:
+ *   - toBuffer(): 同步, 把 dataUrl/base64 解码成原始字节(Buffer)。
+ *   - save(path): 异步, 把字节写到磁盘。
+ */
+export declare 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);
+    /** 解出原始字节(从 dataUrl / 裸 base64 解码)。同步。 */
+    toBuffer(): Buffer;
+    /** 写盘到指定路径(需 round-trip 到磁盘, 故为 async)。 */
+    save(path: string): Promise<void>;
+    toString(): string;
+}
+//# sourceMappingURL=received-file.d.ts.map

package/dist/esm/src/entity/received-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"received-file.d.ts","sourceRoot":"","sources":["../../../../src/entity/received-file.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAE1C;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,sDAAsD;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,mBAAmB;IACnB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,gBAAgB;IAChB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;gBAET,IAAI,EAAE,OAAO;IAO1B,0CAA0C;IAC1C,QAAQ,IAAK,MAAM;IAOnB,2CAA2C;IACrC,IAAI,CAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC,QAAQ,IAAK,MAAM;CACpB"}

package/dist/esm/src/entity/received-file.js

@@ -0,0 +1,31 @@
+import { writeFile } from 'node:fs/promises';
+/**
+ * 收到的媒体/文件(图片/文件/音视频)。自包含, 零外部依赖。
+ *
+ * 除原始字段(dataUrl/mime/name/size)外, 额外提供便捷方法:
+ *   - toBuffer(): 同步, 把 dataUrl/base64 解码成原始字节(Buffer)。
+ *   - save(path): 异步, 把字节写到磁盘。
+ */
+export class ReceivedFile {
+    constructor(init) {
+        this.dataUrl = init.dataUrl;
+        this.mime = init.mime;
+        this.name = init.name;
+        this.size = init.size;
+    }
+    /** 解出原始字节(从 dataUrl / 裸 base64 解码)。同步。 */
+    toBuffer() {
+        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) {
+        // 用 Uint8Array 包一层: 新版 @types/node 的 writeFile 形参要求 Uint8Array<ArrayBuffer>,
+        // 而 Buffer 的底层可能是 SharedArrayBuffer(方差不兼容); 复制成纯 ArrayBuffer 视图即可。
+        await writeFile(path, new Uint8Array(this.toBuffer()));
+    }
+    toString() { return `ReceivedFile<${this.name ?? this.mime ?? 'unknown'}>`; }
+}
+//# sourceMappingURL=received-file.js.map

package/dist/esm/src/entity/received-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"received-file.js","sourceRoot":"","sources":["../../../../src/entity/received-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAG5C;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IAUvB,YAAa,IAAa;QACxB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;IACvB,CAAC;IAED,0CAA0C;IAC1C,QAAQ;QACN,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAA;QAC5B,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAC5B,MAAM,GAAG,GAAG,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QACxE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IACnC,CAAC;IAED,2CAA2C;IAC3C,KAAK,CAAC,IAAI,CAAE,IAAY;QACtB,6EAA6E;QAC7E,mEAAmE;QACnE,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAA;IACxD,CAAC;IAED,QAAQ,KAAc,OAAO,gBAAgB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,SAAS,GAAG,CAAA,CAAC,CAAC;CACtF"}

package/dist/esm/src/entity/room.d.ts

@@ -1,21 +1,31 @@
 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 declare class Room {
     private readonly bot;
     readonly payload: RoomPayload;
+    /** 群 id(R:..; 同步只读属性)。 */
+    readonly id: string;
     constructor(bot: BotApi, payload: RoomPayload);
-    id(): string;
     topic(): string | undefined;
-    ownerId(): string | undefined;
-    /** 群发消息。 */
+    /**
+     * 群主(同步; 由缓存的 ownerId 构造)。
+     * 事件/列表未携带 ownerId 时返回 undefined; 需完整群主资料请用 {@link memberAll} 定位。
+     */
+    owner(): Contact | undefined;
+    /** 群发消息(动作)。 */
     say(sayable: Sayable): Promise<any>;
-    /** 改群名(冷改, 内外群通用)。 */
+    /** 改群名(冷改, 内外群通用; round-trip)。 */
     rename(topic: string): Promise<any>;
-    /** 群成员(完整 Contact 对象; 受探针成员枚举局限)。 */
+    /** 群成员(完整 Contact 对象; 受探针成员枚举局限; round-trip)。 */
     memberAll(): Promise<Contact[]>;
-    /** 群主(若可解析)。 */
-    owner(): Promise<Contact | undefined>;
     toString(): string;
 }
 //# sourceMappingURL=room.d.ts.map

package/dist/esm/src/entity/room.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"room.d.ts","sourceRoot":"","sources":["../../../../src/entity/room.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,WAAW;AACX,qBAAa,IAAI;IACF,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAU,QAAQ,CAAC,OAAO,EAAE,WAAW;gBAA1C,GAAG,EAAE,MAAM,EAAW,OAAO,EAAE,WAAW;IAExE,EAAE,IAAK,MAAM;IACb,KAAK,IAAK,MAAM,GAAG,SAAS;IAC5B,OAAO,IAAK,MAAM,GAAG,SAAS;IAE9B,YAAY;IACN,GAAG,CAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAI1C,sBAAsB;IAChB,MAAM,CAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAI1C,qCAAqC;IAC/B,SAAS,IAAK,OAAO,CAAC,OAAO,EAAE,CAAC;IAUtC,gBAAgB;IACV,KAAK,IAAK,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAO5C,QAAQ,IAAK,MAAM;CACpB"}
+{"version":3,"file":"room.d.ts","sourceRoot":"","sources":["../../../../src/entity/room.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC;;;;;;;GAOG;AACH,qBAAa,IAAI;IAIF,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAU,QAAQ,CAAC,OAAO,EAAE,WAAW;IAHxE,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;gBAEW,GAAG,EAAE,MAAM,EAAW,OAAO,EAAE,WAAW;IAIxE,KAAK,IAAK,MAAM,GAAG,SAAS;IAE5B;;;OAGG;IACH,KAAK,IAAK,OAAO,GAAG,SAAS;IAI7B,gBAAgB;IACV,GAAG,CAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAI1C,kCAAkC;IAC5B,MAAM,CAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAI1C,iDAAiD;IAC3C,SAAS,IAAK,OAAO,CAAC,OAAO,EAAE,CAAC;IAUtC,QAAQ,IAAK,MAAM;CACpB"}

package/dist/esm/src/entity/room.js

@@ -1,22 +1,35 @@
 import { Contact } from './contact.js';
-/** 群实体。 */
+/**
+ * 群实体。
+ *
+ * 【同步 vs 异步约定】实体已持有的数据(来自事件 payload / 缓存)用【同步】读取;
+ * 需要回连接器/企微(拉成员、改名、发送)的操作一律 async。
+ *   - 同步(缓存): id / topic() / owner()
+ *   - 异步(round-trip/动作): say() / rename() / memberAll()
+ */
 export class Room {
     constructor(bot, payload) {
         this.bot = bot;
         this.payload = payload;
+        this.id = payload.id;
     }
-    id() { return this.payload.id; }
     topic() { return this.payload.topic; }
-    ownerId() { return this.payload.ownerId; }
-    /** 群发消息。 */
+    /**
+     * 群主(同步; 由缓存的 ownerId 构造)。
+     * 事件/列表未携带 ownerId 时返回 undefined; 需完整群主资料请用 {@link memberAll} 定位。
+     */
+    owner() {
+        return this.payload.ownerId ? new Contact(this.bot, { id: this.payload.ownerId }) : undefined;
+    }
+    /** 群发消息(动作)。 */
     async say(sayable) {
         return this.bot.sayTo(this.payload.id, sayable);
     }
-    /** 改群名(冷改, 内外群通用)。 */
+    /** 改群名(冷改, 内外群通用; round-trip)。 */
     async rename(topic) {
         return this.bot.command('roomTopic', { conversationId: this.payload.id, topic });
     }
-    /** 群成员(完整 Contact 对象; 受探针成员枚举局限)。 */
+    /** 群成员(完整 Contact 对象; 受探针成员枚举局限; round-trip)。 */
     async memberAll() {
         const r = await this.bot.command('roomMembers', { conversationId: this.payload.id });
         const list = (r && (r.memberList || []));
@@ -26,14 +39,6 @@ export class Room {
             conversationId: u.conversationId,
         }));
     }
-    /** 群主(若可解析)。 */
-    async owner() {
-        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() { return `Room<${this.topic() || this.id()}>`; }
+    toString() { return `Room<${this.topic() || this.id}>`; }
 }
 //# sourceMappingURL=room.js.map

package/dist/esm/src/entity/room.js.map

@@ -1 +1 @@
-{"version":3,"file":"room.js","sourceRoot":"","sources":["../../../../src/entity/room.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,WAAW;AACX,MAAM,OAAO,IAAI;IACf,YAA8B,GAAW,EAAW,OAAoB;QAA1C,QAAG,GAAH,GAAG,CAAQ;QAAW,YAAO,GAAP,OAAO,CAAa;IAAG,CAAC;IAE5E,EAAE,KAAc,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAA,CAAC,CAAC;IACxC,KAAK,KAA0B,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAA,CAAC,CAAC;IAC1D,OAAO,KAA0B,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAA,CAAC,CAAC;IAE9D,YAAY;IACZ,KAAK,CAAC,GAAG,CAAE,OAAgB;QACzB,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IACjD,CAAC;IAED,sBAAsB;IACtB,KAAK,CAAC,MAAM,CAAE,KAAa;QACzB,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IAClF,CAAC;IAED,qCAAqC;IACrC,KAAK,CAAC,SAAS;QACb,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAA;QACpF,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAU,CAAA;QACjD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE;YAC3C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM;YAC5D,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO;YACpE,cAAc,EAAE,CAAC,CAAC,cAAc;SACjC,CAAC,CAAC,CAAA;IACL,CAAC;IAED,gBAAgB;IAChB,KAAK,CAAC,KAAK;QACT,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAA;QACpF,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,SAAS,CAAA;QAC1B,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM;YAAE,OAAO,SAAS,CAAA;QACrC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,CAAA;IAClI,CAAC;IAED,QAAQ,KAAc,OAAO,QAAQ,IAAI,CAAC,KAAK,EAAE,IAAI,IAAI,CAAC,EAAE,EAAE,GAAG,CAAA,CAAC,CAAC;CACpE"}
+{"version":3,"file":"room.js","sourceRoot":"","sources":["../../../../src/entity/room.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC;;;;;;;GAOG;AACH,MAAM,OAAO,IAAI;IAIf,YAA8B,GAAW,EAAW,OAAoB;QAA1C,QAAG,GAAH,GAAG,CAAQ;QAAW,YAAO,GAAP,OAAO,CAAa;QACtE,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,CAAA;IACtB,CAAC;IAED,KAAK,KAA0B,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAA,CAAC,CAAC;IAE1D;;;OAGG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAC/F,CAAC;IAED,gBAAgB;IAChB,KAAK,CAAC,GAAG,CAAE,OAAgB;QACzB,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IACjD,CAAC;IAED,kCAAkC;IAClC,KAAK,CAAC,MAAM,CAAE,KAAa;QACzB,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IAClF,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,SAAS;QACb,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAA;QACpF,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAU,CAAA;QACjD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE;YAC3C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM;YAC5D,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO;YACpE,cAAc,EAAE,CAAC,CAAC,cAAc;SACjC,CAAC,CAAC,CAAA;IACL,CAAC;IAED,QAAQ,KAAc,OAAO,QAAQ,IAAI,CAAC,KAAK,EAAE,IAAI,IAAI,CAAC,EAAE,GAAG,CAAA,CAAC,CAAC;CAClE"}

package/dist/esm/src/mod.d.ts

@@ -12,6 +12,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';
 export { Chatboty as default } from './chatboty.js';
 //# sourceMappingURL=mod.d.ts.map

package/dist/esm/src/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAE3F,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAEnD,cAAc,YAAY,CAAA;AAE1B,OAAO,EAAE,QAAQ,IAAI,OAAO,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAE3F,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAExD,cAAc,YAAY,CAAA;AAE1B,OAAO,EAAE,QAAQ,IAAI,OAAO,EAAE,MAAM,eAAe,CAAA"}

package/dist/esm/src/mod.js

@@ -12,6 +12,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';
 export { Chatboty as default } from './chatboty.js';
 //# sourceMappingURL=mod.js.map

package/dist/esm/src/mod.js.map

@@ -1 +1 @@
-{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAA;AAC9D,OAAO,EAAE,cAAc,EAAiD,MAAM,aAAa,CAAA;AAE3F,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAEnD,cAAc,YAAY,CAAA;AAE1B,OAAO,EAAE,QAAQ,IAAI,OAAO,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAA;AAC9D,OAAO,EAAE,cAAc,EAAiD,MAAM,aAAa,CAAA;AAE3F,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAExD,cAAc,YAAY,CAAA;AAE1B,OAAO,EAAE,QAAQ,IAAI,OAAO,EAAE,MAAM,eAAe,CAAA"}

package/dist/esm/src/types.d.ts

@@ -37,12 +37,17 @@ export interface ContactPayload {
     conversationId?: string;
     type?: ContactType;
 }
-/** 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;

package/dist/esm/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY;AACZ,oBAAY,WAAW;IACrB,OAAO,IAAI;IACX,IAAI,IAAA;IACJ,KAAK,IAAA;IACL,KAAK,IAAA;IACL,KAAK,IAAA;IACL,IAAI,IAAA;IACJ,GAAG,IAAA,CAAS,OAAO;IACnB,WAAW,IAAA;IACX,MAAM,IAAA;CACP;AAED;;;GAGG;AACH,oBAAY,WAAW;IACrB,OAAO,IAAI;IACX,UAAU,IAAA,CAAI,uBAAuB;IACrC,QAAQ,IAAA,CAAM,wBAAwB;IACtC,WAAW,IAAA;CACZ;AAED,kBAAkB;AAClB,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,IAAI,CAAC,EAAE,WAAW,CAAA;CAEnB;AAED,yDAAyD;AACzD,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAElD,mEAAmE;AACnE,MAAM,MAAM,eAAe,GACvB,MAAM,GACN;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnC,SAAS;AACT,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB;AAED,mBAAmB;AACnB,MAAM,WAAW,OAAO;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,UAAU;AACV,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,WAAW,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;CACrC;AAED,cAAc;AACd,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,CAAA;AACrE,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,cAAc,CAAA;IACxB,IAAI,EAAE,cAAc,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,4BAA4B;AAC5B,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,WAAW,CAAC,EAAE,cAAc,EAAE,CAAA;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AACD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,qDAAqD;AACrD,MAAM,MAAM,OAAO,GACf,MAAM,GACN;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAA;AAExC,8CAA8C;AAC9C,MAAM,WAAW,MAAM;IACrB,OAAO,CAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IAC/D,KAAK,CAAE,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IAC9D,wEAAwE;IACxE,WAAW,CAAC,IAAK,cAAc,GAAG,SAAS,CAAA;CAC5C;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,CAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,yCAAyC;AACzC,wBAAgB,aAAa,CAAE,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAa9E"}

package/dist/esm/src/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY;AACZ,MAAM,CAAN,IAAY,WAUX;AAVD,WAAY,WAAW;IACrB,mDAAW,CAAA;IACX,6CAAI,CAAA;IACJ,+CAAK,CAAA;IACL,+CAAK,CAAA;IACL,+CAAK,CAAA;IACL,6CAAI,CAAA;IACJ,2CAAG,CAAA;IACH,2DAAW,CAAA;IACX,iDAAM,CAAA;AACR,CAAC,EAVW,WAAW,KAAX,WAAW,QAUtB;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,mDAAW,CAAA;IACX,yDAAU,CAAA;IACV,qDAAQ,CAAA;IACR,2DAAW,CAAA;AACb,CAAC,EALW,WAAW,KAAX,WAAW,QAKtB;AA+FD,qCAAqC;AACrC,MAAM,UAAU,QAAQ,CAAE,cAAuB;IAC/C,OAAO,CAAC,CAAC,cAAc,IAAI,cAAc,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;AAC5D,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,aAAa,CAAE,OAAgB,EAAE,OAAgB;IAC/D,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACtC,KAAK,MAAM,CAAC,CAAC,OAAO,WAAW,CAAC,IAAI,CAAA;QACpC,KAAK,OAAO,CAAC,CAAC,OAAO,WAAW,CAAC,KAAK,CAAA;QACtC,KAAK,YAAY,CAAC,CAAC,OAAO,WAAW,CAAC,KAAK,CAAA;QAC3C,KAAK,OAAO,CAAC;QAAC,KAAK,OAAO,CAAC,CAAC,OAAO,WAAW,CAAC,KAAK,CAAA;QACpD,KAAK,OAAO,CAAC,CAAC,OAAO,WAAW,CAAC,KAAK,CAAA;QACtC,KAAK,MAAM,CAAC,CAAC,OAAO,WAAW,CAAC,IAAI,CAAA;QACpC,KAAK,KAAK,CAAC,CAAC,OAAO,WAAW,CAAC,GAAG,CAAA;QAClC,KAAK,aAAa,CAAC,CAAC,OAAO,WAAW,CAAC,WAAW,CAAA;QAClD,KAAK,KAAK,CAAC;QAAC,KAAK,QAAQ,CAAC,CAAC,OAAO,WAAW,CAAC,MAAM,CAAA;QACpD,OAAO,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAA;IACrE,CAAC;AACH,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY;AACZ,MAAM,CAAN,IAAY,WAUX;AAVD,WAAY,WAAW;IACrB,mDAAW,CAAA;IACX,6CAAI,CAAA;IACJ,+CAAK,CAAA;IACL,+CAAK,CAAA;IACL,+CAAK,CAAA;IACL,6CAAI,CAAA;IACJ,2CAAG,CAAA;IACH,2DAAW,CAAA;IACX,iDAAM,CAAA;AACR,CAAC,EAVW,WAAW,KAAX,WAAW,QAUtB;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,mDAAW,CAAA;IACX,yDAAU,CAAA;IACV,qDAAQ,CAAA;IACR,2DAAW,CAAA;AACb,CAAC,EALW,WAAW,KAAX,WAAW,QAKtB;AAoGD,qCAAqC;AACrC,MAAM,UAAU,QAAQ,CAAE,cAAuB;IAC/C,OAAO,CAAC,CAAC,cAAc,IAAI,cAAc,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;AAC5D,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,aAAa,CAAE,OAAgB,EAAE,OAAgB;IAC/D,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACtC,KAAK,MAAM,CAAC,CAAC,OAAO,WAAW,CAAC,IAAI,CAAA;QACpC,KAAK,OAAO,CAAC,CAAC,OAAO,WAAW,CAAC,KAAK,CAAA;QACtC,KAAK,YAAY,CAAC,CAAC,OAAO,WAAW,CAAC,KAAK,CAAA;QAC3C,KAAK,OAAO,CAAC;QAAC,KAAK,OAAO,CAAC,CAAC,OAAO,WAAW,CAAC,KAAK,CAAA;QACpD,KAAK,OAAO,CAAC,CAAC,OAAO,WAAW,CAAC,KAAK,CAAA;QACtC,KAAK,MAAM,CAAC,CAAC,OAAO,WAAW,CAAC,IAAI,CAAA;QACpC,KAAK,KAAK,CAAC,CAAC,OAAO,WAAW,CAAC,GAAG,CAAA;QAClC,KAAK,aAAa,CAAC,CAAC,OAAO,WAAW,CAAC,WAAW,CAAA;QAClD,KAAK,KAAK,CAAC;QAAC,KAAK,QAAQ,CAAC,CAAC,OAAO,WAAW,CAAC,MAAM,CAAA;QACpD,OAAO,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAA;IACrE,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatboty",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "chatboty — 企业微信(WeCom)IM 自动化 SDK。自研全生态框架, 收发消息/群管理/群事件/联系人, 经云网关连接你的探针实例。",
   "type": "module",
   "main": "dist/cjs/src/mod.js",
@@ -45,6 +45,7 @@
     "ws": "^8.18.0"
   },
   "devDependencies": {
+    "@types/node": "^20.11.0",
     "@types/ws": "^8.5.10",
     "typescript": "^5.4.0"
   },

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'
@@ -47,12 +48,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 +76,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 }))
   }
 
@@ -177,10 +184,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 +235,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}>` }
 }