@zhin.js/adapter 1.1.11 → 1.2.1

package/src/endpoint-control.ts

@@ -3,7 +3,7 @@ import type { ConversationRef, MessageRef } from '@zhin.js/im-contract';
 /**
  * Transport-neutral control plane for a live endpoint.
  *
- * Sending belongs to EndpointInstance.send(). This port intentionally owns
+ * Sending belongs to Endpoint.send(). This port intentionally owns
  * operations that address an existing platform message, so Core never needs
  * to know a protocol's method names or identifier layout.
  */
@@ -23,6 +23,15 @@ export interface EndpointWithControl {
   readonly control?: EndpointControl;
 }
 
+/** Bridges the common platform `recall(messageId)` shape into canonical control. */
+export function createRecallEndpointControl(
+  recallById: (messageId: string) => void | Promise<void>,
+): Readonly<EndpointControl> {
+  return Object.freeze<EndpointControl>({
+    recall: (message) => Promise.resolve(recallById(message.id)),
+  });
+}
+
 /** Reads the canonical control port without probing protocol-specific methods. */
 export function endpointControlOf(endpoint: unknown): EndpointControl | undefined {
   if (!endpoint || typeof endpoint !== 'object') return undefined;
@@ -46,6 +55,24 @@ export function hasExplicitEndpointOperation(
   }
 }
 
+/** Lists the semantic operations implemented by an Endpoint's explicit control port. */
+export function listExplicitEndpointOperations(
+  endpoint: unknown,
+): readonly ('recall' | 'edit' | 'reaction' | 'typing')[] {
+  if (!endpoint || typeof endpoint !== 'object') return Object.freeze([]);
+  const control = (endpoint as EndpointWithControl).control;
+  if (!control || typeof control !== 'object') return Object.freeze([]);
+  const operations: Array<'recall' | 'edit' | 'reaction' | 'typing'> = [];
+  if (typeof control.recall === 'function') operations.push('recall');
+  if (typeof control.edit === 'function') operations.push('edit');
+  if (
+    typeof control.addReaction === 'function'
+    || typeof control.removeReaction === 'function'
+  ) operations.push('reaction');
+  if (typeof control.typing === 'function') operations.push('typing');
+  return Object.freeze(operations);
+}
+
 /** Rejects a declaration that cannot be fulfilled by the explicit control port. */
 export function assertDeclaredEndpointOperations(
   endpoint: unknown,
@@ -59,8 +86,25 @@ export function assertDeclaredEndpointOperations(
       );
     }
   }
+  const declared = new Set(operations ?? []);
+  for (const operation of listExplicitEndpointOperations(endpoint)) {
+    if (!declared.has(operation)) {
+      throw new TypeError(
+        `Adapter Endpoint ${id} exposes control.${explicitControlMethodName(endpoint, operation)} but does not declare ${operation}`,
+      );
+    }
+  }
 }
 
 function controlMethodName(operation: 'recall' | 'edit' | 'reaction' | 'typing'): string {
   return operation === 'reaction' ? 'addReaction' : operation;
 }
+
+function explicitControlMethodName(
+  endpoint: unknown,
+  operation: 'recall' | 'edit' | 'reaction' | 'typing',
+): string {
+  if (operation !== 'reaction') return operation;
+  const control = (endpoint as EndpointWithControl).control;
+  return typeof control?.addReaction === 'function' ? 'addReaction' : 'removeReaction';
+}

package/src/endpoint-lifecycle.ts

@@ -22,25 +22,19 @@
  *    构造器里 `this.#lifecycle = createEndpointLifecycle({ name: config.id, reconnect, heartbeat })`。
  * 2. `start()` 改为：
  *    ```ts
- *    this.#unregisterAgent = registerXxxAgentEndpoint(name, this); // agent 注册仍在适配器侧
- *    try {
- *      await this.#lifecycle.start(async (handle) => {
- *        this.#handle = handle; // 供 ws 'close' 回调引用
- *        await new Promise<void>((resolve, reject) => {
- *          const ws = createWebSocket(...); this.#ws = ws;
- *          ws.on('open', () => { this.#lifecycle.startHeartbeat(() => beat(), interval); resolve(); });
- *          ws.on('close', (code, reason) => { handle.notifyClosed(...); rejectIfNotSettled(...); });
- *          ws.on('error', (err) => rejectIfNotSettled(err));
- *        });
+ *    await this.#lifecycle.start(async (handle) => {
+ *      this.#handle = handle; // 供 ws 'close' 回调引用
+ *      await new Promise<void>((resolve, reject) => {
+ *        const ws = createWebSocket(...); this.#ws = ws;
+ *        ws.on('open', () => { this.#lifecycle.startHeartbeat(() => beat(), interval); resolve(); });
+ *        ws.on('close', (code, reason) => { handle.notifyClosed(...); rejectIfNotSettled(...); });
+ *        ws.on('error', (err) => rejectIfNotSettled(err));
  *      });
- *    } catch (err) {
- *      this.#unregisterAgent?.(); this.#unregisterAgent = undefined; // 反注册对称
- *      throw err;
- *    }
+ *    });
  *    ```
