@zhin.js/adapter-onebot12 1.1.18 → 1.1.20

package/lib/index.d.ts

@@ -1,10 +1,11 @@
-export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, mediaRefToOneBot12Fields, mediaRefToOneBot12UploadParams, onebot12InboundConversation, resolveOneBot12Config, senderNickname, senderUserId, uploadOneBot12MediaSegments, type OneBot12ActionRequest, type OneBot12ActionResponse, type OneBot12CallAction, type OneBot12ConfigBase, type OneBot12EndpointConfig, type OneBot12Event, type OneBot12HttpOptions, type OneBot12Segment, type OneBot12Self, type OneBot12WebhookConfig, type OneBot12WireSegment, type OneBot12WsConfig, type OneBot12WssConfig, type ResolvedOneBot12Config, } from './protocol.js';
+export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, mediaRefToOneBot12Fields, mediaRefToOneBot12UploadParams, onebot12InboundConversation, resolveOneBot12Config, senderNickname, senderUserId, uploadOneBot12MediaSegments, type OneBot12ActionRequest, type OneBot12ActionResponse, type OneBot12CallAction, type OneBot12ConfigBase, type OneBot12EndpointConfig, type OneBot12Event, type OneBot12HttpOptions, type OneBot12HttpRequest, type OneBot12MediaUpload, type OneBot12MediaSource, type OneBot12Segment, type OneBot12Self, type OneBot12WebhookConfig, type OneBot12WireSegment, type OneBot12WsConfig, type OneBot12WssConfig, type ResolvedOneBot12Config, } from './protocol.js';
 export { OneBot12WebhookEndpoint, type OneBot12WebhookEndpointOptions, } from './webhook.js';
 export { OneBot12WsEndpoint, type OneBot12WsEndpointOptions, } from './ws-endpoint.js';
 export { OneBot12WssEndpoint, type OneBot12WssEndpointOptions, } from './wss-endpoint.js';
 export type { OneBot12WsSocket, OneBot12WsCreateOptions } from './ws-types.js';
 export { verifyOneBotAccessToken } from './wss-auth.js';
-export { Onebot12Client, onebot12Client, type Onebot12ClientEventMap, } from './client.js';
+export { Onebot12Client, type Onebot12ClientEventMap, } from './client.js';
 export type { OneBotV12ActionUrlResolver, OneBotV12AdapterConfig as ImHelperOneBotV12AdapterConfig, OneBotV12Call, OneBotV12ClientConfig, OneBotV12Event as ImHelperOneBotV12Event, OneBotV12Response, } from '@imhelper/onebot-v12';
 export { ProtocolError } from '@imhelper/onebot-v12';
 export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';
+export { Onebot12Adapter } from './adapter.js';

package/lib/index.js

@@ -3,5 +3,6 @@ export { OneBot12WebhookEndpoint, } from './webhook.js';
 export { OneBot12WsEndpoint, } from './ws-endpoint.js';
 export { OneBot12WssEndpoint, } from './wss-endpoint.js';
 export { verifyOneBotAccessToken } from './wss-auth.js';
-export { Onebot12Client, onebot12Client, } from './client.js';
+export { Onebot12Client, } from './client.js';
 export { ProtocolError } from '@imhelper/onebot-v12';
+export { Onebot12Adapter } from './adapter.js';

package/lib/protocol.d.ts

