@zhin.js/adapter-napcat 1.1.18 → 1.1.20

package/lib/endpoint-management.js

@@ -1,7 +1,7 @@
 export function createNapCatEndpointManagement(endpoint) {
     return Object.freeze({
-        async listFriends() {
-            const data = await endpoint.callApi('get_friend_list');
+        async listFriends(request = {}) {
+            const data = await endpoint.requestApi({ action: 'get_friend_list', signal: request.signal });
             return toArray(data).map((value) => {
                 const friend = asRecord(value);
                 return {
@@ -11,8 +11,8 @@ export function createNapCatEndpointManagement(endpoint) {
                 };
             });
         },
-        async listGroups() {
-            const data = await endpoint.callApi('get_group_list');
+        async listGroups(request = {}) {
+            const data = await endpoint.requestApi({ action: 'get_group_list', signal: request.signal });
             return toArray(data).map((value) => {
                 const group = asRecord(value);
                 return {
@@ -21,17 +21,17 @@ export function createNapCatEndpointManagement(endpoint) {
                 };
             });
         },
-        async listGroupMembers(groupId) {
-            const data = await endpoint.callApi('get_group_member_list', {
-                group_id: toNumberId(groupId, 'group_id'),
-            });
+        async listGroupMembers({ groupId, signal }) {
+            const data = await endpoint.requestApi({ action: 'get_group_member_list', params: {
+                    group_id: toNumberId(groupId, 'group_id'),
+                }, signal });
             return toArray(data);
         },
-        async sendGroupNotice(groupId, content) {
-            await endpoint.callApi('_send_group_notice', {
-                group_id: toNumberId(groupId, 'group_id'),
-                content,
-            });
+        async sendGroupNotice({ groupId, content, signal }) {
+            await endpoint.requestApi({ action: '_send_group_notice', params: {
+                    group_id: toNumberId(groupId, 'group_id'),
+                    content,
+                }, signal });
         },
     });
 }

package/lib/http-endpoint.d.ts

@@ -1,27 +1,17 @@
-import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
+import { endpointSpec, type Endpoint, type EndpointSpecification } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
-import { callNapCatHttpAction, type NapCatEvent, type NapCatHttpConfig } from './protocol.js';
+import { callNapCatHttpAction, type NapCatHttpConfig } from './protocol.js';
 import { NapcatClient } from './client.js';
 export interface NapCatHttpEndpointOptions {
     readonly id: CapabilityId;
+    readonly signal?: AbortSignal;
     readonly http: HttpHost;
     readonly config: NapCatHttpConfig;
     readonly callHttpAction?: typeof callNapCatHttpAction;
 }
-export declare class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
+export declare class NapCatHttpEndpoint extends NapcatClient implements Endpoint {
     #private;
-    readonly client: NapcatClient;
-    readonly management: EndpointManagement;
-    readonly control: EndpointControl;
-    readonly content: import("@zhin.js/adapter").EndpointContentPort;
+    readonly [endpointSpec]: EndpointSpecification;
     constructor(options: NapCatHttpEndpointOptions);
-    get transportState(): EndpointTransportState;
-    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/http-endpoint.js

@@ -1,5 +1,5 @@
 import { EndpointDeliveryError } from '@zhin.js/im-contract';
-import { Endpoint, createRecallEndpointControl, } from 'zhin.js/adapter';
+import { createEndpointSpecification, endpointSpec, 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';
@@ -9,29 +9,41 @@ 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));
+export class NapCatHttpEndpoint extends NapcatClient {
+    [endpointSpec];
     #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;
+    #management = createNapCatEndpointManagement(this);
+    #control = createRecallEndpointControl((id, signal) => this.#recallMessage(id, signal));
+    #content = createNapCatContentPort(request => this.requestApi(request));
     #routeReleases = [];
     #open = false;
     #started = false;
     #stopped = false;
     constructor(options) {
-        super();
+        super({ config: options.config, httpAction: options.callHttpAction ?? callNapCatHttpAction, signal: options.signal });
         this.#logger = getAdapterLogger('napcat', options.config.id);
         this.#options = options;
-        this.#callHttpAction = options.callHttpAction ?? callNapCatHttpAction;
+        const readTransportState = () => this.#transportState;
+        this[endpointSpec] = createEndpointSpecification(this, {
+            name: options.config.id,
+            start: () => this.#start(), open: () => this.#openEndpoint(),
+            close: () => this.#close(), stop: () => this.#stop(),
+            send: request => this.#send(request),
+            management: this.#management, control: this.#control, content: this.#content,
+            get transportState() { return readTransportState(); },
+        });
+        this.on('event', event => {
+            void this[endpointSpec].events.run(() => this.#admit(event)).catch((error) => {
+                this.#logger.debug(formatCompact({ op: 'napcat_receive_failed', error: error instanceof Error ? error.message : String(error) }));
+            });
+        });
     }
-    get transportState() {
+    get #transportState() {
         return this.#stopped ? 'stopped' : this.#started ? 'open' : 'idle';
     }
-    async start() {
+    async #start() {
         if (this.#started)
             return;
         this.#stopped = false;
@@ -44,13 +56,13 @@ export class NapCatHttpEndpoint extends Endpoint {
             path: this.#options.config.post_path,
         }));
     }
-    open() {
+    #openEndpoint() {
         this.#open = true;
     }
-    close() {
+    #close() {
         this.#open = false;
     }
-    async stop() {
+    async #stop() {
         this.#stopped = true;
         this.#open = false;
         for (const release of this.#routeReleases.splice(0))
@@ -59,14 +71,10 @@ export class NapCatHttpEndpoint extends Endpoint {
         this.#started = false;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async send({ conversation, payload }) {
+    async #send({ conversation, payload, signal }) {
         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 data = await this.requestApi({ action, params, signal });
         const rawId = data?.message_id;
         if ((typeof rawId !== 'number' && typeof rawId !== 'string') || String(rawId).trim() === '' || (typeof rawId === 'number' && !Number.isFinite(rawId))) {
             throw new EndpointDeliveryError('delivery_unconfirmed', 'Message delivery is unconfirmed: platform returned no message_id', 'unknown');
@@ -80,28 +88,23 @@ export class NapCatHttpEndpoint extends Endpoint {
         }));
         return messageId;
     }
-    async recallMessage(messageId) {
+    async #recallMessage(messageId, signal) {
         if (!messageId)
             return;
-        await this.client.callApi('delete_msg', { message_id: Number(messageId) });
+        await this.requestApi({ action: 'delete_msg', params: { message_id: Number(messageId) }, signal });
     }
-    #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)
+    #admit(ev) {
+        const nativeEvent = ev;
+        if (!this.#started)
             return;
-        void this.emitPlatform(napCatPlatformEventName(ev), ev).catch((error) => {
+        void this[endpointSpec].events.platform(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);
+            receiveNapCatSideEvent((name, payload) => this[endpointSpec].events.emit(name, payload), this.#options.config.id, this, ev, this.#logger);
             return;
         }
         if (isSelfMessage(ev))
@@ -112,10 +115,12 @@ export class NapCatHttpEndpoint extends Endpoint {
         if (Array.isArray(ev.message) || typeof ev.message === 'string') {
             ev = { ...ev, message: normalizeMessage(ev.message) };
         }
-        const conversation = napcatInboundConversation(String(this.#options.id), ev);
+        const conversation = { ...napcatInboundConversation(String(this.#options.id), ev), endpoint: this[endpointSpec].identity };
         const nickname = senderNickname(ev);
         const mentioned = isNapCatBotMentioned(ev);
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.message({
+            event: nativeEvent,
+            ...(typeof nativeEvent.time === 'number' ? { platformSentAt: nativeEvent.time * 1000 } : {}),
             conversation,
             message: { conversation, id: msgId },
             content: formatInboundContent(ev),
@@ -166,8 +171,11 @@ export class NapCatHttpEndpoint extends Endpoint {
                 response.end(JSON.stringify({ message: 'Invalid JSON' }));
                 return;
             }
-            if (this.#open)
-                this.admit(ev);
+            if (this.#open) {
+                void this[endpointSpec].events.run(() => this.ingest(ev)).catch((error) => {
+                    this.#logger.debug(formatCompact({ op: 'napcat_receive_failed', error: error instanceof Error ? error.message : String(error) }));
+                });
+            }
             response.writeHead(200, { 'Content-Type': 'application/json' });
             response.end(JSON.stringify({ status: 'ok' }));
         }

package/lib/identity.d.ts

@@ -0,0 +1,3 @@
+import { type NapCatWsConfig } from './protocol.js';
+/** Separate read-only connection: never changes credentials or state of the running Endpoint. */
+export declare function probeNapcatIdentity(config: NapCatWsConfig, signal: AbortSignal): Promise<string | undefined>;

package/lib/identity.js

@@ -0,0 +1,32 @@
+import WebSocket from 'ws';
+import { buildWsConnectOptions, readNapCatActionResponse } from './protocol.js';
+import { createNapCatRpc } from './ws-transport.js';
+/** Separate read-only connection: never changes credentials or state of the running Endpoint. */
+export async function probeNapcatIdentity(config, signal) {
+    signal.throwIfAborted();
+    const { url, headers } = buildWsConnectOptions(config);
+    const socket = new WebSocket(url, { headers });
+    const rpc = createNapCatRpc({ endpointId: config.id, signal, socket: () => socket });
+    let rejectOpen = () => undefined;
+    const abort = () => { rejectOpen(signal.reason); rpc.disconnect(); socket.terminate(); };
+    signal.addEventListener('abort', abort, { once: true });
+    socket.on('message', data => rpc.receive(data, () => undefined));
+    socket.on('close', () => { rejectOpen(new Error('Identity connection closed')); rpc.disconnect(); });
+    try {
+        await new Promise((resolve, reject) => { rejectOpen = reject; socket.once('open', resolve); socket.on('error', reject); });
+        signal.throwIfAborted();
+        const response = await rpc.call({ action: 'get_login_info', signal });
+        readNapCatActionResponse(response);
+        signal.throwIfAborted();
+        const data = response.data;
+        if (!data || typeof data !== 'object' || !('user_id' in data)
+            || (typeof data.user_id !== 'string' && typeof data.user_id !== 'number') || !String(data.user_id).trim() || String(data.user_id) === '0')
+            return undefined;
+        return `qq:${data.user_id}`;
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        rpc.dispose();
+        socket.terminate();
+    }
+}

package/lib/index.d.ts

@@ -1,11 +1,12 @@
 export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, getChannelId, isMessageEvent, mediaRefToOneBotFile, napcatInboundConversation, napcatOutboundTarget, resolveNapCatConfig, senderNickname, senderUserId, type MessageSegment, type NapCatActionRequest, type NapCatActionResponse, 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 { NapcatAdapter } from './adapter.js';
 export { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
-export { napcatClient, type NapcatClient, type NapcatClientEventMap, } from './client.js';
+export { type NapcatClient, type NapcatClientEventMap, type NapcatClientOptions, type NapcatMemberTitleRequest, type NapcatProfileRequest, type NapcatGroupFileRequest, type NapcatMiniAppRequest, } 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 { createNapCatRpc, decodeWsPayload, type NapCatRpc, type NapCatRpcOptions, } from './ws-transport.js';
 export { verifyNapCatAccessToken } from './wss-auth.js';
 export { readRequestBody } from './webhook.js';

package/lib/index.js

@@ -1,10 +1,10 @@
 export { buildSendAction, buildWsConnectOptions, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, getChannelId, isMessageEvent, mediaRefToOneBotFile, napcatInboundConversation, napcatOutboundTarget, resolveNapCatConfig, senderNickname, senderUserId, } from './protocol.js';
+export { NapcatAdapter } from './adapter.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 { createNapCatRpc, decodeWsPayload, } from './ws-transport.js';
 export { verifyNapCatAccessToken } from './wss-auth.js';
 export { readRequestBody } from './webhook.js';

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

@@ -12,5 +12,5 @@ export interface NapcatMessageLookup {
     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';
+export declare function createNapCatContentPort(callApi: (request: PendingRpcRequest) => Promise<unknown>): EndpointContentPort;
+import type { PendingRpcRequest, EndpointContentPort } from 'zhin.js/adapter';

package/lib/onebot-get-msg.js

@@ -35,7 +35,7 @@ export function createNapCatContentPort(callApi) {
                         : 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 }));
+                    const parsed = parseOneBotGetMsgResponse(reference.message.id, await callApi({ action: 'get_msg', params: { message_id: reference.message.id }, signal: context.signal }));
                     context.signal.throwIfAborted();
                     const value = Object.freeze({
                         ref: reference.message,
@@ -45,7 +45,7 @@ export function createNapCatContentPort(callApi) {
                     });
                     return Object.freeze({ status: 'resolved', reference, value });
                 }
-                const raw = await callApi('get_forward_msg', { message_id: reference.forwardId, id: reference.forwardId });
+                const raw = await callApi({ action: 'get_forward_msg', params: { message_id: reference.forwardId, id: reference.forwardId }, signal: context.signal });
                 context.signal.throwIfAborted();
                 const nodes = Array.isArray(raw.messages) ? raw.messages.slice(0, context.maxEntries) : [];
                 const value = Object.freeze(nodes.map((node) => {

package/lib/protocol.d.ts

@@ -88,6 +88,10 @@ export interface NapCatActionResponse {
     message?: string;
     wording?: string;
 }
+/** OneBot 11: async/1 is submitted without a known result, not a rejection.
+ * https://github.com/botuniverse/onebot-11/blob/master/communication/http.md#响应
+ */
+export declare function readNapCatActionResponse(value: unknown): NapCatActionResponse;
 export interface NapCatWireSegment {
     readonly type: string;
     readonly data?: Record<string, unknown>;
@@ -139,6 +143,7 @@ export declare function buildWsConnectOptions(config: NapCatWsConfig): {
 export interface NapCatHttpOptions {
     readonly http_url: string;
     readonly access_token?: string;
+    readonly signal?: AbortSignal;
 }
 /**
  * 向 NapCat HTTP API 发送动作请求：POST {http_url}/{action}。

package/lib/protocol.js

@@ -6,6 +6,21 @@
 import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('napcat');
+/** OneBot 11: async/1 is submitted without a known result, not a rejection.
+ * https://github.com/botuniverse/onebot-11/blob/master/communication/http.md#响应
+ */
+export function readNapCatActionResponse(value) {
+    if (!value || typeof value !== 'object' || !('status' in value) || !('retcode' in value)
+        || !Number.isInteger(value.retcode))
+        throw new EndpointDeliveryError('delivery_unconfirmed', 'NapCat returned an invalid action response', 'unknown');
+    const response = value;
+    if (response.status === 'failed' && response.retcode !== 0 && response.retcode !== 1) {
+        throw new EndpointDeliveryError('platform_rejected', `NapCat action failed [${response.retcode}]: ${response.message || response.wording || 'unknown'}`, 'rejected');
+    }
+    if (response.status !== 'ok' || response.retcode !== 0)
+        throw new EndpointDeliveryError('delivery_unconfirmed', 'NapCat did not confirm the action result', 'unknown');
+    return response;
+}
 function normalizeConnection(connection) {
     if (connection === 'wss' || connection === 'http')
         return connection;
@@ -299,25 +314,22 @@ export async function callNapCatHttpAction(options, action, params = {}) {
         headers.Authorization = `Bearer ${options.access_token}`;
     }
     const res = await fetch(url, {
-        signal: AbortSignal.timeout(30_000),
+        signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
         method: 'POST',
         headers,
         body: JSON.stringify(params),
     });
     const text = await res.text();
-    if (res.status === 401)
-        throw new EndpointDeliveryError('platform_rejected', `NapCat HTTP auth failed: ${text}`, 'rejected');
-    if (res.status !== 200)
-        throw new EndpointDeliveryError(res.status === 429 || res.status === 403 ? 'platform_rejected' : 'delivery_unconfirmed', `NapCat HTTP ${res.status}: ${text}`, res.status === 429 || res.status === 403 ? 'rejected' : 'unknown');
+    if (res.status !== 200) {
+        const rejected = [400, 401, 403, 404, 406, 429].includes(res.status);
+        throw new EndpointDeliveryError(rejected ? 'platform_rejected' : 'delivery_unconfirmed', `NapCat HTTP ${res.status}: ${text}`, rejected ? 'rejected' : 'unknown');
+    }
     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 EndpointDeliveryError('platform_rejected', `NapCat HTTP action failed [${data.retcode}]: ${data.message || data.wording || 'unknown'}`, 'rejected');
+    catch (cause) {
+        throw new EndpointDeliveryError('delivery_unconfirmed', 'NapCat returned invalid JSON', 'unknown', { cause });
     }
-    return data;
+    return readNapCatActionResponse(data);
 }

package/lib/ws-endpoint.d.ts

@@ -1,27 +1,17 @@
-import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
+import { endpointSpec, type Endpoint, type EndpointSpecification } from 'zhin.js/adapter';
 import type { CapabilityId } from 'zhin.js';
-import { type NapCatEvent, type NapCatWsConfig } from './protocol.js';
+import { type NapCatWsConfig } from './protocol.js';
 import { type NapCatWsCreateOptions, type NapCatWsSocket } from './ws-types.js';
 import { NapcatClient } from './client.js';
 export interface NapCatWsEndpointOptions {
     readonly id: CapabilityId;
+    readonly signal?: AbortSignal;
     readonly config: NapCatWsConfig;
     readonly createWebSocket?: (url: string, options: NapCatWsCreateOptions) => NapCatWsSocket;
 }
-export declare class NapCatWsEndpoint extends Endpoint<NapcatClient> {
+export declare class NapCatWsEndpoint extends NapcatClient implements Endpoint {
     #private;
-    readonly client: NapcatClient;
-    readonly management: EndpointManagement;
-    readonly control: EndpointControl;
-    readonly content: import("@zhin.js/adapter").EndpointContentPort;
+    readonly [endpointSpec]: EndpointSpecification;
     constructor(options: NapCatWsEndpointOptions);
-    get transportState(): EndpointTransportState;
-    start(): Promise<void>;
-    open(): void;
-    close(): void;
-    stop(): Promise<void>;
-    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    recallMessage(messageId: string): Promise<void>;
-    /** Test / internal: admit a parsed event when the endpoint is open. */
-    admit(ev: NapCatEvent): void;
+    protected get actionSocket(): NapCatWsSocket | undefined;
 }