@zhin.js/adapter-milky 7.0.0 → 7.0.1

package/lib/wss-endpoint.js

@@ -1,39 +1,62 @@
 /**
  * Milky reverse WSS endpoint — httpHostToken WS upgrade inbound + baseUrl HTTP API outbound.
  */
-import { clearInterval } from 'node:timers';
-import { createRecallEndpointControl, } from 'zhin.js/adapter';
+import { ClientEndpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 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';
 const WS_OPEN = 1;
-export class MilkyWssEndpoint {
+export class MilkyWssEndpoint extends ClientEndpoint {
+    client;
     #logger;
     #options;
     #callApi;
-    management = createMilkyEndpointManagement(this);
+    management;
     control = createRecallEndpointControl((id) => this.recallMessage(id));
     #ws;
     #wsRelease;
-    #heartbeatTimer;
-    #open = false;
-    #started = false;
-    #unregisterAgent;
+    #clientSocketRelease;
+    #lifecycle;
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('milky', options.config.id);
         this.#options = options;
         this.#callApi = options.callApi ?? callApi;
+        this.#lifecycle = createEndpointLifecycle({
+            name: options.config.id,
+            reconnect: false,
+            heartbeat: { intervalMs: options.config.heartbeat_interval },
+        });
+        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);
-        const handle = this.#options.http.ws(this.#options.config.path);
-        this.#wsRelease = handle.onConnection((connection) => {
-            this.#acceptConnection(connection);
+        await this.#lifecycle.start(async (lifecycleHandle) => {
+            const handle = this.#options.http.ws(this.#options.config.path);
+            this.#wsRelease = handle.onConnection((connection) => {
+                this.#acceptConnection(connection);
+            });
+            lifecycleHandle.onForceClose(() => {
+                this.#wsRelease?.();
+                this.#wsRelease = undefined;
+                this.#clientSocketRelease?.();
+                this.#clientSocketRelease = undefined;
+                try {
+                    this.#ws?.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                this.#ws = undefined;
+            });
         });
         this.#logger.info(formatCompact({
             op: 'listen',
@@ -42,37 +65,14 @@ export class MilkyWssEndpoint {
             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;
+        this.close();
+        await this.#lifecycle.stop();
     }
     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',
@@ -82,91 +82,31 @@ export class MilkyWssEndpoint {
         }));
         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);
@@ -176,7 +116,7 @@ export class MilkyWssEndpoint {
         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,
@@ -216,13 +156,24 @@ export class MilkyWssEndpoint {
             }
         }
         this.#ws = socket;
