@zhin.js/adapter-satori 1.0.1 → 1.1.0

package/lib/endpoint.js

@@ -0,0 +1,472 @@
+/**
+ * SatoriEndpoint — WebSocket and webhook lifecycle, outbound, admit.
+ */
+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 extends ClientEndpoint {
+    client;
+    #logger;
+    #options;
+    #lifecycle;
+    #ws = null;
+    #login;
+    #lastSn;
+    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,
+            reconnect: {
+                initialIntervalMs: 5_000,
+                // 固定间隔（multiplier 1、无抖动），对齐旧 5s 固定重连语义
+                multiplier: 1,
+                maxIntervalMs: 5_000,
+                jitterMs: 0,
+            },
+            heartbeat: {
+                intervalMs: config.heartbeat_interval,
+                // PONG 看门狗：连续 2 轮无回包，下一轮心跳由基座强关连接触发重连
+                watchdogMisses: 2,
+            },
+        });
+    }
+    async start() {
+        try {
+            await this.#lifecycle.start((handle) => this.#connect(handle));
+        }
+        catch (err) {
+            // start 失败清理现场（状态复位由基座保证）
+            if (this.#ws) {
+                try {
+                    this.#ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                this.#ws = null;
+            }
+            throw err;
+        }
+    }
+    async stop() {
+        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.client.call('message', 'create', {
+            channel_id: conversation.id,
+            content,
+        });
+        const msgId = extractCreatedMessageId(result);
+        this.#logger.debug(formatCompact({
+            op: 'satori_send',
+            endpoint: this.#options.config.id,
+            channel: conversation.id,
+            messageId: msgId || undefined,
+        }));
+        return msgId ? formatMessageId(conversation.id, msgId) : '';
+    }
+    #admitRaw(body) {
+        if (body.login && !this.#login)
+            this.#login = body.login;
+        if (!isMessageEvent(body))
+            return;
+        const conversation = satoriInboundConversation(String(this.#options.id), body);
+        const content = formatInboundContent(body);
+        const sender = resolveInboundSender(body);
+        const selfId = this.#login?.user?.id ?? body.login?.user?.id;
+        const mentioned = isSelfMentioned(body, selfId);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: body.message.id },
+            content,
+            sender,
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                type: body.type,
+                channelType: isPrivateChannelType(body) ? 'private' : 'group',
+                sn: body.sn,
+                platform: this.#login?.platform,
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'satori_gateway_receive_failed',
+                channel: conversation.id,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async recall(id, fallbackChannelId) {
+        const { channelId, messageId } = parseMessageRef(id);
+        await this.client.call('message', 'delete', {
+            channel_id: channelId || fallbackChannelId || '',
+            message_id: messageId,
+        });
+    }
+    #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;
+        const createWs = this.#options.createWebSocket ?? defaultCreateWebSocket;
+        const headers = {};
+        if (config.token)
+            headers.Authorization = `Bearer ${config.token}`;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const ws = createWs(buildWsUrl(config.baseUrl, config.token), { headers });
+            this.#ws = ws;
+            handle.onForceClose(() => {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* already closed */
+                }
+            });
+            ws.on('open', () => {
+                this.#logger.debug(formatCompact({ mode: 'ws' }));
+                this.#sendSignal(SatoriOpcode.IDENTIFY, {
+                    token: config.token,
+                    sn: this.#lastSn,
+                });
+                this.#lifecycle.startHeartbeat(() => this.#sendSignal(SatoriOpcode.PING));
+                if (!settled) {
+                    settled = true;
+                    resolve();
+                }
+            });
+            ws.on('message', (data) => {
+                try {
+                    const raw = typeof data === 'string'
+                        ? data
+                        : Buffer.isBuffer(data)
+                            ? data.toString('utf8')
+                            : String(data ?? '');
+                    const signal = JSON.parse(raw);
+                    this.#handleSignal(signal);
+                }
+                catch (error) {
+                    this.#logger.warn(formatCompact({
+                        op: 'ws_parse_error',
+                        endpoint: config.id,
+                        error: error instanceof Error ? error.message : String(error),
+                    }));
+                }
+            });
+            ws.on('close', (code, reason) => {
+                const reasonStr = typeof reason === 'string'
+                    ? reason
+                    : Buffer.isBuffer(reason)
+                        ? reason.toString('utf8')
+                        : String(reason ?? '');
+                const numericCode = typeof code === 'number' ? code : 0;
+                if (!settled) {
+                    settled = true;
+                    reject(new Error(`Satori WS closed: ${numericCode} ${reasonStr}`));
+                }
+                // 断开日志与重连武装均由基座负责；仅曾 open 的连接才会武装重连，
+                // 初始连接失败由 start() 的拒绝路径复位。
+                handle.notifyClosed(`Satori WS closed: ${numericCode} ${reasonStr || 'closed'}`);
+            });
+            ws.on('error', (error) => {
+                this.#logger.warn(formatCompact({
+                    op: 'ws_error',
+                    endpoint: config.id,
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+                if (!settled) {
+                    settled = true;
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        });
+    }
+    #handleSignal(signal) {
+        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' }));
+            }
+            return;
+        }
+        if (signal.op === SatoriOpcode.EVENT && signal.body) {
+            if (typeof signal.body.sn === 'number')
+                this.#lastSn = signal.body.sn;
+            this.client.ingest(signal.body);
+        }
+    }
+    #sendSignal(op, body) {
+        if (!this.#ws || this.#ws.readyState !== WS_OPEN)
+            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,
+        };
+    }
+}
+export class SatoriWebhookEndpoint extends ClientEndpoint {
+    client;
+    #logger;
+    #options;
+    #login;
+    #routeReleases = [];
+    #started = false;
+    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.clientEventsOpen;
+    }
+    get config() {
+        return this.#options.config;
+    }
+    async acceptHttp(request, response) {
+        await this.client.acceptHttp(request, response);
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        if (!this.#options.config.token) {
+            // 未配 token 时 webhook 无鉴权：任何人知道 path 即可注入假事件。
+            this.#logger.warn(formatCompact({
+                op: 'webhook_no_token',
+                endpoint: this.#options.config.id,
+                path: this.#options.config.path,
+                hint: 'set token to authenticate Satori webhook callbacks',
+            }));
+        }
+        this.#routeReleases.push(...registerSatoriWebhookRoutes(this.#options.http, this));
+        this.#logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.id,
+            mode: 'webhook',
+            path: this.#options.config.path,
+        }));
+    }
+    async stop() {
+        this.close();
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#started = false;
+        this.#logger.debug(formatCompact({
+            op: 'disconnect',
+        }));
+    }
+    async send({ conversation, payload }) {
+        const content = formatSatoriOutbound(payload);
+        const result = await this.client.call('message', 'create', {
+            channel_id: conversation.id,
+            content,
+        });
+        const msgId = extractCreatedMessageId(result);
+        this.#logger.debug(formatCompact({
+            op: 'satori_send',
+            endpoint: this.#options.config.id,
+            channel: conversation.id,
+            messageId: msgId || undefined,
+        }));
+        return msgId ? formatMessageId(conversation.id, msgId) : '';
+    }
+    #admitRaw(body) {
+        if (body.login && !this.#login)
+            this.#login = body.login;
+        if (!isMessageEvent(body))
+            return;
+        const conversation = satoriInboundConversation(String(this.#options.id), body);
+        const content = formatInboundContent(body);
+        const sender = resolveInboundSender(body);
+        const selfId = this.#login?.user?.id ?? body.login?.user?.id;
+        const mentioned = isSelfMentioned(body, selfId);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: body.message.id },
+            content,
+            sender,
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                type: body.type,
+                channelType: isPrivateChannelType(body) ? 'private' : 'group',
+                sn: body.sn,
+                platform: this.#login?.platform,
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'satori_gateway_receive_failed',
+                channel: conversation.id,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async recall(id, fallbackChannelId) {
+        const { channelId, messageId } = parseMessageRef(id);
+        await this.client.call('message', 'delete', {
+            channel_id: channelId || fallbackChannelId || '',
+            message_id: messageId,
+        });
+    }
+    #warnPlatformEvent(name, error) {
+        this.#logger.warn(formatCompact({
+            op: 'satori_platform_event_failed',
+            event: name,
+            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,
+        };
+    }
+}
+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) {
+    const items = [];
+    let next;
+    do {
+        const page = await api(resource, 'list', next ? { ...params, next } : params);
+        if (Array.isArray(page)) {
+            items.push(...page);
+            break;
+        }
+        const typed = (page ?? {});
+        if (Array.isArray(typed.data))
+            items.push(...typed.data);
+        next = typeof typed.next === 'string' && typed.next ? typed.next : undefined;
+    } while (next);
+    return items;
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}
+/**
+ * Satori endpoint 的 EndpointManagement 语义端口（ws / webhook 共用），
+ * 数据走协议 API：guild.list / channel.list / guild-member.list。
+ */
+export function createSatoriEndpointManagement(api) {
+    return Object.freeze({
+        async listGroups() {
+            const groups = [];
+            for (const value of await listSatoriPages(api, 'guild', {})) {
+                const guild = asRecord(value);
+                if (guild.id == null)
+                    continue;
+                groups.push({
+                    group_id: toGroupId(String(guild.id)),
+                    name: String(guild.name ?? guild.id),
+                });
+            }
+            return groups;
+        },
+        async listChannels() {
+            const channels = [];
+            for (const value of await listSatoriPages(api, 'guild', {})) {
+                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 })) {
+                    const channel = asRecord(channelValue);
+                    if (channel.id == null)
+                        continue;
+                    // Channel.type: 0=TEXT 1=DIRECT 2=CATEGORY 3=VOICE；缺省按 TEXT 处理
+                    if (channel.type != null && Number(channel.type) !== 0)
+                        continue;
+                    channels.push({
+                        id: String(channel.id),
+                        name: channel.name != null ? String(channel.name) : undefined,
+                        parent: { type: 'guild', id: guildId, name: guildName },
+                    });
+                }
+            }
+            return channels;
+        },
+        async listGroupMembers(groupId) {
+            // 平台形状（GuildMember[]）原样返回
+            return listSatoriPages(api, 'guild-member', { guild_id: groupId });
+        },
+    });
+}

