@zhin.js/adapter-milky 0.0.0

package/src/bot-ws.ts

@@ -0,0 +1,279 @@
+/**
+ * Milky WebSocket 正向连接 Bot（应用连协议端 ws(s)://baseUrl/event）
+ */
+import WebSocket from 'ws';
+import { EventEmitter } from 'events';
+import { clearInterval } from 'node:timers';
+import { Bot, Message, SendOptions, segment } from 'zhin.js';
+import { callApi } from './api.js';
+import type { MilkyWsConfig, MilkyEvent } from './types.js';
+import type { MilkyAdapter } from './adapter.js';
+import {
+  formatMilkyMessagePayload,
+  parseMessageReceiveData,
+  toMilkyOutgoingSegments,
+  parseMilkyMessageId,
+} from './utils.js';
+
+export class MilkyWsClient extends EventEmitter implements Bot<MilkyWsConfig, MilkyEvent> {
+  $connected: boolean;
+  private ws?: WebSocket;
+  private reconnectTimer?: NodeJS.Timeout;
+  private heartbeatTimer?: NodeJS.Timeout;
+
+  get logger() {
+    return this.adapter.plugin.logger;
+  }
+
+  constructor(public adapter: MilkyAdapter, public $config: MilkyWsConfig) {
+    super();
+    this.$connected = false;
+  }
+
+  get $id() {
+    return this.$config.name;
+  }
+
+  private get eventUrl(): string {
+    const base = this.$config.baseUrl.replace(/\/$/, '');
+    const url = base.replace(/^http/, 'ws') + '/event';
+    const token = this.$config.access_token;
+    if (token) return `${url}${url.includes('?') ? '&' : '?'}access_token=${encodeURIComponent(token)}`;
+    return url;
+  }
+
+  private apiOptions() {
+    return { baseUrl: this.$config.baseUrl, access_token: this.$config.access_token };
+  }
+
+  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.eventUrl, { headers });
+
+      this.ws.on('open', () => {
+        this.$connected = true;
+        if (!this.$config.access_token) this.logger.warn('missing access_token, connection is not secured');
+        this.startHeartbeat();
+        resolve();
+      });
+
+      this.ws.on('message', (data) => {
+        try {
+          const event = JSON.parse(data.toString()) as MilkyEvent;
+          this.handleEvent(event);
+        } catch (error) {
+          this.emit('error', error);
+        }
+      });
+
+      this.ws.on('close', (code, reason) => {
+        this.$connected = false;
+        reject(new Error(`WS closed: ${code} ${reason.toString()}`));
+        this.scheduleReconnect();
+      });
+
+      this.ws.on('error', (error) => {
+        reject(error);
+      });
+    });
+  }
+
+  async $disconnect(): Promise<void> {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = undefined;
+    }
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = undefined;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = undefined;
+    }
+    this.$connected = false;
+  }
+
+  private handleEvent(event: MilkyEvent): void {
+    const data = parseMessageReceiveData(event);
+    if (data) {
+      const message = this.$formatMessage(event);
+      this.adapter.emit('message.receive', message);
+      this.logger.debug(
+        `${this.$config.name} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`,
+      );
+    }
+    // 其他 event_type 可在此扩展 Notice / Request
+  }
+
+  $formatMessage(event: MilkyEvent): Message<MilkyEvent> {
+    const data = parseMessageReceiveData(event);
+    if (!data) {
+      return Message.from(event, {
+        $id: '',
+        $adapter: 'milky',
+        $bot: this.$config.name,
+        $channel: { id: '', type: 'private' },
+        $sender: { id: '', name: '' },
+        $content: [],
+        $raw: '',
+        $timestamp: event.time ?? 0,
+        $recall: async () => {},
+        $reply: async () => '',
+      });
+    }
+    const payload = formatMilkyMessagePayload(
+      event,
+      data,
+      (id) => this.$recallMessage(id),
+      (channel, content, _quote) =>
+        this.adapter.sendMessage({
+          ...channel,
+          context: 'milky',
+          bot: this.$config.name,
+          content: content as import('zhin.js').SendContent,
+        }),
+      'milky',
+      this.$config.name,
+    );
+    return Message.from(event, payload);
+  }
+
+  async $sendMessage(options: SendOptions): Promise<string> {
+    const content = Array.isArray(options.content) ? options.content : [options.content];
+    const segments = content.map((c) =>
+      typeof c === 'string' ? { type: 'text' as const, data: { text: c } } : (c as { type: string; data?: Record<string, unknown> }),
+    );
+    const message = toMilkyOutgoingSegments(segments);
+    if (options.type === 'group') {
+      const result = await callApi(this.apiOptions(), 'send_group_message', {
+        group_id: parseInt(options.id, 10),
+        message,
+      });
+      const seq = (result as { message_seq?: number }).message_seq;
+      this.logger.debug(`${this.$config.name} send group(${options.id}):${segment.raw(options.content)}`);
+      return seq != null ? `group:${options.id}:${seq}` : '';
+    }
+    if (options.type === 'private') {
+      const result = await callApi(this.apiOptions(), 'send_private_message', {
+        user_id: parseInt(options.id, 10),
+        message,
+      });
+      const seq = (result as { message_seq?: number }).message_seq;
+      this.logger.debug(`${this.$config.name} send private(${options.id}):${segment.raw(options.content)}`);
+      return seq != null ? `friend:${options.id}:${seq}` : '';
+    }
+    throw new Error('Either group or private must be provided');
+  }
+
+  async $recallMessage(id: string): Promise<void> {
+    const parsed = parseMilkyMessageId(id);
+    if (!parsed) throw new Error(`Invalid message id: ${id}`);
+    if (parsed.message_scene === 'group') {
+      await callApi(this.apiOptions(), 'recall_group_message', {
+        group_id: parsed.peer_id,
+        message_seq: parsed.message_seq,
+      });
+    } else {
+      await callApi(this.apiOptions(), 'recall_private_message', {
+        user_id: parsed.peer_id,
+        message_seq: parsed.message_seq,
+      });
+    }
+  }
+
+  async kickMember(groupId: number, userId: number, rejectAddRequest = false): Promise<boolean> {
+    await callApi(this.apiOptions(), 'kick_group_member', {
+      group_id: groupId,
+      user_id: userId,
+      reject_add_request: rejectAddRequest,
+    });
+    this.logger.info(`Milky Bot ${this.$id} 踢出成员 ${userId}（群 ${groupId}）`);
+    return true;
+  }
+
+  async muteMember(groupId: number, userId: number, duration = 600): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_mute', {
+      group_id: groupId,
+      user_id: userId,
+      duration,
+    });
+    this.logger.info(
+      `Milky Bot ${this.$id} ${duration > 0 ? `禁言成员 ${userId} ${duration}秒` : `解除禁言 ${userId}`}（群 ${groupId}）`,
+    );
+    return true;
+  }
+
+  async muteAll(groupId: number, enable = true): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_whole_mute', { group_id: groupId, is_mute: enable });
+    this.logger.info(`Milky Bot ${this.$id} ${enable ? '开启' : '关闭'}全员禁言（群 ${groupId}）`);
+    return true;
+  }
+
+  async setAdmin(groupId: number, userId: number, enable = true): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_admin', {
+      group_id: groupId,
+      user_id: userId,
+      is_set: enable,
+    });
+    this.logger.info(`Milky Bot ${this.$id} ${enable ? '设置' : '取消'}管理员 ${userId}（群 ${groupId}）`);
+    return true;
+  }
+
+  async setCard(groupId: number, userId: number, card: string): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_card', {
+      group_id: groupId,
+      user_id: userId,
+      card,
+    });
+    this.logger.info(`Milky Bot ${this.$id} 设置成员 ${userId} 群名片（群 ${groupId}）`);
+    return true;
+  }
+
+  async setTitle(groupId: number, userId: number, title: string): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_special_title', {
+      group_id: groupId,
+      user_id: userId,
+      special_title: title,
+    });
+    this.logger.info(`Milky Bot ${this.$id} 设置成员 ${userId} 头衔（群 ${groupId}）`);
+    return true;
+  }
+
+  async setGroupName(groupId: number, name: string): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_name', { group_id: groupId, new_group_name: name });
+    this.logger.info(`Milky Bot ${this.$id} 设置群名（群 ${groupId}）`);
+    return true;
+  }
+
+  async getMemberList(groupId: number): Promise<unknown[]> {
+    return callApi(this.apiOptions(), 'get_group_member_list', { group_id: groupId }) as Promise<unknown[]>;
+  }
+
+  async getGroupInfo(groupId: number): Promise<unknown> {
+    return callApi(this.apiOptions(), 'get_group_info', { group_id: groupId });
+  }
+
+  private startHeartbeat(): void {
+    const interval = this.$config.heartbeat_interval ?? 30000;
+    this.heartbeatTimer = setInterval(() => {
+      if (this.ws?.readyState === WebSocket.OPEN) this.ws.ping();
+    }, interval);
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer) return;
+    const interval = this.$config.reconnect_interval ?? 5000;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      this.$connect().catch((err) => {
+        this.emit('error', err);
+        this.scheduleReconnect();
+      });
+    }, interval);
+  }
+}

