@zhin.js/adapter-onebot11 1.1.17 → 1.1.19

package/lib/side-event-dispatch.d.ts

@@ -4,4 +4,11 @@ import type { OneBot11Event } from './protocol.js';
 export interface OneBot11SideEventCaller {
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
 }
-export declare function receiveOneBot11SideEvent(emit: EndpointEventEmitter, endpointKey: string, caller: OneBot11SideEventCaller, raw: OneBot11Event, logger: ReturnType<typeof getAdapterLogger>): void;
+/** Exact instance-owned dependencies for one canonical side-event projection. */
+export interface OneBot11SideEventContext {
+    readonly emit: EndpointEventEmitter;
+    readonly endpointKey: string;
+    readonly caller: OneBot11SideEventCaller;
+    readonly logger: ReturnType<typeof getAdapterLogger>;
+}
+export declare function receiveOneBot11SideEvent(raw: OneBot11Event, context: OneBot11SideEventContext): void;

package/lib/side-event-dispatch.js

@@ -1,6 +1,7 @@
 import { receiveOneBotLikeSideEvent } from '@zhin.js/core';
 import { formatCompact } from '@zhin.js/logger';
-export function receiveOneBot11SideEvent(emit, endpointKey, caller, raw, logger) {
+export function receiveOneBot11SideEvent(raw, context) {
+    const { emit, endpointKey, caller, logger } = context;
     if (!emit)
         return;
     const record = raw;

package/lib/ws-endpoint.d.ts

@@ -1,25 +1,18 @@
-import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
+import { endpointSpec, type Endpoint, type EndpointSpecification } from 'zhin.js/adapter';
 import type { CapabilityId } from 'zhin.js';
 import { type OneBot11WsConfig } from './protocol.js';
 import { type OneBot11WsCreateOptions, type OneBot11WsSocket } from './ws-types.js';
-import { type Onebot11Client } from './client.js';
+import { Onebot11Client } from './client.js';
 export interface OneBot11WsEndpointOptions {
+    readonly signal?: AbortSignal;
     readonly id: CapabilityId;
     /** 连接后 best-effort 调用 get_login_info 上报账号（Adapter 工厂开启；默认关闭以免占用首个 echo）。 */
     readonly probeLoginInfo?: boolean;
     readonly config: OneBot11WsConfig;
     readonly createWebSocket?: (url: string, options: OneBot11WsCreateOptions) => OneBot11WsSocket;
 }
-export declare class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
+export declare class OneBot11WsEndpoint extends Onebot11Client implements Endpoint {
     #private;
-    readonly client: Onebot11Client;
-    readonly management: EndpointManagement;
-    readonly control: EndpointControl;
-    readonly content: import("@zhin.js/adapter").EndpointContentPort;
+    readonly [endpointSpec]: EndpointSpecification;
     constructor(options: OneBot11WsEndpointOptions);
-    get transportState(): EndpointTransportState;
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    recallMessage(messageId: string): Promise<void>;
 }

package/lib/ws-endpoint.js

@@ -3,39 +3,59 @@ import { EndpointDeliveryError } from '@zhin.js/im-contract';
  * OneBot11 WS client endpoint — outbound connect to OneBot implementation.
  */
 import WebSocket from 'ws';
-import { ClientEndpoint, createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
+import { createEndpointSpecification, endpointSpec, createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createOneBot11EndpointManagement } from './endpoint-management.js';
 import { buildSendAction, buildWsConnectOptions, formatInboundContent, formatInboundMetadata, formatOutboundSegments, isMessageEvent, onebot11InboundConversation, senderDisplayName, senderUserId, } from './protocol.js';
 import { receiveOneBot11SideEvent } from './side-event-dispatch.js';
 import { createOneBot11ContentPort } from './content-port.js';
-import { callOneBot11WsAction, handleOneBot11WsMessage, rejectAllPending, } from './ws-transport.js';
+import { createOneBot11Rpc } from './ws-transport.js';
 import { probeOnebot11SelfId, resolveOnebot11SelfId } from './self-id.js';
-import { callOnebot11Client, createOnebot11EndpointClient, forwardOnebot11ClientEvents } from './client.js';
-export class OneBot11WsEndpoint extends ClientEndpoint {
-    client;
+import { callOnebot11Client, readOnebot11Response, onebot11ClientOptions, forwardOnebot11ClientEvents, Onebot11Client } from './client.js';
+export class OneBot11WsEndpoint extends Onebot11Client {
+    [endpointSpec];
+    #open = false;
     #logger;
     #options;
-    management;
-    control = createRecallEndpointControl((id) => this.recallMessage(id));
-    content;
+    #management;
+    #control = createRecallEndpointControl((id, signal) => this.#recallMessage(id, signal));
+    #content;
+    #releaseClientEvents;
     #lifecycle;
     #ws;
     #stopped = false;
-    #requestId = { value: 0 };
-    #pending = new Map();
+    #rpc;
     constructor(options) {
-        super();
+        const rpc = createOneBot11Rpc({ endpointId: options.config.id, signal: options.signal,
+            socket: () => this.#lifecycle.state === 'open' ? this.#ws : undefined,
+        });
+        super(onebot11ClientOptions(options.config, (action, params) => rpc.call({ action, params })));
+        this.#rpc = rpc;
         this.#logger = getAdapterLogger('onebot11', options.config.id);
         this.#options = options;
-        this.client = createOnebot11EndpointClient(options.config, (action, params) => this.#callApi(action, params));
-        const callApi = (action, params) => callOnebot11Client(this.client, action, params);
-        this.management = createOneBot11EndpointManagement({ callApi });
-        this.content = createOneBot11ContentPort(callApi);
-        this.bindClientEvents((receive) => forwardOnebot11ClientEvents(this.client, receive), (name, payload) => {
-            if (name === 'event')
-                this.#admitRaw(payload);
-        }, (_name, error) => this.#warnPlatformEvent(error));
+        const callApi = (request) => this.#rpc.call(request).then(readOnebot11Response);
+        this.#management = createOneBot11EndpointManagement({ callApi });
+        this.#content = createOneBot11ContentPort(callApi);
+        const readTransportState = () => this.#lifecycle.state;
+        this[endpointSpec] = createEndpointSpecification(this, {
+            name: options.config.id,
+            start: () => this.#start(), open: () => { this.#open = true; },
+            close: () => { this.#open = false; }, stop: () => this.#stop(),
+            send: request => this.#send(request),
+            get transportState() { return readTransportState(); },
+            management: this.#management, control: this.#control, content: this.#content,
+        });
+        this.#releaseClientEvents = forwardOnebot11ClientEvents(this, (name, payload) => {
+            void this[endpointSpec].events.run(() => {
+                // A native frame can arrive before start resolves. The spec owns candidate
+                // buffering and Root/child admission; transport start is not publication.
+                if (this.#stopped || (!this.#open && !this.#lifecycle.started))
+                    return;
+                void this[endpointSpec].events.platform(name, payload).catch(error => this.#warnPlatformEvent(error));
+                if (name === 'event')
+                    this.#admitRaw(payload);
+            }).catch(error => this.#warnPlatformEvent(error));
+        });
         const { config } = options;
         this.#lifecycle = createEndpointLifecycle({
             name: config.id,
@@ -49,10 +69,10 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
             heartbeat: { intervalMs: config.heartbeat_interval, watchdogMisses: 2 },
         });
     }
-    get transportState() {
+    get #transportState() {
         return this.#lifecycle.state;
     }
-    async start() {
+    async #start() {
         if (this.#lifecycle.started)
             return;
         this.#stopped = false;
@@ -75,19 +95,24 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
             throw err;
         }
     }
-    async stop() {
+    async #stop() {
         this.#stopped = true;
-        this.close();
+        this.#open = false;
         // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
-        await this.#lifecycle.stop();
-        rejectAllPending(this.#pending);
-        this.#ws = undefined;
-        this.reportSelfUserId(undefined);
+        try {
+            await this.#lifecycle.stop();
+        }
+        finally {
+            this.#rpc.dispose();
+            this.#releaseClientEvents();
+            this.#ws = undefined;
+            this[endpointSpec].reportSelfUserId(undefined);
+        }
     }
-    async send({ conversation, payload }) {
+    async #send({ conversation, payload, signal }) {
         const message = formatOutboundSegments(payload);
         const { action, params } = buildSendAction(conversation, message);
-        const data = await callOnebot11Client(this.client, action, params);
+        const data = readOnebot11Response(await this.#rpc.call({ action, params, signal }));
         const rawId = data?.message_id;
         if ((typeof rawId !== 'number' && typeof rawId !== 'string') || String(rawId).trim() === '' || (typeof rawId === 'number' && !Number.isFinite(rawId))) {
             throw new EndpointDeliveryError('delivery_unconfirmed', 'Message delivery is unconfirmed: platform returned no message_id', 'unknown');
@@ -101,26 +126,30 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
         }));
         return messageId;
     }
-    async recallMessage(messageId) {
+    async #recallMessage(messageId, signal) {
         if (!messageId)
             return;
-        await callOnebot11Client(this.client, 'delete_msg', { message_id: Number(messageId) });
-    }
-    #callApi(action, params = {}) {
-        return callOneBot11WsAction(this.#lifecycle.state === 'open' ? this.#ws : undefined, this.#pending, this.#requestId, action, params);
+        await this.#rpc.call({ action: 'delete_msg', params: { message_id: Number(messageId) }, signal }).then(readOnebot11Response);
     }
     #admitRaw(ev) {
         const selfId = resolveOnebot11SelfId(ev.self_id);
-        if (!this.#stopped && selfId && selfId !== this.selfUserId)
-            this.reportSelfUserId(selfId);
+        if (!this.#stopped && selfId)
+            this[endpointSpec].reportSelfUserId(selfId);
         if (!isMessageEvent(ev)) {
-            receiveOneBot11SideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, { callApi: (action, params) => callOnebot11Client(this.client, action, params) }, ev, this.#logger);
+            receiveOneBot11SideEvent(ev, {
+                emit: (name, payload) => this[endpointSpec].events.emit(name, payload),
+                endpointKey: this.#options.config.id,
+                caller: { callApi: (action, params) => callOnebot11Client({ client: this, action, params }) },
+                logger: this.#logger,
+            });
             return;
         }
-        const conversation = onebot11InboundConversation(String(this.#options.id), ev);
+        const conversation = { ...onebot11InboundConversation(String(this.#options.id), ev), endpoint: this[endpointSpec].identity };
         const content = formatInboundContent(ev);
         const inbound = formatInboundMetadata(ev, this.#options.config.id);
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.message({
+            event: ev,
+            ...(typeof ev.time === 'number' ? { platformSentAt: ev.time * 1000 } : {}),
             conversation,
             message: { conversation, id: String(ev.message_id) },
             content,
@@ -143,16 +172,16 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
     }
     /** Best-effort 登录账号探测；失败仅 debug，不影响连接。 */
     async #probeSelfUserId() {
-        const selfId = await probeOnebot11SelfId(this.client, (error) => {
+        const selfId = await probeOnebot11SelfId(this, (error) => {
             this.#logger.debug(formatCompact({
                 op: 'onebot11_get_login_info_failed',
                 error: error instanceof Error ? error.message : String(error),
             }));
         });
-        if (this.#stopped || this.transportState !== 'open')
+        if (this.#stopped || this.#transportState !== 'open')
             return;
-        if (selfId && selfId !== this.selfUserId)
-            this.reportSelfUserId(selfId);
+        if (selfId)
+            this[endpointSpec].reportSelfUserId(selfId);
     }
     #warnPlatformEvent(error) {
         this.#logger.warn(formatCompact({
@@ -170,7 +199,7 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
             this.#ws = ws;
             handle.onForceClose(() => {
                 if (this.#ws === ws) {
-                    rejectAllPending(this.#pending);
+                    this.#rpc.disconnect();
                 }
                 try {
                     ws.close();
@@ -206,17 +235,13 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
                 if (this.#ws !== ws || ws.readyState !== 1 || !this.#lifecycle.started)
                     return;
                 this.#lifecycle.notifyHeartbeatAck();
-                handleOneBot11WsMessage(data, {
-                    endpointId: this.#options.config.id,
-                    pending: this.#pending,
-                    ingest: (ev) => this.client.ingest(ev),
-                });
+                this.#rpc.receive(data, (ev) => this.ingest(ev));
             });
             ws.on('close', (code, reason) => {
                 if (this.#ws !== ws)
                     return;
                 this.#ws = undefined;
-                rejectAllPending(this.#pending);
+                this.#rpc.disconnect();
                 const reasonStr = typeof reason === 'string'
                     ? reason
                     : Buffer.isBuffer(reason)

package/lib/ws-transport.d.ts

@@ -1,12 +1,19 @@
-import { type OneBot11ActionResponse, type OneBot11Event } from './protocol.js';
-import { type OneBot11PendingAction, type OneBot11WsSocket } from './ws-types.js';
-export declare function decodeWsPayload(data: unknown): string;
-export declare function handleOneBot11WsMessage(data: unknown, options: {
+import { type PendingRpc, type PendingRpcRequest } from 'zhin.js/adapter';
+import type { OneBot11ActionResponse, OneBot11Event } from './protocol.js';
+import { type OneBot11WsSocket } from './ws-types.js';
+export interface OneBot11RpcOptions {
     readonly endpointId: string;
-    readonly pending: Map<string, OneBot11PendingAction>;
-    readonly ingest: (ev: OneBot11Event) => void;
-}): void;
-export declare function callOneBot11WsAction(ws: OneBot11WsSocket | undefined, pending: Map<string, OneBot11PendingAction>, requestId: {
-    value: number;
-}, action: string, params: Record<string, unknown>): Promise<OneBot11ActionResponse>;
-export declare function rejectAllPending(pending: Map<string, OneBot11PendingAction>, message?: string): void;
+    readonly signal?: AbortSignal;
+    /** Reads the lifecycle's selected socket; RPC never opens or reconnects it. */
+    readonly socket: () => OneBot11WsSocket | undefined;
+}
+export interface OneBot11Rpc {
+    call(request: PendingRpcRequest): Promise<OneBot11ActionResponse>;
+    receive(data: unknown, ingest: (event: OneBot11Event) => void): void;
+    disconnect: PendingRpc<OneBot11ActionResponse>['disconnect'];
+    dispose(): void;
+    readonly pendingCount: number;
+}
+/** A Client's one request owner serves native SDK actions and framework operations. */
+export declare function createOneBot11Rpc(options: OneBot11RpcOptions): OneBot11Rpc;
+export declare function decodeWsPayload(data: unknown): string;

package/lib/ws-transport.js

@@ -1,8 +1,33 @@
-import { EndpointDeliveryError } from '@zhin.js/im-contract';
-import { clearTimeout, setTimeout } from 'node:timers';
+import { createPendingRpc } from 'zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { WS_OPEN, } from './ws-types.js';
+import { WS_OPEN } from './ws-types.js';
 const logger = getLogger('onebot11');
+/** A Client's one request owner serves native SDK actions and framework operations. */
+export function createOneBot11Rpc(options) {
+    const pending = createPendingRpc({
+        signal: options.signal, requestPrefix: 'ob11_', timeoutMs: 30_000,
+        transport: () => { const socket = options.socket(); return socket?.readyState === WS_OPEN ? socket : undefined; },
+        serialize: request => JSON.stringify({ action: request.action, params: request.params ?? {}, echo: request.id }),
+    });
+    return Object.freeze({
+        call: pending.call, disconnect: pending.disconnect, dispose: pending.dispose,
+        get pendingCount() { return pending.pendingCount; },
+        receive(data, ingest) {
+            try {
+                const message = JSON.parse(decodeWsPayload(data));
+                if ('echo' in message && typeof message.echo === 'string') {
+                    pending.accept({ id: message.echo, value: message });
+                    return;
+                }
+                ingest(message);
+            }
+            catch (error) {
+                logger.warn(formatCompact({ op: 'onebot11_parse_failed', endpoint: options.endpointId,
+                    error: error instanceof Error ? error.message : String(error) }));
+            }
+        },
+    });
+}
 export function decodeWsPayload(data) {
     if (typeof data === 'string')
         return data;
@@ -12,56 +37,3 @@ export function decodeWsPayload(data) {
         return new TextDecoder().decode(data);
     return String(data ?? '');
 }
-export function handleOneBot11WsMessage(data, options) {
-    try {
-        const raw = decodeWsPayload(data);
-        const msg = JSON.parse(raw);
-        if ('echo' in msg && typeof msg.echo === 'string') {
-            const resp = msg;
-            const pending = options.pending.get(resp.echo);
-            if (pending) {
-                options.pending.delete(resp.echo);
-                clearTimeout(pending.timeout);
-                pending.resolve(resp);
-            }
-            return;
-        }
-        options.ingest(msg);
-    }
-    catch (error) {
-        logger.warn(formatCompact({
-            op: 'onebot11_parse_failed',
-            endpoint: options.endpointId,
-            error: error instanceof Error ? error.message : String(error),
-        }));
-    }
-}
-export function callOneBot11WsAction(ws, pending, requestId, action, params) {
-    if (!ws || ws.readyState !== WS_OPEN) {
-        return Promise.reject(new EndpointDeliveryError('endpoint_disconnected', 'WebSocket 未连接', 'not_sent'));
-    }
-    const echo = `ob11_${++requestId.value}`;
-    const req = { action, params, echo };
-    return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-            pending.delete(echo);
-            reject(new EndpointDeliveryError('endpoint_timeout', `OneBot11 动作超时: ${action}`, 'unknown'));
-        }, 30_000);
-        pending.set(echo, { resolve, reject, timeout });
-        try {
-            ws.send(JSON.stringify(req));
-        }
-        catch (error) {
-            pending.delete(echo);
-            clearTimeout(timeout);
-            reject(error instanceof Error ? error : new Error(String(error)));
-        }
-    });
-}
-export function rejectAllPending(pending, message = '连接已关闭') {
-    for (const [, entry] of pending) {
-        clearTimeout(entry.timeout);
-        entry.reject(new EndpointDeliveryError('endpoint_disconnected', message, 'unknown'));
-    }
-    pending.clear();
-}

package/lib/ws-types.d.ts

@@ -10,9 +10,3 @@ export interface OneBot11WsCreateOptions {
     readonly headers?: Record<string, string>;
 }
 export declare const WS_OPEN = 1;
-export interface OneBot11PendingAction {
-    resolve: (value: OneBot11ActionResponse) => void;
-    reject: (err: Error) => void;
-    timeout: NodeJS.Timeout;
-}
-import type { OneBot11ActionResponse } from './protocol.js';

package/lib/wss-endpoint.d.ts

@@ -1,28 +1,21 @@
 /**
  * OneBot11 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
  */
-import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
+import { endpointSpec, type Endpoint, type EndpointSpecification } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type OneBot11WssConfig } from './protocol.js';
-import { type Onebot11Client } from './client.js';
+import { Onebot11Client } from './client.js';
 export interface OneBot11WssEndpointOptions {
+    readonly signal?: AbortSignal;
     readonly id: CapabilityId;
     /** 连接后 best-effort 调用 get_login_info 上报账号（Adapter 工厂开启）。 */
     readonly probeLoginInfo?: boolean;
     readonly http: HttpHost;
     readonly config: OneBot11WssConfig;
 }
-export declare class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
+export declare class OneBot11WssEndpoint extends Onebot11Client implements Endpoint {
     #private;
-    readonly client: Onebot11Client;
-    readonly management: EndpointManagement;
-    readonly control: EndpointControl;
-    readonly content: import("@zhin.js/adapter").EndpointContentPort;
+    readonly [endpointSpec]: EndpointSpecification;
     constructor(options: OneBot11WssEndpointOptions);
-    get transportState(): EndpointTransportState;
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    recallMessage(messageId: string): Promise<void>;
 }