@zhin.js/adapter-lark 4.0.1 → 4.0.3

package/lib/index.d.ts

@@ -1,15 +1,5 @@
-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 { LarkEndpoint } from "./endpoint.js";
-export { LarkAdapter } from "./adapter.js";
-//# sourceMappingURL=index.d.ts.map
+export { formatInboundContent, formatOutboundBody, generateMessageId, headerValue, normalizeWebhookPath, readTextBody, resolveChatType, resolveLarkConfig, resolveSender, resolveTarget, verifySignature, type AccessToken, type LarkAdapterConfig, type LarkApiResponse, type LarkEventBody, type LarkMessage, type LarkSendBody, type LarkWireSegment, type ResolvedLarkConfig, } from './protocol.js';
+export { getLarkAgentDeps, registerLarkAgentEndpoint, setLarkAgentDeps, type LarkAgentDeps, type LarkAgentEndpoint, } from './lark-agent-deps.js';
+export { checkLarkPlatformPermit, larkGroupPermitResolver, normalizeLarkSenderForPermit, platformPermit, registerLarkPlatformPermitChecker, } from './platform-permit.js';
+export { LarkEndpoint, type LarkEndpointOptions, type LarkFetch, } from './endpoint.js';
+export { registerLarkWebhookRoutes, handleLarkWebhookRequest, type LarkWebhookHandler, } from './webhook.js';

package/lib/index.js

