@zhin.js/adapter-satori 1.1.26 → 1.1.27

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @zhin.js/adapter-satori
 
+## 1.1.27
+
+### Patch Changes
+
+- 11306b0: 对齐 Satori 出站元素和被动回复的 `referrer`。
+
+  **破坏性变更：** `at` / `mention` 不再编成 `@name`，图片、音频、视频和文件不再编成 `[image:src]` 这类纯文本，改为标准元素 `<at>`、`<img>`、`<audio>`、`<video>`、`<file>`，并支持 `<emoji>`。入站 `content` 仍是协议原文，这些元素会另外解成段。
+
+  收到带 `referrer` 的事件时，同一次处理里的 `message.create` 会原样带回该对象；之后的主动发送不带。`guild-emoji-added` / `guild-emoji-updated` / `guild-emoji-deleted` 映射为 `notice.group.emoji_added` / `emoji_updated` / `emoji_deleted`。
+
+  `@imhelper/satori-v1` 还没有这些类型（上游 `feat/satori-1.3-alignment` 未发布）。适配器使用本地类型，上游发版后可以换成官方类型。
+
+- 54b034f: 对齐 Satori 的 Friend、reaction 和群成员角色。
+
+  **破坏性变更：** `listGroupMembers` 返回的 `roles` 改为 `GuildRole[]`（`{ id, name? }`）。旧 SDK 若仍下发 `string[]`，适配器会收成 `{ id }`。
+
+  新增 `friend.list` / `friend.delete` / `friend.approve`（管理端口的 `listFriends`、`deleteFriend`、`approveRequest`、`rejectRequest`）。`friend-request` 进入 `request.receive`，名称是 `request.friend.add`。表态改为 `reaction.create` / `reaction.delete`，参数名是 `emoji_id`。
+
+  `@imhelper/satori-v1` 1.0.10 仍把好友列表当成 User，reaction 参数仍叫 `emoji`。这些类型是本地声明。上游 `feat/satori-1.3-alignment` 发版后可以换成官方类型。
+
+- 79395bb: 群成员列表改为请求 `POST /v1/guild.member.list`。原先资源名写成 `guild-member`，实际打到 `/v1/guild-member.list`，与 Satori 文档不一致。
+
 ## 1.1.26
 
 ### Patch Changes

package/README.md

@@ -29,7 +29,7 @@ pnpm add @zhin.js/adapter-satori
 
 入站：`endpoint[endpointSpec].events.emit('message.receive', { conversation, message, content, sender, metadata })`（`conversation` 为 ConversationRef：DIRECT 频道 → kind `private`，其余 → kind `group`、所属 guild 进 `parent`）
 
-出站：`send({ conversation, payload })` → Satori `message.create`（`channel_id = conversation.id`；payload 已由 gateway/core 渲染；无 segment-mapper）
+出站：`send({ conversation, payload })` → Satori `message.create`（`channel_id = conversation.id`）。同一次入站处理结束前的被动回复会原样带回 `referrer`。段里的 mention 编成 `<at>`，媒体编成 `<img>` / `<audio>` / `<video>` / `<file>`，`emoji` 和规范 `face` 编成 `<emoji>`。
 
 入站 `metadata.mentioned`：消息 content 中 `<at id="…"/>` 元素的 id 等于登录 selfId（配置的 `userId`）时置 `true`。
 

package/adapters/satori/index.js

@@ -17,9 +17,14 @@ export default defineAdapter({
                     interactive: 'text',
                 },
                 recall: {},
+                reaction: {},
             },
             actions: {
                 recall: { scopes: ['private', 'group', 'channel'] },
+                reaction: {
+                    scopes: ['private', 'group', 'channel'],
+                    params: { cancellable: true },
+                },
             },
             delivery: { send: true, spool: true },
         },

package/adapters/satori/index.ts

@@ -27,9 +27,14 @@ export default defineAdapter<SatoriEndpointConfig>({
           interactive: 'text',
         },
         recall: {},
+        reaction: {},
       },
       actions: {
         recall: { scopes: ['private', 'group', 'channel'] },
+        reaction: {
+          scopes: ['private', 'group', 'channel'],
+          params: { cancellable: true },
+        },
       },
       delivery: { send: true, spool: true },
     },

