@zhin.js/adapter-icqq 6.0.3 → 7.0.0

package/src/endpoint.ts

@@ -1,7 +1,7 @@
 /**
  * IcqqIpcEndpoint — lifecycle, outbound, IPC subscribe/admit for ICQQ daemon.
  */
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -19,6 +19,14 @@ import {
   type IcqqIpcMessageEvent,
 } from './icqq-inbound.js';
 import {
+  buildIcqqInboxNoticeRow,
+  buildIcqqInboxRequestRow,
+  buildIcqqSystemRequestRow,
+  isIcqqNoticePayload,
+  isIcqqRequestPayload,
+} from './icqq-inbox.js';
+import {
+  IcqqGuildCatalog,
   isIcqqGuildIpcEvent,
   normalizeIcqqGuildInboundMessage,
 } from './icqq-guild.js';
@@ -38,7 +46,7 @@ import {
   type IpcResponse,
   type ResolvedIcqqConfig,
 } from './protocol.js';
-import type { IpcFriendInfo, IpcGroupInfo } from './types.js';
+import type { IpcFriendInfo, IpcGroupInfo, IpcMemberInfo, IpcSystemMessage } from './types.js';
 
 const logger = getLogger('icqq');
 
@@ -56,11 +64,23 @@ export interface IcqqIpcTransport {
 
 export type CreateIcqqIpc = (config: ResolvedIcqqConfig) => Promise<IcqqIpcTransport>;
 
+/**
+ * 收件箱写/推钩子（由装配层注入，见 adapters/icqq.ts）。
+ * record* 写 unified_inbox_request/notice；publish 向 console hub 推送实时事件。
+ */
+export interface IcqqInboxHooks {
+  recordRequest(row: Record<string, unknown>): void | Promise<void>;
+  recordNotice(row: Record<string, unknown>): void | Promise<void>;
+  publish?(type: string, data: unknown): void;
+}
+
 export interface IcqqEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
   readonly config: ResolvedIcqqConfig;
   readonly createIpc?: CreateIcqqIpc;
+  /** 未注入时 request/notice 事件仅按非消息载荷忽略（不报错）。 */
+  readonly inbox?: IcqqInboxHooks;
 }
 
 export class IcqqIpcEndpoint implements EndpointInstance {
@@ -71,10 +91,28 @@ export class IcqqIpcEndpoint implements EndpointInstance {
   ipc!: IcqqIpcTransport;
   readonly friends = new Map<number, IpcFriendInfo>();
   readonly groups = new Map<number, IpcGroupInfo>();
+  readonly #guildCatalog = new IcqqGuildCatalog();
+  readonly management: EndpointManagement = Object.freeze<EndpointManagement>({
+    listFriends: () => this.getFriendList(),
+    listGroups: () => this.getGroupList(),
+    listChannels: async () => {
+      await this.#guildCatalog.syncAll(this.ipc);
+      return this.#guildCatalog.getGuildChannelList();
+    },
+    listGroupMembers: (groupId) => this.getGroupMemberList(groupId),
+    approveRequest: (requestId, remark) => this.approveRequest(requestId, remark),
+    rejectRequest: (requestId, reason) => this.rejectRequest(requestId, reason),
+    kickGroupMember: (groupId, userId) => this.removeMember(groupId, userId),
+    muteGroupMember: (groupId, userId, duration) => this.muteMember(groupId, userId, duration),
+    setGroupAdmin: (groupId, userId, enabled) => this.setModerator(groupId, userId, enabled),
+    deleteFriend: (userId) => this.deleteFriend(userId),
+  });
   #open = false;
   #started = false;
   #subscriptions: Array<{ unsubscribe: () => Promise<void> }> = [];
   #inboundDeduper = new InboundMessageDeduper();
+  /** request/notice 去重（推送事件与 GET_SYSTEM_MSG 首拉可能重复同一 flag）。 */
+  #inboxDeduper = new InboundMessageDeduper();
   #unregisterAgent?: () => void;
   /** 用户主动 stop 时为 true，阻止自动重连 */
   #intentionalDisconnect = false;
@@ -130,6 +168,9 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       this.#handleEvent(event);
     });
     this.#subscriptions.push(sub);
