@zhin.js/adapter-lark 1.0.97 → 1.1.2

package/lib/index.js

@@ -1,209 +1,6 @@
-/**
- * 飞书/Lark 适配器入口：类型扩展、导出、注册
- */
-import { usePlugin, createGroupManagementTools } from "zhin.js";
-import { LarkAdapter } from "./adapter.js";
-export * from "./types.js";
-export { LarkBot } from "./bot.js";
-export { LarkAdapter } from "./adapter.js";
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-useContext("router", (router) => {
-    provide({
-        name: "lark",
-        description: "Lark/Feishu Bot Adapter",
-        mounted: async (p) => {
-            const adapter = new LarkAdapter(p, router);
-            await adapter.start();
-            return adapter;
-        },
-        dispose: async (adapter) => {
-            await adapter.stop();
-        },
-    });
-});
-useContext('tool', 'lark', (toolService, lark) => {
-    const groupTools = createGroupManagementTools(lark, 'lark');
-    const disposers = 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) => {
-            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) => {
-            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) => {
-            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) => {
-            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) => {
-            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) => {
-            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) => {
-            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) => {
-            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());
-});
-//# sourceMappingURL=index.js.map
+export { formatInboundContent, formatOutboundBody, generateMessageId, headerValue, larkInboundConversation, normalizeWebhookPath, readTextBody, resolveChatType, resolveLarkConfig, resolveSender, verifySignature, } from './protocol.js';
+export { larkClient } from './client.js';
+export { checkLarkPlatformPermit, larkGroupPermitResolver, normalizeLarkSenderForPermit, platformPermit, } from './platform-permit.js';
+export { LarkClient, LarkEndpoint, } from './endpoint.js';
+export { buildImageUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
+export { registerLarkWebhookRoutes, handleLarkWebhookRequest, } from './webhook.js';

package/lib/lark-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const larkRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/lark-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * 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/lib/media-upload.d.ts

@@ -0,0 +1,15 @@
+import { type MediaRef } from '@zhin.js/im-contract';
+export interface MediaBinary {
+    readonly data: Buffer;
+    readonly mimeType: string;
+    readonly fileName: string;
+}
+/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
+export declare function resolveMediaBinary(media: MediaRef, download?: (url: string) => Promise<Buffer>): Promise<MediaBinary>;
+/** /im/v1/images 的 multipart body（image_type=message 用于消息内图片）。 */
+export declare function buildImageUploadForm(binary: MediaBinary): FormData;
+/**
+ * 出站 image 段待上传的媒体引用（canonical `data.media` 唯一来源）：
+ * kind=file 为平台不透明引用（image_key/file_key），已物化无需再上传，返回 undefined。
+ */
+export declare function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined;

package/lib/media-upload.js

@@ -0,0 +1,58 @@
+/**
+ * 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 } from '@zhin.js/im-contract';
+const MIME_EXT = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/bmp': 'bmp',
+};
+/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
+export async function resolveMediaBinary(media, download = defaultDownload) {
+    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) {
+    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) {
+    // 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) {
+    if (!isMediaRef(data.media))
+        return undefined;
+    if (data.media.kind === 'file')
+        return undefined;
+    return data.media;
+}

package/lib/platform-permit.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 飞书 Lark platform permit
+ */
+import type { PermissionSubject } from '@zhin.js/permission';
+export declare function platformPermit(perm: string): string;
+export declare function larkGroupPermitResolver(logicalPerm: string): string;
+export declare function normalizeLarkSenderForPermit(input: {
+    isOwner?: boolean;
+    isAdmin?: boolean;
+}): {
+    role?: string;
+    permissions?: string[];
+};
+export declare function checkLarkPlatformPermit(perm: string, subject: PermissionSubject): boolean;

package/lib/platform-permit.js

@@ -0,0 +1,35 @@
+const ADAPTER = 'lark';
+export function platformPermit(perm) {
+    return `platform(${ADAPTER},${perm})`;
+}
+const FACTORY_PERM_MAP = {
+    scene_admin: 'chat_admin',
+    scene_owner: 'chat_owner',
+};
+export function larkGroupPermitResolver(logicalPerm) {
+    return platformPermit(FACTORY_PERM_MAP[logicalPerm] ?? logicalPerm);
+}
+export function normalizeLarkSenderForPermit(input) {
+    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, subject) {
+    const role = subject.sender?.role?.[0];
+    const permissions = subject.sender?.permissions ?? [];
+    const has = (t) => 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;
+    }
+}

