feishu-user-plugin 1.3.5 → 1.3.7

package/src/tools/bitable.js

@@ -0,0 +1,246 @@
+// src/tools/bitable.js — Bitable (multi-dimensional table) operations.
+//
+// 5 consolidated tools (replaces 19 in v1.3.6):
+//   manage_bitable_app    — actions: create, copy, get_meta
+//   manage_bitable_table  — actions: list, create, update, delete
+//   manage_bitable_field  — actions: list, create, update, delete
+//   manage_bitable_view   — actions: list, create, delete
+//   manage_bitable_record — actions: search, get, create, update, delete (records arg is array; max 500)
+//
+// The action= discriminator routes to the existing client methods unchanged;
+// this file is just a tool-surface compaction.
+
+const { text, json } = require('./_registry');
+
+const FIELD_TYPE_NOTE = '1=Text, 2=Number, 3=SingleSelect, 4=MultiSelect, 5=DateTime, 7=Checkbox, 11=User, 13=Phone, 15=URL, 17=Attachment, 18=Link, 20=Formula, 21=DuplexLink, 22=Location, 23=GroupChat, 1001=CreateTime, 1002=ModifiedTime, 1003=Creator, 1004=Modifier';
+
+const schemas = [
+  {
+    name: 'manage_bitable_app',
+    description: '[Official API] Manage a Bitable app. action=create (new app, optional wiki_space_id to attach), copy (duplicate an existing app), get_meta (read app metadata).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['create', 'copy', 'get_meta'], description: 'Operation to perform' },
+        app_token: { type: 'string', description: 'Required for copy/get_meta. Native token, wiki node, or Feishu URL.' },
+        name: { type: 'string', description: 'New app name. Required for create/copy.' },
+        folder_id: { type: 'string', description: 'Destination folder token (optional for create/copy; ignored when wiki_space_id is set).' },
+        wiki_space_id: { type: 'string', description: 'Wiki space ID — create the app directly under this space (create only).' },
+        wiki_parent_node_token: { type: 'string', description: 'Parent wiki node within the space (optional for create).' },
+      },
+      required: ['action'],
+    },
+  },
+  {
+    name: 'manage_bitable_table',
+    description: '[Official API] Manage a table inside a Bitable app. action=list, create (with optional initial fields), update (rename), delete.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['list', 'create', 'update', 'delete'], description: 'Operation to perform' },
+        app_token: { type: 'string', description: 'Bitable app token (required for all actions). Accepts native token, wiki node, or Feishu URL.' },
+        table_id: { type: 'string', description: 'Table ID — required for update/delete.' },
+        name: { type: 'string', description: 'Table name — required for create, optional for update (rename).' },
+        fields: {
+          type: 'array',
+          description: `Initial field definitions (create only, optional). Each item: {field_name, type, property?} where type is ${FIELD_TYPE_NOTE}.`,
+          items: { type: 'object' },
+        },
+      },
+      required: ['action', 'app_token'],
+    },
+  },
+  {
+    name: 'manage_bitable_field',
+    description: '[Official API] Manage fields (columns) inside a Bitable table. action=list, create, update (Feishu requires `type` even when only renaming), delete.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['list', 'create', 'update', 'delete'], description: 'Operation to perform' },
+        app_token: { type: 'string', description: 'Bitable app token. Accepts native token, wiki node, or Feishu URL.' },
+        table_id: { type: 'string', description: 'Table ID' },
+        field_id: { type: 'string', description: 'Field ID — required for update/delete.' },
+        field_name: { type: 'string', description: 'Field display name — required for create, optional for update.' },
+        type: { type: 'number', description: `Field type (${FIELD_TYPE_NOTE}). Required for create AND update — Feishu API rejects update without it.` },
+        property: { type: 'object', description: 'Field-type-specific properties (optional). E.g. SingleSelect: {options:[{name:"A"},{name:"B"}]}.' },
+      },
+      required: ['action', 'app_token', 'table_id'],
+    },
+  },
+  {
+    name: 'manage_bitable_view',
+    description: '[Official API] Manage views inside a Bitable table. action=list, create, delete. (Feishu open API does not expose view update — recreate with a new name to change.)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['list', 'create', 'delete'], description: 'Operation to perform' },
+        app_token: { type: 'string', description: 'Bitable app token. Accepts native token, wiki node, or Feishu URL.' },
+        table_id: { type: 'string', description: 'Table ID' },
+        view_id: { type: 'string', description: 'View ID — required for delete.' },
+        view_name: { type: 'string', description: 'View name — required for create.' },
+        view_type: { type: 'string', description: 'View type for create: grid (default), kanban, gallery, form, gantt, calendar.', default: 'grid' },
+      },
+      required: ['action', 'app_token', 'table_id'],
+    },
+  },
+  {
+    name: 'manage_bitable_record',
+    description: '[Official API] Manage records (rows) inside a Bitable table. action=search, get, create, update, delete. create/update/delete accept arrays — single record or up to 500.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['search', 'get', 'create', 'update', 'delete'], description: 'Operation to perform' },
+        app_token: { type: 'string', description: 'Bitable app token. Accepts native token, wiki node, or Feishu URL.' },
+        table_id: { type: 'string', description: 'Table ID' },
+        record_id: { type: 'string', description: 'Record ID — required for action=get.' },
+        records: {
+          type: 'array',
+          description: 'Records to write. For create: [{fields:{field_name:value}}]. For update: [{record_id, fields:{...}}]. Single record or up to 500.',
+          items: { type: 'object' },
+        },
+        record_ids: {
+          type: 'array',
+          description: 'Record IDs to delete. Single ID or up to 500.',
+          items: { type: 'string' },
+        },
+        filter: { type: 'object', description: 'Filter conditions (search only, optional)' },
+        sort: { type: 'array', description: 'Sort conditions (search only, optional)' },
+        page_size: { type: 'number', description: 'Results per page (search only, default 20)' },
+      },
+      required: ['action', 'app_token', 'table_id'],
+    },
+  },
+];
+
+function need(arg, name, action) {
+  if (arg === undefined || arg === null || arg === '') {
+    throw new Error(`manage_bitable: ${name} required for action=${action}`);
+  }
+}
+
+const handlers = {
+  async manage_bitable_app(args, ctx) {
+    const c = ctx.getOfficialClient();
+    switch (args.action) {
+      case 'create': {
+        need(args.name, 'name', 'create');
+        const r = await c.createBitable(args.name, args.folder_id, {
+          wikiSpaceId: args.wiki_space_id,
+          wikiParentNodeToken: args.wiki_parent_node_token,
+        });
+        const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; bitable owned by the app, not you)';
+        const wikiNote = r.wikiNodeToken ? `\nWiki node: ${r.wikiNodeToken}`
+          : r.wikiAttachTaskId ? `\nWiki attach queued — task_id: ${r.wikiAttachTaskId}`
+          : r.wikiAttachError ? `\nWARNING: wiki attach failed — ${r.wikiAttachError}. Bitable exists in drive root/folder.`
+          : '';
+        const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+        return text(`Bitable created${ownership}: ${r.appToken}\nURL: ${r.url || ''}${wikiNote}${warn}`);
+      }
+      case 'copy': {
+        need(args.app_token, 'app_token', 'copy');
+        need(args.name, 'name', 'copy');
+        return json(await c.copyBitable(await ctx.resolveDocId(args.app_token), args.name, args.folder_id));
+      }
+      case 'get_meta': {
+        need(args.app_token, 'app_token', 'get_meta');
+        return json(await c.getBitableMeta(await ctx.resolveDocId(args.app_token)));
+      }
+    }
+  },
+  async manage_bitable_table(args, ctx) {
+    const c = ctx.getOfficialClient();
+    const appToken = await ctx.resolveDocId(args.app_token);
+    switch (args.action) {
+      case 'list':
+        return json(await c.listBitableTables(appToken));
+      case 'create': {
+        need(args.name, 'name', 'create');
+        const r = await c.createBitableTable(appToken, args.name, args.fields);
+        const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+        return text(`Table created: ${r.tableId}${warn}`);
+      }
+      case 'update': {
+        need(args.table_id, 'table_id', 'update');
+        need(args.name, 'name', 'update');
+        return text(`Table renamed: ${(await c.updateBitableTable(appToken, args.table_id, args.name)).name}`);
+      }
+      case 'delete': {
+        need(args.table_id, 'table_id', 'delete');
+        return text(`Table deleted: ${(await c.deleteBitableTable(appToken, args.table_id)).deleted}`);
+      }
+    }
+  },
+  async manage_bitable_field(args, ctx) {
+    const c = ctx.getOfficialClient();
+    const appToken = await ctx.resolveDocId(args.app_token);
+    switch (args.action) {
+      case 'list':
+        return json(await c.listBitableFields(appToken, args.table_id));
+      case 'create': {
+        need(args.field_name, 'field_name', 'create');
+        need(args.type, 'type', 'create');
+        const config = { field_name: args.field_name, type: args.type };
+        if (args.property) config.property = args.property;
+        return json(await c.createBitableField(appToken, args.table_id, config));
+      }
+      case 'update': {
+        need(args.field_id, 'field_id', 'update');
+        need(args.type, 'type', 'update');
+        const config = {};
+        if (args.field_name) config.field_name = args.field_name;
+        if (args.type) config.type = args.type;
+        if (args.property) config.property = args.property;
+        return json(await c.updateBitableField(appToken, args.table_id, args.field_id, config));
+      }
+      case 'delete': {
+        need(args.field_id, 'field_id', 'delete');
+        const r = await c.deleteBitableField(appToken, args.table_id, args.field_id);
+        return text(r.deleted ? `Field ${r.fieldId} deleted` : `Field deletion returned deleted=${r.deleted}`);
+      }
+    }
+  },
+  async manage_bitable_view(args, ctx) {
+    const c = ctx.getOfficialClient();
+    const appToken = await ctx.resolveDocId(args.app_token);
+    switch (args.action) {
+      case 'list':
+        return json(await c.listBitableViews(appToken, args.table_id));
+      case 'create': {
+        need(args.view_name, 'view_name', 'create');
+        return json(await c.createBitableView(appToken, args.table_id, args.view_name, args.view_type));
+      }
+      case 'delete': {
+        need(args.view_id, 'view_id', 'delete');
+        return text(`View deleted: ${(await c.deleteBitableView(appToken, args.table_id, args.view_id)).deleted}`);
+      }
+    }
+  },
+  async manage_bitable_record(args, ctx) {
+    const c = ctx.getOfficialClient();
+    const appToken = await ctx.resolveDocId(args.app_token);
+    switch (args.action) {
+      case 'search':
+        return json(await c.searchBitableRecords(appToken, args.table_id, {
+          filter: args.filter, sort: args.sort, pageSize: args.page_size,
+        }));
+      case 'get': {
+        need(args.record_id, 'record_id', 'get');
+        return json(await c.getBitableRecord(appToken, args.table_id, args.record_id));
+      }
+      case 'create': {
+        need(args.records, 'records', 'create');
+        return json(await c.batchCreateBitableRecords(appToken, args.table_id, args.records));
+      }
+      case 'update': {
+        need(args.records, 'records', 'update');
+        return json(await c.batchUpdateBitableRecords(appToken, args.table_id, args.records));
+      }
+      case 'delete': {
+        need(args.record_ids, 'record_ids', 'delete');
+        return json(await c.batchDeleteBitableRecords(appToken, args.table_id, args.record_ids));
+      }
+    }
+  },
+};
+
+module.exports = { schemas, handlers };

