@zhin.js/adapter-lark 1.0.97 → 1.1.0

package/src/index.ts

@@ -1,227 +1,51 @@
-/**
- * 飞书/Lark 适配器入口：类型扩展、导出、注册
- */
-import { usePlugin, type Plugin, type Context, type IGroupManagement, createGroupManagementTools, type ToolFeature } from "zhin.js";
-import { LarkAdapter } from "./adapter.js";
-
-declare module "zhin.js" {
-  namespace Plugin {
-    interface Contexts {
-      router: import("@zhin.js/host-router").Router;
-    }
-  }
-  interface Adapters {
-    lark: LarkAdapter;
-  }
-}
-
-export * from "./types.js";
-export { LarkBot } from "./bot.js";
-export { LarkAdapter } from "./adapter.js";
-
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-
-(useContext as (key: string, fn: (router: any) => void) => void)("router", (router) => {
-  provide({
-    name: "lark",
-    description: "Lark/Feishu Bot Adapter",
-    mounted: async (p: Plugin) => {
-      const adapter = new LarkAdapter(p, router);
-      await adapter.start();
-      return adapter;
-    },
-    dispose: async (adapter: LarkAdapter) => {
-      await adapter.stop();
-    },
-  } as Context<"lark">);
-});
-
-useContext('tool', 'lark', (toolService: ToolFeature, lark: LarkAdapter) => {
-  const groupTools = createGroupManagementTools(
-    lark as unknown as IGroupManagement,
-    'lark',
-  );
-  const disposers: (() => void)[] = groupTools.map(t => toolService.addTool(t, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'lark_get_user',
-    description: '获取飞书用户信息',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        user_id: { type: 'string', description: '用户 ID (open_id)' },
-      },
-      required: ['bot', 'user_id'],
-    },
-    platforms: ['lark'],
-    tags: ['lark'],
-    execute: async (args: Record<string, any>) => {
-      const bot = lark.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      return await bot.getUserInfo(args.user_id);
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'lark_create_chat',
-    description: '创建飞书群聊',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        name: { type: 'string', description: '群名' },
-        members: { type: 'string', description: '成员 open_id 列表，逗号分隔' },
-        owner: { type: 'string', description: '群主 open_id（可选）' },
-      },
-      required: ['bot', 'name', 'members'],
-    },
-    platforms: ['lark'],
-    tags: ['lark'],
-    execute: async (args: Record<string, any>) => {
-      const bot = lark.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const chatId = await bot.createChat(args.name, args.members.split(','), args.owner);
-      return { success: !!chatId, chat_id: chatId, message: chatId ? `群聊创建成功: ${chatId}` : '创建失败' };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'lark_update_chat',
-    description: '更新飞书群聊信息（群名、描述）',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        chat_id: { type: 'string', description: '群聊 ID' },
-        name: { type: 'string', description: '新群名（可选）' },
-        description: { type: 'string', description: '新描述（可选）' },
-      },
-      required: ['bot', 'chat_id'],
-    },
-    platforms: ['lark'],
-    tags: ['lark'],
-    execute: async (args: Record<string, any>) => {
-      const bot = lark.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const success = await bot.updateChatInfo(args.chat_id, { name: args.name, description: args.description });
-      return { success, message: success ? '群信息更新成功' : '更新失败' };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'lark_add_members',
-    description: '添加飞书群成员',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        chat_id: { type: 'string', description: '群聊 ID' },
-        user_ids: { type: 'string', description: '用户 open_id 列表，逗号分隔' },
-      },
-      required: ['bot', 'chat_id', 'user_ids'],
-    },
-    platforms: ['lark'],
-    tags: ['lark'],
-    execute: async (args: Record<string, any>) => {
-      const bot = lark.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const success = await bot.addChatMembers(args.chat_id, args.user_ids.split(','));
-      return { success, message: success ? '成员添加成功' : '添加失败' };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'lark_set_managers',
-    description: '设置飞书群管理员',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        chat_id: { type: 'string', description: '群聊 ID' },
-        user_ids: { type: 'string', description: '用户 open_id 列表，逗号分隔' },
-      },
-      required: ['bot', 'chat_id', 'user_ids'],
-    },
-    platforms: ['lark'],
-    tags: ['lark'],
-    execute: async (args: Record<string, any>) => {
-      const bot = lark.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const success = await bot.setChatManagers(args.chat_id, args.user_ids.split(','));
-      return { success, message: success ? '管理员设置成功' : '设置失败' };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'lark_remove_managers',
-    description: '移除飞书群管理员',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        chat_id: { type: 'string', description: '群聊 ID' },
-        user_ids: { type: 'string', description: '用户 open_id 列表，逗号分隔' },
-      },
-      required: ['bot', 'chat_id', 'user_ids'],
-    },
-    platforms: ['lark'],
-    tags: ['lark'],
-    execute: async (args: Record<string, any>) => {
-      const bot = lark.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const success = await bot.removeChatManagers(args.chat_id, args.user_ids.split(','));
-      return { success, message: success ? '管理员移除成功' : '移除失败' };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'lark_dissolve_chat',
-    description: '解散飞书群聊（需要群主权限）',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        chat_id: { type: 'string', description: '群聊 ID' },
-      },
-      required: ['bot', 'chat_id'],
-    },
-    platforms: ['lark'],
-    tags: ['lark'],
-    execute: async (args: Record<string, any>) => {
-      const bot = lark.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const success = await bot.dissolveChat(args.chat_id);
-      return { success, message: success ? '群聊已解散' : '解散失败' };
-    },
-  }, plugin.name));
-
-  disposers.push(toolService.addTool({
-    name: 'lark_upload_file',
-    description: '上传文件到飞书（opus/mp4/pdf/doc/xls/ppt/stream）',
-    parameters: {
-      type: 'object',
-      properties: {
-        bot: { type: 'string', description: 'Bot 名称' },
-        file_path: { type: 'string', description: '本地文件路径' },
-        file_type: { type: 'string', description: '文件类型', enum: ['opus', 'mp4', 'pdf', 'doc', 'xls', 'ppt', 'stream'] },
-      },
-      required: ['bot', 'file_path', 'file_type'],
-    },
-    platforms: ['lark'],
-    tags: ['lark'],
-    execute: async (args: Record<string, any>) => {
-      const validTypes = ['opus', 'mp4', 'pdf', 'doc', 'xls', 'ppt', 'stream'];
-      if (!validTypes.includes(args.file_type)) {
-        throw new Error(`不支持的文件类型: ${args.file_type}，支持: ${validTypes.join(', ')}`);
-      }
-      const bot = lark.bots.get(args.bot);
-      if (!bot) throw new Error(`Bot ${args.bot} 不存在`);
-      const result = await bot.uploadFile(args.file_path, args.file_type);
-      return { success: true, file_key: result, message: `文件已上传，file_key: ${result}` };
-    },
-  }, plugin.name));
-
-  return () => disposers.forEach(d => d());
-});
+export {
+  formatInboundContent,
+  formatOutboundBody,
+  generateMessageId,
+  headerValue,
+  larkInboundConversation,
+  normalizeWebhookPath,
+  readTextBody,
+  resolveChatType,
+  resolveLarkConfig,
+  resolveSender,
+  verifySignature,
+  type AccessToken,
+  type LarkAdapterConfig,
+  type LarkApiResponse,
+  type LarkEventBody,
+  type LarkMessage,
+  type LarkSendBody,
+  type LarkWireSegment,
+  type ResolvedLarkConfig,
+} from './protocol.js';
+
+export { larkClient, type LarkClientEventMap } from './client.js';
+
+export {
+  checkLarkPlatformPermit,
+  larkGroupPermitResolver,
+  normalizeLarkSenderForPermit,
+  platformPermit,
+} from './platform-permit.js';
+
+export {
+  LarkClient,
+  LarkEndpoint,
+  type LarkClientApi,
+  type LarkEndpointOptions,
+  type LarkFetch,
+} from './endpoint.js';
+
+export {
+  buildImageUploadForm,
+  readOutboundImageMedia,
+  resolveMediaBinary,
+  type MediaBinary,
+} from './media-upload.js';
+
+export {
+  registerLarkWebhookRoutes,
+  handleLarkWebhookRequest,
+  type LarkWebhookHandler,
+} from './webhook.js';

