@zhin.js/adapter-kook 5.0.1 → 5.0.3

package/lib/index.d.ts

@@ -1,18 +1,6 @@
-import { KookAdapter } from "./adapter.js";
-import { PageManager } from "@zhin.js/host-api";
-declare module "zhin.js" {
-    namespace Plugin {
-        interface Contexts {
-            web: PageManager;
-        }
-    }
-}
-declare module "zhin.js" {
-    interface Adapters {
-        kook: KookAdapter;
-    }
-}
-export * from "./types.js";
-export { KookEndpoint } from "./endpoint.js";
-export { KookAdapter } from "./adapter.js";
-//# sourceMappingURL=index.d.ts.map
+export { formatInboundContent, formatInboundTarget, formatOutboundKmarkdown, parseSendTarget, resolveKookConfig, senderDisplayName, KookPermission, type KookAdapterConfig, type KookInboundMessage, type KookWireSegment, type LogLevel, type ParsedSendTarget, type ResolvedKookConfig, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig, } from './protocol.js';
+export { KookWebhookEndpoint, KookWebsocketEndpoint, type KookEndpointOptions, type KookWebhookEndpointOptions, } from './endpoint.js';
+export { registerKookWebhookRoutes, handleKookWebhookRequest, type KookWebhookHandler, } from './webhook.js';
+export { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, type CreateKookClient, type KookClientTransport, } from './ws.js';
+export { getKookAgentDeps, registerKookAgentEndpoint, setKookAgentDeps, type KookAgentDeps, type KookAgentEndpoint, } from './kook-agent-deps.js';
+export { checkKookPlatformPermit, kookGroupPermitResolver, normalizeKookSenderForPermit, platformPermit, registerKookPlatformPermitChecker, type KookSenderInfo, } from './platform-permit.js';

package/lib/index.js

