@zhin.js/adapter-icqq 1.1.17 → 1.1.18

package/src/icqq-login-control.ts

@@ -0,0 +1,30 @@
+/**
+ * ICQQ login control surface exposed to the Plugin Runtime, Console and the
+ * recovery command. One control per endpoint instance (UIN), provided by the
+ * ICQQ plugin setup and filled by `adapters/icqq/create()`.
+ */
+import { createToken } from 'zhin.js';
+import type { PendingLoginTask } from '@zhin.js/core';
+
+export interface IcqqLoginControlState {
+  readonly endpointId: string;
+  readonly transportState: string;
+  readonly online: boolean;
+  readonly pending: readonly PendingLoginTask[];
+}
+
+export interface IcqqLoginControl {
+  readonly endpointId: string;
+  state(): IcqqLoginControlState;
+  pending(): readonly PendingLoginTask[];
+  /** Force a login attempt; rejects when the endpoint is stopped or the SDK login fails. */
+  relogin(): Promise<void>;
+  submit(taskId: string, value: string | Record<string, unknown>): boolean;
+  cancel(taskId: string, reason?: string): boolean;
+}
+
+/** `endpoint id (QQ uin)` → control for the current generation. */
+export const icqqLoginControlToken = createToken<Map<string, IcqqLoginControl>>(
+  'zhin.icqq.login-control',
+  'ICQQ login control surface for recovery commands',
+);

package/src/index.ts

@@ -3,12 +3,14 @@ export {
   formatInboundContent,
   formatOutboundBody,
   formatOutboundMessages,
+  formatOutboundMessageParts,
   icqqInboundConversation,
   icqqOutboundTarget,
   type ActionResult,
   type IcqqEndpointConfig,
   type IcqqInboundMessage,
   type IcqqWireSegment,
+  type IcqqOutboundMessagePart,
   type ParsedIcqqSendTarget,
   type ResolvedIcqqConfig,
 } from './protocol.js';

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 } : {}),
   };
 }
 
@@ -456,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 {