@zhin.js/adapter-kook 1.1.17 → 1.1.19

package/src/outbound.ts

@@ -1,12 +1,14 @@
 import { readFile } from 'node:fs/promises';
-import { EndpointDeliveryError, isMediaRef, type MessageRef } from '@zhin.js/im-contract';
-import type { EndpointSendRequest } from 'zhin.js/adapter';
+import type { Sendable } from 'kook-client';
+import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
+import { createEndpointOperation, type EndpointRecallRequest, type EndpointSendRequest } from 'zhin.js/adapter';
 import { formatOutboundKmarkdown } from './protocol.js';
 import type { KookClientTransport } from './ws.js';
 import { outboundMessages as t } from './i18n.js';
 
 /** Native cards preserve mixed text/images; SDK's ordinary segments stop at first media. */
-export async function sendKookOutbound(client: KookClientTransport, { conversation, payload, locale }: EndpointSendRequest): Promise<string> {
+export async function sendKookOutbound(client: KookClientTransport, { conversation, payload, locale, signal }: EndpointSendRequest): Promise<string> {
+  const operation = createEndpointOperation({ signal });
   try {
     const items = Array.isArray(payload) ? payload : payload && typeof payload === 'object' ? [payload] : [payload];
     let quote: { message_id: string } | undefined;
@@ -52,13 +54,13 @@ export async function sendKookOutbound(client: KookClientTransport, { conversati
           if (!client.uploadMedia) throw new EndpointDeliveryError('unsupported_media', 'KOOK transport cannot upload images', 'rejected');
           let bytes: Buffer;
           if (media.kind === 'base64') bytes = Buffer.from(media.value.replace(/^data:[^,]*,/, ''), 'base64');
-          else if (media.kind === 'path') bytes = await readFile(media.value);
+          else if (media.kind === 'path') bytes = await operation.prepare(() => readFile(media.value));
           else {
-            const response = await fetch(media.value, { signal: AbortSignal.timeout(30_000) });
+            const response = await operation.prepare(() => fetch(media.value, { signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000) }));
             if (!response.ok) throw new EndpointDeliveryError('media_download_failed', 'KOOK media download failed', 'rejected');
-            bytes = Buffer.from(await response.arrayBuffer());
+            bytes = Buffer.from(await operation.prepare(() => response.arrayBuffer()));
           }
-          url = await client.uploadMedia(bytes);
+          url = await operation.prepare(() => client.uploadMedia!(bytes));
         }
         if (typeof url !== 'string' || !/^https:\/\//.test(url)) throw new EndpointDeliveryError('delivery_unconfirmed', 'KOOK upload returned no media URL', 'unknown');
         modules.push({ type: 'container', elements: [{ type: 'image', src: url, alt: String(item.data?.alt ?? 'image') }] });
@@ -72,10 +74,11 @@ export async function sendKookOutbound(client: KookClientTransport, { conversati
       }
     }
     const body = hasImage || hasCard ? { __isCard: true, type: 'card', theme: 'secondary', size: 'lg', modules } : formatOutboundKmarkdown(payload, locale);
-    const result = conversation.kind === 'private'
-      ? await client.sendPrivateMsg(conversation.id, body, quote)
-      : await client.sendChannelMsg(conversation.id, body, quote);
-    const id = result?.msg_id != null ? String(result.msg_id) : '';
+    // SDK 1.0.5 implements __isCard and returns the API's msg_id; its declaration still describes Message.Ret.
+    const result: unknown = conversation.kind === 'private'
+      ? await operation.run(() => client.sendPrivateMsg(conversation.id, body as unknown as Sendable, quote))
+      : await operation.run(() => client.sendChannelMsg(conversation.id, body as unknown as Sendable, quote));
+    const id = result && typeof result === 'object' && 'msg_id' in result && result.msg_id != null ? String(result.msg_id) : '';
     if (!id.trim()) throw new EndpointDeliveryError('delivery_unconfirmed', 'KOOK did not return a real message ID', 'unknown');
     return id;
   } catch (error) {
@@ -89,16 +92,17 @@ export async function sendKookOutbound(client: KookClientTransport, { conversati
 
 
 /** Deletion requires the canonical conversation: KOOK has separate channel/private APIs. */
-export async function recallKookMessage(client: KookClientTransport, message: MessageRef): Promise<void> {
+export async function recallKookMessage(client: KookClientTransport, { message, signal }: EndpointRecallRequest): Promise<void> {
   if (!message.id.trim()) throw new EndpointDeliveryError('invalid_message_id', 'KOOK recall requires a message ID', 'rejected');
+  const operation = createEndpointOperation({ signal });
   try {
     let deleted: boolean;
     if (message.conversation.kind === 'private') {
       if (!client.recallPrivateMsg) throw new EndpointDeliveryError('unsupported_operation', 'KOOK transport cannot delete private messages', 'rejected');
-      deleted = await client.recallPrivateMsg(message.conversation.id, message.id);
+      deleted = await operation.run(() => client.recallPrivateMsg!(message.conversation.id, message.id));
     } else {
       if (!client.recallChannelMsg) throw new EndpointDeliveryError('unsupported_operation', 'KOOK transport cannot delete channel messages', 'rejected');
-      deleted = await client.recallChannelMsg(message.conversation.id, message.id);
+      deleted = await operation.run(() => client.recallChannelMsg!(message.conversation.id, message.id));
     }
     if (deleted !== true) throw new EndpointDeliveryError('platform_rejected', 'KOOK did not confirm message deletion', 'rejected');
   } catch (error) {

package/src/protocol.ts

@@ -114,6 +114,8 @@ export interface KookWebhookFrame {
 export type ResolvedKookConfig = ResolvedKookWebsocketConfig | ResolvedKookWebhookConfig;
 
 export interface KookInboundMessage {
+  readonly event?: unknown;
+  readonly platformSentAt?: number;
   readonly id: string;
   readonly content: string;
   readonly channelKind: 'private' | 'channel';
@@ -445,6 +447,8 @@ export function normalizeKookWebhookEvent(
 
   return {
     id: String(event.msg_id),
+    event,
+    ...(typeof event.msg_timestamp === 'number' ? { platformSentAt: event.msg_timestamp } : {}),
     content: event.content ?? '',
     channelKind,
     channelId,
@@ -460,7 +464,7 @@ export function normalizeKookWebhookEvent(
 }
 
 /** Native Card return-val events; routing and actor must come from the click event. */
-export function normalizeKookButtonEvent(raw: unknown): { id: string; sourceMessageId: string; payload: string; userId: string; channelKind: 'private' | 'channel'; channelId: string; timestamp: number } | null {
+export function normalizeKookButtonEvent(raw: unknown): { event: unknown; platformSentAt?: number; id: string; sourceMessageId: string; payload: string; userId: string; channelKind: 'private' | 'channel'; channelId: string; timestamp: number } | null {
   if (!raw || typeof raw !== 'object') return null;
   const event = raw as KookWebhookEventData;
   if (event.extra?.type !== 'message_btn_click') return null;
@@ -473,5 +477,5 @@ export function normalizeKookButtonEvent(raw: unknown): { id: string; sourceMess
   const channelId = channelKind === 'private' ? String(body.user_id) : String(bodyTarget || event.target_id || '');
   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/src/webhook.ts

@@ -1,3 +1,4 @@
+import { endpointSpec, type Endpoint } from 'zhin.js/adapter';
 /**
  * KOOK webhook HTTP: verify → parse → admit.
  */
@@ -17,8 +18,8 @@ import {
 
 const logger = getLogger('kook');
 
-export interface KookWebhookHandler {
-  readonly config: ResolvedKookWebhookConfig;
+export interface KookWebhookHandler extends Endpoint {
+  readonly endpointConfig: ResolvedKookWebhookConfig;
   readonly isOpen: boolean;
   readonly selfId?: string;
   admit(msg: KookInboundMessage): void;
@@ -31,7 +32,7 @@ export function registerKookWebhookRoutes(
   http: HttpHost,
   handler: KookWebhookHandler,
 ): HttpRouteRegistration[] {
-  const path = handler.config.webhookPath;
+  const path = handler.endpointConfig.webhookPath;
   return [
     http.route('POST', path, async (request, response) => {
       await handleKookWebhookRequest(request, response, handler);
@@ -48,7 +49,7 @@ export async function handleKookWebhookRequest(
     const rawBody = await readRequestBody(request);
     let frame: KookWebhookFrame;
     try {
-      frame = parseKookWebhookBody(rawBody, handler.config.encryptKey);
+      frame = parseKookWebhookBody(rawBody, handler.endpointConfig.encryptKey);
     } catch (error) {
       logger.warn(formatCompact({
         op: 'kook_webhook',
@@ -68,7 +69,7 @@ export async function handleKookWebhookRequest(
     }
 
     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;
@@ -78,7 +79,7 @@ export async function handleKookWebhookRequest(
       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;
@@ -89,25 +90,27 @@ export async function handleKookWebhookRequest(
       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' }));
-        return;
+    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);
     response.writeHead(200, { 'Content-Type': 'application/json' });

package/src/ws.ts

@@ -15,62 +15,7 @@ import {
   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;
+export type KookClientTransport = RuntimeKookClient;
 
 export function normalizeKookMessage(raw: unknown): KookInboundMessage | null {
   if (!raw || typeof raw !== 'object') return null;
@@ -109,6 +54,8 @@ export function normalizeKookMessage(raw: unknown): KookInboundMessage | null {
 
   return {
     id: String(msg.message_id),
+    event: raw,
+    ...(typeof msg.timestamp === 'number' ? { platformSentAt: msg.timestamp } : {}),
     content,
     channelKind,
     channelId,
@@ -125,6 +72,7 @@ export function normalizeKookMessage(raw: unknown): KookInboundMessage | null {
 }
 
 export class RuntimeKookClient extends Client {
+  readonly #apiAgent?: ReturnType<typeof createKookApiAgent>;
   readonly #lifecycle: ReturnType<typeof createEndpointLifecycle>;
   #initialized = false;
   #connectionAttempt = 0;
@@ -132,7 +80,8 @@ export class RuntimeKookClient extends Client {
     super({ ...config, autoReconnect: false, handleProcessErrors: false } as ConstructorParameters<typeof Client>[0]);
     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 => {
@@ -182,7 +131,7 @@ export class RuntimeKookClient extends Client {
       catch (error) { active = false; receiver.off('disconnected', disconnected); if (attempt === this.#connectionAttempt) await receiver.disconnect(); throw error; }
     });
   }
-  async disconnect(): Promise<void> { await this.#lifecycle.stop(); }
+  async disconnect(): Promise<void> { try { await this.#lifecycle.stop(); } finally { this.#apiAgent?.destroy(); } }
   /** Native FormData avoids kook-client's Buffer-to-text multipart conversion. */
   async uploadMedia(data: Buffer | string): Promise<string> {
     let bytes: Buffer;
@@ -241,8 +190,8 @@ export class RuntimeKookClient extends Client {
   }
 }
 
-export function defaultCreateClient(config: ResolvedKookWebsocketConfig): KookClientTransport {
-  return new RuntimeKookClient({
+export function kookWebsocketClientOptions(config: ResolvedKookWebsocketConfig): ConstructorParameters<typeof Client>[0] {
+  return {
     token: config.token,
     mode: 'websocket',
     socketFactory: (url: string) => createKookStreamSocket(url, config.streamProxy),
@@ -251,11 +200,11 @@ export function defaultCreateClient(config: ResolvedKookWebsocketConfig): KookCl
     max_retry: config.max_retry,
     ignore: config.ignore,
     logLevel: config.logLevel,
-  } as ConstructorParameters<typeof RuntimeKookClient>[0], undefined, config.apiProxy) as unknown as KookClientTransport;
+  } as ConstructorParameters<typeof Client>[0];
 }
 
-export function defaultCreateWebhookClient(config: ResolvedKookWebhookConfig): KookClientTransport {
-  return new RuntimeKookClient({
+export function kookWebhookClientOptions(config: ResolvedKookWebhookConfig): ConstructorParameters<typeof Client>[0] {
+  return {
     token: config.token,
     mode: 'webhook',
     data_dir: path.join(process.cwd(), 'data', 'kook'),
@@ -263,5 +212,5 @@ export function defaultCreateWebhookClient(config: ResolvedKookWebhookConfig): K
     max_retry: 3,
     ignore: config.ignore,
     logLevel: config.logLevel,
-  } as ConstructorParameters<typeof RuntimeKookClient>[0], undefined, config.apiProxy) as unknown as KookClientTransport;
+  } as ConstructorParameters<typeof Client>[0];
 }

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

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

package/lib/kook-runtime-state.js

@@ -1,6 +0,0 @@
-/**
- * KOOK 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `kook endpoint` 命令共享（同一 owner generation）。
- */
-import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
-export const kookRuntimeStateToken = defineEndpointRuntimeStateToken('kook');

package/src/kook-runtime-state.ts

@@ -1,7 +0,0 @@
-/**
- * KOOK 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `kook endpoint` 命令共享（同一 owner generation）。
- */
-import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
-
-export const kookRuntimeStateToken = defineEndpointRuntimeStateToken('kook');