@@ -1,350 +1,6 @@
-/**
- * KOOK 适配器入口：类型扩展、导出、注册
- */
-import path from "node:path";
-import { usePlugin, createSceneManagementTools } from "zhin.js";
-import { KookAdapter } from "./adapter.js";
-import { kookGroupPermitResolver, platformPermit, registerKookPlatformPermitChecker } from "./platform-permit.js";
-export * from "./types.js";
-export { KookEndpoint } from "./endpoint.js";
-export { KookAdapter } from "./adapter.js";
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-provide({
-    name: "kook",
-    description: "KOOK Adapter",
-    mounted: async (p) => {
-        const adapter = new KookAdapter(p);
-        await adapter.start();
-        return adapter;
-    },
-    dispose: async (adapter) => {
-        await adapter.stop();
-    },
-});
-useContext('tool', 'kook', (toolService, kook) => {
-    const disposers = [];
-    disposers.push(registerKookPlatformPermitChecker());
-    const sceneTools = createSceneManagementTools(kook, 'kook', { permitResolver: kookGroupPermitResolver, registerChecker: false });
-    disposers.push(...sceneTools.map(t => toolService.addTool(t, plugin.name)));
-    disposers.push(toolService.addTool({
-        name: 'kook_grant_role',
-        description: '给用户授予 KOOK 服务器角色',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                guild_id: { type: 'string', description: '服务器 ID' },
-                user_id: { type: 'string', description: '用户 ID' },
-                role_id: { type: 'string', description: '角色 ID' },
-            },
-            required: ['endpoint_id', 'guild_id', 'user_id', 'role_id'],
-        },
-        platforms: ['kook'],
-        tags: ['kook'],
-        permissions: [platformPermit('manage_roles')],
-        execute: async (args) => {
-            const endpoint = kook.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const success = await endpoint.grantRole(args.guild_id, args.user_id, args.role_id);
-            return { success, message: success ? `已授予用户 ${args.user_id} 角色 ${args.role_id}` : '授予角色失败' };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'kook_revoke_role',
-        description: '撤销用户的 KOOK 服务器角色',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                guild_id: { type: 'string', description: '服务器 ID' },
-                user_id: { type: 'string', description: '用户 ID' },
-                role_id: { type: 'string', description: '角色 ID' },
-            },
-            required: ['endpoint_id', 'guild_id', 'user_id', 'role_id'],
-        },
-        platforms: ['kook'],
-        tags: ['kook'],
-        permissions: [platformPermit('manage_roles')],
-        execute: async (args) => {
-            const endpoint = kook.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const success = await endpoint.revokeRole(args.guild_id, args.user_id, args.role_id);
-            return { success, message: success ? `已撤销用户 ${args.user_id} 的角色 ${args.role_id}` : '撤销角色失败' };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'kook_list_roles',
-        description: '获取 KOOK 服务器的角色列表',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                guild_id: { type: 'string', description: '服务器 ID' },
-            },
-            required: ['endpoint_id', 'guild_id'],
-        },
-        platforms: ['kook'],
-        tags: ['kook'],
-        execute: async (args) => {
-            const endpoint = kook.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const roles = await endpoint.getRoleList(args.guild_id);
-            return {
-                roles: roles.map((r) => ({
-                    id: r.role_id,
-                    name: r.name,
-                    color: r.color,
-                    position: r.position,
-                    permissions: r.permissions,
-                })),
-                count: roles.length,
-            };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'kook_create_role',
-        description: '在 KOOK 服务器中创建新角色',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                guild_id: { type: 'string', description: '服务器 ID' },
-                name: { type: 'string', description: '角色名称' },
-            },
-            required: ['endpoint_id', 'guild_id', 'name'],
-        },
-        platforms: ['kook'],
-        tags: ['kook'],
-        permissions: [platformPermit('guild_owner')],
-        execute: async (args) => {
-            const endpoint = kook.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const role = await endpoint.createRole(args.guild_id, args.name);
-            return {
-                success: true,
-                message: `已创建角色 "${args.name}"`,
-                role: { id: role.role_id, name: role.name },
-            };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'kook_delete_role',
-        description: '删除 KOOK 服务器中的角色',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                guild_id: { type: 'string', description: '服务器 ID' },
-                role_id: { type: 'string', description: '角色 ID' },
-            },
-            required: ['endpoint_id', 'guild_id', 'role_id'],
-        },
-        platforms: ['kook'],
-        tags: ['kook'],
-        permissions: [platformPermit('guild_owner')],
-        execute: async (args) => {
-            const endpoint = kook.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            const success = await endpoint.deleteRole(args.guild_id, args.role_id);
-            return { success, message: success ? `已删除角色 ${args.role_id}` : '删除角色失败' };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'kook_blacklist',
-        description: 'KOOK 服务器黑名单管理：添加/移除',
-        parameters: {
-            type: 'object',
-            properties: {
-                endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-                guild_id: { type: 'string', description: '服务器 ID' },
-                action: { type: 'string', description: 'add|remove', enum: ['add', 'remove'] },
-                user_id: { type: 'string', description: '用户 ID' },
-                remark: { type: 'string', description: '备注（add 可选）' },
-            },
-            required: ['endpoint_id', 'guild_id', 'action', 'user_id'],
-        },
-        platforms: ['kook'],
-        tags: ['kook'],
-        permissions: [platformPermit('guild_admin')],
-        execute: async (args) => {
-            const endpoint = kook.endpoints.get(args.endpoint_id);
-            if (!endpoint)
-                throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-            switch (args.action) {
-                case 'add': {
-                    const success = await endpoint.addToBlacklist(args.guild_id, args.user_id, args.remark);
-                    return { success, message: success ? `已将 ${args.user_id} 加入黑名单` : '操作失败' };
-                }
-                case 'remove': {
-                    const success = await endpoint.removeFromBlacklist(args.guild_id, args.user_id);
-                    return { success, message: success ? `已将 ${args.user_id} 从黑名单移除` : '操作失败' };
-                }
-                default:
-                    return { success: false, message: `未知操作: ${args.action}` };
-            }
-        },
-    }, plugin.name));
-    return () => disposers.forEach(d => d());
-});
-// ── Web 控制台 ─────────────────────────────────────────────────────────
-useContext("web", (pageManager) => {
-    pageManager.addEntry({
-        id: "kook",
-        development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-        production: path.resolve(import.meta.dirname, "../dist/index.js"),
-        meta: { name: "KOOK" },
-    });
-});
-useContext("router", "kook", (router, kook) => {
-    router.get("/api/kook/endpoints", async (ctx) => {
-        try {
-            const endpoints = Array.from(kook.endpoints.values());
-            const result = endpoints.map((endpoint) => {
-                try {
-                    return {
-                        name: endpoint.$config.name,
-                        connected: endpoint.$connected || false,
-                        guildCount: endpoint.guilds?.size || 0,
-                        status: endpoint.$connected ? "online" : "offline",
-                    };
-                }
-                catch {
-                    return { name: endpoint.$config.name, connected: false, guildCount: 0, status: "error" };
-                }
-            });
-            ctx.body = { success: true, data: result };
-        }
-        catch {
-            ctx.status = 500;
-            ctx.body = { success: false, error: "获取 Endpoint 数据失败" };
-        }
-    });
-    // Endpoint 连接/断开
-    router.post("/api/kook/endpoints/:name/connect", async (ctx) => {
-        try {
-            const endpoint = kook.endpoints.get(ctx.params.name);
-            if (!endpoint) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Endpoint 不存在" };
-                return;
-            }
-            if (endpoint.$connected) {
-                ctx.body = { success: true, message: "已经在线" };
-                return;
-            }
-            await endpoint.$connect();
-            ctx.body = { success: true, message: "连接成功" };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e instanceof Error ? e.message : "连接失败" };
-        }
-    });
-    router.post("/api/kook/endpoints/:name/disconnect", async (ctx) => {
-        try {
-            const endpoint = kook.endpoints.get(ctx.params.name);
-            if (!endpoint) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Endpoint 不存在" };
-                return;
-            }
-            if (!endpoint.$connected) {
-                ctx.body = { success: true, message: "已经离线" };
-                return;
-            }
-            await endpoint.$disconnect();
-            ctx.body = { success: true, message: "已断开" };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e instanceof Error ? e.message : "断开失败" };
-        }
-    });
-    // 角色列表
-    router.get("/api/kook/endpoints/:name/guilds/:guildId/roles", async (ctx) => {
-        try {
-            const endpoint = kook.endpoints.get(ctx.params.name);
-            if (!endpoint) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Endpoint 不存在" };
-                return;
-            }
-            if (!endpoint.$connected) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "Endpoint 未连接" };
-                return;
-            }
-            const roles = await endpoint.getRoleList(ctx.params.guildId);
-            ctx.body = {
-                success: true,
-                data: roles.map((r) => ({
-                    id: r.role_id,
-                    name: r.name,
-                    color: r.color,
-                    position: r.position,
-                })),
-            };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e instanceof Error ? e.message : "获取角色列表失败" };
-        }
-    });
-    // 创建角色
-    router.post("/api/kook/endpoints/:name/guilds/:guildId/roles", async (ctx) => {
-        try {
-            const endpoint = kook.endpoints.get(ctx.params.name);
-            if (!endpoint) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Endpoint 不存在" };
-                return;
-            }
-            if (!endpoint.$connected) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "Endpoint 未连接" };
-                return;
-            }
-            const { name } = ctx.request.body || {};
-            if (!name) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "缺少角色名称" };
-                return;
-            }
-            const role = await endpoint.createRole(ctx.params.guildId, name);
-            ctx.body = { success: true, data: { id: role.role_id, name: role.name } };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e instanceof Error ? e.message : "创建角色失败" };
-        }
-    });
-    // 删除角色
-    router.delete("/api/kook/endpoints/:name/guilds/:guildId/roles/:roleId", async (ctx) => {
-        try {
-            const endpoint = kook.endpoints.get(ctx.params.name);
-            if (!endpoint) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Endpoint 不存在" };
-                return;
-            }
-            if (!endpoint.$connected) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "Endpoint 未连接" };
-                return;
-            }
-            const success = await endpoint.deleteRole(ctx.params.guildId, ctx.params.roleId);
-            ctx.body = { success, message: success ? "角色已删除" : "删除失败" };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e instanceof Error ? e.message : "删除角色失败" };
-        }
-    });
-});
-//# sourceMappingURL=index.js.map
+export { formatInboundContent, formatInboundTarget, formatOutboundKmarkdown, parseSendTarget, resolveKookConfig, senderDisplayName, KookPermission, } from './protocol.js';
+export { KookWebhookEndpoint, KookWebsocketEndpoint, } from './endpoint.js';
+export { registerKookWebhookRoutes, handleKookWebhookRequest, } from './webhook.js';
+export { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';
+export { getKookAgentDeps, registerKookAgentEndpoint, setKookAgentDeps, } from './kook-agent-deps.js';
+export { checkKookPlatformPermit, kookGroupPermitResolver, normalizeKookSenderForPermit, platformPermit, registerKookPlatformPermitChecker, } from './platform-permit.js';

package/lib/kook-agent-deps.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Agent tool deps for kook.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+export interface KookAgentEndpoint {
+    getRoleList(guildId: string): Promise<Array<{
+        role_id: string | number;
+        name: string;
+        color?: number;
+        position?: number;
+        permissions?: unknown;
+    }>>;
+    createRole(guildId: string, name: string): Promise<{
+        role_id: string | number;
+        name: string;
+    }>;
+    deleteRole(guildId: string, roleId: string): Promise<boolean>;
+    grantRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
+    revokeRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
+    addToBlacklist(guildId: string, userId: string, remark?: string): Promise<boolean>;
+    removeFromBlacklist(guildId: string, userId: string): Promise<boolean>;
+}
+export interface KookAgentDeps {
+    getEndpoint: (endpointId: string) => KookAgentEndpoint;
+}
+export declare function registerKookAgentEndpoint(endpointId: string, endpoint: KookAgentEndpoint): () => void;
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export declare function setKookAgentDeps(deps: KookAgentDeps | null): void;
+export declare function getKookAgentDeps(): KookAgentDeps;

package/lib/kook-agent-deps.js

@@ -0,0 +1,30 @@
+/**
+ * Agent tool deps for kook.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+const endpoints = new Map();
+let override = null;
+export function registerKookAgentEndpoint(endpointId, endpoint) {
+    endpoints.set(endpointId, endpoint);
+    return () => {
+        if (endpoints.get(endpointId) === endpoint) {
+            endpoints.delete(endpointId);
+        }
+    };
+}
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setKookAgentDeps(deps) {
+    override = deps;
+}
+export function getKookAgentDeps() {
+    if (override)
+        return override;
+    return {
+        getEndpoint(endpointId) {
+            const registered = endpoints.get(endpointId);
+            if (!registered)
+                throw new Error(`Endpoint ${endpointId} 不存在`);
+            return registered;
+        },
+    };
+}

package/lib/platform-permit.d.ts

@@ -1,14 +1,23 @@
 /**
  * KOOK platform permit — guild / channel 差异化门禁
  */
-import type { Message } from 'zhin.js';
-import type { KookSenderInfo } from './types.js';
+import { type Message } from '@zhin.js/core';
+import { KookPermission } from './protocol.js';
 export declare function platformPermit(perm: string): string;
 export declare function kookGroupPermitResolver(logicalPerm: string): string;
+export interface KookSenderInfo {
+    id: string;
+    name: string;
+    permission?: KookPermission;
+    roles?: number[];
+    isGuildOwner?: boolean;
+    isAdmin?: boolean;
+    role?: string;
+    permissions?: string[];
+}
 export declare function normalizeKookSenderForPermit(info: KookSenderInfo, isChannel: boolean): {
     role?: string;
     permissions?: string[];
 };
 export declare function checkKookPlatformPermit(perm: string, message: Message<any>): boolean;
 export declare function registerKookPlatformPermitChecker(): () => void;
-//# sourceMappingURL=platform-permit.d.ts.map

package/lib/platform-permit.js

@@ -1,5 +1,8 @@
-import { registerPlatformPermitChecker } from 'zhin.js';
-import { KookPermission } from './types.js';
+/**
+ * KOOK platform permit — guild / channel 差异化门禁
+ */
+import { registerPlatformPermitChecker } from '@zhin.js/core';
+import { KookPermission } from './protocol.js';
 const ADAPTER = 'kook';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -60,4 +63,3 @@ export function checkKookPlatformPermit(perm, message) {
 export function registerKookPlatformPermitChecker() {
     return registerPlatformPermitChecker(ADAPTER, checkKookPlatformPermit);
 }
-//# sourceMappingURL=platform-permit.js.map

package/lib/protocol.d.ts

@@ -0,0 +1,147 @@
+/**
+ * KOOK protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import type { IncomingMessage } from 'node:http';
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'mark' | 'off';
+export declare enum KookPermission {
+    Normal = 1,
+    Admin = 2,
+    Owner = 4,
+    ChannelAdmin = 5
+}
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface KookAdapterConfig {
+    readonly name?: string;
+    readonly token?: string;
+    /** Default `websocket`. `webhook` requires httpHostToken + verify_token. */
+    readonly connection?: 'websocket' | 'webhook';
+    readonly webhookPath?: string;
+    readonly verify_token?: string;
+    readonly encrypt_key?: string;
+    readonly data_dir?: string;
+    readonly timeout?: number;
+    readonly max_retry?: number;
+    readonly ignore?: 'bot' | 'self';
+    readonly logLevel?: LogLevel;
+    /** Transitional: legacy root `endpoints[]` with `context: kook`. */
+    readonly endpoints?: ReadonlyArray<{
+        readonly context?: string;
+        readonly name?: string;
+        readonly token?: string;
+        readonly connection?: 'websocket' | 'webhook';
+        readonly webhookPath?: string;
+        readonly verify_token?: string;
+        readonly encrypt_key?: string;
+        readonly data_dir?: string;
+        readonly timeout?: number;
+        readonly max_retry?: number;
+        readonly ignore?: 'bot' | 'self';
+        readonly logLevel?: LogLevel;
+    }>;
+}
+export interface ResolvedKookWebsocketConfig {
+    readonly context: 'kook';
+    readonly connection: 'websocket';
+    readonly name: string;
+    readonly token: string;
+    readonly data_dir?: string;
+    readonly timeout: number;
+    readonly max_retry: number;
+    readonly ignore: 'bot' | 'self';
+    readonly logLevel: LogLevel;
+}
+export interface ResolvedKookWebhookConfig {
+    readonly context: 'kook';
+    readonly connection: 'webhook';
+    readonly name: string;
+    readonly token: string;
+    readonly webhookPath: string;
+    readonly verifyToken: string;
+    readonly encryptKey?: string;
+    readonly ignore: 'bot' | 'self';
+    readonly logLevel: LogLevel;
+}
+export interface KookWebhookEventData {
+    readonly channel_type?: string;
+    readonly type?: number;
+    readonly target_id?: string;
+    readonly author_id?: string;
+    readonly content?: string;
+    readonly msg_id?: string;
+    readonly msg_timestamp?: number;
+    readonly verify_token?: string;
+    readonly challenge?: string;
+    readonly extra?: {
+        readonly guild_id?: string;
+        readonly author?: {
+            readonly id?: string;
+            readonly username?: string;
+            readonly bot?: boolean;
+            readonly roles?: number[];
+        };
+    };
+}
+export interface KookWebhookFrame {
+    readonly s?: number;
+    readonly sn?: number;
+    readonly d?: KookWebhookEventData;
+    readonly encrypt?: string;
+}
+export type ResolvedKookConfig = ResolvedKookWebsocketConfig | ResolvedKookWebhookConfig;
+export interface KookInboundMessage {
+    readonly id: string;
+    readonly content: string;
+    readonly channelKind: 'private' | 'channel';
+    readonly channelId: string;
+    readonly authorId: string;
+    readonly authorName: string;
+    readonly authorBot?: boolean;
+    readonly authorRoles?: number[];
+    readonly timestamp: number;
+    readonly guildId?: string;
+    readonly rawMessage?: string;
+}
+export interface KookWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface ParsedSendTarget {
+    readonly kind: 'private' | 'channel';
+    readonly id: string;
+}
+export declare function resolveKookConfig(config?: KookAdapterConfig): ResolvedKookConfig;
+/**
+ * Gateway reply target：`private:uid` / `channel:cid`，便于 send() 还原 API。
+ */
+export declare function formatInboundTarget(msg: KookInboundMessage): string;
+export declare function parseSendTarget(target: string): ParsedSendTarget;
+export declare function senderDisplayName(msg: KookInboundMessage): string;
+/** Build inbound text for MessageGateway.receive */
+export declare function formatInboundContent(msg: KookInboundMessage): string;
+/**
+ * KOOK @ 用户标记为 `(met)<userId>(met)`；content 含 `(met)<botId>(met)` 时视为 @ 机器人。
+ * botId 取 client 缓存的 self_id（/me 类接口），拿不到则不标注。
+ */
+export declare function isKookBotMentioned(msg: KookInboundMessage, selfId?: string): boolean;
+/**
+ * Wire-encode an already-rendered outbound payload into KOOK KMarkdown.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare function formatOutboundKmarkdown(payload: unknown): string;
+export declare function normalizeWebhookPath(path: string): string;
+export declare function readTextBody(request: IncomingMessage, options?: {
+    readonly limit?: number;
+}): Promise<string>;
+export declare function readRequestBody(request: IncomingMessage, options?: {
+    readonly limit?: number;
+}): Promise<Buffer>;
+export declare function padKookEncryptKey(key: string): Buffer;
+export declare function decryptKookWebhookPayload(encrypted: string, encryptKey: string): Buffer;
+export declare function parseKookWebhookBody(rawBody: Buffer, encryptKey?: string): KookWebhookFrame;
+export declare function isKookWebhookChallenge(event: KookWebhookEventData): boolean;
+export declare function verifyKookWebhookToken(expected: string, actual?: string): boolean;
+export declare function normalizeKookWebhookEvent(event: KookWebhookEventData, options?: {
+    readonly ignore?: 'bot' | 'self';
+    readonly selfId?: string;
+}): KookInboundMessage | null;