@zhin.js/adapter-onebot12 5.0.13 → 6.0.1

package/lib/ws-endpoint.js

@@ -3,26 +3,37 @@
  */
 import WebSocket from 'ws';
 import { clearTimeout } from 'node:timers';
-import { createEndpointLifecycle, } from 'zhin.js/adapter';
+import { ClientEndpoint, createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
 import { buildSendMessageParams, buildWsConnectOptions, formatInboundContent, formatOutboundSegments, isBotMentioned, isMessageEvent, onebot12InboundConversation, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
 import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
 import { createOneBot12ContentPort } from './content-port.js';
+import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents } from './client.js';
 import { WS_OPEN, } from './ws-types.js';
-export class OneBot12WsEndpoint {
+export class OneBot12WsEndpoint extends ClientEndpoint {
+    client;
     #logger;
     #options;
-    management = createOneBot12EndpointManagement(this);
-    content = createOneBot12ContentPort((action, params) => this.callApi(action, params));
+    management;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    content;
     #lifecycle;
     #ws;
     #requestId = 0;
     #pending = new Map();
-    #open = false;
     constructor(options) {
+        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, params) => 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);
+        }, (_name, error) => this.#warnPlatformEvent(error));
         const { config } = options;
         this.#lifecycle = createEndpointLifecycle({
             name: config.id,
@@ -56,14 +67,8 @@ export class OneBot12WsEndpoint {
             throw err;
         }
     }
