@zhin.js/adapter-napcat 1.0.0 → 1.1.0

package/lib/http-endpoint.js

@@ -0,0 +1,177 @@
+import { Endpoint } from 'zhin.js/adapter';
+import { createRecallEndpointControl, } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { createNapCatEndpointManagement } from './endpoint-management.js';
+import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
+import { buildSendAction, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
+import { receiveNapCatSideEvent } from './side-event-dispatch.js';
+import { createNapCatContentPort } from './onebot-get-msg.js';
+import { NapcatClient } from './client.js';
+import { readRequestBody } from './webhook.js';
+import { verifyNapCatAccessToken } from './wss-auth.js';
+export class NapCatHttpEndpoint extends Endpoint {
+    client = new NapcatClient((action, params) => this.#callApi(action, params));
+    #logger;
+    #options;
+    #inboundDeduper = new InboundMessageDeduper();
+    management = createNapCatEndpointManagement(this.client);
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    content = createNapCatContentPort((action, params) => this.client.callApi(action, params));
+    #callHttpAction;
+    #routeReleases = [];
+    #open = false;
+    #started = false;
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('napcat', options.config.id);
+        this.#options = options;
+        this.#callHttpAction = options.callHttpAction ?? callNapCatHttpAction;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#setupRoutes();
+        this.#logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.id,
+            mode: 'http',
+            path: this.#options.config.post_path,
+        }));
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#inboundDeduper.clear();
+        this.#started = false;
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    }
+    async send({ conversation, payload }) {
+        const message = formatOutboundSegments(payload);
+        const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
+        const resp = await this.#callHttpAction({
+            http_url: this.#options.config.http_url,
+            access_token: this.#options.config.access_token,
+        }, action, params);
+        const data = resp.data;
+        const messageId = data?.message_id != null ? String(data.message_id) : '';
+        this.#logger.debug(formatCompact({
+            op: 'napcat_send',
+            endpoint: this.#options.config.id,
+            target: `${conversation.kind}:${conversation.id}`,
+            messageId,
+        }));
+        return messageId;
+    }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await this.client.callApi('delete_msg', { message_id: Number(messageId) });
+    }
+    #callApi(action, params = {}) {
+        return this.#callHttpAction({
+            http_url: this.#options.config.http_url,
+            access_token: this.#options.config.access_token,
+        }, action, params).then((resp) => resp.data);
+    }
+    admit(ev) {
+        if (!this.#open)
+            return;
+        void this.emitPlatform(napCatPlatformEventName(ev), ev).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'napcat_platform_event_failed',
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        if (!isMessageEvent(ev)) {
+            receiveNapCatSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, this.client, ev, this.#logger);
+            return;
+        }
+        if (isSelfMessage(ev))
+            return;
+        const msgId = String(ev.message_id);
+        if (!this.#inboundDeduper.shouldProcess(msgId))
+            return;
+        if (Array.isArray(ev.message) || typeof ev.message === 'string') {
+            ev = { ...ev, message: normalizeMessage(ev.message) };
+        }
+        const conversation = napcatInboundConversation(String(this.#options.id), ev);
+        const nickname = senderNickname(ev);
+        const mentioned = isNapCatBotMentioned(ev);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: msgId },
+            content: formatInboundContent(ev),
+            sender: {
+                id: senderUserId(ev),
+                name: nickname,
+                ...(ev.sender?.role ? { roles: [ev.sender.role] } : {}),
+            },
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                message_type: ev.message_type,
+                user_id: ev.user_id != null ? String(ev.user_id) : undefined,
+                group_id: ev.group_id != null ? String(ev.group_id) : undefined,
+                time: ev.time,
+                self_id: ev.self_id != null ? String(ev.self_id) : undefined,
+                role: ev.sender?.role,
+                ...(nickname ? { nickname } : {}),
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'napcat_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #setupRoutes() {
+        const path = this.#options.config.post_path;
+        this.#routeReleases.push(this.#options.http.route('POST', path, async (request, response) => {
+            await this.#handlePost(request, response);
+        }, { summary: 'NapCat HTTP event callback', tags: ['napcat'] }));
+    }
+    async #handlePost(request, response) {
+        try {
+            if (!verifyNapCatAccessToken(this.#options.config.access_token, request)) {
+                response.writeHead(403, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ message: 'Unauthorized' }));
+                return;
+            }
+            const raw = await readRequestBody(request);
+            let ev;
+            try {
+                ev = JSON.parse(raw);
+            }
+            catch {
+                response.writeHead(400, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ message: 'Invalid JSON' }));
+                return;
+            }
+            if (this.#open)
+                this.admit(ev);
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ status: 'ok' }));
+        }
+        catch (error) {
+            this.#logger.error('NapCat HTTP webhook error:', error);
+            if (!response.headersSent) {
+                response.writeHead(500, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ message: 'Internal Server Error' }));
+            }
+        }
+    }
+}
+function napCatPlatformEventName(ev) {
+    return [ev.post_type, ev.message_type ?? ev.notice_type ?? ev.request_type, ev.sub_type]
+        .filter(Boolean)
+        .join('.');
+}

