@zhin.js/adapter-milky 6.0.14 → 7.0.1

package/lib/webhook-endpoint.d.ts

@@ -1,39 +1,22 @@
-import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+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 { callApi, type MilkyEvent, type MilkyWebhookConfig } from './protocol.js';
+import { type MilkyClient } from './client.js';
+import { callApi, type MilkyWebhookConfig } from './protocol.js';
 export interface MilkyWebhookEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: MilkyWebhookConfig;
     readonly callApi?: typeof callApi;
 }
-export declare class MilkyWebhookEndpoint implements EndpointInstance {
+export declare class MilkyWebhookEndpoint extends ClientEndpoint<MilkyClient> {
     #private;
+    readonly client: MilkyClient;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
     constructor(options: MilkyWebhookEndpointOptions);
     start(): Promise<void>;
-    open(): void;
-    close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): 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/webhook-endpoint.js

@@ -1,27 +1,36 @@
+import { ClientEndpoint, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
-import { readRequestBody, verifyMilkyAccessToken } from './milky-auth.js';
+import { verifyMilkyAccessToken } from './milky-auth.js';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
-import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
+import { callMilkyClient, createMilkyEndpointClient, forwardMilkyClientEvents } from './client.js';
 import { buildSendAction, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatOutboundMessageId, formatOutboundSegments, isMentioned, milkyInboundConversation, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
-export class MilkyWebhookEndpoint {
+export class MilkyWebhookEndpoint extends ClientEndpoint {
+    client;
     #logger;
     #options;
     #callApi;
-    management = createMilkyEndpointManagement(this);
+    management;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
     #routeReleases = [];
-    #open = false;
     #started = false;
-    #unregisterAgent;
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('milky', options.config.id);
         this.#options = options;
         this.#callApi = options.callApi ?? callApi;
+        this.client = createMilkyEndpointClient(options.config, this.#callApi);
+        this.management = createMilkyEndpointManagement({
+            callApi: (action, params) => callMilkyClient(this.client, action, params),
+        });
+        this.bindClientEvents((receive) => forwardMilkyClientEvents(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;
-        this.#unregisterAgent = registerMilkyAgentEndpoint(this.#options.config.id, this);
         this.#setupRoutes();
         this.#logger.info(formatCompact({
             op: 'listen',
@@ -30,25 +39,17 @@ export class MilkyWebhookEndpoint {
             path: this.#options.config.path,
         }));
     }
-    open() {
-        this.#open = true;
-    }
-    close() {
-        this.#open = false;
-    }
     async stop() {
-        this.#open = false;
+        this.close();
         for (const release of this.#routeReleases.splice(0))
             release();
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
         this.#started = false;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
         const { action, params } = buildSendAction(conversation, message);
-        const data = await this.callApi(action, params);
+        const data = await callMilkyClient(this.client, action, params);
         const messageId = formatOutboundMessageId(conversation, data?.message_seq);
         this.#logger.debug(formatCompact({
             op: 'milky_send',
@@ -58,91 +59,31 @@ export class MilkyWebhookEndpoint {
         }));
         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', {
+            await callMilkyClient(this.client, 'recall_group_message', {
                 group_id: parsed.peer_id,
                 message_seq: parsed.message_seq,
             });
         }
         else {
-            await this.callApi('recall_private_message', {
+            await callMilkyClient(this.client, '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) {
+    #admitRaw(event) {
         const data = parseMessageReceiveData(event);
-        if (!this.#open || !data)
+        if (!data)
             return;
         this.#admitMessage(data, event);
     }
-    apiOptions() {
-        return {
-            baseUrl: this.#options.config.baseUrl,
-            access_token: this.#options.config.access_token,
-        };
+    #warnPlatformEvent(error) {
+        this.#logger.warn(formatCompact({ op: 'milky_platform_event_failed', error: error instanceof Error ? error.message : String(error) }));
     }
     #admitMessage(data, event) {
         const conversation = milkyInboundConversation(String(this.#options.id), data);
@@ -152,7 +93,7 @@ export class MilkyWebhookEndpoint {
         const audioUrl = extractInboundAudioUrl(data);
         const nickname = senderNickname(data);
         const mentioned = isMentioned(data, event.self_id);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: formatInboundMessageId(data) },
             content,
@@ -190,20 +131,12 @@ export class MilkyWebhookEndpoint {
                 response.end(JSON.stringify({ message: 'Unauthorized' }));
                 return;
             }
-            const raw = await readRequestBody(request);
-            let event;
-            try {
-                event = JSON.parse(raw);
-            }
-            catch {
-                response.writeHead(400, { 'Content-Type': 'application/json' });
-                response.end(JSON.stringify({ message: 'Invalid JSON' }));
+            if (!this.clientEventsOpen) {
+                response.writeHead(200, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ status: 'ok' }));
                 return;
             }
-            if (this.#open)
-                this.admit(event);
-            response.writeHead(200, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ status: 'ok' }));
+            await this.client.acceptHttp(request, response);
         }
         catch (error) {
             this.#logger.error('Milky webhook error:', error);

package/lib/ws-endpoint.d.ts

@@ -1,41 +1,23 @@
-import { type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { CapabilityId } from 'zhin.js';
-import { callApi, type MilkyEvent, type MilkyWsConfig } from './protocol.js';
+import { type MilkyClient } from './client.js';
+import { callApi, type MilkyWsConfig } from './protocol.js';
 import type { MilkyWsCreateOptions, MilkyWsSocket } from './ws-types.js';
 export interface MilkyWsEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly config: MilkyWsConfig;
     readonly createWebSocket?: (url: string, options: MilkyWsCreateOptions) => MilkyWsSocket;
     readonly callApi?: typeof callApi;
 }
-export declare class MilkyWsEndpoint implements EndpointInstance {
+export declare class MilkyWsEndpoint extends ClientEndpoint<MilkyClient> {
     #private;
+    readonly client: MilkyClient;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
     constructor(options: MilkyWsEndpointOptions);
     start(): Promise<void>;
-    open(): void;
     close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): 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

@@ -2,25 +2,35 @@
  * Milky WS client endpoint — outbound connect to Milky protocol server.
  */
 import WebSocket from 'ws';
-import { createEndpointLifecycle, } from 'zhin.js/adapter';
+import { ClientEndpoint, createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
-import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
+import { callMilkyClient, createMilkyEndpointClient, forwardMilkyClientEvents, } from './client.js';
 import { buildSendAction, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatOutboundMessageId, formatOutboundSegments, isMentioned, milkyInboundConversation, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
 const WS_OPEN = 1;
-export class MilkyWsEndpoint {
+export class MilkyWsEndpoint extends ClientEndpoint {
+    client;
     #logger;
     #options;
     #callApi;
-    management = createMilkyEndpointManagement(this);
+    management;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
     #lifecycle;
     #ws;
-    #open = false;
-    #unregisterAgent;
+    #clientSocketRelease;
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('milky', options.config.id);
         this.#options = options;
         this.#callApi = options.callApi ?? callApi;
+        this.client = createMilkyEndpointClient(options.config, this.#callApi);
+        this.management = createMilkyEndpointManagement({
+            callApi: (action, params) => callMilkyClient(this.client, action, params),
+        });
+        this.bindClientEvents((receive) => forwardMilkyClientEvents(this.client, receive), (name, payload) => {
+            if (name === 'event')
+                this.#admitRaw(payload);
+        }, (_name, error) => this.#warnPlatformEvent(error));
         this.#lifecycle = createEndpointLifecycle({
             name: options.config.id,
             // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
@@ -35,28 +45,16 @@ export class MilkyWsEndpoint {
     async start() {
         if (this.#lifecycle.started)
             return;
-        this.#unregisterAgent = registerMilkyAgentEndpoint(this.#options.config.id, this);
-        try {
-            await this.#lifecycle.start((handle) => this.#connect(handle));
-        }
-        catch (err) {
-            // start 失败复位由基座保证；agent 注册/反注册是适配器专有依赖，留在适配器侧
-            this.#unregisterAgent?.();
-            this.#unregisterAgent = undefined;
-            throw err;
-        }
-    }
-    open() {
-        this.#open = true;
+        await this.#lifecycle.start((handle) => this.#connect(handle));
     }
     close() {
-        this.#open = false;
+        super.close();
+        this.#clientSocketRelease?.();
+        this.#clientSocketRelease = undefined;
     }
     async stop() {
-        this.#open = false;
+        this.close();
         await this.#lifecycle.stop();
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
         if (this.#ws) {
             try {
                 this.#ws.close();
@@ -70,7 +68,7 @@ export class MilkyWsEndpoint {
     async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
         const { action, params } = buildSendAction(conversation, message);
-        const data = await this.callApi(action, params);
+        const data = await callMilkyClient(this.client, action, params);
         const messageId = formatOutboundMessageId(conversation, data?.message_seq);
         this.#logger.debug(formatCompact({
             op: 'milky_send',
@@ -80,93 +78,34 @@ export class MilkyWsEndpoint {
         }));
         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', {
+            await callMilkyClient(this.client, 'recall_group_message', {
                 group_id: parsed.peer_id,
                 message_seq: parsed.message_seq,
             });
         }
         else {
-            await this.callApi('recall_private_message', {
+            await callMilkyClient(this.client, '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) {
+    #admitRaw(event) {
         const data = parseMessageReceiveData(event);
-        if (!this.#open || !data)
+        if (!data)
             return;
         this.#admitMessage(data, event);
     }
-    apiOptions() {
-        return {
-            baseUrl: this.#options.config.baseUrl,
-            access_token: this.#options.config.access_token,
-        };
+    #warnPlatformEvent(error) {
+        this.#logger.warn(formatCompact({
+            op: 'milky_platform_event_failed',
+            error: error instanceof Error ? error.message : String(error),
+        }));
     }
     #admitMessage(data, event) {
         const conversation = milkyInboundConversation(String(this.#options.id), data);
@@ -176,7 +115,7 @@ export class MilkyWsEndpoint {
         const audioUrl = extractInboundAudioUrl(data);
         const nickname = senderNickname(data);
         const mentioned = isMentioned(data, event.self_id);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: formatInboundMessageId(data) },
             content,
@@ -247,10 +186,11 @@ export class MilkyWsEndpoint {
                 }
                 resolve();
             });
-            ws.on('message', (data) => {
-                this.#onMessage(data);
-            });
+            this.#clientSocketRelease?.();
+            this.#clientSocketRelease = this.client.acceptWebSocket(ws);
             ws.on('close', (code, reason) => {
+                this.#clientSocketRelease?.();
+                this.#clientSocketRelease = undefined;
                 const reasonStr = typeof reason === 'string'
                     ? reason
                     : Buffer.isBuffer(reason)
@@ -290,24 +230,4 @@ export class MilkyWsEndpoint {
             });
         });
     }
-    #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) {
-            this.#logger.warn(formatCompact({
-                op: 'milky_parse_failed',
-                endpoint: this.#options.config.id,
-                error: error instanceof Error ? error.message : String(error),
-            }));
-        }
-    }
 }

package/lib/wss-endpoint.d.ts

@@ -1,39 +1,25 @@
-import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+/**
+ * Milky reverse WSS endpoint — httpHostToken WS upgrade inbound + baseUrl HTTP API outbound.
+ */
+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 { callApi, type MilkyEvent, type MilkyWssConfig } from './protocol.js';
+import { type MilkyClient } from './client.js';
+import { callApi, type MilkyWssConfig } from './protocol.js';
 export interface MilkyWssEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: MilkyWssConfig;
     readonly callApi?: typeof callApi;
 }
-export declare class MilkyWssEndpoint implements EndpointInstance {
+export declare class MilkyWssEndpoint extends ClientEndpoint<MilkyClient> {
     #private;
+    readonly client: MilkyClient;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
     constructor(options: MilkyWssEndpointOptions);
     start(): Promise<void>;
-    open(): void;
-    close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): 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;
-    };
 }