@zhin.js/adapter-kook 1.1.4 → 1.1.5

package/lib/protocol.js

@@ -1,7 +1,7 @@
 /** KOOK protocol helpers. Canonicalization is owned by Core. */
 import { createDecipheriv, timingSafeEqual } from 'node:crypto';
 import { inflateSync } from 'node:zlib';
-import { isMediaRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('kook');
 export var KookPermission;
@@ -12,6 +12,11 @@ export var KookPermission;
     KookPermission[KookPermission["ChannelAdmin"] = 5] = "ChannelAdmin";
 })(KookPermission || (KookPermission = {}));
 export function resolveKookConfig(config) {
+    if (config.apiProxy && (!Number.isInteger(config.apiProxy.port) || config.apiProxy.port < 1 || config.apiProxy.port > 65535))
+        throw new TypeError('Invalid KOOK apiProxy port');
+    if (config.streamProxy && (!Number.isInteger(config.streamProxy.port) || config.streamProxy.port < 1 || config.streamProxy.port > 65535
+        || typeof config.streamProxy.serverName !== 'string' || !config.streamProxy.serverName || /[\s/:@?#]/.test(config.streamProxy.serverName)))
+        throw new TypeError('Invalid KOOK streamProxy port/serverName');
     const id = requiredEndpointField(config.id, 'id');
     const token = requiredEndpointField(config.token, 'token');
     const connection = config.connection ?? 'websocket';
@@ -21,6 +26,7 @@ export function resolveKookConfig(config) {
         return {
             context: 'kook',
             connection: 'webhook',
+            ...(config.apiProxy ? { apiProxy: config.apiProxy } : {}),
             id,
             token,
             webhookPath: normalizeWebhookPath(config.webhookPath ?? '/kook/webhook'),
@@ -33,6 +39,8 @@ export function resolveKookConfig(config) {
     return {
         context: 'kook',
         connection: 'websocket',
+        ...(config.apiProxy ? { apiProxy: config.apiProxy } : {}),
+        ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
         id,
         token,
         data_dir: config.data_dir,
@@ -135,6 +143,9 @@ export function formatOutboundKmarkdown(payload) {
                 return String(data.text ?? data.content ?? '');
             case 'markdown':
                 return String(data.content ?? data.text ?? '');
+            case 'share':
+            case 'keyboard':
+                throw new EndpointDeliveryError('unsupported_operation', 'KOOK share cards and native keyboards are not implemented', 'not_sent');
             case 'at': {
                 const id = String(data.user_id ?? data.qq ?? data.id ?? '');
                 return id === 'all' ? '(met)all(met)' : `(met)${id}(met)`;
@@ -298,3 +309,23 @@ export function normalizeKookWebhookEvent(event, options = {}) {
         guildId: event.extra?.guild_id,
     };
 }
+/** Native Card return-val events; routing and actor must come from the click event. */
+export function normalizeKookButtonEvent(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const event = raw;
+    if (event.extra?.type !== 'message_btn_click')
+        return null;
+    const body = event.extra.body;
+    if (!body || typeof body.value !== 'string' || !body.value || !body.user_id || !body.msg_id)
+        return null;
+    // Button system notifications can use PERSON even for a channel card.
+    // body.target_id identifies the original channel; envelope target_id is the recipient.
+    const bodyTarget = body.channel_id || body.target_id;
+    const channelKind = (bodyTarget && String(bodyTarget) !== String(body.user_id)) || event.channel_type === 'GROUP' ? 'channel' : 'private';
+    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 };
+}

package/lib/stream-proxy.d.ts

@@ -0,0 +1,7 @@
+import WebSocket from 'ws';
+export interface KookStreamProxy {
+    readonly port: number;
+    readonly serverName: string;
+}
+/** Route TCP only. WSS HTTP Host, path, ticket, TLS SNI and peer validation stay original. */
+export declare function createKookStreamSocket(url: string, proxy?: KookStreamProxy): WebSocket;

package/lib/stream-proxy.js

@@ -0,0 +1,18 @@
+import tls from 'node:tls';
+import WebSocket from 'ws';
+import { getLogger } from '@zhin.js/logger';
+/** Route TCP only. WSS HTTP Host, path, ticket, TLS SNI and peer validation stay original. */
+export function createKookStreamSocket(url, proxy) {
+    if (!proxy)
+        return new WebSocket(url);
+    const target = new URL(url);
+    if (target.protocol !== 'wss:' || target.hostname !== proxy.serverName || (target.port && target.port !== '443')) {
+        // The hostname is safe diagnostics; never print URL/query/ticket or SDK errors.
+        getLogger('kook').warn(`Stream proxy rejected gateway hostname: ${target.hostname}`);
+        throw new Error('KOOK Stream proxy gateway identity changed; update the fixed upstream before retrying');
+    }
+    return new WebSocket(url, {
+        createConnection: (options) => tls.connect({ ...options, path: undefined, host: '127.0.0.1', port: proxy.port,
+            servername: target.hostname, rejectUnauthorized: true }),
+    });
+}

package/lib/webhook.d.ts

@@ -9,8 +9,9 @@ export interface KookWebhookHandler {
     readonly isOpen: boolean;
     readonly selfId?: string;
     admit(msg: KookInboundMessage): void;
-    admitEvent(event: KookWebhookEventData): void;
+    admitEvent(event: KookWebhookEventData): Promise<void> | void;
     checkAndRememberSn(sn: number): boolean;
+    forgetSn?(sn: number): void;
 }
 export declare function registerKookWebhookRoutes(http: HttpHost, handler: KookWebhookHandler): HttpRouteRegistration[];
 export declare function handleKookWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: KookWebhookHandler): Promise<void>;

package/lib/webhook.js

@@ -47,6 +47,11 @@ export async function handleKookWebhookRequest(request, response, handler) {
             response.end(JSON.stringify({ message: 'Invalid verify_token' }));
             return;
         }
+        if (!handler.isOpen) {
+            response.writeHead(503, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ message: 'Endpoint unavailable' }));
+            return;
+        }
         if (frame.sn != null) {
             if (!handler.checkAndRememberSn(frame.sn)) {
                 response.writeHead(200, { 'Content-Type': 'application/json' });
@@ -54,8 +59,15 @@ export async function handleKookWebhookRequest(request, response, handler) {
                 return;
             }
         }
-        if (handler.isOpen) {
-            handleKookWebhookEvent(event, handler);
+        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' }));
@@ -66,6 +78,3 @@ export async function handleKookWebhookRequest(request, response, handler) {
         response.end(JSON.stringify({ message: 'OK' }));
     }
 }
-function handleKookWebhookEvent(event, handler) {
-    handler.admitEvent(event);
-}

package/lib/ws.d.ts

@@ -1,17 +1,27 @@
+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: string): Promise<{
+    sendChannelMsg(channelId: string, message: unknown, quote?: {
+        message_id: string;
+    }): Promise<{
         msg_id?: string | number;
     }>;
-    sendPrivateMsg(userId: string, message: string): Promise<{
+    sendPrivateMsg(userId: string, message: unknown, quote?: {
+        message_id: string;
+    }): Promise<{
         msg_id?: string | number;
     }>;
-    recallMsg?(messageId: string): Promise<boolean>;
+    uploadMedia?(data: Buffer): Promise<string>;
+    recallChannelMsg?(channelId: string, messageId: string): Promise<boolean>;
+    recallPrivateMsg?(userId: string, messageId: string): Promise<boolean>;
     pickGuild(guildId: string): {
         kick(userId: string): Promise<boolean>;
         getRoleList(): Promise<Array<{
@@ -52,5 +62,16 @@ export interface KookClientTransport {
 }
 export type CreateKookClient = (config: ResolvedKookConfig) => KookClientTransport;
 export declare function normalizeKookMessage(raw: unknown): KookInboundMessage | null;
+export declare class RuntimeKookClient extends Client {
+    #private;
+    constructor(config: ConstructorParameters<typeof Client>[0], lifecycleOptions?: Parameters<typeof createEndpointLifecycle>[0], apiProxy?: KookApiProxy);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /** Native FormData avoids kook-client's Buffer-to-text multipart conversion. */
+    uploadMedia(data: Buffer | string): Promise<string>;
+    getTransportState(): EndpointTransportState | undefined;
+    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;

package/lib/ws.js

@@ -2,7 +2,12 @@
  * KOOK WebSocket transport: kook-client wrapper and inbound message normalization.
  */
 import path from 'node:path';
-import { Client } from 'kook-client';
+import { createKookApiAgent } from './api-proxy.js';
+import { readFile } from 'node:fs/promises';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { Client, WebsocketReceiver } from 'kook-client';
+import { createKookStreamSocket } from './stream-proxy.js';
+import { createEndpointLifecycle } from 'zhin.js/adapter';
 export function normalizeKookMessage(raw) {
     if (!raw || typeof raw !== 'object')
         return null;
@@ -23,35 +28,182 @@ export function normalizeKookMessage(raw) {
         }
     }
     const content = textParts.join('') || msg.raw_message || '';
+    // kook-client resolves these getters through optional local caches and throws
+    // for uncached users/channels. Identity and routing come from the event itself.
+    let author;
+    let channel;
+    try {
+        author = msg.author;
+    }
+    catch { /* optional cache enrichment unavailable */ }
+    try {
+        channel = msg.channel;
+    }
+    catch { /* optional cache enrichment unavailable */ }
     return {
         id: String(msg.message_id),
         content,
         channelKind,
         channelId,
         authorId: String(msg.author_id),
-        authorName: msg.author?.info?.nickname
-            || msg.author?.info?.username
+        authorName: author?.info?.nickname
+            || author?.info?.username
             || String(msg.author_id),
-        authorBot: msg.author?.bot === true || msg.author?.info?.bot === true,
-        authorRoles: msg.author?.info?.roles ?? msg.author?.roles,
+        authorBot: author?.bot === true || author?.info?.bot === true,
+        authorRoles: author?.info?.roles ?? author?.roles,
         timestamp: msg.timestamp ?? Date.now(),
-        guildId: msg.channel?.info?.guild_id,
+        guildId: channel?.info?.guild_id,
         rawMessage: msg.raw_message,
     };
 }
+export class RuntimeKookClient extends Client {
+    #lifecycle;
+    #initialized = false;
+    #connectionAttempt = 0;
+    constructor(config, lifecycleOptions = { name: 'kook' }, apiProxy) {
+        super({ ...config, autoReconnect: false, handleProcessErrors: false });
+        this.#lifecycle = createEndpointLifecycle(lifecycleOptions);
+        if (apiProxy) {
+            this.request.defaults.httpsAgent = createKookApiAgent(apiProxy);
+            this.request.defaults.proxy = false;
+            this.request.defaults.maxRedirects = 0;
+            this.request.interceptors.request.use(request => {
+                const target = new URL(request.url ?? '', request.baseURL);
+                if (target.protocol !== 'https:' || target.hostname !== 'www.kookapp.cn' || (target.port && target.port !== '443')) {
+                    throw new EndpointDeliveryError('invalid_destination', 'KOOK API proxy rejected destination identity', 'not_sent');
+                }
+                return request;
+            });
+        }
+        const transforms = this.request.defaults.transformResponse;
+        this.request.defaults.transformResponse = [
+            ...(Array.isArray(transforms) ? transforms : transforms ? [transforms] : []),
+            (data, _headers, status) => {
+                // Classify HTTP status before the SDK discards it in its error interceptor.
+                if (status !== undefined && status >= 400) {
+                    const rejected = status < 500 && status !== 408;
+                    throw new EndpointDeliveryError(rejected ? 'platform_rejected' : 'delivery_unconfirmed', `KOOK HTTP request failed (status=${status})`, rejected ? 'rejected' : 'unknown');
+                }
+                return data;
+            },
+        ];
+        this.request.interceptors.response.use(response => {
+            // kook-client unwraps HTTP JSON but does not reject nonzero platform codes.
+            const body = response;
+            if (typeof body.code === 'number' && body.code !== 0) {
+                throw new EndpointDeliveryError('platform_rejected', `KOOK rejected API request (code=${body.code})`, 'rejected');
+            }
+            return response;
+        });
+    }
+    async connect() {
+        await this.#lifecycle.start(async (handle) => {
+            const attempt = ++this.#connectionAttempt;
+            const receiver = this.receiver;
+            let active = true;
+            const disconnected = () => { if (!active)
+                return; active = false; receiver.off('disconnected', disconnected); handle.notifyClosed('KOOK receiver disconnected'); };
+            receiver.on('disconnected', disconnected);
+            handle.onForceClose(() => { active = false; receiver.off('disconnected', disconnected); if (attempt === this.#connectionAttempt)
+                void receiver.disconnect(); });
+            try {
+                const resume = receiver instanceof WebsocketReceiver && receiver.canResume();
+                await receiver.connect(resume);
+                if (!active || attempt !== this.#connectionAttempt)
+                    throw new Error('KOOK connection closed before admission');
+                if (!resume || !this.#initialized) {
+                    await this.init();
+                    this.#initialized = true;
+                }
+            }
+            catch (error) {
+                active = false;
+                receiver.off('disconnected', disconnected);
+                if (attempt === this.#connectionAttempt)
+                    await receiver.disconnect();
+                throw error;
+            }
+        });
+    }
+    async disconnect() { await this.#lifecycle.stop(); }
+    /** Native FormData avoids kook-client's Buffer-to-text multipart conversion. */
+    async uploadMedia(data) {
+        let bytes;
+        if (Buffer.isBuffer(data))
+            bytes = data;
+        else if (/^https?:\/\//.test(data)) {
+            const downloaded = await fetch(data, { signal: AbortSignal.timeout(30_000) });
+            if (!downloaded.ok)
+                throw new EndpointDeliveryError('media_download_failed', 'KOOK source download failed', 'rejected');
+            bytes = Buffer.from(await downloaded.arrayBuffer());
+        }
+        else if (/^data:[^,]*;base64,/.test(data) || data.startsWith('base64://')) {
+            bytes = Buffer.from(data.replace(/^data:[^,]*,|^base64:\/\//, ''), 'base64');
+        }
+        else
+            bytes = await readFile(data.replace(/^file:\/\//, ''));
+        const form = new FormData();
+        form.append('file', new Blob([Uint8Array.from(bytes)]), 'image.png');
+        const response = await fetch('https://www.kookapp.cn/api/v3/asset/create', {
+            method: 'POST', headers: { Authorization: `Bot ${this.config.token}` }, body: form,
+            signal: AbortSignal.timeout(30_000),
+        });
+        const body = await response.json();
+        if (!response.ok || body.code !== 0) {
+            const rejected = response.status >= 400 && response.status < 500 && response.status !== 408 || response.ok && typeof body.code === 'number' && body.code !== 0;
+            throw new EndpointDeliveryError(rejected ? 'platform_rejected' : 'delivery_unconfirmed', `KOOK upload failed (status=${response.status}, code=${typeof body.code === 'number' ? body.code : 'missing'})`, rejected ? 'rejected' : 'unknown');
+        }
+        if (typeof body.data?.url !== 'string')
+            throw new EndpointDeliveryError('delivery_unconfirmed', 'KOOK upload returned no URL', 'unknown');
+        return body.data.url;
+    }
+    #preloading = false;
+    getTransportState() {
+        if (!(this.receiver instanceof WebsocketReceiver))
+            return undefined;
+        return this.#lifecycle.state;
+    }
+    async init() {
+        this.#preloading = true;
+        try {
+            return await super.init();
+        }
+        finally {
+            this.#preloading = false;
+        }
+    }
+    async getBlacklist(guildId) {
+        try {
+            return await super.getBlacklist(guildId);
+        }
+        catch (error) {
+            // kook-client 1.0.4 discards structured HTTP metadata in its interceptor.
+            // Match only its exact blacklist permission-denial prefix during preload.
+            if (this.#preloading && error instanceof Error
+                && (error.message.startsWith('request "/v3/blacklist/list" error with code(403):')
+                    || error instanceof EndpointDeliveryError && error.code === 'platform_rejected'
+                        && error.disposition === 'rejected' && error.message === 'KOOK HTTP request failed (status=403)')) {
+                this.logger.warn('启动预加载跳过黑名单：缺少管理权限；消息收发继续。');
+                return [];
+            }
+            throw error;
+        }
+    }
+}
 export function defaultCreateClient(config) {
-    return new Client({
+    return new RuntimeKookClient({
         token: config.token,
         mode: 'websocket',
+        socketFactory: (url) => createKookStreamSocket(url, config.streamProxy),
         data_dir: config.data_dir || path.join(process.cwd(), 'data', 'kook'),
         timeout: config.timeout,
         max_retry: config.max_retry,
         ignore: config.ignore,
         logLevel: config.logLevel,
-    });
+    }, undefined, config.apiProxy);
 }
 export function defaultCreateWebhookClient(config) {
-    return new Client({
+    return new RuntimeKookClient({
         token: config.token,
         mode: 'webhook',
         data_dir: path.join(process.cwd(), 'data', 'kook'),
@@ -59,5 +211,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.4",
+  "version": "1.1.5",
   "description": "Zhin.js KOOK adapter for Plugin Runtime (WebSocket gateway or Webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,23 +34,23 @@
   },
   "dependencies": {
     "kook-client": "^1.0.4",
-    "@zhin.js/adapter": "1.1.15",
-    "@zhin.js/agent-feature": "1.1.2",
-    "@zhin.js/core": "1.1.39",
+    "@zhin.js/adapter": "1.1.16",
+    "@zhin.js/agent-feature": "1.1.3",
+    "@zhin.js/core": "1.1.40",
     "@zhin.js/feature-kit": "1.1.2",
-    "@zhin.js/host-http": "1.1.2",
-    "@zhin.js/im-contract": "1.1.2",
+    "@zhin.js/host-http": "1.1.3",
+    "@zhin.js/im-contract": "1.1.3",
     "@zhin.js/logger": "1.1.1",
     "@zhin.js/permission": "1.1.3",
-    "@zhin.js/skill": "1.1.2",
-    "@zhin.js/tool": "1.1.2"
+    "@zhin.js/skill": "1.1.3",
+    "@zhin.js/tool": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.15",
-    "@zhin.js/command": "^1.1.3",
-    "@zhin.js/core": "^1.1.39",
-    "zhin.js": "^1.1.4"
+    "@zhin.js/adapter": "^1.1.16",
+    "@zhin.js/command": "^1.1.4",
+    "@zhin.js/core": "^1.1.40",
+    "zhin.js": "^1.1.5"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -68,8 +68,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.2",
-    "zhin.js": "1.1.4"
+    "@zhin.js/host-http": "1.1.3",
+    "zhin.js": "1.1.5"
   },
   "files": [
     "adapters",

package/schema.json

@@ -151,6 +151,42 @@
           "id": {
             "type": "string",
             "description": "KOOK bot name"
+          },
+          "streamProxy": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "port": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              },
+              "serverName": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[^\\s/:@?#]+$"
+              }
+            },
+            "required": [
+              "port",
+              "serverName"
+            ],
+            "description": "WSS故障验收固定loopback，保持真实TLS身份"
+          },
+          "apiProxy": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "port"
+            ],
+            "properties": {
+              "port": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              }
+            },
+            "description": "Optional fixed loopback TCP route for www.kookapp.cn JSON API only; verified TLS remains enabled."
           }
         },
         "required": [

package/src/api-proxy.ts

@@ -0,0 +1,21 @@
+import { Agent } from 'node:https';
+import tls from 'node:tls';
+import { Socket } from 'node:net';
+
+export interface KookApiProxy { readonly port: number }
+
+/** JSON Web API only: keep www.kookapp.cn identity, route TCP to a fixed loopback port. */
+export function createKookApiAgent(proxy: KookApiProxy): Agent {
+  const agent = new Agent({ keepAlive: false });
+  agent.createConnection = options => {
+    const hostname = String(options.hostname ?? options.host ?? '');
+    if (hostname !== 'www.kookapp.cn' || Number(options.port ?? 443) !== 443) {
+      const rejected = new Socket();
+      queueMicrotask(() => rejected.destroy(new Error('KOOK JSON API proxy rejected destination identity')));
+      return rejected;
+    }
+    return tls.connect({ ...options as tls.ConnectionOptions, path: undefined,
+      host: '127.0.0.1', port: proxy.port, servername: 'www.kookapp.cn', rejectUnauthorized: true });
+  };
+  return agent;
+}