package/lib/index.d.ts

@@ -1,22 +1,11 @@
-import type { Router } from '@zhin.js/host-router';
-import { PageManager } from '@zhin.js/host-api';
-import { NapCatAdapter } from './adapter.js';
-export * from './types.js';
-export { NapCatWsClient } from './bot-ws-client.js';
-export { NapCatWsServer } from './bot-ws-server.js';
-export { NapCatHttpBot } from './bot-http.js';
-export { NapCatAdapter, type NapCatBot } from './adapter.js';
-export { NapCatBotBase } from './bot-base.js';
-export { NapCatTypingIndicatorManager, enableTypingIndicator, type NapCatTypingIndicatorConfig, } from './typing-indicator.js';
-declare module 'zhin.js' {
-    namespace Plugin {
-        interface Contexts {
-            web: PageManager;
-            router: Router;
-        }
-    }
-    interface Adapters {
-        napcat: NapCatAdapter;
-    }
-}
-//# sourceMappingURL=index.d.ts.map
+export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, getChannelId, isMessageEvent, mediaRefToOneBotFile, napcatInboundConversation, napcatOutboundTarget, resolveNapCatConfig, senderNickname, senderUserId, type MessageSegment, type NapCatActionRequest, type NapCatActionResponse, type NapCatAdapterConfig, type NapCatConfigBase, type NapCatEndpointConfig, type NapCatEvent, type NapCatHttpConfig, type NapCatMessageEvent, type NapCatSender, type NapCatWireSegment, type NapCatWsConfig, type NapCatWssConfig, type ParsedSendTarget, type ResolvedNapCatConfig, } from './protocol.js';
+export { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
+export { napcatClient, type NapcatClient, type NapcatClientEventMap, } from './client.js';
+export { parseOneBotGetMsgResponse } from './onebot-get-msg.js';
+export { NapCatWsEndpoint, type NapCatWsEndpointOptions, } from './ws-endpoint.js';
+export { NapCatWssEndpoint, type NapCatWssEndpointOptions, } from './wss-endpoint.js';
+export { NapCatHttpEndpoint, type NapCatHttpEndpointOptions, } from './http-endpoint.js';
+export type { NapCatWsSocket, NapCatWsCreateOptions } from './ws-types.js';
+export { callNapCatWsAction, decodeWsPayload, handleNapCatWsMessage, rejectAllPending, startNapCatHeartbeat, } from './ws-transport.js';
+export { verifyNapCatAccessToken } from './wss-auth.js';
+export { readRequestBody } from './webhook.js';

package/lib/index.js

@@ -1,58 +1,10 @@
-/**
- * NapCat 适配器入口
- * 支持 OneBot11 标准 + go-cqhttp 扩展 + NapCat 独有 API
- * 连接方式：正向 WS / 反向 WS / HTTP
- */
-import path from 'path';
-import { usePlugin, createGroupManagementTools, registerAgentPromptContributor, unregisterAgentPromptContributor, } from 'zhin.js';
-import { NapCatAdapter } from './adapter.js';
-import { createNapCatTools } from './tools.js';
-import { createNapCatAgentPromptContributor } from './agent-prompt.js';
-import { registerRoutes } from './routes.js';
-export * from './types.js';
-export { NapCatWsClient } from './bot-ws-client.js';
-export { NapCatWsServer } from './bot-ws-server.js';
-export { NapCatHttpBot } from './bot-http.js';
-export { NapCatAdapter } from './adapter.js';
-export { NapCatBotBase } from './bot-base.js';
-export { NapCatTypingIndicatorManager, enableTypingIndicator, } from './typing-indicator.js';
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-// ── 适配器注册 ─────────────────────────────────────────────────────
-provide({
-    name: 'napcat',
-    description: 'NapCatQQ 适配器（OneBot11 + go-cqhttp + NapCat 扩展，正向/反向 WS + HTTP）',
-    mounted: async (p) => {
-        registerAgentPromptContributor(createNapCatAgentPromptContributor());
-        const adapter = new NapCatAdapter(p);
-        await adapter.start();
-        return adapter;
-    },
-    dispose: async (adapter) => {
-        unregisterAgentPromptContributor('napcat');
-        await adapter.stop();
-    },
-});
-// ── AI 工具注册 ────────────────────────────────────────────────────
-useContext('tool', 'napcat', (toolService, napcat) => {
-    const disposers = [];
-    const groupTools = createGroupManagementTools(napcat, 'napcat');
-    disposers.push(...groupTools.map(t => toolService.addTool(t, plugin.name)));
-    const napcatTools = createNapCatTools(napcat);
-    disposers.push(...napcatTools.map(t => toolService.addTool(t, plugin.name)));
-    return () => disposers.forEach(d => d());
-});
-// ── Web 控制台入口 ─────────────────────────────────────────────────
-useContext('web', (pageManager) => {
-    pageManager.addEntry({
-        id: 'napcat',
-        development: path.resolve(import.meta.dirname, '../client/index.tsx'),
-        production: path.resolve(import.meta.dirname, '../dist/index.js'),
-        meta: { name: 'NapCat' },
-    });
-});
-// ── HTTP 路由 ──────────────────────────────────────────────────────
-useContext('router', 'napcat', async (router, napcat) => {
-    registerRoutes(router, napcat);
-});
-//# sourceMappingURL=index.js.map
+export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, getChannelId, isMessageEvent, mediaRefToOneBotFile, napcatInboundConversation, napcatOutboundTarget, resolveNapCatConfig, senderNickname, senderUserId, } from './protocol.js';
+export { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
+export { napcatClient, } from './client.js';
+export { parseOneBotGetMsgResponse } from './onebot-get-msg.js';
+export { NapCatWsEndpoint, } from './ws-endpoint.js';
+export { NapCatWssEndpoint, } from './wss-endpoint.js';
+export { NapCatHttpEndpoint, } from './http-endpoint.js';
+export { callNapCatWsAction, decodeWsPayload, handleNapCatWsMessage, rejectAllPending, startNapCatHeartbeat, } from './ws-transport.js';
+export { verifyNapCatAccessToken } from './wss-auth.js';
+export { readRequestBody } from './webhook.js';

package/lib/napcat-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const napcatEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;

package/lib/napcat-endpoint-commands.js

@@ -0,0 +1,28 @@
+/**
+ * `napcat.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { napcatRuntimeStateToken } from './napcat-runtime-state.js';
+export const napcatEndpointCommands = createEndpointCommands({
+    adapterKey: 'napcat',
+    adapterDisplayName: 'NapCat',
+    fields: [
+        { key: 'url', description: 'NapCat WebSocket URL（connection: ws 必填）' },
+        { key: 'path', description: 'reverse-wss 路径（connection: wss）' },
+        { key: 'http_url', description: 'HTTP API base URL（connection: http 出站）' },
+        { key: 'post_path', description: 'HTTP POST 事件路径（connection: http 入站）' },
+        { key: 'access_token', env: true, description: 'NapCat access token' },
+    ],
+    running: (use) => use(napcatRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => {
+        if (entry.url)
+            return `url: ${String(entry.url)}`;
+        if (entry.path)
+            return `path: ${String(entry.path)}`;
+        if (entry.http_url)
+            return `http_url: ${String(entry.http_url)}`;
+        return '';
+    },
+}, defineCommand);

package/lib/napcat-inbound.d.ts

@@ -1,21 +1,28 @@
 /**
  * NapCat 入站消息治理：去重、自发过滤、消息归一化
  */
-import type { NapCatMessageEvent, MessageSegment } from './types.js';
+import type { NapCatMessageEvent, MessageSegment } from './protocol.js';
 export declare class InboundMessageDeduper {
     private readonly seen;
     shouldProcess(messageId: string): boolean;
     clear(): void;
 }
 /** 判断是否为 bot 自身发出的消息 */
-export declare function isSelfMessage(event: NapCatMessageEvent): boolean;
+export declare function isSelfMessage(event: NapCatMessageEvent | {
+    post_type?: string;
+    self_id?: number | string;
+    user_id?: number | string;
+}): boolean;
 /**
  * 将 message 字段归一化为 MessageSegment[]。
  * NapCat 通常返回数组，但某些配置下可能返回 CQ 字符串。
  */
 export declare function normalizeMessage(message: MessageSegment[] | string): MessageSegment[];
 /**
- * 生成用于 notice / request 事件的去重 key
+ * OneBot11 mentioned 判定：消息段 {type:'at', data:{qq}} 的 qq 等于本机 uin
+ * （事件 self_id）时为 true；`qq === 'all'` 不算。兼容 CQ 字符串形式。
  */
-export declare function resolveSideEventDedupeKey(event: any, prefix: string): string;
-//# sourceMappingURL=napcat-inbound.d.ts.map
+export declare function isNapCatBotMentioned(ev: {
+    self_id?: number | string;
+    message?: MessageSegment[] | string;
+}): boolean;

package/lib/napcat-inbound.js

@@ -37,19 +37,34 @@ export function normalizeMessage(message) {
     }
     return [];
 }
