Merge branch 'dev' into docs_fixes

Dockerfile

@@ -1,6 +1,5 @@
-FROM ubuntu:focal@sha256:0b897358ff6624825fb50d20ffb605ab0eaea77ced0adb8c6a4b756513dec6fc
+FROM ubuntu:noble@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
 
-ENV DEBIAN_FRONTEND=noninteractive
 RUN apt-get update && apt-get install --no-install-recommends -y libssl-dev zlib1g-dev libsodium-dev libopus-dev cmake pkg-config g++ gcc git make && apt-get clean && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /usr/src/DPP

docpages/make_a_bot/token.md

@@ -18,6 +18,8 @@ In this panel, you can get your bot token by clicking "Reset Token". A bot token
 
 \warning **Do not share this token** with anybody! If you ever somehow compromise your current bot token or see your bot in danger, you can regenerate the token in the panel.
 
+\note This token can only be seen once. We highly recommend that, if you're going to be reusing your token, you store it in a VERY safe place (like a password manager).
+
 ## Adding the Bot to Your Server
 
 Once you've created your bot in the discord developer portal, you may wonder:
@@ -29,7 +31,10 @@ That's because you've created a bot application, but it's not on any server righ
 1. Go again into the [Applications page](https://discord.com/developers/applications) and click on your bot.
 2. Go to the "OAuth2" tab and click on the subpage "URL Generator".
 \image html create_application_navigate_to_url_generator.png
-3. Select the `bot` scope. If your bot uses slash commands, also select `applications.commands`. You can read more about scopes and which you need for your application [here](https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes).
+3. Select the `bot` scope.
+
+\note For bots, you ONLY need the `bot` scope, nearly all of the other scopes are related to non-bot applications (external programs that communicate with Discord, such as Logitech G Hub). Whilst you can also select the `applications.commands` scope, the `bot` scope will automatically include this silently. You can read more about scopes and which ones you might need for your application [here](https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes).
+
 4. Choose the permissions required for your bot to function in the "Bot Permissions" section.
 5. Copy and paste the resulting URL in your browser. Choose a server to invite the bot to, and click "Authorize".
 

include/dpp/appcommand.h

@@ -443,6 +443,9 @@ enum interaction_response_type {
 	 * @see https://discord.com/developers/docs/monetization/entitlements#premiumrequired-interaction-response
 	 * @note Not available for autocomplete and ping interactions.
 	 * @warning This response does not support using `content`, `embeds`, or `attachments`, so reply with no data when using this!
+	 *
+	 * @depreciated Replaced with buttons with a style of cos_premium
+	 * This interaction type may stop working at any point
 	 */
 	ir_premium_required = 10,
 };

include/dpp/bignum.h

@@ -0,0 +1,101 @@
+/************************************************************************************
+ *
+ * D++, A Lightweight C++ library for Discord
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright 2021 Craig Edwards and D++ contributors
+ * (https://github.com/brainboxdotcc/DPP/graphs/contributors)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ ************************************************************************************/
+
+#pragma once
+#include <dpp/export.h>
+#include <dpp/snowflake.h>
+#include <memory>
+
+namespace dpp {
+
+/**
+ * @brief This contains the OpenSSL structs. It is not public,
+ * so that the public interface doesn't depend on OpenSSL directly.
+ */
+struct openssl_bignum;
+
+/**
+* @brief An arbitrary length integer number.
+ * Officially, the Discord documentation says that permission values can be any arbitrary
+ * number of digits. At time of writing there are only 50 bits of permissions, but this is
+ * set to grow larger and potentially past 64 bits. They will continue to send this data
+ * as a huge single integer at that point, because this is obviously sensible. /s
+ *
+ * @note dpp::bignumber uses OpenSSL BN_* under the hood, as we include openssl anyway
+ * for HTTPS.
+*/
+class DPP_EXPORT bignumber {
+	/**
+	 * @brief Internal opaque struct to contain OpenSSL things
+	 */
+	std::shared_ptr<openssl_bignum> ssl_bn{nullptr};
+public:
+	/**
+	 * @brief Construct a new bignumber object
+	 */
+	bignumber() = default;
+
+	/**
+	 * @brief Parse a std::string of an arbitrary length number into
+	 * a bignumber.
+	 * @param number_string string representation of a number. The
+	 * number must be an integer, and can be positive or negative.
+	 * @note Prefixing number_string with 0x will parse it as hexadecimal.
+	 * This is not case sensitive.
+	 */
+	bignumber(const std::string& number_string);
+
+	/**
+	 * @brief Build a bignumber from a vector of 64 bit values.
+	 * The values are accepted in "reverse order", so the first vector
+	 * entry at index 0 is the leftmost 64 bits of the bignum.
+	 * The vector can be any arbitrary length.
+	 * @param bits Vector of 64 bit values which represent the number
+	 */
+	bignumber(std::vector<uint64_t> bits);
+
+	/**
+	 * @brief Default destructor
+	 */
+	~bignumber() = default;
+
+	/**
+	 * @brief Get the string representation of the bignumber.
+	 * @param hex If false (the default) the number is returned in
+	 * decimal, else if this parameter is true, it will be returned
+	 * as hex (without leading '0x')
+	 * @return String representation of bignumber
+	 */
+	[[nodiscard]] std::string get_number(bool hex = false) const;
+
+	/**
+	 * @brief Get the array of 64 bit values that represents the
+	 * bignumber. This is what we should use to store bignumbers
+	 * in memory, not this bignumber class itself, as the bignumber
+	 * class instantiates OpenSSL structs and takes significantly
+	 * more ram than just a vector.
+	 * @return Vector of 64 bit values representing the bignumber
+	 */
+	[[nodiscard]] std::vector<uint64_t> get_binary() const;
+};
+
+} // namespace dpp

include/dpp/cluster.h

@@ -3780,6 +3780,16 @@ class DPP_EXPORT cluster {
 	 */
 	void entitlement_test_delete(snowflake entitlement_id, command_completion_event_t callback = utility::log_error());
 
+	/**
+	 * @brief For One-Time Purchase consumable SKUs, marks a given entitlement for the user as consumed.
+	 *
+	 * @see https://discord.com/developers/docs/monetization/entitlements#consume-an-entitlement
+	 * @param entitlement_id The entitlement to mark as consumed.
+	 * @param callback Function to call when the API call completes.
+	 * On success the callback will contain a dpp::confirmation 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 entitlement_consume(snowflake entitlement_id, command_completion_event_t callback = utility::log_error());
+
 	/**
 	 * @brief Returns all SKUs for a given application.
 	 * @note Because of how Discord's SKU and subscription systems work, you will see two SKUs for your premium offering.

include/dpp/cluster_coro_calls.h

@@ -751,6 +751,17 @@
  */
 [[nodiscard]] async<confirmation_callback_t> co_entitlement_test_delete(snowflake entitlement_id);
 
+/**
+ * @brief For One-Time Purchase consumable SKUs, marks a given entitlement for the user as consumed.
+ *
+ * @see dpp::cluster::entitlement_consume
+ * @see https://discord.com/developers/docs/monetization/entitlements#consume-an-entitlement
+ * @param entitlement_id The entitlement to mark as consumed.
+ * @return confirmation returned object on completion
+ * \memberof dpp::cluster
+ */
+[[nodiscard]] async<confirmation_callback_t> co_entitlement_consume(snowflake entitlement_id);
+
 /**
  * @brief Get the gateway information for the bot using the token
  * @see dpp::cluster::get_gateway_bot

include/dpp/cluster_sync_calls.h

@@ -931,6 +931,20 @@ entitlement entitlement_test_create_sync(const class entitlement& new_entitlemen
  */
 confirmation entitlement_test_delete_sync(snowflake entitlement_id);
 
+/**
+ * @brief For One-Time Purchase consumable SKUs, marks a given entitlement for the user as consumed.
+ *
+ * @see dpp::cluster::entitlement_consume
+ * @see https://discord.com/developers/docs/monetization/entitlements#consume-an-entitlement
+ * @param entitlement_id The entitlement to mark as consumed.
+ * @return confirmation returned object on completion
+ * \memberof dpp::cluster
+ * @throw dpp::rest_exception upon failure to execute REST function
+ * @warning This function is a blocking (synchronous) call and should only be used from within a separate thread.
+ * Avoid direct use of this function inside an event handler.
+ */
+confirmation entitlement_consume_sync(snowflake entitlement_id);
+
 /**
  * @brief Get the gateway information for the bot using the token
  * @see dpp::cluster::get_gateway_bot

include/dpp/coro/async.h

@@ -414,6 +414,11 @@ class async : private detail::async::async_base<R> {
 	using detail::async::async_base<R>::operator=; // use async_base's assignment operator
 	using detail::async::async_base<R>::await_ready; // expose await_ready as public
 
+	/**
+	 * @brief The return type of the API call. Defaults to confirmation_callback_t
+	 */
+	using result_type = R;
+
 	/**
 	 * @brief Construct an async object wrapping an object method, the call is made immediately by forwarding to <a href="https://en.cppreference.com/w/cpp/utility/functional/invoke">std::invoke</a> and can be awaited later to retrieve the result.
 	 *

include/dpp/coro/coroutine.h

@@ -232,6 +232,10 @@ class coroutine : private detail::coroutine::coroutine_base<R> {
 	}
 
 public:
+	/**
+	 * @brief The type of the result produced by this coroutine.
+	 */
+	using result_type = R;
 #ifdef _DOXYGEN_ // :))))
 	/**
 	 * @brief Default constructor, creates an empty coroutine.
@@ -334,6 +338,11 @@ class coroutine<void> : private detail::coroutine::coroutine_base<void> {
 	using detail::coroutine::coroutine_base<void>::operator=; // use coroutine_base's assignment operators
 	using detail::coroutine::coroutine_base<void>::await_ready; // expose await_ready as public
 
+	/**
+	 * @brief The type of the result produced by this coroutine.
+	 */
+	using result_type = void;
+
 	/**
 	 * @brief Suspend the current coroutine until the coroutine completes.
 	 *

include/dpp/coro/task.h

@@ -335,6 +335,10 @@ class task : private detail::task::task_base<R> {
 	}
 
 public:
+	/**
+	 * @brief The type of the result produced by this task.
+	 */
+	using result_type = R;
 #ifdef _DOXYGEN_ // :)
 	/**
 	 * @brief Default constructor, creates a task not bound to a coroutine.
@@ -465,6 +469,11 @@ class task<void> : private detail::task::task_base<void> {
 	using detail::task::task_base<void>::cancel; // expose cancel() as public
 	using detail::task::task_base<void>::await_ready; // expose await_ready as public
 
+	/**
+	 * @brief The type of the result produced by this task
+	 */
+	using result_type = void;
+
 	/**
 	 * @brief Suspend the current coroutine until the task completes.
 	 *

include/dpp/dpp.h

@@ -74,3 +74,4 @@
 #include <dpp/discordevents.h>
 #include <dpp/timed_listener.h>
 #include <dpp/collector.h>
+#include <dpp/bignum.h>