@zhin.js/adapter-onebot12 1.0.0 → 1.1.0

package/lib/webhook.js

@@ -0,0 +1,161 @@
+import { ClientEndpoint, createRecallEndpointControl, } from 'zhin.js/adapter';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { createOneBot12EndpointManagement } from './endpoint-management.js';
+import { buildSendMessageParams, callOneBot12Action, 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';
+const logger = getLogger('onebot12');
+export class OneBot12WebhookEndpoint extends ClientEndpoint {
+    client;
+    #options;
+    management;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    content;
+    #callAction;
+    #routeReleases = [];
+    #started = false;
+    constructor(options) {
+        super();
+        this.#options = options;
+        this.#callAction = options.callAction ?? callOneBot12Action;
+        this.client = createOnebot12EndpointClient(options.config, (action, params) => this.#callApi(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) {
+            // webhook 模式未配 access_token 时任何 POST 都会被放行（verifyOneBotAccessToken 直接 return true）
+            logger.warn(formatCompact({
+                endpoint: this.#options.config.id,
+                mode: 'webhook',
+                ok: false,
+                error: 'missing access_token',
+            }));
+        }
+        this.#setupRoutes();
+        logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.id,
+            mode: 'webhook',
+            path: this.#options.config.path,
+        }));
+    }
+    async stop() {
+        this.close();
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.id }));
+    }
+    async send({ conversation, payload }) {
+        const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => callOnebot12Client(this.client, action, params), (error) => {
+            logger.warn(formatCompact({
+                op: 'onebot12_upload_failed',
+                endpoint: this.#options.config.id,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        const message = formatOutboundSegments(materialized);
+        const params = buildSendMessageParams(conversation, message);
+        const data = await callOnebot12Client(this.client, 'send_message', params);
+        const messageId = data?.message_id ?? '';
+        logger.debug(formatCompact({
+            op: 'onebot12_send',
+            endpoint: this.#options.config.id,
+            kind: conversation.kind,
+            conversationId: conversation.id,
+            messageId,
+        }));
+        return messageId;
+    }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
+    }
+    async #callApi(action, params = {}) {
+        const apiUrl = this.#options.config.api_url;
+        if (!apiUrl) {
+            throw new Error('OneBot12 connection:webhook requires api_url for outbound api');
+        }
+        return this.#callAction({ url: apiUrl, access_token: this.#options.config.access_token }, action, params);
+    }
+    #admitRaw(ev) {
+        if (!isMessageEvent(ev)) {
+            receiveOneBot12SideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, { callApi: (action, params) => callOnebot12Client(this.client, action, params) }, ev, logger);
+            return;
+        }
+        const conversation = onebot12InboundConversation(String(this.#options.id), ev);
+        const content = formatInboundContent(ev);
+        const nickname = senderNickname(ev);
+        const mentioned = isBotMentioned(ev);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: ev.message_id },
+            content,
+            sender: { id: senderUserId(ev), ...(nickname ? { name: nickname } : {}) },
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                detail_type: ev.detail_type,
+                user_id: ev.user_id,
+                group_id: ev.group_id,
+                channel_id: ev.channel_id,
+                guild_id: ev.guild_id,
+                time: ev.time,
+                ...(nickname ? { nickname } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'onebot12_gateway_receive_failed',
+                kind: conversation.kind,
+                conversationId: conversation.id,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #warnPlatformEvent(error) {
+        logger.warn(formatCompact({
+            op: 'onebot12_platform_event_failed',
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    }
+    #setupRoutes() {
+        const path = this.#options.config.path;
+        this.#routeReleases.push(this.#options.http.route('POST', path, async (request, response) => {
+            await this.#handleWebhook(request, response);
+        }, { summary: 'OneBot12 webhook callback', tags: ['onebot12'] }));
+    }
+    async #handleWebhook(request, response) {
+        try {
+            if (!verifyOneBotAccessToken(this.#options.config.access_token, request)) {
+                response.writeHead(403, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ message: 'Unauthorized' }));
+                return;
+            }
+            if (!this.clientEventsOpen) {
+                response.writeHead(200, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ status: 'ok' }));
+                return;
+            }
+            await this.client.acceptHttp(request, response);
+        }
+        catch (error) {
+            logger.error('OneBot12 webhook error:', error);
+            if (!response.headersSent) {
+                response.writeHead(500, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ message: 'Internal Server Error' }));
+            }
+        }
+    }
+}

