@zhin.js/adapter-milky 3.0.1 → 4.0.1

package/lib/ws-endpoint.d.ts

@@ -0,0 +1,42 @@
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { callApi, type MilkyEvent, type MilkyWsConfig } from './protocol.js';
+import type { MilkyWsCreateOptions, MilkyWsSocket } from './ws-types.js';
+export interface MilkyWsEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly config: MilkyWsConfig;
+    readonly createWebSocket?: (url: string, options: MilkyWsCreateOptions) => MilkyWsSocket;
+    readonly callApi?: typeof callApi;
+}
+export declare class MilkyWsEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: MilkyWsEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    /** Public API for agent tools / callers. */
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+    recallMessage(id: string): Promise<void>;
+    kickMember(groupId: number, userId: number, rejectAddRequest?: boolean): Promise<boolean>;
+    muteMember(groupId: number, userId: number, duration?: number): Promise<boolean>;
+    muteAll(groupId: number, enable?: boolean): Promise<boolean>;
+    setAdmin(groupId: number, userId: number, enable?: boolean): Promise<boolean>;
+    setCard(groupId: number, userId: number, card: string): Promise<boolean>;
+    setTitle(groupId: number, userId: number, title: string): Promise<boolean>;
+    setGroupName(groupId: number, name: string): Promise<boolean>;
+    getMemberList(groupId: number): Promise<unknown[]>;
+    getGroupInfo(groupId: number): Promise<unknown>;
+    /** Test / internal: admit a parsed event when the endpoint is open. */
+    admit(event: MilkyEvent): void;
+    apiOptions(): {
+        baseUrl: string;
+        access_token?: string;
+    };
+}

package/lib/ws-endpoint.js

