@zhin.js/adapter-onebot12 6.0.0 → 6.0.1

package/src/webhook.ts

@@ -3,13 +3,12 @@
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import {
+  ClientEndpoint,
   createRecallEndpointControl,
   type EndpointControl,
-  type EndpointInstance,
   type EndpointManagement,
   type EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -30,32 +29,43 @@ import {
 } from './protocol.js';
 import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
 import { createOneBot12ContentPort } from './content-port.js';
+import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents, type Onebot12Client } from './client.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 
 const logger = getLogger('onebot12');
 
 export interface OneBot12WebhookEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: OneBot12WebhookConfig;
   readonly callAction?: typeof callOneBot12Action;
 }
 
-export class OneBot12WebhookEndpoint implements EndpointInstance {
+export class OneBot12WebhookEndpoint extends ClientEndpoint<Onebot12Client> {
+  readonly client: Onebot12Client;
   readonly #options: OneBot12WebhookEndpointOptions;
-  readonly management: EndpointManagement = createOneBot12EndpointManagement(this);
+  readonly management: EndpointManagement;
   readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
-  readonly content = createOneBot12ContentPort((action, params) => this.callApi(action, params));
+  readonly content;
   readonly #callAction: typeof callOneBot12Action;
   #routeReleases: HttpRouteRegistration[] = [];
-  #open = false;
   #started = false;
 
   constructor(options: OneBot12WebhookEndpointOptions) {
+    super();
     this.#options = options;
     this.#callAction = options.callAction ?? callOneBot12Action;
+    this.client = createOnebot12EndpointClient(options.config, (action, params) => this.#callApi(action, params));
+    const callApi = (action: string, params?: Record<string, unknown>) => callOnebot12Client(this.client, action, params);
+    this.management = createOneBot12EndpointManagement({ callApi });
+    this.content = createOneBot12ContentPort(callApi);
+    this.bindClientEvents(
+      (receive) => forwardOnebot12ClientEvents(this.client, receive),
+      (name, payload) => {
+        if (name === 'event') this.#admitRaw(payload as OneBot12Event);
+      },
+      (_name, error) => this.#warnPlatformEvent(error),
+    );
   }
 
   async start(): Promise<void> {
@@ -79,16 +89,8 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
     }));
   }
 
-  open(): void {
-    this.#open = true;
-  }
-
-  close(): void {
-    this.#open = false;
-  }
-
   async stop(): Promise<void> {
-    this.#open = false;
+    this.close();
     for (const release of this.#routeReleases.splice(0)) release();
     this.#started = false;
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.id }));
@@ -97,7 +99,7 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const materialized = await uploadOneBot12MediaSegments(
       payload,
-      (action, params) => this.callApi(action, params),
+      (action, params) => callOnebot12Client(this.client, action, params),
       (error) => {
         logger.warn(formatCompact({
           op: 'onebot12_upload_failed',
@@ -108,7 +110,7 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
     );
     const message = formatOutboundSegments(materialized);
     const params = buildSendMessageParams(conversation, message);
-    const data = await this.callApi('send_message', params) as { message_id?: string } | undefined;
+    const data = await callOnebot12Client<{ message_id?: string }>(this.client, 'send_message', params);
     const messageId = data?.message_id ?? '';
     logger.debug(formatCompact({
       op: 'onebot12_send',
@@ -122,30 +124,30 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
 
   async recallMessage(messageId: string): Promise<void> {
     if (!messageId) return;
-    await this.callApi('delete_message', { message_id: messageId });
+    await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
   }
 
-  /** Public API for management surface / callers；webhook 模式走 api_url。 */
-  async callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
+  async #callApi(
+    action: string,
+    params: Record<string, unknown> = {},
+  ): Promise<import('@imhelper/onebot-v12').OneBotV12Response> {
     const apiUrl = this.#options.config.api_url;
     if (!apiUrl) {
       throw new Error('OneBot12 connection:webhook requires api_url for outbound api');
     }
-    const resp = await this.#callAction(
+    return this.#callAction(
       { url: apiUrl, access_token: this.#options.config.access_token },
       action,
       params,
     );
-    return resp.data;
   }
 
-  admit(ev: OneBot12Event): void {
-    if (!this.#open) return;
+  #admitRaw(ev: OneBot12Event): void {
     if (!isMessageEvent(ev)) {
       receiveOneBot12SideEvent(
-        this.#options.sideEvents,
+        (name, payload) => this.emit(name, payload),
         this.#options.config.id,
-        this,
+        { callApi: (action, params) => callOnebot12Client(this.client, action, params) },
         ev,
         logger,
       );
@@ -155,7 +157,7 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
     const content = formatInboundContent(ev);
     const nickname = senderNickname(ev);
     const mentioned = isBotMentioned(ev);
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: ev.message_id },
       content,
@@ -181,6 +183,13 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
     });
   }
 
+  #warnPlatformEvent(error: unknown): void {
+    logger.warn(formatCompact({
+      op: 'onebot12_platform_event_failed',
+      error: error instanceof Error ? error.message : String(error),
+    }));
+  }
+
   #setupRoutes(): void {
     const path = this.#options.config.path;
     this.#routeReleases.push(
@@ -197,18 +206,12 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
         response.end(JSON.stringify({ message: 'Unauthorized' }));
         return;
       }
-      const raw = await readRequestBody(request);
-      let ev: OneBot12Event;
-      try {
-        ev = JSON.parse(raw) as OneBot12Event;
-      } catch {
-        response.writeHead(400, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ message: 'Invalid JSON' }));
+      if (!this.clientEventsOpen) {
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ status: 'ok' }));
         return;
       }
