cc-lark 0.1.1

package/src/tools/drive/file.ts

@@ -0,0 +1,265 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * feishu_drive_file tool - Manage Feishu Drive files.
+ *
+ * Actions: list, get_meta, copy, move, delete
+ *
+ * Adapted from openclaw-lark for MCP Server architecture.
+ */
+
+import { z } from 'zod';
+import type { ToolRegistry } from '../index.js';
+import { LarkClient } from '../../core/lark-client.js';
+import { getValidAccessToken, NeedAuthorizationError } from '../../core/uat-client.js';
+import { assertLarkOk } from '../../core/api-error.js';
+import { json, jsonError, type ToolResult } from '../im/helpers.js';
+import { logger } from '../../utils/logger.js';
+
+const log = logger('tools:drive:file');
+
+// Schemas
+const listActionSchema = {
+  action: z.literal('list').describe('List files in a folder'),
+  folder_token: z.string().optional().describe('Folder token (optional, defaults to root)'),
+  page_size: z.number().min(1).max(200).optional().describe('Page size (default 200)'),
+  page_token: z.string().optional().describe('Pagination token'),
+  order_by: z.enum(['EditedTime', 'CreatedTime']).optional().describe('Sort order'),
+  direction: z.enum(['ASC', 'DESC']).optional().describe('Sort direction'),
+};
+
+const docTypeEnum = z.enum(['doc', 'sheet', 'file', 'bitable', 'docx', 'folder', 'mindnote', 'slides']);
+
+const getMetaActionSchema = {
+  action: z.literal('get_meta').describe('Get file metadata'),
+  request_docs: z.array(z.object({
+    doc_token: z.string().describe('Document token'),
+    doc_type: docTypeEnum.describe('Document type'),
+  })).min(1).max(50).describe('Documents to query'),
+};
+
+const copyActionSchema = {
+  action: z.literal('copy').describe('Copy a file'),
+  file_token: z.string().describe('File token'),
+  name: z.string().describe('New file name'),
+  type: docTypeEnum.describe('Document type'),
+  folder_token: z.string().optional().describe('Target folder token'),
+};
+
+const moveActionSchema = {
+  action: z.literal('move').describe('Move a file'),
+  file_token: z.string().describe('File token'),
+  type: docTypeEnum.describe('Document type'),
+  folder_token: z.string().describe('Target folder token'),
+};
+
+const deleteActionSchema = {
+  action: z.literal('delete').describe('Delete a file'),
+  file_token: z.string().describe('File token'),
+  type: docTypeEnum.describe('Document type'),
+};
+
+async function getAccessToken(context: { larkClient: LarkClient | null; config: import('../../core/types.js').FeishuConfig }): Promise<string | ToolResult> {
+  const { larkClient, config } = context;
+  if (!larkClient) return jsonError('LarkClient not initialized.');
+  const { appId, appSecret, brand } = config;
+  if (!appId || !appSecret) return jsonError('Missing FEISHU_APP_ID or FEISHU_APP_SECRET.');
+
+  const { listStoredTokens } = await import('../../core/token-store.js');
+  const tokens = await listStoredTokens(appId);
+  if (tokens.length === 0) return jsonError('No user authorization found. Use feishu_oauth tool first.');
+  const userOpenId = tokens[0].userOpenId;
+
+  try {
+    return await getValidAccessToken({ userOpenId, appId, appSecret, domain: brand ?? 'feishu' });
+  } catch (err) {
+    if (err instanceof NeedAuthorizationError) return jsonError('User authorization expired. Re-authorize with feishu_oauth.');
+    throw err;
+  }
+}
+
+export function registerDriveFileTool(registry: ToolRegistry): void {
+  // List files
+  registry.register({
+    name: 'feishu_drive_file_list',
+    description: 'List files in a Feishu Drive folder.\n\nRequires OAuth authorization.',
+    inputSchema: listActionSchema,
+    handler: async (args, context) => {
+      const p = args as z.infer<ReturnType<typeof z.object<typeof listActionSchema>>>;
+      const { larkClient } = context;
+
+      const tokenResult = await getAccessToken(context);
+      if (typeof tokenResult === 'object' && 'content' in tokenResult) return tokenResult;
+      const accessToken = tokenResult;
+
+      log.info(`list: folder_token=${p.folder_token || '(root)'}, page_size=${p.page_size ?? 200}`);
+
+      const Lark = await import('@larksuiteoapi/node-sdk');
+      const opts = Lark.withUserAccessToken(accessToken);
+
+      const res = await larkClient!.sdk.drive.v1.file.list(
+        {
+          params: {
+            folder_token: p.folder_token || '',
+            page_size: p.page_size,
+            page_token: p.page_token,
+            order_by: p.order_by,
+            direction: p.direction,
+          },
+        },
+        opts
+      );
+      assertLarkOk(res);
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const data = res.data as any;
+
+      return json({
+        files: data?.files,
+        has_more: data?.has_more,
+        page_token: data?.next_page_token,
+      });
+    },
+  });
+
+  // Get metadata
+  registry.register({
+    name: 'feishu_drive_file_get_meta',
+    description: 'Get metadata for Feishu documents.\n\nRequires OAuth authorization.',
+    inputSchema: getMetaActionSchema,
+    handler: async (args, context) => {
+      const p = args as z.infer<ReturnType<typeof z.object<typeof getMetaActionSchema>>>;
+      const { larkClient } = context;
+
+      if (!p.request_docs || p.request_docs.length === 0) {
+        return jsonError('request_docs must be a non-empty array');
+      }
+
+      const tokenResult = await getAccessToken(context);
+      if (typeof tokenResult === 'object' && 'content' in tokenResult) return tokenResult;
+      const accessToken = tokenResult;
+
+      log.info(`get_meta: querying ${p.request_docs.length} documents`);
+
+      const Lark = await import('@larksuiteoapi/node-sdk');
+      const opts = Lark.withUserAccessToken(accessToken);
+
+      const res = await larkClient!.sdk.drive.meta.batchQuery(
+        { data: { request_docs: p.request_docs } },
+        opts
+      );
+      assertLarkOk(res);
+
+      return json({ metas: res.data?.metas ?? [] });
+    },
+  });
+
+  // Copy file
+  registry.register({
+    name: 'feishu_drive_file_copy',
+    description: 'Copy a Feishu Drive file.\n\nRequires OAuth authorization.',
+    inputSchema: copyActionSchema,
+    handler: async (args, context) => {
+      const p = args as z.infer<ReturnType<typeof z.object<typeof copyActionSchema>>>;
+      const { larkClient } = context;
+
+      const tokenResult = await getAccessToken(context);
+      if (typeof tokenResult === 'object' && 'content' in tokenResult) return tokenResult;
+      const accessToken = tokenResult;
+
+      log.info(`copy: file_token=${p.file_token}, name=${p.name}, type=${p.type}`);
+
+      const Lark = await import('@larksuiteoapi/node-sdk');
+      const opts = Lark.withUserAccessToken(accessToken);
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const data: any = { name: p.name, type: p.type };
+      if (p.folder_token) data.folder_token = p.folder_token;
+
+      const res = await larkClient!.sdk.drive.file.copy(
+        { path: { file_token: p.file_token }, data },
+        opts
+      );
+      assertLarkOk(res);
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const fileData = res.data as any;
+
+      return json({ file: fileData?.file });
+    },
+  });
+
+  // Move file
+  registry.register({
+    name: 'feishu_drive_file_move',
+    description: 'Move a Feishu Drive file.\n\nRequires OAuth authorization.',
+    inputSchema: moveActionSchema,
+    handler: async (args, context) => {
+      const p = args as z.infer<ReturnType<typeof z.object<typeof moveActionSchema>>>;
+      const { larkClient } = context;
+
+      const tokenResult = await getAccessToken(context);
+      if (typeof tokenResult === 'object' && 'content' in tokenResult) return tokenResult;
+      const accessToken = tokenResult;
+
+      log.info(`move: file_token=${p.file_token}, type=${p.type}, folder_token=${p.folder_token}`);
+
+      const Lark = await import('@larksuiteoapi/node-sdk');
+      const opts = Lark.withUserAccessToken(accessToken);
+
+      const res = await larkClient!.sdk.drive.file.move(
+        { path: { file_token: p.file_token }, data: { type: p.type as any, folder_token: p.folder_token } },
+        opts
+      );
+      assertLarkOk(res);
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const data = res.data as any;
+
+      return json({
+        success: true,
+        task_id: data?.task_id,
+        file_token: p.file_token,
+        target_folder_token: p.folder_token,
+      });
+    },
+  });
+
+  // Delete file
+  registry.register({
+    name: 'feishu_drive_file_delete',
+    description: 'Delete a Feishu Drive file.\n\nRequires OAuth authorization.',
+    inputSchema: deleteActionSchema,
+    handler: async (args, context) => {
+      const p = args as z.infer<ReturnType<typeof z.object<typeof deleteActionSchema>>>;
+      const { larkClient } = context;
+
+      const tokenResult = await getAccessToken(context);
+      if (typeof tokenResult === 'object' && 'content' in tokenResult) return tokenResult;
+      const accessToken = tokenResult;
+
+      log.info(`delete: file_token=${p.file_token}, type=${p.type}`);
+
+      const Lark = await import('@larksuiteoapi/node-sdk');
+      const opts = Lark.withUserAccessToken(accessToken);
+
+      const res = await larkClient!.sdk.drive.file.delete(
+        { path: { file_token: p.file_token }, params: { type: p.type as any } },
+        opts
+      );
+      assertLarkOk(res);
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const data = res.data as any;
+
+      return json({
+        success: true,
+        task_id: data?.task_id,
+        file_token: p.file_token,
+      });
+    },
+  });
+
+  log.debug('feishu_drive_file tools registered');
+}