+const CQ_AT_RE = /\[CQ:at,qq=([^\],\s]+)\]/g;
+function atTargetMatchesUin(target, uin) {
+    const qq = String(target ?? '').trim();
+    return Boolean(qq) && qq !== 'all' && Number(qq) === Number(uin);
+}
 /**
- * 生成用于 notice / request 事件的去重 key
+ * OneBot11 mentioned 判定：消息段 {type:'at', data:{qq}} 的 qq 等于本机 uin
+ * （事件 self_id）时为 true；`qq === 'all'` 不算。兼容 CQ 字符串形式。
  */
-export function resolveSideEventDedupeKey(event, prefix) {
-    const parts = [prefix, event.time, event.notice_type || event.request_type];
-    if (event.group_id)
-        parts.push(event.group_id);
-    if (event.user_id)
-        parts.push(event.user_id);
-    if (event.message_id)
-        parts.push(event.message_id);
-    if (event.flag)
-        parts.push(event.flag);
-    return parts.join(':');
+export function isNapCatBotMentioned(ev) {
+    if (ev.self_id == null)
+        return false;
+    const uin = String(ev.self_id).trim();
+    if (!uin)
+        return false;
+    const segments = normalizeMessage(ev.message ?? []);
+    for (const seg of segments) {
+        if (seg.type === 'at' && atTargetMatchesUin(seg.data?.qq, uin))
+            return true;
+    }
+    const text = segments
+        .map((seg) => (seg.type === 'text' ? String(seg.data?.text ?? '') : ''))
+        .join('');
+    if (!text)
+        return false;
+    for (const match of text.matchAll(CQ_AT_RE)) {
+        if (atTargetMatchesUin(match[1], uin))
+            return true;
+    }
+    return false;
 }
-//# sourceMappingURL=napcat-inbound.js.map

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

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

package/lib/napcat-runtime-state.js

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

package/lib/onebot-get-msg.d.ts

@@ -1,3 +1,16 @@
-import type { QuotedMessagePayload } from 'zhin.js';
-export declare function parseOneBotGetMsgResponse(messageId: string, data: unknown): QuotedMessagePayload;
-//# sourceMappingURL=onebot-get-msg.d.ts.map
+export interface NapcatMessageLookup {
+    messageId: string;
+    sender?: {
+        id: string;
+        name: string;
+    };
+    content: Array<{
+        type: string;
+        data?: Record<string, unknown>;
+    }>;
+    raw?: string;
+    time?: number;
+}
+export declare function parseOneBotGetMsgResponse(messageId: string, data: unknown): NapcatMessageLookup;
+export declare function createNapCatContentPort(callApi: (action: string, params?: Record<string, unknown>) => Promise<unknown>): EndpointContentPort;
+import type { EndpointContentPort } from 'zhin.js/adapter';

package/lib/onebot-get-msg.js

@@ -24,4 +24,56 @@ export function parseOneBotGetMsgResponse(messageId, data) {
         time: typeof record.time === 'number' ? record.time : undefined,
     };
 }