package/lib/protocol.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Lark/Feishu protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import type { IncomingMessage } from 'node:http';
+import { type ConversationRef } from '@zhin.js/im-contract';
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface LarkEndpointConfig {
+    readonly id: string;
+    readonly appId: string;
+    readonly appSecret: string;
+    readonly encryptKey?: string;
+    readonly verificationToken?: string;
+    readonly webhookPath?: string;
+    readonly apiBaseUrl?: string;
+    readonly isFeishu?: boolean;
+}
+export interface ResolvedLarkConfig {
+    readonly context: 'lark';
+    readonly id: string;
+    readonly appId: string;
+    readonly appSecret: string;
+    readonly encryptKey?: string;
+    readonly verificationToken?: string;
+    readonly webhookPath: string;
+    readonly apiBaseUrl: string;
+    readonly isFeishu: boolean;
+}
+export interface LarkMessage {
+    readonly message_id?: string;
+    readonly root_id?: string;
+    readonly parent_id?: string;
+    readonly create_time?: string;
+    readonly update_time?: string;
+    readonly chat_id?: string;
+    /** 事件携带的会话类型（'p2p' | 'group'）；p2p 的 chat_id 也是 oc_ 开头。 */
+    readonly chat_type?: string;
+    readonly sender?: {
+        readonly sender_id?: {
+            readonly user_id?: string;
+            readonly open_id?: string;
+            readonly union_id?: string;
+        };
+        readonly sender_type?: string;
+        readonly tenant_key?: string;
+    };
+    readonly message_type?: string;
+    readonly content?: string;
+    readonly mentions?: ReadonlyArray<{
+        readonly key?: string;
+        readonly id?: {
+            readonly user_id?: string;
+            readonly open_id?: string;
+            readonly union_id?: string;
+        };
+        readonly name?: string;
+        readonly tenant_key?: string;
+    }>;
+}
+export interface LarkEventBody {
+    readonly uuid?: string;
+    readonly token?: string;
+    readonly ts?: string;
+    readonly type?: string;
+    readonly challenge?: string;
+    readonly event?: {
+        readonly sender?: LarkMessage['sender'];
+        readonly message?: LarkMessage;
+        readonly [key: string]: unknown;
+    };
+}
+export interface AccessToken {
+    token: string;
+    expires_in: number;
+    timestamp: number;
+}
+export interface LarkApiResponse {
+    readonly code: number;
+    readonly msg?: string;
+    readonly tenant_access_token?: string;
+    readonly expire?: number;
+    readonly data?: Record<string, unknown>;
+    readonly [key: string]: unknown;
+}
+export interface LarkWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface LarkSendBody {
+    readonly msg_type: string;
+    readonly content: string;
+}
+export declare function resolveLarkConfig(config: LarkEndpointConfig): ResolvedLarkConfig;
+export declare function normalizeWebhookPath(path: string): string;
+export declare function resolveChatType(chatId?: string, chatType?: string): 'group' | 'private';
+/**
+ * 入站归一化 → ConversationRef：`chat_type` 为 'group' 的会话映射为 group，
+ * p2p 单聊映射为 private；id 一律为平台 chat_id。Lark 无 guild/频道容器，
+ * 不产生 `parent`。
+ */
+export declare function larkInboundConversation(endpointKey: string, msg: LarkMessage): ConversationRef;
+export declare function resolveSender(msg: LarkMessage): string;
+export declare function generateMessageId(msg: LarkMessage): string;
+/** Build inbound text for OutboundMessageService.receive. */
+export declare function formatInboundContent(msg: LarkMessage): string;
+/** 验签时间戳时效窗口（防重放）。 */
+export declare const LARK_SIGNATURE_MAX_AGE_MS: number;
+export declare function verifySignature(encryptKey: string, timestamp: string, nonce: string, body: string, signature: string, nowMs?: number): boolean;
+/** timing-safe 比较 webhook verification token（长度不同快速失败）。 */
+export declare function verifyToken(token: string, expected: string): boolean;
+/**
+ * Wire-encode an already-rendered outbound payload into Lark im/v1 message body.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare function formatOutboundBody(payload: unknown): LarkSendBody;
+export declare function headerValue(headers: IncomingMessage['headers'], name: string): string;
+export declare function readTextBody(request: IncomingMessage, options?: {
+    readonly limit?: number;
+}): Promise<string>;