easemob-websdk 4.24.1 → 5.0.0

package/types/event-system.d.ts

@@ -0,0 +1,721 @@
+/**
+ * 统一事件系统类型定义
+ */
+import type { ConnectionEventName as ConnectionEventNameType, ConnectionEventPayload, InternalEventName as InternalEventNameType, SendTimeoutEventPayload, TokenLifecycleEventPayload } from './connection';
+import type { Message, StreamMessage } from './index';
+import type { ConversationListUpdatePayload } from '../cache/cache-types';
+import type { ChatThreadCreatedEventPayload, ChatThreadDestroyedEventPayload, ChatThreadRawNotifyEvent, ChatThreadUpdatedEventPayload, ChatThreadUserRemovedEventPayload } from './chat-thread';
+import type { ContactRosterEventPayload, ContactInfoUpdatedEvent } from './contact';
+import type { SyncDataFinishedPayload, SyncDataStartPayload } from './sync-data';
+import type { ChatRoomAdminAddedEventPayload, ChatRoomAdminRemovedEventPayload, ChatRoomAllMemberMuteStateChangedEventPayload, ChatRoomAnnouncementChangedEventPayload, ChatRoomAttributesRemovedEventPayload, ChatRoomAttributesUpdateEventPayload, ChatRoomAllowListAddedEventPayload, ChatRoomAllowListRemovedEventPayload, ChatRoomDestroyedEventPayload, ChatRoomInfoChangedEventPayload, ChatRoomMembersExitedEventPayload, ChatRoomMembersJoinedEventPayload, ChatRoomMuteListAddedEventPayload, ChatRoomMuteListRemovedEventPayload, ChatRoomOwnerChangedEventPayload, ChatRoomRawNotifyEvent, ChatRoomRemovedFromChatRoomEventPayload } from './chatroom';
+import type { GroupAdminAddedEventPayload, GroupAdminRemovedEventPayload, GroupAllMemberMuteStateChangedEventPayload, GroupAnnouncementChangedEventPayload, GroupAutoAcceptInvitationEventPayload, GroupDestroyedEventPayload, GroupInvitationAcceptedEventPayload, GroupInvitationDeclinedEventPayload, GroupInvitationReceivedEventPayload, GroupMemberAttributeChangedEventPayload, GroupDisabledChangedEventPayload, GroupInfoChangedEventPayload, GroupMembersExitedEventPayload, GroupMembersJoinedEventPayload, GroupMuteListAddedEventPayload, GroupMuteListRemovedEventPayload, GroupOwnerChangedEventPayload, GroupRawNotifyEvent, GroupRequestToJoinAcceptedEventPayload, GroupRequestToJoinDeclinedEventPayload, GroupRequestToJoinReceivedEventPayload, GroupSharedFileAddedEventPayload, GroupSharedFileDeletedEventPayload, GroupUserGroupNamecardUpdatedEventPayload, GroupUserRemovedEventPayload, GroupAllowListAddedEventPayload, GroupAllowListRemovedEventPayload } from './group';
+import type { PresenceState } from './presence';
+import type { UserInfo, UserInfoRawNotifyEvent } from './user-info';
+import type { MessageDeliveredEventPayload, MessageReceiptEventPayload, MessageRecalledEventPayload, MessageUpdatedEventPayload, PinnedMessageChangedEventPayload, ReactionChangedEventPayload } from './chat-manager';
+import type { MultiDeviceContactEvent, MultiDeviceConversationEvent, MultiDeviceGroupEvent, MultiDeviceMessageRemovedEvent, MultiDeviceThreadEvent } from './multi-device';
+/**
+ * [zh-CN] 连接事件名称。
+ * [en-US] Connection event name.
+ */
+export type ConnectionEventName = ConnectionEventNameType;
+/** @internal 内部事件名称。 */
+export type InternalEventName = InternalEventNameType;
+/**
+ * [zh-CN] Chat 事件名称常量。
+ * [en-US] Chat event name constants.
+ */
+export declare const ChatEventName: {
+    readonly MESSAGE: "onMessage";
+    readonly STREAM_MESSAGE: "onStreamMessage";
+    readonly CONVERSATION_LIST_UPDATE: "onConversationListUpdate";
+    readonly MESSAGE_READ_RECEIPTS: "onMessageReadReceipts";
+    readonly MESSAGE_DELIVERED: "onMessageDelivered";
+    readonly MESSAGE_RECALLED: "onMessageRecalled";
+    readonly MESSAGE_UPDATED: "onMessageUpdated";
+    readonly REACTION_CHANGED: "onReactionChanged";
+    readonly PINNED_MESSAGE_CHANGED: "onPinnedMessageChanged";
+    readonly MULTI_DEVICE_CONTACT: "onMultiDeviceContact";
+    readonly MULTI_DEVICE_GROUP: "onMultiDeviceGroup";
+    readonly MULTI_DEVICE_THREAD: "onMultiDeviceThread";
+    readonly MULTI_DEVICE_CONVERSATION: "onMultiDeviceConversation";
+    readonly MULTI_DEVICE_MESSAGE_REMOVED: "onMultiDeviceMessageRemoved";
+    readonly SYNC_DATA_START: "onSyncDataStart";
+    readonly SYNC_DATA_FINISHED: "onSyncDataFinished";
+};
+/**
+ * [zh-CN] Chat 事件名称。
+ * [en-US] Chat event name.
+ */
+export type ChatEventName = (typeof ChatEventName)[keyof typeof ChatEventName];
+/**
+ * [zh-CN] 消息话题事件名称常量。
+ * [en-US] Chat thread event name constants.
+ */
+export declare const ChatThreadEventName: {
+    readonly CREATED: "onChatThreadCreated";
+    readonly DESTROYED: "onChatThreadDestroyed";
+    readonly UPDATED: "onChatThreadUpdated";
+    readonly USER_REMOVED: "onChatThreadUserRemoved";
+};
+/**
+ * [zh-CN] 消息话题事件名称。
+ * [en-US] Chat thread event name.
+ */
+export type ChatThreadEventName = (typeof ChatThreadEventName)[keyof typeof ChatThreadEventName];
+export declare const PresenceEventName: {
+    readonly STATUS_CHANGE: "onPresenceStatusChange";
+};
+export type PresenceEventName = (typeof PresenceEventName)[keyof typeof PresenceEventName];
+export declare const ContactEventName: {
+    readonly INVITED: "onContactInvited";
+    readonly DELETED: "onContactDeleted";
+    readonly ADDED: "onContactAdded";
+    readonly REFUSE: "onContactRefuse";
+    readonly AGREED: "onContactAgreed";
+    readonly CONTACT_INFO_UPDATED: "onContactInfoUpdated";
+};
+export type ContactEventName = (typeof ContactEventName)[keyof typeof ContactEventName];
+export declare const UserInfoEventName: {
+    readonly OWN_UPDATED: "onOwnInfoUpdated";
+    readonly USER_UPDATED: "onUserInfoUpdated";
+};
+export type UserInfoEventName = (typeof UserInfoEventName)[keyof typeof UserInfoEventName];
+export declare const GroupEventName: {
+    readonly INVITATION_RECEIVED: "onInvitationReceived";
+    readonly REQUEST_TO_JOIN_RECEIVED: "onRequestToJoinReceived";
+    readonly REQUEST_TO_JOIN_ACCEPTED: "onRequestToJoinAccepted";
+    readonly REQUEST_TO_JOIN_DECLINED: "onRequestToJoinDeclined";
+    readonly INVITATION_ACCEPTED: "onInvitationAccepted";
+    readonly INVITATION_DECLINED: "onInvitationDeclined";
+    readonly USER_REMOVED: "onUserRemoved";
+    readonly GROUP_DESTROYED: "onGroupDestroyed";
+    readonly AUTO_ACCEPT_INVITATION: "onAutoAcceptInvitationFromGroup";
+    readonly MUTE_LIST_ADDED: "onMuteListAdded";
+    readonly MUTE_LIST_REMOVED: "onMuteListRemoved";
+    readonly ALLOW_LIST_ADDED: "onAllowListAdded";
+    readonly ALLOW_LIST_REMOVED: "onAllowListRemoved";
+    readonly ALL_MEMBER_MUTE_STATE_CHANGED: "onAllMemberMuteStateChanged";
+    readonly ADMIN_ADDED: "onAdminAdded";
+    readonly ADMIN_REMOVED: "onAdminRemoved";
+    readonly OWNER_CHANGED: "onOwnerChanged";
+    readonly MEMBERS_JOINED: "onMembersJoined";
+    readonly MEMBERS_EXITED: "onMembersExited";
+    readonly ANNOUNCEMENT_CHANGED: "onAnnouncementChanged";
+    readonly SHARED_FILE_ADDED: "onSharedFileAdded";
+    readonly SHARED_FILE_DELETED: "onSharedFileDeleted";
+    readonly GROUP_INFO_CHANGED: "onGroupInfoChanged";
+    readonly GROUP_DISABLED_CHANGED: "onGroupDisabledChanged";
+    readonly GROUP_MEMBER_ATTRIBUTE_CHANGED: "onGroupMemberAttributeChanged";
+    readonly USER_GROUP_NAMECARD_UPDATED: "onUserGroupNamecardUpdated";
+};
+export type GroupEventName = (typeof GroupEventName)[keyof typeof GroupEventName];
+export declare const ChatRoomDispatchEventName: {
+    readonly CHAT_ROOM_DESTROYED: "__chatroom:onChatRoomDestroyed";
+    readonly MEMBERS_JOINED: "__chatroom:onMembersJoined";
+    readonly MEMBERS_EXITED: "__chatroom:onMembersExited";
+    readonly REMOVED_FROM_CHAT_ROOM: "__chatroom:onRemovedFromChatRoom";
+    readonly MUTE_LIST_ADDED: "__chatroom:onMuteListAdded";
+    readonly MUTE_LIST_REMOVED: "__chatroom:onMuteListRemoved";
+    readonly ALLOW_LIST_ADDED: "__chatroom:onAllowListAdded";
+    readonly ALLOW_LIST_REMOVED: "__chatroom:onAllowListRemoved";
+    readonly ALL_MEMBER_MUTE_STATE_CHANGED: "__chatroom:onAllMemberMuteStateChanged";
+    readonly ADMIN_ADDED: "__chatroom:onAdminAdded";
+    readonly ADMIN_REMOVED: "__chatroom:onAdminRemoved";
+    readonly OWNER_CHANGED: "__chatroom:onOwnerChanged";
+    readonly ANNOUNCEMENT_CHANGED: "__chatroom:onAnnouncementChanged";
+    readonly CHAT_ROOM_INFO_CHANGED: "__chatroom:onChatRoomInfoChanged";
+    readonly ATTRIBUTES_UPDATE: "__chatroom:onAttributesUpdate";
+    readonly ATTRIBUTES_REMOVED: "__chatroom:onAttributesRemoved";
+};
+export type ChatRoomDispatchEventName = (typeof ChatRoomDispatchEventName)[keyof typeof ChatRoomDispatchEventName];
+/**
+ * [zh-CN] SDK 事件名称联合类型。
+ * [en-US] Union of SDK event names.
+ */
+export type EventName = ConnectionEventName | ChatEventName | ChatThreadEventName | InternalEventName | PresenceEventName | ContactEventName | UserInfoEventName | GroupEventName | ChatRoomDispatchEventName;
+/**
+ * [zh-CN] SDK 事件名称到事件载荷的映射。
+ * [en-US] Mapping from SDK event names to event payloads.
+ */
+export interface EventPayloadMap {
+    /** [zh-CN] 正在连接到服务器（含自动重连）。 [en-US] Connecting to server (including auto-reconnect). */
+    onConnecting: ConnectionEventPayload;
+    /** [zh-CN] 成功连接到服务器。 [en-US] Successfully connected to server. */
+    onConnected: ConnectionEventPayload;
+    /**
+     * [zh-CN] 与服务器断开连接。断开原因包括：主动登出、Token 过期、被踢下线、设备超限等。
+     * [en-US] Disconnected from server. Reasons include: logout, token expired, kicked, device limit exceeded, etc.
+     */
+    onDisconnected: ConnectionEventPayload;
+    /** [zh-CN] 自动重连失败（达到最大重试次数）。 [en-US] Auto-reconnect failed (max retries reached). */
+    onReconnectFailed: ConnectionEventPayload;
+    /**
+     * [zh-CN] Token 即将过期（约 80% 生命周期时触发）。应在此时获取新 Token 并调用 renewToken。
+     * [en-US] Token will expire soon (triggered at ~80% lifetime). Fetch a new token and call renewToken.
+     */
+    onTokenWillExpire: TokenLifecycleEventPayload;
+    /** [zh-CN] Token 已过期，需要重新登录。 [en-US] Token has expired, re-login required. */
+    onTokenExpired: TokenLifecycleEventPayload;
+    /** [zh-CN] 登录或重连后首次开始拉取离线消息；同一连接周期的后续心跳不会重复触发。 [en-US] The first offline message sync started after login or reconnection; subsequent heartbeats in the same connection cycle do not trigger it again. */
+    onOfflineMessageSyncStart: undefined;
+    /** [zh-CN] 登录或重连后的首次离线消息拉取完成；与 `onOfflineMessageSyncStart` 在每个连接周期内最多各触发一次。 [en-US] The first offline message sync after login or reconnection finished; this event and `onOfflineMessageSyncStart` are each emitted at most once per connection cycle. */
+    onOfflineMessageSyncFinish: undefined;
+    /**
+     * [zh-CN] 收到新消息。
+     * 触发时机：有新消息到达（含单聊、群聊、聊天室）。
+     * 接收方：消息接收方（含发送方的其他设备）。
+     * [en-US] New message received.
+     * Triggered when: a new message arrives (single/group/chatroom).
+     * Received by: message recipient (including sender's other devices).
+     */
+    onMessage: Message;
+    /**
+     * [zh-CN] 流式消息更新。
+     * 触发时机：流式消息（如 AI 生成内容）有增量更新。
+     * 接收方：消息接收方。
+     * [en-US] Stream message update.
+     * Triggered when: a stream message (e.g., AI-generated content) has incremental updates.
+     * Received by: message recipient.
+     */
+    onStreamMessage: StreamMessage;
+    /**
+     * [zh-CN] 会话列表有更新。事件载荷始终包含当前完整且已排序的 ConversationItem 快照；需要保留业务本地字段时，可结合 patch.reset、patch.upserted、patch.removed 与 patch.orderChanged 做增量合并。
+     * [en-US] Conversation list updated. The payload always contains the current full and ordered ConversationItem snapshot; apps that preserve app-local fields can merge incrementally with patch.reset, patch.upserted, patch.removed, and patch.orderChanged.
+     */
+    onConversationListUpdate: ConversationListUpdatePayload;
+    /**
+     * [zh-CN] 消息已读回执列表。
+     * 触发时机：对方发送一条或多条消息已读回执。
+     * 接收方：消息的原始发送方。
+     * [en-US] Message read receipt list.
+     * Triggered when: recipient sends one or more read receipts.
+     * Received by: original message sender.
+     */
+    onMessageReadReceipts: ReadonlyArray<MessageReceiptEventPayload>;
+    /**
+     * [zh-CN] 消息送达回执。
+     * 触发时机：接收方 SDK 自动回送达回执后，发送方收到此事件。
+     * 接收方：消息的原始发送方。
+     * [en-US] Message delivery receipt.
+     * Triggered when: recipient's SDK auto-sends delivery ack.
+     * Received by: original message sender.
+     */
+    onMessageDelivered: MessageDeliveredEventPayload;
+    /**
+     * [zh-CN] 消息被撤回。
+     * 触发时机：发送方撤回消息，或群主/管理员撤回他人消息。
+     * 接收方：除当前操作设备外的会话成员，以及撤回者的其他设备。
+     * [en-US] Message recalled.
+     * Triggered when: sender recalls a message, or group owner/admin recalls another's message.
+     * Received by: conversation members and the recaller's other devices, except the operating device.
+     */
+    onMessageRecalled: MessageRecalledEventPayload;
+    /**
+     * [zh-CN] 消息被编辑。
+     * 触发时机：发送方编辑已发送的消息。
+     * 接收方：除当前操作设备外的会话成员，以及编辑者的其他设备。
+     * [en-US] Message updated (edited).
+     * Triggered when: sender edits a sent message.
+     * Received by: conversation members and the editor's other devices, except the operating device.
+     */
+    onMessageUpdated: MessageUpdatedEventPayload;
+    /**
+     * [zh-CN] 消息 Reaction 变更。
+     * 触发时机：有成员对消息添加或移除 Reaction。
+     * 接收方：会话中的所有成员（仅单聊和群聊）。
+     * [en-US] Message reaction changed.
+     * Triggered when: a member adds or removes a reaction.
+     * Received by: all members in the conversation (single/group chat only).
+     */
+    onReactionChanged: ReactionChangedEventPayload;
+    /**
+     * [zh-CN] 消息置顶状态变更。
+     * 触发时机：有成员置顶或取消置顶消息。
+     * 接收方：除当前操作设备外的会话成员，以及当前用户的其他设备。
+     * [en-US] Pinned message changed.
+     * Triggered when: a member pins or unpins a message.
+     * Received by: conversation members and the current user's other devices, except the device performing the operation.
+     */
+    onPinnedMessageChanged: PinnedMessageChangedEventPayload;
+    /**
+     * [zh-CN] ChatThread 创建事件。接收方：子区所属群组的所有成员。
+     * [en-US] Chat thread created event. Received by all members of the parent group.
+     */
+    onChatThreadCreated: ChatThreadCreatedEventPayload;
+    /**
+     * [zh-CN] ChatThread 解散事件。接收方：子区所属群组的所有成员。
+     * [en-US] Chat thread destroyed event. Received by all members of the parent group.
+     */
+    onChatThreadDestroyed: ChatThreadDestroyedEventPayload;
+    /**
+     * [zh-CN] ChatThread 更新事件。修改子区名称，或子区中添加、撤销回复消息时触发。接收方：子区所属群组的所有成员。
+     * [en-US] Chat thread updated event. Triggered when the thread name changes, or a reply message is added or recalled. Received by all members of the parent group.
+     */
+    onChatThreadUpdated: ChatThreadUpdatedEventPayload;
+    /**
+     * [zh-CN] 当前登录用户被群主或群管理员移出 ChatThread。接收方：被移出的当前登录用户。
+     * [en-US] Current user removed from a chat thread by the group owner or admin. Received by the removed current user.
+     */
+    onChatThreadUserRemoved: ChatThreadUserRemovedEventPayload;
+    /**
+     * [zh-CN] 联系人相关多设备事件。
+     * 触发时机：当前用户在其他设备上执行联系人操作（添加/删除/黑名单等）。
+     * 接收方：当前用户的其他在线设备。
+     * [en-US] Multi-device contact event.
+     * Received by: current user's other online devices.
+     */
+    onMultiDeviceContact: MultiDeviceContactEvent;
+    /**
+     * [zh-CN] 群组相关多设备事件。
+     * 触发时机：当前用户在其他设备上执行群组操作。
+     * 接收方：当前用户的其他在线设备。
+     * [en-US] Multi-device group event.
+     * Received by: current user's other online devices.
+     */
+    onMultiDeviceGroup: MultiDeviceGroupEvent;
+    /**
+     * [zh-CN] Thread 相关多设备事件。
+     * 触发时机：当前用户在其他设备上执行 Thread 操作。
+     * 接收方：当前用户的其他在线设备。
+     * [en-US] Multi-device thread event.
+     * Received by: current user's other online devices.
+     */
+    onMultiDeviceThread: MultiDeviceThreadEvent;
+    /**
+     * [zh-CN] 会话相关多设备事件。
+     * 触发时机：当前用户在其他设备上执行会话操作（删除/置顶/标记/免打扰等）。
+     * 接收方：当前用户的其他在线设备。
+     * [en-US] Multi-device conversation event.
+     * Received by: current user's other online devices.
+     */
+    onMultiDeviceConversation: MultiDeviceConversationEvent;
+    /**
+     * [zh-CN] 消息删除多设备事件。
+     * 触发时机：当前用户在其他设备上删除漫游消息。
+     * 接收方：当前用户的其他在线设备。
+     * [en-US] Multi-device message removed event.
+     * Received by: current user's other online devices.
+     */
+    onMultiDeviceMessageRemoved: MultiDeviceMessageRemovedEvent;
+    /** [zh-CN] 自动数据同步开始。 [en-US] Automatic data sync started. */
+    onSyncDataStart: SyncDataStartPayload;
+    /** [zh-CN] 自动数据同步完成。 [en-US] Automatic data sync finished. */
+    onSyncDataFinished: SyncDataFinishedPayload;
+    /** @internal 发送超时内部事件。 */
+    /** @internal 消息发送超时内部事件。 */
+    onSendTimeout: SendTimeoutEventPayload;
+    /**
+     * [zh-CN] 订阅的用户在线状态变更。
+     * 触发时机：已订阅的用户在线状态发生变化。
+     * 接收方：订阅方。
+     * [en-US] Subscribed user presence status changed.
+     * Triggered when: a subscribed user's presence status changes.
+     * Received by: the subscriber.
+     */
+    onPresenceStatusChange: ReadonlyArray<PresenceState>;
+    /**
+     * [zh-CN] 收到好友请求。
+     * 触发时机：其他用户向当前用户发送好友请求。
+     * 接收方：被邀请方。
+     * [en-US] Contact invitation received.
+     * Received by: the invited user.
+     */
+    onContactInvited: ContactRosterEventPayload;
+    /**
+     * [zh-CN] 被对方删除联系人。
+     * 触发时机：对方将当前用户从联系人列表中删除。
+     * 接收方：被删除方。
+     * [en-US] Removed from contact list by the other party.
+     * Received by: the removed user.
+     */
+    onContactDeleted: ContactRosterEventPayload;
+    /**
+     * [zh-CN] 新增联系人。
+     * 触发时机：好友关系建立成功。
+     * 接收方：双方。
+     * [en-US] New contact added.
+     * Triggered when: friend relationship established.
+     * Received by: both parties.
+     */
+    onContactAdded: ContactRosterEventPayload;
+    /**
+     * [zh-CN] 好友请求被拒绝。
+     * 触发时机：对方拒绝了当前用户的好友请求。
+     * 接收方：请求发起方。
+     * [en-US] Contact invitation declined.
+     * Received by: the invitation sender.
+     */
+    onContactRefuse: ContactRosterEventPayload;
+    /**
+     * [zh-CN] 好友请求被接受。
+     * 触发时机：对方接受了当前用户的好友请求。
+     * 接收方：请求发起方。
+     * [en-US] Contact invitation accepted.
+     * Received by: the invitation sender.
+     */
+    onContactAgreed: ContactRosterEventPayload;
+    /**
+     * [zh-CN] 联系人信息变更。
+     * 触发时机：已订阅的联系人信息发生变化。
+     * 接收方：订阅方。
+     * [en-US] Contact info updated.
+     * Received by: the subscriber.
+     */
+    onContactInfoUpdated: ContactInfoUpdatedEvent;
+    /**
+     * [zh-CN] 自己的用户属性被修改。
+     * 触发时机：当前用户的属性被修改（含其他设备修改）。
+     * 接收方：当前用户所有设备。
+     * [en-US] Own user info updated.
+     * Received by: all devices of the current user.
+     */
+    onOwnInfoUpdated: UserInfo;
+    /**
+     * [zh-CN] 订阅的用户属性变更。
+     * 触发时机：已订阅的用户属性发生变化。
+     * 接收方：订阅方。
+     * [en-US] Subscribed user info updated.
+     * Received by: the subscriber.
+     */
+    onUserInfoUpdated: ReadonlyArray<UserInfo>;
+    /** @internal */
+    /** @internal 群组原始通知内部事件。 */
+    onGroupNotify: GroupRawNotifyEvent;
+    /** @internal */
+    /** @internal 聊天室原始通知内部事件。 */
+    onChatRoomNotify: ChatRoomRawNotifyEvent;
+    /** @internal */
+    /** @internal 消息话题原始通知内部事件。 */
+    onChatThreadNotify: ChatThreadRawNotifyEvent;
+    /** @internal */
+    /** @internal 用户资料原始通知内部事件。 */
+    onUserInfoNotify: UserInfoRawNotifyEvent;
+    /** @internal */
+    /** @internal 消息发送完成内部事件。 */
+    '__internal:onMessageSent': Message;
+    /**
+     * [zh-CN] 收到入群邀请。接收方：被邀请者。
+     * [en-US] Group invitation received. Received by: the invited user.
+     */
+    onInvitationReceived: GroupInvitationReceivedEventPayload;
+    /**
+     * [zh-CN] 收到入群申请。接收方：群主和管理员。
+     * [en-US] Group join request received. Received by: group owner and admins.
+     */
+    onRequestToJoinReceived: GroupRequestToJoinReceivedEventPayload;
+    /**
+     * [zh-CN] 入群申请被同意。接收方：申请者。
+     * [en-US] Group join request accepted. Received by: the applicant.
+     */
+    onRequestToJoinAccepted: GroupRequestToJoinAcceptedEventPayload;
+    /**
+     * [zh-CN] 入群申请被拒绝。接收方：申请者。
+     * [en-US] Group join request declined. Received by: the applicant.
+     */
+    onRequestToJoinDeclined: GroupRequestToJoinDeclinedEventPayload;
+    /**
+     * [zh-CN] 入群邀请被接受。接收方：邀请发起者。
+     * [en-US] Group invitation accepted. Received by: the invitation sender.
+     */
+    onInvitationAccepted: GroupInvitationAcceptedEventPayload;
+    /**
+     * [zh-CN] 入群邀请被拒绝。接收方：邀请发起者。
+     * [en-US] Group invitation declined. Received by: the invitation sender.
+     */
+    onInvitationDeclined: GroupInvitationDeclinedEventPayload;
+    /**
+     * [zh-CN] 被移出群组。接收方：被移出者 + 群内所有成员。
+     * [en-US] Removed from group. Received by: the removed user + all group members.
+     */
+    onUserRemoved: GroupUserRemovedEventPayload;
+    /**
+     * [zh-CN] 群组被解散。接收方：群内所有成员。
+     * [en-US] Group destroyed. Received by: all group members.
+     */
+    onGroupDestroyed: GroupDestroyedEventPayload;
+    /**
+     * [zh-CN] 自动接受入群邀请（群设置为不需要确认时）。接收方：被邀请者。
+     * [en-US] Auto-accepted group invitation. Received by: the invited user.
+     */
+    onAutoAcceptInvitationFromGroup: GroupAutoAcceptInvitationEventPayload;
+    /**
+     * [zh-CN] 成员被禁言。接收方：群内所有成员。
+     * [en-US] Member muted. Received by: all group members.
+     */
+    onMuteListAdded: GroupMuteListAddedEventPayload;
+    /**
+     * [zh-CN] 成员被解除禁言。接收方：群内所有成员。
+     * [en-US] Member unmuted. Received by: all group members.
+     */
+    onMuteListRemoved: GroupMuteListRemovedEventPayload;
+    /**
+     * [zh-CN] 成员加入白名单。接收方：群内所有成员。
+     * [en-US] Member added to allowlist. Received by: all group members.
+     */
+    onAllowListAdded: GroupAllowListAddedEventPayload;
+    /**
+     * [zh-CN] 成员移出白名单。接收方：群内所有成员。
+     * [en-US] Member removed from allowlist. Received by: all group members.
+     */
+    onAllowListRemoved: GroupAllowListRemovedEventPayload;
+    /**
+     * [zh-CN] 全员禁言状态变更。接收方：群内所有成员。
+     * [en-US] All-member mute state changed. Received by: all group members.
+     */
+    onAllMemberMuteStateChanged: GroupAllMemberMuteStateChangedEventPayload;
+    /**
+     * [zh-CN] 新增管理员。接收方：群内所有成员。
+     * [en-US] Admin added. Received by: all group members.
+     */
+    onAdminAdded: GroupAdminAddedEventPayload;
+    /**
+     * [zh-CN] 移除管理员。接收方：群内所有成员。
+     * [en-US] Admin removed. Received by: all group members.
+     */
+    onAdminRemoved: GroupAdminRemovedEventPayload;
+    /**
+     * [zh-CN] 群主变更。接收方：群内所有成员。
+     * [en-US] Group owner changed. Received by: all group members.
+     */
+    onOwnerChanged: GroupOwnerChangedEventPayload;
+    /**
+     * [zh-CN] 新成员加入群组。接收方：群内所有成员。
+     * [en-US] New member joined group. Received by: all group members.
+     */
+    onMembersJoined: GroupMembersJoinedEventPayload;
+    /**
+     * [zh-CN] 成员退出群组。接收方：群内所有成员。
+     * [en-US] Member left group. Received by: all group members.
+     */
+    onMembersExited: GroupMembersExitedEventPayload;
+    /**
+     * [zh-CN] 群公告变更。接收方：群内所有成员。
+     * [en-US] Group announcement changed. Received by: all group members.
+     */
+    onAnnouncementChanged: GroupAnnouncementChangedEventPayload;
+    /**
+     * [zh-CN] 新增群共享文件。接收方：群内所有成员。
+     * [en-US] Group shared file added. Received by: all group members.
+     */
+    onSharedFileAdded: GroupSharedFileAddedEventPayload;
+    /**
+     * [zh-CN] 删除群共享文件。接收方：群内所有成员。
+     * [en-US] Group shared file deleted. Received by: all group members.
+     */
+    onSharedFileDeleted: GroupSharedFileDeletedEventPayload;
+    /**
+     * [zh-CN] 群信息变更。接收方：群内所有成员。
+     * [en-US] Group info changed. Received by: all group members.
+     */
+    onGroupInfoChanged: GroupInfoChangedEventPayload;
+    /**
+     * [zh-CN] 群组禁用状态变更。接收方：群内所有成员。
+     * [en-US] Group disabled state changed. Received by: all group members.
+     */
+    onGroupDisabledChanged: GroupDisabledChangedEventPayload;
+    /**
+     * [zh-CN] 群成员自定义属性变更。接收方：群内所有成员。
+     * [en-US] Group member attribute changed. Received by: all group members.
+     */
+    onGroupMemberAttributeChanged: GroupMemberAttributeChangedEventPayload;
+    /**
+     * [zh-CN] 群名片变更。接收方：群内所有成员。
+     * [en-US] Group namecard updated. Received by: all group members.
+     */
+    onUserGroupNamecardUpdated: GroupUserGroupNamecardUpdatedEventPayload;
+    /**
+     * [zh-CN] 聊天室被销毁。接收方：聊天室内所有成员。
+     * [en-US] Chat room destroyed. Received by: all chat room members.
+     */
+    '__chatroom:onChatRoomDestroyed': ChatRoomDestroyedEventPayload;
+    /**
+     * [zh-CN] 成员加入聊天室。接收方：聊天室内所有成员。
+     * [en-US] Member joined chat room. Received by: all chat room members.
+     */
+    '__chatroom:onMembersJoined': ChatRoomMembersJoinedEventPayload;
+    /**
+     * [zh-CN] 成员离开聊天室。接收方：聊天室内所有成员。
+     * [en-US] Member left chat room. Received by: all chat room members.
+     */
+    '__chatroom:onMembersExited': ChatRoomMembersExitedEventPayload;
+    /**
+     * [zh-CN] 被移出聊天室。接收方：被移出者 + 聊天室内所有成员。
+     * [en-US] Removed from chat room. Received by: removed user + all chat room members.
+     */
+    '__chatroom:onRemovedFromChatRoom': ChatRoomRemovedFromChatRoomEventPayload;
+    /**
+     * [zh-CN] 成员被禁言。接收方：聊天室内所有成员。
+     * [en-US] Member muted. Received by: all chat room members.
+     */
+    '__chatroom:onMuteListAdded': ChatRoomMuteListAddedEventPayload;
+    /**
+     * [zh-CN] 成员被解除禁言。接收方：聊天室内所有成员。
+     * [en-US] Member unmuted. Received by: all chat room members.
+     */
+    '__chatroom:onMuteListRemoved': ChatRoomMuteListRemovedEventPayload;
+    /**
+     * [zh-CN] 成员加入白名单。接收方：聊天室内所有成员。
+     * [en-US] Member added to allowlist. Received by: all chat room members.
+     */
+    '__chatroom:onAllowListAdded': ChatRoomAllowListAddedEventPayload;
+    /**
+     * [zh-CN] 成员移出白名单。接收方：聊天室内所有成员。
+     * [en-US] Member removed from allowlist. Received by: all chat room members.
+     */
+    '__chatroom:onAllowListRemoved': ChatRoomAllowListRemovedEventPayload;
+    /**
+     * [zh-CN] 全员禁言状态变更。接收方：聊天室内所有成员。
+     * [en-US] All-member mute state changed. Received by: all chat room members.
+     */
+    '__chatroom:onAllMemberMuteStateChanged': ChatRoomAllMemberMuteStateChangedEventPayload;
+    /**
+     * [zh-CN] 新增管理员。接收方：聊天室内所有成员。
+     * [en-US] Admin added. Received by: all chat room members.
+     */
+    '__chatroom:onAdminAdded': ChatRoomAdminAddedEventPayload;
+    /**
+     * [zh-CN] 移除管理员。接收方：聊天室内所有成员。
+     * [en-US] Admin removed. Received by: all chat room members.
+     */
+    '__chatroom:onAdminRemoved': ChatRoomAdminRemovedEventPayload;
+    /**
+     * [zh-CN] 聊天室主变更。接收方：聊天室内所有成员。
+     * [en-US] Chat room owner changed. Received by: all chat room members.
+     */
+    '__chatroom:onOwnerChanged': ChatRoomOwnerChangedEventPayload;
+    /**
+     * [zh-CN] 聊天室公告变更。接收方：聊天室内所有成员。
+     * [en-US] Chat room announcement changed. Received by: all chat room members.
+     */
+    '__chatroom:onAnnouncementChanged': ChatRoomAnnouncementChangedEventPayload;
+    /**
+     * [zh-CN] 聊天室信息变更。接收方：聊天室内所有成员。
+     * [en-US] Chat room info changed. Received by: all chat room members.
+     */
+    '__chatroom:onChatRoomInfoChanged': ChatRoomInfoChangedEventPayload;
+    /**
+     * [zh-CN] 聊天室自定义属性更新。接收方：聊天室内所有成员。
+     * [en-US] Chat room attributes updated. Received by: all chat room members.
+     */
+    '__chatroom:onAttributesUpdate': ChatRoomAttributesUpdateEventPayload;
+    /**
+     * [zh-CN] 聊天室自定义属性删除。接收方：聊天室内所有成员。
+     * [en-US] Chat room attributes removed. Received by: all chat room members.
+     */
+    '__chatroom:onAttributesRemoved': ChatRoomAttributesRemovedEventPayload;
+}
+/**
+ * [zh-CN] 连接事件载荷映射。
+ * [en-US] Connection event payload map.
+ */
+export type ConnectionEventPayloadMap = Pick<EventPayloadMap, ConnectionEventName>;
+/** @inline */
+type EventHandlerResult = void | Promise<void>;
+/**
+ * [zh-CN] 连接事件处理器映射。
+ * [en-US] Connection event handler map.
+ */
+export type ConnectionEventHandlerMap = Partial<{
+    [K in ConnectionEventName]: (payload: ConnectionEventPayloadMap[K]) => EventHandlerResult;
+}>;
+/**
+ * [zh-CN] Chat 事件载荷映射。
+ * [en-US] Chat event payload map.
+ */
+export type ChatEventPayloadMap = Pick<EventPayloadMap, ChatEventName>;
+/**
+ * [zh-CN] Chat 事件处理器映射。
+ * [en-US] Chat event handler map.
+ */
+export type ChatEventHandlerMap = Partial<{
+    [K in ChatEventName]: (payload: ChatEventPayloadMap[K]) => EventHandlerResult;
+}>;
+/**
+ * [zh-CN] 消息话题事件载荷映射。
+ * [en-US] Chat thread event payload map.
+ */
+export type ChatThreadEventPayloadMap = Pick<EventPayloadMap, ChatThreadEventName>;
+/**
+ * [zh-CN] 消息话题事件处理器映射。
+ * [en-US] Chat thread event handler map.
+ */
+export type ChatThreadEventHandlerMap = Partial<{
+    [K in ChatThreadEventName]: (payload: ChatThreadEventPayloadMap[K]) => EventHandlerResult;
+}>;
+/**
+ * [zh-CN] 多设备事件载荷映射。
+ * [en-US] Multi-device event payload map.
+ */
+export type MultiDeviceEventPayloadMap = Pick<EventPayloadMap, 'onMultiDeviceContact' | 'onMultiDeviceGroup' | 'onMultiDeviceThread' | 'onMultiDeviceConversation' | 'onMultiDeviceMessageRemoved'>;
+/**
+ * [zh-CN] 多设备事件处理器映射。
+ * [en-US] Multi-device event handler map.
+ */
+export type MultiDeviceEventHandlerMap = Partial<{
+    [K in keyof MultiDeviceEventPayloadMap]: (payload: MultiDeviceEventPayloadMap[K]) => EventHandlerResult;
+}>;
+/**
+ * [zh-CN] 在线状态事件载荷映射。
+ * [en-US] Presence event payload map.
+ */
+export type PresenceEventPayloadMap = Pick<EventPayloadMap, PresenceEventName>;
+/**
+ * [zh-CN] 在线状态事件处理器映射。
+ * [en-US] Presence event handler map.
+ */
+export type PresenceEventHandlerMap = Partial<{
+    [K in PresenceEventName]: (payload: PresenceEventPayloadMap[K]) => EventHandlerResult;
+}>;
+/**
+ * [zh-CN] 联系人事件载荷映射。
+ * [en-US] Contact event payload map.
+ */
+export type ContactEventPayloadMap = Pick<EventPayloadMap, ContactEventName>;
+/**
+ * [zh-CN] 联系人事件处理器映射。
+ * [en-US] Contact event handler map.
+ */
+export type ContactEventHandlerMap = Partial<{
+    [K in ContactEventName]: (payload: ContactEventPayloadMap[K]) => EventHandlerResult;
+}>;
+/**
+ * [zh-CN] 用户资料事件载荷映射。
+ * [en-US] User profile event payload map.
+ */
+export type UserInfoEventPayloadMap = Pick<EventPayloadMap, UserInfoEventName>;
+/**
+ * [zh-CN] 用户资料事件处理器映射。
+ * [en-US] User profile event handler map.
+ */
+export type UserInfoEventHandlerMap = Partial<{
+    [K in UserInfoEventName]: (payload: UserInfoEventPayloadMap[K]) => EventHandlerResult;
+}>;
+/**
+ * [zh-CN] 群组事件载荷映射。
+ * [en-US] Group event payload map.
+ */
+export type GroupEventPayloadMap = Pick<EventPayloadMap, GroupEventName>;
+/**
+ * [zh-CN] 群组事件处理器映射。
+ * [en-US] Group event handler map.
+ */
+export type GroupEventHandlerMap = Partial<{
+    [K in GroupEventName]: (payload: GroupEventPayloadMap[K]) => EventHandlerResult;
+}>;
+export type ChatRoomInternalEventPayloadMap = Pick<EventPayloadMap, ChatRoomDispatchEventName>;
+export type ChatRoomInternalEventHandlerMap = Partial<{
+    [K in ChatRoomDispatchEventName]: (payload: ChatRoomInternalEventPayloadMap[K]) => EventHandlerResult;
+}>;
+/**
+ * [zh-CN] 所有 SDK 事件的通用处理器映射。
+ * [en-US] Generic handler map for all SDK events.
+ */
+export type EventHandlerMap = Partial<{
+    [K in EventName]: (payload: EventPayloadMap[K]) => EventHandlerResult;
+}>;
+/**
+ * [zh-CN] 事件处理器注册 ID。
+ * [en-US] Event handler registration ID.
+ */
+export type EventHandlerId = string;
+export {};