@zhin.js/adapter-lark 1.1.17 → 1.1.19

package/lib/index.d.ts

@@ -1,7 +1,9 @@
 export { formatInboundContent, formatOutboundBody, generateMessageId, headerValue, larkInboundConversation, normalizeWebhookPath, readTextBody, resolveChatType, resolveLarkConfig, resolveSender, verifySignature, type AccessToken, type LarkEndpointConfig, type LarkApiResponse, type LarkEventBody, type LarkMessage, type LarkSendBody, type LarkWireSegment, type ResolvedLarkConfig, } from './protocol.js';
-export { larkClient, type LarkClientEventMap } from './client.js';
+export { 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 { LarkEndpoint, 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';
 export { createLarkLongConnection, type LarkLongConnection, type LarkLongConnectionFactory, type LarkLongConnectionOptions, } from './long-connection.js';
+export { LarkClient, type LarkClientApi } from './client.js';
+export { LarkAdapter } from './adapter.js';

package/lib/index.js

@@ -1,7 +1,8 @@
 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 { LarkEndpoint, } from './endpoint.js';
 export { buildImageUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
 export { registerLarkWebhookRoutes, handleLarkWebhookRequest, } from './webhook.js';
 export { createLarkLongConnection, } from './long-connection.js';
+export { LarkClient } from './client.js';
+export { LarkAdapter } from './adapter.js';

package/lib/long-connection.d.ts

@@ -7,7 +7,7 @@ export interface LarkLongConnection {
 }
 export interface LarkLongConnectionOptions {
     readonly config: ResolvedLarkConfig;
-    readonly receive: (message: LarkMessage) => void;
+    readonly receive: (message: LarkMessage, nativeEvent?: unknown) => void;
     readonly cardAction?: (event: LarkCardAction) => void;
     readonly disconnected: () => void;
 }

package/lib/long-connection.js

@@ -42,7 +42,7 @@ export const createLarkLongConnection = ({ config, receive, cardAction, disconne
             cardAction?.(event); return {}; },
         'im.message.receive_v1': (event) => {
             if (!cancelled)
-                receive({ ...event.message, sender: event.sender });
+                receive({ ...event.message, sender: event.sender }, event);
             // No downstream send is awaited: SDK ACK remains within its 3-second window.
         },
     });

package/lib/media-upload.d.ts

@@ -5,7 +5,11 @@ export interface MediaBinary {
     readonly fileName: string;
 }
 /** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
-export declare function resolveMediaBinary(media: MediaRef, download?: (url: string) => Promise<Buffer>): Promise<MediaBinary>;
+export interface MediaResolveOptions {
+    readonly download?: (url: string, signal?: AbortSignal) => Promise<Buffer>;
+    readonly signal?: AbortSignal;
+}
+export declare function resolveMediaBinary(media: MediaRef, { download, signal }?: MediaResolveOptions): Promise<MediaBinary>;
 /** /im/v1/images 的 multipart body（image_type=message 用于消息内图片）。 */
 export declare function buildImageUploadForm(binary: MediaBinary): FormData;
 /**

package/lib/media-upload.js

@@ -13,8 +13,8 @@ const MIME_EXT = {
     'image/webp': 'webp',
     'image/bmp': 'bmp',
 };
-/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
-export async function resolveMediaBinary(media, download = defaultDownload) {
+export async function resolveMediaBinary(media, { download = defaultDownload, signal } = {}) {
+    signal?.throwIfAborted();
     const mimeType = media.mime_type ?? 'image/png';
     const ext = MIME_EXT[mimeType] ?? 'png';
     if (media.kind === 'base64') {
@@ -25,12 +25,12 @@ export async function resolveMediaBinary(media, download = defaultDownload) {
     }
     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 readFile(path, { signal }), mimeType, fileName: basename(path) };
     }
-    return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+    return { data: await download(media.value, signal), mimeType, fileName: `image.${ext}` };
 }
-async function defaultDownload(url) {
-    const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+async function defaultDownload(url, signal) {
+    const response = await fetch(url, { signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000) });
     if (!response.ok)
         throw new Error(`download failed: HTTP ${response.status}`);
     return Buffer.from(await response.arrayBuffer());

package/lib/protocol.d.ts

@@ -103,7 +103,7 @@ export declare function resolveChatType(chatId?: string, chatType?: string): 'gr
  * 不产生 `parent`。
  */
 export declare function larkInboundConversation(endpointKey: string, msg: LarkMessage): ConversationRef;
-export declare function resolveSender(msg: LarkMessage): string;
+export declare function resolveSender(msg: LarkMessage): string | undefined;
 export declare function generateMessageId(msg: LarkMessage): string;
 /** Build inbound text for OutboundMessageService.receive. */
 export declare function formatInboundContent(msg: LarkMessage): string;

package/lib/protocol.js

@@ -78,7 +78,7 @@ export function larkInboundConversation(endpointKey, msg) {
 export function resolveSender(msg) {
     return msg.sender?.sender_id?.open_id
         || msg.sender?.sender_id?.user_id
-        || 'unknown';
+        || undefined;
 }
 export function generateMessageId(msg) {
     return msg.message_id || `${msg.create_time ?? Date.now()}`;

package/lib/sdk-http.d.ts

@@ -0,0 +1,4 @@
+import type { HttpInstance } from '@larksuiteoapi/node-sdk';
+import type { LarkFetch } from './client.js';
+/** The installed SDK's documented HttpInstance seam, using the same account-owned transport. */
+export declare function createLarkSdkHttpInstance(fetch: LarkFetch): HttpInstance;

package/lib/sdk-http.js

@@ -0,0 +1,88 @@
+import { Readable, PassThrough } from 'node:stream';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/** The installed SDK's documented HttpInstance seam, using the same account-owned transport. */
+export function createLarkSdkHttpInstance(fetch) {
+    const request = async (input) => {
+        if (!input.url)
+            throw new TypeError('Lark SDK request URL is required');
+        const url = new URL(input.url);
+        if (input.params) {
+            const serializer = typeof input.paramsSerializer === 'function' ? input.paramsSerializer
+                : input.paramsSerializer?.serialize;
+            if (serializer) {
+                const query = serializer(input.params);
+                if (query)
+                    url.search = url.search ? `${url.search}&${query}` : query;
+            }
+            else
+                for (const [key, value] of Object.entries(input.params)) {
+                    if (value === undefined || value === null)
+                        continue;
+                    for (const item of Array.isArray(value) ? value : [value])
+                        url.searchParams.append(key, String(item));
+                }
+        }
+        const headers = Object.fromEntries(Object.entries(input.headers ?? {}).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+        let body;
+        let streaming = false;
+        if (input.data !== undefined) {
+            const native = input.data;
+            if (typeof input.data === 'string' || input.data instanceof FormData || input.data instanceof ArrayBuffer || ArrayBuffer.isView(input.data))
+                body = input.data;
+            else if (native && (typeof native.pipe === 'function' || typeof native[Symbol.asyncIterator] === 'function')) {
+                if (native.getHeaders)
+                    Object.assign(headers, native.getHeaders());
+                if (typeof native.pipe === 'function') {
+                    const stream = new PassThrough();
+                    stream.once('close', () => native.destroy?.());
+                    native.pipe(stream);
+                    body = stream;
+                }
+                else
+                    body = input.data;
+                streaming = true;
+            }
+            else {
+                body = JSON.stringify(input.data);
+                if (!Object.keys(headers).some(key => key.toLowerCase() === 'content-type'))
+                    headers['Content-Type'] = 'application/json';
+            }
+        }
+        const response = await fetch(url.toString(), { method: input.method, headers, body, ...(streaming ? { duplex: 'half' } : {}),
+            ...(input.timeout ? { signal: AbortSignal.timeout(input.timeout) } : {}) });
+        if (!response.ok)
+            throw new EndpointDeliveryError('http_error', `Lark HTTP ${response.status}`, response.status >= 400 && response.status < 500 && response.status !== 408 ? 'rejected' : 'unknown');
+        const native = response;
+        let data;
+        if (input.responseType === 'stream') {
+            if (!native.body)
+                throw new Error('Lark transport returned no response stream');
+            data = Readable.fromWeb(native.body);
+        }
+        else if (input.responseType === 'arraybuffer') {
+            if (!native.arrayBuffer)
+                throw new Error('Lark transport returned no binary reader');
+            data = Buffer.from(await native.arrayBuffer());
+        }
+        else if (input.responseType === 'blob') {
+            if (!native.blob)
+                throw new Error('Lark transport returned no blob reader');
+            data = await native.blob();
+        }
+        else if (input.responseType === 'text' || input.responseType === 'document')
+            data = await response.text();
+        else
+            data = await response.json();
+        return (input.$return_headers ? { data, headers: Object.fromEntries(native.headers?.entries() ?? []) } : data);
+    };
+    return {
+        request,
+        get: (url, options) => request({ ...options, url, method: 'GET' }),
+        delete: (url, options) => request({ ...options, url, method: 'DELETE' }),
+        head: (url, options) => request({ ...options, url, method: 'HEAD' }),
+        options: (url, options) => request({ ...options, url, method: 'OPTIONS' }),
+        post: (url, data, options) => request({ ...options, url, data, method: 'POST' }),
+        put: (url, data, options) => request({ ...options, url, data, method: 'PUT' }),
+        patch: (url, data, options) => request({ ...options, url, data, method: 'PATCH' }),
+    };
+}

package/lib/webhook.d.ts

@@ -9,7 +9,7 @@ export interface LarkWebhookHandler {
     readonly config: ResolvedLarkConfig;
     readonly isOpen: boolean;
     admitPlatform(name: string, event: unknown): void;
-    admit(msg: LarkMessage): void;
+    admit(msg: LarkMessage, nativeEvent?: unknown): void;
     admitCardAction?(event: LarkCardAction): void;
 }
 export declare function registerLarkWebhookRoutes(http: HttpHost, handler: LarkWebhookHandler): HttpRouteRegistration[];

package/lib/webhook.js

@@ -63,7 +63,7 @@ export async function handleLarkWebhookRequest(request, response, handler) {
                 ...event.event.message,
                 sender: event.event.message.sender ?? event.event.sender,
             };
-            handler.admit(message);
+            handler.admit(message, event);
         }
         response.writeHead(200, { 'Content-Type': 'application/json' });
         response.end(JSON.stringify({ code: 0, msg: 'success' }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-lark",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "description": "Zhin.js Lark/Feishu adapter (HTTP webhook and WebSocket long connection)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,26 +33,29 @@
     "directory": "plugins/adapters/lark"
   },
   "dependencies": {
-    "undici": "6.29.1",
     "@larksuiteoapi/node-sdk": "^1.67.0",
-    "@zhin.js/adapter": "1.1.24",
-    "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/core": "1.1.52",
-    "@zhin.js/feature-kit": "1.1.9",
-    "@zhin.js/host-http": "1.1.11",
-    "@zhin.js/im-contract": "1.1.8",
+    "undici": "6.29.1",
+    "@zhin.js/adapter": "1.1.26",
+    "@zhin.js/agent-feature": "1.1.11",
+    "@zhin.js/client": "1.1.22",
+    "@zhin.js/console-contract": "1.1.3",
+    "@zhin.js/core": "1.1.54",
+    "@zhin.js/feature-kit": "1.1.10",
+    "@zhin.js/host-http": "1.1.12",
+    "@zhin.js/im-contract": "1.1.9",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.11"
+    "@zhin.js/page": "1.1.11",
+    "@zhin.js/skill": "1.1.11",
+    "@zhin.js/tool": "1.1.13"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.24",
-    "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.52",
-    "@zhin.js/permission": "^1.1.9",
-    "@zhin.js/host-http": "^1.1.11",
-    "zhin.js": "^1.1.17"
+    "@zhin.js/adapter": "^1.1.26",
+    "@zhin.js/command": "^1.1.12",
+    "@zhin.js/core": "^1.1.54",
+    "@zhin.js/host-http": "^1.1.12",
+    "@zhin.js/permission": "^1.1.10",
+    "zhin.js": "^1.1.19"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -70,11 +73,12 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "zhin.js": "1.1.17"
+    "zhin.js": "1.1.19"
   },
   "files": [
     "adapters",
     "commands",
+    "pages",
     "plugin.js",
     "schema.json",
     "src",
@@ -101,7 +105,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^1.0.0"
+        "api": "^2.0.0"
       },
       {
         "package": "@zhin.js/command",
@@ -118,6 +122,10 @@
       {
         "package": "@zhin.js/agent-feature",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/page",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/pages/index/index.js

@@ -0,0 +1,15 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+export const meta = definePage({
+    title: 'Lark',
+    titleI18n: { en: 'Lark' },
+    icon: 'Bird',
+    order: 66,
+    requiredPermissions: ['lark:read'],
+});
+/**
+ * Convention page: `pages/index/index.ts` → `/lark`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('lark');

package/pages/index/index.ts

@@ -0,0 +1,16 @@
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+
+export const meta = definePage({
+  title: 'Lark',
+  titleI18n: { en: 'Lark' },
+  icon: 'Bird',
+  order: 66,
+  requiredPermissions: ['lark:read'],
+});
+
+/**
+ * Convention page: `pages/index/index.ts` → `/lark`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('lark');

package/plugin.js

@@ -1,16 +1,15 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { createEndpointRuntimeState } from 'zhin.js/adapter';
-import { definePlugin } from 'zhin.js';
+import { definePlugin, pluginConsoleRpcToken } from 'zhin.js';
 import { permissionHostToken } from '@zhin.js/permission';
 import { checkLarkPlatformPermit } from "./lib/platform-permit.js";
-import { larkRuntimeStateToken } from "./lib/lark-runtime-state.js";
+import { createLarkConsoleRpc } from "./lib/console.js";
 export default definePlugin({
     name: 'lark',
     metadata: {
         displayName: 'Lark/Feishu (飞书) Adapter',
     },
     setup(context) {
-        context.resources.provide(larkRuntimeStateToken, createEndpointRuntimeState());
+        context.resources.provide(pluginConsoleRpcToken, createLarkConsoleRpc(context.resources, () => context.config.get()));
         if (context.resources.has(permissionHostToken)) {
             const host = context.resources.use(permissionHostToken);
             return host.registerPlatform('lark', checkLarkPlatformPermit);

package/src/adapter.ts

@@ -0,0 +1,30 @@
+import { LarkClient, type LarkClientEventMap } from './client.js';
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { LarkEndpoint } from './endpoint.js';
+import { resolveLarkConfig, type LarkEndpointConfig } from './protocol.js';
+import { httpHostToken } from '@zhin.js/host-http';
+
+export class LarkAdapter extends Adapter<LarkEndpoint, LarkEndpointConfig, LarkClientEventMap> {
+  readonly #context: AdapterContext<LarkEndpointConfig>;
+  constructor(context: AdapterContext<LarkEndpointConfig>) { super(); this.#context = context; }
+  override get configurationIdentityFields(): readonly string[] { return ['id', 'appId', 'isFeishu']; }
+  override get configurationUpdateFields(): readonly string[] { return ['appSecret', 'encryptKey', 'verificationToken', 'mode', 'webhookPath', 'apiBaseUrl', 'webApiProxy', 'streamProxy']; }
+  override get configurationIdentityProbeFields(): readonly string[] { return ['appSecret', 'apiBaseUrl']; }
+  protected override async identifyConfiguration(input: LarkEndpointConfig, signal: AbortSignal, _changed: readonly string[]): Promise<string | undefined> {
+    const config = resolveLarkConfig(input), client = new LarkClient({ id: this.descriptor.id, config, signal });
+    try {
+      const response = await client.request<{ code?: number; bot?: { open_id?: unknown } }>({ url: `${config.apiBaseUrl}/bot/v3/info`, method: 'GET' });
+      if (response.code !== 0 || typeof response.bot?.open_id !== 'string' || !response.bot.open_id) throw new Error('Lark identity verification returned no bot open_id');
+      return JSON.stringify(['lark', new URL(config.apiBaseUrl).origin, response.bot.open_id]);
+    } finally { await client[Symbol.asyncDispose](); }
+  }
+  protected override validateConfiguration(config: LarkEndpointConfig): void { resolveLarkConfig(config); }
+  protected createEndpoint(input: LarkEndpointConfig, execution: EndpointCreationContext): LarkEndpoint {
+    const config = resolveLarkConfig(input);
+    return new LarkEndpoint({ id: execution.canonicalId, config, ...(config.mode === 'websocket' ? {} : { http: this.#context.use(httpHostToken) }) });
+  }
+}
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterRegistry { readonly 'lark': LarkAdapter; }
+}