package/lib/endpoint.d.ts

@@ -41,7 +41,8 @@ export declare class SatoriWebhookEndpoint extends SatoriClient implements Endpo
 export type SatoriManagementApi = SatoriActionCaller;
 /**
  * Satori endpoint 的 EndpointManagement 语义端口（ws / webhook 共用），
- * 数据走协议 API：guild.list / channel.list / guild-member.list。
+ * 数据走协议 API：guild.list / channel.list / guild.member.list。
+ * @see https://satori.chat/zh-CN/resources/member.html
  */
 export declare function createSatoriEndpointManagement(api: SatoriManagementApi): EndpointManagement;
 export type { CreateSatoriWebSocket, SatoriWsSocket } from './ws.js';

package/lib/endpoint.js

@@ -5,7 +5,7 @@ import { acceptHttpIngress } from 'imhelper';
  */
 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 { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatMessageId, formatSatoriOutbound, inboundSatoriSegments, isMessageEvent, mapSatoriFriendRequest, readSatoriFriend, satoriFriendApproveParams, satoriReactionParams, withSatoriGuildRoles, isSelfMentioned, mapGuildEmojiNotice, parseMessageRef, resolveInboundSender, satoriInboundConversation, satoriMessageCreateParams, withSatoriReferrer, } from './protocol.js';
 import { registerSatoriWebhookRoutes } from './webhook.js';
 import { satoriClientOptions, createSatoriActionCaller, forwardSatoriClientEvents, SatoriClient } from './client.js';
 import { WS_OPEN, defaultCreateWebSocket, } from './ws.js';
@@ -21,6 +21,8 @@ export class SatoriWsEndpoint extends SatoriClient {
     #call;
     #control = Object.freeze({
         recall: request => this.#recall(request),
+        addReaction: request => this.#addReaction(request),
+        removeReaction: request => this.#removeReaction(request),
     });
     constructor(options) {
         const call = createSatoriActionCaller({ config: options.config, request: options.callApi ?? callSatoriApi, signal: options.signal });
@@ -90,10 +92,7 @@ export class SatoriWsEndpoint extends SatoriClient {
     }
     async #send({ conversation, payload, signal }) {
         const content = formatSatoriOutbound(payload);
-        const result = await this.#call({ resource: 'message', method: 'create', signal, params: {
-                channel_id: conversation.id,
-                content,
-            } });
+        const result = await this.#call({ resource: 'message', method: 'create', signal, params: satoriMessageCreateParams(conversation.id, content) });
         const msgId = extractCreatedMessageId(result);
         this.#logger.debug(formatCompact({
             op: 'satori_send',
