@zhin.js/adapter-kook 2.0.11 → 3.0.0

package/src/kook-side-events.ts

@@ -0,0 +1,202 @@
+/**
+ * KOOK Gateway 非聊天入站：系统消息 (type=255) / BROADCAST → Notice
+ * @see https://developer.kookapp.cn/doc/event/event-introduction
+ */
+import { Notice, formatCompact, type NoticeType } from "zhin.js";
+
+/** KOOK WebSocket s=0 时 d 字段（kook-client Receiver 入参） */
+export interface KookGatewayEvent {
+  channel_type?: string;
+  type?: number;
+  target_id?: string;
+  author_id?: string;
+  content?: string;
+  msg_id?: string;
+  msg_timestamp?: number;
+  nonce?: string;
+  extra?: KookGatewayExtra;
+  [key: string]: unknown;
+}
+
+export interface KookGatewayExtra {
+  type?: string;
+  body?: Record<string, unknown>;
+  guild_id?: string;
+  channel_id?: string;
+  channel_name?: string;
+  author?: { id?: string; username?: string; nickname?: string };
+  [key: string]: unknown;
+}
+
+const SYSTEM_MESSAGE_TYPE = 255;
+
+/** 是否应由适配器作为 notice 处理（kook-client 对 notice 的 transform 为空实现） */
+export function isKookNoticeGatewayEvent(data: unknown): data is KookGatewayEvent {
+  if (!data || typeof data !== "object") return false;
+  const ev = data as KookGatewayEvent;
+  if (ev.type === SYSTEM_MESSAGE_TYPE) return true;
+  return ev.channel_type === "BROADCAST";
+}
+
+export function resolveKookSideEventDedupeKey(
+  event: KookGatewayEvent,
+  kind: "notice" | "gateway",
+): string {
+  if (event.msg_id) return `${kind}:${event.msg_id}`;
+  const extra = event.extra ?? {};
+  const noticeType = extra.type ?? String(event.type ?? "");
+  const scope = event.target_id ?? "";
+  const ts = event.msg_timestamp ?? 0;
+  return `${kind}:${ts}_${noticeType}_${scope}`;
+}
+
+const NOTICE_TYPE_MAP: Record<string, NoticeType> = {
+  joined_guild: "group_member_increase",
+  exited_guild: "group_member_decrease",
+  deleted_message: "group_recall",
+  deleted_private_message: "friend_recall",
+  added_reaction: "group_emoji_reaction",
+  deleted_reaction: "group_emoji_reaction",
+  private_added_reaction: "group_emoji_reaction",
+  private_deleted_reaction: "group_emoji_reaction",
+};
+
+function resolveNoticeZhinType(rawType: string): NoticeType {
+  return NOTICE_TYPE_MAP[rawType] ?? rawType;
+}
+
+function senderFromId(id: unknown, name?: string) {
+  if (id == null || id === "") return undefined;
+  const s = String(id);
+  return { id: s, name: name ?? s };
+}
+
+function readString(obj: Record<string, unknown> | undefined, key: string): string | undefined {
+  const v = obj?.[key];
+  if (v == null || v === "") return undefined;
+  return String(v);
+}
+
+/** 解析 notice 发生的频道 / 群 / 私聊 */
+export function resolveKookNoticeChannel(
+  event: KookGatewayEvent,
+): { id: string; type: "group" | "private" | "channel" } {
+  const extra = event.extra ?? {};
+  const body = extra.body ?? {};
+  const rawType = String(extra.type ?? "");
+
+  if (event.channel_type === "BROADCAST") {
+    const guildId =
+      readString(body, "guild_id")
+      ?? extra.guild_id
+      ?? event.target_id
+      ?? "";
+    return { id: guildId, type: "group" };
+  }
+
+  if (event.type === SYSTEM_MESSAGE_TYPE && event.channel_type === "GROUP") {
+    const guildId =
+      readString(body, "guild_id")
+      ?? extra.guild_id
+      ?? event.target_id
+      ?? "";
+    if (
+      rawType === "joined_guild"
+      || rawType === "exited_guild"
+      || rawType === "updated_guild"
+      || rawType === "deleted_guild"
+      || rawType.startsWith("added_role")
+      || rawType.startsWith("deleted_role")
+      || rawType.startsWith("updated_role")
+      || rawType.startsWith("added_block")
+      || rawType.startsWith("deleted_block")
+      || rawType === "self_joined_guild"
+      || rawType === "self_exited_guild"
+    ) {
+      return { id: guildId, type: "group" };
+    }
+    const channelId =
+      readString(body, "channel_id")
+      ?? extra.channel_id
+      ?? event.target_id
+      ?? "";
+    return { id: channelId, type: "channel" };
+  }
+
+  if (
+    rawType.startsWith("private_")
+    || rawType.includes("private_message")
+    || event.channel_type === "PERSON"
+  ) {
+    const userId =
+      readString(body, "user_id")
+      ?? readString(body, "target_id")
+      ?? event.target_id
+      ?? event.author_id
+      ?? "";
+    return { id: userId, type: "private" };
+  }
+
+  const channelId =
+    readString(body, "channel_id")
+    ?? extra.channel_id
+    ?? event.target_id
+    ?? "";
+  return { id: channelId, type: "channel" };
+}
+
+export function enrichKookGatewayForPlugins(event: KookGatewayEvent): KookGatewayEvent {
+  const extra = event.extra ?? {};
+  const noticeType = extra.type;
+  if (!isKookNoticeGatewayEvent(event)) {
+    return { ...(event as object), post_type: "message" } as KookGatewayEvent;
+  }
+  return {
+    ...(event as object),
+    post_type: "notice",
+    notice_type: noticeType ?? "system",
+  } as KookGatewayEvent;
+}
+
+export function formatKookNotice(
+  event: KookGatewayEvent,
+  botName: string,
+): ReturnType<typeof Notice.from<KookGatewayEvent>> {
+  const extra = event.extra ?? {};
+  const body = extra.body ?? {};
+  const rawType = String(extra.type ?? "unknown");
+  const $type = resolveNoticeZhinType(rawType);
+  const channel = resolveKookNoticeChannel(event);
+  const ts = event.msg_timestamp ?? Date.now();
+
+  const targetId =
+    readString(body, "user_id")
+    ?? readString(body, "msg_id")
+    ?? readString(body, "target_id");
+  const operatorId =
+    readString(body, "operator_id")
+    ?? (event.author_id !== "1" ? event.author_id : undefined);
+
+  const mapped = NOTICE_TYPE_MAP[rawType] != null;
+
+  return Notice.from(event, {
+    $id: resolveKookSideEventDedupeKey(event, "notice"),
+    $adapter: "kook",
+    $bot: botName,
+    $type,
+    $subType: mapped ? rawType : undefined,
+    $channel: channel,
+    $operator: senderFromId(operatorId),
+    $target: senderFromId(targetId),
+    $timestamp: ts,
+  });
+}
+
+export function formatKookNoticeLog(notice: ReturnType<typeof formatKookNotice>): string {
+  return formatCompact({
+    notice: notice.$type,
+    kook_type: notice.$subType,
+    channel: `${notice.$channel.type}(${notice.$channel.id})`,
+    bot: notice.$bot,
+  });
+}