package/lib/ws-endpoint.d.ts

@@ -0,0 +1,22 @@
+import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { CapabilityId } from 'zhin.js';
+import { type OneBot12WsConfig } from './protocol.js';
+import { type Onebot12Client } from './client.js';
+import { type OneBot12WsCreateOptions, type OneBot12WsSocket } from './ws-types.js';
+export interface OneBot12WsEndpointOptions {
+    readonly id: CapabilityId;
+    readonly config: OneBot12WsConfig;
+    readonly createWebSocket?: (url: string, options: OneBot12WsCreateOptions) => OneBot12WsSocket;
+}
+export declare class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
+    #private;
+    readonly client: Onebot12Client;
+    readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
+    constructor(options: OneBot12WsEndpointOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
+}

package/lib/ws-endpoint.js

@@ -0,0 +1,255 @@
+/**
+ * OneBot12 WS client endpoint — outbound connect to OneBot implementation.
+ */
+import WebSocket from 'ws';
+import { clearTimeout } from 'node:timers';
+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 extends ClientEndpoint {
+    client;
+    #logger;
+    #options;
+    management;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    content;
+    #lifecycle;
+    #ws;
+    #requestId = 0;
+    #pending = new Map();
+    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,
+            reconnect: {
+                initialIntervalMs: config.reconnect_interval,
+                // 固定间隔（multiplier 1、无抖动），对齐旧 reconnect_interval 语义
+                multiplier: 1,
+                maxIntervalMs: config.reconnect_interval,
+                jitterMs: 0,
+            },
+            heartbeat: { intervalMs: config.heartbeat_interval },
+        });
+    }
+    async start() {
+        if (this.#lifecycle.started)
+            return;
+        try {
+            await this.#lifecycle.start((handle) => this.#connect(handle));
+        }
+        catch (err) {
+            // start 失败必须清理现场（状态复位由基座保证）
+            if (this.#ws) {
+                try {
+                    this.#ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                this.#ws = undefined;
+            }
+            throw err;
+        }
+    }
+    async stop() {
+        this.close();
+        // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
+        await this.#lifecycle.stop();
+        for (const [, pending] of this.#pending) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error('连接已关闭'));
+        }
+        this.#pending.clear();
+        this.#ws = undefined;
+    }
+    async send({ conversation, payload }) {
+        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,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        const message = formatOutboundSegments(materialized);
+        const params = buildSendMessageParams(conversation, message);
+        const data = await callOnebot12Client(this.client, 'send_message', params);
+        const messageId = data?.message_id ?? '';
+        this.#logger.debug(formatCompact({
+            op: 'onebot12_send',
+            endpoint: this.#options.config.id,
+            kind: conversation.kind,
+            conversationId: conversation.id,
+            messageId,
+        }));
+        return messageId;
+    }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
+    }
+    #admitRaw(ev) {
+        if (!isMessageEvent(ev)) {
+            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.emit('message.receive', {
+            conversation,
+            message: { conversation, id: ev.message_id },
+            content,
+            sender: { id: senderUserId(ev), name: senderNickname(ev) },
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                detail_type: ev.detail_type,
+                user_id: ev.user_id,
+                group_id: ev.group_id,
+                channel_id: ev.channel_id,
+                guild_id: ev.guild_id,
+                time: ev.time,
+                ...(nickname ? { nickname } : {}),
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'onebot12_gateway_receive_failed',
+                kind: conversation.kind,
+                conversationId: conversation.id,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #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
+            ?? ((connectUrl, options) => new WebSocket(connectUrl, { headers: options.headers }));
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const ws = create(url, { headers });
+            this.#ws = ws;
+            handle.onForceClose(() => {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            });
+            ws.on('open', () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.#logger.debug(formatCompact({
+                    endpoint: this.#options.config.id,
+                    mode: 'ws',
+                    url: safeUrl,
+                }));
+                this.#lifecycle.startHeartbeat(() => {
+                    this.#callAction('get_status', {}).catch(() => { });
+                });
+                resolve();
+            });
+            ws.on('message', (data) => {
+                this.#onMessage(data);
+            });
+            ws.on('close', (code, reason) => {
+                const reasonStr = typeof reason === 'string'
+                    ? reason
+                    : Buffer.isBuffer(reason)
+                        ? reason.toString()
+                        : String(reason ?? '');
+                const codeNum = typeof code === 'number' ? code : Number(code ?? 0);
+                if (!settled) {
+                    settled = true;
+                    reject(new Error(`OneBot12 WS 关闭: ${codeNum} ${reasonStr}`));
+                }
+                // 断开日志与重连武装均由基座负责；仅曾 open 的连接才会武装重连，
+                // 初始连接失败由 start() 的拒绝路径复位，不产生僵尸重连。
+                handle.notifyClosed(`OneBot12 WS 关闭: ${codeNum} ${reasonStr || 'closed'}`);
+            });
+            ws.on('error', (err) => {
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.#logger.warn(formatCompact({
+                    op: 'ws_error',
+                    endpoint: this.#options.config.id,
+                    ok: false,
+                    error: error.message,
+                }));
+                if (!settled) {
+                    settled = true;
+                    reject(error);
+                }
+            });
+        });
+    }
+    #onMessage(data) {
+        try {
+            const raw = typeof data === 'string'
+                ? data
+                : Buffer.isBuffer(data)
+                    ? data.toString()
+                    : data instanceof ArrayBuffer
+                        ? new TextDecoder().decode(data)
+                        : String(data ?? '');
+            const msg = JSON.parse(raw);
+            if ('echo' in msg && typeof msg.echo === 'string') {
+                const resp = msg;
+                const pending = this.#pending.get(resp.echo);
+                if (pending) {
+                    this.#pending.delete(resp.echo);
+                    clearTimeout(pending.timeout);
+                    pending.resolve(resp);
+                }
+                return;
+            }
+            this.client.ingest(msg);
+        }
+        catch (error) {
+            this.#logger.warn(formatCompact({
+                op: 'onebot12_parse_failed',
+                endpoint: this.#options.config.id,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+    #callAction(action, params) {
+        if (!this.#ws || this.#ws.readyState !== WS_OPEN) {
+            return Promise.reject(new Error('WebSocket 未连接'));
+        }
+        const echo = `ob12_${++this.#requestId}`;
+        const req = { action, params, echo };
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.#pending.delete(echo);
+                reject(new Error(`OneBot12 动作超时: ${action}`));
+            }, 30_000);
+            this.#pending.set(echo, { resolve, reject, timeout });
+            this.#ws.send(JSON.stringify(req));
+        });
+    }
+}

