@zhin.js/adapter 1.2.0 → 1.2.1

package/lib/endpoint.d.ts

@@ -0,0 +1,78 @@
+import { 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 declare const endpointEventGatewayToken: import("@zhin.js/plugin-runtime").Token<EndpointEventGateway>;
+/** 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;
+}
+declare const endpointBrand: unique symbol;
+declare const endpointBind: unique symbol;
+/**
+ * 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 declare abstract class Endpoint<TClient = unknown> {
+    #private;
+    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;
+    /** @internal Bound exactly once by the generation-owned AdapterIndex. */
+    [endpointBind](context: AdapterContext, admission?: GenerationAdmissionGate): void;
+    /** The identity is available after AdapterDefinition.create returns. */
+    get identity(): EndpointIdentity;
+    /** The only legal platform-to-framework event ingress. */
+    protected emit<TPayload, TName extends string>(name: TName, payload: TPayload): Promise<unknown>;
+    /**
+     * 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>;
+    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 declare function bindEndpoint(endpoint: Endpoint, context: AdapterContext, admission?: GenerationAdmissionGate): void;
+/** @internal Cross-generation Endpoint check that survives ESM module re-evaluation. */
+export declare function isEndpoint(value: unknown): value is Endpoint;
+export {};

package/lib/endpoint.js

@@ -0,0 +1,100 @@
+import { createToken, } from '@zhin.js/plugin-runtime';
+/** Generation-bound gateway injected into Endpoint by AdapterIndex. */
+export const endpointEventGatewayToken = createToken('zhin.adapter.endpoint-events');
+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 class Endpoint {
+    [endpointBrand] = true;
+    management;
+    control;
+    content;
+    #identity;
+    #events;
+    #admissionState = 'unbound';
+    #pendingEvents = [];
+    /** @internal Bound exactly once by the generation-owned AdapterIndex. */
+    [endpointBind](context, admission) {
+        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() {
+        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. */
+    emit(name, payload) {
+        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.
+     */
+    emitPlatform(name, event) {
+        return this.emit('platform.receive', Object.freeze({ name, event }));
+    }
+}
+/** @internal AdapterIndex binding hook; deliberately not exported by name. */
+export function bindEndpoint(endpoint, context, admission) {
+    endpoint[endpointBind](context, admission);
+}
+/** @internal Cross-generation Endpoint check that survives ESM module re-evaluation. */
+export function isEndpoint(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    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/lib/index.d.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';

package/lib/index.js

@@ -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';

package/lib/provider.d.ts

@@ -1,5 +1,5 @@
 import { AdapterIndex } from './adapter-index.js';
 export declare const adapterFeatureId: import("@zhin.js/plugin-runtime").FeatureId;
-declare const adapterFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").AdapterDefinition<unknown>, AdapterIndex>>;
+declare const adapterFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").AdapterDefinition<unknown, unknown>, AdapterIndex>>;
 export { adapterFeature };
 export default adapterFeature;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Convention-based Adapter and Endpoint Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,15 +18,15 @@
   ],
   "dependencies": {
     "yaml": "^2.9.0",
-    "@zhin.js/feature-kit": "1.0.12",
+    "@zhin.js/feature-kit": "1.0.13",
     "@zhin.js/im-contract": "1.0.4",
-    "@zhin.js/logger": "1.0.76",
-    "@zhin.js/plugin-runtime": "1.1.7"
+    "@zhin.js/logger": "1.0.77",
+    "@zhin.js/plugin-runtime": "1.1.8"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
-    "@zhin.js/command": "1.0.15"
+    "@zhin.js/command": "1.0.16"
   },
   "zhin": {
     "protocol": 1,

package/src/adapter-index.ts

@@ -17,9 +17,9 @@ import {
   type AdapterDefinition,
   type AdapterOperation,
   type AdapterSegmentPolicy,
-  type EndpointInstance,
   type EndpointSendRequest,
 } from './definition.js';
+import { bindEndpoint, isEndpoint, type Endpoint } from './endpoint.js';
 import {
   listEndpointManagementCapabilities,
   type EndpointManagementCapability,
@@ -57,7 +57,7 @@ export type AdapterEndpointPhase =
   'pending' | 'starting' | 'online';
 
 interface AdapterRecord extends AdapterDescriptor {
-  readonly endpoint: EndpointInstance;
+  readonly endpoint: Endpoint;
   readonly segments?: AdapterSegmentPolicy;
   started: boolean;
   open: boolean;
@@ -157,15 +157,49 @@ export class AdapterIndex {
     return exact?.id ?? matches[0]?.id;
   }
 
-  /**
-   * Resolve a live EndpointInstance for Host-side side channels (reactions, etc.).
-   */
-  instance(adapter: string, endpointKey: string): EndpointInstance | undefined {
+  /** Resolve the framework-owned Endpoint for internal Host control ports. */
+  connection(adapter: string, endpointKey: string): Endpoint | undefined {
     const id = this.resolve(adapter, endpointKey);
     if (!id) return undefined;
     return this.#records.get(id)?.endpoint;
   }
 
+  /** Resolve the platform-native client owned by one active Endpoint. */
+  client<TClient>(adapter: string, endpointKey: string): TClient {
+    const id = this.resolve(adapter, endpointKey);
+    const record = id ? this.#records.get(id) : undefined;
+    if (!record) throw new Error(`Endpoint ${adapter}/${endpointKey} does not exist`);
+    if (!record.started || record.stopped) {
+      throw new Error(`Endpoint ${adapter}/${endpointKey} is not active`);
+    }
+    return record.endpoint.client as TClient;
+  }
+
+  /** Resolve the Client directly from a generation-stable CapabilityId. */
+  clientById<TClient>(id: CapabilityId): TClient {
+    const record = this.#records.get(id);
+    if (!record) throw new Error(`Unknown Adapter Endpoint: ${id}`);
+    if (!record.started || record.stopped) {
+      throw new Error(`Adapter Endpoint ${id} is not active`);
+    }
+    return record.endpoint.client as TClient;
+  }
+
+  /** Literal adapter name used by authoring-context type discrimination. */
+  clientAdapter(id: CapabilityId): string {
+    const record = this.#records.get(id);
+    if (!record) throw new Error(`Unknown Adapter Endpoint: ${id}`);
+    return record.endpoint.identity.adapter;
+  }
+
+  /** Optional Client lookup for cross-platform middleware and routing. */
+  findClient<TClient>(adapter: string, endpointKey: string): TClient | undefined {
+    const id = this.resolve(adapter, endpointKey);
+    const record = id ? this.#records.get(id) : undefined;
+    if (!record || !record.started || record.stopped) return undefined;
+    return record.endpoint.client as TClient;
+  }
+
   owner(id: CapabilityId): PluginId {
     const record = this.#records.get(id);
     if (!record) throw new Error(`Unknown Adapter Endpoint: ${id}`);
@@ -228,6 +262,11 @@ export class AdapterIndex {
         }
         signal.throwIfAborted();
         if (record.stopped) throw new Error(`Adapter Endpoint stopped during start: ${record.id}`);
+        if (record.endpoint.client === record.endpoint) {
+          throw new TypeError(
+            `Adapter Endpoint ${record.id} must expose a distinct platform client`,
+          );
+        }
         record.started = true;
       }
     } catch (error) {
@@ -335,7 +374,7 @@ function matchesEndpoint(
     || record.id.endsWith(`/${adapter}`)
     || record.owner === adapter
     || record.owner.endsWith(`/${adapter}`);
-  // Live EndpointInstance.name is the bot runtime id (e.g. ICQQ uin). Host /
+  // The live Endpoint identity is the bot runtime id (e.g. ICQQ uin). Host /
   // activity-feedback resolve with that id; slot.localName alone is not enough
   // when multiple plugin instances share localName "icqq".
   const liveName = endpointLiveName(record.endpoint);
@@ -346,7 +385,7 @@ function matchesEndpoint(
   return adapterOk && endpointOk;
 }
 
-function endpointLiveName(endpoint: EndpointInstance): string | undefined {
+function endpointLiveName(endpoint: Endpoint): string | undefined {
   const name = (endpoint as { readonly name?: unknown }).name;
   return typeof name === 'string' && name.length > 0 ? name : undefined;
 }
@@ -357,9 +396,9 @@ function endpointPhase(record: AdapterRecord): AdapterEndpointPhase {
   return 'pending';
 }
 
-function assertEndpoint(value: unknown, id: CapabilityId): asserts value is EndpointInstance {
-  if (!value || typeof value !== 'object') {
-    throw new TypeError(`Adapter ${id} create() must return an Endpoint instance`);
+function assertEndpoint(value: unknown, id: CapabilityId): asserts value is Endpoint {
+  if (!isEndpoint(value)) {
+    throw new TypeError(`Adapter ${id} create() must return an Endpoint subclass`);
   }
 }
 
@@ -425,7 +464,7 @@ async function createEndpoint(
   admission: GenerationAdmissionGate,
   signal: AbortSignal,
   expansion?: EndpointExpansion,
-): Promise<Readonly<{ endpoint: EndpointInstance; operations: readonly AdapterOperation[] }>> {
+): Promise<Readonly<{ endpoint: Endpoint; operations: readonly AdapterOperation[] }>> {
   const context = Object.freeze({
     ...createCapabilityContext(snapshot, slot.owner, admission, signal),
     ...(expansion?.config ? { config: expansion.config } : {}),
@@ -435,6 +474,7 @@ async function createEndpoint(
   const operations = resolveAdapterOperations(slot.definition, context);
   const endpoint = await slot.definition.create(context);
   assertEndpoint(endpoint, expansion?.id ?? slot.id);
+  bindEndpoint(endpoint, context, admission);
   if (slot.definition.capabilities.includes('outbound') && typeof endpoint.send !== 'function') {
     throw new TypeError(
       `Adapter Endpoint ${String(expansion?.id ?? slot.id)} declares outbound but send() is missing`,

package/src/definition.ts

@@ -1,3 +1,7 @@
+/**
+ * Adapter authoring API consumed from `zhin.js/adapter`.
+ * @module zhin.js/adapter
+ */
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import type { CapabilityContext } from '@zhin.js/feature-kit';
 import type {
@@ -5,9 +9,19 @@ import type {
   EndpointCapabilities,
   EndpointOperation,
 } from '@zhin.js/im-contract';
-import type { EndpointManagement } from './endpoint-management.js';
-import type { EndpointControl } from './endpoint-control.js';
-import type { EndpointContentPort } from './endpoint-content.js';
+import type { Endpoint } from './endpoint.js';
+
+export { Endpoint } from './endpoint.js';
+export type {
+  EndpointEvent,
+  EndpointIdentity,
+  PlatformEvent,
+} from './endpoint.js';
+export { defineEndpointClient } from './endpoint-client.js';
+export type {
+  EndpointClientContext,
+  EndpointClientToken,
+} from './endpoint-client.js';
 
 const adapterBrand = 'zhin.adapter/1' as const;
 
@@ -35,25 +49,9 @@ export interface EndpointSendRequest {
   readonly payload: unknown;
 }
 
-export interface EndpointInstance {
-  /** Optional platform-neutral Console/Host management surface. */
-  readonly management?: EndpointManagement;
-  /** Optional platform-neutral control surface for existing messages. */
-  readonly control?: EndpointControl;
-  /** Optional canonical resolver for message, merged-forward and media references. */
-  readonly content?: EndpointContentPort;
-  /** Required readiness; must observe abort and settle before rollback returns. */
-  start?(signal: AbortSignal): void | Promise<void>;
-  /** Opens Endpoint-local flow behind the candidate generation admission gate. */
-  open?(): void;
-  /** Stops new inbound events while preserving in-flight work. */
-  close?(): void | Promise<void>;
-  /** Releases transport resources. Calls must be idempotent. */
-  stop?(): void | Promise<void>;
-  /** Platform message id. Core wraps it in the canonical MessageRef/DeliveryReceipt. */
-  send?(request: EndpointSendRequest): string | Promise<string>;
-}
-
+/**
+ * Generation-owned construction context for one runtime Endpoint.
+ */
 export interface AdapterContext<TConfig = unknown> extends CapabilityContext<TConfig> {
   readonly id: CapabilityId;
   readonly name: string;
@@ -100,7 +98,8 @@ const OUTBOUND_MEDIA_FORMS: readonly AdapterOutboundMedia[] = [
 
 const ADAPTER_OPERATIONS: readonly AdapterOperation[] = ['recall', 'edit', 'reaction', 'typing'];
 
-export interface AdapterDefinition<TConfig = unknown> {
+export interface AdapterDefinition<TConfig = unknown, TClient = unknown> {
+  /** @internal Runtime feature brand. */
   readonly $feature: typeof adapterBrand;
   readonly capabilities: readonly AdapterCapability[];
   /**
@@ -113,7 +112,7 @@ export interface AdapterDefinition<TConfig = unknown> {
   readonly segments?: AdapterSegmentPolicy;
   create(
     context: AdapterContext<TConfig>,
-  ): EndpointInstance | Promise<EndpointInstance>;
+  ): Endpoint<TClient> | Promise<Endpoint<TClient>>;
 }
 
 declare module '@zhin.js/plugin-runtime' {
@@ -125,6 +124,23 @@ declare module '@zhin.js/plugin-runtime' {
   }
 }
 
+/**
+ * Define an Adapter module for the `adapters/` convention directory.
+ *
+ * The returned definition is immutable and declares capabilities before an
+ * Endpoint is created, so Runtime admission can fail closed.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { defineAdapter } from 'zhin.js/adapter';
+ *
+ * export default defineAdapter({
+ *   capabilities: ['inbound', 'outbound'],
+ *   create: () => new MyPlatformEndpoint(),
+ * });
+ * ```
+ */
 export function defineAdapter<TConfig = unknown>(
   definition: Omit<AdapterDefinition<TConfig>, '$feature'>,
 ): Readonly<AdapterDefinition<TConfig>> {
@@ -151,7 +167,10 @@ export function defineAdapter<TConfig = unknown>(
   });
 }
 
-/** Converts the definition's compact authoring form into the public contract. */
+/**
+ * Converts the definition's compact authoring form into the Runtime contract.
+ * @internal Adapter projection helper.
+ */
 export function endpointCapabilitiesOf(
   definition: Pick<AdapterDefinition, 'capabilities' | 'operations'>,
   resolvedOperations?: readonly AdapterOperation[],
@@ -172,7 +191,10 @@ export function endpointCapabilitiesOf(
   });
 }
 
-/** Resolve and validate the operation declaration for one concrete Endpoint. */
+/**
+ * Resolve and validate the operation declaration for one concrete Endpoint.
+ * @internal Adapter projection helper.
+ */
 export function resolveAdapterOperations<TConfig>(
   definition: Pick<AdapterDefinition<TConfig>, 'operations'>,
   context: AdapterContext<TConfig>,
@@ -251,6 +273,7 @@ function normalizeSegmentPolicy(
   });
 }
 
+/** @internal Runtime validation for convention-discovered modules. */
 export function parseAdapterDefinition(value: unknown): AdapterDefinition {
   if (!value || typeof value !== 'object') throw invalidAdapter();
   const definition = value as Partial<AdapterDefinition>;