- *    start 失败复位由基座保证；agent 注册/反注册是适配器专有依赖，刻意不收入基座。
+ *    start 失败复位由基座保证；Client 由 Endpoint 直接持有，不建立旁路 registry。
  * 3. `stop()` 改为：先 `await this.#lifecycle.stop()`（清定时器 + 强关 ws + 竞态 settle），
- *    再做适配器专有清理（rejectAllPending、deduper.clear、agent 反注册）。
+ *    再做适配器专有清理（rejectAllPending、deduper.clear）。
  * 4. `handle.onForceClose(() => this.#ws?.close())` 在每次拿到新 socket 后注册，
  *    供心跳看门狗主动断开；ws 'message'/'pong' 回调里调 `notifyHeartbeatAck()` 喂狗。
  * 5. 退避参数由配置映射：reconnect_interval → initialIntervalMs，可按需覆盖

package/src/endpoint.ts

@@ -0,0 +1,181 @@
+import {
+  createToken,
+  type CapabilityId,
+  type GenerationAdmissionGate,
+} from '@zhin.js/plugin-runtime';
+import type { AdapterContext, EndpointSendRequest } from './definition.js';
+import type { EndpointManagement } from './endpoint-management.js';
+import type { EndpointControl } from './endpoint-control.js';
+import type { EndpointContentPort } from './endpoint-content.js';
+
+/** The one inbound event boundary shared by every platform Endpoint. */
+export interface EndpointEventGateway {
+  receive(event: EndpointEvent): Promise<unknown>;
+}
+
+/** Callback shape used by protocol normalizers which feed Endpoint.emit(). */
+export type EndpointEventEmitter = <TPayload>(name: string, payload: TPayload) => Promise<unknown>;
+
+/** Generation-bound gateway injected into Endpoint by AdapterIndex. */
+export const endpointEventGatewayToken = createToken<EndpointEventGateway>(
+  'zhin.adapter.endpoint-events',
+);
+
+/** Stable identity of the Endpoint which produced an event. */
+export interface EndpointIdentity {
+  readonly id: CapabilityId;
+  readonly adapter: string;
+}
+
+/**
+ * The single event context delivered from an Endpoint into Core and plugins.
+ * `client` is the actual platform SDK/protocol client owned by the Endpoint.
+ */
+export interface EndpointEvent<
+  TPayload = unknown,
+  TClient = unknown,
+  TName extends string = string,
+> {
+  readonly name: TName;
+  readonly payload: TPayload;
+  readonly endpoint: EndpointIdentity;
+  readonly client: TClient;
+}
+
+/** Lossless native event delivered before any optional canonical projection. */
+export interface PlatformEvent<
+  TEvent = unknown,
+  TName extends string = string,
+> {
+  /** Native SDK/protocol event name, for example `guild_member_add`. */
+  readonly name: TName;
+  /** Native SDK/protocol payload without canonicalization. */
+  readonly event: TEvent;
+}
+
+const endpointBrand = Symbol.for('zhin.adapter.endpoint/1');
+const endpointBind = Symbol.for('zhin.adapter.endpoint-bind/1');
+const PRE_ADMISSION_EVENT_LIMIT = 256;
+
+/**
+ * Deep platform boundary.
+ *
+ * Platform implementations inherit this class, expose the platform-native
+ * `client`, own account/transport lifecycle, and normalize every inbound SDK
+ * callback through `emit()`. Core owns dispatch, admission and plugin context.
+ */
+export abstract class Endpoint<TClient = unknown> {
+  readonly [endpointBrand] = true;
+  /**
+   * Platform SDK or protocol client exposed to plugin code.
+   * It must be a distinct object: Endpoint owns framework lifecycle, Client
+   * owns platform operations.
+   */
+  abstract readonly client: TClient;
+
+  readonly management?: EndpointManagement;
+  readonly control?: EndpointControl;
+  readonly content?: EndpointContentPort;
+
+  #identity?: EndpointIdentity;
+  #events?: EndpointEventGateway;
+  #admissionState: 'unbound' | 'pending' | 'active' | 'retired' = 'unbound';
+  #pendingEvents: EndpointEvent[] = [];
+
+  /** @internal Bound exactly once by the generation-owned AdapterIndex. */
+  [endpointBind](context: AdapterContext, admission?: GenerationAdmissionGate): void {
+    if (this.#events) throw new Error(`Endpoint ${context.id} is already bound`);
+    this.#identity = Object.freeze({ id: context.id, adapter: context.name });
+    this.#events = context.use(endpointEventGatewayToken);
+    if (!admission) {
+      this.#admissionState = 'active';
+      return;
+    }
+    this.#admissionState = 'pending';
+    admission.onActivate(() => {
+      if (this.#admissionState !== 'pending') return;
+      this.#admissionState = 'active';
+      admission.onDeactivate(() => {
+        this.#admissionState = 'retired';
+        this.#pendingEvents.length = 0;
+      });
+      const pending = this.#pendingEvents.splice(0);
+      for (const event of pending) {
+        void this.#events?.receive(event).catch(() => undefined);
+      }
+    });
+  }
+
+  /** The identity is available after AdapterDefinition.create returns. */
+  get identity(): EndpointIdentity {
+    if (!this.#identity) throw new Error('Endpoint is not bound to a runtime generation');
+    return this.#identity;
+  }
+
+  /** The only legal platform-to-framework event ingress. */
+  protected emit<TPayload, TName extends string>(
+    name: TName,
+    payload: TPayload,
+  ): Promise<unknown> {
+    if (!this.#events || !this.#identity) {
+      throw new Error('Endpoint emitted before it was bound to a runtime generation');
+    }
+    const event = Object.freeze({
+      name,
+      payload,
+      endpoint: this.#identity,
+      client: this.client,
+    });
+    if (this.#admissionState === 'pending') {
+      if (this.#pendingEvents.length >= PRE_ADMISSION_EVENT_LIMIT) {
+        this.#pendingEvents.shift();
+      }
+      this.#pendingEvents.push(event);
+      return Promise.resolve(undefined);
+    }
+    if (this.#admissionState === 'retired') return Promise.resolve(undefined);
+    return this.#events.receive(event);
+  }
+
+  /**
+   * Lossless native-event projection. Adapters call this before deriving
+   * message/notice/request/system events, including for unknown event kinds.
+   */
+  protected emitPlatform<TEvent, TName extends string>(
+    name: TName,
+    event: TEvent,
+  ): Promise<unknown> {
+    return this.emit('platform.receive', Object.freeze({ name, event }));
+  }
+
+  abstract start(signal: AbortSignal): void | Promise<void>;
+  abstract open(): void;
+  abstract close(): void | Promise<void>;
+  abstract stop(): void | Promise<void>;
+  send?(_request: EndpointSendRequest): string | Promise<string>;
+}
+
+/** @internal AdapterIndex binding hook; deliberately not exported by name. */
+export function bindEndpoint(
+  endpoint: Endpoint,
+  context: AdapterContext,
+  admission?: GenerationAdmissionGate,
+): void {
+  endpoint[endpointBind](context, admission);
+}
+
+/** @internal Cross-generation Endpoint check that survives ESM module re-evaluation. */
+export function isEndpoint(value: unknown): value is Endpoint {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Partial<Endpoint> & {
+    readonly [endpointBrand]?: unknown;
+    readonly [endpointBind]?: unknown;
+  };
+  return candidate[endpointBrand] === true
+    && typeof candidate[endpointBind] === 'function'
+    && typeof candidate.start === 'function'
+    && typeof candidate.open === 'function'
+    && typeof candidate.close === 'function'
+    && typeof candidate.stop === 'function'
+    && 'client' in candidate;
+}

package/src/index.ts

@@ -1,12 +1,18 @@
+/**
+ * Adapter authoring contracts and platform-neutral Endpoint capabilities.
+ * @module @zhin.js/adapter
+ */
 /** @internal 适配器 projection（AdapterIndex），框架内部机制，不承诺不 break。 */
 export * from './adapter-index.js';
 export * from './credentials.js';
 /** @public 用户侧创作面：`defineAdapter`（`adapters/` 约定目录默认导出，承诺 semver）。 */
 export * from './definition.js';
+export * from './endpoint.js';
 export * from './endpoint-commands.js';
 export * from './endpoint-lifecycle.js';
 export * from './endpoint-management.js';
 export * from './endpoint-control.js';
 export * from './endpoint-content.js';
+export * from './endpoint-client.js';
 export * from './provider.js';
 export { default } from './provider.js';