diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index aa5fda5e..b31fd924 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -11,6 +11,11 @@ on: permissions: contents: read +env: + CMAKE_INSTALL_MESSAGE: NEVER + CMAKE_LOG_LEVEL: WARNING + MAKEFLAGS: --silent + jobs: lint: runs-on: ubuntu-24.04 @@ -40,7 +45,7 @@ jobs: if: steps.python-tools-cache.outputs.cache-hit != 'true' run: | python -m venv .ci-tools - .ci-tools/bin/python -m pip install "clang-format==22.1.8" "poetry==2.4.1" + .ci-tools/bin/python -m pip install --quiet --disable-pip-version-check "clang-format==22.1.8" "poetry==2.4.1" - name: Add Python tools to PATH run: echo "$GITHUB_WORKSPACE/.ci-tools/bin" >> "$GITHUB_PATH" - name: Lint diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 5969ce61..87060829 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -11,6 +11,11 @@ on: permissions: contents: read +env: + CMAKE_INSTALL_MESSAGE: NEVER + CMAKE_LOG_LEVEL: WARNING + MAKEFLAGS: --silent + jobs: test-linux: runs-on: ubuntu-24.04 @@ -23,6 +28,10 @@ jobs: with: context: . file: Dockerfile + build-args: | + CMAKE_INSTALL_MESSAGE=NEVER + CMAKE_LOG_LEVEL=WARNING + MAKEFLAGS=--silent load: true tags: reo7sp/tgbot-cpp cache-from: type=gha,scope=runtime @@ -32,6 +41,10 @@ jobs: with: context: . file: Dockerfile_test + build-args: | + CMAKE_INSTALL_MESSAGE=NEVER + CMAKE_LOG_LEVEL=WARNING + MAKEFLAGS=--silent load: true tags: reo7sp/tgbot-cpp-test cache-from: type=gha,scope=test @@ -45,6 +58,7 @@ jobs: runs-on: windows-2022 timeout-minutes: 30 env: + CMAKE_BUILD_ARGS: -- --quiet POETRY_VIRTUALENVS_IN_PROJECT: "true" steps: - uses: actions/checkout@v6 @@ -76,7 +90,7 @@ jobs: shell: pwsh run: | python -m venv .ci-tools - .ci-tools/Scripts/python -m pip install "clang-format==22.1.8" "conan==2.31.1" "poetry==2.4.1" + .ci-tools/Scripts/python -m pip install --quiet --disable-pip-version-check "clang-format==22.1.8" "conan==2.31.1" "poetry==2.4.1" - name: Add Python tools to PATH shell: pwsh run: Resolve-Path .ci-tools/Scripts | Out-File -FilePath $env:GITHUB_PATH -Append diff --git a/Dockerfile b/Dockerfile index 2881639b..9d24bcde 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,17 +1,21 @@ FROM debian:trixie AS dependencies RUN apt-get -qq update && \ - apt-get -qq install -y \ + DEBIAN_FRONTEND=noninteractive apt-get -qq install -y \ build-essential \ cmake \ libboost-dev \ libcurl4-openssl-dev \ - nlohmann-json3-dev && \ + nlohmann-json3-dev >/dev/null && \ rm -rf /var/lib/apt/lists/* FROM dependencies AS builder +ARG MAKEFLAGS +ARG CMAKE_INSTALL_MESSAGE +ARG CMAKE_LOG_LEVEL + WORKDIR /usr/src/tgbot-cpp COPY include include diff --git a/Dockerfile_test b/Dockerfile_test index 5d8eae3c..47e55f41 100644 --- a/Dockerfile_test +++ b/Dockerfile_test @@ -2,19 +2,23 @@ FROM ubuntu:24.04 LABEL org.opencontainers.image.authors="Oleg Morozenkov " +ARG MAKEFLAGS +ARG CMAKE_INSTALL_MESSAGE +ARG CMAKE_LOG_LEVEL + RUN apt-get -qq update && \ - apt-get -qq install -y \ + DEBIAN_FRONTEND=noninteractive apt-get -qq install -y \ build-essential \ cmake \ python3 \ python3-pip \ - python3-venv && \ + python3-venv >/dev/null && \ rm -rf /var/lib/apt/lists/* ENV CONAN_BUILD_ARGS="--build=missing:gtest/*" RUN python3 -m venv /opt/conan && \ - /opt/conan/bin/pip install --no-cache-dir \ + /opt/conan/bin/pip install --quiet --disable-pip-version-check --no-cache-dir \ "clang-format==22.1.8" \ "conan==2.31.1" \ "poetry==2.4.1" diff --git a/Makefile b/Makefile index 15a6f7dc..bc9f1345 100644 --- a/Makefile +++ b/Makefile @@ -2,10 +2,18 @@ BUILD_TYPE ?= Release BUILD_DIR ?= build/$(BUILD_TYPE) NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 1) CONAN_BUILD_ARGS ?= --build=missing +CONAN_VERBOSITY ?= quiet CONAN_RECIPE_VERSION ?= $(shell git describe --tags --abbrev=0 --match 'v*' 2>/dev/null | sed 's/^v//') CONAN_RECIPE_ARGS ?= +CMAKE_LOG_LEVEL ?= STATUS +CMAKE_INSTALL_MESSAGE ?= ALWAYS +CMAKE_BUILD_ARGS ?= +POETRY_INSTALL_ARGS ?= --no-interaction --quiet INSTALL_PREFIX ?= -CPP_FILES = $(shell find include src tests examples -type f \( -name '*.h' -o -name '*.cpp' \) ! -name '*.inc.h' | sort) +API_METHODS_CPP = src/ApiMethods.cpp +API_METHODS_INC = include/tgbot/ApiMethods.inc.h +API_METHODS_CLANG_FORMAT_CONFIG = api_codegen/clang-format-api-methods.yaml +CPP_FILES = $(shell find include src tests examples -type f \( -name '*.h' -o -name '*.cpp' \) ! -name '*.inc.h' ! -path '$(API_METHODS_CPP)' | sort) PYTHON_FILES = conanfile.py api_codegen DOCKER_IMAGE ?= reo7sp/tgbot-cpp DOCKER_TEST_IMAGE ?= reo7sp/tgbot-cpp-test @@ -71,44 +79,47 @@ endif all: build dependencies: - conan profile detect --exist-ok - conan install . $(CONAN_BUILD_ARGS) -s build_type=$(BUILD_TYPE) -s compiler.cppstd=20 + conan profile detect --exist-ok -v$(CONAN_VERBOSITY) + conan install . $(CONAN_BUILD_ARGS) -v$(CONAN_VERBOSITY) -s build_type=$(BUILD_TYPE) -s compiler.cppstd=20 dependencies-python: - poetry install --no-interaction + poetry install $(POETRY_INSTALL_ARGS) dependencies-with-test: dependencies-python - conan profile detect --exist-ok - conan install . $(CONAN_BUILD_ARGS) -s build_type=$(BUILD_TYPE) -s compiler.cppstd=20 -o '&:with_tests=True' + conan profile detect --exist-ok -v$(CONAN_VERBOSITY) + conan install . $(CONAN_BUILD_ARGS) -v$(CONAN_VERBOSITY) -s build_type=$(BUILD_TYPE) -s compiler.cppstd=20 -o '&:with_tests=True' configure: dependencies - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ -DCMAKE_TOOLCHAIN_FILE=$(abspath $(BUILD_DIR)/generators/conan_toolchain.cmake) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ + -DCMAKE_INSTALL_MESSAGE=$(CMAKE_INSTALL_MESSAGE) \ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ -DENABLE_TESTS=OFF configure-with-system: - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ + -DCMAKE_INSTALL_MESSAGE=$(CMAKE_INSTALL_MESSAGE) \ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ -DENABLE_TESTS=OFF configure-with-test: dependencies-with-test - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ -DCMAKE_TOOLCHAIN_FILE=$(abspath $(BUILD_DIR)/generators/conan_toolchain.cmake) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ + -DCMAKE_INSTALL_MESSAGE=$(CMAKE_INSTALL_MESSAGE) \ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ -DENABLE_TESTS=ON build: configure - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) build-with-system: configure-with-system - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) build-with-test: configure-with-test - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) compile-commands: configure-with-test cmake -E copy_if_different $(BUILD_DIR)/compile_commands.json compile_commands.json @@ -156,6 +167,8 @@ format: format-cpp format-python format-cpp: clang-format -i $(CPP_FILES) + clang-format -i --style='file:$(API_METHODS_CLANG_FORMAT_CONFIG)' $(API_METHODS_CPP) + sh api_codegen/format-api-methods-inc.sh --write $(API_METHODS_INC) $(API_METHODS_CLANG_FORMAT_CONFIG) format-python: poetry run ruff check --fix $(PYTHON_FILES) @@ -165,6 +178,8 @@ lint: lint-cpp lint-python lint-cpp: clang-format --dry-run --Werror $(CPP_FILES) + clang-format --dry-run --Werror --style='file:$(API_METHODS_CLANG_FORMAT_CONFIG)' $(API_METHODS_CPP) + sh api_codegen/format-api-methods-inc.sh --check $(API_METHODS_INC) $(API_METHODS_CLANG_FORMAT_CONFIG) lint-python: poetry run ruff check $(PYTHON_FILES) @@ -184,10 +199,10 @@ docker-test: docker-test-image $(MAKE) docker-test-api-codegen docker-test-only: - docker run --rm -t --platform=$(DOCKER_PLATFORM) $(DOCKER_TEST_IMAGE) make test-only + docker run --rm -t --platform=$(DOCKER_PLATFORM) -e MAKEFLAGS $(DOCKER_TEST_IMAGE) make test-only docker-test-api-codegen: - docker run --rm -t --platform=$(DOCKER_PLATFORM) $(DOCKER_TEST_IMAGE) make test-api-codegen + docker run --rm -t --platform=$(DOCKER_PLATFORM) -e MAKEFLAGS $(DOCKER_TEST_IMAGE) make test-api-codegen docker-push: @set -eu; \ diff --git a/api/codegen.yaml b/api/codegen.yaml index 7a6c32c6..37e42f60 100644 --- a/api/codegen.yaml +++ b/api/codegen.yaml @@ -51,151 +51,151 @@ types: api: addStickerToSet: - parameter_order: [user_id, name, sticker] + args_order: [user_id, name, sticker] answerCallbackQuery: - parameter_order: [callback_query_id, text, show_alert, url, cache_time] + args_order: [callback_query_id, text, show_alert, url, cache_time] answerInlineQuery: - parameter_order: [inline_query_id, results, cache_time, is_personal, next_offset, button] - parameters: + args_order: [inline_query_id, results, cache_time, is_personal, next_offset, button] + args: cache_time: {default: 300} answerPreCheckoutQuery: - parameter_order: [pre_checkout_query_id, ok, error_message] + args_order: [pre_checkout_query_id, ok, error_message] answerShippingQuery: - parameter_order: [shipping_query_id, ok, shipping_options, error_message] + args_order: [shipping_query_id, ok, shipping_options, error_message] answerWebAppQuery: - parameter_order: [web_app_query_id, result] + args_order: [web_app_query_id, result] banChatMember: - parameter_order: [chat_id, user_id, until_date, revoke_messages] - parameters: + args_order: [chat_id, user_id, until_date, revoke_messages] + args: revoke_messages: {default: true, always_send: true} copyMessage: - parameter_order: [chat_id, from_chat_id, message_id, caption, parse_mode, caption_entities, disable_notification, reply_parameters, reply_markup, protect_content, message_thread_id] + args_order: [chat_id, from_chat_id, message_id, caption, parse_mode, caption_entities, disable_notification, reply_parameters, reply_markup, protect_content, message_thread_id] copyMessages: - parameter_order: [chat_id, from_chat_id, message_ids, message_thread_id, disable_notification, protect_content, remove_caption] + args_order: [chat_id, from_chat_id, message_ids, message_thread_id, disable_notification, protect_content, remove_caption] createChatInviteLink: - parameter_order: [chat_id, expire_date, member_limit, name, creates_join_request] + args_order: [chat_id, expire_date, member_limit, name, creates_join_request] createInvoiceLink: - parameter_order: [title, description, payload, provider_token, currency, prices, max_tip_amount, suggested_tip_amounts, provider_data, photo_url, photo_size, photo_width, photo_height, need_name, need_phone_number, need_email, need_shipping_address, send_phone_number_to_provider, send_email_to_provider, is_flexible] - parameters: + args_order: [title, description, payload, provider_token, currency, prices, max_tip_amount, suggested_tip_amounts, provider_data, photo_url, photo_size, photo_width, photo_height, need_name, need_phone_number, need_email, need_shipping_address, send_phone_number_to_provider, send_email_to_provider, is_flexible] + args: provider_token: {declaration_required: true} createNewStickerSet: - parameter_order: [user_id, name, title, stickers, sticker_type, needs_repainting] - parameters: + args_order: [user_id, name, title, stickers, sticker_type, needs_repainting] + args: sticker_type: {type: "Sticker::Type", default: "Sticker::Type::Regular"} deleteMyCommands: - parameter_order: [scope, language_code] + args_order: [scope, language_code] editChatInviteLink: - parameter_order: [chat_id, invite_link, expire_date, member_limit, name, creates_join_request] + args_order: [chat_id, invite_link, expire_date, member_limit, name, creates_join_request] editForumTopic: - parameter_order: [chat_id, message_thread_id, name, icon_custom_emoji_id] + args_order: [chat_id, message_thread_id, name, icon_custom_emoji_id] editMessageCaption: return_type: std::shared_ptr - parameter_order: [chat_id, message_id, caption, inline_message_id, reply_markup, parse_mode, caption_entities] + args_order: [chat_id, message_id, caption, inline_message_id, reply_markup, parse_mode, caption_entities] editMessageLiveLocation: return_type: std::shared_ptr - parameter_order: [latitude, longitude, chat_id, message_id, inline_message_id, reply_markup, horizontal_accuracy, heading, proximity_alert_radius] + args_order: [latitude, longitude, chat_id, message_id, inline_message_id, reply_markup, horizontal_accuracy, heading, proximity_alert_radius] editMessageMedia: return_type: std::shared_ptr - parameter_order: [media, chat_id, message_id, inline_message_id, reply_markup] + args_order: [media, chat_id, message_id, inline_message_id, reply_markup] editMessageReplyMarkup: return_type: std::shared_ptr - parameter_order: [chat_id, message_id, inline_message_id, reply_markup] + args_order: [chat_id, message_id, inline_message_id, reply_markup] editMessageText: return_type: std::shared_ptr - parameter_order: [text, chat_id, message_id, inline_message_id, parse_mode, link_preview_options, reply_markup, entities] + args_order: [text, chat_id, message_id, inline_message_id, parse_mode, link_preview_options, reply_markup, entities] forwardMessage: - parameter_order: [chat_id, from_chat_id, message_id, disable_notification, protect_content, message_thread_id] + args_order: [chat_id, from_chat_id, message_id, disable_notification, protect_content, message_thread_id] forwardMessages: - parameter_order: [chat_id, from_chat_id, message_ids, message_thread_id, disable_notification, protect_content] + args_order: [chat_id, from_chat_id, message_ids, message_thread_id, disable_notification, protect_content] getGameHighScores: - parameter_order: [user_id, chat_id, message_id, inline_message_id] + args_order: [user_id, chat_id, message_id, inline_message_id] getMyCommands: - parameter_order: [scope, language_code] + args_order: [scope, language_code] getUpdates: - parameter_order: [offset, limit, timeout, allowed_updates] - parameters: + args_order: [offset, limit, timeout, allowed_updates] + args: limit: {default: 100} getUserProfilePhotos: - parameter_order: [user_id, offset, limit] - parameters: + args_order: [user_id, offset, limit] + args: limit: {default: 100} promoteChatMember: - parameter_order: [chat_id, user_id, can_change_info, can_post_messages, can_edit_messages, can_delete_messages, can_invite_users, can_pin_messages, can_promote_members, is_anonymous, can_manage_chat, can_manage_video_chats, can_restrict_members, can_manage_topics, can_post_stories, can_edit_stories, can_delete_stories] + args_order: [chat_id, user_id, can_change_info, can_post_messages, can_edit_messages, can_delete_messages, can_invite_users, can_pin_messages, can_promote_members, is_anonymous, can_manage_chat, can_manage_video_chats, can_restrict_members, can_manage_topics, can_post_stories, can_edit_stories, can_delete_stories] replaceStickerInSet: - parameter_order: [user_id, name, old_sticker, sticker] + args_order: [user_id, name, old_sticker, sticker] restrictChatMember: - parameter_order: [chat_id, user_id, permissions, until_date, use_independent_chat_permissions] + args_order: [chat_id, user_id, permissions, until_date, use_independent_chat_permissions] sendAnimation: - parameter_order: [chat_id, animation, duration, width, height, thumbnail, caption, reply_parameters, reply_markup, parse_mode, disable_notification, caption_entities, message_thread_id, protect_content, has_spoiler, business_connection_id] + args_order: [chat_id, animation, duration, width, height, thumbnail, caption, reply_parameters, reply_markup, parse_mode, disable_notification, caption_entities, message_thread_id, protect_content, has_spoiler, business_connection_id] sendAudio: - parameter_order: [chat_id, audio, caption, duration, performer, title, thumbnail, reply_parameters, reply_markup, parse_mode, disable_notification, caption_entities, message_thread_id, protect_content, business_connection_id] + args_order: [chat_id, audio, caption, duration, performer, title, thumbnail, reply_parameters, reply_markup, parse_mode, disable_notification, caption_entities, message_thread_id, protect_content, business_connection_id] sendChatAction: - parameter_order: [chat_id, action, message_thread_id, business_connection_id] + args_order: [chat_id, action, message_thread_id, business_connection_id] sendContact: - parameter_order: [chat_id, phone_number, first_name, last_name, vcard, disable_notification, reply_parameters, reply_markup, message_thread_id, protect_content, business_connection_id] + args_order: [chat_id, phone_number, first_name, last_name, vcard, disable_notification, reply_parameters, reply_markup, message_thread_id, protect_content, business_connection_id] sendDice: - parameter_order: [chat_id, disable_notification, reply_parameters, reply_markup, emoji, message_thread_id, protect_content, business_connection_id] + args_order: [chat_id, disable_notification, reply_parameters, reply_markup, emoji, message_thread_id, protect_content, business_connection_id] sendDocument: - parameter_order: [chat_id, document, thumbnail, caption, reply_parameters, reply_markup, parse_mode, disable_notification, caption_entities, disable_content_type_detection, message_thread_id, protect_content, business_connection_id] + args_order: [chat_id, document, thumbnail, caption, reply_parameters, reply_markup, parse_mode, disable_notification, caption_entities, disable_content_type_detection, message_thread_id, protect_content, business_connection_id] sendGame: - parameter_order: [chat_id, game_short_name, reply_parameters, reply_markup, disable_notification, message_thread_id, protect_content, business_connection_id] + args_order: [chat_id, game_short_name, reply_parameters, reply_markup, disable_notification, message_thread_id, protect_content, business_connection_id] sendInvoice: - parameter_order: [chat_id, title, description, payload, provider_token, currency, prices, provider_data, photo_url, photo_size, photo_width, photo_height, need_name, need_phone_number, need_email, need_shipping_address, send_phone_number_to_provider, send_email_to_provider, is_flexible, reply_parameters, reply_markup, disable_notification, message_thread_id, max_tip_amount, suggested_tip_amounts, start_parameter, protect_content] - parameters: + args_order: [chat_id, title, description, payload, provider_token, currency, prices, provider_data, photo_url, photo_size, photo_width, photo_height, need_name, need_phone_number, need_email, need_shipping_address, send_phone_number_to_provider, send_email_to_provider, is_flexible, reply_parameters, reply_markup, disable_notification, message_thread_id, max_tip_amount, suggested_tip_amounts, start_parameter, protect_content] + args: provider_token: {declaration_required: true} sendLocation: - parameter_order: [chat_id, latitude, longitude, live_period, reply_parameters, reply_markup, disable_notification, horizontal_accuracy, heading, proximity_alert_radius, message_thread_id, protect_content, business_connection_id] + args_order: [chat_id, latitude, longitude, live_period, reply_parameters, reply_markup, disable_notification, horizontal_accuracy, heading, proximity_alert_radius, message_thread_id, protect_content, business_connection_id] sendMediaGroup: - parameter_order: [chat_id, media, disable_notification, reply_parameters, message_thread_id, protect_content, business_connection_id] + args_order: [chat_id, media, disable_notification, reply_parameters, message_thread_id, protect_content, business_connection_id] sendMessage: - parameter_order: [chat_id, text, link_preview_options, reply_parameters, reply_markup, parse_mode, disable_notification, entities, message_thread_id, protect_content, business_connection_id] + args_order: [chat_id, text, link_preview_options, reply_parameters, reply_markup, parse_mode, disable_notification, entities, message_thread_id, protect_content, business_connection_id] sendPhoto: - parameter_order: [chat_id, photo, caption, reply_parameters, reply_markup, parse_mode, disable_notification, caption_entities, message_thread_id, protect_content, has_spoiler, business_connection_id] + args_order: [chat_id, photo, caption, reply_parameters, reply_markup, parse_mode, disable_notification, caption_entities, message_thread_id, protect_content, has_spoiler, business_connection_id] sendPoll: - parameter_order: [chat_id, question, options, disable_notification, reply_parameters, reply_markup, is_anonymous, type, allows_multiple_answers, correct_option_id, explanation, explanation_parse_mode, explanation_entities, open_period, close_date, is_closed, message_thread_id, protect_content, business_connection_id] - parameters: + args_order: [chat_id, question, options, disable_notification, reply_parameters, reply_markup, is_anonymous, type, allows_multiple_answers, correct_option_id, explanation, explanation_parse_mode, explanation_entities, open_period, close_date, is_closed, message_thread_id, protect_content, business_connection_id] + args: is_anonymous: {default: true} sendSticker: - parameter_order: [chat_id, sticker, reply_parameters, reply_markup, disable_notification, message_thread_id, protect_content, emoji, business_connection_id] + args_order: [chat_id, sticker, reply_parameters, reply_markup, disable_notification, message_thread_id, protect_content, emoji, business_connection_id] sendVenue: - parameter_order: [chat_id, latitude, longitude, title, address, foursquare_id, foursquare_type, disable_notification, reply_parameters, reply_markup, google_place_id, google_place_type, message_thread_id, protect_content, business_connection_id] + args_order: [chat_id, latitude, longitude, title, address, foursquare_id, foursquare_type, disable_notification, reply_parameters, reply_markup, google_place_id, google_place_type, message_thread_id, protect_content, business_connection_id] sendVideo: - parameter_order: [chat_id, video, supports_streaming, duration, width, height, thumbnail, caption, reply_parameters, reply_markup, parse_mode, disable_notification, caption_entities, message_thread_id, protect_content, has_spoiler, business_connection_id] + args_order: [chat_id, video, supports_streaming, duration, width, height, thumbnail, caption, reply_parameters, reply_markup, parse_mode, disable_notification, caption_entities, message_thread_id, protect_content, has_spoiler, business_connection_id] sendVideoNote: - parameter_order: [chat_id, video_note, reply_parameters, disable_notification, duration, length, thumbnail, reply_markup, message_thread_id, protect_content, business_connection_id] + args_order: [chat_id, video_note, reply_parameters, disable_notification, duration, length, thumbnail, reply_markup, message_thread_id, protect_content, business_connection_id] sendVoice: - parameter_order: [chat_id, voice, caption, duration, reply_parameters, reply_markup, parse_mode, disable_notification, caption_entities, message_thread_id, protect_content, business_connection_id] + args_order: [chat_id, voice, caption, duration, reply_parameters, reply_markup, parse_mode, disable_notification, caption_entities, message_thread_id, protect_content, business_connection_id] setChatAdministratorCustomTitle: - parameter_order: [chat_id, user_id, custom_title] + args_order: [chat_id, user_id, custom_title] setGameScore: return_type: std::shared_ptr - parameter_order: [user_id, score, force, disable_edit_message, chat_id, message_id, inline_message_id] + args_order: [user_id, score, force, disable_edit_message, chat_id, message_id, inline_message_id] setMessageReaction: - parameter_order: [chat_id, message_id, reaction, is_big] + args_order: [chat_id, message_id, reaction, is_big] setMyCommands: - parameter_order: [commands, scope, language_code] + args_order: [commands, scope, language_code] setMyDefaultAdministratorRights: - parameter_order: [rights, for_channels] + args_order: [rights, for_channels] setMyName: - parameter_order: [name, language_code] + args_order: [name, language_code] setMyShortDescription: - parameter_order: [short_description, language_code] + args_order: [short_description, language_code] setPassportDataErrors: - parameter_order: [user_id, errors] + args_order: [user_id, errors] setStickerEmojiList: - parameter_order: [sticker, emoji_list] + args_order: [sticker, emoji_list] setStickerPositionInSet: - parameter_order: [sticker, position] + args_order: [sticker, position] setStickerSetThumbnail: - parameter_order: [name, user_id, format, thumbnail] + args_order: [name, user_id, format, thumbnail] setStickerSetTitle: - parameter_order: [name, title] + args_order: [name, title] setWebhook: - parameter_order: [url, certificate, max_connections, allowed_updates, ip_address, drop_pending_updates, secret_token] - parameters: + args_order: [url, certificate, max_connections, allowed_updates, ip_address, drop_pending_updates, secret_token] + args: max_connections: {default: 40} stopMessageLiveLocation: return_type: std::shared_ptr - parameter_order: [chat_id, message_id, inline_message_id, reply_markup] + args_order: [chat_id, message_id, inline_message_id, reply_markup] uploadStickerFile: - parameter_order: [user_id, sticker, sticker_format] + args_order: [user_id, sticker, sticker_format] diff --git a/api_codegen/clang-format-api-methods.yaml b/api_codegen/clang-format-api-methods.yaml new file mode 100644 index 00000000..fcf21c86 --- /dev/null +++ b/api_codegen/clang-format-api-methods.yaml @@ -0,0 +1,8 @@ +BasedOnStyle: InheritParentConfig +ColumnLimit: 116 +BinPackArguments: false +BinPackParameters: OnePerLine +AllowAllArgumentsOnNextLine: false +WhitespaceSensitiveMacros: + - makeFields + - sendRequest diff --git a/api_codegen/format-api-methods-inc.sh b/api_codegen/format-api-methods-inc.sh new file mode 100644 index 00000000..2514d3ff --- /dev/null +++ b/api_codegen/format-api-methods-inc.sh @@ -0,0 +1,40 @@ +#!/bin/sh + +set -eu + +mode=$1 +input=$2 +style=$3 +temporary_directory=$(mktemp -d) +wrapped=$temporary_directory/wrapped.h +formatted=$temporary_directory/formatted.h +output=$temporary_directory/output.inc.h + +cleanup() { + rm -f "$wrapped" "$formatted" "$output" + rmdir "$temporary_directory" +} +trap cleanup EXIT HUP INT TERM + +{ + printf 'class Api {\npublic:\n' + sed '1,2d' "$input" + printf '};\n' +} >"$wrapped" + +clang-format --style="file:$style" "$wrapped" >"$formatted" + +{ + sed -n '1p' "$input" + printf '\n' + sed -n '/^public:$/,/^};$/p' "$formatted" | sed '1d;$d' +} >"$output" + +if [ "$mode" = "--check" ]; then + if ! cmp -s "$input" "$output"; then + printf '%s is not formatted\n' "$input" >&2 + exit 1 + fi +else + mv "$output" "$input" +fi diff --git a/api_codegen/generate.py b/api_codegen/generate.py index 08fb8d06..fb88d175 100644 --- a/api_codegen/generate.py +++ b/api_codegen/generate.py @@ -1,7 +1,6 @@ from __future__ import annotations import re -import subprocess import textwrap from dataclasses import dataclass from pathlib import Path @@ -27,55 +26,60 @@ API_CONFIG = CONFIG.get("api", {}) +def run(schema_path: Path, root: Path) -> None: + generated = _OpenApiGenerator(schema_path, root).generate() + print(f"Generated {generated.types} types and {generated.methods} API methods") + + @dataclass(frozen=True) -class GeneratedCount: - objects: int +class _GeneratedCount: + types: int methods: int @dataclass(frozen=True) -class ConstantModel: +class _ConstantModel: name: str value: str @dataclass(frozen=True) -class FieldModel: +class _FieldModel: wire_name: str cpp_name: str cpp_type: str required: bool description: tuple[str, ...] - constant: ConstantModel | None - enum: EnumModel | None + constant: _ConstantModel | None + enum: _EnumModel | None @dataclass(frozen=True) -class EnumValueModel: +class _EnumValueModel: name: str value: str @dataclass(frozen=True) -class EnumModel: +class _EnumModel: name: str - values: tuple[EnumValueModel, ...] + values: tuple[_EnumValueModel, ...] @dataclass(frozen=True) -class ObjectModel: +class _TypeModel: name: str description: tuple[str, ...] - constants: tuple[ConstantModel, ...] - enums: tuple[EnumModel, ...] - fields: tuple[FieldModel, ...] + constants: tuple[_ConstantModel, ...] + enums: tuple[_EnumModel, ...] + fields: tuple[_FieldModel, ...] union_members: tuple[str, ...] dependencies: tuple[str, ...] standard_headers: tuple[str, ...] @dataclass(frozen=True) -class ParameterModel: +class _ArgModel: wire_name: str cpp_name: str cpp_type: str @@ -88,433 +92,447 @@ class ParameterModel: @dataclass(frozen=True) -class MethodModel: +class _MethodModel: name: str return_type: str response_type: str + return_description: str description: tuple[str, ...] - parameters: tuple[ParameterModel, ...] - - -def run(schema_path: Path, root: Path) -> None: - generated = generate_openapi(schema_path, root) - print(f"Generated {generated.objects} types and {generated.methods} API methods") - - -def generate_openapi(schema_path: Path, root: Path) -> GeneratedCount: - document = yaml.safe_load(schema_path.read_text(encoding="utf-8")) - components = {name: schema for name, schema in document["components"]["schemas"].items() if "x-tags" in schema} - objects = _build_objects(components) - methods = _build_methods(document["paths"]) - outputs = { - root / "include" / "tgbot" / "Types.h": _render_template("types.h.j2", objects=objects), - root / "src" / "Types.cpp": _render_template("types.cpp.j2", objects=objects), - root / "include" / "tgbot" / "ApiMethods.inc.h": _render_template("api_methods.inc.h.j2", methods=methods), - root / "src" / "ApiMethods.cpp": _render_template("api_methods.cpp.j2", methods=methods), - } - for path, content in outputs.items(): - _write(path, content) - - return GeneratedCount(len(objects), len(methods)) - - -def _build_objects(components: dict[str, Schema]) -> tuple[ObjectModel, ...]: - names = set(components) - objects = [] - for name in sorted(names): - schema = components[name] - required = set(schema.get("required", [])) - union_members = _union_members(name, schema, names) - fields = tuple( - _build_field(name, field_name, field, field_name in required) - for field_name, field in schema.get("properties", {}).items() - ) - objects.append( - ObjectModel( - name=name, - description=_comment_lines(schema.get("description", ""), 92), - constants=_object_constants(fields), - enums=tuple(field.enum for field in fields if field.enum), - fields=fields, - union_members=union_members, - dependencies=_object_dependencies(name, fields, union_members, names), - standard_headers=_object_standard_headers(fields, union_members), - ) - ) - - return tuple(objects) - - -def _build_field(object_name: str, name: str, schema: Schema, required: bool) -> FieldModel: - enum = _field_enum(object_name, name) - field_config = TYPE_CONFIG.get(object_name, {}).get("fields", {}).get(name, {}) - cpp_type = field_config.get("type", enum.name if enum else _field_type(name, schema, required)) - return FieldModel( - wire_name=name, - cpp_name=_snake_to_camel(name), - cpp_type=cpp_type, - required=required, - description=_comment_lines(schema.get("description", ""), 88), - constant=_field_constant(name, schema, required), - enum=enum, - ) - + args: tuple[_ArgModel, ...] + args_name: str | None + + +class _OpenApiGenerator: + def __init__(self, schema_path: Path, root: Path) -> None: + self._schema_path = schema_path + self._root = root + + def generate(self) -> _GeneratedCount: + document = yaml.safe_load(self._schema_path.read_text(encoding="utf-8")) + components = {name: schema for name, schema in document["components"]["schemas"].items() if "x-tags" in schema} + types = _TypeModelBuilder(components).build() + methods = _MethodModelBuilder(document["paths"]).build() + + for path, content in self._outputs(types, methods).items(): + self._write(path, content) + + return _GeneratedCount(len(types), len(methods)) + + def _outputs( + self, + types: tuple[_TypeModel, ...], + methods: tuple[_MethodModel, ...], + ) -> dict[Path, str]: + return { + self._root / "include" / "tgbot" / "Types.h": self._render("types.h.j2", types=types, methods=methods), + self._root / "src" / "Types.cpp": self._render("types.cpp.j2", types=types), + self._root / "include" / "tgbot" / "ApiMethods.inc.h": self._render( + "api_methods.inc.h.j2", methods=methods + ), + self._root / "src" / "ApiMethods.cpp": self._render("api_methods.cpp.j2", methods=methods), + } + + @staticmethod + def _render(name: str, **context: Any) -> str: + return TEMPLATES.get_template(name).render(**context) + + @staticmethod + def _write(path: Path, content: str) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(content, encoding="utf-8") + + +class _CppTypeResolver: + @classmethod + def api_type(cls, schema: Schema) -> str: + if name := cls.ref_name(schema): + return f"std::shared_ptr<{name}>" + if choices := schema.get("oneOf"): + return f"std::variant<{', '.join(cls.api_type(item) for item in choices)}>" + if schema.get("type") == "array": + return f"std::vector<{cls.api_type(schema['items'])}>" + + return cls.type(schema) + + @classmethod + def type(cls, schema: Schema) -> str: + if name := cls.ref_name(schema): + return f"std::shared_ptr<{name}>" + if choices := schema.get("oneOf"): + return f"std::variant<{', '.join(cls.type(item) for item in choices)}>" + schema_type = schema.get("type") + if schema_type == "array": + return f"std::vector<{cls.type(schema['items'])}>" + if schema_type == "boolean": + return "bool" + if schema_type == "integer": + return "std::int64_t" if schema.get("format") == "int64" else "std::int32_t" + if schema_type == "number": + return "double" + if schema_type == "string": + return "std::string" + + return "nlohmann::json" + + @staticmethod + def telegram_integer(name: str, cpp_type: str) -> str: + wide_id = name in { + "user_id", + "chat_id", + "direct_messages_topic_id", + } or name.endswith(("_user_id", "_chat_id")) + if wide_id and cpp_type == "std::int32_t": + return "std::int64_t" + + return cpp_type + + @classmethod + def field_type(cls, name: str, schema: Schema, required: bool) -> str: + result = cls.telegram_integer(name, cls.type(schema)) + if required or result.startswith("std::shared_ptr<"): + return result -def _field_enum(object_name: str, field_name: str) -> EnumModel | None: - values = TYPE_CONFIG.get(object_name, {}).get("fields", {}).get(field_name, {}).get("enum") - if not values: - return None + return f"std::optional<{result}>" - return EnumModel( - name="Type", - values=tuple(EnumValueModel(name=name, value=value) for name, value in values.items()), - ) - - -def _object_constants(fields: tuple[FieldModel, ...]) -> tuple[ConstantModel, ...]: - return tuple(field.constant for field in fields if field.constant) - - -def _object_dependencies( - name: str, - fields: tuple[FieldModel, ...], - union_members: tuple[str, ...], - object_names: set[str], -) -> tuple[str, ...]: - cpp_types = [field.cpp_type for field in fields] - cpp_types.extend(union_members) - dependencies = { - token - for cpp_type in cpp_types - for token in re.findall(r"\b[A-Z][A-Za-z0-9]*\b", cpp_type) - if token in object_names and token != name - } - - return tuple(sorted(dependencies)) - - -def _object_standard_headers(fields: tuple[FieldModel, ...], union_members: tuple[str, ...]) -> tuple[str, ...]: - cpp_types = " ".join(field.cpp_type for field in fields) - headers = {"memory"} - for cpp_type, header in ( - ("std::int", "cstdint"), - ("std::optional", "optional"), - ("std::string", "string"), - ("std::variant", "variant"), - ("std::vector", "vector"), - ): - if cpp_type in cpp_types: - headers.add(header) - if union_members: - headers.add("variant") - - return tuple(sorted(headers)) - - -def _build_methods(paths: dict[str, Schema]) -> tuple[MethodModel, ...]: - methods = [] - for path in sorted(paths): - operation = paths[path]["post"] - name = operation["operationId"] - request = _request_schema(operation) - multipart = _multipart_schema(operation) - properties = dict(request.get("properties", {})) - for parameter_name, parameter in multipart.get("properties", {}).items(): - properties.setdefault(parameter_name, parameter) - required = set(request.get("required", [])) | set(multipart.get("required", [])) - binary = _binary_parameters(operation) - parameter_names = _ordered_parameter_names(name, properties, required) - response_type = _api_cpp_type(_response_schema(operation)) - method_config = API_CONFIG.get(name, {}) - methods.append( - MethodModel( - name=name, - return_type=method_config.get("return_type", response_type), - response_type=response_type, - description=_comment_lines(operation.get("description", ""), 88), - parameters=tuple( - _build_parameter( - name, - parameter_name, - properties[parameter_name], - parameter_name in required, - parameter_name in binary, - ) - for parameter_name in parameter_names - ), - ) - ) + @classmethod + def ref_name(cls, schema: Schema) -> str | None: + if ref := schema.get("$ref"): + return str(ref).rsplit("/", 1)[-1] + for item in schema.get("allOf", []): + if name := cls.ref_name(item): + return name - return tuple(methods) - - -def _ordered_parameter_names(method_name: str, properties: dict[str, Schema], required: set[str]) -> list[str]: - method_config = API_CONFIG.get(method_name, {}) - preferred = method_config.get("parameter_order", ()) - parameter_order = {name: index for index, name in enumerate(preferred)} - declaration_required = required | { - name for name in properties if method_config.get("parameters", {}).get(name, {}).get("declaration_required") - } - required_names = sorted( - (name for name in properties if name in declaration_required), - key=lambda name: ( - name != "chat_id", - parameter_order.get(name, len(parameter_order)), - name, - ), - ) - optional_names = [name for name in properties if name not in declaration_required] - optional_names.sort(key=lambda name: (parameter_order.get(name, len(parameter_order)), name)) - - return required_names + optional_names - - -def _build_parameter(method_name: str, name: str, schema: Schema, required: bool, binary: bool) -> ParameterModel: - parameter_config = API_CONFIG.get(method_name, {}).get("parameters", {}).get(name, {}) - override = parameter_config.get("type") - if override: - cpp_type = override - elif name in {"chat_id", "from_chat_id"}: - cpp_type = "std::variant" - elif name == "certificate" and binary: - cpp_type = "std::shared_ptr" - elif binary: - cpp_type = "std::variant, std::string>" - else: - cpp_type = _api_cpp_type(schema) - cpp_type = _telegram_integer_type(name, cpp_type) - return ParameterModel( - wire_name=name, - cpp_name=_snake_to_camel(name), - cpp_type=cpp_type, - declaration_type=_parameter_declaration_type(cpp_type), - required=required, - always_send=bool(parameter_config.get("always_send")), - default_value=( - None - if required or parameter_config.get("declaration_required") - else _parameter_default(cpp_type, method_name, name) - ), - wire_default_value=( - None if parameter_config.get("always_send") else _configured_parameter_default(method_name, name) - ), - description=_comment_lines(schema.get("description", ""), 72), - ) - - -def _parameter_declaration_type(cpp_type: str) -> str: - if cpp_type == "std::string" or cpp_type.startswith("std::vector<"): - return f"const {cpp_type}&" - if cpp_type == "nlohmann::json": - return "const nlohmann::json&" - - return cpp_type - - -def _parameter_default(cpp_type: str, method_name: str, parameter_name: str) -> str: - if (default := _configured_parameter_default(method_name, parameter_name)) is not None: - return default - if cpp_type == "bool": - return "false" - if cpp_type in {"std::int32_t", "std::int64_t", "double"}: - return "0" - if cpp_type == "std::string": - return '""' - if cpp_type.startswith("std::shared_ptr<"): - return "nullptr" - if cpp_type == "nlohmann::json": - return "nullptr" - - return "{ }" - - -def _configured_parameter_default(method_name: str, parameter_name: str) -> str | None: - parameter_config = API_CONFIG.get(method_name, {}).get("parameters", {}).get(parameter_name, {}) - default = parameter_config.get("default") - if default is None: return None - if isinstance(default, bool): - return str(default).lower() - - return str(default) - - -def _write(path: Path, content: str) -> None: - content = _format_cpp(path, content) - path.parent.mkdir(parents=True, exist_ok=True) - path.write_text(content, encoding="utf-8") - - -def _format_cpp(path: Path, content: str) -> str: - if path.name.endswith(".inc.h"): - return _format_cpp_class_fragment(path, content) - - return _run_clang_format(path, content) -def _format_cpp_class_fragment(path: Path, content: str) -> str: - marker, separator, body = content.partition("\n\n") - if not separator: - raise ValueError(f"Generated C++ fragment {path} has no marker") - wrapped = f"class Api {{\npublic:\n{body}}};\n" - formatted = _run_clang_format(path, wrapped) - body_start = formatted.index("public:\n") + len("public:\n") - body_end = formatted.rindex("\n};") +class _BaseModelBuilder: + @staticmethod + def _comment_lines(text: str, width: int) -> tuple[str, ...]: + normalized = " ".join(text.replace("*/", "* /").split()) + if not normalized: + return () - return f"{marker}\n\n{formatted[body_start:body_end]}\n" + return tuple(textwrap.wrap(normalized, width=width, break_long_words=False)) + @staticmethod + def _cpp_name(value: str) -> str: + first, *rest = value.split("_") -def _run_clang_format(path: Path, content: str) -> str: - process = subprocess.run( - ["clang-format", f"--assume-filename={path.name}"], - input=content, - text=True, - capture_output=True, - check=True, - ) + return first + "".join(part[:1].upper() + part[1:] for part in rest) - return process.stdout +class _TypeModelBuilder(_BaseModelBuilder): + def __init__(self, components: dict[str, Schema], type_config: Schema = TYPE_CONFIG) -> None: + self._components = components + self._type_config = type_config + self._names = set(components) -def _render_template(name: str, **context: Any) -> str: - return TEMPLATES.get_template(name).render(**context) - - -def _request_schema(operation: Schema) -> Schema: - return ( - operation.get("requestBody", {}) - .get("content", {}) - .get("application/json", {"schema": {"type": "object", "properties": {}}})["schema"] - ) - - -def _multipart_schema(operation: Schema) -> Schema: - return operation.get("requestBody", {}).get("content", {}).get("multipart/form-data", {"schema": {}})["schema"] + def build(self) -> tuple[_TypeModel, ...]: + types = [] + for name in sorted(self._names): + schema = self._components[name] + required = set(schema.get("required", [])) + union_members = self._union_members(name, schema) + fields = tuple( + self._build_field(name, field_name, field, field_name in required) + for field_name, field in schema.get("properties", {}).items() + ) + types.append( + _TypeModel( + name=name, + description=self._comment_lines(schema.get("description", ""), 92), + constants=self._constants(fields), + enums=tuple(field.enum for field in fields if field.enum), + fields=fields, + union_members=union_members, + dependencies=self._dependencies(name, fields, union_members), + standard_headers=self._standard_headers(fields, union_members), + ) + ) + return tuple(types) + + def _build_field(self, type_name: str, name: str, schema: Schema, required: bool) -> _FieldModel: + enum = self._field_enum(type_name, name) + field_config = self._type_config.get(type_name, {}).get("fields", {}).get(name, {}) + cpp_type = field_config.get("type", enum.name if enum else _CppTypeResolver.field_type(name, schema, required)) + return _FieldModel( + wire_name=name, + cpp_name=self._cpp_name(name), + cpp_type=cpp_type, + required=required, + description=self._comment_lines(schema.get("description", ""), 88), + constant=self._field_constant(name, schema, required), + enum=enum, + ) -def _binary_parameters(operation: Schema) -> set[str]: - multipart = operation.get("requestBody", {}).get("content", {}).get("multipart/form-data", {}) + def _field_enum(self, type_name: str, field_name: str) -> _EnumModel | None: + values = self._type_config.get(type_name, {}).get("fields", {}).get(field_name, {}).get("enum") + if not values: + return None - return { - name - for name, schema in multipart.get("schema", {}).get("properties", {}).items() - if schema.get("format") == "binary" - } + return _EnumModel( + name="Type", + values=tuple(_EnumValueModel(name=name, value=value) for name, value in values.items()), + ) + @staticmethod + def _constants(fields: tuple[_FieldModel, ...]) -> tuple[_ConstantModel, ...]: + return tuple(field.constant for field in fields if field.constant) + + def _dependencies( + self, + name: str, + fields: tuple[_FieldModel, ...], + union_members: tuple[str, ...], + ) -> tuple[str, ...]: + cpp_types = [field.cpp_type for field in fields] + cpp_types.extend(union_members) + dependencies = { + token + for cpp_type in cpp_types + for token in re.findall(r"\b[A-Z][A-Za-z0-9]*\b", cpp_type) + if token in self._names and token != name + } + + return tuple(sorted(dependencies)) + + @staticmethod + def _standard_headers(fields: tuple[_FieldModel, ...], union_members: tuple[str, ...]) -> tuple[str, ...]: + cpp_types = " ".join(field.cpp_type for field in fields) + headers = {"memory"} + for cpp_type, header in ( + ("std::int", "cstdint"), + ("std::optional", "optional"), + ("std::string", "string"), + ("std::variant", "variant"), + ("std::vector", "vector"), + ): + if cpp_type in cpp_types: + headers.add(header) + if union_members: + headers.add("variant") + + return tuple(sorted(headers)) + + @staticmethod + def _field_constant(name: str, schema: Schema, required: bool) -> _ConstantModel | None: + if not required or name not in {"source", "status", "type"}: + return None + if schema.get("type") != "string": + return None + + values = schema.get("enum", []) + if len(values) == 1: + return _ConstantModel(name.upper(), str(values[0])) + + description = schema.get("description", "") + for pattern in ( + r"\bmust be ([a-z0-9_]+)(?:[.,]|$)", + r'\balways ["“]([a-z0-9_]+)["”]', + ): + if match := re.search(pattern, description): + return _ConstantModel(name.upper(), match.group(1)) -def _response_schema(operation: Schema) -> Schema: - response = operation["responses"]["200"]["content"]["application/json"]["schema"] - for part in response.get("allOf", []): - if result := part.get("properties", {}).get("result"): - return result + return None - raise ValueError(f"Response type is missing for {operation['operationId']}") + def _union_members(self, name: str, schema: Schema) -> tuple[str, ...]: + if schema.get("properties"): + return () + return tuple( + dict.fromkeys( + line.strip() + for line in schema.get("description", "").splitlines() + if line.strip() in self._names and line.strip() != name + ) + ) -def _field_type(name: str, schema: Schema, required: bool) -> str: - result = _telegram_integer_type(name, _cpp_type(schema)) - if required or result.startswith("std::shared_ptr<"): - return result - return f"std::optional<{result}>" +class _MethodModelBuilder(_BaseModelBuilder): + def __init__(self, paths: dict[str, Schema], api_config: Schema = API_CONFIG) -> None: + self._paths = paths + self._api_config = api_config + def build(self) -> tuple[_MethodModel, ...]: + return tuple(self._build_method(self._paths[path]["post"]) for path in sorted(self._paths)) -def _field_constant(name: str, schema: Schema, required: bool) -> ConstantModel | None: - if not required or name not in {"source", "status", "type"}: - return None - if schema.get("type") != "string": - return None - - values = schema.get("enum", []) - if len(values) == 1: - return ConstantModel(name.upper(), str(values[0])) - - description = schema.get("description", "") - for pattern in ( - r"\bmust be ([a-z0-9_]+)(?:[.,]|$)", - r"\balways [\"“]([a-z0-9_]+)[\"”]", - ): - if match := re.search(pattern, description): - return ConstantModel(name.upper(), match.group(1)) - - return None - - -def _api_cpp_type(schema: Schema) -> str: - if name := _ref_name(schema): - return f"std::shared_ptr<{name}>" - if choices := schema.get("oneOf"): - return f"std::variant<{', '.join(_api_cpp_type(item) for item in choices)}>" - if schema.get("type") == "array": - return f"std::vector<{_api_cpp_type(schema['items'])}>" - - return _cpp_type(schema) - - -def _cpp_type(schema: Schema) -> str: - if name := _ref_name(schema): - return f"std::shared_ptr<{name}>" - if choices := schema.get("oneOf"): - return f"std::variant<{', '.join(_cpp_type(item) for item in choices)}>" - schema_type = schema.get("type") - if schema_type == "array": - return f"std::vector<{_cpp_type(schema['items'])}>" - if schema_type == "boolean": - return "bool" - if schema_type == "integer": - return "std::int64_t" if schema.get("format") == "int64" else "std::int32_t" - if schema_type == "number": - return "double" - if schema_type == "string": - return "std::string" - - return "nlohmann::json" - - -def _telegram_integer_type(name: str, cpp_type: str) -> str: - wide_id = name in { - "user_id", - "chat_id", - "direct_messages_topic_id", - } or name.endswith(("_user_id", "_chat_id")) - if wide_id and cpp_type == "std::int32_t": - return "std::int64_t" - - return cpp_type - - -def _union_members(name: str, schema: Schema, names: set[str]) -> tuple[str, ...]: - if schema.get("properties"): - return () - - return tuple( - dict.fromkeys( - line.strip() - for line in schema.get("description", "").splitlines() - if line.strip() in names and line.strip() != name + def _build_method(self, operation: Schema) -> _MethodModel: + name = operation["operationId"] + request = self._request_schema(operation) + multipart = self._multipart_schema(operation) + properties = dict(request.get("properties", {})) + for arg_name, arg in multipart.get("properties", {}).items(): + properties.setdefault(arg_name, arg) + required = set(request.get("required", [])) | set(multipart.get("required", [])) + binary = self._binary_args(operation) + arg_names = self._ordered_arg_names(name, properties, required) + response_type = _CppTypeResolver.api_type(self._response_schema(operation)) + method_config = self._api_config.get(name, {}) + return_type = method_config.get("return_type", response_type) + args = tuple( + self._build_arg( + name, + arg_name, + properties[arg_name], + arg_name in required, + arg_name in binary, + ) + for arg_name in arg_names + ) + return _MethodModel( + name=name, + return_type=return_type, + response_type=response_type, + return_description=self._return_description(return_type, response_type), + description=self._comment_lines(operation.get("description", ""), 88), + args=args, + args_name=f"{name[0].upper()}{name[1:]}Args" if args else None, ) - ) - - -def _ref_name(schema: Schema) -> str | None: - if ref := schema.get("$ref"): - return str(ref).rsplit("/", 1)[-1] - for item in schema.get("allOf", []): - if name := _ref_name(item): - return name - return None + def _ordered_arg_names( + self, + method_name: str, + properties: dict[str, Schema], + required: set[str], + ) -> list[str]: + method_config = self._api_config.get(method_name, {}) + preferred = method_config.get("args_order", ()) + args_order = {name: index for index, name in enumerate(preferred)} + declaration_required = required | { + name for name in properties if method_config.get("args", {}).get(name, {}).get("declaration_required") + } + required_names = sorted( + (name for name in properties if name in declaration_required), + key=lambda name: ( + name != "chat_id", + args_order.get(name, len(args_order)), + name, + ), + ) + optional_names = [name for name in properties if name not in declaration_required] + optional_names.sort(key=lambda name: (args_order.get(name, len(args_order)), name)) + + return required_names + optional_names + + def _build_arg( + self, + method_name: str, + name: str, + schema: Schema, + required: bool, + binary: bool, + ) -> _ArgModel: + arg_config = self._api_config.get(method_name, {}).get("args", {}).get(name, {}) + override = arg_config.get("type") + if override: + cpp_type = override + elif name in {"chat_id", "from_chat_id"}: + cpp_type = "std::variant" + elif name == "certificate" and binary: + cpp_type = "std::shared_ptr" + elif binary: + cpp_type = "std::variant, std::string>" + else: + cpp_type = _CppTypeResolver.telegram_integer(name, _CppTypeResolver.api_type(schema)) + return _ArgModel( + wire_name=name, + cpp_name=self._cpp_name(name), + cpp_type=cpp_type, + declaration_type=self._arg_declaration_type(cpp_type), + required=required, + always_send=bool(arg_config.get("always_send")), + default_value=( + None + if required or arg_config.get("declaration_required") + else self._arg_default(cpp_type, method_name, name) + ), + wire_default_value=( + None if arg_config.get("always_send") else self._configured_arg_default(method_name, name) + ), + description=self._comment_lines(schema.get("description", ""), 72), + ) + def _arg_default(self, cpp_type: str, method_name: str, arg_name: str) -> str: + if (default := self._configured_arg_default(method_name, arg_name)) is not None: + return default + if cpp_type == "bool": + return "false" + if cpp_type in {"std::int32_t", "std::int64_t", "double"}: + return "0" + if cpp_type == "std::string": + return '""' + if cpp_type.startswith("std::shared_ptr<"): + return "nullptr" + if cpp_type == "nlohmann::json": + return "nullptr" + + return "{ }" + + def _configured_arg_default(self, method_name: str, arg_name: str) -> str | None: + arg_config = self._api_config.get(method_name, {}).get("args", {}).get(arg_name, {}) + default = arg_config.get("default") + if default is None: + return None + if isinstance(default, bool): + return str(default).lower() + + return str(default) + + @staticmethod + def _return_description(return_type: str, response_type: str) -> str: + if return_type == "bool": + return "True on success." + if return_type == "std::int32_t": + return "The resulting integer." + if return_type == "std::string": + return "The resulting string." + if match := re.fullmatch(r"std::shared_ptr<([A-Za-z0-9]+)>", return_type): + type_name = match.group(1) + if return_type != response_type: + return f"The resulting {type_name} object, or nullptr if Telegram returns True." + return f"The resulting {type_name} object." + if match := re.fullmatch(r"std::vector>", return_type): + return f"The resulting list of {match.group(1)} objects." + + raise ValueError(f"Unsupported API return type: {return_type}") + + @staticmethod + def _arg_declaration_type(cpp_type: str) -> str: + if cpp_type == "std::string" or cpp_type.startswith("std::vector<"): + return f"const {cpp_type}&" + if cpp_type == "nlohmann::json": + return "const nlohmann::json&" + + return cpp_type + + @staticmethod + def _request_schema(operation: Schema) -> Schema: + return ( + operation.get("requestBody", {}) + .get("content", {}) + .get("application/json", {"schema": {"type": "object", "properties": {}}})["schema"] + ) -def _comment_lines(text: str, width: int) -> tuple[str, ...]: - normalized = " ".join(text.replace("*/", "* /").split()) - if not normalized: - return () + @staticmethod + def _multipart_schema(operation: Schema) -> Schema: + return operation.get("requestBody", {}).get("content", {}).get("multipart/form-data", {"schema": {}})["schema"] - return tuple(textwrap.wrap(normalized, width=width, break_long_words=False)) + @staticmethod + def _binary_args(operation: Schema) -> set[str]: + multipart = operation.get("requestBody", {}).get("content", {}).get("multipart/form-data", {}) + return { + name + for name, schema in multipart.get("schema", {}).get("properties", {}).items() + if schema.get("format") == "binary" + } -def _snake_to_camel(value: str) -> str: - first, *rest = value.split("_") + @staticmethod + def _response_schema(operation: Schema) -> Schema: + response = operation["responses"]["200"]["content"]["application/json"]["schema"] + for part in response.get("allOf", []): + if result := part.get("properties", {}).get("result"): + return result - return first + "".join(part[:1].upper() + part[1:] for part in rest) + raise ValueError(f"Response type is missing for {operation['operationId']}") diff --git a/api_codegen/templates/api_methods.cpp.j2 b/api_codegen/templates/api_methods.cpp.j2 index 963666e1..b12599a0 100644 --- a/api_codegen/templates/api_methods.cpp.j2 +++ b/api_codegen/templates/api_methods.cpp.j2 @@ -4,24 +4,58 @@ #include "tgbot/ApiCodec.h" #include "tgbot/Types.h" +{% macro decoder(method) -%} +{{ "decodeObjectOrTrue" if method.return_type != method.response_type else "decode<" + method.return_type + ">" }} +{%- endmacro %} + +{% macro request_field(arg) -%} +{% set factory = "required" if arg.required or arg.always_send else "optional" -%} +{% set wire_default = ", " + arg.wire_default_value if arg.wire_default_value is not none else "" -%} +ApiRequest::{{ factory }}("{{ arg.wire_name }}", {{ arg.cpp_name }}{{ wire_default }}) +{%- endmacro %} + +{% macro method_definition(method, argument_object=false) -%} +{{ method.return_type }} Api::{{ method.name }}( +{% if argument_object %} + const {{ method.args_name }}& args +{% else %} +{% for arg in method.args %} + {{ arg.declaration_type }} {{ arg.cpp_name }}{{ "," if not loop.last else "" }} +{% endfor %} +{% endif %} +) const +{%- endmacro %} + namespace TgBot { {% for method in methods %} -{% if method.parameters %} -{{ method.return_type }} Api::{{ method.name }}({{ method.parameters[0].declaration_type }} {{ method.parameters[0].cpp_name }}{{ "," if method.parameters | length > 1 else "" }} -{% for parameter in method.parameters[1:] %} - {{ parameter.declaration_type }} {{ parameter.cpp_name }}{{ "," if not loop.last else "" }} -{% endfor %}) const { + +{{ method_definition(method) }} { + return ApiResponse::{{ decoder(method) }}( + sendRequest( + "{{ method.name }}", +{% if method.args %} + ApiRequest::makeFields( +{% for arg in method.args %} + {{ request_field(arg) }}{{ "," if not loop.last else "" }} +{% endfor %} + ) {% else %} -{{ method.return_type }} Api::{{ method.name }}() const { + ApiRequest::makeFields() {% endif %} - return ApiResponse::{{ "decodeObjectOrTrue" if method.return_type != method.response_type else "decode<" + method.return_type + ">" }}(sendRequest( - "{{ method.name }}", - ApiRequest::makeFields( -{% for parameter in method.parameters %} - ApiRequest::{{ "required" if parameter.required or parameter.always_send else "optional" }}("{{ parameter.wire_name }}", {{ parameter.cpp_name }}{% if parameter.wire_default_value is not none %}, {{ parameter.wire_default_value }}{% endif %}){{ "," if not loop.last else "" }} -{% endfor %}))); + ) + ); +} + +{% if method.args_name %} +{{ method_definition(method, argument_object=true) }} { + return {{ method.name }}( +{% for arg in method.args %} + args.{{ arg.cpp_name }}{{ "," if not loop.last else "" }} +{% endfor %} + ); } +{% endif %} {% endfor %} diff --git a/api_codegen/templates/api_methods.inc.h.j2 b/api_codegen/templates/api_methods.inc.h.j2 index 8d858c24..0a22ed3c 100644 --- a/api_codegen/templates/api_methods.inc.h.j2 +++ b/api_codegen/templates/api_methods.inc.h.j2 @@ -1,28 +1,52 @@ // Generated by `make api-generate`. Do not edit. -{% for method in methods %} +{% macro arg_declaration(arg) -%} +{% set default = " = " + arg.default_value if arg.default_value is not none else "" -%} +{{ arg.declaration_type }} {{ arg.cpp_name }}{{ default }} +{%- endmacro %} + +{% macro documentation(method, argument_object=false) -%} /** * @brief{{ " " + method.description[0] if method.description else "" }} {% for line in method.description[1:] %} * {{ line }} {% endfor %} * -{% for parameter in method.parameters %} - * @param {{ parameter.cpp_name }}{{ " " + parameter.description[0] if parameter.description else "" }} -{% for line in parameter.description[1:] %} +{% if argument_object %} + * @param args Method arguments. +{% else %} +{% for arg in method.args %} + * @param {{ arg.cpp_name }}{{ " " + arg.description[0] if arg.description else "" }} +{% for line in arg.description[1:] %} * {{ line }} {% endfor %} {% endfor %} +{% endif %} * - * @return Telegram Bot API result. + * @return {{ method.return_description }} */ -{% if method.parameters %} - {{ method.return_type }} {{ method.name }}({{ method.parameters[0].declaration_type }} {{ method.parameters[0].cpp_name }}{% if method.parameters[0].default_value is not none %} = {{ method.parameters[0].default_value }}{% endif %}{{ "," if method.parameters | length > 1 else "" }} -{% for parameter in method.parameters[1:] %} - {{ parameter.declaration_type }} {{ parameter.cpp_name }}{% if parameter.default_value is not none %} = {{ parameter.default_value }}{% endif %}{{ "," if not loop.last else "" }} -{% endfor %}) const; +{%- endmacro %} + +{% macro method_declaration(method, argument_object=false) -%} + {{ method.return_type }} {{ method.name }}( +{% if argument_object %} + const {{ method.args_name }}& args {% else %} - {{ method.return_type }} {{ method.name }}() const; +{% for arg in method.args %} + {{ arg_declaration(arg) }}{{ "," if not loop.last else "" }} +{% endfor %} +{% endif %} +) const; +{%- endmacro %} + +{% for method in methods %} + +{{ documentation(method) }} +{{ method_declaration(method) }} + +{% if method.args_name %} +{{ documentation(method, argument_object=true) }} +{{ method_declaration(method, argument_object=true) }} {% endif %} {% endfor %} diff --git a/api_codegen/templates/types.cpp.j2 b/api_codegen/templates/types.cpp.j2 index b9a7a962..4c1f7e32 100644 --- a/api_codegen/templates/types.cpp.j2 +++ b/api_codegen/templates/types.cpp.j2 @@ -7,57 +7,57 @@ namespace TgBot { -{% for object in objects %} -{% for constant in object.constants %} -const std::string {{ object.name }}::{{ constant.name }} = "{{ constant.value }}"; +{% for type in types %} + +{% for constant in type.constants %} +const std::string {{ type.name }}::{{ constant.name }} = "{{ constant.value }}"; {% endfor %} -{% if object.constants %} -{% endif %} -{% for enum in object.enums %} -void from_json(const nlohmann::json& json, {{ object.name }}::{{ enum.name }}& value) { +{% for enum in type.enums %} +void from_json(const nlohmann::json& json, {{ type.name }}::{{ enum.name }}& value) { const auto text = json.get(); {% for enum_value in enum.values %} if (text == "{{ enum_value.value }}") { - value = {{ object.name }}::{{ enum.name }}::{{ enum_value.name }}; + value = {{ type.name }}::{{ enum.name }}::{{ enum_value.name }}; return; } {% endfor %} - throw std::invalid_argument("Unknown {{ object.name }}.{{ enum.name }} value: " + text); + throw std::invalid_argument("Unknown {{ type.name }}.{{ enum.name }} value: " + text); } -void to_json(nlohmann::json& json, const {{ object.name }}::{{ enum.name }}& value) { +void to_json(nlohmann::json& json, const {{ type.name }}::{{ enum.name }}& value) { switch (value) { {% for enum_value in enum.values %} - case {{ object.name }}::{{ enum.name }}::{{ enum_value.name }}: + case {{ type.name }}::{{ enum.name }}::{{ enum_value.name }}: json = "{{ enum_value.value }}"; return; {% endfor %} } - throw std::invalid_argument("Unknown {{ object.name }}.{{ enum.name }} value"); + throw std::invalid_argument("Unknown {{ type.name }}.{{ enum.name }} value"); } - {% endfor %} -void from_json(const nlohmann::json& json, {{ object.name }}& value) { -{% if object.union_members %} + +void from_json(const nlohmann::json& json, {{ type.name }}& value) { +{% if type.union_members %} Json::decode(json, value.value); {% else %} -{% for field in object.fields %} +{% for field in type.fields %} Json::{{ "readRequiredField" if field.required else "readOptionalField" }}(json, "{{ field.wire_name }}", value.{{ field.cpp_name }}); {% endfor %} {% endif %} } -void to_json(nlohmann::json& json, const {{ object.name }}& value) { -{% if object.union_members %} +void to_json(nlohmann::json& json, const {{ type.name }}& value) { +{% if type.union_members %} json = Json::encode(value.value); {% else %} json = nlohmann::json::object(); -{% for field in object.fields %} +{% for field in type.fields %} Json::{{ "writeRequiredField" if field.required else "writeOptionalField" }}(json, "{{ field.wire_name }}", value.{{ field.cpp_name }}); {% endfor %} {% endif %} } {% endfor %} + } // namespace TgBot diff --git a/api_codegen/templates/types.h.j2 b/api_codegen/templates/types.h.j2 index ceaa2818..c9029863 100644 --- a/api_codegen/templates/types.h.j2 +++ b/api_codegen/templates/types.h.j2 @@ -15,44 +15,45 @@ namespace TgBot { -{% for object in objects %} -struct {{ object.name }}; +struct InputFile; + +{% for type in types %} +struct {{ type.name }}; {% endfor %} -{% for object in objects %} +{% for type in types %} + /** - * @brief{{ " " + object.description[0] if object.description else "" }} -{% for line in object.description[1:] %} + * @brief{{ " " + type.description[0] if type.description else "" }} +{% for line in type.description[1:] %} * {{ line }} {% endfor %} * @ingroup api */ -struct {{ object.name }} { - using Ptr = std::shared_ptr<{{ object.name }}>; +struct {{ type.name }} { + using Ptr = std::shared_ptr<{{ type.name }}>; -{% for constant in object.constants %} +{% for constant in type.constants %} static TGBOT_API const std::string {{ constant.name }}; {% endfor %} -{% if object.constants %} -{% endif %} -{% for enum in object.enums %} +{% for enum in type.enums %} enum class {{ enum.name }} { {% for value in enum.values %} {{ value.name }}{{ "," if not loop.last else "" }} {% endfor %} }; - {% endfor %} -{% if object.union_members %} + +{% if type.union_members %} std::variant< -{% for member in object.union_members %} +{% for member in type.union_members %} std::shared_ptr<{{ member }}>{{ "," if not loop.last else "" }} {% endfor %} > value; {% else %} -{% for field in object.fields %} +{% for field in type.fields %} /** * @brief{{ " " + field.description[0] if field.description else "" }} {% for line in field.description[1:] %} @@ -60,20 +61,39 @@ struct {{ object.name }} { {% endfor %} */ {{ field.cpp_type }} {{ field.cpp_name }} { {{ field.constant.name if field.constant else "" }} }; - {% endfor %} {% endif %} }; -{% for enum in object.enums %} -TGBOT_API void from_json(const nlohmann::json& json, {{ object.name }}::{{ enum.name }}& value); -TGBOT_API void to_json(nlohmann::json& json, const {{ object.name }}::{{ enum.name }}& value); +{% for enum in type.enums %} +TGBOT_API void from_json(const nlohmann::json& json, {{ type.name }}::{{ enum.name }}& value); +TGBOT_API void to_json(nlohmann::json& json, const {{ type.name }}::{{ enum.name }}& value); {% endfor %} -{% if object.enums %} -{% endif %} -TGBOT_API void from_json(const nlohmann::json& json, {{ object.name }}& value); -TGBOT_API void to_json(nlohmann::json& json, const {{ object.name }}& value); +TGBOT_API void from_json(const nlohmann::json& json, {{ type.name }}& value); +TGBOT_API void to_json(nlohmann::json& json, const {{ type.name }}& value); {% endfor %} + +{% for method in methods if method.args_name %} + +/** + * @brief Arguments for Api::{{ method.name }}. + * @ingroup api + */ +struct {{ method.args_name }} { +{% for arg in method.args %} + /** + * @brief{{ " " + arg.description[0] if arg.description else "" }} +{% for line in arg.description[1:] %} + * {{ line }} +{% endfor %} + */ + {{ arg.cpp_type }} {{ arg.cpp_name }}{% if arg.default_value is none %} { }{% else %} = {{ arg.default_value }}{% endif %}; + +{% endfor %} +}; + +{% endfor %} + } // namespace TgBot diff --git a/api_codegen/tests/test_generate.py b/api_codegen/tests/test_generate.py index d091277d..3a405767 100644 --- a/api_codegen/tests/test_generate.py +++ b/api_codegen/tests/test_generate.py @@ -1,3 +1,4 @@ +import re from pathlib import Path import pytest @@ -6,24 +7,21 @@ from api_codegen.generate import ( API_CONFIG, TYPE_CONFIG, - _build_field, - _build_parameter, - _cpp_type, - _field_constant, - _object_standard_headers, - _ordered_parameter_names, - _parameter_default, - _snake_to_camel, - generate_openapi, + _BaseModelBuilder, + _CppTypeResolver, + _MethodModelBuilder, + _OpenApiGenerator, + _TypeModelBuilder, ) def test_snake_to_camel_converts_telegram_names() -> None: - assert _snake_to_camel("id") == "id" - assert _snake_to_camel("file_unique_id") == "fileUniqueId" + assert _BaseModelBuilder._cpp_name("id") == "id" + assert _BaseModelBuilder._cpp_name("file_unique_id") == "fileUniqueId" -def test_direct_api_keeps_legacy_parameter_order_and_defaults() -> None: +def test_direct_api_keeps_legacy_args_order_and_defaults() -> None: + builder = _MethodModelBuilder({}) properties = { "audio": {}, "business_connection_id": {}, @@ -32,71 +30,73 @@ def test_direct_api_keeps_legacy_parameter_order_and_defaults() -> None: "duration": {}, } - assert _ordered_parameter_names("sendAudio", properties, {"audio", "chat_id"}) == [ + assert builder._ordered_arg_names("sendAudio", properties, {"audio", "chat_id"}) == [ "chat_id", "audio", "caption", "duration", "business_connection_id", ] - assert _parameter_default("std::int32_t", "setWebhook", "max_connections") == "40" - assert _parameter_default("std::shared_ptr", "setWebhook", "certificate") == "nullptr" + assert builder._arg_default("std::int32_t", "setWebhook", "max_connections") == "40" + assert builder._arg_default("std::shared_ptr", "setWebhook", "certificate") == "nullptr" def test_compatibility_config_is_grouped_by_telegram_entity() -> None: - assert API_CONFIG["setStickerSetTitle"]["parameter_order"] == ["name", "title"] + assert API_CONFIG["setStickerSetTitle"]["args_order"] == ["name", "title"] assert API_CONFIG["editMessageText"]["return_type"] == "std::shared_ptr" - assert API_CONFIG["getUpdates"]["parameters"]["limit"]["default"] == 100 + assert API_CONFIG["getUpdates"]["args"]["limit"]["default"] == 100 assert TYPE_CONFIG["BotCommandScopeChatMember"]["fields"]["user_id"]["type"] == "std::int64_t" assert TYPE_CONFIG["Chat"]["fields"]["type"]["enum"]["Private"] == "private" def test_integer_widths_follow_schema_and_telegram_id_rules() -> None: - assert _cpp_type({"type": "integer", "format": "int64"}) == "std::int64_t" - assert _cpp_type({"type": "integer", "format": "int32"}) == "std::int32_t" - assert _cpp_type({"type": "integer"}) == "std::int32_t" + method_builder = _MethodModelBuilder({}) + type_builder = _TypeModelBuilder({}) + assert _CppTypeResolver.type({"type": "integer", "format": "int64"}) == "std::int64_t" + assert _CppTypeResolver.type({"type": "integer", "format": "int32"}) == "std::int32_t" + assert _CppTypeResolver.type({"type": "integer"}) == "std::int32_t" - user_id = _build_parameter( + user_id = method_builder._build_arg( "giftPremiumSubscription", "receiver_user_id", {"type": "integer", "format": "int32"}, True, False, ) - limit = _build_parameter( + limit = method_builder._build_arg( "getUpdates", "limit", {"type": "integer", "format": "int32"}, False, False, ) - chat_id = _build_parameter( + chat_id = method_builder._build_arg( "sendMessage", "chat_id", {"type": "integer", "format": "int64"}, True, False, ) - direct_messages_topic_id = _build_parameter( + direct_messages_topic_id = method_builder._build_arg( "sendMessage", "direct_messages_topic_id", {"type": "integer", "format": "int32"}, False, False, ) - configured_user_id = _build_field( + configured_user_id = type_builder._build_field( "BotCommandScopeChatMember", "user_id", {"type": "integer", "format": "int32"}, True, ) - shared_user_id = _build_field( + shared_user_id = type_builder._build_field( "SharedUser", "user_id", {"type": "integer", "format": "int32"}, True, ) - message_id = _build_field( + message_id = type_builder._build_field( "Message", "message_id", {"type": "integer", "format": "int32"}, @@ -112,7 +112,8 @@ def test_integer_widths_follow_schema_and_telegram_id_rules() -> None: assert message_id.cpp_type == "std::int32_t" -def test_high_risk_methods_keep_legacy_parameter_order() -> None: +def test_high_risk_methods_keep_legacy_args_order() -> None: + builder = _MethodModelBuilder({}) properties = { "chat_id": {}, "user_id": {}, @@ -124,7 +125,7 @@ def test_high_risk_methods_keep_legacy_parameter_order() -> None: "can_manage_tags": {}, } - assert _ordered_parameter_names("promoteChatMember", properties, {"chat_id", "user_id"}) == [ + assert builder._ordered_arg_names("promoteChatMember", properties, {"chat_id", "user_id"}) == [ "chat_id", "user_id", "can_change_info", @@ -137,7 +138,7 @@ def test_high_risk_methods_keep_legacy_parameter_order() -> None: def test_field_constant_recognizes_only_fixed_discriminators() -> None: - constant = _field_constant( + constant = _TypeModelBuilder._field_constant( "status", { "type": "string", @@ -150,7 +151,7 @@ def test_field_constant_recognizes_only_fixed_discriminators() -> None: assert constant.name == "STATUS" assert constant.value == "creator" assert ( - _field_constant( + _TypeModelBuilder._field_constant( "type", { "type": "string", @@ -163,10 +164,10 @@ def test_field_constant_recognizes_only_fixed_discriminators() -> None: def test_union_header_includes_variant() -> None: - assert "variant" in _object_standard_headers((), ("Message",)) + assert "variant" in _TypeModelBuilder._standard_headers((), ("Message",)) -def test_generate_openapi_renders_types_methods_and_documentation( +def test_generator_renders_types_methods_and_documentation( tmp_path: Path, ) -> None: schema_path = tmp_path / "schema.yaml" @@ -175,13 +176,14 @@ def test_generate_openapi_renders_types_methods_and_documentation( source_dir.mkdir() source_dir.joinpath("Api.cpp").write_text("", encoding="utf-8") - generated = generate_openapi(schema_path, tmp_path) + generated = _OpenApiGenerator(schema_path, tmp_path).generate() - types = tmp_path.joinpath("include/tgbot/Types.h").read_text() - types_source = tmp_path.joinpath("src/Types.cpp").read_text() - api_source = tmp_path.joinpath("src/ApiMethods.cpp").read_text() - methods = tmp_path.joinpath("include/tgbot/ApiMethods.inc.h").read_text() - assert generated.objects == 2 + types = tmp_path.joinpath("include/tgbot/Types.h").read_text(encoding="utf-8") + types_source = tmp_path.joinpath("src/Types.cpp").read_text(encoding="utf-8") + api_source = tmp_path.joinpath("src/ApiMethods.cpp").read_text(encoding="utf-8") + methods = tmp_path.joinpath("include/tgbot/ApiMethods.inc.h").read_text(encoding="utf-8") + normalized_methods = " ".join(methods.split()) + assert generated.types == 2 assert generated.methods == 2 assert types.startswith("// Generated by `make api-generate`. Do not edit.\n\n#pragma once") assert "struct User;" in types @@ -196,36 +198,48 @@ def test_generate_openapi_renders_types_methods_and_documentation( assert "TGBOT_API void from_json" in types assert "TGBOT_API void to_json" in types assert "std::string type { TYPE };" in types - assert "std::string id { };\n\n /**" in types + assert "std::string id" in types assert 'const std::string InlineQueryResultCachedAudio::TYPE = "audio";' in types_source assert '#include "tgbot/Json.h"' in types_source assert '#include "tgbot/Types.h"' in types_source assert 'Json::readRequiredField(json, "id", value.id);' in types_source assert not tmp_path.joinpath("include/tgbot/types").exists() assert not tmp_path.joinpath("src/types").exists() - assert "\n /**\n * @brief Returns information about the bot.\n" in methods - assert "\n std::shared_ptr getMe() const" in methods + assert "@brief Returns information about the bot." in normalized_methods + assert "std::shared_ptr getMe( ) const;" in normalized_methods assert "Returns information about the bot." in methods assert "@param url HTTPS URL for incoming updates." in methods assert '#include "tgbot/ApiCodec.h"' in api_source assert "ApiRequest::makeFields(" in api_source assert "ApiResponse::decode>" in api_source - assert "HttpReqArg" not in api_source assert "std::shared_ptr certificate = nullptr" in methods assert "std::int32_t maxConnections = 40" in methods assert 'ApiRequest::required("url", url)' in api_source assert 'ApiRequest::optional("certificate", certificate)' in api_source assert 'ApiRequest::optional("allowed_updates", allowedUpdates)' in api_source - - generated_again = generate_openapi(schema_path, tmp_path) + assert "struct SetWebhookArgs" in types + assert "std::string url { };" in types + assert "std::int32_t maxConnections = 40;" in types + assert "std::shared_ptr certificate = nullptr;" in types + assert "setWebhook( const SetWebhookArgs& args ) const;" in normalized_methods + assert methods.count("@brief Specify a URL and receive incoming updates.") == 2 + assert "@return True on success." in methods + assert "@return The resulting User object." in methods + assert "return setWebhook(" in api_source + assert "args.url" in api_source + assert "args.certificate" in api_source + assert "args.maxConnections" in api_source + assert "args.allowedUpdates" in api_source + + generated_again = _OpenApiGenerator(schema_path, tmp_path).generate() assert generated_again == generated - assert tmp_path.joinpath("include/tgbot/Types.h").read_text() == types - assert tmp_path.joinpath("src/Types.cpp").read_text() == types_source - assert tmp_path.joinpath("src/ApiMethods.cpp").read_text() == api_source + assert tmp_path.joinpath("include/tgbot/Types.h").read_text(encoding="utf-8") == types + assert tmp_path.joinpath("src/Types.cpp").read_text(encoding="utf-8") == types_source + assert tmp_path.joinpath("src/ApiMethods.cpp").read_text(encoding="utf-8") == api_source -def test_generate_openapi_rejects_method_without_result_schema(tmp_path: Path) -> None: +def test_generator_rejects_method_without_result_schema(tmp_path: Path) -> None: schema = _schema() response_parts = schema["paths"]["/getMe"]["post"]["responses"]["200"]["content"]["application/json"]["schema"][ "allOf" @@ -235,7 +249,51 @@ def test_generate_openapi_rejects_method_without_result_schema(tmp_path: Path) - schema_path.write_text(yaml.safe_dump(schema), encoding="utf-8") with pytest.raises(ValueError, match="Response type is missing for getMe"): - generate_openapi(schema_path, tmp_path) + _OpenApiGenerator(schema_path, tmp_path).generate() + + +def test_every_method_with_args_generates_ordered_argument_object_delegation(tmp_path: Path) -> None: + schema_path = Path(__file__).parents[2] / "api" / "telegram-bot-api.yaml" + document = yaml.safe_load(schema_path.read_text(encoding="utf-8")) + methods = _MethodModelBuilder(document["paths"]).build() + + _OpenApiGenerator(schema_path, tmp_path).generate() + + types = tmp_path.joinpath("include/tgbot/Types.h").read_text(encoding="utf-8") + declarations = tmp_path.joinpath("include/tgbot/ApiMethods.inc.h").read_text(encoding="utf-8") + normalized_declarations = " ".join(declarations.split()) + definitions = tmp_path.joinpath("src/ApiMethods.cpp").read_text(encoding="utf-8") + + for method in methods: + if not method.args: + assert method.args_name is None + continue + + expected_args_name = f"{method.name[0].upper()}{method.name[1:]}Args" + assert method.args_name == expected_args_name + assert f"struct {expected_args_name} {{" in types + assert f"{method.name}( const {expected_args_name}& args ) const;" in normalized_declarations + + classic_start = definitions.index(f"Api::{method.name}(") + classic_end = definitions.index("\n}", classic_start) + classic_body = definitions[classic_start:classic_end] + normalized_classic_body = " ".join(classic_body.split()) + assert f'sendRequest( "{method.name}", ApiRequest::makeFields(' in normalized_classic_body + for arg in method.args: + field_factory = "required" if arg.required or arg.always_send else "optional" + assert f'ApiRequest::{field_factory}("{arg.wire_name}", {arg.cpp_name}' in classic_body + + args_signature = re.search( + rf"Api::{method.name}\(\s*const {expected_args_name}& args\s*\) const \{{", + definitions, + ) + assert args_signature is not None + args_start = args_signature.start() + args_end = definitions.index("\n}", args_start) + args_body = definitions[args_start:args_end] + assert f"return {method.name}(" in args_body + positions = [args_body.index(f"args.{arg.cpp_name}") for arg in method.args] + assert positions == sorted(positions) def _schema() -> dict: diff --git a/examples/echobot-proxy/Makefile b/examples/echobot-proxy/Makefile index 8a31323c..4111890e 100644 --- a/examples/echobot-proxy/Makefile +++ b/examples/echobot-proxy/Makefile @@ -2,6 +2,8 @@ BUILD_TYPE ?= Release BUILD_DIR ?= build/$(BUILD_TYPE) TOOLCHAIN_FILE ?= INSTALL_PREFIX ?= +CMAKE_LOG_LEVEL ?= STATUS +CMAKE_BUILD_ARGS ?= NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 1) .PHONY: all configure build install @@ -9,14 +11,14 @@ NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _ all: build configure: - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ $(if $(TOOLCHAIN_FILE),-DCMAKE_TOOLCHAIN_FILE=$(TOOLCHAIN_FILE),) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ -DENABLE_TESTS=OFF \ $(if $(INSTALL_PREFIX),-DCMAKE_PREFIX_PATH=$(INSTALL_PREFIX),) build: configure - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) install: build cmake --install $(BUILD_DIR) $(if $(INSTALL_PREFIX),--prefix $(INSTALL_PREFIX),) diff --git a/examples/echobot-setmycommands/Makefile b/examples/echobot-setmycommands/Makefile index 8a31323c..4111890e 100644 --- a/examples/echobot-setmycommands/Makefile +++ b/examples/echobot-setmycommands/Makefile @@ -2,6 +2,8 @@ BUILD_TYPE ?= Release BUILD_DIR ?= build/$(BUILD_TYPE) TOOLCHAIN_FILE ?= INSTALL_PREFIX ?= +CMAKE_LOG_LEVEL ?= STATUS +CMAKE_BUILD_ARGS ?= NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 1) .PHONY: all configure build install @@ -9,14 +11,14 @@ NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _ all: build configure: - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ $(if $(TOOLCHAIN_FILE),-DCMAKE_TOOLCHAIN_FILE=$(TOOLCHAIN_FILE),) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ -DENABLE_TESTS=OFF \ $(if $(INSTALL_PREFIX),-DCMAKE_PREFIX_PATH=$(INSTALL_PREFIX),) build: configure - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) install: build cmake --install $(BUILD_DIR) $(if $(INSTALL_PREFIX),--prefix $(INSTALL_PREFIX),) diff --git a/examples/echobot-submodule/Makefile b/examples/echobot-submodule/Makefile index 9ab06239..ec9e10d6 100644 --- a/examples/echobot-submodule/Makefile +++ b/examples/echobot-submodule/Makefile @@ -2,6 +2,8 @@ BUILD_TYPE ?= Release BUILD_DIR ?= build/$(BUILD_TYPE) TOOLCHAIN_FILE ?= INSTALL_PREFIX ?= +CMAKE_LOG_LEVEL ?= STATUS +CMAKE_BUILD_ARGS ?= TGBOT_CPP_SOURCE_DIR ?= ../.. NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 1) @@ -10,7 +12,7 @@ NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _ all: build configure: - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ $(if $(TOOLCHAIN_FILE),-DCMAKE_TOOLCHAIN_FILE=$(TOOLCHAIN_FILE),) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ -DENABLE_TESTS=OFF \ @@ -18,7 +20,7 @@ configure: $(if $(INSTALL_PREFIX),-DCMAKE_PREFIX_PATH=$(INSTALL_PREFIX),) build: configure - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) install: build cmake --install $(BUILD_DIR) $(if $(INSTALL_PREFIX),--prefix $(INSTALL_PREFIX),) diff --git a/examples/echobot-webhook-server/Makefile b/examples/echobot-webhook-server/Makefile index 8a31323c..4111890e 100644 --- a/examples/echobot-webhook-server/Makefile +++ b/examples/echobot-webhook-server/Makefile @@ -2,6 +2,8 @@ BUILD_TYPE ?= Release BUILD_DIR ?= build/$(BUILD_TYPE) TOOLCHAIN_FILE ?= INSTALL_PREFIX ?= +CMAKE_LOG_LEVEL ?= STATUS +CMAKE_BUILD_ARGS ?= NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 1) .PHONY: all configure build install @@ -9,14 +11,14 @@ NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _ all: build configure: - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ $(if $(TOOLCHAIN_FILE),-DCMAKE_TOOLCHAIN_FILE=$(TOOLCHAIN_FILE),) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ -DENABLE_TESTS=OFF \ $(if $(INSTALL_PREFIX),-DCMAKE_PREFIX_PATH=$(INSTALL_PREFIX),) build: configure - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) install: build cmake --install $(BUILD_DIR) $(if $(INSTALL_PREFIX),--prefix $(INSTALL_PREFIX),) diff --git a/examples/echobot/Makefile b/examples/echobot/Makefile index 8a31323c..4111890e 100644 --- a/examples/echobot/Makefile +++ b/examples/echobot/Makefile @@ -2,6 +2,8 @@ BUILD_TYPE ?= Release BUILD_DIR ?= build/$(BUILD_TYPE) TOOLCHAIN_FILE ?= INSTALL_PREFIX ?= +CMAKE_LOG_LEVEL ?= STATUS +CMAKE_BUILD_ARGS ?= NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 1) .PHONY: all configure build install @@ -9,14 +11,14 @@ NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _ all: build configure: - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ $(if $(TOOLCHAIN_FILE),-DCMAKE_TOOLCHAIN_FILE=$(TOOLCHAIN_FILE),) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ -DENABLE_TESTS=OFF \ $(if $(INSTALL_PREFIX),-DCMAKE_PREFIX_PATH=$(INSTALL_PREFIX),) build: configure - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) install: build cmake --install $(BUILD_DIR) $(if $(INSTALL_PREFIX),--prefix $(INSTALL_PREFIX),) diff --git a/examples/inline-keyboard/Makefile b/examples/inline-keyboard/Makefile index 8a31323c..4111890e 100644 --- a/examples/inline-keyboard/Makefile +++ b/examples/inline-keyboard/Makefile @@ -2,6 +2,8 @@ BUILD_TYPE ?= Release BUILD_DIR ?= build/$(BUILD_TYPE) TOOLCHAIN_FILE ?= INSTALL_PREFIX ?= +CMAKE_LOG_LEVEL ?= STATUS +CMAKE_BUILD_ARGS ?= NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 1) .PHONY: all configure build install @@ -9,14 +11,14 @@ NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _ all: build configure: - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ $(if $(TOOLCHAIN_FILE),-DCMAKE_TOOLCHAIN_FILE=$(TOOLCHAIN_FILE),) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ -DENABLE_TESTS=OFF \ $(if $(INSTALL_PREFIX),-DCMAKE_PREFIX_PATH=$(INSTALL_PREFIX),) build: configure - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) install: build cmake --install $(BUILD_DIR) $(if $(INSTALL_PREFIX),--prefix $(INSTALL_PREFIX),) diff --git a/examples/photo/Makefile b/examples/photo/Makefile index 8a31323c..4111890e 100644 --- a/examples/photo/Makefile +++ b/examples/photo/Makefile @@ -2,6 +2,8 @@ BUILD_TYPE ?= Release BUILD_DIR ?= build/$(BUILD_TYPE) TOOLCHAIN_FILE ?= INSTALL_PREFIX ?= +CMAKE_LOG_LEVEL ?= STATUS +CMAKE_BUILD_ARGS ?= NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 1) .PHONY: all configure build install @@ -9,14 +11,14 @@ NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _ all: build configure: - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ $(if $(TOOLCHAIN_FILE),-DCMAKE_TOOLCHAIN_FILE=$(TOOLCHAIN_FILE),) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ -DENABLE_TESTS=OFF \ $(if $(INSTALL_PREFIX),-DCMAKE_PREFIX_PATH=$(INSTALL_PREFIX),) build: configure - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) install: build cmake --install $(BUILD_DIR) $(if $(INSTALL_PREFIX),--prefix $(INSTALL_PREFIX),) diff --git a/examples/receive-file/Makefile b/examples/receive-file/Makefile index 8a31323c..4111890e 100644 --- a/examples/receive-file/Makefile +++ b/examples/receive-file/Makefile @@ -2,6 +2,8 @@ BUILD_TYPE ?= Release BUILD_DIR ?= build/$(BUILD_TYPE) TOOLCHAIN_FILE ?= INSTALL_PREFIX ?= +CMAKE_LOG_LEVEL ?= STATUS +CMAKE_BUILD_ARGS ?= NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 1) .PHONY: all configure build install @@ -9,14 +11,14 @@ NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _ all: build configure: - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ $(if $(TOOLCHAIN_FILE),-DCMAKE_TOOLCHAIN_FILE=$(TOOLCHAIN_FILE),) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ -DENABLE_TESTS=OFF \ $(if $(INSTALL_PREFIX),-DCMAKE_PREFIX_PATH=$(INSTALL_PREFIX),) build: configure - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) install: build cmake --install $(BUILD_DIR) $(if $(INSTALL_PREFIX),--prefix $(INSTALL_PREFIX),) diff --git a/examples/received-text-processing/Makefile b/examples/received-text-processing/Makefile index 8a31323c..4111890e 100644 --- a/examples/received-text-processing/Makefile +++ b/examples/received-text-processing/Makefile @@ -2,6 +2,8 @@ BUILD_TYPE ?= Release BUILD_DIR ?= build/$(BUILD_TYPE) TOOLCHAIN_FILE ?= INSTALL_PREFIX ?= +CMAKE_LOG_LEVEL ?= STATUS +CMAKE_BUILD_ARGS ?= NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 1) .PHONY: all configure build install @@ -9,14 +11,14 @@ NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _ all: build configure: - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ $(if $(TOOLCHAIN_FILE),-DCMAKE_TOOLCHAIN_FILE=$(TOOLCHAIN_FILE),) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ -DENABLE_TESTS=OFF \ $(if $(INSTALL_PREFIX),-DCMAKE_PREFIX_PATH=$(INSTALL_PREFIX),) build: configure - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) install: build cmake --install $(BUILD_DIR) $(if $(INSTALL_PREFIX),--prefix $(INSTALL_PREFIX),) diff --git a/examples/reply-keyboard/Makefile b/examples/reply-keyboard/Makefile index 8a31323c..4111890e 100644 --- a/examples/reply-keyboard/Makefile +++ b/examples/reply-keyboard/Makefile @@ -2,6 +2,8 @@ BUILD_TYPE ?= Release BUILD_DIR ?= build/$(BUILD_TYPE) TOOLCHAIN_FILE ?= INSTALL_PREFIX ?= +CMAKE_LOG_LEVEL ?= STATUS +CMAKE_BUILD_ARGS ?= NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 1) .PHONY: all configure build install @@ -9,14 +11,14 @@ NPROC ?= $(shell nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || getconf _ all: build configure: - cmake -S . -B $(BUILD_DIR) \ + cmake --log-level=$(CMAKE_LOG_LEVEL) -S . -B $(BUILD_DIR) \ $(if $(TOOLCHAIN_FILE),-DCMAKE_TOOLCHAIN_FILE=$(TOOLCHAIN_FILE),) \ -DCMAKE_BUILD_TYPE=$(BUILD_TYPE) \ -DENABLE_TESTS=OFF \ $(if $(INSTALL_PREFIX),-DCMAKE_PREFIX_PATH=$(INSTALL_PREFIX),) build: configure - cmake --build $(BUILD_DIR) --parallel $(NPROC) + cmake --build $(BUILD_DIR) --parallel $(NPROC) $(CMAKE_BUILD_ARGS) install: build cmake --install $(BUILD_DIR) $(if $(INSTALL_PREFIX),--prefix $(INSTALL_PREFIX),) diff --git a/include/tgbot/ApiMethods.inc.h b/include/tgbot/ApiMethods.inc.h index 0d2986bc..cf57cc29 100644 --- a/include/tgbot/ApiMethods.inc.h +++ b/include/tgbot/ApiMethods.inc.h @@ -11,10 +11,21 @@ * exactly the same sticker had already been added to the set, then the set * isn't changed. * - * @return Telegram Bot API result. + * @return True on success. */ bool addStickerToSet(std::int64_t userId, const std::string& name, std::shared_ptr sticker) const; + /** + * @brief Use this method to add a new sticker to a set created by the bot. Emoji sticker sets can + * have up to 200 stickers. Other sticker sets can have up to 120 stickers. Returns True on + * success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool addStickerToSet(const AddStickerToSetArgs& args) const; + /** * @brief Use this method to send answers to callback queries sent from inline keyboards. The * answer will be displayed to the user as a notification at the top of the chat screen or @@ -34,10 +45,24 @@ * query may be cached client-side. Telegram apps will support caching * starting in version 3.14. Defaults to 0. * - * @return Telegram Bot API result. + * @return True on success. + */ + bool answerCallbackQuery(const std::string& callbackQueryId, + const std::string& text = "", + bool showAlert = false, + const std::string& url = "", + std::int32_t cacheTime = 0) const; + + /** + * @brief Use this method to send answers to callback queries sent from inline keyboards. The + * answer will be displayed to the user as a notification at the top of the chat screen or + * as an alert. On success, True is returned. + * + * @param args Method arguments. + * + * @return True on success. */ - bool answerCallbackQuery(const std::string& callbackQueryId, const std::string& text = "", bool showAlert = false, - const std::string& url = "", std::int32_t cacheTime = 0) const; + bool answerCallbackQuery(const AnswerCallbackQueryArgs& args) const; /** * @brief Use this method to process a received chat join request query. Returns True on success. @@ -47,10 +72,19 @@ * the chat, “decline” to disallow the user to join the chat, or “queue” to * leave the decision to other administrators. * - * @return Telegram Bot API result. + * @return True on success. */ bool answerChatJoinRequestQuery(const std::string& chatJoinRequestQueryId, const std::string& result) const; + /** + * @brief Use this method to process a received chat join request query. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool answerChatJoinRequestQuery(const AnswerChatJoinRequestQueryArgs& args) const; + /** * @brief Use this method to reply to a received guest message. On success, a SentGuestMessage * object is returned. @@ -58,11 +92,21 @@ * @param guestQueryId Unique identifier for the query to be answered * @param result A JSON-serialized object describing the message to be sent * - * @return Telegram Bot API result. + * @return The resulting SentGuestMessage object. */ std::shared_ptr answerGuestQuery(const std::string& guestQueryId, std::shared_ptr result) const; + /** + * @brief Use this method to reply to a received guest message. On success, a SentGuestMessage + * object is returned. + * + * @param args Method arguments. + * + * @return The resulting SentGuestMessage object. + */ + std::shared_ptr answerGuestQuery(const AnswerGuestQueryArgs& args) const; + /** * @brief Use this method to send answers to an inline query. On success, True is returned.No more * than 50 results per query are allowed. @@ -81,13 +125,25 @@ * @param button A JSON-serialized object describing a button to be shown above inline * query results * - * @return Telegram Bot API result. + * @return True on success. */ bool answerInlineQuery(const std::string& inlineQueryId, - const std::vector>& results, std::int32_t cacheTime = 300, - bool isPersonal = false, const std::string& nextOffset = "", + const std::vector>& results, + std::int32_t cacheTime = 300, + bool isPersonal = false, + const std::string& nextOffset = "", std::shared_ptr button = nullptr) const; + /** + * @brief Use this method to send answers to an inline query. On success, True is returned.No more + * than 50 results per query are allowed. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool answerInlineQuery(const AnswerInlineQueryArgs& args) const; + /** * @brief Once the user has confirmed their payment and shipping details, the Bot API sends the * final confirmation in the form of an Update with the field pre_checkout_query. Use this @@ -105,11 +161,24 @@ * different color or garment!"). Telegram will display this message to the * user. * - * @return Telegram Bot API result. + * @return True on success. */ - bool answerPreCheckoutQuery(const std::string& preCheckoutQueryId, bool ok, + bool answerPreCheckoutQuery(const std::string& preCheckoutQueryId, + bool ok, const std::string& errorMessage = "") const; + /** + * @brief Once the user has confirmed their payment and shipping details, the Bot API sends the + * final confirmation in the form of an Update with the field pre_checkout_query. Use this + * method to respond to such pre-checkout queries. On success, True is returned. Note: The + * Bot API must receive an answer within 10 seconds after the pre-checkout query was sent. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool answerPreCheckoutQuery(const AnswerPreCheckoutQueryArgs& args) const; + /** * @brief If you sent an invoice requesting a shipping address and the parameter is_flexible was * specified, the Bot API will send an Update with a shipping_query field to the bot. Use @@ -126,12 +195,24 @@ * delivery to your desired address is unavailable”). Telegram will display * this message to the user. * - * @return Telegram Bot API result. + * @return True on success. */ - bool answerShippingQuery(const std::string& shippingQueryId, bool ok, + bool answerShippingQuery(const std::string& shippingQueryId, + bool ok, const std::vector>& shippingOptions = { }, const std::string& errorMessage = "") const; + /** + * @brief If you sent an invoice requesting a shipping address and the parameter is_flexible was + * specified, the Bot API will send an Update with a shipping_query field to the bot. Use + * this method to reply to shipping queries. On success, True is returned. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool answerShippingQuery(const AnswerShippingQueryArgs& args) const; + /** * @brief Use this method to set the result of an interaction with a Web App and send a * corresponding message on behalf of the user to the chat from which the query originated. @@ -140,11 +221,22 @@ * @param webAppQueryId Unique identifier for the query to be answered * @param result A JSON-serialized object describing the message to be sent * - * @return Telegram Bot API result. + * @return The resulting SentWebAppMessage object. */ std::shared_ptr answerWebAppQuery(const std::string& webAppQueryId, std::shared_ptr result) const; + /** + * @brief Use this method to set the result of an interaction with a Web App and send a + * corresponding message on behalf of the user to the chat from which the query originated. + * On success, a SentWebAppMessage object is returned. + * + * @param args Method arguments. + * + * @return The resulting SentWebAppMessage object. + */ + std::shared_ptr answerWebAppQuery(const AnswerWebAppQueryArgs& args) const; + /** * @brief Use this method to approve a chat join request. The bot must be an administrator in the * chat for this to work and must have the can_invite_users administrator right. Returns @@ -154,10 +246,21 @@ * in the format @username * @param userId Unique identifier of the target user * - * @return Telegram Bot API result. + * @return True on success. */ bool approveChatJoinRequest(std::variant chatId, std::int64_t userId) const; + /** + * @brief Use this method to approve a chat join request. The bot must be an administrator in the + * chat for this to work and must have the can_invite_users administrator right. Returns + * True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool approveChatJoinRequest(const ApproveChatJoinRequestArgs& args) const; + /** * @brief Use this method to approve a suggested post in a direct messages chat. The bot must have * the 'can_post_messages' administrator right in the corresponding channel chat. Returns @@ -170,11 +273,23 @@ * suggested post was created. If specified, then the date must be not more * than 2678400 seconds (30 days) in the future. * - * @return Telegram Bot API result. + * @return True on success. */ - bool approveSuggestedPost(std::variant chatId, std::int32_t messageId, + bool approveSuggestedPost(std::variant chatId, + std::int32_t messageId, std::int32_t sendDate = 0) const; + /** + * @brief Use this method to approve a suggested post in a direct messages chat. The bot must have + * the 'can_post_messages' administrator right in the corresponding channel chat. Returns + * True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool approveSuggestedPost(const ApproveSuggestedPostArgs& args) const; + /** * @brief Use this method to ban a user in a group, a supergroup or a channel. In the case of * supergroups and channels, the user will not be able to return to the chat on their own @@ -194,11 +309,26 @@ * group that were sent before the user was removed. Always True for * supergroups and channels. * - * @return Telegram Bot API result. + * @return True on success. */ - bool banChatMember(std::variant chatId, std::int64_t userId, std::int32_t untilDate = 0, + bool banChatMember(std::variant chatId, + std::int64_t userId, + std::int32_t untilDate = 0, bool revokeMessages = true) const; + /** + * @brief Use this method to ban a user in a group, a supergroup or a channel. In the case of + * supergroups and channels, the user will not be able to return to the chat on their own + * using invite links, etc., unless unbanned first. The bot must be an administrator in the + * chat for this to work and must have the appropriate administrator rights. Returns True + * on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool banChatMember(const BanChatMemberArgs& args) const; + /** * @brief Use this method to ban a channel chat in a supergroup or a channel. Until the chat is * unbanned, the owner of the banned chat won't be able to send messages on behalf of any @@ -210,10 +340,23 @@ * in the format @username * @param senderChatId Unique identifier of the target sender chat * - * @return Telegram Bot API result. + * @return True on success. */ bool banChatSenderChat(std::variant chatId, std::int64_t senderChatId) const; + /** + * @brief Use this method to ban a channel chat in a supergroup or a channel. Until the chat is + * unbanned, the owner of the banned chat won't be able to send messages on behalf of any + * of their channels. The bot must be an administrator in the supergroup or channel for + * this to work and must have the appropriate administrator rights. Returns True on + * success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool banChatSenderChat(const BanChatSenderChatArgs& args) const; + /** * @brief Use this method to close the bot instance before moving it from one local server to * another. You need to delete the webhook before calling this method to ensure that the @@ -222,7 +365,7 @@ * parameters. * * - * @return Telegram Bot API result. + * @return True on success. */ bool close() const; @@ -235,10 +378,21 @@ * supergroup in the format @username * @param messageThreadId Unique identifier for the target message thread of the forum topic * - * @return Telegram Bot API result. + * @return True on success. */ bool closeForumTopic(std::variant chatId, std::int32_t messageThreadId) const; + /** + * @brief Use this method to close an open topic in a forum supergroup chat. The bot must be an + * administrator in the chat for this to work and must have the can_manage_topics + * administrator rights, unless it is the creator of the topic. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool closeForumTopic(const CloseForumTopicArgs& args) const; + /** * @brief Use this method to close an open 'General' topic in a forum supergroup chat. The bot * must be an administrator in the chat for this to work and must have the @@ -247,10 +401,21 @@ * @param chatId Unique identifier for the target chat or username of the target * supergroup in the format @username * - * @return Telegram Bot API result. + * @return True on success. */ bool closeGeneralForumTopic(std::variant chatId) const; + /** + * @brief Use this method to close an open 'General' topic in a forum supergroup chat. The bot + * must be an administrator in the chat for this to work and must have the + * can_manage_topics administrator rights. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool closeGeneralForumTopic(const CloseGeneralForumTopicArgs& args) const; + /** * @brief Converts a given regular gift to Telegram Stars. Requires the can_convert_gifts_to_stars * business bot right. Returns True on success. @@ -259,10 +424,20 @@ * @param ownedGiftId Unique identifier of the regular gift that should be converted to * Telegram Stars * - * @return Telegram Bot API result. + * @return True on success. */ bool convertGiftToStars(const std::string& businessConnectionId, const std::string& ownedGiftId) const; + /** + * @brief Converts a given regular gift to Telegram Stars. Requires the can_convert_gifts_to_stars + * business bot right. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool convertGiftToStars(const ConvertGiftToStarsArgs& args) const; + /** * @brief Use this method to copy messages of any kind. Service messages, paid media messages, * giveaway messages, giveaway winners messages, and invoice messages can't be copied. A @@ -308,21 +483,43 @@ * automatically declined. * @param videoStartTimestamp New start timestamp for the copied video in the message * - * @return Telegram Bot API result. + * @return The resulting MessageId object. + */ + std::shared_ptr copyMessage(std::variant chatId, + std::variant fromChatId, + std::int32_t messageId, + const std::string& caption = "", + const std::string& parseMode = "", + const std::vector>& captionEntities = { }, + bool disableNotification = false, + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + bool protectContent = false, + std::int32_t messageThreadId = 0, + bool allowPaidBroadcast = false, + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + bool showCaptionAboveMedia = false, + std::shared_ptr suggestedPostParameters + = nullptr, + std::int32_t videoStartTimestamp = 0) const; + + /** + * @brief Use this method to copy messages of any kind. Service messages, paid media messages, + * giveaway messages, giveaway winners messages, and invoice messages can't be copied. A + * quiz poll can be copied only if the value of the field correct_option_ids is known to + * the bot. The method is analogous to the method forwardMessage, but the copied message + * doesn't have a link to the original message. Returns the MessageId of the sent message + * on success. + * + * @param args Method arguments. + * + * @return The resulting MessageId object. */ - std::shared_ptr - copyMessage(std::variant chatId, std::variant fromChatId, - std::int32_t messageId, const std::string& caption = "", const std::string& parseMode = "", - const std::vector>& captionEntities = { }, - bool disableNotification = false, std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - bool protectContent = false, std::int32_t messageThreadId = 0, bool allowPaidBroadcast = false, - std::int64_t directMessagesTopicId = 0, const std::string& messageEffectId = "", - bool showCaptionAboveMedia = false, - std::shared_ptr suggestedPostParameters = nullptr, - std::int32_t videoStartTimestamp = 0) const; + std::shared_ptr copyMessage(const CopyMessageArgs& args) const; /** * @brief Use this method to copy messages of any kind. If some of the specified messages can't be @@ -351,13 +548,31 @@ * @param directMessagesTopicId Identifier of the direct messages topic to which the messages will be * sent; required if the messages are sent to a direct messages chat * - * @return Telegram Bot API result. + * @return The resulting list of MessageId objects. + */ + std::vector> copyMessages(std::variant chatId, + std::variant fromChatId, + const std::vector& messageIds, + std::int32_t messageThreadId = 0, + bool disableNotification = false, + bool protectContent = false, + bool removeCaption = false, + std::int64_t directMessagesTopicId = 0) const; + + /** + * @brief Use this method to copy messages of any kind. If some of the specified messages can't be + * found or copied, they are skipped. Service messages, paid media messages, giveaway + * messages, giveaway winners messages, and invoice messages can't be copied. A quiz poll + * can be copied only if the value of the field correct_option_ids is known to the bot. The + * method is analogous to the method forwardMessages, but the copied messages don't have a + * link to the original message. Album grouping is kept for copied messages. On success, an + * Array of MessageId of the sent messages is returned. + * + * @param args Method arguments. + * + * @return The resulting list of MessageId objects. */ - std::vector> - copyMessages(std::variant chatId, std::variant fromChatId, - const std::vector& messageIds, std::int32_t messageThreadId = 0, - bool disableNotification = false, bool protectContent = false, bool removeCaption = false, - std::int64_t directMessagesTopicId = 0) const; + std::vector> copyMessages(const CopyMessagesArgs& args) const; /** * @brief Use this method to create an additional invite link for a chat. The bot must be an @@ -374,13 +589,26 @@ * @param createsJoinRequest True, if users joining the chat via the link need to be approved by chat * administrators. If True, member_limit can't be specified. * - * @return Telegram Bot API result. + * @return The resulting ChatInviteLink object. */ std::shared_ptr createChatInviteLink(std::variant chatId, - std::int32_t expireDate = 0, std::int32_t memberLimit = 0, + std::int32_t expireDate = 0, + std::int32_t memberLimit = 0, const std::string& name = "", bool createsJoinRequest = false) const; + /** + * @brief Use this method to create an additional invite link for a chat. The bot must be an + * administrator in the chat for this to work and must have the appropriate administrator + * rights. The link can be revoked using the method revokeChatInviteLink. Returns the new + * invite link as ChatInviteLink object. + * + * @param args Method arguments. + * + * @return The resulting ChatInviteLink object. + */ + std::shared_ptr createChatInviteLink(const CreateChatInviteLinkArgs& args) const; + /** * @brief Use this method to create a subscription invite link for a channel chat. The bot must * have the can_invite_users administrator rights. The link can be edited using the method @@ -395,13 +623,26 @@ * subsequent subscription period to be a member of the chat; 1-10000 * @param name Invite link name; 0-32 characters * - * @return Telegram Bot API result. + * @return The resulting ChatInviteLink object. */ std::shared_ptr createChatSubscriptionInviteLink(std::variant chatId, std::int32_t subscriptionPeriod, std::int32_t subscriptionPrice, const std::string& name = "") const; + /** + * @brief Use this method to create a subscription invite link for a channel chat. The bot must + * have the can_invite_users administrator rights. The link can be edited using the method + * editChatSubscriptionInviteLink or revoked using the method revokeChatInviteLink. Returns + * the new invite link as a ChatInviteLink object. + * + * @param args Method arguments. + * + * @return The resulting ChatInviteLink object. + */ + std::shared_ptr + createChatSubscriptionInviteLink(const CreateChatSubscriptionInviteLinkArgs& args) const; + /** * @brief Use this method to create a topic in a forum supergroup chat or a private chat with a * user. In the case of a supergroup chat the bot must be an administrator in the chat for @@ -417,12 +658,25 @@ * @param iconCustomEmojiId Unique identifier of the custom emoji shown as the topic icon. Use * getForumTopicIconStickers to get all allowed custom emoji identifiers. * - * @return Telegram Bot API result. + * @return The resulting ForumTopic object. */ std::shared_ptr createForumTopic(std::variant chatId, - const std::string& name, std::int32_t iconColor = 0, + const std::string& name, + std::int32_t iconColor = 0, const std::string& iconCustomEmojiId = "") const; + /** + * @brief Use this method to create a topic in a forum supergroup chat or a private chat with a + * user. In the case of a supergroup chat the bot must be an administrator in the chat for + * this to work and must have the can_manage_topics administrator right. Returns + * information about the created topic as a ForumTopic object. + * + * @param args Method arguments. + * + * @return The resulting ForumTopic object. + */ + std::shared_ptr createForumTopic(const CreateForumTopicArgs& args) const; + /** * @brief Use this method to create a link for an invoice. Returns the created invoice link as * String on success. @@ -480,18 +734,40 @@ * the same time, including multiple concurrent subscriptions from the same * user. Subscription price must no exceed 10000 Telegram Stars. * - * @return Telegram Bot API result. + * @return The resulting string. + */ + std::string createInvoiceLink(const std::string& title, + const std::string& description, + const std::string& payload, + const std::string& providerToken, + const std::string& currency, + const std::vector>& prices, + std::int32_t maxTipAmount = 0, + const std::vector& suggestedTipAmounts = { }, + const std::string& providerData = "", + const std::string& photoUrl = "", + std::int32_t photoSize = 0, + std::int32_t photoWidth = 0, + std::int32_t photoHeight = 0, + bool needName = false, + bool needPhoneNumber = false, + bool needEmail = false, + bool needShippingAddress = false, + bool sendPhoneNumberToProvider = false, + bool sendEmailToProvider = false, + bool isFlexible = false, + const std::string& businessConnectionId = "", + std::int32_t subscriptionPeriod = 0) const; + + /** + * @brief Use this method to create a link for an invoice. Returns the created invoice link as + * String on success. + * + * @param args Method arguments. + * + * @return The resulting string. */ - std::string - createInvoiceLink(const std::string& title, const std::string& description, const std::string& payload, - const std::string& providerToken, const std::string& currency, - const std::vector>& prices, std::int32_t maxTipAmount = 0, - const std::vector& suggestedTipAmounts = { }, const std::string& providerData = "", - const std::string& photoUrl = "", std::int32_t photoSize = 0, std::int32_t photoWidth = 0, - std::int32_t photoHeight = 0, bool needName = false, bool needPhoneNumber = false, - bool needEmail = false, bool needShippingAddress = false, bool sendPhoneNumberToProvider = false, - bool sendEmailToProvider = false, bool isFlexible = false, - const std::string& businessConnectionId = "", std::int32_t subscriptionPeriod = 0) const; + std::string createInvoiceLink(const CreateInvoiceLinkArgs& args) const; /** * @brief Use this method to create a new sticker set owned by a user. The bot will be able to @@ -513,11 +789,24 @@ * white on chat photos, or another appropriate color based on context; for * custom emoji sticker sets only * - * @return Telegram Bot API result. + * @return True on success. */ - bool createNewStickerSet(std::int64_t userId, const std::string& name, const std::string& title, + bool createNewStickerSet(std::int64_t userId, + const std::string& name, + const std::string& title, const std::vector>& stickers, - Sticker::Type stickerType = Sticker::Type::Regular, bool needsRepainting = false) const; + Sticker::Type stickerType = Sticker::Type::Regular, + bool needsRepainting = false) const; + + /** + * @brief Use this method to create a new sticker set owned by a user. The bot will be able to + * edit the sticker set thus created. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool createNewStickerSet(const CreateNewStickerSetArgs& args) const; /** * @brief Use this method to decline a chat join request. The bot must be an administrator in the @@ -528,10 +817,21 @@ * in the format @username * @param userId Unique identifier of the target user * - * @return Telegram Bot API result. + * @return True on success. */ bool declineChatJoinRequest(std::variant chatId, std::int64_t userId) const; + /** + * @brief Use this method to decline a chat join request. The bot must be an administrator in the + * chat for this to work and must have the can_invite_users administrator right. Returns + * True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool declineChatJoinRequest(const DeclineChatJoinRequestArgs& args) const; + /** * @brief Use this method to decline a suggested post in a direct messages chat. The bot must have * the 'can_manage_direct_messages' administrator right in the corresponding channel chat. @@ -541,11 +841,23 @@ * @param messageId Identifier of a suggested post message to decline * @param comment Comment for the creator of the suggested post; 0-128 characters * - * @return Telegram Bot API result. + * @return True on success. */ - bool declineSuggestedPost(std::variant chatId, std::int32_t messageId, + bool declineSuggestedPost(std::variant chatId, + std::int32_t messageId, const std::string& comment = "") const; + /** + * @brief Use this method to decline a suggested post in a direct messages chat. The bot must have + * the 'can_manage_direct_messages' administrator right in the corresponding channel chat. + * Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool declineSuggestedPost(const DeclineSuggestedPostArgs& args) const; + /** * @brief Use this method to remove up to 10000 recent reactions in a group or a supergroup chat * added by a given user or chat. The bot must have the 'can_delete_messages' administrator @@ -559,11 +871,24 @@ * @param userId Identifier of the user whose reactions will be removed, if the reactions * were added by a user * - * @return Telegram Bot API result. + * @return True on success. */ - bool deleteAllMessageReactions(std::variant chatId, std::int64_t actorChatId = 0, + bool deleteAllMessageReactions(std::variant chatId, + std::int64_t actorChatId = 0, std::int64_t userId = 0) const; + /** + * @brief Use this method to remove up to 10000 recent reactions in a group or a supergroup chat + * added by a given user or chat. The bot must have the 'can_delete_messages' administrator + * right in the chat. Returns True on success. The following methods and objects allow your + * bot to handle stickers and sticker sets. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool deleteAllMessageReactions(const DeleteAllMessageReactionsArgs& args) const; + /** * @brief Delete messages on behalf of a business account. Requires the can_delete_sent_messages * business bot right to delete messages sent by the bot itself, or the @@ -576,11 +901,23 @@ * messages must be from the same chat. See deleteMessage for limitations * on which messages can be deleted. * - * @return Telegram Bot API result. + * @return True on success. */ bool deleteBusinessMessages(const std::string& businessConnectionId, const std::vector& messageIds) const; + /** + * @brief Delete messages on behalf of a business account. Requires the can_delete_sent_messages + * business bot right to delete messages sent by the bot itself, or the + * can_delete_all_messages business bot right to delete any message. Returns True on + * success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool deleteBusinessMessages(const DeleteBusinessMessagesArgs& args) const; + /** * @brief Use this method to delete a chat photo. Photos can't be changed for private chats. The * bot must be an administrator in the chat for this to work and must have the appropriate @@ -589,10 +926,21 @@ * @param chatId Unique identifier for the target chat or username of the target channel * in the format @username * - * @return Telegram Bot API result. + * @return True on success. */ bool deleteChatPhoto(std::variant chatId) const; + /** + * @brief Use this method to delete a chat photo. Photos can't be changed for private chats. The + * bot must be an administrator in the chat for this to work and must have the appropriate + * administrator rights. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool deleteChatPhoto(const DeleteChatPhotoArgs& args) const; + /** * @brief Use this method to delete a group sticker set from a supergroup. The bot must be an * administrator in the chat for this to work and must have the appropriate administrator @@ -602,10 +950,22 @@ * @param chatId Unique identifier for the target chat or username of the target * supergroup in the format @username * - * @return Telegram Bot API result. + * @return True on success. */ bool deleteChatStickerSet(std::variant chatId) const; + /** + * @brief Use this method to delete a group sticker set from a supergroup. The bot must be an + * administrator in the chat for this to work and must have the appropriate administrator + * rights. Use the field can_set_sticker_set optionally returned in getChat requests to + * check if the bot can use this method. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool deleteChatStickerSet(const DeleteChatStickerSetArgs& args) const; + /** * @brief Use this method to delete an ephemeral message. Note that it is not guaranteed that the * user will receive the message deletion event, especially if they are offline. Returns @@ -616,11 +976,23 @@ * @param ephemeralMessageId Identifier of the ephemeral message to delete * @param receiverUserId Identifier of the user who received the message * - * @return Telegram Bot API result. + * @return True on success. */ - bool deleteEphemeralMessage(std::variant chatId, std::int32_t ephemeralMessageId, + bool deleteEphemeralMessage(std::variant chatId, + std::int32_t ephemeralMessageId, std::int64_t receiverUserId) const; + /** + * @brief Use this method to delete an ephemeral message. Note that it is not guaranteed that the + * user will receive the message deletion event, especially if they are offline. Returns + * True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool deleteEphemeralMessage(const DeleteEphemeralMessageArgs& args) const; + /** * @brief Use this method to delete a forum topic along with all its messages in a forum * supergroup chat or a private chat with a user. In the case of a supergroup chat the bot @@ -631,10 +1003,22 @@ * supergroup in the format @username * @param messageThreadId Unique identifier for the target message thread of the forum topic * - * @return Telegram Bot API result. + * @return True on success. */ bool deleteForumTopic(std::variant chatId, std::int32_t messageThreadId) const; + /** + * @brief Use this method to delete a forum topic along with all its messages in a forum + * supergroup chat or a private chat with a user. In the case of a supergroup chat the bot + * must be an administrator in the chat for this to work and must have the + * can_delete_messages administrator rights. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool deleteForumTopic(const DeleteForumTopicArgs& args) const; + /** * @brief Use this method to delete a message, including service messages, with the following * limitations:- A message can only be deleted if it was sent less than 48 hours ago.- @@ -652,27 +1036,59 @@ * supergroup or channel in the format @username * @param messageId Identifier of the message to delete * - * @return Telegram Bot API result. + * @return True on success. */ bool deleteMessage(std::variant chatId, std::int32_t messageId) const; /** - * @brief Use this method to remove a reaction from a message in a group or a supergroup chat. The - * bot must have the 'can_delete_messages' administrator right in the chat. Returns True on - * success. - * - * @param chatId Unique identifier for the target chat or username of the target - * supergroup in the format @username + * @brief Use this method to delete a message, including service messages, with the following + * limitations:- A message can only be deleted if it was sent less than 48 hours ago.- + * Service messages about a supergroup, channel, or forum topic creation can't be deleted.- + * A dice message in a private chat can only be deleted if it was sent more than 24 hours + * ago.- Bots can delete outgoing messages in private chats, groups, and supergroups.- Bots + * can delete incoming messages in private chats.- Bots granted can_post_messages + * permissions can delete outgoing messages in channels.- If the bot is an administrator of + * a group, it can delete any message there.- If the bot has can_delete_messages + * administrator right in a supergroup or a channel, it can delete any message there.- If + * the bot has can_manage_direct_messages administrator right in a channel, it can delete + * any message in the corresponding direct messages chat.Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool deleteMessage(const DeleteMessageArgs& args) const; + + /** + * @brief Use this method to remove a reaction from a message in a group or a supergroup chat. The + * bot must have the 'can_delete_messages' administrator right in the chat. Returns True on + * success. + * + * @param chatId Unique identifier for the target chat or username of the target + * supergroup in the format @username * @param messageId Identifier of the target message * @param actorChatId Identifier of the chat whose reaction will be removed, if the reaction * was added by a chat * @param userId Identifier of the user whose reaction will be removed, if the reaction * was added by a user * - * @return Telegram Bot API result. + * @return True on success. + */ + bool deleteMessageReaction(std::variant chatId, + std::int32_t messageId, + std::int64_t actorChatId = 0, + std::int64_t userId = 0) const; + + /** + * @brief Use this method to remove a reaction from a message in a group or a supergroup chat. The + * bot must have the 'can_delete_messages' administrator right in the chat. Returns True on + * success. + * + * @param args Method arguments. + * + * @return True on success. */ - bool deleteMessageReaction(std::variant chatId, std::int32_t messageId, - std::int64_t actorChatId = 0, std::int64_t userId = 0) const; + bool deleteMessageReaction(const DeleteMessageReactionArgs& args) const; /** * @brief Use this method to delete multiple messages simultaneously. If some of the specified @@ -683,11 +1099,21 @@ * @param messageIds A JSON-serialized list of 1-100 identifiers of messages to delete. See * deleteMessage for limitations on which messages can be deleted. * - * @return Telegram Bot API result. + * @return True on success. */ bool deleteMessages(std::variant chatId, const std::vector& messageIds) const; + /** + * @brief Use this method to delete multiple messages simultaneously. If some of the specified + * messages can't be found, they are skipped. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool deleteMessages(const DeleteMessagesArgs& args) const; + /** * @brief Use this method to delete the list of the bot's commands for the given scope and user * language. After deletion, higher level commands will be shown to affected users. Returns @@ -699,9 +1125,21 @@ * to all users from the given scope, for whose language there are no * dedicated commands. * - * @return Telegram Bot API result. + * @return True on success. + */ + bool deleteMyCommands(std::shared_ptr scope = nullptr, + const std::string& languageCode = "") const; + + /** + * @brief Use this method to delete the list of the bot's commands for the given scope and user + * language. After deletion, higher level commands will be shown to affected users. Returns + * True on success. + * + * @param args Method arguments. + * + * @return True on success. */ - bool deleteMyCommands(std::shared_ptr scope = nullptr, const std::string& languageCode = "") const; + bool deleteMyCommands(const DeleteMyCommandsArgs& args) const; /** * @brief Use this method to delete a sticker from a set created by the bot. Returns True on @@ -709,10 +1147,20 @@ * * @param sticker File identifier of the sticker * - * @return Telegram Bot API result. + * @return True on success. */ bool deleteStickerFromSet(const std::string& sticker) const; + /** + * @brief Use this method to delete a sticker from a set created by the bot. Returns True on + * success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool deleteStickerFromSet(const DeleteStickerFromSetArgs& args) const; + /** * @brief Use this method to delete a sticker set that was created by the bot. Returns True on * success. The following methods and objects allow your bot to handle and send rich @@ -720,10 +1168,21 @@ * * @param name Sticker set name * - * @return Telegram Bot API result. + * @return True on success. */ bool deleteStickerSet(const std::string& name) const; + /** + * @brief Use this method to delete a sticker set that was created by the bot. Returns True on + * success. The following methods and objects allow your bot to handle and send rich + * messages. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool deleteStickerSet(const DeleteStickerSetArgs& args) const; + /** * @brief Deletes a story previously posted by the bot on behalf of a managed business account. * Requires the can_manage_stories business bot right. Returns True on success. @@ -731,20 +1190,40 @@ * @param businessConnectionId Unique identifier of the business connection * @param storyId Unique identifier of the story to delete * - * @return Telegram Bot API result. + * @return True on success. */ bool deleteStory(const std::string& businessConnectionId, std::int32_t storyId) const; + /** + * @brief Deletes a story previously posted by the bot on behalf of a managed business account. + * Requires the can_manage_stories business bot right. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool deleteStory(const DeleteStoryArgs& args) const; + /** * @brief Use this method to remove webhook integration if you decide to switch back to * getUpdates. Returns True on success. * * @param dropPendingUpdates Pass True to drop all pending updates * - * @return Telegram Bot API result. + * @return True on success. */ bool deleteWebhook(bool dropPendingUpdates = false) const; + /** + * @brief Use this method to remove webhook integration if you decide to switch back to + * getUpdates. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool deleteWebhook(const DeleteWebhookArgs& args) const; + /** * @brief Use this method to edit a non-primary invite link created by the bot. The bot must be an * administrator in the chat for this to work and must have the appropriate administrator @@ -760,13 +1239,26 @@ * @param createsJoinRequest True, if users joining the chat via the link need to be approved by chat * administrators. If True, member_limit can't be specified. * - * @return Telegram Bot API result. + * @return The resulting ChatInviteLink object. */ std::shared_ptr editChatInviteLink(std::variant chatId, - const std::string& inviteLink, std::int32_t expireDate = 0, - std::int32_t memberLimit = 0, const std::string& name = "", + const std::string& inviteLink, + std::int32_t expireDate = 0, + std::int32_t memberLimit = 0, + const std::string& name = "", bool createsJoinRequest = false) const; + /** + * @brief Use this method to edit a non-primary invite link created by the bot. The bot must be an + * administrator in the chat for this to work and must have the appropriate administrator + * rights. Returns the edited invite link as a ChatInviteLink object. + * + * @param args Method arguments. + * + * @return The resulting ChatInviteLink object. + */ + std::shared_ptr editChatInviteLink(const EditChatInviteLinkArgs& args) const; + /** * @brief Use this method to edit a subscription invite link created by the bot. The bot must have * the can_invite_users administrator rights. Returns the edited invite link as a @@ -777,12 +1269,24 @@ * @param inviteLink The invite link to edit * @param name Invite link name; 0-32 characters * - * @return Telegram Bot API result. + * @return The resulting ChatInviteLink object. */ std::shared_ptr editChatSubscriptionInviteLink(std::variant chatId, const std::string& inviteLink, const std::string& name = "") const; + /** + * @brief Use this method to edit a subscription invite link created by the bot. The bot must have + * the can_invite_users administrator rights. Returns the edited invite link as a + * ChatInviteLink object. + * + * @param args Method arguments. + * + * @return The resulting ChatInviteLink object. + */ + std::shared_ptr + editChatSubscriptionInviteLink(const EditChatSubscriptionInviteLinkArgs& args) const; + /** * @brief Use this method to edit the caption of an ephemeral message. Note that it is not * guaranteed that the user will receive the message edit event, especially if they are @@ -799,14 +1303,27 @@ * for more details. * @param replyMarkup A JSON-serialized object for an inline keyboard * - * @return Telegram Bot API result. + * @return True on success. */ - bool editEphemeralMessageCaption(std::variant chatId, std::int32_t ephemeralMessageId, - std::int64_t receiverUserId, const std::string& caption = "", + bool editEphemeralMessageCaption(std::variant chatId, + std::int32_t ephemeralMessageId, + std::int64_t receiverUserId, + const std::string& caption = "", const std::vector>& captionEntities = { }, const std::string& parseMode = "", std::shared_ptr replyMarkup = nullptr) const; + /** + * @brief Use this method to edit the caption of an ephemeral message. Note that it is not + * guaranteed that the user will receive the message edit event, especially if they are + * offline. On success, True is returned. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool editEphemeralMessageCaption(const EditEphemeralMessageCaptionArgs& args) const; + /** * @brief Use this method to edit the media of an ephemeral message. Note that it is not * guaranteed that the user will receive the message edit event, especially if they are @@ -821,12 +1338,25 @@ * @param receiverUserId Identifier of the user who received the message * @param replyMarkup A JSON-serialized object for an inline keyboard * - * @return Telegram Bot API result. + * @return True on success. */ - bool editEphemeralMessageMedia(std::variant chatId, std::int32_t ephemeralMessageId, - std::shared_ptr media, std::int64_t receiverUserId, + bool editEphemeralMessageMedia(std::variant chatId, + std::int32_t ephemeralMessageId, + std::shared_ptr media, + std::int64_t receiverUserId, std::shared_ptr replyMarkup = nullptr) const; + /** + * @brief Use this method to edit the media of an ephemeral message. Note that it is not + * guaranteed that the user will receive the message edit event, especially if they are + * offline. On success, True is returned. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool editEphemeralMessageMedia(const EditEphemeralMessageMediaArgs& args) const; + /** * @brief Use this method to edit only the reply markup of an ephemeral message. Note that it is * not guaranteed that the user will receive the message edit event, especially if they are @@ -838,12 +1368,24 @@ * @param receiverUserId Identifier of the user who received the message * @param replyMarkup A JSON-serialized object for an inline keyboard * - * @return Telegram Bot API result. + * @return True on success. */ bool editEphemeralMessageReplyMarkup(std::variant chatId, - std::int32_t ephemeralMessageId, std::int64_t receiverUserId, + std::int32_t ephemeralMessageId, + std::int64_t receiverUserId, std::shared_ptr replyMarkup = nullptr) const; + /** + * @brief Use this method to edit only the reply markup of an ephemeral message. Note that it is + * not guaranteed that the user will receive the message edit event, especially if they are + * offline. On success, True is returned. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool editEphemeralMessageReplyMarkup(const EditEphemeralMessageReplyMarkupArgs& args) const; + /** * @brief Use this method to edit an ephemeral text message. Note that it is not guaranteed that * the user will receive the message edit event, especially if they are offline. On @@ -861,15 +1403,28 @@ * for more details. * @param replyMarkup A JSON-serialized object for an inline keyboard * - * @return Telegram Bot API result. + * @return True on success. */ - bool editEphemeralMessageText(std::variant chatId, std::int32_t ephemeralMessageId, - std::int64_t receiverUserId, const std::string& text, + bool editEphemeralMessageText(std::variant chatId, + std::int32_t ephemeralMessageId, + std::int64_t receiverUserId, + const std::string& text, const std::vector>& entities = { }, std::shared_ptr linkPreviewOptions = nullptr, const std::string& parseMode = "", std::shared_ptr replyMarkup = nullptr) const; + /** + * @brief Use this method to edit an ephemeral text message. Note that it is not guaranteed that + * the user will receive the message edit event, especially if they are offline. On + * success, True is returned. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool editEphemeralMessageText(const EditEphemeralMessageTextArgs& args) const; + /** * @brief Use this method to edit name and icon of a topic in a forum supergroup chat or a private * chat with a user. In the case of a supergroup chat the bot must be an administrator in @@ -886,10 +1441,24 @@ * Pass an empty string to remove the icon. If not specified, the current * icon will be kept. * - * @return Telegram Bot API result. + * @return True on success. + */ + bool editForumTopic(std::variant chatId, + std::int32_t messageThreadId, + const std::string& name = "", + const std::string& iconCustomEmojiId = "") const; + + /** + * @brief Use this method to edit name and icon of a topic in a forum supergroup chat or a private + * chat with a user. In the case of a supergroup chat the bot must be an administrator in + * the chat for this to work and must have the can_manage_topics administrator rights, + * unless it is the creator of the topic. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. */ - bool editForumTopic(std::variant chatId, std::int32_t messageThreadId, - const std::string& name = "", const std::string& iconCustomEmojiId = "") const; + bool editForumTopic(const EditForumTopicArgs& args) const; /** * @brief Use this method to edit the name of the 'General' topic in a forum supergroup chat. The @@ -900,10 +1469,21 @@ * supergroup in the format @username * @param name New topic name, 1-128 characters * - * @return Telegram Bot API result. + * @return True on success. */ bool editGeneralForumTopic(std::variant chatId, const std::string& name) const; + /** + * @brief Use this method to edit the name of the 'General' topic in a forum supergroup chat. The + * bot must be an administrator in the chat for this to work and must have the + * can_manage_topics administrator rights. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool editGeneralForumTopic(const EditGeneralForumTopicArgs& args) const; + /** * @brief Use this method to edit captions of messages. On success, if the edited message is not * an inline message, the edited Message is returned, otherwise True is returned. Note that @@ -928,14 +1508,30 @@ * @param showCaptionAboveMedia Pass True if the caption must be shown above the message media. * Supported only for animation, photo and video messages. * - * @return Telegram Bot API result. + * @return The resulting Message object, or nullptr if Telegram returns True. + */ + std::shared_ptr editMessageCaption(std::variant chatId = { }, + std::int32_t messageId = 0, + const std::string& caption = "", + const std::string& inlineMessageId = "", + std::shared_ptr replyMarkup = nullptr, + const std::string& parseMode = "", + const std::vector>& captionEntities + = { }, + const std::string& businessConnectionId = "", + bool showCaptionAboveMedia = false) const; + + /** + * @brief Use this method to edit captions of messages. On success, if the edited message is not + * an inline message, the edited Message is returned, otherwise True is returned. Note that + * business messages that were not sent by the bot and do not contain an inline keyboard + * can only be edited within 48 hours from the time they were sent. + * + * @param args Method arguments. + * + * @return The resulting Message object, or nullptr if Telegram returns True. */ - std::shared_ptr - editMessageCaption(std::variant chatId = { }, std::int32_t messageId = 0, - const std::string& caption = "", const std::string& inlineMessageId = "", - std::shared_ptr replyMarkup = nullptr, const std::string& parseMode = "", - const std::vector>& captionEntities = { }, - const std::string& businessConnectionId = "", bool showCaptionAboveMedia = false) const; + std::shared_ptr editMessageCaption(const EditMessageCaptionArgs& args) const; /** * @brief Use this method to edit a checklist on behalf of a connected business account. On @@ -949,12 +1545,24 @@ * @param messageId Unique identifier for the target message * @param replyMarkup A JSON-serialized object for the new inline keyboard for the message * - * @return Telegram Bot API result. + * @return The resulting Message object. */ std::shared_ptr editMessageChecklist(std::variant chatId, const std::string& businessConnectionId, - std::shared_ptr checklist, std::int32_t messageId, - std::shared_ptr replyMarkup = nullptr) const; + std::shared_ptr checklist, + std::int32_t messageId, + std::shared_ptr replyMarkup + = nullptr) const; + + /** + * @brief Use this method to edit a checklist on behalf of a connected business account. On + * success, the edited Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. + */ + std::shared_ptr editMessageChecklist(const EditMessageChecklistArgs& args) const; /** * @brief Use this method to edit live location messages. A location can be edited until its @@ -986,14 +1594,31 @@ * expiration date must remain within the next 90 days. If not specified, * then live_period remains unchanged. * - * @return Telegram Bot API result. + * @return The resulting Message object, or nullptr if Telegram returns True. + */ + std::shared_ptr editMessageLiveLocation(double latitude, + double longitude, + std::variant chatId = { }, + std::int32_t messageId = 0, + const std::string& inlineMessageId = "", + std::shared_ptr replyMarkup = nullptr, + double horizontalAccuracy = 0, + std::int32_t heading = 0, + std::int32_t proximityAlertRadius = 0, + const std::string& businessConnectionId = "", + std::int32_t livePeriod = 0) const; + + /** + * @brief Use this method to edit live location messages. A location can be edited until its + * live_period expires or editing is explicitly disabled by a call to + * stopMessageLiveLocation. On success, if the edited message is not an inline message, the + * edited Message is returned, otherwise True is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object, or nullptr if Telegram returns True. */ - std::shared_ptr - editMessageLiveLocation(double latitude, double longitude, std::variant chatId = { }, - std::int32_t messageId = 0, const std::string& inlineMessageId = "", - std::shared_ptr replyMarkup = nullptr, double horizontalAccuracy = 0, - std::int32_t heading = 0, std::int32_t proximityAlertRadius = 0, - const std::string& businessConnectionId = "", std::int32_t livePeriod = 0) const; + std::shared_ptr editMessageLiveLocation(const EditMessageLiveLocationArgs& args) const; /** * @brief Use this method to edit animation, audio, document, live photo, photo, or video @@ -1018,14 +1643,32 @@ * @param businessConnectionId Unique identifier of the business connection on behalf of which the * message to be edited was sent * - * @return Telegram Bot API result. + * @return The resulting Message object, or nullptr if Telegram returns True. */ std::shared_ptr editMessageMedia(std::shared_ptr media, std::variant chatId = { }, - std::int32_t messageId = 0, const std::string& inlineMessageId = "", + std::int32_t messageId = 0, + const std::string& inlineMessageId = "", std::shared_ptr replyMarkup = nullptr, const std::string& businessConnectionId = "") const; + /** + * @brief Use this method to edit animation, audio, document, live photo, photo, or video + * messages, or to replace a text or a rich message with a media. If a message is part of a + * message album, then it can be edited only to an audio for audio albums, only to a + * document for document albums and to a photo, a live photo, or a video otherwise. When an + * inline message is edited, a new file can't be uploaded; use a previously uploaded file + * via its file_id or specify a URL. On success, if the edited message is not an inline + * message, the edited Message is returned, otherwise True is returned. Note that business + * messages that were not sent by the bot and do not contain an inline keyboard can only be + * edited within 48 hours from the time they were sent. + * + * @param args Method arguments. + * + * @return The resulting Message object, or nullptr if Telegram returns True. + */ + std::shared_ptr editMessageMedia(const EditMessageMediaArgs& args) const; + /** * @brief Use this method to edit only the reply markup of messages. On success, if the edited * message is not an inline message, the edited Message is returned, otherwise True is @@ -1043,13 +1686,26 @@ * @param businessConnectionId Unique identifier of the business connection on behalf of which the * message to be edited was sent * - * @return Telegram Bot API result. + * @return The resulting Message object, or nullptr if Telegram returns True. */ std::shared_ptr editMessageReplyMarkup(std::variant chatId = { }, - std::int32_t messageId = 0, const std::string& inlineMessageId = "", + std::int32_t messageId = 0, + const std::string& inlineMessageId = "", std::shared_ptr replyMarkup = nullptr, const std::string& businessConnectionId = "") const; + /** + * @brief Use this method to edit only the reply markup of messages. On success, if the edited + * message is not an inline message, the edited Message is returned, otherwise True is + * returned. Note that business messages that were not sent by the bot and do not contain + * an inline keyboard can only be edited within 48 hours from the time they were sent. + * + * @param args Method arguments. + * + * @return The resulting Message object, or nullptr if Telegram returns True. + */ + std::shared_ptr editMessageReplyMarkup(const EditMessageReplyMarkupArgs& args) const; + /** * @brief Use this method to edit text, rich and game messages. On success, if the edited message * is not an inline message, the edited Message is returned, otherwise True is returned. @@ -1077,11 +1733,12 @@ * Direct upload of new files isn't supported when an inline message is * edited. * - * @return Telegram Bot API result. + * @return The resulting Message object, or nullptr if Telegram returns True. */ std::shared_ptr editMessageText(const std::string& text = "", std::variant chatId = { }, - std::int32_t messageId = 0, const std::string& inlineMessageId = "", + std::int32_t messageId = 0, + const std::string& inlineMessageId = "", const std::string& parseMode = "", std::shared_ptr linkPreviewOptions = nullptr, std::shared_ptr replyMarkup = nullptr, @@ -1089,6 +1746,18 @@ const std::string& businessConnectionId = "", std::shared_ptr richMessage = nullptr) const; + /** + * @brief Use this method to edit text, rich and game messages. On success, if the edited message + * is not an inline message, the edited Message is returned, otherwise True is returned. + * Note that business messages that were not sent by the bot and do not contain an inline + * keyboard can only be edited within 48 hours from the time they were sent. + * + * @param args Method arguments. + * + * @return The resulting Message object, or nullptr if Telegram returns True. + */ + std::shared_ptr editMessageText(const EditMessageTextArgs& args) const; + /** * @brief Edits a story previously posted by the bot on behalf of a managed business account. * Requires the can_manage_stories business bot right. Returns Story on success. @@ -1103,15 +1772,26 @@ * @param parseMode Mode for parsing entities in the story caption. See formatting options * for more details. * - * @return Telegram Bot API result. + * @return The resulting Story object. */ std::shared_ptr editStory(const std::string& businessConnectionId, - std::shared_ptr content, std::int32_t storyId, + std::shared_ptr content, + std::int32_t storyId, const std::vector>& areas = { }, const std::string& caption = "", const std::vector>& captionEntities = { }, const std::string& parseMode = "") const; + /** + * @brief Edits a story previously posted by the bot on behalf of a managed business account. + * Requires the can_manage_stories business bot right. Returns Story on success. + * + * @param args Method arguments. + * + * @return The resulting Story object. + */ + std::shared_ptr editStory(const EditStoryArgs& args) const; + /** * @brief Allows the bot to cancel or re-enable extension of a subscription paid in Telegram * Stars. Returns True on success. @@ -1123,11 +1803,22 @@ * @param telegramPaymentChargeId Telegram payment identifier for the subscription * @param userId Identifier of the user whose subscription will be edited * - * @return Telegram Bot API result. + * @return True on success. */ - bool editUserStarSubscription(bool isCanceled, const std::string& telegramPaymentChargeId, + bool editUserStarSubscription(bool isCanceled, + const std::string& telegramPaymentChargeId, std::int64_t userId) const; + /** + * @brief Allows the bot to cancel or re-enable extension of a subscription paid in Telegram + * Stars. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool editUserStarSubscription(const EditUserStarSubscriptionArgs& args) const; + /** * @brief Use this method to generate a new primary invite link for a chat; any previously * generated primary link is revoked. The bot must be an administrator in the chat for this @@ -1137,10 +1828,22 @@ * @param chatId Unique identifier for the target chat or username of the target channel * in the format @username * - * @return Telegram Bot API result. + * @return The resulting string. */ std::string exportChatInviteLink(std::variant chatId) const; + /** + * @brief Use this method to generate a new primary invite link for a chat; any previously + * generated primary link is revoked. The bot must be an administrator in the chat for this + * to work and must have the appropriate administrator rights. Returns the new invite link + * as String on success. + * + * @param args Method arguments. + * + * @return The resulting string. + */ + std::string exportChatInviteLink(const ExportChatInviteLinkArgs& args) const; + /** * @brief Use this method to forward messages of any kind. Service messages and messages with * protected content can't be forwarded. On success, the sent Message is returned. @@ -1167,16 +1870,30 @@ * to send; for direct messages chats only * @param videoStartTimestamp New start timestamp for the forwarded video in the message * - * @return Telegram Bot API result. + * @return The resulting Message object. */ std::shared_ptr forwardMessage(std::variant chatId, - std::variant fromChatId, std::int32_t messageId, - bool disableNotification = false, bool protectContent = false, - std::int32_t messageThreadId = 0, std::int64_t directMessagesTopicId = 0, + std::variant fromChatId, + std::int32_t messageId, + bool disableNotification = false, + bool protectContent = false, + std::int32_t messageThreadId = 0, + std::int64_t directMessagesTopicId = 0, const std::string& messageEffectId = "", - std::shared_ptr suggestedPostParameters = nullptr, + std::shared_ptr suggestedPostParameters + = nullptr, std::int32_t videoStartTimestamp = 0) const; + /** + * @brief Use this method to forward messages of any kind. Service messages and messages with + * protected content can't be forwarded. On success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. + */ + std::shared_ptr forwardMessage(const ForwardMessageArgs& args) const; + /** * @brief Use this method to forward multiple messages of any kind. If some of the specified * messages can't be found or forwarded, they are skipped. Service messages and messages @@ -1202,20 +1919,34 @@ * forwarded; required if the messages are forwarded to a direct messages * chat * - * @return Telegram Bot API result. + * @return The resulting list of MessageId objects. + */ + std::vector> forwardMessages(std::variant chatId, + std::variant fromChatId, + const std::vector& messageIds, + std::int32_t messageThreadId = 0, + bool disableNotification = false, + bool protectContent = false, + std::int64_t directMessagesTopicId = 0) const; + + /** + * @brief Use this method to forward multiple messages of any kind. If some of the specified + * messages can't be found or forwarded, they are skipped. Service messages and messages + * with protected content can't be forwarded. Album grouping is kept for forwarded + * messages. On success, an Array of MessageId of the sent messages is returned. + * + * @param args Method arguments. + * + * @return The resulting list of MessageId objects. */ - std::vector> - forwardMessages(std::variant chatId, std::variant fromChatId, - const std::vector& messageIds, std::int32_t messageThreadId = 0, - bool disableNotification = false, bool protectContent = false, - std::int64_t directMessagesTopicId = 0) const; + std::vector> forwardMessages(const ForwardMessagesArgs& args) const; /** * @brief Returns the list of gifts that can be sent by the bot to users and channel chats. * Requires no parameters. Returns a Gifts object. * * - * @return Telegram Bot API result. + * @return The resulting Gifts object. */ std::shared_ptr getAvailableGifts() const; @@ -1242,14 +1973,29 @@ * @param sortByPrice Pass True to sort results by gift price instead of send date. Sorting is * applied before pagination. * - * @return Telegram Bot API result. + * @return The resulting OwnedGifts object. + */ + std::shared_ptr getBusinessAccountGifts(const std::string& businessConnectionId, + bool excludeFromBlockchain = false, + bool excludeLimitedNonUpgradable = false, + bool excludeLimitedUpgradable = false, + bool excludeSaved = false, + bool excludeUnique = false, + bool excludeUnlimited = false, + bool excludeUnsaved = false, + std::int32_t limit = 0, + const std::string& offset = "", + bool sortByPrice = false) const; + + /** + * @brief Returns the gifts received and owned by a managed business account. Requires the + * can_view_gifts_and_stars business bot right. Returns OwnedGifts on success. + * + * @param args Method arguments. + * + * @return The resulting OwnedGifts object. */ - std::shared_ptr - getBusinessAccountGifts(const std::string& businessConnectionId, bool excludeFromBlockchain = false, - bool excludeLimitedNonUpgradable = false, bool excludeLimitedUpgradable = false, - bool excludeSaved = false, bool excludeUnique = false, bool excludeUnlimited = false, - bool excludeUnsaved = false, std::int32_t limit = 0, const std::string& offset = "", - bool sortByPrice = false) const; + std::shared_ptr getBusinessAccountGifts(const GetBusinessAccountGiftsArgs& args) const; /** * @brief Returns the amount of Telegram Stars owned by a managed business account. Requires the @@ -1257,31 +2003,61 @@ * * @param businessConnectionId Unique identifier of the business connection * - * @return Telegram Bot API result. + * @return The resulting StarAmount object. */ std::shared_ptr getBusinessAccountStarBalance(const std::string& businessConnectionId) const; + /** + * @brief Returns the amount of Telegram Stars owned by a managed business account. Requires the + * can_view_gifts_and_stars business bot right. Returns StarAmount on success. + * + * @param args Method arguments. + * + * @return The resulting StarAmount object. + */ + std::shared_ptr getBusinessAccountStarBalance(const GetBusinessAccountStarBalanceArgs& args) const; + /** * @brief Use this method to get information about the connection of the bot with a business * account. Returns a BusinessConnection object on success. * * @param businessConnectionId Unique identifier of the business connection * - * @return Telegram Bot API result. + * @return The resulting BusinessConnection object. */ std::shared_ptr getBusinessConnection(const std::string& businessConnectionId) const; /** - * @brief Use this method to get up-to-date information about the chat. Returns a ChatFullInfo - * object on success. - * + * @brief Use this method to get information about the connection of the bot with a business + * account. Returns a BusinessConnection object on success. + * + * @param args Method arguments. + * + * @return The resulting BusinessConnection object. + */ + std::shared_ptr getBusinessConnection(const GetBusinessConnectionArgs& args) const; + + /** + * @brief Use this method to get up-to-date information about the chat. Returns a ChatFullInfo + * object on success. + * * @param chatId Unique identifier for the target chat or username of the target * supergroup or channel in the format @username * - * @return Telegram Bot API result. + * @return The resulting ChatFullInfo object. */ std::shared_ptr getChat(std::variant chatId) const; + /** + * @brief Use this method to get up-to-date information about the chat. Returns a ChatFullInfo + * object on success. + * + * @param args Method arguments. + * + * @return The resulting ChatFullInfo object. + */ + std::shared_ptr getChat(const GetChatArgs& args) const; + /** * @brief Use this method to get a list of administrators in a chat. Returns an Array of * ChatMember objects. @@ -1291,11 +2067,21 @@ * @param returnBots Pass True to additionally receive all bots that are administrators of * the chat. By default, bots other than the current bot are omitted. * - * @return Telegram Bot API result. + * @return The resulting list of ChatMember objects. */ std::vector> getChatAdministrators(std::variant chatId, bool returnBots = false) const; + /** + * @brief Use this method to get a list of administrators in a chat. Returns an Array of + * ChatMember objects. + * + * @param args Method arguments. + * + * @return The resulting list of ChatMember objects. + */ + std::vector> getChatAdministrators(const GetChatAdministratorsArgs& args) const; + /** * @brief Returns the gifts owned by a chat. Returns OwnedGifts on success. * @@ -1322,15 +2108,28 @@ * @param sortByPrice Pass True to sort results by gift price instead of send date. Sorting is * applied before pagination. * - * @return Telegram Bot API result. + * @return The resulting OwnedGifts object. */ std::shared_ptr getChatGifts(std::variant chatId, bool excludeFromBlockchain = false, bool excludeLimitedNonUpgradable = false, - bool excludeLimitedUpgradable = false, bool excludeSaved = false, - bool excludeUnique = false, bool excludeUnlimited = false, - bool excludeUnsaved = false, std::int32_t limit = 0, - const std::string& offset = "", bool sortByPrice = false) const; + bool excludeLimitedUpgradable = false, + bool excludeSaved = false, + bool excludeUnique = false, + bool excludeUnlimited = false, + bool excludeUnsaved = false, + std::int32_t limit = 0, + const std::string& offset = "", + bool sortByPrice = false) const; + + /** + * @brief Returns the gifts owned by a chat. Returns OwnedGifts on success. + * + * @param args Method arguments. + * + * @return The resulting OwnedGifts object. + */ + std::shared_ptr getChatGifts(const GetChatGiftsArgs& args) const; /** * @brief Use this method to get information about a member of a chat. The method is only @@ -1341,21 +2140,41 @@ * supergroup or channel in the format @username * @param userId Unique identifier of the target user * - * @return Telegram Bot API result. + * @return The resulting ChatMember object. */ std::shared_ptr getChatMember(std::variant chatId, std::int64_t userId) const; + /** + * @brief Use this method to get information about a member of a chat. The method is only + * guaranteed to work for other users if the bot is an administrator in the chat. Returns a + * ChatMember object on success. + * + * @param args Method arguments. + * + * @return The resulting ChatMember object. + */ + std::shared_ptr getChatMember(const GetChatMemberArgs& args) const; + /** * @brief Use this method to get the number of members in a chat. Returns Integer on success. * * @param chatId Unique identifier for the target chat or username of the target * supergroup or channel in the format @username * - * @return Telegram Bot API result. + * @return The resulting integer. */ std::int32_t getChatMemberCount(std::variant chatId) const; + /** + * @brief Use this method to get the number of members in a chat. Returns Integer on success. + * + * @param args Method arguments. + * + * @return The resulting integer. + */ + std::int32_t getChatMemberCount(const GetChatMemberCountArgs& args) const; + /** * @brief Use this method to get the current value of the bot's menu button in a private chat, or * the default menu button. Returns MenuButton on success. @@ -1363,10 +2182,20 @@ * @param chatId Unique identifier for the target private chat. If not specified, the * bot's default menu button will be returned. * - * @return Telegram Bot API result. + * @return The resulting MenuButton object. */ std::shared_ptr getChatMenuButton(std::variant chatId = { }) const; + /** + * @brief Use this method to get the current value of the bot's menu button in a private chat, or + * the default menu button. Returns MenuButton on success. + * + * @param args Method arguments. + * + * @return The resulting MenuButton object. + */ + std::shared_ptr getChatMenuButton(const GetChatMenuButtonArgs& args) const; + /** * @brief Use this method to get information about custom emoji stickers by their identifiers. * Returns an Array of Sticker objects. @@ -1374,9 +2203,20 @@ * @param customEmojiIds A JSON-serialized list of custom emoji identifiers. At most 200 custom * emoji identifiers can be specified. * - * @return Telegram Bot API result. + * @return The resulting list of Sticker objects. + */ + std::vector> + getCustomEmojiStickers(const std::vector& customEmojiIds) const; + + /** + * @brief Use this method to get information about custom emoji stickers by their identifiers. + * Returns an Array of Sticker objects. + * + * @param args Method arguments. + * + * @return The resulting list of Sticker objects. */ - std::vector> getCustomEmojiStickers(const std::vector& customEmojiIds) const; + std::vector> getCustomEmojiStickers(const GetCustomEmojiStickersArgs& args) const; /** * @brief Use this method to get basic information about a file and prepare it for downloading. @@ -1390,16 +2230,32 @@ * * @param fileId File identifier to get information about * - * @return Telegram Bot API result. + * @return The resulting File object. */ std::shared_ptr getFile(const std::string& fileId) const; + /** + * @brief Use this method to get basic information about a file and prepare it for downloading. + * For the moment, bots can download files of up to 20MB in size. On success, a File object + * is returned. The file can then be downloaded via the link + * https://api.telegram.org/file/bot/, where is taken from + * the response. It is guaranteed that the link will be valid for at least 1 hour. When the + * link expires, a new one can be requested by calling getFile again. Note: This function + * may not preserve the original file name and MIME type. You should save the file's MIME + * type and name (if available) when the File object is received. + * + * @param args Method arguments. + * + * @return The resulting File object. + */ + std::shared_ptr getFile(const GetFileArgs& args) const; + /** * @brief Use this method to get custom emoji stickers, which can be used as a forum topic icon by * any user. Requires no parameters. Returns an Array of Sticker objects. * * - * @return Telegram Bot API result. + * @return The resulting list of Sticker objects. */ std::vector> getForumTopicIconStickers() const; @@ -1416,13 +2272,25 @@ * @param inlineMessageId Required if chat_id and message_id are not specified. Identifier of the * inline message. * - * @return Telegram Bot API result. + * @return The resulting list of GameHighScore objects. */ std::vector> getGameHighScores(std::int64_t userId, - std::variant chatId = { }, + std::variant chatId + = { }, std::int32_t messageId = 0, const std::string& inlineMessageId = "") const; + /** + * @brief Use this method to get data for high score tables. Will return the score of the + * specified user and several of their neighbors in a game. Returns an Array of + * GameHighScore objects. + * + * @param args Method arguments. + * + * @return The resulting list of GameHighScore objects. + */ + std::vector> getGameHighScores(const GetGameHighScoresArgs& args) const; + /** * @brief Use this method to get the access settings of a managed bot. Returns a BotAccessSettings * object on success. @@ -1430,26 +2298,47 @@ * @param userId User identifier of the managed bot whose access settings will be * returned * - * @return Telegram Bot API result. + * @return The resulting BotAccessSettings object. */ std::shared_ptr getManagedBotAccessSettings(std::int64_t userId) const; + /** + * @brief Use this method to get the access settings of a managed bot. Returns a BotAccessSettings + * object on success. + * + * @param args Method arguments. + * + * @return The resulting BotAccessSettings object. + */ + std::shared_ptr + getManagedBotAccessSettings(const GetManagedBotAccessSettingsArgs& args) const; + /** * @brief Use this method to get the token of a managed bot. Returns the token as String on * success. * * @param userId User identifier of the managed bot whose token will be returned * - * @return Telegram Bot API result. + * @return The resulting string. */ std::string getManagedBotToken(std::int64_t userId) const; + /** + * @brief Use this method to get the token of a managed bot. Returns the token as String on + * success. + * + * @param args Method arguments. + * + * @return The resulting string. + */ + std::string getManagedBotToken(const GetManagedBotTokenArgs& args) const; + /** * @brief A simple method for testing your bot's authentication token. Requires no parameters. * Returns basic information about the bot in form of a User object. * * - * @return Telegram Bot API result. + * @return The resulting User object. */ std::shared_ptr getMe() const; @@ -1462,11 +2351,22 @@ * BotCommandScopeDefault. * @param languageCode A two-letter ISO 639-1 language code or an empty string * - * @return Telegram Bot API result. + * @return The resulting list of BotCommand objects. */ std::vector> getMyCommands(std::shared_ptr scope = nullptr, const std::string& languageCode = "") const; + /** + * @brief Use this method to get the current list of the bot's commands for the given scope and + * user language. Returns an Array of BotCommand objects. If commands aren't set, an empty + * list is returned. + * + * @param args Method arguments. + * + * @return The resulting list of BotCommand objects. + */ + std::vector> getMyCommands(const GetMyCommandsArgs& args) const; + /** * @brief Use this method to get the current default administrator rights of the bot. Returns * ChatAdministratorRights on success. @@ -1475,46 +2375,87 @@ * Otherwise, default administrator rights of the bot for groups and * supergroups will be returned. * - * @return Telegram Bot API result. + * @return The resulting ChatAdministratorRights object. */ std::shared_ptr getMyDefaultAdministratorRights(bool forChannels = false) const; + /** + * @brief Use this method to get the current default administrator rights of the bot. Returns + * ChatAdministratorRights on success. + * + * @param args Method arguments. + * + * @return The resulting ChatAdministratorRights object. + */ + std::shared_ptr + getMyDefaultAdministratorRights(const GetMyDefaultAdministratorRightsArgs& args) const; + /** * @brief Use this method to get the current bot description for the given user language. Returns * BotDescription on success. * * @param languageCode A two-letter ISO 639-1 language code or an empty string * - * @return Telegram Bot API result. + * @return The resulting BotDescription object. */ std::shared_ptr getMyDescription(const std::string& languageCode = "") const; + /** + * @brief Use this method to get the current bot description for the given user language. Returns + * BotDescription on success. + * + * @param args Method arguments. + * + * @return The resulting BotDescription object. + */ + std::shared_ptr getMyDescription(const GetMyDescriptionArgs& args) const; + /** * @brief Use this method to get the current bot name for the given user language. Returns BotName * on success. * * @param languageCode A two-letter ISO 639-1 language code or an empty string * - * @return Telegram Bot API result. + * @return The resulting BotName object. */ std::shared_ptr getMyName(const std::string& languageCode = "") const; + /** + * @brief Use this method to get the current bot name for the given user language. Returns BotName + * on success. + * + * @param args Method arguments. + * + * @return The resulting BotName object. + */ + std::shared_ptr getMyName(const GetMyNameArgs& args) const; + /** * @brief Use this method to get the current bot short description for the given user language. * Returns BotShortDescription on success. * * @param languageCode A two-letter ISO 639-1 language code or an empty string * - * @return Telegram Bot API result. + * @return The resulting BotShortDescription object. */ std::shared_ptr getMyShortDescription(const std::string& languageCode = "") const; + /** + * @brief Use this method to get the current bot short description for the given user language. + * Returns BotShortDescription on success. + * + * @param args Method arguments. + * + * @return The resulting BotShortDescription object. + */ + std::shared_ptr getMyShortDescription(const GetMyShortDescriptionArgs& args) const; + /** * @brief A method to get the current Telegram Stars balance of the bot. Requires no parameters. * On success, returns a StarAmount object. * * - * @return Telegram Bot API result. + * @return The resulting StarAmount object. */ std::shared_ptr getMyStarBalance() const; @@ -1526,19 +2467,38 @@ * are accepted. Defaults to 100. * @param offset Number of transactions to skip in the response * - * @return Telegram Bot API result. + * @return The resulting StarTransactions object. */ std::shared_ptr getStarTransactions(std::int32_t limit = 0, std::int32_t offset = 0) const; + /** + * @brief Returns the bot's Telegram Star transactions in chronological order. On success, returns + * a StarTransactions object. + * + * @param args Method arguments. + * + * @return The resulting StarTransactions object. + */ + std::shared_ptr getStarTransactions(const GetStarTransactionsArgs& args) const; + /** * @brief Use this method to get a sticker set. On success, a StickerSet object is returned. * * @param name Name of the sticker set * - * @return Telegram Bot API result. + * @return The resulting StickerSet object. */ std::shared_ptr getStickerSet(const std::string& name) const; + /** + * @brief Use this method to get a sticker set. On success, a StickerSet object is returned. + * + * @param args Method arguments. + * + * @return The resulting StickerSet object. + */ + std::shared_ptr getStickerSet(const GetStickerSetArgs& args) const; + /** * @brief Use this method to receive incoming updates using long polling (wiki). Returns an Array * of Update objects. @@ -1565,12 +2525,23 @@ * created before the call to getUpdates, so unwanted updates may be * received for a short period of time. * - * @return Telegram Bot API result. + * @return The resulting list of Update objects. */ - std::vector> getUpdates(std::int32_t offset = 0, std::int32_t limit = 100, + std::vector> getUpdates(std::int32_t offset = 0, + std::int32_t limit = 100, std::int32_t timeout = 0, const std::vector& allowedUpdates = { }) const; + /** + * @brief Use this method to receive incoming updates using long polling (wiki). Returns an Array + * of Update objects. + * + * @param args Method arguments. + * + * @return The resulting list of Update objects. + */ + std::vector> getUpdates(const GetUpdatesArgs& args) const; + /** * @brief Use this method to get the list of boosts added to a chat by a user. Requires * administrator rights in the chat. Returns a UserChatBoosts object. @@ -1579,11 +2550,21 @@ * @username * @param userId Unique identifier of the target user * - * @return Telegram Bot API result. + * @return The resulting UserChatBoosts object. */ std::shared_ptr getUserChatBoosts(std::variant chatId, std::int64_t userId) const; + /** + * @brief Use this method to get the list of boosts added to a chat by a user. Requires + * administrator rights in the chat. Returns a UserChatBoosts object. + * + * @param args Method arguments. + * + * @return The resulting UserChatBoosts object. + */ + std::shared_ptr getUserChatBoosts(const GetUserChatBoostsArgs& args) const; + /** * @brief Returns the gifts owned and hosted by a user. Returns OwnedGifts on success. * @@ -1603,13 +2584,26 @@ * @param sortByPrice Pass True to sort results by gift price instead of send date. Sorting is * applied before pagination. * - * @return Telegram Bot API result. + * @return The resulting OwnedGifts object. */ - std::shared_ptr getUserGifts(std::int64_t userId, bool excludeFromBlockchain = false, + std::shared_ptr getUserGifts(std::int64_t userId, + bool excludeFromBlockchain = false, bool excludeLimitedNonUpgradable = false, - bool excludeLimitedUpgradable = false, bool excludeUnique = false, - bool excludeUnlimited = false, std::int32_t limit = 0, - const std::string& offset = "", bool sortByPrice = false) const; + bool excludeLimitedUpgradable = false, + bool excludeUnique = false, + bool excludeUnlimited = false, + std::int32_t limit = 0, + const std::string& offset = "", + bool sortByPrice = false) const; + + /** + * @brief Returns the gifts owned and hosted by a user. Returns OwnedGifts on success. + * + * @param args Method arguments. + * + * @return The resulting OwnedGifts object. + */ + std::shared_ptr getUserGifts(const GetUserGiftsArgs& args) const; /** * @brief Use this method to get the last messages from the personal chat (i.e., the chat @@ -1619,9 +2613,22 @@ * @param limit The maximum number of messages to return; 1-20 * @param userId Unique identifier for the target user * - * @return Telegram Bot API result. + * @return The resulting list of Message objects. + */ + std::vector> getUserPersonalChatMessages(std::int32_t limit, + std::int64_t userId) const; + + /** + * @brief Use this method to get the last messages from the personal chat (i.e., the chat + * currently added to their profile) of a given user. On success, an Array of Message + * objects is returned. + * + * @param args Method arguments. + * + * @return The resulting list of Message objects. */ - std::vector> getUserPersonalChatMessages(std::int32_t limit, std::int64_t userId) const; + std::vector> + getUserPersonalChatMessages(const GetUserPersonalChatMessagesArgs& args) const; /** * @brief Use this method to get a list of profile audios for a user. Returns a UserProfileAudios @@ -1633,10 +2640,20 @@ * @param offset Sequential number of the first audio to be returned. By default, all * audios are returned. * - * @return Telegram Bot API result. + * @return The resulting UserProfileAudios object. + */ + std::shared_ptr + getUserProfileAudios(std::int64_t userId, std::int32_t limit = 0, std::int32_t offset = 0) const; + + /** + * @brief Use this method to get a list of profile audios for a user. Returns a UserProfileAudios + * object. + * + * @param args Method arguments. + * + * @return The resulting UserProfileAudios object. */ - std::shared_ptr getUserProfileAudios(std::int64_t userId, std::int32_t limit = 0, - std::int32_t offset = 0) const; + std::shared_ptr getUserProfileAudios(const GetUserProfileAudiosArgs& args) const; /** * @brief Use this method to get a list of profile pictures for a user. Returns a @@ -1648,10 +2665,20 @@ * @param limit Limits the number of photos to be retrieved. Values between 1-100 are * accepted. Defaults to 100. * - * @return Telegram Bot API result. + * @return The resulting UserProfilePhotos object. + */ + std::shared_ptr + getUserProfilePhotos(std::int64_t userId, std::int32_t offset = 0, std::int32_t limit = 100) const; + + /** + * @brief Use this method to get a list of profile pictures for a user. Returns a + * UserProfilePhotos object. + * + * @param args Method arguments. + * + * @return The resulting UserProfilePhotos object. */ - std::shared_ptr getUserProfilePhotos(std::int64_t userId, std::int32_t offset = 0, - std::int32_t limit = 100) const; + std::shared_ptr getUserProfilePhotos(const GetUserProfilePhotosArgs& args) const; /** * @brief Use this method to get current webhook status. Requires no parameters. On success, @@ -1659,7 +2686,7 @@ * the url field empty. * * - * @return Telegram Bot API result. + * @return The resulting WebhookInfo object. */ std::shared_ptr getWebhookInfo() const; @@ -1682,13 +2709,24 @@ * details. Entities other than “bold”, “italic”, “underline”, * “strikethrough”, “spoiler”, “custom_emoji”, and “date_time” are ignored. * - * @return Telegram Bot API result. + * @return True on success. */ - bool giftPremiumSubscription(std::int32_t monthCount, std::int32_t starCount, std::int64_t userId, + bool giftPremiumSubscription(std::int32_t monthCount, + std::int32_t starCount, + std::int64_t userId, const std::string& text = "", const std::vector>& textEntities = { }, const std::string& textParseMode = "") const; + /** + * @brief Gifts a Telegram Premium subscription to the given user. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool giftPremiumSubscription(const GiftPremiumSubscriptionArgs& args) const; + /** * @brief Use this method to hide the 'General' topic in a forum supergroup chat. The bot must be * an administrator in the chat for this to work and must have the can_manage_topics @@ -1698,10 +2736,22 @@ * @param chatId Unique identifier for the target chat or username of the target * supergroup in the format @username * - * @return Telegram Bot API result. + * @return True on success. */ bool hideGeneralForumTopic(std::variant chatId) const; + /** + * @brief Use this method to hide the 'General' topic in a forum supergroup chat. The bot must be + * an administrator in the chat for this to work and must have the can_manage_topics + * administrator rights. The topic will be automatically closed if it was open. Returns + * True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool hideGeneralForumTopic(const HideGeneralForumTopicArgs& args) const; + /** * @brief Use this method for your bot to leave a group, supergroup or channel. Returns True on * success. @@ -1710,10 +2760,20 @@ * supergroup or channel in the format @username. Channel direct messages * chats aren't supported; leave the corresponding channel instead. * - * @return Telegram Bot API result. + * @return True on success. */ bool leaveChat(std::variant chatId) const; + /** + * @brief Use this method for your bot to leave a group, supergroup or channel. Returns True on + * success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool leaveChat(const LeaveChatArgs& args) const; + /** * @brief Use this method to log out from the cloud Bot API server before launching the bot * locally. You must log out the bot before running it locally, otherwise there is no @@ -1722,7 +2782,7 @@ * Bot API server for 10 minutes. Returns True on success. Requires no parameters. * * - * @return Telegram Bot API result. + * @return True on success. */ bool logOut() const; @@ -1742,10 +2802,25 @@ * members about the new pinned message. Notifications are always disabled * in channels and private chats. * - * @return Telegram Bot API result. + * @return True on success. + */ + bool pinChatMessage(std::variant chatId, + std::int32_t messageId, + const std::string& businessConnectionId = "", + bool disableNotification = false) const; + + /** + * @brief Use this method to add a message to the list of pinned messages in a chat. In private + * chats and channel direct messages chats, all non-service messages can be pinned. + * Conversely, the bot must be an administrator with the 'can_pin_messages' right or the + * 'can_edit_messages' right to pin messages in groups and channels respectively. Returns + * True on success. + * + * @param args Method arguments. + * + * @return True on success. */ - bool pinChatMessage(std::variant chatId, std::int32_t messageId, - const std::string& businessConnectionId = "", bool disableNotification = false) const; + bool pinChatMessage(const PinChatMessageArgs& args) const; /** * @brief Posts a story on behalf of a managed business account. Requires the can_manage_stories @@ -1765,13 +2840,27 @@ * @param protectContent Pass True if the content of the story must be protected from forwarding * and screenshotting * - * @return Telegram Bot API result. + * @return The resulting Story object. + */ + std::shared_ptr postStory(std::int32_t activePeriod, + const std::string& businessConnectionId, + std::shared_ptr content, + const std::vector>& areas = { }, + const std::string& caption = "", + const std::vector>& captionEntities = { }, + const std::string& parseMode = "", + bool postToChatPage = false, + bool protectContent = false) const; + + /** + * @brief Posts a story on behalf of a managed business account. Requires the can_manage_stories + * business bot right. Returns Story on success. + * + * @param args Method arguments. + * + * @return The resulting Story object. */ - std::shared_ptr - postStory(std::int32_t activePeriod, const std::string& businessConnectionId, - std::shared_ptr content, const std::vector>& areas = { }, - const std::string& caption = "", const std::vector>& captionEntities = { }, - const std::string& parseMode = "", bool postToChatPage = false, bool protectContent = false) const; + std::shared_ptr postStory(const PostStoryArgs& args) const; /** * @brief Use this method to promote or demote a user in a supergroup or a channel. The bot must @@ -1816,17 +2905,40 @@ * @param canManageTags Pass True if the administrator can edit the tags of regular members; for * groups and supergroups only * - * @return Telegram Bot API result. - */ - bool promoteChatMember(std::variant chatId, std::int64_t userId, - bool canChangeInfo = false, bool canPostMessages = false, bool canEditMessages = false, - bool canDeleteMessages = false, bool canInviteUsers = false, bool canPinMessages = false, - bool canPromoteMembers = false, bool isAnonymous = false, bool canManageChat = false, - bool canManageVideoChats = false, bool canRestrictMembers = false, - bool canManageTopics = false, bool canPostStories = false, bool canEditStories = false, - bool canDeleteStories = false, bool canManageDirectMessages = false, + * @return True on success. + */ + bool promoteChatMember(std::variant chatId, + std::int64_t userId, + bool canChangeInfo = false, + bool canPostMessages = false, + bool canEditMessages = false, + bool canDeleteMessages = false, + bool canInviteUsers = false, + bool canPinMessages = false, + bool canPromoteMembers = false, + bool isAnonymous = false, + bool canManageChat = false, + bool canManageVideoChats = false, + bool canRestrictMembers = false, + bool canManageTopics = false, + bool canPostStories = false, + bool canEditStories = false, + bool canDeleteStories = false, + bool canManageDirectMessages = false, bool canManageTags = false) const; + /** + * @brief Use this method to promote or demote a user in a supergroup or a channel. The bot must + * be an administrator in the chat for this to work and must have the appropriate + * administrator rights. Pass False for all boolean parameters to demote a user. Returns + * True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool promoteChatMember(const PromoteChatMemberArgs& args) const; + /** * @brief Marks incoming message as read on behalf of a business account. Requires the * can_read_messages business bot right. Returns True on success. @@ -1837,21 +2949,41 @@ * the message * @param messageId Unique identifier of the message to mark as read * - * @return Telegram Bot API result. + * @return True on success. */ - bool readBusinessMessage(std::variant chatId, const std::string& businessConnectionId, + bool readBusinessMessage(std::variant chatId, + const std::string& businessConnectionId, std::int32_t messageId) const; + /** + * @brief Marks incoming message as read on behalf of a business account. Requires the + * can_read_messages business bot right. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool readBusinessMessage(const ReadBusinessMessageArgs& args) const; + /** * @brief Refunds a successful payment in Telegram Stars. Returns True on success. * * @param telegramPaymentChargeId Telegram payment identifier * @param userId Identifier of the user whose payment will be refunded * - * @return Telegram Bot API result. + * @return True on success. */ bool refundStarPayment(const std::string& telegramPaymentChargeId, std::int64_t userId) const; + /** + * @brief Refunds a successful payment in Telegram Stars. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool refundStarPayment(const RefundStarPaymentArgs& args) const; + /** * @brief Removes the current profile photo of a managed business account. Requires the * can_edit_profile_photo business bot right. Returns True on success. @@ -1862,26 +2994,46 @@ * main photo is removed, the previous profile photo (if present) becomes * the main photo. * - * @return Telegram Bot API result. + * @return True on success. */ bool removeBusinessAccountProfilePhoto(const std::string& businessConnectionId, bool isPublic = false) const; /** - * @brief Removes verification from a chat that is currently verified on behalf of the - * organization represented by the bot. Returns True on success. + * @brief Removes the current profile photo of a managed business account. Requires the + * can_edit_profile_photo business bot right. Returns True on success. * - * @param chatId Unique identifier for the target chat or username of the target bot or + * @param args Method arguments. + * + * @return True on success. + */ + bool removeBusinessAccountProfilePhoto(const RemoveBusinessAccountProfilePhotoArgs& args) const; + + /** + * @brief Removes verification from a chat that is currently verified on behalf of the + * organization represented by the bot. Returns True on success. + * + * @param chatId Unique identifier for the target chat or username of the target bot or * channel in the format @username * - * @return Telegram Bot API result. + * @return True on success. */ bool removeChatVerification(std::variant chatId) const; + /** + * @brief Removes verification from a chat that is currently verified on behalf of the + * organization represented by the bot. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool removeChatVerification(const RemoveChatVerificationArgs& args) const; + /** * @brief Removes the profile photo of the bot. Requires no parameters. Returns True on success. * * - * @return Telegram Bot API result. + * @return True on success. */ bool removeMyProfilePhoto() const; @@ -1891,10 +3043,20 @@ * * @param userId Unique identifier of the target user * - * @return Telegram Bot API result. + * @return True on success. */ bool removeUserVerification(std::int64_t userId) const; + /** + * @brief Removes verification from a user who is currently verified on behalf of the organization + * represented by the bot. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool removeUserVerification(const RemoveUserVerificationArgs& args) const; + /** * @brief Use this method to reopen a closed topic in a forum supergroup chat. The bot must be an * administrator in the chat for this to work and must have the can_manage_topics @@ -1904,10 +3066,21 @@ * supergroup in the format @username * @param messageThreadId Unique identifier for the target message thread of the forum topic * - * @return Telegram Bot API result. + * @return True on success. */ bool reopenForumTopic(std::variant chatId, std::int32_t messageThreadId) const; + /** + * @brief Use this method to reopen a closed topic in a forum supergroup chat. The bot must be an + * administrator in the chat for this to work and must have the can_manage_topics + * administrator rights, unless it is the creator of the topic. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool reopenForumTopic(const ReopenForumTopicArgs& args) const; + /** * @brief Use this method to reopen a closed 'General' topic in a forum supergroup chat. The bot * must be an administrator in the chat for this to work and must have the @@ -1917,20 +3090,42 @@ * @param chatId Unique identifier for the target chat or username of the target * supergroup in the format @username * - * @return Telegram Bot API result. + * @return True on success. */ bool reopenGeneralForumTopic(std::variant chatId) const; + /** + * @brief Use this method to reopen a closed 'General' topic in a forum supergroup chat. The bot + * must be an administrator in the chat for this to work and must have the + * can_manage_topics administrator rights. The topic will be automatically unhidden if it + * was hidden. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool reopenGeneralForumTopic(const ReopenGeneralForumTopicArgs& args) const; + /** * @brief Use this method to revoke the current token of a managed bot and generate a new one. * Returns the new token as String on success. * * @param userId User identifier of the managed bot whose token will be replaced * - * @return Telegram Bot API result. + * @return The resulting string. */ std::string replaceManagedBotToken(std::int64_t userId) const; + /** + * @brief Use this method to revoke the current token of a managed bot and generate a new one. + * Returns the new token as String on success. + * + * @param args Method arguments. + * + * @return The resulting string. + */ + std::string replaceManagedBotToken(const ReplaceManagedBotTokenArgs& args) const; + /** * @brief Use this method to replace an existing sticker in a sticker set with a new one. The * method is equivalent to calling deleteStickerFromSet, then addStickerToSet, then @@ -1943,11 +3138,24 @@ * exactly the same sticker had already been added to the set, then the set * remains unchanged. * - * @return Telegram Bot API result. + * @return True on success. */ - bool replaceStickerInSet(std::int64_t userId, const std::string& name, const std::string& oldSticker, + bool replaceStickerInSet(std::int64_t userId, + const std::string& name, + const std::string& oldSticker, std::shared_ptr sticker) const; + /** + * @brief Use this method to replace an existing sticker in a sticker set with a new one. The + * method is equivalent to calling deleteStickerFromSet, then addStickerToSet, then + * setStickerPositionInSet. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool replaceStickerInSet(const ReplaceStickerInSetArgs& args) const; + /** * @brief Reposts a story on behalf of a business account from another business account. Both * business accounts must be managed by the same bot, and the story on the source account @@ -1964,11 +3172,26 @@ * @param protectContent Pass True if the content of the story must be protected from forwarding * and screenshotting * - * @return Telegram Bot API result. + * @return The resulting Story object. + */ + std::shared_ptr repostStory(std::int32_t activePeriod, + const std::string& businessConnectionId, + std::variant fromChatId, + std::int32_t fromStoryId, + bool postToChatPage = false, + bool protectContent = false) const; + + /** + * @brief Reposts a story on behalf of a business account from another business account. Both + * business accounts must be managed by the same bot, and the story on the source account + * must have been posted (or reposted) by the bot. Requires the can_manage_stories business + * bot right for both business accounts. Returns Story on success. + * + * @param args Method arguments. + * + * @return The resulting Story object. */ - std::shared_ptr repostStory(std::int32_t activePeriod, const std::string& businessConnectionId, - std::variant fromChatId, std::int32_t fromStoryId, - bool postToChatPage = false, bool protectContent = false) const; + std::shared_ptr repostStory(const RepostStoryArgs& args) const; /** * @brief Use this method to restrict a user in a supergroup. The bot must be an administrator in @@ -1989,12 +3212,25 @@ * can_send_voice_notes permissions; the can_send_polls permission will * imply the can_send_messages permission. * - * @return Telegram Bot API result. + * @return True on success. */ - bool restrictChatMember(std::variant chatId, std::int64_t userId, - std::shared_ptr permissions, std::int32_t untilDate = 0, + bool restrictChatMember(std::variant chatId, + std::int64_t userId, + std::shared_ptr permissions, + std::int32_t untilDate = 0, bool useIndependentChatPermissions = false) const; + /** + * @brief Use this method to restrict a user in a supergroup. The bot must be an administrator in + * the supergroup for this to work and must have the appropriate administrator rights. Pass + * True for all permissions to lift restrictions from a user. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool restrictChatMember(const RestrictChatMemberArgs& args) const; + /** * @brief Use this method to revoke an invite link created by the bot. If the primary link is * revoked, a new link is automatically generated. The bot must be an administrator in the @@ -2005,11 +3241,23 @@ * in the format @username * @param inviteLink The invite link to revoke * - * @return Telegram Bot API result. + * @return The resulting ChatInviteLink object. */ std::shared_ptr revokeChatInviteLink(std::variant chatId, const std::string& inviteLink) const; + /** + * @brief Use this method to revoke an invite link created by the bot. If the primary link is + * revoked, a new link is automatically generated. The bot must be an administrator in the + * chat for this to work and must have the appropriate administrator rights. Returns the + * revoked invite link as ChatInviteLink object. + * + * @param args Method arguments. + * + * @return The resulting ChatInviteLink object. + */ + std::shared_ptr revokeChatInviteLink(const RevokeChatInviteLinkArgs& args) const; + /** * @brief Stores a message that can be sent by a user of a Mini App. Returns a * PreparedInlineMessage object. @@ -2021,14 +3269,26 @@ * @param allowGroupChats Pass True if the message can be sent to group and supergroup chats * @param allowUserChats Pass True if the message can be sent to private chats with users * - * @return Telegram Bot API result. + * @return The resulting PreparedInlineMessage object. */ std::shared_ptr savePreparedInlineMessage(std::shared_ptr result, - std::int64_t userId, bool allowBotChats = false, + std::int64_t userId, + bool allowBotChats = false, bool allowChannelChats = false, bool allowGroupChats = false, bool allowUserChats = false) const; + /** + * @brief Stores a message that can be sent by a user of a Mini App. Returns a + * PreparedInlineMessage object. + * + * @param args Method arguments. + * + * @return The resulting PreparedInlineMessage object. + */ + std::shared_ptr + savePreparedInlineMessage(const SavePreparedInlineMessageArgs& args) const; + /** * @brief Stores a keyboard button that can be used by a user within a Mini App. Returns a * PreparedKeyboardButton object. @@ -2037,11 +3297,22 @@ * must be of the type request_users, request_chat, or request_managed_bot. * @param userId Unique identifier of the target user that can use the button * - * @return Telegram Bot API result. + * @return The resulting PreparedKeyboardButton object. */ std::shared_ptr savePreparedKeyboardButton(std::shared_ptr button, std::int64_t userId) const; + /** + * @brief Stores a keyboard button that can be used by a user within a Mini App. Returns a + * PreparedKeyboardButton object. + * + * @param args Method arguments. + * + * @return The resulting PreparedKeyboardButton object. + */ + std::shared_ptr + savePreparedKeyboardButton(const SavePreparedKeyboardButtonArgs& args) const; + /** * @brief Use this method to send animation files (GIF or H.264/MPEG-4 AVC video without sound). * On success, the sent Message is returned. Bots can currently send animation files of up @@ -2103,23 +3374,46 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. - */ - std::shared_ptr sendAnimation( - std::variant chatId, std::variant, std::string> animation, - std::int32_t duration = 0, std::int32_t width = 0, std::int32_t height = 0, - std::variant, std::string> thumbnail = { }, const std::string& caption = "", - std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - const std::string& parseMode = "", bool disableNotification = false, - const std::vector>& captionEntities = { }, std::int32_t messageThreadId = 0, - bool protectContent = false, bool hasSpoiler = false, const std::string& businessConnectionId = "", - bool allowPaidBroadcast = false, const std::string& callbackQueryId = "", - std::int64_t directMessagesTopicId = 0, const std::string& messageEffectId = "", - std::int64_t receiverUserId = 0, bool showCaptionAboveMedia = false, - std::shared_ptr suggestedPostParameters = nullptr) const; + * @return The resulting Message object. + */ + std::shared_ptr sendAnimation(std::variant chatId, + std::variant, std::string> animation, + std::int32_t duration = 0, + std::int32_t width = 0, + std::int32_t height = 0, + std::variant, std::string> thumbnail = { }, + const std::string& caption = "", + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + const std::string& parseMode = "", + bool disableNotification = false, + const std::vector>& captionEntities = { }, + std::int32_t messageThreadId = 0, + bool protectContent = false, + bool hasSpoiler = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& callbackQueryId = "", + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::int64_t receiverUserId = 0, + bool showCaptionAboveMedia = false, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send animation files (GIF or H.264/MPEG-4 AVC video without sound). + * On success, the sent Message is returned. Bots can currently send animation files of up + * to 50 MB in size, this limit may be changed in the future. + * + * @param args Method arguments. + * + * @return The resulting Message object. + */ + std::shared_ptr sendAnimation(const SendAnimationArgs& args) const; /** * @brief Use this method to send audio files, if you want Telegram clients to display them in the @@ -2180,22 +3474,46 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendAudio(std::variant chatId, + std::variant, std::string> audio, + const std::string& caption = "", + std::int32_t duration = 0, + const std::string& performer = "", + const std::string& title = "", + std::variant, std::string> thumbnail = { }, + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + const std::string& parseMode = "", + bool disableNotification = false, + const std::vector>& captionEntities = { }, + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& callbackQueryId = "", + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::int64_t receiverUserId = 0, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send audio files, if you want Telegram clients to display them in the + * music player. Your audio must be in the .MP3 or .M4A format. On success, the sent + * Message is returned. Bots can currently send audio files of up to 50 MB in size, this + * limit may be changed in the future. For sending voice messages, use the sendVoice method + * instead. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr sendAudio( - std::variant chatId, std::variant, std::string> audio, - const std::string& caption = "", std::int32_t duration = 0, const std::string& performer = "", - const std::string& title = "", std::variant, std::string> thumbnail = { }, - std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - const std::string& parseMode = "", bool disableNotification = false, - const std::vector>& captionEntities = { }, std::int32_t messageThreadId = 0, - bool protectContent = false, const std::string& businessConnectionId = "", bool allowPaidBroadcast = false, - const std::string& callbackQueryId = "", std::int64_t directMessagesTopicId = 0, - const std::string& messageEffectId = "", std::int64_t receiverUserId = 0, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendAudio(const SendAudioArgs& args) const; /** * @brief Use this method when you need to tell the user that something is happening on the bot's @@ -2218,10 +3536,25 @@ * @param businessConnectionId Unique identifier of the business connection on behalf of which the * action will be sent * - * @return Telegram Bot API result. + * @return True on success. */ - bool sendChatAction(std::variant chatId, const std::string& action, - std::int32_t messageThreadId = 0, const std::string& businessConnectionId = "") const; + bool sendChatAction(std::variant chatId, + const std::string& action, + std::int32_t messageThreadId = 0, + const std::string& businessConnectionId = "") const; + + /** + * @brief Use this method when you need to tell the user that something is happening on the bot's + * side. The status is set for 5 seconds or less (when a message arrives from your bot, + * Telegram clients clear its typing status). Returns True on success. We only recommend + * using this method when a response from the bot will take a noticeable amount of time to + * arrive. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool sendChatAction(const SendChatActionArgs& args) const; /** * @brief Use this method to process a received chat join request query by showing a Mini App to @@ -2233,10 +3566,22 @@ * @param webAppUrl An HTTPS URL of a Web App to be opened with additional data as specified * in Initializing Web Apps * - * @return Telegram Bot API result. + * @return True on success. */ bool sendChatJoinRequestWebApp(const std::string& chatJoinRequestQueryId, const std::string& webAppUrl) const; + /** + * @brief Use this method to process a received chat join request query by showing a Mini App to + * the user before deciding the outcome. Call answerChatJoinRequestQuery to resolve the + * join request query based on the user interaction with the Mini App. Returns True on + * success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool sendChatJoinRequestWebApp(const SendChatJoinRequestWebAppArgs& args) const; + /** * @brief Use this method to send a checklist on behalf of a connected business account. On * success, the sent Message is returned. @@ -2253,15 +3598,27 @@ * @param replyMarkup A JSON-serialized object for an inline keyboard * @param replyParameters A JSON-serialized object for description of the message to reply to * - * @return Telegram Bot API result. + * @return The resulting Message object. */ std::shared_ptr sendChecklist(std::variant chatId, const std::string& businessConnectionId, - std::shared_ptr checklist, bool disableNotification = false, - const std::string& messageEffectId = "", bool protectContent = false, + std::shared_ptr checklist, + bool disableNotification = false, + const std::string& messageEffectId = "", + bool protectContent = false, std::shared_ptr replyMarkup = nullptr, std::shared_ptr replyParameters = nullptr) const; + /** + * @brief Use this method to send a checklist on behalf of a connected business account. On + * success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. + */ + std::shared_ptr sendChecklist(const SendChecklistArgs& args) const; + /** * @brief Use this method to send phone contacts. On success, the sent Message is returned. * @@ -2301,20 +3658,38 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendContact(std::variant chatId, + const std::string& phoneNumber, + const std::string& firstName, + const std::string& lastName = "", + const std::string& vcard = "", + bool disableNotification = false, + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& callbackQueryId = "", + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::int64_t receiverUserId = 0, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send phone contacts. On success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr - sendContact(std::variant chatId, const std::string& phoneNumber, - const std::string& firstName, const std::string& lastName = "", const std::string& vcard = "", - bool disableNotification = false, std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - std::int32_t messageThreadId = 0, bool protectContent = false, - const std::string& businessConnectionId = "", bool allowPaidBroadcast = false, - const std::string& callbackQueryId = "", std::int64_t directMessagesTopicId = 0, - const std::string& messageEffectId = "", std::int64_t receiverUserId = 0, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendContact(const SendContactArgs& args) const; /** * @brief Use this method to send an animated emoji that will display a random value. On success, @@ -2349,18 +3724,34 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendDice(std::variant chatId, + bool disableNotification = false, + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + const std::string& emoji = "", + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send an animated emoji that will display a random value. On success, + * the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr - sendDice(std::variant chatId, bool disableNotification = false, - std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - const std::string& emoji = "", std::int32_t messageThreadId = 0, bool protectContent = false, - const std::string& businessConnectionId = "", bool allowPaidBroadcast = false, - std::int64_t directMessagesTopicId = 0, const std::string& messageEffectId = "", - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendDice(const SendDiceArgs& args) const; /** * @brief Use this method to send general files. On success, the sent Message is returned. Bots @@ -2419,22 +3810,42 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendDocument(std::variant chatId, + std::variant, std::string> document, + std::variant, std::string> thumbnail = { }, + const std::string& caption = "", + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + const std::string& parseMode = "", + bool disableNotification = false, + const std::vector>& captionEntities = { }, + bool disableContentTypeDetection = false, + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& callbackQueryId = "", + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::int64_t receiverUserId = 0, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send general files. On success, the sent Message is returned. Bots + * can currently send files of any type of up to 50 MB in size, this limit may be changed + * in the future. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr sendDocument( - std::variant chatId, std::variant, std::string> document, - std::variant, std::string> thumbnail = { }, const std::string& caption = "", - std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - const std::string& parseMode = "", bool disableNotification = false, - const std::vector>& captionEntities = { }, - bool disableContentTypeDetection = false, std::int32_t messageThreadId = 0, bool protectContent = false, - const std::string& businessConnectionId = "", bool allowPaidBroadcast = false, - const std::string& callbackQueryId = "", std::int64_t directMessagesTopicId = 0, - const std::string& messageEffectId = "", std::int64_t receiverUserId = 0, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendDocument(const SendDocumentArgs& args) const; /** * @brief Use this method to send a game. On success, the sent Message is returned. @@ -2462,14 +3873,27 @@ * @param messageEffectId Unique identifier of the message effect to be added to the message; for * private chats only * - * @return Telegram Bot API result. + * @return The resulting Message object. */ - std::shared_ptr sendGame(std::variant chatId, const std::string& gameShortName, + std::shared_ptr sendGame(std::variant chatId, + const std::string& gameShortName, std::shared_ptr replyParameters = nullptr, std::shared_ptr replyMarkup = nullptr, - bool disableNotification = false, std::int32_t messageThreadId = 0, - bool protectContent = false, const std::string& businessConnectionId = "", - bool allowPaidBroadcast = false, const std::string& messageEffectId = "") const; + bool disableNotification = false, + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& messageEffectId = "") const; + + /** + * @brief Use this method to send a game. On success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. + */ + std::shared_ptr sendGame(const SendGameArgs& args) const; /** * @brief Sends a gift to the given user or channel chat. The gift can't be converted to Telegram @@ -2492,12 +3916,25 @@ * @param userId Required if chat_id is not specified. Unique identifier of the target * user who will receive the gift. * - * @return Telegram Bot API result. + * @return True on success. */ - bool sendGift(const std::string& giftId, std::variant chatId = { }, - bool payForUpgrade = false, const std::string& text = "", + bool sendGift(const std::string& giftId, + std::variant chatId = { }, + bool payForUpgrade = false, + const std::string& text = "", const std::vector>& textEntities = { }, - const std::string& textParseMode = "", std::int64_t userId = 0) const; + const std::string& textParseMode = "", + std::int64_t userId = 0) const; + + /** + * @brief Sends a gift to the given user or channel chat. The gift can't be converted to Telegram + * Stars by the receiver. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool sendGift(const SendGiftArgs& args) const; /** * @brief Use this method to send invoices. On success, the sent Message is returned. @@ -2577,23 +4014,49 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. - */ - std::shared_ptr - sendInvoice(std::variant chatId, const std::string& title, - const std::string& description, const std::string& payload, const std::string& providerToken, - const std::string& currency, const std::vector>& prices, - const std::string& providerData = "", const std::string& photoUrl = "", std::int32_t photoSize = 0, - std::int32_t photoWidth = 0, std::int32_t photoHeight = 0, bool needName = false, - bool needPhoneNumber = false, bool needEmail = false, bool needShippingAddress = false, - bool sendPhoneNumberToProvider = false, bool sendEmailToProvider = false, bool isFlexible = false, - std::shared_ptr replyParameters = nullptr, - std::shared_ptr replyMarkup = nullptr, bool disableNotification = false, - std::int32_t messageThreadId = 0, std::int32_t maxTipAmount = 0, - const std::vector& suggestedTipAmounts = { }, const std::string& startParameter = "", - bool protectContent = false, bool allowPaidBroadcast = false, std::int64_t directMessagesTopicId = 0, - const std::string& messageEffectId = "", - std::shared_ptr suggestedPostParameters = nullptr) const; + * @return The resulting Message object. + */ + std::shared_ptr sendInvoice(std::variant chatId, + const std::string& title, + const std::string& description, + const std::string& payload, + const std::string& providerToken, + const std::string& currency, + const std::vector>& prices, + const std::string& providerData = "", + const std::string& photoUrl = "", + std::int32_t photoSize = 0, + std::int32_t photoWidth = 0, + std::int32_t photoHeight = 0, + bool needName = false, + bool needPhoneNumber = false, + bool needEmail = false, + bool needShippingAddress = false, + bool sendPhoneNumberToProvider = false, + bool sendEmailToProvider = false, + bool isFlexible = false, + std::shared_ptr replyParameters = nullptr, + std::shared_ptr replyMarkup = nullptr, + bool disableNotification = false, + std::int32_t messageThreadId = 0, + std::int32_t maxTipAmount = 0, + const std::vector& suggestedTipAmounts = { }, + const std::string& startParameter = "", + bool protectContent = false, + bool allowPaidBroadcast = false, + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send invoices. On success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. + */ + std::shared_ptr sendInvoice(const SendInvoiceArgs& args) const; /** * @brief Use this method to send live photos. On success, the sent Message is returned. @@ -2647,21 +4110,41 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendLivePhoto(std::variant chatId, + std::variant, std::string> livePhoto, + std::variant, std::string> photo, + bool allowPaidBroadcast = false, + const std::string& businessConnectionId = "", + const std::string& callbackQueryId = "", + const std::string& caption = "", + const std::vector>& captionEntities = { }, + std::int64_t directMessagesTopicId = 0, + bool disableNotification = false, + bool hasSpoiler = false, + const std::string& messageEffectId = "", + std::int32_t messageThreadId = 0, + const std::string& parseMode = "", + bool protectContent = false, + std::int64_t receiverUserId = 0, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + std::shared_ptr replyParameters = nullptr, + bool showCaptionAboveMedia = false, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send live photos. On success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr sendLivePhoto( - std::variant chatId, std::variant, std::string> livePhoto, - std::variant, std::string> photo, bool allowPaidBroadcast = false, - const std::string& businessConnectionId = "", const std::string& callbackQueryId = "", - const std::string& caption = "", const std::vector>& captionEntities = { }, - std::int64_t directMessagesTopicId = 0, bool disableNotification = false, bool hasSpoiler = false, - const std::string& messageEffectId = "", std::int32_t messageThreadId = 0, const std::string& parseMode = "", - bool protectContent = false, std::int64_t receiverUserId = 0, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - std::shared_ptr replyParameters = nullptr, bool showCaptionAboveMedia = false, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendLivePhoto(const SendLivePhotoArgs& args) const; /** * @brief Use this method to send point on the map. On success, the sent Message is returned. @@ -2710,20 +4193,40 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendLocation(std::variant chatId, + double latitude, + double longitude, + std::int32_t livePeriod = 0, + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + bool disableNotification = false, + double horizontalAccuracy = 0, + std::int32_t heading = 0, + std::int32_t proximityAlertRadius = 0, + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& callbackQueryId = "", + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::int64_t receiverUserId = 0, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send point on the map. On success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr - sendLocation(std::variant chatId, double latitude, double longitude, - std::int32_t livePeriod = 0, std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - bool disableNotification = false, double horizontalAccuracy = 0, std::int32_t heading = 0, - std::int32_t proximityAlertRadius = 0, std::int32_t messageThreadId = 0, bool protectContent = false, - const std::string& businessConnectionId = "", bool allowPaidBroadcast = false, - const std::string& callbackQueryId = "", std::int64_t directMessagesTopicId = 0, - const std::string& messageEffectId = "", std::int64_t receiverUserId = 0, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendLocation(const SendLocationArgs& args) const; /** * @brief Use this method to send a group of photos, live photos, videos, documents or audios as @@ -2751,17 +4254,34 @@ * @param messageEffectId Unique identifier of the message effect to be added to the message; for * private chats only * - * @return Telegram Bot API result. + * @return The resulting list of Message objects. + */ + std::vector> + sendMediaGroup(std::variant chatId, + const std::vector, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr>>& media, + bool disableNotification = false, + std::shared_ptr replyParameters = nullptr, + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "") const; + + /** + * @brief Use this method to send a group of photos, live photos, videos, documents or audios as + * an album. Documents and audio files can be only grouped in an album with messages of the + * same type. On success, an Array of Message objects that were sent is returned. + * + * @param args Method arguments. + * + * @return The resulting list of Message objects. */ - std::vector> sendMediaGroup( - std::variant chatId, - const std::vector, std::shared_ptr, - std::shared_ptr, std::shared_ptr, - std::shared_ptr>>& media, - bool disableNotification = false, std::shared_ptr replyParameters = nullptr, - std::int32_t messageThreadId = 0, bool protectContent = false, const std::string& businessConnectionId = "", - bool allowPaidBroadcast = false, std::int64_t directMessagesTopicId = 0, - const std::string& messageEffectId = "") const; + std::vector> sendMediaGroup(const SendMediaGroupArgs& args) const; /** * @brief Use this method to send text messages. On success, the sent Message is returned. @@ -2804,22 +4324,38 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendMessage(std::variant chatId, + const std::string& text, + std::shared_ptr linkPreviewOptions = nullptr, + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + const std::string& parseMode = "", + bool disableNotification = false, + const std::vector>& entities = { }, + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& callbackQueryId = "", + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::int64_t receiverUserId = 0, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send text messages. On success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr - sendMessage(std::variant chatId, const std::string& text, - std::shared_ptr linkPreviewOptions = nullptr, - std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - const std::string& parseMode = "", bool disableNotification = false, - const std::vector>& entities = { }, std::int32_t messageThreadId = 0, - bool protectContent = false, const std::string& businessConnectionId = "", - bool allowPaidBroadcast = false, const std::string& callbackQueryId = "", - std::int64_t directMessagesTopicId = 0, const std::string& messageEffectId = "", - std::int64_t receiverUserId = 0, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendMessage(const SendMessageArgs& args) const; /** * @brief Use this method to stream a partial message to a user while the message is being @@ -2838,13 +4374,27 @@ * @param text Text of the message to be sent, 0-4096 characters after entities * parsing. Pass an empty text to show a “Thinking…” placeholder. * - * @return Telegram Bot API result. + * @return True on success. */ - bool sendMessageDraft(std::variant chatId, std::int32_t draftId, + bool sendMessageDraft(std::variant chatId, + std::int32_t draftId, const std::vector>& entities = { }, - std::int32_t messageThreadId = 0, const std::string& parseMode = "", + std::int32_t messageThreadId = 0, + const std::string& parseMode = "", const std::string& text = "") const; + /** + * @brief Use this method to stream a partial message to a user while the message is being + * generated. Note that the streamed draft is ephemeral and acts as a temporary 30-second + * preview - once the output is finalized, you must call sendMessage with the complete + * message to persist it in the user's chat. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool sendMessageDraft(const SendMessageDraftArgs& args) const; + /** * @brief Use this method to send paid media. On success, the sent Message is returned. * @@ -2885,19 +4435,38 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendPaidMedia(std::variant chatId, + const std::vector>& media, + std::int32_t starCount, + bool allowPaidBroadcast = false, + const std::string& businessConnectionId = "", + const std::string& caption = "", + const std::vector>& captionEntities = { }, + std::int64_t directMessagesTopicId = 0, + bool disableNotification = false, + std::int32_t messageThreadId = 0, + const std::string& parseMode = "", + const std::string& payload = "", + bool protectContent = false, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + std::shared_ptr replyParameters = nullptr, + bool showCaptionAboveMedia = false, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send paid media. On success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr sendPaidMedia( - std::variant chatId, const std::vector>& media, - std::int32_t starCount, bool allowPaidBroadcast = false, const std::string& businessConnectionId = "", - const std::string& caption = "", const std::vector>& captionEntities = { }, - std::int64_t directMessagesTopicId = 0, bool disableNotification = false, std::int32_t messageThreadId = 0, - const std::string& parseMode = "", const std::string& payload = "", bool protectContent = false, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - std::shared_ptr replyParameters = nullptr, bool showCaptionAboveMedia = false, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendPaidMedia(const SendPaidMediaArgs& args) const; /** * @brief Use this method to send photos. On success, the sent Message is returned. @@ -2948,21 +4517,40 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendPhoto(std::variant chatId, + std::variant, std::string> photo, + const std::string& caption = "", + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + const std::string& parseMode = "", + bool disableNotification = false, + const std::vector>& captionEntities = { }, + std::int32_t messageThreadId = 0, + bool protectContent = false, + bool hasSpoiler = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& callbackQueryId = "", + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::int64_t receiverUserId = 0, + bool showCaptionAboveMedia = false, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send photos. On success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr sendPhoto( - std::variant chatId, std::variant, std::string> photo, - const std::string& caption = "", std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - const std::string& parseMode = "", bool disableNotification = false, - const std::vector>& captionEntities = { }, std::int32_t messageThreadId = 0, - bool protectContent = false, bool hasSpoiler = false, const std::string& businessConnectionId = "", - bool allowPaidBroadcast = false, const std::string& callbackQueryId = "", - std::int64_t directMessagesTopicId = 0, const std::string& messageEffectId = "", - std::int64_t receiverUserId = 0, bool showCaptionAboveMedia = false, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendPhoto(const SendPhotoArgs& args) const; /** * @brief Use this method to send a native poll. On success, the sent Message is returned. @@ -3035,29 +4623,54 @@ * more details. Currently, only custom emoji entities are allowed. * @param shuffleOptions Pass True if the poll options must be shown in random order * - * @return Telegram Bot API result. - */ - std::shared_ptr - sendPoll(std::variant chatId, const std::string& question, - const std::vector>& options, bool disableNotification = false, - std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - bool isAnonymous = true, const std::string& type = "", bool allowsMultipleAnswers = false, - const std::string& explanation = "", const std::string& explanationParseMode = "", - const std::vector>& explanationEntities = { }, std::int32_t openPeriod = 0, - std::int32_t closeDate = 0, bool isClosed = false, std::int32_t messageThreadId = 0, - bool protectContent = false, const std::string& businessConnectionId = "", bool allowAddingOptions = false, - bool allowPaidBroadcast = false, bool allowsRevoting = false, - const std::vector& correctOptionIds = { }, - const std::vector& countryCodes = { }, const std::string& description = "", - const std::vector>& descriptionEntities = { }, - const std::string& descriptionParseMode = "", std::shared_ptr explanationMedia = nullptr, - bool hideResultsUntilCloses = false, std::shared_ptr media = nullptr, - bool membersOnly = false, const std::string& messageEffectId = "", - const std::vector>& questionEntities = { }, - const std::string& questionParseMode = "", bool shuffleOptions = false) const; + * @return The resulting Message object. + */ + std::shared_ptr sendPoll(std::variant chatId, + const std::string& question, + const std::vector>& options, + bool disableNotification = false, + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + bool isAnonymous = true, + const std::string& type = "", + bool allowsMultipleAnswers = false, + const std::string& explanation = "", + const std::string& explanationParseMode = "", + const std::vector>& explanationEntities = { }, + std::int32_t openPeriod = 0, + std::int32_t closeDate = 0, + bool isClosed = false, + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& businessConnectionId = "", + bool allowAddingOptions = false, + bool allowPaidBroadcast = false, + bool allowsRevoting = false, + const std::vector& correctOptionIds = { }, + const std::vector& countryCodes = { }, + const std::string& description = "", + const std::vector>& descriptionEntities = { }, + const std::string& descriptionParseMode = "", + std::shared_ptr explanationMedia = nullptr, + bool hideResultsUntilCloses = false, + std::shared_ptr media = nullptr, + bool membersOnly = false, + const std::string& messageEffectId = "", + const std::vector>& questionEntities = { }, + const std::string& questionParseMode = "", + bool shuffleOptions = false) const; + + /** + * @brief Use this method to send a native poll. On success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. + */ + std::shared_ptr sendPoll(const SendPollArgs& args) const; /** * @brief Use this method to send rich messages. If the message contains a block with a media @@ -3092,19 +4705,35 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendRichMessage(std::variant chatId, + std::shared_ptr richMessage, + bool allowPaidBroadcast = false, + const std::string& businessConnectionId = "", + std::int64_t directMessagesTopicId = 0, + bool disableNotification = false, + const std::string& messageEffectId = "", + std::int32_t messageThreadId = 0, + bool protectContent = false, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + std::shared_ptr replyParameters = nullptr, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send rich messages. If the message contains a block with a media + * element, then the bot must have the right to send the media to the chat. On success, the + * sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr - sendRichMessage(std::variant chatId, std::shared_ptr richMessage, - bool allowPaidBroadcast = false, const std::string& businessConnectionId = "", - std::int64_t directMessagesTopicId = 0, bool disableNotification = false, - const std::string& messageEffectId = "", std::int32_t messageThreadId = 0, - bool protectContent = false, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - std::shared_ptr replyParameters = nullptr, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendRichMessage(const SendRichMessageArgs& args) const; /** * @brief Use this method to stream a partial rich message to a user while the message is being @@ -3119,10 +4748,24 @@ * supported. * @param messageThreadId Unique identifier for the target message thread * - * @return Telegram Bot API result. + * @return True on success. + */ + bool sendRichMessageDraft(std::variant chatId, + std::int32_t draftId, + std::shared_ptr richMessage, + std::int32_t messageThreadId = 0) const; + + /** + * @brief Use this method to stream a partial rich message to a user while the message is being + * generated. Note that the streamed draft is ephemeral and acts as a temporary 30-second + * preview - once the output is finalized, you must call sendRichMessage with the complete + * message to persist it in the user's chat. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. */ - bool sendRichMessageDraft(std::variant chatId, std::int32_t draftId, - std::shared_ptr richMessage, std::int32_t messageThreadId = 0) const; + bool sendRichMessageDraft(const SendRichMessageDraftArgs& args) const; /** * @brief Use this method to send static .WEBP, animated .TGS, or video .WEBM stickers. On @@ -3167,19 +4810,37 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendSticker(std::variant chatId, + std::variant, std::string> sticker, + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + bool disableNotification = false, + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& emoji = "", + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& callbackQueryId = "", + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::int64_t receiverUserId = 0, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send static .WEBP, animated .TGS, or video .WEBM stickers. On + * success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr sendSticker( - std::variant chatId, std::variant, std::string> sticker, - std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - bool disableNotification = false, std::int32_t messageThreadId = 0, bool protectContent = false, - const std::string& emoji = "", const std::string& businessConnectionId = "", bool allowPaidBroadcast = false, - const std::string& callbackQueryId = "", std::int64_t directMessagesTopicId = 0, - const std::string& messageEffectId = "", std::int64_t receiverUserId = 0, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendSticker(const SendStickerArgs& args) const; /** * @brief Use this method to send information about a venue. On success, the sent Message is @@ -3227,22 +4888,43 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendVenue(std::variant chatId, + double latitude, + double longitude, + const std::string& title, + const std::string& address, + const std::string& foursquareId = "", + const std::string& foursquareType = "", + bool disableNotification = false, + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + const std::string& googlePlaceId = "", + const std::string& googlePlaceType = "", + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& callbackQueryId = "", + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::int64_t receiverUserId = 0, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send information about a venue. On success, the sent Message is + * returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr - sendVenue(std::variant chatId, double latitude, double longitude, - const std::string& title, const std::string& address, const std::string& foursquareId = "", - const std::string& foursquareType = "", bool disableNotification = false, - std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - const std::string& googlePlaceId = "", const std::string& googlePlaceType = "", - std::int32_t messageThreadId = 0, bool protectContent = false, - const std::string& businessConnectionId = "", bool allowPaidBroadcast = false, - const std::string& callbackQueryId = "", std::int64_t directMessagesTopicId = 0, - const std::string& messageEffectId = "", std::int64_t receiverUserId = 0, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendVenue(const SendVenueArgs& args) const; /** * @brief Use this method to send video files, Telegram clients support MPEG4 videos (other @@ -3312,24 +4994,50 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. - */ - std::shared_ptr sendVideo( - std::variant chatId, std::variant, std::string> video, - bool supportsStreaming = false, std::int32_t duration = 0, std::int32_t width = 0, std::int32_t height = 0, - std::variant, std::string> thumbnail = { }, const std::string& caption = "", - std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - const std::string& parseMode = "", bool disableNotification = false, - const std::vector>& captionEntities = { }, std::int32_t messageThreadId = 0, - bool protectContent = false, bool hasSpoiler = false, const std::string& businessConnectionId = "", - bool allowPaidBroadcast = false, const std::string& callbackQueryId = "", - std::variant, std::string> cover = { }, std::int64_t directMessagesTopicId = 0, - const std::string& messageEffectId = "", std::int64_t receiverUserId = 0, bool showCaptionAboveMedia = false, - std::int32_t startTimestamp = 0, - std::shared_ptr suggestedPostParameters = nullptr) const; + * @return The resulting Message object. + */ + std::shared_ptr sendVideo(std::variant chatId, + std::variant, std::string> video, + bool supportsStreaming = false, + std::int32_t duration = 0, + std::int32_t width = 0, + std::int32_t height = 0, + std::variant, std::string> thumbnail = { }, + const std::string& caption = "", + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + const std::string& parseMode = "", + bool disableNotification = false, + const std::vector>& captionEntities = { }, + std::int32_t messageThreadId = 0, + bool protectContent = false, + bool hasSpoiler = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& callbackQueryId = "", + std::variant, std::string> cover = { }, + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::int64_t receiverUserId = 0, + bool showCaptionAboveMedia = false, + std::int32_t startTimestamp = 0, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send video files, Telegram clients support MPEG4 videos (other + * formats may be sent as Document). On success, the sent Message is returned. Bots can + * currently send video files of up to 50 MB in size, this limit may be changed in the + * future. + * + * @param args Method arguments. + * + * @return The resulting Message object. + */ + std::shared_ptr sendVideo(const SendVideoArgs& args) const; /** * @brief As of v.4.0, Telegram clients support rounded square MPEG4 videos of up to 1 minute @@ -3381,22 +5089,39 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendVideoNote(std::variant chatId, + std::variant, std::string> videoNote, + std::shared_ptr replyParameters = nullptr, + bool disableNotification = false, + std::int32_t duration = 0, + std::int32_t length = 0, + std::variant, std::string> thumbnail = { }, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& callbackQueryId = "", + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::int64_t receiverUserId = 0, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief As of v.4.0, Telegram clients support rounded square MPEG4 videos of up to 1 minute + * long. Use this method to send video messages. On success, the sent Message is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr - sendVideoNote(std::variant chatId, - std::variant, std::string> videoNote, - std::shared_ptr replyParameters = nullptr, bool disableNotification = false, - std::int32_t duration = 0, std::int32_t length = 0, - std::variant, std::string> thumbnail = { }, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - std::int32_t messageThreadId = 0, bool protectContent = false, - const std::string& businessConnectionId = "", bool allowPaidBroadcast = false, - const std::string& callbackQueryId = "", std::int64_t directMessagesTopicId = 0, - const std::string& messageEffectId = "", std::int64_t receiverUserId = 0, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendVideoNote(const SendVideoNoteArgs& args) const; /** * @brief Use this method to send audio files, if you want Telegram clients to display the file as @@ -3447,22 +5172,43 @@ * reply to another suggested post, then that suggested post is * automatically declined. * - * @return Telegram Bot API result. + * @return The resulting Message object. + */ + std::shared_ptr sendVoice(std::variant chatId, + std::variant, std::string> voice, + const std::string& caption = "", + std::int32_t duration = 0, + std::shared_ptr replyParameters = nullptr, + std::variant, + std::shared_ptr, + std::shared_ptr, + std::shared_ptr> replyMarkup = { }, + const std::string& parseMode = "", + bool disableNotification = false, + const std::vector>& captionEntities = { }, + std::int32_t messageThreadId = 0, + bool protectContent = false, + const std::string& businessConnectionId = "", + bool allowPaidBroadcast = false, + const std::string& callbackQueryId = "", + std::int64_t directMessagesTopicId = 0, + const std::string& messageEffectId = "", + std::int64_t receiverUserId = 0, + std::shared_ptr suggestedPostParameters + = nullptr) const; + + /** + * @brief Use this method to send audio files, if you want Telegram clients to display the file as + * a playable voice message. For this to work, your audio must be in an .OGG file encoded + * with OPUS, or in .MP3 format, or in .M4A format (other formats may be sent as Audio or + * Document). On success, the sent Message is returned. Bots can currently send voice + * messages of up to 50 MB in size, this limit may be changed in the future. + * + * @param args Method arguments. + * + * @return The resulting Message object. */ - std::shared_ptr - sendVoice(std::variant chatId, - std::variant, std::string> voice, const std::string& caption = "", - std::int32_t duration = 0, std::shared_ptr replyParameters = nullptr, - std::variant, std::shared_ptr, - std::shared_ptr, std::shared_ptr> - replyMarkup = { }, - const std::string& parseMode = "", bool disableNotification = false, - const std::vector>& captionEntities = { }, - std::int32_t messageThreadId = 0, bool protectContent = false, - const std::string& businessConnectionId = "", bool allowPaidBroadcast = false, - const std::string& callbackQueryId = "", std::int64_t directMessagesTopicId = 0, - const std::string& messageEffectId = "", std::int64_t receiverUserId = 0, - std::shared_ptr suggestedPostParameters = nullptr) const; + std::shared_ptr sendVoice(const SendVoiceArgs& args) const; /** * @brief Changes the bio of a managed business account. Requires the can_change_bio business bot @@ -3471,10 +5217,20 @@ * @param businessConnectionId Unique identifier of the business connection * @param bio The new value of the bio for the business account; 0-140 characters * - * @return Telegram Bot API result. + * @return True on success. */ bool setBusinessAccountBio(const std::string& businessConnectionId, const std::string& bio = "") const; + /** + * @brief Changes the bio of a managed business account. Requires the can_change_bio business bot + * right. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setBusinessAccountBio(const SetBusinessAccountBioArgs& args) const; + /** * @brief Changes the privacy settings pertaining to incoming gifts in a managed business account. * Requires the can_change_gift_settings business bot right. Returns True on success. @@ -3484,10 +5240,21 @@ * @param showGiftButton Pass True if a button for sending a gift to the user or by the business * account must always be shown in the input field * - * @return Telegram Bot API result. + * @return True on success. */ bool setBusinessAccountGiftSettings(std::shared_ptr acceptedGiftTypes, - const std::string& businessConnectionId, bool showGiftButton) const; + const std::string& businessConnectionId, + bool showGiftButton) const; + + /** + * @brief Changes the privacy settings pertaining to incoming gifts in a managed business account. + * Requires the can_change_gift_settings business bot right. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setBusinessAccountGiftSettings(const SetBusinessAccountGiftSettingsArgs& args) const; /** * @brief Changes the first and last name of a managed business account. Requires the @@ -3498,11 +5265,22 @@ * characters * @param lastName The new value of the last name for the business account; 0-64 characters * - * @return Telegram Bot API result. + * @return True on success. */ - bool setBusinessAccountName(const std::string& businessConnectionId, const std::string& firstName, + bool setBusinessAccountName(const std::string& businessConnectionId, + const std::string& firstName, const std::string& lastName = "") const; + /** + * @brief Changes the first and last name of a managed business account. Requires the + * can_change_name business bot right. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setBusinessAccountName(const SetBusinessAccountNameArgs& args) const; + /** * @brief Changes the profile photo of a managed business account. Requires the * can_edit_profile_photo business bot right. Returns True on success. @@ -3513,10 +5291,21 @@ * main photo is hidden by the business account's privacy settings. An * account can have only one public photo. * - * @return Telegram Bot API result. + * @return True on success. */ bool setBusinessAccountProfilePhoto(const std::string& businessConnectionId, - std::shared_ptr photo, bool isPublic = false) const; + std::shared_ptr photo, + bool isPublic = false) const; + + /** + * @brief Changes the profile photo of a managed business account. Requires the + * can_edit_profile_photo business bot right. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setBusinessAccountProfilePhoto(const SetBusinessAccountProfilePhotoArgs& args) const; /** * @brief Changes the username of a managed business account. Requires the can_change_username @@ -3525,9 +5314,20 @@ * @param businessConnectionId Unique identifier of the business connection * @param username The new value of the username for the business account; 0-32 characters * - * @return Telegram Bot API result. + * @return True on success. */ - bool setBusinessAccountUsername(const std::string& businessConnectionId, const std::string& username = "") const; + bool setBusinessAccountUsername(const std::string& businessConnectionId, + const std::string& username = "") const; + + /** + * @brief Changes the username of a managed business account. Requires the can_change_username + * business bot right. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setBusinessAccountUsername(const SetBusinessAccountUsernameArgs& args) const; /** * @brief Use this method to set a custom title for an administrator in a supergroup promoted by @@ -3539,11 +5339,22 @@ * @param customTitle New custom title for the administrator; 0-16 characters, emoji are not * allowed * - * @return Telegram Bot API result. + * @return True on success. */ - bool setChatAdministratorCustomTitle(std::variant chatId, std::int64_t userId, + bool setChatAdministratorCustomTitle(std::variant chatId, + std::int64_t userId, const std::string& customTitle) const; + /** + * @brief Use this method to set a custom title for an administrator in a supergroup promoted by + * the bot. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setChatAdministratorCustomTitle(const SetChatAdministratorCustomTitleArgs& args) const; + /** * @brief Use this method to change the description of a group, a supergroup or a channel. The bot * must be an administrator in the chat for this to work and must have the appropriate @@ -3553,9 +5364,21 @@ * in the format @username * @param description New chat description, 0-255 characters * - * @return Telegram Bot API result. + * @return True on success. + */ + bool setChatDescription(std::variant chatId, + const std::string& description = "") const; + + /** + * @brief Use this method to change the description of a group, a supergroup or a channel. The bot + * must be an administrator in the chat for this to work and must have the appropriate + * administrator rights. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. */ - bool setChatDescription(std::variant chatId, const std::string& description = "") const; + bool setChatDescription(const SetChatDescriptionArgs& args) const; /** * @brief Use this method to set a tag for a regular member in a group or a supergroup. The bot @@ -3567,11 +5390,23 @@ * @param userId Unique identifier of the target user * @param tag New tag for the member; 0-16 characters, emoji are not allowed * - * @return Telegram Bot API result. + * @return True on success. */ - bool setChatMemberTag(std::variant chatId, std::int64_t userId, + bool setChatMemberTag(std::variant chatId, + std::int64_t userId, const std::string& tag = "") const; + /** + * @brief Use this method to set a tag for a regular member in a group or a supergroup. The bot + * must be an administrator in the chat for this to work and must have the can_manage_tags + * administrator right. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setChatMemberTag(const SetChatMemberTagArgs& args) const; + /** * @brief Use this method to change the bot's menu button in a private chat, or the default menu * button. Returns True on success. @@ -3581,11 +5416,21 @@ * @param menuButton A JSON-serialized object for the bot's new menu button. Defaults to * MenuButtonDefault. * - * @return Telegram Bot API result. + * @return True on success. */ bool setChatMenuButton(std::variant chatId = { }, std::shared_ptr menuButton = nullptr) const; + /** + * @brief Use this method to change the bot's menu button in a private chat, or the default menu + * button. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setChatMenuButton(const SetChatMenuButtonArgs& args) const; + /** * @brief Use this method to set default chat permissions for all members. The bot must be an * administrator in the group or a supergroup for this to work and must have the @@ -3601,12 +5446,23 @@ * can_send_voice_notes permissions; the can_send_polls permission will * imply the can_send_messages permission. * - * @return Telegram Bot API result. + * @return True on success. */ bool setChatPermissions(std::variant chatId, std::shared_ptr permissions, bool useIndependentChatPermissions = false) const; + /** + * @brief Use this method to set default chat permissions for all members. The bot must be an + * administrator in the group or a supergroup for this to work and must have the + * can_restrict_members administrator rights. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setChatPermissions(const SetChatPermissionsArgs& args) const; + /** * @brief Use this method to set a new profile photo for the chat. Photos can't be changed for * private chats. The bot must be an administrator in the chat for this to work and must @@ -3616,11 +5472,22 @@ * in the format @username * @param photo New chat photo, uploaded using multipart/form-data * - * @return Telegram Bot API result. + * @return True on success. */ bool setChatPhoto(std::variant chatId, std::variant, std::string> photo) const; + /** + * @brief Use this method to set a new profile photo for the chat. Photos can't be changed for + * private chats. The bot must be an administrator in the chat for this to work and must + * have the appropriate administrator rights. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setChatPhoto(const SetChatPhotoArgs& args) const; + /** * @brief Use this method to set a new group sticker set for a supergroup. The bot must be an * administrator in the chat for this to work and must have the appropriate administrator @@ -3631,10 +5498,22 @@ * supergroup in the format @username * @param stickerSetName Name of the sticker set to be set as the group sticker set * - * @return Telegram Bot API result. + * @return True on success. */ bool setChatStickerSet(std::variant chatId, const std::string& stickerSetName) const; + /** + * @brief Use this method to set a new group sticker set for a supergroup. The bot must be an + * administrator in the chat for this to work and must have the appropriate administrator + * rights. Use the field can_set_sticker_set optionally returned in getChat requests to + * check if the bot can use this method. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setChatStickerSet(const SetChatStickerSetArgs& args) const; + /** * @brief Use this method to change the title of a chat. Titles can't be changed for private * chats. The bot must be an administrator in the chat for this to work and must have the @@ -3644,10 +5523,21 @@ * in the format @username * @param title New chat title, 1-128 characters * - * @return Telegram Bot API result. + * @return True on success. */ bool setChatTitle(std::variant chatId, const std::string& title) const; + /** + * @brief Use this method to change the title of a chat. Titles can't be changed for private + * chats. The bot must be an administrator in the chat for this to work and must have the + * appropriate administrator rights. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setChatTitle(const SetChatTitleArgs& args) const; + /** * @brief Use this method to set the thumbnail of a custom emoji sticker set. Returns True on * success. @@ -3656,10 +5546,20 @@ * @param customEmojiId Custom emoji identifier of a sticker from the sticker set; pass an empty * string to drop the thumbnail and use the first sticker as the thumbnail * - * @return Telegram Bot API result. + * @return True on success. */ bool setCustomEmojiStickerSetThumbnail(const std::string& name, const std::string& customEmojiId = "") const; + /** + * @brief Use this method to set the thumbnail of a custom emoji sticker set. Returns True on + * success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setCustomEmojiStickerSetThumbnail(const SetCustomEmojiStickerSetThumbnailArgs& args) const; + /** * @brief Use this method to set the score of the specified user in a game message. On success, if * the message is not an inline message, the Message is returned, otherwise True is @@ -3679,12 +5579,27 @@ * @param inlineMessageId Required if chat_id and message_id are not specified. Identifier of the * inline message. * - * @return Telegram Bot API result. + * @return The resulting Message object, or nullptr if Telegram returns True. */ - std::shared_ptr setGameScore(std::int64_t userId, std::int32_t score, bool force = false, + std::shared_ptr setGameScore(std::int64_t userId, + std::int32_t score, + bool force = false, bool disableEditMessage = false, std::variant chatId = { }, - std::int32_t messageId = 0, const std::string& inlineMessageId = "") const; + std::int32_t messageId = 0, + const std::string& inlineMessageId = "") const; + + /** + * @brief Use this method to set the score of the specified user in a game message. On success, if + * the message is not an inline message, the Message is returned, otherwise True is + * returned. Returns an error, if the new score is not greater than the user's current + * score in the chat and force is False. + * + * @param args Method arguments. + * + * @return The resulting Message object, or nullptr if Telegram returns True. + */ + std::shared_ptr setGameScore(const SetGameScoreArgs& args) const; /** * @brief Use this method to change the access settings of a managed bot. Returns True on success. @@ -3696,11 +5611,21 @@ * access to the bot in addition to its owner. Ignored if * is_access_restricted is False. * - * @return Telegram Bot API result. + * @return True on success. */ - bool setManagedBotAccessSettings(bool isAccessRestricted, std::int64_t userId, + bool setManagedBotAccessSettings(bool isAccessRestricted, + std::int64_t userId, const std::vector& addedUserIds = { }) const; + /** + * @brief Use this method to change the access settings of a managed bot. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setManagedBotAccessSettings(const SetManagedBotAccessSettingsArgs& args) const; + /** * @brief Use this method to change the chosen reactions on a message. Service messages of some * types can't be reacted to. Automatically forwarded messages from a channel to its @@ -3719,10 +5644,24 @@ * Paid reactions can't be used by bots. * @param isBig Pass True to set the reaction with a big animation * - * @return Telegram Bot API result. + * @return True on success. */ - bool setMessageReaction(std::variant chatId, std::int32_t messageId, - const std::vector>& reaction = { }, bool isBig = false) const; + bool setMessageReaction(std::variant chatId, + std::int32_t messageId, + const std::vector>& reaction = { }, + bool isBig = false) const; + + /** + * @brief Use this method to change the chosen reactions on a message. Service messages of some + * types can't be reacted to. Automatically forwarded messages from a channel to its + * discussion group have the same available reactions as messages in the channel. Bots + * can't use paid reactions. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setMessageReaction(const SetMessageReactionArgs& args) const; /** * @brief Use this method to change the list of the bot's commands. See this manual for more @@ -3736,10 +5675,21 @@ * to all users from the given scope, for whose language there are no * dedicated commands. * - * @return Telegram Bot API result. + * @return True on success. */ bool setMyCommands(const std::vector>& commands, - std::shared_ptr scope = nullptr, const std::string& languageCode = "") const; + std::shared_ptr scope = nullptr, + const std::string& languageCode = "") const; + + /** + * @brief Use this method to change the list of the bot's commands. See this manual for more + * details about bot commands. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setMyCommands(const SetMyCommandsArgs& args) const; /** * @brief Use this method to change the default administrator rights requested by the bot when @@ -3753,11 +5703,23 @@ * channels. Otherwise, the default administrator rights of the bot for * groups and supergroups will be changed. * - * @return Telegram Bot API result. + * @return True on success. */ bool setMyDefaultAdministratorRights(std::shared_ptr rights = nullptr, bool forChannels = false) const; + /** + * @brief Use this method to change the default administrator rights requested by the bot when + * it's added as an administrator to groups or channels. These rights will be suggested to + * users, but they are free to modify the list before adding the bot. Returns True on + * success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setMyDefaultAdministratorRights(const SetMyDefaultAdministratorRightsArgs& args) const; + /** * @brief Use this method to change the bot's description, which is shown in the chat with the bot * if the chat is empty. Returns True on success. @@ -3768,10 +5730,20 @@ * applied to all users for whose language there is no dedicated * description. * - * @return Telegram Bot API result. + * @return True on success. */ bool setMyDescription(const std::string& description = "", const std::string& languageCode = "") const; + /** + * @brief Use this method to change the bot's description, which is shown in the chat with the bot + * if the chat is empty. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setMyDescription(const SetMyDescriptionArgs& args) const; + /** * @brief Use this method to change the bot's name. Returns True on success. * @@ -3780,19 +5752,37 @@ * @param languageCode A two-letter ISO 639-1 language code. If empty, the name will be shown * to all users for whose language there is no dedicated name. * - * @return Telegram Bot API result. + * @return True on success. */ bool setMyName(const std::string& name = "", const std::string& languageCode = "") const; + /** + * @brief Use this method to change the bot's name. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setMyName(const SetMyNameArgs& args) const; + /** * @brief Changes the profile photo of the bot. Returns True on success. * * @param photo The new profile photo to set * - * @return Telegram Bot API result. + * @return True on success. */ bool setMyProfilePhoto(std::shared_ptr photo) const; + /** + * @brief Changes the profile photo of the bot. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setMyProfilePhoto(const SetMyProfilePhotoArgs& args) const; + /** * @brief Use this method to change the bot's short description, which is shown on the bot's * profile page and is sent together with the link when users share the bot. Returns True @@ -3804,9 +5794,21 @@ * will be applied to all users for whose language there is no dedicated * short description. * - * @return Telegram Bot API result. + * @return True on success. + */ + bool setMyShortDescription(const std::string& shortDescription = "", + const std::string& languageCode = "") const; + + /** + * @brief Use this method to change the bot's short description, which is shown on the bot's + * profile page and is sent together with the link when users share the bot. Returns True + * on success. + * + * @param args Method arguments. + * + * @return True on success. */ - bool setMyShortDescription(const std::string& shortDescription = "", const std::string& languageCode = "") const; + bool setMyShortDescription(const SetMyShortDescriptionArgs& args) const; /** * @brief Informs a user that some of the Telegram Passport elements they provided contains @@ -3820,11 +5822,26 @@ * @param userId User identifier * @param errors A JSON-serialized Array describing the errors * - * @return Telegram Bot API result. + * @return True on success. */ bool setPassportDataErrors(std::int64_t userId, const std::vector>& errors) const; + /** + * @brief Informs a user that some of the Telegram Passport elements they provided contains + * errors. The user will not be able to re-submit their Passport to you until the errors + * are fixed (the contents of the field for which you returned the error must change). + * Returns True on success. Use this if the data submitted by the user doesn't satisfy the + * standards your service requires for any reason. For example, if a birthday date seems + * invalid, a submitted document is blurry, a scan shows evidence of tampering, etc. Supply + * some details in the error message to make sure the user knows how to correct the issues. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setPassportDataErrors(const SetPassportDataErrorsArgs& args) const; + /** * @brief Use this method to change the list of emoji assigned to a regular or custom emoji * sticker. The sticker must belong to a sticker set created by the bot. Returns True on @@ -3833,10 +5850,21 @@ * @param sticker File identifier of the sticker * @param emojiList A JSON-serialized list of 1-20 emoji associated with the sticker * - * @return Telegram Bot API result. + * @return True on success. */ bool setStickerEmojiList(const std::string& sticker, const std::vector& emojiList) const; + /** + * @brief Use this method to change the list of emoji assigned to a regular or custom emoji + * sticker. The sticker must belong to a sticker set created by the bot. Returns True on + * success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setStickerEmojiList(const SetStickerEmojiListArgs& args) const; + /** * @brief Use this method to change search keywords assigned to a regular or custom emoji sticker. * The sticker must belong to a sticker set created by the bot. Returns True on success. @@ -3845,10 +5873,20 @@ * @param keywords A JSON-serialized list of 0-20 search keywords for the sticker with * total length of up to 64 characters * - * @return Telegram Bot API result. + * @return True on success. */ bool setStickerKeywords(const std::string& sticker, const std::vector& keywords = { }) const; + /** + * @brief Use this method to change search keywords assigned to a regular or custom emoji sticker. + * The sticker must belong to a sticker set created by the bot. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setStickerKeywords(const SetStickerKeywordsArgs& args) const; + /** * @brief Use this method to change the mask position of a mask sticker. The sticker must belong * to a sticker set that was created by the bot. Returns True on success. @@ -3857,9 +5895,20 @@ * @param maskPosition A JSON-serialized object with the position where the mask should be * placed on faces. Omit the parameter to remove the mask position. * - * @return Telegram Bot API result. + * @return True on success. */ - bool setStickerMaskPosition(const std::string& sticker, std::shared_ptr maskPosition = nullptr) const; + bool setStickerMaskPosition(const std::string& sticker, + std::shared_ptr maskPosition = nullptr) const; + + /** + * @brief Use this method to change the mask position of a mask sticker. The sticker must belong + * to a sticker set that was created by the bot. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setStickerMaskPosition(const SetStickerMaskPositionArgs& args) const; /** * @brief Use this method to move a sticker in a set created by the bot to a specific position. @@ -3868,10 +5917,20 @@ * @param sticker File identifier of the sticker * @param position New sticker position in the set, zero-based * - * @return Telegram Bot API result. + * @return True on success. */ bool setStickerPositionInSet(const std::string& sticker, std::int32_t position) const; + /** + * @brief Use this method to move a sticker in a set created by the bot to a specific position. + * Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setStickerPositionInSet(const SetStickerPositionInSetArgs& args) const; + /** * @brief Use this method to set the thumbnail of a regular or mask sticker set. The format of the * thumbnail file must match the format of the stickers in the set. Returns True on @@ -3895,21 +5954,43 @@ * thumbnails can't be uploaded via HTTP URL. If omitted, then the * thumbnail is dropped and the first sticker is used as the thumbnail. * - * @return Telegram Bot API result. + * @return True on success. */ - bool setStickerSetThumbnail(const std::string& name, std::int64_t userId, const std::string& format, + bool setStickerSetThumbnail(const std::string& name, + std::int64_t userId, + const std::string& format, std::variant, std::string> thumbnail = { }) const; + /** + * @brief Use this method to set the thumbnail of a regular or mask sticker set. The format of the + * thumbnail file must match the format of the stickers in the set. Returns True on + * success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setStickerSetThumbnail(const SetStickerSetThumbnailArgs& args) const; + /** * @brief Use this method to set the title of a created sticker set. Returns True on success. * * @param name Sticker set name * @param title Sticker set title, 1-64 characters * - * @return Telegram Bot API result. + * @return True on success. */ bool setStickerSetTitle(const std::string& name, const std::string& title) const; + /** + * @brief Use this method to set the title of a created sticker set. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setStickerSetTitle(const SetStickerSetTitleArgs& args) const; + /** * @brief Changes the emoji status for a given user that previously allowed the bot to manage * their emoji status via the Mini App method requestEmojiStatusAccess. Returns True on @@ -3920,11 +6001,23 @@ * to remove the status. * @param emojiStatusExpirationDate Expiration date of the emoji status, if any * - * @return Telegram Bot API result. + * @return True on success. */ - bool setUserEmojiStatus(std::int64_t userId, const std::string& emojiStatusCustomEmojiId = "", + bool setUserEmojiStatus(std::int64_t userId, + const std::string& emojiStatusCustomEmojiId = "", std::int32_t emojiStatusExpirationDate = 0) const; + /** + * @brief Changes the emoji status for a given user that previously allowed the bot to manage + * their emoji status via the Mini App method requestEmojiStatusAccess. Returns True on + * success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setUserEmojiStatus(const SetUserEmojiStatusArgs& args) const; + /** * @brief Use this method to specify a URL and receive incoming updates via an outgoing webhook. * Whenever there is an update for the bot, we will send an HTTPS POST request to the @@ -3960,13 +6053,32 @@ * 0-9, _ and - are allowed. The header is useful to ensure that the * request comes from a webhook set by you. * - * @return Telegram Bot API result. + * @return True on success. */ - bool setWebhook(const std::string& url, std::shared_ptr certificate = nullptr, - std::int32_t maxConnections = 40, const std::vector& allowedUpdates = { }, - const std::string& ipAddress = "", bool dropPendingUpdates = false, + bool setWebhook(const std::string& url, + std::shared_ptr certificate = nullptr, + std::int32_t maxConnections = 40, + const std::vector& allowedUpdates = { }, + const std::string& ipAddress = "", + bool dropPendingUpdates = false, const std::string& secretToken = "") const; + /** + * @brief Use this method to specify a URL and receive incoming updates via an outgoing webhook. + * Whenever there is an update for the bot, we will send an HTTPS POST request to the + * specified URL, containing a JSON-serialized Update. In case of an unsuccessful request + * (a request with response HTTP status code different from 2XY), we will repeat the + * request and give up after a reasonable amount of attempts. Returns True on success. If + * you'd like to make sure that the webhook was set by you, you can specify secret data in + * the parameter secret_token. If specified, the request will contain a header “X-Telegram- + * Bot-Api-Secret-Token” with the secret token as content. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool setWebhook(const SetWebhookArgs& args) const; + /** * @brief Use this method to stop updating a live location message before live_period expires. On * success, if the message is not an inline message, the edited Message is returned, @@ -3983,7 +6095,7 @@ * @param businessConnectionId Unique identifier of the business connection on behalf of which the * message to be edited was sent * - * @return Telegram Bot API result. + * @return The resulting Message object, or nullptr if Telegram returns True. */ std::shared_ptr stopMessageLiveLocation(std::variant chatId = { }, std::int32_t messageId = 0, @@ -3991,6 +6103,17 @@ std::shared_ptr replyMarkup = nullptr, const std::string& businessConnectionId = "") const; + /** + * @brief Use this method to stop updating a live location message before live_period expires. On + * success, if the message is not an inline message, the edited Message is returned, + * otherwise True is returned. + * + * @param args Method arguments. + * + * @return The resulting Message object, or nullptr if Telegram returns True. + */ + std::shared_ptr stopMessageLiveLocation(const StopMessageLiveLocationArgs& args) const; + /** * @brief Use this method to stop a poll which was sent by the bot. On success, the stopped Poll * is returned. @@ -4002,12 +6125,23 @@ * message to be edited was sent * @param replyMarkup A JSON-serialized object for a new message inline keyboard * - * @return Telegram Bot API result. + * @return The resulting Poll object. */ - std::shared_ptr stopPoll(std::variant chatId, std::int32_t messageId, + std::shared_ptr stopPoll(std::variant chatId, + std::int32_t messageId, const std::string& businessConnectionId = "", std::shared_ptr replyMarkup = nullptr) const; + /** + * @brief Use this method to stop a poll which was sent by the bot. On success, the stopped Poll + * is returned. + * + * @param args Method arguments. + * + * @return The resulting Poll object. + */ + std::shared_ptr stopPoll(const StopPollArgs& args) const; + /** * @brief Transfers Telegram Stars from the business account balance to the bot's balance. * Requires the can_transfer_stars business bot right. Returns True on success. @@ -4015,10 +6149,20 @@ * @param businessConnectionId Unique identifier of the business connection * @param starCount Number of Telegram Stars to transfer; 1-10000 * - * @return Telegram Bot API result. + * @return True on success. */ bool transferBusinessAccountStars(const std::string& businessConnectionId, std::int32_t starCount) const; + /** + * @brief Transfers Telegram Stars from the business account balance to the bot's balance. + * Requires the can_transfer_stars business bot right. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool transferBusinessAccountStars(const TransferBusinessAccountStarsArgs& args) const; + /** * @brief Transfers an owned unique gift to another user. Requires the * can_transfer_and_upgrade_gifts business bot right. Requires can_transfer_stars business @@ -4032,10 +6176,23 @@ * business account balance. If positive, then the can_transfer_stars * business bot right is required. * - * @return Telegram Bot API result. + * @return True on success. + */ + bool transferGift(const std::string& businessConnectionId, + std::int64_t newOwnerChatId, + const std::string& ownedGiftId, + std::int32_t starCount = 0) const; + + /** + * @brief Transfers an owned unique gift to another user. Requires the + * can_transfer_and_upgrade_gifts business bot right. Requires can_transfer_stars business + * bot right if the transfer is paid. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. */ - bool transferGift(const std::string& businessConnectionId, std::int64_t newOwnerChatId, - const std::string& ownedGiftId, std::int32_t starCount = 0) const; + bool transferGift(const TransferGiftArgs& args) const; /** * @brief Use this method to unban a previously banned user in a supergroup or channel. The user @@ -4050,11 +6207,26 @@ * @param userId Unique identifier of the target user * @param onlyIfBanned Do nothing if the user is not banned * - * @return Telegram Bot API result. + * @return True on success. */ - bool unbanChatMember(std::variant chatId, std::int64_t userId, + bool unbanChatMember(std::variant chatId, + std::int64_t userId, bool onlyIfBanned = false) const; + /** + * @brief Use this method to unban a previously banned user in a supergroup or channel. The user + * will not return to the group or channel automatically, but will be able to join via + * link, etc. The bot must be an administrator for this to work. By default, this method + * guarantees that after the call the user is not a member of the chat, but will be able to + * join it. So if the user is a member of the chat they will also be removed from the chat. + * If you don't want this, use the parameter only_if_banned. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool unbanChatMember(const UnbanChatMemberArgs& args) const; + /** * @brief Use this method to unban a previously banned channel chat in a supergroup or channel. * The bot must be an administrator for this to work and must have the appropriate @@ -4064,10 +6236,21 @@ * in the format @username * @param senderChatId Unique identifier of the target sender chat * - * @return Telegram Bot API result. + * @return True on success. */ bool unbanChatSenderChat(std::variant chatId, std::int64_t senderChatId) const; + /** + * @brief Use this method to unban a previously banned channel chat in a supergroup or channel. + * The bot must be an administrator for this to work and must have the appropriate + * administrator rights. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool unbanChatSenderChat(const UnbanChatSenderChatArgs& args) const; + /** * @brief Use this method to unhide the 'General' topic in a forum supergroup chat. The bot must * be an administrator in the chat for this to work and must have the can_manage_topics @@ -4076,10 +6259,21 @@ * @param chatId Unique identifier for the target chat or username of the target * supergroup in the format @username * - * @return Telegram Bot API result. + * @return True on success. */ bool unhideGeneralForumTopic(std::variant chatId) const; + /** + * @brief Use this method to unhide the 'General' topic in a forum supergroup chat. The bot must + * be an administrator in the chat for this to work and must have the can_manage_topics + * administrator rights. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool unhideGeneralForumTopic(const UnhideGeneralForumTopicArgs& args) const; + /** * @brief Use this method to clear the list of pinned messages in a chat. In private chats and * channel direct messages chats, no additional rights are required to unpin all pinned @@ -4090,10 +6284,23 @@ * @param chatId Unique identifier for the target chat or username of the target channel * in the format @username * - * @return Telegram Bot API result. + * @return True on success. */ bool unpinAllChatMessages(std::variant chatId) const; + /** + * @brief Use this method to clear the list of pinned messages in a chat. In private chats and + * channel direct messages chats, no additional rights are required to unpin all pinned + * messages. Conversely, the bot must be an administrator with the 'can_pin_messages' right + * or the 'can_edit_messages' right to unpin all pinned messages in groups and channels + * respectively. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool unpinAllChatMessages(const UnpinAllChatMessagesArgs& args) const; + /** * @brief Use this method to clear the list of pinned messages in a forum topic in a forum * supergroup chat or a private chat with a user. In the case of a supergroup chat the bot @@ -4104,9 +6311,22 @@ * supergroup in the format @username * @param messageThreadId Unique identifier for the target message thread of the forum topic * - * @return Telegram Bot API result. + * @return True on success. */ - bool unpinAllForumTopicMessages(std::variant chatId, std::int32_t messageThreadId) const; + bool unpinAllForumTopicMessages(std::variant chatId, + std::int32_t messageThreadId) const; + + /** + * @brief Use this method to clear the list of pinned messages in a forum topic in a forum + * supergroup chat or a private chat with a user. In the case of a supergroup chat the bot + * must be an administrator in the chat for this to work and must have the can_pin_messages + * administrator right in the supergroup. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool unpinAllForumTopicMessages(const UnpinAllForumTopicMessagesArgs& args) const; /** * @brief Use this method to clear the list of pinned messages in a General forum topic. The bot @@ -4116,10 +6336,21 @@ * @param chatId Unique identifier for the target chat or username of the target * supergroup in the format @username * - * @return Telegram Bot API result. + * @return True on success. */ bool unpinAllGeneralForumTopicMessages(std::variant chatId) const; + /** + * @brief Use this method to clear the list of pinned messages in a General forum topic. The bot + * must be an administrator in the chat for this to work and must have the can_pin_messages + * administrator right in the supergroup. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool unpinAllGeneralForumTopicMessages(const UnpinAllGeneralForumTopicMessagesArgs& args) const; + /** * @brief Use this method to remove a message from the list of pinned messages in a chat. In * private chats and channel direct messages chats, all messages can be unpinned. @@ -4135,11 +6366,25 @@ * is specified. If not specified, the most recent pinned message (by * sending date) will be unpinned. * - * @return Telegram Bot API result. + * @return True on success. */ - bool unpinChatMessage(std::variant chatId, const std::string& businessConnectionId = "", + bool unpinChatMessage(std::variant chatId, + const std::string& businessConnectionId = "", std::int32_t messageId = 0) const; + /** + * @brief Use this method to remove a message from the list of pinned messages in a chat. In + * private chats and channel direct messages chats, all messages can be unpinned. + * Conversely, the bot must be an administrator with the 'can_pin_messages' right or the + * 'can_edit_messages' right to unpin messages in groups and channels respectively. Returns + * True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool unpinChatMessage(const UnpinChatMessageArgs& args) const; + /** * @brief Upgrades a given regular gift to a unique gift. Requires the * can_transfer_and_upgrade_gifts business bot right. Additionally requires the @@ -4155,10 +6400,23 @@ * pass 0, otherwise, the can_transfer_stars business bot right is required * and gift.upgrade_star_count must be passed. * - * @return Telegram Bot API result. + * @return True on success. */ - bool upgradeGift(const std::string& businessConnectionId, const std::string& ownedGiftId, - bool keepOriginalDetails = false, std::int32_t starCount = 0) const; + bool upgradeGift(const std::string& businessConnectionId, + const std::string& ownedGiftId, + bool keepOriginalDetails = false, + std::int32_t starCount = 0) const; + + /** + * @brief Upgrades a given regular gift to a unique gift. Requires the + * can_transfer_and_upgrade_gifts business bot right. Additionally requires the + * can_transfer_stars business bot right if the upgrade is paid. Returns True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool upgradeGift(const UpgradeGiftArgs& args) const; /** * @brief Use this method to upload a file with a sticker for later use in the @@ -4171,12 +6429,23 @@ * information on Sending Files » * @param stickerFormat Format of the sticker, must be one of “static”, “animated”, “video” * - * @return Telegram Bot API result. + * @return The resulting File object. */ std::shared_ptr uploadStickerFile(std::int64_t userId, std::variant, std::string> sticker, const std::string& stickerFormat) const; + /** + * @brief Use this method to upload a file with a sticker for later use in the + * createNewStickerSet, addStickerToSet, or replaceStickerInSet methods (the file can be + * used multiple times). Returns the uploaded File on success. + * + * @param args Method arguments. + * + * @return The resulting File object. + */ + std::shared_ptr uploadStickerFile(const UploadStickerFileArgs& args) const; + /** * @brief Verifies a chat on behalf of the organization which is represented by the bot. Returns * True on success. @@ -4188,9 +6457,20 @@ * if the organization isn't allowed to provide a custom verification * description. * - * @return Telegram Bot API result. + * @return True on success. + */ + bool verifyChat(std::variant chatId, + const std::string& customDescription = "") const; + + /** + * @brief Verifies a chat on behalf of the organization which is represented by the bot. Returns + * True on success. + * + * @param args Method arguments. + * + * @return True on success. */ - bool verifyChat(std::variant chatId, const std::string& customDescription = "") const; + bool verifyChat(const VerifyChatArgs& args) const; /** * @brief Verifies a user on behalf of the organization which is represented by the bot. Returns @@ -4201,6 +6481,16 @@ * if the organization isn't allowed to provide a custom verification * description. * - * @return Telegram Bot API result. + * @return True on success. */ bool verifyUser(std::int64_t userId, const std::string& customDescription = "") const; + + /** + * @brief Verifies a user on behalf of the organization which is represented by the bot. Returns + * True on success. + * + * @param args Method arguments. + * + * @return True on success. + */ + bool verifyUser(const VerifyUserArgs& args) const; diff --git a/include/tgbot/InputFile.h b/include/tgbot/InputFile.h index c706e97a..bb9bfb36 100644 --- a/include/tgbot/InputFile.h +++ b/include/tgbot/InputFile.h @@ -12,8 +12,7 @@ namespace TgBot { * * @ingroup api */ -class TGBOT_API InputFile { -public: +struct TGBOT_API InputFile { using Ptr = std::shared_ptr; /** diff --git a/include/tgbot/Types.h b/include/tgbot/Types.h index 75ac7bbd..905a6b21 100644 --- a/include/tgbot/Types.h +++ b/include/tgbot/Types.h @@ -15,6 +15,8 @@ namespace TgBot { +struct InputFile; + struct AcceptedGiftTypes; struct AffiliateInfo; struct Animation; @@ -414,22 +416,18 @@ struct AcceptedGiftTypes { * @brief True, if unlimited regular gifts are accepted */ bool unlimitedGifts { }; - /** * @brief True, if limited regular gifts are accepted */ bool limitedGifts { }; - /** * @brief True, if unique gifts or gifts that can be upgraded to unique for free are accepted */ bool uniqueGifts { }; - /** * @brief True, if a Telegram Premium subscription is accepted */ bool premiumSubscription { }; - /** * @brief True, if transfers of unique gifts from channels are accepted */ @@ -451,24 +449,20 @@ struct AffiliateInfo { * by a bot or a user */ std::shared_ptr affiliateUser { }; - /** * @brief Optional. The chat that received an affiliate commission if it was received by a chat */ std::shared_ptr affiliateChat { }; - /** * @brief The number of Telegram Stars received by the affiliate for each 1000 Telegram Stars * received by the bot from referred users */ std::int32_t commissionPerMille { }; - /** * @brief Integer amount of Telegram Stars received by the affiliate from the transaction, rounded * to 0; can be negative for refunds */ std::int32_t amount { }; - /** * @brief Optional. The number of 1/1000000000 shares of Telegram Stars received by the affiliate; * from -999999999 to 999999999; can be negative for refunds @@ -490,43 +484,35 @@ struct Animation { * @brief Identifier for this file, which can be used to download or reuse the file */ std::string fileId { }; - /** * @brief Unique identifier for this file, which is supposed to be the same over time and for * different bots. Can't be used to download or reuse the file. */ std::string fileUniqueId { }; - /** * @brief Video width as defined by the sender */ std::int32_t width { }; - /** * @brief Video height as defined by the sender */ std::int32_t height { }; - /** * @brief Duration of the video in seconds as defined by the sender */ std::int32_t duration { }; - /** * @brief Optional. Animation thumbnail as defined by the sender */ std::shared_ptr thumbnail { }; - /** * @brief Optional. Original animation filename as defined by the sender */ std::optional fileName { }; - /** * @brief Optional. MIME type of the file as defined by the sender */ std::optional mimeType { }; - /** * @brief Optional. File size in bytes. It can be bigger than 2^31 and some programming languages * may have difficulty/silent defects in interpreting it. But it has at most 52 significant @@ -550,38 +536,31 @@ struct Audio { * @brief Identifier for this file, which can be used to download or reuse the file */ std::string fileId { }; - /** * @brief Unique identifier for this file, which is supposed to be the same over time and for * different bots. Can't be used to download or reuse the file. */ std::string fileUniqueId { }; - /** * @brief Duration of the audio in seconds as defined by the sender */ std::int32_t duration { }; - /** * @brief Optional. Performer of the audio as defined by the sender or by audio tags */ std::optional performer { }; - /** * @brief Optional. Title of the audio as defined by the sender or by audio tags */ std::optional title { }; - /** * @brief Optional. Original filename as defined by the sender */ std::optional fileName { }; - /** * @brief Optional. MIME type of the file as defined by the sender */ std::optional mimeType { }; - /** * @brief Optional. File size in bytes. It can be bigger than 2^31 and some programming languages * may have difficulty/silent defects in interpreting it. But it has at most 52 significant @@ -589,7 +568,6 @@ struct Audio { * this value. */ std::optional fileSize { }; - /** * @brief Optional. Thumbnail of the album cover to which the music file belongs */ @@ -629,7 +607,6 @@ struct BackgroundFillFreeformGradient { * @brief Type of the background fill, always “freeform_gradient” */ std::string type { TYPE }; - /** * @brief A list of the 3 or 4 base colors that are used to generate the freeform gradient in the * RGB24 format @@ -653,17 +630,14 @@ struct BackgroundFillGradient { * @brief Type of the background fill, always “gradient” */ std::string type { TYPE }; - /** * @brief Top color of the gradient in the RGB24 format */ std::int32_t topColor { }; - /** * @brief Bottom color of the gradient in the RGB24 format */ std::int32_t bottomColor { }; - /** * @brief Clockwise rotation angle of the background fill in degrees; 0-359 */ @@ -686,7 +660,6 @@ struct BackgroundFillSolid { * @brief Type of the background fill, always “solid” */ std::string type { TYPE }; - /** * @brief The color of the background fill in the RGB24 format */ @@ -725,7 +698,6 @@ struct BackgroundTypeChatTheme { * @brief Type of the background, always “chat_theme” */ std::string type { TYPE }; - /** * @brief Name of the chat theme, which is usually an emoji */ @@ -748,12 +720,10 @@ struct BackgroundTypeFill { * @brief Type of the background, always “fill” */ std::string type { TYPE }; - /** * @brief The background fill */ std::shared_ptr fill { }; - /** * @brief Dimming of the background in dark themes, as a percentage; 0-100 */ @@ -778,28 +748,23 @@ struct BackgroundTypePattern { * @brief Type of the background, always “pattern” */ std::string type { TYPE }; - /** * @brief Document with the pattern */ std::shared_ptr document { }; - /** * @brief The background fill that is combined with the pattern */ std::shared_ptr fill { }; - /** * @brief Intensity of the pattern when it is shown above the filled background; 0-100 */ std::int32_t intensity { }; - /** * @brief Optional. True, if the background fill must be applied only to the pattern itself. All * other pixels are black in this case. For dark themes only. */ std::optional isInverted { }; - /** * @brief Optional. True, if the background moves slightly when the device is tilted */ @@ -822,23 +787,19 @@ struct BackgroundTypeWallpaper { * @brief Type of the background, always “wallpaper” */ std::string type { TYPE }; - /** * @brief Document with the wallpaper */ std::shared_ptr document { }; - /** * @brief Dimming of the background in dark themes, as a percentage; 0-100 */ std::int32_t darkThemeDimming { }; - /** * @brief Optional. True, if the wallpaper is downscaled to fit in a 450x450 square and then box- * blurred with radius 12 */ std::optional isBlurred { }; - /** * @brief Optional. True, if the background moves slightly when the device is tilted */ @@ -859,12 +820,10 @@ struct Birthdate { * @brief Day of the user's birth; 1-31 */ std::int32_t day { }; - /** * @brief Month of the user's birth; 1-12 */ std::int32_t month { }; - /** * @brief Optional. Year of the user's birth */ @@ -885,7 +844,6 @@ struct BotAccessSettings { * @brief True, if only selected users can access the bot. The bot's owner can always access it. */ bool isAccessRestricted { }; - /** * @brief Optional. The list of other users who have access to the bot if the access is restricted */ @@ -907,12 +865,10 @@ struct BotCommand { * and underscores. */ std::string command { }; - /** * @brief Description of the command; 1-256 characters */ std::string description { }; - /** * @brief Optional. True, if the command sends an ephemeral message, which can be seen only by the * sender of the message and the bot @@ -1010,7 +966,6 @@ struct BotCommandScopeChat { * @brief Scope type, must be chat */ std::string type { TYPE }; - /** * @brief Unique identifier for the target chat or username of the target supergroup in the format * @username. Channel direct messages chats and channel chats aren't supported. @@ -1035,7 +990,6 @@ struct BotCommandScopeChatAdministrators { * @brief Scope type, must be chat_administrators */ std::string type { TYPE }; - /** * @brief Unique identifier for the target chat or username of the target supergroup in the format * @username. Channel direct messages chats and channel chats aren't supported. @@ -1060,13 +1014,11 @@ struct BotCommandScopeChatMember { * @brief Scope type, must be chat_member */ std::string type { TYPE }; - /** * @brief Unique identifier for the target chat or username of the target supergroup in the format * @username. Channel direct messages chats and channel chats aren't supported. */ std::int64_t chatId { }; - /** * @brief Unique identifier of the target user */ @@ -1155,12 +1107,10 @@ struct BotSubscriptionUpdated { * @brief User who subscribed for payments toward the bot */ std::shared_ptr user { }; - /** * @brief Bot-specified invoice payload */ std::string invoicePayload { }; - /** * @brief The new state of the subscription. Currently, it can be one of “canceled” if the user * canceled the subscription, “active” if the user re-enabled a previously canceled @@ -1184,71 +1134,58 @@ struct BusinessBotRights { * incoming messages in the last 24 hours */ std::optional canReply { }; - /** * @brief Optional. True, if the bot can mark incoming private messages as read */ std::optional canReadMessages { }; - /** * @brief Optional. True, if the bot can delete messages sent by the bot */ std::optional canDeleteSentMessages { }; - /** * @brief Optional. True, if the bot can delete all private messages in managed chats */ std::optional canDeleteAllMessages { }; - /** * @brief Optional. True, if the bot can edit the first and last name of the business account */ std::optional canEditName { }; - /** * @brief Optional. True, if the bot can edit the bio of the business account */ std::optional canEditBio { }; - /** * @brief Optional. True, if the bot can edit the profile photo of the business account */ std::optional canEditProfilePhoto { }; - /** * @brief Optional. True, if the bot can edit the username of the business account */ std::optional canEditUsername { }; - /** * @brief Optional. True, if the bot can change the privacy settings pertaining to gifts for the * business account */ std::optional canChangeGiftSettings { }; - /** * @brief Optional. True, if the bot can view gifts and the amount of Telegram Stars owned by the * business account */ std::optional canViewGiftsAndStars { }; - /** * @brief Optional. True, if the bot can convert regular gifts owned by the business account to * Telegram Stars */ std::optional canConvertGiftsToStars { }; - /** * @brief Optional. True, if the bot can transfer and upgrade gifts owned by the business account */ std::optional canTransferAndUpgradeGifts { }; - /** * @brief Optional. True, if the bot can transfer Telegram Stars received by the business account * to its own account, or use them to upgrade and transfer gifts */ std::optional canTransferStars { }; - /** * @brief Optional. True, if the bot can post, edit and delete stories on behalf of the business * account @@ -1270,12 +1207,10 @@ struct BusinessConnection { * @brief Unique identifier of the business connection */ std::string id { }; - /** * @brief Business account user that created the business connection */ std::shared_ptr user { }; - /** * @brief Identifier of a private chat with the user who created the business connection. This * number may have more than 32 significant bits and some programming languages may have @@ -1283,17 +1218,14 @@ struct BusinessConnection { * a 64-bit integer or double-precision float type are safe for storing this identifier. */ std::int64_t userChatId { }; - /** * @brief Date the connection was established in Unix time */ std::int32_t date { }; - /** * @brief Optional. Rights of the business bot */ std::shared_ptr rights { }; - /** * @brief True, if the connection is active */ @@ -1314,12 +1246,10 @@ struct BusinessIntro { * @brief Optional. Title text of the business intro */ std::optional title { }; - /** * @brief Optional. Message text of the business intro */ std::optional message { }; - /** * @brief Optional. Sticker of the business intro */ @@ -1340,7 +1270,6 @@ struct BusinessLocation { * @brief Address of the business */ std::string address { }; - /** * @brief Optional. Location of the business */ @@ -1361,13 +1290,11 @@ struct BusinessMessagesDeleted { * @brief Unique identifier of the business connection */ std::string businessConnectionId { }; - /** * @brief Information about a chat in the business account. The bot may not have access to the * chat or the corresponding user. */ std::shared_ptr chat { }; - /** * @brief The list of identifiers of deleted messages in the chat of the business account */ @@ -1388,7 +1315,6 @@ struct BusinessOpeningHours { * @brief Unique name of the time zone for which the opening hours are defined */ std::string timeZoneName { }; - /** * @brief List of time intervals describing business opening hours */ @@ -1410,7 +1336,6 @@ struct BusinessOpeningHoursInterval { * time interval during which the business is open; 0 - 7 * 24 * 60 */ std::int32_t openingMinute { }; - /** * @brief The minute's sequence number in a week, starting on Monday, marking the end of the time * interval during which the business is open; 0 - 8 * 24 * 60 @@ -1447,35 +1372,29 @@ struct CallbackQuery { * @brief Unique identifier for this query */ std::string id { }; - /** * @brief Sender */ std::shared_ptr from { }; - /** * @brief Optional. Message sent by the bot with the callback button that originated the query */ std::shared_ptr message { }; - /** * @brief Optional. Identifier of the message sent via the bot in inline mode, that originated the * query */ std::optional inlineMessageId { }; - /** * @brief Global identifier, uniquely corresponding to the chat to which the message with the * callback button was sent. Useful for high scores in games. */ std::string chatInstance { }; - /** * @brief Optional. Data associated with the callback button. Be aware that the message originated * the query can contain no callback buttons with this data. */ std::optional data { }; - /** * @brief Optional. Short name of a Game to be returned, serves as the unique identifier for the * game @@ -1502,37 +1421,30 @@ struct Chat { * type are safe for storing this identifier. */ std::int64_t id { }; - /** * @brief Type of the chat, can be either “private”, “group”, “supergroup” or “channel” */ Type type { }; - /** * @brief Optional. Title, for supergroups, channels and group chats */ std::optional title { }; - /** * @brief Optional. Username, for private chats, supergroups and channels if available */ std::optional username { }; - /** * @brief Optional. First name of the other party in a private chat */ std::optional firstName { }; - /** * @brief Optional. Last name of the other party in a private chat */ std::optional lastName { }; - /** * @brief Optional. True, if the supergroup chat is a forum (has topics enabled) */ std::optional isForum { }; - /** * @brief Optional. True, if the chat is the direct messages chat of a channel */ @@ -1556,7 +1468,6 @@ struct ChatAdministratorRights { * @brief True, if the user's presence in the chat is hidden */ bool isAnonymous { }; - /** * @brief True, if the administrator can access the chat event log, get boost list, see hidden * supergroup and channel members, report spam messages, ignore slow mode, and send @@ -1564,85 +1475,70 @@ struct ChatAdministratorRights { * privilege. */ bool canManageChat { }; - /** * @brief True, if the administrator can delete messages of other users */ bool canDeleteMessages { }; - /** * @brief True, if the administrator can manage video chats */ bool canManageVideoChats { }; - /** * @brief True, if the administrator can restrict, ban or unban chat members, or access supergroup * statistics */ bool canRestrictMembers { }; - /** * @brief True, if the administrator can add new administrators with a subset of their own * privileges or demote administrators that they have promoted, directly or indirectly * (promoted by administrators that were appointed by the user) */ bool canPromoteMembers { }; - /** * @brief True, if the user is allowed to change the chat title, photo and other settings */ bool canChangeInfo { }; - /** * @brief True, if the user is allowed to invite new users to the chat */ bool canInviteUsers { }; - /** * @brief True, if the administrator can post stories to the chat */ bool canPostStories { }; - /** * @brief True, if the administrator can edit stories posted by other users, post stories to the * chat page, pin chat stories, and access the chat's story archive */ bool canEditStories { }; - /** * @brief True, if the administrator can delete stories posted by other users */ bool canDeleteStories { }; - /** * @brief Optional. True, if the administrator can post messages in the channel, approve suggested * posts, or access channel statistics; for channels only */ std::optional canPostMessages { }; - /** * @brief Optional. True, if the administrator can edit messages of other users and can pin * messages; for channels only */ std::optional canEditMessages { }; - /** * @brief Optional. True, if the user is allowed to pin messages; for groups and supergroups only */ std::optional canPinMessages { }; - /** * @brief Optional. True, if the user is allowed to create, rename, close, and reopen forum * topics; for supergroups only */ std::optional canManageTopics { }; - /** * @brief Optional. True, if the administrator can manage direct messages of the channel and * decline suggested posts; for channels only */ std::optional canManageDirectMessages { }; - /** * @brief Optional. True, if the administrator can edit the tags of regular members; for groups * and supergroups only. If omitted, defaults to the value of can_pin_messages. @@ -1680,18 +1576,15 @@ struct ChatBoost { * @brief Unique identifier of the boost */ std::string boostId { }; - /** * @brief Point in time (Unix timestamp) when the chat was boosted */ std::int32_t addDate { }; - /** * @brief Point in time (Unix timestamp) when the boost will automatically expire, unless the * booster's Telegram Premium subscription is prolonged */ std::int32_t expirationDate { }; - /** * @brief Source of the added boost */ @@ -1728,17 +1621,14 @@ struct ChatBoostRemoved { * @brief Chat which was boosted */ std::shared_ptr chat { }; - /** * @brief Unique identifier of the boost */ std::string boostId { }; - /** * @brief Point in time (Unix timestamp) when the boost was removed */ std::int32_t removeDate { }; - /** * @brief Source of the removed boost */ @@ -1779,7 +1669,6 @@ struct ChatBoostSourceGiftCode { * @brief Source of the boost, always “gift_code” */ std::string source { SOURCE }; - /** * @brief User for which the gift code was created */ @@ -1805,25 +1694,21 @@ struct ChatBoostSourceGiveaway { * @brief Source of the boost, always “giveaway” */ std::string source { SOURCE }; - /** * @brief Identifier of a message in the chat with the giveaway; the message could have been * deleted already. May be 0 if the message isn't sent yet. */ std::int32_t giveawayMessageId { }; - /** * @brief Optional. User that won the prize in the giveaway if any; for Telegram Premium giveaways * only */ std::shared_ptr user { }; - /** * @brief Optional. The number of Telegram Stars to be split between giveaway winners; for * Telegram Star giveaways only */ std::optional prizeStarCount { }; - /** * @brief Optional. True, if the giveaway was completed, but there was no user to win the prize */ @@ -1847,7 +1732,6 @@ struct ChatBoostSourcePremium { * @brief Source of the boost, always “premium” */ std::string source { SOURCE }; - /** * @brief User that boosted the chat */ @@ -1868,7 +1752,6 @@ struct ChatBoostUpdated { * @brief Chat which was boosted */ std::shared_ptr chat { }; - /** * @brief Information about the chat boost */ @@ -1892,248 +1775,203 @@ struct ChatFullInfo { * type are safe for storing this identifier. */ std::int64_t id { }; - /** * @brief Type of the chat, can be either “private”, “group”, “supergroup” or “channel” */ std::string type { }; - /** * @brief Optional. Title, for supergroups, channels and group chats */ std::optional title { }; - /** * @brief Optional. Username, for private chats, supergroups and channels if available */ std::optional username { }; - /** * @brief Optional. First name of the other party in a private chat */ std::optional firstName { }; - /** * @brief Optional. Last name of the other party in a private chat */ std::optional lastName { }; - /** * @brief Optional. True, if the supergroup chat is a forum (has topics enabled) */ std::optional isForum { }; - /** * @brief Optional. True, if the chat is the direct messages chat of a channel */ std::optional isDirectMessages { }; - /** * @brief Identifier of the accent color for the chat name and backgrounds of the chat photo, * reply header, and link preview. See accent colors for more details. */ std::int32_t accentColorId { }; - /** * @brief The maximum number of reactions that can be set on a message in the chat */ std::int32_t maxReactionCount { }; - /** * @brief Optional. Chat photo */ std::shared_ptr photo { }; - /** * @brief Optional. If non-empty, the list of all active chat usernames; for private chats, * supergroups and channels */ std::optional> activeUsernames { }; - /** * @brief Optional. For private chats, the date of birth of the user */ std::shared_ptr birthdate { }; - /** * @brief Optional. For private chats with business accounts, the intro of the business */ std::shared_ptr businessIntro { }; - /** * @brief Optional. For private chats with business accounts, the location of the business */ std::shared_ptr businessLocation { }; - /** * @brief Optional. For private chats with business accounts, the opening hours of the business */ std::shared_ptr businessOpeningHours { }; - /** * @brief Optional. For private chats, the personal channel of the user */ std::shared_ptr personalChat { }; - /** * @brief Optional. Information about the corresponding channel chat; for direct messages chats * only */ std::shared_ptr parentChat { }; - /** * @brief Optional. List of available reactions allowed in the chat. If omitted, then all emoji * reactions are allowed. */ std::optional>> availableReactions { }; - /** * @brief Optional. Custom emoji identifier of the emoji chosen by the chat for the reply header * and link preview background */ std::optional backgroundCustomEmojiId { }; - /** * @brief Optional. Identifier of the accent color for the chat's profile background. See profile * accent colors for more details. */ std::optional profileAccentColorId { }; - /** * @brief Optional. Custom emoji identifier of the emoji chosen by the chat for its profile * background */ std::optional profileBackgroundCustomEmojiId { }; - /** * @brief Optional. Custom emoji identifier of the emoji status of the chat or the other party in * a private chat */ std::optional emojiStatusCustomEmojiId { }; - /** * @brief Optional. Expiration date of the emoji status of the chat or the other party in a * private chat, in Unix time, if any */ std::optional emojiStatusExpirationDate { }; - /** * @brief Optional. Bio of the other party in a private chat */ std::optional bio { }; - /** * @brief Optional. True, if privacy settings of the other party in the private chat allows to use * tg://user?id= links only in chats with the user */ std::optional hasPrivateForwards { }; - /** * @brief Optional. True, if the privacy settings of the other party restrict sending voice and * video note messages in the private chat */ std::optional hasRestrictedVoiceAndVideoMessages { }; - /** * @brief Optional. True, if users need to join the supergroup before they can send messages */ std::optional joinToSendMessages { }; - /** * @brief Optional. True, if all users directly joining the supergroup without using an invite * link need to be approved by supergroup administrators */ std::optional joinByRequest { }; - /** * @brief Optional. Description, for groups, supergroups and channel chats */ std::optional description { }; - /** * @brief Optional. Primary invite link, for groups, supergroups and channel chats */ std::optional inviteLink { }; - /** * @brief Optional. The most recent pinned message (by sending date) */ std::shared_ptr pinnedMessage { }; - /** * @brief Optional. Default chat member permissions, for groups and supergroups */ std::shared_ptr permissions { }; - /** * @brief Information about types of gifts that are accepted by the chat or by the corresponding * user for private chats */ std::shared_ptr acceptedGiftTypes { }; - /** * @brief Optional. True, if paid media messages can be sent or forwarded to the channel chat. The * field is available only for channel chats. */ std::optional canSendPaidMedia { }; - /** * @brief Optional. For supergroups, the minimum allowed delay between consecutive messages sent * by each unprivileged user; in seconds */ std::optional slowModeDelay { }; - /** * @brief Optional. For supergroups, the minimum number of boosts that a non-administrator user * needs to add in order to ignore slow mode and chat permissions */ std::optional unrestrictBoostCount { }; - /** * @brief Optional. The time after which all messages sent to the chat will be automatically * deleted; in seconds */ std::optional messageAutoDeleteTime { }; - /** * @brief Optional. True, if aggressive anti-spam checks are enabled in the supergroup. The field * is only available to chat administrators. */ std::optional hasAggressiveAntiSpamEnabled { }; - /** * @brief Optional. True, if non-administrators can only get the list of bots and administrators * in the chat */ std::optional hasHiddenMembers { }; - /** * @brief Optional. True, if messages from the chat can't be forwarded to other chats */ std::optional hasProtectedContent { }; - /** * @brief Optional. True, if new chat members will have access to old messages; available only to * chat administrators */ std::optional hasVisibleHistory { }; - /** * @brief Optional. For supergroups, name of the group sticker set */ std::optional stickerSetName { }; - /** * @brief Optional. True, if the bot can change the group sticker set */ std::optional canSetStickerSet { }; - /** * @brief Optional. For supergroups, the name of the group's custom emoji sticker set. Custom * emoji from this set can be used by all users and bots in the group. */ std::optional customEmojiStickerSetName { }; - /** * @brief Optional. Unique identifier for the linked chat, i.e. the discussion group identifier * for a channel and vice versa; for supergroups and channel chats. This identifier may be @@ -2142,40 +1980,33 @@ struct ChatFullInfo { * double-precision float type are safe for storing this identifier. */ std::optional linkedChatId { }; - /** * @brief Optional. For supergroups, the location to which the supergroup is connected */ std::shared_ptr location { }; - /** * @brief Optional. For private chats, the rating of the user if any */ std::shared_ptr rating { }; - /** * @brief Optional. For private chats, the first audio added to the profile of the user */ std::shared_ptr