@zhin.js/adapter-satori 0.0.0

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Satori 适配器入口：单一适配器，支持 WS / Webhook，协议文档 https://satori.chat/zh-CN/introduction.html
+ */
+import { usePlugin, type Plugin, type Context } from 'zhin.js';
+import type { Router } from '@zhin.js/http';
+import { SatoriAdapter } from './adapter.js';
+
+export * from './types.js';
+export { callSatoriApi } from './api.js';
+export * from './utils.js';
+export { SatoriWsClient } from './bot-ws.js';
+export { SatoriWebhookBot } from './bot-webhook.js';
+export { SatoriAdapter, type SatoriBot } from './adapter.js';
+
+declare module 'zhin.js' {
+  namespace Plugin {
+    interface Contexts {
+      router: import('@zhin.js/http').Router;
+    }
+  }
+  interface Adapters {
+    satori: SatoriAdapter;
+  }
+}
+
+const { provide } = usePlugin();
+provide({
+  name: 'satori',
+  description: 'Satori 协议适配器（WS 正向 / Webhook）',
+  mounted: async (p: Plugin) => {
+    const adapter = new SatoriAdapter(p);
+    await adapter.start();
+    return adapter;
+  },
+  dispose: async (adapter: SatoriAdapter) => {
+    await adapter.stop();
+  },
+} as unknown as Context<'satori'>);

package/src/types.ts

@@ -0,0 +1,91 @@
+/**
+ * Satori 适配器类型（参考 https://satori.chat 协议）
+ */
+
+/** 配置公共字段；单一适配器 context 均为 'satori'，连接方式由 connection 区分 */
+export interface SatoriConfigBase {
+  context: 'satori';
+  name: string;
+  baseUrl: string;
+  /** 认证 token，API 用 Authorization: Bearer，WebSocket IDENTIFY 用 token 字段 */
+  token?: string;
+}
+
+/** WebSocket 连接（应用连 SDK /v1/events） */
+export interface SatoriWsConfig extends SatoriConfigBase {
+  connection: 'ws';
+  /** 心跳间隔（毫秒），默认 10000 */
+  heartbeat_interval?: number;
+}
+
+/** WebHook（SDK POST 到应用提供的 path） */
+export interface SatoriWebhookConfig extends SatoriConfigBase {
+  connection: 'webhook';
+  path: string;
+}
+
+export type SatoriBotConfig = SatoriWsConfig | SatoriWebhookConfig;
+
+/** WebSocket/API 信号：op + body */
+export interface SatoriSignal {
+  op: number;
+  body?: Record<string, unknown>;
+}
+
+/** Opcode：EVENT=0, PING=1, PONG=2, IDENTIFY=3, READY=4, META=5 */
+export const SatoriOpcode = {
+  EVENT: 0,
+  PING: 1,
+  PONG: 2,
+  IDENTIFY: 3,
+  READY: 4,
+  META: 5,
+} as const;
+
+/** 事件体（EVENT 的 body）：type、sn、timestamp、login、message、channel、user 等 */
+export interface SatoriEventBody {
+  type?: string;
+  sn?: number;
+  timestamp?: number;
+  login?: SatoriLogin;
+  message?: SatoriMessage;
+  channel?: SatoriChannel;
+  user?: SatoriUser;
+  guild?: { id: string; name?: string };
+  member?: { user?: SatoriUser; nick?: string; roles?: string[] };
+  [key: string]: unknown;
+}
+
+/** Login 资源（READY 与事件中） */
+export interface SatoriLogin {
+  platform?: string;
+  user?: SatoriUser;
+  status?: number;
+  sn?: number;
+}
+
+/** Channel 资源：id, type (0=TEXT,1=DIRECT,2=CATEGORY,3=VOICE) */
+export interface SatoriChannel {
+  id: string;
+  type?: number;
+  name?: string;
+  parent_id?: string;
+}
+
+/** User 资源 */
+export interface SatoriUser {
+  id: string;
+  name?: string;
+  avatar?: string;
+}
+
+/** Message 资源：id, content（元素字符串）, channel, user 等 */
+export interface SatoriMessage {
+  id: string;
+  content?: string;
+  channel?: SatoriChannel;
+  user?: SatoriUser;
+  member?: { user?: SatoriUser; nick?: string };
+  created_at?: number;
+  updated_at?: number;
+}

package/src/utils.ts

@@ -0,0 +1,64 @@
+/**
+ * Satori 事件与 zhin Message 的转换
+ */
+import type { SendContent } from 'zhin.js';
+import { Message } from 'zhin.js';
+import type { SatoriEventBody, SatoriMessage, SatoriChannel } from './types.js';
+
+/** Satori Channel.type: 0=TEXT, 1=DIRECT, 2=CATEGORY, 3=VOICE */
+export function isPrivateChannel(channel?: SatoriChannel): boolean {
+  return channel?.type === 1;
+}
+
+/** 将 Satori 事件体转为 zhin Message 的 MessageBase（仅 message-created/updated，供 $formatMessage 使用） */
+export function formatSatoriMessagePayload(
+  body: SatoriEventBody,
+  adapterName: 'satori',
+  botName: string,
+  recallFn: (msgId: string) => Promise<void>,
+  replyFn: (channel: { id: string; type: 'group' | 'private' }, content: (string | { type: string; data?: Record<string, unknown> })[], quote?: boolean | string) => Promise<string>,
+): {
+  $id: string;
+  $adapter: 'satori';
+  $bot: string;
+  $channel: { id: string; type: 'group' | 'private' };
+  $sender: { id: string; name: string };
+  $content: Array<{ type: string; data: Record<string, unknown> }>;
+  $raw: string;
+  $timestamp: number;
+  $recall: () => Promise<void>;
+  $reply: (content: SendContent, quote?: boolean | string) => Promise<string>;
+} {
+  const msg = body.message!;
+  const channel = body.channel ?? msg.channel;
+  const user = body.user ?? msg.user ?? msg.member?.user;
+  const channelId = channel?.id ?? '';
+  const isPrivate = isPrivateChannel(channel);
+  const content = msg.content ?? '';
+  const raw = typeof content === 'string' ? content : String(content);
+  const senderId = user?.id ?? '';
+  const senderName = user?.name ?? msg.member?.nick ?? senderId;
+
+  return {
+    $id: `${channelId}:${msg.id}`,
+    $adapter: 'satori',
+    $bot: botName,
+    $channel: { id: channelId, type: isPrivate ? 'private' : 'group' },
+    $sender: { id: senderId, name: senderName },
+    $content: [{ type: 'text', data: { text: raw } }],
+    $raw: raw,
+    $timestamp: body.timestamp ?? msg.created_at ?? Math.floor(Date.now() / 1000),
+    $recall: () => recallFn(`${channelId}:${msg.id}`),
+    $reply: (cnt: SendContent, quote?: boolean | string) =>
+      replyFn(
+        { id: channelId, type: isPrivate ? 'private' : 'group' },
+        (Array.isArray(cnt) ? cnt : [cnt]) as (string | { type: string; data?: Record<string, unknown> })[],
+        quote,
+      ),
+  };
+}
+
+/** 判断是否为消息相关事件（message-created / message-updated） */
+export function isMessageEvent(body: SatoriEventBody): body is SatoriEventBody & { message: SatoriMessage } {
+  return (body.type === 'message-created' || body.type === 'message-updated') && !!body.message?.id;
+}