package/src/tools/calendar.js

@@ -0,0 +1,207 @@
+// src/tools/calendar.js — Calendar read + write tools.
+//
+// 8 tools (was 3 in v1.3.6): list_calendars, list_calendar_events,
+// get_calendar_event, plus the v1.3.7 write tools:
+//   create_calendar_event / update_calendar_event / delete_calendar_event
+//   respond_calendar_event / get_freebusy
+// All UAT-first. Write tools require `calendar:calendar.event:write` scope.
+
+const { json, text } = require('./_registry');
+
+const TIME_NOTE = 'A time object: {timestamp:"<unix-seconds>", timezone?:"Asia/Shanghai"} OR {date:"YYYY-MM-DD"} for all-day events.';
+
+const schemas = [
+  {
+    name: 'list_calendars',
+    description: '[Official API + UAT] List the current user\'s calendars (primary + shared + subscribed). Requires UAT — app identity only sees calendars it was explicitly invited to. Requires `calendar:calendar:readonly` scope on the OAuth.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page_size: { type: 'number', description: 'Items per page (min 50, default 50). Feishu\'s calendar endpoint rejects page_size < 50.' },
+        page_token: { type: 'string', description: 'Pagination token' },
+        sync_token: { type: 'string', description: 'Incremental sync token (optional)' },
+      },
+    },
+  },
+  {
+    name: 'list_calendar_events',
+    description: '[Official API + UAT] List events in a calendar within an optional time range. Typical usage: first list_calendars to find calendar_id (primary calendar has type="primary"), then list events in e.g. [now, now+7d] (Unix seconds).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        calendar_id: { type: 'string', description: 'Calendar ID from list_calendars' },
+        start_time: { type: 'string', description: 'Range start (Unix seconds, optional)' },
+        end_time: { type: 'string', description: 'Range end (Unix seconds, optional)' },
+        page_size: { type: 'number', description: 'Items per page (default 50)' },
+        page_token: { type: 'string', description: 'Pagination token' },
+        sync_token: { type: 'string', description: 'Incremental sync token (optional)' },
+      },
+      required: ['calendar_id'],
+    },
+  },
+  {
+    name: 'get_calendar_event',
+    description: '[Official API + UAT] Get full details of a single calendar event (summary, description, start/end, attendees, location, attachments, meeting link).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        calendar_id: { type: 'string', description: 'Calendar ID' },
+        event_id: { type: 'string', description: 'Event ID from list_calendar_events' },
+      },
+      required: ['calendar_id', 'event_id'],
+    },
+  },
+  {
+    name: 'create_calendar_event',
+    description: `[Official API + UAT, v1.3.7] Create a new calendar event. Requires \`calendar:calendar.event:write\` scope (re-run \`npx feishu-user-plugin oauth\` after enabling). The current identity (UAT-first) must have writer or owner permission on the calendar.\n\nTime fields: ${TIME_NOTE}`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        calendar_id: { type: 'string', description: 'Calendar ID (use list_calendars; primary calendar has type="primary").' },
+        summary: { type: 'string', description: 'Event title' },
+        description: { type: 'string', description: 'Description / notes (optional)' },
+        start_time: { type: 'object', description: TIME_NOTE },
+        end_time: { type: 'object', description: TIME_NOTE },
+        location: { type: 'object', description: 'Optional. {name, address?, latitude?, longitude?}.' },
+        visibility: { type: 'string', enum: ['default', 'public', 'private'], description: 'Event visibility (optional)' },
+        attendee_ability: { type: 'string', enum: ['none', 'can_see_others', 'can_invite_others', 'can_modify_event'], description: 'What attendees may do (optional)' },
+        free_busy_status: { type: 'string', enum: ['busy', 'free'], description: 'Whether this event blocks the calendar (optional)' },
+        reminders: { type: 'array', description: 'Reminders before event start (optional). E.g. [{minutes:15}].', items: { type: 'object' } },
+        recurrence: { type: 'string', description: 'iCal RRULE recurrence string (optional)' },
+        need_notification: { type: 'boolean', description: 'Whether to notify attendees on create (default true)' },
+      },
+      required: ['calendar_id', 'summary', 'start_time', 'end_time'],
+    },
+  },
+  {
+    name: 'update_calendar_event',
+    description: '[Official API + UAT, v1.3.7] Patch fields on an existing calendar event. Pass only the fields you want to change. Requires `calendar:calendar.event:write` scope.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        calendar_id: { type: 'string', description: 'Calendar ID' },
+        event_id: { type: 'string', description: 'Event ID' },
+        summary: { type: 'string', description: 'New title (optional)' },
+        description: { type: 'string', description: 'New description (optional)' },
+        start_time: { type: 'object', description: TIME_NOTE },
+        end_time: { type: 'object', description: TIME_NOTE },
+        location: { type: 'object', description: 'New location object (optional)' },
+        visibility: { type: 'string', enum: ['default', 'public', 'private'] },
+        attendee_ability: { type: 'string', enum: ['none', 'can_see_others', 'can_invite_others', 'can_modify_event'] },
+        free_busy_status: { type: 'string', enum: ['busy', 'free'] },
+        reminders: { type: 'array', items: { type: 'object' } },
+        recurrence: { type: 'string', description: 'RRULE string' },
+        need_notification: { type: 'boolean', description: 'Whether to notify attendees of the update' },
+      },
+      required: ['calendar_id', 'event_id'],
+    },
+  },
+  {
+    name: 'delete_calendar_event',
+    description: '[Official API + UAT, v1.3.7] Delete a calendar event. Requires `calendar:calendar.event:write` scope.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        calendar_id: { type: 'string', description: 'Calendar ID' },
+        event_id: { type: 'string', description: 'Event ID' },
+        need_notification: { type: 'boolean', description: 'Whether to notify attendees of the deletion (default true)' },
+        meeting_chat_id: { type: 'string', description: 'Optional. If the event has a linked meeting chat, pass its chat_id to also dissolve it.' },
+      },
+      required: ['calendar_id', 'event_id'],
+    },
+  },
+  {
+    name: 'respond_calendar_event',
+    description: '[Official API + UAT, v1.3.7] Respond to an event invitation. The current identity must be in the event\'s attendee list. Requires `calendar:calendar.event:write` scope.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        calendar_id: { type: 'string', description: 'Calendar ID' },
+        event_id: { type: 'string', description: 'Event ID' },
+        rsvp_status: { type: 'string', enum: ['accept', 'decline', 'tentative'], description: 'Your response' },
+      },
+      required: ['calendar_id', 'event_id', 'rsvp_status'],
+    },
+  },
+  {
+    name: 'get_freebusy',
+    description: '[Official API + UAT, v1.3.7] Query freebusy windows for one or more users in a time range. Use to find a meeting slot. Requires `calendar:calendar:readonly` (already in default scope set).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        time_min: { type: 'string', description: 'RFC3339 start, e.g. 2026-05-04T09:00:00+08:00' },
+        time_max: { type: 'string', description: 'RFC3339 end' },
+        user_ids: { type: 'array', description: 'Open IDs to query (use get_login_status / search_contacts to look up).', items: { type: 'string' } },
+        room_ids: { type: 'array', description: 'Optional meeting-room IDs.', items: { type: 'string' } },
+        include_external_calendar: { type: 'boolean', description: 'Include the user\'s synced external calendars (optional)' },
+        only_busy: { type: 'boolean', description: 'Only return busy windows (optional)' },
+      },
+      required: ['time_min', 'time_max', 'user_ids'],
+    },
+  },
+];
+
+function eventDataFromArgs(args, isUpdate = false) {
+  const data = {};
+  if (args.summary !== undefined) data.summary = args.summary;
+  if (args.description !== undefined) data.description = args.description;
+  if (args.start_time !== undefined) data.start_time = args.start_time;
+  if (args.end_time !== undefined) data.end_time = args.end_time;
+  if (args.location !== undefined) data.location = args.location;
+  if (args.visibility !== undefined) data.visibility = args.visibility;
+  if (args.attendee_ability !== undefined) data.attendee_ability = args.attendee_ability;
+  if (args.free_busy_status !== undefined) data.free_busy_status = args.free_busy_status;
+  if (args.reminders !== undefined) data.reminders = args.reminders;
+  if (args.recurrence !== undefined) data.recurrence = args.recurrence;
+  if (args.need_notification !== undefined) data.need_notification = args.need_notification;
+  if (!isUpdate && data.need_notification === undefined) data.need_notification = true;
+  return data;
+}
+
+const handlers = {
+  async list_calendars(args, ctx) {
+    return json(await ctx.getOfficialClient().listCalendars({ pageSize: args.page_size, pageToken: args.page_token, syncToken: args.sync_token }));
+  },
+  async list_calendar_events(args, ctx) {
+    return json(await ctx.getOfficialClient().listCalendarEvents(args.calendar_id, {
+      startTime: args.start_time, endTime: args.end_time,
+      pageSize: args.page_size, pageToken: args.page_token, syncToken: args.sync_token,
+    }));
+  },
+  async get_calendar_event(args, ctx) {
+    return json(await ctx.getOfficialClient().getCalendarEvent(args.calendar_id, args.event_id));
+  },
+  async create_calendar_event(args, ctx) {
+    const r = await ctx.getOfficialClient().createCalendarEvent(args.calendar_id, eventDataFromArgs(args, false));
+    const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; event organized by the app, not you)';
+    const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+    return text(`Event created${ownership}: ${r.event?.event_id || '(no id returned)'}\n${JSON.stringify(r.event, null, 2)}${warn}`);
+  },
+  async update_calendar_event(args, ctx) {
+    const r = await ctx.getOfficialClient().updateCalendarEvent(args.calendar_id, args.event_id, eventDataFromArgs(args, true));
+    const ownership = r.viaUser ? ' (as user)' : ' (as app)';
+    const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+    return text(`Event updated${ownership}: ${args.event_id}\n${JSON.stringify(r.event, null, 2)}${warn}`);
+  },
+  async delete_calendar_event(args, ctx) {
+    const r = await ctx.getOfficialClient().deleteCalendarEvent(args.calendar_id, args.event_id, {
+      needNotification: args.need_notification, meetingChatId: args.meeting_chat_id,
+    });
+    const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+    return text(`Event deleted: ${args.event_id}${warn}`);
+  },
+  async respond_calendar_event(args, ctx) {
+    const r = await ctx.getOfficialClient().respondCalendarEvent(args.calendar_id, args.event_id, args.rsvp_status);
+    const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+    return text(`Responded to event ${args.event_id} as ${args.rsvp_status}${warn}`);
+  },
+  async get_freebusy(args, ctx) {
+    return json(await ctx.getOfficialClient().getFreebusy({
+      timeMin: args.time_min, timeMax: args.time_max,
+      userIds: args.user_ids, roomIds: args.room_ids,
+      includeExternalCalendar: args.include_external_calendar, onlyBusy: args.only_busy,
+    }));
+  },
+};
+
+module.exports = { schemas, handlers };

