Laniakea/tgapi/games_methods.go

package tgapi

import "context"

// SendGame holds parameters for the sendGame method.
// Since: Bot API 2.2
// See https://core.telegram.org/bots/api#sendgame
type SendGame struct {
	// BusinessConnectionID Optional. Unique identifier of the business connection on behalf of which the
	// message will be sent
	BusinessConnectionID string `json:"business_connection_id,omitempty"`
	// ChatID Required. Unique identifier for the target chat or username of the target bot in the format
	// @username. Games can't be sent to channel direct messages chats and channel chats.
	ChatID int64 `json:"chat_id"`
	// MessageThreadID Optional. Unique identifier for the target message thread (topic) of a forum; for forum
	// supergroups and private chats of bots with forum topic mode enabled only
	MessageThreadID int `json:"message_thread_id,omitempty"`

	// GameShortName Required. Short name of the game, serves as the unique identifier for the game. Set up your
	// games via @BotFather.
	GameShortName string `json:"game_short_name"`

	// DisableNotification Optional. Sends the message silently. Users will receive a notification with no
	// sound.
	DisableNotification bool `json:"disable_notification,omitempty"`
	// ProtectContent Optional. Protects the contents of the sent message from forwarding and saving
	ProtectContent bool `json:"protect_content,omitempty"`
	// AllowPaidBroadcast Optional. Pass True to allow up to 1000 messages per second, ignoring broadcasting
	// limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot's
	// balance.
	AllowPaidBroadcast bool `json:"allow_paid_broadcast,omitempty"`
	// MessageEffectID Optional. Unique identifier of the message effect to be added to the message; for private
	// chats only
	MessageEffectID string `json:"message_effect_id,omitempty"`
	// ReplyParameters Optional. Description of the message to reply to
	ReplyParameters *ReplyParameters `json:"reply_parameters,omitempty"`
	// ReplyMarkup Optional. A JSON-serialized object for an inline keyboard. If empty, one 'Play game_title'
	// button will be shown. If not empty, the first button must launch the game.
	ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
}

// SendGame sends a game message.
// Since: Bot API 2.2
// See https://core.telegram.org/bots/api#sendgame
func (api *API) SendGame(params SendGame) (Message, error) {
	req := NewRequestWithChatID[Message]("sendGame", params, params.ChatID)
	return req.Do(api)
}

// SendGameWithContext is the context-aware variant of SendGame.
// Since: Bot API 2.2
// It executes the same request but uses ctx for cancellation and deadlines.
// See https://core.telegram.org/bots/api#sendgame
func (api *API) SendGameWithContext(ctx context.Context, params SendGame) (Message, error) {
	req := NewRequestWithChatID[Message]("sendGame", params, params.ChatID)
	return req.DoWithContext(ctx, api)
}

// SetGameScore holds parameters for the setGameScore method.
// Since: Bot API 2.2
// See https://core.telegram.org/bots/api#setgamescore
type SetGameScore struct {
	// UserID Required. User identifier
	UserID int64 `json:"user_id"`
	// Score Required. New score, must be non-negative
	Score int `json:"score"`
	// Force Optional. Pass True if the high score is allowed to decrease. This can be useful when fixing
	// mistakes or banning cheaters.
	Force bool `json:"force,omitempty"`
	// DisableEditMessage Optional. Pass True if the game message should not be automatically edited to include
	// the current scoreboard
	DisableEditMessage bool `json:"disable_edit_message,omitempty"`
	// ChatID Optional. Required if inline_message_id is not specified. Unique identifier for the target chat.
	ChatID int64 `json:"chat_id,omitempty"`
	// MessageID Optional. Required if inline_message_id is not specified. Identifier of the sent message.
	MessageID int `json:"message_id,omitempty"`
	// InlineMessageID Optional. Required if chat_id and message_id are not specified. Identifier of the inline
	// message.
	InlineMessageID string `json:"inline_message_id,omitempty"`
}

// SetGameScore sets a user's score in a game message.
// Since: Bot API 2.2
// If inline_message_id is provided, returns a boolean success flag.
// Otherwise returns the edited Message.
// See https://core.telegram.org/bots/api#setgamescore
func (api *API) SetGameScore(params SetGameScore) (Message, bool, error) {
	var zero Message
	if params.InlineMessageID != "" {
		req := NewRequestWithChatID[bool]("setGameScore", params, params.ChatID)
		res, err := req.Do(api)
		return zero, res, err
	}
	req := NewRequestWithChatID[Message]("setGameScore", params, params.ChatID)
	res, err := req.Do(api)
	return res, false, err
}

// SetGameScoreWithContext is the context-aware variant of SetGameScore.
// Since: Bot API 2.2
// It executes the same request but uses ctx for cancellation and deadlines.
// See https://core.telegram.org/bots/api#setgamescore
func (api *API) SetGameScoreWithContext(ctx context.Context, params SetGameScore) (Message, bool, error) {
	var zero Message
	if params.InlineMessageID != "" {
		req := NewRequestWithChatID[bool]("setGameScore", params, params.ChatID)
		res, err := req.DoWithContext(ctx, api)
		return zero, res, err
	}
	req := NewRequestWithChatID[Message]("setGameScore", params, params.ChatID)
	res, err := req.DoWithContext(ctx, api)
	return res, false, err
}

// GetGameHighScores holds parameters for the getGameHighScores method.
// Since: Bot API 2.2
// See https://core.telegram.org/bots/api#getgamehighscores
type GetGameHighScores struct {
	// UserID Required. Target user id
	UserID int64 `json:"user_id"`
	// ChatID Optional. Required if inline_message_id is not specified. Unique identifier for the target chat.
	ChatID int64 `json:"chat_id,omitempty"`
	// MessageID Optional. Required if inline_message_id is not specified. Identifier of the sent message.
	MessageID int `json:"message_id,omitempty"`
	// InlineMessageID Optional. Required if chat_id and message_id are not specified. Identifier of the inline
	// message.
	InlineMessageID string `json:"inline_message_id,omitempty"`
}

// GetGameHighScores returns game high score data for a user.
// Since: Bot API 2.2
// See https://core.telegram.org/bots/api#getgamehighscores
func (api *API) GetGameHighScores(params GetGameHighScores) ([]GameHighScore, error) {
	req := NewRequestWithChatID[[]GameHighScore]("getGameHighScores", params, params.ChatID)
	return req.Do(api)
}

// GetGameHighScoresWithContext is the context-aware variant of GetGameHighScores.
// Since: Bot API 2.2
// It executes the same request but uses ctx for cancellation and deadlines.
// See https://core.telegram.org/bots/api#getgamehighscores
func (api *API) GetGameHighScoresWithContext(ctx context.Context, params GetGameHighScores) ([]GameHighScore, error) {
	req := NewRequestWithChatID[[]GameHighScore]("getGameHighScores", params, params.ChatID)
	return req.DoWithContext(ctx, api)
}