feishu-user-plugin 1.3.6 → 1.3.8

package/src/tools/tasks.js

@@ -0,0 +1,168 @@
+// src/tools/tasks.js — Feishu Tasks v2 tools (v1.3.7 new domain).
+//
+// 7 tools backed by clients/official/tasks.js. All UAT-first.
+// Requires `task:task` scope on the OAuth — re-run `npx feishu-user-plugin oauth`
+// after enabling the scope on the Feishu app console.
+
+const { json, text } = require('./_registry');
+
+const schemas = [
+  {
+    name: 'list_tasks',
+    description: '[Official API + UAT, v1.3.7] List the current user\'s tasks. Filter by completion or type.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        completed: { type: 'boolean', description: 'true → only completed; false → only pending; omit → all' },
+        type: { type: 'string', description: 'Filter by task type (optional). E.g. "all" / "personal".' },
+        page_size: { type: 'number', description: 'Items per page (default Feishu default)' },
+        page_token: { type: 'string', description: 'Pagination token' },
+      },
+    },
+  },
+  {
+    name: 'get_task',
+    description: '[Official API + UAT, v1.3.7] Get full details of a single task by GUID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_guid: { type: 'string', description: 'Task GUID (from list_tasks / create_task / Feishu URL)' },
+      },
+      required: ['task_guid'],
+    },
+  },
+  {
+    name: 'create_task',
+    description: '[Official API + UAT, v1.3.7] Create a new task. summary is required; due / members / etc. are optional.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        summary: { type: 'string', description: 'Task title' },
+        description: { type: 'string', description: 'Task description (optional)' },
+        due: { type: 'object', description: 'Due time (optional). {timestamp:"<unix-millis>", is_all_day?:true|false}' },
+        members: {
+          type: 'array',
+          description: 'Initial members (optional). Each: {id:"<open_id>", role:"assignee"|"follower", type?:"user", name?:"..."}',
+          items: { type: 'object' },
+        },
+        repeat_rule: { type: 'string', description: 'Recurrence (optional, RFC5545 RRULE)' },
+        extra: { type: 'string', description: 'Free-form extra metadata (optional)' },
+      },
+      required: ['summary'],
+    },
+  },
+  {
+    name: 'update_task',
+    description: '[Official API + UAT, v1.3.7] Patch a task. **update_fields** is required by Feishu — list which fields to update (e.g. ["summary","due","completed_at"]).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_guid: { type: 'string', description: 'Task GUID' },
+        update_fields: {
+          type: 'array',
+          description: 'Required. Names of fields to update. E.g. ["summary","description","due","completed_at","start","extra","repeat_rule"]. Feishu only patches fields listed here, ignoring other keys in `task`.',
+          items: { type: 'string' },
+        },
+        task: {
+          type: 'object',
+          description: 'Field values. E.g. {summary:"new title", due:{timestamp:"1717939200000"}}.',
+        },
+      },
+      required: ['task_guid', 'update_fields', 'task'],
+    },
+  },
+  {
+    name: 'complete_task',
+    description: '[Official API + UAT, v1.3.7] Mark a task complete (or uncomplete it). Convenience wrapper around update_task with completed_at.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_guid: { type: 'string', description: 'Task GUID' },
+        completed: { type: 'boolean', description: 'true → mark complete (uses Date.now()); false → uncomplete (sets completed_at to "0"). Default true.' },
+      },
+      required: ['task_guid'],
+    },
+  },
+  {
+    name: 'delete_task',
+    description: '[Official API + UAT, v1.3.7] Permanently delete a task.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_guid: { type: 'string', description: 'Task GUID' },
+      },
+      required: ['task_guid'],
+    },
+  },
+  {
+    name: 'manage_task_members',
+    description: '[Official API + UAT, v1.3.7] Add or remove members on a task. Members are objects {id:"<open_id>", role:"assignee"|"follower", type?:"user", name?:""}.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['add', 'remove'], description: 'add or remove' },
+        task_guid: { type: 'string', description: 'Task GUID' },
+        members: {
+          type: 'array',
+          description: 'Members to add/remove. Each: {id, role, type?, name?}.',
+          items: { type: 'object' },
+        },
+      },
+      required: ['action', 'task_guid', 'members'],
+    },
+  },
+];
+
+const handlers = {
+  async list_tasks(args, ctx) {
+    return json(await ctx.getOfficialClient().listTasks({
+      completed: args.completed,
+      type: args.type,
+      pageSize: args.page_size,
+      pageToken: args.page_token,
+    }));
+  },
+  async get_task(args, ctx) {
+    return json(await ctx.getOfficialClient().getTask(args.task_guid));
+  },
+  async create_task(args, ctx) {
+    const data = { summary: args.summary };
+    if (args.description !== undefined) data.description = args.description;
+    if (args.due !== undefined) data.due = args.due;
+    if (args.members !== undefined) data.members = args.members;
+    if (args.repeat_rule !== undefined) data.repeat_rule = args.repeat_rule;
+    if (args.extra !== undefined) data.extra = args.extra;
+    const r = await ctx.getOfficialClient().createTask(data);
+    const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; task created by the app, not you)';
+    const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+    return text(`Task created${ownership}: ${r.task?.guid || '(no guid returned)'}\n${JSON.stringify(r.task, null, 2)}${warn}`);
+  },
+  async update_task(args, ctx) {
+    const r = await ctx.getOfficialClient().updateTask(args.task_guid, args.task, args.update_fields);
+    const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+    return text(`Task updated: ${args.task_guid}\n${JSON.stringify(r.task, null, 2)}${warn}`);
+  },
+  async complete_task(args, ctx) {
+    const completed = args.completed === undefined ? true : !!args.completed;
+    const r = await ctx.getOfficialClient().completeTask(args.task_guid, completed);
+    return text(`Task ${completed ? 'completed' : 'uncompleted'}: ${args.task_guid}`);
+  },
+  async delete_task(args, ctx) {
+    await ctx.getOfficialClient().deleteTask(args.task_guid);
+    return text(`Task deleted: ${args.task_guid}`);
+  },
+  async manage_task_members(args, ctx) {
+    const c = ctx.getOfficialClient();
+    if (args.action === 'add') {
+      const r = await c.addTaskMembers(args.task_guid, args.members);
+      return text(`Members added to ${args.task_guid}: ${args.members.length}\n${JSON.stringify(r.task?.members, null, 2)}`);
+    }
+    if (args.action === 'remove') {
+      const r = await c.removeTaskMembers(args.task_guid, args.members);
+      return text(`Members removed from ${args.task_guid}: ${args.members.length}\n${JSON.stringify(r.task?.members, null, 2)}`);
+    }
+    throw new Error('manage_task_members: action must be add or remove');
+  },
+};
+
+module.exports = { schemas, handlers };