-      if (this.#open) this.admit(ev);
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ status: 'ok' }));
+      await this.client.acceptHttp(request, response);
     } catch (error) {
       logger.error('OneBot12 webhook error:', error);
       if (!response.headersSent) {
@@ -218,18 +221,3 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
     }
   }
 }
-
-async function readRequestBody(request: IncomingMessage): Promise<string> {
-  const chunks: Buffer[] = [];
-  let size = 0;
-  for await (const chunk of request) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    size += buffer.length;
-    if (size > 1_048_576) {
-      request.destroy();
-      throw new Error('Request body exceeds 1MB');
-    }
-    chunks.push(buffer);
-  }
-  return Buffer.concat(chunks).toString('utf8');
-}

package/src/ws-endpoint.ts

@@ -4,16 +4,15 @@
 import WebSocket from 'ws';
 import { clearTimeout } from 'node:timers';
 import {
+  ClientEndpoint,
   createRecallEndpointControl,
   createEndpointLifecycle,
   type EndpointConnectHandle,
   type EndpointControl,
-  type EndpointInstance,
   type EndpointLifecycle,
   type EndpointManagement,
   type EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
@@ -35,6 +34,7 @@ import {
 } from './protocol.js';
 import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
 import { createOneBot12ContentPort } from './content-port.js';
+import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents, type Onebot12Client } from './client.js';
 import {
   type OneBot12WsCreateOptions,
   type OneBot12WsSocket,
@@ -43,8 +43,6 @@ import {
 
 export interface OneBot12WsEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly config: OneBot12WsConfig;
   readonly createWebSocket?: (
     url: string,
@@ -52,26 +50,38 @@ export interface OneBot12WsEndpointOptions {
   ) => OneBot12WsSocket;
 }
 
-export class OneBot12WsEndpoint implements EndpointInstance {
+export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
+  readonly client: Onebot12Client;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: OneBot12WsEndpointOptions;
-  readonly management: EndpointManagement = createOneBot12EndpointManagement(this);
+  readonly management: EndpointManagement;
   readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
-  readonly content = createOneBot12ContentPort((action, params) => this.callApi(action, params));
+  readonly content;
   readonly #lifecycle: EndpointLifecycle;
   #ws?: OneBot12WsSocket;
   #requestId = 0;
   #pending = new Map<string, {
-    resolve: (value: unknown) => void;
+    resolve: (value: OneBot12ActionResponse) => void;
     reject: (err: Error) => void;
     timeout: NodeJS.Timeout;
   }>();
-  #open = false;
 
   constructor(options: OneBot12WsEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('onebot12', options.config.id);
     this.#options = options;
+    this.client = createOnebot12EndpointClient(options.config, (action, params) => this.#callAction(action, params ?? {}));
+    const callApi = (action: string, params?: Record<string, unknown>) => callOnebot12Client(this.client, action, params);
+    this.management = createOneBot12EndpointManagement({ callApi });
+    this.content = createOneBot12ContentPort(callApi);
+    this.bindClientEvents(
+      (receive) => forwardOnebot12ClientEvents(this.client, receive),
+      (name, payload) => {
+        if (name === 'event') this.#admitRaw(payload as OneBot12Event);
+      },
+      (_name, error) => this.#warnPlatformEvent(error),
+    );
     const { config } = options;
     this.#lifecycle = createEndpointLifecycle({
       name: config.id,
@@ -104,16 +114,8 @@ export class OneBot12WsEndpoint implements EndpointInstance {
     }
   }
 
-  open(): void {
-    this.#open = true;
-  }
-
-  close(): void {
-    this.#open = false;
-  }
-
   async stop(): Promise<void> {
-    this.#open = false;
+    this.close();
     // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
     await this.#lifecycle.stop();
     for (const [, pending] of this.#pending) {
@@ -127,7 +129,7 @@ export class OneBot12WsEndpoint implements EndpointInstance {
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const materialized = await uploadOneBot12MediaSegments(
       payload,
-      (action, params) => this.callApi(action, params),
+      (action, params) => callOnebot12Client(this.client, action, params),
       (error) => {
         this.#logger.warn(formatCompact({
           op: 'onebot12_upload_failed',
@@ -138,7 +140,7 @@ export class OneBot12WsEndpoint implements EndpointInstance {
     );
     const message = formatOutboundSegments(materialized);
     const params = buildSendMessageParams(conversation, message);
-    const data = await this.#callAction('send_message', params) as { message_id?: string } | undefined;
+    const data = await callOnebot12Client<{ message_id?: string }>(this.client, 'send_message', params);
     const messageId = data?.message_id ?? '';
     this.#logger.debug(formatCompact({
       op: 'onebot12_send',
@@ -152,22 +154,15 @@ export class OneBot12WsEndpoint implements EndpointInstance {
 
   async recallMessage(messageId: string): Promise<void> {
     if (!messageId) return;
-    await this.#callAction('delete_message', { message_id: messageId });
+    await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
   }
 
-  /** Public API for management surface / callers. */
-  callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
-    return this.#callAction(action, params);
-  }
-
-  /** Test / internal: admit a parsed event when the endpoint is open. */
-  admit(ev: OneBot12Event): void {
-    if (!this.#open) return;
+  #admitRaw(ev: OneBot12Event): void {
     if (!isMessageEvent(ev)) {
       receiveOneBot12SideEvent(
-        this.#options.sideEvents,
+        (name, payload) => this.emit(name, payload),
         this.#options.config.id,
-        this,
+        { callApi: (action, params) => callOnebot12Client(this.client, action, params) },
         ev,
         this.#logger,
       );
@@ -177,7 +172,7 @@ export class OneBot12WsEndpoint implements EndpointInstance {
     const content = formatInboundContent(ev);
     const nickname = senderNickname(ev);
     const mentioned = isBotMentioned(ev);
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: ev.message_id },
       content,
@@ -203,6 +198,13 @@ export class OneBot12WsEndpoint implements EndpointInstance {
     });
   }
 
+  #warnPlatformEvent(error: unknown): void {
+    this.#logger.warn(formatCompact({
+      op: 'onebot12_platform_event_failed',
+      error: error instanceof Error ? error.message : String(error),
+    }));
+  }
+
   async #connect(handle: EndpointConnectHandle): Promise<void> {
     const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
     const create = this.#options.createWebSocket
@@ -287,12 +289,11 @@ export class OneBot12WsEndpoint implements EndpointInstance {
         if (pending) {
           this.#pending.delete(resp.echo!);
           clearTimeout(pending.timeout);
-          if (resp.status === 'ok') pending.resolve(resp.data);
-          else pending.reject(new Error(`OneBot12 retcode=${resp.retcode}: ${resp.message}`));
+          pending.resolve(resp);
         }
         return;
       }
-      this.admit(msg as OneBot12Event);
+      this.client.ingest(msg as Parameters<Onebot12Client['ingest']>[0]);
     } catch (error) {
       this.#logger.warn(formatCompact({
         op: 'onebot12_parse_failed',
@@ -302,7 +303,7 @@ export class OneBot12WsEndpoint implements EndpointInstance {
     }
   }
 
-  #callAction(action: string, params: Record<string, unknown>): Promise<unknown> {
+  #callAction(action: string, params: Record<string, unknown>): Promise<OneBot12ActionResponse> {
     if (!this.#ws || this.#ws.readyState !== WS_OPEN) {
       return Promise.reject(new Error('WebSocket 未连接'));
     }

package/src/wss-endpoint.ts

@@ -1,15 +1,15 @@
 /**
  * OneBot12 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
  */
-import { clearInterval } from 'node:timers';
 import {
+  ClientEndpoint,
+  createEndpointLifecycle,
   createRecallEndpointControl,
+  type EndpointLifecycle,
   type EndpointControl,
-  type EndpointInstance,
   type EndpointManagement,
   type EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -31,44 +31,57 @@ import {
 } from './protocol.js';
 import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
 import { createOneBot12ContentPort } from './content-port.js';
+import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents, type Onebot12Client } from './client.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 import { type OneBot12WsSocket, WS_OPEN } from './ws-types.js';
 
 export interface OneBot12WssEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: OneBot12WssConfig;
 }
 
-export class OneBot12WssEndpoint implements EndpointInstance {
+export class OneBot12WssEndpoint extends ClientEndpoint<Onebot12Client> {
+  readonly client: Onebot12Client;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: OneBot12WssEndpointOptions;
-  readonly management: EndpointManagement = createOneBot12EndpointManagement(this);
+  readonly management: EndpointManagement;
   readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
-  readonly content = createOneBot12ContentPort((action, params) => this.callApi(action, params));
+  readonly content;
   #ws?: OneBot12WsSocket;
   #wsRelease?: () => void;
-  #heartbeatTimer?: NodeJS.Timeout;
+  readonly #lifecycle: EndpointLifecycle;
   #requestId = 0;
   #pending = new Map<string, {
-    resolve: (value: unknown) => void;
+    resolve: (value: OneBot12ActionResponse) => void;
     reject: (err: Error) => void;
     timeout: NodeJS.Timeout;
   }>();
-  #open = false;
-  #started = false;
 
   constructor(options: OneBot12WssEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('onebot12', options.config.id);
     this.#options = options;
+    this.#lifecycle = createEndpointLifecycle({
+      name: options.config.id,
+      reconnect: false,
+      heartbeat: { intervalMs: options.config.heartbeat_interval },
+    });
+    this.client = createOnebot12EndpointClient(options.config, (action, params) => this.#callAction(action, params ?? {}));
+    const callApi = (action: string, params?: Record<string, unknown>) => callOnebot12Client(this.client, action, params);
+    this.management = createOneBot12EndpointManagement({ callApi });
+    this.content = createOneBot12ContentPort(callApi);
+    this.bindClientEvents(
+      (receive) => forwardOnebot12ClientEvents(this.client, receive),
+      (name, payload) => {
+        if (name === 'event') this.#admitRaw(payload as OneBot12Event);
+      },
+      (_name, error) => this.#warnPlatformEvent(error),
+    );
   }
 
   async start(): Promise<void> {
-    if (this.#started) return;
-    this.#started = true;
     if (!this.#options.config.access_token) {
       // wss 模式未配 access_token 时任何连接都会被放行（verifyOneBotAccessToken 直接 return true）
       this.#logger.warn(formatCompact({
@@ -78,9 +91,21 @@ export class OneBot12WssEndpoint implements EndpointInstance {
         error: 'missing access_token',
       }));
     }
-    const handle = this.#options.http.ws(this.#options.config.path);
-    this.#wsRelease = handle.onConnection((connection) => {
-      this.#acceptConnection(connection);
+    await this.#lifecycle.start(async (lifecycleHandle) => {
+      const handle = this.#options.http.ws(this.#options.config.path);
+      this.#wsRelease = handle.onConnection((connection) => {
+        this.#acceptConnection(connection);
+      });
+      lifecycleHandle.onForceClose(() => {
+        this.#wsRelease?.();
+        this.#wsRelease = undefined;
+        try {
+          this.#ws?.close();
+        } catch {
+          /* ignore */
+        }
+        this.#ws = undefined;
+      });
     });
     this.#logger.info(formatCompact({
       op: 'listen',