package/src/tools/drive/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Drive Tools Index
+ *
+ * Drive/file management tools for Feishu/Lark.
+ * Adapted from openclaw-lark for MCP Server architecture.
+ */
+
+import type { ToolRegistry } from '../index.js';
+import { registerDriveFileTool } from './file.js';
+import { logger } from '../../utils/logger.js';
+
+const log = logger('tools:drive');
+
+export function registerDriveTools(registry: ToolRegistry): void {
+  registerDriveFileTool(registry);
+
+  log.info('Drive tools registered', {
+    tools: [
+      'feishu_drive_file_list',
+      'feishu_drive_file_get_meta',
+      'feishu_drive_file_copy',
+      'feishu_drive_file_move',
+      'feishu_drive_file_delete',
+    ].join(', '),
+  });
+}

package/src/tools/im/format-messages.ts

@@ -0,0 +1,391 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Message formatting utilities for IM tools.
+ *
+ * Converts raw Feishu IM API message objects to AI-readable JSON format.
+ * Adapted from openclaw-lark for MCP Server architecture.
+ */
+
+import { millisStringToDateTime } from './time-utils.js';
+import { getCachedUserName, setCachedUserNames } from './helpers.js';
+import { logger } from '../../utils/logger.js';
+
+const log = logger('tools:im:format-messages');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape of a message item returned by the Feishu IM API.
+ */
+export interface ApiMessageItem {
+  message_id?: string;
+  msg_type?: string;
+  create_time?: string;
+  upper_message_id?: string;
+  body?: { content?: string };
+  sender?: {
+    id?: string;
+    sender_type?: string;
+  };
+  mentions?: Array<{
+    key: string;
+    id: unknown;
+    name?: string;
+  }>;
+  parent_id?: string;
+  thread_id?: string;
+  deleted?: boolean;
+  updated?: boolean;
+  chat_id?: string;
+}
+
+/**
+ * Formatted message structure for AI consumption.
+ */
+export interface FormattedMessage {
+  message_id: string;
+  msg_type: string;
+  content: string;
+  sender: { id: string; sender_type: string; name?: string };
+  create_time: string;
+  /** Reply message ID (parent_id). Omitted when thread_id exists since thread context is inferable */
+  reply_to?: string;
+  thread_id?: string;
+  mentions?: Array<{ key: string; id: string; name: string }>;
+  deleted: boolean;
+  updated: boolean;
+  chat_id?: string;
+  chat_type?: 'p2p' | 'group';
+  chat_name?: string;
+  chat_partner?: { open_id: string; name?: string };
+}
+
+/**
+ * Context for message content conversion.
+ */
+export interface ConvertContext {
+  messageId: string;
+  accountId?: string;
+  resolveUserName?: (openId: string) => string | undefined;
+  batchResolveNames?: (openIds: string[]) => Promise<void>;
+  fetchSubMessages?: (messageId: string) => Promise<ApiMessageItem[]>;
+}
+
+// ---------------------------------------------------------------------------
+// Mention extraction
+// ---------------------------------------------------------------------------
+
+/** Extract open_id from mention's id field (handles both object and string formats) */
+export function extractMentionOpenId(id: unknown): string {
+  if (typeof id === 'string') return id;
+  if (id != null && typeof id === 'object' && 'open_id' in id) {
+    const openId = (id as Record<string, unknown>).open_id;
+    return typeof openId === 'string' ? openId : '';
+  }
+  return '';
+}
+
+// ---------------------------------------------------------------------------
+// Message content conversion
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert raw message content to AI-readable text.
+ * This is a simplified version - full converter handles all message types.
+ */
+export function convertMessageContent(
+  raw: string,
+  msgType: string,
+  _ctx: ConvertContext
+): string {
+  if (!raw) return '';
+
+  try {
+    const parsed = JSON.parse(raw);
+
+    switch (msgType) {
+      case 'text':
+        return parsed.text || raw;
+
+      case 'post':
+      case 'rich_text': {
+        // Rich text - extract text from content blocks
+        return extractPostContent(parsed);
+      }
+
+      case 'image':
+        return `[Image: ${parsed.image_key || 'unknown'}]`;
+
+      case 'file':
+        return `[File: ${parsed.file_name || parsed.file_key || 'unknown'}]`;
+
+      case 'audio':
+        return `[Audio: ${parsed.file_name || parsed.audio_key || 'unknown'}]`;
+
+      case 'media':
+        return `[Media: ${parsed.file_name || parsed.media_key || 'unknown'}]`;
+
+      case 'sticker':
+        return `[Sticker: ${parsed.file_key || 'unknown'}]`;
+
+      case 'interactive':
+        return '[Interactive Card]';
+
+      case 'share_chat':
+        return `[Share Chat: ${parsed.chat_id || 'unknown'}]`;
+
+      case 'share_user':
+        return `[Share User: ${parsed.user_id || 'unknown'}]`;
+
+      case 'merge_forward':
+        return '[Merged Forwarded Messages]';
+
+      default:
+        return raw;
+    }
+  } catch {
+    // Not valid JSON, return as-is
+    return raw;
+  }
+}
+
+/**
+ * Extract text content from a post/rich_text message.
+ */
+function extractPostContent(parsed: Record<string, unknown>): string {
+  const sections: string[] = [];
+
+  // Handle multi-language content (zh_cn, en_us, etc.)
+  for (const lang of ['zh_cn', 'en_us']) {
+    const content = parsed[lang] as Record<string, unknown> | undefined;
+    if (!content) continue;
+
+    // Title
+    if (content.title) {
+      sections.push(String(content.title));
+    }
+
+    // Content lines
+    if (Array.isArray(content.content)) {
+      for (const line of content.content) {
+        if (Array.isArray(line)) {
+          const lineText = extractLineText(line);
+          if (lineText) sections.push(lineText);
+        }
+      }
+    }
+  }
+
+  return sections.join('\n') || JSON.stringify(parsed);
+}
+
+/**
+ * Extract text from a rich text line.
+ */
+function extractLineText(line: unknown[]): string {
+  const parts: string[] = [];
+
+  for (const element of line) {
+    if (!element || typeof element !== 'object') continue;
+    const el = element as Record<string, unknown>;
+
+    if (el.text_run) {
+      const tr = el.text_run as Record<string, unknown>;
+      if (tr.content) parts.push(String(tr.content));
+    } else if (el.mention_run) {
+      const mr = el.mention_run as Record<string, unknown>;
+      if (mr.text) parts.push(String(mr.text));
+    } else if (el.equation_run) {
+      const er = el.equation_run as Record<string, unknown>;
+      if (er.content) parts.push(`$${er.content}$`);
+    } else if (el.text) {
+      parts.push(String(el.text));
+    }
+  }
+
+  return parts.join('');
+}
+
+// ---------------------------------------------------------------------------
+// Message formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Build ConvertContext from a raw API message item.
+ */
+export function buildConvertContextFromItem(
+  item: ApiMessageItem,
+  fallbackMessageId: string,
+  accountId?: string
+): ConvertContext {
+  const mentions = new Map<string, { key: string; openId: string; name: string }>();
+  const mentionsByOpenId = new Map<string, { key: string; openId: string; name: string }>();
+
+  for (const m of item.mentions ?? []) {
+    const openId = extractMentionOpenId(m.id);
+    if (!openId) continue;
+
+    const info = {
+      key: m.key,
+      openId,
+      name: m.name ?? '',
+    };
+    mentions.set(m.key, info);
+    mentionsByOpenId.set(openId, info);
+  }
+
+  return {
+    messageId: item.message_id ?? fallbackMessageId,
+    accountId,
+    resolveUserName: accountId ? (openId) => getCachedUserName(openId) : undefined,
+  };
+}
+
+/**
+ * Format a single message item.
+ */
+export async function formatMessageItem(
+  item: ApiMessageItem,
+  accountId: string,
+  nameResolver: (openId: string) => string | undefined,
+  ctxOverrides?: Partial<ConvertContext>
+): Promise<FormattedMessage> {
+  const messageId = item.message_id ?? '';
+  const msgType = item.msg_type ?? 'unknown';
+
+  // Convert message content
+  let content = '';
+  try {
+    const rawContent = item.body?.content ?? '';
+    if (rawContent) {
+      const ctx = {
+        ...buildConvertContextFromItem(item, messageId, accountId),
+        ...ctxOverrides,
+      };
+      content = convertMessageContent(rawContent, msgType, ctx);
+    }
+  } catch (err) {
+    log.warn('Content conversion failed, using raw content', {
+      messageId,
+      msgType,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    content = item.body?.content ?? '';
+  }
+
+  // Build sender info
+  const senderId = item.sender?.id ?? '';
+  const senderType = item.sender?.sender_type ?? 'unknown';
+  let senderName: string | undefined;
+  if (senderId && senderType === 'user') {
+    senderName = nameResolver(senderId);
+  }
+
+  const sender: FormattedMessage['sender'] = {
+    id: senderId,
+    sender_type: senderType,
+  };
+  if (senderName) {
+    sender.name = senderName;
+  }
+
+  // Build mentions
+  let mentions: FormattedMessage['mentions'];
+  if (item.mentions && item.mentions.length > 0) {
+    mentions = item.mentions.map((m) => ({
+      key: m.key ?? '',
+      id: extractMentionOpenId(m.id),
+      name: m.name ?? '',
+    }));
+  }
+
+  // Convert create_time (milliseconds string to ISO 8601 +08:00)
+  const createTime = item.create_time ? millisStringToDateTime(item.create_time) : '';
+
+  const formatted: FormattedMessage = {
+    message_id: messageId,
+    msg_type: msgType,
+    content,
+    sender,
+    create_time: createTime,
+    deleted: item.deleted ?? false,
+    updated: item.updated ?? false,
+  };
+
+  // Optional fields
+  // reply_to (parent_id) and thread_id display logic:
+  // - If thread_id exists, only show thread_id (omit reply_to, thread context is inferable)
+  // - If no thread_id but has parent_id, show as reply_to
+  if (item.thread_id) {
+    formatted.thread_id = item.thread_id;
+  } else if (item.parent_id) {
+    formatted.reply_to = item.parent_id;
+  }
+  if (mentions) {
+    formatted.mentions = mentions;
+  }
+  if (item.chat_id) {
+    formatted.chat_id = item.chat_id;
+  }
+
+  return formatted;
+}
+
+/**
+ * Batch format message list.
+ *
+ * First batch resolves all sender names (writes to cache),
+ * then formats each message individually.
+ */
+export async function formatMessageList(
+  items: ApiMessageItem[],
+  accountId: string,
+  nameResolver: (openId: string) => string | undefined,
+  batchResolver: (openIds: string[]) => Promise<void>
+): Promise<FormattedMessage[]> {
+  // 1. Cache mention names (free info from API)
+  const mentionNames = new Map<string, string>();
+  for (const item of items) {
+    for (const m of item.mentions ?? []) {
+      const openId = extractMentionOpenId(m.id);
+      if (openId && m.name) {
+        mentionNames.set(openId, m.name);
+      }
+    }
+  }
+  if (mentionNames.size > 0) {
+    setCachedUserNames(mentionNames);
+  }
+
+  // 2. Collect all user sender open_ids
+  const senderIds = [
+    ...new Set(
+      items
+        .map((item) => (item.sender?.sender_type === 'user' ? item.sender.id : undefined))
+        .filter((id): id is string => !!id)
+    ),
+  ];
+
+  // 3. Batch resolve missing names
+  if (senderIds.length > 0) {
+    const missing = senderIds.filter((id) => nameResolver(id) === undefined);
+    if (missing.length > 0) {
+      await batchResolver(missing);
+    }
+  }
+
+  // 4. Format each message
+  const ctxOverrides: Partial<ConvertContext> = {
+    accountId,
+    resolveUserName: nameResolver,
+    batchResolveNames: batchResolver,
+  };
+
+  return Promise.all(
+    items.map((item) => formatMessageItem(item, accountId, nameResolver, ctxOverrides))
+  );
+}