@zhin.js/adapter-onebot12 0.0.0

package/src/bot-webhook.ts

@@ -0,0 +1,130 @@
+/**
+ * OneBot 12 HTTP Webhook Bot：OneBot 实现 POST 事件到应用 path，可选 api_url 用于发消息
+ */
+import { EventEmitter } from 'events';
+import { Bot, Message, SendOptions, segment } from 'zhin.js';
+import type { Router, RouterContext } from '@zhin.js/http';
+import { callOneBot12Action } from './api.js';
+import type { OneBot12WebhookConfig, OneBot12Event } from './types.js';
+import type { OneBot12Adapter } from './adapter.js';
+import { formatOneBot12MessagePayload, isMessageEvent, contentToOb12Segments } from './utils.js';
+
+export class OneBot12WebhookBot extends EventEmitter implements Bot<OneBot12WebhookConfig, OneBot12Event> {
+  $connected: boolean = true;
+
+  get logger() {
+    return this.adapter.plugin.logger;
+  }
+
+  constructor(
+    public adapter: OneBot12Adapter,
+    public router: Router,
+    public $config: OneBot12WebhookConfig,
+  ) {
+    super();
+  }
+
+  get $id() {
+    return this.$config.name;
+  }
+
+  private httpOptions() {
+    const url = this.$config.api_url?.replace(/\/$/, '') ?? '';
+    return { url: url || '', access_token: this.$config.access_token };
+  }
+
+  async $connect(): Promise<void> {
+    const path = this.$config.path.startsWith('/') ? this.$config.path : `/${this.$config.path}`;
+    this.router.post(path, async (ctx: RouterContext) => {
+      const body = ctx.request.body as OneBot12Event | undefined;
+      if (!body || typeof body !== 'object' || !body.id || body.time == null || !body.type) {
+        ctx.status = 400;
+        ctx.body = { message: 'Invalid OneBot12 event' };
+        return;
+      }
+      const token = this.$config.access_token;
+      const auth = ctx.headers['authorization'];
+      if (token && auth !== `Bearer ${token}`) {
+        ctx.status = 401;
+        ctx.body = { message: 'Unauthorized' };
+        return;
+      }
+      this.handleEvent(body);
+      ctx.status = 204;
+      ctx.body = undefined;
+    });
+    this.logger.info(`OneBot12 Webhook 注册路径: ${path}`);
+  }
+
+  async $disconnect(): Promise<void> {
+    this.$connected = false;
+  }
+
+  private handleEvent(ev: OneBot12Event): void {
+    if (ev.type === 'message' && isMessageEvent(ev)) {
+      const message = this.$formatMessage(ev);
+      this.adapter.emit('message.receive', message);
+      this.logger.debug(`${this.$config.name} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`);
+    }
+  }
+
+  $formatMessage(ev: OneBot12Event): Message<OneBot12Event> {
+    if (!isMessageEvent(ev)) {
+      return Message.from(ev, {
+        $id: '',
+        $adapter: 'onebot12',
+        $bot: this.$config.name,
+        $channel: { id: '', type: 'private' },
+        $sender: { id: '', name: '' },
+        $content: [],
+        $raw: '',
+        $timestamp: ev.time ?? 0,
+        $recall: async () => {},
+        $reply: async () => '',
+      });
+    }
+    const payload = formatOneBot12MessagePayload(
+      ev,
+      this.$config.name,
+      (id) => this.$recallMessage(id),
+      (channel, content, _quote) =>
+        this.adapter.sendMessage({
+          ...channel,
+          context: 'onebot12',
+          bot: this.$config.name,
+          content: content as import('zhin.js').SendContent,
+        }),
+    );
+    return Message.from(ev, payload);
+  }
+
+  async $sendMessage(options: SendOptions): Promise<string> {
+    const apiUrl = this.$config.api_url;
+    if (!apiUrl) {
+      throw new Error('OneBot12 Webhook 发消息需要配置 api_url（OneBot 实现的 HTTP 端点）');
+    }
+    const message = contentToOb12Segments(options.content);
+    const params: Record<string, unknown> = { message };
+    if (options.type === 'private') {
+      params.detail_type = 'private';
+      params.user_id = options.id;
+    } else if (options.type === 'group') {
+      params.detail_type = 'group';
+      params.group_id = options.id;
+    } else {
+      const [guildId, channelId] = options.id.includes(':') ? options.id.split(':') : [undefined, options.id];
+      params.detail_type = 'channel';
+      params.channel_id = channelId ?? options.id;
+      if (guildId) params.guild_id = guildId;
+    }
+    const data = await callOneBot12Action(this.httpOptions(), 'send_message', params);
+    const out = (data as { message_id?: string })?.message_id ?? '';
+    return out;
+  }
+
+  async $recallMessage(id: string): Promise<void> {
+    const apiUrl = this.$config.api_url;
+    if (!apiUrl) throw new Error('OneBot12 Webhook 撤回需要配置 api_url');
+    await callOneBot12Action(this.httpOptions(), 'delete_message', { message_id: id });
+  }
+}