package/lib/index.d.ts

@@ -1,18 +1,8 @@
-import { SatoriAdapter } from './adapter.js';
-export * from './types.js';
-export { callSatoriApi } from './api.js';
-export * from './utils.js';
-export { SatoriWsClient } from './endpoint-ws.js';
-export { SatoriWebhookEndpoint } from './endpoint-webhook.js';
-export { SatoriAdapter, type SatoriBot } from './adapter.js';
-declare module 'zhin.js' {
-    namespace Plugin {
-        interface Contexts {
-            router: import('@zhin.js/host-router').Router;
-        }
-    }
-    interface Adapters {
-        satori: SatoriAdapter;
-    }
-}
-//# sourceMappingURL=index.d.ts.map
+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, 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,25 +1,6 @@
-/**
- * Satori 适配器入口：单一适配器，支持 WS / Webhook，协议文档 https://satori.chat/zh-CN/introduction.html
- */
-import { usePlugin } from 'zhin.js';
-import { SatoriAdapter } from './adapter.js';
-export * from './types.js';
-export { callSatoriApi } from './api.js';
-export * from './utils.js';
-export { SatoriWsClient } from './endpoint-ws.js';
-export { SatoriWebhookEndpoint } from './endpoint-webhook.js';
-export { SatoriAdapter } from './adapter.js';
-const { provide } = usePlugin();
-provide({
-    name: 'satori',
-    description: 'Satori 协议适配器（WS 正向 / Webhook）',
-    mounted: async (p) => {
-        const adapter = new SatoriAdapter(p);
-        await adapter.start();
-        return adapter;
-    },
-    dispose: async (adapter) => {
-        await adapter.stop();
-    },
-});
-//# sourceMappingURL=index.js.map
+export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatSatoriOutbound, isMessageEvent, isPrivateChannel, resolveInboundSender, resolveSatoriConfig, satoriInboundConversation, } from './protocol.js';
+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 { ProtocolError } from '@imhelper/satori-v1';

