@zhin.js/adapter-onebot12 3.0.2 → 3.0.3

package/lib/protocol.d.ts

@@ -0,0 +1,151 @@
+/**
+ * OneBot 12 protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ * Spec: https://12.onebot.dev/
+ */
+/** Transitional legacy endpoint row (`endpoints[]` with `context: onebot12`). */
+export interface OneBot12LegacyEndpointRow {
+    readonly context?: string;
+    readonly connection?: 'ws' | 'webhook' | 'wss';
+    readonly name?: string;
+    readonly access_token?: string;
+    readonly url?: string;
+    readonly path?: string;
+    readonly api_url?: string;
+    readonly reconnect_interval?: number;
+    readonly heartbeat_interval?: number;
+}
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface OneBot12AdapterConfig {
+    readonly connection?: 'ws' | 'webhook' | 'wss';
+    readonly name?: string;
+    readonly access_token?: string;
+    readonly url?: string;
+    readonly path?: string;
+    readonly api_url?: string;
+    readonly reconnect_interval?: number;
+    readonly heartbeat_interval?: number;
+    /** Transitional: legacy root `endpoints[]` with `context: onebot12`. */
+    readonly endpoints?: ReadonlyArray<OneBot12LegacyEndpointRow>;
+}
+export interface OneBot12ConfigBase {
+    readonly context: 'onebot12';
+    readonly name: string;
+    readonly access_token?: string;
+}
+/** 正向 WebSocket：应用连 OneBot 实现的 WS 服务器 */
+export interface OneBot12WsConfig extends OneBot12ConfigBase {
+    readonly connection: 'ws';
+    readonly url: string;
+    readonly reconnect_interval: number;
+    readonly heartbeat_interval: number;
+}
+/** HTTP Webhook：httpHostToken POST 入站 + api_url HTTP 出站 */
+export interface OneBot12WebhookConfig extends OneBot12ConfigBase {
+    readonly connection: 'webhook';
+    readonly path: string;
+    readonly api_url?: string;
+}
+/** 反向 WebSocket：httpHostToken WS upgrade 入站/出站 */
+export interface OneBot12WssConfig extends OneBot12ConfigBase {
+    readonly connection: 'wss';
+    readonly path: string;
+    readonly heartbeat_interval: number;
+}
+export type ResolvedOneBot12Config = OneBot12WsConfig | OneBot12WebhookConfig | OneBot12WssConfig;
+export type OneBot12EndpointConfig = ResolvedOneBot12Config;
+export interface OneBot12Self {
+    readonly platform: string;
+    readonly user_id: string;
+}
+export interface OneBot12Event {
+    id: string;
+    time: number;
+    type: 'meta' | 'message' | 'notice' | 'request';
+    detail_type: string;
+    sub_type: string;
+    self?: OneBot12Self;
+    message_id?: string;
+    message?: OneBot12Segment[];
+    alt_message?: string;
+    user_id?: string;
+    group_id?: string;
+    channel_id?: string;
+    guild_id?: string;
+    [key: string]: unknown;
+}
+export interface OneBot12Segment {
+    type: string;
+    data?: Record<string, unknown>;
+}
+export interface OneBot12ActionRequest {
+    action: string;
+    params: Record<string, unknown>;
+    echo?: string;
+    self?: OneBot12Self;
+}
+export interface OneBot12ActionResponse {
+    status: 'ok' | 'failed';
+    retcode: number;
+    data?: unknown;
+    message: string;
+    echo?: string;
+}
+export interface OneBot12HttpOptions {
+    readonly url: string;
+    readonly access_token?: string;
+}
+export interface OneBot12WireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface ParsedSendTarget {
+    readonly detail_type: 'private' | 'group' | 'channel';
+    readonly id: string;
+    readonly guild_id?: string;
+}
+export declare function resolveOneBot12Config(config?: OneBot12AdapterConfig): ResolvedOneBot12Config;
+/** 判断是否为消息事件（type=message） */
+export declare function isMessageEvent(ev: OneBot12Event): ev is OneBot12Event & {
+    message_id: string;
+    message?: OneBot12Segment[];
+};
+/** 从事件得到场景 id：私聊 user_id，群 group_id，频道 channel_id 或 guild_id:channel_id */
+export declare function getChannelId(ev: OneBot12Event): string;
+/**
+ * Gateway reply target：`detail_type:channelId`，便于 send() 还原动作参数。
+ */
+export declare function formatInboundTarget(ev: OneBot12Event): string;
+export declare function parseSendTarget(target: string): ParsedSendTarget;
+/** Build inbound text for MessageGateway.receive */
+export declare function formatInboundContent(ev: OneBot12Event): string;
+/**
+ * Runtime Message sender 必须是用户 ID（agent bridge 以 sender 与 endpointMaster 比对）。
+ * 显示名经 {@link senderNickname} 放入 metadata.nickname。
+ */
+export declare function senderUserId(ev: OneBot12Event): string;
+/** 事件携带的发送者显示名（`user.name` / `qq.nickname`），没有则返回 undefined。 */
+export declare function senderNickname(ev: OneBot12Event): string | undefined;
+/**
+ * 判断入站消息是否 @ 了本机：OneBot12 提及段为 `{type:'mention', data:{user_id}}`，
+ * 目标 user_id 等于事件 self.user_id（self 为 {platform, user_id} 对象）时视为提及。
+ * 新 Plugin Runtime 的 Message.content 为纯文本，mention 信息只能经 metadata.mentioned 传递。
+ */
+export declare function isBotMentioned(ev: OneBot12Event): boolean;
+/**
+ * Wire-encode an already-rendered outbound payload into OneBot 12 message segments.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare function formatOutboundSegments(payload: unknown): OneBot12Segment[];
+export declare function buildSendMessageParams(target: string, message: OneBot12Segment[]): Record<string, unknown>;
+/**
+ * 向 OneBot 实现发送动作请求（HTTP POST），返回动作响应。
+ * 供 webhook 出站与纯协议测试使用；WS 路径走 WebSocket echo 请求。
+ */
+export declare function callOneBot12Action(options: OneBot12HttpOptions, action: string, params?: Record<string, unknown>, echo?: string): Promise<OneBot12ActionResponse>;
+/** Build WS connect URL + headers (access_token via Bearer + query). */
+export declare function buildWsConnectOptions(config: OneBot12WsConfig): {
+    readonly url: string;
+    readonly headers: Record<string, string>;
+    readonly safeUrl: string;
+};