@@ -6,6 +6,8 @@
 import { type MediaRef, type ConversationRef } from '@zhin.js/im-contract';
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface OneBot12EndpointConfig {
+    readonly platform: string;
+    readonly userId: string;
     readonly connection?: 'ws' | 'webhook' | 'wss';
     readonly id: string;
     readonly access_token?: string;
@@ -16,6 +18,8 @@ export interface OneBot12EndpointConfig {
     readonly heartbeat_interval?: number;
 }
 export interface OneBot12ConfigBase {
+    readonly platform: string;
+    readonly userId: string;
     readonly context: 'onebot12';
     readonly id: string;
     readonly access_token?: string;
@@ -65,10 +69,10 @@ export interface OneBot12Segment {
     data?: Record<string, unknown>;
 }
 export interface OneBot12ActionRequest {
+    readonly self: OneBot12Self;
     action: string;
     params: Record<string, unknown>;
     echo?: string;
-    self?: OneBot12Self;
 }
 export interface OneBot12ActionResponse {
     status: 'ok' | 'failed';
@@ -78,6 +82,8 @@ export interface OneBot12ActionResponse {
     echo?: string;
 }
 export interface OneBot12HttpOptions {
+    readonly self: OneBot12Self;
+    readonly signal?: AbortSignal;
     readonly url: string;
     readonly access_token?: string;
 }
@@ -130,15 +136,27 @@ export declare function mediaRefToOneBot12Fields(media: MediaRef): Record<string
 export declare function formatOutboundSegments(payload: unknown): OneBot12Segment[];
 /** 端点动作调用签名（WS echo 请求 / webhook api_url HTTP）。 */
 export type OneBot12CallAction = (action: string, params: Record<string, unknown>) => Promise<unknown>;
+/** upload_file 文件名：优先段 data.name/filename，URL/路径取 basename，再按 mime 给默认名。 */
+export interface OneBot12MediaSource {
+    readonly type: string;
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly media: MediaRef;
+}
 /** canonical MediaRef → OB12 `upload_file` 动作参数（spec: type url/path/data）。 */
-export declare function mediaRefToOneBot12UploadParams(segmentType: string, data: Record<string, unknown>, media: MediaRef): Record<string, unknown> | undefined;
+export declare function mediaRefToOneBot12UploadParams(source: OneBot12MediaSource): Record<string, unknown> | undefined;
 /**
  * 出站媒体段物化：image/voice/audio/video/file 段的 MediaRef（url/base64/path）
  * 先经 `upload_file` 换 file_id（spec 正式投递形状），再交给
  * {@link formatOutboundSegments} 编码；kind=file 的 MediaRef 直接按 file_id 复投。
  * 上传失败保留原段（降级扩展字段透传）并回调 onUploadFailed。
  */
-export declare function uploadOneBot12MediaSegments(payload: unknown, callAction: OneBot12CallAction, onUploadFailed?: (error: unknown) => void): Promise<unknown>;
+export interface OneBot12MediaUpload {
+    readonly payload: unknown;
+    readonly callAction: OneBot12CallAction;
+    readonly signal?: AbortSignal;
+    readonly onUploadFailed?: (error: unknown) => void;
+}
+export declare function uploadOneBot12MediaSegments(request: OneBot12MediaUpload): Promise<unknown>;
 /**
  * 结构化会话 → OB12 `send_message` 动作参数：kind 直映射 detail_type；
  * channel 的 guild 容器取自 `conversation.parent`（kind 'channel'）。
@@ -148,10 +166,20 @@ export declare function buildSendMessageParams(conversation: ConversationRef, me
  * 向 OneBot 实现发送动作请求（HTTP POST），返回动作响应。
  * 供 webhook 出站与纯协议测试使用；WS 路径走 WebSocket echo 请求。
  */
-export declare function callOneBot12Action(options: OneBot12HttpOptions, action: string, params?: Record<string, unknown>, echo?: string): Promise<OneBot12ActionResponse>;
+export interface OneBot12HttpRequest extends OneBot12HttpOptions {
+    readonly action: string;
+    readonly params?: Record<string, unknown>;
+    readonly echo?: string;
+}
+/** HTTP owns submission evidence and cancellation for both SDK and framework callers. */
+export declare function callOneBot12Action(request: OneBot12HttpRequest): Promise<OneBot12ActionResponse>;
 /** Build WS connect URL + headers (access_token via Bearer + query). */
 export declare function buildWsConnectOptions(config: OneBot12WsConfig): {
     readonly url: string;
     readonly headers: Record<string, string>;
     readonly safeUrl: string;
 };
+/** Route only the explicitly selected bot; service-wide frames carry no account authority. */
+export declare function matchesOneBot12Self(config: Pick<OneBot12ConfigBase, 'platform' | 'userId'>, event: OneBot12Event): event is OneBot12Event & {
+    readonly self: OneBot12Self;
+};

package/lib/protocol.js

@@ -1,19 +1,22 @@
+import { readOnebot12Response } from './response.js';
 /**
  * OneBot 12 protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://12.onebot.dev/
  */
-import { isMediaRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('onebot12');
 export function resolveOneBot12Config(config) {
     const connection = config.connection ?? 'ws';
     const id = requiredEndpointField(config.id, 'id');
+    const platform = requiredEndpointField(config.platform, 'platform');
+    const userId = requiredEndpointField(config.userId, 'userId');
     const access_token = optionalEndpointField(config.access_token);
     if (connection === 'ws') {
         const url = requiredEndpointField(config.url, 'url');
         return {
-            context: 'onebot12',
+            context: 'onebot12', platform, userId,
             connection: 'ws',
             id,
             access_token,
@@ -26,7 +29,7 @@ export function resolveOneBot12Config(config) {
         const path = requiredEndpointField(config.path, 'path');
         const api_url = requiredEndpointField(config.api_url, 'api_url');
         return {
-            context: 'onebot12',
+            context: 'onebot12', platform, userId,
             connection: 'webhook',
             id,
             access_token,
@@ -37,7 +40,7 @@ export function resolveOneBot12Config(config) {
     if (connection === 'wss') {
         const path = requiredEndpointField(config.path, 'path');
         return {
-            context: 'onebot12',
+            context: 'onebot12', platform, userId,
             connection: 'wss',
             id,
             access_token,
@@ -272,8 +275,7 @@ export function formatOutboundSegments(payload) {
     }
     return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
 }
-/** upload_file 文件名：优先段 data.name/filename，URL/路径取 basename，再按 mime 给默认名。 */
-function oneBot12UploadName(segmentType, data, media) {
+function oneBot12UploadName({ type, data, media }) {
     const named = data.name ?? data.filename;
     if (typeof named === 'string' && named)
         return named;
@@ -293,11 +295,12 @@ function oneBot12UploadName(segmentType, data, media) {
             return base;
     }
     const ext = media.mime_type?.split('/')[1]?.split(';')[0];
-    return `${segmentType}.${ext || 'bin'}`;
+    return `${type}.${ext || 'bin'}`;
 }
 /** canonical MediaRef → OB12 `upload_file` 动作参数（spec: type url/path/data）。 */
-export function mediaRefToOneBot12UploadParams(segmentType, data, media) {
-    const name = oneBot12UploadName(segmentType, data, media);
+export function mediaRefToOneBot12UploadParams(source) {
+    const { media } = source;
+    const name = oneBot12UploadName(source);
     if (media.kind === 'url')
         return { type: 'url', name, url: media.value };
     if (media.kind === 'path') {
@@ -312,7 +315,7 @@ export function mediaRefToOneBot12UploadParams(segmentType, data, media) {
     }
     return undefined;
 }
-async function uploadOneMediaSegment(item, callAction, onUploadFailed) {
+async function uploadOneMediaSegment(item, request) {
     if (!item || typeof item !== 'object' || Array.isArray(item))
         return item;
     const segment = item;
@@ -330,33 +333,29 @@ async function uploadOneMediaSegment(item, callAction, onUploadFailed) {
     if (media.kind === 'file') {
         return { type: segment.type, data: { ...oneBot12MediaExtra(data), file_id: media.value } };
     }
-    const params = mediaRefToOneBot12UploadParams(segment.type, data, media);
+    const params = mediaRefToOneBot12UploadParams({ type: segment.type, data, media });
     if (!params)
         return item;
     try {
-        const result = await callAction('upload_file', params);
+        const result = await request.callAction('upload_file', params);
         if (result && typeof result.file_id === 'string' && result.file_id) {
             return { type: segment.type, data: { ...oneBot12MediaExtra(data), file_id: result.file_id } };
         }
         throw new Error('upload_file 响应缺少 file_id');
     }
     catch (error) {
+        if (request.signal?.aborted)
+            throw error;
         // 上传失败降级：保留原段，由 formatOutboundSegments 走扩展字段（url/data/path）
-        onUploadFailed?.(error);
+        request.onUploadFailed?.(error);
         return item;
     }
 }
-/**
- * 出站媒体段物化：image/voice/audio/video/file 段的 MediaRef（url/base64/path）
- * 先经 `upload_file` 换 file_id（spec 正式投递形状），再交给
- * {@link formatOutboundSegments} 编码；kind=file 的 MediaRef 直接按 file_id 复投。
- * 上传失败保留原段（降级扩展字段透传）并回调 onUploadFailed。
- */
-export async function uploadOneBot12MediaSegments(payload, callAction, onUploadFailed) {
-    if (Array.isArray(payload)) {
-        return Promise.all(payload.map((item) => uploadOneMediaSegment(item, callAction, onUploadFailed)));
+export async function uploadOneBot12MediaSegments(request) {
+    if (Array.isArray(request.payload)) {
+        return Promise.all(request.payload.map(item => uploadOneMediaSegment(item, request)));
     }
-    return uploadOneMediaSegment(payload, callAction, onUploadFailed);
+    return uploadOneMediaSegment(request.payload, request);
 }
 /**
  * 结构化会话 → OB12 `send_message` 动作参数：kind 直映射 detail_type；
@@ -380,40 +379,38 @@ export function buildSendMessageParams(conversation, message) {
     }
     return params;
 }
-/**
- * 向 OneBot 实现发送动作请求（HTTP POST），返回动作响应。
- * 供 webhook 出站与纯协议测试使用；WS 路径走 WebSocket echo 请求。
- */
-export async function callOneBot12Action(options, action, params = {}, echo) {
+/** HTTP owns submission evidence and cancellation for both SDK and framework callers. */
+export async function callOneBot12Action(request) {
+    if (request.signal?.aborted)
+        throw new EndpointDeliveryError('endpoint_inactive', 'Endpoint operation cancelled', 'not_sent');
     const headers = { 'Content-Type': 'application/json' };
-    if (options.access_token) {
-        headers.Authorization = `Bearer ${options.access_token}`;
-    }
-    const body = { action, params };
-    if (echo)
-        body.echo = echo;
-    const res = await fetch(options.url, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(30_000),
-    });
-    const text = await res.text();
-    if (res.status === 401)
-        throw new Error(`OneBot12 鉴权失败: ${text}`);
-    if (res.status !== 200)
-        throw new Error(`OneBot12 HTTP ${res.status}: ${text}`);
-    let data;
+    if (request.access_token)
+        headers.Authorization = `Bearer ${request.access_token}`;
+    const body = { action: request.action, params: request.params ?? {}, self: request.self,
+        ...(request.echo !== undefined ? { echo: request.echo } : {}) };
     try {
-        data = JSON.parse(text);
-    }
-    catch {
-        throw new Error(`OneBot12 无效响应: ${text.slice(0, 200)}`);
+        const response = await fetch(request.url, { method: 'POST', headers, body: JSON.stringify(body),
+            signal: request.signal ? AbortSignal.any([request.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000) });
+        const text = await response.text();
+        if (response.status === 401)
+            throw new EndpointDeliveryError('platform_rejected', `OneBot12 鉴权失败: ${text}`, 'rejected');
+        if (response.status !== 200)
+            throw new EndpointDeliveryError('endpoint_http_failed', `OneBot12 HTTP ${response.status}: ${text}`, 'unknown');
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            throw new EndpointDeliveryError('delivery_unconfirmed', `OneBot12 无效响应: ${text.slice(0, 200)}`, 'unknown');
+        }
+        readOnebot12Response(data);
+        return data;
     }
-    if (data.status === 'failed' && data.retcode !== 0) {
-        throw new Error(`OneBot12 动作失败 retcode=${data.retcode}: ${data.message}`);
+    catch (cause) {
+        if (cause instanceof EndpointDeliveryError)
+            throw cause;
+        throw new EndpointDeliveryError(request.signal?.aborted ? 'endpoint_inactive' : 'endpoint_transport_failed', cause instanceof Error ? cause.message : String(cause), 'unknown', { cause });
     }
-    return data;
 }
 /** Build WS connect URL + headers (access_token via Bearer + query). */
 export function buildWsConnectOptions(config) {
@@ -429,3 +426,7 @@ export function buildWsConnectOptions(config) {
     safeUrl.searchParams.delete('access_token');
     return { url: connectUrl, headers, safeUrl: safeUrl.toString() };
 }
+/** Route only the explicitly selected bot; service-wide frames carry no account authority. */
+export function matchesOneBot12Self(config, event) {
+    return event.self?.platform === config.platform && event.self?.user_id === config.userId;
+}

package/lib/response.d.ts

@@ -0,0 +1,5 @@
+/**
+ * One classifier for native SDK, HTTP and WS results.
+ * @see https://12.onebot.dev/connect/data-protocol/action-response/
+ */
+export declare function readOnebot12Response<T = unknown>(response: unknown): T | undefined;

package/lib/response.js

@@ -0,0 +1,17 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/**
+ * One classifier for native SDK, HTTP and WS results.
+ * @see https://12.onebot.dev/connect/data-protocol/action-response/
+ */
+export function readOnebot12Response(response) {
+    if (response && typeof response === 'object') {
+        const result = response;
+        if (result.status === 'ok' && result.retcode === 0)
+            return result.data;
+        if (result.status === 'failed' && typeof result.retcode === 'number' && Number.isSafeInteger(result.retcode) && result.retcode >= 10000 && result.retcode <= 99999) {
+            throw new EndpointDeliveryError('platform_rejected', `OneBot 12 API rejected: retcode=${result.retcode}${result.message ? ` ${result.message}` : ''}`, 'rejected');
+        }
+    }
+    // OB12 defines only ok/0 or failed with an error code; inconsistent envelopes prove neither result.
+    throw new EndpointDeliveryError('delivery_unconfirmed', 'OneBot 12 response did not confirm the action result', 'unknown');
+}

package/lib/side-event-dispatch.d.ts

@@ -4,4 +4,11 @@ import type { OneBot12Event } from './protocol.js';
 export interface OneBot12SideEventCaller {
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
 }
-export declare function receiveOneBot12SideEvent(emit: EndpointEventEmitter, endpointKey: string, caller: OneBot12SideEventCaller, raw: OneBot12Event, logger: ReturnType<typeof getAdapterLogger>): void;
+/** Exact instance-owned dependencies for one canonical side-event projection. */
+export interface OneBot12SideEventContext {
+    readonly emit: EndpointEventEmitter;
+    readonly endpointKey: string;
+    readonly caller: OneBot12SideEventCaller;
+    readonly logger: ReturnType<typeof getAdapterLogger>;
+}
+export declare function receiveOneBot12SideEvent(raw: OneBot12Event, context: OneBot12SideEventContext): void;

package/lib/side-event-dispatch.js

@@ -1,6 +1,7 @@
 import { receiveOneBotLikeSideEvent } from '@zhin.js/core';
 import { formatCompact } from '@zhin.js/logger';
-export function receiveOneBot12SideEvent(emit, endpointKey, caller, raw, logger) {
+export function receiveOneBot12SideEvent(raw, context) {
+    const { emit, endpointKey, caller, logger } = context;
     if (!emit)
         return;
     const record = raw;

package/lib/webhook.d.ts

@@ -1,23 +1,17 @@
-import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import { endpointSpec, type Endpoint, type EndpointSpecification } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { callOneBot12Action, type OneBot12WebhookConfig } from './protocol.js';
-import { type Onebot12Client } from './client.js';
+import { Onebot12Client } from './client.js';
 export interface OneBot12WebhookEndpointOptions {
+    readonly signal?: AbortSignal;
     readonly id: CapabilityId;
     readonly http: HttpHost;
     readonly config: OneBot12WebhookConfig;
     readonly callAction?: typeof callOneBot12Action;
 }
-export declare class OneBot12WebhookEndpoint extends ClientEndpoint<Onebot12Client> {
+export declare class OneBot12WebhookEndpoint extends Onebot12Client implements Endpoint {
     #private;
-    readonly client: Onebot12Client;
-    readonly management: EndpointManagement;
-    readonly control: EndpointControl;
-    readonly content: import("@zhin.js/adapter").EndpointContentPort;
+    readonly [endpointSpec]: EndpointSpecification;
     constructor(options: OneBot12WebhookEndpointOptions);
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    recallMessage(messageId: string): Promise<void>;
 }

package/lib/webhook.js

@@ -1,35 +1,49 @@
-import { ClientEndpoint, createRecallEndpointControl, } from 'zhin.js/adapter';
+import { acceptHttpIngress } from 'imhelper';
+import { createEndpointSpecification, endpointSpec, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
-import { buildSendMessageParams, callOneBot12Action, formatInboundContent, formatOutboundSegments, isBotMentioned, isMessageEvent, onebot12InboundConversation, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
+import { buildSendMessageParams, matchesOneBot12Self, callOneBot12Action, formatInboundContent, formatOutboundSegments, isBotMentioned, isMessageEvent, onebot12InboundConversation, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
 import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
 import { createOneBot12ContentPort } from './content-port.js';
-import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents } from './client.js';
+import { callOnebot12Client, readOnebot12Response, onebot12ClientOptions, forwardOnebot12ClientEvents, Onebot12Client } from './client.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 const logger = getLogger('onebot12');
-export class OneBot12WebhookEndpoint extends ClientEndpoint {
-    client;
+export class OneBot12WebhookEndpoint extends Onebot12Client {
+    [endpointSpec];
+    #open = false;
     #options;
-    management;
-    control = createRecallEndpointControl((id) => this.recallMessage(id));
-    content;
+    #management;
+    #control = createRecallEndpointControl((id, signal) => this.#recallMessage(id, signal));
+    #content;
+    #releaseClientEvents;
     #callAction;
     #routeReleases = [];
     #started = false;
     constructor(options) {
-        super();
+        super(onebot12ClientOptions(options.config, (action, params) => this.#callApi({ action, params })));
         this.#options = options;
         this.#callAction = options.callAction ?? callOneBot12Action;
-        this.client = createOnebot12EndpointClient(options.config, (action, params) => this.#callApi(action, params));
-        const callApi = (action, params) => callOnebot12Client(this.client, action, params);
-        this.management = createOneBot12EndpointManagement({ callApi });
-        this.content = createOneBot12ContentPort(callApi);
-        this.bindClientEvents((receive) => forwardOnebot12ClientEvents(this.client, receive), (name, payload) => {
-            if (name === 'event')
-                this.#admitRaw(payload);
-        }, (_name, error) => this.#warnPlatformEvent(error));
+        const callApi = (request) => this.#callApi(request).then(readOnebot12Response);
+        this.#management = createOneBot12EndpointManagement({ callApi });
+        this.#content = createOneBot12ContentPort(callApi);
+        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, content: this.#content,
+        });
+        this.#releaseClientEvents = forwardOnebot12ClientEvents(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);
+            }).catch(error => this.#warnPlatformEvent(error));
+        });
     }
-    async start() {
+    async #start() {
         if (this.#started)
             return;
         this.#started = true;
@@ -50,24 +64,26 @@ export class OneBot12WebhookEndpoint extends ClientEndpoint {
             path: this.#options.config.path,
         }));
     }
-    async stop() {
-        this.close();
+    async #stop() {
+        this.#open = false;
         for (const release of this.#routeReleases.splice(0))
             release();
         this.#started = false;
+        this.#releaseClientEvents();
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.id }));
     }
-    async send({ conversation, payload }) {
-        const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => callOnebot12Client(this.client, action, params), (error) => {
-            logger.warn(formatCompact({
-                op: 'onebot12_upload_failed',
-                endpoint: this.#options.config.id,
-                error: error instanceof Error ? error.message : String(error),
-            }));
+    async #send({ conversation, payload, signal }) {
+        const materialized = await uploadOneBot12MediaSegments({
+            payload, signal,
+            callAction: (action, params) => this.#callApi({ action, params, signal }).then(readOnebot12Response),
+            onUploadFailed: error => {
+                logger.warn(formatCompact({ op: 'onebot12_upload_failed', endpoint: this.#options.config.id,
+                    error: error instanceof Error ? error.message : String(error) }));
+            },
         });
         const message = formatOutboundSegments(materialized);
         const params = buildSendMessageParams(conversation, message);
-        const data = await callOnebot12Client(this.client, 'send_message', params);
+        const data = readOnebot12Response(await this.#callApi({ action: 'send_message', params, signal }));
         const messageId = data?.message_id ?? '';
         logger.debug(formatCompact({
             op: 'onebot12_send',
@@ -78,24 +94,38 @@ export class OneBot12WebhookEndpoint extends ClientEndpoint {
         }));
         return messageId;
     }
-    async recallMessage(messageId) {
+    async #recallMessage(messageId, signal) {
         if (!messageId)
             return;
-        await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
+        await this.#callApi({ action: 'delete_message', params: { message_id: messageId }, signal }).then(readOnebot12Response);
     }
-    async #callApi(action, params = {}) {
-        return this.#callAction({ url: this.#options.config.api_url, access_token: this.#options.config.access_token }, action, params);
+    async #callApi(request) {
+        const epoch = this.#options.signal;
+        const signal = epoch && request.signal ? AbortSignal.any([epoch, request.signal]) : epoch ?? request.signal;
+        return this.#callAction({ url: this.#options.config.api_url, access_token: this.#options.config.access_token,
+            self: { platform: this.#options.config.platform, user_id: this.#options.config.userId },
+            action: request.action, params: request.params, signal });
     }
     #admitRaw(ev) {
+        if (!matchesOneBot12Self(this.#options.config, ev))
+            return;
+        this[endpointSpec].reportSelfUserId(ev.self.user_id);
         if (!isMessageEvent(ev)) {
-            receiveOneBot12SideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, { callApi: (action, params) => callOnebot12Client(this.client, action, params) }, ev, logger);
+            receiveOneBot12SideEvent(ev, {
+                emit: (name, payload) => this[endpointSpec].events.emit(name, payload),
+                endpointKey: this.#options.config.id,
+                caller: { callApi: (action, params) => callOnebot12Client({ client: this, action, params }) },
+                logger: logger,
+            });
             return;
         }
-        const conversation = onebot12InboundConversation(String(this.#options.id), ev);
+        const conversation = { ...onebot12InboundConversation(String(this.#options.id), ev), endpoint: this[endpointSpec].identity };
         const content = formatInboundContent(ev);
         const nickname = senderNickname(ev);
         const mentioned = isBotMentioned(ev);
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.message({
+            event: ev,
+            ...(typeof ev.time === 'number' ? { platformSentAt: ev.time * 1000 } : {}),
             conversation,
             message: { conversation, id: ev.message_id },
             content,
@@ -139,12 +169,17 @@ export class OneBot12WebhookEndpoint extends ClientEndpoint {
                 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(request, response, event => {
+                if (!matchesOneBot12Self(this.#options.config, event))
+                    return;
+                void this[endpointSpec].events.run(() => this.ingest(event))
+                    .catch(error => this.#warnPlatformEvent(error));
+            });
         }
         catch (error) {
             logger.error('OneBot12 webhook error:', error);

package/lib/ws-endpoint.d.ts

@@ -1,22 +1,16 @@
-import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import { endpointSpec, type Endpoint, type EndpointSpecification } from 'zhin.js/adapter';
 import type { CapabilityId } from 'zhin.js';
 import { type OneBot12WsConfig } from './protocol.js';
-import { type Onebot12Client } from './client.js';
+import { Onebot12Client } from './client.js';
 import { type OneBot12WsCreateOptions, type OneBot12WsSocket } from './ws-types.js';
 export interface OneBot12WsEndpointOptions {
+    readonly signal?: AbortSignal;
     readonly id: CapabilityId;
     readonly config: OneBot12WsConfig;
     readonly createWebSocket?: (url: string, options: OneBot12WsCreateOptions) => OneBot12WsSocket;
 }
-export declare class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
+export declare class OneBot12WsEndpoint extends Onebot12Client implements Endpoint {
     #private;
-    readonly client: Onebot12Client;
-    readonly management: EndpointManagement;
-    readonly control: EndpointControl;
-    readonly content: import("@zhin.js/adapter").EndpointContentPort;
+    readonly [endpointSpec]: EndpointSpecification;
     constructor(options: OneBot12WsEndpointOptions);
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    recallMessage(messageId: string): Promise<void>;
 }