@@ -1,216 +1,5 @@
-/**
- * 飞书/Lark 适配器入口：类型扩展、导出、注册
- */
-import { usePlugin, createSceneManagementTools } from "zhin.js";
-import { LarkAdapter } from "./adapter.js";
-import { larkGroupPermitResolver, platformPermit, registerLarkPlatformPermitChecker, } from "./platform-permit.js";
-export * from "./types.js";
-export { LarkEndpoint } from "./endpoint.js";
-export { LarkAdapter } from "./adapter.js";
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-useContext("router", (router) => {
-    provide({
-        name: "lark",
-        description: "Lark/Feishu Endpoint 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 disposers = [];
-    disposers.push(registerLarkPlatformPermitChecker());
-    const sceneTools = createSceneManagementTools(lark, 'lark', { permitResolver: larkGroupPermitResolver, registerChecker: false });
-    disposers.push(...sceneTools.map(t => toolService.addTool(t, plugin.name)));
-    disposers.push(toolService.addTool({
-        name: 'lark_get_user',
-        description: '获取飞书用户信息',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                user_id: { type: 'string', description: '用户 ID (open_id)' },
-            },
-            required: ['endpoint_id', 'user_id'],
-        },
-        platforms: ['lark'],
-        tags: ['lark'],
-        execute: async (args) => {
-            const endpoint = lark.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            return await endpoint.getUserInfo(args.user_id);
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'lark_create_chat',
-        description: '创建飞书群聊',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                name: { type: 'string', description: '群名' },
-                members: { type: 'string', description: '成员 open_id 列表，逗号分隔' },
-                owner: { type: 'string', description: '群主 open_id（可选）' },
-            },
-            required: ['endpoint_id', 'name', 'members'],
-        },
-        platforms: ['lark'],
-        tags: ['lark'],
-        execute: async (args) => {
-            const endpoint = lark.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const chatId = await endpoint.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: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                chat_id: { type: 'string', description: '群聊 ID' },
-                name: { type: 'string', description: '新群名（可选）' },
-                description: { type: 'string', description: '新描述（可选）' },
-            },
-            required: ['endpoint_id', 'chat_id'],
-        },
-        platforms: ['lark'],
-        tags: ['lark'],
-        permissions: [platformPermit('chat_admin')],
-        execute: async (args) => {
-            const endpoint = lark.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const success = await endpoint.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: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                chat_id: { type: 'string', description: '群聊 ID' },
-                user_ids: { type: 'string', description: '用户 open_id 列表，逗号分隔' },
-            },
-            required: ['endpoint_id', 'chat_id', 'user_ids'],
-        },
-        platforms: ['lark'],
-        tags: ['lark'],
-        permissions: [platformPermit('chat_admin')],
-        execute: async (args) => {
-            const endpoint = lark.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const success = await endpoint.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: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                chat_id: { type: 'string', description: '群聊 ID' },
-                user_ids: { type: 'string', description: '用户 open_id 列表，逗号分隔' },
-            },
-            required: ['endpoint_id', 'chat_id', 'user_ids'],
-        },
-        platforms: ['lark'],
-        tags: ['lark'],
-        permissions: [platformPermit('manage_managers')],
-        execute: async (args) => {
-            const endpoint = lark.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const success = await endpoint.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: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                chat_id: { type: 'string', description: '群聊 ID' },
-                user_ids: { type: 'string', description: '用户 open_id 列表，逗号分隔' },
-            },
-            required: ['endpoint_id', 'chat_id', 'user_ids'],
-        },
-        platforms: ['lark'],
-        tags: ['lark'],
-        permissions: [platformPermit('manage_managers')],
-        execute: async (args) => {
-            const endpoint = lark.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const success = await endpoint.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: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                chat_id: { type: 'string', description: '群聊 ID' },
-            },
-            required: ['endpoint_id', 'chat_id'],
-        },
-        platforms: ['lark'],
-        tags: ['lark'],
-        execute: async (args) => {
-            const endpoint = lark.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const success = await endpoint.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: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                file_path: { type: 'string', description: '本地文件路径' },
-                file_type: { type: 'string', description: '文件类型', enum: ['opus', 'mp4', 'pdf', 'doc', 'xls', 'ppt', 'stream'] },
-            },
-            required: ['endpoint_id', '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 endpoint = lark.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const result = await endpoint.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, normalizeWebhookPath, readTextBody, resolveChatType, resolveLarkConfig, resolveSender, resolveTarget, verifySignature, } from './protocol.js';
+export { getLarkAgentDeps, registerLarkAgentEndpoint, setLarkAgentDeps, } from './lark-agent-deps.js';
+export { checkLarkPlatformPermit, larkGroupPermitResolver, normalizeLarkSenderForPermit, platformPermit, registerLarkPlatformPermitChecker, } from './platform-permit.js';
+export { LarkEndpoint, } from './endpoint.js';
+export { registerLarkWebhookRoutes, handleLarkWebhookRequest, } from './webhook.js';

package/lib/lark-agent-deps.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent tool deps for lark (user / chat / managers / upload).
+ * Endpoints register themselves on start; tools look up by endpoint id.
+ */
+export interface LarkAgentEndpoint {
+    getUserInfo(userId: string, userIdType?: 'open_id' | 'user_id' | 'union_id'): Promise<unknown>;
+    getChatInfo(chatId: string): Promise<unknown>;
+    uploadFile(filePath: string, fileType?: 'image' | 'file' | 'video' | 'audio'): Promise<string | null>;
+    createChat(name: string, userIds: string[], ownerId?: string): Promise<string | null>;
+    updateChatInfo(chatId: string, options: {
+        name?: string;
+        description?: string;
+    }): Promise<boolean>;
+    addChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
+    removeChatMembers(chatId: string, userIds: string[]): Promise<boolean>;
+    getChatMembers(chatId: string): Promise<unknown[]>;
+    dissolveChat(chatId: string): Promise<boolean>;
+    setChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
+    removeChatManagers(chatId: string, userIds: string[]): Promise<boolean>;
+}
+export interface LarkAgentDeps {
+    getEndpoint: (endpointId: string) => LarkAgentEndpoint;
+}
+export declare function registerLarkAgentEndpoint(endpointId: string, endpoint: LarkAgentEndpoint): () => void;
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export declare function setLarkAgentDeps(deps: LarkAgentDeps | null): void;
+export declare function getLarkAgentDeps(): LarkAgentDeps;

package/lib/lark-agent-deps.js

@@ -0,0 +1,30 @@
+/**
+ * Agent tool deps for lark (user / chat / managers / upload).
+ * Endpoints register themselves on start; tools look up by endpoint id.
+ */
+const endpoints = new Map();
+let override = null;
+export function registerLarkAgentEndpoint(endpointId, endpoint) {
+    endpoints.set(endpointId, endpoint);
+    return () => {
+        if (endpoints.get(endpointId) === endpoint) {
+            endpoints.delete(endpointId);
+        }
+    };
+}
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setLarkAgentDeps(deps) {
+    override = deps;
+}
+export function getLarkAgentDeps() {
+    if (override)
+        return override;
+    return {
+        getEndpoint(endpointId) {
+            const endpoint = endpoints.get(endpointId);
+            if (!endpoint)
+                throw new Error(`Endpoint ${endpointId} 不存在`);
+            return endpoint;
+        },
+    };
+}

package/lib/platform-permit.d.ts

@@ -1,7 +1,7 @@
 /**
  * 飞书 Lark platform permit
  */
-import type { Message } from 'zhin.js';
+import { type Message } from '@zhin.js/core';
 export declare function platformPermit(perm: string): string;
 export declare function larkGroupPermitResolver(logicalPerm: string): string;
 export declare function normalizeLarkSenderForPermit(input: {
@@ -13,4 +13,3 @@ export declare function normalizeLarkSenderForPermit(input: {
 };
 export declare function checkLarkPlatformPermit(perm: string, message: Message<any>): boolean;
 export declare function registerLarkPlatformPermitChecker(): () => void;
-//# sourceMappingURL=platform-permit.d.ts.map

package/lib/platform-permit.js

@@ -1,4 +1,7 @@
-import { registerPlatformPermitChecker } from 'zhin.js';
+/**
+ * 飞书 Lark platform permit
+ */
+import { registerPlatformPermitChecker } from '@zhin.js/core';
 const ADAPTER = 'lark';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -38,4 +41,3 @@ export function checkLarkPlatformPermit(perm, message) {
 export function registerLarkPlatformPermitChecker() {
     return registerPlatformPermitChecker(ADAPTER, checkLarkPlatformPermit);
 }
-//# sourceMappingURL=platform-permit.js.map

package/lib/protocol.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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';
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface LarkAdapterConfig {
+    readonly name?: string;
+    readonly appId?: string;
+    readonly appSecret?: string;
+    readonly encryptKey?: string;
+    readonly verificationToken?: string;
+    readonly webhookPath?: string;
+    readonly apiBaseUrl?: string;
+    readonly isFeishu?: boolean;
+    /** Transitional: legacy root `endpoints[]` with `context: lark`. */
+    readonly endpoints?: ReadonlyArray<Partial<ResolvedLarkConfig> & {
+        readonly context?: string;
+    }>;
+}
+export interface ResolvedLarkConfig {
+    readonly context: 'lark';
+    readonly name: 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;
+    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?: LarkAdapterConfig): ResolvedLarkConfig;
+export declare function normalizeWebhookPath(path: string): string;
+export declare function resolveChatType(chatId?: string): 'group' | 'private';
+export declare function resolveTarget(msg: LarkMessage): string;
+export declare function resolveSender(msg: LarkMessage): string;
+export declare function generateMessageId(msg: LarkMessage): string;
+/** Build inbound text for MessageGateway.receive. */
+export declare function formatInboundContent(msg: LarkMessage): string;
+export declare function verifySignature(encryptKey: string, timestamp: string, nonce: string, body: string, signature: 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>;

package/lib/protocol.js

@@ -0,0 +1,204 @@
+/**
+ * Lark/Feishu protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { createHash, timingSafeEqual } from 'node:crypto';
+export function resolveLarkConfig(config = {}) {
+    const entry = config.endpoints?.find((item) => item.context === 'lark');
+    const appId = config.appId ?? entry?.appId ?? process.env.LARK_APP_ID;
+    const appSecret = config.appSecret ?? entry?.appSecret ?? process.env.LARK_APP_SECRET;
+    if (!appId || !appSecret) {
+        throw new TypeError('Lark adapter requires appId + appSecret (plugins.<key> or endpoints with context: lark)');
+    }
+    const isFeishu = config.isFeishu ?? entry?.isFeishu ?? true;
+    const name = (typeof config.name === 'string' && config.name)
+        || (typeof entry?.name === 'string' && entry.name)
+        || process.env.LARK_BOT_NAME
+        || 'lark-bot';
+    const webhookPath = normalizeWebhookPath(config.webhookPath ?? entry?.webhookPath ?? '/lark/webhook');
+    const defaultBase = isFeishu
+        ? 'https://open.feishu.cn/open-apis'
+        : 'https://open.larksuite.com/open-apis';
+    const apiBaseUrl = (config.apiBaseUrl ?? entry?.apiBaseUrl ?? defaultBase).replace(/\/$/, '');
+    const encryptKey = config.encryptKey ?? entry?.encryptKey;
+    const verificationToken = config.verificationToken ?? entry?.verificationToken;
+    return {
+        context: 'lark',
+        name,
+        appId,
+        appSecret,
+        ...(encryptKey ? { encryptKey } : {}),
+        ...(verificationToken ? { verificationToken } : {}),
+        webhookPath,
+        apiBaseUrl,
+        isFeishu,
+    };
+}
+export function normalizeWebhookPath(path) {
+    const trimmed = path.trim() || '/lark/webhook';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+export function resolveChatType(chatId) {
+    return chatId?.startsWith('oc_') ? 'group' : 'private';
+}
+export function resolveTarget(msg) {
+    return msg.chat_id || 'unknown';
+}
+export function resolveSender(msg) {
+    return msg.sender?.sender_id?.open_id
+        || msg.sender?.sender_id?.user_id
+        || 'unknown';
+}
+export function generateMessageId(msg) {
+    return msg.message_id || `${msg.create_time ?? Date.now()}`;
+}
+/** Build inbound text for MessageGateway.receive. */
+export function formatInboundContent(msg) {
+    if (!msg.content || !msg.message_type)
+        return '';
+    try {
+        const parsed = JSON.parse(msg.content);
+        switch (msg.message_type) {
+            case 'text':
+                return typeof parsed.text === 'string' ? parsed.text : '';
+            case 'image':
+                return '[image]';
+            case 'file': {
+                const name = typeof parsed.file_name === 'string' ? parsed.file_name : '';
+                return name ? `[file: ${name}]` : '[file]';
+            }
+            case 'audio':
+                return '[audio]';
+            case 'video':
+                return '[video]';
+            case 'sticker':
+                return '[sticker]';
+            case 'post':
+            case 'interactive':
+                return `[${msg.message_type}]`;
+            case 'rich_text':
+                return '[rich_text]';
+            default:
+                return `[${msg.message_type}]`;
+        }
+    }
+    catch {
+        return '[消息解析失败]';
+    }
+}
+export function verifySignature(encryptKey, timestamp, nonce, body, signature) {
+    try {
+        const stringToSign = `${timestamp}${nonce}${encryptKey}${body}`;
+        const calculated = createHash('sha256').update(stringToSign).digest('hex');
+        const a = Buffer.from(calculated);
+        const b = Buffer.from(signature);
+        if (a.length !== b.length)
+            return false;
+        return timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Wire-encode an already-rendered outbound payload into Lark im/v1 message body.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundBody(payload) {
+    if (typeof payload === 'string') {
+        return {
+            msg_type: 'text',
+            content: JSON.stringify({ text: payload }),
+        };
+    }
+    const items = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    if (items.length === 0) {
+        const text = payload == null
+            ? ''
+            : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload);
+        return {
+            msg_type: 'text',
+            content: JSON.stringify({ text }),
+        };
+    }
+    const textParts = [];
+    let media = null;
+    for (const item of items) {
+        if (typeof item === 'string') {
+            textParts.push(item);
+            continue;
+        }
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'text':
+                textParts.push(String(data.content ?? data.text ?? ''));
+                break;
+            case 'at':
+                textParts.push(`<at user_id="${String(data.id ?? '')}">${String(data.name || data.id || '')}</at>`);
+                break;
+            case 'image':
+                if (!media) {
+                    media = {
+                        msg_type: 'image',
+                        content: JSON.stringify({
+                            image_key: data.file_key ?? data.key ?? data.url,
+                        }),
+                    };
+                }
+                break;
+            case 'file':
+                if (!media) {
+                    media = {
+                        msg_type: 'file',
+                        content: JSON.stringify({
+                            file_key: data.file_key ?? data.key,
+                        }),
+                    };
+                }
+                break;
+            case 'card':
+                if (!media) {
+                    media = {
+                        msg_type: 'interactive',
+                        content: JSON.stringify(data),
+                    };
+                }
+                break;
+            default:
+                textParts.push(`[${item.type}]`);
+        }
+    }
+    if (media)
+        return media;
+    return {
+        msg_type: 'text',
+        content: JSON.stringify({ text: textParts.join('') }),
+    };
+}
+export function headerValue(headers, name) {
+    const value = headers[name] ?? headers[name.toLowerCase()];
+    if (Array.isArray(value))
+        return value[0] ?? '';
+    return value ?? '';
+}
+export async function readTextBody(request, options = {}) {
+    const limit = options.limit ?? 1_048_576;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > limit) {
+            request.destroy();
+            throw new Error(`Request body exceeds ${limit} bytes`);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}

package/lib/webhook.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lark/Feishu webhook HTTP: verification → signature → challenge/event → admit.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { type LarkMessage, type ResolvedLarkConfig } from './protocol.js';
+export interface LarkWebhookHandler {
+    readonly config: ResolvedLarkConfig;
+    readonly isOpen: boolean;
+    admit(msg: LarkMessage): void;
+}
+export declare function registerLarkWebhookRoutes(http: HttpHost, handler: LarkWebhookHandler): HttpRouteRegistration[];
+export declare function handleLarkWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: LarkWebhookHandler): Promise<void>;