package/src/outbound-media.ts

@@ -0,0 +1,111 @@
+/**
+ * KOOK 出站媒体：base64 / 本地文件须先走 /v3/asset/create 上传，再嵌入 KMarkdown。
+ */
+import type { MessageElement, MessageSegment, SendContent } from "zhin.js";
+
+const MEDIA_TYPES = new Set(["image", "audio", "video", "file"]);
+
+export interface KookMediaUploader {
+  uploadMedia(data: string | Buffer): Promise<string>;
+}
+
+function isMessageSegment(seg: MessageElement): seg is MessageSegment {
+  return typeof seg.type === "string";
+}
+
+function isRemoteUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function asSegments(content: SendContent): MessageElement[] {
+  if (typeof content === "string") {
+    return [{ type: "text", data: { text: content } }];
+  }
+  if (!Array.isArray(content)) {
+    return [content];
+  }
+  return content.map((item) =>
+    typeof item === "string" ? { type: "text", data: { text: item } } : item,
+  );
+}
+
+function extractBase64Buffer(data: Record<string, unknown>): Buffer | undefined {
+  const url = typeof data.url === "string" ? data.url : undefined;
+  const file = typeof data.file === "string" ? data.file : undefined;
+  const base64 = typeof data.base64 === "string" ? data.base64 : undefined;
+
+  if (url?.startsWith("base64://")) {
+    return Buffer.from(url.slice(9), "base64");
+  }
+  if (url && /^data:[^/]+\/[^;]+;base64,/i.test(url)) {
+    return Buffer.from(url.replace(/^data:[^/]+\/[^;]+;base64,/, ""), "base64");
+  }
+  if (file?.startsWith("base64://")) {
+    return Buffer.from(file.slice(9), "base64");
+  }
+  if (base64) {
+    const raw = base64.startsWith("base64://") ? base64.slice(9) : base64;
+    return Buffer.from(raw, "base64");
+  }
+  return undefined;
+}
+
+function resolveLocalFile(data: Record<string, unknown>): string | undefined {
+  const url = typeof data.url === "string" ? data.url : undefined;
+  const file = typeof data.file === "string" ? data.file : undefined;
+  const candidate = file ?? url;
+  if (!candidate || isRemoteUrl(candidate)) return undefined;
+  if (candidate.startsWith("base64://") || /^data:/.test(candidate)) return undefined;
+  if (candidate.startsWith("file://") || candidate.startsWith("/") || !candidate.includes("://")) {
+    return candidate;
+  }
+  return undefined;
+}
+
+function withUploadedUrl(seg: MessageSegment, uploadedUrl: string): MessageSegment {
+  const data = { ...seg.data } as Record<string, unknown>;
+  data.url = uploadedUrl;
+  data.file = uploadedUrl;
+  delete data.base64;
+  return { type: seg.type, data } as MessageSegment;
+}
+
+async function resolveMediaSegment(
+  uploader: KookMediaUploader,
+  seg: MessageSegment,
+): Promise<MessageSegment> {
+  if (!MEDIA_TYPES.has(seg.type)) return seg;
+
+  const data = seg.data as Record<string, unknown>;
+  const url = typeof data.url === "string" ? data.url : undefined;
+  const file = typeof data.file === "string" ? data.file : undefined;
+  if ((url && isRemoteUrl(url)) || (file && isRemoteUrl(file))) {
+    return seg;
+  }
+
+  const buffer = extractBase64Buffer(data);
+  if (buffer) {
+    const uploaded = await uploader.uploadMedia(buffer);
+    return withUploadedUrl(seg, uploaded);
+  }
+
+  const local = resolveLocalFile(data);
+  if (local) {
+    const uploaded = await uploader.uploadMedia(local);
+    return withUploadedUrl(seg, uploaded);
+  }
+
+  return seg;
+}
+
+/** 将 base64 / 本地媒体上传为 KOOK 可访问 URL */
+export async function materializeOutboundMedia(
+  uploader: KookMediaUploader,
+  content: SendContent,
+): Promise<MessageElement[]> {
+  const segments = asSegments(content);
+  return Promise.all(segments.map(async (item) => {
+    if (!isMessageSegment(item)) return item;
+    return resolveMediaSegment(uploader, item);
+  }));
+}