package/src/bot-wss.ts

@@ -0,0 +1,268 @@
+/**
+ * Milky 反向 WebSocket Bot：应用开 WS 服务端，协议端来连；鉴权后收事件同正向
+ */
+import { IncomingMessage } from 'http';
+import WebSocket, { WebSocketServer } from 'ws';
+import { EventEmitter } from 'events';
+import { clearInterval } from 'node:timers';
+import { Bot, Message, SendOptions, segment } from 'zhin.js';
+import type { Router } from '@zhin.js/http';
+import { callApi } from './api.js';
+import type { MilkyWssConfig, MilkyEvent } from './types.js';
+import type { MilkyAdapter } from './adapter.js';
+import {
+  formatMilkyMessagePayload,
+  parseMessageReceiveData,
+  toMilkyOutgoingSegments,
+  parseMilkyMessageId,
+} from './utils.js';
+
+function getAccessTokenFromWsRequest(req: IncomingMessage): string | undefined {
+  const auth = req.headers['authorization'];
+  if (typeof auth === 'string' && auth.startsWith('Bearer ')) return auth.slice(7);
+  const url = req.url ?? '';
+  const idx = url.indexOf('?');
+  if (idx >= 0) {
+    const params = new URLSearchParams(url.slice(idx));
+    return params.get('access_token') ?? undefined;
+  }
+  return undefined;
+}
+
+export class MilkyWssServer extends EventEmitter implements Bot<MilkyWssConfig, MilkyEvent> {
+  $connected: boolean;
+  #wss?: WebSocketServer;
+  #client?: WebSocket;
+  private heartbeatTimer?: NodeJS.Timeout;
+
+  get logger() {
+    return this.adapter.plugin.logger;
+  }
+
+  constructor(
+    public adapter: MilkyAdapter,
+    public router: Router,
+    public $config: MilkyWssConfig,
+  ) {
+    super();
+    this.$connected = false;
+  }
+
+  get $id() {
+    return this.$config.name;
+  }
+
+  private apiOptions() {
+    return { baseUrl: this.$config.baseUrl, access_token: this.$config.access_token };
+  }
+
+  async $connect(): Promise<void> {
+    const path = this.$config.path.startsWith('/') ? this.$config.path : `/${this.$config.path}`;
+    const token = this.$config.access_token;
+    if (!token) this.logger.warn('missing access_token, reverse WS is not secured');
+
+    this.#wss = this.router.ws(path, {
+      verifyClient: (info: { req: IncomingMessage }) => {
+        const received = getAccessTokenFromWsRequest(info.req);
+        if (token && received !== token) {
+          this.logger.error('反向 WS 鉴权失败');
+          return false;
+        }
+        return true;
+      },
+    });
+
+    this.$connected = true;
+    this.logger.info(`Milky 反向 WS 服务端已启动: ${path}`);
+
+    this.#wss.on('connection', (client, req) => {
+      this.#client = client;
+      this.startHeartbeat();
+      this.logger.info(`协议端已连接: ${req.socket?.remoteAddress}`);
+
+      client.on('message', (data) => {
+        try {
+          const event = JSON.parse(data.toString()) as MilkyEvent;
+          this.handleEvent(event);
+        } catch (err) {
+          this.emit('error', err);
+        }
+      });
+
+      client.on('close', () => {
+        this.#client = undefined;
+        this.logger.warn('协议端断开连接');
+      });
+
+      client.on('error', (err) => this.logger.error('反向 WS 连接错误', err));
+    });
+  }
+
+  async $disconnect(): Promise<void> {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = undefined;
+    }
+    this.#wss?.close();
+    this.#wss = undefined;
+    this.#client = undefined;
+    this.$connected = false;
+  }
+
+  $formatMessage(event: MilkyEvent): Message<MilkyEvent> {
+    const data = parseMessageReceiveData(event);
+    if (!data) {
+      return Message.from(event, {
+        $id: '',
+        $adapter: 'milky',
+        $bot: this.$config.name,
+        $channel: { id: '', type: 'private' },
+        $sender: { id: '', name: '' },
+        $content: [],
+        $raw: '',
+        $timestamp: event.time ?? 0,
+        $recall: async () => {},
+        $reply: async () => '',
+      });
+    }
+    const payload = formatMilkyMessagePayload(
+      event,
+      data,
+      (id) => this.$recallMessage(id),
+      (channel, content) =>
+        this.adapter.sendMessage({
+          ...channel,
+          context: 'milky',
+          bot: this.$config.name,
+          content: content as import('zhin.js').SendContent,
+        }),
+      'milky',
+      this.$config.name,
+    );
+    return Message.from(event, payload);
+  }
+
+  private handleEvent(event: MilkyEvent): void {
+    const data = parseMessageReceiveData(event);
+    if (data) {
+      const message = this.$formatMessage(event);
+      this.adapter.emit('message.receive', message);
+      this.logger.debug(
+        `${this.$config.name} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`,
+      );
+    }
+  }
+
+  async $sendMessage(options: SendOptions): Promise<string> {
+    const content = Array.isArray(options.content) ? options.content : [options.content];
+    const segments = content.map((c) =>
+      typeof c === 'string' ? { type: 'text' as const, data: { text: c } } : (c as { type: string; data?: Record<string, unknown> }),
+    );
+    const message = toMilkyOutgoingSegments(segments);
+    if (options.type === 'group') {
+      const result = await callApi(this.apiOptions(), 'send_group_message', {
+        group_id: parseInt(options.id, 10),
+        message,
+      });
+      const seq = (result as { message_seq?: number }).message_seq;
+      this.logger.debug(`${this.$config.name} send group(${options.id}):${segment.raw(options.content)}`);
+      return seq != null ? `group:${options.id}:${seq}` : '';
+    }
+    if (options.type === 'private') {
+      const result = await callApi(this.apiOptions(), 'send_private_message', {
+        user_id: parseInt(options.id, 10),
+        message,
+      });
+      const seq = (result as { message_seq?: number }).message_seq;
+      this.logger.debug(`${this.$config.name} send private(${options.id}):${segment.raw(options.content)}`);
+      return seq != null ? `friend:${options.id}:${seq}` : '';
+    }
+    throw new Error('Either group or private must be provided');
+  }
+
+  async $recallMessage(id: string): Promise<void> {
+    const parsed = parseMilkyMessageId(id);
+    if (!parsed) throw new Error(`Invalid message id: ${id}`);
+    if (parsed.message_scene === 'group') {
+      await callApi(this.apiOptions(), 'recall_group_message', {
+        group_id: parsed.peer_id,
+        message_seq: parsed.message_seq,
+      });
+    } else {
+      await callApi(this.apiOptions(), 'recall_private_message', {
+        user_id: parsed.peer_id,
+        message_seq: parsed.message_seq,
+      });
+    }
+  }
+
+  async kickMember(groupId: number, userId: number, rejectAddRequest = false): Promise<boolean> {
+    await callApi(this.apiOptions(), 'kick_group_member', {
+      group_id: groupId,
+      user_id: userId,
+      reject_add_request: rejectAddRequest,
+    });
+    return true;
+  }
+
+  async muteMember(groupId: number, userId: number, duration = 600): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_mute', {
+      group_id: groupId,
+      user_id: userId,
+      duration,
+    });
+    return true;
+  }
+
+  async muteAll(groupId: number, enable = true): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_whole_mute', { group_id: groupId, is_mute: enable });
+    return true;
+  }
+
+  async setAdmin(groupId: number, userId: number, enable = true): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_admin', {
+      group_id: groupId,
+      user_id: userId,
+      is_set: enable,
+    });
+    return true;
+  }
+
+  async setCard(groupId: number, userId: number, card: string): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_card', {
+      group_id: groupId,
+      user_id: userId,
+      card,
+    });
+    return true;
+  }
+
+  async setTitle(groupId: number, userId: number, title: string): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_member_special_title', {
+      group_id: groupId,
+      user_id: userId,
+      special_title: title,
+    });
+    return true;
+  }
+
+  async setGroupName(groupId: number, name: string): Promise<boolean> {
+    await callApi(this.apiOptions(), 'set_group_name', { group_id: groupId, new_group_name: name });
+    return true;
+  }
+
+  async getMemberList(groupId: number): Promise<unknown[]> {
+    return callApi(this.apiOptions(), 'get_group_member_list', { group_id: groupId }) as Promise<unknown[]>;
+  }
+
+  async getGroupInfo(groupId: number): Promise<unknown> {
+    return callApi(this.apiOptions(), 'get_group_info', { group_id: groupId });
+  }
+
+  private startHeartbeat(): void {
+    const interval = this.$config.heartbeat_interval ?? 30000;
+    this.heartbeatTimer = setInterval(() => {
+      if (this.#client?.readyState === WebSocket.OPEN) this.#client.ping();
+    }, interval);
+  }
+}