@@ -106,35 +105,36 @@ export class SatoriWsEndpoint extends SatoriClient {
     #admitRaw(body) {
         if (!matchesSatoriLogin(this.#options.config, body.login))
             return;
-        if (!isMessageEvent(body))
+        if (emitSatoriFriendRequest(body, {
+            endpointId: this.#options.config.id,
+            call: this.#call,
+            emit: request => {
+                void this[endpointSpec].events.emit('request.receive', request).catch(error => {
+                    this.#warnPlatformEvent('request.receive', error);
+                });
+            },
+        }))
             return;
-        const conversation = { ...satoriInboundConversation(String(this.#options.id), body), endpoint: this[endpointSpec].identity };
-        const content = formatInboundContent(body);
-        const sender = resolveInboundSender(body);
-        const selfId = this.#options.config.userId;
-        const mentioned = isSelfMentioned(body, selfId);
-        void this[endpointSpec].events.message({
-            event: body,
-            ...(typeof body.timestamp === 'number' ? { platformSentAt: body.timestamp } : {}),
-            conversation,
-            message: { conversation, id: body.message.id },
-            content,
-            sender,
+        const deliver = () => deliverSatoriInbound(body, {
             endpointId: this.#options.config.id,
-            ...(mentioned ? { mentioned: true } : {}),
-            metadata: Object.freeze({
-                type: body.type,
-                channelType: isPrivateChannelType(body) ? 'private' : 'group',
-                sn: body.sn,
-                platform: this.#options.config.platform,
-            }),
-        }).catch((err) => {
-            this.#logger.warn(formatCompact({
-                op: 'satori_gateway_receive_failed',
-                channel: conversation.id,
-                error: err instanceof Error ? err.message : String(err),
-            }));
+            endpointKey: String(this.#options.id),
+            identity: this[endpointSpec].identity,
+            selfId: this.#options.config.userId,
+            platform: this.#options.config.platform,
+            events: this[endpointSpec].events,
+            warnReceive: (channel, error) => {
+                this.#logger.warn(formatCompact({
+                    op: 'satori_gateway_receive_failed',
+                    channel,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            },
+            warnEvent: (event, error) => this.#warnPlatformEvent(event, error),
         });
+        if (body.referrer !== undefined)
+            withSatoriReferrer(body.referrer, deliver);
+        else
+            deliver();
     }
     async #recall({ message, signal }) {
         const { channelId, messageId } = parseMessageRef(message.id);
@@ -143,6 +143,12 @@ export class SatoriWsEndpoint extends SatoriClient {
                 message_id: messageId,
             } });
     }
+    #addReaction(request) {
+        return addSatoriReaction(this.#call, request);
+    }
+    #removeReaction(request) {
+        return removeSatoriReaction(this.#call, request);
+    }
     #warnPlatformEvent(name, error) {
         this.#logger.warn(formatCompact({
             op: 'satori_platform_event_failed',
@@ -294,6 +300,8 @@ export class SatoriWebhookEndpoint extends SatoriClient {
     #call;
     #control = Object.freeze({
         recall: request => this.#recall(request),
+        addReaction: request => this.#addReaction(request),
+        removeReaction: request => this.#removeReaction(request),
     });
     constructor(options) {
         const call = createSatoriActionCaller({ config: options.config, request: options.callApi ?? callSatoriApi, signal: options.signal });
@@ -363,10 +371,7 @@ export class SatoriWebhookEndpoint extends SatoriClient {
     }
     async #send({ conversation, payload, signal }) {
         const content = formatSatoriOutbound(payload);
-        const result = await this.#call({ resource: 'message', method: 'create', signal, params: {
-                channel_id: conversation.id,
-                content,
-            } });
+        const result = await this.#call({ resource: 'message', method: 'create', signal, params: satoriMessageCreateParams(conversation.id, content) });
         const msgId = extractCreatedMessageId(result);
         this.#logger.debug(formatCompact({
             op: 'satori_send',
