@saiboniuma/realtime-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1044 @@
+import { HubConnection } from '@microsoft/signalr';
+
+/** 通用 API 响应 */
+export declare interface ApiResponse<T = unknown> {
+    code: number;
+    message: string;
+    type?: string;
+    data: T;
+}
+
+/** 分配的客服信息 */
+export declare interface AssignedAgentInfo {
+    agentUserId: string;
+    nickname: string;
+    avatar: string;
+    onlineStatus: KefuOnlineStatus;
+    isOnline: boolean;
+    welcomeMessage?: string;
+    autoSendWelcome: boolean;
+    /** 预计算的 Realtime 会话 ID */
+    conversationId?: string;
+    /** 会话群组 ID（统一群聊模式） */
+    groupId?: string;
+}
+
+/** 认证服务，处理 Token 获取和用户信息更新 */
+export declare class AuthService {
+    private baseURL;
+    constructor(baseURL: string);
+    /** 获取 Token（完整参数版） */
+    getToken(request: GetTokenRequest): Promise<GetTokenResponse>;
+    /** 获取 Token（简化参数版） */
+    getTokenSimple(platformKey: string, userId?: string, platformType?: PlatformType, options?: {
+        nickname?: string;
+        avatar?: string;
+        deviceId?: string;
+        metadata?: string;
+        source?: string;
+    }): Promise<GetTokenResponse>;
+    /** 更新用户信息 */
+    updateUserInfo(platformKey: string, deviceId: string, userId?: string, nickname?: string, avatar?: string): Promise<void>;
+}
+
+/** 聊天用户资料 */
+export declare interface ChatUserProfile {
+    userId: string;
+    userType: ChatUserType;
+    isNewUser: boolean;
+    nickname: string;
+    avatar: string;
+    externalUserId?: string;
+    deviceId?: string;
+    firstVisitTime?: string;
+    tags?: string[];
+    metadata?: Record<string, string>;
+}
+
+/** 聊天用户类型枚举 */
+export declare const ChatUserType: {
+    readonly Anonymous: 0;
+    readonly Authenticated: 1;
+    readonly VIP: 2;
+};
+
+export declare type ChatUserType = (typeof ChatUserType)[keyof typeof ChatUserType];
+
+/**
+ * 熔断器
+ * 三态模式：Closed -> Open -> HalfOpen -> Closed
+ */
+export declare class CircuitBreaker {
+    private readonly failureThreshold;
+    private readonly resetTimeout;
+    private readonly successThreshold;
+    private _state;
+    private failureCount;
+    private successCount;
+    private openTimestamp;
+    private stateChangeListeners;
+    constructor(options?: CircuitBreakerOptions);
+    /** 当前熔断器状态 */
+    get state(): CircuitState;
+    /** 注册状态变化监听 */
+    onStateChanged(callback: (data: CircuitStateChangedData) => void): void;
+    /** 移除状态变化监听 */
+    offStateChanged(callback: (data: CircuitStateChangedData) => void): void;
+    /** 切换状态 */
+    private transitionTo;
+    /** 记录成功 */
+    recordSuccess(): void;
+    /** 记录失败，达到阈值则打开 */
+    recordFailure(): void;
+    /** 是否可以尝试（半开时探测） */
+    canAttempt(): boolean;
+    /** 重置为关闭状态 */
+    reset(): void;
+}
+
+/** 熔断器配置 */
+export declare interface CircuitBreakerOptions {
+    /** 失败阈值，达到后熔断器打开，默认 10 */
+    failureThreshold?: number;
+    /** 重置超时时间（毫秒），打开状态持续多久后进入半开，默认 60000 */
+    resetTimeout?: number;
+    /** 半开状态下成功阈值，达到后熔断器关闭，默认 3 */
+    successThreshold?: number;
+}
+
+/** 熔断器状态 */
+export declare enum CircuitState {
+    /** 关闭状态：正常通行，记录失败次数 */
+    Closed = "Closed",
+    /** 打开状态：失败达到阈值，拒绝请求 */
+    Open = "Open",
+    /** 半开状态：超时后探测，尝试少量请求 */
+    HalfOpen = "HalfOpen"
+}
+
+/** 熔断器状态变化事件数据 */
+export declare interface CircuitStateChangedData {
+    from: CircuitState;
+    to: CircuitState;
+}
+
+/**
+ * 统一消息分类函数
+ */
+export declare function classifyMessage(message: Message): MessageClassification;
+
+/** 客户端设备信息 */
+export declare interface ClientDeviceInfo {
+    userAgent: string;
+    platform: string;
+    screenWidth: number;
+    screenHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    devicePixelRatio: number;
+    colorDepth: number;
+    connectionType?: string;
+    effectiveType?: string;
+    downlink?: number;
+    rtt?: number;
+    language: string;
+    languages: string[];
+    timezone: string;
+    timezoneOffset: number;
+    currentUrl: string;
+    pageTitle: string;
+    referrer: string;
+    touchSupport: boolean;
+    maxTouchPoints: number;
+    deviceMemory?: number;
+    hardwareConcurrency?: number;
+    cookieEnabled: boolean;
+    prefersDarkMode: boolean;
+    online: boolean;
+}
+
+/** 采集设备信息 */
+export declare function collectDeviceInfo(): ClientDeviceInfo;
+
+/** 连接状态枚举 */
+export declare const ConnectionStatus: {
+    readonly CONNECTING: 0;
+    readonly CONNECTED: 1;
+    readonly DISCONNECTED: 2;
+    readonly FAILED: 3;
+    readonly RECONNECTING: 4;
+};
+
+export declare type ConnectionStatus = (typeof ConnectionStatus)[keyof typeof ConnectionStatus];
+
+/** 会话对象 */
+export declare interface Conversation {
+    conversationID: string;
+    conversationType: number;
+    userID: string;
+    groupID: string;
+    showName: string;
+    faceURL: string;
+    recvMsgOpt: number;
+    unreadCount: number;
+    latestMsg: string;
+    latestMsgSendTime: number;
+    draftText: string;
+    draftTextTime: number;
+    isPinned: boolean;
+    isPrivateChat: boolean;
+}
+
+/** 会话服务（基于 SignalR Hub） */
+export declare class ConversationService {
+    private client;
+    constructor(client: IRealtimeClient_3);
+    /** 获取会话列表 */
+    getList(count?: number): Promise<Conversation[]>;
+    /** 根据用户 ID 获取单个会话 */
+    getOne(userID: string, sessionType?: number): Promise<Conversation | null>;
+    /** 加入会话组（接收该会话的实时消息推送） */
+    joinConversation(conversationId: string): Promise<void>;
+    /** 离开会话组 */
+    leaveConversation(conversationId: string): Promise<void>;
+    /** 获取历史消息 */
+    getHistory(conversationID: string, count?: number, startClientMsgID?: string): Promise<Message[]>;
+    /** 标记会话消息已读 */
+    markAsRead(conversationID: string): Promise<void>;
+}
+
+/** 创建 Realtime 核心客户端实例（工厂函数） */
+export declare function createRealtimeCore(config: RealtimeCoreConfig): RealtimeClient;
+
+/** 自定义消息元素 */
+export declare interface CustomElem {
+    data: string;
+    extension: string;
+    description: string;
+}
+
+/** 自定义图片消息数据 */
+export declare interface CustomImageData {
+    type: 'image';
+    url: string;
+    width: number;
+    height: number;
+    size: number;
+}
+
+/** 送达回执信息 */
+export declare interface DeliveryReceiptInfo {
+    conversationId: string;
+    userId: string;
+    seq: number;
+}
+
+/** 事件回调函数 */
+export declare type EventCallback<T = unknown> = (data: T) => void;
+
+/** 类型安全的事件管理器 */
+export declare class EventManager {
+    private listeners;
+    /** 注册事件监听 */
+    on<E extends RealtimeEventType>(event: E, callback: EventCallback<RealtimeEventMap[E]>): void;
+    /** 移除事件监听 */
+    off<E extends RealtimeEventType>(event: E, callback: EventCallback<RealtimeEventMap[E]>): void;
+    /** 触发事件 */
+    emit<E extends RealtimeEventType>(event: E, data: RealtimeEventMap[E]): void;
+    /** 清除所有事件监听 */
+    clear(): void;
+    /** 清除指定事件的所有监听 */
+    clearEvent(event: RealtimeEventType): void;
+}
+
+/** 功能开关 */
+export declare interface FeatureFlags {
+    allowImage: boolean;
+    allowFile: boolean;
+    allowVoice: boolean;
+    showOnlineStatus: boolean;
+    showReadStatus: boolean;
+    enableSatisfactionRating: boolean;
+    enableVisitorForm: boolean;
+    enableQueue: boolean;
+    enableBroadcast: boolean;
+}
+
+/** 获取或生成客户端 ID（持久化到 localStorage） */
+export declare function getClientId(): string;
+
+export declare function getLogLevel(): number;
+
+/**
+ * 获取消息的摘要文本（用于会话列表预览）
+ */
+export declare function getMessagePreview(message: Message): string;
+
+/** 获取系统消息的显示文本，非系统消息或 session_init 返回空字符串 */
+export declare function getSystemMessageLabel(message: Message): string;
+
+/** 从消息中提取系统消息类型，非系统消息返回 null */
+export declare function getSystemMessageType(message: Message): SystemMessageType | null;
+
+/** 获取 Token 请求参数 */
+export declare interface GetTokenRequest {
+    platformKey: string;
+    deviceId?: string;
+    userId?: string;
+    clientId?: string;
+    nickname?: string;
+    avatar?: string;
+    metadata?: string;
+    platformType?: PlatformType;
+    deviceInfo?: string;
+    /** 接入来源标识：js | vue | chat */
+    source?: string;
+}
+
+/** 获取 Token 响应 */
+export declare interface GetTokenResponse {
+    userID: string;
+    token: string;
+    expireTime: number;
+    user: ChatUserProfile;
+    agent: AssignedAgentInfo | null;
+    platform: PlatformConfigInfo | null;
+    features: FeatureFlags;
+    /** 排队信息（当并发会话超限时返回） */
+    queue?: QueueInfo;
+    /** 访客表单配置（启用时返回） */
+    visitorForm?: VisitorFormConfig;
+    /** Realtime 连接配置（服务端下发） */
+    realtimeConfig?: RealtimeConfig;
+}
+
+/** 检查是否已有客户端 ID */
+export declare function hasClientId(): boolean;
+
+/** RealtimeClient 接口（避免循环依赖） */
+declare interface IRealtimeClient {
+    login(userId: string, token: string): Promise<boolean>;
+}
+
+/** RealtimeClient 接口（避免循环依赖） */
+declare interface IRealtimeClient_2 {
+    getHub(): HubConnection;
+    getConversationId(): string;
+    getCurrentUserId(): string;
+}
+
+/** RealtimeClient 接口（避免循环依赖） */
+declare interface IRealtimeClient_3 {
+    getHub(): HubConnection;
+    getConversationId(): string;
+}
+
+/**
+ * 判断是否为应在聊天窗口中显示的系统消息
+ * session_init 不显示，其余（上线/离线/信息更新）显示
+ */
+export declare function isDisplayableSystemMessage(message: Message): boolean;
+
+/** 判断消息是否为系统消息 */
+export declare function isSystemMessage(message: Message): boolean;
+
+/** 客服在线状态枚举 */
+export declare const KefuOnlineStatus: {
+    readonly Offline: 0;
+    readonly Online: 1;
+    readonly Busy: 2;
+    readonly Away: 3;
+};
+
+export declare type KefuOnlineStatus = (typeof KefuOnlineStatus)[keyof typeof KefuOnlineStatus];
+
+export declare const logger: {
+    verbose: (tag: string, ...args: unknown[]) => false | void;
+    debug: (tag: string, ...args: unknown[]) => false | void;
+    info: (tag: string, ...args: unknown[]) => false | void;
+    warn: (tag: string, ...args: unknown[]) => false | void;
+    error: (tag: string, ...args: unknown[]) => false | void;
+};
+
+/** 将 C# RealtimeConversation 映射为 JS Conversation */
+export declare function mapToConversation(raw: any): Conversation | null;
+
+/** 将 C# RealtimeConversation 数组映射为 JS Conversation 数组 */
+export declare function mapToConversationList(raw: any): Conversation[];
+
+/** 将 C# RealtimeMessage 映射为 JS Message */
+export declare function mapToMessage(raw: any): Message | null;
+
+/** 将 C# RealtimeUserInfo 映射为 JS UserInfo */
+export declare function mapToUserInfo(raw: any): UserInfo | null;
+
+/** 消息对象 */
+export declare interface Message {
+    clientMsgID: string;
+    serverMsgID: string;
+    createTime: number;
+    sendTime: number;
+    sendID: string;
+    recvID: string;
+    msgFrom: number;
+    contentType: MessageType | number | string;
+    senderNickname: string;
+    senderFaceUrl: string;
+    content: string;
+    textElem?: TextElement;
+    pictureElem?: PictureElem;
+    customElem?: CustomElem;
+    conversationID: string;
+    isRead: boolean;
+    /** 消息状态（对应 MessageStatus） */
+    status: number;
+    /** 送达时间（ISO 字符串） */
+    deliveredAt?: string;
+    /** 已读时间（ISO 字符串） */
+    readAt?: string;
+    /** 编辑时间（ISO 字符串） */
+    editedAt?: string;
+    /** 编辑前内容 */
+    previousContent?: string;
+    /** 撤回标记（与 status=Withdrawn 同步） */
+    isWithdrawn?: boolean;
+}
+
+/** 消息分类结果 */
+export declare interface MessageClassification {
+    showInChat: boolean;
+    showInListPreview: boolean;
+    previewText: string;
+    systemType: SystemMessageType | null;
+    systemLabel: string;
+}
+
+/** 消息删除事件数据 */
+declare interface MessageDeletedInfo {
+    conversationId: string;
+    seq: number;
+}
+
+/** 数据解析工具 — SignalR 返回的数据已经是对象，无需 JSON.parse */
+export declare class MessageParser {
+    /** 透传数据（SignalR 自动反序列化 JSON 为对象） */
+    static parse<T>(data: unknown): T;
+}
+
+/** 消息收发服务（基于 SignalR Hub） */
+export declare class MessageService {
+    private client;
+    /** 前端消息类型注册表 */
+    readonly types: MessageTypeRegistry;
+    constructor(client: IRealtimeClient_2);
+    /** 判断是否为系统消息（静态方法，供外部调用） */
+    static isSystemMessage(message: Message): boolean;
+    /** 发送文本消息 */
+    sendText(_recvID: string, text: string, _isGroup?: boolean): Promise<Message>;
+    /** 发送图片消息 */
+    sendImage(_recvID: string, _file: File, imageUrl: string, imageInfo: {
+        width: number;
+        height: number;
+        size: number;
+        type: string;
+    }, _isGroup?: boolean): Promise<Message>;
+    /** 发送自定义消息 */
+    sendCustomMessage(_recvID: string, data: string, extension: string, description: string): Promise<Message>;
+    /** 发送系统消息（通用） */
+    sendSystemMessage(type: string, data: Record<string, unknown>): Promise<void>;
+    /** 发送用户信息更新系统消息 */
+    sendUserInfoUpdated(_agentUserID: string, updates: {
+        nickname?: string;
+        avatar?: string;
+        userId?: string;
+    }, previousValues?: {
+        nickname?: string;
+        avatar?: string;
+        userId?: string;
+    }): Promise<void>;
+    /** 发送会话初始化系统消息 */
+    sendSessionInit(_agentUserID: string, info: {
+        visitorId: string;
+        platformKey: string;
+        reason: 'login' | 'reconnect' | 'refresh';
+    }): Promise<void>;
+    /** 发送访客离线系统消息 */
+    sendVisitorOffline(_agentUserID: string, info: {
+        visitorId: string;
+        reason: string;
+        sessionDuration?: number;
+    }): Promise<void>;
+    /** 发送访客上线系统消息 */
+    sendVisitorOnline(_agentUserID: string, visitorInfo: {
+        visitorId: string;
+        deviceId: string;
+        nickname: string;
+        avatar: string;
+        isAnonymous: boolean;
+        userType?: number;
+        source: string;
+        platformType: number;
+        metadata?: Record<string, unknown>;
+        pageUrl?: string;
+        pageTitle?: string;
+        referrer?: string;
+    }): Promise<void>;
+    /**
+     * 上报消息送达（AcknowledgeDelivery）
+     * @param conversationId 会话 ID
+     * @param seq 消息序号
+     */
+    acknowledgeDelivery(conversationId: string, seq: number): Promise<void>;
+    /**
+     * 上报消息已读（AcknowledgeRead）
+     * @param conversationId 会话 ID
+     * @param lastReadSeq 最后已读消息序号
+     */
+    acknowledgeRead(conversationId: string, lastReadSeq: number): Promise<void>;
+    /**
+     * 撤回消息（WithdrawMessage）
+     * @param conversationId 会话 ID
+     * @param seq 消息序号
+     * @returns 撤回后的消息对象（status=Withdrawn），失败返回 null
+     */
+    withdraw(conversationId: string, seq: number): Promise<Message | null>;
+    /**
+     * 编辑消息（EditMessage）
+     * @param conversationId 会话 ID
+     * @param seq 消息序号
+     * @param newContent 新内容
+     * @returns 编辑后的消息对象（status=Edited），失败返回 null
+     */
+    edit(conversationId: string, seq: number, newContent: string): Promise<Message | null>;
+    /**
+     * 删除消息（DeleteMessage）
+     * @param conversationId 会话 ID
+     * @param seq 消息序号
+     */
+    deleteMessage(conversationId: string, seq: number): Promise<void>;
+}
+
+/** 消息状态枚举（8 态） */
+export declare const MessageStatus: {
+    readonly Sending: 1;
+    readonly Sent: 2;
+    /** @deprecated 请使用 MessageStatus.Sent，值相同，向后兼容 */
+    readonly Success: 2;
+    readonly Delivered: 3;
+    readonly Read: 4;
+    readonly Failed: 5;
+    readonly Withdrawn: 6;
+    readonly Edited: 7;
+    readonly Deleted: 8;
+};
+
+export declare type MessageStatus = (typeof MessageStatus)[keyof typeof MessageStatus];
+
+/** 消息类型枚举（数字类型 + 命名空间字符串类型） */
+export declare const MessageType: {
+    readonly TextMessage: 101;
+    readonly PictureMessage: 102;
+    readonly VoiceMessage: 103;
+    readonly VideoMessage: 104;
+    readonly FileMessage: 105;
+    readonly AtTextMessage: 106;
+    readonly MergeMessage: 107;
+    readonly CardMessage: 108;
+    readonly LocationMessage: 109;
+    readonly CustomMessage: 110;
+    readonly TypingMessage: 113;
+    readonly QuoteMessage: 114;
+    readonly FaceMessage: 115;
+    readonly SystemNotice: "system.notice";
+    readonly SystemMember: "system.member";
+    readonly SystemMute: "system.mute";
+    readonly CallVoice: "call.voice";
+    readonly CallVideo: "call.video";
+    readonly CallMissed: "call.missed";
+    readonly InteractPoke: "interact.poke";
+    readonly InteractShake: "interact.shake";
+    readonly InteractFlash: "interact.flash";
+};
+
+export declare type MessageType = (typeof MessageType)[keyof typeof MessageType];
+
+/** 消息类型处理器 */
+export declare interface MessageTypeHandler {
+    onClick?(message: any): void;
+}
+
+/**
+ * 前端消息类型注册表
+ *
+ * 用于注册自定义消息类型的渲染器和处理器，
+ * 支持业务层动态扩展消息类型的展示与交互逻辑。
+ */
+export declare class MessageTypeRegistry {
+    private types;
+    /**
+     * 注册一种消息类型
+     * @param typeName 消息类型名称（如 'custom.card'）
+     * @param renderer 渲染器
+     * @param handler 处理器（可选）
+     */
+    register(typeName: string, renderer: MessageTypeRenderer, handler?: MessageTypeHandler): void;
+    /**
+     * 尝试解析已注册的消息类型
+     * @param typeName 消息类型名称
+     * @returns 渲染器与处理器，或 null（未注册）
+     */
+    tryResolve(typeName: string): {
+        renderer: MessageTypeRenderer;
+        handler: MessageTypeHandler;
+    } | null;
+    /**
+     * 判断某类型是否已注册
+     * @param typeName 消息类型名称
+     */
+    isRegistered(typeName: string): boolean;
+}
+
+/** 消息类型渲染器 */
+export declare interface MessageTypeRenderer {
+    canRender(message: any): boolean;
+    render(message: any, container: HTMLElement): void;
+}
+
+/** 消息撤回事件数据 */
+declare interface MessageWithdrawnInfo {
+    conversationId: string;
+    seq: number;
+    message?: Message;
+}
+
+/** 图片基础信息 */
+export declare interface Picture {
+    uuid: string;
+    type: string;
+    size: number;
+    width: number;
+    height: number;
+    url: string;
+}
+
+/** 图片消息元素 */
+export declare interface PictureElem {
+    sourcePath: string;
+    sourcePicture: Picture;
+    bigPicture: Picture;
+    snapshotPicture: Picture;
+}
+
+/** 平台配置信息 */
+export declare interface PlatformConfigInfo {
+    platformId: number;
+    platformName: string;
+    domain?: string;
+    logo?: string;
+    offlineMessage?: string;
+    allowOfflineMessage: boolean;
+    isWorkingHours: boolean;
+    nonWorkingMessage?: string;
+}
+
+/** 平台类型枚举 */
+export declare const PlatformType: {
+    readonly Web: 0;
+    readonly iOS: 1;
+    readonly Android: 2;
+    readonly Windows: 3;
+    readonly MacOS: 4;
+    readonly Linux: 5;
+};
+
+export declare type PlatformType = (typeof PlatformType)[keyof typeof PlatformType];
+
+/** 排队信息 */
+export declare interface QueueInfo {
+    isQueued: boolean;
+    position: number;
+    totalWaiting: number;
+    estimatedWaitMinutes: number;
+}
+
+/** C2C 已读回执信息 */
+export declare interface ReadReceiptInfo {
+    userID: string;
+    msgIDList: string[];
+    readTime: number;
+    sessionType: number;
+}
+
+/** Realtime 核心客户端（基于 SignalR） */
+export declare class RealtimeClient {
+    private config;
+    private hub;
+    private currentUserId;
+    private currentToken;
+    private currentConversationId;
+    private hubListenersRegistered;
+    private heartbeatTimer;
+    /** 连接状态 */
+    private _connectionStatus;
+    /** 主动关闭标志（logout/destroy 时设置，断开不触发重连） */
+    private _isManualClose;
+    /** 重连管理器 */
+    private reconnectManager;
+    /** 熔断器 */
+    private circuitBreaker;
+    /** 事件管理器 */
+    readonly events: EventManager;
+    /** 认证服务 */
+    readonly auth: AuthService;
+    /** 会话管理 */
+    readonly session: SessionManager;
+    /** Token 自动续期 */
+    readonly tokenRefresher: TokenRefresher;
+    /** 消息服务 */
+    readonly message: MessageService;
+    /** 会话服务 */
+    readonly conversation: ConversationService;
+    /** 文件上传服务 */
+    readonly upload: UploadService;
+    constructor(config: RealtimeCoreConfig);
+    /** 获取当前连接状态 */
+    get connectionStatus(): ConnectionStatus;
+    /** 设置连接状态 */
+    private setConnectionStatus;
+    /** 获取 Hub 连接实例 */
+    getHub(): HubConnection;
+    /** 获取当前会话 ID */
+    getConversationId(): string;
+    /** 设置当前会话 ID（登录后由外部设置） */
+    setConversationId(conversationId: string): void;
+    /** 获取配置 */
+    getConfig(): RealtimeCoreConfig;
+    /** 动态更新 Realtime 服务器地址（用于接收服务端下发的配置） */
+    updateRealtimeAddrs(wsUrl: string): void;
+    /** 检查是否已连接 */
+    isConnected(): Promise<boolean>;
+    /** 登录 — 建立 SignalR 连接 */
+    login(userId: string, token: string): Promise<boolean>;
+    /** 登出 */
+    logout(): Promise<void>;
+    /** 获取当前登录用户 ID */
+    getCurrentUserId(): string;
+    /** 启动心跳定时器（间隔从配置读取，默认 15 秒） */
+    private startHeartbeat;
+    /** 停止心跳定时器 */
+    private stopHeartbeat;
+    /** 启动重连流程 */
+    private startReconnect;
+    /** 执行单次重连尝试（由 ReconnectManager 回调） */
+    private handleReconnectAttempt;
+    /** 重连最终失败回调 */
+    private handleReconnectFinalFail;
+    /** 获取当前登录用户信息（通过 Hub 查询） */
+    getUserInfo(): Promise<UserInfo | null>;
+    /** 注册事件监听（快捷方法） */
+    on<E extends RealtimeEventType>(event: E, callback: EventCallback<RealtimeEventMap[E]>): void;
+    /** 移除事件监听（快捷方法） */
+    off<E extends RealtimeEventType>(event: E, callback: EventCallback<RealtimeEventMap[E]>): void;
+    /** 销毁客户端实例，清理所有资源 */
+    destroy(): void;
+    /** 注册 Hub 事件监听器（仅注册一次） */
+    private setupHubListeners;
+    /** 解析消息数据（自动映射 C# RealtimeMessage → JS Message） */
+    private parseMessage;
+    /** 通用数据解析 */
+    private parseData;
+}
+
+/** Realtime 连接配置（服务端下发） */
+export declare interface RealtimeConfig {
+    /** API 基础地址 */
+    apiUrl: string;
+    /** Realtime Hub WebSocket 地址 */
+    wsUrl: string;
+}
+
+/** Realtime 核心库配置 */
+export declare interface RealtimeCoreConfig {
+    /** Realtime Hub WebSocket 地址（可选，支持服务端下发） */
+    wsAddr?: string;
+    /** 业务后端 API 地址 */
+    baseURL: string;
+    /** 平台密钥 */
+    platformKey: string;
+    /** 日志级别（0=Error, 1=Warn, 2=Info, 3=Debug, 4=Verbose） */
+    logLevel?: number;
+    /** 重连配置 */
+    reconnect?: {
+        /** 最大重试次数，默认 10 */
+        maxRetries?: number;
+        /** 基础延迟（毫秒），默认 1000 */
+        baseDelay?: number;
+        /** 最大延迟（毫秒），默认 30000 */
+        maxDelay?: number;
+        /** 抖动因子（0~1），默认 0.2 */
+        jitterFactor?: number;
+    };
+    /** 熔断器配置 */
+    circuitBreaker?: {
+        /** 失败阈值，达到后熔断器打开，默认 10 */
+        failureThreshold?: number;
+        /** 重置超时时间（毫秒），打开状态持续多久后进入半开，默认 60000 */
+        resetTimeout?: number;
+        /** 半开状态下成功阈值，达到后熔断器关闭，默认 3 */
+        successThreshold?: number;
+    };
+    /** 心跳间隔（毫秒），默认 15000 */
+    heartbeatInterval?: number;
+}
+
+/** 事件数据映射 */
+export declare interface RealtimeEventMap {
+    'connection:connecting': undefined;
+    'connection:success': undefined;
+    'connection:failed': unknown;
+    'connection:reconnecting': {
+        attempt: number;
+    };
+    'connection:circuit-open': undefined;
+    'connection:circuit-half-open': undefined;
+    'kicked:offline': undefined;
+    'token:expired': undefined;
+    'sync:finished': undefined;
+    'sync:failed': unknown;
+    'message:received': Message;
+    'message:received:raw': Message;
+    'message:read-receipt': ReadReceiptInfo[];
+    'message:delivered': DeliveryReceiptInfo;
+    'message:withdrawn': MessageWithdrawnInfo;
+    'message:edited': Message;
+    'message:deleted': MessageDeletedInfo;
+    'conversation:changed': Conversation[];
+    'conversation:new': {
+        conversationId: string;
+        visitorName?: string;
+    };
+}
+
+/** 事件类型（冒号分隔） */
+export declare type RealtimeEventType = 'connection:connecting' | 'connection:success' | 'connection:failed' | 'connection:reconnecting' | 'connection:circuit-open' | 'connection:circuit-half-open' | 'kicked:offline' | 'token:expired' | 'sync:finished' | 'sync:failed' | 'message:received' | 'message:received:raw' | 'message:read-receipt' | 'message:delivered' | 'message:withdrawn' | 'message:edited' | 'message:deleted' | 'conversation:changed' | 'conversation:new';
+
+/** 插件接口（预留） */
+export declare interface RealtimePlugin {
+    /** 插件名称 */
+    name: string;
+    /** 插件版本 */
+    version: string;
+    /** 安装插件 */
+    install(client: RealtimeClient): void;
+    /** 卸载插件 */
+    uninstall?(): void;
+}
+
+/** 重连事件类型 */
+export declare type ReconnectEvent = 'reconnecting' | 'reconnected' | 'failed';
+
+/** 重连事件回调 */
+export declare type ReconnectEventCallback = (attempt: number) => void;
+
+/**
+ * 重连管理器
+ * 实现指数退避 + 抖动算法，与 C# RetryUtil 算法一致
+ */
+export declare class ReconnectManager {
+    private readonly maxRetries;
+    private readonly baseDelay;
+    private readonly maxDelay;
+    private readonly jitterFactor;
+    private readonly useExponentialBackoff;
+    private _currentAttempt;
+    private _isRetrying;
+    private retryTimer;
+    private stopped;
+    private readonly onReconnect;
+    private readonly onFinalFail;
+    private readonly eventListeners;
+    constructor(options: ReconnectManagerOptions, onReconnect: (attempt: number) => Promise<void>, onFinalFail: () => void);
+    /** 当前重试次数 */
+    get currentAttempt(): number;
+    /** 是否正在重连中 */
+    get isRetrying(): boolean;
+    /** 注册事件监听 */
+    on(event: ReconnectEvent, callback: ReconnectEventCallback): void;
+    /** 移除事件监听 */
+    off(event: ReconnectEvent, callback: ReconnectEventCallback): void;
+    /** 触发事件 */
+    private emit;
+    /**
+     * 计算下次重试延迟
+     * 指数退避 + 抖动算法
+     */
+    private calculateDelay;
+    /** 开始重连流程 */
+    start(): void;
+    /** 安排下一次重试 */
+    private scheduleNextRetry;
+    /** 停止重连（主动关闭时调用） */
+    stop(): void;
+    /** 重置重试计数（连接成功后调用） */
+    reset(): void;
+}
+
+/** 重连管理器配置 */
+export declare interface ReconnectManagerOptions {
+    /** 最大重试次数，默认 10 */
+    maxRetries?: number;
+    /** 基础延迟（毫秒），默认 1000 */
+    baseDelay?: number;
+    /** 最大延迟（毫秒），默认 30000 */
+    maxDelay?: number;
+    /** 抖动因子（0~1），默认 0.2 */
+    jitterFactor?: number;
+    /** 是否使用指数退避，默认 true */
+    useExponentialBackoff?: boolean;
+}
+
+/** RefreshSession 响应 */
+declare interface RefreshSessionResponse {
+    token: string;
+    expireTimeSeconds: number;
+    agentUserId: string | null;
+    agentOnline: boolean;
+}
+
+/** 重置客户端 ID */
+export declare function resetClientId(): string;
+
+/** 会话持久化管理器（基于 localStorage） */
+export declare class SessionManager {
+    /** 保存认证数据到 localStorage */
+    saveAuthData(data: GetTokenResponse): void;
+    /** 从 localStorage 加载认证数据（过期则返回 null） */
+    loadAuthData(): StoredSessionData | null;
+    /** 清除认证数据 */
+    clearAuthData(): void;
+    /** 更新本地存储中的用户资料 */
+    updateUserProfile(updates: {
+        nickname?: string;
+        avatar?: string;
+    }): void;
+}
+
+export declare function setLogLevel(level: number): void;
+
+/** 会话数据（含过期时间） */
+declare interface StoredSessionData extends GetTokenResponse {
+    expireAt: number;
+}
+
+/** 所有系统消息类型值数组（用于 isSystemMessage 判断） */
+export declare const SYSTEM_MESSAGE_TYPES: ("session_init" | "visitor_online" | "visitor_offline" | "user_info_updated" | "message_read")[];
+
+declare type SystemMessageType = (typeof SystemMsg)[keyof typeof SystemMsg];
+
+/**
+ * 系统消息类型常量 — 与 C# SystemMessageTypes.cs 对齐
+ *
+ * 系统消息使用 contentType=110 (CustomMessage)，
+ * data.type 标识具体类型，extension 包含 {systemMessage:true, notDisplay:true}。
+ */
+export declare const SystemMsg: {
+    readonly SessionInit: "session_init";
+    readonly VisitorOnline: "visitor_online";
+    readonly VisitorOffline: "visitor_offline";
+    readonly UserInfoUpdated: "user_info_updated";
+    readonly MessageRead: "message_read";
+};
+
+/** 文本消息元素 */
+export declare interface TextElement {
+    content: string;
+}
+
+/** Token 自动续期管理器 */
+export declare class TokenRefresher {
+    private authService;
+    private client;
+    private lastLoginRequest;
+    private active;
+    private baseURL;
+    private chatUserId;
+    private clientId;
+    private platformKey;
+    /** 当 agent 因滑落而变化时触发 */
+    onAgentChanged: ((newAgentUserId: string) => void) | null;
+    constructor(authService: AuthService, client: IRealtimeClient);
+    /** 设置上次登录请求参数（用于自动续期） */
+    setLastLoginRequest(request: GetTokenRequest): void;
+    /** 设置容灾恢复所需的参数 */
+    setSessionInfo(info: {
+        baseURL: string;
+        chatUserId: string;
+        clientId: string;
+        platformKey: string;
+    }): void;
+    /** Token 过期时的自动刷新回调 */
+    refresh(): Promise<void>;
+    /** 容灾恢复：调用 RefreshSession 做完整重置 */
+    refreshSession(): Promise<RefreshSessionResponse>;
+    /** 是否已激活 */
+    isActive(): boolean;
+    /** 停止自动续期 */
+    stop(): void;
+}
+
+/** 更新用户信息请求 */
+export declare interface UpdateUserInfoRequest {
+    platformKey: string;
+    deviceId: string;
+    userId?: string;
+    nickname?: string;
+    avatar?: string;
+}
+
+/** 上传响应 */
+export declare interface UploadResponse {
+    fileName: string;
+    absfileName: string;
+}
+
+/** 文件上传服务 */
+export declare class UploadService {
+    private baseURL;
+    constructor(baseURL: string);
+    /** 上传文件 */
+    uploadFile(file: File): Promise<UploadResponse>;
+    /** 获取图片宽高 */
+    getImageDimensions(file: File): Promise<{
+        width: number;
+        height: number;
+    }>;
+}
+
+/** 用户信息 */
+export declare interface UserInfo {
+    userID: string;
+    nickname: string;
+    faceURL: string;
+    createTime: number;
+    ex: string;
+}
+
+/** 访客表单配置 */
+export declare interface VisitorFormConfig {
+    formId: number;
+    formName: string;
+    formFields: VisitorFormField[];
+    isRequired: boolean;
+}
+
+/** 访客表单字段 */
+export declare interface VisitorFormField {
+    key: string;
+    label: string;
+    type: 'text' | 'email' | 'phone' | 'select' | 'textarea';
+    required: boolean;
+    placeholder?: string;
+    options?: string[];
+}
+
+export { }