@zhin.js/adapter-napcat 1.1.18 → 1.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-napcat",
-  "version": "1.1.18",
+  "version": "1.1.20",
   "description": "Zhin.js NapCat adapter for Plugin Runtime (WebSocket client, OneBot11 + NapCat extensions)",
   "type": "module",
   "main": "./lib/index.js",
@@ -45,19 +45,19 @@
   },
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.25",
-    "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/client": "1.1.21",
+    "@zhin.js/adapter": "1.1.26",
+    "@zhin.js/agent-feature": "1.1.11",
+    "@zhin.js/client": "1.1.22",
     "@zhin.js/console-contract": "1.1.3",
-    "@zhin.js/core": "1.1.53",
-    "@zhin.js/feature-kit": "1.1.9",
-    "@zhin.js/host-http": "1.1.11",
+    "@zhin.js/core": "1.1.54",
+    "@zhin.js/feature-kit": "1.1.10",
+    "@zhin.js/host-http": "1.1.12",
     "@zhin.js/im-contract": "1.1.9",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.10",
-    "@zhin.js/permission": "1.1.9",
-    "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.12"
+    "@zhin.js/page": "1.1.12",
+    "@zhin.js/permission": "1.1.10",
+    "@zhin.js/skill": "1.1.11",
+    "@zhin.js/tool": "1.1.13"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -65,15 +65,15 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.11",
-    "zhin.js": "1.1.18"
+    "@zhin.js/host-http": "1.1.12",
+    "zhin.js": "1.1.19"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.25",
-    "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.53",
-    "zhin.js": "^1.1.18"
+    "@zhin.js/adapter": "^1.1.26",
+    "@zhin.js/command": "^1.1.12",
+    "@zhin.js/core": "^1.1.54",
+    "zhin.js": "^1.1.19"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -107,7 +107,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^1.0.0"
+        "api": "^2.0.0"
       },
       {
         "package": "@zhin.js/command",

package/plugin.js

@@ -1,8 +1,6 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { createEndpointRuntimeState } from 'zhin.js/adapter';
 import { definePlugin, pluginConsoleRpcToken } from 'zhin.js';
 import { permissionHostToken, createSceneRolePlatformChecker } from '@zhin.js/permission';
-import { napcatRuntimeStateToken } from "./lib/napcat-runtime-state.js";
 import { createNapcatConsoleRpc } from "./lib/console.js";
 export default definePlugin({
     name: 'napcat',
@@ -10,7 +8,6 @@ export default definePlugin({
         displayName: 'NapCat Adapter',
     },
     setup(context) {
-        context.resources.provide(napcatRuntimeStateToken, createEndpointRuntimeState());
         context.resources.provide(pluginConsoleRpcToken, createNapcatConsoleRpc(context.resources, () => context.config.get()));
         if (context.resources.has(permissionHostToken)) {
             const host = context.resources.use(permissionHostToken);

package/src/adapter.ts

@@ -0,0 +1,45 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { callNapCatHttpAction, resolveNapCatConfig, type NapCatEndpointConfig } from './protocol.js';
+import { NapCatWsEndpoint } from './ws-endpoint.js';
+import { NapCatWssEndpoint } from './wss-endpoint.js';
+import { NapCatHttpEndpoint } from './http-endpoint.js';
+import { probeNapcatIdentity } from './identity.js';
+import type { NapcatClientEventMap } from './client.js';
+
+type NapcatEndpoint = NapCatWsEndpoint | NapCatWssEndpoint | NapCatHttpEndpoint;
+export class NapcatAdapter extends Adapter<NapcatEndpoint, NapCatEndpointConfig, NapcatClientEventMap> {
+  readonly #context: AdapterContext<NapCatEndpointConfig>;
+  constructor(context: AdapterContext<NapCatEndpointConfig>) { super(); this.#context = context; }
+  override get configurationIdentityFields(): readonly string[] { return ['id']; }
+  override get configurationIdentityProbeFields(): readonly string[] { return ['connection', 'access_token', 'url', 'http_url']; }
+  override get configurationUpdateFields(): readonly string[] {
+    return ['connection', 'url', 'path', 'http_url', 'post_path', 'access_token', 'reconnect_interval', 'heartbeat_interval', 'poll_interval'];
+  }
+  protected override validateConfiguration(config: NapCatEndpointConfig): void { resolveNapCatConfig(config); }
+  protected override async identifyConfiguration(input: NapCatEndpointConfig, signal: AbortSignal): Promise<string | undefined> {
+    const config = resolveNapCatConfig(input);
+    if (config.connection === 'ws') return probeNapcatIdentity(config, signal);
+    if (config.connection === 'wss') return undefined;
+    signal.throwIfAborted();
+    const response = await callNapCatHttpAction({ ...config, signal }, 'get_login_info');
+    signal.throwIfAborted();
+    const data = response.data as { user_id?: unknown } | undefined;
+    if (data?.user_id === 0 || data?.user_id === '0' || (typeof data?.user_id === 'string' && !data.user_id.trim())) return undefined;
+    if ((typeof data?.user_id !== 'string' && typeof data?.user_id !== 'number') || !String(data.user_id).trim()) {
+      throw new Error('NapCat login identity is unavailable');
+    }
+    return `qq:${data.user_id}`;
+  }
+  protected createEndpoint(input: NapCatEndpointConfig, execution: EndpointCreationContext): NapcatEndpoint {
+    const config = resolveNapCatConfig(input), id = execution.canonicalId, signal = execution.signal;
+    switch (config.connection) {
+      case 'wss': return new NapCatWssEndpoint({ id, signal, config, http: this.#context.use(httpHostToken) });
+      case 'http': return new NapCatHttpEndpoint({ id, signal, config, http: this.#context.use(httpHostToken) });
+      case 'ws': return new NapCatWsEndpoint({ id, signal, config });
+    }
+  }
+}
+declare module '@zhin.js/feature-kit' {
+  interface AdapterRegistry { readonly napcat: NapcatAdapter; }
+}

package/src/client.ts

@@ -1,16 +1,99 @@
-import { defineEndpointClient } from 'zhin.js/adapter';
-import type { NapCatEvent } from './protocol.js';
+import { EventEmitter } from 'node:events';
+import { callNapCatHttpAction, readNapCatActionResponse, type NapCatEvent, type ResolvedNapCatConfig } from './protocol.js';
+import { createNapCatRpc, type NapCatRpc } from './ws-transport.js';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import type { PendingRpcRequest } from 'zhin.js/adapter';
+import type { NapCatWsSocket } from './ws-types.js';
 
 export type NapcatApiCall = (
   action: string,
   params?: Record<string, unknown>,
 ) => Promise<unknown>;
 
+/** Platform actions use one named payload; wire field names stay inside this Client. */
+export interface NapcatMemberTitleRequest {
+  readonly groupId: number;
+  readonly userId: number;
+  readonly title: string;
+  /** Platform duration; omission retains the existing indefinite value (-1). */
+  readonly duration?: number;
+}
+export interface NapcatProfileRequest {
+  readonly nickname: string;
+  readonly company?: string;
+  readonly email?: string;
+  readonly college?: string;
+  readonly personalNote?: string;
+}
+export interface NapcatGroupFileRequest {
+  readonly groupId: number;
+  readonly file: string;
+  readonly name: string;
+  readonly folder?: string;
+}
+export interface NapcatMiniAppRequest {
+  readonly type: string;
+  readonly title: string;
+  readonly desc: string;
+  readonly picUrl: string;
+  readonly jumpUrl: string;
+}
+
+export interface NapcatClientOptions {
+  readonly config: ResolvedNapCatConfig;
+  readonly httpAction?: typeof callNapCatHttpAction;
+  readonly signal?: AbortSignal;
+}
+
 /** Transport-independent NapCat protocol Client produced by every Endpoint mode. */
-export class NapcatClient {
-  constructor(readonly callApi: NapcatApiCall) {}
+export class NapcatClient extends EventEmitter<Record<string, [NapCatEvent]>> {
+  protected transportSocket?: NapCatWsSocket;
+  protected readonly rpc: NapCatRpc;
+  protected readonly protocolConfig: ResolvedNapCatConfig;
+  readonly #httpAction: typeof callNapCatHttpAction;
+  readonly #executionSignal?: AbortSignal;
 
-  async setTitle(groupId: number, userId: number, title: string, duration = -1): Promise<boolean> {
+  constructor(options: NapcatClientOptions) {
+    super();
+    this.protocolConfig = options.config;
+    this.#httpAction = options.httpAction ?? callNapCatHttpAction;
+    this.#executionSignal = options.signal;
+    this.rpc = createNapCatRpc({ endpointId: options.config.id, signal: options.signal,
+      socket: () => this.actionSocket });
+  }
+
+  ingest(event: NapCatEvent): void {
+    this.emit('event', event);
+    const name = [event.post_type, event.message_type ?? event.notice_type ?? event.request_type, event.sub_type].filter(Boolean).join('.');
+    if (name && name !== 'event') this.emit(name, event);
+  }
+
+  protected get actionSocket(): NapCatWsSocket | undefined { return this.transportSocket; }
+
+  /** Existing platform methods retain their native action/params calling convention. */
+  readonly callApi: NapcatApiCall = (action, params = {}) => this.requestApi({ action, params });
+
+  /** A semantic operation supplies its caller lifetime to the same native protocol owner. */
+  async requestApi(request: PendingRpcRequest): Promise<unknown> {
+    const signals = [this.#executionSignal, request.signal].filter((signal): signal is AbortSignal => !!signal);
+    const signal = signals.length ? AbortSignal.any(signals) : undefined;
+    if (signal?.aborted) throw new EndpointDeliveryError('endpoint_inactive', 'Endpoint operation ended', 'not_sent');
+    if (this.protocolConfig.connection === 'http') {
+      try {
+        const response = await this.#httpAction({ http_url: this.protocolConfig.http_url,
+          access_token: this.protocolConfig.access_token, signal }, request.action, request.params ?? {});
+        if (signal?.aborted) throw new EndpointDeliveryError('endpoint_inactive', 'Endpoint operation cancelled', 'unknown');
+        return readNapCatActionResponse(response).data;
+      } catch (cause) {
+        if (cause instanceof EndpointDeliveryError) throw cause;
+        throw new EndpointDeliveryError('delivery_unconfirmed', cause instanceof Error ? cause.message : String(cause), 'unknown', { cause });
+      }
+    }
+    const response = await this.rpc.call({ ...request, signal });
+    return readNapCatActionResponse(response).data;
+  }
+
+  async setTitle({ groupId, userId, title, duration = -1 }: NapcatMemberTitleRequest): Promise<boolean> {
     await this.callApi('set_group_special_title', {
       group_id: groupId,
       user_id: userId,
@@ -24,7 +107,7 @@ export class NapcatClient {
   deleteFriend(userId: number) { return this.callApi('delete_friend', { user_id: userId }); }
   markMsgAsRead(messageId: number) { return this.callApi('mark_msg_as_read', { message_id: messageId }); }
   ocrImage(image: string) { return this.callApi('ocr_image', { image }); }
-  setQQProfile(nickname: string, company?: string, email?: string, college?: string, personalNote?: string) {
+  setQQProfile({ nickname, company, email, college, personalNote }: NapcatProfileRequest) {
     return this.callApi('set_qq_profile', { nickname, company, email, college, personal_note: personalNote });
   }
   setGroupPortrait(groupId: number, file: string) { return this.callApi('set_group_portrait', { group_id: groupId, file }); }
@@ -35,7 +118,7 @@ export class NapcatClient {
   sendGroupNotice(groupId: number, content: string, image?: string) { return this.callApi('_send_group_notice', { group_id: groupId, content, image }); }
   getGroupNotice(groupId: number) { return this.callApi('_get_group_notice', { group_id: groupId }); }
   deleteGroupNotice(groupId: number, noticeId: string) { return this.callApi('_del_group_notice', { group_id: groupId, notice_id: noticeId }); }
-  uploadGroupFile(groupId: number, file: string, name: string, folder?: string) { return this.callApi('upload_group_file', { group_id: groupId, file, name, folder }); }
+  uploadGroupFile({ groupId, file, name, folder }: NapcatGroupFileRequest) { return this.callApi('upload_group_file', { group_id: groupId, file, name, folder }); }
   getGroupRootFiles(groupId: number) { return this.callApi('get_group_root_files', { group_id: groupId }); }
   getGroupFileUrl(groupId: number, fileId: string, busid: number) { return this.callApi('get_group_file_url', { group_id: groupId, file_id: fileId, busid }); }
   downloadFile(url: string, threadCount = 1, headers?: string[]) { return this.callApi('download_file', { url, thread_count: threadCount, headers }); }
@@ -59,21 +142,10 @@ export class NapcatClient {
   sendPoke(userId: number, groupId?: number) { return this.callApi('send_poke', { user_id: userId, group_id: groupId }); }
   ncGetUserStatus(userId: number) { return this.callApi('nc_get_user_status', { user_id: userId }); }
   getGroupShutList(groupId: number) { return this.callApi('get_group_shut_list', { group_id: groupId }); }
-  getMiniAppArk(type: string, title: string, desc: string, picUrl: string, jumpUrl: string) { return this.callApi('get_mini_app_ark', { type, title, desc, picUrl, jumpUrl }); }
+  getMiniAppArk({ type, title, desc, picUrl, jumpUrl }: NapcatMiniAppRequest) { return this.callApi('get_mini_app_ark', { type, title, desc, picUrl, jumpUrl }); }
   getAiCharacters(groupId: number) { return this.callApi('get_ai_characters', { group_id: groupId }); }
   sendGroupAiRecord(groupId: number, characterId: string, text: string) {
     return this.callApi('send_group_ai_record', { group_id: groupId, character: characterId, text });
   }
 }
 export type NapcatClientEventMap = Record<string, NapCatEvent>;
-
-declare module '@zhin.js/feature-kit' {
-  interface AdapterClientRegistry {
-    readonly napcat: {
-      readonly client: NapcatClient;
-      readonly events: NapcatClientEventMap;
-    };
-  }
-}
-
-export const napcatClient = defineEndpointClient<NapcatClient, NapcatClientEventMap>('napcat');

package/src/console.ts

@@ -5,17 +5,14 @@
  */
 import { createAdapterConsoleRpc, type AdapterConsoleResources } from 'zhin.js/adapter';
 import type { PluginConsoleRpc } from 'zhin.js';
-import { napcatRuntimeStateToken } from './napcat-runtime-state.js';
 import { napcatConsoleSpec } from './console-spec.js';
 
 export function createNapcatConsoleRpc(
-  resources: AdapterConsoleResources,
+  _resources: AdapterConsoleResources,
   getConfig: () => unknown,
 ): PluginConsoleRpc {
-  const state = resources.use(napcatRuntimeStateToken);
   return createAdapterConsoleRpc({
     ...napcatConsoleSpec,
-    running: () => state.endpoints.values(),
     getConfig,
-  }, resources);
+  });
 }

package/src/endpoint-management.ts

@@ -7,23 +7,27 @@
  * - group → {group_id:number, name: group_name ?? name}
  * - 群成员列表保持 OneBot11 原生形状，仅保证数组
  */
-import type {
-  EndpointFriend,
-  EndpointGroup,
-  EndpointManagement,
+import {
+  type PendingRpcRequest,
+  type EndpointFriend,
+  type EndpointGroup,
+  type EndpointManagement,
+  type EndpointManagementRequest,
+  type EndpointGroupRequest,
+  type EndpointGroupNoticeRequest,
 } from 'zhin.js/adapter';
 
 /** 管理面只依赖 endpoint 的 callApi（ws/wss/http 三种传输各自实现）。 */
 export interface NapCatManagementCaller {
-  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+  requestApi(request: PendingRpcRequest): Promise<unknown>;
 }
 
 export function createNapCatEndpointManagement(
   endpoint: NapCatManagementCaller,
 ): EndpointManagement {
   return Object.freeze<EndpointManagement>({
-    async listFriends(): Promise<readonly EndpointFriend[]> {
-      const data = await endpoint.callApi('get_friend_list');
+    async listFriends(request: EndpointManagementRequest = {}): Promise<readonly EndpointFriend[]> {
+      const data = await endpoint.requestApi({ action: 'get_friend_list', signal: request.signal });
       return toArray(data).map((value) => {
         const friend = asRecord(value);
         return {
@@ -33,8 +37,8 @@ export function createNapCatEndpointManagement(
         };
       });
     },
-    async listGroups(): Promise<readonly EndpointGroup[]> {
-      const data = await endpoint.callApi('get_group_list');
+    async listGroups(request: EndpointManagementRequest = {}): Promise<readonly EndpointGroup[]> {
+      const data = await endpoint.requestApi({ action: 'get_group_list', signal: request.signal });
       return toArray(data).map((value) => {
         const group = asRecord(value);
         return {
@@ -43,17 +47,17 @@ export function createNapCatEndpointManagement(
         };
       });
     },
-    async listGroupMembers(groupId: string): Promise<readonly unknown[]> {
-      const data = await endpoint.callApi('get_group_member_list', {
+    async listGroupMembers({ groupId, signal }: EndpointGroupRequest): Promise<readonly unknown[]> {
+      const data = await endpoint.requestApi({ action: 'get_group_member_list', params: {
         group_id: toNumberId(groupId, 'group_id'),
-      });
+      }, signal });
       return toArray(data);
     },
-    async sendGroupNotice(groupId: string, content: string): Promise<void> {
-      await endpoint.callApi('_send_group_notice', {
+    async sendGroupNotice({ groupId, content, signal }: EndpointGroupNoticeRequest): Promise<void> {
+      await endpoint.requestApi({ action: '_send_group_notice', params: {
         group_id: toNumberId(groupId, 'group_id'),
         content,
-      });
+      }, signal });
     },
   });
 }

package/src/http-endpoint.ts

@@ -4,7 +4,7 @@ import { EndpointDeliveryError } from '@zhin.js/im-contract';
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import {
-  Endpoint,
+  createEndpointSpecification, endpointSpec, type Endpoint, type EndpointSpecification,
   createRecallEndpointControl,
   type EndpointControl,
   type EndpointManagement,
@@ -38,43 +38,55 @@ import { receiveNapCatSideEvent } from './side-event-dispatch.js';
 import { createNapCatContentPort } from './onebot-get-msg.js';
 import { NapcatClient } from './client.js';
 import { readRequestBody } from './webhook.js';
-import { NapCatWsEndpoint } from './ws-endpoint.js';
 import { verifyNapCatAccessToken } from './wss-auth.js';
 
 export interface NapCatHttpEndpointOptions {
   readonly id: CapabilityId;
+  readonly signal?: AbortSignal;
   readonly http: HttpHost;
   readonly config: NapCatHttpConfig;
   readonly callHttpAction?: typeof callNapCatHttpAction;
 }
 
-export class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
-  readonly client = new NapcatClient((action, params) => this.#callApi(action, params));
+export class NapCatHttpEndpoint extends NapcatClient implements Endpoint {
+  readonly [endpointSpec]: EndpointSpecification;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: NapCatHttpEndpointOptions;
   readonly #inboundDeduper = new InboundMessageDeduper();
-  readonly management: EndpointManagement = createNapCatEndpointManagement(this.client);
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
-  readonly content = createNapCatContentPort((action, params) => this.client.callApi(action, params));
-  readonly #callHttpAction: typeof callNapCatHttpAction;
+  readonly #management: EndpointManagement = createNapCatEndpointManagement(this);
+  readonly #control: EndpointControl = createRecallEndpointControl((id, signal) => this.#recallMessage(id, signal));
+  readonly #content = createNapCatContentPort(request => this.requestApi(request));
   #routeReleases: HttpRouteRegistration[] = [];
   #open = false;
   #started = false;
   #stopped = false;
 
   constructor(options: NapCatHttpEndpointOptions) {
-    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: unknown) => {
+        this.#logger.debug(formatCompact({ op: 'napcat_receive_failed', error: error instanceof Error ? error.message : String(error) }));
+      });
+    });
   }
 
-  get transportState(): EndpointTransportState {
+  get #transportState(): EndpointTransportState {
     return this.#stopped ? 'stopped' : this.#started ? 'open' : 'idle';
   }
 
-  async start(): Promise<void> {
+  async #start(): Promise<void> {
     if (this.#started) return;
     this.#stopped = false;
     this.#started = true;
@@ -87,15 +99,15 @@ export class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
     }));
   }
 
-  open(): void {
+  #openEndpoint(): void {
     this.#open = true;
   }
 
-  close(): void {
+  #close(): void {
     this.#open = false;
   }
 
-  async stop(): Promise<void> {
+  async #stop(): Promise<void> {
     this.#stopped = true;
     this.#open = false;
     for (const release of this.#routeReleases.splice(0)) release();
@@ -104,18 +116,10 @@ export class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
     this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+  async #send({ conversation, payload, signal }: EndpointSendRequest): Promise<string> {
     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 as { message_id?: number | string } | undefined;
+    const data = await this.requestApi({ action, params, signal }) as { message_id?: number | string } | undefined;
     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');
@@ -130,25 +134,17 @@ export class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
     return messageId;
   }
 
-  async recallMessage(messageId: string): Promise<void> {
+  async #recallMessage(messageId: string, signal?: AbortSignal): Promise<void> {
     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: string, params: Record<string, unknown> = {}): Promise<unknown> {
-    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: NapCatEvent): void {
-    if (!this.#open) return;
-    void this.emitPlatform(napCatPlatformEventName(ev), ev).catch((error) => {
+
+  #admit(ev: NapCatEvent): void {
+    const nativeEvent = ev;
+    if (!this.#started) return;
+    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),
@@ -156,9 +152,9 @@ export class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
     });
     if (!isMessageEvent(ev)) {
       receiveNapCatSideEvent(
-        (name, payload) => this.emit(name, payload),
+        (name, payload) => this[endpointSpec].events.emit(name, payload),
         this.#options.config.id,
-        this.client,
+        this,
         ev,
         this.#logger,
       );
@@ -170,10 +166,12 @@ export class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
     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),
@@ -227,7 +225,11 @@ export class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
         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: unknown) => {
+          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' }));
     } catch (error) {

package/src/identity.ts

@@ -0,0 +1,29 @@
+import WebSocket from 'ws';
+import { buildWsConnectOptions, readNapCatActionResponse, type NapCatWsConfig } 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: NapCatWsConfig, signal: AbortSignal): Promise<string | undefined> {
+  signal.throwIfAborted();
+  const { url, headers } = buildWsConnectOptions(config);
+  const socket = new WebSocket(url, { headers });
+  const rpc = createNapCatRpc({ endpointId: config.id, signal, socket: () => socket });
+  let rejectOpen: (error: unknown) => void = () => 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<void>((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: unknown = 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/src/index.ts

@@ -27,6 +27,7 @@ export {
   type ParsedSendTarget,
   type ResolvedNapCatConfig,
 } from './protocol.js';
+export { NapcatAdapter } from './adapter.js';
 
 export {
   InboundMessageDeduper,
@@ -36,9 +37,13 @@ export {
 } from './napcat-inbound.js';
 
 export {
-  napcatClient,
   type NapcatClient,
   type NapcatClientEventMap,
+  type NapcatClientOptions,
+  type NapcatMemberTitleRequest,
+  type NapcatProfileRequest,
+  type NapcatGroupFileRequest,
+  type NapcatMiniAppRequest,
 } from './client.js';
 
 export { parseOneBotGetMsgResponse } from './onebot-get-msg.js';
@@ -61,11 +66,10 @@ export {
 export type { NapCatWsSocket, NapCatWsCreateOptions } from './ws-types.js';
 
 export {
-  callNapCatWsAction,
+  createNapCatRpc,
   decodeWsPayload,
-  handleNapCatWsMessage,
-  rejectAllPending,
-  startNapCatHeartbeat,
+  type NapCatRpc,
+  type NapCatRpcOptions,
 } from './ws-transport.js';
 
 export { verifyNapCatAccessToken } from './wss-auth.js';

package/src/onebot-get-msg.ts

@@ -39,7 +39,7 @@ export function parseOneBotGetMsgResponse(
 }
 
 export function createNapCatContentPort(
-  callApi: (action: string, params?: Record<string, unknown>) => Promise<unknown>,
+  callApi: (request: PendingRpcRequest) => Promise<unknown>,
 ): EndpointContentPort {
   return Object.freeze({
     async resolve(reference: ConversationReference, context: EndpointContentResolveContext) {
@@ -51,7 +51,7 @@ export function createNapCatContentPort(
             : Object.freeze({ status: 'resolved' as const, 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: ConversationMessage = Object.freeze({
             ref: reference.message,
@@ -61,7 +61,7 @@ export function createNapCatContentPort(
           });
           return Object.freeze({ status: 'resolved' as const, reference, value });
         }
-        const raw = await callApi('get_forward_msg', { message_id: reference.forwardId, id: reference.forwardId }) as Record<string, unknown>;
+        const raw = await callApi({ action: 'get_forward_msg', params: { message_id: reference.forwardId, id: reference.forwardId }, signal: context.signal }) as Record<string, unknown>;
         context.signal.throwIfAborted();
         const nodes = Array.isArray(raw.messages) ? raw.messages.slice(0, context.maxEntries) : [];
         const value: readonly ForwardEntry[] = Object.freeze(nodes.map((node) => {
@@ -93,5 +93,5 @@ function toMillis(value: unknown): number {
   const time = Number(value);
   return Number.isFinite(time) ? (time < 10_000_000_000 ? time * 1000 : time) : Date.now();
 }
-import type { EndpointContentPort, EndpointContentResolveContext } from 'zhin.js/adapter';
+import type { PendingRpcRequest, EndpointContentPort, EndpointContentResolveContext } from 'zhin.js/adapter';
 import type { ConversationMessage, ConversationReference, ForwardEntry } from '@zhin.js/im-contract';