package/src/outbound-sendable.ts

@@ -0,0 +1,61 @@
+/**
+ * Zhin 消息段 → kook-client Sendable。
+ * 图片/音视频须用 segment 发送对应 msg_type，不能写成 Markdown ![alt](url)。
+ */
+import { segment, type MessageSegment as KookMessageSegment } from "kook-client";
+import type { MessageElement } from "zhin.js";
+
+function mediaUrl(data: Record<string, unknown>): string {
+  return String(data.url ?? data.file ?? "");
+}
+
+/**
+ * 单张图片（可带 reply）→ kook image 消息段（type=2）
+ */
+export function convertToKookSendable(
+  elements: MessageElement[],
+  formatText: (content: MessageElement[]) => string,
+): string | KookMessageSegment[] {
+  const replies: string[] = [];
+  const images: string[] = [];
+  const videos: string[] = [];
+  const audios: string[] = [];
+  const rest: MessageElement[] = [];
+
+  for (const el of elements) {
+    if (el.type === "reply" && el.data.id) {
+      replies.push(String(el.data.id));
+      continue;
+    }
+    if (el.type === "image") {
+      const url = mediaUrl(el.data as Record<string, unknown>);
+      if (url) images.push(url);
+      continue;
+    }
+    if (el.type === "video") {
+      const url = mediaUrl(el.data as Record<string, unknown>);
+      if (url) videos.push(url);
+      continue;
+    }
+    if (el.type === "audio") {
+      const url = mediaUrl(el.data as Record<string, unknown>);
+      if (url) audios.push(url);
+      continue;
+    }
+    rest.push(el);
+  }
+
+  const replySegs = replies.map((id) => segment.reply(id));
+
+  if (images.length === 1 && videos.length === 0 && audios.length === 0 && rest.length === 0) {
+    return [...replySegs, segment.image(images[0])];
+  }
+  if (videos.length === 1 && images.length === 0 && audios.length === 0 && rest.length === 0) {
+    return [...replySegs, segment.video(videos[0])];
+  }
+  if (audios.length === 1 && images.length === 0 && videos.length === 0 && rest.length === 0) {
+    return [...replySegs, segment.audio(audios[0])];
+  }
+
+  return formatText(elements);
+}

package/src/types.ts

@@ -22,6 +22,24 @@ export interface KookSenderInfo {
   isAdmin?: boolean;
 }
 
+export interface KookTypingIndicatorConfig {
+  enabled?: boolean;
+  defaultEmoji?: string;
+  autoRemove?: boolean;
+  removeDelay?: number;
+  privateConfig?: {
+    type?: 'reaction' | 'message' | 'typing' | 'none';
+    emoji?: string;
+    message?: string;
+  };
+  /** 频道/群聊（KOOK channel 走 groupConfig 合并逻辑） */
+  groupConfig?: {
+    type?: 'reaction' | 'message' | 'typing' | 'none';
+    emoji?: string;
+    message?: string;
+  };
+}
+
 export interface KookBotConfig {
   context: "kook";
   name: string;
@@ -31,6 +49,8 @@ export interface KookBotConfig {
   max_retry?: number;
   ignore?: "bot" | "self";
   logLevel?: LogLevel;
+  /** AI 处理中提示（reaction 推荐：不打断会话） */
+  typingIndicator?: KookTypingIndicatorConfig;
 }
 
 export type KookRawMessage = PrivateMessageEvent | ChannelMessageEvent;