package/src/tools/uploads.js

@@ -0,0 +1,63 @@
+// src/tools/uploads.js — upload helpers (image, file, bitable attachment).
+
+const { text, json } = require('./_registry');
+
+const schemas = [
+  {
+    name: 'upload_image',
+    description: '[Official API] Upload an image file to Feishu. Returns image_key for use with send_image_as_user.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image_path: { type: 'string', description: 'Absolute path to the image file on disk' },
+        image_type: { type: 'string', enum: ['message', 'avatar'], description: 'Image usage type (default: message)' },
+      },
+      required: ['image_path'],
+    },
+  },
+  {
+    name: 'upload_file',
+    description: '[Official API] Upload a file to Feishu. Returns file_key for use with send_file_as_user.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the file on disk' },
+        file_type: { type: 'string', enum: ['opus', 'mp4', 'pdf', 'doc', 'xls', 'ppt', 'stream'], description: 'File type (default: stream for generic files)' },
+        file_name: { type: 'string', description: 'Display file name (optional, defaults to basename)' },
+      },
+      required: ['file_path'],
+    },
+  },
+  {
+    name: 'upload_bitable_attachment',
+    description: '[Official API] Upload a file as a Bitable attachment (drive/v1/medias/upload_all with parent_type=bitable_image or bitable_file). Returns file_token suitable for writing into a Bitable Attachment-type field via batch_create/update_bitable_records (the field value should be [{file_token}]).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        app_token: { type: 'string', description: 'Bitable app token (the bascn... or basc... id)' },
+        file_path: { type: 'string', description: 'Absolute path to the file on disk' },
+        kind: { type: 'string', enum: ['image', 'file'], description: 'Whether the attachment is an image (bitable_image) or a generic file (bitable_file). Default: file.' },
+      },
+      required: ['app_token', 'file_path'],
+    },
+  },
+];
+
+const handlers = {
+  async upload_image(args, ctx) {
+    const r = await ctx.getOfficialClient().uploadImage(args.image_path, args.image_type);
+    return text(`Image uploaded: ${r.imageKey}\nUse this image_key with send_image_as_user to send it.`);
+  },
+  async upload_file(args, ctx) {
+    const r = await ctx.getOfficialClient().uploadFile(args.file_path, args.file_type, args.file_name);
+    return text(`File uploaded: ${r.fileKey}\nUse this file_key with send_file_as_user to send it.`);
+  },
+  async upload_bitable_attachment(args, ctx) {
+    const kind = args.kind === 'image' ? 'bitable_image' : 'bitable_file';
+    const appToken = await ctx.resolveDocId(args.app_token);
+    const up = await ctx.getOfficialClient().uploadMedia(args.file_path, appToken, kind);
+    return json({ fileToken: up.fileToken, viaUser: up.viaUser, parentType: kind, hint: `Pass [{ file_token: "${up.fileToken}" }] as the value of an Attachment-type Bitable field.` });
+  },
+};
+
+module.exports = { schemas, handlers };