@@ -379,35 +384,36 @@ export class SatoriWebhookEndpoint extends SatoriClient {
     #admitRaw(body) {
         if (!matchesSatoriLogin(this.#options.config, body.login))
             return;
-        if (!isMessageEvent(body))
+        if (emitSatoriFriendRequest(body, {
+            endpointId: this.#options.config.id,
+            call: this.#call,
+            emit: request => {
+                void this[endpointSpec].events.emit('request.receive', request).catch(error => {
+                    this.#warnPlatformEvent('request.receive', error);
+                });
+            },
+        }))
             return;
-        const conversation = { ...satoriInboundConversation(String(this.#options.id), body), endpoint: this[endpointSpec].identity };
-        const content = formatInboundContent(body);
-        const sender = resolveInboundSender(body);
-        const selfId = this.#options.config.userId;
-        const mentioned = isSelfMentioned(body, selfId);
-        void this[endpointSpec].events.message({
-            event: body,
-            ...(typeof body.timestamp === 'number' ? { platformSentAt: body.timestamp } : {}),
-            conversation,
-            message: { conversation, id: body.message.id },
-            content,
-            sender,
+        const deliver = () => deliverSatoriInbound(body, {
             endpointId: this.#options.config.id,
-            ...(mentioned ? { mentioned: true } : {}),
-            metadata: Object.freeze({
-                type: body.type,
-                channelType: isPrivateChannelType(body) ? 'private' : 'group',
-                sn: body.sn,
-                platform: this.#options.config.platform,
-            }),
-        }).catch((err) => {
-            this.#logger.warn(formatCompact({
-                op: 'satori_gateway_receive_failed',
-                channel: conversation.id,
-                error: err instanceof Error ? err.message : String(err),
-            }));
+            endpointKey: String(this.#options.id),
+            identity: this[endpointSpec].identity,
+            selfId: this.#options.config.userId,
+            platform: this.#options.config.platform,
+            events: this[endpointSpec].events,
+            warnReceive: (channel, error) => {
+                this.#logger.warn(formatCompact({
+                    op: 'satori_gateway_receive_failed',
+                    channel,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            },
+            warnEvent: (event, error) => this.#warnPlatformEvent(event, error),
         });
+        if (body.referrer !== undefined)
+            withSatoriReferrer(body.referrer, deliver);
+        else
+            deliver();
     }
     async #recall({ message, signal }) {
         const { channelId, messageId } = parseMessageRef(message.id);
@@ -416,6 +422,12 @@ export class SatoriWebhookEndpoint extends SatoriClient {
                 message_id: messageId,
             } });
     }
+    #addReaction(request) {
+        return addSatoriReaction(this.#call, request);
+    }
+    #removeReaction(request) {
+        return removeSatoriReaction(this.#call, request);
+    }
     #warnPlatformEvent(name, error) {
         this.#logger.warn(formatCompact({
             op: 'satori_platform_event_failed',
@@ -430,6 +442,38 @@ export class SatoriWebhookEndpoint extends SatoriClient {
         this.ingest(body);
     }
 }
+function deliverSatoriInbound(body, input) {
+    const notice = mapGuildEmojiNotice(body, input.endpointId);
+    if (notice) {
+        return input.events.emit('notice.receive', notice).catch(error => input.warnEvent('notice.receive', error));
+    }
+    if (!isMessageEvent(body))
+        return Promise.resolve();
+    const conversation = { ...satoriInboundConversation(input.endpointKey, body), endpoint: input.identity };
+    const content = formatInboundContent(body);
+    const segments = typeof body.message.content === 'string'
+        ? inboundSatoriSegments(body.message.content)
+        : undefined;
+    const sender = resolveInboundSender(body);
+    const mentioned = isSelfMentioned(body, input.selfId);
+    return input.events.message({
+        event: body,
+        ...(typeof body.timestamp === 'number' ? { platformSentAt: body.timestamp } : {}),
+        conversation,
+        message: { conversation, id: body.message.id },
+        content,
+        ...(segments ? { segments } : {}),
+        sender,
+        endpointId: input.endpointId,
+        ...(mentioned ? { mentioned: true } : {}),
+        metadata: Object.freeze({
+            type: body.type,
+            channelType: isPrivateChannelType(body) ? 'private' : 'group',
+            sn: body.sn,
+            platform: input.platform,
+        }),
+    }).catch(error => input.warnReceive(conversation.id, error));
+}
 function isPrivateChannelType(body) {
     const channel = body.channel ?? body.message?.channel;
     return channel?.type === 1;
@@ -458,7 +502,8 @@ function asRecord(value) {
 }
 /**
  * Satori endpoint 的 EndpointManagement 语义端口（ws / webhook 共用），
- * 数据走协议 API：guild.list / channel.list / guild-member.list。
+ * 数据走协议 API：guild.list / channel.list / guild.member.list。
+ * @see https://satori.chat/zh-CN/resources/member.html
  */
 export function createSatoriEndpointManagement(api) {
     return Object.freeze({
@@ -500,9 +545,91 @@ export function createSatoriEndpointManagement(api) {
             return channels;
         },
         async listGroupMembers({ groupId, signal }) {
-            // 平台形状（GuildMember[]）原样返回
-            return listSatoriPages(api, { resource: 'guild-member', params: { guild_id: groupId }, signal });
+            // 平台形状（GuildMember[]）原样返回，再规范化 1.3 的 GuildRole 角色
+            const members = await listSatoriPages(api, { resource: 'guild.member', params: { guild_id: groupId }, signal });
+            return members.map(member => withSatoriGuildRoles(member));
+        },
+        async listFriends(request = {}) {
+            const friends = [];
+            for (const value of await listSatoriPages(api, { resource: 'friend', signal: request.signal })) {
+                const friend = readSatoriFriend(value);
+                if (!friend?.user?.id)
+                    continue;
+                const nick = friend.nick ?? '';
+                const name = friend.user.name ?? '';
+                friends.push({
+                    user_id: friend.user.id,
+                    nickname: name || nick || friend.user.id,
+                    remark: nick,
+                });
+            }
+            return friends;
+        },
+        async deleteFriend({ userId, signal }) {
+            await api({ resource: 'friend', method: 'delete', params: { user_id: userId }, signal });
         },
+        async approveRequest({ requestId, remark, signal }) {
+            await api({
+                resource: 'friend',
+                method: 'approve',
+                signal,
+                params: satoriFriendApproveParams(requestId, true, remark),
+            });
+        },
+        async rejectRequest({ requestId, reason, signal }) {
+            await api({
+                resource: 'friend',
+                method: 'approve',
+                signal,
+                params: satoriFriendApproveParams(requestId, false, reason),
+            });
+        },
+    });
+}
+function emitSatoriFriendRequest(body, input) {
+    if (body.type !== 'friend-request')
+        return false;
+    const request = mapSatoriFriendRequest(body, input.endpointId, {
+        approve: (messageId, comment) => input.call({
+            resource: 'friend',
+            method: 'approve',
+            params: satoriFriendApproveParams(messageId, true, comment),
+        }).then(() => undefined),
+        reject: (messageId, reason) => input.call({
+            resource: 'friend',
+            method: 'approve',
+            params: satoriFriendApproveParams(messageId, false, reason),
+        }).then(() => undefined),
+    });
+    if (request)
+        input.emit(request);
+    return true;
+}
+async function addSatoriReaction(call, request) {
+    const { channelId, messageId } = parseMessageRef(request.message.id);
+    await call({
+        resource: 'reaction',
+        method: 'create',
+        signal: request.signal,
+        params: satoriReactionParams('create', {
+            channelId: channelId || request.message.conversation.id,
+            messageId,
+            emojiId: request.emoji,
+        }),
+    });
+    return request.emoji;
+}
+async function removeSatoriReaction(call, request) {
+    const { channelId, messageId } = parseMessageRef(request.message.id);
+    await call({
+        resource: 'reaction',
+        method: 'delete',
+        signal: request.signal,
+        params: satoriReactionParams('delete', {
+            channelId: channelId || request.message.conversation.id,
+            messageId,
+            emojiId: request.reactionId,
+        }),
     });
 }
 /** A transport connection may multiplex logins; this Endpoint admits only its selected account. */

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-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 { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, decodeSatoriContent, formatInboundContent, formatSatoriOutbound, inboundSatoriSegments, isMessageEvent, mapSatoriFriendRequest, normalizeSatoriGuildRoles, readSatoriFriend, satoriFriendApproveParams, satoriReactionParams, mapGuildEmojiNotice, satoriMessageCreateParams, withSatoriReferrer, isPrivateChannel, resolveInboundSender, resolveSatoriConfig, satoriInboundConversation, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig, type SatoriEndpointConfig, type SatoriApiOptions, type SatoriApiRequest, type SatoriChannel, type SatoriEmoji, type SatoriEventBody, type SatoriFriend, type SatoriFriendRequestActions, type SatoriGuildMember, type SatoriGuildRole, type SatoriReactionMethod, 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';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatSatoriOutbound, isMessageEvent, isPrivateChannel, resolveInboundSender, resolveSatoriConfig, satoriInboundConversation, } from './protocol.js';
+export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, decodeSatoriContent, formatInboundContent, formatSatoriOutbound, inboundSatoriSegments, isMessageEvent, mapSatoriFriendRequest, normalizeSatoriGuildRoles, readSatoriFriend, satoriFriendApproveParams, satoriReactionParams, mapGuildEmojiNotice, satoriMessageCreateParams, withSatoriReferrer, 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';

package/lib/protocol.d.ts

@@ -1,6 +1,6 @@
 import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
-/** Satori protocol helpers. Spec: https://satori.chat/zh-CN/protocol/overview.html */
-import { type ConversationRef } from '@zhin.js/im-contract';
+import { type IncomingNotice, type IncomingRequest } from '@zhin.js/core';
+import { type ConversationRef, type Segment } 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;
@@ -19,6 +19,48 @@ export interface SatoriUser {
     readonly name?: string;
     readonly avatar?: string;
 }
+/**
+ * Satori Emoji。字段对齐文档 https://satori.chat/zh-CN/resources/emoji.html （`id`、`name?`）。
+ * `@imhelper/satori-v1` 1.0.7 / 1.0.10 没有这个类型。上游 `feat/satori-1.3-alignment`
+ * 会补上，但这次不发布 npm，适配器先用本地声明。上游发版后可以换成 SDK 导出的官方类型。
+ */
+export interface SatoriEmoji {
+    readonly id: string;
+    readonly name?: string;
+}
+/**
+ * 群组角色。文档只声明 `id` 和 `name?`。
+ * 协议源码里还有 color、position 等字段，这里以文档为准，不建模它们。
+ * `@imhelper/satori-v1` 没有这个类型。上游 `feat/satori-1.3-alignment` 会补，但未发 npm。
+ * 上游发版后可以换成官方类型。
+ * @see https://satori.chat/zh-CN/resources/role.html
+ */
+export interface SatoriGuildRole {
+    readonly id: string;
+    readonly name?: string;
+}
+/**
+ * 好友。文档形状是 `{ user?, nick? }`，不是带顶层 `id` / `name` / `avatar` 的 User。
+ * 1.0.10 的 `directory-api.getFriendList` 仍按 User 读取 `friend.id`。本地按文档解析。
+ * 上游发版后可以换成官方类型。
+ * @see https://satori.chat/zh-CN/resources/friend.html
+ */
+export interface SatoriFriend {
+    readonly user?: SatoriUser;
+    readonly nick?: string;
+}
+/**
+ * 群组成员。`roles` 在 1.3 起是 `GuildRole[]`，不再是 `string[]`。
+ * 本地类型。上游发版后可以换成官方类型。
+ * @see https://satori.chat/zh-CN/resources/member.html
+ */
+export interface SatoriGuildMember {
+    readonly user?: SatoriUser;
+    readonly nick?: string;
+    readonly avatar?: string;
+    readonly joined_at?: number;
+    readonly roles?: readonly SatoriGuildRole[];
+}
 export interface SatoriChannel {
     readonly id: string;
     /** 0=TEXT, 1=DIRECT, 2=CATEGORY, 3=VOICE */
@@ -56,11 +98,26 @@ export interface SatoriEventBody {
         readonly id: string;
         readonly name?: string;
     };
-    readonly member?: {
-        readonly user?: SatoriUser;
-        readonly nick?: string;
-        readonly roles?: string[];
-    };
+    readonly member?: SatoriGuildMember;
+    /**
+     * 事件里的好友。本地字段，原因见 {@link SatoriFriend}。
+     * @see https://satori.chat/zh-CN/protocol/events.html
+     */
+    readonly friend?: SatoriFriend;
+    readonly operator?: SatoriUser;
+    /**
+     * 事件表情。本地字段，原因见 {@link SatoriEmoji}。
+     * @see https://satori.chat/zh-CN/protocol/events.html
+     */
+    readonly emoji?: SatoriEmoji;
+    /**
+     * 被动请求的来源上下文。协议不约束内部结构，发送时必须原样回传。
+     * 资源页 `message.create` 表格目前没列出该字段，但被动请求页要求传入，
+     * 协议方法表也包含 `referrer`。这里以被动请求页为准。
+     * 本地字段：`SatoriV1Event` 尚未声明它。上游发版后可以换成官方类型。
+     * @see https://satori.chat/zh-CN/advanced/passive.html
+     */
+    readonly referrer?: unknown;
     readonly [key: string]: unknown;
 }
 export interface SatoriApiOptions {
@@ -73,6 +130,7 @@ export interface SatoriApiOptions {
 export interface SatoriWireSegment {
     readonly type: string;
     readonly data?: Record<string, unknown>;
+    readonly platform?: Record<string, unknown>;
 }
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface SatoriEndpointConfig extends EndpointProfileConfiguration {
@@ -129,6 +187,19 @@ export declare function callSatoriApi<T = unknown>({ resource, method, params, .
 export declare function formatInboundContent(body: SatoriEventBody & {
     message: SatoriMessage;
 }): string;
+export declare function decodeSatoriContent(content: string, depth?: number): Segment[];
+/** 仅在出现非文本元素时把解码结果送进消息管道，纯文本保持原来的 content-only 形状。 */
+export declare function inboundSatoriSegments(content: string): readonly Segment[] | undefined;
+/**
+ * `guild-emoji-*` → `notice.group.emoji_*`。
+ * 文档只要求资源 `emoji`，没有可回复频道，因此不填 conversation。
+ * 上游 SDK 目前只把这些事件原样 emit("event")，映射放在适配器内。
+ * @see https://satori.chat/zh-CN/resources/emoji.html
+ */
+export declare function mapGuildEmojiNotice(body: SatoriEventBody, endpointId: string): IncomingNotice | undefined;
+export declare function withSatoriReferrer<T>(referrer: unknown, run: () => T): T;
+/** `message.create` 参数。处理尚未结束时原样附带 referrer，不挑字段、不改名。 */
+export declare function satoriMessageCreateParams(channelId: string, content: string): Record<string, unknown>;
 /**
  * 入站归一化 → ConversationRef：Channel.type 1 (DIRECT) → kind 'private'；
  * 其余频道消息 → kind 'group'，所属 guild 容器进 `parent`（kind 'channel'）。
@@ -155,8 +226,49 @@ export declare function parseMessageRef(id: string): {
     messageId: string;
 };
 /**
- * Wire-encode an already-rendered outbound payload into Satori message content.
- * Segment canonicalization is intentionally not done here.
+ * 把已渲染的出站载荷编成 Satori 消息字符串。
+ * at / mention → `<at>`，image → `<img>`，其余媒体用同名标准元素，emoji → `<emoji>`。
+ * 整段字符串原样发送（调用方可能已经写好标记）；段数组里的文本会转义。
+ * 上游 message-codec 把段编成 `{type, attrs}` 对象，而且不会把 mention/image 改成 at/img。
+ * 这里在适配器内按文档元素编码。上游发版后如果 SDK 直接产出这些元素，可以改走 SDK。
+ * @see https://satori.chat/zh-CN/protocol/elements.html
  */
 export declare function formatSatoriOutbound(payload: unknown): string;
 export declare function extractCreatedMessageId(result: unknown): string;
+/**
+ * 把 `guild-member.list` 的 `roles` 收成 `GuildRole[]`。
+ * 旧 SDK 可能仍下发 `string[]`，这里收成 `{ id }`。上游发版并保证对象数组后，字符串分支可以去掉。
+ */
+export declare function normalizeSatoriGuildRoles(value: unknown): readonly SatoriGuildRole[] | undefined;
+/** 成员列表原样保留其余字段，只把 roles 收成 GuildRole[]。 */
+export declare function withSatoriGuildRoles<T>(member: T): T;
+/**
+ * 按 `{ user, nick }` 读取好友。顶层 `id` / `name` 是 1.0.10 误用的 User 形状，这里不认。
+ */
+export declare function readSatoriFriend(value: unknown): SatoriFriend | undefined;
+export type SatoriReactionMethod = 'create' | 'delete' | 'clear' | 'list';
+/**
+ * reaction.* 的参数名是 `emoji_id`，不是 1.0.10 `addMessageReactionIn` 用的 `emoji`。
+ * clear 不传 emoji_id 表示清除全部表态。
+ * @see https://satori.chat/zh-CN/resources/reaction.html
+ */
+export declare function satoriReactionParams(method: SatoriReactionMethod, input: {
+    readonly channelId: string;
+    readonly messageId: string;
+    readonly emojiId?: string;
+    readonly userId?: string;
+    readonly next?: string;
+}): Record<string, unknown>;
+/** `friend.approve` 同时表达通过和拒绝。 */
+export declare function satoriFriendApproveParams(messageId: string, approve: boolean, comment?: string): Record<string, unknown>;
+export interface SatoriFriendRequestActions {
+    approve(messageId: string, comment?: string): Promise<void>;
+    reject(messageId: string, reason?: string): Promise<void>;
+}
+/**
+ * `friend-request` → `request.friend.add`，让它进入 request.receive 管道。
+ * 文档的必需资源是 `user`。`friend.approve` 的请求 ID 是 `message_id`；
+ * 事件没有 `message.id` 时仍然投递，但批准/拒绝会说明缺少该字段。
+ * @see https://satori.chat/zh-CN/resources/friend.html
+ */
+export declare function mapSatoriFriendRequest(body: SatoriEventBody, endpointId: string, actions: SatoriFriendRequestActions): IncomingRequest | undefined;