package/src/bot-ws.ts

@@ -0,0 +1,191 @@
+/**
+ * OneBot 12 正向 WebSocket Bot：应用连 OneBot 实现的 WS，收事件、发动作
+ */
+import WebSocket from 'ws';
+import { EventEmitter } from 'events';
+import { clearInterval, clearTimeout } from 'node:timers';
+import { Bot, Message, SendOptions, segment } from 'zhin.js';
+import type { OneBot12WsConfig, OneBot12Event, OneBot12ActionRequest, OneBot12ActionResponse } from './types.js';
+import type { OneBot12Adapter } from './adapter.js';
+import { formatOneBot12MessagePayload, isMessageEvent, contentToOb12Segments } from './utils.js';
+
+export class OneBot12WsClient extends EventEmitter implements Bot<OneBot12WsConfig, OneBot12Event> {
+  $connected: boolean;
+  private ws?: WebSocket;
+  private reconnectTimer?: NodeJS.Timeout;
+  private heartbeatTimer?: NodeJS.Timeout;
+  private requestId = 0;
+  private pendingRequests = new Map<string, { resolve: (value: unknown) => void; reject: (err: Error) => void; timeout: NodeJS.Timeout }>();
+
+  get logger() {
+    return this.adapter.plugin.logger;
+  }
+
+  constructor(public adapter: OneBot12Adapter, public $config: OneBot12WsConfig) {
+    super();
+    this.$connected = false;
+  }
+
+  get $id() {
+    return this.$config.name;
+  }
+
+  private startHeartbeat(): void {
+    const interval = this.$config.heartbeat_interval ?? 30000;
+    this.heartbeatTimer = setInterval(() => {
+      this.callAction('get_status', {}).catch(() => {});
+    }, interval);
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer) return;
+    const delay = this.$config.reconnect_interval ?? 5000;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      this.$connect().catch((err) => this.logger.warn('OneBot12 重连失败', err));
+    }, delay);
+  }
+
+  private callAction(action: string, params: Record<string, unknown>): Promise<OneBot12ActionResponse['data']> {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      return Promise.reject(new Error('WebSocket 未连接'));
+    }
+    const echo = `ob12_${++this.requestId}`;
+    const req: OneBot12ActionRequest = { action, params, echo };
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(echo);
+        reject(new Error(`OneBot12 动作超时: ${action}`));
+      }, 30000);
+      this.pendingRequests.set(echo, {
+        resolve: (data: unknown) => resolve(data as OneBot12ActionResponse['data']),
+        reject,
+        timeout,
+      });
+      this.ws!.send(JSON.stringify(req));
+    });
+  }
+
+  async $connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const headers: Record<string, string> = {};
+      if (this.$config.access_token) headers['Authorization'] = `Bearer ${this.$config.access_token}`;
+      this.ws = new WebSocket(this.$config.url, { headers });
+
+      this.ws.on('open', () => {
+        this.$connected = true;
+        this.startHeartbeat();
+        resolve();
+      });
+
+      this.ws.on('message', (data) => {
+        try {
+          const msg = JSON.parse(data.toString()) as OneBot12Event | OneBot12ActionResponse;
+          if ('echo' in msg && typeof (msg as OneBot12ActionResponse).echo === 'string') {
+            const resp = msg as OneBot12ActionResponse;
+            const pending = this.pendingRequests.get(resp.echo!);
+            if (pending) {
+              this.pendingRequests.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}`));
+            }
+            return;
+          }
+          const ev = msg as OneBot12Event;
+          if (ev.type === 'message' && isMessageEvent(ev)) {
+            const message = this.$formatMessage(ev);
+            this.adapter.emit('message.receive', message);
+            this.logger.debug(`${this.$config.name} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`);
+          }
+        } catch (error) {
+          this.emit('error', error);
+        }
+      });
+
+      this.ws.on('close', (code, reason) => {
+        this.$connected = false;
+        reject(new Error(`OneBot12 WS 关闭: ${code} ${reason.toString()}`));
+        this.scheduleReconnect();
+      });
+
+      this.ws.on('error', (err) => reject(err));
+    });
+  }
+
+  async $disconnect(): Promise<void> {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = undefined;
+    }
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = undefined;
+    }
+    for (const [, p] of this.pendingRequests) {
+      clearTimeout(p.timeout);
+      p.reject(new Error('连接已关闭'));
+    }
+    this.pendingRequests.clear();
+    if (this.ws) {
+      this.ws.close();
+      this.ws = undefined;
+    }
+    this.$connected = false;
+  }
+
+  $formatMessage(ev: OneBot12Event): Message<OneBot12Event> {
+    if (!isMessageEvent(ev)) {
+      return Message.from(ev, {
+        $id: '',
+        $adapter: 'onebot12',
+        $bot: this.$config.name,
+        $channel: { id: '', type: 'private' },
+        $sender: { id: '', name: '' },
+        $content: [],
+        $raw: '',
+        $timestamp: ev.time ?? 0,
+        $recall: async () => {},
+        $reply: async () => '',
+      });
+    }
+    const payload = formatOneBot12MessagePayload(
+      ev,
+      this.$config.name,
+      (id) => this.$recallMessage(id),
+      (channel, content, _quote) =>
+        this.adapter.sendMessage({
+          ...channel,
+          context: 'onebot12',
+          bot: this.$config.name,
+          content: content as import('zhin.js').SendContent,
+        }),
+    );
+    return Message.from(ev, payload);
+  }
+
+  async $sendMessage(options: SendOptions): Promise<string> {
+    const message = contentToOb12Segments(options.content);
+    const params: Record<string, unknown> = { message };
+    if (options.type === 'private') {
+      params.detail_type = 'private';
+      params.user_id = options.id;
+    } else if (options.type === 'group') {
+      params.detail_type = 'group';
+      params.group_id = options.id;
+    } else {
+      const [guildId, channelId] = options.id.includes(':') ? options.id.split(':') : [undefined, options.id];
+      params.detail_type = 'channel';
+      params.channel_id = channelId ?? options.id;
+      if (guildId) params.guild_id = guildId;
+    }
+    const data = await this.callAction('send_message', params) as { message_id?: string } | undefined;
+    const msgId = data?.message_id ?? '';
+    this.logger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(options.content)}`);
+    return msgId;
+  }
+
+  async $recallMessage(id: string): Promise<void> {
+    await this.callAction('delete_message', { message_id: id });
+  }
+}

package/src/bot-wss.ts

@@ -0,0 +1,188 @@
+/**
+ * OneBot 12 反向 WebSocket Bot：应用开 WS 服务端，OneBot 实现连上来
+ */
+import WebSocket, { WebSocketServer } from 'ws';
+import { EventEmitter } from 'events';
+import { clearInterval, clearTimeout } from 'node:timers';
+import { IncomingMessage } from 'http';
+import { Bot, Message, SendOptions, segment } from 'zhin.js';
+import type { Router } from '@zhin.js/http';
+import type { OneBot12WssConfig, OneBot12Event, OneBot12ActionRequest, OneBot12ActionResponse } from './types.js';
+import type { OneBot12Adapter } from './adapter.js';
+import { formatOneBot12MessagePayload, isMessageEvent, contentToOb12Segments } from './utils.js';
+
+export class OneBot12WssServer extends EventEmitter implements Bot<OneBot12WssConfig, OneBot12Event> {
+  $connected: boolean = false;
+  #wss?: WebSocketServer;
+  #client?: WebSocket;
+  private heartbeatTimer?: NodeJS.Timeout;
+  private requestId = 0;
+  private pendingRequests = new Map<string, { resolve: (value: unknown) => void; reject: (err: Error) => void; timeout: NodeJS.Timeout }>();
+
+  get logger() {
+    return this.adapter.plugin.logger;
+  }
+
+  constructor(
+    public adapter: OneBot12Adapter,
+    public router: Router,
+    public $config: OneBot12WssConfig,
+  ) {
+    super();
+  }
+
+  get $id() {
+    return this.$config.name;
+  }
+
+  private getClient(): WebSocket | undefined {
+    return this.#client && this.#client.readyState === WebSocket.OPEN ? this.#client : undefined;
+  }
+
+  private callAction(action: string, params: Record<string, unknown>): Promise<OneBot12ActionResponse['data']> {
+    const client = this.getClient();
+    if (!client) return Promise.reject(new Error('反向 WebSocket 未连接'));
+    const echo = `ob12wss_${++this.requestId}`;
+    const req: OneBot12ActionRequest = { action, params, echo };
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(echo);
+        reject(new Error(`OneBot12 动作超时: ${action}`));
+      }, 30000);
+      this.pendingRequests.set(echo, {
+        resolve: (data: unknown) => resolve(data as OneBot12ActionResponse['data']),
+        reject,
+        timeout,
+      });
+      client.send(JSON.stringify(req));
+    });
+  }
+
+  async $connect(): Promise<void> {
+    const path = this.$config.path.startsWith('/') ? this.$config.path : `/${this.$config.path}`;
+    this.#wss = this.router.ws(path, {
+      verifyClient: (info: { req: IncomingMessage }) => {
+        const auth = info.req.headers['authorization'];
+        if (this.$config.access_token && auth !== `Bearer ${this.$config.access_token}`) {
+          this.logger.error('OneBot12 反向 WS 鉴权失败');
+          return false;
+        }
+        return true;
+      },
+    });
+
+    this.#wss.on('connection', (ws: WebSocket) => {
+      if (this.#client && this.#client.readyState === WebSocket.OPEN) {
+        this.#client.close();
+      }
+      this.#client = ws;
+      this.$connected = true;
+      this.logger.info(`OneBot12 反向 WS 已连接: ${this.$config.name}`);
+
+      ws.on('message', (data) => {
+        try {
+          const msg = JSON.parse(data.toString()) as OneBot12Event | OneBot12ActionResponse;
+          if ('echo' in msg && typeof (msg as OneBot12ActionResponse).echo === 'string') {
+            const resp = msg as OneBot12ActionResponse;
+            const pending = this.pendingRequests.get(resp.echo!);
+            if (pending) {
+              this.pendingRequests.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}`));
+            }
+            return;
+          }
+          const ev = msg as OneBot12Event;
+          if (ev.type === 'message' && isMessageEvent(ev)) {
+            const message = this.$formatMessage(ev);
+            this.adapter.emit('message.receive', message);
+            this.logger.debug(`${this.$config.name} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`);
+          }
+        } catch (error) {
+          this.emit('error', error);
+        }
+      });
+
+      ws.on('close', () => {
+        this.$connected = false;
+        this.#client = undefined;
+        this.logger.warn('OneBot12 反向 WS 断开');
+      });
+
+      ws.on('error', (err) => this.logger.error('OneBot12 反向 WS 错误', err));
+    });
+  }
+
+  async $disconnect(): Promise<void> {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = undefined;
+    }
+    for (const [, p] of this.pendingRequests) {
+      clearTimeout(p.timeout);
+      p.reject(new Error('连接已关闭'));
+    }
+    this.pendingRequests.clear();
+    if (this.#client) {
+      this.#client.close();
+      this.#client = undefined;
+    }
+    this.#wss?.close();
+    this.#wss = undefined;
+    this.$connected = false;
+  }
+
+  $formatMessage(ev: OneBot12Event): Message<OneBot12Event> {
+    if (!isMessageEvent(ev)) {
+      return Message.from(ev, {
+        $id: '',
+        $adapter: 'onebot12',
+        $bot: this.$config.name,
+        $channel: { id: '', type: 'private' },
+        $sender: { id: '', name: '' },
+        $content: [],
+        $raw: '',
+        $timestamp: ev.time ?? 0,
+        $recall: async () => {},
+        $reply: async () => '',
+      });
+    }
+    const payload = formatOneBot12MessagePayload(
+      ev,
+      this.$config.name,
+      (id) => this.$recallMessage(id),
+      (channel, content, _quote) =>
+        this.adapter.sendMessage({
+          ...channel,
+          context: 'onebot12',
+          bot: this.$config.name,
+          content: content as import('zhin.js').SendContent,
+        }),
+    );
+    return Message.from(ev, payload);
+  }
+
+  async $sendMessage(options: SendOptions): Promise<string> {
+    const message = contentToOb12Segments(options.content);
+    const params: Record<string, unknown> = { message };
+    if (options.type === 'private') {
+      params.detail_type = 'private';
+      params.user_id = options.id;
+    } else if (options.type === 'group') {
+      params.detail_type = 'group';
+      params.group_id = options.id;
+    } else {
+      const [guildId, channelId] = options.id.includes(':') ? options.id.split(':') : [undefined, options.id];
+      params.detail_type = 'channel';
+      params.channel_id = channelId ?? options.id;
+      if (guildId) params.guild_id = guildId;
+    }
+    const data = await this.callAction('send_message', params) as { message_id?: string } | undefined;
+    return data?.message_id ?? '';
+  }
+
+  async $recallMessage(id: string): Promise<void> {
+    await this.callAction('delete_message', { message_id: id });
+  }
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * OneBot 12 适配器入口：单一适配器，支持正向 WS / Webhook / 反向 WS
+ * 协议文档 https://12.onebot.dev/
+ */
+import { usePlugin, type Plugin, type Context } from 'zhin.js';
+import type { Router } from '@zhin.js/http';
+import { OneBot12Adapter } from './adapter.js';
+
+export * from './types.js';
+export { callOneBot12Action } from './api.js';
+export * from './utils.js';
+export { OneBot12WsClient } from './bot-ws.js';
+export { OneBot12WebhookBot } from './bot-webhook.js';
+export { OneBot12WssServer } from './bot-wss.js';
+export { OneBot12Adapter, type OneBot12Bot } from './adapter.js';
+
+declare module 'zhin.js' {
+  namespace Plugin {
+    interface Contexts {
+      router: import('@zhin.js/http').Router;
+    }
+  }
+  interface Adapters {
+    onebot12: OneBot12Adapter;
+  }
+}
+
+const { provide } = usePlugin();
+provide({
+  name: 'onebot12',
+  description: 'OneBot 12 协议适配器（正向 WS / Webhook / 反向 WS）',
+  mounted: async (p: Plugin) => {
+    const adapter = new OneBot12Adapter(p);
+    await adapter.start();
+    return adapter;
+  },
+  dispose: async (adapter: OneBot12Adapter) => {
+    await adapter.stop();
+  },
+} as unknown as Context<'onebot12'>);

package/src/types.ts

@@ -0,0 +1,86 @@
+/**
+ * OneBot 12 适配器类型（参考 https://12.onebot.dev/ ）
+ */
+
+/** 配置公共字段；单一适配器 context 均为 'onebot12'，连接方式由 connection 区分 */
+export interface OneBot12ConfigBase {
+  context: 'onebot12';
+  name: string;
+  /** 访问令牌，鉴权用 */
+  access_token?: string;
+}
+
+/** 正向 WebSocket：应用连 OneBot 实现的 WS 服务器 */
+export interface OneBot12WsConfig extends OneBot12ConfigBase {
+  connection: 'ws';
+  /** OneBot 实现提供的 WebSocket 地址，如 ws://127.0.0.1:6700 */
+  url: string;
+  reconnect_interval?: number;
+  heartbeat_interval?: number;
+}
+
+/** HTTP Webhook：OneBot 实现 POST 事件到应用提供的 path */
+export interface OneBot12WebhookConfig extends OneBot12ConfigBase {
+  connection: 'webhook';
+  /** 应用接收事件的 POST 路径 */
+  path: string;
+  /** 可选：OneBot 实现的 HTTP 端点，用于发消息等动作（实现 POST 事件到我们，我们 POST 动作到该 url） */
+  api_url?: string;
+}
+
+/** 反向 WebSocket：应用开 WS 服务端，OneBot 实现连上来 */
+export interface OneBot12WssConfig extends OneBot12ConfigBase {
+  connection: 'wss';
+  /** 应用侧 WS 路径 */
+  path: string;
+  heartbeat_interval?: number;
+}
+
+export type OneBot12BotConfig = OneBot12WsConfig | OneBot12WebhookConfig | OneBot12WssConfig;
+
+/** 机器人自身标识（事件与动作中的 self） */
+export interface OneBot12Self {
+  platform: string;
+  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;
+}