feishu-user-plugin 1.3.6 → 1.3.8

package/src/clients/official/base.js

@@ -0,0 +1,188 @@
+const lark = require('@larksuiteoapi/node-sdk');
+const { fetchWithTimeout } = require('../../utils');
+const { stderrLogger } = require('../../logger');
+const uatLifecycle = require('../../auth/uat');
+
+class LarkOfficialClient {
+  constructor(appId, appSecret) {
+    this.appId = appId;
+    this.appSecret = appSecret;
+    this.client = new lark.Client({ appId, appSecret, disableTokenCache: false, logger: stderrLogger, loggerLevel: lark.LoggerLevel.warn });
+    this._uat = null;
+    this._uatRefresh = null;
+    this._uatExpires = 0;
+    this._userNameCache = new Map(); // open_id → display name
+  }
+
+  // --- UAT (User Access Token) Management ---
+
+  loadUAT() {
+    const token = process.env.LARK_USER_ACCESS_TOKEN;
+    const refresh = process.env.LARK_USER_REFRESH_TOKEN;
+    const expires = parseInt(process.env.LARK_UAT_EXPIRES || '0');
+    if (token) {
+      this._uat = token;
+      this._uatRefresh = refresh || null;
+      this._uatExpires = expires || this._decodeTokenExpiry(token);
+    }
+  }
+
+  get hasUAT() {
+    return !!this._uat;
+  }
+
+  // Fetches (and caches) an app_access_token directly via the internal endpoint.
+  // Avoids relying on SDK-internal token-manager APIs that may change across versions.
+  async _getAppToken() {
+    const now = Math.floor(Date.now() / 1000);
+    if (this._appToken && this._appTokenExpires > now + 60) return this._appToken;
+    const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ app_id: this.appId, app_secret: this.appSecret }),
+      timeoutMs: 10000,
+    });
+    const data = await res.json();
+    if (data.code !== 0 || !data.app_access_token) {
+      throw new Error(`app_access_token failed: ${data.code}: ${data.msg || 'unknown'}`);
+    }
+    this._appToken = data.app_access_token;
+    this._appTokenExpires = now + (typeof data.expire === 'number' ? data.expire : 7200);
+    return this._appToken;
+  }
+
+  // Probe APP_ID/SECRET validity by requesting a tenant access token.
+  // Catches the common "user's Claude filled in a wrong/stale APP_ID" failure mode
+  // (observed in production: 周宇's machine ran with an APP_ID nobody recognized,
+  // causing all Official API calls to 401 with cryptic messages that looked like
+  // MCP "掉线" to the user). Returns { valid, appId, appName?, error? }.
+  async verifyApp() {
+    try {
+      const token = await this._getAppToken();
+      // Try to fetch app display name (best-effort; requires application scope)
+      let appName = null;
+      try {
+        const infoRes = await fetchWithTimeout(`https://open.feishu.cn/open-apis/application/v6/applications/${this.appId}?lang=zh_cn`, {
+          headers: { 'Authorization': `Bearer ${token}` },
+          timeoutMs: 10000,
+        });
+        const info = await infoRes.json();
+        if (info.code === 0) appName = info.data?.app?.app_name || null;
+      } catch (_) { /* name is best-effort; valid creds still matter most */ }
+      return { valid: true, appId: this.appId, appName };
+    } catch (e) {
+      return { valid: false, appId: this.appId, error: e.message };
+    }
+  }
+
+  // UAT lifecycle methods are extracted to src/auth/uat.js (v1.3.8 D.1).
+  // State (this._uat / this._uatRefresh / this._uatExpires) still lives here;
+  // function bodies live in auth/uat.js. These methods are 1-line delegates.
+  _decodeTokenExpiry(token)            { return uatLifecycle.decodeTokenExpiry(token); }
+  async _getValidUAT()                 { return uatLifecycle.getValidUAT(this); }
+  _adoptPersistedUATIfNewer()          { return uatLifecycle.adoptPersistedUATIfNewer(this); }
+  async _refreshUAT()                  { return uatLifecycle.refreshUAT(this); }
+  _persistUAT()                        { return uatLifecycle.persistUAT(this); }
+  async _withUAT(fn)                   { return uatLifecycle.withUAT(this, fn); }
+  async _uatREST(method, path, opts)   { return uatLifecycle.uatREST(this, method, path, opts); }
+  async _asUserOrApp(opts)             { return uatLifecycle.asUserOrApp(this, opts); }
+
+  // --- Safe SDK Call (extracts real Feishu error from AxiosError) ---
+
+  async _safeSDKCall(fn, label = 'API') {
+    try {
+      const res = await fn();
+      // SDK returns abbreviated responses for multipart uploads (code/msg undefined)
+      // Only treat as error if code is explicitly non-zero
+      if (res.code !== undefined && res.code !== 0) throw new Error(`${label} failed (${res.code}): ${res.msg}`);
+      return res;
+    } catch (err) {
+      // Lark SDK uses axios; extract actual Feishu error from response body
+      if (err.response?.data) {
+        const d = err.response.data;
+        const code = d.code ?? d.error ?? 'unknown';
+        const msg = d.msg ?? d.error_description ?? d.message ?? JSON.stringify(d);
+        throw new Error(`${label} failed (HTTP ${err.response.status}, code=${code}): ${msg}`);
+      }
+      throw err;
+    }
+  }
+
+  async _populateSenderNames(items, userClient) {
+    // Collect unique sender IDs that aren't cached
+    const unknownIds = new Set();
+    for (const item of items) {
+      if (item.senderId && !this._userNameCache.has(item.senderId)) {
+        unknownIds.add(item.senderId);
+      }
+    }
+    // Parallel resolve via official contact API (instead of sequential N calls)
+    if (unknownIds.size > 0) {
+      await Promise.allSettled([...unknownIds].map(id => this.getUserById(id)));
+    }
+    // Fallback: resolve remaining unknowns via cookie-based user identity client
+    if (userClient) {
+      for (const id of unknownIds) {
+        if (!this._userNameCache.has(id)) {
+          try {
+            const name = await userClient.getUserName(id);
+            if (name) this._userNameCache.set(id, name);
+          } catch {}
+        }
+      }
+    }
+    // Populate senderName field
+    for (const item of items) {
+      if (item.senderId) {
+        item.senderName = this._userNameCache.get(item.senderId) || null;
+      }
+    }
+  }
+
+  // --- Helpers ---
+
+  _formatMessage(m) {
+    if (!m) return null;
+    let body = m.body?.content || '';
+    try { body = JSON.parse(body); } catch {}
+    const out = {
+      messageId: m.message_id,
+      chatId: m.chat_id,
+      senderId: m.sender?.id,
+      senderType: m.sender?.sender_type,
+      msgType: m.msg_type,
+      content: body,
+      createTime: this._normalizeTimestamp(m.create_time),
+      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;
+  }
+
+  _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);
+  }
+
+}
+
+// base.js exports only the bare class. clients/official/index.js composes the
+// domain mixins onto its prototype — callers should always import from there,
+// never directly from base.js.
+module.exports = { LarkOfficialClient };

