feishu-user-plugin 1.3.6 → 1.3.8

package/src/tools/im-read.js

@@ -0,0 +1,259 @@
+// src/tools/im-read.js — IM read paths (chat list, message history, P2P).
+
+const { text, json } = require('./_registry');
+
+// ChatIdMapper — fuzzy chat-id resolver shared across im-read handlers.
+// Moved from src/index.js in v1.3.7 phase A. Only read_messages uses it,
+// so it lives here as a module-level singleton.
+class ChatIdMapper {
+  constructor() {
+    this.nameCache = new Map(); // oc_id → chat name
+    this.lastRefresh = 0;
+    this.TTL = 5 * 60 * 1000; // 5 min cache
+  }
+
+  async _refresh(official) {
+    if (Date.now() - this.lastRefresh < this.TTL) return;
+    try {
+      const chats = await official.listAllChats();
+      this.nameCache.clear();
+      for (const chat of chats) {
+        this.nameCache.set(chat.chat_id, chat.name || '');
+      }
+      this.lastRefresh = Date.now();
+    } catch (e) {
+      console.error('[feishu-user-plugin] ChatIdMapper refresh failed:', e.message);
+    }
+  }
+
+  // Case-insensitive name matching helper
+  static _nameMatch(haystack, needle, exact = false) {
+    if (!haystack || !needle) return false;
+    const h = haystack.toLowerCase(), n = needle.toLowerCase();
+    return exact ? h === n : h.includes(n);
+  }
+
+  async findByName(name, official) {
+    await this._refresh(official);
+    // Exact match first (case-insensitive)
+    for (const [ocId, chatName] of this.nameCache) {
+      if (ChatIdMapper._nameMatch(chatName, name, true)) return ocId;
+    }
+    // Partial match (case-insensitive)
+    for (const [ocId, chatName] of this.nameCache) {
+      if (ChatIdMapper._nameMatch(chatName, name)) return ocId;
+    }
+    return null;
+  }
+
+  async resolveToOcId(chatIdOrName, official) {
+    if (!chatIdOrName) return null;
+    if (chatIdOrName.startsWith('oc_')) return chatIdOrName;
+    // Also accept raw numeric IDs (from search_contacts)
+    if (/^\d+$/.test(chatIdOrName)) return chatIdOrName;
+    // Strategy 1: Search in bot's group list cache
+    const cached = await this.findByName(chatIdOrName, official);
+    if (cached) return cached;
+    // Strategy 2: Use im.v1.chat.search API (finds groups even if not in cache)
+    try {
+      const results = await official.chatSearch(chatIdOrName);
+      for (const chat of results) {
+        this.nameCache.set(chat.chat_id, chat.name || '');
+        if (ChatIdMapper._nameMatch(chat.name, chatIdOrName, true)) return chat.chat_id;
+      }
+      // Partial match on search results (case-insensitive)
+      for (const chat of results) {
+        if (ChatIdMapper._nameMatch(chat.name, chatIdOrName)) return chat.chat_id;
+      }
+    } catch (e) {
+      console.error('[feishu-user-plugin] chatSearch fallback failed:', e.message);
+    }
+    return null;
+  }
+
+  // Strategy 3: Use search_contacts (cookie-based) to find external groups by name
+  // Returns numeric chat_id that works with UAT readMessagesAsUser
+  async resolveViaContacts(chatName, userClient) {
+    if (!userClient) return null;
+    try {
+      const results = await userClient.search(chatName);
+      const groups = results.filter(r => r.type === 'group');
+      // Exact match first (case-insensitive)
+      for (const g of groups) {
+        if (ChatIdMapper._nameMatch(g.title, chatName, true)) return String(g.id);
+      }
+      // Partial match (case-insensitive)
+      for (const g of groups) {
+        if (ChatIdMapper._nameMatch(g.title, chatName)) return String(g.id);
+      }
+    } catch (e) {
+      console.error('[feishu-user-plugin] search_contacts fallback failed:', e.message);
+    }
+    return null;
+  }
+}
+
+const chatIdMapper = new ChatIdMapper();
+
+const schemas = [
+  {
+    name: 'get_chat_info',
+    description: '[Official API + User Identity fallback] Get chat details: name, description, member count, owner. Supports both oc_xxx and numeric chat_id.',
+    inputSchema: {
+      type: 'object',
+      properties: { chat_id: { type: 'string', description: 'Chat ID (oc_xxx or numeric)' } },
+      required: ['chat_id'],
+    },
+  },
+  {
+    name: 'read_p2p_messages',
+    description: '[User UAT] Read P2P (direct message) chat history using user_access_token. Works for chats the bot cannot access. Returns newest messages first by default. Auto-expands merge_forward messages into their child messages by default — disable with expand_merge_forward=false. Requires OAuth setup.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Chat ID (numeric from create_p2p_chat, or oc_xxx from list_user_chats). Both formats work.' },
+        page_size: { type: 'number', description: 'Messages to fetch (default 20, max 50)' },
+        start_time: { type: 'string', description: 'Start timestamp in seconds (optional)' },
+        end_time: { type: 'string', description: 'End timestamp in seconds (optional)' },
+        sort_type: { type: 'string', enum: ['ByCreateTimeDesc', 'ByCreateTimeAsc'], description: 'Sort order (default: ByCreateTimeDesc = newest first)' },
+        expand_merge_forward: { type: 'boolean', description: 'Auto-expand merge_forward placeholders into their child messages (default true). Children carry parentMessageId; use that id (not the child id) with download_message_resource (kind=image or file).' },
+      },
+      required: ['chat_id'],
+    },
+  },
+  {
+    name: 'list_user_chats',
+    description: '[User UAT] List group chats the user is in. Note: only returns groups, not P2P. For P2P chats, use search_contacts → create_p2p_chat → read_p2p_messages. Requires OAuth setup.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page_size: { type: 'number', description: 'Items per page (default 20)' },
+        page_token: { type: 'string', description: 'Pagination token' },
+      },
+    },
+  },
+  {
+    name: 'list_chats',
+    description: '[Official API] List all chats the bot has joined. Returns chat_id, name, type.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page_size: { type: 'number', description: 'Items per page (default 20, max 100)' },
+        page_token: { type: 'string', description: 'Pagination token' },
+      },
+    },
+  },
+  {
+    name: 'read_messages',
+    description: '[Official API + UAT fallback] Read message history from any group. Accepts oc_xxx ID, numeric ID, or chat name (auto-searched). Auto-falls back to UAT for external groups the bot cannot access. Returns newest messages first by default, with sender names resolved. Auto-expands merge_forward messages into their child messages (with original sender / time / content preserved) by default — disable with expand_merge_forward=false. Text messages have URLs extracted into `urls`; Feishu doc links are additionally surfaced as `feishuDocs` so agents can feed them straight into read_doc / get_doc_blocks.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Chat ID (oc_xxx), numeric ID, or chat name (auto-searched via bot groups, im.chat.search, and user contacts)' },
+        page_size: { type: 'number', description: 'Messages to fetch (default 20, max 50)' },
+        start_time: { type: 'string', description: 'Start timestamp in seconds (optional)' },
+        end_time: { type: 'string', description: 'End timestamp in seconds (optional)' },
+        sort_type: { type: 'string', enum: ['ByCreateTimeDesc', 'ByCreateTimeAsc'], description: 'Sort order (default: ByCreateTimeDesc = newest first)' },
+        expand_merge_forward: { type: 'boolean', description: 'Auto-expand merge_forward placeholders into their child messages (default true). Children carry parentMessageId; use that id (not the child id) with download_message_resource (kind=image or file).' },
+      },
+      required: ['chat_id'],
+    },
+  },
+];
+
+const handlers = {
+  async get_chat_info(args, ctx) {
+    // Strategy 1: Official API im.chat.get (supports oc_xxx format)
+    if (args.chat_id.startsWith('oc_')) {
+      try {
+        const info = await ctx.getOfficialClient().getChatInfo(args.chat_id);
+        return info ? json(info) : text(`No info for chat ${args.chat_id}`);
+      } catch (e) {
+        console.error(`[feishu-user-plugin] Official getChatInfo failed: ${e.message}`);
+      }
+    }
+    // Strategy 2: Protobuf gateway (supports numeric chat_id)
+    try {
+      const c = await ctx.getUserClient();
+      const info = await c.getGroupInfo(args.chat_id);
+      if (info) return json(info);
+    } catch (e) {
+      console.error(`[feishu-user-plugin] Protobuf getChatInfo failed: ${e.message}`);
+    }
+    return text(`No info for chat ${args.chat_id}`);
+  },
+
+  async read_p2p_messages(args, ctx) {
+    const official = ctx.getOfficialClient();
+    let chatId = args.chat_id;
+    let uc = null;
+    let ucError = null;
+    try { uc = await ctx.getUserClient(); } catch (e) { ucError = e; }
+    // If chat_id is not numeric or oc_, try to resolve as user name → P2P chat
+    if (!/^\d+$/.test(chatId) && !chatId.startsWith('oc_')) {
+      if (uc) {
+        const results = await uc.search(chatId);
+        const user = results.find(r => r.type === 'user');
+        if (user) {
+          const pChatId = await uc.createChat(String(user.id));
+          if (pChatId) chatId = String(pChatId);
+          else return text(`Found user "${user.title}" but failed to create P2P chat.`);
+        } else {
+          // Maybe it's a group name
+          const group = results.find(r => r.type === 'group');
+          if (group) chatId = String(group.id);
+          else return text(`Cannot resolve "${args.chat_id}" to a chat. Use search_contacts to find the ID first.`);
+        }
+      } else {
+        const hint = ucError ? `Cookie auth failed: ${ucError.message}. Fix LARK_COOKIE first, or p` : 'P';
+        return text(`"${args.chat_id}" is not a valid chat ID. ${hint}rovide a numeric ID or oc_xxx format. Use search_contacts + create_p2p_chat to get the ID.`);
+      }
+    }
+    return json(await official.readMessagesAsUser(chatId, {
+      pageSize: args.page_size, startTime: args.start_time, endTime: args.end_time,
+      sortType: args.sort_type,
+      expandMergeForward: args.expand_merge_forward !== false,
+    }, uc));
+  },
+
+  async list_user_chats(args, ctx) {
+    return json(await ctx.getOfficialClient().listChatsAsUser({ pageSize: args.page_size, pageToken: args.page_token }));
+  },
+
+  async list_chats(args, ctx) {
+    return json(await ctx.getOfficialClient().listChats({ pageSize: args.page_size, pageToken: args.page_token }));
+  },
+
+  async read_messages(args, ctx) {
+    const official = ctx.getOfficialClient();
+    const msgOpts = {
+      pageSize: args.page_size, startTime: args.start_time, endTime: args.end_time,
+      sortType: args.sort_type,
+      expandMergeForward: args.expand_merge_forward !== false,
+    };
+    // Get userClient for name resolution fallback (best-effort)
+    let uc = null;
+    try { uc = await ctx.getUserClient(); } catch (_) {}
+
+    // Path A — chat_id that resolves inside bot's / official search scope.
+    const resolvedChatId = await chatIdMapper.resolveToOcId(args.chat_id, official);
+    if (resolvedChatId) {
+      return json(await official.readMessagesWithFallback(resolvedChatId, msgOpts, uc));
+    }
+
+    // Path B — external group discovered only via cookie search_contacts.
+    // When we got here the bot definitely can't see it, so skip bot entirely
+    // and go straight to UAT with a `contacts` via label.
+    if (official.hasUAT) {
+      if (!uc) try { uc = await ctx.getUserClient(); } catch (_) {}
+      const contactChatId = await chatIdMapper.resolveViaContacts(args.chat_id, uc);
+      if (contactChatId) {
+        return json(await official.readMessagesWithFallback(contactChatId, msgOpts, uc, { skipBot: true, via: 'contacts' }));
+      }
+    }
+
+    return text(`Cannot resolve "${args.chat_id}" to a chat ID.\nSearched: bot's group list, im.chat.search API, and user contacts (search_contacts).\nTry: provide the oc_xxx or numeric chat ID directly.`);
+  },
+};
+
+module.exports = { schemas, handlers };