package/src/eventsource.d.ts

@@ -0,0 +1,12 @@
+declare module 'eventsource' {
+  interface EventSourceConstructor {
+    new (url: string, init?: { headers?: Record<string, string> }): EventSource;
+  }
+  interface EventSource {
+    addEventListener(type: string, listener: (e: MessageEvent) => void): void;
+    onerror: ((err: unknown) => void) | null;
+    close(): void;
+  }
+  const EventSource: EventSourceConstructor;
+  export = EventSource;
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Milky 适配器入口：单一适配器，支持 WS/SSE/Webhook/反向 WS，依赖 router 注册
+ */
+import { usePlugin, type Plugin, type Context } from 'zhin.js';
+import type { Router } from '@zhin.js/http';
+import { MilkyAdapter } from './adapter.js';
+
+export * from './types.js';
+export { callApi } from './api.js';
+export * from './utils.js';
+export { MilkyWsClient } from './bot-ws.js';
+export { MilkySseClient } from './bot-sse.js';
+export { MilkyWebhookBot } from './bot-webhook.js';
+export { MilkyWssServer } from './bot-wss.js';
+export { MilkyAdapter, type MilkyBot } from './adapter.js';
+
+declare module 'zhin.js' {
+  namespace Plugin {
+    interface Contexts {
+      router: import('@zhin.js/http').Router;
+    }
+  }
+  interface Adapters {
+    milky: MilkyAdapter;
+  }
+}
+
+const { provide } = usePlugin();
+provide({
+  name: 'milky',
+  description: 'Milky Adapter（WS 正向 / SSE / Webhook / 反向 WS）',
+  mounted: async (p: Plugin) => {
+    const adapter = new MilkyAdapter(p);
+    await adapter.start();
+    return adapter;
+  },
+  dispose: async (adapter: MilkyAdapter) => {
+    await adapter.stop();
+  },
+} as unknown as Context<'milky'>);

package/src/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Milky 适配器类型与配置（与官方文档一致）
+ */
+
+/** 配置公共字段；单一适配器下 context 均为 'milky'，连接方式由 connection 区分 */
+export interface MilkyConfigBase {
+  context: 'milky';
+  name: string;
+  baseUrl: string;
+  access_token?: string;
+}
+
+/** WebSocket 正向连接 */
+export interface MilkyWsConfig extends MilkyConfigBase {
+  connection: 'ws';
+  reconnect_interval?: number;
+  heartbeat_interval?: number;
+}
+
+/** SSE 连接 */
+export interface MilkySseConfig extends MilkyConfigBase {
+  connection: 'sse';
+}
+
+/** Webhook（协议端 POST 到应用） */
+export interface MilkyWebhookConfig extends MilkyConfigBase {
+  connection: 'webhook';
+  path: string;
+}
+
+/** WebSocket 反向（协议端连应用） */
+export interface MilkyWssConfig extends MilkyConfigBase {
+  connection: 'wss';
+  path: string;
+  heartbeat_interval?: number;
+}
+
+export type MilkyBotConfig = MilkyWsConfig | MilkySseConfig | MilkyWebhookConfig | MilkyWssConfig;
+
+/** 协议端 API 响应：status、retcode、data?、message? */
+export interface MilkyApiResponse<T = unknown> {
+  status: string;
+  retcode: number;
+  data?: T;
+  message?: string;
+}
+
+/** 事件结构：event_type、time、self_id、data */
+export interface MilkyEvent {
+  event_type: string;
+  time: number;
+  self_id: number;
+  data?: Record<string, unknown>;
+}
+
+/** 接收消息 data（message_receive）：message_scene、peer_id、message_seq、sender_id、time、segments、可选 friend/group/group_member */
+export interface MilkyIncomingMessage {
+  message_scene: 'friend' | 'group' | 'temp';
+  peer_id: number;
+  message_seq: number;
+  sender_id: number;
+  time: number;
+  segments: MilkyIncomingSegment[];
+  friend?: { user_id: number; nickname?: string };
+  group?: { group_id: number; group_name?: string };
+  group_member?: { user_id: number; nickname?: string; card?: string; role?: string };
+}
+
+/** 接收消息段：type、data */
+export interface MilkyIncomingSegment {
+  type: string;
+  data?: Record<string, unknown>;
+}