sim-sdk-web
Version:
Sim SDK for Web
489 lines (488 loc) • 16.9 kB
TypeScript
import { HistoryMessageParam, ServerResponse, Request, MessageItem, ReqPageParam, MarkConversationReadParam, HistoryMessageResponse, GroupPermission, UpdateGroupPermission, UpdateGroupMemberPermission, LiveMessageParam, MuteMembersParams, KickGroupMemberParams } from '../types/entity';
import type { LoginParams, UploadFileParams } from '../types/params';
import { RequestApi } from '../constant/api';
import Emitter from '../utils/emitter';
import { GroupType } from '../types/enum';
import { HttpMethod } from '../utils/request';
import { UserService } from './user';
import { GroupService } from './group';
import { MessageService } from './message';
import { ConversationService } from './conversation';
interface SDKConfig {
username?: string;
token?: string;
appKey?: string;
apiAddr?: string;
ossApiAddr?: string;
debug: boolean;
isLive: boolean;
anonLogin?: boolean;
connectTimeout?: number;
maxRetries?: number;
}
interface SDKOptions {
debug?: boolean;
isLive?: boolean;
apiAddr?: string;
ossApiAddr?: string;
appKey?: string;
connectTimeout?: number;
maxRetries?: number;
}
/**
* SIMSDK主类 - 实时通信SDK的入口点
*/
declare class SIMSDK extends Emitter {
private config;
private internalState;
private cacheManager;
private sseClient?;
private readonly serviceManager;
private conversationSyncTimer?;
private syncInterval;
private isSyncing;
private lastFetchTtl;
/**
* 创建SIMSDK实例
* @param debug 是否启用调试模式
*/
constructor(debug?: boolean);
/**
* 启动会话同步定时任务
* @param interval 可选的同步间隔时间(毫秒)
*/
startConversationSync(interval?: number): void;
/**
* 停止会话同步定时任务
*/
stopConversationSync(): void;
/**
* 立即执行一次会话同步
*/
syncConversationsNow(): Promise<void>;
/**
* 同步会话列表与服务器
* 检查每个会话是否有新消息，并更新相应的会话
* 异常补充
*/
private syncConversationsWithServer;
/**
* 清理和释放资源
*/
destroy(): void;
/**
* 配置SDK
* @param options SDK配置选项
*/
configure: (options: SDKOptions) => void;
/**
* 获取指定服务实例
* @param name 服务名称
* @returns 服务实例
*/
private getService;
/**
* 消息服务访问器
*/
get message(): MessageService;
/**
* 会话服务访问器
*/
get conversation(): ConversationService;
/**
* 群组服务访问器
*/
get group(): GroupService;
/**
* 用户服务访问器
*/
get user(): UserService;
/**
* 获取用户名
*/
get username(): string | undefined;
/**
* 获取配置
*/
get getConfig(): SDKConfig | undefined;
/**
* 检查是否已连接
* @returns 是否已连接
*/
isConnected(): boolean;
/**
* 检查是否已登录
* @returns 是否已登录
*/
isLoggedIn(): boolean;
/**
* 发送请求到服务器
* @param requestObj 请求对象
* @returns 请求响应Promise
*/
sendRequest: <T>(requestObj: Request) => Promise<ServerResponse<T>>;
/**
* 记录请求日志
* @param requestObj 请求对象
*/
private logRequest;
/**
* 创建带参数的请求函数
* @param reqFuncName 请求API名称
* @param method HTTP方法
* @returns 请求函数
*/
createRequestFunction: <ReqType extends Record<string, any> | undefined, ResType = unknown>(reqFuncName: RequestApi, method: HttpMethod) => (params: ReqType) => Promise<ServerResponse<ResType>>;
/**
* 创建无参数的请求函数
* @param reqFuncName 请求API名称
* @param method HTTP方法
* @returns 请求函数
*/
createRequestFunctionWithoutParams: <ResType = unknown>(reqFuncName: RequestApi, method: HttpMethod) => () => Promise<ServerResponse<ResType>>;
/**
* 处理SSE消息
* @param response SSE响应数据
*/
private handleMessage;
/**
* 处理重连成功事件
*/
private handleReconnectSuccess;
/**
* 处理连接关闭事件
*/
private handleConnectionClosed;
/**
* 登录到服务器
* @param params 登录参数 (只需要username和token)
* @returns 登录结果Promise
* @remarks 必须在调用login前先调用configure方法设置appKey和apiAddr配置。
*/
login: (params: LoginParams) => Promise<string>;
/**
* 登出
* @returns 登出结果Promise
*/
logout: () => Promise<ServerResponse<unknown>>;
/**
* 初始化会话列表缓存
* @private
*/
private initializeConversationCache;
/**
* 获取会话列表
* @param params 分页参数
* @returns Promise<void> - 不返回数据，通过事件机制通知结果
* @remarks 数据通过OnConversationListUpdated事件返回，请使用事件监听获取结果
*/
getConversations: (params: ReqPageParam) => Promise<boolean>;
/**
* 内部上传文件方法
* @param file 要上传的文件
* @param groupId 所属群组 ID，用于标识上传的文件归属
* @returns 上传结果，包括原图地址和缩略图地址，或错误信息
*/
private internalUploadFile;
/**
* 上传文件
* @param file
* @param groupId
*/
uploadFile: ({ file }: UploadFileParams, groupId: number) => Promise<ServerResponse<{
originalUrl: string;
thumbnailUrl?: string;
}>>;
/**
* 监听单条消息
* @param callback 消息回调函数
* @returns 取消订阅函数
*/
onMessage(callback: (message: MessageItem) => void): () => void;
/**
* 监听多条消息
* @param callback 消息回调函数
* @returns 取消订阅函数
*/
onMessages(callback: (messages: MessageItem[]) => void): () => void;
/**
* 监听连接状态变化
* @param callback 状态变化回调
* @returns 取消订阅函数
*/
onConnectionChange(callback: (isConnected: boolean) => void): () => void;
/**
* 监听被踢下线事件
* @param callback 回调函数
* @returns 取消订阅函数
*/
onKickedOffline(callback: () => void): () => void;
/**
* 发送文本消息
* @param text 文本内容
* @param to 接收者用户名或群组ID
* @param groupType 会话类型（群聊或私聊）
* @param params 附加消息参数（MessageItem 类型的部分属性，排除 text 字段）
* @returns Promise，返回服务器响应的消息列表
*/
sendTextMessage: (text: string, to: string, groupType: GroupType, params?: Partial<Omit<MessageItem, "text">>) => Promise<ServerResponse<MessageItem[]>>;
/**
* 发送图片消息
* @param link 图片链接
* @param snapshot 图片缩略图（base64）
* @param to 接收者用户名或群组ID
* @param groupType 会话类型
* @param params 附加消息参数（排除 link 和 snapshot 字段）
* @returns Promise，返回服务器响应的消息列表
*/
sendImageMessage: (link: string, snapshot: string, to: string, groupType: GroupType, params?: Partial<Omit<MessageItem, "link" | "snapshot">>) => Promise<ServerResponse<MessageItem[]>>;
/**
* 发送文件消息
* @param fileUrl 文件链接
* @param to 接收者用户名或群组ID
* @param groupType 会话类型
* @param params 附加消息参数（排除 link 字段）
* @returns Promise，返回服务器响应的消息列表
*/
sendFileMessage: (fileUrl: string, to: string, groupType: GroupType, params?: Partial<Omit<MessageItem, "link">>) => Promise<ServerResponse<MessageItem[]>>;
/**
* 发送音频消息
* @param audioUrl 音频链接
* @param to 接收者用户名或群组ID
* @param groupType 会话类型
* @param params 附加消息参数（排除 link 字段）
* @returns Promise，返回服务器响应的消息列表
*/
sendAudioMessage: (audioUrl: string, to: string, groupType: GroupType, params?: Partial<Omit<MessageItem, "link">>) => Promise<ServerResponse<MessageItem[]>>;
/**
* 发送视频消息
* @param videoUrl 视频链接
* @param to 接收者用户名或群组ID
* @param groupType 会话类型
* @param params 附加消息参数（排除 link 字段）
* @returns Promise，返回服务器响应的消息列表
*/
sendVideoMessage: (videoUrl: string, to: string, groupType: GroupType, params?: Partial<Omit<MessageItem, "link">>) => Promise<ServerResponse<MessageItem[]>>;
/**
* 发送超链接消息
* @param linkUrl 超链接地址
* @param to 接收者用户名或群组ID
* @param groupType 会话类型
* @param params 附加消息参数（排除 text 字段）
* @returns Promise，返回服务器响应的消息列表
*/
sendLinkMessage: (linkUrl: string, to: string, groupType: GroupType, params?: Partial<Omit<MessageItem, "text">>) => Promise<ServerResponse<MessageItem[]>>;
/**
* 发送 Gif 动图消息
* @param gifUrl gif 图片链接
* @param to 接收者用户名或群组ID
* @param groupType 会话类型
* @param params 附加消息参数（排除 link 字段）
* @returns Promise，返回服务器响应的消息列表
*/
sendGifMessage: (gifUrl: string, to: string, groupType: GroupType, params?: Partial<Omit<MessageItem, "link">>) => Promise<ServerResponse<MessageItem[]>>;
/**
* 发送操作类型消息（如系统提示、操作反馈等）
* @param optionText 操作文本内容
* @param to 接收者用户名或群组ID
* @param groupType 会话类型
* @param params 附加消息参数（排除 text 字段）
* @returns Promise，返回服务器响应的消息列表
*/
sendOptionMessage: (optionText: string, to: string, groupType: GroupType, params?: Partial<Omit<MessageItem, "text">>) => Promise<ServerResponse<MessageItem[]>>;
/**
* 发送 Emoji 表情消息
* @param emoji Emoji 内容（如 😂）
* @param to 接收者用户名或群组ID
* @param groupType 会话类型
* @param params 附加消息参数（排除 text 字段）
* @returns Promise，返回服务器响应的消息列表
*/
sendEmojiMessage: (emoji: string, to: string, groupType: GroupType, params?: Partial<Omit<MessageItem, "text">>) => Promise<ServerResponse<MessageItem[]>>;
/**
* 发送自定义消息（前端/业务自定义格式）
* @param customText 自定义内容（如 json 字符串）
* @param to 接收者用户名或群组ID
* @param groupType 会话类型
* @param params 附加消息参数（排除 text 字段）
* @returns Promise，返回服务器响应的消息列表
*/
sendCustomMessage: (customText: string, to: string, groupType: GroupType, params?: Partial<Omit<MessageItem, "text">>) => Promise<ServerResponse<MessageItem[]>>;
/**
* 获取历史消息列表
* @param params
* @returns 历史消息
*/
getHistoryMessageList: (params: HistoryMessageParam) => Promise<ServerResponse<HistoryMessageResponse>>;
/**
* 获取直播消息列表
* @param params
* @returns 历史消息
*/
getLiveMessageList: (params: LiveMessageParam) => Promise<ServerResponse<HistoryMessageResponse>>;
/**
* 获取群组信息
* @param groupId 群组ID
* @returns 群组信息
*/
getGroupInfo: (groupId: number) => Promise<ServerResponse<import("../types/entity").GroupInfoVO>>;
/**
* 获取群组成员列表
* @param params 包含群组ID和可选分页参数的对象
* @returns 群组成员信息
*/
getGroupMembers: (params: {
groupId: number;
} & Partial<ReqPageParam>) => Promise<ServerResponse<import("../types/entity").GroupInfoVO>>;
/**
* 进群
* @param groupId 包含群组ID
* @returns 进群状态
*/
joinGroup: (groupId: number) => Promise<ServerResponse<unknown>>;
/**
* 退群
* @param groupId 包含群组ID
* @returns 退群状态
*/
leftGroup: (groupId: number) => Promise<ServerResponse<unknown>>;
/**
* 检测是否可以进群
* @param groupId 包含群组ID
* @returns 是否可以进群状态
*/
checkGroupBlock: (groupId: number) => Promise<ServerResponse<unknown>>;
/**
* 获取我的群权限
* @param groupId 包含群组ID
* @returns 进群状态
*/
getMyGroupPermission: (groupId: number) => Promise<ServerResponse<GroupPermission[]>>;
/**
* 获取群权限
* @param groupId 包含群组ID
* @returns 进群状态
*/
getGroupPermission: (groupId: number) => Promise<ServerResponse<GroupPermission[]>>;
/**
* 获取群成员
* @param groupId 包含群组ID
* @returns 进群状态
*/
getGroupMember: (groupId: number) => Promise<ServerResponse>;
/**
* 获取群成员权限
* @param groupId 包含群组ID
* @param userId 包含用户ID
* @returns 进群状态
*/
getGroupMemberPermission: (groupId: number, userId: number) => Promise<ServerResponse<GroupPermission[]>>;
/**
* 更新群权限（管理员使用）
* @param params
* @returns Promise
*/
updateGroupPermission: (params: UpdateGroupPermission) => Promise<ServerResponse>;
/**
*
* @param params
*/
kickGroupMember: (params: KickGroupMemberParams) => Promise<ServerResponse>;
/**
*
* @param params
*/
muteMembers: (params: MuteMembersParams) => Promise<ServerResponse>;
/**
* 更新群用户权限（管理员使用）
* @param params
* @returns Promise
*/
updateGroupMemberPermission: (params: UpdateGroupMemberPermission) => Promise<ServerResponse>;
/**
* 修改群名称
* @param groupId 包含 groupId
* @param name 包含 name
* @returns Promise
*/
editGroupName: (groupId: number, name: string) => Promise<ServerResponse>;
/**
* 修改群简介/公告
* @param groupId 包含 groupId
* @param notification 包含 notification
* @returns Promise
*/
editNotification: (groupId: number, notification: string) => Promise<ServerResponse>;
/**
* 修改群自定义信息
* @param groupId 包含 groupId
* @param customer 包含 customer
* @returns Promise
*/
editGroupCustomer: (groupId: number, customer: string) => Promise<ServerResponse>;
/**
* 设置群管理员
* @param groupId 群 ID
* @param username 用户名
* @returns Promise
*/
addAdmin: (groupId: number, username: number) => Promise<ServerResponse>;
/**
* 删除群管理员
* @param groupId 群 ID
* @param username 用户名
* @returns Promise
*/
deleteAdmin: (groupId: number, username: number) => Promise<ServerResponse>;
/**
* 置顶消息
* @param groupId 群 ID
* @param messageId 消息 ID
* @param type 类型（0：取消置顶，1：置顶）
* @returns Promise
*/
pin: (groupId: number, messageId: number, type: number) => Promise<ServerResponse>;
/**
* 群禁言 / 解除禁言
* @param groupId 群 ID
* @param type 类型（0：禁言，1：解除禁言）
* @returns Promise
*/
muteGroup: (groupId: number, type: number) => Promise<ServerResponse>;
/**
* 群成员禁言 / 解除禁言
* @param groupId 群 ID
* @param username 用户名
* @param type 类型（0：禁言，1：解除禁言）
* @returns Promise
*/
muteMember: (groupId: number, username: number, type: number) => Promise<ServerResponse>;
/**
* 设置会话已读
* @param params 会话已读参数
* @returns 群组信息
*/
markConversationRead: (params: MarkConversationReadParam) => Promise<ServerResponse<unknown>>;
/**
* 清除指定会话的未读数
* @param conversationId
*/
clearConversationUnread: (conversationId: number) => void;
/**
* 清除所有会话的未读数
*/
clearAllConversationUnread: () => void;
get uuid(): string;
/**
* 更新消息缓存
* @param message 消息
*/
private updateMessageCache;
/**
* 获取缓存的群组消息
* @param groupId 群组ID
* @returns 缓存的群组消息数组
*/
getCachedGroupMessages(groupId: number): MessageItem[];
}
export default SIMSDK;