package/src/tools/contacts.js

@@ -0,0 +1,66 @@
+// src/tools/contacts.js — contact lookup + P2P chat creation.
+
+const { text, json } = require('./_registry');
+
+const schemas = [
+  {
+    name: 'search_contacts',
+    description: '[User Identity] Search Feishu users, bots, or group chats by name. Returns IDs.',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string', description: 'Search keyword' } },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'create_p2p_chat',
+    description: '[User Identity] Create or get a P2P (direct message) chat. Returns numeric chat_id.',
+    inputSchema: {
+      type: 'object',
+      properties: { user_id: { type: 'string', description: 'Target user ID from search_contacts' } },
+      required: ['user_id'],
+    },
+  },
+  {
+    name: 'get_user_info',
+    description: '[User Identity] Look up a user\'s display name by user ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        user_id: { type: 'string', description: 'User ID' },
+        chat_id: { type: 'string', description: 'Chat context (optional)' },
+      },
+      required: ['user_id'],
+    },
+  },
+];
+
+const handlers = {
+  async search_contacts(args, ctx) {
+    const c = await ctx.getUserClient();
+    return json(await c.search(args.query));
+  },
+  async create_p2p_chat(args, ctx) {
+    const c = await ctx.getUserClient();
+    const chatId = await c.createChat(args.user_id);
+    return text(chatId ? `P2P chat: ${chatId}` : 'Failed to create P2P chat');
+  },
+  async get_user_info(args, ctx) {
+    let n = null;
+    try {
+      const official = ctx.getOfficialClient();
+      n = await official.getUserById(args.user_id, 'open_id');
+    } catch {}
+    if (!n) {
+      try {
+        const c = await ctx.getUserClient();
+        n = await c.getUserName(args.user_id);
+      } catch {}
+    }
+    return text(n
+      ? `User ${args.user_id}: ${n}`
+      : `Could not resolve user ${args.user_id}. Tried (1) UAT contact API, (2) bot contact API, (3) cookie protobuf cache. Possible causes:\n  • External tenant user — contact API can't see them. Use search_contacts with display name + the inferred numeric ID for messaging.\n  • App is missing contact:user.base:readonly scope (only blocks bot path; UAT path should still work).\n  • UAT not configured — run \`npx feishu-user-plugin oauth\`.`);
+  },
+};
+
+module.exports = { schemas, handlers };