-    open() {
-        this.#open = true;
-    }
-    close() {
-        this.#open = false;
-    }
     async stop() {
-        this.#open = false;
+        this.close();
         // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
         await this.#lifecycle.stop();
         for (const [, pending] of this.#pending) {
@@ -74,7 +79,7 @@ export class OneBot12WsEndpoint {
         this.#ws = undefined;
     }
     async send({ conversation, payload }) {
-        const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => this.callApi(action, params), (error) => {
+        const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => callOnebot12Client(this.client, action, params), (error) => {
             this.#logger.warn(formatCompact({
                 op: 'onebot12_upload_failed',
                 endpoint: this.#options.config.id,
@@ -83,7 +88,7 @@ export class OneBot12WsEndpoint {
         });
         const message = formatOutboundSegments(materialized);
         const params = buildSendMessageParams(conversation, message);
-        const data = await this.#callAction('send_message', params);
+        const data = await callOnebot12Client(this.client, 'send_message', params);
         const messageId = data?.message_id ?? '';
         this.#logger.debug(formatCompact({
             op: 'onebot12_send',
@@ -97,25 +102,18 @@ export class OneBot12WsEndpoint {
     async recallMessage(messageId) {
         if (!messageId)
             return;
-        await this.#callAction('delete_message', { message_id: messageId });
-    }
-    /** Public API for management surface / callers. */
-    callApi(action, params = {}) {
-        return this.#callAction(action, params);
+        await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
     }
-    /** Test / internal: admit a parsed event when the endpoint is open. */
-    admit(ev) {
-        if (!this.#open)
-            return;
+    #admitRaw(ev) {
         if (!isMessageEvent(ev)) {
-            receiveOneBot12SideEvent(this.#options.sideEvents, this.#options.config.id, this, ev, this.#logger);
+            receiveOneBot12SideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, { callApi: (action, params) => callOnebot12Client(this.client, action, params) }, ev, this.#logger);
             return;
         }
         const conversation = onebot12InboundConversation(String(this.#options.id), ev);
         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,
@@ -140,6 +138,12 @@ export class OneBot12WsEndpoint {
             }));
         });
     }
+    #warnPlatformEvent(error) {
+        this.#logger.warn(formatCompact({
+            op: 'onebot12_platform_event_failed',
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    }
     async #connect(handle) {
         const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
         const create = this.#options.createWebSocket
@@ -219,14 +223,11 @@ export class OneBot12WsEndpoint {
                 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);
+            this.client.ingest(msg);
         }
         catch (error) {
             this.#logger.warn(formatCompact({

package/lib/wss-endpoint.d.ts

@@ -1,27 +1,25 @@
-import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+/**
+ * OneBot12 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
+ */
+import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
-import { type OneBot12Event, type OneBot12WssConfig } from './protocol.js';
+import { type OneBot12WssConfig } from './protocol.js';
+import { type Onebot12Client } from './client.js';
 export interface OneBot12WssEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: OneBot12WssConfig;
 }
-export declare class OneBot12WssEndpoint implements EndpointInstance {
+export declare class OneBot12WssEndpoint extends ClientEndpoint<Onebot12Client> {
     #private;
+    readonly client: Onebot12Client;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
     readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: OneBot12WssEndpointOptions);
     start(): Promise<void>;
-    open(): void;
-    close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
-    /** Public API for management surface / callers. */
-    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
-    admit(ev: OneBot12Event): void;
 }

package/lib/wss-endpoint.js

@@ -1,34 +1,46 @@
 /**
  * OneBot12 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
  */
-import { clearInterval } from 'node:timers';
+import { ClientEndpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
 import { buildSendMessageParams, formatInboundContent, formatOutboundSegments, isBotMentioned, isMessageEvent, onebot12InboundConversation, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
 import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
 import { createOneBot12ContentPort } from './content-port.js';
+import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents } from './client.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 import { WS_OPEN } from './ws-types.js';
-export class OneBot12WssEndpoint {
+export class OneBot12WssEndpoint extends ClientEndpoint {
+    client;
     #logger;
     #options;
-    management = createOneBot12EndpointManagement(this);
-    content = createOneBot12ContentPort((action, params) => this.callApi(action, params));
+    management;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    content;
     #ws;
     #wsRelease;
-    #heartbeatTimer;
+    #lifecycle;
     #requestId = 0;
     #pending = new Map();
-    #open = false;
-    #started = false;
     constructor(options) {
+        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, params) => 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);
+        }, (_name, error) => this.#warnPlatformEvent(error));
     }
     async start() {
-        if (this.#started)
-            return;
-        this.#started = true;
         if (!this.#options.config.access_token) {
             // wss 模式未配 access_token 时任何连接都会被放行（verifyOneBotAccessToken 直接 return true）
             this.#logger.warn(formatCompact({
@@ -38,9 +50,22 @@ export class OneBot12WssEndpoint {
                 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',
@@ -49,38 +74,17 @@ export class OneBot12WssEndpoint {
             path: this.#options.config.path,
         }));
     }
-    open() {
-        this.#open = true;
-    }
-    close() {
-        this.#open = false;
-    }
     async stop() {
-        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 }) {
-        const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => this.callApi(action, params), (error) => {
+        const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => callOnebot12Client(this.client, action, params), (error) => {
             this.#logger.warn(formatCompact({
                 op: 'onebot12_upload_failed',
                 endpoint: this.#options.config.id,
@@ -89,29 +93,23 @@ export class OneBot12WssEndpoint {
         });
         const message = formatOutboundSegments(materialized);
         const params = buildSendMessageParams(conversation, message);
-        const data = await this.#callAction('send_message', params);
+        const data = await callOnebot12Client(this.client, 'send_message', params);
         return data?.message_id ?? '';
     }
     async recallMessage(messageId) {
         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, params = {}) {
-        return this.#callAction(action, params);
-    }
-    admit(ev) {
-        if (!this.#open)
-            return;
+    #admitRaw(ev) {
         if (!isMessageEvent(ev)) {
-            receiveOneBot12SideEvent(this.#options.sideEvents, this.#options.config.id, this, ev, this.#logger);
+            receiveOneBot12SideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, { callApi: (action, params) => callOnebot12Client(this.client, action, params) }, ev, this.#logger);
             return;
         }
         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),
@@ -136,6 +134,12 @@ export class OneBot12WssEndpoint {
             }));
         });
     }
+    #warnPlatformEvent(error) {
+        this.#logger.warn(formatCompact({
+            op: 'onebot12_platform_event_failed',
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    }
     #acceptConnection(connection) {
         if (!verifyOneBotAccessToken(this.#options.config.access_token, connection.request)) {
             connection.socket.close(4003, 'Unauthorized');
@@ -151,17 +155,17 @@ export class OneBot12WssEndpoint {
             }
         }
         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({
@@ -186,14 +190,11 @@ export class OneBot12WssEndpoint {
                 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);
+            this.client.ingest(msg);
         }
         catch (error) {
             this.#logger.warn(formatCompact({
@@ -218,11 +219,4 @@ export class OneBot12WssEndpoint {
             this.#ws.send(JSON.stringify(req));
         });
     }
-    #startHeartbeat() {
-        if (this.#heartbeatTimer)
-            clearInterval(this.#heartbeatTimer);
-        this.#heartbeatTimer = setInterval(() => {
-            this.#callAction('get_status', {}).catch(() => { });
-        }, this.#options.config.heartbeat_interval);
-    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot12",
-  "version": "5.0.13",
+  "version": "6.0.1",
   "description": "Zhin.js OneBot 12 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -39,26 +39,29 @@
     "directory": "plugins/adapters/onebot12"
   },
   "dependencies": {
+    "@imhelper/onebot-v12": "1.0.7",
+    "imhelper": "1.0.7",
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.11",
-    "@zhin.js/core": "1.5.12",
-    "@zhin.js/host-http": "1.0.11",
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/core": "1.5.14",
+    "@zhin.js/feature-kit": "1.0.13",
+    "@zhin.js/host-http": "1.0.13",
     "@zhin.js/im-contract": "1.0.4",
-    "@zhin.js/logger": "1.0.76"
+    "@zhin.js/logger": "1.0.77"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@zhin.js/host-http": "1.0.11",
-    "zhin.js": "6.0.12"
+    "@zhin.js/host-http": "1.0.13",
+    "zhin.js": "6.0.14"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.11",
-    "@zhin.js/command": "1.0.15",
-    "@zhin.js/core": "1.5.12",
-    "zhin.js": "6.0.12"
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/command": "1.0.16",
+    "@zhin.js/core": "1.5.14",
+    "zhin.js": "6.0.14"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {

package/src/client.ts

@@ -0,0 +1,81 @@
+import {
+  OneBotV12Client,
+  type OneBotV12Event as ImHelperOneBot12Event,
+  type OneBotV12Response,
+} from '@imhelper/onebot-v12';
+import { EventFactory, type EventMap, type ImHelperEventMap } from 'imhelper';
+import {
+  defineEndpointClient,
+  forwardEndpointClientEvents,
+  type ClientEventPayloads,
+} from 'zhin.js/adapter';
+import type { ResolvedOneBot12Config } from './protocol.js';
+
+export { OneBotV12Client as Onebot12Client } from '@imhelper/onebot-v12';
+
+export type Onebot12ApiCall = (
+  action: string,
+  params?: Record<string, unknown>,
+) => Promise<OneBotV12Response>;
+
+type Onebot12ClientEvents = ImHelperEventMap<
+  string,
+  ImHelperOneBot12Event,
+  EventMap<string>
+>;
+export type Onebot12ClientEventMap = ClientEventPayloads<Onebot12ClientEvents>;
+
+export function createOnebot12EndpointClient(
+  config: ResolvedOneBot12Config,
+  request: Onebot12ApiCall,
+): OneBotV12Client {
+  const baseUrl = config.connection === 'ws'
+    ? config.url.replace(/^ws(s?):/, 'http$1:')
+    : config.connection === 'webhook' && config.api_url
+      ? config.api_url
+      : 'http://localhost';
+  return new OneBotV12Client({
+    baseUrl,
+    selfId: config.id,
+    accessToken: config.access_token,
+    receiveMode: 'manual',
+    call: request,
+  });
+}
+
+export async function callOnebot12Client<T = unknown>(
+  client: OneBotV12Client,
+  action: string,
+  params?: Record<string, unknown>,
+): Promise<T | undefined> {
+  const response: OneBotV12Response<T> = await client.call<T>(action, params);
+  if (response.status !== 'ok') {
+    throw new Error(
+      `OneBot 12 API ${action}: retcode=${response.retcode}${response.message ? ` ${response.message}` : ''}`,
+    );
+  }
+  return response.data;
+}
+
+const onebot12ClientEventNames = Object.freeze([
+  ...EventFactory.getSupportedEventTypes<string>(),
+  'event',
+]);
+
+export function forwardOnebot12ClientEvents(
+  client: OneBotV12Client,
+  receive: (name: string, payload: unknown) => void,
+): () => void {
+  return forwardEndpointClientEvents(client, onebot12ClientEventNames, receive);
+}
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly onebot12: {
+      readonly client: OneBotV12Client;
+      readonly events: Onebot12ClientEventMap;
+    };
+  }
+}
+
+export const onebot12Client = defineEndpointClient<OneBotV12Client, Onebot12ClientEventMap>('onebot12');

package/src/index.ts

@@ -49,3 +49,19 @@ export {
 export type { OneBot12WsSocket, OneBot12WsCreateOptions } from './ws-types.js';
 
 export { verifyOneBotAccessToken } from './wss-auth.js';
+export {
+  Onebot12Client,
+  onebot12Client,
+  type Onebot12ClientEventMap,
+} from './client.js';
+
+export type {
+  OneBotV12ActionUrlResolver,
+  OneBotV12AdapterConfig as ImHelperOneBotV12AdapterConfig,
+  OneBotV12Call,
+  OneBotV12ClientConfig,
+  OneBotV12Event as ImHelperOneBotV12Event,
+  OneBotV12Response,
+} from '@imhelper/onebot-v12';
+export { ProtocolError } from '@imhelper/onebot-v12';
+export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';

package/src/protocol.ts

@@ -78,7 +78,7 @@ export interface OneBot12Event {
   type: 'meta' | 'message' | 'notice' | 'request';
   detail_type: string;
   sub_type: string;
-  self?: OneBot12Self;
+  self: OneBot12Self;
   message_id?: string;
   message?: OneBot12Segment[];
   alt_message?: string;
@@ -226,7 +226,7 @@ export function onebot12InboundConversation(endpointKey: string, ev: OneBot12Eve
   };
 }
 
-/** Build inbound text for MessageGateway.receive */
+/** Build inbound text for OutboundMessageService.receive */
 export function formatInboundContent(ev: OneBot12Event): string {
   if (Array.isArray(ev.message)) {
     return ev.message

package/src/side-event-dispatch.ts

@@ -1,5 +1,5 @@
 import { receiveOneBotLikeSideEvent } from '@zhin.js/core';
-import type { SideEventGateway } from '@zhin.js/core/runtime';
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
 import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
 import type { OneBot12Event } from './protocol.js';
 
@@ -8,19 +8,19 @@ export interface OneBot12SideEventCaller {
 }
 
 export function receiveOneBot12SideEvent(
-  sideEvents: SideEventGateway | undefined,
+  emit: EndpointEventEmitter,
   endpointKey: string,
   caller: OneBot12SideEventCaller,
   raw: OneBot12Event,
   logger: ReturnType<typeof getAdapterLogger>,
 ): void {
-  if (!sideEvents) return;
+  if (!emit) return;
   const record = raw as Record<string, unknown>;
   const eventType = String(record.type ?? record.post_type ?? '');
   const detailType = String(record.detail_type ?? '');
   const isRequest = eventType === 'request' || eventType.startsWith('request.');
   const isFriend = detailType.includes('friend') || String(record.request_type ?? '') === 'friend';
-  void receiveOneBotLikeSideEvent(sideEvents, {
+  void receiveOneBotLikeSideEvent(emit, {
     adapter: 'onebot12',
     endpointKey,
     platform: 'onebot',