package/src/lark-endpoint-commands.ts

@@ -0,0 +1,20 @@
+/**
+ * `lark.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { larkRuntimeStateToken } from './lark-runtime-state.js';
+
+export const larkEndpointCommands = createEndpointCommands({
+  adapterKey: 'lark',
+  adapterDisplayName: 'Lark',
+  fields: [
+    { key: 'appId', required: true, env: true, description: '飞书 App ID' },
+    { key: 'appSecret', required: true, env: true, description: '飞书 App Secret' },
+    { key: 'encryptKey', env: true, description: '事件加密 key' },
+    { key: 'verificationToken', env: true, description: '事件验证 token' },
+  ],
+  running: (use) => use(larkRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `appId: ${String(entry.appId)}`,
+}, defineCommand);

package/src/lark-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * Lark 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `lark.endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+
+export const larkRuntimeStateToken = defineEndpointRuntimeStateToken('lark');

package/src/media-upload.ts

@@ -0,0 +1,69 @@
+/**
+ * Lark 图片上传（im/v1 消息 image 段需要 image_key）。
+ * 接口：POST {apiBaseUrl}/im/v1/images（multipart：image_type=message + image）
+ * 与 im/v1/messages 同属 IM 接口域（同一 tenant_access_token），不引入额外授权域。
+ */
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { isMediaRef, type MediaRef } from '@zhin.js/core';
+
+export interface MediaBinary {
+  readonly data: Buffer;
+  readonly mimeType: string;
+  readonly fileName: string;
+}
+
+const MIME_EXT: Record<string, string> = {
+  'image/jpeg': 'jpg',
+  'image/png': 'png',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/bmp': 'bmp',
+};
+
+/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
+export async function resolveMediaBinary(
+  media: MediaRef,
+  download: (url: string) => Promise<Buffer> = defaultDownload,
+): Promise<MediaBinary> {
+  const mimeType = media.mime_type ?? 'image/png';
+  const ext = MIME_EXT[mimeType] ?? 'png';
+  if (media.kind === 'base64') {
+    const value = media.value.startsWith('base64://')
+      ? media.value.slice('base64://'.length)
+      : media.value;
+    return { data: Buffer.from(value, 'base64'), mimeType, fileName: `image.${ext}` };
+  }
+  if (media.kind === 'path') {
+    const path = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
+    return { data: await readFile(path), mimeType, fileName: basename(path) };
+  }
+  return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+}
+
+async function defaultDownload(url: string): Promise<Buffer> {
+  const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+  if (!response.ok) throw new Error(`download failed: HTTP ${response.status}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+/** /im/v1/images 的 multipart body（image_type=message 用于消息内图片）。 */
+export function buildImageUploadForm(binary: MediaBinary): FormData {
+  // Buffer 的 ArrayBufferLike 不满足 BlobPart（SharedArrayBuffer 分支），拷贝为 Uint8Array<ArrayBuffer>
+  const bytes = new Uint8Array(binary.data.byteLength);
+  bytes.set(binary.data);
+  const form = new FormData();
+  form.append('image_type', 'message');
+  form.append('image', new Blob([bytes], { type: binary.mimeType }), binary.fileName);
+  return form;
+}
+
+/**
+ * 出站 image 段待上传的媒体引用（canonical `data.media` 唯一来源）：
+ * kind=file 为平台不透明引用（image_key/file_key），已物化无需再上传，返回 undefined。
+ */
+export function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined {
+  if (!isMediaRef(data.media)) return undefined;
+  if (data.media.kind === 'file') return undefined;
+  return data.media;
+}

package/src/platform-permit.ts

@@ -0,0 +1,50 @@
+/**
+ * 飞书 Lark platform permit
+ */
+import type { PermissionSubject } from '@zhin.js/permission';
+
+const ADAPTER = 'lark';
+
+export function platformPermit(perm: string): string {
+  return `platform(${ADAPTER},${perm})`;
+}
+
+const FACTORY_PERM_MAP: Record<string, string> = {
+  scene_admin: 'chat_admin',
+  scene_owner: 'chat_owner',
+};
+
+export function larkGroupPermitResolver(logicalPerm: string): string {
+  return platformPermit(FACTORY_PERM_MAP[logicalPerm] ?? logicalPerm);
+}
+
+export function normalizeLarkSenderForPermit(input: {
+  isOwner?: boolean;
+  isAdmin?: boolean;
+}): { role?: string; permissions?: string[] } {
+  if (input.isOwner) {
+    return { role: 'owner', permissions: ['chat_owner', 'chat_admin', 'manage_managers'] };
+  }
+  if (input.isAdmin) {
+    return { role: 'admin', permissions: ['chat_admin'] };
+  }
+  return { role: 'member', permissions: [] };
+}
+
+export function checkLarkPlatformPermit(perm: string, subject: PermissionSubject): boolean {
+  const role = subject.sender?.role?.[0];
+  const permissions = subject.sender?.permissions ?? [];
+  const has = (t: string) => permissions.includes(t);
+
+  switch (perm) {
+    case 'chat_owner':
+      return role === 'owner' || has('chat_owner');
+    case 'chat_admin':
+      return role === 'owner' || role === 'admin' || has('chat_admin') || has('chat_owner');
+    case 'manage_managers':
+      return role === 'owner' || has('chat_owner');
+    default:
+      return false;
+  }
+}
+