@zhin.js/adapter-satori 5.0.13 → 6.0.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @zhin.js/adapter-satori
 
+## 6.0.1
+
+### Patch Changes
+
+- 4e8117c: Expose the published imhelper protocol Clients from every Endpoint, preserve native action responses, and route host-owned HTTP, WebSocket, and raw ingress through the Client APIs. Add the shared `ClientEndpoint` deep base so concrete transports inherit one open-gated Client event bridge, and move reverse WebSocket lifecycle and heartbeat cleanup onto the common lifecycle state machine.
+- 1fc78bc: Unify native platform Client access behind the literal `adapter` discriminant. Handlers infer both native events and Clients, while command, inbound/outbound middleware, and both Agent tool authoring surfaces expose the exact operation-scoped Client through a lazy `$client` getter. Definitions without `adapter` keep `$client` typed as `unknown`, and runtime dispatch rejects adapter mismatches before resolving the Client. Bundled platform tools now use this single path instead of model-provided endpoint ids and adapter-specific dependency wrappers. Every adapter registers one Client/EventMap contract, and protocol adapters including NapCat, Milky, OneBot and Satori now produce transport-independent Client objects rather than letting Endpoint instances impersonate Clients.
+- 2ca9a52: Upgrade the protocol Clients to imhelper 1.0.7, keep receiver ownership exclusively in Endpoint through manual mode, expose structured protocol errors, and support canonical non-message Client events.
+- Updated dependencies [4e8117c]
+- Updated dependencies [54bfd6b]
+- Updated dependencies [12025ee]
+- Updated dependencies [09b14d6]
+- Updated dependencies [1fc78bc]
+  - @zhin.js/adapter@1.2.1
+  - @zhin.js/core@1.5.14
+  - @zhin.js/host-http@1.0.13
+  - @zhin.js/command@1.0.16
+  - @zhin.js/logger@1.0.77
+  - zhin.js@6.0.14
+  - @zhin.js/feature-kit@1.0.13
+
+## 6.0.0
+
+### Patch Changes
+
+- f2c532f: Expose exact per-Endpoint message operations through one validated Adapter capability model, route Core control calls through declared active capabilities, and connect existing recall, edit, reaction, and typing implementations across platform adapters.
+- Updated dependencies [b10d058]
+- Updated dependencies [f2c532f]
+  - @zhin.js/host-http@1.0.12
+  - @zhin.js/adapter@1.2.0
+  - @zhin.js/core@1.5.13
+  - zhin.js@6.0.13
+
 ## 5.0.13
 
 ### Patch Changes

package/README.md

@@ -22,7 +22,7 @@ pnpm add @zhin.js/adapter-satori
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/satori.ts`（`defineAdapter`）
-- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - `@zhin.js/host-http` — Webhook 模式需 `httpHostToken` 注册 POST 路由
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`（`baseUrl` / `token` / …）
@@ -32,6 +32,16 @@ pnpm add @zhin.js/adapter-satori
 
 入站 `metadata.mentioned`：消息 content 中 `<at id="…"/>` 元素的 id 等于登录 selfId（READY/事件 `login.user.id`）时置 `true`。
 
+每个 Endpoint 的 `$client` 是 `@imhelper/satori-v1` 的 `SatoriV1Client`。业务代码直接调用
+`$client.call(resource, method, params)` 或其公开便捷方法；Client 负责协议事件变换，Endpoint
+只负责 Satori IDENTIFY/心跳、Webhook 鉴权和 Zhin 投影。
+
+## 前置条件
+
+1. 准备兼容 Satori 的服务端，记录 API Base、平台标识和用户标识。
+2. 正向 WS 需 Zhin 可达 Satori 服务；Webhook 需服务端可达 Zhin HTTP Host。
+3. 若服务启用鉴权，在两端配置相同的 Bearer token。
+
 ## 最小配置
 
 ```yaml
@@ -89,3 +99,12 @@ SDK 会向 `path` 发送 POST，请求头 `Satori-Opcode: 0` 表示事件；适
 - [介绍](https://satori.chat/zh-CN/introduction.html)
 - [总览](https://satori.chat/zh-CN/protocol/overview.html)
 - [API](https://satori.chat/zh-CN/protocol/api.html)
+
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| WS IDENTIFY 失败 | 检查 `baseUrl`、平台/用户标识与 token |
+| Webhook 无事件 | 确认路径、`Satori-Opcode: 0` 与 HTTP Host |
+| 401 | 检查 API、WS IDENTIFY 与 Webhook 使用的 token 是否一致 |
+| 发送目标错误 | 核对 `channel_id` 与 Conversation kind；DIRECT 才映射为 private |

package/adapters/satori.js

@@ -3,7 +3,6 @@
  * Convention entry: discover `adapters/satori.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { SatoriWebhookEndpoint, SatoriWsEndpoint } from "../lib/endpoint.js";
 import { resolveSatoriConfig, } from "../lib/protocol.js";
