@zhin.js/adapter-kook 1.1.17 → 1.1.19

package/lib/protocol.js

@@ -297,6 +297,8 @@ export function normalizeKookWebhookEvent(event, options = {}) {
         return null;
     return {
         id: String(event.msg_id),
+        event,
+        ...(typeof event.msg_timestamp === 'number' ? { platformSentAt: event.msg_timestamp } : {}),
         content: event.content ?? '',
         channelKind,
         channelId,
@@ -328,5 +330,5 @@ export function normalizeKookButtonEvent(raw) {
     if (!channelId)
         return null;
     const timestamp = event.msg_timestamp ?? Date.now();
-    return { id: String(event.msg_id || `button:${body.msg_id}:${timestamp}`), sourceMessageId: String(body.msg_id), payload: body.value, userId: String(body.user_id), channelKind, channelId, timestamp };
+    return { event: raw, ...(typeof event.msg_timestamp === 'number' ? { platformSentAt: event.msg_timestamp } : {}), id: String(event.msg_id || `button:${body.msg_id}:${timestamp}`), sourceMessageId: String(body.msg_id), payload: body.value, userId: String(body.user_id), channelKind, channelId, timestamp };
 }

package/lib/webhook.d.ts

@@ -1,11 +1,12 @@
+import { type Endpoint } from 'zhin.js/adapter';
 /**
  * KOOK webhook HTTP: verify → parse → admit.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { type KookInboundMessage, type KookWebhookEventData, type ResolvedKookWebhookConfig } from './protocol.js';
-export interface KookWebhookHandler {
-    readonly config: ResolvedKookWebhookConfig;
+export interface KookWebhookHandler extends Endpoint {
+    readonly endpointConfig: ResolvedKookWebhookConfig;
     readonly isOpen: boolean;
     readonly selfId?: string;
     admit(msg: KookInboundMessage): void;

package/lib/webhook.js

@@ -1,8 +1,9 @@
+import { endpointSpec } from 'zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { isKookWebhookChallenge, parseKookWebhookBody, readRequestBody, verifyKookWebhookToken, } from './protocol.js';
 const logger = getLogger('kook');
 export function registerKookWebhookRoutes(http, handler) {
-    const path = handler.config.webhookPath;
+    const path = handler.endpointConfig.webhookPath;
     return [
         http.route('POST', path, async (request, response) => {
             await handleKookWebhookRequest(request, response, handler);
@@ -14,7 +15,7 @@ export async function handleKookWebhookRequest(request, response, handler) {
         const rawBody = await readRequestBody(request);
         let frame;
         try {
-            frame = parseKookWebhookBody(rawBody, handler.config.encryptKey);
+            frame = parseKookWebhookBody(rawBody, handler.endpointConfig.encryptKey);
         }
         catch (error) {
             logger.warn(formatCompact({
@@ -33,7 +34,7 @@ export async function handleKookWebhookRequest(request, response, handler) {
             return;
         }
         if (isKookWebhookChallenge(event)) {
-            if (!verifyKookWebhookToken(handler.config.verifyToken, event.verify_token)) {
+            if (!verifyKookWebhookToken(handler.endpointConfig.verifyToken, event.verify_token)) {
                 response.writeHead(403, { 'Content-Type': 'application/json' });
                 response.end(JSON.stringify({ message: 'Invalid verify_token' }));
                 return;
@@ -42,7 +43,7 @@ export async function handleKookWebhookRequest(request, response, handler) {
             response.end(JSON.stringify({ challenge: event.challenge ?? '' }));
             return;
         }
-        if (!verifyKookWebhookToken(handler.config.verifyToken, event.verify_token)) {
+        if (!verifyKookWebhookToken(handler.endpointConfig.verifyToken, event.verify_token)) {
             response.writeHead(403, { 'Content-Type': 'application/json' });
             response.end(JSON.stringify({ message: 'Invalid verify_token' }));
             return;
@@ -52,25 +53,27 @@ export async function handleKookWebhookRequest(request, response, handler) {
             response.end(JSON.stringify({ message: 'Endpoint unavailable' }));
             return;
         }
-        if (frame.sn != null) {
-            if (!handler.checkAndRememberSn(frame.sn)) {
-                response.writeHead(200, { 'Content-Type': 'application/json' });
-                response.end(JSON.stringify({ message: 'OK' }));
+        await handler[endpointSpec].events.run(async () => {
+            if (frame.sn != null) {
+                if (!handler.checkAndRememberSn(frame.sn)) {
+                    response.writeHead(200, { 'Content-Type': 'application/json' });
+                    response.end(JSON.stringify({ message: 'OK' }));
+                    return;
+                }
+            }
+            try {
+                await handler.admitEvent(event);
+            }
+            catch {
+                if (frame.sn != null)
+                    handler.forgetSn?.(frame.sn);
+                response.writeHead(503, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ message: 'Admission unavailable' }));
                 return;
             }
-        }
-        try {
-            await handler.admitEvent(event);
-        }
-        catch {
-            if (frame.sn != null)
-                handler.forgetSn?.(frame.sn);
-            response.writeHead(503, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ message: 'Admission unavailable' }));
-            return;
-        }
-        response.writeHead(200, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ message: 'OK' }));
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ message: 'OK' }));
+        });
     }
     catch (error) {
         logger.error('KOOK webhook error:', error);

package/lib/ws.d.ts

@@ -1,70 +1,8 @@
 import { type KookApiProxy } from './api-proxy.js';
 import { Client } from 'kook-client';
 import { createEndpointLifecycle, type EndpointTransportState } from 'zhin.js/adapter';
-import { type KookInboundMessage, type ResolvedKookConfig, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig } from './protocol.js';
-/** Minimal client surface used by the endpoint (real kook-client or test mock). */
-export interface KookClientTransport {
-    getTransportState?(): EndpointTransportState | undefined;
-    connect(): Promise<void>;
-    disconnect(): Promise<void>;
-    on(event: string, listener: (...args: unknown[]) => void): void;
-    removeAllListeners(): void;
-    sendChannelMsg(channelId: string, message: unknown, quote?: {
-        message_id: string;
-    }): Promise<{
-        msg_id?: string | number;
-    }>;
-    sendPrivateMsg(userId: string, message: unknown, quote?: {
-        message_id: string;
-    }): Promise<{
-        msg_id?: string | number;
-    }>;
-    uploadMedia?(data: Buffer): Promise<string>;
-    recallChannelMsg?(channelId: string, messageId: string): Promise<boolean>;
-    recallPrivateMsg?(userId: string, messageId: string): Promise<boolean>;
-    /** GET /api/v3/guild/view（群主 id）。 */
-    getGuildInfo?(guildId: string): Promise<{
-        user_id?: string | number;
-    }>;
-    pickGuild(guildId: string): {
-        kick(userId: string): Promise<boolean>;
-        getRoleList(): Promise<Array<{
-            role_id: string | number;
-            name: string;
-            color?: number;
-            position?: number;
-            permissions?: unknown;
-        }>>;
-        createRole(name: string): Promise<{
-            role_id: string | number;
-            name: string;
-        }>;
-        deleteRole(roleId: string): Promise<boolean>;
-    };
-    pickGuildMember(guildId: string, userId: string): {
-        addToBlackList(remark?: string, delMsgDays?: number): Promise<boolean>;
-        removeFromBlackList(): Promise<boolean>;
-        grant(roleId: string): Promise<boolean>;
-        revoke(roleId: string): Promise<boolean>;
-        setNickname(nickname: string): Promise<boolean>;
-    };
-    /** GET /api/v3/guild/list（kook-client 内部分页聚合）。 */
-    getGuildList(): Promise<Array<{
-        id: string | number;
-        name?: string;
-    }>>;
-    /** GET /api/v3/channel/list（type: 1=文字 2=语音；is_category 为分组）。 */
-    getChannelList(guildId: string): Promise<Array<{
-        id: string | number;
-        name?: string;
-        type?: string | number;
-        is_category?: boolean;
-    }>>;
-    /** GET /api/v3/guild/user-list。 */
-    getGuildUserList(guildId: string, channelId?: string): Promise<unknown[]>;
-    self_id?: string | number;
-}
-export type CreateKookClient = (config: ResolvedKookConfig) => KookClientTransport;
+import { type KookInboundMessage, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig } from './protocol.js';
+export type KookClientTransport = RuntimeKookClient;
 export declare function normalizeKookMessage(raw: unknown): KookInboundMessage | null;
 export declare class RuntimeKookClient extends Client {
     #private;
@@ -77,5 +15,5 @@ export declare class RuntimeKookClient extends Client {
     init(): Promise<void>;
     getBlacklist(guildId: string): Promise<import("kook-client").Guild.BlackInfo[]>;
 }
-export declare function defaultCreateClient(config: ResolvedKookWebsocketConfig): KookClientTransport;
-export declare function defaultCreateWebhookClient(config: ResolvedKookWebhookConfig): KookClientTransport;
+export declare function kookWebsocketClientOptions(config: ResolvedKookWebsocketConfig): ConstructorParameters<typeof Client>[0];
+export declare function kookWebhookClientOptions(config: ResolvedKookWebhookConfig): ConstructorParameters<typeof Client>[0];

package/lib/ws.js

@@ -42,6 +42,8 @@ export function normalizeKookMessage(raw) {
     catch { /* optional cache enrichment unavailable */ }
     return {
         id: String(msg.message_id),
+        event: raw,
+        ...(typeof msg.timestamp === 'number' ? { platformSentAt: msg.timestamp } : {}),
         content,
         channelKind,
         channelId,
@@ -57,6 +59,7 @@ export function normalizeKookMessage(raw) {
     };
 }
 export class RuntimeKookClient extends Client {
+    #apiAgent;
     #lifecycle;
     #initialized = false;
     #connectionAttempt = 0;
@@ -64,7 +67,8 @@ export class RuntimeKookClient extends Client {
         super({ ...config, autoReconnect: false, handleProcessErrors: false });
         this.#lifecycle = createEndpointLifecycle(lifecycleOptions);
         if (apiProxy) {
-            this.request.defaults.httpsAgent = createKookApiAgent(apiProxy);
+            this.#apiAgent = createKookApiAgent(apiProxy);
+            this.request.defaults.httpsAgent = this.#apiAgent;
             this.request.defaults.proxy = false;
             this.request.defaults.maxRedirects = 0;
             this.request.interceptors.request.use(request => {
@@ -125,7 +129,12 @@ export class RuntimeKookClient extends Client {
             }
         });
     }
-    async disconnect() { await this.#lifecycle.stop(); }
+    async disconnect() { try {
+        await this.#lifecycle.stop();
+    }
+    finally {
+        this.#apiAgent?.destroy();
+    } }
     /** Native FormData avoids kook-client's Buffer-to-text multipart conversion. */
     async uploadMedia(data) {
         let bytes;
@@ -190,8 +199,8 @@ export class RuntimeKookClient extends Client {
         }
     }
 }
-export function defaultCreateClient(config) {
-    return new RuntimeKookClient({
+export function kookWebsocketClientOptions(config) {
+    return {
         token: config.token,
         mode: 'websocket',
         socketFactory: (url) => createKookStreamSocket(url, config.streamProxy),
@@ -200,10 +209,10 @@ export function defaultCreateClient(config) {
         max_retry: config.max_retry,
         ignore: config.ignore,
         logLevel: config.logLevel,
-    }, undefined, config.apiProxy);
+    };
 }
-export function defaultCreateWebhookClient(config) {
-    return new RuntimeKookClient({
+export function kookWebhookClientOptions(config) {
+    return {
         token: config.token,
         mode: 'webhook',
         data_dir: path.join(process.cwd(), 'data', 'kook'),
@@ -211,5 +220,5 @@ export function defaultCreateWebhookClient(config) {
         max_retry: 3,
         ignore: config.ignore,
         logLevel: config.logLevel,
-    }, undefined, config.apiProxy);
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-kook",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "description": "Zhin.js KOOK adapter for Plugin Runtime (WebSocket gateway or Webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,23 +33,26 @@
   },
   "dependencies": {
     "kook-client": "^1.0.5",
-    "@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",
+    "@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/permission": "1.1.9",
-    "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.11"
+    "@zhin.js/page": "1.1.11",
+    "@zhin.js/permission": "1.1.10",
+    "@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": "^1.1.17"
+    "@zhin.js/adapter": "^1.1.26",
+    "@zhin.js/command": "^1.1.12",
+    "@zhin.js/core": "^1.1.54",
+    "zhin.js": "^1.1.19"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -67,12 +70,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.11",
-    "zhin.js": "1.1.17"
+    "@zhin.js/host-http": "1.1.12",
+    "zhin.js": "1.1.19"
   },
   "files": [
     "adapters",
     "commands",
+    "pages",
     "plugin.js",
     "schema.json",
     "src",
@@ -99,7 +103,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^1.0.0"
+        "api": "^2.0.0"
       },
       {
         "package": "@zhin.js/command",
@@ -116,6 +120,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: 'KOOK',
+    titleI18n: { en: 'KOOK' },
+    icon: 'Gamepad2',
+    order: 65,
+    requiredPermissions: ['kook:read'],
+});
+/**
+ * Convention page: `pages/index/index.ts` → `/kook`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('kook');

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: 'KOOK',
+  titleI18n: { en: 'KOOK' },
+  icon: 'Gamepad2',
+  order: 65,
+  requiredPermissions: ['kook:read'],
+});
+
+/**
+ * Convention page: `pages/index/index.ts` → `/kook`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('kook');

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 { checkKookPlatformPermit } from "./lib/platform-permit.js";
-import { kookRuntimeStateToken } from "./lib/kook-runtime-state.js";
+import { createKookConsoleRpc } from "./lib/console.js";
 export default definePlugin({
     name: 'kook',
     metadata: {
         displayName: 'KOOK WebSocket Adapter',
     },
     setup(context) {
-        context.resources.provide(kookRuntimeStateToken, createEndpointRuntimeState());
+        context.resources.provide(pluginConsoleRpcToken, createKookConsoleRpc(() => context.config.get()));
         if (context.resources.has(permissionHostToken)) {
             const host = context.resources.use(permissionHostToken);
             return host.registerPlatform('kook', checkKookPlatformPermit);

package/src/adapter.ts

@@ -0,0 +1,35 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { KookWebhookEndpoint, KookWebsocketEndpoint } from './endpoint.js';
+import { RuntimeKookClient, kookWebhookClientOptions, kookWebsocketClientOptions } from './ws.js';
+import { resolveKookConfig, type KookEndpointConfig } from './protocol.js';
+import type { KookClientEventMap } from './client.js';
+
+export class KookAdapter extends Adapter<KookWebhookEndpoint | KookWebsocketEndpoint, KookEndpointConfig, KookClientEventMap> {
+  constructor(private readonly context: AdapterContext<KookEndpointConfig>) { super(); }
+  override get configurationIdentityFields(): readonly string[] { return ['id']; }
+  override get configurationIdentityProbeFields(): readonly string[] { return ['token', 'verify_token', 'encrypt_key']; }
+  override get configurationUpdateFields(): readonly string[] { return ['token', 'verify_token', 'encrypt_key', 'connection',
+    'webhookPath', 'data_dir', 'timeout', 'max_retry', 'ignore', 'logLevel', 'apiProxy', 'apiProxy.port',
+    'streamProxy', 'streamProxy.port', 'streamProxy.serverName']; }
+  protected override validateConfiguration(input: KookEndpointConfig): void { resolveKookConfig(input); }
+  protected override async identifyConfiguration(input: KookEndpointConfig, signal: AbortSignal, changedFields: readonly string[]): Promise<string | undefined> {
+    if (changedFields.some(field => field !== 'token')) return undefined;
+    const config = resolveKookConfig(input);
+    const options = config.connection === 'websocket' ? kookWebsocketClientOptions(config) : kookWebhookClientOptions(config);
+    // Webhook receiver construction has no gateway socket or login; only GET /v3/user/me is issued.
+    const client = new RuntimeKookClient({ ...options, mode: 'webhook' }, undefined, config.apiProxy);
+    client.request.interceptors.request.use(request => { request.signal = signal; return request; });
+    try {
+      const me = await client.getSelfInfo();
+      if (typeof me?.id !== 'string' || !me.id.trim()) throw new Error('KOOK identity response is incomplete');
+      return JSON.stringify(['kook', me.id]);
+    } finally { await client.disconnect(); }
+  }
+  protected createEndpoint(input: KookEndpointConfig, execution: EndpointCreationContext): KookWebhookEndpoint | KookWebsocketEndpoint {
+    const config = resolveKookConfig(input);
+    return config.connection === 'webhook'
+      ? new KookWebhookEndpoint({ id: execution.canonicalId, config, http: this.context.use(httpHostToken) })
+      : new KookWebsocketEndpoint({ id: execution.canonicalId, config });
+  }
+}

package/src/client.ts

@@ -1,15 +1,8 @@
-import { defineEndpointClient } from 'zhin.js/adapter';
-import type { KookClientTransport } from './ws.js';
+import type { EventMap } from 'kook-client';
+import type { KookAdapter } from './adapter.js';
 
-export type KookClientEventMap = Record<string, unknown>;
+export type KookClientEventMap = { readonly [K in keyof EventMap]: EventMap[K] extends (event: infer E, ...args: never[]) => unknown ? E : never };
 
 declare module '@zhin.js/feature-kit' {
-  interface AdapterClientRegistry {
-    readonly kook: {
-      readonly client: KookClientTransport;
-      readonly events: KookClientEventMap;
-    };
-  }
+  interface AdapterRegistry { readonly kook: KookAdapter; }
 }
-
-export const kookClient = defineEndpointClient<KookClientTransport, KookClientEventMap>('kook');

package/src/console-spec.ts

@@ -0,0 +1,27 @@
+/**
+ * KOOK Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+
+export const kookConsoleSpec = {
+  adapterKey: 'kook',
+  adapterDisplayName: 'KOOK',
+  fields: [
+    { key: 'token', required: true, env: true, description: 'KOOK bot token' },
+    { key: 'encrypt_key', env: true, description: 'webhook 加密密钥（connection: webhook）', descriptionI18n: { en: 'Webhook encryption secret' } },
+    { key: 'verify_token', env: true, description: 'webhook 验证 token（connection: webhook）', descriptionI18n: { en: 'Webhook verification token' } },
+    { key: 'connection', description: 'websocket or webhook' },
+    { key: 'webhookPath', description: 'Local webhook route' },
+    { key: 'data_dir', description: 'SDK data directory' },
+    { key: 'timeout', type: 'number', description: 'SDK request timeout' },
+    { key: 'max_retry', type: 'number', description: 'SDK configured retry count' },
+    { key: 'ignore', description: 'SDK inbound ignore setting: bot or self' },
+    { key: 'logLevel', description: 'SDK log level' },
+    { key: 'apiProxy.port', type: 'number', description: 'Configured API loopback proxy port' },
+    { key: 'streamProxy.port', type: 'number', description: 'Configured Gateway loopback proxy port' },
+    { key: 'streamProxy.serverName', description: 'Expected Gateway TLS hostname' },
+  ] as readonly AdapterConsoleField[],
+  docsUrl: 'https://zhin.js.org/adapters/kook',
+  readPermission: 'kook:read',
+  writePermission: 'kook:write',
+} as const;

package/src/console.ts

@@ -0,0 +1,17 @@
+/**
+ * KOOK Console RPC：运行状态 + endpoint 增删（原 `kook endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { createAdapterConsoleRpc } from 'zhin.js/adapter';
+import type { PluginConsoleRpc } from 'zhin.js';
+import { kookConsoleSpec } from './console-spec.js';
+
+export function createKookConsoleRpc(
+  getConfig: () => unknown,
+): PluginConsoleRpc {
+  return createAdapterConsoleRpc({
+    ...kookConsoleSpec,
+    getConfig,
+  });
+}