|
| 1 | +package com.pubnub.chat |
| 2 | + |
| 3 | +import com.pubnub.api.PubNubError |
| 4 | +import com.pubnub.api.models.consumer.PNPublishResult |
| 5 | +import com.pubnub.api.models.consumer.history.PNFetchMessageItem.Action |
| 6 | +import com.pubnub.chat.types.EventContent |
| 7 | +import com.pubnub.chat.types.File |
| 8 | +import com.pubnub.chat.types.MessageMentionedUsers |
| 9 | +import com.pubnub.chat.types.MessageReferencedChannels |
| 10 | +import com.pubnub.chat.types.QuotedMessage |
| 11 | +import com.pubnub.chat.types.TextLink |
| 12 | +import com.pubnub.kmp.PNFuture |
| 13 | + |
| 14 | +/** |
| 15 | + * Represents an object that refers to a single message in a chat. |
| 16 | + */ |
| 17 | +interface BaseMessage<M : BaseMessage<M, C>, C : BaseChannel<C, M>> { |
| 18 | + /** |
| 19 | + * Reference to the main Chat object. |
| 20 | + */ |
| 21 | + val chat: Chat |
| 22 | + |
| 23 | + /** |
| 24 | + * Unique identifier for the message. |
| 25 | + */ |
| 26 | + val timetoken: Long |
| 27 | + |
| 28 | + /** |
| 29 | + * Original text content of the message. |
| 30 | + */ |
| 31 | + val content: EventContent.TextMessageContent |
| 32 | + |
| 33 | + /** |
| 34 | + * Unique identifier for the channel in which the message was sent. |
| 35 | + */ |
| 36 | + val channelId: String |
| 37 | + |
| 38 | + /** |
| 39 | + * Unique ID of the user who sent the message. |
| 40 | + */ |
| 41 | + val userId: String |
| 42 | + |
| 43 | + /** |
| 44 | + * Any actions associated with the message, such as reactions, replies, or other interactive elements. |
| 45 | + */ |
| 46 | + val actions: Map<String, Map<String, List<Action>>>? |
| 47 | + |
| 48 | + /** |
| 49 | + * Extra information added to the message giving additional context. |
| 50 | + */ |
| 51 | + val meta: Map<String, Any>? |
| 52 | + |
| 53 | + /** |
| 54 | + * Access the original quoted message. |
| 55 | + * |
| 56 | + * `quotedMessage` returns only values for the timetoken, text, and userId parameters. If you want to return the |
| 57 | + * full quoted Message object, use the [Channel.getMessage] method and the timetoken from the quote that you can |
| 58 | + * extract from the `quotedMessage` parameter added to the published message. |
| 59 | + */ |
| 60 | + val quotedMessage: QuotedMessage? |
| 61 | + |
| 62 | + /** |
| 63 | + * Content of the message. |
| 64 | + */ |
| 65 | + val text: String |
| 66 | + |
| 67 | + /** |
| 68 | + * Whether the message is soft deleted. |
| 69 | + */ |
| 70 | + val deleted: Boolean |
| 71 | + |
| 72 | + /** |
| 73 | + * Message type (currently "text" for all Messages). |
| 74 | + */ |
| 75 | + val type: String |
| 76 | + |
| 77 | + /** |
| 78 | + * List of attached files with their names, types, and sources. |
| 79 | + */ |
| 80 | + val files: List<File> |
| 81 | + |
| 82 | + /** |
| 83 | + * List of reactions attached to the message. |
| 84 | + */ |
| 85 | + val reactions: Map<String, List<Action>> |
| 86 | + |
| 87 | + /** |
| 88 | + * Error associated with the message, if any. |
| 89 | + */ |
| 90 | + val error: PubNubError? |
| 91 | + |
| 92 | + /** |
| 93 | + * List of included text links and their position. |
| 94 | + */ |
| 95 | + @Deprecated("Use `Message.getMessageElements()` instead.") |
| 96 | + val textLinks: List<TextLink>? |
| 97 | + |
| 98 | + /** |
| 99 | + * List of mentioned users with IDs and names. |
| 100 | + */ |
| 101 | + @Deprecated("Use `Message.getMessageElements()` instead.") |
| 102 | + val mentionedUsers: MessageMentionedUsers? |
| 103 | + |
| 104 | + /** |
| 105 | + * List of referenced channels with IDs and names. |
| 106 | + */ |
| 107 | + @Deprecated("Use `Message.getMessageElements()` instead.") |
| 108 | + val referencedChannels: MessageReferencedChannels? |
| 109 | + |
| 110 | + /** |
| 111 | + * Checks if the current user added a given emoji to the message. |
| 112 | + * |
| 113 | + * @param reaction Specific emoji added to the message. |
| 114 | + * @return Specifies if the current user added a given emoji to the message or not. |
| 115 | + */ |
| 116 | + fun hasUserReaction(reaction: String): Boolean |
| 117 | + |
| 118 | + /** |
| 119 | + * Changes the content of the existing message to a new one. |
| 120 | + * |
| 121 | + * @param newText New/updated text that you want to add in place of the existing message. |
| 122 | + * @return An updated message instance with an added `edited` action type. |
| 123 | + */ |
| 124 | + fun editText(newText: String): PNFuture<M> |
| 125 | + |
| 126 | + /** |
| 127 | + * Either permanently removes a historical message from Message Persistence or marks it as deleted (if you remove the message with the soft option). |
| 128 | + * |
| 129 | + * Requires Message Persistence configuration. To manage messages, you must enable Message Persistence for your app's keyset in the Admin Portal. To delete messages from PubNub storage, you must also mark the Enable Delete-From-History option. |
| 130 | + * |
| 131 | + * @param soft Decide if you want to permanently remove message data. By default, the message data gets permanently deleted from Message Persistence. If you set this parameter to true, the Message object gets the deleted status and you can still restore/get its data. |
| 132 | + * @param preserveFiles Define if you want to keep the files attached to the message or remove them. |
| 133 | + * @return For hard delete, the method returns `PNFuture` without a value (`null`). For soft delete, a `PNFuture` with an updated message instance with an added deleted action type. |
| 134 | + */ |
| 135 | + fun delete(soft: Boolean = false, preserveFiles: Boolean = false): PNFuture<M?> |
| 136 | + |
| 137 | + /** |
| 138 | + * Forward a given message from one channel to another. |
| 139 | + * |
| 140 | + * @param channelId Unique identifier of the channel to which you want to forward the message. You can forward a message to the same channel on which it was published or to any other. |
| 141 | + * @return [PNFuture] containing [PNPublishResult] that holds the timetoken of the forwarded message. |
| 142 | + */ |
| 143 | + fun forward(channelId: String): PNFuture<PNPublishResult> |
| 144 | + |
| 145 | + /** |
| 146 | + * Attach this message to its channel. |
| 147 | + * |
| 148 | + * @return `PNFuture` containing the updated channel metadata |
| 149 | + */ |
| 150 | + fun pin(): PNFuture<C> |
| 151 | + |
| 152 | + /** |
| 153 | + * Flag and report an inappropriate message to the admin. |
| 154 | + * |
| 155 | + * @param reason Reason for reporting/flagging a given message. |
| 156 | + * @return [PNFuture] containing [PNPublishResult] that holds the timetoken of the report message. |
| 157 | + */ |
| 158 | + fun report(reason: String): PNFuture<PNPublishResult> |
| 159 | + |
| 160 | + /** |
| 161 | + * Add or remove a reaction to a message. |
| 162 | + * |
| 163 | + * `toggleReaction()` is a method for both adding and removing message reactions. It adds a string flag to the message if the current user hasn't added it yet or removes it if the current user already added it before. |
| 164 | + * |
| 165 | + * If you use this method to add or remove message reactions, this flag would be a literal emoji you could implement in your app's UI. However, you could also use this method for a different purpose, like marking a message as pinned to a channel or unpinned if you implement the pinning feature in your chat app. |
| 166 | + * |
| 167 | + * @param reaction Emoji added to the message or removed from it by the current user. |
| 168 | + * @return Updated message instance with an added reactions action type. |
| 169 | + */ |
| 170 | + fun toggleReaction(reaction: String): PNFuture<M> |
| 171 | + |
| 172 | + /** |
| 173 | + * You can receive updates when this message and related message reactions are added, edited, or removed. |
| 174 | + * |
| 175 | + * @param callback Function that takes a single Message object. It defines the custom behavior to be executed when detecting message or message reaction changes. |
| 176 | + * @return Interface that lets you stop receiving message-related updates by invoking the close() method |
| 177 | + */ |
| 178 | + fun streamUpdates(callback: (message: M) -> Unit): AutoCloseable |
| 179 | + |
| 180 | + /** |
| 181 | + * If you delete a message, you can restore its content together with the attached files using the restore() method. |
| 182 | + * |
| 183 | + * This is possible, however, only if the message you want to restore was soft deleted (the soft parameter was set to true when deleting it). Hard deleted messages cannot be restored as their data is no longer available in Message Persistence. |
| 184 | + * |
| 185 | + * Requires Message Persistence configuration. To manage messages, you must enable Message Persistence for your app's keyset in the Admin Portal and mark the Enable Delete-From-History option. |
| 186 | + * |
| 187 | + * @return Object returning the restored Message object. |
| 188 | + */ |
| 189 | + fun restore(): PNFuture<M> |
| 190 | + |
| 191 | + companion object |
| 192 | +} |
0 commit comments