feat: add guild messages search endpoint (#1565)

Author: Sim-hu

include/dpp/cluster.h

@@ -1983,6 +1983,17 @@ class DPP_EXPORT cluster {
 	 */
 	void messages_get(snowflake channel_id, snowflake around, snowflake before, snowflake after, uint64_t limit, command_completion_event_t callback);
 
+	/**
+	 * @brief Search for messages in a guild
+	 *
+	 * @see https://discord.com/developers/docs/resources/message#search-guild-messages
+	 * @param guild_id Guild ID to search in
+	 * @param params Search parameters
+	 * @param callback Function to call when the API call completes.
+	 * On success the callback will contain a dpp::message_search_result object in confirmation_callback_t::value. On failure, the value is undefined and confirmation_callback_t::is_error() method will return true. You can obtain full error details with confirmation_callback_t::get_error().
+	 */
+	void guild_messages_search(snowflake guild_id, const message_search_params& params, command_completion_event_t callback);
+
 	/**
 	 * @brief Send a message to a channel. The callback function is called when the message has been sent
 	 *

include/dpp/cluster_coro_calls.h

@@ -1743,6 +1743,18 @@
  */
 [[nodiscard]] async<confirmation_callback_t> co_poll_end(snowflake message_id, snowflake channel_id);
 
+/**
+ * @brief Search for messages in a guild
+ *
+ * @see dpp::cluster::guild_messages_search
+ * @see https://discord.com/developers/docs/resources/message#search-guild-messages
+ * @param guild_id Guild ID to search in
+ * @param params Search parameters
+ * @return message_search_result returned object on completion
+ * \memberof dpp::cluster
+ */
+[[nodiscard]] async<confirmation_callback_t> co_guild_messages_search(snowflake guild_id, const message_search_params& params);
+
 /**
  * @brief Get a channel's pins
  * @see dpp::cluster::channel_pins_get

include/dpp/message.h

@@ -3090,6 +3090,209 @@ typedef std::unordered_map<snowflake, message> message_map;
  */
 typedef std::unordered_map<snowflake, message_pin> message_pin_map;
 
+/**
+ * @brief Possible values for the "has" filter in message search
+ */
+enum message_search_has : uint8_t {
+	has_image,
+	has_sound,
+	has_video,
+	has_file,
+	has_sticker,
+	has_embed,
+	has_link,
+	has_poll,
+	has_snapshot,
+};
+
+/**
+ * @brief Sort mode for message search results
+ */
+enum message_search_sort : uint8_t {
+	sort_timestamp,
+	sort_relevance,
+};
+
+/**
+ * @brief Sort order for message search results
+ */
+enum message_search_order : uint8_t {
+	sort_desc,
+	sort_asc,
+};
+
+/**
+ * @brief Parameters for searching messages within a guild
+ * @see https://discord.com/developers/docs/resources/message#search-guild-messages
+ */
+struct DPP_EXPORT message_search_params {
+	/**
+	 * @brief Filter messages by content (max 1024 characters)
+	 */
+	std::string content;
+
+	/**
+	 * @brief Filter by author IDs (max 100)
+	 */
+	std::vector<snowflake> author_id;
+
+	/**
+	 * @brief Filter messages that mention these users (max 100)
+	 */
+	std::vector<snowflake> mentions;
+
+	/**
+	 * @brief Filter by channel IDs (max 500)
+	 */
+	std::vector<snowflake> channel_id;
+
+	/**
+	 * @brief Filter messages that mention these roles (max 100)
+	 */
+	std::vector<snowflake> mentions_role_id;
+
+	/**
+	 * @brief Filter messages that reply to these users (max 100)
+	 */
+	std::vector<snowflake> replied_to_user_id;
+
+	/**
+	 * @brief Filter messages that reply to these messages (max 100)
+	 */
+	std::vector<snowflake> replied_to_message_id;
+
+	/**
+	 * @brief Filter by author type (user, bot, webhook; prefix with - to negate)
+	 */
+	std::vector<std::string> author_type;
+
+	/**
+	 * @brief Filter by presence of element types
+	 */
+	std::vector<message_search_has> has;
+
+	/**
+	 * @brief Filter messages by embed type
+	 */
+	std::vector<std::string> embed_type;
+
+	/**
+	 * @brief Filter messages by embed provider (case-sensitive, max 100)
+	 */
+	std::vector<std::string> embed_provider;
+
+	/**
+	 * @brief Filter messages by link hostname (max 100)
+	 */
+	std::vector<std::string> link_hostname;
+
+	/**
+	 * @brief Filter messages by attachment filename (max 100)
+	 */
+	std::vector<std::string> attachment_filename;
+
+	/**
+	 * @brief Filter messages by attachment extension (max 100)
+	 */
+	std::vector<std::string> attachment_extension;
+
+	/**
+	 * @brief Get messages before this message ID
+	 */
+	snowflake max_id;
+
+	/**
+	 * @brief Get messages after this message ID
+	 */
+	snowflake min_id;
+
+	/**
+	 * @brief Filter messages by whether they are pinned
+	 */
+	std::optional<bool> pinned;
+
+	/**
+	 * @brief Filter by @everyone mention presence
+	 */
+	std::optional<bool> mention_everyone;
+
+	/**
+	 * @brief Whether to include results from age-restricted channels (default false)
+	 */
+	std::optional<bool> include_nsfw;
+
+	/**
+	 * @brief Max number of messages to return (1-25, default 25)
+	 */
+	std::optional<uint32_t> limit;
+
+	/**
+	 * @brief Pagination offset (max 9975)
+	 */
+	std::optional<uint32_t> offset;
+
+	/**
+	 * @brief Max number of words to skip between matching tokens (max 100, default 2)
+	 */
+	std::optional<uint32_t> slop;
+
+	/**
+	 * @brief Sorting algorithm to use (default: sort_timestamp)
+	 */
+	std::optional<message_search_sort> sort_by;
+
+	/**
+	 * @brief Direction to sort (default: sort_desc)
+	 */
+	std::optional<message_search_order> sort_order;
+
+	/**
+	 * @brief Build the query string for the REST request
+	 * @return URL query string starting with '?'
+	 */
+	std::string build_url_params() const;
+};
+
+/**
+ * @brief Represents the result of a guild message search
+ * @see https://discord.com/developers/docs/resources/message#search-guild-messages
+ */
+struct DPP_EXPORT message_search_result : public json_interface<message_search_result> {
+protected:
+	friend struct json_interface<message_search_result>;
+
+	/**
+	 * @brief Fill from JSON
+	 * @param j JSON data
+	 * @return Reference to self
+	 */
+	message_search_result& fill_from_json_impl(nlohmann::json* j);
+
+public:
+	message_search_result() = default;
+
+	/**
+	 * @brief Total number of results matching the query
+	 */
+	uint32_t total_results{0};
+
+	/**
+	 * @brief Whether a deep historical index is being performed
+	 */
+	bool doing_deep_historical_index{false};
+
+	/**
+	 * @brief Number of documents indexed so far (only present during deep indexing)
+	 */
+	std::optional<uint32_t> documents_indexed;
+
+	/**
+	 * @brief Matched messages grouped by context.
+	 * Each inner vector contains the matched message followed by context messages.
+	 */
+	std::vector<std::vector<message>> messages;
+};
+
 /**
  * @brief A group of stickers
  */

include/dpp/restresults.h

@@ -196,7 +196,8 @@ typedef std::variant<
 		entitlement,
 		entitlement_map,
 		sku,
-		sku_map
+		sku_map,
+		message_search_result
 	> confirmable_t;
 
 /**

src/dpp/cluster/message.cpp

@@ -206,6 +206,15 @@ void cluster::poll_end(snowflake message_id, snowflake channel_id, command_compl
 }
 
 
+void cluster::guild_messages_search(snowflake guild_id, const message_search_params& params, command_completion_event_t callback) {
+	this->post_rest(API_PATH "/guilds", std::to_string(guild_id), "messages/search" + params.build_url_params(), m_get, "", [this, callback](json &j, const http_request_completion_t& http) {
+		if (callback) {
+			callback(confirmation_callback_t(this, message_search_result().fill_from_json(&j), http));
+		}
+	});
+}
+
+
 void cluster::channel_pins_get(snowflake channel_id, command_completion_event_t callback) {
 	channel_pins_get(channel_id, {}, {}, callback);
 }

src/dpp/cluster_coro_calls.cpp

@@ -304,7 +304,7 @@ async<confirmation_callback_t> cluster::co_get_gateway_bot() {
 }
 
 async<confirmation_callback_t> cluster::co_guild_current_member_edit(snowflake guild_id, const std::string& nickname, const std::string& banner_blob, const image_type banner_type, const std::string& avatar_blob, const image_type avatar_type, const std::string& bio) {
-	return async{ this, static_cast<void (cluster::*)(snowflake, const std::string &, const std::string&, const image_type, const std::string&, const image_type, const std::string&, command_completion_event_t)>(&cluster::guild_current_member_edit), guild_id, nickname, banner_blob, banner_type, avatar_blob, avatar_type, bio };
+	return async{ this, static_cast<void (cluster::*)(snowflake, const std::string&, const std::string&, const image_type, const std::string&, const image_type, const std::string&, command_completion_event_t)>(&cluster::guild_current_member_edit), guild_id, nickname, banner_blob, banner_type, avatar_blob, avatar_type, bio };
 }
 
 async<confirmation_callback_t> cluster::co_guild_auditlog_get(snowflake guild_id, snowflake user_id, uint32_t action_type, snowflake before, snowflake after, uint32_t limit) {
@@ -571,6 +571,10 @@ async<confirmation_callback_t> cluster::co_poll_end(snowflake message_id, snowfl
 	return async{ this, static_cast<void (cluster::*)(snowflake, snowflake, command_completion_event_t)>(&cluster::poll_end), message_id, channel_id };
 }
 
+async<confirmation_callback_t> cluster::co_guild_messages_search(snowflake guild_id, const message_search_params& params) {
+	return async{ this, static_cast<void (cluster::*)(snowflake, const message_search_params&, command_completion_event_t)>(&cluster::guild_messages_search), guild_id, params };
+}
+
 async<confirmation_callback_t> cluster::co_channel_pins_get(snowflake channel_id) {
 	return async{ this, static_cast<void (cluster::*)(snowflake, command_completion_event_t)>(&cluster::channel_pins_get), channel_id };
 }