@zhin.js/adapter-icqq 1.1.17 → 1.1.19

package/src/group-moderation.ts

@@ -1,17 +1,17 @@
 import type { Client } from '@icqqjs/icqq';
-import type { GroupModerationAction, GroupModerationMember } from 'zhin.js/adapter';
+import { createEndpointOperation, type EndpointMemberInspectionRequest, type EndpointModerationRequest, type GroupModerationMember } from 'zhin.js/adapter';
 
 /** Native role/join facts stay in the adapter; the moderation plugin owns policy. */
 export async function inspectGroupMember(
-  client: Client, groupId: string, userId: string, signal: AbortSignal,
+  client: Client, { groupId, userId, signal }: EndpointMemberInspectionRequest,
 ): Promise<GroupModerationMember> {
-  signal.throwIfAborted();
+  const operation = createEndpointOperation({ signal });
   const group = numericId(groupId);
   const user = numericId(userId);
-  const selfLookup = client.getGroupMemberInfo(group, client.uin, true);
+  const selfLookup = operation.run(() => client.getGroupMemberInfo(group, client.uin, true));
   const [self, member] = await Promise.all([
     selfLookup,
-    user === client.uin ? selfLookup : client.getGroupMemberInfo(group, user, true),
+    user === client.uin ? selfLookup : operation.run(() => client.getGroupMemberInfo(group, user, true)),
   ]);
   signal.throwIfAborted();
   const joinedAt = member.join_time * 1000;
@@ -29,10 +29,10 @@ export async function inspectGroupMember(
 }
 
 export async function moderateGroupMember(
-  client: Client, groupId: string, userId: string, action: GroupModerationAction,
-  signal: AbortSignal, isActive: () => boolean,
+  { client, isActive }: { readonly client: Client; readonly isActive: () => boolean },
+  { groupId, userId, action, signal }: EndpointModerationRequest,
 ): Promise<void> {
-  const member = await inspectGroupMember(client, groupId, userId, signal);
+  const member = await inspectGroupMember(client, { groupId: groupId, userId: userId, signal: signal });
   signal.throwIfAborted();
   if (!isActive() || !member.canModerate) throw new Error('Group moderation permission is unavailable');
   if (action.type === 'kick') {
@@ -45,8 +45,8 @@ export async function moderateGroupMember(
     throw new Error('Invalid group mute duration');
   }
   const ok = action.type === 'kick'
-    ? await client.setGroupKick(numericId(groupId), numericId(userId))
-    : await client.setGroupBan(numericId(groupId), numericId(userId), action.durationSeconds);
+    ? await createEndpointOperation({ signal }).run(() => client.setGroupKick(numericId(groupId), numericId(userId)))
+    : await createEndpointOperation({ signal }).run(() => client.setGroupBan(numericId(groupId), numericId(userId), action.durationSeconds));
   if (!ok) throw new Error('Platform did not confirm the moderation action');
 }
 

package/src/group-scene.ts

@@ -1,5 +1,5 @@
 import type { Client } from '@icqqjs/icqq';
-import type { GroupMemberProfile, GroupSceneFacts } from 'zhin.js/adapter';
+import { createEndpointOperation, type EndpointGroupInspectionRequest, type EndpointMemberInspectionRequest, type GroupMemberProfile, type GroupSceneFacts } from 'zhin.js/adapter';
 
 /** Listing a very large roster only to find admins is not worth the packet; adminIds stay unknown. */
 export const ADMIN_SCAN_MAX_MEMBERS = 1000;
@@ -19,10 +19,10 @@ function numericId(value: string): number {
  * ADR 0041 scene facts: one uncached group-info read, plus (small groups only) one roster read for
  * admins. A roster failure leaves adminIds unknown instead of failing the other facts.
  */
-export async function inspectGroupScene(client: Client, groupId: string, signal: AbortSignal): Promise<GroupSceneFacts> {
-  signal.throwIfAborted();
+export async function inspectGroupScene(client: Client, { groupId, signal }: EndpointGroupInspectionRequest): Promise<GroupSceneFacts> {
+  const operation = createEndpointOperation({ signal });
   const group = numericId(groupId);
-  const info = await client.getGroupInfo(group, true);
+  const info = await operation.run(() => client.getGroupInfo(group, true));
   signal.throwIfAborted();
   if (info.group_id !== group) return {};
   const memberCount = Number.isSafeInteger(info.member_count) && info.member_count > 0 ? info.member_count : undefined;
@@ -30,7 +30,7 @@ export async function inspectGroupScene(client: Client, groupId: string, signal:
   let adminIds: string[] | undefined;
   if (memberCount === undefined || memberCount <= ADMIN_SCAN_MAX_MEMBERS) {
     try {
-      const roster = await client.getGroupMemberList(group);
+      const roster = await operation.run(() => client.getGroupMemberList(group));
       signal.throwIfAborted();
       adminIds = [...roster.values()]
         .filter(member => member.role === 'admin' && member.group_id === group)
@@ -55,12 +55,12 @@ export async function inspectGroupScene(client: Client, groupId: string, signal:
 
 /** ADR 0041 member facts from one uncached lookup (same rationale as the agent `freshMember` helper). */
 export async function inspectGroupMemberProfile(
-  client: Client, groupId: string, userId: string, signal: AbortSignal,
+  client: Client, { groupId, userId, signal }: EndpointMemberInspectionRequest,
 ): Promise<GroupMemberProfile> {
-  signal.throwIfAborted();
+  const operation = createEndpointOperation({ signal });
   const group = numericId(groupId);
   const user = numericId(userId);
-  const member = await client.getGroupMemberInfo(group, user, true);
+  const member = await operation.run(() => client.getGroupMemberInfo(group, user, true));
   signal.throwIfAborted();
   if (member.user_id !== user || member.group_id !== group) return {};
   const card = typeof member.card === 'string' && member.card.trim() ? member.card.trim() : undefined;

package/src/icqq-login-assist.ts

@@ -1,6 +1,6 @@
 import type { Locale } from 'zhin.js/i18n';
 import { messages as t } from './i18n.js';
-import type { LoginAssist, LoginAssistType, PendingLoginTaskPayload } from '@zhin.js/core';
+import type { LoginAssist, LoginAssistEndpointIdentity, LoginAssistType, PendingLoginTaskPayload } from '@zhin.js/core';
 import { formatCompact } from '@zhin.js/logger';
 
 type IcqqLoginClient = {
@@ -26,6 +26,8 @@ export async function runIcqqLoginAssistStep(input: {
   adapter: string;
   endpointKey: string;
   owner: object;
+  signal?: AbortSignal;
+  endpointIdentity?: LoginAssistEndpointIdentity;
   logger: Logger;
   step: LoginAssistType;
   event: unknown;
@@ -44,6 +46,7 @@ export async function runIcqqLoginAssistStep(input: {
   }));
 
   try {
+    input.signal?.throwIfAborted();
     if (step === 'device') {
       try {
         await client.sendSmsCode();
@@ -56,7 +59,8 @@ export async function runIcqqLoginAssistStep(input: {
       }
     }
 
-    const value = await assist.waitForInput(adapter, endpointKey, step, payload, { owner });
+    const value = await assist.waitForInput(adapter, endpointKey, step, payload, { owner, signal: input.signal, endpointIdentity: input.endpointIdentity });
+    input.signal?.throwIfAborted();
     const text = normalizeSubmitValue(value);
 
     switch (step) {

package/src/icqq-login-control.ts

@@ -0,0 +1,42 @@
+/**
+ * ICQQ login control surface exposed to the Plugin Runtime, Console and the
+ * recovery command. Controls are projected from actual current incarnations in
+ * the owning IcqqAdapter; no plugin resource keeps a second Endpoint directory.
+ */
+import { adapterFeatureId, isAdapterIndex } from 'zhin.js/adapter';
+import type { FeatureId, PluginId } from 'zhin.js';
+import { IcqqAdapter } from './adapter.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;
+}
+
+/** Read the owning Adapter's actual incarnations; this projection retains no independent directory. */
+export function icqqLoginControls(context: Readonly<{ owner: PluginId | Readonly<{ id: PluginId }>; project<T>(id: FeatureId): T }>): ReadonlyMap<string, IcqqLoginControl> {
+  const index = context.project<unknown>(adapterFeatureId);
+  if (!isAdapterIndex(index)) throw new Error('ICQQ Adapter projection is unavailable');
+  const owner = typeof context.owner === 'string' ? context.owner : context.owner.id;
+  const controls = new Map<string, IcqqLoginControl>();
+  for (const adapter of index.forOwner(owner).adapters()) {
+    if (!(adapter instanceof IcqqAdapter)) continue;
+    for (const row of adapter.list()) {
+      const endpoint = adapter.getEndpoint(row.instanceId);
+      if (endpoint) controls.set(row.endpointId, endpoint.loginControl);
+    }
+  }
+  return controls;
+}

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';
@@ -21,7 +23,6 @@ export {
 export * from './types.js';
 
 export {
-  icqqClient,
   type IcqqClient,
   type IcqqClientEventMap,
 } from './client.js';
@@ -29,3 +30,5 @@ export {
 export {
   resolveIcqqInboundMessageId,
 } from './icqq-inbound.js';
+
+export { IcqqAdapter } from './adapter.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 {
@@ -273,6 +277,9 @@ export interface IcqqWireSegment {
 }
 
 export interface IcqqInboundMessage {
+  /** Exact SDK callback object, operation-local and never a persisted projection. */
+  readonly event?: unknown;
+  readonly platformSentAt?: number;
   readonly id: string;
   readonly conversation: ConversationRef;
   readonly content: string;
@@ -311,6 +318,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 +335,7 @@ export function resolveIcqqConfig(config: IcqqEndpointConfig): ResolvedIcqqConfi
     ...(autoServer != null ? { autoServer } : {}),
     ...(qqnt != null ? { qqnt } : {}),
     ...(ntLogin != null ? { ntLogin } : {}),
+    ...(notify ? { notify } : {}),
   };
 }
 
@@ -456,19 +465,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 {

package/lib/icqq-runtime-state.d.ts

@@ -1 +0,0 @@
-export declare const icqqRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/icqq-runtime-state.js

@@ -1,6 +0,0 @@
-/**
- * ICQQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `icqq endpoint` 命令共享（同一 owner generation）。
- */
-import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
-export const icqqRuntimeStateToken = defineEndpointRuntimeStateToken('icqq');

package/src/icqq-runtime-state.ts

@@ -1,7 +0,0 @@
-/**
- * ICQQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `icqq endpoint` 命令共享（同一 owner generation）。
- */
-import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
-
-export const icqqRuntimeStateToken = defineEndpointRuntimeStateToken('icqq');