package/src/clients/official/bitable.js

@@ -0,0 +1,269 @@
+// src/clients/official/bitable.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.attachToWiki (mixed in via wiki.js), etc. — all
+// defined in base.js or mixed in via other domain modules.
+
+module.exports = {
+  // --- Bitable ---
+
+  async createBitable(name, folderId, { wikiSpaceId, wikiParentNodeToken } = {}) {
+    const data = {};
+    if (name) data.name = name;
+    if (folderId) data.folder_token = folderId;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.bitable.app.create({ data }),
+      label: 'createBitable',
+    });
+    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) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables`,
+      sdkFn: () => this.client.bitable.appTable.list({ path: { app_token: appToken } }),
+      label: 'listTables',
+    });
+    return { items: res.data.items || [] };
+  },
+
+  async createBitableTable(appToken, name, fields) {
+    const data = { table: { name } };
+    if (fields && fields.length > 0) data.table.default_view_name = name;
+    if (fields && fields.length > 0) data.table.fields = fields;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.bitable.appTable.create({ path: { app_token: appToken }, data }),
+      label: 'createTable',
+    });
+    return { tableId: res.data.table_id, fallbackWarning: res._fallbackWarning || null };
+  },
+
+  async listBitableFields(appToken, tableId) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/fields`,
+      sdkFn: () => this.client.bitable.appTableField.list({ path: { app_token: appToken, table_id: tableId } }),
+      label: 'listFields',
+    });
+    return { items: res.data.items || [] };
+  },
+
+  async createBitableField(appToken, tableId, fieldConfig) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/fields`,
+      method: 'POST',
+      body: fieldConfig,
+      sdkFn: () => this.client.bitable.appTableField.create({ path: { app_token: appToken, table_id: tableId }, data: fieldConfig }),
+      label: 'createField',
+    });
+    return { field: res.data.field, fallbackWarning: res._fallbackWarning || null };
+  },
+
+  async updateBitableField(appToken, tableId, fieldId, fieldConfig) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/fields/${fieldId}`,
+      method: 'PUT',
+      body: fieldConfig,
+      sdkFn: () => this.client.bitable.appTableField.update({ path: { app_token: appToken, table_id: tableId, field_id: fieldId }, data: fieldConfig }),
+      label: 'updateField',
+    });
+    return { field: res.data.field };
+  },
+
+  async deleteBitableField(appToken, tableId, fieldId) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/fields/${fieldId}`,
+      method: 'DELETE',
+      sdkFn: () => this.client.bitable.appTableField.delete({ path: { app_token: appToken, table_id: tableId, field_id: fieldId } }),
+      label: 'deleteField',
+    });
+    return { fieldId: res.data.field_id, deleted: res.data.deleted };
+  },
+
+  async searchBitableRecords(appToken, tableId, { filter, sort, pageSize = 20, pageToken } = {}) {
+    const data = {};
+    if (filter) data.filter = filter;
+    if (sort) data.sort = sort;
+    const query = {};
+    if (pageSize) query.page_size = String(pageSize);
+    if (pageToken) query.page_token = pageToken;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/search`,
+      method: 'POST',
+      body: data,
+      query,
+      sdkFn: () => this.client.bitable.appTableRecord.search({
+        path: { app_token: appToken, table_id: tableId },
+        params: { page_size: pageSize, ...(pageToken ? { page_token: pageToken } : {}) },
+        data,
+      }),
+      label: 'searchRecords',
+    });
+    return { items: res.data.items || [], total: res.data.total, hasMore: res.data.has_more };
+  },
+
+  async createBitableRecord(appToken, tableId, fields) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records`,
+      method: 'POST',
+      body: { fields },
+      sdkFn: () => this.client.bitable.appTableRecord.create({ path: { app_token: appToken, table_id: tableId }, data: { fields } }),
+      label: 'createRecord',
+    });
+    return { recordId: res.data.record?.record_id, fallbackWarning: res._fallbackWarning || null };
+  },
+
+  async updateBitableRecord(appToken, tableId, recordId, fields) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/${recordId}`,
+      method: 'PUT',
+      body: { fields },
+      sdkFn: () => this.client.bitable.appTableRecord.update({ path: { app_token: appToken, table_id: tableId, record_id: recordId }, data: { fields } }),
+      label: 'updateRecord',
+    });
+    return { recordId: res.data.record?.record_id };
+  },
+
+  async deleteBitableRecord(appToken, tableId, recordId) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/${recordId}`,
+      method: 'DELETE',
+      sdkFn: () => this.client.bitable.appTableRecord.delete({ path: { app_token: appToken, table_id: tableId, record_id: recordId } }),
+      label: 'deleteRecord',
+    });
+    return { deleted: res.data.deleted };
+  },
+
+  async batchCreateBitableRecords(appToken, tableId, records) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/batch_create`,
+      method: 'POST',
+      body: { records },
+      sdkFn: () => this.client.bitable.appTableRecord.batchCreate({ path: { app_token: appToken, table_id: tableId }, data: { records } }),
+      label: 'batchCreateRecords',
+    });
+    return { records: res.data.records || [], fallbackWarning: res._fallbackWarning || null };
+  },
+
+  async batchUpdateBitableRecords(appToken, tableId, records) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/batch_update`,
+      method: 'POST',
+      body: { records },
+      sdkFn: () => this.client.bitable.appTableRecord.batchUpdate({ path: { app_token: appToken, table_id: tableId }, data: { records } }),
+      label: 'batchUpdateRecords',
+    });
+    return { records: res.data.records || [] };
+  },
+
+  async batchDeleteBitableRecords(appToken, tableId, recordIds) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/batch_delete`,
+      method: 'POST',
+      body: { records: recordIds },
+      sdkFn: () => this.client.bitable.appTableRecord.batchDelete({ path: { app_token: appToken, table_id: tableId }, data: { records: recordIds } }),
+      label: 'batchDeleteRecords',
+    });
+    return { records: res.data.records || [] };
+  },
+
+  async listBitableViews(appToken, tableId) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/views`,
+      query: { page_size: '50' },
+      sdkFn: () => this.client.bitable.appTableView.list({ path: { app_token: appToken, table_id: tableId }, params: { page_size: 50 } }),
+      label: 'listViews',
+    });
+    return { items: res.data.items || [] };
+  },
+
+  async getBitableRecord(appToken, tableId, recordId) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/${recordId}`,
+      sdkFn: () => this.client.bitable.appTableRecord.get({ path: { app_token: appToken, table_id: tableId, record_id: recordId } }),
+      label: 'getRecord',
+    });
+    return { record: res.data.record };
+  },
+
+  async deleteBitableTable(appToken, tableId) {
+    await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}`,
+      method: 'DELETE',
+      sdkFn: () => this.client.bitable.appTable.delete({ path: { app_token: appToken, table_id: tableId } }),
+      label: 'deleteTable',
+    });
+    return { deleted: true };
+  },
+
+  async getBitableMeta(appToken) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}`,
+      sdkFn: () => this.client.bitable.app.get({ path: { app_token: appToken } }),
+      label: 'getBitableMeta',
+    });
+    return { app: res.data.app };
+  },
+
+  async updateBitableTable(appToken, tableId, name) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}`,
+      method: 'PATCH',
+      body: { name },
+      sdkFn: () => this.client.bitable.appTable.patch({ path: { app_token: appToken, table_id: tableId }, data: { name } }),
+      label: 'updateTable',
+    });
+    return { name: res.data.name };
+  },
+
+  async createBitableView(appToken, tableId, viewName, viewType = 'grid') {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/views`,
+      method: 'POST',
+      body: { view_name: viewName, view_type: viewType },
+      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, fallbackWarning: res._fallbackWarning || null };
+  },
+
+  async deleteBitableView(appToken, tableId, viewId) {
+    await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/views/${viewId}`,
+      method: 'DELETE',
+      sdkFn: () => this.client.bitable.appTableView.delete({ path: { app_token: appToken, table_id: tableId, view_id: viewId } }),
+      label: 'deleteView',
+    });
+    return { deleted: true };
+  },
+
+  async copyBitable(appToken, name, folderId) {
+    const data = { name };
+    if (folderId) data.folder_token = folderId;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/copy`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.bitable.app.copy({ path: { app_token: appToken }, data }),
+      label: 'copyBitable',
+    });
+    return { app: res.data.app, fallbackWarning: res._fallbackWarning || null };
+  },
+};