@@ -11,6 +10,7 @@ import { satoriRuntimeStateToken } from "../lib/satori-runtime-state.js";
 export { SatoriWebhookEndpoint, SatoriWsEndpoint } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
     // Satori 协议 img/file 元素消费 url 与 base64 内联数据；无卡片交互面，交互段降级纯文本。
     segments: {
         outboundMedia: ['url', 'base64'],
@@ -18,8 +18,6 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveSatoriConfig(context.config);
-        const gateway = context.use(messageGatewayToken);
-        const sideEvents = context.use(sideEventGatewayToken);
         // 注册到插件运行时状态（satori.endpoint list 的"运行中"数据源）
         context.use(satoriRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
@@ -28,16 +26,12 @@ export default defineAdapter({
         if (config.connection === 'webhook') {
             return new SatoriWebhookEndpoint({
                 id: context.id,
-                gateway,
-                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });
         }
         return new SatoriWsEndpoint({
             id: context.id,
-            gateway,
-            sideEvents,
             config,
         });
     },

package/adapters/satori.ts

@@ -2,7 +2,6 @@
  * Convention entry: discover `adapters/satori.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { SatoriWebhookEndpoint, SatoriWsEndpoint } from '../src/endpoint.js';
 import {
@@ -22,6 +21,7 @@ export type {
 
 export default defineAdapter<SatoriAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
   // Satori 协议 img/file 元素消费 url 与 base64 内联数据；无卡片交互面，交互段降级纯文本。
   segments: {
     outboundMedia: ['url', 'base64'],
@@ -29,8 +29,6 @@ export default defineAdapter<SatoriAdapterConfig>({
   },
   create(context) {
     const config = resolveSatoriConfig(context.config);
-    const gateway = context.use(messageGatewayToken);
-    const sideEvents = context.use(sideEventGatewayToken);
     // 注册到插件运行时状态（satori.endpoint list 的"运行中"数据源）
     context.use(satoriRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
@@ -39,16 +37,12 @@ export default defineAdapter<SatoriAdapterConfig>({
     if (config.connection === 'webhook') {
       return new SatoriWebhookEndpoint({
         id: context.id,
-        gateway,
-        sideEvents,
         http: context.use(httpHostToken),
         config,
       });
     }
     return new SatoriWsEndpoint({
       id: context.id,
-      gateway,
-      sideEvents,
       config,
     });
   },

package/lib/client.d.ts

@@ -0,0 +1,18 @@
+import { SatoriV1Client, type SatoriV1Event } from '@imhelper/satori-v1';
+import { type EventMap, type ImHelperEventMap } from 'imhelper';
+import { type ClientEventPayloads } from 'zhin.js/adapter';
+import type { ResolvedSatoriConfig, SatoriApiOptions, callSatoriApi } from './protocol.js';
+export { SatoriV1Client as SatoriClient } from '@imhelper/satori-v1';
+type SatoriClientEvents = ImHelperEventMap<string, SatoriV1Event, EventMap<string>>;
+export type SatoriClientEventMap = ClientEventPayloads<SatoriClientEvents>;
+export declare function createSatoriEndpointClient(config: ResolvedSatoriConfig, request: typeof callSatoriApi, apiOptions: () => SatoriApiOptions): SatoriV1Client;
+export declare function forwardSatoriClientEvents(client: SatoriV1Client, receive: (name: string, payload: unknown) => void): () => void;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly satori: {
+            readonly client: SatoriV1Client;
+            readonly events: SatoriClientEventMap;
+        };
+    }
+}
+export declare const satoriClient: import("@zhin.js/adapter").EndpointClientToken<SatoriV1Client, ClientEventPayloads<SatoriClientEvents>>;

package/lib/client.js

@@ -0,0 +1,21 @@
+import { SatoriV1Client, } from '@imhelper/satori-v1';
+import { EventFactory } from 'imhelper';
+import { defineEndpointClient, forwardEndpointClientEvents, } from 'zhin.js/adapter';
+export { SatoriV1Client as SatoriClient } from '@imhelper/satori-v1';
+export function createSatoriEndpointClient(config, request, apiOptions) {
+    return new SatoriV1Client({
+        baseUrl: config.baseUrl,
+        selfId: config.id,
+        accessToken: config.token,
+        receiveMode: 'manual',
+        call: (resource, method, params) => request(apiOptions(), resource, method, params ?? {}),
+    });
+}
+const satoriClientEventNames = Object.freeze([
+    ...EventFactory.getSupportedEventTypes(),
+    'event',
+]);
+export function forwardSatoriClientEvents(client, receive) {
+    return forwardEndpointClientEvents(client, satoriClientEventNames, receive);
+}
+export const satoriClient = defineEndpointClient('satori');

package/lib/endpoint.d.ts

@@ -1,60 +1,51 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
 /**
  * SatoriEndpoint — WebSocket and webhook lifecycle, outbound, admit.
  */
-import { type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
-import { callSatoriApi, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig, type SatoriEventBody, type SatoriLogin } from './protocol.js';
+import { callSatoriApi, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig } from './protocol.js';
+import { type SatoriClient } from './client.js';
 import { type CreateSatoriWebSocket } from './ws.js';
 export type SatoriApiCaller = typeof callSatoriApi;
 export interface SatoriWsEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly config: ResolvedSatoriWsConfig;
     readonly createWebSocket?: CreateSatoriWebSocket;
     readonly callApi?: SatoriApiCaller;
 }
-export declare class SatoriWsEndpoint implements EndpointInstance {
+export declare class SatoriWsEndpoint extends ClientEndpoint<SatoriClient> {
     #private;
+    readonly client: SatoriClient;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
     constructor(options: SatoriWsEndpointOptions);
     start(): Promise<void>;
-    open(): void;
-    close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    /** Test / internal: admit a gateway event when the endpoint is open. */
-    admit(body: SatoriEventBody): void;
-    recall(id: string): Promise<void>;
-    /** Test helper: inject a READY login without a live socket. */
-    setLogin(login: SatoriLogin): void;
+    recall(id: string, fallbackChannelId?: string): Promise<void>;
 }
 export interface SatoriWebhookEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: ResolvedSatoriWebhookConfig;
     readonly callApi?: SatoriApiCaller;
 }
-export declare class SatoriWebhookEndpoint implements EndpointInstance {
+export declare class SatoriWebhookEndpoint extends ClientEndpoint<SatoriClient> {
     #private;
+    readonly client: SatoriClient;
     readonly management: EndpointManagement;
+    readonly control: EndpointControl;
     constructor(options: SatoriWebhookEndpointOptions);
     /** Used by webhook handler. */
     get isOpen(): boolean;
     get config(): ResolvedSatoriWebhookConfig;
+    acceptHttp(request: IncomingMessage, response: ServerResponse): Promise<void>;
     start(): Promise<void>;
-    open(): void;
-    close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
-    admit(body: SatoriEventBody): void;
-    recall(id: string): Promise<void>;
-    /** Test helper: inject login without a live webhook push. */
-    setLogin(login: SatoriLogin): void;
+    recall(id: string, fallbackChannelId?: string): Promise<void>;
 }
 export type SatoriManagementApi = (resource: string, method: string, params: Record<string, unknown>) => Promise<unknown>;
 /**

package/lib/endpoint.js

@@ -1,23 +1,34 @@
 /**
  * SatoriEndpoint — WebSocket and webhook lifecycle, outbound, admit.
  */
-import { createEndpointLifecycle, } from 'zhin.js/adapter';
+import { ClientEndpoint, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatMessageId, formatSatoriOutbound, isMessageEvent, isSelfMentioned, parseMessageRef, resolveInboundSender, satoriInboundConversation, } from './protocol.js';
 import { registerSatoriWebhookRoutes } from './webhook.js';
+import { createSatoriEndpointClient, forwardSatoriClientEvents } from './client.js';
 import { WS_OPEN, defaultCreateWebSocket, } from './ws.js';
-export class SatoriWsEndpoint {
+export class SatoriWsEndpoint extends ClientEndpoint {
+    client;
     #logger;
     #options;
     #lifecycle;
     #ws = null;
     #login;
     #lastSn;
-    #open = false;
-    management = createSatoriEndpointManagement((resource, method, params) => this.#api(resource, method, params));
+    management;
+    control = Object.freeze({
+        recall: (message) => this.recall(message.id, message.conversation.id),
+    });
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('satori', options.config.id);
         this.#options = options;
+        this.client = createSatoriEndpointClient(options.config, options.callApi ?? callSatoriApi, () => this.#apiOptions());
+        this.management = createSatoriEndpointManagement((resource, method, params) => this.client.call(resource, method, params));
+        this.bindClientEvents((receive) => forwardSatoriClientEvents(this.client, receive), (name, payload) => {
+            if (name === 'event')
+                this.#admitRaw(payload);
+        }, (name, error) => this.#warnPlatformEvent(name, error));
         const { config } = options;
         this.#lifecycle = createEndpointLifecycle({
             name: config.id,
@@ -53,21 +64,15 @@ export class SatoriWsEndpoint {
             throw err;
         }
     }
-    open() {
-        this.#open = true;
-    }
-    close() {
-        this.#open = false;
-    }
     async stop() {
-        this.#open = false;
+        this.close();
         // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
         await this.#lifecycle.stop();
         this.#ws = null;
     }
     async send({ conversation, payload }) {
         const content = formatSatoriOutbound(payload);
-        const result = await this.#api('message', 'create', {
+        const result = await this.client.call('message', 'create', {
             channel_id: conversation.id,
             content,
         });
@@ -80,10 +85,7 @@ export class SatoriWsEndpoint {
         }));
         return msgId ? formatMessageId(conversation.id, msgId) : '';
     }
-    /** Test / internal: admit a gateway event when the endpoint is open. */
-    admit(body) {
-        if (!this.#open)
-            return;
+    #admitRaw(body) {
         if (body.login && !this.#login)
             this.#login = body.login;
         if (!isMessageEvent(body))
@@ -93,7 +95,7 @@ export class SatoriWsEndpoint {
         const sender = resolveInboundSender(body);
         const selfId = this.#login?.user?.id ?? body.login?.user?.id;
         const mentioned = isSelfMentioned(body, selfId);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: body.message.id },
             content,
@@ -114,16 +116,19 @@ export class SatoriWsEndpoint {
             }));
         });
     }
-    async recall(id) {
+    async recall(id, fallbackChannelId) {
         const { channelId, messageId } = parseMessageRef(id);
-        await this.#api('message', 'delete', {
-            channel_id: channelId,
+        await this.client.call('message', 'delete', {
+            channel_id: channelId || fallbackChannelId || '',
             message_id: messageId,
         });
     }
-    /** Test helper: inject a READY login without a live socket. */
-    setLogin(login) {
-        this.#login = login;
+    #warnPlatformEvent(name, error) {
+        this.#logger.warn(formatCompact({
+            op: 'satori_platform_event_failed',
+            event: name,
+            error: error instanceof Error ? error.message : String(error),
+        }));
     }
     async #connect(handle) {
         const { config } = this.#options;
@@ -206,11 +211,25 @@ export class SatoriWsEndpoint {
         if (signal.op === SatoriOpcode.PONG) {
             // 喂狗：复位基座看门狗计数
             this.#lifecycle.notifyHeartbeatAck();
+            void this.emitPlatform('pong', signal).catch((error) => {
+                this.#logger.warn(formatCompact({
+                    op: 'satori_platform_event_failed',
+                    event: 'pong',
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            });
             return;
         }
         if (signal.op === SatoriOpcode.READY && signal.body?.logins) {
             const logins = signal.body.logins;
             this.#login = logins[0];
+            void this.emitPlatform('ready', signal).catch((error) => {
+                this.#logger.warn(formatCompact({
+                    op: 'satori_platform_event_failed',
+                    event: 'ready',
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            });
             if (!this.#login?.platform || !this.#login?.user?.id) {
                 this.#logger.warn(formatCompact({ op: 'ready', ok: false, error: 'missing platform/user' }));
             }
@@ -219,7 +238,7 @@ export class SatoriWsEndpoint {
         if (signal.op === SatoriOpcode.EVENT && signal.body) {
             if (typeof signal.body.sn === 'number')
                 this.#lastSn = signal.body.sn;
-            this.admit(signal.body);
+            this.client.ingest(signal.body);
         }
     }
     #sendSignal(op, body) {
@@ -235,30 +254,39 @@ export class SatoriWsEndpoint {
             token: this.#options.config.token,
         };
     }
-    #api(resource, method, params) {
-        const call = this.#options.callApi ?? callSatoriApi;
-        return call(this.#apiOptions(), resource, method, params);
-    }
 }
-export class SatoriWebhookEndpoint {
+export class SatoriWebhookEndpoint extends ClientEndpoint {
+    client;
     #logger;
     #options;
     #login;
     #routeReleases = [];
-    #open = false;
     #started = false;
-    management = createSatoriEndpointManagement((resource, method, params) => this.#api(resource, method, params));
+    management;
+    control = Object.freeze({
+        recall: (message) => this.recall(message.id, message.conversation.id),
+    });
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('satori', options.config.id);
         this.#options = options;
+        this.client = createSatoriEndpointClient(options.config, options.callApi ?? callSatoriApi, () => this.#apiOptions());
+        this.management = createSatoriEndpointManagement((resource, method, params) => this.client.call(resource, method, params));
+        this.bindClientEvents((receive) => forwardSatoriClientEvents(this.client, receive), (name, payload) => {
+            if (name === 'event')
+                this.#admitRaw(payload);
+        }, (name, error) => this.#warnPlatformEvent(name, error));
     }
     /** Used by webhook handler. */
     get isOpen() {
-        return this.#open;
+        return this.clientEventsOpen;
     }
     get config() {
         return this.#options.config;
     }
+    async acceptHttp(request, response) {
+        await this.client.acceptHttp(request, response);
+    }
     async start() {
         if (this.#started)
             return;
@@ -280,14 +308,8 @@ export class SatoriWebhookEndpoint {
             path: this.#options.config.path,
         }));
     }
-    open() {
-        this.#open = true;
-    }
-    close() {
-        this.#open = false;
-    }
     async stop() {
-        this.#open = false;
+        this.close();
         for (const release of this.#routeReleases.splice(0))
             release();
         this.#started = false;
@@ -297,7 +319,7 @@ export class SatoriWebhookEndpoint {
     }
     async send({ conversation, payload }) {
         const content = formatSatoriOutbound(payload);
-        const result = await this.#api('message', 'create', {
+        const result = await this.client.call('message', 'create', {
             channel_id: conversation.id,
             content,
         });
@@ -310,9 +332,7 @@ export class SatoriWebhookEndpoint {
         }));
         return msgId ? formatMessageId(conversation.id, msgId) : '';
     }
-    admit(body) {
-        if (!this.#open)
-            return;
+    #admitRaw(body) {
         if (body.login && !this.#login)
             this.#login = body.login;
         if (!isMessageEvent(body))
@@ -322,7 +342,7 @@ export class SatoriWebhookEndpoint {
         const sender = resolveInboundSender(body);
         const selfId = this.#login?.user?.id ?? body.login?.user?.id;
         const mentioned = isSelfMentioned(body, selfId);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: body.message.id },
             content,
@@ -343,16 +363,19 @@ export class SatoriWebhookEndpoint {
             }));
         });
     }
-    async recall(id) {
+    async recall(id, fallbackChannelId) {
         const { channelId, messageId } = parseMessageRef(id);
-        await this.#api('message', 'delete', {
-            channel_id: channelId,
+        await this.client.call('message', 'delete', {
+            channel_id: channelId || fallbackChannelId || '',
             message_id: messageId,
         });
     }
-    /** Test helper: inject login without a live webhook push. */
-    setLogin(login) {
-        this.#login = login;
+    #warnPlatformEvent(name, error) {
+        this.#logger.warn(formatCompact({
+            op: 'satori_platform_event_failed',
+            event: name,
+            error: error instanceof Error ? error.message : String(error),
+        }));
     }
     #apiOptions() {
         return {
@@ -362,10 +385,6 @@ export class SatoriWebhookEndpoint {
             token: this.#options.config.token,
         };
     }
-    #api(resource, method, params) {
-        const call = this.#options.callApi ?? callSatoriApi;
-        return call(this.#apiOptions(), resource, method, params);
-    }
 }
 function isPrivateChannelType(body) {
     const channel = body.channel ?? body.message?.channel;

package/lib/index.d.ts

@@ -1,4 +1,8 @@
 export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatSatoriOutbound, isMessageEvent, isPrivateChannel, resolveInboundSender, resolveSatoriConfig, satoriInboundConversation, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig, type SatoriAdapterConfig, type SatoriApiOptions, type SatoriChannel, type SatoriEventBody, type SatoriLogin, type SatoriMessage, type SatoriSignal, type SatoriUser, type SatoriWireSegment, } from './protocol.js';
 export { SatoriWebhookEndpoint, SatoriWsEndpoint, type CreateSatoriWebSocket, type SatoriApiCaller, type SatoriWebhookEndpointOptions, type SatoriWsEndpointOptions, type SatoriWsSocket, } from './endpoint.js';
-export { handleSatoriWebhookRequest, readRequestBody, registerSatoriWebhookRoutes, resolveSatoriOpcode, verifySatoriToken, type SatoriWebhookHandler, } from './webhook.js';
+export { handleSatoriWebhookRequest, registerSatoriWebhookRoutes, resolveSatoriOpcode, verifySatoriToken, type SatoriWebhookHandler, } from './webhook.js';
 export { WS_OPEN, defaultCreateWebSocket, } from './ws.js';
+export { SatoriClient, satoriClient, type SatoriClientEventMap, } from './client.js';
+export type { SatoriAdapterConfig as ImHelperSatoriAdapterConfig, SatoriActionUrlResolver, SatoriCall, SatoriV1ClientConfig, SatoriV1Event, SatoriV1Response, } from '@imhelper/satori-v1';
+export { ProtocolError } from '@imhelper/satori-v1';
+export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';

package/lib/index.js

@@ -1,4 +1,6 @@
 export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatSatoriOutbound, isMessageEvent, isPrivateChannel, resolveInboundSender, resolveSatoriConfig, satoriInboundConversation, } from './protocol.js';
 export { SatoriWebhookEndpoint, SatoriWsEndpoint, } from './endpoint.js';
-export { handleSatoriWebhookRequest, readRequestBody, registerSatoriWebhookRoutes, resolveSatoriOpcode, verifySatoriToken, } from './webhook.js';
+export { handleSatoriWebhookRequest, registerSatoriWebhookRoutes, resolveSatoriOpcode, verifySatoriToken, } from './webhook.js';
 export { WS_OPEN, defaultCreateWebSocket, } from './ws.js';
+export { SatoriClient, satoriClient, } from './client.js';
+export { ProtocolError } from '@imhelper/satori-v1';

package/lib/protocol.d.ts

@@ -121,7 +121,7 @@ export declare function buildWsUrl(baseUrl: string, token?: string): string;
  * @see https://satori.chat/en-US/protocol/api.html
  */
 export declare function callSatoriApi<T = unknown>(options: SatoriApiOptions, resource: string, method: string, params?: Record<string, unknown>): Promise<T>;
-/** Build inbound text for MessageGateway.receive. */
+/** Build inbound text for OutboundMessageService.receive. */
 export declare function formatInboundContent(body: SatoriEventBody & {
     message: SatoriMessage;
 }): string;

package/lib/protocol.js

@@ -108,7 +108,7 @@ export async function callSatoriApi(options, resource, method, params = {}) {
         throw new Error(`Satori API 无效 JSON: ${text.slice(0, 200)}`);
     }
 }
-/** Build inbound text for MessageGateway.receive. */
+/** Build inbound text for OutboundMessageService.receive. */
 export function formatInboundContent(body) {
     const content = body.message.content ?? '';
     return typeof content === 'string' ? content : String(content);

package/lib/satori-endpoint-commands.d.ts

@@ -1 +1 @@
-export declare const satoriEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;
+export declare const satoriEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;

package/lib/webhook.d.ts

@@ -1,14 +1,12 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
-import { type ResolvedSatoriWebhookConfig, type SatoriEventBody, type SatoriLogin } from './protocol.js';
+import { type ResolvedSatoriWebhookConfig } from './protocol.js';
 export interface SatoriWebhookHandler {
     readonly config: ResolvedSatoriWebhookConfig;
     readonly isOpen: boolean;
-    admit(body: SatoriEventBody): void;
-    setLogin(login: SatoriLogin): void;
+    acceptHttp(request: IncomingMessage, response: ServerResponse): Promise<void>;
 }
 export declare function registerSatoriWebhookRoutes(http: HttpHost, handler: SatoriWebhookHandler): HttpRouteRegistration[];
 export declare function handleSatoriWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: SatoriWebhookHandler): Promise<void>;
 export declare function resolveSatoriOpcode(request: IncomingMessage): number | undefined;
 export declare function verifySatoriToken(token: string | undefined, request: IncomingMessage): boolean;
-export declare function readRequestBody(request: IncomingMessage): Promise<string>;

package/lib/webhook.js

@@ -26,24 +26,13 @@ export async function handleSatoriWebhookRequest(request, response, handler) {
             response.end(JSON.stringify({ message: 'OK' }));
             return;
         }
-        const raw = await readRequestBody(request);
-        let body;
-        try {
-            body = JSON.parse(raw);
+        if (handler.isOpen) {
+            await handler.acceptHttp(request, response);
         }
-        catch {
-            response.writeHead(400, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ message: 'Invalid JSON' }));
-            return;
-        }
-        if (opcode === SatoriOpcode.EVENT && handler.isOpen) {
-            handler.admit(body);
-        }
-        else if (opcode === SatoriOpcode.META && body.login && handler.isOpen) {
-            handler.setLogin(body.login);
+        else {
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ status: 'ok' }));
         }
-        response.writeHead(200, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ message: 'OK' }));
     }
     catch (error) {
         logger.error('Satori webhook error:', error);
@@ -69,17 +58,3 @@ export function verifySatoriToken(token, request) {
     const actual = Buffer.from(auth, 'utf8');
     return actual.length === expected.length && timingSafeEqual(actual, expected);
 }
-export async function readRequestBody(request) {
-    const chunks = [];
-    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-satori",
-  "version": "5.0.13",
+  "version": "6.0.1",
   "description": "Zhin.js Satori adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -38,26 +38,29 @@
     "directory": "plugins/adapters/satori"
   },
   "dependencies": {
+    "@imhelper/satori-v1": "1.0.7",
+    "imhelper": "1.0.7",
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.11",
-    "@zhin.js/core": "1.5.12",
-    "@zhin.js/host-http": "1.0.11",
+    "@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",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@zhin.js/host-http": "1.0.11",
-    "zhin.js": "6.0.12"
+    "@zhin.js/host-http": "1.0.13",
+    "zhin.js": "6.0.14"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.11",
-    "@zhin.js/command": "1.0.15",
-    "@zhin.js/core": "1.5.12",
-    "zhin.js": "6.0.12"
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/command": "1.0.16",
+    "@zhin.js/core": "1.5.14",
+    "zhin.js": "6.0.14"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {

package/src/client.ts

@@ -0,0 +1,57 @@
+import {
+  SatoriV1Client,
+  type SatoriV1Event,
+} from '@imhelper/satori-v1';
+import { EventFactory, type EventMap, type ImHelperEventMap } from 'imhelper';
+import {
+  defineEndpointClient,
+  forwardEndpointClientEvents,
+  type ClientEventPayloads,
+} from 'zhin.js/adapter';
+import type {
+  ResolvedSatoriConfig,
+  SatoriApiOptions,
+  callSatoriApi,
+} from './protocol.js';
+
+export { SatoriV1Client as SatoriClient } from '@imhelper/satori-v1';
+
+type SatoriClientEvents = ImHelperEventMap<string, SatoriV1Event, EventMap<string>>;
+export type SatoriClientEventMap = ClientEventPayloads<SatoriClientEvents>;
+
+export function createSatoriEndpointClient(
+  config: ResolvedSatoriConfig,
+  request: typeof callSatoriApi,
+  apiOptions: () => SatoriApiOptions,
+): SatoriV1Client {
+  return new SatoriV1Client({
+    baseUrl: config.baseUrl,
+    selfId: config.id,
+    accessToken: config.token,
+    receiveMode: 'manual',
+    call: (resource, method, params) => request(apiOptions(), resource, method, params ?? {}),
+  });
+}
+
+const satoriClientEventNames = Object.freeze([
+  ...EventFactory.getSupportedEventTypes<string>(),
+  'event',
+]);
+
+export function forwardSatoriClientEvents(
+  client: SatoriV1Client,
+  receive: (name: string, payload: unknown) => void,
+): () => void {
+  return forwardEndpointClientEvents(client, satoriClientEventNames, receive);
+}
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly satori: {
+      readonly client: SatoriV1Client;
+      readonly events: SatoriClientEventMap;
+    };
+  }
+}
+
+export const satoriClient = defineEndpointClient<SatoriV1Client, SatoriClientEventMap>('satori');

package/src/endpoint.ts

@@ -1,17 +1,18 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
 /**
  * SatoriEndpoint — WebSocket and webhook lifecycle, outbound, admit.
  */
 import {
+  ClientEndpoint,
   createEndpointLifecycle,
   type EndpointChannel,
   type EndpointConnectHandle,
+  type EndpointControl,
   type EndpointGroup,
-  type EndpointInstance,
   type EndpointLifecycle,
   type EndpointManagement,
   type EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -36,6 +37,7 @@ import {
   type SatoriSignal,
 } from './protocol.js';
 import { registerSatoriWebhookRoutes } from './webhook.js';
+import { createSatoriEndpointClient, forwardSatoriClientEvents, type SatoriClient } from './client.js';
 import {
   WS_OPEN,
   defaultCreateWebSocket,
@@ -47,14 +49,13 @@ export type SatoriApiCaller = typeof callSatoriApi;
 
 export interface SatoriWsEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly config: ResolvedSatoriWsConfig;
   readonly createWebSocket?: CreateSatoriWebSocket;
   readonly callApi?: SatoriApiCaller;
 }
 
-export class SatoriWsEndpoint implements EndpointInstance {
+export class SatoriWsEndpoint extends ClientEndpoint<SatoriClient> {
+  readonly client: SatoriClient;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: SatoriWsEndpointOptions;
@@ -62,14 +63,30 @@ export class SatoriWsEndpoint implements EndpointInstance {
   #ws: SatoriWsSocket | null = null;
   #login: SatoriLogin | undefined;
   #lastSn: number | undefined;
-  #open = false;
-  readonly management: EndpointManagement = createSatoriEndpointManagement(
-    (resource, method, params) => this.#api(resource, method, params),
-  );
+  readonly management: EndpointManagement;
+  readonly control: EndpointControl = Object.freeze<EndpointControl>({
+    recall: (message) => this.recall(message.id, message.conversation.id),
+  });
 
   constructor(options: SatoriWsEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('satori', options.config.id);
     this.#options = options;
+    this.client = createSatoriEndpointClient(
+      options.config,
+      options.callApi ?? callSatoriApi,
+      () => this.#apiOptions(),
+    );
+    this.management = createSatoriEndpointManagement(
+      (resource, method, params) => this.client.call(resource, method, params),
+    );
+    this.bindClientEvents(
+      (receive) => forwardSatoriClientEvents(this.client, receive),
+      (name, payload) => {
+        if (name === 'event') this.#admitRaw(payload as SatoriEventBody);
+      },
+      (name, error) => this.#warnPlatformEvent(name, error),
+    );
     const { config } = options;
     this.#lifecycle = createEndpointLifecycle({
       name: config.id,
@@ -105,16 +122,8 @@ export class SatoriWsEndpoint implements EndpointInstance {
     }
   }
 
-  open(): void {
-    this.#open = true;
-  }
-
-  close(): void {
-    this.#open = false;
-  }
-
   async stop(): Promise<void> {
-    this.#open = false;
+    this.close();
     // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
     await this.#lifecycle.stop();
     this.#ws = null;
@@ -122,7 +131,7 @@ export class SatoriWsEndpoint implements EndpointInstance {
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const content = formatSatoriOutbound(payload);
-    const result = await this.#api('message', 'create', {
+    const result = await this.client.call('message', 'create', {
       channel_id: conversation.id,
       content,
     });
@@ -136,9 +145,7 @@ export class SatoriWsEndpoint implements EndpointInstance {
     return msgId ? formatMessageId(conversation.id, msgId) : '';
   }
 
-  /** Test / internal: admit a gateway event when the endpoint is open. */
-  admit(body: SatoriEventBody): void {
-    if (!this.#open) return;
+  #admitRaw(body: SatoriEventBody): void {
     if (body.login && !this.#login) this.#login = body.login;
     if (!isMessageEvent(body)) return;
     const conversation = satoriInboundConversation(String(this.#options.id), body);
@@ -146,7 +153,7 @@ export class SatoriWsEndpoint implements EndpointInstance {
     const sender = resolveInboundSender(body);
     const selfId = this.#login?.user?.id ?? body.login?.user?.id;
     const mentioned = isSelfMentioned(body, selfId);
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: body.message.id },
       content,
@@ -168,17 +175,20 @@ export class SatoriWsEndpoint implements EndpointInstance {
     });
   }
 
-  async recall(id: string): Promise<void> {
+  async recall(id: string, fallbackChannelId?: string): Promise<void> {
     const { channelId, messageId } = parseMessageRef(id);
-    await this.#api('message', 'delete', {
-      channel_id: channelId,
+    await this.client.call('message', 'delete', {
+      channel_id: channelId || fallbackChannelId || '',
       message_id: messageId,
     });
   }
 
-  /** Test helper: inject a READY login without a live socket. */
-  setLogin(login: SatoriLogin): void {
-    this.#login = login;
+  #warnPlatformEvent(name: string, error: unknown): void {
+    this.#logger.warn(formatCompact({
+      op: 'satori_platform_event_failed',
+      event: name,
+      error: error instanceof Error ? error.message : String(error),
+    }));
   }
 
   async #connect(handle: EndpointConnectHandle): Promise<void> {
@@ -265,11 +275,25 @@ export class SatoriWsEndpoint implements EndpointInstance {
     if (signal.op === SatoriOpcode.PONG) {
       // 喂狗：复位基座看门狗计数
       this.#lifecycle.notifyHeartbeatAck();
+      void this.emitPlatform('pong', signal).catch((error) => {
+        this.#logger.warn(formatCompact({
+          op: 'satori_platform_event_failed',
+          event: 'pong',
+          error: error instanceof Error ? error.message : String(error),
+        }));
+      });
       return;
     }
     if (signal.op === SatoriOpcode.READY && signal.body?.logins) {
       const logins = signal.body.logins as SatoriLogin[];
       this.#login = logins[0];
+      void this.emitPlatform('ready', signal).catch((error) => {
+        this.#logger.warn(formatCompact({
+          op: 'satori_platform_event_failed',
+          event: 'ready',
+          error: error instanceof Error ? error.message : String(error),
+        }));
+      });
       if (!this.#login?.platform || !this.#login?.user?.id) {
         this.#logger.warn(formatCompact({ op: 'ready', ok: false, error: 'missing platform/user' }));
       }
@@ -277,7 +301,7 @@ export class SatoriWsEndpoint implements EndpointInstance {
     }
     if (signal.op === SatoriOpcode.EVENT && signal.body) {
       if (typeof signal.body.sn === 'number') this.#lastSn = signal.body.sn;
-      this.admit(signal.body as SatoriEventBody);
+      this.client.ingest(signal.body as Parameters<SatoriClient['ingest']>[0]);
     }
   }
 
@@ -295,51 +319,62 @@ export class SatoriWsEndpoint implements EndpointInstance {
     };
   }
 
-  #api(
-    resource: string,
-    method: string,
-    params: Record<string, unknown>,
-  ): Promise<unknown> {
-    const call = this.#options.callApi ?? callSatoriApi;
-    return call(this.#apiOptions(), resource, method, params);
-  }
 }
 
 export interface SatoriWebhookEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: ResolvedSatoriWebhookConfig;
   readonly callApi?: SatoriApiCaller;
 }
 
-export class SatoriWebhookEndpoint implements EndpointInstance {
+export class SatoriWebhookEndpoint extends ClientEndpoint<SatoriClient> {
+  readonly client: SatoriClient;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: SatoriWebhookEndpointOptions;
   #login: SatoriLogin | undefined;
   #routeReleases: HttpRouteRegistration[] = [];
-  #open = false;
   #started = false;
-  readonly management: EndpointManagement = createSatoriEndpointManagement(
-    (resource, method, params) => this.#api(resource, method, params),
-  );
+  readonly management: EndpointManagement;
+  readonly control: EndpointControl = Object.freeze<EndpointControl>({
+    recall: (message) => this.recall(message.id, message.conversation.id),
+  });
 
   constructor(options: SatoriWebhookEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('satori', options.config.id);
     this.#options = options;
+    this.client = createSatoriEndpointClient(
+      options.config,
+      options.callApi ?? callSatoriApi,
+      () => this.#apiOptions(),
+    );
+    this.management = createSatoriEndpointManagement(
+      (resource, method, params) => this.client.call(resource, method, params),
+    );
+    this.bindClientEvents(
+      (receive) => forwardSatoriClientEvents(this.client, receive),
+      (name, payload) => {
+        if (name === 'event') this.#admitRaw(payload as SatoriEventBody);
+      },
+      (name, error) => this.#warnPlatformEvent(name, error),
+    );
   }
 
   /** Used by webhook handler. */
   get isOpen(): boolean {
-    return this.#open;
+    return this.clientEventsOpen;
   }
 
   get config(): ResolvedSatoriWebhookConfig {
     return this.#options.config;
   }
 
+  async acceptHttp(request: IncomingMessage, response: ServerResponse): Promise<void> {
+    await this.client.acceptHttp(request, response);
+  }
+
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
@@ -361,16 +396,8 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
     }));
   }
 
-  open(): void {
-    this.#open = true;
-  }
-
-  close(): void {
-    this.#open = false;
-  }
-
   async stop(): Promise<void> {
-    this.#open = false;
+    this.close();
     for (const release of this.#routeReleases.splice(0)) release();
     this.#started = false;
     this.#logger.debug(formatCompact({
@@ -380,7 +407,7 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const content = formatSatoriOutbound(payload);
-    const result = await this.#api('message', 'create', {
+    const result = await this.client.call('message', 'create', {
       channel_id: conversation.id,
       content,
     });
@@ -394,8 +421,7 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
     return msgId ? formatMessageId(conversation.id, msgId) : '';
   }
 
-  admit(body: SatoriEventBody): void {
-    if (!this.#open) return;
+  #admitRaw(body: SatoriEventBody): void {
     if (body.login && !this.#login) this.#login = body.login;
     if (!isMessageEvent(body)) return;
     const conversation = satoriInboundConversation(String(this.#options.id), body);
@@ -403,7 +429,7 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
     const sender = resolveInboundSender(body);
     const selfId = this.#login?.user?.id ?? body.login?.user?.id;
     const mentioned = isSelfMentioned(body, selfId);
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: body.message.id },
       content,
@@ -425,17 +451,20 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
     });
   }
 
-  async recall(id: string): Promise<void> {
+  async recall(id: string, fallbackChannelId?: string): Promise<void> {
     const { channelId, messageId } = parseMessageRef(id);
-    await this.#api('message', 'delete', {
-      channel_id: channelId,
+    await this.client.call('message', 'delete', {
+      channel_id: channelId || fallbackChannelId || '',
       message_id: messageId,
     });
   }
 
-  /** Test helper: inject login without a live webhook push. */
-  setLogin(login: SatoriLogin): void {
-    this.#login = login;
+  #warnPlatformEvent(name: string, error: unknown): void {
+    this.#logger.warn(formatCompact({
+      op: 'satori_platform_event_failed',
+      event: name,
+      error: error instanceof Error ? error.message : String(error),
+    }));
   }
 
   #apiOptions(): SatoriApiOptions {
@@ -447,14 +476,6 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
     };
   }
 
-  #api(
-    resource: string,
-    method: string,
-    params: Record<string, unknown>,
-  ): Promise<unknown> {
-    const call = this.#options.callApi ?? callSatoriApi;
-    return call(this.#apiOptions(), resource, method, params);
-  }
 }
 
 function isPrivateChannelType(body: SatoriEventBody): boolean {

package/src/index.ts

@@ -35,7 +35,6 @@ export {
 
 export {
   handleSatoriWebhookRequest,
-  readRequestBody,
   registerSatoriWebhookRoutes,
   resolveSatoriOpcode,
   verifySatoriToken,
@@ -46,3 +45,20 @@ export {
   WS_OPEN,
   defaultCreateWebSocket,
 } from './ws.js';
+
+export {
+  SatoriClient,
+  satoriClient,
+  type SatoriClientEventMap,
+} from './client.js';
+
+export type {
+  SatoriAdapterConfig as ImHelperSatoriAdapterConfig,
+  SatoriActionUrlResolver,
+  SatoriCall,
+  SatoriV1ClientConfig,
+  SatoriV1Event,
+  SatoriV1Response,
+} from '@imhelper/satori-v1';
+export { ProtocolError } from '@imhelper/satori-v1';
+export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';

package/src/protocol.ts

@@ -222,7 +222,7 @@ export async function callSatoriApi<T = unknown>(
   }
 }
 
-/** Build inbound text for MessageGateway.receive. */
+/** Build inbound text for OutboundMessageService.receive. */
 export function formatInboundContent(body: SatoriEventBody & { message: SatoriMessage }): string {
   const content = body.message.content ?? '';
   return typeof content === 'string' ? content : String(content);

package/src/webhook.ts

@@ -8,8 +8,6 @@ import { getLogger } from '@zhin.js/logger';
 import {
   SatoriOpcode,
   type ResolvedSatoriWebhookConfig,
-  type SatoriEventBody,
-  type SatoriLogin,
 } from './protocol.js';
 
 const logger = getLogger('satori');
@@ -17,8 +15,7 @@ const logger = getLogger('satori');
 export interface SatoriWebhookHandler {
   readonly config: ResolvedSatoriWebhookConfig;
   readonly isOpen: boolean;
-  admit(body: SatoriEventBody): void;
-  setLogin(login: SatoriLogin): void;
+  acceptHttp(request: IncomingMessage, response: ServerResponse): Promise<void>;
 }
 
 export function registerSatoriWebhookRoutes(
@@ -50,22 +47,12 @@ export async function handleSatoriWebhookRequest(
       response.end(JSON.stringify({ message: 'OK' }));
       return;
     }
-    const raw = await readRequestBody(request);
-    let body: SatoriEventBody;
-    try {
-      body = JSON.parse(raw) as SatoriEventBody;
-    } catch {
-      response.writeHead(400, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ message: 'Invalid JSON' }));
-      return;
-    }
-    if (opcode === SatoriOpcode.EVENT && handler.isOpen) {
-      handler.admit(body);
-    } else if (opcode === SatoriOpcode.META && body.login && handler.isOpen) {
-      handler.setLogin(body.login);
+    if (handler.isOpen) {
+      await handler.acceptHttp(request, response);
+    } else {
+      response.writeHead(200, { 'Content-Type': 'application/json' });
+      response.end(JSON.stringify({ status: 'ok' }));
     }
-    response.writeHead(200, { 'Content-Type': 'application/json' });
-    response.end(JSON.stringify({ message: 'OK' }));
   } catch (error) {
     logger.error('Satori webhook error:', error);
     if (!response.headersSent) {
@@ -90,18 +77,3 @@ export function verifySatoriToken(token: string | undefined, request: IncomingMe
   const actual = Buffer.from(auth, 'utf8');
   return actual.length === expected.length && timingSafeEqual(actual, expected);
 }
-
-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');
-}