-        this.#startHeartbeat();
-        socket.on('message', (data) => {
-            this.#onMessage(data);
+        this.#lifecycle.startHeartbeat(() => {
+            try {
+                if (this.#ws?.readyState === WS_OPEN)
+                    this.#ws.ping?.();
+            }
+            catch {
+                /* ignore */
+            }
         });
+        this.#clientSocketRelease?.();
+        this.#clientSocketRelease = this.client.acceptWebSocket(socket);
         socket.on('close', () => {
-            if (this.#ws === socket)
+            this.#clientSocketRelease?.();
+            this.#clientSocketRelease = undefined;
+            if (this.#ws === socket) {
                 this.#ws = undefined;
+                this.#lifecycle.stopHeartbeat();
+            }
         });
         this.#logger.debug(formatCompact({
             endpoint: this.#options.config.id,
@@ -230,40 +181,4 @@ export class MilkyWssEndpoint {
             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) {
-            this.#logger.warn(formatCompact({
-                op: 'milky_parse_failed',
-                endpoint: this.#options.config.id,
-                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);
-    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-milky",
-  "version": "7.0.0",
+  "version": "7.0.1",
   "description": "Zhin.js Milky adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -39,12 +39,15 @@
     "directory": "plugins/adapters/milky"
   },
   "dependencies": {
+    "@imhelper/milky-v1": "1.0.7",
+    "imhelper": "1.0.7",
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/core": "1.5.13",
-    "@zhin.js/host-http": "1.0.12",
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/core": "1.5.14",
+    "@zhin.js/feature-kit": "1.0.13",
+    "@zhin.js/host-http": "1.0.13",
     "@zhin.js/im-contract": "1.0.4",
-    "@zhin.js/logger": "1.0.76"
+    "@zhin.js/logger": "1.0.77"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -52,17 +55,17 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.15",
-    "@zhin.js/host-http": "1.0.12",
-    "zhin.js": "6.0.13"
+    "@zhin.js/agent": "1.1.16",
+    "@zhin.js/host-http": "1.0.13",
+    "zhin.js": "6.0.14"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/agent": "1.1.15",
-    "@zhin.js/command": "1.0.15",
-    "@zhin.js/core": "1.5.13",
-    "zhin.js": "6.0.13"
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/agent": "1.1.16",
+    "@zhin.js/command": "1.0.16",
+    "@zhin.js/core": "1.5.14",
+    "zhin.js": "6.0.14"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {

package/src/client.ts

@@ -0,0 +1,80 @@
+import {
+  MilkyV1Client,
+  type MilkyV1Event,
+  type MilkyV1Response,
+} from '@imhelper/milky-v1';
+import {
+  EventFactory,
+  type EventMap,
+  type ImHelperEventMap,
+} from 'imhelper';
+import {
+  defineEndpointClient,
+  forwardEndpointClientEvents,
+  type ClientEventPayloads,
+} from 'zhin.js/adapter';
+import type { ResolvedMilkyConfig, callApi } from './protocol.js';
+
+export { MilkyV1Client as MilkyClient } from '@imhelper/milky-v1';
+
+type MilkyClientEvents = ImHelperEventMap<string, MilkyV1Event, EventMap<string>>;
+export type MilkyClientEventMap = ClientEventPayloads<MilkyClientEvents>;
+
+/** Construct the exact public imhelper Client without handing it transport ownership. */
+export function createMilkyEndpointClient(
+  config: ResolvedMilkyConfig,
+  request: typeof callApi,
+): MilkyV1Client {
+  return new MilkyV1Client({
+    baseUrl: config.baseUrl,
+    selfId: config.id,
+    accessToken: config.access_token,
+    receiveMode: 'manual',
+    call: (action, params) => request(
+      {
+        baseUrl: config.baseUrl,
+        access_token: config.access_token,
+      },
+      action,
+      params,
+    ),
+  });
+}
+
+/** Use the Client's complete protocol response while keeping Endpoint internals data-oriented. */
+export async function callMilkyClient<T = unknown>(
+  client: MilkyV1Client,
+  action: string,
+  params?: Record<string, unknown>,
+): Promise<T | undefined> {
+  const response: MilkyV1Response<T> = await client.call<T>(action, params);
+  if (response.status !== 'ok') {
+    throw new Error(
+      `Milky API ${action}: retcode=${response.retcode}${response.message ? ` ${response.message}` : ''}`,
+    );
+  }
+  return response.data;
+}
+
+const milkyClientEventNames = Object.freeze([
+  ...EventFactory.getSupportedEventTypes<string>(),
+  'event',
+]);
+
+export function forwardMilkyClientEvents(
+  client: MilkyV1Client,
+  receive: (name: string, payload: unknown) => void,
+): () => void {
+  return forwardEndpointClientEvents(client, milkyClientEventNames, receive);
+}
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly milky: {
+      readonly client: MilkyV1Client;
+      readonly events: MilkyClientEventMap;
+    };
+  }
+}
+
+export const milkyClient = defineEndpointClient<MilkyV1Client, MilkyClientEventMap>('milky');

package/src/endpoint.ts

@@ -21,6 +21,6 @@ export {
 
 export type { MilkyWsSocket, MilkyWsCreateOptions } from './ws-types.js';
 
-export { verifyMilkyAccessToken, readRequestBody } from './milky-auth.js';
+export { verifyMilkyAccessToken } from './milky-auth.js';
 
 export { openSseStream, consumeSseBuffer } from './sse-client.js';

package/src/index.ts

@@ -36,7 +36,6 @@ export {
   MilkyWsEndpoint,
   consumeSseBuffer,
   openSseStream,
-  readRequestBody,
   verifyMilkyAccessToken,
   type CreateMilkySseStream,
   type MilkySseEndpointOptions,
@@ -48,9 +47,20 @@ export {
 } from './endpoint.js';
 
 export {
-  getMilkyAgentDeps,
-  registerMilkyAgentEndpoint,
-  setMilkyAgentDeps,
-  type MilkyAgentDeps,
-  type MilkyAgentEndpoint,
-} from './milky-agent-deps.js';
+  MilkyClient,
+  milkyClient,
+  type MilkyClientEventMap,
+} from './client.js';
+
+export type {
+  MilkyAdapterConfig as ImHelperMilkyAdapterConfig,
+  MilkyActionUrlResolver,
+  MilkyCall,
+  MilkyMessageReceiveEvent,
+  MilkyMessageRecallEvent,
+  MilkyV1ClientConfig,
+  MilkyV1Event,
+  MilkyV1Response,
+} from '@imhelper/milky-v1';
+export { ProtocolError } from '@imhelper/milky-v1';
+export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';

package/src/milky-auth.ts

@@ -12,18 +12,3 @@ export function verifyMilkyAccessToken(accessToken: string | undefined, request:
   }
   return false;
 }
-
-export async function readRequestBody(request: IncomingMessage): Promise<string> {
-  const chunks: Buffer[] = [];
-  let size = 0;
-  for await (const chunk of request) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    size += buffer.length;
-    if (size > 1_048_576) {
-      request.destroy();
-      throw new Error('Request body exceeds 1MB');
-    }
-    chunks.push(buffer);
-  }
-  return Buffer.concat(chunks).toString('utf8');
-}

package/src/protocol.ts

@@ -77,7 +77,7 @@ export type ResolvedMilkyConfig =
 export type MilkyEndpointConfig = ResolvedMilkyConfig;
 
 export interface MilkyApiResponse<T = unknown> {
-  status: string;
+  status: 'ok' | 'failed';
   retcode: number;
   data?: T;
   message?: string;
@@ -203,13 +203,13 @@ function authQuery(access_token?: string): string {
 
 /**
  * 调用协议端 API：POST {baseUrl}/api/{apiName}，Body JSON，鉴权。
- * 非 200 或 retcode !== 0 时抛错。
+ * HTTP 层错误抛出；协议响应原样返回，由 Client 公开 call() 保留完整语义。
  */
 export async function callApi<T = unknown>(
   options: MilkyApiClientOptions,
   apiName: string,
   params: Record<string, unknown> = {},
-): Promise<T> {
+): Promise<MilkyApiResponse<T>> {
   const { baseUrl, access_token } = options;
   const url = new URL(`/api/${apiName}`, baseUrl.replace(/\/$/, ''));
   const q = authQuery(access_token);
@@ -235,10 +235,7 @@ export async function callApi<T = unknown>(
   if (res.status !== 200) {
     throw new Error(`Milky API ${apiName}: HTTP ${res.status} ${body.message ?? text}`);
   }
-  if (body.retcode !== 0) {
-    throw new Error(`Milky API ${apiName}: retcode=${body.retcode} ${body.message ?? ''}`);
-  }
-  return (body.data ?? {}) as T;
+  return body;
 }
 
 /** 根据 event_type 判断是否为 message_receive，并解析 data */