package/lib/protocol.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Satori protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ * Spec: https://satori.chat/zh-CN/protocol/overview.html
+ */
+import type { ConversationRef } from '@zhin.js/im-contract';
+/** Opcode：EVENT=0, PING=1, PONG=2, IDENTIFY=3, READY=4, META=5 */
+export declare const SatoriOpcode: {
+    readonly EVENT: 0;
+    readonly PING: 1;
+    readonly PONG: 2;
+    readonly IDENTIFY: 3;
+    readonly READY: 4;
+    readonly META: 5;
+};
+export interface SatoriSignal {
+    readonly op: number;
+    readonly body?: Record<string, unknown>;
+}
+export interface SatoriUser {
+    readonly id: string;
+    readonly name?: string;
+    readonly avatar?: string;
+}
+export interface SatoriChannel {
+    readonly id: string;
+    /** 0=TEXT, 1=DIRECT, 2=CATEGORY, 3=VOICE */
+    readonly type?: number;
+    readonly name?: string;
+    readonly parent_id?: string;
+}
+export interface SatoriMessage {
+    readonly id: string;
+    readonly content?: string;
+    readonly channel?: SatoriChannel;
+    readonly user?: SatoriUser;
+    readonly member?: {
+        readonly user?: SatoriUser;
+        readonly nick?: string;
+    };
+    readonly created_at?: number;
+    readonly updated_at?: number;
+}
+export interface SatoriLogin {
+    readonly platform?: string;
+    readonly user?: SatoriUser;
+    readonly status?: number;
+    readonly sn?: number;
+}
+export interface SatoriEventBody {
+    readonly type?: string;
+    readonly sn?: number;
+    readonly timestamp?: number;
+    readonly login?: SatoriLogin;
+    readonly message?: SatoriMessage;
+    readonly channel?: SatoriChannel;
+    readonly user?: SatoriUser;
+    readonly guild?: {
+        readonly id: string;
+        readonly name?: string;
+    };
+    readonly member?: {
+        readonly user?: SatoriUser;
+        readonly nick?: string;
+        readonly roles?: string[];
+    };
+    readonly [key: string]: unknown;
+}
+export interface SatoriApiOptions {
+    readonly baseUrl: string;
+    readonly platform: string;
+    readonly userId: string;
+    readonly token?: string;
+}
+export interface SatoriWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface SatoriAdapterConfig {
+    readonly id?: string;
+    readonly connection?: 'ws' | 'webhook';
+    readonly baseUrl?: string;
+    readonly token?: string;
+    readonly heartbeat_interval?: number;
+    /** Webhook POST path (connection: webhook). */
+    readonly path?: string;
+    /** Transitional: legacy root `endpoints[]` with `context: satori`. */
+    readonly endpoints?: ReadonlyArray<Partial<ResolvedSatoriWsConfig> & {
+        readonly context?: string;
+        readonly connection?: 'ws' | 'webhook';
+        readonly path?: string;
+    }>;
+}
+export interface ResolvedSatoriWsConfig {
+    readonly context: 'satori';
+    readonly connection: 'ws';
+    readonly id: string;
+    readonly baseUrl: string;
+    readonly token?: string;
+    readonly heartbeat_interval: number;
+}
+export interface ResolvedSatoriWebhookConfig {
+    readonly context: 'satori';
+    readonly connection: 'webhook';
+    readonly id: string;
+    readonly baseUrl: string;
+    readonly token?: string;
+    readonly path: string;
+}
+export type ResolvedSatoriConfig = ResolvedSatoriWsConfig | ResolvedSatoriWebhookConfig;
+export declare function resolveSatoriConfig(config?: SatoriAdapterConfig): ResolvedSatoriConfig;
+/** Channel.type 1 = DIRECT (private). */
+export declare function isPrivateChannel(channel?: SatoriChannel): boolean;
+export declare function isMessageEvent(body: SatoriEventBody): body is SatoriEventBody & {
+    message: SatoriMessage;
+};
+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>;
+/** Build inbound text for OutboundMessageService.receive. */
+export declare function formatInboundContent(body: SatoriEventBody & {
+    message: SatoriMessage;
+}): string;
+/**
+ * 入站归一化 → ConversationRef：Channel.type 1 (DIRECT) → kind 'private'；
+ * 其余频道消息 → kind 'group'，所属 guild 容器进 `parent`（kind 'channel'）。
+ */
+export declare function satoriInboundConversation(endpointKey: string, body: SatoriEventBody & {
+    message: SatoriMessage;
+}): ConversationRef;
+export declare function resolveInboundSender(body: SatoriEventBody & {
+    message: SatoriMessage;
+}): {
+    id: string;
+    name?: string;
+};
+/**
+ * Detect `<at id="…"/>` elements in message content targeting the bot selfId.
+ * selfId 来源：READY/事件携带的 `login.user.id`。
+ */
+export declare function isSelfMentioned(body: SatoriEventBody & {
+    message: SatoriMessage;
+}, selfId?: string): boolean;
+export declare function formatMessageId(channelId: string, messageId: string): string;
+export declare function parseMessageRef(id: string): {
+    channelId: string;
+    messageId: string;
+};
+/**
+ * Wire-encode an already-rendered outbound payload into Satori message content.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare function formatSatoriOutbound(payload: unknown): string;
+export declare function extractCreatedMessageId(result: unknown): string;