@zhin.js/adapter-satori 1.1.18 → 1.1.19

package/lib/endpoint.js

@@ -1,34 +1,49 @@
+import { acceptHttpIngress } from 'imhelper';
 /**
  * SatoriEndpoint — WebSocket and webhook lifecycle, outbound, admit.
  */
-import { ClientEndpoint, createEndpointLifecycle, } from 'zhin.js/adapter';
+import { createEndpointSpecification, endpointSpec, 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 { satoriClientOptions, createSatoriActionCaller, forwardSatoriClientEvents, SatoriClient } from './client.js';
 import { WS_OPEN, defaultCreateWebSocket, } from './ws.js';
-export class SatoriWsEndpoint extends ClientEndpoint {
-    client;
+export class SatoriWsEndpoint extends SatoriClient {
+    [endpointSpec];
+    #open = false;
     #logger;
     #options;
     #lifecycle;
     #ws = null;
-    #login;
     #lastSn;
-    management;
-    control = Object.freeze({
-        recall: (message) => this.recall(message.id, message.conversation.id),
+    #management;
+    #call;
+    #control = Object.freeze({
+        recall: request => this.#recall(request),
     });
     constructor(options) {
-        super();
+        const call = createSatoriActionCaller({ config: options.config, request: options.callApi ?? callSatoriApi, signal: options.signal });
+        super(satoriClientOptions({ config: options.config, call }));
+        this.#call = call;
         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));
+        this.#management = createSatoriEndpointManagement(call);
+        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,
+        });
+        forwardSatoriClientEvents(this, (name, payload) => {
+            void this[endpointSpec].events.run(() => {
+                if (!this.#open && !this.#lifecycle.started)
+                    return;
+                void this[endpointSpec].events.platform(name, payload).catch(error => this.#warnPlatformEvent(name, error));
+                if (name === 'event')
+                    this.#admitRaw(payload);
+            }).catch(error => this.#warnPlatformEvent(name, error));
+        });
         const { config } = options;
         this.#lifecycle = createEndpointLifecycle({
             name: config.id,
@@ -46,7 +61,7 @@ export class SatoriWsEndpoint extends ClientEndpoint {
             },
         });
     }
-    async start() {
+    async #start() {
         try {
             await this.#lifecycle.start((handle) => this.#connect(handle));
         }
@@ -64,18 +79,18 @@ export class SatoriWsEndpoint extends ClientEndpoint {
             throw err;
         }
     }
-    async stop() {
-        this.close();
+    async #stop() {
+        this.#open = false;
         // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
         await this.#lifecycle.stop();
         this.#ws = null;
     }
-    async send({ conversation, payload }) {
+    async #send({ conversation, payload, signal }) {
         const content = formatSatoriOutbound(payload);
-        const result = await this.client.call('message', 'create', {
-            channel_id: conversation.id,
-            content,
-        });
+        const result = await this.#call({ resource: 'message', method: 'create', signal, params: {
+                channel_id: conversation.id,
+                content,
+            } });
         const msgId = extractCreatedMessageId(result);
         this.#logger.debug(formatCompact({
             op: 'satori_send',
@@ -86,16 +101,18 @@ export class SatoriWsEndpoint extends ClientEndpoint {
         return msgId ? formatMessageId(conversation.id, msgId) : '';
     }
     #admitRaw(body) {
