feishu-user-plugin 1.3.6 → 1.3.7

package/src/clients/official/tasks.js

@@ -0,0 +1,142 @@
+// src/clients/official/tasks.js — Feishu Tasks v2 API.
+//
+// Feishu's Task v2 API. Reference:
+//   https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/task-v2/task/overview
+//
+// All methods are UAT-first since tasks are user-owned by default. Requires
+// `task:task` scope on the OAuth.
+//
+// Note on identifiers: v2 uses `task_guid` (not numeric task_id like v1). All
+// our methods accept and return guid strings.
+//
+// Note on completion: there is no separate `complete()` endpoint in v2 —
+// completion is a `patch` setting `completed_at` to a unix-millis string
+// ("0" to uncomplete) plus update_fields=['completed_at'].
+
+module.exports = {
+  async listTasks({ completed, type, pageSize, pageToken } = {}) {
+    const params = {};
+    if (completed !== undefined) params.completed = String(!!completed);
+    if (type) params.type = type;
+    if (pageSize) params.page_size = String(pageSize);
+    if (pageToken) params.page_token = pageToken;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/task/v2/tasks`,
+      method: 'GET',
+      query: params,
+      sdkFn: () => this.client.task.v2.task.list({
+        params: {
+          ...(completed !== undefined ? { completed: !!completed } : {}),
+          ...(type ? { type } : {}),
+          ...(pageSize ? { page_size: pageSize } : {}),
+          ...(pageToken ? { page_token: pageToken } : {}),
+        },
+      }),
+      label: 'listTasks',
+    });
+    return {
+      items: res.data.items || [],
+      pageToken: res.data.page_token,
+      hasMore: res.data.has_more,
+    };
+  },
+
+  async getTask(taskGuid) {
+    if (!taskGuid) throw new Error('getTask: task_guid is required');
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/task/v2/tasks/${encodeURIComponent(taskGuid)}`,
+      method: 'GET',
+      sdkFn: () => this.client.task.v2.task.get({ path: { task_guid: taskGuid } }),
+      label: 'getTask',
+    });
+    return { task: res.data.task };
+  },
+
+  async createTask(taskData) {
+    if (!taskData?.summary) throw new Error('createTask: summary is required');
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/task/v2/tasks`,
+      method: 'POST',
+      body: taskData,
+      sdkFn: () => this.client.task.v2.task.create({ data: taskData }),
+      label: 'createTask',
+    });
+    const out = { task: res.data.task, viaUser: !!res._viaUser };
+    if (res._fallbackWarning) out.fallbackWarning = res._fallbackWarning;
+    return out;
+  },
+
+  async updateTask(taskGuid, taskUpdates, updateFields) {
+    if (!taskGuid) throw new Error('updateTask: task_guid is required');
+    if (!Array.isArray(updateFields) || updateFields.length === 0) {
+      throw new Error('updateTask: update_fields array is required (e.g. ["summary","due","completed_at"]) — Feishu only patches the listed fields.');
+    }
+    const body = { task: taskUpdates || {}, update_fields: updateFields };
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/task/v2/tasks/${encodeURIComponent(taskGuid)}`,
+      method: 'PATCH',
+      body,
+      sdkFn: () => this.client.task.v2.task.patch({
+        path: { task_guid: taskGuid },
+        data: body,
+      }),
+      label: 'updateTask',
+    });
+    const out = { task: res.data.task, viaUser: !!res._viaUser };
+    if (res._fallbackWarning) out.fallbackWarning = res._fallbackWarning;
+    return out;
+  },
+
+  // completed=true marks done now; completed=false un-completes (sets completed_at to "0")
+  async completeTask(taskGuid, completed = true) {
+    if (!taskGuid) throw new Error('completeTask: task_guid is required');
+    const completedAt = completed ? String(Date.now()) : '0';
+    return this.updateTask(taskGuid, { completed_at: completedAt }, ['completed_at']);
+  },
+
+  async deleteTask(taskGuid) {
+    if (!taskGuid) throw new Error('deleteTask: task_guid is required');
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/task/v2/tasks/${encodeURIComponent(taskGuid)}`,
+      method: 'DELETE',
+      sdkFn: () => this.client.task.v2.task.delete({ path: { task_guid: taskGuid } }),
+      label: 'deleteTask',
+    });
+    return { deleted: true, viaUser: !!res._viaUser };
+  },
+
+  // members: array of {id, type?, role, name?}. role is typically "assignee" or "follower".
+  async addTaskMembers(taskGuid, members) {
+    if (!taskGuid) throw new Error('addTaskMembers: task_guid is required');
+    if (!Array.isArray(members) || members.length === 0) throw new Error('addTaskMembers: members array required ({id, role}, role=assignee|follower)');
+    const body = { members };
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/task/v2/tasks/${encodeURIComponent(taskGuid)}/add_members`,
+      method: 'POST',
+      body,
+      sdkFn: () => this.client.task.v2.task.addMembers({
+        path: { task_guid: taskGuid },
+        data: body,
+      }),
+      label: 'addTaskMembers',
+    });
+    return { task: res.data.task, viaUser: !!res._viaUser };
+  },
+
+  async removeTaskMembers(taskGuid, members) {
+    if (!taskGuid) throw new Error('removeTaskMembers: task_guid is required');
+    if (!Array.isArray(members) || members.length === 0) throw new Error('removeTaskMembers: members array required');
+    const body = { members };
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/task/v2/tasks/${encodeURIComponent(taskGuid)}/remove_members`,
+      method: 'POST',
+      body,
+      sdkFn: () => this.client.task.v2.task.removeMembers({
+        path: { task_guid: taskGuid },
+        data: body,
+      }),
+      label: 'removeTaskMembers',
+    });
+    return { task: res.data.task, viaUser: !!res._viaUser };
+  },
+};

package/src/clients/official/uploads.js

@@ -0,0 +1,260 @@
+// src/clients/official/uploads.js
+// Mixed into LarkOfficialClient.prototype by ./index.js (or temporarily by
+// ./base.js during phase A.4–A.11). Methods receive `this` bound to the
+// LarkOfficialClient instance, so they can use this.client, this._safeSDKCall,
+// this._asUserOrApp, this._uatREST, etc. — all defined in base.js.
+
+const { fetchWithTimeout } = require('../../utils');
+
+module.exports = {
+  // --- Upload ---
+
+  async uploadImage(imagePath, imageType = 'message') {
+    const fs = require('fs');
+    const res = await this._safeSDKCall(
+      () => this.client.im.image.create({
+        data: { image_type: imageType, image: fs.createReadStream(imagePath) },
+      }),
+      'uploadImage'
+    );
+    // SDK multipart responses may have data at top level or nested under .data
+    const imageKey = res.data?.image_key || res.image_key;
+    if (!imageKey) throw new Error(`uploadImage: unexpected response structure: ${JSON.stringify(res).slice(0, 500)}`);
+    return { imageKey };
+  },
+
+  async uploadFile(filePath, fileType = 'stream', fileName) {
+    const fs = require('fs');
+    const path = require('path');
+    if (!fileName) fileName = path.basename(filePath);
+    const res = await this._safeSDKCall(
+      () => this.client.im.file.create({
+        data: {
+          file_type: fileType,
+          file_name: fileName,
+          file: fs.createReadStream(filePath),
+        },
+      }),
+      'uploadFile'
+    );
+    // SDK multipart responses may have data at top level or nested under .data
+    const fileKey = res.data?.file_key || res.file_key;
+    if (!fileKey) throw new Error(`uploadFile: unexpected response structure: ${JSON.stringify(res).slice(0, 500)}`);
+    return { fileKey };
+  },
+
+  // --- Docx Image Read (v1.3.4) ---
+
+  // Download a media asset (image, file, etc.) referenced from inside a Feishu
+  // docx block. The model actually gets the pixels via MCP image content in the
+  // handler layer; here we just return base64 + metadata.
+  //
+  // Feishu's drive/v1/medias/{token}/download requires a query `extra` with
+  // a JSON-encoded doc_token when the media lives inside a doc (to pass
+  // tenant-scoped auth). Passing extra is harmless for generic drive files.
+  async downloadDocImage(imageToken, docToken, docType = 'docx') {
+    if (!imageToken) throw new Error('downloadDocImage: imageToken is required');
+    // Feishu's drive media download uses `extra` as a JSON-string query param to
+    // identify the enclosing doc context. Most observed forms carry both
+    // `doc_type` and `doc_token`; omitting docType falls back to 'docx' which
+    // is the by-far most common case. Omitting extra entirely is safe for
+    // standalone drive-media tokens that don't live inside a doc.
+    const extra = docToken
+      ? `?extra=${encodeURIComponent(JSON.stringify({ doc_type: docType, doc_token: docToken }))}`
+      : '';
+    const path = `/open-apis/drive/v1/medias/${encodeURIComponent(imageToken)}/download${extra}`;
+    const url = 'https://open.feishu.cn' + path;
+
+    // Attempt 1 — user identity (most reliable for user-owned docs).
+    if (this.hasUAT) {
+      try {
+        const uat = await this._getValidUAT();
+        const res = await fetchWithTimeout(url, { headers: { 'Authorization': `Bearer ${uat}` }, timeoutMs: 60000 });
+        if (res.ok && !res.headers.get('content-type')?.includes('application/json')) {
+          const buf = Buffer.from(await res.arrayBuffer());
+          return {
+            base64: buf.toString('base64'),
+            mimeType: res.headers.get('content-type') || 'application/octet-stream',
+            bytes: buf.length,
+            viaUser: true,
+          };
+        }
+        const errJson = await res.json().catch(() => null);
+        console.error(`[feishu-user-plugin] downloadDocImage as user failed: ${errJson?.code}: ${errJson?.msg || res.statusText}, retrying as app`);
+      } catch (e) {
+        console.error(`[feishu-user-plugin] downloadDocImage as user threw (${e.message}), retrying as app`);
+      }
+    }
+
+    // Attempt 2 — app identity. Requires the app to have drive access to the doc.
+    const token = await this._getAppToken();
+    const res = await fetchWithTimeout(url, { headers: { 'Authorization': `Bearer ${token}` }, timeoutMs: 60000 });
+    if (!res.ok || res.headers.get('content-type')?.includes('application/json')) {
+      const errJson = await res.json().catch(() => null);
+      throw new Error(`downloadDocImage failed: ${errJson?.code}: ${errJson?.msg || res.statusText}. Note: app identity requires drive access to the document; configure UAT for user-owned docs.`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    return {
+      base64: buf.toString('base64'),
+      mimeType: res.headers.get('content-type') || 'application/octet-stream',
+      bytes: buf.length,
+      viaUser: false,
+    };
+  },
+
+  // --- Docx Image Write (v1.3.4) ---
+
+  // Upload binary media to Feishu's drive layer so it can be attached to a
+  // docx block, sheet cell, bitable attachment field, etc. Returns the
+  // media's file_token, which is what the host block's replace_*.token
+  // (or bitable attachment field value) expects.
+  //
+  // parentType ∈ {
+  //   docx_image, docx_file,
+  //   sheet_image, sheet_file,
+  //   bitable_image, bitable_file,
+  //   doc_image, doc_file,        // legacy doc (pre-docx)
+  //   ccm_import_open,            // import-task host
+  //   vc_virtual_background       // VC bg, grayscale-only
+  // }
+  // parentNode = the block_id (docx) / spreadsheet_token (sheet) / app_token
+  // (bitable) / doc_token (legacy) — depends on parentType.
+  async uploadMedia(filePath, parentNode, parentType = 'docx_image') {
+    const fs = require('fs');
+    const path = require('path');
+    if (!filePath) throw new Error('uploadMedia: filePath is required');
+    if (!parentNode) throw new Error('uploadMedia: parentNode is required');
+    const ALLOWED = new Set([
+      'docx_image', 'docx_file',
+      'sheet_image', 'sheet_file',
+      'bitable_image', 'bitable_file',
+      'doc_image', 'doc_file',
+      'ccm_import_open', 'vc_virtual_background',
+    ]);
+    if (!ALLOWED.has(parentType)) {
+      throw new Error(`uploadMedia: unsupported parent_type "${parentType}". Allowed: ${[...ALLOWED].join(', ')}`);
+    }
+
+    const stat = fs.statSync(filePath);
+    const fileName = path.basename(filePath);
+    const buf = fs.readFileSync(filePath);
+
+    // Best-effort content-type from extension. Feishu doesn't require it but
+    // some CDNs behind the API key off it; the Blob default is text/plain
+    // which would look wrong for binary attachments.
+    const ext = path.extname(fileName).toLowerCase();
+    const mimeMap = {
+      // image
+      '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+      '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
+      '.bmp': 'image/bmp', '.tiff': 'image/tiff', '.ico': 'image/x-icon',
+      // doc / archive
+      '.pdf': 'application/pdf', '.zip': 'application/zip',
+      '.doc': 'application/msword',
+      '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      '.xls': 'application/vnd.ms-excel',
+      '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      '.ppt': 'application/vnd.ms-powerpoint',
+      '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+      '.txt': 'text/plain', '.md': 'text/markdown', '.csv': 'text/csv', '.json': 'application/json',
+    };
+    const contentType = mimeMap[ext] || 'application/octet-stream';
+
+    const doUpload = async (bearer) => {
+      const form = new FormData();
+      form.append('file_name', fileName);
+      form.append('parent_type', parentType);
+      form.append('parent_node', parentNode);
+      form.append('size', String(stat.size));
+      form.append('file', new Blob([buf], { type: contentType }), fileName);
+      const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/drive/v1/medias/upload_all', {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${bearer}` },
+        body: form,
+        timeoutMs: 120000,
+      });
+      return res.json();
+    };
+
+    // User identity first — host resources are usually user-owned.
+    if (this.hasUAT) {
+      try {
+        const data = await this._withUAT(doUpload);
+        if (data.code === 0 && data.data?.file_token) {
+          return { fileToken: data.data.file_token, viaUser: true };
+        }
+        console.error(`[feishu-user-plugin] uploadMedia (${parentType}) as user failed (${data.code}: ${data.msg}), retrying as app`);
+      } catch (e) {
+        console.error(`[feishu-user-plugin] uploadMedia (${parentType}) as user threw (${e.message}), retrying as app`);
+      }
+    }
+    const appToken = await this._getAppToken();
+    const data = await doUpload(appToken);
+    if (data.code !== 0 || !data.data?.file_token) {
+      throw new Error(`uploadMedia (${parentType}) failed: ${data.code}: ${data.msg || 'no file_token returned'}`);
+    }
+    return { fileToken: data.data.file_token, viaUser: false };
+  },
+
+  // Backwards-compat alias — old name from v1.3.4.
+  async uploadDocMedia(filePath, parentNode, parentType = 'docx_image') {
+    return this.uploadMedia(filePath, parentNode, parentType);
+  },
+
+  // Upload a file to a drive folder (NOT for embedding in a doc — that's
+  // uploadMedia). Uses drive/v1/files/upload_all with parent_type=explorer.
+  // Returns { fileToken, viaUser } where fileToken is the cloud-doc file id.
+  async uploadDriveFile(filePath, folderToken) {
+    const fs = require('fs');
+    const path = require('path');
+    if (!filePath) throw new Error('uploadDriveFile: filePath is required');
+    if (!folderToken) throw new Error('uploadDriveFile: folderToken is required (use the destination folder token; for "my space" root call list_files first to get it)');
+
+    const stat = fs.statSync(filePath);
+    const fileName = path.basename(filePath);
+    const buf = fs.readFileSync(filePath);
+    const ext = path.extname(fileName).toLowerCase();
+    const mimeMap = {
+      '.pdf': 'application/pdf', '.zip': 'application/zip',
+      '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+      '.txt': 'text/plain', '.md': 'text/markdown', '.csv': 'text/csv', '.json': 'application/json',
+      '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    };
+    const contentType = mimeMap[ext] || 'application/octet-stream';
+
+    const doUpload = async (bearer) => {
+      const form = new FormData();
+      form.append('file_name', fileName);
+      form.append('parent_type', 'explorer');
+      form.append('parent_node', folderToken);
+      form.append('size', String(stat.size));
+      form.append('file', new Blob([buf], { type: contentType }), fileName);
+      const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/drive/v1/files/upload_all', {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${bearer}` },
+        body: form,
+        timeoutMs: 120000,
+      });
+      return res.json();
+    };
+
+    if (this.hasUAT) {
+      try {
+        const data = await this._withUAT(doUpload);
+        if (data.code === 0 && data.data?.file_token) {
+          return { fileToken: data.data.file_token, viaUser: true };
+        }
+        console.error(`[feishu-user-plugin] uploadDriveFile as user failed (${data.code}: ${data.msg}), retrying as app`);
+      } catch (e) {
+        console.error(`[feishu-user-plugin] uploadDriveFile as user threw (${e.message}), retrying as app`);
+      }
+    }
+    const appToken = await this._getAppToken();
+    const data = await doUpload(appToken);
+    if (data.code !== 0 || !data.data?.file_token) {
+      throw new Error(`uploadDriveFile failed: ${data.code}: ${data.msg || 'no file_token returned'}`);
+    }
+    return { fileToken: data.data.file_token, viaUser: false };
+  },
+};