-//# sourceMappingURL=onebot-get-msg.js.map
+export function createNapCatContentPort(callApi) {
+    return Object.freeze({
+        async resolve(reference, context) {
+            try {
+                context.signal.throwIfAborted();
+                if (reference.kind === 'media') {
+                    return reference.media.kind === 'file'
+                        ? Object.freeze({ status: 'unsupported', code: 'napcat_opaque_media_requires_platform_file_metadata' })
+                        : Object.freeze({ status: 'resolved', reference, value: reference.media });
+                }
+                if (reference.kind === 'message') {
+                    const parsed = parseOneBotGetMsgResponse(reference.message.id, await callApi('get_msg', { message_id: reference.message.id }));
+                    context.signal.throwIfAborted();
+                    const value = Object.freeze({
+                        ref: reference.message,
+                        ...(parsed.sender?.id ? { actor: Object.freeze({ id: parsed.sender.id, ...(parsed.sender.name ? { displayName: parsed.sender.name } : {}) }) } : {}),
+                        segments: canonicalSegments(parsed.content),
+                        timestamp: toMillis(parsed.time),
+                    });
+                    return Object.freeze({ status: 'resolved', reference, value });
+                }
+                const raw = await callApi('get_forward_msg', { message_id: reference.forwardId, id: reference.forwardId });
+                context.signal.throwIfAborted();
+                const nodes = Array.isArray(raw.messages) ? raw.messages.slice(0, context.maxEntries) : [];
+                const value = Object.freeze(nodes.map((node) => {
+                    const row = node;
+                    const sender = row.sender;
+                    return Object.freeze({
+                        ...(sender?.user_id != null ? { actor: Object.freeze({ id: String(sender.user_id), ...(sender.nickname ? { displayName: String(sender.nickname) } : {}) }) } : {}),
+                        segments: canonicalSegments(Array.isArray(row.content) ? row.content : []),
+                        timestamp: toMillis(row.time),
+                    });
+                }));
+                return Object.freeze({ status: 'resolved', reference, value });
+            }
+            catch (error) {
+                if (context.signal.aborted)
+                    return Object.freeze({ status: 'expired', code: 'turn_aborted' });
+                return Object.freeze({ status: 'failed', code: 'napcat_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+            }
+        },
+    });
+}
+function canonicalSegments(content) {
+    return Object.freeze(content.map((segment) => Object.freeze({
+        type: segment.type,
+        data: Object.freeze(segment.data ?? {}),
+    })));
+}
+function toMillis(value) {
+    const time = Number(value);
+    return Number.isFinite(time) ? (time < 10_000_000_000 ? time * 1000 : time) : Date.now();
+}

package/lib/protocol.d.ts

@@ -0,0 +1,165 @@
+/**
+ * NapCat protocol helpers (OneBot 11 + NapCat extensions).
+ * No legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { type MediaRef } from '@zhin.js/core';
+import type { ConversationRef } from '@zhin.js/im-contract';
+/** Transitional legacy endpoint row (`endpoints[]` with `context: napcat`). */
+export interface NapCatLegacyEndpointRow {
+    readonly context?: string;
+    readonly connection?: 'ws' | 'wss' | 'http';
+    readonly id?: string;
+    readonly access_token?: string;
+    readonly url?: string;
+    readonly path?: string;
+    readonly http_url?: string;
+    readonly post_path?: string;
+    readonly reconnect_interval?: number;
+    readonly heartbeat_interval?: number;
+    readonly poll_interval?: number;
+}
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface NapCatAdapterConfig {
+    readonly connection?: 'ws' | 'wss' | 'http';
+    readonly id?: string;
+    readonly access_token?: string;
+    readonly url?: string;
+    readonly path?: string;
+    readonly http_url?: string;
+    readonly post_path?: string;
+    readonly reconnect_interval?: number;
+    readonly heartbeat_interval?: number;
+    readonly poll_interval?: number;
+    /** Transitional: legacy root `endpoints[]` with `context: napcat`. */
+    readonly endpoints?: ReadonlyArray<NapCatLegacyEndpointRow>;
+}
+export interface NapCatConfigBase {
+    readonly context: 'napcat';
+    readonly id: string;
+    readonly access_token?: string;
+}
+/** 正向 WebSocket：应用连 NapCat WS */
+export interface NapCatWsConfig extends NapCatConfigBase {
+    readonly connection: 'ws';
+    readonly url: string;
+    readonly reconnect_interval: number;
+    readonly heartbeat_interval: number;
+}
+/** 反向 WebSocket：httpHostToken WS upgrade 入站/出站 */
+export interface NapCatWssConfig extends NapCatConfigBase {
+    readonly connection: 'wss';
+    readonly path: string;
+    readonly heartbeat_interval: number;
+}
+/** HTTP API + POST 上报：httpHostToken POST 入站 + http_url/{action} 出站 */
+export interface NapCatHttpConfig extends NapCatConfigBase {
+    readonly connection: 'http';
+    readonly http_url: string;
+    readonly post_path: string;
+    readonly poll_interval: number;
+}
+export type ResolvedNapCatConfig = NapCatWsConfig | NapCatWssConfig | NapCatHttpConfig;
+export type NapCatEndpointConfig = ResolvedNapCatConfig;
+export interface NapCatSender {
+    readonly role?: string;
+    readonly nickname?: string;
+    readonly card?: string;
+    readonly title?: string;
+    readonly user_id?: number;
+}
+export interface MessageSegment {
+    type: string;
+    data?: Record<string, unknown>;
+}
+export interface NapCatEvent {
+    post_type: string;
+    self_id?: number | string;
+    message_type?: string;
+    sub_type?: string;
+    message_id?: number | string;
+    user_id?: number | string;
+    group_id?: number | string;
+    sender?: NapCatSender;
+    message?: MessageSegment[] | string;
+    raw_message?: string;
+    time?: number;
+    notice_type?: string;
+    request_type?: string;
+    [key: string]: unknown;
+}
+export type NapCatMessageEvent = NapCatEvent & {
+    post_type: 'message' | 'message_sent';
+    message_id: number | string;
+    user_id: number | string;
+};
+export interface NapCatActionRequest {
+    action: string;
+    params: Record<string, unknown>;
+    echo?: string;
+}
+export interface NapCatActionResponse {
+    status: string;
+    retcode: number;
+    data?: unknown;
+    echo?: string;
+    message?: string;
+    wording?: string;
+}
+export interface NapCatWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface ParsedSendTarget {
+    readonly message_type: 'private' | 'group';
+    readonly id: string;
+}
+export declare function resolveNapCatConfig(config?: NapCatAdapterConfig): ResolvedNapCatConfig;
+export declare function isMessageEvent(ev: NapCatEvent): ev is NapCatMessageEvent;
+export declare function getChannelId(ev: NapCatEvent): string;
+/**
+ * 入站归一化 → ConversationRef：群消息 → kind 'group'；私聊临时会话
+ * （sub_type 'group'）→ kind 'private' + 群容器进 `parent`；其余私聊 → 'private'。
+ */
+export declare function napcatInboundConversation(endpointKey: string, ev: NapCatEvent): ConversationRef;
+/** 出站：ConversationRef → OneBot 私聊/群聊目标。 */
+export declare function napcatOutboundTarget(conversation: ConversationRef): ParsedSendTarget;
+export declare function formatInboundContent(ev: NapCatEvent): string;
+/**
+ * 入站 sender 语义：必须是用户 ID（Runtime Message contract）。
+ * 显示名走 metadata.nickname，见 senderNickname。
+ */
+export declare function senderUserId(ev: NapCatEvent): string;
+/** 显示名（群名片 card 优先于 nickname），没有则 undefined。 */
+export declare function senderNickname(ev: NapCatEvent): string | undefined;
+/**
+ * canonical MediaRef → OneBot `file` 参数：url 直传、base64 → `base64://`、
+ * 本地路径 → `file://`（路径在 OneBot 实现侧解析）、kind=file 不透明引用原样透传。
+ */
+export declare function mediaRefToOneBotFile(media: MediaRef): string;
+/**
+ * Wire-encode an already-rendered outbound payload into OneBot message segments.
+ * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
+ * 媒体段（image/audio/video）仅认 canonical `data.media`，缺失则 warn + 丢弃；
+ * 非媒体的 wire 段（at 等）原样透传。
+ */
+export declare function formatOutboundSegments(payload: unknown): MessageSegment[];
+export declare function buildSendAction(target: ParsedSendTarget, message: MessageSegment[]): {
+    action: string;
+    params: Record<string, unknown>;
+};
+/** Build WS connect URL + headers (access_token via Bearer + query). */
+export declare function buildWsConnectOptions(config: NapCatWsConfig): {
+    readonly url: string;
+    readonly headers: Record<string, string>;
+    readonly safeUrl: string;
+};
+export interface NapCatHttpOptions {
+    readonly http_url: string;
+    readonly access_token?: string;
+}
+/**
+ * 向 NapCat HTTP API 发送动作请求：POST {http_url}/{action}。
+ * 供 connection:http 出站与纯协议测试使用。
+ */
+export declare function callNapCatHttpAction(options: NapCatHttpOptions, action: string, params?: Record<string, unknown>): Promise<NapCatActionResponse>;