package/lib/protocol.js

@@ -0,0 +1,242 @@
+/**
+ * OneBot 12 protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ * Spec: https://12.onebot.dev/
+ */
+export function resolveOneBot12Config(config = {}) {
+    const entry = config.endpoints?.find((item) => item.context === 'onebot12');
+    const connection = config.connection
+        ?? entry?.connection
+        ?? 'ws';
+    const name = (typeof config.name === 'string' && config.name)
+        || (typeof entry?.name === 'string' && entry.name)
+        || process.env.ONEBOT12_BOT_NAME
+        || 'onebot12-bot';
+    const access_token = config.access_token ?? entry?.access_token;
+    if (connection === 'ws') {
+        const url = config.url ?? entry?.url;
+        if (!url) {
+            throw new TypeError('OneBot12 connection:ws requires url (plugins.<key>.url or endpoints with context: onebot12)');
+        }
+        return {
+            context: 'onebot12',
+            connection: 'ws',
+            name,
+            access_token,
+            url,
+            reconnect_interval: config.reconnect_interval ?? entry?.reconnect_interval ?? 5000,
+            heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
+        };
+    }
+    if (connection === 'webhook') {
+        const path = config.path ?? entry?.path;
+        if (!path) {
+            throw new TypeError('OneBot12 connection:webhook requires path');
+        }
+        return {
+            context: 'onebot12',
+            connection: 'webhook',
+            name,
+            access_token,
+            path,
+            api_url: config.api_url ?? entry?.api_url,
+        };
+    }
+    if (connection === 'wss') {
+        const path = config.path ?? entry?.path;
+        if (!path) {
+            throw new TypeError('OneBot12 connection:wss requires path');
+        }
+        return {
+            context: 'onebot12',
+            connection: 'wss',
+            name,
+            access_token,
+            path,
+            heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
+        };
+    }
+    throw new TypeError(`Unknown OneBot12 connection: ${String(connection)}`);
+}
+/** 判断是否为消息事件（type=message） */
+export function isMessageEvent(ev) {
+    return ev.type === 'message' && !!ev.message_id;
+}
+/** 从事件得到场景 id：私聊 user_id，群 group_id，频道 channel_id 或 guild_id:channel_id */
+export function getChannelId(ev) {
+    if (ev.detail_type === 'private' && ev.user_id)
+        return ev.user_id;
+    if (ev.detail_type === 'group' && ev.group_id)
+        return ev.group_id;
+    if (ev.detail_type === 'channel' && ev.channel_id) {
+        return ev.guild_id ? `${ev.guild_id}:${ev.channel_id}` : ev.channel_id;
+    }
+    return ev.user_id ?? ev.group_id ?? '';
+}
+/**
+ * Gateway reply target：`detail_type:channelId`，便于 send() 还原动作参数。
+ */
+export function formatInboundTarget(ev) {
+    const detail = ev.detail_type === 'private' || ev.detail_type === 'group' || ev.detail_type === 'channel'
+        ? ev.detail_type
+        : 'private';
+    return `${detail}:${getChannelId(ev)}`;
+}
+export function parseSendTarget(target) {
+    const sep = target.indexOf(':');
+    if (sep <= 0) {
+        return { detail_type: 'private', id: target };
+    }
+    const head = target.slice(0, sep);
+    const rest = target.slice(sep + 1);
+    if (head === 'private' || head === 'group') {
+        return { detail_type: head, id: rest };
+    }
+    if (head === 'channel') {
+        const guildSep = rest.indexOf(':');
+        if (guildSep > 0) {
+            return {
+                detail_type: 'channel',
+                guild_id: rest.slice(0, guildSep),
+                id: rest.slice(guildSep + 1),
+            };
+        }
+        return { detail_type: 'channel', id: rest };
+    }
+    return { detail_type: 'private', id: target };
+}
+/** Build inbound text for MessageGateway.receive */
+export function formatInboundContent(ev) {
+    if (typeof ev.alt_message === 'string' && ev.alt_message)
+        return ev.alt_message;
+    if (Array.isArray(ev.message)) {
+        return ev.message
+            .map((seg) => (seg.type === 'text' ? String(seg.data?.text ?? '') : ''))
+            .join('');
+    }
+    return '';
+}
+/**
+ * Runtime Message sender 必须是用户 ID（agent bridge 以 sender 与 endpointMaster 比对）。
+ * 显示名经 {@link senderNickname} 放入 metadata.nickname。
+ */
+export function senderUserId(ev) {
+    return ev.user_id ?? '';
+}
+/** 事件携带的发送者显示名（`user.name` / `qq.nickname`），没有则返回 undefined。 */
+export function senderNickname(ev) {
+    const record = ev;
+    const name = record['user.name'] ?? record['qq.nickname'];
+    if (typeof name === 'string' && name)
+        return name;
+    return undefined;
+}
+/**
+ * 判断入站消息是否 @ 了本机：OneBot12 提及段为 `{type:'mention', data:{user_id}}`，
+ * 目标 user_id 等于事件 self.user_id（self 为 {platform, user_id} 对象）时视为提及。
+ * 新 Plugin Runtime 的 Message.content 为纯文本，mention 信息只能经 metadata.mentioned 传递。
+ */
+export function isBotMentioned(ev) {
+    const selfId = ev.self?.user_id;
+    if (!selfId || !Array.isArray(ev.message))
+        return false;
+    return ev.message.some((seg) => seg.type === 'mention' && String(seg.data?.['user_id'] ?? '') === selfId);
+}
+/**
+ * Wire-encode an already-rendered outbound payload into OneBot 12 message segments.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundSegments(payload) {
+    if (typeof payload === 'string') {
+        return [{ type: 'text', data: { text: payload } }];
+    }
+    const items = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    if (items.length === 0) {
+        const text = payload == null
+            ? ''
+            : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload);
+        return [{ type: 'text', data: { text } }];
+    }
+    const segs = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            segs.push({ type: 'text', data: { text: item } });
+            continue;
+        }
+        segs.push({ type: item.type, data: item.data ?? {} });
+    }
+    return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
+}
+export function buildSendMessageParams(target, message) {
+    const parsed = parseSendTarget(target);
+    const params = {
+        message,
+        detail_type: parsed.detail_type,
+    };
+    if (parsed.detail_type === 'private') {
+        params.user_id = parsed.id;
+    }
+    else if (parsed.detail_type === 'group') {
+        params.group_id = parsed.id;
+    }
+    else {
+        params.channel_id = parsed.id;
+        if (parsed.guild_id)
+            params.guild_id = parsed.guild_id;
+    }
+    return params;
+}
+/**
+ * 向 OneBot 实现发送动作请求（HTTP POST），返回动作响应。
+ * 供 webhook 出站与纯协议测试使用；WS 路径走 WebSocket echo 请求。
+ */
+export async function callOneBot12Action(options, action, params = {}, echo) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (options.access_token) {
+        headers.Authorization = `Bearer ${options.access_token}`;
+    }
+    const body = { action, params };
+    if (echo)
+        body.echo = echo;
+    const res = await fetch(options.url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (res.status === 401)
+        throw new Error(`OneBot12 鉴权失败: ${text}`);
+    if (res.status !== 200)
+        throw new Error(`OneBot12 HTTP ${res.status}: ${text}`);
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`OneBot12 无效响应: ${text.slice(0, 200)}`);
+    }
+    if (data.status === 'failed' && data.retcode !== 0) {
+        throw new Error(`OneBot12 动作失败 retcode=${data.retcode}: ${data.message}`);
+    }
+    return data;
+}
+/** Build WS connect URL + headers (access_token via Bearer + query). */
+export function buildWsConnectOptions(config) {
+    const headers = {};
+    let connectUrl = config.url;
+    if (config.access_token) {
+        headers.Authorization = `Bearer ${config.access_token}`;
+        const url = new URL(config.url);
+        url.searchParams.set('access_token', config.access_token);
+        connectUrl = url.toString();
+    }
+    const safeUrl = new URL(connectUrl);
+    safeUrl.searchParams.delete('access_token');
+    return { url: connectUrl, headers, safeUrl: safeUrl.toString() };
+}

