@zhin.js/adapter-icqq 1.1.16 → 1.1.18

package/src/protocol.ts

@@ -1,5 +1,6 @@
 import type { MessageElem, Sendable, ShareElem } from '@icqqjs/icqq';
 import { isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
+import { resolveAdapterNotifyTarget, type AdapterNotifyTarget, type ResolvedAdapterNotifyTarget } from 'zhin.js/adapter';
 import type { MessageSegment, SendContent } from "zhin.js";
 import { resolveIcqqMediaFile } from "./cq-message.js";
 
@@ -246,6 +247,8 @@ export interface IcqqEndpointConfig {
   readonly autoServer?: boolean;
   readonly qqnt?: boolean;
   readonly ntLogin?: boolean;
+  /** Optional out-of-band outage notification target (usually a QQ adapter instance). */
+  readonly notify?: AdapterNotifyTarget;
 }
 
 export interface ResolvedIcqqConfig {
@@ -264,6 +267,7 @@ export interface ResolvedIcqqConfig {
   readonly autoServer?: boolean;
   readonly qqnt?: boolean;
   readonly ntLogin?: boolean;
+  readonly notify?: ResolvedAdapterNotifyTarget;
 }
 
 export interface IcqqWireSegment {
@@ -311,6 +315,7 @@ export function resolveIcqqConfig(config: IcqqEndpointConfig): ResolvedIcqqConfi
   const autoServer = config.autoServer ?? true;
   const qqnt = config.qqnt;
   const ntLogin = config.ntLogin;
+  const notify = resolveAdapterNotifyTarget(config.notify);
   return {
     context: 'icqq',
     id,
@@ -327,6 +332,7 @@ export function resolveIcqqConfig(config: IcqqEndpointConfig): ResolvedIcqqConfi
     ...(autoServer != null ? { autoServer } : {}),
     ...(qqnt != null ? { qqnt } : {}),
     ...(ntLogin != null ? { ntLogin } : {}),
+    ...(notify ? { notify } : {}),
   };
 }
 
@@ -342,6 +348,8 @@ export function icqqInboundConversation(endpointKey: string, input: {
   readonly channelId: string;
   readonly channelParentGroupId?: string;
   readonly guildId?: string;
+  /** 群名（仅 group 会话使用） */
+  readonly name?: string;
 }): ConversationRef {
   const endpoint = { id: endpointKey, adapter: ICQQ_ADAPTER_NAME };
   if (input.channelType === 'private' && input.channelParentGroupId) {
@@ -360,7 +368,8 @@ export function icqqInboundConversation(endpointKey: string, input: {
       parent: { kind: 'channel', id: input.guildId },
     };
   }
-  return { endpoint, kind: input.channelType, id: input.channelId };
+  const name = input.channelType === 'group' ? input.name?.trim() : undefined;
+  return { endpoint, kind: input.channelType, id: input.channelId, ...(name ? { name } : {}) };
 }
 
 /**
@@ -453,19 +462,37 @@ export function formatOutboundBody(payload: unknown): Sendable {
  * quote or whitespace are dropped: a standalone element cannot carry the quote.
  */
 export function formatOutboundMessages(payload: unknown): Sendable[] {
+  return formatOutboundMessageParts(payload).map(part => part.message);
+}
+
+/** Native bubble and the exact source segment positions which produced it. */
+export interface IcqqOutboundMessagePart {
+  readonly message: Sendable;
+  readonly sourceIndices?: readonly number[];
+}
+
+export function formatOutboundMessageParts(payload: unknown): IcqqOutboundMessagePart[] {
   if (!Array.isArray(payload)) {
-    return isWireSegment(payload) ? formatOutboundMessages([payload]) : [formatOutboundBody(payload)];
+    if (isWireSegment(payload)) return formatOutboundMessageParts([payload]);
+    const message = formatOutboundBody(payload);
+    return [{ message, ...(typeof payload === 'string' && message !== payload ? {} : { sourceIndices: [0] }) }];
   }
-  const groups: (string | MessageElem)[][] = [[]];
-  for (const element of formatOutboundElements(payload)) {
-    if (isStandaloneElement(element)) groups.push([element], []);
-    else groups.at(-1)!.push(element);
+  const groups: { element: string | MessageElem; sourceIndex: number }[][] = [[]];
+  for (const [sourceIndex, source] of payload.entries()) {
+    for (const element of formatOutboundElements([source])) {
+      const item = { element, sourceIndex };
+      if (isStandaloneElement(element)) groups.push([item], []);
+      else groups.at(-1)!.push(item);
+    }
   }
-  const messages = groups.filter(group => group.some(element => typeof element === 'string'
+  const messages = groups.filter(group => group.some(({ element }) => typeof element === 'string'
     ? element.trim() !== ''
     : element.type !== 'reply' && element.type !== 'quote'));
-  if (messages.length === 0) return ['\u200b'];
-  return messages.map(group => group.length === 1 ? group[0]! : group);
+  if (messages.length === 0) return [{ message: '\u200b', sourceIndices: [] }];
+  return messages.map(group => ({
+    message: group.length === 1 ? group[0]!.element : group.map(item => item.element),
+    sourceIndices: [...new Set(group.map(item => item.sourceIndex))],
+  }));
 }
 
 function isStandaloneElement(element: string | MessageElem): element is MessageElem {
@@ -487,7 +514,8 @@ function formatOutboundElements(payload: readonly unknown[]): (string | MessageE
         if (!Number.isSafeInteger(qq) || qq <= 0) {
           throw new TypeError(`Invalid ICQQ mention target: ${String(target ?? '')}`);
         }
-        return { type: 'at', qq };
+        const name = typeof item.data?.name === 'string' ? item.data.name.trim() : '';
+        return name ? { type: 'at', qq, text: name.startsWith('@') ? name : `@${name}` } : { type: 'at', qq };
       }
       case 'image': {
         const arg = resolveIcqqMediaFile(normalizeIcqqImageData(item.data));