@zhin.js/adapter-napcat 3.0.1 → 4.0.1

package/lib/index.js

@@ -1,59 +1,10 @@
-/**
- * NapCat 适配器入口
- * 支持 OneBot11 标准 + go-cqhttp 扩展 + NapCat 独有 API
- * 连接方式：正向 WS / 反向 WS / HTTP
- */
-import path from 'path';
-import { usePlugin, createSceneManagementTools, registerDefaultScenePlatformPermitChecker, } from 'zhin.js';
-import { registerAgentPromptContributor, unregisterAgentPromptContributor } from 'zhin.js/agent';
-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 './endpoint-ws-client.js';
-export { NapCatWsServer } from './endpoint-ws-server.js';
-export { NapCatHttpEndpoint } from './endpoint-http.js';
-export { NapCatAdapter } from './adapter.js';
-export { NapCatEndpointBase } from './endpoint-base.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 = [];
-    disposers.push(registerDefaultScenePlatformPermitChecker('napcat'));
-    const sceneTools = createSceneManagementTools(napcat, 'napcat');
-    disposers.push(...sceneTools.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, 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

@@ -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/onebot-get-msg.d.ts

@@ -1,3 +1,14 @@
-import type { QuotedMessagePayload } from 'zhin.js';
+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;
-//# sourceMappingURL=onebot-get-msg.d.ts.map

package/lib/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>;

package/lib/protocol.js

@@ -0,0 +1,217 @@
+/**
+ * NapCat protocol helpers (OneBot 11 + NapCat extensions).
+ * No legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+function normalizeConnection(connection) {
+    if (connection === 'wss' || connection === 'http')
+        return connection;
+    return 'ws';
+}
+export function resolveNapCatConfig(config = {}) {
+    const entry = config.endpoints?.find((item) => item.context === 'napcat');
+    const connection = normalizeConnection(config.connection ?? entry?.connection);
+    const name = (typeof config.name === 'string' && config.name)
+        || (typeof entry?.name === 'string' && entry.name)
+        || process.env.NAPCAT_BOT_NAME
+        || 'napcat-bot';
+    const access_token = config.access_token ?? entry?.access_token;
+    if (connection === 'ws') {
+        const url = config.url ?? entry?.url;
+        if (!url) {
+            throw new TypeError('NapCat connection:ws requires url (plugins.<key>.url or endpoints with context: napcat)');
+        }
+        return {
+            context: 'napcat',
+            connection: 'ws',
+            name,
+            access_token,
+            url,
+            reconnect_interval: config.reconnect_interval ?? entry?.reconnect_interval ?? 5000,
+            heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
+        };
+    }
+    if (connection === 'wss') {
+        const path = config.path ?? entry?.path;
+        if (!path)
+            throw new TypeError('NapCat connection:wss requires path');
+        return {
+            context: 'napcat',
+            connection: 'wss',
+            name,
+            access_token,
+            path,
+            heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
+        };
+    }
+    if (connection === 'http') {
+        const http_url = config.http_url ?? entry?.http_url;
+        const post_path = config.post_path ?? entry?.post_path;
+        if (!http_url || !post_path) {
+            throw new TypeError('NapCat connection:http requires http_url and post_path');
+        }
+        return {
+            context: 'napcat',
+            connection: 'http',
+            name,
+            access_token,
+            http_url,
+            post_path,
+            poll_interval: config.poll_interval ?? entry?.poll_interval ?? 30_000,
+        };
+    }
+    throw new TypeError(`Unknown NapCat connection: ${String(connection)}`);
+}
+export function isMessageEvent(ev) {
+    return (ev.post_type === 'message' || ev.post_type === 'message_sent')
+        && ev.message_id != null;
+}
+export function getChannelId(ev) {
+    if (ev.message_type === 'group' && ev.group_id != null)
+        return String(ev.group_id);
+    if (ev.group_id != null && ev.message_type !== 'private')
+        return String(ev.group_id);
+    if (ev.user_id != null)
+        return String(ev.user_id);
+    return '';
+}
+export function formatInboundTarget(ev) {
+    const messageType = ev.message_type === 'group' || (ev.group_id != null && ev.message_type !== 'private')
+        ? 'group'
+        : 'private';
+    return `${messageType}:${getChannelId(ev)}`;
+}
+export function parseSendTarget(target) {
+    const sep = target.indexOf(':');
+    if (sep <= 0) {
+        return { message_type: 'private', id: target };
+    }
+    const head = target.slice(0, sep);
+    const rest = target.slice(sep + 1);
+    if (head === 'group')
+        return { message_type: 'group', id: rest };
+    if (head === 'private')
+        return { message_type: 'private', id: rest };
+    return { message_type: 'private', id: target };
+}
+export function formatInboundContent(ev) {
+    if (typeof ev.raw_message === 'string' && ev.raw_message)
+        return ev.raw_message;
+    if (Array.isArray(ev.message)) {
+        return ev.message
+            .map((seg) => (seg.type === 'text' ? String(seg.data?.text ?? '') : ''))
+            .join('');
+    }
+    if (typeof ev.message === 'string')
+        return ev.message;
+    return '';
+}
+/**
+ * 入站 sender 语义：必须是用户 ID（Runtime Message contract）。
+ * 显示名走 metadata.nickname，见 senderNickname。
+ */
+export function senderUserId(ev) {
+    return ev.user_id != null ? String(ev.user_id) : '';
+}
+/** 显示名（群名片 card 优先于 nickname），没有则 undefined。 */
+export function senderNickname(ev) {
+    const name = ev.sender?.card || ev.sender?.nickname;
+    return typeof name === 'string' && name ? name : undefined;
+}
+/**
+ * Wire-encode an already-rendered outbound payload into OneBot message segments.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundSegments(payload) {
+    if (typeof payload === 'string') {
+        return [{ type: 'text', data: { text: payload } }];
+    }
+    const items = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    if (items.length === 0) {
+        const text = payload == null
+            ? ''
+            : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload);
+        return [{ type: 'text', data: { text } }];
+    }
+    const segs = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            segs.push({ type: 'text', data: { text: item } });
+            continue;
+        }
+        segs.push({ type: item.type, data: item.data ?? {} });
+    }
+    return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
+}
+export function buildSendAction(target, message) {
+    const parsed = parseSendTarget(target);
+    if (parsed.message_type === 'group') {
+        return {
+            action: 'send_group_msg',
+            params: {
+                group_id: Number(parsed.id) || parsed.id,
+                message,
+            },
+        };
+    }
+    return {
+        action: 'send_private_msg',
+        params: {
+            user_id: Number(parsed.id) || parsed.id,
+            message,
+        },
+    };
+}
+/** Build WS connect URL + headers (access_token via Bearer + query). */
+export function buildWsConnectOptions(config) {
+    const headers = {};
+    let connectUrl = config.url;
+    if (config.access_token) {
+        headers.Authorization = `Bearer ${config.access_token}`;
+        const url = new URL(config.url);
+        url.searchParams.set('access_token', config.access_token);
+        connectUrl = url.toString();
+    }
+    const safeUrl = new URL(connectUrl);
+    safeUrl.searchParams.delete('access_token');
+    return { url: connectUrl, headers, safeUrl: safeUrl.toString() };
+}
+/**
+ * 向 NapCat HTTP API 发送动作请求：POST {http_url}/{action}。
+ * 供 connection:http 出站与纯协议测试使用。
+ */
+export async function callNapCatHttpAction(options, action, params = {}) {
+    const base = options.http_url.replace(/\/$/, '');
+    const url = `${base}/${action}`;
+    const headers = { 'Content-Type': 'application/json' };
+    if (options.access_token) {
+        headers.Authorization = `Bearer ${options.access_token}`;
+    }
+    const res = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(params),
+    });
+    const text = await res.text();
+    if (res.status === 401)
+        throw new Error(`NapCat HTTP auth failed: ${text}`);
+    if (res.status !== 200)
+        throw new Error(`NapCat HTTP ${res.status}: ${text}`);
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`NapCat HTTP invalid response: ${text.slice(0, 200)}`);
+    }
+    if (data.status !== 'ok' && data.retcode !== 0) {
+        throw new Error(`NapCat HTTP action failed [${data.retcode}]: ${data.message || data.wording || 'unknown'}`);
+    }
+    return data;
+}

package/lib/webhook.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingMessage } from 'node:http';
+export declare function readRequestBody(request: IncomingMessage): Promise<string>;

package/lib/webhook.js

@@ -0,0 +1,14 @@
+export async function readRequestBody(request) {
+    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 > 1_048_576) {
+            request.destroy();
+            throw new Error('Request body exceeds 1MB');
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}