feishu-user-plugin 1.3.5 → 1.3.7

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;
+  },
+};

package/src/clients/official/docs.js

@@ -0,0 +1,301 @@
+// src/clients/official/docs.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, this.uploadMedia, etc. — all defined in
+// base.js or mixed in via other domain modules.
+
+const { buildEmptyImageBlock, buildReplaceImagePayload, buildEmptyFileBlock, buildReplaceFilePayload } = require('../../doc-blocks');
+
+module.exports = {
+  // --- Docs ---
+
+  async searchDocs(query, { pageSize = 10, pageToken } = {}) {
+    const res = await this._safeSDKCall(
+      () => this.client.request({
+        method: 'POST', url: '/open-apis/suite/docs-api/search/object',
+        data: { search_key: query, count: pageSize, offset: pageToken ? parseInt(pageToken) : 0, owner_ids: [], chat_ids: [], docs_types: [] },
+      }),
+      'searchDocs'
+    );
+    return { items: res.data.docs_entities || [], hasMore: res.data.has_more };
+  },
+
+  async readDoc(documentId) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/raw_content`,
+      query: { lang: '0' },
+      sdkFn: () => this.client.docx.document.rawContent({ path: { document_id: documentId }, params: { lang: 0 } }),
+      label: 'readDoc',
+    });
+    return { content: res.data.content };
+  },
+
+  async createDoc(title, folderId, { wikiSpaceId, wikiParentNodeToken } = {}) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents`,
+      method: 'POST',
+      body: { title, folder_token: folderId || '' },
+      sdkFn: () => this.client.docx.document.create({ data: { title, folder_token: folderId || '' } }),
+      label: 'createDoc',
+    });
+    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) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks`,
+      query: { page_size: '500' },
+      sdkFn: () => this.client.docx.documentBlock.list({ path: { document_id: documentId }, params: { page_size: 500 } }),
+      label: 'getDocBlocks',
+    });
+    return { items: res.data.items || [] };
+  },
+
+  async createDocBlock(documentId, parentBlockId, children, index) {
+    const data = { children };
+    if (index !== undefined) data.index = index;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${parentBlockId}/children`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.docx.documentBlockChildren.create({
+        path: { document_id: documentId, block_id: parentBlockId },
+        data,
+      }),
+      label: 'createDocBlock',
+    });
+    return { blocks: res.data.children || [], fallbackWarning: res._fallbackWarning || null };
+  },
+
+  async updateDocBlock(documentId, blockId, updateBody) {
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,
+      method: 'PATCH',
+      body: updateBody,
+      sdkFn: () => this.client.docx.documentBlock.patch({
+        path: { document_id: documentId, block_id: blockId },
+        data: updateBody,
+      }),
+      label: 'updateDocBlock',
+    });
+    return { block: res.data.block };
+  },
+
+  async deleteDocBlocks(documentId, parentBlockId, startIndex, endIndex) {
+    await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${parentBlockId}/children/batch_delete`,
+      method: 'DELETE',
+      body: { start_index: startIndex, end_index: endIndex },
+      sdkFn: () => this.client.docx.documentBlockChildren.batchDelete({
+        path: { document_id: documentId, block_id: parentBlockId },
+        data: { start_index: startIndex, end_index: endIndex },
+      }),
+      label: 'deleteDocBlocks',
+    });
+    return { deleted: true };
+  },
+
+  // 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.uploadMedia(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
+  // uploadMedia 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 };
+  },
+
+  // Create a file-attachment block in a docx, mirroring createDocBlockWithImage:
+  //   1) create empty file placeholder block
+  //   2) upload the binary via uploadMedia(parent_type=docx_file)
+  //   3) PATCH with replace_file.token to attach
+  // Returns { blockId, fileToken, viaUser, fallbackWarning }.
+  async createDocBlockWithFile(documentId, parentBlockId, { filePath, fileToken, index } = {}) {
+    if (!filePath && !fileToken) {
+      throw new Error('createDocBlockWithFile: either filePath or fileToken is required');
+    }
+    const placeholder = buildEmptyFileBlock();
+    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: 'createDocBlockWithFile.placeholder',
+    });
+    // Feishu auto-wraps a FILE block (block_type=23) in a VIEW block
+    // (block_type=33) — the create response returns the OUTER view block.
+    // We need the inner file block's id for both the media upload (parent_node)
+    // and the replace_file PATCH. Walk children to find it; fall back to a
+    // get_doc_blocks lookup if the response didn't materialize the descendant.
+    const newBlock = (created.data.children || [])[0];
+    const outerBlockId = newBlock?.block_id;
+    if (!outerBlockId) throw new Error(`createDocBlockWithFile: placeholder creation returned no block_id: ${JSON.stringify(created.data).slice(0, 400)}`);
+    // Feishu auto-wraps a FILE block (23) in a VIEW block (33). The create
+    // response's outer block is the view; we need to find the inner file
+    // block for both the media upload (parent_node) and the replace_file PATCH.
+    let blockId = outerBlockId;
+    if (newBlock.block_type !== 23) {
+      const inner = await this._findFileChildOf(documentId, outerBlockId, newBlock.children);
+      if (!inner) throw new Error(`createDocBlockWithFile: could not locate inner FILE block under view ${outerBlockId}`);
+      blockId = inner;
+    }
+
+    let finalToken = fileToken;
+    let viaUser = !!created._viaUser;
+    let fallbackWarning = created._fallbackWarning || null;
+    if (!finalToken) {
+      const uploaded = await this.uploadMedia(filePath, blockId, 'docx_file');
+      finalToken = uploaded.fileToken;
+      viaUser = viaUser && uploaded.viaUser;
+    }
+
+    const patch = buildReplaceFilePayload(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: 'createDocBlockWithFile.replaceFile',
+    });
+
+    return { blockId, viewBlockId: outerBlockId !== blockId ? outerBlockId : undefined, fileToken: finalToken, viaUser, fallbackWarning };
+  },
+
+  // Helper for createDocBlockWithFile — given a view block id and the children
+  // array surfaced by the create response (just IDs in docx v1), find the
+  // FILE child (block_type=23). If no children list was returned, fall back
+  // to listing the doc and walking by parent_id.
+  async _findFileChildOf(documentId, viewBlockId, childIds) {
+    if (Array.isArray(childIds) && childIds.length > 0) {
+      // childIds[0] is most likely the file block — verify with a get
+      for (const childId of childIds) {
+        try {
+          const res = await this._asUserOrApp({
+            uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${childId}`,
+            method: 'GET',
+            sdkFn: () => this.client.docx.documentBlock.get({ path: { document_id: documentId, block_id: childId } }),
+            label: '_findFileChildOf.get',
+          });
+          if (res?.data?.block?.block_type === 23) return childId;
+        } catch (_) { /* fall through */ }
+      }
+      // None matched directly; return the first as best-effort
+      return childIds[0];
+    }
+    // Fallback: list all blocks and find a 23 whose parent_id is the view block
+    try {
+      const res = await this._asUserOrApp({
+        uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks`,
+        method: 'GET',
+        sdkFn: () => this.client.docx.documentBlock.list({ path: { document_id: documentId } }),
+        label: '_findFileChildOf.list',
+      });
+      const items = res?.data?.items || [];
+      const match = items.find(b => b.block_type === 23 && b.parent_id === viewBlockId);
+      return match?.block_id || null;
+    } catch (_) {
+      return null;
+    }
+  },
+
+  // Replace an existing file block's media token. Expects an already-uploaded
+  // file token (use uploadMedia with parent_type=docx_file, or
+  // create_doc_block's file_path shortcut).
+  async updateDocBlockFile(documentId, blockId, fileToken) {
+    const patch = buildReplaceFilePayload(fileToken);
+    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: 'updateDocBlockFile',
+    });
+    return { blockId, fileToken };
+  },
+};

package/src/clients/official/drive.js

@@ -0,0 +1,77 @@
+// src/clients/official/drive.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 = {
+  // --- Drive ---
+
+  async listFiles(folderToken, { pageSize = 50, pageToken } = {}) {
+    const params = { page_size: pageSize, folder_token: folderToken || '' };
+    if (pageToken) params.page_token = pageToken;
+    const res = await this._safeSDKCall(() => this.client.drive.file.list({ params }), 'listFiles');
+    return { items: res.data.files || [], hasMore: res.data.has_more };
+  },
+
+  async createFolder(name, parentToken) {
+    const body = { name, folder_token: parentToken || '' };
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/drive/v1/files/create_folder`,
+      method: 'POST',
+      body,
+      sdkFn: () => this.client.drive.file.createFolder({ data: body }),
+      label: 'createFolder',
+    });
+    return { token: res.data.token, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
+  },
+
+  // --- Drive: File Operations ---
+
+  async copyFile(fileToken, name, folderToken, type) {
+    const data = { name, folder_token: folderToken || '' };
+    if (type) data.type = type;
+    // _asUserOrApp so UAT-owned files (created by the user) can be copied
+    // without the bot needing edit permission. Bot-only path returned 1062501.
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/drive/v1/files/${fileToken}/copy`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.drive.file.copy({ path: { file_token: fileToken }, data }),
+      label: 'copyFile',
+    });
+    return { file: res.data.file, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
+  },
+
+  async moveFile(fileToken, folderToken, type) {
+    // Feishu drive move requires `type` in the request body — without it Feishu
+    // returns 1061002 ("invalid params"). type values: file, folder, doc,
+    // sheet, bitable, docx, mindnote, slides. _asUserOrApp so user-owned
+    // resources can be moved without bot edit permission.
+    const data = { folder_token: folderToken || '' };
+    if (type) data.type = type;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/drive/v1/files/${fileToken}/move`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.drive.file.move({ path: { file_token: fileToken }, data }),
+      label: 'moveFile',
+    });
+    return { taskId: res.data.task_id, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
+  },
+
+  async deleteFile(fileToken, type) {
+    // _asUserOrApp so UAT-owned files can be deleted by the user. Bot-only
+    // path returned 1062501 because the bot lacks edit permission on
+    // user-created resources. Feishu also requires `type` as a query param.
+    const params = { type: type || 'file' };
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/drive/v1/files/${fileToken}`,
+      method: 'DELETE',
+      query: params,
+      sdkFn: () => this.client.drive.file.delete({ path: { file_token: fileToken }, params }),
+      label: 'deleteFile',
+    });
+    return { taskId: res.data.task_id, viaUser: !!res._viaUser, fallbackWarning: res._fallbackWarning || null };
+  },
+};

package/src/clients/official/groups.js

@@ -0,0 +1,68 @@
+// src/clients/official/groups.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 = {
+  // --- IM: Chat Management ---
+
+  async createChat({ name, description, userIds, botIds } = {}) {
+    const data = {};
+    if (name) data.name = name;
+    if (description) data.description = description;
+    if (userIds) data.user_id_list = userIds;
+    if (botIds) data.bot_id_list = botIds;
+    const res = await this._safeSDKCall(
+      () => this.client.im.chat.create({ params: { user_id_type: 'open_id' }, data }),
+      'createChat'
+    );
+    return { chatId: res.data.chat_id };
+  },
+
+  async updateChat(chatId, { name, description } = {}) {
+    const data = {};
+    if (name) data.name = name;
+    if (description) data.description = description;
+    const res = await this._safeSDKCall(
+      () => this.client.im.chat.update({ path: { chat_id: chatId }, data }),
+      'updateChat'
+    );
+    return { updated: true };
+  },
+
+  async listChatMembers(chatId, { pageSize = 50, pageToken } = {}) {
+    const res = await this._safeSDKCall(
+      () => this.client.im.chatMembers.get({
+        path: { chat_id: chatId },
+        params: { member_id_type: 'open_id', page_size: pageSize, page_token: pageToken },
+      }),
+      'listChatMembers'
+    );
+    return { items: res.data.items || [], hasMore: res.data.has_more, pageToken: res.data.page_token };
+  },
+
+  async addChatMembers(chatId, userIds, memberIdType = 'open_id') {
+    const res = await this._safeSDKCall(
+      () => this.client.im.chatMembers.create({
+        path: { chat_id: chatId },
+        params: { member_id_type: memberIdType },
+        data: { id_list: userIds },
+      }),
+      'addChatMembers'
+    );
+    return { invalidIds: res.data.invalid_id_list || [] };
+  },
+
+  async removeChatMembers(chatId, userIds, memberIdType = 'open_id') {
+    const res = await this._safeSDKCall(
+      () => this.client.im.chatMembers.delete({
+        path: { chat_id: chatId },
+        params: { member_id_type: memberIdType },
+        data: { id_list: userIds },
+      }),
+      'removeChatMembers'
+    );
+    return { invalidIds: res.data.invalid_id_list || [] };
+  },
+};