@zhin.js/adapter-napcat 3.0.2 → 5.0.0

package/agent/tools/set_online_status.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getEndpoint } from '../../src/napcat-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; status: number; ext_status?: number }>({
+export default defineAgentTool<{ endpoint_id: string; status: number; ext_status?: number }>({
   description: '设置在线状态（在线、隐身、忙碌等）。',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/set_profile.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getEndpoint } from '../../src/napcat-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; nickname: string; company?: string; email?: string; college?: string; personal_note?: string }>({
+export default defineAgentTool<{ endpoint_id: string; nickname: string; company?: string; email?: string; college?: string; personal_note?: string }>({
   description: '修改 QQ 资料（昵称等）。',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/set_signature.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getEndpoint } from '../../src/napcat-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; signature: string }>({
+export default defineAgentTool<{ endpoint_id: string; signature: string }>({
   description: '设置个人签名（个性签名）。',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/set_title.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getEndpoint } from '../../src/napcat-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; group_id: number; user_id: number; title: string }>({
+export default defineAgentTool<{ endpoint_id: string; group_id: number; user_id: number; title: string }>({
   description: '设置群成员专属头衔。需要群主权限。',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/translate.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getEndpoint } from '../../src/napcat-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; text: string }>({
+export default defineAgentTool<{ endpoint_id: string; text: string }>({
   description: '英译中翻译。',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/agent/tools/upload_group_file.ts

@@ -1,8 +1,8 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { getEndpoint } from '../../src/napcat-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; group_id: number; file: string; name: string; folder?: string }>({
+export default defineAgentTool<{ endpoint_id: string; group_id: number; file: string; name: string; folder?: string }>({
   description: '上传文件到群。file 为本地路径或 URL。',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),

package/lib/http-endpoint.d.ts

@@ -0,0 +1,26 @@
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { callNapCatHttpAction, type NapCatEvent, type NapCatHttpConfig } from './protocol.js';
+export interface NapCatHttpEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly config: NapCatHttpConfig;
+    readonly callHttpAction?: typeof callNapCatHttpAction;
+}
+export declare class NapCatHttpEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: NapCatHttpEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+    admit(ev: NapCatEvent): void;
+}

package/lib/http-endpoint.js

@@ -0,0 +1,147 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { registerNapcatAgentEndpoint } from './napcat-agent-deps.js';
+import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
+import { buildSendAction, callNapCatHttpAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
+import { readRequestBody } from './webhook.js';
+import { verifyNapCatAccessToken } from './wss-auth.js';
+const logger = getLogger('napcat');
+export class NapCatHttpEndpoint {
+    #options;
+    #inboundDeduper = new InboundMessageDeduper();
+    #callHttpAction;
+    #routeReleases = [];
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+        this.#callHttpAction = options.callHttpAction ?? callNapCatHttpAction;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#unregisterAgent = registerNapcatAgentEndpoint(this.#options.config.name, this);
+        this.#setupRoutes();
+        logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.name,
+            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.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        this.#inboundDeduper.clear();
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const message = formatOutboundSegments(payload);
+        const { action, params } = buildSendAction(target, 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) : '';
+        logger.debug(formatCompact({
+            op: 'napcat_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId,
+        }));
+        return 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 || !isMessageEvent(ev))
+            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 target = formatInboundTarget(ev);
+        const nickname = senderNickname(ev);
+        const mentioned = isNapCatBotMentioned(ev);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content: formatInboundContent(ev),
+            sender: senderUserId(ev),
+            id: msgId,
+            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,
+                endpoint: this.#options.config.name,
+                time: ev.time,
+                self_id: ev.self_id != null ? String(ev.self_id) : undefined,
+                role: ev.sender?.role,
+                ...(nickname ? { nickname } : {}),
+                ...(mentioned ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'napcat_gateway_receive_failed',
+                target,
+                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) {
+            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' }));
+            }
+        }
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,11 @@
+export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isMessageEvent, parseSendTarget, 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 { getEndpoint, getNapcatAgentDeps, registerNapcatAgentEndpoint, setNapcatAgentDeps, type NapcatAgentDeps, type NapcatAgentEndpoint, } from './napcat-agent-deps.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

@@ -0,0 +1,10 @@
+export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isMessageEvent, parseSendTarget, resolveNapCatConfig, senderNickname, senderUserId, } from './protocol.js';
+export { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
+export { getEndpoint, getNapcatAgentDeps, registerNapcatAgentEndpoint, setNapcatAgentDeps, } from './napcat-agent-deps.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-agent-deps.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Agent tool deps for napcat.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+export interface NapcatAgentEndpoint {
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+    setTitle(groupId: number, userId: number, title: string, duration?: number): Promise<boolean>;
+    sendLike(userId: number, times?: number): Promise<unknown>;
+    deleteFriend(userId: number): Promise<unknown>;
+    markMsgAsRead(messageId: number): Promise<unknown>;
+    ocrImage(image: string): Promise<unknown>;
+    setQQProfile(nickname: string, company?: string, email?: string, college?: string, personalNote?: string): Promise<unknown>;
+    setGroupPortrait(groupId: number, file: string): Promise<unknown>;
+    setEssenceMsg(messageId: number): Promise<unknown>;
+    deleteEssenceMsg(messageId: number): Promise<unknown>;
+    getEssenceMsgList(groupId: number): Promise<unknown>;
+    sendGroupSign(groupId: number): Promise<unknown>;
+    sendGroupNotice(groupId: number, content: string, image?: string): Promise<unknown>;
+    getGroupNotice(groupId: number): Promise<unknown>;
+    deleteGroupNotice(groupId: number, noticeId: string): Promise<unknown>;
+    uploadGroupFile(groupId: number, file: string, name: string, folder?: string): Promise<unknown>;
+    getGroupRootFiles(groupId: number): Promise<unknown>;
+    getGroupFileUrl(groupId: number, fileId: string, busid: number): Promise<unknown>;
+    downloadFile(url: string, threadCount?: number, headers?: string[]): Promise<unknown>;
+    setOnlineStatus(status: number, extStatus: number): Promise<unknown>;
+    setQQAvatar(file: string): Promise<unknown>;
+    forwardFriendSingleMsg(userId: number, messageId: number): Promise<unknown>;
+    forwardGroupSingleMsg(groupId: number, messageId: number): Promise<unknown>;
+    translateEn2Zh(sourceText: string): Promise<unknown>;
+    setMsgEmojiLike(messageId: number, emojiId: string): Promise<unknown>;
+    sendForwardMsg(messageType: 'private' | 'group', id: number, messages: unknown[]): Promise<unknown>;
+    getFriendMsgHistory(userId: number, messageSeq?: number, count?: number): Promise<unknown>;
+    getGroupMsgHistory(groupId: number, messageSeq?: number, count?: number): Promise<unknown>;
+    setSelfLongnick(longnick: string): Promise<unknown>;
+    getGroupInfoEx(groupId: number): Promise<unknown>;
+    sendPoke(userId: number, groupId?: number): Promise<unknown>;
+    ncGetUserStatus(userId: number): Promise<unknown>;
+    getGroupShutList(groupId: number): Promise<unknown>;
+    getMiniAppArk(type: string, title: string, desc: string, picUrl: string, jumpUrl: string): Promise<unknown>;
+    getAiCharacters(groupId: number): Promise<unknown>;
+    sendGroupAiRecord(groupId: number, characterId: string, text: string): Promise<unknown>;
+}
+export interface NapcatAgentDeps {
+    getEndpoint: (endpointId: string) => NapcatAgentEndpoint;
+}
+export declare function registerNapcatAgentEndpoint(endpointId: string, endpoint: NapcatAgentEndpoint): () => void;
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export declare function setNapcatAgentDeps(deps: NapcatAgentDeps | null): void;
+export declare function getNapcatAgentDeps(): NapcatAgentDeps;
+/** Convenience for agent/tools (unchanged call sites). */
+export declare function getEndpoint(endpointId: string): NapcatAgentEndpoint;

package/lib/napcat-agent-deps.js

@@ -0,0 +1,33 @@
+/**
+ * Agent tool deps for napcat.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+const endpoints = new Map();
+let override = null;
+export function registerNapcatAgentEndpoint(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 setNapcatAgentDeps(deps) {
+    override = deps;
+}
+function lookup(endpointId) {
+    const registered = endpoints.get(endpointId);
+    if (!registered)
+        throw new Error(`Endpoint ${endpointId} not found`);
+    return registered;
+}
+export function getNapcatAgentDeps() {
+    if (override)
+        return override;
+    return { getEndpoint: lookup };
+}
+/** Convenience for agent/tools (unchanged call sites). */
+export function getEndpoint(endpointId) {
+    return getNapcatAgentDeps().getEndpoint(endpointId);
+}

package/lib/napcat-inbound.d.ts

@@ -0,0 +1,28 @@
+/**
+ * NapCat 入站消息治理：去重、自发过滤、消息归一化
+ */
+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 | {
+    post_type?: string;
+    self_id?: number | string;
+    user_id?: number | string;
+}): boolean;
+/**
+ * 将 message 字段归一化为 MessageSegment[]。
+ * NapCat 通常返回数组，但某些配置下可能返回 CQ 字符串。
+ */
+export declare function normalizeMessage(message: MessageSegment[] | string): MessageSegment[];
+/**
+ * OneBot11 mentioned 判定：消息段 {type:'at', data:{qq}} 的 qq 等于本机 uin
+ * （事件 self_id）时为 true；`qq === 'all'` 不算。兼容 CQ 字符串形式。
+ */
+export declare function isNapCatBotMentioned(ev: {
+    self_id?: number | string;
+    message?: MessageSegment[] | string;
+}): boolean;

package/lib/{src/napcat-inbound.js → 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/onebot-get-msg.d.ts

@@ -0,0 +1,14 @@
+export interface QuotedMessagePayload {
+    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): QuotedMessagePayload;

package/lib/{src/onebot-get-msg.js → onebot-get-msg.js}

@@ -24,4 +24,3 @@ export function parseOneBotGetMsgResponse(messageId, data) {
         time: typeof record.time === 'number' ? record.time : undefined,
     };
 }
-//# sourceMappingURL=onebot-get-msg.js.map

package/lib/protocol.d.ts

@@ -0,0 +1,151 @@
+/**
+ * NapCat protocol helpers (OneBot 11 + NapCat extensions).
+ * No legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+/** Transitional legacy endpoint row (`endpoints[]` with `context: napcat`). */
+export interface NapCatLegacyEndpointRow {
+    readonly context?: string;
+    readonly connection?: 'ws' | 'wss' | 'http';
+    readonly name?: 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 name?: 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 name: 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;
+export declare function formatInboundTarget(ev: NapCatEvent): string;
+export declare function parseSendTarget(target: string): 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;
+/**
+ * Wire-encode an already-rendered outbound payload into OneBot message segments.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare function formatOutboundSegments(payload: unknown): MessageSegment[];
+export declare function buildSendAction(target: string, 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>;