package/src/tools/messaging-bot.js

@@ -0,0 +1,151 @@
+// src/tools/messaging-bot.js — Bot-identity messaging operations (send, reply,
+// forward, delete, update, pin, reactions). send_card_as_user is intentionally
+// kept inline in src/index.js until v1.3.7's user-identity card path lands; it
+// will move to src/tools/messaging-user.js together with that work.
+
+const { text, json } = require('./_registry');
+
+const schemas = [
+  {
+    name: 'send_message_as_bot',
+    description: '[Official API] Send a message as the bot to any chat. Supports text, post, interactive, etc. This is the reliable path for @-mentions: include `<at user_id="ou_xxx">Name</at>` inline in text content and Feishu resolves it to a real @-notification.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Target chat_id (oc_xxx) or open_id' },
+        msg_type: { type: 'string', description: 'Message type: text, post, image, interactive, etc.', enum: ['text', 'post', 'image', 'interactive', 'share_chat', 'share_user', 'audio', 'media', 'file', 'sticker'] },
+        content: { description: 'Message content (string or object, auto-serialized). Plain text: {"text":"hello"}. Text with @-mention: {"text":"<at user_id=\\"ou_xxx\\">Alice</at> hi"} — the inline tag becomes a real @-notification.' },
+      },
+      required: ['chat_id', 'msg_type', 'content'],
+    },
+  },
+  {
+    name: 'reply_message',
+    description: '[Official API] Reply to a specific message by message_id (as bot). Only works for text messages; other types return error 230054.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message_id: { type: 'string', description: 'Message ID to reply to (om_xxx)' },
+        text: { type: 'string', description: 'Reply text' },
+      },
+      required: ['message_id', 'text'],
+    },
+  },
+  {
+    name: 'forward_message',
+    description: '[Official API] Forward a message to another chat or user. `receive_id` may be a group chat_id (oc_xxx), an open_id (ou_xxx), a union_id, a user_id, or an email — set `receive_id_type` to match (default: chat_id).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message_id: { type: 'string', description: 'Message ID to forward (om_xxx)' },
+        receive_id: { type: 'string', description: 'Target chat_id (oc_xxx), open_id (ou_xxx), union_id, user_id, or email — set receive_id_type to match.' },
+        receive_id_type: { type: 'string', enum: ['chat_id', 'open_id', 'union_id', 'user_id', 'email'], description: 'Format of receive_id (default: chat_id). Set to "open_id" when forwarding to a user via their open_id.', default: 'chat_id' },
+      },
+      required: ['message_id', 'receive_id'],
+    },
+  },
+  {
+    name: 'delete_message',
+    description: '[Official API] Recall/delete a message (bot can only delete its own messages).',
+    inputSchema: {
+      type: 'object',
+      properties: { message_id: { type: 'string', description: 'Message ID (om_xxx)' } },
+      required: ['message_id'],
+    },
+  },
+  {
+    name: 'update_message',
+    description: '[Official API] Edit a sent message (bot can only edit its own messages). Feishu supports edit only for `text` and `interactive` (card) messages — other types (post, image, file, etc.) are rejected by the API.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message_id: { type: 'string', description: 'Message ID (om_xxx)' },
+        msg_type: { type: 'string', enum: ['text', 'interactive'], description: 'Message type: text or interactive. Other types are not editable per Feishu API.' },
+        content: { description: 'New content. For text: {"text":"updated text"}. For interactive: full card JSON.' },
+      },
+      required: ['message_id', 'msg_type', 'content'],
+    },
+  },
+  {
+    name: 'pin_message',
+    description: '[Official API] Pin or unpin a message in a chat.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message_id: { type: 'string', description: 'Message ID' },
+        pinned: { type: 'boolean', description: 'true to pin, false to unpin', default: true },
+      },
+      required: ['message_id'],
+    },
+  },
+  {
+    name: 'add_reaction',
+    description: '[Official API] Add an emoji reaction to a message.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message_id: { type: 'string', description: 'Message ID (om_xxx)' },
+        emoji_type: { type: 'string', description: 'Emoji type string, e.g. "THUMBSUP", "SMILE", "HEART"' },
+      },
+      required: ['message_id', 'emoji_type'],
+    },
+  },
+  {
+    name: 'delete_reaction',
+    description: '[Official API] Remove an emoji reaction from a message.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message_id: { type: 'string', description: 'Message ID' },
+        reaction_id: { type: 'string', description: 'Reaction ID (from add_reaction response)' },
+      },
+      required: ['message_id', 'reaction_id'],
+    },
+  },
+];
+
+const handlers = {
+  async send_message_as_bot(args, ctx) {
+    const r = await ctx.getOfficialClient().sendMessageAsBot(args.chat_id, args.msg_type, args.content);
+    return text(`Message sent (bot): ${r.messageId}`);
+  },
+  async reply_message(args, ctx) {
+    return text(`Reply sent: ${(await ctx.getOfficialClient().replyMessage(args.message_id, args.text)).messageId}`);
+  },
+  async forward_message(args, ctx) {
+    // Auto-detect receive_id_type when not provided so callers can pass an open_id
+    // (ou_xxx) without having to set the type field — matches what
+    // send_to_user/send_to_group already do for chat resolution.
+    let receiveIdType = args.receive_id_type;
+    if (!receiveIdType) {
+      const id = args.receive_id || '';
+      if (id.startsWith('ou_')) receiveIdType = 'open_id';
+      else if (id.startsWith('on_')) receiveIdType = 'union_id';
+      else if (id.includes('@')) receiveIdType = 'email';
+      else receiveIdType = 'chat_id';
+    }
+    return text(`Forwarded: ${(await ctx.getOfficialClient().forwardMessage(args.message_id, args.receive_id, receiveIdType)).messageId}`);
+  },
+  async delete_message(args, ctx) {
+    return text(`Message deleted: ${(await ctx.getOfficialClient().deleteMessage(args.message_id)).deleted}`);
+  },
+  async update_message(args, ctx) {
+    // Feishu API limit: only text + interactive are editable. Reject early so
+    // the user sees a clear message instead of a 230053 from the API.
+    if (!['text', 'interactive'].includes(args.msg_type)) {
+      return text(`update_message only supports msg_type=text or interactive (Feishu API limit). Got: ${args.msg_type}`);
+    }
+    return text(`Message updated: ${(await ctx.getOfficialClient().updateMessage(args.message_id, args.msg_type, args.content)).messageId}`);
+  },
+  async pin_message(args, ctx) {
+    return json(await ctx.getOfficialClient().pinMessage(args.message_id, args.pinned !== false));
+  },
+  async add_reaction(args, ctx) {
+    return text(`Reaction added: ${(await ctx.getOfficialClient().addReaction(args.message_id, args.emoji_type)).reactionId}`);
+  },
+  async delete_reaction(args, ctx) {
+    return text(`Reaction removed: ${(await ctx.getOfficialClient().deleteReaction(args.message_id, args.reaction_id)).deleted}`);
+  },
+};
+
+module.exports = { schemas, handlers };