@meet-im/meet-bot-jssdk 1.0.0 → 1.1.0

package/README.md

@@ -1,367 +1 @@
 # @meet-im/meet-bot-jssdk
-
-MeetIM Chatbot JavaScript SDK - 支持 Long Polling 消息获取、消息发送和媒体文件处理
-
-## 安装
-
-```bash
-pnpm add @meet-im/meet-bot-jssdk
-```
-
-## 快速开始
-
-### 类实例风格
-
-```typescript
-import { MeetBot } from '@meet-im/meet-bot-jssdk'
-
-const bot = new MeetBot({
-  token: 'bot_id:secret',
-  useV2: true, // 启用 getUpdatesV2，支持引用消息
-})
-
-bot.on('message', ({ message, quoteMsgMap }) => {
-  console.log('收到消息:', message.content)
-
-  // 处理引用消息
-  if (message.quoteSeqID && message.sessionInfo) {
-    const { getConvID, getQuoteMsgKey } = await import('@meet-im/meet-bot-jssdk')
-    const convID = getConvID(
-      message.sessionInfo.firstID,
-      message.sessionInfo.secondID,
-      message.sessionInfo.sessionType,
-      message.sessionInfo.companyID
-    )
-    const quoteKey = getQuoteMsgKey(convID, message.quoteSeqID)
-    const quoteMsg = quoteMsgMap[quoteKey]
-    if (quoteMsg) {
-      console.log('引用消息:', quoteMsg.content)
-    }
-  }
-
-  if (message.sessionInfo) {
-    bot.sendMessage(message.sessionInfo, { content: `收到: ${message.content}` })
-  }
-})
-
-bot.startPolling()
-```
-
-### 函数式风格
-
-```typescript
-import { getUpdatesV2, sendMessage } from '@meet-im/meet-bot-jssdk'
-
-const token = 'bot_id:secret'
-const baseUrl = 'https://staging-meet-api.miyachat.com'
-
-const { msgs, quoteMsgMap } = await getUpdatesV2({ token, baseUrl })
-
-for (const { message } of msgs) {
-  if (message.sessionInfo) {
-    console.log('收到消息:', message.content)
-
-    await sendMessage({
-      token,
-      baseUrl,
-      sessionInfo: message.sessionInfo,
-      msgContent: { content: '收到！' },
-    })
-  }
-}
-```
-
-## API 文档
-
-### MeetBot 类
-
-#### 构造函数
-
-```typescript
-new MeetBot(config: MeetBotConfig)
-```
-
-| 参数               | 类型               | 必填 | 说明                                                   |
-| ------------------ | ------------------ | ---- | ------------------------------------------------------ |
-| token              | string             | 是\* | Bot Token，格式：`bot_id:secret`                       |
-| botId              | string \| number   | 是\* | Bot ID（与 botToken 配合使用）                         |
-| botToken           | string             | 是\* | Bot Token（与 botId 配合使用）                         |
-| baseUrl            | string             | 否   | API 地址，默认 `https://staging-meet-api.miyachat.com` |
-| pollingLimit       | number             | 否   | 每次拉取消息条数，默认 100                             |
-| longPollingTimeout | number             | 否   | 长轮询超时时间（秒），默认 30                          |
-| useV2              | boolean            | 否   | 使用 getUpdatesV2 接口，默认 false                     |
-| logLevel           | 'silent' \| 'info' | 否   | 日志级别，默认 'silent'                                |
-
-\*token 或 (botId + botToken) 二选一
-
-#### 方法
-
-| 方法                                   | 说明               |
-| -------------------------------------- | ------------------ |
-| `on(event, handler)`                   | 监听事件           |
-| `off(event, handler)`                  | 移除事件监听       |
-| `startPolling(options?)`               | 启动长轮询         |
-| `stopPolling()`                        | 停止轮询           |
-| `isPolling()`                          | 获取轮询状态       |
-| `getUpdates(options?)`                 | 手动获取消息（V1） |
-| `getUpdatesV2(options?)`               | 手动获取消息（V2） |
-| `sendMessage(sessionInfo, msgContent)` | 发送消息           |
-| `getUploadURL(params)`                 | 获取单文件上传地址 |
-| `getMultiPartUploadURL(params)`        | 获取分片上传地址   |
-| `completeMultipartUpload(params)`      | 完成分片上传       |
-| `getAccessURL(params)`                 | 获取文件下载地址   |
-| `uploadFile(buffer, options)`          | 上传文件           |
-| `sendMedia(sessionInfo, options)`      | 发送媒体消息       |
-
-#### startPolling options
-
-| 参数           | 类型                     | 默认值 | 说明                           |
-| -------------- | ------------------------ | ------ | ------------------------------ |
-| timeout        | number                   | 30     | 长轮询超时时间（秒）           |
-| limit          | number                   | 100    | 每次拉取消息条数               |
-| retryDelay     | number                   | 1000   | 重试延迟基础时间（毫秒）       |
-| maxRetries     | number                   | 0      | 最大重试次数（0 表示无限重试） |
-| onOffsetUpdate | (offset: number) => void | -      | offset 更新回调                |
-
-#### 事件
-
-| 事件            | 参数                                   | 说明       |
-| --------------- | -------------------------------------- | ---------- |
-| `message`       | `{ message: MsgContent, quoteMsgMap }` | 收到新消息 |
-| `error`         | `Error`                                | 发生错误   |
-| `polling_start` | `void`                                 | 轮询开始   |
-| `polling_stop`  | `void`                                 | 轮询停止   |
-
-### 函数式 API
-
-#### getUpdates（已废弃）
-
-```typescript
-getUpdates(params: GetUpdatesParams): Promise<BotUpdate[]>
-```
-
-| 参数    | 类型   | 必填 | 默认值 | 说明                    |
-| ------- | ------ | ---- | ------ | ----------------------- |
-| token   | string | 是   | -      | Bot Token               |
-| baseUrl | string | 否   | -      | API 地址                |
-| timeout | number | 否   | 0      | Long Polling 超时（秒） |
-| offset  | number | 否   | 0      | 从该 seqId 之后获取     |
-| limit   | number | 否   | 100    | 最大返回条数            |
-
-#### getUpdatesV2（推荐）
-
-```typescript
-getUpdatesV2(params: GetUpdatesV2Params): Promise<GetUpdatesV2Result>
-```
-
-| 参数    | 类型   | 必填 | 默认值 | 说明                    |
-| ------- | ------ | ---- | ------ | ----------------------- |
-| token   | string | 是   | -      | Bot Token               |
-| baseUrl | string | 否   | -      | API 地址                |
-| timeout | number | 否   | 0      | Long Polling 超时（秒） |
-| limit   | number | 否   | 100    | 最大返回条数            |
-
-返回值：
-
-```typescript
-interface GetUpdatesV2Result {
-  msgs: { message: MsgContent }[]
-  quoteMsgMap: Record<string, MsgContent> // key: "convID:seqID"
-}
-```
-
-#### sendMessage
-
-```typescript
-sendMessage(params: SendMessageParams): Promise<SendMessageResult>
-```
-
-| 参数        | 类型        | 必填 | 说明      |
-| ----------- | ----------- | ---- | --------- |
-| token       | string      | 是   | Bot Token |
-| baseUrl     | string      | 否   | API 地址  |
-| sessionInfo | SessionInfo | 是   | 会话信息  |
-| msgContent  | MsgContent  | 是   | 消息内容  |
-
-### 媒体文件 API
-
-#### getUploadURL
-
-获取单文件上传签名地址。
-
-```typescript
-getUploadURL(params): Promise<UploadURLResult>
-```
-
-| 参数           | 类型   | 必填 | 说明             |
-| -------------- | ------ | ---- | ---------------- |
-| token          | string | 是   | Bot Token        |
-| originFileName | string | 是   | 原始文件名       |
-| contentType    | string | 是   | MIME 类型        |
-| md5            | string | 是   | 格式：`md5_hash` |
-| size           | number | 是   | 文件大小（字节） |
-
-#### getAccessURL
-
-获取文件下载地址。
-
-```typescript
-// 方式1：完整参数
-getAccessURL({ token, firstId, secondId, sessionType, seqId, fileId })
-
-// 方式2：使用 sessionInfo
-getAccessURL({ token, sessionInfo, seqId, fileId })
-```
-
-#### uploadFile
-
-上传文件（自动选择单文件或分片上传）。
-
-```typescript
-uploadFile(token, buffer, { fileName, contentType, onProgress? })
-```
-
-#### sendMedia
-
-发送媒体消息（上传并发送）。
-
-```typescript
-sendMedia(token, sessionInfo, { buffer, fileName, contentType, content?, onProgress? })
-```
-
-### 工具函数
-
-#### getConvID
-
-生成会话 ID。
-
-```typescript
-import { getConvID } from '@meet-im/meet-bot-jssdk'
-
-const convID = getConvID(firstID, secondID, sessionType, companyID?)
-```
-
-| 会话类型 | convID 格式                            |
-| -------- | -------------------------------------- |
-| 私聊 (1) | `min:max` 或 `min:max:companyID`       |
-| 群聊 (3) | `firstID+secondID` 或追加 `+companyID` |
-| 频道     | `firstID_secondID` 或追加 `_companyID` |
-
-#### getQuoteMsgKey
-
-生成引用消息的 key。
-
-```typescript
-import { getQuoteMsgKey } from '@meet-im/meet-bot-jssdk'
-
-const key = getQuoteMsgKey(convID, seqID) // "convID:seqID"
-```
-
-## 类型定义
-
-```typescript
-type SessionType = 1 | 3 // 1: 私聊, 3: 群聊
-
-interface SessionInfo {
-  firstID: number
-  secondID: number
-  sessionType: SessionType
-  companyID?: number
-}
-
-type MsgType = 'NORMAL' | 'RECALL' | 'QUOTE'
-
-interface AttachmentInfo {
-  fileID: string | number
-  fileName?: string
-  filePath?: string
-  fileSize?: number
-  mimeType?: string
-  fileUrl?: string
-}
-
-interface ExtraInfo {
-  msgType?: MsgType
-  attechmentInfo?: AttachmentInfo // 单附件
-  attechmentInfos?: AttachmentInfo[] // 多附件
-  [key: string]: unknown
-}
-
-interface MsgContent {
-  content: string
-  seqId?: number
-  timestamp?: number
-  fromUid?: number
-  atIds?: number[]
-  quoteSeqID?: number // 引用消息 seqID
-  extraInfo?: ExtraInfo
-  sessionInfo?: SessionInfo
-}
-
-interface BotUpdate {
-  message?: MsgContent
-}
-
-interface GetUpdatesV2Result {
-  msgs: { message: MsgContent }[]
-  quoteMsgMap: Record<string, MsgContent>
-}
-
-interface SendMessageResult {
-  msgContent: MsgContent
-  quoteMsg: unknown
-  userProfileMap: Record<number, unknown>
-}
-```
-
-## 错误处理
-
-SDK 提供以下错误类型：
-
-| 错误类            | 说明           |
-| ----------------- | -------------- |
-| `MeetBotError`    | 基础错误类     |
-| `ApiError`        | API 返回的错误 |
-| `NetworkError`    | 网络连接错误   |
-| `TimeoutError`    | 请求超时错误   |
-| `ValidationError` | 参数验证错误   |
-
-```typescript
-import { ApiError, NetworkError } from '@meet-im/meet-bot-jssdk'
-
-try {
-  await bot.sendMessage(sessionInfo, { content: 'Hello' })
-} catch (error) {
-  if (error instanceof ApiError) {
-    console.error('API 错误:', error.code, error.statusCode)
-  } else if (error instanceof NetworkError) {
-    console.error('网络错误:', error.message)
-  }
-}
-```
-
-## 开发
-
-```bash
-# 安装依赖
-pnpm install
-
-# 构建
-pnpm build
-
-# 测试
-pnpm test
-
-# 类型检查
-pnpm typecheck
-
-# 代码格式化
-pnpm format
-
-# 代码检查
-pnpm lint
-```
-
-## License
-
-MIT

