@zhin.js/adapter-milky 1.1.18 → 1.1.20

package/src/sse-endpoint.ts

@@ -2,7 +2,7 @@
  * Milky SSE client endpoint — GET text/event-stream on /event.
  */
 import {
-  ClientEndpoint,
+  createEndpointSpecification, endpointSpec, type Endpoint, type EndpointSpecification,
   createRecallEndpointControl,
   createEndpointLifecycle,
   type EndpointConnectHandle,
@@ -14,7 +14,7 @@ import {
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
-import { callMilkyClient, createMilkyEndpointClient, forwardMilkyClientEvents, type MilkyClient } from './client.js';
+import { createMilkyActionCaller, readMilkyResponse, type MilkyActionCaller, milkyClientOptions, forwardMilkyClientEvents, MilkyClient } from './client.js';
 import {
   buildSendAction,
   buildSseConnectOptions,
@@ -46,38 +46,49 @@ export type CreateMilkySseStream = (options: {
 
 export interface MilkySseEndpointOptions {
   readonly id: CapabilityId;
+  readonly signal?: AbortSignal;
   readonly config: MilkySseConfig;
   readonly createSseStream?: CreateMilkySseStream;
   readonly callApi?: typeof callApi;
 }
 
-export class MilkySseEndpoint extends ClientEndpoint<MilkyClient> {
-  readonly client: MilkyClient;
+export class MilkySseEndpoint extends MilkyClient implements Endpoint {
+  readonly [endpointSpec]: EndpointSpecification;
+  #open = false;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: MilkySseEndpointOptions;
-  readonly #callApi: typeof callApi;
-  readonly management: EndpointManagement;
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly #management: EndpointManagement;
+  readonly #call: MilkyActionCaller;
+  readonly #control: EndpointControl = createRecallEndpointControl((id, signal) => this.#recallMessage({ id, signal }));
   readonly #lifecycle: EndpointLifecycle;
   #stream?: SseClientHandle;
 
   constructor(options: MilkySseEndpointOptions) {
-    super();
+    const call = createMilkyActionCaller({ config: options.config, request: options.callApi ?? callApi, signal: options.signal });
+    super(milkyClientOptions({ config: options.config, call }));
+    this.#call = call;
     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.#management = createMilkyEndpointManagement({
+      callApi: request => call(request).then(response => readMilkyResponse(response, request.action)),
     });
-    this.bindClientEvents(
-      (receive) => forwardMilkyClientEvents(this.client, receive),
-      (name, payload) => {
+    const readTransportState = () => this.#lifecycle.state;
+    this[endpointSpec] = createEndpointSpecification(this, {
+      name: options.config.id,
+      start: () => this.#start(), open: () => { this.#open = true; },
+      close: () => { this.#open = false; }, stop: () => this.#stop(),
+      send: request => this.#send(request),
+      management: this.#management, control: this.#control,
+      get transportState() { return readTransportState(); },
+    });
+    forwardMilkyClientEvents(this, (name, payload) => {
+      void this[endpointSpec].events.run(() => {
+        if (!this.#open && !this.#lifecycle.started) return;
+        void this[endpointSpec].events.platform(name, payload).catch(error => this.#warnPlatformEvent(error));
         if (name === 'event') this.#admitRaw(payload as MilkyEvent);
-      },
-      (_name, error) => this.#warnPlatformEvent(error),
-    );
+      }).catch(error => this.#warnPlatformEvent(error));
+    });
     this.#lifecycle = createEndpointLifecycle({
       name: options.config.id,
       // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
@@ -90,7 +101,7 @@ export class MilkySseEndpoint extends ClientEndpoint<MilkyClient> {
     });
   }
 
-  async start(): Promise<void> {
+  async #start(): Promise<void> {
     if (this.#lifecycle.started) return;
     try {
       await this.#lifecycle.start((handle) => this.#connect(handle));
@@ -100,17 +111,17 @@ export class MilkySseEndpoint extends ClientEndpoint<MilkyClient> {
     }
   }
 
-  async stop(): Promise<void> {
-    this.close();
+  async #stop(): Promise<void> {
+    this.#open = false;
     await this.#lifecycle.stop();
     this.#stream?.close();
     this.#stream = undefined;
   }
 
-  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+  async #send({ conversation, payload, signal }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
     const { action, params } = buildSendAction(conversation, message);
-    const data = await callMilkyClient<{ message_seq?: number }>(this.client, action, params);
+    const data = readMilkyResponse<{ message_seq?: number }>(await this.#call({ action, params, signal }), action);
     const messageId = formatOutboundMessageId(conversation, data?.message_seq);
     this.#logger.debug(formatCompact({
       op: 'milky_send',
@@ -122,23 +133,24 @@ export class MilkySseEndpoint extends ClientEndpoint<MilkyClient> {
     return messageId;
   }
 
-  async recallMessage(id: string): Promise<void> {
+  async #recallMessage({ id, signal }: { readonly id: string; readonly signal?: AbortSignal }): Promise<void> {
     const parsed = parseMilkyMessageId(id);
     if (!parsed) throw new Error(`Invalid message id: ${id}`);
     if (parsed.message_scene === 'group') {
-      await callMilkyClient(this.client, 'recall_group_message', {
+      readMilkyResponse(await this.#call({ action: 'recall_group_message', signal, params: {
         group_id: parsed.peer_id,
         message_seq: parsed.message_seq,
-      });
+      } }), 'recall_group_message');
     } else {
-      await callMilkyClient(this.client, 'recall_private_message', {
+      readMilkyResponse(await this.#call({ action: 'recall_private_message', signal, params: {
         user_id: parsed.peer_id,
         message_seq: parsed.message_seq,
-      });
+      } }), 'recall_private_message');
     }
   }
 
   #admitRaw(event: MilkyEvent): void {
+    if (event.self_id != null) this[endpointSpec].reportSelfUserId(String(event.self_id));
     const data = parseMessageReceiveData(event);
     if (!data) return;
     this.#admitMessage(data, event);
@@ -149,14 +161,16 @@ export class MilkySseEndpoint extends ClientEndpoint<MilkyClient> {
   }
 
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
-    const conversation = milkyInboundConversation(String(this.#options.id), data);
+    const conversation = { ...milkyInboundConversation(String(this.#options.id), data), endpoint: this[endpointSpec].identity };
     const target = `${conversation.kind}:${conversation.id}`;
     const content = formatInboundContent(data);
     const segments = formatInboundSegments(data);
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
-    void this.emit('message.receive', {
+    void this[endpointSpec].events.message({
+      event,
+      ...(typeof event.time === 'number' ? { platformSentAt: event.time * 1000 } : {}),
       conversation,
       message: { conversation, id: formatInboundMessageId(data) },
       content,
@@ -245,7 +259,7 @@ export class MilkySseEndpoint extends ClientEndpoint<MilkyClient> {
   #onMessage(data: string): void {
     try {
       const event = JSON.parse(data) as MilkyEvent;
-      this.client.ingest(event as Parameters<MilkyClient['ingest']>[0]);
+      this.ingest(event as Parameters<MilkyClient['ingest']>[0]);
     } catch (error) {
       this.#logger.warn(formatCompact({
         op: 'milky_parse_failed',

package/src/webhook-endpoint.ts

@@ -2,8 +2,9 @@
  * Milky webhook endpoint — httpHostToken POST inbound + baseUrl HTTP API outbound.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { acceptHttpIngress } from 'imhelper';
 import {
-  ClientEndpoint,
+  createEndpointSpecification, endpointSpec, type Endpoint, type EndpointSpecification,
   createRecallEndpointControl,
   type EndpointControl,
   type EndpointManagement,
@@ -14,7 +15,7 @@ import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { verifyMilkyAccessToken } from './milky-auth.js';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
-import { callMilkyClient, createMilkyEndpointClient, forwardMilkyClientEvents, type MilkyClient } from './client.js';
+import { createMilkyActionCaller, readMilkyResponse, type MilkyActionCaller, milkyClientOptions, forwardMilkyClientEvents, MilkyClient } from './client.js';
 import {
   buildSendAction,
   callApi,
@@ -36,41 +37,50 @@ import {
 
 export interface MilkyWebhookEndpointOptions {
   readonly id: CapabilityId;
+  readonly signal?: AbortSignal;
   readonly http: HttpHost;
   readonly config: MilkyWebhookConfig;
   readonly callApi?: typeof callApi;
 }
 
-export class MilkyWebhookEndpoint extends ClientEndpoint<MilkyClient> {
-  readonly client: MilkyClient;
+export class MilkyWebhookEndpoint extends MilkyClient implements Endpoint {
+  readonly [endpointSpec]: EndpointSpecification;
+  #open = false;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: MilkyWebhookEndpointOptions;
-  readonly #callApi: typeof callApi;
-  readonly management: EndpointManagement;
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly #management: EndpointManagement;
+  readonly #call: MilkyActionCaller;
+  readonly #control: EndpointControl = createRecallEndpointControl((id, signal) => this.#recallMessage({ id, signal }));
   #routeReleases: HttpRouteRegistration[] = [];
   #started = false;
 
   constructor(options: MilkyWebhookEndpointOptions) {
-    super();
+    const call = createMilkyActionCaller({ config: options.config, request: options.callApi ?? callApi, signal: options.signal });
+    super(milkyClientOptions({ config: options.config, call }));
+    this.#call = call;
     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.#management = createMilkyEndpointManagement({
+      callApi: request => call(request).then(response => readMilkyResponse(response, request.action)),
     });
-    this.bindClientEvents(
-      (receive) => forwardMilkyClientEvents(this.client, receive),
-      (name, payload) => {
+    this[endpointSpec] = createEndpointSpecification(this, {
+      name: options.config.id,
+      start: () => this.#start(), open: () => { this.#open = true; },
+      close: () => { this.#open = false; }, stop: () => this.#stop(),
+      send: request => this.#send(request),
+      management: this.#management, control: this.#control,
+    });
+    forwardMilkyClientEvents(this, (name, payload) => {
+      void this[endpointSpec].events.run(() => {
+        if (!this.#started) return;
+        void this[endpointSpec].events.platform(name, payload).catch(error => this.#warnPlatformEvent(error));
         if (name === 'event') this.#admitRaw(payload as MilkyEvent);
-      },
-      (_name, error) => this.#warnPlatformEvent(error),
-    );
+      }).catch(error => this.#warnPlatformEvent(error));
+    });
   }
 
-  async start(): Promise<void> {
+  async #start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
     this.#setupRoutes();
@@ -82,17 +92,17 @@ export class MilkyWebhookEndpoint extends ClientEndpoint<MilkyClient> {
     }));
   }
 
-  async stop(): Promise<void> {
-    this.close();
+  async #stop(): Promise<void> {
+    this.#open = false;
     for (const release of this.#routeReleases.splice(0)) release();
     this.#started = false;
     this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+  async #send({ conversation, payload, signal }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
     const { action, params } = buildSendAction(conversation, message);
-    const data = await callMilkyClient<{ message_seq?: number }>(this.client, action, params);
+    const data = readMilkyResponse<{ message_seq?: number }>(await this.#call({ action, params, signal }), action);
     const messageId = formatOutboundMessageId(conversation, data?.message_seq);
     this.#logger.debug(formatCompact({
       op: 'milky_send',
@@ -103,23 +113,24 @@ export class MilkyWebhookEndpoint extends ClientEndpoint<MilkyClient> {
     return messageId;
   }
 
-  async recallMessage(id: string): Promise<void> {
+  async #recallMessage({ id, signal }: { readonly id: string; readonly signal?: AbortSignal }): Promise<void> {
     const parsed = parseMilkyMessageId(id);
     if (!parsed) throw new Error(`Invalid message id: ${id}`);
     if (parsed.message_scene === 'group') {
-      await callMilkyClient(this.client, 'recall_group_message', {
+      readMilkyResponse(await this.#call({ action: 'recall_group_message', signal, params: {
         group_id: parsed.peer_id,
         message_seq: parsed.message_seq,
-      });
+      } }), 'recall_group_message');
     } else {
-      await callMilkyClient(this.client, 'recall_private_message', {
+      readMilkyResponse(await this.#call({ action: 'recall_private_message', signal, params: {
         user_id: parsed.peer_id,
         message_seq: parsed.message_seq,
-      });
+      } }), 'recall_private_message');
     }
   }
 
   #admitRaw(event: MilkyEvent): void {
+    if (event.self_id != null) this[endpointSpec].reportSelfUserId(String(event.self_id));
     const data = parseMessageReceiveData(event);
     if (!data) return;
     this.#admitMessage(data, event);
@@ -130,14 +141,16 @@ export class MilkyWebhookEndpoint extends ClientEndpoint<MilkyClient> {
   }
 
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
-    const conversation = milkyInboundConversation(String(this.#options.id), data);
+    const conversation = { ...milkyInboundConversation(String(this.#options.id), data), endpoint: this[endpointSpec].identity };
     const target = `${conversation.kind}:${conversation.id}`;
     const content = formatInboundContent(data);
     const segments = formatInboundSegments(data);
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
-    void this.emit('message.receive', {
+    void this[endpointSpec].events.message({
+      event,
+      ...(typeof event.time === 'number' ? { platformSentAt: event.time * 1000 } : {}),
       conversation,
       message: { conversation, id: formatInboundMessageId(data) },
       content,
@@ -179,12 +192,15 @@ export class MilkyWebhookEndpoint extends ClientEndpoint<MilkyClient> {
         response.end(JSON.stringify({ message: 'Unauthorized' }));
         return;
       }
-      if (!this.clientEventsOpen) {
+      if (!this.#open) {
         response.writeHead(200, { 'Content-Type': 'application/json' });
         response.end(JSON.stringify({ status: 'ok' }));
         return;
       }
-      await this.client.acceptHttp(request, response);
+      await acceptHttpIngress<MilkyEvent>(request, response, event => {
+        void this[endpointSpec].events.run(() => this.ingest(event as Parameters<MilkyClient['ingest']>[0]))
+          .catch(error => this.#warnPlatformEvent(error));
+      });
     } catch (error) {
       this.#logger.error('Milky webhook error:', error);
       if (!response.headersSent) {

package/src/ws-endpoint.ts

@@ -3,7 +3,7 @@
  */
 import WebSocket from 'ws';
 import {
-  ClientEndpoint,
+  createEndpointSpecification, endpointSpec, type Endpoint, type EndpointSpecification,
   createRecallEndpointControl,
   createEndpointLifecycle,
   type EndpointConnectHandle,
@@ -16,10 +16,10 @@ import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
 import {
-  callMilkyClient,
-  createMilkyEndpointClient,
+  createMilkyActionCaller, readMilkyResponse, type MilkyActionCaller,
+  milkyClientOptions,
   forwardMilkyClientEvents,
-  type MilkyClient,
+  MilkyClient,
 } from './client.js';
 import {
   buildSendAction,
@@ -46,6 +46,7 @@ const WS_OPEN = 1;
 
 export interface MilkyWsEndpointOptions {
   readonly id: CapabilityId;
+  readonly signal?: AbortSignal;
   readonly config: MilkyWsConfig;
   readonly createWebSocket?: (
     url: string,
@@ -54,34 +55,44 @@ export interface MilkyWsEndpointOptions {
   readonly callApi?: typeof callApi;
 }
 
-export class MilkyWsEndpoint extends ClientEndpoint<MilkyClient> {
-  readonly client: MilkyClient;
+export class MilkyWsEndpoint extends MilkyClient implements Endpoint {
+  readonly [endpointSpec]: EndpointSpecification;
+  #open = false;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: MilkyWsEndpointOptions;
-  readonly #callApi: typeof callApi;
-  readonly management: EndpointManagement;
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly #management: EndpointManagement;
+  readonly #call: MilkyActionCaller;
+  readonly #control: EndpointControl = createRecallEndpointControl((id, signal) => this.#recallMessage({ id, signal }));
   readonly #lifecycle: EndpointLifecycle;
   #ws?: MilkyWsSocket;
   #clientSocketRelease?: () => void;
 
   constructor(options: MilkyWsEndpointOptions) {
-    super();
+    const call = createMilkyActionCaller({ config: options.config, request: options.callApi ?? callApi, signal: options.signal });
+    super(milkyClientOptions({ config: options.config, call }));
+    this.#call = call;
     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.#management = createMilkyEndpointManagement({
+      callApi: request => call(request).then(response => readMilkyResponse(response, request.action)),
     });
-    this.bindClientEvents(
-      (receive) => forwardMilkyClientEvents(this.client, receive),
-      (name, payload) => {
+    const readTransportState = () => this.#lifecycle.state;
+    this[endpointSpec] = createEndpointSpecification(this, {
+      name: options.config.id,
+      start: () => this.#start(), open: () => { this.#open = true; },
+      close: () => { this.#close(); }, stop: () => this.#stop(),
+      send: request => this.#send(request),
+      management: this.#management, control: this.#control,
+      get transportState() { return readTransportState(); },
+    });
+    forwardMilkyClientEvents(this, (name, payload) => {
+      void this[endpointSpec].events.run(() => {
+        if (!this.#open && !this.#lifecycle.started) return;
+        void this[endpointSpec].events.platform(name, payload).catch(error => this.#warnPlatformEvent(error));
         if (name === 'event') this.#admitRaw(payload as MilkyEvent);
-      },
-      (_name, error) => this.#warnPlatformEvent(error),
-    );
+      }).catch(error => this.#warnPlatformEvent(error));
+    });
     this.#lifecycle = createEndpointLifecycle({
       name: options.config.id,
       // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
@@ -94,19 +105,19 @@ export class MilkyWsEndpoint extends ClientEndpoint<MilkyClient> {
     });
   }
 
-  async start(): Promise<void> {
+  async #start(): Promise<void> {
     if (this.#lifecycle.started) return;
     await this.#lifecycle.start((handle) => this.#connect(handle));
   }
 
-  close(): void {
-    super.close();
+  #close(): void {
+    this.#open = false;
     this.#clientSocketRelease?.();
     this.#clientSocketRelease = undefined;
   }
 
-  async stop(): Promise<void> {
-    this.close();
+  async #stop(): Promise<void> {
+    this.#close();
     await this.#lifecycle.stop();
     if (this.#ws) {
       try {
@@ -118,10 +129,10 @@ export class MilkyWsEndpoint extends ClientEndpoint<MilkyClient> {
     }
   }
 
-  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+  async #send({ conversation, payload, signal }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
     const { action, params } = buildSendAction(conversation, message);
-    const data = await callMilkyClient<{ message_seq?: number }>(this.client, action, params);
+    const data = readMilkyResponse<{ message_seq?: number }>(await this.#call({ action, params, signal }), action);
     const messageId = formatOutboundMessageId(conversation, data?.message_seq);
     this.#logger.debug(formatCompact({
       op: 'milky_send',
@@ -132,23 +143,24 @@ export class MilkyWsEndpoint extends ClientEndpoint<MilkyClient> {
     return messageId;
   }
 
-  async recallMessage(id: string): Promise<void> {
+  async #recallMessage({ id, signal }: { readonly id: string; readonly signal?: AbortSignal }): Promise<void> {
     const parsed = parseMilkyMessageId(id);
     if (!parsed) throw new Error(`Invalid message id: ${id}`);
     if (parsed.message_scene === 'group') {
-      await callMilkyClient(this.client, 'recall_group_message', {
+      readMilkyResponse(await this.#call({ action: 'recall_group_message', signal, params: {
         group_id: parsed.peer_id,
         message_seq: parsed.message_seq,
-      });
+      } }), 'recall_group_message');
     } else {
-      await callMilkyClient(this.client, 'recall_private_message', {
+      readMilkyResponse(await this.#call({ action: 'recall_private_message', signal, params: {
         user_id: parsed.peer_id,
         message_seq: parsed.message_seq,
-      });
+      } }), 'recall_private_message');
     }
   }
 
   #admitRaw(event: MilkyEvent): void {
+    if (event.self_id != null) this[endpointSpec].reportSelfUserId(String(event.self_id));
     const data = parseMessageReceiveData(event);
     if (!data) return;
     this.#admitMessage(data, event);
@@ -162,14 +174,16 @@ export class MilkyWsEndpoint extends ClientEndpoint<MilkyClient> {
   }
 
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
-    const conversation = milkyInboundConversation(String(this.#options.id), data);
+    const conversation = { ...milkyInboundConversation(String(this.#options.id), data), endpoint: this[endpointSpec].identity };
     const target = `${conversation.kind}:${conversation.id}`;
     const content = formatInboundContent(data);
     const segments = formatInboundSegments(data);
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
-    void this.emit('message.receive', {
+    void this[endpointSpec].events.message({
+      event,
+      ...(typeof event.time === 'number' ? { platformSentAt: event.time * 1000 } : {}),
       conversation,
       message: { conversation, id: formatInboundMessageId(data) },
       content,
@@ -242,7 +256,7 @@ export class MilkyWsEndpoint extends ClientEndpoint<MilkyClient> {
       });
 
       this.#clientSocketRelease?.();
-      this.#clientSocketRelease = this.client.acceptWebSocket(ws);
+      this.#clientSocketRelease = this.acceptWebSocket(ws);
 
       ws.on('close', (code, reason) => {
         this.#clientSocketRelease?.();