feat(plugins): Added message read/update methods to the Channel API. (#6650)

This PR adds methods to read and update messages in a channel. Specifically, it adds:
 - message_snapshot
 - last_message
 - replace_message/replace_message_at
 - clear_messages
 - find_message_by_id
 - has_messages
 - count_messages


Reviewed-by: Mm2PL <mm2pl+gh@kotmisia.pl>

docs/chatterino.d.ts

@@ -63,6 +63,20 @@ declare namespace c2 {
             override_flags?: MessageFlag | null
         ): void;
 
+        message_snapshot(n_items: number): Message[];
+        last_message(): Message | null;
+        replace_message(message: Message, replacement: Message): void;
+        replace_message(
+            message: Message,
+            replacement: Message,
+            hint: number
+        ): void;
+        replace_message_at(index: number, replacement: Message): void;
+        clear_messages(): void;
+        find_message_by_id(id: string): Message | null;
+        has_messages(): boolean;
+        count_messages(): number;
+
         is_twitch_channel(): boolean;
 
         get_room_modes(): RoomModes;

docs/lua-meta/globals.lua

@@ -151,6 +151,57 @@ function c2.Channel:add_system_message(message) end
 ---@param override_flags? c2.MessageFlag|nil Flags to override the message's flags (some splits might filter for this)
 function c2.Channel:add_message(message, context, override_flags) end
 
+--- Get a list of messages in this channel (starting from the most recent messages).
+--- The snapshot is returned as a usertype that wraps a C++ object.
+---
+---@param n_items number Number of messages to retrieve. This is an upper bound, the actual number of messages returned might be lower.
+---@return c2.Message[]
+function c2.Channel:message_snapshot(n_items) end
+
+--- Get the most recent message. If this channel doesn't have any message, this returns `nil`.
+---
+---@return c2.Message?
+function c2.Channel:last_message() end
+
+--- Replace a specific message with a different one.
+---
+---@param message c2.Message The message to replace.
+---@param replacement c2.Message The replacement.
+function c2.Channel:replace_message(message, replacement) end
+
+--- Replace a specific message with a different one.
+---
+---@param message c2.Message The message to replace.
+---@param replacement c2.Message The replacement.
+---@param hint number A one-based index (from the start) where the message is probably located. This is checked first. Otherwise the behavior is identical to the overload without this parameter.
+function c2.Channel:replace_message(message, replacement, hint) end
+
+--- Replace a message at an index with a different one.
+---
+---@param index number A one-based index (from the start) of the message to replace.
+---@param replacement c2.Message The replacement.
+function c2.Channel:replace_message_at(index, replacement) end
+
+--- Remove all messages in this channel.
+---
+function c2.Channel:clear_messages() end
+
+--- Find a message by its ID.
+---
+---@param id string
+---@return c2.Message?
+function c2.Channel:find_message_by_id(id) end
+
+--- Check if the channel has any messages.
+---
+---@return boolean
+function c2.Channel:has_messages() end
+
+--- Count the number of messages in this channel.
+---
+---@return number
+function c2.Channel:count_messages() end
+
 --- Returns true for twitch channels.
 --- Compares the channel Type. Note that enum values aren't guaranteed, just
 --- that they are equal to the exposed enum.

docs/wip-plugins.md

@@ -442,6 +442,42 @@ Returns `true` if the channel can be moderated by the current user.
 
 Returns `true` if the current user is a VIP in the channel.
 
+##### `Channel:message_snapshot(n_items)`
+
+Get a list of messages in this channel (starting from the most recent messages).
+The snapshot is returned as a usertype that wraps a C++ object.
+`n_items` is an upper bound, the actual number of messages returned might be lower.
+
+##### `Channel:last_message()`
+
+Get the most recent message. If this channel doesn't have any message, this returns `nil`.
+
+##### `Channel:replace_message(message, replacement[, hint])`
+
+Replace a specific message with a different one.
+`hint` is a one-based index (from the start) where the message is probably located. This is checked first. Otherwise the behavior is identical to the overload without this parameter.
+
+##### `Channel:replace_message_at(index, replacement)`
+
+Replace a message at an index with a different one.
+`index` is a one-based index (from the start) of the message to replace.
+
+##### `Channel:clear_messages()`
+
+Remove all messages in this channel.
+
+##### `Channel:find_message_by_id(id)`
+
+Find a message by its ID. If no message is found, `nil` is returned.
+
+##### `Channel:has_messages()`
+
+Check if the channel has any messages.
+
+##### `Channel:count_messages()`
+
+Count the number of messages in this channel.
+
 #### `HTTPMethod` enum
 
 This table describes HTTP methods available to Lua Plugins. The values behind