package/lib/ws-types.d.ts

@@ -0,0 +1,16 @@
+/** Minimal WS surface used by the endpoint (real `ws` or test mock). */
+export interface OneBot12WsSocket {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    on(event: 'open' | 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+}
+export interface OneBot12WsCreateOptions {
+    readonly headers?: Record<string, string>;
+}
+export declare const WS_OPEN = 1;
+export interface OneBot12PendingAction {
+    resolve: (value: unknown) => void;
+    reject: (err: Error) => void;
+    timeout: NodeJS.Timeout;
+}

package/lib/ws-types.js

@@ -0,0 +1 @@
+export const WS_OPEN = 1;

package/lib/wss-auth.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingMessage } from 'node:http';
+export declare function verifyOneBotAccessToken(accessToken: string | undefined, request: IncomingMessage): boolean;

package/lib/wss-auth.js

@@ -0,0 +1,16 @@
+export function verifyOneBotAccessToken(accessToken, request) {
+    if (!accessToken)
+        return true;
+    const auth = request.headers.authorization ?? '';
+    if (auth === `Bearer ${accessToken}`)
+        return true;
+    try {
+        const url = new URL(request.url ?? '/', 'http://localhost');
+        if (url.searchParams.get('access_token') === accessToken)
+            return true;
+    }
+    catch {
+        /* ignore */
+    }
+    return false;
+}

package/lib/wss-endpoint.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 OneBot12WssConfig } from './protocol.js';
+import { type Onebot12Client } from './client.js';
+export interface OneBot12WssEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly config: OneBot12WssConfig;
+}
+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>;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
+}