@zhin.js/adapter-napcat 1.0.1 → 1.1.2

package/lib/ws-endpoint.js

@@ -0,0 +1,241 @@
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * NapCat WS client endpoint — outbound connect to NapCat.
+ */
+import WebSocket from 'ws';
+import { createRecallEndpointControl, createEndpointLifecycle, } 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, buildWsConnectOptions, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
+import { receiveNapCatSideEvent } from './side-event-dispatch.js';
+import { callNapCatWsAction, handleNapCatWsMessage, rejectAllPending, } from './ws-transport.js';
+import { createNapCatContentPort } from './onebot-get-msg.js';
+import { NapcatClient } from './client.js';
+export class NapCatWsEndpoint 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));
+    #lifecycle;
+    #ws;
+    #requestId = { value: 0 };
+    #pending = new Map();
+    #open = false;
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('napcat', options.config.id);
+        this.#options = options;
+        this.#lifecycle = createEndpointLifecycle({
+            name: options.config.id,
+            // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
+            reconnect: {
+                initialIntervalMs: options.config.reconnect_interval,
+                multiplier: 1,
+                maxIntervalMs: Number.MAX_SAFE_INTEGER,
+                jitterMs: 0,
+            },
+        });
+    }
+    async start() {
+        if (this.#lifecycle.started)
+            return;
+        await this.#lifecycle.start((handle) => this.#connect(handle));
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        await this.#lifecycle.stop();
+        rejectAllPending(this.#pending);
+        this.#inboundDeduper.clear();
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#ws = undefined;
+        }
+    }
+    async send({ conversation, payload }) {
+        const message = formatOutboundSegments(payload);
+        const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
+        const data = await this.client.callApi(action, params);
+        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 callNapCatWsAction(this.#ws, this.#pending, this.#requestId, action, params);
+    }
+    /** Test / internal: admit a parsed event when the endpoint is open. */
+    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 content = formatInboundContent(ev);
+        const nickname = senderNickname(ev);
+        const mentioned = isNapCatBotMentioned(ev);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: msgId },
+            content,
+            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),
+            }));
+        });
+    }
+    async #connect(handle) {
+        const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
+        const create = this.#options.createWebSocket
+            ?? ((connectUrl, options) => new WebSocket(connectUrl, { headers: options.headers }));
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const ws = create(url, { headers });
+            this.#ws = ws;
+            handle.onForceClose(() => {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            });
+            ws.on('open', () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (!this.#options.config.access_token) {
+                    this.#logger.warn(formatCompact({
+                        endpoint: this.#options.config.id,
+                        ok: false,
+                        error: 'missing access_token',
+                    }));
+                }
+                this.#logger.debug(formatCompact({
+                    endpoint: this.#options.config.id,
+                    mode: 'ws',
+                    url: safeUrl,
+                }));
+                // stop-during-connect 竞态：已停止则不再武装心跳（基座 stop 已清理定时器）
+                if (this.#lifecycle.started) {
+                    this.#lifecycle.startHeartbeat(() => {
+                        try {
+                            ws.ping?.();
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                    }, this.#options.config.heartbeat_interval);
+                }
+                resolve();
+            });
+            ws.on('message', (data) => {
+                handleNapCatWsMessage(data, {
+                    endpointId: this.#options.config.id,
+                    pending: this.#pending,
+                    admit: (event) => this.admit(event),
+                });
+            });
+            ws.on('close', (code, reason) => {
+                const reasonStr = typeof reason === 'string'
+                    ? reason
+                    : Buffer.isBuffer(reason)
+                        ? reason.toString()
+                        : String(reason ?? '');
+                const codeNum = typeof code === 'number' ? code : Number(code ?? 0);
+                const codeHint = codeNum === 1005
+                    ? ' [no status]'
+                    : codeNum === 1006
+                        ? ' [abnormal]'
+                        : '';
+                this.#logger.warn(formatCompact({
+                    op: 'disconnect',
+                    code: codeNum,
+                    error: `${reasonStr || 'closed'}${codeHint}`,
+                    reconnect_ms: this.#options.config.reconnect_interval,
+                }));
+                // 基座语义：仅曾 open 的连接才武装重连；初始连接失败由 start() 的 catch 复位
+                handle.notifyClosed(new Error(`NapCat WS closed: ${codeNum} ${reasonStr}`));
+                if (!settled) {
+                    settled = true;
+                    reject(new Error(`NapCat WS closed: ${codeNum} ${reasonStr}`));
+                }
+            });
+            ws.on('error', (err) => {
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.#logger.warn(formatCompact({
+                    op: 'ws_error',
+                    endpoint: this.#options.config.id,
+                    ok: false,
+                    error: error.message,
+                }));
+                if (!settled) {
+                    settled = true;
+                    reject(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/ws-transport.d.ts

@@ -0,0 +1,13 @@
+import { type NapCatEvent } from './protocol.js';
+import { type NapCatPendingAction, type NapCatWsSocket } from './ws-types.js';
+export declare function decodeWsPayload(data: unknown): string;
+export declare function handleNapCatWsMessage(data: unknown, options: {
+    readonly endpointId: string;
+    readonly pending: Map<string, NapCatPendingAction>;
+    readonly admit: (ev: NapCatEvent) => void;
+}): void;
+export declare function callNapCatWsAction(ws: NapCatWsSocket | undefined, pending: Map<string, NapCatPendingAction>, requestId: {
+    value: number;
+}, action: string, params: Record<string, unknown>): Promise<unknown>;
+export declare function startNapCatHeartbeat(ws: NapCatWsSocket | undefined, intervalMs: number, existingTimer?: NodeJS.Timeout): NodeJS.Timeout;
+export declare function rejectAllPending(pending: Map<string, NapCatPendingAction>, message?: string): void;

package/lib/ws-transport.js

@@ -0,0 +1,75 @@
+import { clearInterval, clearTimeout, setInterval, setTimeout } from 'node:timers';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { WS_OPEN, } from './ws-types.js';
+const logger = getLogger('napcat');
+export function decodeWsPayload(data) {
+    if (typeof data === 'string')
+        return data;
+    if (Buffer.isBuffer(data))
+        return data.toString();
+    if (data instanceof ArrayBuffer)
+        return new TextDecoder().decode(data);
+    return String(data ?? '');
+}
+export function handleNapCatWsMessage(data, options) {
+    try {
+        const raw = decodeWsPayload(data);
+        const msg = JSON.parse(raw);
+        if ('echo' in msg && typeof msg.echo === 'string') {
+            const resp = msg;
+            const pending = options.pending.get(resp.echo);
+            if (pending) {
+                options.pending.delete(resp.echo);
+                clearTimeout(pending.timeout);
+                if (resp.status === 'ok')
+                    pending.resolve(resp.data);
+                else {
+                    pending.reject(new Error(`API error [${resp.retcode}]: ${resp.message || resp.wording || 'unknown'}`));
+                }
+            }
+            return;
+        }
+        options.admit(msg);
+    }
+    catch (error) {
+        logger.warn(formatCompact({
+            op: 'napcat_parse_failed',
+            endpoint: options.endpointId,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    }
+}
+export function callNapCatWsAction(ws, pending, requestId, action, params) {
+    if (!ws || ws.readyState !== WS_OPEN) {
+        return Promise.reject(new Error('WebSocket is not connected'));
+    }
+    const echo = `req_${++requestId.value}`;
+    const req = { action, params, echo };
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            pending.delete(echo);
+            reject(new Error(`API call timeout: ${action}`));
+        }, 30_000);
+        pending.set(echo, { resolve, reject, timeout });
+        ws.send(JSON.stringify(req));
+    });
+}
+export function startNapCatHeartbeat(ws, intervalMs, existingTimer) {
+    if (existingTimer)
+        clearInterval(existingTimer);
+    return setInterval(() => {
+        try {
+            ws?.ping?.();
+        }
+        catch {
+            /* ignore */
+        }
+    }, intervalMs);
+}
+export function rejectAllPending(pending, message = 'Connection closed') {
+    for (const [, entry] of pending) {
+        clearTimeout(entry.timeout);
+        entry.reject(new Error(message));
+    }
+    pending.clear();
+}

package/lib/ws-types.d.ts

@@ -0,0 +1,17 @@
+/** Minimal WS surface used by the endpoint (real `ws` or test mock). */
+export interface NapCatWsSocket {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    ping?(): void;
+    on(event: 'open' | 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+}
+export interface NapCatWsCreateOptions {
+    readonly headers?: Record<string, string>;
+}
+export declare const WS_OPEN = 1;
+export interface NapCatPendingAction {
+    resolve: (value: unknown) => void;
+    reject: (err: Error) => void;
+    timeout: NodeJS.Timeout;
+}

package/lib/ws-types.js

@@ -0,0 +1 @@
+export const WS_OPEN = 1;

package/lib/wss-auth.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingMessage } from 'node:http';
+export declare function verifyNapCatAccessToken(accessToken: string | undefined, request: IncomingMessage): boolean;

package/lib/wss-auth.js

@@ -0,0 +1,16 @@
+export function verifyNapCatAccessToken(accessToken, request) {
+    if (!accessToken)
+        return true;
+    const auth = request.headers.authorization ?? '';
+    if (auth === `Bearer ${accessToken}`)
+        return true;
+    try {
+        const url = new URL(request.url ?? '/', 'http://localhost');
+        if (url.searchParams.get('access_token') === accessToken)
+            return true;
+    }
+    catch {
+        /* ignore */
+    }
+    return false;
+}

package/lib/wss-endpoint.d.ts

@@ -0,0 +1,29 @@
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * NapCat reverse WSS endpoint — accepts inbound WebSocket from NapCat.
+ */
+import { type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+import { type NapCatEvent, type NapCatWssConfig } from './protocol.js';
+import { NapcatClient } from './client.js';
+export interface NapCatWssEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly config: NapCatWssConfig;
+}
+export declare class NapCatWssEndpoint extends Endpoint<NapcatClient> {
+    #private;
+    readonly client: NapcatClient;
+    readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
+    constructor(options: NapCatWssEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
+    admit(ev: NapCatEvent): void;
+}

package/lib/wss-endpoint.js

@@ -0,0 +1,196 @@
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * NapCat reverse WSS endpoint — accepts inbound WebSocket from NapCat.
+ */
+import { createEndpointLifecycle, 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, 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 { callNapCatWsAction, handleNapCatWsMessage, rejectAllPending, } from './ws-transport.js';
+import { verifyNapCatAccessToken } from './wss-auth.js';
+export class NapCatWssEndpoint 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));
+    #connectionLifecycle;
+    #ws;
+    #wsRelease;
+    #connectionTask = Promise.resolve();
+    #requestId = { value: 0 };
+    #pending = new Map();
+    #open = false;
+    #started = false;
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('napcat', options.config.id);
+        this.#options = options;
+        this.#connectionLifecycle = createEndpointLifecycle({
+            name: `${options.config.id}:inbound`,
+            reconnect: false,
+        });
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        const handle = this.#options.http.ws(this.#options.config.path);
+        this.#wsRelease = handle.onConnection((connection) => {
+            this.#connectionTask = this.#connectionTask
+                .then(() => this.#acceptConnection(connection))
+                .catch((error) => {
+                this.#logger.warn(formatCompact({
+                    op: 'wss_connection_failed',
+                    endpoint: this.#options.config.id,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            });
+        });
+        this.#logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.id,
+            mode: 'wss',
+            path: this.#options.config.path,
+        }));
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#wsRelease?.();
+        this.#wsRelease = undefined;
+        await this.#connectionTask;
+        await this.#connectionLifecycle.stop();
+        rejectAllPending(this.#pending);
+        this.#inboundDeduper.clear();
+        this.#ws = undefined;
+        this.#started = false;
+    }
+    async send({ conversation, payload }) {
+        const message = formatOutboundSegments(payload);
+        const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
+        const data = await this.client.callApi(action, params);
+        return data?.message_id != null ? String(data.message_id) : '';
+    }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await this.client.callApi('delete_msg', { message_id: Number(messageId) });
+    }
+    #callApi(action, params = {}) {
+        return callNapCatWsAction(this.#ws, this.#pending, this.#requestId, action, params);
+    }
+    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),
+            }));
+        });
+    }
+    async #acceptConnection(connection) {
+        if (!verifyNapCatAccessToken(this.#options.config.access_token, connection.request)) {
+            connection.socket.close(4003, 'Unauthorized');
+            return;
+        }
+        const socket = connection.socket;
+        await this.#connectionLifecycle.stop();
+        await this.#connectionLifecycle.start(async (lifecycleHandle) => {
+            this.#ws = socket;
+            lifecycleHandle.onForceClose(() => {
+                try {
+                    socket.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            });
+            this.#connectionLifecycle.startHeartbeat(() => {
+                try {
+                    socket.ping?.();
+                }
+                catch {
+                    /* ignore */
+                }
+            }, this.#options.config.heartbeat_interval);
+            socket.on('message', (data) => {
+                this.#connectionLifecycle.notifyHeartbeatAck();
+                handleNapCatWsMessage(data, {
+                    endpointId: this.#options.config.id,
+                    pending: this.#pending,
+                    admit: (event) => this.admit(event),
+                });
+            });
+            socket.on('close', () => {
+                if (this.#ws === socket)
+                    this.#ws = undefined;
+                lifecycleHandle.notifyClosed(new Error('NapCat reverse WebSocket closed'));
+            });
+        });
+        this.#logger.debug(formatCompact({
+            endpoint: this.#options.config.id,
+            mode: 'wss',
+            peer: connection.request.socket.remoteAddress,
+        }));
+    }
+}
+function napCatPlatformEventName(ev) {
+    return [ev.post_type, ev.message_type ?? ev.notice_type ?? ev.request_type, ev.sub_type]
+        .filter(Boolean)
+        .join('.');
+}