feishu-user-plugin 1.3.3 → 1.3.5

package/src/official.js

@@ -1,5 +1,7 @@
 const lark = require('@larksuiteoapi/node-sdk');
 const { fetchWithTimeout } = require('./utils');
+const { classifyError } = require('./error-codes');
+const { buildEmptyImageBlock, buildReplaceImagePayload } = require('./doc-blocks');
 
 // Redirect all Lark SDK logs to stderr.
 // The SDK's defaultLogger.error uses console.log (stdout), which corrupts
@@ -32,7 +34,7 @@ class LarkOfficialClient {
     if (token) {
       this._uat = token;
       this._uatRefresh = refresh || null;
-      this._uatExpires = expires;
+      this._uatExpires = expires || this._decodeTokenExpiry(token);
     }
   }
 
@@ -88,6 +90,7 @@ class LarkOfficialClient {
     if (!this._uat) throw new Error('No user_access_token. Run: npx feishu-user-plugin oauth');
 
     const now = Math.floor(Date.now() / 1000);
+    if (!this._uatExpires) this._uatExpires = this._decodeTokenExpiry(this._uat);
     // Proactively refresh if we know it's expiring within 5 min
     if (this._uatExpires > 0 && this._uatExpires <= now + 300) {
       return this._refreshUAT();
@@ -95,30 +98,125 @@ class LarkOfficialClient {
     return this._uat;
   }
 
+  _decodeTokenExpiry(token) {
+    try {
+      const payload = token?.split('.')?.[1];
+      if (!payload) return 0;
+      const data = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+      return typeof data.exp === 'number' ? data.exp : 0;
+    } catch (_) {
+      return 0;
+    }
+  }
+
+  _adoptPersistedUATIfNewer() {
+    try {
+      const { readCredentials } = require('./config');
+      const creds = readCredentials();
+      const token = creds.LARK_USER_ACCESS_TOKEN;
+      const refresh = creds.LARK_USER_REFRESH_TOKEN;
+      if (!token && !refresh) return false;
+
+      const expires = parseInt(creds.LARK_UAT_EXPIRES || '0') || this._decodeTokenExpiry(token);
+      const changed = (token && token !== this._uat)
+        || (refresh && refresh !== this._uatRefresh)
+        || (expires && expires !== this._uatExpires);
+      if (!changed) return false;
+
+      if (token) this._uat = token;
+      if (refresh) this._uatRefresh = refresh;
+      this._uatExpires = expires || 0;
+      console.error('[feishu-user-plugin] UAT adopted latest persisted token before refresh');
+      return true;
+    } catch (e) {
+      console.error(`[feishu-user-plugin] UAT persisted-token check failed: ${e.message}`);
+      return false;
+    }
+  }
+
+  // Cross-process advisory lock for UAT refresh. Feishu rotates the refresh_token
+  // on every refresh (old one invalidated instantly). When multiple MCP server
+  // processes share the same persisted refresh_token and all wake up near expiry,
+  // they race: the first wins, the rest see `invalid_grant` and can't recover.
+  // This lock serialises refreshes across processes; inside the critical section
+  // we also re-read the persisted config so late arrivals adopt the winner's
+  // token instead of attempting a doomed refresh with the already-rotated one.
+  _uatLockPath() {
+    const path = require('path');
+    const os = require('os');
+    return path.join(os.homedir(), '.claude', 'feishu-uat-refresh.lock');
+  }
+
+  async _acquireRefreshLock(lockPath, { staleMs = 30000, pollMs = 200, timeoutMs = 20000 } = {}) {
+    const fs = require('fs');
+    const path = require('path');
+    try { fs.mkdirSync(path.dirname(lockPath), { recursive: true }); } catch (_) {}
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      try {
+        const fd = fs.openSync(lockPath, 'wx'); // O_CREAT | O_EXCL
+        fs.writeSync(fd, `${process.pid}\n${Date.now()}\n`);
+        fs.closeSync(fd);
+        return true;
+      } catch (e) {
+        if (e.code !== 'EEXIST') throw e;
+        try {
+          const stat = fs.statSync(lockPath);
+          if (Date.now() - stat.mtimeMs > staleMs) {
+            try { fs.unlinkSync(lockPath); } catch (_) {}
+            continue;
+          }
+        } catch (_) { /* lock vanished under us — retry */ }
+        await new Promise(r => setTimeout(r, pollMs));
+      }
+    }
+    return false;
+  }
+
+  _releaseRefreshLock(lockPath) {
+    try { require('fs').unlinkSync(lockPath); } catch (_) {}
+  }
+
   async _refreshUAT() {
-    if (!this._uatRefresh) throw new Error('UAT expired and no refresh token. Run: npx feishu-user-plugin oauth');
+    const lockPath = this._uatLockPath();
+    const acquired = await this._acquireRefreshLock(lockPath);
+    if (!acquired) {
+      console.error('[feishu-user-plugin] UAT refresh lock timed out; proceeding without mutual exclusion');
+    }
+    try {
+      // Re-check under lock: another process may have already refreshed and
+      // persisted a new token while we waited. If so, adopt and skip the refresh.
+      const now = Math.floor(Date.now() / 1000);
+      if (this._adoptPersistedUATIfNewer() && this._uatExpires > now + 300) {
+        return this._uat;
+      }
 
-    const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({
-        grant_type: 'refresh_token',
-        client_id: this.appId,
-        client_secret: this.appSecret,
-        refresh_token: this._uatRefresh,
-      }),
-    });
-    const data = await res.json();
-    const tokenData = data.access_token ? data : data.data;
-    if (!tokenData?.access_token) throw new Error(`UAT refresh failed: ${JSON.stringify(data)}. Run: npx feishu-user-plugin oauth`);
-
-    this._uat = tokenData.access_token;
-    this._uatRefresh = tokenData.refresh_token || this._uatRefresh;
-    const expiresIn = typeof tokenData.expires_in === 'number' && tokenData.expires_in > 0 ? tokenData.expires_in : 7200;
-    this._uatExpires = Math.floor(Date.now() / 1000) + expiresIn;
-    this._persistUAT();
-    console.error('[feishu-user-plugin] UAT refreshed successfully');
-    return this._uat;
+      if (!this._uatRefresh) throw new Error('UAT expired and no refresh token. Run: npx feishu-user-plugin oauth');
+
+      const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          grant_type: 'refresh_token',
+          client_id: this.appId,
+          client_secret: this.appSecret,
+          refresh_token: this._uatRefresh,
+        }),
+      });
+      const data = await res.json();
+      const tokenData = data.access_token ? data : data.data;
+      if (!tokenData?.access_token) throw new Error(`UAT refresh failed: ${JSON.stringify(data)}. Run: npx feishu-user-plugin oauth`);
+
+      this._uat = tokenData.access_token;
+      this._uatRefresh = tokenData.refresh_token || this._uatRefresh;
+      const expiresIn = typeof tokenData.expires_in === 'number' && tokenData.expires_in > 0 ? tokenData.expires_in : 7200;
+      this._uatExpires = Math.floor(Date.now() / 1000) + expiresIn;
+      this._persistUAT();
+      console.error('[feishu-user-plugin] UAT refreshed successfully');
+      return this._uat;
+    } finally {
+      if (acquired) this._releaseRefreshLock(lockPath);
+    }
   }
 
   _persistUAT() {
@@ -139,6 +237,14 @@ class LarkOfficialClient {
     const data = await fn(uat);
     // Known auth error codes: 99991668 (invalid), 99991663 (expired), 99991677 (auth_expired)
     if (data.code === 99991668 || data.code === 99991663 || data.code === 99991677) {
+      // 99991668 is overloaded: "invalid token" (→ refresh helps) vs
+      // "endpoint doesn't support UAT at all" (→ refresh is pointless, and
+      // worse, it consumes a one-shot refresh_token rotation). The second
+      // case is identifiable by the msg "user access token not support" or
+      // "not support". If so, surface the code to the caller without refresh.
+      if (data.code === 99991668 && typeof data.msg === 'string' && /not support/i.test(data.msg)) {
+        return data;
+      }
       // Token invalid/expired — try refresh once
       uat = await this._refreshUAT();
       return fn(uat);
@@ -147,8 +253,20 @@ class LarkOfficialClient {
   }
 
   // Generic UAT REST helper. Returns parsed JSON ({code, msg, data}).
+  // Array query values are expanded to repeated keys (period_ids=a&period_ids=b)
+  // because several Feishu endpoints (OKR, calendar) rely on that convention.
   async _uatREST(method, path, { body, query } = {}) {
-    const qs = query ? '?' + new URLSearchParams(query).toString() : '';
+    let qs = '';
+    if (query) {
+      const sp = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (v === undefined || v === null) continue;
+        if (Array.isArray(v)) { for (const item of v) sp.append(k, String(item)); }
+        else sp.append(k, String(v));
+      }
+      const str = sp.toString();
+      if (str) qs = '?' + str;
+    }
     const url = 'https://open.feishu.cn' + path + qs;
     return this._withUAT(async (uat) => {
       const headers = { 'Authorization': `Bearer ${uat}` };
@@ -166,7 +284,12 @@ class LarkOfficialClient {
   // Returns SDK-shaped {code, msg, data, _viaUser}. _viaUser is true iff the UAT call succeeded;
   // callers can surface this to distinguish "created by user" vs "created by app" for resources
   // whose ownership matters (docs, bitables, folders).
+  //
+  // When BOTH paths fail (common for OKR/Calendar if neither UAT nor app has the scope),
+  // the final error includes the UAT-side reason too, so the user can tell whether they
+  // need a new OAuth (UAT missing scope) or a different app (app missing scope).
   async _asUserOrApp({ uatPath, method = 'GET', body, query, sdkFn, label }) {
+    let uatSummary = null;
     if (this.hasUAT) {
       try {
         const data = await this._uatREST(method, uatPath, { body, query });
@@ -174,14 +297,36 @@ class LarkOfficialClient {
           data._viaUser = true;
           return data;
         }
-        console.error(`[feishu-user-plugin] ${label} as user failed (${data.code}: ${data.msg}), retrying as app`);
+        uatSummary = `as user: code=${data.code} msg=${data.msg}`;
+        console.error(`[feishu-user-plugin] ${label} ${uatSummary}, retrying as app`);
       } catch (err) {
+        uatSummary = `as user: ${err.message}`;
         console.error(`[feishu-user-plugin] ${label} as user threw (${err.message}), retrying as app`);
       }
     }
-    const appData = await this._safeSDKCall(sdkFn, label);
-    if (appData && typeof appData === 'object') appData._viaUser = false;
-    return appData;
+    try {
+      const appData = await this._safeSDKCall(sdkFn, label);
+      if (appData && typeof appData === 'object') {
+        appData._viaUser = false;
+        // Attach a warning when we silently fell back to bot identity. This lets
+        // write handlers surface "⚠️ created as BOT, not you" so the user doesn't
+        // discover it days later when a teammate can read the "private" resource.
+        if (uatSummary) {
+          appData._fallbackWarning = `⚠️  UAT 不可用 (${uatSummary}),本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。恢复方法:运行 \`npx feishu-user-plugin oauth\` 后重启 Claude Code / Codex。`;
+        } else if (!this.hasUAT) {
+          appData._fallbackWarning = `⚠️  未配置 UAT,本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。想让资源归你所有,先跑 \`npx feishu-user-plugin oauth\` 然后重启 Claude Code / Codex。`;
+        }
+      }
+      return appData;
+    } catch (appErr) {
+      if (uatSummary) {
+        const err = new Error(`${label} failed on both identities. ${uatSummary}. as app: ${appErr.message}`);
+        err.uatSummary = uatSummary;
+        err.appError = appErr;
+        throw err;
+      }
+      throw appErr;
+    }
   }
 
   async listChatsAsUser({ pageSize = 20, pageToken } = {}) {
@@ -197,7 +342,7 @@ class LarkOfficialClient {
     return { items: data.data.items || [], pageToken: data.data.page_token, hasMore: data.data.has_more };
   }
 
-  async readMessagesAsUser(chatId, { pageSize = 20, startTime, endTime, pageToken, sortType = 'ByCreateTimeDesc' } = {}, userClient) {
+  async readMessagesAsUser(chatId, { pageSize = 20, startTime, endTime, pageToken, sortType = 'ByCreateTimeDesc', expandMergeForward = true } = {}, userClient) {
     // Feishu API requires end_time >= start_time; auto-set end_time to now if missing
     if (startTime && !endTime) {
       endTime = String(Math.floor(Date.now() / 1000));
@@ -218,6 +363,7 @@ class LarkOfficialClient {
     if (data.code !== 0) throw new Error(`readMessagesAsUser failed (${data.code}): ${data.msg}`);
     const items = (data.data.items || []).map(m => this._formatMessage(m));
     await this._populateSenderNames(items, userClient);
+    if (expandMergeForward) await this._expandMergeForwardItems(items, userClient, { preferUAT: true });
     return { items, hasMore: data.data.has_more, pageToken: data.data.page_token };
   }
 
@@ -231,7 +377,7 @@ class LarkOfficialClient {
     return { items: res.data.items || [], pageToken: res.data.page_token, hasMore: res.data.has_more };
   }
 
-  async readMessages(chatId, { pageSize = 20, startTime, endTime, pageToken, sortType = 'ByCreateTimeDesc' } = {}, userClient) {
+  async readMessages(chatId, { pageSize = 20, startTime, endTime, pageToken, sortType = 'ByCreateTimeDesc', expandMergeForward = true } = {}, userClient) {
     const params = { container_id_type: 'chat', container_id: chatId, page_size: pageSize, sort_type: sortType };
     if (startTime) params.start_time = startTime;
     if (endTime) params.end_time = endTime;
@@ -239,6 +385,7 @@ class LarkOfficialClient {
     const res = await this._safeSDKCall(() => this.client.im.message.list({ params }), 'readMessages');
     const items = (res.data.items || []).map(m => this._formatMessage(m));
     await this._populateSenderNames(items, userClient);
+    if (expandMergeForward) await this._expandMergeForwardItems(items, userClient, { preferUAT: false });
     return { items, hasMore: res.data.has_more, pageToken: res.data.page_token };
   }
 
@@ -514,7 +661,7 @@ class LarkOfficialClient {
     return { content: res.data.content };
   }
 
-  async createDoc(title, folderId) {
+  async createDoc(title, folderId, { wikiSpaceId, wikiParentNodeToken } = {}) {
     const res = await this._asUserOrApp({
       uatPath: `/open-apis/docx/v1/documents`,
       method: 'POST',
@@ -522,7 +669,18 @@ class LarkOfficialClient {
       sdkFn: () => this.client.docx.document.create({ data: { title, folder_token: folderId || '' } }),
       label: 'createDoc',
     });
-    return { documentId: res.data.document?.document_id, viaUser: !!res._viaUser };
+    const documentId = res.data.document?.document_id;
+    const out = { documentId, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
+    if (documentId && wikiSpaceId) {
+      try {
+        const node = await this.attachToWiki(wikiSpaceId, 'docx', documentId, wikiParentNodeToken);
+        if (node?.node_token) out.wikiNodeToken = node.node_token;
+        else if (node?.task_id) out.wikiAttachTaskId = node.task_id;
+      } catch (e) {
+        out.wikiAttachError = e.message;
+      }
+    }
+    return out;
   }
 
   async getDocBlocks(documentId) {
@@ -548,7 +706,7 @@ class LarkOfficialClient {
       }),
       label: 'createDocBlock',
     });
-    return { blocks: res.data.children || [] };
+    return { blocks: res.data.children || [], fallbackWarning: res._fallbackWarning || null };
   }
 
   async updateDocBlock(documentId, blockId, updateBody) {
@@ -591,7 +749,7 @@ class LarkOfficialClient {
 
   // --- Bitable ---
 
-  async createBitable(name, folderId) {
+  async createBitable(name, folderId, { wikiSpaceId, wikiParentNodeToken } = {}) {
     const data = {};
     if (name) data.name = name;
     if (folderId) data.folder_token = folderId;
@@ -602,7 +760,18 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.app.create({ data }),
       label: 'createBitable',
     });
-    return { appToken: res.data.app?.app_token, name: res.data.app?.name, url: res.data.app?.url, viaUser: !!res._viaUser };
+    const appToken = res.data.app?.app_token;
+    const out = { appToken, name: res.data.app?.name, url: res.data.app?.url, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
+    if (appToken && wikiSpaceId) {
+      try {
+        const node = await this.attachToWiki(wikiSpaceId, 'bitable', appToken, wikiParentNodeToken);
+        if (node?.node_token) out.wikiNodeToken = node.node_token;
+        else if (node?.task_id) out.wikiAttachTaskId = node.task_id;
+      } catch (e) {
+        out.wikiAttachError = e.message;
+      }
+    }
+    return out;
   }
 
   async listBitableTables(appToken) {
@@ -625,7 +794,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.appTable.create({ path: { app_token: appToken }, data }),
       label: 'createTable',
     });
-    return { tableId: res.data.table_id };
+    return { tableId: res.data.table_id, fallbackWarning: res._fallbackWarning || null };
   }
 
   async listBitableFields(appToken, tableId) {
@@ -645,7 +814,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.appTableField.create({ path: { app_token: appToken, table_id: tableId }, data: fieldConfig }),
       label: 'createField',
     });
-    return { field: res.data.field };
+    return { field: res.data.field, fallbackWarning: res._fallbackWarning || null };
   }
 
   async updateBitableField(appToken, tableId, fieldId, fieldConfig) {
@@ -699,7 +868,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.appTableRecord.create({ path: { app_token: appToken, table_id: tableId }, data: { fields } }),
       label: 'createRecord',
     });
-    return { recordId: res.data.record?.record_id };
+    return { recordId: res.data.record?.record_id, fallbackWarning: res._fallbackWarning || null };
   }
 
   async updateBitableRecord(appToken, tableId, recordId, fields) {
@@ -731,7 +900,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.appTableRecord.batchCreate({ path: { app_token: appToken, table_id: tableId }, data: { records } }),
       label: 'batchCreateRecords',
     });
-    return { records: res.data.records || [] };
+    return { records: res.data.records || [], fallbackWarning: res._fallbackWarning || null };
   }
 
   async batchUpdateBitableRecords(appToken, tableId, records) {
@@ -813,7 +982,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.appTableView.create({ path: { app_token: appToken, table_id: tableId }, data: { view_name: viewName, view_type: viewType } }),
       label: 'createView',
     });
-    return { view: res.data.view };
+    return { view: res.data.view, fallbackWarning: res._fallbackWarning || null };
   }
 
   async deleteBitableView(appToken, tableId, viewId) {
@@ -836,7 +1005,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.bitable.app.copy({ path: { app_token: appToken }, data }),
       label: 'copyBitable',
     });
-    return { app: res.data.app };
+    return { app: res.data.app, fallbackWarning: res._fallbackWarning || null };
   }
 
   // --- Wiki ---
@@ -854,7 +1023,10 @@ class LarkOfficialClient {
     return { items: res.data.docs_entities || [] };
   }
 
-  async getWikiNode(spaceId, nodeToken) {
+  // 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.
+  async getWikiNode(nodeToken, _spaceId) {
     const res = await this._safeSDKCall(() => this.client.wiki.space.getNode({ params: { token: nodeToken } }), 'getNode');
     return res.data.node;
   }
@@ -888,7 +1060,7 @@ class LarkOfficialClient {
       sdkFn: () => this.client.drive.file.createFolder({ data: body }),
       label: 'createFolder',
     });
-    return { token: res.data.token, viaUser: !!res._viaUser };
+    return { token: res.data.token, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
   }
 
   // --- Drive: File Operations ---
@@ -1046,15 +1218,517 @@ class LarkOfficialClient {
       updateTime: this._normalizeTimestamp(m.update_time),
     };
     if (Array.isArray(m.mentions) && m.mentions.length > 0) out.mentions = m.mentions;
+    if (m.upper_message_id) out.upperMessageId = m.upper_message_id;
+    if (m.root_id) out.rootId = m.root_id;
+    if (m.parent_id) out.parentId = m.parent_id;
+    // Extract URL-like strings from text bodies so agents can call WebFetch /
+    // read_doc / get_doc_blocks without having to regex the body themselves.
+    if (out.msgType === 'text' && typeof body?.text === 'string') {
+      const urls = body.text.match(/https?:\/\/[^\s一-鿿]+/g);
+      if (urls && urls.length > 0) {
+        out.urls = Array.from(new Set(urls));
+        const feishuDocs = out.urls.filter(u =>
+          /feishu\.cn\/(?:docx|wiki|base|sheets|docs|mindnotes)\//i.test(u));
+        if (feishuDocs.length > 0) out.feishuDocs = feishuDocs;
+      }
+    }
     return out;
   }
 
+  // Fetch the child messages inside a merge_forward parent. Feishu exposes them
+  // via `/im/v1/messages/{parent_id}` (single-message GET). The response is
+  // actually a list: items[0] is the parent merge_forward placeholder,
+  // items[1..N] are the children carrying `upper_message_id` pointing back to
+  // the parent and `chat_id` pointing to their ORIGIN chat (the one being
+  // forwarded from, not where the merge_forward was posted).
+  //
+  // Media resources (image_key / file_key) on children must be downloaded
+  // using the PARENT message id — a Feishu quirk: downloading with the child
+  // id returns "File not in msg".
+  async readMergeForwardChildren(parentMessageId, userClient, { preferUAT = true } = {}) {
+    const url = `https://open.feishu.cn/open-apis/im/v1/messages/${encodeURIComponent(parentMessageId)}`;
+
+    const tryPath = async (bearer) => {
+      const res = await fetchWithTimeout(url, {
+        headers: { 'Authorization': `Bearer ${bearer}` },
+        timeoutMs: 30000,
+      });
+      return res.json();
+    };
+
+    let data = null;
+    const order = preferUAT ? ['uat', 'bot'] : ['bot', 'uat'];
+    const errors = [];
+    for (const identity of order) {
+      try {
+        if (identity === 'uat') {
+          if (!this.hasUAT) { errors.push('uat: not configured'); continue; }
+          const uat = await this._getValidUAT();
+          const resp = await tryPath(uat);
+          if (resp.code === 0) { data = resp; break; }
+          errors.push(`uat: code=${resp.code} msg=${resp.msg}`);
+        } else {
+          const tat = await this._getAppToken();
+          const resp = await tryPath(tat);
+          if (resp.code === 0) { data = resp; break; }
+          errors.push(`bot: code=${resp.code} msg=${resp.msg}`);
+        }
+      } catch (e) {
+        errors.push(`${identity}: ${e.message}`);
+      }
+    }
+    if (!data) {
+      throw new Error(`readMergeForwardChildren failed: ${errors.join(' | ')}`);
+    }
+
+    // items[0] is the parent itself — filter it out. The rest are children.
+    const rawChildren = (data.data?.items || []).filter(m =>
+      m.message_id !== parentMessageId && m.upper_message_id);
+
+    const children = rawChildren.map(raw => {
+      const f = this._formatMessage(raw);
+      // Surface the parent id on the child so downstream tools (download_image /
+      // download_file) know which id to pass to Feishu's resource endpoint.
+      f.parentMessageId = parentMessageId;
+      // Mark the origin chat explicitly — child.chatId is the ORIGINAL chat the
+      // message came from, not the chat where the merge_forward was posted.
+      f.originChatId = raw.chat_id;
+      return f;
+    });
+    await this._populateSenderNames(children, userClient);
+    return children;
+  }
+
+  // Expand merge_forward placeholders in-place. Adds `children: [...]` or
+  // `expandError` on each merge_forward item. `depth` guards against nesting
+  // (Feishu does allow nested merge_forward, but we cap at 1 level to avoid
+  // exponential fan-out in agent contexts).
+  async _expandMergeForwardItems(items, userClient, { preferUAT = true, depth = 0, maxDepth = 1 } = {}) {
+    if (!items || depth >= maxDepth) return;
+    for (const m of items) {
+      if (m.msgType !== 'merge_forward') continue;
+      try {
+        const children = await this.readMergeForwardChildren(m.messageId, userClient, { preferUAT });
+        m.children = children;
+        // One extra level deep if user really wants, via recursive call.
+        if (depth + 1 < maxDepth) {
+          await this._expandMergeForwardItems(children, userClient, { preferUAT, depth: depth + 1, maxDepth });
+        }
+      } catch (e) {
+        m.expandError = e.message;
+      }
+    }
+  }
+
   _normalizeTimestamp(ts) {
     if (!ts) return null;
     const n = parseInt(ts);
     // Feishu returns millisecond strings; normalize to seconds
     return String(n > 1e12 ? Math.floor(n / 1000) : n);
   }
+
+  // --- Hardened Message Read (v1.3.4) ---
+
+  // Reads messages with explicit fallback routing: tries the bot path first,
+  // classifies any failure via error-codes.js, and escalates to UAT when
+  // appropriate. Returns the same shape as readMessages/readMessagesAsUser
+  // plus `via` ('bot' | 'user' | 'contacts') and, if fallback fired,
+  // `via_reason` (a short enum from classifyError).
+  //
+  // If `skipBot` is true, the bot path is never attempted (callers use this
+  // when the chat_id came from search_contacts — i.e. definitely external).
+  //
+  // Throws a single, wrapped error if BOTH paths fail or if UAT is absent and
+  // the bot failed; the message points the user at `npx feishu-user-plugin oauth`.
+  async readMessagesWithFallback(chatId, options, userClient, { skipBot = false, via = 'bot' } = {}) {
+    const tryUAT = async (viaLabel, reason) => {
+      if (!this.hasUAT) {
+        const hint = 'To read external / private groups, configure UAT via: npx feishu-user-plugin oauth';
+        const err = new Error(`Cannot read chat ${chatId} as bot (${reason || 'bot failed and no UAT configured'}). ${hint}`);
+        err.viaReason = reason;
+        throw err;
+      }
+      const data = await this.readMessagesAsUser(chatId, options, userClient);
+      data.via = viaLabel;
+      if (reason) data.via_reason = reason;
+      return data;
+    };
+
+    if (skipBot) {
+      return tryUAT(via || 'contacts', 'contacts_resolved_external');
+    }
+
+    // Attempt 1 — bot identity.
+    try {
+      const data = await this.readMessages(chatId, options, userClient);
+      data.via = 'bot';
+      return data;
+    } catch (botErr) {
+      const klass = classifyError(botErr);
+      console.error(`[feishu-user-plugin] read_messages bot failed for ${chatId}: ${botErr.message} [class=${klass.action}, reason=${klass.reason}, code=${klass.code}]`);
+
+      if (klass.action === 'retry') {
+        // One retry after short backoff before hopping to UAT.
+        await new Promise(r => setTimeout(r, 2000));
+        try {
+          const data = await this.readMessages(chatId, options, userClient);
+          data.via = 'bot';
+          data.via_reason = klass.reason + '_recovered';
+          return data;
+        } catch (retryErr) {
+          console.error(`[feishu-user-plugin] read_messages bot retry failed for ${chatId}: ${retryErr.message}`);
+        }
+      }
+
+      // Fall through to UAT — if UAT is missing, tryUAT throws the user-friendly
+      // "run npx feishu-user-plugin oauth" error instead of the raw Feishu payload.
+      return tryUAT('user', klass.reason);
+    }
+  }
+
+  // --- 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 (typically an image) to Feishu's drive layer so it can
+  // be attached to a docx block. Returns the media's file_token, which is what
+  // the image block's `replace_image.token` expects.
+  //
+  // parentType = 'docx_image' for doc-embedded images (most common).
+  // parentNode = the block_id of the image placeholder (NOT the document_id).
+  async uploadDocMedia(filePath, parentNode, parentType = 'docx_image') {
+    const fs = require('fs');
+    const path = require('path');
+    if (!filePath) throw new Error('uploadDocMedia: filePath is required');
+    if (!parentNode) throw new Error('uploadDocMedia: parentNode (block_id) is required');
+
+    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 images.
+    const ext = path.extname(fileName).toLowerCase();
+    const mimeMap = {
+      '.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',
+    };
+    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 — docx_image usually belongs to a user-owned doc.
+    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] uploadDocMedia as user failed (${data.code}: ${data.msg}), retrying as app`);
+      } catch (e) {
+        console.error(`[feishu-user-plugin] uploadDocMedia 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(`uploadDocMedia failed: ${data.code}: ${data.msg || 'no file_token returned'}`);
+    }
+    return { fileToken: data.data.file_token, viaUser: false };
+  }
+
+  // Create a new image block and populate it from either a local file path or
+  // an already-uploaded media token. Orchestrates the three-step Feishu flow:
+  //   1) create empty image placeholder block
+  //   2) upload pixels (skipped if caller passes a ready-made imageToken)
+  //   3) patch the placeholder with the uploaded token
+  // Returns { blockId, imageToken, viaUser }.
+  async createDocBlockWithImage(documentId, parentBlockId, { imagePath, imageToken, index } = {}) {
+    if (!imagePath && !imageToken) {
+      throw new Error('createDocBlockWithImage: either imagePath or imageToken is required');
+    }
+
+    // Step 1 — empty placeholder.
+    const placeholder = buildEmptyImageBlock();
+    const createBody = { children: [placeholder] };
+    if (index !== undefined) createBody.index = index;
+    const created = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${parentBlockId}/children`,
+      method: 'POST',
+      body: createBody,
+      sdkFn: () => this.client.docx.documentBlockChildren.create({
+        path: { document_id: documentId, block_id: parentBlockId },
+        data: createBody,
+      }),
+      label: 'createDocBlockWithImage.placeholder',
+    });
+    const newBlock = (created.data.children || [])[0];
+    const blockId = newBlock?.block_id;
+    if (!blockId) throw new Error(`createDocBlockWithImage: placeholder creation returned no block_id: ${JSON.stringify(created.data).slice(0, 400)}`);
+
+    // Step 2 — upload (if needed).
+    let finalToken = imageToken;
+    let viaUser = !!created._viaUser;
+    let fallbackWarning = created._fallbackWarning || null;
+    if (!finalToken) {
+      const uploaded = await this.uploadDocMedia(imagePath, blockId, 'docx_image');
+      finalToken = uploaded.fileToken;
+      viaUser = viaUser && uploaded.viaUser; // true iff both steps went via user
+    }
+
+    // Step 3 — attach token to the placeholder via PATCH replace_image.
+    const patch = buildReplaceImagePayload(finalToken);
+    await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,
+      method: 'PATCH',
+      body: patch,
+      sdkFn: () => this.client.docx.documentBlock.patch({
+        path: { document_id: documentId, block_id: blockId },
+        data: patch,
+      }),
+      label: 'createDocBlockWithImage.replaceImage',
+    });
+
+    return { blockId, imageToken: finalToken, viaUser, fallbackWarning };
+  }
+
+  // Replace an existing image block's media token (e.g. swap the picture in an
+  // already-created image block). Expects an uploaded media token — use
+  // uploadDocMedia or create_doc_block's image_path shortcut to obtain one.
+  async updateDocBlockImage(documentId, blockId, imageToken) {
+    const patch = buildReplaceImagePayload(imageToken);
+    await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,
+      method: 'PATCH',
+      body: patch,
+      sdkFn: () => this.client.docx.documentBlock.patch({
+        path: { document_id: documentId, block_id: blockId },
+        data: patch,
+      }),
+      label: 'updateDocBlockImage',
+    });
+    return { blockId, imageToken };
+  }
+
+  // --- 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;
+  }
+
+  // --- OKR (v1.3.4) ---
+
+  async listUserOkrs(userId, { periodIds, offset = 0, limit = 10, lang, userIdType = 'open_id' } = {}) {
+    if (!userId) throw new Error('listUserOkrs: userId is required (the user whose OKRs to read). For your own, get your open_id from get_login_status or search_contacts.');
+    const params = { user_id_type: userIdType, offset: String(offset), limit: String(limit) };
+    if (lang) params.lang = lang;
+    if (periodIds && periodIds.length) params.period_ids = periodIds;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/okr/v1/users/${encodeURIComponent(userId)}/okrs`,
+      query: params,
+      sdkFn: () => this.client.okr.userOkr.list({
+        path: { user_id: userId },
+        params: {
+          user_id_type: userIdType,
+          offset: String(offset),
+          limit: String(limit),
+          ...(lang ? { lang } : {}),
+          ...(periodIds && periodIds.length ? { period_ids: periodIds } : {}),
+        },
+      }),
+      label: 'listUserOkrs',
+    });
+    return { total: res.data.total, items: res.data.okr_list || [] };
+  }
+
+  async getOkrs(okrIds, { lang, userIdType = 'open_id' } = {}) {
+    if (!Array.isArray(okrIds) || okrIds.length === 0) {
+      throw new Error('getOkrs: okrIds must be a non-empty array');
+    }
+    const params = { user_id_type: userIdType, okr_ids: okrIds };
+    if (lang) params.lang = lang;
+    // UAT REST path takes repeated okr_ids= params; URLSearchParams will serialize an array properly
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/okr/v1/okrs/batch_get`,
+      query: params,
+      sdkFn: () => this.client.okr.okr.batchGet({ params }),
+      label: 'getOkrs',
+    });
+    return { items: res.data.okr_list || [] };
+  }
+
+  async listOkrPeriods({ pageSize = 10, pageToken } = {}) {
+    const params = { page_size: String(pageSize) };
+    if (pageToken) params.page_token = pageToken;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/okr/v1/periods`,
+      query: params,
+      sdkFn: () => this.client.okr.period.list({ params: { page_size: pageSize, ...(pageToken ? { page_token: pageToken } : {}) } }),
+      label: 'listOkrPeriods',
+    });
+    return { items: res.data.items || [], pageToken: res.data.page_token, hasMore: res.data.has_more };
+  }
+
+  // --- Calendar (v1.3.4) ---
+
+  async listCalendars({ pageSize = 50, pageToken, syncToken } = {}) {
+    // Feishu's calendar/v4/calendars endpoint rejects page_size < 50 with
+    // `99992402 field validation failed` ("the min value is 50"). The docs don't
+    // flag this — smoke-tested against the real API. Clamp to be safe.
+    const ps = Math.max(50, Number(pageSize) || 50);
+    const params = { page_size: String(ps) };
+    if (pageToken) params.page_token = pageToken;
+    if (syncToken) params.sync_token = syncToken;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/calendar/v4/calendars`,
+      query: params,
+      sdkFn: () => this.client.calendar.calendar.list({ params: { page_size: ps, ...(pageToken ? { page_token: pageToken } : {}), ...(syncToken ? { sync_token: syncToken } : {}) } }),
+      label: 'listCalendars',
+    });
+    return {
+      items: res.data.calendar_list || [],
+      pageToken: res.data.page_token,
+      syncToken: res.data.sync_token,
+      hasMore: res.data.has_more,
+    };
+  }
+
+  async listCalendarEvents(calendarId, { startTime, endTime, pageSize = 50, pageToken, syncToken } = {}) {
+    if (!calendarId) throw new Error('listCalendarEvents: calendarId is required');
+    const params = { page_size: String(pageSize) };
+    if (startTime) params.start_time = String(startTime);
+    if (endTime) params.end_time = String(endTime);
+    if (pageToken) params.page_token = pageToken;
+    if (syncToken) params.sync_token = syncToken;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/calendar/v4/calendars/${encodeURIComponent(calendarId)}/events`,
+      query: params,
+      sdkFn: () => this.client.calendar.calendarEvent.list({
+        path: { calendar_id: calendarId },
+        params: {
+          page_size: pageSize,
+          ...(startTime ? { start_time: String(startTime) } : {}),
+          ...(endTime ? { end_time: String(endTime) } : {}),
+          ...(pageToken ? { page_token: pageToken } : {}),
+          ...(syncToken ? { sync_token: syncToken } : {}),
+        },
+      }),
+      label: 'listCalendarEvents',
+    });
+    return {
+      items: res.data.items || [],
+      pageToken: res.data.page_token,
+      syncToken: res.data.sync_token,
+      hasMore: res.data.has_more,
+    };
+  }
+
+  async getCalendarEvent(calendarId, eventId) {
+    if (!calendarId || !eventId) throw new Error('getCalendarEvent: calendarId and eventId are required');
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/calendar/v4/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}`,
+      sdkFn: () => this.client.calendar.calendarEvent.get({ path: { calendar_id: calendarId, event_id: eventId } }),
+      label: 'getCalendarEvent',
+    });
+    return { event: res.data.event };
+  }
 }
 
 module.exports = { LarkOfficialClient };