@@ -0,0 +1,320 @@
+/**
+ * Milky WS client endpoint — outbound connect to Milky protocol server.
+ */
+import WebSocket from 'ws';
+import { clearInterval, clearTimeout } from 'node:timers';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
+import { buildSendAction, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
+const logger = getLogger('milky');
+const WS_OPEN = 1;
+export class MilkyWsEndpoint {
+    #options;
+    #callApi;
+    #ws;
+    #reconnectTimer;
+    #heartbeatTimer;
+    #open = false;
+    #started = false;
+    #stopping = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+        this.#callApi = options.callApi ?? callApi;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#stopping = false;
+        this.#unregisterAgent = registerMilkyAgentEndpoint(this.#options.config.name, this);
+        await this.#connect();
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#stopping = true;
+        this.#started = false;
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        if (this.#reconnectTimer) {
+            clearTimeout(this.#reconnectTimer);
+            this.#reconnectTimer = undefined;
+        }
+        if (this.#heartbeatTimer) {
+            clearInterval(this.#heartbeatTimer);
+            this.#heartbeatTimer = undefined;
+        }
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#ws = undefined;
+        }
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const message = formatOutboundSegments(payload);
+        const { action, params } = buildSendAction(target, message);
+        const data = await this.callApi(action, params);
+        const messageId = formatOutboundMessageId(target, data?.message_seq);
+        logger.debug(formatCompact({
+            op: 'milky_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId,
+        }));
+        return messageId;
+    }
+    /** Public API for agent tools / callers. */
+    callApi(action, params = {}) {
+        return this.#callApi(this.apiOptions(), action, params);
+    }
+    async recallMessage(id) {
+        const parsed = parseMilkyMessageId(id);
+        if (!parsed)
+            throw new Error(`Invalid message id: ${id}`);
+        if (parsed.message_scene === 'group') {
+            await this.callApi('recall_group_message', {
+                group_id: parsed.peer_id,
+                message_seq: parsed.message_seq,
+            });
+        }
+        else {
+            await this.callApi('recall_private_message', {
+                user_id: parsed.peer_id,
+                message_seq: parsed.message_seq,
+            });
+        }
+    }
+    async kickMember(groupId, userId, rejectAddRequest = false) {
+        await this.callApi('kick_group_member', {
+            group_id: groupId,
+            user_id: userId,
+            reject_add_request: rejectAddRequest,
+        });
+        return true;
+    }
+    async muteMember(groupId, userId, duration = 600) {
+        await this.callApi('set_group_member_mute', {
+            group_id: groupId,
+            user_id: userId,
+            duration,
+        });
+        return true;
+    }
+    async muteAll(groupId, enable = true) {
+        await this.callApi('set_group_whole_mute', { group_id: groupId, is_mute: enable });
+        return true;
+    }
+    async setAdmin(groupId, userId, enable = true) {
+        await this.callApi('set_group_member_admin', {
+            group_id: groupId,
+            user_id: userId,
+            is_set: enable,
+        });
+        return true;
+    }
+    async setCard(groupId, userId, card) {
+        await this.callApi('set_group_member_card', {
+            group_id: groupId,
+            user_id: userId,
+            card,
+        });
+        return true;
+    }
+    async setTitle(groupId, userId, title) {
+        await this.callApi('set_group_member_special_title', {
+            group_id: groupId,
+            user_id: userId,
+            special_title: title,
+        });
+        return true;
+    }
+    async setGroupName(groupId, name) {
+        await this.callApi('set_group_name', { group_id: groupId, new_group_name: name });
+        return true;
+    }
+    async getMemberList(groupId) {
+        return this.callApi('get_group_member_list', { group_id: groupId });
+    }
+    async getGroupInfo(groupId) {
+        return this.callApi('get_group_info', { group_id: groupId });
+    }
+    /** Test / internal: admit a parsed event when the endpoint is open. */
+    admit(event) {
+        const data = parseMessageReceiveData(event);
+        if (!this.#open || !data)
+            return;
+        this.#admitMessage(data, event);
+    }
+    apiOptions() {
+        return {
+            baseUrl: this.#options.config.baseUrl,
+            access_token: this.#options.config.access_token,
+        };
+    }
+    #admitMessage(data, event) {
+        const target = formatInboundTarget(data);
+        const content = formatInboundContent(data);
+        const audioUrl = extractInboundAudioUrl(data);
+        const nickname = senderNickname(data);
+        const mentioned = isMentioned(data, event.self_id);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content,
+            sender: String(data.sender_id),
+            id: formatInboundMessageId(data),
+            metadata: Object.freeze({
+                message_scene: data.message_scene,
+                peer_id: String(data.peer_id),
+                sender_id: String(data.sender_id),
+                message_seq: data.message_seq,
+                endpoint: this.#options.config.name,
+                time: data.time ?? event.time,
+                self_id: event.self_id != null ? String(event.self_id) : undefined,
+                ...(nickname ? { nickname } : {}),
+                ...(mentioned ? { mentioned: true } : {}),
+                ...(audioUrl ? { audio_url: audioUrl } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'milky_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async #connect() {
+        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;
+            ws.on('open', () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (!this.#options.config.access_token) {
+                    logger.warn(formatCompact({
+                        endpoint: this.#options.config.name,
+                        ok: false,
+                        error: 'missing access_token',
+                    }));
+                }
+                logger.debug(formatCompact({
+                    endpoint: this.#options.config.name,
+                    mode: 'ws',
+                    url: safeUrl,
+                }));
+                this.#startHeartbeat();
+                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);
+                const codeHint = codeNum === 1005
+                    ? ' [无状态，多为服务端/代理未发 close 帧即断开]'
+                    : codeNum === 1006
+                        ? ' [异常关闭]'
+                        : '';
+                logger.warn(formatCompact({
+                    op: 'disconnect',
+                    endpoint: this.#options.config.name,
+                    code: codeNum,
+                    error: `${reasonStr || 'closed'}${codeHint}`,
+                    reconnect_ms: this.#options.config.reconnect_interval,
+                }));
+                if (!settled) {
+                    settled = true;
+                    reject(new Error(`Milky WS 关闭: ${codeNum} ${reasonStr}`));
+                }
+                this.#scheduleReconnect();
+            });
+            ws.on('error', (err) => {
+                const error = err instanceof Error ? err : new Error(String(err));
+                logger.warn(formatCompact({
+                    op: 'ws_error',
+                    endpoint: this.#options.config.name,
+                    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 event = JSON.parse(raw);
+            this.admit(event);
+        }
+        catch (error) {
+            logger.warn(formatCompact({
+                op: 'milky_parse_failed',
+                endpoint: this.#options.config.name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+    #startHeartbeat() {
+        if (this.#heartbeatTimer) {
+            clearInterval(this.#heartbeatTimer);
+        }
+        const interval = this.#options.config.heartbeat_interval;
+        if (interval <= 0)
+            return;
+        this.#heartbeatTimer = setInterval(() => {
+            try {
+                if (this.#ws?.readyState === WS_OPEN)
+                    this.#ws.ping?.();
+            }
+            catch {
+                /* ignore */
+            }
+        }, interval);
+    }
+    #scheduleReconnect() {
+        if (this.#stopping || !this.#started || this.#reconnectTimer)
+            return;
+        const delay = this.#options.config.reconnect_interval;
+        this.#reconnectTimer = setTimeout(() => {
+            this.#reconnectTimer = undefined;
+            void this.#connect().catch((err) => {
+                logger.warn(formatCompact({
+                    op: 'reconnect',
+                    endpoint: this.#options.config.name,
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+            });
+        }, delay);
+    }
+}

package/lib/ws-types.d.ts

@@ -0,0 +1,11 @@
+/** Minimal WS surface used by the endpoint (real `ws` or test mock). */
+export interface MilkyWsSocket {
+    readonly readyState: number;
+    send?(data: string): void;
+    close(code?: number, reason?: string): void;
+    ping?(): void;
+    on(event: 'open' | 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+}
+export interface MilkyWsCreateOptions {
+    readonly headers?: Record<string, string>;
+}

package/lib/ws-types.js

@@ -0,0 +1 @@
+export {};

package/lib/wss-endpoint.d.ts

@@ -0,0 +1,40 @@
+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 { callApi, type MilkyEvent, type MilkyWssConfig } from './protocol.js';
+export interface MilkyWssEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly config: MilkyWssConfig;
+    readonly callApi?: typeof callApi;
+}
+export declare class MilkyWssEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: MilkyWssEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+    recallMessage(id: string): Promise<void>;
+    kickMember(groupId: number, userId: number, rejectAddRequest?: boolean): Promise<boolean>;
+    muteMember(groupId: number, userId: number, duration?: number): Promise<boolean>;
+    muteAll(groupId: number, enable?: boolean): Promise<boolean>;
+    setAdmin(groupId: number, userId: number, enable?: boolean): Promise<boolean>;
+    setCard(groupId: number, userId: number, card: string): Promise<boolean>;
+    setTitle(groupId: number, userId: number, title: string): Promise<boolean>;
+    setGroupName(groupId: number, name: string): Promise<boolean>;
+    getMemberList(groupId: number): Promise<unknown[]>;
+    getGroupInfo(groupId: number): Promise<unknown>;
+    admit(event: MilkyEvent): void;
+    apiOptions(): {
+        baseUrl: string;
+        access_token?: string;
+    };
+}

package/lib/wss-endpoint.js

@@ -0,0 +1,263 @@
+/**
+ * Milky reverse WSS endpoint — httpHostToken WS upgrade inbound + baseUrl HTTP API outbound.
+ */
+import { clearInterval } from 'node:timers';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { verifyMilkyAccessToken } from './milky-auth.js';
+import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
+import { buildSendAction, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
+const logger = getLogger('milky');
+const WS_OPEN = 1;
+export class MilkyWssEndpoint {
+    #options;
+    #callApi;
+    #ws;
+    #wsRelease;
+    #heartbeatTimer;
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+        this.#callApi = options.callApi ?? callApi;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#unregisterAgent = registerMilkyAgentEndpoint(this.#options.config.name, this);
+        const handle = this.#options.http.ws(this.#options.config.path);
+        this.#wsRelease = handle.onConnection((connection) => {
+            this.#acceptConnection(connection);
+        });
+        logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.name,
+            mode: 'wss',
+            path: this.#options.config.path,
+        }));
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        this.#wsRelease?.();
+        this.#wsRelease = undefined;
+        if (this.#heartbeatTimer) {
+            clearInterval(this.#heartbeatTimer);
+            this.#heartbeatTimer = undefined;
+        }
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#ws = undefined;
+        }
+        this.#started = false;
+    }
+    async send({ target, payload }) {
+        const message = formatOutboundSegments(payload);
+        const { action, params } = buildSendAction(target, message);
+        const data = await this.callApi(action, params);
+        const messageId = formatOutboundMessageId(target, data?.message_seq);
+        logger.debug(formatCompact({
+            op: 'milky_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId,
+        }));
+        return messageId;
+    }
+    callApi(action, params = {}) {
+        return this.#callApi(this.apiOptions(), action, params);
+    }
+    async recallMessage(id) {
+        const parsed = parseMilkyMessageId(id);
+        if (!parsed)
+            throw new Error(`Invalid message id: ${id}`);
+        if (parsed.message_scene === 'group') {
+            await this.callApi('recall_group_message', {
+                group_id: parsed.peer_id,
+                message_seq: parsed.message_seq,
+            });
+        }
+        else {
+            await this.callApi('recall_private_message', {
+                user_id: parsed.peer_id,
+                message_seq: parsed.message_seq,
+            });
+        }
+    }
+    async kickMember(groupId, userId, rejectAddRequest = false) {
+        await this.callApi('kick_group_member', {
+            group_id: groupId,
+            user_id: userId,
+            reject_add_request: rejectAddRequest,
+        });
+        return true;
+    }
+    async muteMember(groupId, userId, duration = 600) {
+        await this.callApi('set_group_member_mute', {
+            group_id: groupId,
+            user_id: userId,
+            duration,
+        });
+        return true;
+    }
+    async muteAll(groupId, enable = true) {
+        await this.callApi('set_group_whole_mute', { group_id: groupId, is_mute: enable });
+        return true;
+    }
+    async setAdmin(groupId, userId, enable = true) {
+        await this.callApi('set_group_member_admin', {
+            group_id: groupId,
+            user_id: userId,
+            is_set: enable,
+        });
+        return true;
+    }
+    async setCard(groupId, userId, card) {
+        await this.callApi('set_group_member_card', {
+            group_id: groupId,
+            user_id: userId,
+            card,
+        });
+        return true;
+    }
+    async setTitle(groupId, userId, title) {
+        await this.callApi('set_group_member_special_title', {
+            group_id: groupId,
+            user_id: userId,
+            special_title: title,
+        });
+        return true;
+    }
+    async setGroupName(groupId, name) {
+        await this.callApi('set_group_name', { group_id: groupId, new_group_name: name });
+        return true;
+    }
+    async getMemberList(groupId) {
+        return this.callApi('get_group_member_list', { group_id: groupId });
+    }
+    async getGroupInfo(groupId) {
+        return this.callApi('get_group_info', { group_id: groupId });
+    }
+    admit(event) {
+        const data = parseMessageReceiveData(event);
+        if (!this.#open || !data)
+            return;
+        this.#admitMessage(data, event);
+    }
+    apiOptions() {
+        return {
+            baseUrl: this.#options.config.baseUrl,
+            access_token: this.#options.config.access_token,
+        };
+    }
+    #admitMessage(data, event) {
+        const target = formatInboundTarget(data);
+        const content = formatInboundContent(data);
+        const audioUrl = extractInboundAudioUrl(data);
+        const nickname = senderNickname(data);
+        const mentioned = isMentioned(data, event.self_id);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content,
+            sender: String(data.sender_id),
+            id: formatInboundMessageId(data),
+            metadata: Object.freeze({
+                message_scene: data.message_scene,
+                peer_id: String(data.peer_id),
+                sender_id: String(data.sender_id),
+                message_seq: data.message_seq,
+                endpoint: this.#options.config.name,
+                time: data.time ?? event.time,
+                self_id: event.self_id != null ? String(event.self_id) : undefined,
+                ...(nickname ? { nickname } : {}),
+                ...(mentioned ? { mentioned: true } : {}),
+                ...(audioUrl ? { audio_url: audioUrl } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'milky_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #acceptConnection(connection) {
+        if (!verifyMilkyAccessToken(this.#options.config.access_token, connection.request)) {
+            connection.socket.close(4003, 'Unauthorized');
+            return;
+        }
+        const socket = connection.socket;
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.#ws = socket;
+        this.#startHeartbeat();
+        socket.on('message', (data) => {
+            this.#onMessage(data);
+        });
+        socket.on('close', () => {
+            if (this.#ws === socket)
+                this.#ws = undefined;
+        });
+        logger.debug(formatCompact({
+            endpoint: this.#options.config.name,
+            mode: 'wss',
+            peer: connection.request.socket.remoteAddress,
+        }));
+    }
+    #onMessage(data) {
+        try {
+            const raw = typeof data === 'string'
+                ? data
+                : Buffer.isBuffer(data)
+                    ? data.toString()
+                    : data instanceof ArrayBuffer
+                        ? new TextDecoder().decode(data)
+                        : String(data ?? '');
+            const event = JSON.parse(raw);
+            this.admit(event);
+        }
+        catch (error) {
+            logger.warn(formatCompact({
+                op: 'milky_parse_failed',
+                endpoint: this.#options.config.name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+    #startHeartbeat() {
+        if (this.#heartbeatTimer)
+            clearInterval(this.#heartbeatTimer);
+        const interval = this.#options.config.heartbeat_interval;
+        if (interval <= 0)
+            return;
+        this.#heartbeatTimer = setInterval(() => {
+            try {
+                if (this.#ws?.readyState === WS_OPEN)
+                    this.#ws.ping?.();
+            }
+            catch {
+                /* ignore */
+            }
+        }, interval);
+    }
+}