easemob-websdk 4.5.1 → 4.6.0-beta

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changes to easemob chat
 
 
+# 4.6.0 (April 2, 2024)
+
+- Adds pin message feature.
+    - pinMessage
+    - unpinMessage
+    - getServerPinnedMessages
+- Adds `onMessagePinEvent` callback to handle the message pin event.        
+- `onModifiedMessage` support custom message.
+- `getHistoryMessages` support get chat room history message.
+- Support custom chat room ID.
+- Optimize token login failed error code for make the reason more clearly.
+- Fix the message field  `onlineState` status error.
+
 # 4.5.1 (Feb 21, 2024)
 
 - Format the attachment file url.

package/Easemob-chat.d.ts

@@ -74,6 +74,9 @@ export declare namespace EasemobChat {
 	/** The modified message. */
 	type ModifiedMsg = TextMsgBody;
 
+	/** Messages supported by the `onModifiedMessage` event. */
+	type ModifiedEventMessage = TextMsgBody | CustomMsgBody;
+
 	interface ModifyMsgResult extends SendMsgResult {
 		/** The modified message. */
 		message: ModifiedMsg;
@@ -822,6 +825,22 @@ export declare namespace EasemobChat {
 		/** The position from which to start getting data for the next query. If the number of returned data entries is smaller than that specified in the request, the cursor is `'undefined'`, which indicates that the current page is the last page; otherwise, the SDK returns the specific cursor position which indicates where to start getting data for the next query.*/
 		cursor: string;
 	}
+
+	interface PinnedMessageInfo {
+		/** The pinned message. */
+		message: MessagesType;
+		/** When the message is pinned. The unit is millisecond.  */
+		pinTime: number;
+		/** The user ID of the operator that pins the message. */
+		operatorId: UserId;
+	}
+	interface CursorPinnedMessagesResult {
+		/** The position from which to start getting data for the next query. If the number of returned data entries is smaller than that specified in the request, the cursor is an empty string (''), which indicates that the current page is the last page; otherwise, the SDK returns the specific cursor position which indicates where to start getting data for the next query.*/
+		cursor: string;
+		/** The list of pinned messages. */
+		list: PinnedMessageInfo[];
+	}
+
 	interface ConversationItem {
 		/** The conversation ID. */
 		conversationId: string;
@@ -1511,7 +1530,7 @@ export declare namespace EasemobChat {
 		open(parameters: {
 			/** The User ID. */
 			user: string;
-			/** The password. */
+			/** The password. It is recommended to use `accessToken` params. */
 			pwd?: string;
 			/** Token required to connect to the message service. */
 			accessToken?: string;
@@ -1798,7 +1817,7 @@ export declare namespace EasemobChat {
 				success?: (res: AsyncResult<BaseMembers[]>) => void;
 				error?: (error: ErrorEvent) => void;
 			}
-		): Promise<AsyncResult<{ member: string }[]>>;
+		): Promise<AsyncResult<BaseMembers[]>>;
 
 		/**
 		 * Lists all chat room members with pagination.
@@ -4251,18 +4270,19 @@ export declare namespace EasemobChat {
 		getHistoryMessages(
 			this: Connection,
 			options: {
-				/** The user ID of the other party or the group ID. */
+				/** The user ID of the other party or the group ID or chat room ID. */
 				targetId: string;
 				/** The starting message ID for this query. The default value is -1, which means to start retrieving from the latest message. */
 				cursor?: number | string | null;
 				/** The number of messages to retrieve each time. The default value is 20,The maximum value is 50. */
 				pageSize?: number;
-				/** The chat type for SDK:
+				/**
+				 * The chat type for SDK:
 				 * - `singleChat`: one-to-one chat;
 				 * - `groupChat`: group chat;
-				 * - (Default)`singleChat`: No.
+				 * - `chatRoom`: chat room chat.
 				 */
-				chatType?: 'singleChat' | 'groupChat';
+				chatType: 'singleChat' | 'groupChat' | 'chatRoom';
 				/** Whether to select pull history messages in positive order(Pull message from the oldest to the latest).
 				 * - `up`: means searching from the newer messages to the older messages.
 				 * - `down`: means searching from the older messages to the newer messages.
@@ -5010,7 +5030,7 @@ export declare namespace EasemobChat {
 		): Promise<void>;
 
 		/**
-		 * Get the list of filter conversations from the server with pagination.
+		 * Gets the conversations from the server with pagination according to the conversation filter.
 		 *
 		 * ```typescript
 		 * connection.getServerConversationsByFilter({pageSize:10, cursor: '',filter: {mark: 0})
@@ -5019,11 +5039,13 @@ export declare namespace EasemobChat {
 		getServerConversationsByFilter(
 			this: Connection,
 			params: {
-				/** The number of conversations that you expect to get on each page. The value range is [1,10] and the default value is `10`. */
+				/** The number of conversations to retrieve on each page. The value range is [1,10] and the default value is `10`. */
 				pageSize?: number;
 				/** The position from which to start getting data. */
 				cursor?: string;
+				/** The conversation filter options. */
 				filter: {
+					/** The conversation mark for query. */
 					mark: MarkType;
 				};
 			}
@@ -5049,6 +5071,72 @@ export declare namespace EasemobChat {
 		 */
 		deleteAllMessagesAndConversations(this: Connection): Promise<void>;
 
+		/**
+		 * Pins a message.
+		 *
+		 * connection.pinMessage({
+		 * 		conversationId: 'conversationId',
+		 * 		conversationType: 'groupChat',
+		 * 		messageId: 'messageId'
+		 * })
+		 */
+		pinMessage(
+			this: Connection,
+			params: {
+				/** The conversation ID. */
+				conversationId: string;
+				/** The conversation type. */
+				conversationType: 'groupChat' | 'chatRoom';
+				/** The ID of the message to be pinned. */
+				messageId: string;
+			}
+		): Promise<void>;
+
+		/**
+		 * Unpins a message.
+		 *
+		 * connection.unpinMessage({
+		 * 		conversationId: 'conversationId',
+		 * 		conversationType: 'groupChat',
+		 * 		messageId: 'messageId'
+		 * })
+		 */
+		unpinMessage(
+			this: Connection,
+			params: {
+				/** The conversation ID. */
+				conversationId: string;
+				/** The conversation type. */
+				conversationType: 'groupChat' | 'chatRoom';
+				/** The ID of the message to be unpinned. */
+				messageId: string;
+			}
+		): Promise<void>;
+
+		/**
+		 * Gets the pinned messages in a conversation with pagination.
+		 *
+		 * connection.getServerPinnedMessages({
+		 * 		conversationId: 'conversationId',
+		 * 		conversationType: 'groupChat',
+		 * 		pageSize: 20,
+		 * 		cursor: ''
+		 * })
+		 */
+		getServerPinnedMessages(
+			this: Connection,
+			params: {
+				/** The conversation ID. */
+				conversationId: string;
+				/** The conversation type. */
+				conversationType: 'groupChat' | 'chatRoom';
+				/** The number of pinned messages to retrieve on each page. The value range is [1,50] and the default value is `10`. */
+				pageSize?: number;
+				/** The position from which to start getting data. For the first call of the method, an empty string ('') is passed in and the SDK returns the list of pinned messages in the descending order of when they are pinned.  */
+				cursor?: string;
+			}
+		): Promise<AsyncResult<CursorPinnedMessagesResult>>;
+
 		/**
 		 * Set the DND Settings for the current login user.
 		 *
@@ -5498,7 +5586,6 @@ export declare namespace EasemobChat {
 	type Event =
 		| 'onOpened'
 		| 'onPresence'
-		| 'onMessage'
 		| 'onTextMessage'
 		| 'onImageMessage'
 		| 'onAudioMessage'
@@ -5534,7 +5621,8 @@ export declare namespace EasemobChat {
 		| 'onChatThreadChange'
 		| 'onMultiDeviceEvent'
 		| 'onGroupEvent'
-		| 'onChatroomEvent';
+		| 'onChatroomEvent'
+		| 'onMessagePinEvent';
 
 	interface GroupEvent {
 		/** The type of operation. <br/>
@@ -5664,6 +5752,24 @@ export declare namespace EasemobChat {
 		memberCount?: number;
 	}
 
+	interface MessagePinEvent {
+		/** The conversation type. */
+		conversationType: 'groupChat' | 'chatRoom';
+		/** The conversation ID. */
+		conversationId: string;
+		/** The ID of the message that is pinned or unpinned. */
+		messageId: string;
+		/** The user ID of the operator that pins or unpins the message */
+		operatorId: UserId;
+		/** When the message is pinned or unpinned. */
+		time: number;
+		/** The operation type. <br/>
+		 * pin: A message is pinned.<br/>
+		 * unpin: A message is unpinned.<br/>
+		 */
+		operation: 'pin' | 'unpin';
+	}
+
 	interface EventHandlerType {
 		/** @deprecated  Use { onConnected } instead. */
 		onOpened?: (msg: any) => void;
@@ -5703,7 +5809,7 @@ export declare namespace EasemobChat {
 		/** The callback to receive a session read ack. */
 		onChannelMessage?: (msg: ChannelMsgBody) => void;
 		/** Occurs when the message content is modified. */
-		onModifiedMessage?: (msg: ModifiedMsg) => void;
+		onModifiedMessage?: (msg: ModifiedEventMessage) => void;
 		/** The callback to receive error. */
 		onError?: (error: ErrorEvent) => void;
 		/** The callback for network disconnection. */
@@ -5748,6 +5854,8 @@ export declare namespace EasemobChat {
 		onGroupEvent?: (eventData: GroupEvent) => void;
 		/** The callback to receive a chatroom event. */
 		onChatroomEvent?: (eventData: ChatroomEvent) => void;
+		/** The callback to receive a pin message event. */
+		onMessagePinEvent?: (eventData: MessagePinEvent) => void;
 	}
 
 	interface HandlerData {
@@ -5861,8 +5969,8 @@ export declare namespace EasemobChat {
 	interface Config {
 		useCache: boolean;
 		maxCache: number;
-		color: string;
-		background: string;
+		color?: string;
+		background?: string;
 	}
 
 	/**
@@ -5879,6 +5987,9 @@ export declare namespace EasemobChat {
 		config: Config;
 		logBytes: number;
 		constructor(name: string, defaultLevel: Level, factory?: any);
+		/**
+		 * set Logger config.
+		 */
 		setConfig(cofig: Config): void;
 		/**
 		 * get current log level
@@ -5889,8 +6000,8 @@ export declare namespace EasemobChat {
 		 */
 		setLevel(
 			level: Level,
-			persist: boolean,
-			name: string
+			persist?: boolean,
+			name?: string
 		): 'No console available for logging' | undefined;
 		setDefaultLevel(level: Level): void;
 		/**
@@ -5909,6 +6020,17 @@ export declare namespace EasemobChat {
 		 * down load logs
 		 */
 		download(): void;
+		/**
+		 * The logs callback function.
+		 */
+		onLog(data: {
+			/** The time when logs are printed. */
+			time: string;
+			/** The log level. */
+			level: string;
+			/** The log content. */
+			logs: any[];
+		}): void;
 	}
 
 	// --- for Message ---
@@ -6575,6 +6697,8 @@ export declare namespace EasemobChat {
 		deliverOnlineOnly?: boolean;
 		/** The list of message recipients. */
 		receiverList?: string[];
+		/** Message modified info. */
+		modifiedInfo?: ModifiedMsgInfo;
 	}
 
 	interface CreateCustomMsgParameters {