@@ -90,42 +115,20 @@ export class OneBot12WssEndpoint implements EndpointInstance {
     }));
   }
 
-  open(): void {
-    this.#open = true;
-  }
-
-  close(): void {
-    this.#open = false;
-  }
-
   async stop(): Promise<void> {
-    this.#open = false;
-    this.#wsRelease?.();
-    this.#wsRelease = undefined;
-    if (this.#heartbeatTimer) {
-      clearInterval(this.#heartbeatTimer);
-      this.#heartbeatTimer = undefined;
-    }
+    this.close();
+    await this.#lifecycle.stop();
     for (const [, pending] of this.#pending) {
       clearTimeout(pending.timeout);
       pending.reject(new Error('连接已关闭'));
     }
     this.#pending.clear();
-    if (this.#ws) {
-      try {
-        this.#ws.close();
-      } catch {
-        /* ignore */
-      }
-      this.#ws = undefined;
-    }
-    this.#started = false;
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const materialized = await uploadOneBot12MediaSegments(
       payload,
-      (action, params) => this.callApi(action, params),
+      (action, params) => callOnebot12Client(this.client, action, params),
       (error) => {
         this.#logger.warn(formatCompact({
           op: 'onebot12_upload_failed',
@@ -136,27 +139,21 @@ export class OneBot12WssEndpoint implements EndpointInstance {
     );
     const message = formatOutboundSegments(materialized);
     const params = buildSendMessageParams(conversation, message);
-    const data = await this.#callAction('send_message', params) as { message_id?: string } | undefined;
+    const data = await callOnebot12Client<{ message_id?: string }>(this.client, 'send_message', params);
     return data?.message_id ?? '';
   }
 
   async recallMessage(messageId: string): Promise<void> {
     if (!messageId) return;
-    await this.#callAction('delete_message', { message_id: messageId });
+    await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
   }
 
-  /** Public API for management surface / callers. */
-  callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
-    return this.#callAction(action, params);
-  }
-
-  admit(ev: OneBot12Event): void {
-    if (!this.#open) return;
+  #admitRaw(ev: OneBot12Event): void {
     if (!isMessageEvent(ev)) {
       receiveOneBot12SideEvent(
-        this.#options.sideEvents,
+        (name, payload) => this.emit(name, payload),
         this.#options.config.id,
-        this,
+        { callApi: (action, params) => callOnebot12Client(this.client, action, params) },
         ev,
         this.#logger,
       );
@@ -165,7 +162,7 @@ export class OneBot12WssEndpoint implements EndpointInstance {
     const conversation = onebot12InboundConversation(String(this.#options.id), ev);
     const nickname = senderNickname(ev);
     const mentioned = isBotMentioned(ev);
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: ev.message_id },
       content: formatInboundContent(ev),
@@ -191,6 +188,13 @@ export class OneBot12WssEndpoint implements EndpointInstance {
     });
   }
 
+  #warnPlatformEvent(error: unknown): void {
+    this.#logger.warn(formatCompact({
+      op: 'onebot12_platform_event_failed',
+      error: error instanceof Error ? error.message : String(error),
+    }));
+  }
+
   #acceptConnection(connection: WsConnection): void {
     if (!verifyOneBotAccessToken(this.#options.config.access_token, connection.request)) {
       connection.socket.close(4003, 'Unauthorized');
@@ -205,17 +209,17 @@ export class OneBot12WssEndpoint implements EndpointInstance {
       }
     }
     this.#ws = socket;
-    this.#startHeartbeat();
+    this.#lifecycle.startHeartbeat(() => {
+      this.#callAction('get_status', {}).catch(() => {});
+    });
     socket.on('message', (data) => {
+      this.#lifecycle.notifyHeartbeatAck();
       this.#onMessage(data);
     });
     socket.on('close', () => {
       if (this.#ws === socket) {
         this.#ws = undefined;
-        if (this.#heartbeatTimer) {
-          clearInterval(this.#heartbeatTimer);
-          this.#heartbeatTimer = undefined;
-        }
+        this.#lifecycle.stopHeartbeat();
       }
     });
     this.#logger.debug(formatCompact({
@@ -241,12 +245,11 @@ export class OneBot12WssEndpoint implements EndpointInstance {
         if (pending) {
           this.#pending.delete(resp.echo!);
           clearTimeout(pending.timeout);
-          if (resp.status === 'ok') pending.resolve(resp.data);
-          else pending.reject(new Error(`OneBot12 retcode=${resp.retcode}: ${resp.message}`));
+          pending.resolve(resp);
         }
         return;
       }
-      this.admit(msg as OneBot12Event);
+      this.client.ingest(msg as Parameters<Onebot12Client['ingest']>[0]);
     } catch (error) {
       this.#logger.warn(formatCompact({
         op: 'onebot12_parse_failed',
@@ -256,7 +259,7 @@ export class OneBot12WssEndpoint implements EndpointInstance {
     }
   }
 
-  #callAction(action: string, params: Record<string, unknown>): Promise<unknown> {
+  #callAction(action: string, params: Record<string, unknown>): Promise<OneBot12ActionResponse> {
     if (!this.#ws || this.#ws.readyState !== WS_OPEN) {
       return Promise.reject(new Error('WebSocket 未连接'));
     }
@@ -272,10 +275,4 @@ export class OneBot12WssEndpoint implements EndpointInstance {
     });
   }
 
-  #startHeartbeat(): void {
-    if (this.#heartbeatTimer) clearInterval(this.#heartbeatTimer);
-    this.#heartbeatTimer = setInterval(() => {
-      this.#callAction('get_status', {}).catch(() => {});
-    }, this.#options.config.heartbeat_interval);
-  }
 }