-        if (body.login && !this.#login)
-            this.#login = body.login;
+        if (!matchesSatoriLogin(this.#options.config, body.login))
+            return;
         if (!isMessageEvent(body))
             return;
-        const conversation = satoriInboundConversation(String(this.#options.id), body);
+        const conversation = { ...satoriInboundConversation(String(this.#options.id), body), endpoint: this[endpointSpec].identity };
         const content = formatInboundContent(body);
         const sender = resolveInboundSender(body);
-        const selfId = this.#login?.user?.id ?? body.login?.user?.id;
+        const selfId = this.#options.config.userId;
         const mentioned = isSelfMentioned(body, selfId);
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.message({
+            event: body,
+            ...(typeof body.timestamp === 'number' ? { platformSentAt: body.timestamp } : {}),
             conversation,
             message: { conversation, id: body.message.id },
             content,
@@ -106,7 +123,7 @@ export class SatoriWsEndpoint extends ClientEndpoint {
                 type: body.type,
                 channelType: isPrivateChannelType(body) ? 'private' : 'group',
                 sn: body.sn,
-                platform: this.#login?.platform,
+                platform: this.#options.config.platform,
             }),
         }).catch((err) => {
             this.#logger.warn(formatCompact({
@@ -116,12 +133,12 @@ export class SatoriWsEndpoint extends ClientEndpoint {
             }));
         });
     }
-    async recall(id, fallbackChannelId) {
-        const { channelId, messageId } = parseMessageRef(id);
-        await this.client.call('message', 'delete', {
-            channel_id: channelId || fallbackChannelId || '',
-            message_id: messageId,
-        });
+    async #recall({ message, signal }) {
+        const { channelId, messageId } = parseMessageRef(message.id);
+        await this.#call({ resource: 'message', method: 'delete', signal, params: {
+                channel_id: channelId || message.conversation.id,
+                message_id: messageId,
+            } });
     }
     #warnPlatformEvent(name, error) {
         this.#logger.warn(formatCompact({
@@ -149,6 +166,8 @@ export class SatoriWsEndpoint extends ClientEndpoint {
                 }
             });
             ws.on('open', () => {
+                if (this.#ws !== ws || !this.#lifecycle.started)
+                    return;
                 this.#logger.debug(formatCompact({ mode: 'ws' }));
                 this.#sendSignal(SatoriOpcode.IDENTIFY, {
                     token: config.token,
@@ -161,6 +180,8 @@ export class SatoriWsEndpoint extends ClientEndpoint {
                 }
             });
             ws.on('message', (data) => {
+                if (this.#ws !== ws || !this.#lifecycle.started)
+                    return;
                 try {
                     const raw = typeof data === 'string'
                         ? data
@@ -211,7 +232,7 @@ export class SatoriWsEndpoint extends ClientEndpoint {
         if (signal.op === SatoriOpcode.PONG) {
             // 喂狗：复位基座看门狗计数
             this.#lifecycle.notifyHeartbeatAck();
-            void this.emitPlatform('pong', signal).catch((error) => {
+            void this[endpointSpec].events.platform('pong', signal).catch((error) => {
                 this.#logger.warn(formatCompact({
                     op: 'satori_platform_event_failed',
                     event: 'pong',
@@ -222,23 +243,28 @@ export class SatoriWsEndpoint extends ClientEndpoint {
         }
         if (signal.op === SatoriOpcode.READY && signal.body?.logins) {
             const logins = signal.body.logins;
-            this.#login = logins[0];
-            void this.emitPlatform('ready', signal).catch((error) => {
+            const login = logins.find(candidate => matchesSatoriLogin(this.#options.config, candidate));
+            if (login?.user?.id)
+                this[endpointSpec].reportSelfUserId(login.user.id);
+            void this[endpointSpec].events.platform('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) {
+            if (!login) {
                 this.#logger.warn(formatCompact({ op: 'ready', ok: false, error: 'missing platform/user' }));
             }
             return;
         }
         if (signal.op === SatoriOpcode.EVENT && signal.body) {
-            if (typeof signal.body.sn === 'number')
-                this.#lastSn = signal.body.sn;
-            this.client.ingest(signal.body);
+            const body = signal.body;
+            void this[endpointSpec].events.run(() => {
+                if (typeof body.sn === 'number')
+                    this.#lastSn = body.sn;
+                this.#receive(body);
+            }).catch(error => this.#warnPlatformEvent('event', error));
         }
     }
     #sendSignal(op, body) {
@@ -246,48 +272,50 @@ export class SatoriWsEndpoint extends ClientEndpoint {
             return;
         this.#ws.send(JSON.stringify({ op, body: body ?? {} }));
     }
-    #apiOptions() {
-        return {
-            baseUrl: this.#options.config.baseUrl,
-            platform: this.#login?.platform ?? '',
-            userId: this.#login?.user?.id ?? '',
-            token: this.#options.config.token,
-        };
+    #receive(body) {
+        if (!matchesSatoriLogin(this.#options.config, body.login))
+            return;
+        this[endpointSpec].reportSelfUserId(this.#options.config.userId);
+        this.ingest(body);
     }
 }
-export class SatoriWebhookEndpoint extends ClientEndpoint {
-    client;
+export class SatoriWebhookEndpoint extends SatoriClient {
+    [endpointSpec];
+    #open = false;
     #logger;
     #options;
-    #login;
     #routeReleases = [];
     #started = false;
-    management;
-    control = Object.freeze({
-        recall: (message) => this.recall(message.id, message.conversation.id),
+    #management;
+    #call;
+    #control = Object.freeze({
+        recall: request => this.#recall(request),
     });
     constructor(options) {
-        super();
+        const call = createSatoriActionCaller({ config: options.config, request: options.callApi ?? callSatoriApi, signal: options.signal });
+        super(satoriClientOptions({ config: options.config, call }));
+        this.#call = call;
         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.clientEventsOpen;
-    }
-    get config() {
-        return this.#options.config;
-    }
-    async acceptHttp(request, response) {
-        await this.client.acceptHttp(request, response);
+        this.#management = createSatoriEndpointManagement(call);
+        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,
+        });
+        forwardSatoriClientEvents(this, (name, payload) => {
+            void this[endpointSpec].events.run(() => {
+                if (!this.#started)
+                    return;
+                void this[endpointSpec].events.platform(name, payload).catch(error => this.#warnPlatformEvent(name, error));
+                if (name === 'event')
+                    this.#admitRaw(payload);
+            }).catch(error => this.#warnPlatformEvent(name, error));
+        });
     }
-    async start() {
+    async #start() {
         if (this.#started)
             return;
         this.#started = true;
@@ -300,7 +328,17 @@ export class SatoriWebhookEndpoint extends ClientEndpoint {
                 hint: 'set token to authenticate Satori webhook callbacks',
             }));
         }
-        this.#routeReleases.push(...registerSatoriWebhookRoutes(this.#options.http, this));
+        const isOpen = () => this.#open;
+        this.#routeReleases.push(...registerSatoriWebhookRoutes(this.#options.http, {
+            config: this.#options.config,
+            get isOpen() { return isOpen(); },
+            acceptHttp: async (request, response) => {
+                await acceptHttpIngress(request, response, body => {
+                    void this[endpointSpec].events.run(() => this.#receive(body))
+                        .catch(error => this.#warnPlatformEvent('event', error));
+                });
+            },
+        }));
         this.#logger.info(formatCompact({
             op: 'listen',
             endpoint: this.#options.config.id,
@@ -308,8 +346,8 @@ export class SatoriWebhookEndpoint 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;
@@ -317,12 +355,12 @@ export class SatoriWebhookEndpoint extends ClientEndpoint {
             op: 'disconnect',
         }));
     }
-    async send({ conversation, payload }) {
+    async #send({ conversation, payload, signal }) {
         const content = formatSatoriOutbound(payload);
-        const result = await this.client.call('message', 'create', {
-            channel_id: conversation.id,
-            content,
-        });
+        const result = await this.#call({ resource: 'message', method: 'create', signal, params: {
+                channel_id: conversation.id,
+                content,
+            } });
         const msgId = extractCreatedMessageId(result);
         this.#logger.debug(formatCompact({
             op: 'satori_send',
@@ -333,16 +371,18 @@ export class SatoriWebhookEndpoint extends ClientEndpoint {
         return msgId ? formatMessageId(conversation.id, msgId) : '';
     }
     #admitRaw(body) {
-        if (body.login && !this.#login)
-            this.#login = body.login;
+        if (!matchesSatoriLogin(this.#options.config, body.login))
+            return;
         if (!isMessageEvent(body))
             return;
-        const conversation = satoriInboundConversation(String(this.#options.id), body);
+        const conversation = { ...satoriInboundConversation(String(this.#options.id), body), endpoint: this[endpointSpec].identity };
         const content = formatInboundContent(body);
         const sender = resolveInboundSender(body);
-        const selfId = this.#login?.user?.id ?? body.login?.user?.id;
+        const selfId = this.#options.config.userId;
         const mentioned = isSelfMentioned(body, selfId);
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.message({
+            event: body,
+            ...(typeof body.timestamp === 'number' ? { platformSentAt: body.timestamp } : {}),
             conversation,
             message: { conversation, id: body.message.id },
             content,
@@ -353,7 +393,7 @@ export class SatoriWebhookEndpoint extends ClientEndpoint {
                 type: body.type,
                 channelType: isPrivateChannelType(body) ? 'private' : 'group',
                 sn: body.sn,
-                platform: this.#login?.platform,
+                platform: this.#options.config.platform,
             }),
         }).catch((err) => {
             this.#logger.warn(formatCompact({
@@ -363,12 +403,12 @@ export class SatoriWebhookEndpoint extends ClientEndpoint {
             }));
         });
     }
-    async recall(id, fallbackChannelId) {
-        const { channelId, messageId } = parseMessageRef(id);
-        await this.client.call('message', 'delete', {
-            channel_id: channelId || fallbackChannelId || '',
-            message_id: messageId,
-        });
+    async #recall({ message, signal }) {
+        const { channelId, messageId } = parseMessageRef(message.id);
+        await this.#call({ resource: 'message', method: 'delete', signal, params: {
+                channel_id: channelId || message.conversation.id,
+                message_id: messageId,
+            } });
     }
     #warnPlatformEvent(name, error) {
         this.#logger.warn(formatCompact({
@@ -377,34 +417,23 @@ export class SatoriWebhookEndpoint extends ClientEndpoint {
             error: error instanceof Error ? error.message : String(error),
         }));
     }
-    #apiOptions() {
-        return {
-            baseUrl: this.#options.config.baseUrl,
-            platform: this.#login?.platform ?? '',
-            userId: this.#login?.user?.id ?? '',
-            token: this.#options.config.token,
-        };
+    #receive(body) {
+        if (!matchesSatoriLogin(this.#options.config, body.login))
+            return;
+        this[endpointSpec].reportSelfUserId(this.#options.config.userId);
+        this.ingest(body);
     }
 }
 function isPrivateChannelType(body) {
     const channel = body.channel ?? body.message?.channel;
     return channel?.type === 1;
 }
-/**
- * Satori guild id 是平台相关字符串（多数平台为雪花号，超
- * Number.MAX_SAFE_INTEGER）。Console 社交面只把 group_id 当 JSON 值透传、
- * 并以字符串回传给 listGroupMembers，因此保留原始字符串（仅按契约类型
- * 声明强转）是全链路最不丢信息的方案。
- */
-function toGroupId(id) {
-    return id;
-}
 /** Satori 分页列表（{data, next?}）聚合；兼容直接返回数组的实现。 */
-async function listSatoriPages(api, resource, params) {
+async function listSatoriPages(api, { resource, params = {}, signal }) {
     const items = [];
     let next;
     do {
-        const page = await api(resource, 'list', next ? { ...params, next } : params);
+        const page = await api({ resource, method: 'list', params: next ? { ...params, next } : params, signal });
         if (Array.isArray(page)) {
             items.push(...page);
             break;
@@ -427,28 +456,28 @@ function asRecord(value) {
  */
 export function createSatoriEndpointManagement(api) {
     return Object.freeze({
-        async listGroups() {
+        async listGroups(request = {}) {
             const groups = [];
-            for (const value of await listSatoriPages(api, 'guild', {})) {
+            for (const value of await listSatoriPages(api, { resource: 'guild', signal: request.signal })) {
                 const guild = asRecord(value);
                 if (guild.id == null)
                     continue;
                 groups.push({
-                    group_id: toGroupId(String(guild.id)),
+                    group_id: String(guild.id),
                     name: String(guild.name ?? guild.id),
                 });
             }
             return groups;
         },
-        async listChannels() {
+        async listChannels(request = {}) {
             const channels = [];
-            for (const value of await listSatoriPages(api, 'guild', {})) {
+            for (const value of await listSatoriPages(api, { resource: 'guild', signal: request.signal })) {
                 const guild = asRecord(value);
                 if (guild.id == null)
                     continue;
                 const guildId = String(guild.id);
                 const guildName = String(guild.name ?? guildId);
-                for (const channelValue of await listSatoriPages(api, 'channel', { guild_id: guildId })) {
+                for (const channelValue of await listSatoriPages(api, { resource: 'channel', params: { guild_id: guildId }, signal: request.signal })) {
                     const channel = asRecord(channelValue);
                     if (channel.id == null)
                         continue;
@@ -464,9 +493,13 @@ export function createSatoriEndpointManagement(api) {
             }
             return channels;
         },
-        async listGroupMembers(groupId) {
+        async listGroupMembers({ groupId, signal }) {
             // 平台形状（GuildMember[]）原样返回
-            return listSatoriPages(api, 'guild-member', { guild_id: groupId });
+            return listSatoriPages(api, { resource: 'guild-member', params: { guild_id: groupId }, signal });
         },
     });
 }
+/** A transport connection may multiplex logins; this Endpoint admits only its selected account. */
+function matchesSatoriLogin(config, login) {
+    return login?.platform === config.platform && login.user?.id === config.userId;
+}

package/lib/index.d.ts

@@ -1,8 +1,9 @@
-export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatSatoriOutbound, isMessageEvent, isPrivateChannel, resolveInboundSender, resolveSatoriConfig, satoriInboundConversation, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig, type SatoriEndpointConfig, type SatoriApiOptions, type SatoriChannel, type SatoriEventBody, type SatoriLogin, type SatoriMessage, type SatoriSignal, type SatoriUser, type SatoriWireSegment, } from './protocol.js';
+export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatSatoriOutbound, isMessageEvent, isPrivateChannel, resolveInboundSender, resolveSatoriConfig, satoriInboundConversation, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig, type SatoriEndpointConfig, type SatoriApiOptions, type SatoriApiRequest, 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, registerSatoriWebhookRoutes, resolveSatoriOpcode, verifySatoriToken, type SatoriWebhookHandler, } from './webhook.js';
 export { WS_OPEN, defaultCreateWebSocket, } from './ws.js';
-export { SatoriClient, satoriClient, type SatoriClientEventMap, } from './client.js';
+export { 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';
+export { SatoriAdapter } from './adapter.js';

package/lib/index.js

@@ -2,5 +2,6 @@ export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, forma
 export { SatoriWebhookEndpoint, SatoriWsEndpoint, } from './endpoint.js';
 export { handleSatoriWebhookRequest, registerSatoriWebhookRoutes, resolveSatoriOpcode, verifySatoriToken, } from './webhook.js';
 export { WS_OPEN, defaultCreateWebSocket, } from './ws.js';
-export { SatoriClient, satoriClient, } from './client.js';
+export { SatoriClient, } from './client.js';
 export { ProtocolError } from '@imhelper/satori-v1';
+export { SatoriAdapter } from './adapter.js';

package/lib/protocol.d.ts

@@ -67,6 +67,7 @@ export interface SatoriApiOptions {
     readonly platform: string;
     readonly userId: string;
     readonly token?: string;
+    readonly signal?: AbortSignal;
 }
 export interface SatoriWireSegment {
     readonly type: string;
@@ -75,6 +76,9 @@ export interface SatoriWireSegment {
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface SatoriEndpointConfig {
     readonly id: string;
+    /** Exact remote login selected by this configured Endpoint. */
+    readonly platform: string;
+    readonly userId: string;
     readonly connection?: 'ws' | 'webhook';
     readonly baseUrl: string;
     readonly token?: string;
@@ -86,6 +90,8 @@ export interface ResolvedSatoriWsConfig {
     readonly context: 'satori';
     readonly connection: 'ws';
     readonly id: string;
+    readonly platform: string;
+    readonly userId: string;
     readonly baseUrl: string;
     readonly token?: string;
     readonly heartbeat_interval: number;
@@ -94,6 +100,8 @@ export interface ResolvedSatoriWebhookConfig {
     readonly context: 'satori';
     readonly connection: 'webhook';
     readonly id: string;
+    readonly platform: string;
+    readonly userId: string;
     readonly baseUrl: string;
     readonly token?: string;
     readonly path: string;
@@ -110,7 +118,12 @@ export declare function buildWsUrl(baseUrl: string, token?: string): string;
  * Call Satori HTTP API: POST {baseUrl}/v1/{resource}.{method}
  * @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>;
+export interface SatoriApiRequest extends SatoriApiOptions {
+    readonly resource: string;
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+export declare function callSatoriApi<T = unknown>({ resource, method, params, ...options }: SatoriApiRequest): Promise<T>;
 /** Build inbound text for OutboundMessageService.receive. */
 export declare function formatInboundContent(body: SatoriEventBody & {
     message: SatoriMessage;

package/lib/protocol.js

@@ -1,5 +1,5 @@
 /** Satori protocol helpers. Spec: https://satori.chat/zh-CN/protocol/overview.html */
-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('satori');
 /** Opcode：EVENT=0, PING=1, PONG=2, IDENTIFY=3, READY=4, META=5 */
@@ -14,6 +14,8 @@ export const SatoriOpcode = {
 export function resolveSatoriConfig(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 baseUrl = requiredEndpointField(config.baseUrl, 'baseUrl');
     const token = typeof config.token === 'string' && config.token.trim()
         ? config.token.trim()
@@ -24,6 +26,8 @@ export function resolveSatoriConfig(config) {
             context: 'satori',
             connection: 'webhook',
             id,
+            platform,
+            userId,
             baseUrl,
             token,
             path,
@@ -34,6 +38,8 @@ export function resolveSatoriConfig(config) {
         context: 'satori',
         connection: 'ws',
         id,
+        platform,
+        userId,
         baseUrl,
         token,
         heartbeat_interval: heartbeat,
@@ -59,11 +65,7 @@ export function buildWsUrl(baseUrl, token) {
         url.searchParams.set('access_token', token);
     return url.toString();
 }
-/**
- * Call Satori HTTP API: POST {baseUrl}/v1/{resource}.{method}
- * @see https://satori.chat/en-US/protocol/api.html
- */
-export async function callSatoriApi(options, resource, method, params = {}) {
+export async function callSatoriApi({ resource, method, params = {}, ...options }) {
     const { baseUrl, platform, userId, token } = options;
     const url = `${baseUrl.replace(/\/$/, '')}/v1/${resource}.${method}`;
     const headers = {
@@ -73,11 +75,16 @@ export async function callSatoriApi(options, resource, method, params = {}) {
     };
     if (token)
         headers.Authorization = `Bearer ${token}`;
-    const res = await fetch(url, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(params),
-    });
+    if (options.signal?.aborted)
+        throw new EndpointDeliveryError('endpoint_inactive', 'Satori request ended before submission', 'not_sent', { cause: options.signal.reason });
+    const body = JSON.stringify(params);
+    let res;
+    try {
+        res = await fetch(url, { method: 'POST', headers, body, signal: options.signal });
+    }
+    catch (cause) {
+        throw new EndpointDeliveryError('delivery_unconfirmed', 'Satori HTTP request outcome is unknown', 'unknown', { cause });
+    }
     const text = await res.text();
     if (res.status === 401)
         throw new Error(`Satori API 认证失败: ${text}`);