package/src/clients/official/wiki.js

@@ -0,0 +1,207 @@
+// src/clients/official/wiki.js
+// Mixed into LarkOfficialClient.prototype by ./index.js (or temporarily by
+// ./base.js during phase A.4–A.11). Methods receive `this` bound to the
+// LarkOfficialClient instance, so they can use this.client, this._safeSDKCall,
+// this._asUserOrApp, this._uatREST, etc. — all defined in base.js.
+
+module.exports = {
+  // --- Wiki ---
+
+  async listWikiSpaces() {
+    // Try UAT first — most users access only their own / team Wiki spaces
+    // which the bot may not have been invited to. Falling back to app keeps
+    // the bot-shared-spaces case working too.
+    const res = await this._asUserOrApp({
+      uatPath: '/open-apis/wiki/v2/spaces?page_size=50',
+      method: 'GET',
+      sdkFn: () => this.client.wiki.space.list({ params: { page_size: 50 } }),
+      label: 'listSpaces',
+    });
+    const items = res.data.items || [];
+    const out = { items, viaUser: !!res._viaUser };
+    if (res._fallbackWarning) out.fallbackWarning = res._fallbackWarning;
+    // Empty + bot path means scope is missing; surface a clear hint instead
+    // of silently returning nothing.
+    if (items.length === 0 && !res._viaUser) {
+      out.scopeHint = 'No spaces returned via app — the bot likely lacks `wiki:wiki:readonly` scope, or has not been invited to any Wiki space. Run `npx feishu-user-plugin oauth` and ensure the wiki scope is granted; or invite the bot to the target Wiki space.';
+    }
+    return out;
+  },
+
+  async searchWiki(query) {
+    const res = await this._safeSDKCall(
+      () => this.client.request({ method: 'POST', url: '/open-apis/suite/docs-api/search/object', data: { search_key: query, count: 20, offset: 0, owner_ids: [], chat_ids: [], docs_types: ['wiki'] } }),
+      'searchWiki'
+    );
+    return { items: res.data.docs_entities || [] };
+  },
+
+  // Resolves a wiki node token to its underlying object (docx / sheet / bitable / ...).
+  // `spaceId` argument is kept for backward compatibility but isn't used — the Feishu
+  // endpoint `wiki.v2.getNode` takes only the token.
+  //
+  // Accepts both wiki node tokens (wikcnXXX from list_wiki_nodes) and underlying
+  // obj_tokens (docxXXX / bascnXXX from search_wiki). For obj_tokens the wiki
+  // endpoint returns 95300x errors; the handler in tools/wiki.js detects this
+  // and returns a synthesized node-shaped result so callers don't have to know
+  // which ID space they're holding.
+  async getWikiNode(nodeToken, _spaceId) {
+    const res = await this._safeSDKCall(() => this.client.wiki.space.getNode({ params: { token: nodeToken } }), 'getNode');
+    return res.data.node;
+  },
+
+  async listWikiNodes(spaceId, { parentNodeToken, pageToken } = {}) {
+    // UAT-first (v1.3.7): bot identity hits 131006 "wiki space permission
+    // denied" for spaces it wasn't explicitly invited to, even when the user
+    // has access. listWikiSpaces is already UAT-first; this matches.
+    const queryParams = { page_size: '50' };
+    if (parentNodeToken) queryParams.parent_node_token = parentNodeToken;
+    if (pageToken) queryParams.page_token = pageToken;
+    const sdkParams = { page_size: 50 };
+    if (parentNodeToken) sdkParams.parent_node_token = parentNodeToken;
+    if (pageToken) sdkParams.page_token = pageToken;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/wiki/v2/spaces/${encodeURIComponent(spaceId)}/nodes`,
+      query: queryParams,
+      sdkFn: () => this.client.wiki.spaceNode.list({ path: { space_id: spaceId }, params: sdkParams }),
+      label: 'listWikiNodes',
+    });
+    return { items: res.data.items || [], hasMore: res.data.has_more, viaUser: !!res._viaUser };
+  },
+
+  // --- Wiki write (v1.3.7) ---
+
+  // Create a new node inside a Wiki space. obj_type picks the underlying
+  // resource (docx / sheet / bitable / mindnote / file / slides). For
+  // node_type='shortcut' the caller must also pass origin_node_token to
+  // point at an existing node.
+  async createWikiNode(spaceId, { obj_type, node_type = 'origin', parent_node_token, origin_node_token, title } = {}) {
+    if (!spaceId) throw new Error('createWikiNode: spaceId is required');
+    if (!obj_type) throw new Error('createWikiNode: obj_type is required (doc/sheet/bitable/mindnote/file/docx/slides)');
+    if (node_type === 'shortcut' && !origin_node_token) {
+      throw new Error('createWikiNode: origin_node_token is required when node_type=shortcut');
+    }
+    const data = { obj_type, node_type };
+    if (parent_node_token) data.parent_node_token = parent_node_token;
+    if (origin_node_token) data.origin_node_token = origin_node_token;
+    if (title) data.title = title;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/wiki/v2/spaces/${encodeURIComponent(spaceId)}/nodes`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.wiki.spaceNode.create({ path: { space_id: spaceId }, data }),
+      label: 'createWikiNode',
+    });
+    return { node: res.data.node, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
+  },
+
+  // Rename a wiki node. Feishu's SDK exposes this as updateTitle (the
+  // underlying API is /open-apis/wiki/v2/spaces/{space_id}/nodes/{token}/update_title).
+  async updateWikiNodeTitle(spaceId, nodeToken, title) {
+    if (!spaceId) throw new Error('updateWikiNodeTitle: spaceId is required');
+    if (!nodeToken) throw new Error('updateWikiNodeTitle: nodeToken is required');
+    if (!title) throw new Error('updateWikiNodeTitle: title is required');
+    const data = { title };
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/wiki/v2/spaces/${encodeURIComponent(spaceId)}/nodes/${encodeURIComponent(nodeToken)}/update_title`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.wiki.spaceNode.updateTitle({ path: { space_id: spaceId, node_token: nodeToken }, data }),
+      label: 'updateWikiNodeTitle',
+    });
+    return { ok: res.code === 0, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
+  },
+
+  // Move a wiki node to a different parent or different space.
+  async moveWikiNode(spaceId, nodeToken, { target_parent_token, target_space_id } = {}) {
+    if (!spaceId) throw new Error('moveWikiNode: spaceId is required');
+    if (!nodeToken) throw new Error('moveWikiNode: nodeToken is required');
+    if (!target_parent_token && !target_space_id) {
+      throw new Error('moveWikiNode: at least one of target_parent_token or target_space_id is required');
+    }
+    const data = {};
+    if (target_parent_token) data.target_parent_token = target_parent_token;
+    if (target_space_id) data.target_space_id = target_space_id;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/wiki/v2/spaces/${encodeURIComponent(spaceId)}/nodes/${encodeURIComponent(nodeToken)}/move`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.wiki.spaceNode.move({ path: { space_id: spaceId, node_token: nodeToken }, data }),
+      label: 'moveWikiNode',
+    });
+    return { node: res.data.node, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
+  },
+
+  // Delete a wiki node. The Feishu SDK does not expose this endpoint, but the
+  // open API documents `DELETE /open-apis/wiki/v2/spaces/{space_id}/nodes/{token}`
+  // (added 2025-Q1 per the API console; not yet typed in @larksuiteoapi/node-sdk).
+  // We fall back to UAT REST and the bot's `client.request` raw helper, since
+  // there's no SDK method to call.
+  //
+  // CAVEAT: this only removes the wiki node. The underlying drive resource
+  // (docx / sheet / bitable / file) is NOT deleted — Feishu's design treats
+  // wiki nodes as pointers. To delete the actual resource, follow up with
+  // manage_drive_file(action=delete, type=<obj_type>, file_token=<obj_token>).
+  async deleteWikiNode(spaceId, nodeToken) {
+    if (!spaceId) throw new Error('deleteWikiNode: spaceId is required');
+    if (!nodeToken) throw new Error('deleteWikiNode: nodeToken is required');
+    const path = `/open-apis/wiki/v2/spaces/${encodeURIComponent(spaceId)}/nodes/${encodeURIComponent(nodeToken)}`;
+    const res = await this._asUserOrApp({
+      uatPath: path,
+      method: 'DELETE',
+      sdkFn: () => this.client.request({ method: 'DELETE', url: path }),
+      label: 'deleteWikiNode',
+    });
+    return { deleted: res.code === 0, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
+  },
+
+  // Copy a wiki node — deep copies the underlying resource into the target
+  // location. target_parent_token / target_space_id select the destination;
+  // omitting target_space_id keeps it within the source space.
+  async copyWikiNode(spaceId, nodeToken, { target_parent_token, target_space_id, title } = {}) {
+    if (!spaceId) throw new Error('copyWikiNode: spaceId is required');
+    if (!nodeToken) throw new Error('copyWikiNode: nodeToken is required');
+    const data = {};
+    if (target_parent_token) data.target_parent_token = target_parent_token;
+    if (target_space_id) data.target_space_id = target_space_id;
+    if (title) data.title = title;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/wiki/v2/spaces/${encodeURIComponent(spaceId)}/nodes/${encodeURIComponent(nodeToken)}/copy`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.wiki.spaceNode.copy({ path: { space_id: spaceId, node_token: nodeToken }, data }),
+      label: 'copyWikiNode',
+    });
+    return { node: res.data.node, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
+  },
+
+  // --- Wiki attach (v1.3.4) ---
+
+  // Move an existing drive resource (docx / bitable / sheet / ...) into a Wiki
+  // space as an 'origin' node. Used by createDoc / createBitable when their
+  // wikiSpaceId option is set.
+  //
+  // Uses wiki/v2/spaces/{space_id}/nodes/move_docs_to_wiki — the documented path
+  // for migrating an existing drive doc into wiki. Note: this endpoint is async;
+  // if the move completes immediately (typical for newly-created docs) we get
+  // back a wiki_token and surface it as node_token. If it's queued we return
+  // { task_id } so the caller can see the async state — we don't currently poll.
+  async attachToWiki(spaceId, objType, objToken, parentNodeToken) {
+    if (!spaceId) throw new Error('attachToWiki: spaceId is required');
+    if (!objType) throw new Error('attachToWiki: objType is required');
+    if (!objToken) throw new Error('attachToWiki: objToken is required');
+    const body = { obj_type: objType, obj_token: objToken, apply: true };
+    if (parentNodeToken) body.parent_wiki_token = parentNodeToken;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/wiki/v2/spaces/${encodeURIComponent(spaceId)}/nodes/move_docs_to_wiki`,
+      method: 'POST',
+      body,
+      sdkFn: () => this.client.wiki.spaceNode.moveDocsToWiki({ path: { space_id: spaceId }, data: body }),
+      label: 'attachToWiki',
+    });
+    const data = res.data || {};
+    if (data.wiki_token) return { node_token: data.wiki_token, applied: !!data.applied };
+    if (data.task_id) return { task_id: data.task_id, applied: false };
+    return data;
+  },
+};