@zhin.js/adapter-kook 1.0.84 → 1.1.0

package/lib/protocol.js

@@ -0,0 +1,313 @@
+/**
+ * KOOK protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { createDecipheriv, timingSafeEqual } from 'node:crypto';
+import { inflateSync } from 'node:zlib';
+import { pickCredential } from 'zhin.js/adapter';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('kook');
+export var KookPermission;
+(function (KookPermission) {
+    KookPermission[KookPermission["Normal"] = 1] = "Normal";
+    KookPermission[KookPermission["Admin"] = 2] = "Admin";
+    KookPermission[KookPermission["Owner"] = 4] = "Owner";
+    KookPermission[KookPermission["ChannelAdmin"] = 5] = "ChannelAdmin";
+})(KookPermission || (KookPermission = {}));
+export function resolveKookConfig(config = {}) {
+    const entry = config.endpoints?.find((item) => item.context === 'kook' || !item.context);
+    const token = pickCredential(config.token, entry?.token, process.env.KOOK_TOKEN, process.env.KOOK_BOT_TOKEN);
+    if (!token) {
+        throw new TypeError('KOOK adapter requires token (plugins.<key>.token or endpoints with context: kook)');
+    }
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
+        || process.env.KOOK_BOT_NAME
+        || 'kook-bot';
+    const connection = config.connection
+        ?? entry?.connection
+        ?? 'websocket';
+    if (connection === 'webhook') {
+        const verifyToken = (typeof config.verify_token === 'string' && config.verify_token)
+            || (typeof entry?.verify_token === 'string' && entry.verify_token)
+            || process.env.KOOK_VERIFY_TOKEN
+            || '';
+        if (!verifyToken) {
+            throw new TypeError('KOOK webhook mode requires verify_token (plugins.<key>.verify_token or KOOK_VERIFY_TOKEN)');
+        }
+        const encryptKey = config.encrypt_key ?? entry?.encrypt_key ?? process.env.KOOK_ENCRYPT_KEY;
+        return {
+            context: 'kook',
+            connection: 'webhook',
+            id,
+            token,
+            webhookPath: normalizeWebhookPath(config.webhookPath ?? entry?.webhookPath ?? process.env.KOOK_WEBHOOK_PATH ?? '/kook/webhook'),
+            verifyToken,
+            encryptKey: typeof encryptKey === 'string' && encryptKey ? encryptKey : undefined,
+            ignore: config.ignore ?? entry?.ignore ?? 'bot',
+            logLevel: config.logLevel ?? entry?.logLevel ?? 'info',
+        };
+    }
+    return {
+        context: 'kook',
+        connection: 'websocket',
+        id,
+        token,
+        data_dir: config.data_dir ?? entry?.data_dir,
+        timeout: config.timeout ?? entry?.timeout ?? 10_000,
+        max_retry: config.max_retry ?? entry?.max_retry ?? 3,
+        ignore: config.ignore ?? entry?.ignore ?? 'bot',
+        logLevel: config.logLevel ?? entry?.logLevel ?? 'info',
+    };
+}
+/**
+ * 入站归一化 → ConversationRef：频道消息的所属 guild 进 `parent`（guild 容器
+ * 映射为 channel 容器）；私聊（PERSON）无容器，直接 kind 'private'。
+ */
+export function kookInboundConversation(endpointKey, msg) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: msg.channelKind,
+        id: msg.channelId,
+        ...(msg.guildId && msg.channelKind === 'channel'
+            ? { parent: { kind: 'channel', id: msg.guildId } }
+            : {}),
+    };
+}
+export function senderDisplayName(msg) {
+    return msg.authorName || msg.authorId;
+}
+/** Build inbound text for OutboundMessageService.receive */
+export function formatInboundContent(msg) {
+    const text = (msg.content || msg.rawMessage || '').trim();
+    return text || '(Empty message)';
+}
+/**
+ * KOOK @ 用户标记为 `(met)<userId>(met)`；content 含 `(met)<botId>(met)` 时视为 @ 机器人。
+ * botId 取 client 缓存的 self_id（/me 类接口），拿不到则不标注。
+ */
+export function isKookBotMentioned(msg, selfId) {
+    if (!selfId)
+        return false;
+    const marker = `(met)${selfId}(met)`;
+    return (msg.content || '').includes(marker) || (msg.rawMessage || '').includes(marker);
+}
+/**
+ * 解析 image/audio/video/file 段的投递 URL（canonical MediaRef 唯一来源）。
+ * KOOK KMarkdown 媒体只能消费远程 URL；base64 / path / file 引用无法经
+ * KMarkdown 投递，warn 后丢弃（返回 undefined）。
+ */
+function resolveOutboundMediaUrl(seg) {
+    const media = (seg.data ?? {}).media;
+    if (!isMediaRef(media)) {
+        logger.warn(formatCompact({
+            op: 'kook_outbound_media_dropped',
+            type: seg.type,
+            reason: 'missing_media_ref',
+        }));
+        return undefined;
+    }
+    if (media.kind !== 'url') {
+        logger.warn(formatCompact({
+            op: 'kook_outbound_media_dropped',
+            type: seg.type,
+            reason: 'unsupported_media_kind',
+            kind: media.kind,
+        }));
+        return undefined;
+    }
+    return media.value;
+}
+/**
+ * Wire-encode an already-rendered outbound payload into KOOK KMarkdown.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundKmarkdown(payload) {
+    if (typeof payload === 'string')
+        return payload;
+    const segments = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    if (segments.length === 0) {
+        return payload == null
+            ? ''
+            : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload);
+    }
+    return segments
+        .map((item) => {
+        if (typeof item === 'string')
+            return item;
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'text':
+                return String(data.text ?? data.content ?? '');
+            case 'markdown':
+                return String(data.content ?? data.text ?? '');
+            case 'at': {
+                const id = String(data.user_id ?? data.qq ?? data.id ?? '');
+                return id === 'all' ? '(met)all(met)' : `(met)${id}(met)`;
+            }
+            case 'image': {
+                const url = resolveOutboundMediaUrl(item);
+                return url ? `![${String(data.alt || '图片')}](${url})` : '';
+            }
+            case 'face':
+                return `(emj)${String(data.name || 'emoji')}(emj)[${String(data.id ?? '')}]`;
+            case 'link':
+                return `[${String(data.text || data.url || '')}](${String(data.url || '')})`;
+            case 'video': {
+                const url = resolveOutboundMediaUrl(item);
+                return url ? `[视频](${url})` : '';
+            }
+            case 'audio': {
+                const url = resolveOutboundMediaUrl(item);
+                return url ? `[音频](${url})` : '';
+            }
+            case 'file': {
+                const url = resolveOutboundMediaUrl(item);
+                return url ? `[文件: ${String(data.name || '未命名')}](${url})` : '';
+            }
+            case 'bold':
+                return `**${String(data.text ?? '')}**`;
+            case 'italic':
+                return `*${String(data.text ?? '')}*`;
+            case 'code':
+                return `\`${String(data.text ?? '')}\``;
+            case 'code_block':
+                return `\`\`\`${String(data.language || '')}\n${String(data.text ?? '')}\n\`\`\``;
+            case 'reply':
+                return '';
+            default:
+                return data.text != null ? String(data.text) : '';
+        }
+    })
+        .filter(Boolean)
+        .join('');
+}
+export function normalizeWebhookPath(path) {
+    const trimmed = path.trim() || '/kook/webhook';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+export async function readTextBody(request, options = {}) {
+    const limit = options.limit ?? 1_048_576;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > limit) {
+            request.destroy();
+            throw new Error(`Request body exceeds ${limit} bytes`);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export async function readRequestBody(request, options = {}) {
+    const limit = options.limit ?? 1_048_576;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > limit) {
+            request.destroy();
+            throw new Error(`Request body exceeds ${limit} bytes`);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+}
+export function padKookEncryptKey(key) {
+    const buf = Buffer.alloc(32, 0);
+    Buffer.from(key, 'utf8').copy(buf, 0, 0, Math.min(32, Buffer.byteLength(key, 'utf8')));
+    return buf;
+}
+export function decryptKookWebhookPayload(encrypted, encryptKey) {
+    const decoded = Buffer.from(encrypted, 'base64');
+    const iv = decoded.subarray(0, 16);
+    const ciphertext = decoded.subarray(16);
+    const decipher = createDecipheriv('aes-256-cbc', padKookEncryptKey(encryptKey), iv);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+export function parseKookWebhookBody(rawBody, encryptKey) {
+    let text = rawBody.toString('utf8').trim();
+    if (!text.startsWith('{')) {
+        text = inflateSync(rawBody).toString('utf8');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new TypeError('Invalid KOOK webhook JSON body');
+    }
+    if (parsed.encrypt) {
+        if (!encryptKey) {
+            throw new TypeError('KOOK webhook payload is encrypted but encrypt_key is not configured');
+        }
+        const decrypted = decryptKookWebhookPayload(parsed.encrypt, encryptKey);
+        // 在字节层面判断：明文 JSON 以 '{' 开头，否则按 zlib 压缩数据处理。
+        // 不能先 toString('utf8') 再转回 Buffer —— 压缩二进制会被替换字符损坏。
+        let offset = 0;
+        while (offset < decrypted.length
+            && (decrypted[offset] === 0x20 || decrypted[offset] === 0x09
+                || decrypted[offset] === 0x0a || decrypted[offset] === 0x0d)) {
+            offset += 1;
+        }
+        const decryptedText = decrypted[offset] === 0x7b // '{'
+            ? decrypted.toString('utf8')
+            : inflateSync(decrypted).toString('utf8');
+        parsed = JSON.parse(decryptedText);
+    }
+    return parsed;
+}
+export function isKookWebhookChallenge(event) {
+    return event.type === 255 && event.channel_type === 'WEBHOOK_CHALLENGE';
+}
+export function verifyKookWebhookToken(expected, actual) {
+    if (!actual)
+        return false;
+    const left = Buffer.from(expected, 'utf8');
+    const right = Buffer.from(actual, 'utf8');
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(left, right);
+}
+export function normalizeKookWebhookEvent(event, options = {}) {
+    if (isKookWebhookChallenge(event))
+        return null;
+    if (event.msg_id == null || event.author_id == null)
+        return null;
+    const authorBot = event.extra?.author?.bot === true;
+    if (authorBot && options.ignore === 'bot')
+        return null;
+    if (options.selfId && String(event.author_id) === options.selfId && options.ignore === 'self') {
+        return null;
+    }
+    const channelKind = event.channel_type === 'GROUP' ? 'channel' : 'private';
+    const channelId = channelKind === 'channel'
+        ? String(event.target_id ?? '')
+        : String(event.author_id);
+    if (!channelId)
+        return null;
+    return {
+        id: String(event.msg_id),
+        content: event.content ?? '',
+        channelKind,
+        channelId,
+        authorId: String(event.author_id),
+        authorName: event.extra?.author?.username
+            || event.extra?.author?.id
+            || String(event.author_id),
+        authorBot,
+        authorRoles: event.extra?.author?.roles,
+        timestamp: event.msg_timestamp ?? Date.now(),
+        guildId: event.extra?.guild_id,
+    };
+}

package/lib/side-event-dispatch.d.ts

@@ -0,0 +1,3 @@
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
+import { type getAdapterLogger } from '@zhin.js/logger';
+export declare function receiveKookSideEvent(emit: EndpointEventEmitter, configId: string, raw: unknown, logger: ReturnType<typeof getAdapterLogger>): boolean;

package/lib/side-event-dispatch.js

@@ -0,0 +1,49 @@
+import { buildNotice, mapNoticeParts, senderFromId, KOOK_NOTICE_PARTS_MAP } from '@zhin.js/core';
+import { formatCompact } from '@zhin.js/logger';
+function extractKookNoticeType(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const event = raw;
+    const extraType = event.extra?.type;
+    if (typeof extraType === 'string' && extraType)
+        return extraType;
+    if (event.channel_type === 'NOTICE' && event.type != null) {
+        return String(event.type);
+    }
+    return null;
+}
+export function receiveKookSideEvent(emit, configId, raw, logger) {
+    const noticeType = extractKookNoticeType(raw);
+    if (!noticeType)
+        return false;
+    if (!Object.prototype.hasOwnProperty.call(KOOK_NOTICE_PARTS_MAP, noticeType))
+        return false;
+    const event = raw;
+    const parts = mapNoticeParts('kook', noticeType);
+    const guildId = event.extra?.guild_id;
+    const userId = event.author_id ?? event.extra?.author?.id;
+    const sceneId = guildId != null
+        ? String(guildId)
+        : userId != null
+            ? String(userId)
+            : configId;
+    void emit('notice.receive', buildNotice(event, {
+        $id: `kook:${noticeType}:${event.msg_timestamp ?? Date.now()}:${sceneId}:${String(userId ?? '')}`,
+        $adapter: 'kook',
+        $endpoint: configId,
+        $type: 'notice',
+        $scene_id: sceneId,
+        $scene_type: parts.scene_type,
+        $sub_type: parts.sub_type,
+        $actor: senderFromId(userId, event.extra?.author?.username),
+        $timestamp: event.msg_timestamp ?? Date.now(),
+    })).catch((err) => {
+        logger.warn(formatCompact({
+            op: 'kook_side_event_failed',
+            endpoint: configId,
+            event: noticeType,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    });
+    return true;
+}

package/lib/webhook.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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;
+    readonly isOpen: boolean;
+    readonly selfId?: string;
+    admit(msg: KookInboundMessage): void;
+    admitEvent(event: KookWebhookEventData): void;
+    checkAndRememberSn(sn: number): boolean;
+}
+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

@@ -0,0 +1,71 @@
+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;
+    return [
+        http.route('POST', path, async (request, response) => {
+            await handleKookWebhookRequest(request, response, handler);
+        }, { summary: 'KOOK webhook callback', tags: ['kook'] }),
+    ];
+}
+export async function handleKookWebhookRequest(request, response, handler) {
+    try {
+        const rawBody = await readRequestBody(request);
+        let frame;
+        try {
+            frame = parseKookWebhookBody(rawBody, handler.config.encryptKey);
+        }
+        catch (error) {
+            logger.warn(formatCompact({
+                op: 'kook_webhook',
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+            response.writeHead(400, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ message: 'Invalid webhook payload' }));
+            return;
+        }
+        const event = frame.d;
+        if (!event || typeof event !== 'object') {
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ message: 'OK' }));
+            return;
+        }
+        if (isKookWebhookChallenge(event)) {
+            if (!verifyKookWebhookToken(handler.config.verifyToken, event.verify_token)) {
+                response.writeHead(403, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ message: 'Invalid verify_token' }));
+                return;
+            }
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ challenge: event.challenge ?? '' }));
+            return;
+        }
+        if (!verifyKookWebhookToken(handler.config.verifyToken, event.verify_token)) {
+            response.writeHead(403, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ message: 'Invalid verify_token' }));
+            return;
+        }
+        if (frame.sn != null) {
+            if (!handler.checkAndRememberSn(frame.sn)) {
+                response.writeHead(200, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ message: 'OK' }));
+                return;
+            }
+        }
+        if (handler.isOpen) {
+            handleKookWebhookEvent(event, handler);
+        }
+        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' });
+        response.end(JSON.stringify({ message: 'OK' }));
+    }
+}
+function handleKookWebhookEvent(event, handler) {
+    handler.admitEvent(event);
+}

package/lib/ws.d.ts

@@ -0,0 +1,56 @@
+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 {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    removeAllListeners(): void;
+    sendChannelMsg(channelId: string, message: string): Promise<{
+        msg_id?: string | number;
+    }>;
+    sendPrivateMsg(userId: string, message: string): Promise<{
+        msg_id?: string | number;
+    }>;
+    recallMsg?(messageId: string): Promise<boolean>;
+    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 declare function normalizeKookMessage(raw: unknown): KookInboundMessage | null;
+export declare function defaultCreateClient(config: ResolvedKookWebsocketConfig): KookClientTransport;
+export declare function defaultCreateWebhookClient(config: ResolvedKookWebhookConfig): KookClientTransport;

package/lib/ws.js

@@ -0,0 +1,63 @@
+/**
+ * KOOK WebSocket transport: kook-client wrapper and inbound message normalization.
+ */
+import path from 'node:path';
+import { Client } from 'kook-client';
+export function normalizeKookMessage(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const msg = raw;
+    if (msg.message_id == null || msg.author_id == null)
+        return null;
+    const channelKind = msg.message_type === 'channel' ? 'channel' : 'private';
+    const channelId = channelKind === 'channel'
+        ? String(msg.channel_id ?? '')
+        : String(msg.author_id);
+    if (!channelId)
+        return null;
+    const textParts = [];
+    for (const seg of msg.message ?? []) {
+        if (seg.type === 'text' || seg.type === 'markdown') {
+            if (seg.text)
+                textParts.push(seg.text);
+        }
+    }
+    const content = textParts.join('') || msg.raw_message || '';
+    return {
+        id: String(msg.message_id),
+        content,
+        channelKind,
+        channelId,
+        authorId: String(msg.author_id),
+        authorName: msg.author?.info?.nickname
+            || msg.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,
+        timestamp: msg.timestamp ?? Date.now(),
+        guildId: msg.channel?.info?.guild_id,
+        rawMessage: msg.raw_message,
+    };
+}
+export function defaultCreateClient(config) {
+    return new Client({
+        token: config.token,
+        mode: 'websocket',
+        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,
+    });
+}
+export function defaultCreateWebhookClient(config) {
+    return new Client({
+        token: config.token,
+        mode: 'webhook',
+        data_dir: path.join(process.cwd(), 'data', 'kook'),
+        timeout: 10_000,
+        max_retry: 3,
+        ignore: config.ignore,
+        logLevel: config.logLevel,
+    });
+}