package/lib/webhook.d.ts

@@ -0,0 +1,25 @@
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { callOneBot12Action, type OneBot12Event, type OneBot12WebhookConfig } from './protocol.js';
+export interface OneBot12WebhookEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly config: OneBot12WebhookConfig;
+    readonly callAction?: typeof callOneBot12Action;
+}
+export declare class OneBot12WebhookEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: OneBot12WebhookEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    admit(ev: OneBot12Event): void;
+}

package/lib/webhook.js

@@ -0,0 +1,140 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { buildSendMessageParams, callOneBot12Action, formatInboundContent, formatInboundTarget, formatOutboundSegments, isBotMentioned, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
+import { verifyOneBotAccessToken } from './wss-auth.js';
+const logger = getLogger('onebot12');
+export class OneBot12WebhookEndpoint {
+    #options;
+    #callAction;
+    #routeReleases = [];
+    #open = false;
+    #started = false;
+    constructor(options) {
+        this.#options = options;
+        this.#callAction = options.callAction ?? callOneBot12Action;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#setupRoutes();
+        logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.name,
+            mode: 'webhook',
+            path: this.#options.config.path,
+        }));
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const apiUrl = this.#options.config.api_url;
+        if (!apiUrl) {
+            throw new Error('OneBot12 connection:webhook requires api_url for outbound send');
+        }
+        const message = formatOutboundSegments(payload);
+        const params = buildSendMessageParams(target, message);
+        const resp = await this.#callAction({ url: apiUrl, access_token: this.#options.config.access_token }, 'send_message', params);
+        const data = resp.data;
+        const messageId = data?.message_id ?? '';
+        logger.debug(formatCompact({
+            op: 'onebot12_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId,
+        }));
+        return messageId;
+    }
+    admit(ev) {
+        if (!this.#open || !isMessageEvent(ev))
+            return;
+        const target = formatInboundTarget(ev);
+        const content = formatInboundContent(ev);
+        const nickname = senderNickname(ev);
+        const mentioned = isBotMentioned(ev);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content,
+            sender: senderUserId(ev),
+            id: ev.message_id,
+            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,
+                endpoint: this.#options.config.name,
+                time: ev.time,
+                ...(nickname ? { nickname } : {}),
+                ...(mentioned ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'onebot12_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #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;
+            }
+            const raw = await readRequestBody(request);
+            let ev;
+            try {
+                ev = JSON.parse(raw);
+            }
+            catch {
+                response.writeHead(400, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ message: 'Invalid JSON' }));
+                return;
+            }
+            if (this.#open)
+                this.admit(ev);
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ status: 'ok' }));
+        }
+        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' }));
+            }
+        }
+    }
+}
+async function readRequestBody(request) {
+    const chunks = [];
+    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/lib/ws-endpoint.d.ts

@@ -0,0 +1,25 @@
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { type OneBot12Event, type OneBot12WsConfig } from './protocol.js';
+import { type OneBot12WsCreateOptions, type OneBot12WsSocket } from './ws-types.js';
+export interface OneBot12WsEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly config: OneBot12WsConfig;
+    readonly createWebSocket?: (url: string, options: OneBot12WsCreateOptions) => OneBot12WsSocket;
+}
+export declare class OneBot12WsEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: OneBot12WsEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    /** Test / internal: admit a parsed event when the endpoint is open. */
+    admit(ev: OneBot12Event): void;
+}