package/dist/index.cjs

@@ -50,16 +50,34 @@ var init_error = __esm({
     };
     exports.NetworkError = class extends exports.MeetBotError {
       cause;
-      constructor(message, cause) {
+      /**
+       * HTTP 状态码（如果有的话）
+       * 例如：504 表示网关超时，0 表示无 HTTP 响应
+       */
+      httpStatus;
+      /**
+       * 响应内容片段（用于调试）
+       */
+      responseSnippet;
+      constructor(message, cause, httpStatus, responseSnippet) {
         super(message, "NETWORK_ERROR");
         this.name = "NetworkError";
         this.cause = cause;
+        this.httpStatus = httpStatus;
+        this.responseSnippet = responseSnippet;
       }
     };
     exports.TimeoutError = class extends exports.MeetBotError {
-      constructor(message) {
+      /**
+       * 是否为本地客户端超时（AbortController 触发）
+       * true: 本地 HTTP 请求超时
+       * false: 服务端/网关返回的超时（如 504 Gateway Timeout）
+       */
+      isLocal;
+      constructor(message, isLocal = true) {
         super(message, "TIMEOUT_ERROR");
         this.name = "TimeoutError";
+        this.isLocal = isLocal;
       }
     };
     exports.ValidationError = class extends exports.MeetBotError {
@@ -202,8 +220,8 @@ function extractBotToken(token) {
   const parts = token.split(":");
   return parts.length >= 2 ? parts.slice(1).join(":") : token;
 }
-function buildUrl(baseUrl, path, params) {
-  const url = new URL(`/im/bot/${path}`, baseUrl);
+function buildUrl(baseUrl, path, pathPrefix, params) {
+  const url = new URL(`${pathPrefix}${path}`, baseUrl);
   if (params) {
     for (const [key, value] of Object.entries(params)) {
       if (value !== void 0) {
@@ -214,9 +232,19 @@ function buildUrl(baseUrl, path, params) {
   return url.toString();
 }
 async function request(options) {
-  const { token, baseUrl, method = "GET", path, params, body, timeout = HTTP.DEFAULT_TIMEOUT } = options;
+  const {
+    token,
+    baseUrl,
+    method = "GET",
+    path,
+    pathPrefix = "/im/bot/",
+    params,
+    body,
+    timeout = HTTP.DEFAULT_TIMEOUT,
+    raw = false
+  } = options;
   validateToken(token);
-  const url = buildUrl(baseUrl || DEFAULT_BASE_URL, path, method === "GET" ? params : void 0);
+  const url = buildUrl(baseUrl || DEFAULT_BASE_URL, path, pathPrefix, method === "GET" ? params : void 0);
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeout);
   const headers = {
@@ -245,18 +273,40 @@ async function request(options) {
     const responseText = await response.text();
     if (!contentType.includes("application/json")) {
       logger.error("[Response] Non-JSON response:", responseText.substring(0, 500));
-      throw new exports.NetworkError(`Server returned non-JSON response (status ${response.status})`, void 0);
+      if (response.status === 504) {
+        throw new exports.TimeoutError(`Gateway timeout (status ${response.status})`, false);
+      }
+      throw new exports.NetworkError(
+        `Server returned non-JSON response (status ${response.status})`,
+        void 0,
+        response.status,
+        responseText.substring(0, 200)
+      );
     }
     let data;
     try {
       data = JSON.parse(responseText);
     } catch {
       logger.error("[Response] Failed to parse JSON:", responseText.substring(0, 500));
-      throw new exports.NetworkError("Failed to parse server response", void 0);
+      throw new exports.NetworkError(
+        "Failed to parse server response",
+        void 0,
+        response.status,
+        responseText.substring(0, 200)
+      );
     }
     logger.info("[Response Body]", JSON.stringify(data));
+    if (raw) {
+      return data;
+    }
     if (!response.ok || !data.ok) {
       const errorData = data;
+      if (response.status === 504) {
+        throw new exports.TimeoutError(
+          errorData.description || `Gateway timeout (status ${response.status})`,
+          false
+        );
+      }
       throw new exports.ApiError(
         errorData.description || `HTTP ${response.status}`,
         response.status,
@@ -272,7 +322,7 @@ async function request(options) {
     }
     if (error instanceof Error) {
       if (error.name === "AbortError") {
-        throw new exports.TimeoutError(`Request timeout after ${timeout}ms`);
+        throw new exports.TimeoutError(`Request timeout after ${timeout}ms`, true);
       }
       throw new exports.NetworkError(`Network error: ${error.message}`, error);
     }
@@ -547,6 +597,25 @@ async function sendMediaMessage(token, sessionInfo, options, baseUrl) {
   });
 }
 
+// src/api/user.ts
+async function getUsers(params) {
+  const { token, baseUrl } = params;
+  const result = await request({
+    token,
+    baseUrl,
+    method: "POST",
+    path: "general/SyncCompanyUser",
+    pathPrefix: "/",
+    body: { syncAt: 0 },
+    timeout: HTTP.DEFAULT_TIMEOUT,
+    raw: true
+  });
+  return Object.values(result.users).map((user) => ({
+    userID: user.userID,
+    nickName: user.nickName
+  }));
+}
+
 // src/api/index.ts
 async function getUpdates(params) {
   const { token, baseUrl, timeout = API.DEFAULT_TIMEOUT, offset, limit = API.DEFAULT_LIMIT } = params;
@@ -599,6 +668,115 @@ async function sendMessage(params) {
 
 // src/client.ts
 init_error();
+
+// src/user-cache.ts
+var UserCache = class {
+  byId = /* @__PURE__ */ new Map();
+  byNickName = /* @__PURE__ */ new Map();
+  byAliasName = /* @__PURE__ */ new Map();
+  loadedAt = 0;
+  ttl;
+  loading = null;
+  constructor(options) {
+    this.ttl = options?.ttl ?? 60 * 60 * 1e3;
+  }
+  isExpired() {
+    return this.byId.size === 0 || this.ttl > 0 && Date.now() - this.loadedAt > this.ttl;
+  }
+  async load(fetchAll) {
+    if (this.loading) {
+      return this.loading;
+    }
+    this.loading = (async () => {
+      try {
+        const users = await fetchAll();
+        this.rebuild(users);
+        logger.info(`\u7528\u6237\u7F13\u5B58\u5DF2\u52A0\u8F7D\uFF0C\u5171 ${users.length} \u4E2A\u7528\u6237`);
+      } finally {
+        this.loading = null;
+      }
+    })();
+    return this.loading;
+  }
+  rebuild(users) {
+    this.byId.clear();
+    this.byNickName.clear();
+    this.byAliasName.clear();
+    for (const user of users) {
+      this.byId.set(user.userID, user);
+      const nickKey = user.nickName.toLowerCase();
+      let nickList = this.byNickName.get(nickKey);
+      if (!nickList) {
+        nickList = [];
+        this.byNickName.set(nickKey, nickList);
+      }
+      nickList.push(user);
+      if (user.aliasName) {
+        const aliasKey = user.aliasName.toLowerCase();
+        let aliasList = this.byAliasName.get(aliasKey);
+        if (!aliasList) {
+          aliasList = [];
+          this.byAliasName.set(aliasKey, aliasList);
+        }
+        aliasList.push(user);
+      }
+    }
+    this.loadedAt = Date.now();
+  }
+  async ensureLoaded(fetchAll) {
+    if (!this.isExpired()) return;
+    await this.load(fetchAll);
+  }
+  getById(userId) {
+    return this.byId.get(userId);
+  }
+  getByIds(userIds) {
+    const result = /* @__PURE__ */ new Map();
+    for (const id of userIds) {
+      const user = this.byId.get(id);
+      if (user) {
+        result.set(id, user);
+      }
+    }
+    return result;
+  }
+  getByName(name) {
+    const key = name.toLowerCase();
+    const byNick = this.byNickName.get(key);
+    const byAlias = this.byAliasName.get(key);
+    if (!byNick && !byAlias) return [];
+    if (!byNick) return [...byAlias];
+    if (!byAlias) return [...byNick];
+    const seen = /* @__PURE__ */ new Set();
+    const result = [];
+    for (const u of [...byNick, ...byAlias]) {
+      if (!seen.has(u.userID)) {
+        seen.add(u.userID);
+        result.push(u);
+      }
+    }
+    return result;
+  }
+  searchByName(query) {
+    const q = query.toLowerCase();
+    const result = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const user of this.byId.values()) {
+      if (user.nickName.toLowerCase().includes(q) || user.aliasName && user.aliasName.toLowerCase().includes(q) || user.nickNamePinyin && user.nickNamePinyin.toLowerCase().includes(q) || user.aliasNamePinyin && user.aliasNamePinyin.toLowerCase().includes(q)) {
+        if (!seen.has(user.userID)) {
+          seen.add(user.userID);
+          result.push(user);
+        }
+      }
+    }
+    return result;
+  }
+  get size() {
+    return this.byId.size;
+  }
+};
+
+// src/client.ts
 var MeetBot = class {
   token;
   baseUrl;
@@ -609,6 +787,7 @@ var MeetBot = class {
   polling = false;
   offset = 0;
   abortController = null;
+  userCache;
   constructor(config) {
     if (config.token) {
       if (!config.token.includes(":")) {
@@ -624,6 +803,7 @@ var MeetBot = class {
     this.pollingLimit = config.pollingLimit ?? POLLING.DEFAULT_LIMIT;
     this.longPollingTimeout = config.longPollingTimeout ?? POLLING.DEFAULT_TIMEOUT;
     this.useV2 = config.useV2 ?? false;
+    this.userCache = new UserCache(config.userCacheOptions);
     logger.setLevel(config.logLevel ?? "silent");
   }
   on(event, handler) {
@@ -805,6 +985,56 @@ var MeetBot = class {
   async sendMedia(sessionInfo, options) {
     return sendMediaMessage(this.token, sessionInfo, options, this.baseUrl);
   }
+  /**
+   * 刷新用户缓存
+   */
+  async refreshUserCache() {
+    await this.userCache.load(async () => {
+      return getUsers({ token: this.token, baseUrl: this.baseUrl });
+    });
+  }
+  /**
+   * 根据用户 ID 获取用户信息
+   */
+  async getUserById(userId) {
+    await this.userCache.ensureLoaded(async () => {
+      return getUsers({ token: this.token, baseUrl: this.baseUrl });
+    });
+    return this.userCache.getById(userId);
+  }
+  /**
+   * 批量根据用户 ID 获取用户信息
+   */
+  async getUserByIds(userIds) {
+    await this.userCache.ensureLoaded(async () => {
+      return getUsers({ token: this.token, baseUrl: this.baseUrl });
+    });
+    return this.userCache.getByIds(userIds);
+  }
+  /**
+   * 根据昵称或别名精确查找用户
+   */
+  async getUserByName(name) {
+    await this.userCache.ensureLoaded(async () => {
+      return getUsers({ token: this.token, baseUrl: this.baseUrl });
+    });
+    return this.userCache.getByName(name);
+  }
+  /**
+   * 根据昵称或别名模糊搜索用户
+   */
+  async searchUserByName(query) {
+    await this.userCache.ensureLoaded(async () => {
+      return getUsers({ token: this.token, baseUrl: this.baseUrl });
+    });
+    return this.userCache.searchByName(query);
+  }
+  /**
+   * 获取缓存用户数
+   */
+  get userCacheSize() {
+    return this.userCache.size;
+  }
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
@@ -821,6 +1051,7 @@ exports.MeetBot = MeetBot;
 exports.POLLING = POLLING;
 exports.SESSION_TYPE = SESSION_TYPE;
 exports.UPLOAD = UPLOAD;
+exports.UserCache = UserCache;
 exports.completeMultipartUpload = completeMultipartUpload;
 exports.computeMD5 = computeMD5;
 exports.getAccessURL = getAccessURL;
@@ -831,8 +1062,7 @@ exports.getQuoteMsgKey = getQuoteMsgKey;
 exports.getUpdates = getUpdates;
 exports.getUpdatesV2 = getUpdatesV2;
 exports.getUploadURL = getUploadURL;
+exports.getUsers = getUsers;
 exports.sendMediaMessage = sendMediaMessage;
 exports.sendMessage = sendMessage;
 exports.uploadFile = uploadFile;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map