+    // daemon 推送 client.em 全部事件，request/notice 实时到达；
+    // 启动时补一次 GET_SYSTEM_MSG，捞离线期间积存的待处理请求。
+    void this.#pullPendingSystemMessages();
   }
 
   /** IPC/RPC 意外断开时调度重连（指数退避） */
@@ -203,8 +244,10 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     this.#unregisterAgent?.();
     this.#unregisterAgent = undefined;
     this.#inboundDeduper.clear();
+    this.#inboxDeduper.clear();
     this.friends.clear();
     this.groups.clear();
+    this.#guildCatalog.clear();
     try {
       this.ipc?.close();
     } catch {
@@ -404,6 +447,181 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     }
   }
 
+  // ── 社交/群管（Console endpoint RPC 探测面）────────────────────────
+  // console-rpc-extended.ts 按方法名探测这些接口；全部薄封装走 IPC daemon。
+
+  /** EndpointManagement.listFriends —— 好友列表（LIST_FRIENDS，归一为 {user_id, nickname, remark}）。 */
+  async getFriendList(): Promise<Array<{ user_id: number; nickname: string; remark: string }>> {
+    const resp = await this.#mustRequest(Actions.LIST_FRIENDS, undefined, '获取好友列表');
+    const list = Array.isArray(resp.data) ? (resp.data as IpcFriendInfo[]) : [];
+    return list.map((f) => ({
+      user_id: f.user_id,
+      nickname: f.nickname,
+      remark: f.remark ?? '',
+    }));
+  }
+
+  /** EndpointManagement.listGroups —— 群列表（LIST_GROUPS，归一为 {group_id, name}）。 */
+  async getGroupList(): Promise<Array<{ group_id: number; name: string }>> {
+    const resp = await this.#mustRequest(Actions.LIST_GROUPS, undefined, '获取群列表');
+    const list = Array.isArray(resp.data) ? (resp.data as IpcGroupInfo[]) : [];
+    return list.map((g) => ({
+      group_id: g.group_id,
+      name: g.group_name,
+    }));
+  }
+
+  /** EndpointManagement.listGroupMembers —— 群成员列表（字段对齐 daemon 返回）。 */
+  async getGroupMemberList(groupId: number | string): Promise<IpcMemberInfo[]> {
+    const resp = await this.#mustRequest(
+      Actions.LIST_GROUP_MEMBERS,
+      { group_id: toNumericId(groupId, 'group_id') },
+      '获取群成员列表',
+    );
+    return Array.isArray(resp.data) ? (resp.data as IpcMemberInfo[]) : [];
+  }
+
+  /** getGroupMemberList 别名（console 探测 listMembers / getMemberList）。 */
+  listMembers(groupId: number | string): Promise<IpcMemberInfo[]> {
+    return this.getGroupMemberList(groupId);
+  }
+
+  getMemberList(groupId: number | string): Promise<IpcMemberInfo[]> {
+    return this.getGroupMemberList(groupId);
+  }
+
+  /**
+   * EndpointManagement.resolveRequest —— id 为 inbox 行的 platform_request_id。
+   * 先 GET_SYSTEM_MSG 按 flag（回退 seq）定位请求，再按类型路由 handle_friend/group_request。
+   */
+  async approveRequest(id: string, remark?: string): Promise<void> {
+    await this.#handleSystemRequest(id, true, { remark });
+  }
+
+  async rejectRequest(id: string, reason?: string): Promise<void> {
+    await this.#handleSystemRequest(id, false, { reason });
+  }
+
+  /** EndpointManagement.deleteFriend —— FRIEND_DELETE。 */
+  async deleteFriend(userId: number | string): Promise<void> {
+    await this.#mustRequest(
+      Actions.FRIEND_DELETE,
+      { user_id: toNumericId(userId, 'user_id') },
+      '删除好友',
+    );
+  }
+
+  /** deleteFriend 别名（console 探测 delete_friend）。 */
+  delete_friend(userId: number | string): Promise<void> {
+    return this.deleteFriend(userId);
+  }
+
+  /** EndpointManagement.kickGroupMember —— GROUP_KICK。 */
+  async removeMember(groupId: number | string, userId: number | string): Promise<void> {
+    await this.#mustRequest(
+      Actions.GROUP_KICK,
+      { group_id: toNumericId(groupId, 'group_id'), user_id: toNumericId(userId, 'user_id') },
+      '踢出群成员',
+    );
+  }
+
+  kickMember(groupId: number | string, userId: number | string): Promise<void> {
+    return this.removeMember(groupId, userId);
+  }
+
+  setGroupKick(groupId: number | string, userId: number | string): Promise<void> {
+    return this.removeMember(groupId, userId);
+  }
+
+  /** EndpointManagement.muteGroupMember —— GROUP_MUTE（duration 秒，默认 600）。 */
+  async muteMember(groupId: number | string, userId: number | string, duration = 600): Promise<void> {
+    await this.#mustRequest(
+      Actions.GROUP_MUTE,
+      {
+        group_id: toNumericId(groupId, 'group_id'),
+        user_id: toNumericId(userId, 'user_id'),
+        duration,
+      },
+      '禁言群成员',
+    );
+  }
+
+  banMember(groupId: number | string, userId: number | string, duration = 600): Promise<void> {
+    return this.muteMember(groupId, userId, duration);
+  }
+
+  setGroupMute(groupId: number | string, userId: number | string, duration = 600): Promise<void> {
+    return this.muteMember(groupId, userId, duration);
+  }
+
+  /** EndpointManagement.setGroupAdmin —— SET_GROUP_ADMIN（enable 默认 true）。 */
+  async setModerator(groupId: number | string, userId: number | string, enable = true): Promise<void> {
+    await this.#mustRequest(
+      Actions.SET_GROUP_ADMIN,
+      {
+        group_id: toNumericId(groupId, 'group_id'),
+        user_id: toNumericId(userId, 'user_id'),
+        enable,
+      },
+      '设置群管理员',
+    );
+  }
+
+  setAdmin(groupId: number | string, userId: number | string, enable = true): Promise<void> {
+    return this.setModerator(groupId, userId, enable);
+  }
+
+  setGroupAdmin(groupId: number | string, userId: number | string, enable = true): Promise<void> {
+    return this.setModerator(groupId, userId, enable);
+  }
+
+  /** IPC 请求并统一错误上下文：daemon 返回 ok=false 时抛出带操作名的错误。 */
+  async #mustRequest(
+    action: string,
+    params: Record<string, unknown> | undefined,
+    label: string,
+  ): Promise<IpcResponse> {
+    const resp = await this.request(action, params);
+    if (!resp.ok) {
+      throw new Error(`icqq ${label}失败: ${resp.error ?? 'daemon 未返回错误详情'}`);
+    }
+    return resp;
+  }
+
+  /** 按 flag/seq 在 GET_SYSTEM_MSG 中定位请求，路由到好友/群请求处理 action。 */
+  async #handleSystemRequest(
+    id: string,
+    approve: boolean,
+    extra: { remark?: string; reason?: string },
+  ): Promise<void> {
+    const resp = await this.#mustRequest(Actions.GET_SYSTEM_MSG, undefined, '获取待处理请求');
+    const data = resp.data as
+      | { friendRequests?: unknown; groupRequests?: unknown }
+      | undefined;
+    const friendRequests = Array.isArray(data?.friendRequests)
+      ? (data.friendRequests as IpcSystemMessage[])
+      : [];
+    const groupRequests = Array.isArray(data?.groupRequests)
+      ? (data.groupRequests as IpcSystemMessage[])
+      : [];
+    const matches = (m: IpcSystemMessage): boolean =>
+      m.flag === id || (m.seq != null && String(m.seq) === id);
+    const friend = friendRequests.find(matches);
+    const group = friend ? undefined : groupRequests.find(matches);
+    const target = friend ?? group;
+    if (!target?.flag) {
+      throw new Error(`icqq 未找到待处理请求: ${id}（GET_SYSTEM_MSG 中无匹配 flag/seq）`);
+    }
+    const params: Record<string, unknown> = { flag: target.flag, approve };
+    if (friend) {
+      if (extra.remark) params.remark = extra.remark;
+      await this.#mustRequest(Actions.HANDLE_FRIEND_REQUEST, params, '处理好友请求');
+    } else {
+      if (extra.reason) params.reason = extra.reason;
+      await this.#mustRequest(Actions.HANDLE_GROUP_REQUEST, params, '处理群请求');
+    }
+  }
+
   /** Test / internal: admit when open. */
   admit(msg: IcqqInboundMessage): void {
     if (!this.#open) return;
@@ -456,6 +674,14 @@ export class IcqqIpcEndpoint implements EndpointInstance {
     }
     const payload = unwrapIcqqIpcEventPayload(event);
     if (!payload || typeof payload !== 'object') return;
+    if (isIcqqRequestPayload(payload)) {
+      this.#recordInboxRequest(payload as Record<string, unknown>);
+      return;
+    }
+    if (isIcqqNoticePayload(payload)) {
+      this.#recordInboxNotice(payload as Record<string, unknown>);
+      return;
+    }
     if (!isIcqqMessagePostType(payload)) return;
     const data = payload as IcqqIpcMessageEvent;
     if (shouldSkipSelfInboundMessage(data)) return;
@@ -486,6 +712,7 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       payload as Parameters<typeof normalizeIcqqGuildInboundMessage>[0],
     );
     if (!normalized) return;
+    this.#guildCatalog.upsertFromInbound(normalized.raw);
     if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`)) return;
     this.admit({
       id: normalized.messageId,
@@ -503,6 +730,68 @@ export class IcqqIpcEndpoint implements EndpointInstance {
       },
     });
   }
+
+  /** 收件箱行公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
+  #inboxBase(): { adapter: string; endpointId: string } {
+    const id = String(this.#options.id);
+    return { adapter: id.split('\0').pop() ?? id, endpointId: this.name };
+  }
+
+  #recordInboxRequest(payload: Record<string, unknown>): void {
+    const hooks = this.#options.inbox;
+    if (!hooks) return;
+    const row = buildIcqqInboxRequestRow(payload, this.#inboxBase());
+    if (!row) return;
+    if (!this.#inboxDeduper.shouldProcess(`request:${String(row.platform_request_id)}`)) return;
+    void hooks.recordRequest(row);
+    hooks.publish?.('endpoint:request', row);
+  }
+
+  #recordInboxNotice(payload: Record<string, unknown>): void {
+    const hooks = this.#options.inbox;
+    if (!hooks) return;
+    const row = buildIcqqInboxNoticeRow(payload, this.#inboxBase());
+    if (!row) return;
+    if (!this.#inboxDeduper.shouldProcess(`notice:${String(row.platform_notice_id)}`)) return;
+    void hooks.recordNotice(row);
+    hooks.publish?.('endpoint:notice', row);
+  }
+
+  /** 启动/重连后首拉 GET_SYSTEM_MSG：补录离线期间的好友/群待处理请求。 */
+  async #pullPendingSystemMessages(): Promise<void> {
+    const hooks = this.#options.inbox;
+    if (!hooks || !this.ipc) return;
+    try {
+      const resp = await this.ipc.request(Actions.GET_SYSTEM_MSG);
+      if (!resp.ok) return;
+      const data = resp.data as
+        | { friendRequests?: unknown; groupRequests?: unknown }
+        | undefined;
+      const base = this.#inboxBase();
+      const rows = [
+        ...(Array.isArray(data?.friendRequests)
+          ? (data.friendRequests as IpcSystemMessage[]).map((m) =>
+            buildIcqqSystemRequestRow(m, 'friend', base))
+          : []),
+        ...(Array.isArray(data?.groupRequests)
+          ? (data.groupRequests as IpcSystemMessage[]).map((m) =>
+            buildIcqqSystemRequestRow(m, 'group', base))
+          : []),
+      ];
+      for (const row of rows) {
+        if (!row) continue;
+        if (!this.#inboxDeduper.shouldProcess(`request:${String(row.platform_request_id)}`)) continue;
+        void hooks.recordRequest(row);
+        hooks.publish?.('endpoint:request', row);
+      }
+    } catch (error) {
+      logger.debug(formatCompact({
+        op: 'inbox_pull_system_msg',
+        endpoint: this.name,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    }
+  }
 }
 
 /**
@@ -536,6 +825,15 @@ function buildIcqqQuoteMetadata(
   return metadata;
 }
 
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumericId(value: number | string, label: string): number {
+  const n = Number(value);
+  if (!Number.isFinite(n) || String(value).trim() === '') {
+    throw new TypeError(`icqq ${label} 必须是数字: ${String(value)}`);
+  }
+  return n;
+}
+
 async function defaultCreateIpc(config: ResolvedIcqqConfig): Promise<IcqqIpcTransport> {
   const uin = Number(config.name);
   if (config.rpc) {

package/src/icqq-guild.ts

@@ -3,9 +3,16 @@
  */
 import { toCanonicalSegments, type MessageSegment } from "zhin.js";
 import { Actions, type IpcGuildMessageEventData } from "./protocol.js";
-import type { IpcClient } from "./ipc-client.js";
 import { parseCqMessage } from "./cq-message.js";
 
+/** Narrow request port shared by the real IPC client and endpoint test transports. */
+export interface IcqqGuildRpc {
+  request(
+    action: string,
+    params?: Record<string, unknown>,
+  ): Promise<{ ok: boolean; data?: unknown }>;
+}
+
 export interface IcqqGuildChannelEntry {
   channel_id: string;
   channel_name: string;
@@ -36,7 +43,7 @@ export class IcqqGuildCatalog {
     this.guilds.clear();
   }
 
-  async syncAll(ipc: IpcClient): Promise<void> {
+  async syncAll(ipc: IcqqGuildRpc): Promise<void> {
     const listResp = await ipc.request(Actions.GUILD_LIST);
     if (!listResp.ok) return;
 

package/src/icqq-inbox.ts

@@ -0,0 +1,155 @@
+/**
+ * icqq IPC request/notice 事件 → 统一收件箱行（unified_inbox_request / unified_inbox_notice）。
+ *
+ * daemon 经 IpcEvent 推送 icqq client.em 分发的全部事件（见 protocol.ts），
+ * 好友/群请求（request.friend.add、request.group.add、request.group.invite）
+ * 与通知（notice.friend.*、notice.group.*）随事件流实时到达，无需轮询；
+ * endpoint 启动时补一次 GET_SYSTEM_MSG 拉取离线期间积存的待处理请求。
+ */
+import type { IpcSystemMessage } from './types.js';
+
+/** 行级公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
+export interface IcqqInboxBase {
+  readonly adapter: string;
+  readonly endpointId: string;
+}
+
+/** post_type=request / request.* 判定（OneBot 事件壳）。 */
+export function isIcqqRequestPayload(payload: unknown): boolean {
+  const postType = (payload as { post_type?: unknown } | null)?.post_type;
+  return typeof postType === 'string'
+    && (postType === 'request' || postType.startsWith('request.'));
+}
+
+/** post_type=notice / notice.* 判定。 */
+export function isIcqqNoticePayload(payload: unknown): boolean {
+  const postType = (payload as { post_type?: unknown } | null)?.post_type;
+  return typeof postType === 'string'
+    && (postType === 'notice' || postType.startsWith('notice.'));
+}
+
+/**
+ * request 事件载荷 → unified_inbox_request 行。
+ * platform_request_id 取 flag（审批回执句柄），缺省回退 seq；两者皆无则无法审批，丢弃。
+ */
+export function buildIcqqInboxRequestRow(
+  payload: Record<string, unknown>,
+  base: IcqqInboxBase,
+): Record<string, unknown> | null {
+  const userId = payload.user_id ?? payload.actor_id;
+  if (userId == null) return null;
+  const flag = asNonEmptyString(payload.flag);
+  const platformRequestId = flag ?? (payload.seq != null ? String(payload.seq) : '');
+  if (!platformRequestId) return null;
+  const requestType = asNonEmptyString(payload.request_type) ?? asNonEmptyString(payload.type);
+  const groupId = payload.group_id;
+  const isGroup = requestType === 'group' || groupId != null;
+  return {
+    adapter: base.adapter,
+    endpoint_id: base.endpointId,
+    platform_request_id: platformRequestId,
+    type: isGroup ? 'group' : (requestType ?? 'friend'),
+    scene_type: isGroup ? 'group' : null,
+    scene_id: String(groupId ?? userId),
+    sub_type: asNonEmptyString(payload.sub_type),
+    actor_id: String(userId),
+    actor_name: asNonEmptyString(payload.nickname),
+    comment: asNonEmptyString(payload.comment),
+    created_at: toMillis(payload.time),
+    resolved: 0,
+    resolved_at: null,
+    consumed: 0,
+    consumed_at: null,
+  };
+}
+
+/**
+ * notice 事件载荷 → unified_inbox_notice 行。
+ * 事件本身无稳定 id，platform_notice_id 由 time + actor + type 合成（配合去重）。
+ */
+export function buildIcqqInboxNoticeRow(
+  payload: Record<string, unknown>,
+  base: IcqqInboxBase,
+): Record<string, unknown> | null {
+  const noticeType = asNonEmptyString(payload.notice_type) ?? asNonEmptyString(payload.type);
+  if (!noticeType) return null;
+  const subType = asNonEmptyString(payload.sub_type);
+  const userId = payload.user_id;
+  const operatorId = payload.operator_id;
+  const groupId = payload.group_id;
+  const createdAt = toMillis(payload.time);
+  const actorId = operatorId ?? userId;
+  const platformNoticeId = asNonEmptyString(payload.notice_id)
+    ?? (payload.seq != null ? String(payload.seq) : undefined)
+    ?? `${createdAt}_${String(actorId ?? '')}_${noticeType}${subType ? `.${subType}` : ''}`;
+  const targetId = userId != null && String(userId) !== String(actorId ?? '') ? userId : undefined;
+  return {
+    adapter: base.adapter,
+    endpoint_id: base.endpointId,
+    platform_notice_id: platformNoticeId,
+    type: noticeType,
+    scene_type: groupId != null ? 'group' : null,
+    scene_id: String(groupId ?? userId ?? operatorId ?? ''),
+    sub_type: subType,
+    actor_id: actorId != null ? String(actorId) : null,
+    actor_name: asNonEmptyString(payload.nickname),
+    target_id: targetId != null ? String(targetId) : null,
+    target_name: null,
+    payload: safeJson(payload),
+    created_at: createdAt,
+    consumed: 0,
+    consumed_at: null,
+  };
+}
+
+/**
+ * GET_SYSTEM_MSG 返回项 → unified_inbox_request 行（启动时首次拉取）。
+ * friend 列表项 type 语义即好友请求；group 列表项 type 为 add/invite（记 sub_type）。
+ */
+export function buildIcqqSystemRequestRow(
+  message: IpcSystemMessage,
+  kind: 'friend' | 'group',
+  base: IcqqInboxBase,
+): Record<string, unknown> | null {
+  if (message.user_id == null) return null;
+  const platformRequestId = asNonEmptyString(message.flag)
+    ?? (message.seq != null ? String(message.seq) : '');
+  if (!platformRequestId) return null;
+  return {
+    adapter: base.adapter,
+    endpoint_id: base.endpointId,
+    platform_request_id: platformRequestId,
+    type: kind,
+    scene_type: kind === 'group' ? 'group' : null,
+    scene_id: String(kind === 'group' ? (message.group_id ?? message.user_id) : message.user_id),
+    sub_type: kind === 'group' ? (asNonEmptyString(message.type) ?? null) : null,
+    actor_id: String(message.user_id),
+    actor_name: asNonEmptyString(message.nickname),
+    comment: asNonEmptyString(message.comment),
+    created_at: toMillis(message.time),
+    resolved: 0,
+    resolved_at: null,
+    consumed: 0,
+    consumed_at: null,
+  };
+}
+
+function asNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+/** oicq 事件 time 为秒；缺失时回退当前时间。 */
+function toMillis(time: unknown): number {
+  const seconds = Number(time);
+  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : Date.now();
+}
+
+function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value ?? {});
+  } catch {
+    return '{}';
+  }
+}

package/src/index.ts

@@ -20,6 +20,7 @@ export {
   IcqqIpcEndpoint,
   type CreateIcqqIpc,
   type IcqqEndpointOptions,
+  type IcqqInboxHooks,
   type IcqqIpcTransport,
 } from './endpoint.js';
 

package/src/types.ts

@@ -76,3 +76,19 @@ export interface IpcMemberInfo {
   last_sent_time?: number;
   shutup_time?: number;
 }
+
+/**
+ * GET_SYSTEM_MSG 归一后的待处理请求（@icqqjs/cli NormalizedSystemMessage）。
+ * friendRequests 与 groupRequests 均为该形状，按 flag 处理。
+ */
+export interface IpcSystemMessage {
+  type: string;
+  user_id?: number;
+  nickname?: string;
+  group_id?: number;
+  group_name?: string;
+  comment?: string;
+  flag?: string;
+  seq?: number;
+  time?: number;
+}