@zhin.js/adapter-napcat 1.1.17 → 1.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-napcat",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "description": "Zhin.js NapCat adapter for Plugin Runtime (WebSocket client, OneBot11 + NapCat extensions)",
   "type": "module",
   "main": "./lib/index.js",
@@ -14,6 +14,7 @@
   "files": [
     "adapters",
     "commands",
+    "pages",
     "plugin.js",
     "schema.json",
     "src",
@@ -44,16 +45,19 @@
   },
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.24",
-    "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/core": "1.1.52",
-    "@zhin.js/feature-kit": "1.1.9",
-    "@zhin.js/host-http": "1.1.11",
-    "@zhin.js/im-contract": "1.1.8",
+    "@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.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/permission": "1.1.9",
-    "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.11"
+    "@zhin.js/page": "1.1.11",
+    "@zhin.js/permission": "1.1.10",
+    "@zhin.js/skill": "1.1.11",
+    "@zhin.js/tool": "1.1.13"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -61,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.17"
+    "@zhin.js/host-http": "1.1.12",
+    "zhin.js": "1.1.19"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.24",
-    "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.52",
-    "zhin.js": "^1.1.17"
+    "@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": {
@@ -103,7 +107,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^1.0.0"
+        "api": "^2.0.0"
       },
       {
         "package": "@zhin.js/command",
@@ -120,6 +124,10 @@
       {
         "package": "@zhin.js/agent-feature",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/page",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/pages/index/index.js

@@ -0,0 +1,15 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+export const meta = definePage({
+    title: 'NapCat',
+    titleI18n: { en: 'NapCat' },
+    icon: 'Cat',
+    order: 69,
+    requiredPermissions: ['napcat:read'],
+});
+/**
+ * Convention page: `pages/index/index.ts` → `/napcat`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('napcat');

package/pages/index/index.ts

@@ -0,0 +1,16 @@
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+
+export const meta = definePage({
+  title: 'NapCat',
+  titleI18n: { en: 'NapCat' },
+  icon: 'Cat',
+  order: 69,
+  requiredPermissions: ['napcat:read'],
+});
+
+/**
+ * Convention page: `pages/index/index.ts` → `/napcat`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('napcat');

package/plugin.js

@@ -1,15 +1,14 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { createEndpointRuntimeState } from 'zhin.js/adapter';
-import { definePlugin } from 'zhin.js';
+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',
     metadata: {
         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);
             return host.registerPlatform('napcat', createSceneRolePlatformChecker());

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-spec.ts

@@ -0,0 +1,19 @@
+/**
+ * NapCat Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+
+export const napcatConsoleSpec = {
+  adapterKey: 'napcat',
+  adapterDisplayName: 'NapCat',
+  fields: [
+    { key: 'url', description: 'NapCat WebSocket URL（connection: ws 必填）', descriptionI18n: { en: 'NapCat WebSocket URL (required for connection: ws)' } },
+    { key: 'path', description: 'reverse-wss 路径（connection: wss）', descriptionI18n: { en: 'Reverse WebSocket path (connection: wss)' } },
+    { key: 'http_url', description: 'HTTP API base URL（connection: http 出站）', descriptionI18n: { en: 'HTTP API base URL (outbound connection: http)' } },
+    { key: 'post_path', description: 'HTTP POST 事件路径（connection: http 入站）', descriptionI18n: { en: 'HTTP POST event path (inbound connection: http)' } },
+    { key: 'access_token', env: true, description: 'NapCat access token' },
+  ] as readonly AdapterConsoleField[],
+  docsUrl: 'https://zhin.js.org/adapters/napcat',
+  readPermission: 'napcat:read',
+  writePermission: 'napcat:write',
+} as const;

package/src/console.ts

@@ -0,0 +1,18 @@
+/**
+ * NapCat Console RPC：运行状态 + endpoint 增删（原 `napcat endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { createAdapterConsoleRpc, type AdapterConsoleResources } from 'zhin.js/adapter';
+import type { PluginConsoleRpc } from 'zhin.js';
+import { napcatConsoleSpec } from './console-spec.js';
+
+export function createNapcatConsoleRpc(
+  _resources: AdapterConsoleResources,
+  getConfig: () => unknown,
+): PluginConsoleRpc {
+  return createAdapterConsoleRpc({
+    ...napcatConsoleSpec,
+    getConfig,
+  });
+}

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) {