@zhin.js/adapter-lark 4.0.2 → 4.0.3

package/lib/endpoint.js

@@ -0,0 +1,333 @@
+/**
+ * LarkEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
+ */
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { registerLarkAgentEndpoint } from './lark-agent-deps.js';
+import { formatInboundContent, formatOutboundBody, generateMessageId, resolveChatType, resolveSender, resolveTarget, } from './protocol.js';
+import { registerLarkWebhookRoutes } from './webhook.js';
+const logger = getLogger('lark');
+export class LarkEndpoint {
+    #options;
+    #fetch;
+    #routeReleases = [];
+    #accessToken = { token: '', expires_in: 0, timestamp: 0 };
+    #refreshPromise = null;
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+    }
+    /** Used by webhook handler. */
+    get isOpen() {
+        return this.#open;
+    }
+    get config() {
+        return this.#options.config;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        try {
+            await this.#refreshAccessToken();
+            this.#unregisterAgent = registerLarkAgentEndpoint(this.#options.config.name, this);
+            this.#routeReleases.push(...registerLarkWebhookRoutes(this.#options.http, this));
+            logger.debug(formatCompact({
+                endpoint: this.#options.config.name,
+                op: 'webhook',
+                path: this.#options.config.webhookPath,
+            }));
+        }
+        catch (error) {
+            await this.stop();
+            logger.error('Failed to connect Lark endpoint:', error);
+            throw error;
+        }
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const content = formatOutboundBody(payload);
+        const data = await this.#request('/im/v1/messages', {
+            method: 'POST',
+            params: { receive_id_type: 'chat_id' },
+            body: {
+                receive_id: target,
+                msg_type: content.msg_type,
+                content: content.content,
+            },
+        });
+        if (data.code !== 0) {
+            throw new Error(`Failed to send message: ${data.msg}`);
+        }
+        const messageId = data.data?.message_id || `${Date.now()}`;
+        logger.debug(formatCompact({
+            op: 'send',
+            endpoint: this.#options.config.name,
+            to: target,
+            id: messageId,
+        }));
+        return messageId;
+    }
+    /** Test / internal: admit a parsed message when open (non-webhook path). */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        const target = resolveTarget(msg);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content: formatInboundContent(msg),
+            sender: resolveSender(msg),
+            id: generateMessageId(msg),
+            metadata: Object.freeze({
+                messageType: msg.message_type,
+                chatType: resolveChatType(msg.chat_id),
+                endpoint: this.#options.config.name,
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'lark_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async getUserInfo(userId, userIdType = 'open_id') {
+        try {
+            const data = await this.#request(`/contact/v3/users/${userId}`, {
+                method: 'GET',
+                params: { user_id_type: userIdType },
+            });
+            return data.data?.user ?? null;
+        }
+        catch (error) {
+            logger.error('Failed to get user info:', error);
+            return null;
+        }
+    }
+    async getChatInfo(chatId) {
+        try {
+            const data = await this.#request(`/im/v1/chats/${chatId}`, { method: 'GET' });
+            return data.data ?? null;
+        }
+        catch (error) {
+            logger.error('Failed to get chat info:', error);
+            return null;
+        }
+    }
+    async uploadFile(filePath, fileType = 'file') {
+        try {
+            await this.#ensureAccessToken();
+            const buf = await readFile(filePath);
+            const form = new FormData();
+            form.append('file', new Blob([buf]), basename(filePath));
+            form.append('file_type', fileType);
+            const url = `${this.#options.config.apiBaseUrl}/im/v1/files`;
+            const response = await this.#fetch(url, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${this.#accessToken.token}` },
+                body: form,
+            });
+            const data = await response.json();
+            if (data.code === 0) {
+                return data.data?.file_key || null;
+            }
+            throw new Error(`Upload failed: ${data.msg}`);
+        }
+        catch (error) {
+            logger.error('Failed to upload file:', error);
+            return null;
+        }
+    }
+    async createChat(name, userIds, ownerId) {
+        try {
+            const data = await this.#request('/im/v1/chats', {
+                method: 'POST',
+                body: {
+                    name,
+                    user_id_list: userIds,
+                    ...(ownerId ? { owner_id: ownerId } : {}),
+                },
+            });
+            if (data.code === 0)
+                return data.data?.chat_id || null;
+            throw new Error(`Failed to create chat: ${data.msg}`);
+        }
+        catch (error) {
+            logger.error('Failed to create chat:', error);
+            return null;
+        }
+    }
+    async updateChatInfo(chatId, options) {
+        try {
+            const data = await this.#request(`/im/v1/chats/${chatId}`, {
+                method: 'PUT',
+                body: options,
+            });
+            if (data.code === 0)
+                return true;
+            throw new Error(`Failed to update chat: ${data.msg}`);
+        }
+        catch (error) {
+            logger.error('Failed to update chat:', error);
+            return false;
+        }
+    }
+    async addChatMembers(chatId, userIds) {
+        try {
+            const data = await this.#request(`/im/v1/chats/${chatId}/members`, {
+                method: 'POST',
+                body: { id_list: userIds },
+            });
+            if (data.code === 0)
+                return true;
+            throw new Error(`Failed to add members: ${data.msg}`);
+        }
+        catch (error) {
+            logger.error('Failed to add chat members:', error);
+            return false;
+        }
+    }
+    async removeChatMembers(chatId, userIds) {
+        try {
+            const data = await this.#request(`/im/v1/chats/${chatId}/members`, {
+                method: 'DELETE',
+                body: { id_list: userIds },
+            });
+            if (data.code === 0)
+                return true;
+            throw new Error(`Failed to remove members: ${data.msg}`);
+        }
+        catch (error) {
+            logger.error('Failed to remove chat members:', error);
+            return false;
+        }
+    }
+    async getChatMembers(chatId) {
+        try {
+            const data = await this.#request(`/im/v1/chats/${chatId}/members`, { method: 'GET' });
+            if (data.code === 0)
+                return data.data?.items || [];
+            throw new Error(`Failed to get members: ${data.msg}`);
+        }
+        catch (error) {
+            logger.error('Failed to get chat members:', error);
+            return [];
+        }
+    }
+    async dissolveChat(chatId) {
+        try {
+            const data = await this.#request(`/im/v1/chats/${chatId}`, { method: 'DELETE' });
+            if (data.code === 0)
+                return true;
+            throw new Error(`Failed to dissolve chat: ${data.msg}`);
+        }
+        catch (error) {
+            logger.error('Failed to dissolve chat:', error);
+            return false;
+        }
+    }
+    async setChatManagers(chatId, userIds) {
+        try {
+            const data = await this.#request(`/im/v1/chats/${chatId}/managers/add_managers`, {
+                method: 'POST',
+                body: { manager_ids: userIds },
+            });
+            if (data.code === 0)
+                return true;
+            throw new Error(`Failed to set managers: ${data.msg}`);
+        }
+        catch (error) {
+            logger.error('Failed to set chat managers:', error);
+            return false;
+        }
+    }
+    async removeChatManagers(chatId, userIds) {
+        try {
+            const data = await this.#request(`/im/v1/chats/${chatId}/managers/delete_managers`, {
+                method: 'POST',
+                body: { manager_ids: userIds },
+            });
+            if (data.code === 0)
+                return true;
+            throw new Error(`Failed to remove managers: ${data.msg}`);
+        }
+        catch (error) {
+            logger.error('Failed to remove chat managers:', error);
+            return false;
+        }
+    }
+    async #request(path, options = {}) {
+        await this.#ensureAccessToken();
+        const { method = 'GET', params = {}, body } = options;
+        const urlParams = new URLSearchParams(Object.fromEntries(Object.entries(params).map(([key, value]) => [key, String(value)])));
+        const query = urlParams.toString();
+        const url = `${this.#options.config.apiBaseUrl}${path}${query ? `?${query}` : ''}`;
+        const response = await this.#fetch(url, {
+            method,
+            headers: {
+                'Content-Type': 'application/json; charset=utf-8',
+                Authorization: `Bearer ${this.#accessToken.token}`,
+            },
+            body: body && method !== 'GET' ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`Lark API error ${response.status}: ${text}`);
+        }
+        return await response.json();
+    }
+    async #ensureAccessToken() {
+        const now = Date.now();
+        if (this.#accessToken.token
+            && now < this.#accessToken.timestamp + (this.#accessToken.expires_in - 300) * 1000) {
+            return;
+        }
+        if (this.#refreshPromise) {
+            await this.#refreshPromise;
+            return;
+        }
+        this.#refreshPromise = this.#refreshAccessToken()
+            .then(() => this.#accessToken.token)
+            .finally(() => { this.#refreshPromise = null; });
+        await this.#refreshPromise;
+    }
+    async #refreshAccessToken() {
+        const { appId, appSecret, apiBaseUrl } = this.#options.config;
+        const url = `${apiBaseUrl}/auth/v3/tenant_access_token/internal`;
+        const response = await this.#fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json; charset=utf-8' },
+            body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+        });
+        const data = await response.json();
+        if (data.code === 0 && data.tenant_access_token) {
+            this.#accessToken = {
+                token: data.tenant_access_token,
+                expires_in: data.expire ?? 7200,
+                timestamp: Date.now(),
+            };
+            logger.debug('Access token refreshed successfully');
+            return;
+        }
+        throw new Error(`Failed to get access token: ${data.msg} (${data.code})`);
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,15 @@
+/**
+ * 飞书 Lark platform permit
+ */
+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: {
+    isOwner?: boolean;
+    isAdmin?: boolean;
+}): {
+    role?: string;
+    permissions?: string[];
+};
+export declare function checkLarkPlatformPermit(perm: string, message: Message<any>): boolean;
+export declare function registerLarkPlatformPermitChecker(): () => void;

package/lib/{src/platform-permit.js → platform-permit.js}

@@ -1,7 +1,7 @@
 /**
  * 飞书 Lark platform permit
  */
-import { registerPlatformPermitChecker } from 'zhin.js';
+import { registerPlatformPermitChecker } from '@zhin.js/core';
 const ADAPTER = 'lark';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -41,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>;