package/src/clients/official/calendar.js

@@ -0,0 +1,176 @@
+// src/clients/official/calendar.js
+// Mixed into LarkOfficialClient.prototype by ./index.js. UAT-first for all
+// methods (calendar resources are user-owned by default).
+
+module.exports = {
+  // --- Calendar read (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 };
+  },
+
+  // --- Calendar write (v1.3.7) ---
+  // Requires `calendar:calendar.event:write` scope on app + UAT.
+
+  async createCalendarEvent(calendarId, eventData) {
+    if (!calendarId) throw new Error('createCalendarEvent: calendarId is required');
+    if (!eventData?.start_time || !eventData?.end_time) {
+      throw new Error('createCalendarEvent: start_time and end_time are required (each: {timestamp: "<unix-seconds>", timezone?: "Asia/Shanghai"} or {date: "YYYY-MM-DD"})');
+    }
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/calendar/v4/calendars/${encodeURIComponent(calendarId)}/events`,
+      method: 'POST',
+      body: eventData,
+      sdkFn: () => this.client.calendar.calendarEvent.create({
+        path: { calendar_id: calendarId },
+        data: eventData,
+      }),
+      label: 'createCalendarEvent',
+    });
+    const out = { event: res.data.event, viaUser: !!res._viaUser };
+    if (res._fallbackWarning) out.fallbackWarning = res._fallbackWarning;
+    return out;
+  },
+
+  async updateCalendarEvent(calendarId, eventId, updates) {
+    if (!calendarId || !eventId) throw new Error('updateCalendarEvent: calendarId and eventId are required');
+    if (!updates || typeof updates !== 'object' || Object.keys(updates).length === 0) {
+      throw new Error('updateCalendarEvent: updates object is required (e.g. {summary, description, start_time, end_time, attendee_ability, ...})');
+    }
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/calendar/v4/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}`,
+      method: 'PATCH',
+      body: updates,
+      sdkFn: () => this.client.calendar.calendarEvent.patch({
+        path: { calendar_id: calendarId, event_id: eventId },
+        data: updates,
+      }),
+      label: 'updateCalendarEvent',
+    });
+    const out = { event: res.data.event, viaUser: !!res._viaUser };
+    if (res._fallbackWarning) out.fallbackWarning = res._fallbackWarning;
+    return out;
+  },
+
+  async deleteCalendarEvent(calendarId, eventId, { needNotification, meetingChatId } = {}) {
+    if (!calendarId || !eventId) throw new Error('deleteCalendarEvent: calendarId and eventId are required');
+    const query = {};
+    if (needNotification !== undefined) query.need_notification = String(needNotification);
+    if (meetingChatId) query.meeting_chat_id = meetingChatId;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/calendar/v4/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}`,
+      method: 'DELETE',
+      query,
+      sdkFn: () => this.client.calendar.calendarEvent.delete({
+        path: { calendar_id: calendarId, event_id: eventId },
+        params: meetingChatId ? { meeting_chat_id: meetingChatId } : {},
+      }),
+      label: 'deleteCalendarEvent',
+    });
+    const out = { deleted: true, viaUser: !!res._viaUser };
+    if (res._fallbackWarning) out.fallbackWarning = res._fallbackWarning;
+    return out;
+  },
+
+  async respondCalendarEvent(calendarId, eventId, rsvpStatus) {
+    if (!calendarId || !eventId) throw new Error('respondCalendarEvent: calendarId and eventId are required');
+    if (!['accept', 'decline', 'tentative'].includes(rsvpStatus)) {
+      throw new Error('respondCalendarEvent: rsvp_status must be one of accept|decline|tentative');
+    }
+    const body = { rsvp_status: rsvpStatus };
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/calendar/v4/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}/reply`,
+      method: 'PATCH',
+      body,
+      sdkFn: () => this.client.calendar.calendarEvent.reply({
+        path: { calendar_id: calendarId, event_id: eventId },
+        data: body,
+      }),
+      label: 'respondCalendarEvent',
+    });
+    const out = { rsvp: rsvpStatus, viaUser: !!res._viaUser };
+    if (res._fallbackWarning) out.fallbackWarning = res._fallbackWarning;
+    return out;
+  },
+
+  async getFreebusy({ timeMin, timeMax, userIds = [], roomIds = [], includeExternalCalendar, onlyBusy } = {}) {
+    if (!timeMin || !timeMax) throw new Error('getFreebusy: time_min and time_max (RFC3339 strings) are required');
+    if (!Array.isArray(userIds) || userIds.length === 0) {
+      throw new Error('getFreebusy: user_ids array is required (use list_profiles / get_login_status to get your own open_id)');
+    }
+    const body = {
+      time_min: timeMin,
+      time_max: timeMax,
+      user_ids: userIds,
+    };
+    if (roomIds && roomIds.length) body.room_ids = roomIds;
+    if (includeExternalCalendar !== undefined) body.include_external_calendar = !!includeExternalCalendar;
+    if (onlyBusy !== undefined) body.only_busy = !!onlyBusy;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/calendar/v4/freebusy/batch_get`,
+      method: 'POST',
+      body,
+      sdkFn: () => this.client.calendar.freebusy.batch({ data: body }),
+      label: 'getFreebusy',
+    });
+    return { freebusyLists: res.data.freebusy_lists || [], viaUser: !!res._viaUser };
+  },
+};

package/src/clients/official/contacts.js

@@ -0,0 +1,54 @@
+// src/clients/official/contacts.js
+// Mixed into LarkOfficialClient.prototype by ./index.js. Methods receive `this`
+// bound to the LarkOfficialClient instance, so they can use this.client,
+// this._safeSDKCall, this._asUserOrApp, this._uatREST, etc.
+
+module.exports = {
+  // --- User Name Resolution ---
+  //
+  // UAT-first (v1.3.7 C1.15 fix) so that calling get_user_info with the
+  // current user's own open_id resolves correctly. The bot path goes via the
+  // app-level contact API which can read tenant employees but does not have a
+  // notion of "the calling user" — so when the bot couldn't see a user (because
+  // contact scope wasn't granted, or the user happened to be the bot's owner)
+  // the previous code fell into a `null` and we surfaced "may be from external
+  // tenant", which was misleading. UAT can always see the current user.
+  async getUserById(userId, userIdType = 'open_id') {
+    if (this._userNameCache.has(userId)) return this._userNameCache.get(userId);
+
+    // 1. UAT path — works for the current user (self) and any colleague the
+    //    UAT owner has access to.
+    if (this.hasUAT) {
+      try {
+        const data = await this._uatREST(
+          'GET',
+          `/open-apis/contact/v3/users/${encodeURIComponent(userId)}`,
+          { query: { user_id_type: userIdType } },
+        );
+        if (data && data.code === 0 && data.data?.user?.name) {
+          this._userNameCache.set(userId, data.data.user.name);
+          return data.data.user.name;
+        }
+      } catch (e) {
+        console.error(`[feishu-user-plugin] getUserById(${userId}) as user failed: ${e.message}`);
+      }
+    }
+
+    // 2. Bot fallback — needs `contact:user.base:readonly` scope on the app.
+    try {
+      const res = await this.client.contact.user.get({
+        path: { user_id: userId },
+        params: { user_id_type: userIdType },
+      });
+      if (res.code === 0 && res.data?.user?.name) {
+        this._userNameCache.set(userId, res.data.user.name);
+        return res.data.user.name;
+      }
+    } catch (e) {
+      // Surface to the diagnostics log so users can see whether the failure
+      // was a missing contact scope vs an actual external user.
+      console.error(`[feishu-user-plugin] getUserById(${userId}) as bot failed: ${e.message}`);
+    }
+    return null;
+  },
+};