@zhin.js/adapter-satori 1.1.26 → 1.1.28

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;