@zhin.js/adapter-satori 1.1.26 → 1.1.28

package/lib/protocol.js

@@ -1,4 +1,6 @@
 /** Satori protocol helpers. Spec: https://satori.chat/zh-CN/protocol/overview.html */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { buildNotice, buildRequest, composeSideEventName, senderFromId, sideEventConversation } from '@zhin.js/core';
 import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('satori');
@@ -108,6 +110,115 @@ export function formatInboundContent(body) {
     const content = body.message.content ?? '';
     return typeof content === 'string' ? content : String(content);
 }
+/**
+ * 入站元素解码。`content` 仍保留协议原文，结构化元素另外放进 segments。
+ * 只识别标准元素 at / img / emoji / audio / video / file。
+ * @see https://satori.chat/zh-CN/protocol/elements.html
+ */
+const MAX_SATORI_ELEMENT_DEPTH = 8;
+export function decodeSatoriContent(content, depth = 0) {
+    if (depth >= MAX_SATORI_ELEMENT_DEPTH) {
+        return [{ type: 'text', data: { text: unescapeXml(content) } }];
+    }
+    const segments = [];
+    let text = '';
+    const flush = () => {
+        if (!text)
+            return;
+        segments.push({ type: 'text', data: { text: unescapeXml(text) } });
+        text = '';
+    };
+    for (let index = 0; index < content.length;) {
+        if (content[index] !== '<') {
+            text += content[index];
+            index += 1;
+            continue;
+        }
+        const scanned = readSatoriElement(content, index);
+        if (scanned.kind === 'incomplete') {
+            text += content.slice(index);
+            break;
+        }
+        if (scanned.kind === 'literal' || !DECODABLE_SATORI_TAGS.has(scanned.element.name)) {
+            text += content[index];
+            index += 1;
+            continue;
+        }
+        const parsed = scanned.element;
+        flush();
+        segments.push(segmentFromSatoriElement(parsed.name, parsed.attrs));
+        if (parsed.inner)
+            segments.push(...decodeSatoriContent(parsed.inner, depth + 1));
+        index = parsed.end;
+    }
+    flush();
+    return segments;
+}
+/** 仅在出现非文本元素时把解码结果送进消息管道，纯文本保持原来的 content-only 形状。 */
+export function inboundSatoriSegments(content) {
+    const segments = decodeSatoriContent(content);
+    return segments.some(segment => segment.type !== 'text') ? segments : undefined;
+}
+const GUILD_EMOJI_NOTICE = {
+    'guild-emoji-added': 'emoji_added',
+    'guild-emoji-updated': 'emoji_updated',
+    'guild-emoji-deleted': 'emoji_deleted',
+};
+/**
+ * `guild-emoji-*` → `notice.group.emoji_*`。
+ * 文档只要求资源 `emoji`，没有可回复频道，因此不填 conversation。
+ * 上游 SDK 目前只把这些事件原样 emit("event")，映射放在适配器内。
+ * @see https://satori.chat/zh-CN/resources/emoji.html
+ */
+export function mapGuildEmojiNotice(body, endpointId) {
+    const subType = body.type ? GUILD_EMOJI_NOTICE[body.type] : undefined;
+    if (!subType)
+        return undefined;
+    const emoji = normalizeSatoriEmoji(body.emoji);
+    if (!emoji)
+        return undefined;
+    const label = noticeLabel(emoji.name ?? emoji.id);
+    return buildNotice(body, {
+        id: ['satori', body.type, body.guild?.id ?? '', emoji.id, String(body.sn ?? body.timestamp ?? 0)].join(':'),
+        clientAdapter: 'satori',
+        endpointId,
+        type: 'notice',
+        name: composeSideEventName('notice', 'group', subType),
+        ...(body.operator?.id ? { actor: senderFromId(body.operator.id, body.operator.name) } : {}),
+        timestamp: typeof body.timestamp === 'number' ? body.timestamp : Date.now(),
+        ...(label ? { value: label } : {}),
+    });
+}
+const satoriReferrer = new AsyncLocalStorage();
+export function withSatoriReferrer(referrer, run) {
+    const frame = { value: referrer, open: true };
+    const close = () => { frame.open = false; };
+    return satoriReferrer.run(frame, () => {
+        try {
+            const result = run();
+            if (isPromiseLike(result))
+                return result.finally(close);
+            close();
+            return result;
+        }
+        catch (error) {
+            close();
+            throw error;
+        }
+    });
+}
+function isPromiseLike(value) {
+    return typeof value === 'object' && value !== null && typeof value.then === 'function';
+}
+/** `message.create` 参数。处理尚未结束时原样附带 referrer，不挑字段、不改名。 */
+export function satoriMessageCreateParams(channelId, content) {
+    const frame = satoriReferrer.getStore();
+    return {
+        channel_id: channelId,
+        content,
+        ...(frame?.open ? { referrer: frame.value } : {}),
+    };
+}
 /**
  * 入站归一化 → ConversationRef：Channel.type 1 (DIRECT) → kind 'private'；
  * 其余频道消息 → kind 'group'，所属 guild 容器进 `parent`（kind 'channel'）。
@@ -182,8 +293,12 @@ function resolveMediaSrc(type, data) {
     return undefined;
 }
 /**
- * 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 function formatSatoriOutbound(payload) {
     if (typeof payload === 'string')
@@ -201,17 +316,22 @@ export function formatSatoriOutbound(payload) {
     const parts = [];
     for (const item of segments) {
         if (typeof item === 'string') {
-            parts.push(item);
+            parts.push(escapeXmlText(item));
             continue;
         }
         const data = item.data ?? {};
+        const platform = item.platform;
         switch (item.type) {
             case 'text':
-                parts.push(String(data.text ?? data.content ?? ''));
+                parts.push(escapeXmlText(String(data.text ?? data.content ?? '')));
                 break;
             case 'at':
             case 'mention':
-                parts.push(`@${String(data.name ?? data.id ?? data.target ?? '')}`);
+                parts.push(encodeAtElement(data, platform));
+                break;
+            case 'emoji':
+            case 'face':
+                parts.push(encodeEmojiElement(data));
                 break;
             case 'image':
             case 'audio':
@@ -219,7 +339,7 @@ export function formatSatoriOutbound(payload) {
             case 'file': {
                 const src = resolveMediaSrc(item.type, data);
                 if (src)
-                    parts.push(`[${item.type}:${src}]`);
+                    parts.push(encodeMediaElement(item.type, src, data, platform));
                 break;
             }
             default:
@@ -228,6 +348,319 @@ export function formatSatoriOutbound(payload) {
     }
     return parts.join('');
 }
+const MEDIA_ELEMENT_NAMES = {
+    image: 'img',
+    audio: 'audio',
+    video: 'video',
+    file: 'file',
+};
+const DECODABLE_SATORI_TAGS = new Set(['at', 'img', 'emoji', 'audio', 'video', 'file']);
+function encodeAtElement(data, platform) {
+    const explicitType = readString(data.type) ?? readString(platform?.type);
+    const rawId = readString(data.id) ?? readString(data.target);
+    const id = rawId === 'all' || rawId === 'here' ? undefined : rawId;
+    const type = explicitType ?? (rawId === 'all' || rawId === 'here' ? rawId : undefined);
+    return renderSatoriElement('at', [
+        ['id', id],
+        ['name', readString(data.name)],
+        ['role', readString(data.role) ?? readString(platform?.role)],
+        ['type', type],
+    ]);
+}
+function encodeEmojiElement(data) {
+    return renderSatoriElement('emoji', [
+        ['id', readToken(data.id) ?? readToken(data.face_id) ?? readString(data.emoji)],
+        ['name', readString(data.name)],
+    ]);
+}
+function encodeMediaElement(type, src, data, platform) {
+    const title = readString(data.title) ?? readString(data.name);
+    const fileName = isMediaRef(data.media) ? data.media.file_name : undefined;
+    const duration = typeof data.duration === 'number' ? String(data.duration) : undefined;
+    const poster = readString(data.poster) ?? readString(platform?.poster);
+    const timed = type === 'audio' || type === 'video';
+    return renderSatoriElement(MEDIA_ELEMENT_NAMES[type], [
+        ['src', src],
+        ['title', title ?? fileName],
+        ['duration', timed ? duration : undefined],
+        ['poster', timed || type === 'file' ? poster : undefined],
+    ]);
+}
+function renderSatoriElement(name, attrs) {
+    const rendered = attrs
+        .filter((entry) => typeof entry[1] === 'string' && entry[1] !== '')
+        .map(([key, value]) => ` ${key}="${escapeXmlAttr(value)}"`)
+        .join('');
+    return `<${name}${rendered}/>`;
+}
+function readString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function readToken(value) {
+    if (typeof value === 'string' && value)
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return undefined;
+}
+function escapeXmlText(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function escapeXmlAttr(value) {
+    return escapeXmlText(value).replace(/"/g, '&quot;');
+}
+function unescapeXml(value) {
+    let out = '';
+    for (let index = 0; index < value.length;) {
+        if (value[index] !== '&') {
+            out += value[index];
+            index += 1;
+            continue;
+        }
+        const window = value.slice(index + 1, index + 13);
+        const semi = window.indexOf(';');
+        if (semi <= 0) {
+            out += '&';
+            index += 1;
+            continue;
+        }
+        const decoded = decodeXmlEntity(window.slice(0, semi));
+        if (decoded === undefined) {
+            out += '&';
+            index += 1;
+            continue;
+        }
+        out += decoded;
+        index += semi + 2;
+    }
+    return out;
+}
+function decodeXmlEntity(body) {
+    switch (body) {
+        case 'quot': return '"';
+        case 'apos': return "'";
+        case 'lt': return '<';
+        case 'gt': return '>';
+        case 'amp': return '&';
+        default: break;
+    }
+    if (body.startsWith('#x') || body.startsWith('#X'))
+        return xmlCodePoint(body.slice(2), 16);
+    if (body.startsWith('#'))
+        return xmlCodePoint(body.slice(1), 10);
+    return undefined;
+}
+function xmlCodePoint(body, radix) {
+    if (!body || (radix === 16 ? !isHex(body) : !isDigits(body)))
+        return undefined;
+    const code = Number.parseInt(body, radix);
+    if (!Number.isInteger(code) || code < 0 || code > 0x10ffff)
+        return undefined;
+    if (code >= 0xd800 && code <= 0xdfff)
+        return undefined;
+    return String.fromCodePoint(code);
+}
+function isDigits(body) {
+    for (const char of body) {
+        if (char < '0' || char > '9')
+            return false;
+    }
+    return true;
+}
+function isHex(body) {
+    for (const char of body) {
+        const hex = (char >= '0' && char <= '9')
+            || (char >= 'a' && char <= 'f')
+            || (char >= 'A' && char <= 'F');
+        if (!hex)
+            return false;
+    }
+    return true;
+}
+function readSatoriElement(content, start) {
+    if (content[start] !== '<')
+        return { kind: 'literal' };
+    const next = content[start + 1];
+    if (!next || next === '/' || next === '!' || next === '?' || !isAsciiLetter(next))
+        return { kind: 'literal' };
+    let index = start + 2;
+    while (index < content.length && isTagNameChar(content[index] ?? ''))
+        index += 1;
+    const name = content.slice(start + 1, index).toLowerCase();
+    const attrStart = index;
+    let quote = '';
+    while (index < content.length) {
+        const char = content[index] ?? '';
+        if (quote) {
+            if (char === quote)
+                quote = '';
+            index += 1;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            index += 1;
+            continue;
+        }
+        if (char === '>')
+            break;
+        index += 1;
+    }
+    if (index >= content.length || content[index] !== '>')
+        return { kind: 'incomplete' };
+    const rawAttrs = content.slice(attrStart, index);
+    const trimmed = rawAttrs.trimEnd();
+    const selfClosing = trimmed.endsWith('/');
+    const attrs = parseXmlAttributes(selfClosing ? trimmed.slice(0, -1) : rawAttrs);
+    const end = index + 1;
+    if (selfClosing)
+        return { kind: 'element', element: { name, attrs, end } };
+    const close = findClosingTag(content, end, name);
+    if (!close)
+        return { kind: 'element', element: { name, attrs, end } };
+    const inner = content.slice(end, close.start);
+    return { kind: 'element', element: { name, attrs, ...(inner ? { inner } : {}), end: close.end } };
+}
+function parseXmlAttributes(source) {
+    const attrs = {};
+    let index = 0;
+    while (index < source.length) {
+        while (index < source.length && isXmlSpace(source[index] ?? ''))
+            index += 1;
+        if (index >= source.length)
+            break;
+        const first = source[index] ?? '';
+        if (!isAttrNameStart(first)) {
+            index += 1;
+            continue;
+        }
+        const keyStart = index;
+        index += 1;
+        while (index < source.length && isAttrNameChar(source[index] ?? ''))
+            index += 1;
+        const key = source.slice(keyStart, index).toLowerCase();
+        while (index < source.length && isXmlSpace(source[index] ?? ''))
+            index += 1;
+        if (source[index] !== '=')
+            continue;
+        index += 1;
+        while (index < source.length && isXmlSpace(source[index] ?? ''))
+            index += 1;
+        const quote = source[index];
+        if (quote !== '"' && quote !== "'")
+            continue;
+        index += 1;
+        const valueStart = index;
+        while (index < source.length && source[index] !== quote)
+            index += 1;
+        const value = source.slice(valueStart, index);
+        if (index < source.length)
+            index += 1;
+        attrs[key] = unescapeXml(value);
+    }
+    return attrs;
+}
+function findClosingTag(content, from, name) {
+    for (let index = from; index < content.length; index += 1) {
+        if (content[index] !== '<' || content[index + 1] !== '/')
+            continue;
+        let cursor = index + 2;
+        let matched = true;
+        for (let offset = 0; offset < name.length; offset += 1) {
+            if ((content[cursor + offset] ?? '').toLowerCase() !== name[offset]) {
+                matched = false;
+                break;
+            }
+        }
+        if (!matched)
+            continue;
+        cursor += name.length;
+        while (isXmlSpace(content[cursor] ?? ''))
+            cursor += 1;
+        if (content[cursor] === '>')
+            return { start: index, end: cursor + 1 };
+    }
+    return undefined;
+}
+function isAsciiLetter(char) {
+    return (char >= 'A' && char <= 'Z') || (char >= 'a' && char <= 'z');
+}
+function isTagNameChar(char) {
+    return isAsciiLetter(char) || isAsciiDigit(char) || char === '_' || char === ':' || char === '-';
+}
+function isAttrNameStart(char) {
+    return isAsciiLetter(char) || char === '_' || char === ':';
+}
+function isAttrNameChar(char) {
+    return isAttrNameStart(char) || isAsciiDigit(char) || char === '.' || char === '-';
+}
+function isAsciiDigit(char) {
+    return char >= '0' && char <= '9';
+}
+function isXmlSpace(char) {
+    return char === ' ' || char === '\t' || char === '\n' || char === '\r';
+}
+function segmentFromSatoriElement(name, attrs) {
+    if (name === 'at') {
+        const type = attrs.type;
+        const target = attrs.id || (type === 'all' || type === 'here' ? type : attrs.role);
+        const platform = {};
+        if (attrs.role)
+            platform.role = attrs.role;
+        if (type)
+            platform.type = type;
+        return {
+            type: 'mention',
+            data: {
+                ...(target ? { target } : {}),
+                ...(attrs.name ? { name: attrs.name } : {}),
+            },
+            ...(Object.keys(platform).length > 0 ? { platform } : {}),
+        };
+    }
+    if (name === 'emoji') {
+        return {
+            type: 'emoji',
+            data: {
+                ...(attrs.id ? { id: attrs.id } : {}),
+                ...(attrs.name ? { name: attrs.name } : {}),
+            },
+        };
+    }
+    const type = name === 'img' ? 'image' : name;
+    const src = attrs.src ?? '';
+    const base64 = src.startsWith('base64://');
+    const duration = attrs.duration && Number.isFinite(Number(attrs.duration)) ? Number(attrs.duration) : undefined;
+    return {
+        type,
+        data: {
+            media: base64
+                ? { kind: 'base64', value: src.slice('base64://'.length) }
+                : { kind: 'url', value: src },
+            ...(attrs.title ? { name: attrs.title } : {}),
+            ...(duration !== undefined ? { duration } : {}),
+            ...(attrs.poster ? { poster: attrs.poster } : {}),
+        },
+        ...(attrs.poster ? { platform: { poster: attrs.poster } } : {}),
+    };
+}
+function normalizeSatoriEmoji(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    if (typeof record.id !== 'string' || !record.id)
+        return undefined;
+    return {
+        id: record.id,
+        ...(typeof record.name === 'string' ? { name: record.name } : {}),
+    };
+}
+function noticeLabel(value) {
+    const flat = value.replace(/\s+/g, ' ').trim();
+    if (!flat)
+        return undefined;
+    return flat.length > 40 ? `${flat.slice(0, 39)}…` : flat;
+}
 export function extractCreatedMessageId(result) {
     const list = Array.isArray(result)
         ? result
@@ -235,3 +668,125 @@ export function extractCreatedMessageId(result) {
     const msg = list?.[0];
     return msg?.id ?? '';
 }
+/**
+ * 把 `guild-member.list` 的 `roles` 收成 `GuildRole[]`。
+ * 旧 SDK 可能仍下发 `string[]`，这里收成 `{ id }`。上游发版并保证对象数组后，字符串分支可以去掉。
+ */
+export function normalizeSatoriGuildRoles(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const roles = [];
+    for (const role of value) {
+        if (typeof role === 'string' && role) {
+            roles.push({ id: role });
+            continue;
+        }
+        if (!role || typeof role !== 'object')
+            continue;
+        const record = role;
+        if (typeof record.id !== 'string' || !record.id)
+            continue;
+        roles.push({
+            id: record.id,
+            ...(typeof record.name === 'string' ? { name: record.name } : {}),
+        });
+    }
+    return roles;
+}
+/** 成员列表原样保留其余字段，只把 roles 收成 GuildRole[]。 */
+export function withSatoriGuildRoles(member) {
+    if (!member || typeof member !== 'object' || !('roles' in member))
+        return member;
+    const roles = normalizeSatoriGuildRoles(member.roles);
+    if (!roles)
+        return member;
+    return { ...member, roles };
+}
+/**
+ * 按 `{ user, nick }` 读取好友。顶层 `id` / `name` 是 1.0.10 误用的 User 形状，这里不认。
+ */
+export function readSatoriFriend(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    if (!record.user || typeof record.user !== 'object')
+        return undefined;
+    const user = record.user;
+    if (typeof user.id !== 'string' || !user.id)
+        return undefined;
+    return {
+        user: {
+            id: user.id,
+            ...(typeof user.name === 'string' ? { name: user.name } : {}),
+            ...(typeof user.avatar === 'string' ? { avatar: user.avatar } : {}),
+        },
+        ...(typeof record.nick === 'string' ? { nick: record.nick } : {}),
+    };
+}
+/**
+ * reaction.* 的参数名是 `emoji_id`，不是 1.0.10 `addMessageReactionIn` 用的 `emoji`。
+ * clear 不传 emoji_id 表示清除全部表态。
+ * @see https://satori.chat/zh-CN/resources/reaction.html
+ */
+export function satoriReactionParams(method, input) {
+    const params = {
+        channel_id: input.channelId,
+        message_id: input.messageId,
+    };
+    if (input.emojiId !== undefined && (method !== 'clear' || input.emojiId !== '')) {
+        params.emoji_id = input.emojiId;
+    }
+    if (method === 'delete' && input.userId !== undefined)
+        params.user_id = input.userId;
+    if (method === 'list' && input.next !== undefined)
+        params.next = input.next;
+    return params;
+}
+/** `friend.approve` 同时表达通过和拒绝。 */
+export function satoriFriendApproveParams(messageId, approve, comment) {
+    return {
+        message_id: messageId,
+        approve,
+        ...(comment !== undefined ? { comment } : {}),
+    };
+}
+/**
+ * `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 function mapSatoriFriendRequest(body, endpointId, actions) {
+    if (body.type !== 'friend-request')
+        return undefined;
+    const user = body.user ?? body.friend?.user;
+    if (!user?.id)
+        return undefined;
+    const actor = senderFromId(user.id, user.name ?? body.friend?.nick);
+    if (!actor)
+        return undefined;
+    const messageId = typeof body.message?.id === 'string' && body.message.id ? body.message.id : undefined;
+    const requireMessageId = (kind) => {
+        if (!messageId) {
+            throw new Error(`Satori friend.approve 需要事件 message.id 作为 message_id，无法${kind === 'approve' ? '通过' : '拒绝'}该好友申请`);
+        }
+        return messageId;
+    };
+    return buildRequest(body, {
+        id: messageId ?? `satori:friend-request:${user.id}:${String(body.sn ?? body.timestamp ?? 0)}`,
+        clientAdapter: 'satori',
+        endpointId,
+        type: 'request',
+        name: 'request.friend.add',
+        conversation: sideEventConversation('friend', user.id),
+        actor,
+        ...(typeof body.message?.content === 'string' ? { comment: body.message.content } : {}),
+        timestamp: typeof body.timestamp === 'number' ? body.timestamp : Date.now(),
+        async $approve(remark) {
+            await actions.approve(requireMessageId('approve'), remark);
+        },
+        async $reject(reason) {
+            await actions.reject(requireMessageId('reject'), reason);
+        },
+    });
+}

package/lib/webhook.d.ts

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