package/src/tools/wiki.js

@@ -0,0 +1,191 @@
+// src/tools/wiki.js — Wiki space + node read tools.
+
+const { json } = require('./_registry');
+
+const schemas = [
+  {
+    name: 'list_wiki_spaces',
+    description: '[Official API] List all accessible Wiki spaces.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'search_wiki',
+    description: '[Official API] Search Wiki nodes by keyword.',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string', description: 'Search keyword' } },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'list_wiki_nodes',
+    description: '[Official API] List nodes in a Wiki space.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        space_id: { type: 'string', description: 'Wiki space ID' },
+        parent_node_token: { type: 'string', description: 'Parent node token (optional)' },
+      },
+      required: ['space_id'],
+    },
+  },
+  {
+    name: 'get_wiki_node',
+    description: '[Official API] Resolve a Wiki node token to its underlying object (docx / bitable / sheet / mindnote / file). Returns obj_type + obj_token + space_id so you can read/write the real resource via the usual docx / bitable tools. Accepts bare wiki node token (wikcnXXX), an underlying obj_token (docxXXX / bascnXXX from search_wiki), or a full Feishu /wiki/ URL — the handler tries the wiki endpoint first and falls back to a synthesized node-shape for non-wiki tokens.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        node_token: { type: 'string', description: 'Wiki node token (wikcnXXX / wikmXXX / wiknXXX), underlying obj_token (docxXXX / bascnXXX), or full Feishu /wiki/<token> URL' },
+      },
+      required: ['node_token'],
+    },
+  },
+  {
+    name: 'create_wiki_node',
+    description: '[Official API] Create a new Wiki node inside a space. obj_type picks the underlying resource (doc/sheet/bitable/mindnote/file/docx/slides). UAT-first so the resource is owned by the user.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        space_id: { type: 'string', description: 'Wiki space ID (from list_wiki_spaces)' },
+        obj_type: { type: 'string', enum: ['doc', 'sheet', 'bitable', 'mindnote', 'file', 'docx', 'slides'], description: 'Underlying resource type' },
+        title: { type: 'string', description: 'Node title (optional; Feishu generates a default if absent)' },
+        parent_node_token: { type: 'string', description: 'Parent wiki node under which to create (optional; root if omitted)' },
+        node_type: { type: 'string', enum: ['origin', 'shortcut'], description: 'origin = real resource, shortcut = pointer to existing node (default: origin)', default: 'origin' },
+        origin_node_token: { type: 'string', description: 'Required when node_type=shortcut — the wiki node this shortcut points at' },
+      },
+      required: ['space_id', 'obj_type'],
+    },
+  },
+  {
+    name: 'update_wiki_node',
+    description: '[Official API] Rename a Wiki node (only `title` is updatable via the wiki API; the underlying resource content is edited via docx/bitable/sheet tools).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        space_id: { type: 'string', description: 'Wiki space ID' },
+        node_token: { type: 'string', description: 'Wiki node token (wikcnXXX)' },
+        title: { type: 'string', description: 'New title' },
+      },
+      required: ['space_id', 'node_token', 'title'],
+    },
+  },
+  {
+    name: 'move_wiki_node',
+    description: '[Official API] Move a Wiki node to a different parent (within the same space) or to a different space. Pass at least one of target_parent_token / target_space_id.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        space_id: { type: 'string', description: 'Source space ID' },
+        node_token: { type: 'string', description: 'Wiki node token to move' },
+        target_parent_token: { type: 'string', description: 'New parent wiki node token (optional)' },
+        target_space_id: { type: 'string', description: 'New target space ID (optional; same-space move if omitted)' },
+      },
+      required: ['space_id', 'node_token'],
+    },
+  },
+  {
+    name: 'copy_wiki_node',
+    description: '[Official API] Deep-copy a Wiki node into a different location (and optionally a different space). Underlying resource is duplicated.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        space_id: { type: 'string', description: 'Source space ID' },
+        node_token: { type: 'string', description: 'Wiki node token to copy' },
+        target_parent_token: { type: 'string', description: 'Destination parent wiki node token (optional)' },
+        target_space_id: { type: 'string', description: 'Destination space ID (optional; same-space copy if omitted)' },
+        title: { type: 'string', description: 'Title for the copy (optional; defaults to source title)' },
+      },
+      required: ['space_id', 'node_token'],
+    },
+  },
+  {
+    name: 'delete_wiki_node',
+    description: '[Official API, v1.3.7] Delete a Wiki node. Calls `DELETE /open-apis/wiki/v2/spaces/{space_id}/nodes/{node_token}`. The Feishu SDK does not type this endpoint, so the call goes through raw REST (UAT-first; bot fallback uses `client.request`). **The underlying drive resource (docx / sheet / bitable / file) is NOT deleted** — Feishu treats wiki nodes as pointers. To delete the actual resource as well, follow up with `manage_drive_file(action=delete, type=<obj_type>, file_token=<obj_token>)` (use `get_wiki_node` first to get obj_type / obj_token).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        space_id: { type: 'string', description: 'Wiki space ID' },
+        node_token: { type: 'string', description: 'Wiki node token to delete' },
+      },
+      required: ['space_id', 'node_token'],
+    },
+  },
+];
+
+const { parseFeishuInput } = require('../resolver');
+
+const handlers = {
+  async list_wiki_spaces(_args, ctx) {
+    return json(await ctx.getOfficialClient().listWikiSpaces());
+  },
+  async search_wiki(args, ctx) {
+    return json(await ctx.getOfficialClient().searchWiki(args.query));
+  },
+  async list_wiki_nodes(args, ctx) {
+    return json(await ctx.getOfficialClient().listWikiNodes(args.space_id, { parentNodeToken: args.parent_node_token }));
+  },
+  async create_wiki_node(args, ctx) {
+    return json(await ctx.getOfficialClient().createWikiNode(args.space_id, {
+      obj_type: args.obj_type,
+      node_type: args.node_type || 'origin',
+      parent_node_token: args.parent_node_token,
+      origin_node_token: args.origin_node_token,
+      title: args.title,
+    }));
+  },
+  async update_wiki_node(args, ctx) {
+    return json(await ctx.getOfficialClient().updateWikiNodeTitle(args.space_id, args.node_token, args.title));
+  },
+  async move_wiki_node(args, ctx) {
+    return json(await ctx.getOfficialClient().moveWikiNode(args.space_id, args.node_token, {
+      target_parent_token: args.target_parent_token,
+      target_space_id: args.target_space_id,
+    }));
+  },
+  async copy_wiki_node(args, ctx) {
+    return json(await ctx.getOfficialClient().copyWikiNode(args.space_id, args.node_token, {
+      target_parent_token: args.target_parent_token,
+      target_space_id: args.target_space_id,
+      title: args.title,
+    }));
+  },
+  async delete_wiki_node(args, ctx) {
+    return json(await ctx.getOfficialClient().deleteWikiNode(args.space_id, args.node_token));
+  },
+  async get_wiki_node(args, ctx) {
+    const parsed = parseFeishuInput(args.node_token);
+    const token = (parsed.kind === 'wiki' || parsed.kind === 'raw') ? parsed.token : args.node_token;
+    try {
+      return json(await ctx.getOfficialClient().getWikiNode(token));
+    } catch (e) {
+      // search_wiki returns underlying obj_tokens (docxXXX / bascnXXX), which
+      // wiki.v2.getNode rejects. Detect the wiki-only error codes and return
+      // a synthesized node-shape so callers can pass either token kind.
+      const msg = String(e.message || '');
+      if (/95300\d|invalid.*token|node.*not.*found/i.test(msg)) {
+        const objType = inferObjTypeFromToken(token);
+        if (objType) {
+          return json({
+            obj_type: objType,
+            obj_token: token,
+            note: `Token does not look like a wiki node token; treating as a direct ${objType} obj_token. Pass it to ${objType === 'bitable' ? 'list_bitable_tables / search_bitable_records' : objType === 'docx' ? 'read_doc / get_doc_blocks' : 'the matching read tool'} directly.`,
+          });
+        }
+      }
+      throw e;
+    }
+  },
+};
+
+function inferObjTypeFromToken(token) {
+  if (!token || typeof token !== 'string') return null;
+  if (token.startsWith('docx')) return 'docx';
+  if (token.startsWith('doccn') || token.startsWith('doc')) return 'doc';
+  if (token.startsWith('bascn') || token.startsWith('bas')) return 'bitable';
+  if (token.startsWith('shtcn') || token.startsWith('sht')) return 'sheet';
+  if (token.startsWith('mind') || token.startsWith('mn')) return 'mindnote';
+  if (token.startsWith('boxcn') || token.startsWith('boxbn')) return 'file';
+  return null;
+}
+
+module.exports = { schemas, handlers };