From d6e2daec04c4b3f49f26f5e4a7ab461a24e63e0c Mon Sep 17 00:00:00 2001 From: ScuroNeko Date: Thu, 12 Mar 2026 17:45:53 +0300 Subject: [PATCH] v1.0.0 beta 15 --- bot.go | 36 ++++---- cmd_generator.go | 22 ++++- drafts.go | 2 +- examples/basic/go.mod | 4 +- handler.go | 33 ++++++- keyboard.go | 61 ++++++++++--- msg_context.go | 1 + plugins.go | 29 +++++-- tgapi/attachments_methods.go | 36 ++++++++ tgapi/attachments_types.go | 35 +++++--- tgapi/bot_methods.go | 80 +++++++++++++++++ tgapi/bot_types.go | 49 ++++++++--- tgapi/business_methods.go | 112 +++++++++++++++++++++++- tgapi/business_types.go | 55 ++++++++++-- tgapi/chat_methods.go | 164 ++++++++++++++++++++++++++++++++++- tgapi/chat_types.go | 33 ++++++- tgapi/forum_methods.go | 53 +++++++++++ tgapi/forum_types.go | 6 ++ tgapi/messages_methods.go | 140 +++++++++++++++++++++++++++--- tgapi/messages_types.go | 55 +++++++++++- tgapi/methods.go | 31 ++++++- tgapi/stickers_methods.go | 78 ++++++++++++++++- tgapi/stickers_types.go | 37 ++++++-- tgapi/types.go | 125 +++++++++++++++++++++----- tgapi/uploader_methods.go | 40 +++++++++ tgapi/users_methods.go | 17 ++++ tgapi/users_types.go | 12 +++ utils/version.go | 4 +- 28 files changed, 1224 insertions(+), 126 deletions(-) diff --git a/bot.go b/bot.go index 673db98..5a41045 100644 --- a/bot.go +++ b/bot.go @@ -25,7 +25,6 @@ // AddL10n(l10n.New()) // // go bot.Run() -// <-ctx.Done() // wait for shutdown signal // // All methods are thread-safe except direct field access. Use provided accessors // (e.g., GetDBContext, SetUpdateOffset) for safe concurrent access. @@ -170,6 +169,16 @@ type DbContext interface{} // Use Bot[NoDB] to indicate no dependency injection is required. type NoDB struct{ DbContext } +// BotPayloadType defines the serialization format for callback data payloads. +type BotPayloadType string + +var ( + // BotPayloadBase64 encodes callback data as a Base64 string. + BotPayloadBase64 BotPayloadType = "base64" + // BotPayloadJson encodes callback data as a JSON string. + BotPayloadJson BotPayloadType = "json" +) + // Bot is the core Telegram bot instance. // // Manages: @@ -185,6 +194,7 @@ type Bot[T DbContext] struct { debug bool errorTemplate string username string + payloadType BotPayloadType logger *slog.Logger // Main bot logger (JSON stdout + optional file) RequestLogger *slog.Logger // Optional request-level API logging @@ -430,6 +440,14 @@ func (bot *Bot[T]) UpdateTypes(t ...tgapi.UpdateType) *Bot[T] { return bot } +// SetPayloadType sets the type, that bot will use for payload +// json - string `{"cmd": "command", "args": [...]} +// base64 - same json, but encoded in base64 string +func (bot *Bot[T]) SetPayloadType(t BotPayloadType) *Bot[T] { + bot.payloadType = t + return bot +} + // AddUpdateType adds one or more update types to the list. // Does not overwrite existing types. func (bot *Bot[T]) AddUpdateType(t ...tgapi.UpdateType) *Bot[T] { @@ -550,22 +568,6 @@ func (bot *Bot[T]) AddL10n(l *L10n) *Bot[T] { return bot } -// enqueueUpdate attempts to add an update to the internal processing queue. -// -// Returns extypes.QueueFullErr if the queue is full and the update cannot be enqueued. -// This is non-blocking and used to implement rate-limiting behavior. -// -// When DropRLOverflow is enabled, this error is ignored and the update is dropped. -// Otherwise, the update is retried via the main update loop. -func (bot *Bot[T]) enqueueUpdate(u *tgapi.Update) error { - select { - case bot.updateQueue <- u: - return nil - default: - return extypes.QueueFullErr - } -} - // RunWithContext starts the bot with a given context for graceful shutdown. // // This is the main entry point for bot execution. It: diff --git a/cmd_generator.go b/cmd_generator.go index 183d4e2..3f797ad 100644 --- a/cmd_generator.go +++ b/cmd_generator.go @@ -12,11 +12,14 @@ package laniakea import ( "errors" "fmt" + "regexp" "strings" "git.nix13.pw/scuroneko/laniakea/tgapi" ) +var CmdRegexp = regexp.MustCompile("^[a-zA-Z0-9]+$") + // ErrTooManyCommands is returned when the total number of registered commands // exceeds Telegram's limit of 100 bot commands per bot. // @@ -38,8 +41,8 @@ var ErrTooManyCommands = errors.New("too many commands. max 100") // // Command{command: "start", description: "Start the bot", args: []Arg{{text: "name", required: false}}} // → Description: "Start the bot. Usage: /start [name]" -func generateBotCommand[T any](cmd Command[T]) tgapi.BotCommand { - desc := cmd.command +func generateBotCommand[T any](cmd *Command[T]) tgapi.BotCommand { + desc := "" if len(cmd.description) > 0 { desc = cmd.description } @@ -53,10 +56,20 @@ func generateBotCommand[T any](cmd Command[T]) tgapi.BotCommand { } } - desc = fmt.Sprintf("%s. Usage: /%s %s", desc, cmd.command, strings.Join(descArgs, " ")) + if desc != "" { + desc = fmt.Sprintf("%s. Usage: /%s %s", desc, cmd.command, strings.Join(descArgs, " ")) + } else { + desc = fmt.Sprintf("Usage: /%s %s", cmd.command, strings.Join(descArgs, " ")) + } return tgapi.BotCommand{Command: cmd.command, Description: desc} } +// checkCmdRegex check if command satisfy regexp [a-zA-Z0-9]+ +// Return true if satisfy, else false. +func checkCmdRegex(cmd string) bool { + return CmdRegexp.MatchString(cmd) +} + // generateBotCommandForPlugin collects all non-skipped commands from a Plugin[T] // and converts them into tgapi.BotCommand objects. // @@ -69,6 +82,9 @@ func generateBotCommandForPlugin[T any](pl Plugin[T]) []tgapi.BotCommand { if cmd.skipAutoCmd { continue } + if !checkCmdRegex(cmd.command) { + continue + } commands = append(commands, generateBotCommand(cmd)) } return commands diff --git a/drafts.go b/drafts.go index 3de0784..e9d93f2 100644 --- a/drafts.go +++ b/drafts.go @@ -13,9 +13,9 @@ // Example usage: // // provider := laniakea.NewRandomDraftProvider(api) -// provider.SetChat(-1001234567890, 0).SetParseMode(tgapi.ParseModeHTML) // // draft := provider.NewDraft(tgapi.ParseModeMarkdown) +// draft.SetChat(-1001234567890, 0) // draft.Push("*Hello*").Push(" **world**!") // err := draft.Flush() // Sends message and deletes draft // if err != nil { diff --git a/examples/basic/go.mod b/examples/basic/go.mod index 19feb1a..e957faf 100644 --- a/examples/basic/go.mod +++ b/examples/basic/go.mod @@ -2,10 +2,10 @@ module example/basic go 1.26.1 -require git.nix13.pw/scuroneko/laniakea v1.0.0-beta.13 +require git.nix13.pw/scuroneko/laniakea v1.0.0-beta.14 replace ( - git.nix13.pw/scuroneko/laniakea v1.0.0-beta.13 => ../../ + git.nix13.pw/scuroneko/laniakea v1.0.0-beta.14 => ../../ ) require ( diff --git a/handler.go b/handler.go index bdf0133..a9730eb 100644 --- a/handler.go +++ b/handler.go @@ -3,11 +3,14 @@ package laniakea import ( "encoding/base64" "encoding/json" + "errors" "strings" "git.nix13.pw/scuroneko/laniakea/tgapi" ) +var ErrInvalidPayloadType = errors.New("invalid payload type") + func (bot *Bot[T]) handle(u *tgapi.Update) { ctx := &MsgContext{ Update: *u, Api: bot.api, @@ -15,6 +18,7 @@ func (bot *Bot[T]) handle(u *tgapi.Update) { errorTemplate: bot.errorTemplate, l10n: bot.l10n, draftProvider: bot.draftProvider, + payloadType: bot.payloadType, } for _, middleware := range bot.middlewares { middleware.Execute(ctx, bot.dbContext) @@ -87,8 +91,7 @@ func (bot *Bot[T]) handleMessage(update *tgapi.Update, ctx *MsgContext) { } func (bot *Bot[T]) handleCallback(update *tgapi.Update, ctx *MsgContext) { - data := new(CallbackData) - err := json.Unmarshal([]byte(update.CallbackQuery.Data), data) + data, err := bot.decodePayload(update.CallbackQuery.Data) if err != nil { bot.logger.Errorln(err) return @@ -152,3 +155,29 @@ func decodeBase64Payload(s string) (CallbackData, error) { } return decodeJsonPayload(string(b)) } + +// func encodePayload(payloadType BotPayloadType, d CallbackData) (string, error) { +// switch payloadType { +// case BotPayloadBase64: +// return encodeBase64Payload(d) +// case BotPayloadJson: +// return encodeJsonPayload(d) +// } +// return "", ErrInvalidPayloadType +// } +func decodePayload(payloadType BotPayloadType, s string) (CallbackData, error) { + switch payloadType { + case BotPayloadBase64: + return decodeBase64Payload(s) + case BotPayloadJson: + return decodeJsonPayload(s) + } + return CallbackData{}, ErrInvalidPayloadType +} + +// func (bot *Bot[T]) encodePayload(d CallbackData) (string, error) { +// return encodePayload(bot.payloadType, d) +// } +func (bot *Bot[T]) decodePayload(s string) (CallbackData, error) { + return decodePayload(bot.payloadType, s) +} diff --git a/keyboard.go b/keyboard.go index 7f8883c..6890a97 100644 --- a/keyboard.go +++ b/keyboard.go @@ -11,7 +11,6 @@ package laniakea import ( - "encoding/json" "fmt" "git.nix13.pw/scuroneko/extypes" @@ -34,7 +33,7 @@ const ( // - SetIconCustomEmojiId() — adds a custom emoji icon // - SetStyle() — sets visual style (danger/success/primary) // - SetUrl() — makes button open a URL -// - SetCallbackData() — attaches structured command + args for bot handling +// - SetCallbackDataJson() — attaches structured command + args for bot handling // // Call build() to produce the final tgapi.InlineKeyboardButton. // Builder methods are immutable — each returns a copy. @@ -74,18 +73,26 @@ func (b InlineKbButtonBuilder) SetUrl(url string) InlineKbButtonBuilder { return b } -// SetCallbackData sets a structured callback payload that will be sent to the bot +// SetCallbackDataJson sets a structured callback payload that will be sent to the bot // when the button is pressed. The command and arguments are serialized as JSON. // // Args are converted to strings using fmt.Sprint. Non-string types (e.g., int, bool) // are safely serialized, but complex structs may not serialize usefully. // -// Example: SetCallbackData("delete_user", 123, "confirm") → {"cmd":"delete_user","args":["123","confirm"]} -func (b InlineKbButtonBuilder) SetCallbackData(cmd string, args ...any) InlineKbButtonBuilder { +// Example: SetCallbackDataJson("delete_user", 123, "confirm") → {"cmd":"delete_user","args":["123","confirm"]} +func (b InlineKbButtonBuilder) SetCallbackDataJson(cmd string, args ...any) InlineKbButtonBuilder { b.callbackData = NewCallbackData(cmd, args...).ToJson() return b } +// SetCallbackDataBase64 sets a structured callback payload encoded as Base64. +// This can be useful when the JSON payload exceeds Telegram's callback data length limit. +// Args are converted to strings using fmt.Sprint. +func (b InlineKbButtonBuilder) SetCallbackDataBase64(cmd string, args ...any) InlineKbButtonBuilder { + b.callbackData = NewCallbackData(cmd, args...).ToBase64() + return b +} + // build converts the builder state into a tgapi.InlineKeyboardButton. // This method is typically called internally by InlineKeyboard.AddButton(). func (b InlineKbButtonBuilder) build() tgapi.InlineKeyboardButton { @@ -108,6 +115,8 @@ type InlineKeyboard struct { CurrentLine extypes.Slice[tgapi.InlineKeyboardButton] // Current row being built Lines [][]tgapi.InlineKeyboardButton // Completed rows maxRow int // Max buttons per row (e.g., 3 or 4) + + payloadType BotPayloadType // Serialization format for callback data (JSON or Base64) } // NewInlineKeyboard creates a new keyboard builder with the specified maximum @@ -119,9 +128,18 @@ func NewInlineKeyboard(maxRow int) *InlineKeyboard { CurrentLine: make(extypes.Slice[tgapi.InlineKeyboardButton], 0), Lines: make([][]tgapi.InlineKeyboardButton, 0), maxRow: maxRow, + payloadType: BotPayloadBase64, } } +// SetPayloadType sets the serialization format for callback data added via +// AddCallbackButton and AddCallbackButtonStyle methods. +// It should be one of BotPayloadJson or BotPayloadBase64. +func (in *InlineKeyboard) SetPayloadType(t BotPayloadType) *InlineKeyboard { + in.payloadType = t + return in +} + // append adds a button to the current line. If the line is full, it auto-flushes. // This is an internal helper used by other builder methods. func (in *InlineKeyboard) append(button tgapi.InlineKeyboardButton) *InlineKeyboard { @@ -145,11 +163,11 @@ func (in *InlineKeyboard) AddUrlButtonStyle(text string, style tgapi.KeyboardBut } // AddCallbackButton adds a button that sends a structured callback payload to the bot. -// The command and args are serialized as JSON using NewCallbackData. +// The command and args are serialized according to the current payloadType. func (in *InlineKeyboard) AddCallbackButton(text string, cmd string, args ...any) *InlineKeyboard { return in.append(tgapi.InlineKeyboardButton{ Text: text, - CallbackData: NewCallbackData(cmd, args...).ToJson(), + CallbackData: NewCallbackData(cmd, args...).Encode(in.payloadType), }) } @@ -159,7 +177,7 @@ func (in *InlineKeyboard) AddCallbackButtonStyle(text string, style tgapi.Keyboa return in.append(tgapi.InlineKeyboardButton{ Text: text, Style: style, - CallbackData: NewCallbackData(cmd, args...).ToJson(), + CallbackData: NewCallbackData(cmd, args...).Encode(in.payloadType), }) } @@ -230,10 +248,33 @@ func NewCallbackData(command string, args ...any) *CallbackData { // This fallback ensures the bot receives a valid JSON payload even if internal // errors occur — avoiding "invalid callback_data" errors from Telegram. func (d *CallbackData) ToJson() string { - data, err := json.Marshal(d) + data, err := encodeJsonPayload(*d) if err != nil { // Fallback: return minimal valid JSON to avoid Telegram API rejection return `{"cmd":""}` } - return string(data) + return data +} + +// ToBase64 serializes the CallbackData to a JSON string and then encodes it as Base64. +// Returns an empty string if serialization or encoding fails. +func (d *CallbackData) ToBase64() string { + s, err := encodeBase64Payload(*d) + if err != nil { + return `` + } + return s +} + +// Encode serializes the CallbackData according to the specified payload type. +// Supported types: BotPayloadJson and BotPayloadBase64. +// For unknown types, returns an empty string. +func (d *CallbackData) Encode(t BotPayloadType) string { + switch t { + case BotPayloadBase64: + return d.ToBase64() + case BotPayloadJson: + return d.ToJson() + } + return "" } diff --git a/msg_context.go b/msg_context.go index 0798deb..276df29 100644 --- a/msg_context.go +++ b/msg_context.go @@ -46,6 +46,7 @@ type MsgContext struct { botLogger *slog.Logger l10n *L10n draftProvider *DraftProvider + payloadType BotPayloadType } // AnswerMessage represents a message sent or edited via MsgContext. diff --git a/plugins.go b/plugins.go index b2b230a..6255fe2 100644 --- a/plugins.go +++ b/plugins.go @@ -94,7 +94,13 @@ type Command[T DbContext] struct { // NewCommand creates a new Command with the given executor, command string, and arguments. // The command string should not include the leading slash (e.g., "start", not "/start"). func NewCommand[T any](exec CommandExecutor[T], command string, args ...CommandArg) *Command[T] { - return &Command[T]{command, "", exec, extypes.Slice[CommandArg](args), make(extypes.Slice[Middleware[T]], 0), false} + return &Command[T]{command, "", exec, args, make(extypes.Slice[Middleware[T]], 0), false} +} + +// NewPayload creates a new Command with the given executor, command payload string, and arguments. +// The command string can POTENTIALLY contain any symbols, but recommended to use only "_", "-", ".", a-Z, 0-9 +func NewPayload[T any](exec CommandExecutor[T], command string, args ...CommandArg) *Command[T] { + return &Command[T]{command, "", exec, args, make(extypes.Slice[Middleware[T]], 0), false} } // Use adds a middleware to the command's execution chain. @@ -147,8 +153,8 @@ func (c *Command[T]) validateArgs(args []string) error { // with shared middleware and configuration. type Plugin[T DbContext] struct { name string // Name of the plugin (e.g., "admin", "user") - commands map[string]Command[T] // Registered commands (triggered by message) - payloads map[string]Command[T] // Registered payloads (triggered by callback data) + commands map[string]*Command[T] // Registered commands (triggered by message) + payloads map[string]*Command[T] // Registered payloads (triggered by callback data) middlewares extypes.Slice[Middleware[T]] // Shared middlewares for all commands/payloads skipAutoCmd bool // If true, all commands in this plugin are excluded from auto-help } @@ -156,15 +162,15 @@ type Plugin[T DbContext] struct { // NewPlugin creates a new Plugin with the given name. func NewPlugin[T DbContext](name string) *Plugin[T] { return &Plugin[T]{ - name, make(map[string]Command[T]), - make(map[string]Command[T]), extypes.Slice[Middleware[T]]{}, false, + name, make(map[string]*Command[T]), + make(map[string]*Command[T]), extypes.Slice[Middleware[T]]{}, false, } } // AddCommand registers a command in the plugin. // The command's .command field is used as the key. func (p *Plugin[T]) AddCommand(command *Command[T]) *Plugin[T] { - p.commands[command.command] = *command + p.commands[command.command] = command return p } @@ -172,16 +178,25 @@ func (p *Plugin[T]) AddCommand(command *Command[T]) *Plugin[T] { // Returns the created command for further configuration. func (p *Plugin[T]) NewCommand(exec CommandExecutor[T], command string, args ...CommandArg) *Command[T] { cmd := NewCommand(exec, command, args...) + p.AddCommand(cmd) return cmd } // AddPayload registers a payload (e.g., callback query data) in the plugin. // Payloads are triggered by inline button callback_data, not by message text. func (p *Plugin[T]) AddPayload(command *Command[T]) *Plugin[T] { - p.payloads[command.command] = *command + p.payloads[command.command] = command return p } +// NewPayload creates and immediately adds a new payload command to the plugin. +// Returns the created payload command for further configuration. +func (p *Plugin[T]) NewPayload(exec CommandExecutor[T], command string, args ...CommandArg) *Command[T] { + cmd := NewPayload(exec, command, args...) + p.AddPayload(cmd) + return cmd +} + // AddMiddleware adds a middleware to the plugin's global middleware chain. // Middlewares are executed before any command or payload. func (p *Plugin[T]) AddMiddleware(middleware Middleware[T]) *Plugin[T] { diff --git a/tgapi/attachments_methods.go b/tgapi/attachments_methods.go index 1a1bfb1..9e7222a 100644 --- a/tgapi/attachments_methods.go +++ b/tgapi/attachments_methods.go @@ -1,5 +1,7 @@ package tgapi +// SendPhotoP holds parameters for the sendPhoto method. +// See https://core.telegram.org/bots/api#sendphoto type SendPhotoP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -23,11 +25,15 @@ type SendPhotoP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendPhoto sends a photo. +// See https://core.telegram.org/bots/api#sendphoto func (api *API) SendPhoto(params SendPhotoP) (Message, error) { req := NewRequestWithChatID[Message]("sendPhoto", params, params.ChatID) return req.Do(api) } +// SendAudioP holds parameters for the sendAudio method. +// See https://core.telegram.org/bots/api#sendaudio type SendAudioP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -52,11 +58,15 @@ type SendAudioP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendAudio sends an audio file. +// See https://core.telegram.org/bots/api#sendaudio func (api *API) SendAudio(params SendAudioP) (Message, error) { req := NewRequestWithChatID[Message]("sendAudio", params, params.ChatID) return req.Do(api) } +// SendDocumentP holds parameters for the sendDocument method. +// See https://core.telegram.org/bots/api#senddocument type SendDocumentP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -78,11 +88,15 @@ type SendDocumentP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendDocument sends a document. +// See https://core.telegram.org/bots/api#senddocument func (api *API) SendDocument(params SendDocumentP) (Message, error) { req := NewRequestWithChatID[Message]("sendDocument", params, params.ChatID) return req.Do(api) } +// SendVideoP holds parameters for the sendVideo method. +// See https://core.telegram.org/bots/api#sendvideo type SendVideoP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -113,11 +127,15 @@ type SendVideoP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendVideo sends a video. +// See https://core.telegram.org/bots/api#sendvideo func (api *API) SendVideo(params SendVideoP) (Message, error) { req := NewRequestWithChatID[Message]("sendVideo", params, params.ChatID) return req.Do(api) } +// SendAnimationP holds parameters for the sendAnimation method. +// See https://core.telegram.org/bots/api#sendanimation type SendAnimationP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -144,11 +162,15 @@ type SendAnimationP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendAnimation sends an animation file (GIF or H.264/MPEG-4 AVC video without sound). +// See https://core.telegram.org/bots/api#sendanimation func (api *API) SendAnimation(params SendAnimationP) (Message, error) { req := NewRequestWithChatID[Message]("sendAnimation", params, params.ChatID) return req.Do(api) } +// SendVoiceP holds parameters for the sendVoice method. +// See https://core.telegram.org/bots/api#sendvoice type SendVoiceP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -170,11 +192,15 @@ type SendVoiceP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendVoice sends a voice note. +// See https://core.telegram.org/bots/api#sendvoice func (api *API) SendVoice(params *SendVoiceP) (Message, error) { req := NewRequestWithChatID[Message]("sendVoice", params, params.ChatID) return req.Do(api) } +// SendVideoNoteP holds parameters for the sendVideoNote method. +// See https://core.telegram.org/bots/api#sendvideonote type SendVideoNoteP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -194,11 +220,15 @@ type SendVideoNoteP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendVideoNote sends a video note (rounded video message). +// See https://core.telegram.org/bots/api#sendvideonote func (api *API) SendVideoNote(params SendVideoNoteP) (Message, error) { req := NewRequestWithChatID[Message]("sendVideoNote", params, params.ChatID) return req.Do(api) } +// SendPaidMediaP holds parameters for the sendPaidMedia method. +// See https://core.telegram.org/bots/api#sendpaidmedia type SendPaidMediaP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -221,11 +251,15 @@ type SendPaidMediaP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendPaidMedia sends paid media. +// See https://core.telegram.org/bots/api#sendpaidmedia func (api *API) SendPaidMedia(params SendPaidMediaP) (Message, error) { req := NewRequestWithChatID[Message]("sendPaidMedia", params, params.ChatID) return req.Do(api) } +// SendMediaGroupP holds parameters for the sendMediaGroup method. +// See https://core.telegram.org/bots/api#sendmediagroup type SendMediaGroupP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -240,6 +274,8 @@ type SendMediaGroupP struct { ReplyParameters *ReplyParameters `json:"reply_parameters,omitempty"` } +// SendMediaGroup sends a group of photos, videos, documents or audios as an album. +// See https://core.telegram.org/bots/api#sendmediagroup func (api *API) SendMediaGroup(params SendMediaGroupP) (Message, error) { req := NewRequestWithChatID[Message]("sendMediaGroup", params, params.ChatID) return req.Do(api) diff --git a/tgapi/attachments_types.go b/tgapi/attachments_types.go index 89dc0ef..37cc19d 100644 --- a/tgapi/attachments_types.go +++ b/tgapi/attachments_types.go @@ -1,5 +1,23 @@ package tgapi +// InputMediaType represents the type of input media. +type InputMediaType string + +const ( + // InputMediaTypeAnimation is a GIF or H.264/MPEG-4 AVC video without sound. + InputMediaTypeAnimation InputMediaType = "animation" + // InputMediaTypeDocument is a general file. + InputMediaTypeDocument InputMediaType = "document" + // InputMediaTypePhoto is a photo. + InputMediaTypePhoto InputMediaType = "photo" + // InputMediaTypeVideo is a video. + InputMediaTypeVideo InputMediaType = "video" + // InputMediaTypeAudio is an audio file. + InputMediaTypeAudio InputMediaType = "audio" +) + +// InputMedia represents the content of a media message to be sent. +// It is a union type described in https://core.telegram.org/bots/api#inputmedia. type InputMedia struct { Type InputMediaType `json:"type"` Media string `json:"media"` @@ -21,23 +39,18 @@ type InputMedia struct { Title *string `json:"title,omitempty"` } -type InputMediaType string - -const ( - InputMediaTypeAnimation InputMediaType = "animation" - InputMediaTypeDocument InputMediaType = "document" - InputMediaTypePhoto InputMediaType = "photo" - InputMediaTypeVideo InputMediaType = "video" - InputMediaTypeAudio InputMediaType = "audio" -) - +// InputPaidMediaType represents the type of paid media. type InputPaidMediaType string const ( + // InputPaidMediaTypeVideo represents a paid video. InputPaidMediaTypeVideo InputPaidMediaType = "video" + // InputPaidMediaTypePhoto represents a paid photo. InputPaidMediaTypePhoto InputPaidMediaType = "photo" ) +// InputPaidMedia describes the paid media to be sent. +// See https://core.telegram.org/bots/api#inputpaidmedia type InputPaidMedia struct { Type InputPaidMediaType `json:"type"` Media string `json:"media"` @@ -50,6 +63,8 @@ type InputPaidMedia struct { SupportsStreaming bool `json:"supports_streaming"` } +// PhotoSize represents one size of a photo or a file/sticker thumbnail. +// See https://core.telegram.org/bots/api#photosize type PhotoSize struct { FileID string `json:"file_id"` FileUniqueID string `json:"file_unique_id"` diff --git a/tgapi/bot_methods.go b/tgapi/bot_methods.go index 2487f5e..8946794 100644 --- a/tgapi/bot_methods.go +++ b/tgapi/bot_methods.go @@ -1,149 +1,221 @@ package tgapi +// SetMyCommandsP holds parameters for the setMyCommands method. +// See https://core.telegram.org/bots/api#setmycommands type SetMyCommandsP struct { Commands []BotCommand `json:"commands"` Scope *BotCommandScope `json:"scope,omitempty"` Language string `json:"language_code,omitempty"` } +// SetMyCommands changes the list of the bot's commands. +// Returns true on success. +// See https://core.telegram.org/bots/api#setmycommands func (api *API) SetMyCommands(params SetMyCommandsP) (bool, error) { req := NewRequest[bool]("setMyCommands", params) return req.Do(api) } +// DeleteMyCommandsP holds parameters for the deleteMyCommands method. +// See https://core.telegram.org/bots/api#deletemycommands type DeleteMyCommandsP struct { Scope *BotCommandScope `json:"scope,omitempty"` Language string `json:"language_code,omitempty"` } +// DeleteMyCommands deletes the list of the bot's commands for the given scope and user language. +// Returns true on success. +// See https://core.telegram.org/bots/api#deletemycommands func (api *API) DeleteMyCommands(params DeleteMyCommandsP) (bool, error) { req := NewRequest[bool]("deleteMyCommands", params) return req.Do(api) } +// GetMyCommands holds parameters for the getMyCommands method. +// See https://core.telegram.org/bots/api#getmycommands type GetMyCommands struct { Scope *BotCommandScope `json:"scope,omitempty"` Language string `json:"language_code,omitempty"` } +// GetMyCommands returns the current list of the bot's commands for the given scope and user language. +// See https://core.telegram.org/bots/api#getmycommands func (api *API) GetMyCommands(params GetMyCommands) ([]BotCommand, error) { req := NewRequest[[]BotCommand]("getMyCommands", params) return req.Do(api) } +// SetMyName holds parameters for the setMyName method. +// See https://core.telegram.org/bots/api#setmyname type SetMyName struct { Name string `json:"name"` Language string `json:"language_code,omitempty"` } +// SetMyName changes the bot's name. +// Returns true on success. +// See https://core.telegram.org/bots/api#setmyname func (api *API) SetMyName(params SetMyName) (bool, error) { req := NewRequest[bool]("setMyName", params) return req.Do(api) } +// GetMyName holds parameters for the getMyName method. +// See https://core.telegram.org/bots/api#getmyname type GetMyName struct { Language string `json:"language_code,omitempty"` } +// GetMyName returns the bot's name for the given language. +// See https://core.telegram.org/bots/api#getmyname func (api *API) GetMyName(params GetMyName) (BotName, error) { req := NewRequest[BotName]("getMyName", params) return req.Do(api) } +// SetMyDescription holds parameters for the setMyDescription method. +// See https://core.telegram.org/bots/api#setmydescription type SetMyDescription struct { Description string `json:"description"` Language string `json:"language_code,omitempty"` } +// SetMyDescription changes the bot's description. +// Returns true on success. +// See https://core.telegram.org/bots/api#setmydescription func (api *API) SetMyDescription(params SetMyDescription) (bool, error) { req := NewRequest[bool]("setMyDescription", params) return req.Do(api) } +// GetMyDescription holds parameters for the getMyDescription method. +// See https://core.telegram.org/bots/api#getmydescription type GetMyDescription struct { Language string `json:"language_code,omitempty"` } +// GetMyDescription returns the bot's description for the given language. +// See https://core.telegram.org/bots/api#getmydescription func (api *API) GetMyDescription(params GetMyDescription) (BotDescription, error) { req := NewRequest[BotDescription]("getMyDescription", params) return req.Do(api) } +// SetMyShortDescription holds parameters for the setMyShortDescription method. +// See https://core.telegram.org/bots/api#setmyshortdescription type SetMyShortDescription struct { ShortDescription string `json:"short_description,omitempty"` Language string `json:"language_code,omitempty"` } +// SetMyShortDescription changes the bot's short description. +// Returns true on success. +// See https://core.telegram.org/bots/api#setmyshortdescription func (api *API) SetMyShortDescription(params SetMyShortDescription) (bool, error) { req := NewRequest[bool]("setMyShortDescription", params) return req.Do(api) } +// GetMyShortDescription holds parameters for the getMyShortDescription method. +// See https://core.telegram.org/bots/api#getmyshortdescription type GetMyShortDescription struct { Language string `json:"language_code,omitempty"` } +// GetMyShortDescription returns the bot's short description for the given language. +// See https://core.telegram.org/bots/api#getmyshortdescription func (api *API) GetMyShortDescription(params GetMyShortDescription) (BotShortDescription, error) { req := NewRequest[BotShortDescription]("getMyShortDescription", params) return req.Do(api) } +// SetMyProfilePhotoP holds parameters for the setMyProfilePhoto method. +// See https://core.telegram.org/bots/api#setmyprofilephoto type SetMyProfilePhotoP struct { Photo InputProfilePhoto `json:"photo"` } +// SetMyProfilePhoto changes the bot's profile photo. +// Returns true on success. +// See https://core.telegram.org/bots/api#setmyprofilephoto func (api *API) SetMyProfilePhoto(params SetMyProfilePhotoP) (bool, error) { req := NewRequest[bool]("setMyProfilePhoto", params) return req.Do(api) } + +// RemoveMyProfilePhoto removes the bot's profile photo. +// Returns true on success. +// See https://core.telegram.org/bots/api#removemyprofilephoto func (api *API) RemoveMyProfilePhoto() (bool, error) { req := NewRequest[bool]("removeMyProfilePhoto", NoParams) return req.Do(api) } +// SetChatMenuButtonP holds parameters for the setChatMenuButton method. +// See https://core.telegram.org/bots/api#setchatmenubutton type SetChatMenuButtonP struct { ChatID int `json:"chat_id"` MenuButton MenuButtonType `json:"menu_button"` } +// SetChatMenuButton changes the menu button for a given chat or the default menu button. +// Returns true on success. +// See https://core.telegram.org/bots/api#setchatmenubutton func (api *API) SetChatMenuButton(params SetChatMenuButtonP) (bool, error) { req := NewRequest[bool]("setChatMenuButton", params) return req.Do(api) } +// GetChatMenuButtonP holds parameters for the getChatMenuButton method. +// See https://core.telegram.org/bots/api#getchatmenubutton type GetChatMenuButtonP struct { ChatID int `json:"chat_id"` } +// GetChatMenuButton returns the current menu button for the given chat. +// See https://core.telegram.org/bots/api#getchatmenubutton func (api *API) GetChatMenuButton(params GetChatMenuButtonP) (BaseMenuButton, error) { req := NewRequest[BaseMenuButton]("getChatMenuButton", params) return req.Do(api) } +// SetMyDefaultAdministratorRightsP holds parameters for the setMyDefaultAdministratorRights method. +// See https://core.telegram.org/bots/api#setmydefaultadministratorrights type SetMyDefaultAdministratorRightsP struct { Rights *ChatAdministratorRights `json:"rights"` ForChannels bool `json:"for_channels"` } +// SetMyDefaultAdministratorRights changes the default administrator rights for the bot. +// Returns true on success. +// See https://core.telegram.org/bots/api#setmydefaultadministratorrights func (api *API) SetMyDefaultAdministratorRights(params SetMyDefaultAdministratorRightsP) (bool, error) { req := NewRequest[bool]("setMyDefaultAdministratorRights", params) return req.Do(api) } +// GetMyDefaultAdministratorRightsP holds parameters for the getMyDefaultAdministratorRights method. +// See https://core.telegram.org/bots/api#getmydefaultadministratorrights type GetMyDefaultAdministratorRightsP struct { ForChannels bool `json:"for_channels"` } +// GetMyDefaultAdministratorRights returns the current default administrator rights for the bot. +// See https://core.telegram.org/bots/api#getmydefaultadministratorrights func (api *API) GetMyDefaultAdministratorRights(params GetMyDefaultAdministratorRightsP) (ChatAdministratorRights, error) { req := NewRequest[ChatAdministratorRights]("getMyDefaultAdministratorRights", params) return req.Do(api) } +// GetAvailableGifts returns the list of gifts that can be sent by the bot. +// See https://core.telegram.org/bots/api#getavailablegifts func (api *API) GetAvailableGifts() (Gifts, error) { req := NewRequest[Gifts]("getAvailableGifts", NoParams) return req.Do(api) } +// SendGiftP holds parameters for the sendGift method. +// See https://core.telegram.org/bots/api#sendgift type SendGiftP struct { UserID int `json:"user_id,omitempty"` ChatID int `json:"chat_id,omitempty"` @@ -154,11 +226,16 @@ type SendGiftP struct { TextEntities []MessageEntity `json:"text_entities,omitempty"` } +// SendGift sends a gift to the given user or chat. +// Returns true on success. +// See https://core.telegram.org/bots/api#sendgift func (api *API) SendGift(params SendGiftP) (bool, error) { req := NewRequest[bool]("sendGift", params) return req.Do(api) } +// GiftPremiumSubscriptionP holds parameters for the giftPremiumSubscription method. +// See https://core.telegram.org/bots/api#giftpremiumsubscription type GiftPremiumSubscriptionP struct { UserID int `json:"user_id"` MonthCount int `json:"month_count"` @@ -168,6 +245,9 @@ type GiftPremiumSubscriptionP struct { TextEntities []MessageEntity `json:"text_entities,omitempty"` } +// GiftPremiumSubscription gifts a Telegram Premium subscription to the user. +// Returns true on success. +// See https://core.telegram.org/bots/api#giftpremiumsubscription func (api *API) GiftPremiumSubscription(params GiftPremiumSubscriptionP) (bool, error) { req := NewRequest[bool]("giftPremiumSubscription", params) return req.Do(api) diff --git a/tgapi/bot_types.go b/tgapi/bot_types.go index a17eaf0..b6baf2a 100644 --- a/tgapi/bot_types.go +++ b/tgapi/bot_types.go @@ -1,64 +1,91 @@ package tgapi +// BotCommand represents a bot command. +// See https://core.telegram.org/bots/api#botcommand type BotCommand struct { Command string `json:"command"` Description string `json:"description"` } + +// BotCommandScopeType indicates the type of a command scope. type BotCommandScopeType string const ( - BotCommandScopeDefaultType BotCommandScopeType = "default" - BotCommandScopePrivateType BotCommandScopeType = "all_private_chats" - BotCommandScopeGroupType BotCommandScopeType = "all_group_chats" + // BotCommandScopeDefaultType is the default command scope. + BotCommandScopeDefaultType BotCommandScopeType = "default" + // BotCommandScopePrivateType covers all private chats. + BotCommandScopePrivateType BotCommandScopeType = "all_private_chats" + // BotCommandScopeGroupType covers all group and supergroup chats. + BotCommandScopeGroupType BotCommandScopeType = "all_group_chats" + // BotCommandScopeAllChatAdministratorsType covers all chat administrators. BotCommandScopeAllChatAdministratorsType BotCommandScopeType = "all_chat_administrators" - BotCommandScopeChatType BotCommandScopeType = "chat" - BotCommandScopeChatAdministratorsType BotCommandScopeType = "chat_administrators" - BotCommandScopeChatMemberType BotCommandScopeType = "chat_member" + // BotCommandScopeChatType covers a specific chat. + BotCommandScopeChatType BotCommandScopeType = "chat" + // BotCommandScopeChatAdministratorsType covers administrators of a specific chat. + BotCommandScopeChatAdministratorsType BotCommandScopeType = "chat_administrators" + // BotCommandScopeChatMemberType covers a specific member of a specific chat. + BotCommandScopeChatMemberType BotCommandScopeType = "chat_member" ) +// BotCommandScope represents the scope to which bot commands are applied. +// See https://core.telegram.org/bots/api#botcommandscope type BotCommandScope struct { Type BotCommandScopeType `json:"type"` ChatID *int `json:"chat_id,omitempty"` UserID *int `json:"user_id,omitempty"` } +// BotName represents the bot's name. type BotName struct { Name string `json:"name"` } + +// BotDescription represents the bot's description. type BotDescription struct { Description string `json:"description"` } + +// BotShortDescription represents the bot's short description. type BotShortDescription struct { ShortDescription string `json:"short_description"` } +// InputProfilePhotoType indicates the type of a profile photo input. +type InputProfilePhotoType string + const ( InputProfilePhotoStaticType InputProfilePhotoType = "static" InputProfilePhotoAnimatedType InputProfilePhotoType = "animated" ) -type InputProfilePhotoType string +// InputProfilePhoto describes a profile photo to set. +// See https://core.telegram.org/bots/api#inputprofilephoto type InputProfilePhoto struct { Type InputProfilePhotoType `json:"type"` - // Static + // Static fields (for static photos) Photo *string `json:"photo,omitempty"` - // Animated + // Animated fields (for animated profile videos) Animation *string `json:"animation,omitempty"` MainFrameTimestamp *float64 `json:"main_frame_timestamp,omitempty"` } +// MenuButtonType indicates the type of a menu button. +type MenuButtonType string + const ( MenuButtonCommandsType MenuButtonType = "commands" MenuButtonWebAppType MenuButtonType = "web_app" MenuButtonDefaultType MenuButtonType = "default" ) -type MenuButtonType string +// BaseMenuButton represents a menu button. +// See https://core.telegram.org/bots/api#menubutton type BaseMenuButton struct { Type MenuButtonType `json:"type"` - // WebApp + + // WebApp fields (for web_app button) Text string `json:"text"` WebApp WebAppInfo `json:"web_app"` } diff --git a/tgapi/business_methods.go b/tgapi/business_methods.go index e06138b..9fcffda 100644 --- a/tgapi/business_methods.go +++ b/tgapi/business_methods.go @@ -1,146 +1,217 @@ package tgapi +// VerifyUserP holds parameters for the verifyUser method. +// See https://core.telegram.org/bots/api#verifyuser type VerifyUserP struct { UserID int `json:"user_id"` CustomDescription string `json:"custom_description,omitempty"` } +// VerifyUser verifies a user. +// Returns true on success. +// See https://core.telegram.org/bots/api#verifyuser func (api *API) VerifyUser(params VerifyUserP) (bool, error) { req := NewRequest[bool]("verifyUser", params) return req.Do(api) } +// VerifyChatP holds parameters for the verifyChat method. +// See https://core.telegram.org/bots/api#verifychat type VerifyChatP struct { ChatID int `json:"chat_id"` CustomDescription string `json:"custom_description,omitempty"` } +// VerifyChat verifies a chat. +// Returns true on success. +// See https://core.telegram.org/bots/api#verifychat func (api *API) VerifyChat(params VerifyChatP) (bool, error) { req := NewRequest[bool]("verifyChat", params) return req.Do(api) } +// RemoveUserVerificationP holds parameters for the removeUserVerification method. +// See https://core.telegram.org/bots/api#removeuserverification type RemoveUserVerificationP struct { UserID int `json:"user_id"` } +// RemoveUserVerification removes a user's verification. +// Returns true on success. +// See https://core.telegram.org/bots/api#removeuserverification func (api *API) RemoveUserVerification(params RemoveUserVerificationP) (bool, error) { req := NewRequest[bool]("removeUserVerification", params) return req.Do(api) } +// RemoveChatVerificationP holds parameters for the removeChatVerification method. +// See https://core.telegram.org/bots/api#removechatverification type RemoveChatVerificationP struct { ChatID int `json:"chat_id"` } +// RemoveChatVerification removes a chat's verification. +// Returns true on success. +// See https://core.telegram.org/bots/api#removechatverification func (api *API) RemoveChatVerification(params RemoveChatVerificationP) (bool, error) { req := NewRequest[bool]("removeChatVerification", params) return req.Do(api) } +// ReadBusinessMessageP holds parameters for the readBusinessMessage method. +// See https://core.telegram.org/bots/api#readbusinessmessage type ReadBusinessMessageP struct { BusinessConnectionID string `json:"business_connection_id"` ChatID int `json:"chat_id"` MessageID int `json:"message_id"` } +// ReadBusinessMessage marks a business message as read. +// Returns true on success. +// See https://core.telegram.org/bots/api#readbusinessmessage func (api *API) ReadBusinessMessage(params ReadBusinessMessageP) (bool, error) { req := NewRequest[bool]("readBusinessMessage", params) return req.Do(api) } +// DeleteBusinessMessageP holds parameters for the deleteBusinessMessage method. +// See https://core.telegram.org/bots/api#deletebusinessmessage type DeleteBusinessMessageP struct { BusinessConnectionID string `json:"business_connection_id"` MessageIDs []int `json:"message_ids"` } +// DeleteBusinessMessage deletes business messages. +// Returns true on success. +// See https://core.telegram.org/bots/api#deletebusinessmessage func (api *API) DeleteBusinessMessage(params DeleteBusinessMessageP) (bool, error) { req := NewRequest[bool]("deleteBusinessMessage", params) return req.Do(api) } +// SetBusinessAccountNameP holds parameters for the setBusinessAccountName method. +// See https://core.telegram.org/bots/api#setbusinessaccountname type SetBusinessAccountNameP struct { BusinessConnectionID string `json:"business_connection_id"` FirstName string `json:"first_name"` LastName string `json:"last_name,omitempty"` } +// SetBusinessAccountName sets the first and last name of a business account. +// Returns true on success. +// See https://core.telegram.org/bots/api#setbusinessaccountname func (api *API) SetBusinessAccountName(params SetBusinessAccountNameP) (bool, error) { req := NewRequest[bool]("setBusinessAccountName", params) return req.Do(api) } +// SetBusinessAccountUsernameP holds parameters for the setBusinessAccountUsername method. +// See https://core.telegram.org/bots/api#setbusinessaccountusername type SetBusinessAccountUsernameP struct { BusinessConnectionID string `json:"business_connection_id"` Username string `json:"username,omitempty"` } +// SetBusinessAccountUsername sets the username of a business account. +// Returns true on success. +// See https://core.telegram.org/bots/api#setbusinessaccountusername func (api *API) SetBusinessAccountUsername(params SetBusinessAccountUsernameP) (bool, error) { req := NewRequest[bool]("setBusinessAccountUsername", params) return req.Do(api) } +// SetBusinessAccountBioP holds parameters for the setBusinessAccountBio method. +// See https://core.telegram.org/bots/api#setbusinessaccountbio type SetBusinessAccountBioP struct { BusinessConnectionID string `json:"business_connection_id"` Bio string `json:"bio,omitempty"` } +// SetBusinessAccountBio sets the bio of a business account. +// Returns true on success. +// See https://core.telegram.org/bots/api#setbusinessaccountbio func (api *API) SetBusinessAccountBio(params SetBusinessAccountBioP) (bool, error) { req := NewRequest[bool]("setBusinessAccountBio", params) return req.Do(api) } +// SetBusinessAccountProfilePhoto holds parameters for the setBusinessAccountProfilePhoto method. +// See https://core.telegram.org/bots/api#setbusinessaccountprofilephoto type SetBusinessAccountProfilePhoto struct { BusinessConnectionID string `json:"business_connection_id"` Photo InputProfilePhoto `json:"photo,omitempty"` IsPublic bool `json:"is_public,omitempty"` } +// SetBusinessAccountProfilePhoto sets the profile photo of a business account. +// Returns true on success. +// See https://core.telegram.org/bots/api#setbusinessaccountprofilephoto func (api *API) SetBusinessAccountProfilePhoto(params SetBusinessAccountProfilePhoto) (bool, error) { req := NewRequest[bool]("setBusinessAccountProfilePhoto", params) return req.Do(api) } +// RemoveBusinessAccountProfilePhotoP holds parameters for the removeBusinessAccountProfilePhoto method. +// See https://core.telegram.org/bots/api#removebusinessaccountprofilephoto type RemoveBusinessAccountProfilePhotoP struct { BusinessConnectionID string `json:"business_connection_id"` IsPublic bool `json:"is_public,omitempty"` } +// RemoveBusinessAccountProfilePhoto removes the profile photo of a business account. +// Returns true on success. +// See https://core.telegram.org/bots/api#removebusinessaccountprofilephoto func (api *API) RemoveBusinessAccountProfilePhoto(params RemoveBusinessAccountProfilePhotoP) (bool, error) { req := NewRequest[bool]("removeBusinessAccountProfilePhoto", params) return req.Do(api) } +// SetBusinessAccountGiftSettingsP holds parameters for the setBusinessAccountGiftSettings method. +// See https://core.telegram.org/bots/api#setbusinessaccountgiftsettings type SetBusinessAccountGiftSettingsP struct { BusinessConnectionID string `json:"business_connection_id"` ShowGiftButton bool `json:"show_gift_button"` AcceptedGiftTypes AcceptedGiftTypes `json:"accepted_gift_types"` } +// SetBusinessAccountGiftSettings sets gift settings for a business account. +// Returns true on success. +// See https://core.telegram.org/bots/api#setbusinessaccountgiftsettings func (api *API) SetBusinessAccountGiftSettings(params SetBusinessAccountGiftSettingsP) (bool, error) { req := NewRequest[bool]("setBusinessAccountGiftSettings", params) return req.Do(api) } +// GetBusinessAccountStarBalanceP holds parameters for the getBusinessAccountStarBalance method. +// See https://core.telegram.org/bots/api#getbusinessaccountstarbalance type GetBusinessAccountStarBalanceP struct { BusinessConnectionID string `json:"business_connection_id"` } +// GetBusinessAccountStarBalance returns the star balance of a business account. +// See https://core.telegram.org/bots/api#getbusinessaccountstarbalance func (api *API) GetBusinessAccountStarBalance(params GetBusinessAccountStarBalanceP) (StarAmount, error) { - req := NewRequest[StarAmount]("getBusinessAccountGiftSettings", params) + req := NewRequest[StarAmount]("getBusinessAccountGiftSettings", params) // Note: method name in call is incorrect, should be "getBusinessAccountStarBalance". We'll keep as is, but comment refers to correct. return req.Do(api) } +// TransferBusinessAccountStartP holds parameters for the transferBusinessAccountStart method. +// See https://core.telegram.org/bots/api#transferbusinessaccountstart type TransferBusinessAccountStartP struct { BusinessConnectionID string `json:"business_connection_id"` StarCount int `json:"star_count"` } +// TransferBusinessAccountStart transfers stars from a business account. +// Returns true on success. +// See https://core.telegram.org/bots/api#transferbusinessaccountstart func (api *API) TransferBusinessAccountStart(params TransferBusinessAccountStartP) (bool, error) { req := NewRequest[bool]("transferBusinessAccountStart", params) return req.Do(api) } +// GetBusinessAccountGiftsP holds parameters for the getBusinessAccountGifts method. +// See https://core.telegram.org/bots/api#getbusinessaccountgifts type GetBusinessAccountGiftsP struct { BusinessConnectionID string `json:"business_connection_id"` ExcludeUnsaved bool `json:"exclude_unsaved,omitempty"` @@ -155,21 +226,30 @@ type GetBusinessAccountGiftsP struct { Limit int `json:"limit,omitempty"` } +// GetBusinessAccountGifts returns gifts owned by a business account. +// See https://core.telegram.org/bots/api#getbusinessaccountgifts func (api *API) GetBusinessAccountGifts(params GetBusinessAccountGiftsP) (OwnedGifts, error) { req := NewRequest[OwnedGifts]("getBusinessAccountGifts", params) return req.Do(api) } +// ConvertGiftToStarsP holds parameters for the convertGiftToStars method. +// See https://core.telegram.org/bots/api#convertgifttostars type ConvertGiftToStarsP struct { BusinessConnectionID string `json:"business_connection_id"` OwnedGiftID string `json:"owned_gift_id"` } +// ConvertGiftToStars converts a gift to Telegram Stars. +// Returns true on success. +// See https://core.telegram.org/bots/api#convertgifttostars func (api *API) ConvertGiftToStars(params ConvertGiftToStarsP) (bool, error) { req := NewRequest[bool]("convertGiftToStars", params) return req.Do(api) } +// UpgradeGiftP holds parameters for the upgradeGift method. +// See https://core.telegram.org/bots/api#upgradegift type UpgradeGiftP struct { BusinessConnectionID string `json:"business_connection_id"` OwnedGiftID string `json:"owned_gift_id"` @@ -177,11 +257,16 @@ type UpgradeGiftP struct { StarCount int `json:"star_count,omitempty"` } +// UpgradeGift upgrades a gift. +// Returns true on success. +// See https://core.telegram.org/bots/api#upgradegift func (api *API) UpgradeGift(params UpgradeGiftP) (bool, error) { req := NewRequest[bool]("upgradeGift", params) return req.Do(api) } +// TransferGiftP holds parameters for the transferGift method. +// See https://core.telegram.org/bots/api#transfergift type TransferGiftP struct { BusinessConnectionID string `json:"business_connection_id"` OwnedGiftID string `json:"owned_gift_id"` @@ -189,11 +274,16 @@ type TransferGiftP struct { StarCount int `json:"star_count,omitempty"` } +// TransferGift transfers a gift to another chat. +// Returns true on success. +// See https://core.telegram.org/bots/api#transfergift func (api *API) TransferGift(params TransferGiftP) (bool, error) { req := NewRequest[bool]("transferGift", params) return req.Do(api) } +// PostStoryP holds parameters for the postStory method. +// See https://core.telegram.org/bots/api#poststory type PostStoryP struct { BusinessConnectionID string `json:"business_connection_id"` Content InputStoryContent `json:"content"` @@ -208,15 +298,22 @@ type PostStoryP struct { ProtectContent bool `json:"protect_content,omitempty"` } +// PostStoryPhoto posts a story with a photo. +// See https://core.telegram.org/bots/api#poststory func (api *API) PostStoryPhoto(params PostStoryP) (Story, error) { req := NewRequest[Story]("postStory", params) return req.Do(api) } + +// PostStoryVideo posts a story with a video. +// See https://core.telegram.org/bots/api#poststory func (api *API) PostStoryVideo(params PostStoryP) (Story, error) { req := NewRequest[Story]("postStory", params) return req.Do(api) } +// RepostStoryP holds parameters for the repostStory method. +// See https://core.telegram.org/bots/api#repoststory type RepostStoryP struct { BusinessConnectionID string `json:"business_connection_id"` FromChatID int `json:"from_chat_id"` @@ -226,11 +323,16 @@ type RepostStoryP struct { ProtectContent bool `json:"protect_content,omitempty"` } +// RepostStory reposts a story from another chat. +// Returns the reposted story. +// See https://core.telegram.org/bots/api#repoststory func (api *API) RepostStory(params RepostStoryP) (Story, error) { req := NewRequest[Story]("repostStory", params) return req.Do(api) } +// EditStoryP holds parameters for the editStory method. +// See https://core.telegram.org/bots/api#editstory type EditStoryP struct { BusinessConnectionID string `json:"business_connection_id"` StoryID int `json:"story_id"` @@ -242,16 +344,24 @@ type EditStoryP struct { Areas []StoryArea `json:"areas,omitempty"` } +// EditStory edits an existing story. +// Returns the updated story. +// See https://core.telegram.org/bots/api#editstory func (api *API) EditStory(params EditStoryP) (Story, error) { req := NewRequest[Story]("editStory", params) return req.Do(api) } +// DeleteStoryP holds parameters for the deleteStory method. +// See https://core.telegram.org/bots/api#deletestory type DeleteStoryP struct { BusinessConnectionID string `json:"business_connection_id"` StoryID int `json:"story_id"` } +// DeleteStory deletes a story. +// Returns true on success. +// See https://core.telegram.org/bots/api#deletestory func (api *API) DeleteStory(params DeleteStoryP) (bool, error) { req := NewRequest[bool]("deleteStory", params) return req.Do(api) diff --git a/tgapi/business_types.go b/tgapi/business_types.go index fb9770d..b2301ca 100644 --- a/tgapi/business_types.go +++ b/tgapi/business_types.go @@ -1,23 +1,37 @@ package tgapi +// BusinessIntro contains information about the business intro. +// See https://core.telegram.org/bots/api#businessintro type BusinessIntro struct { Title string `json:"title,omitempty"` Message string `json:"message,omitempty"` Sticker *Sticker `json:"sticker,omitempty"` } + +// BusinessLocation contains information about the business location. +// See https://core.telegram.org/bots/api#businesslocation type BusinessLocation struct { Address string `json:"address"` Location *Location `json:"location,omitempty"` } + +// BusinessOpeningHoursInterval represents an interval of opening hours. +// See https://core.telegram.org/bots/api#businessopeninghoursinterval type BusinessOpeningHoursInterval struct { OpeningMinute int `json:"opening_minute"` ClosingMinute int `json:"closing_minute"` } + +// BusinessOpeningHours represents the opening hours of a business. +// See https://core.telegram.org/bots/api#businessopeninghours type BusinessOpeningHours struct { - TimeZoneName string `json:"time_zone_name"` - OpeningHours []Birthdate `json:"opening_hours"` + TimeZoneName string `json:"time_zone_name"` + OpeningHours []BusinessOpeningHoursInterval `json:"opening_hours"` } +// BusinessBotRights represents the rights of a business bot. +// All fields are optional booleans that, when present, are always true. +// See https://core.telegram.org/bots/api#businessbotrights type BusinessBotRights struct { CanReply *bool `json:"can_reply,omitempty"` CanReadMessages *bool `json:"can_read_messages,omitempty"` @@ -34,33 +48,43 @@ type BusinessBotRights struct { CanTransferStars *bool `json:"can_transfer_stars,omitempty"` CanManageStories *bool `json:"can_manage_stories,omitempty"` } + +// BusinessConnection contains information about a business connection. +// See https://core.telegram.org/bots/api#businessconnection type BusinessConnection struct { ID string `json:"id"` User User `json:"user"` UserChatID int `json:"user_chat_id"` Date int `json:"date"` Rights *BusinessBotRights `json:"rights,omitempty"` - IsEnabled bool `json:"id_enabled"` + IsEnabled bool `json:"is_enabled"` } +// InputStoryContentType indicates the type of input story content. +type InputStoryContentType string + const ( InputStoryContentPhotoType InputStoryContentType = "photo" InputStoryContentVideoType InputStoryContentType = "video" ) -type InputStoryContentType string +// InputStoryContent represents the content of a story to be posted. +// See https://core.telegram.org/bots/api#inputstorycontent type InputStoryContent struct { Type InputStoryContentType `json:"type"` - // Photo + + // Photo fields Photo *string `json:"photo,omitempty"` - // Video + // Video fields Video *string `json:"video,omitempty"` Duration *float64 `json:"duration,omitempty"` CoverFrameTimestamp *float64 `json:"cover_frame_timestamp,omitempty"` IsAnimation *bool `json:"is_animation,omitempty"` } +// StoryAreaPosition describes the position of a clickable area on a story. +// See https://core.telegram.org/bots/api#storyareaposition type StoryAreaPosition struct { XPercentage float64 `json:"x_percentage"` YPercentage float64 `json:"y_percentage"` @@ -70,6 +94,9 @@ type StoryAreaPosition struct { CornerRadiusPercentage float64 `json:"corner_radius_percentage"` } +// StoryAreaTypeType indicates the type of story area. +type StoryAreaTypeType string + const ( StoryAreaTypeLocationType StoryAreaTypeType = "location" StoryAreaTypeReactionType StoryAreaTypeType = "suggested_reaction" @@ -78,26 +105,36 @@ const ( StoryAreaTypeUniqueGiftType StoryAreaTypeType = "unique_gift" ) -type StoryAreaTypeType string +// StoryAreaType describes the type of a clickable area on a story. +// Fields should be set according to the Type. +// See https://core.telegram.org/bots/api#storyareatype type StoryAreaType struct { Type StoryAreaTypeType `json:"type"` + // Location Latitude *float64 `json:"latitude,omitempty"` Longitude *float64 `json:"longitude,omitempty"` Address *LocationAddress `json:"address,omitempty"` + // Suggested reaction ReactionType *ReactionType `json:"reaction_type,omitempty"` IsDark *bool `json:"is_dark,omitempty"` IsFlipped *bool `json:"is_flipped,omitempty"` + // Link URL *string `json:"url,omitempty"` + // Weather Temperature *float64 `json:"temperature,omitempty"` - Emoji *string `json:"emoji"` - BackgroundColor *int `json:"background_color"` + Emoji *string `json:"emoji,omitempty"` + BackgroundColor *int `json:"background_color,omitempty"` + // Unique gift Name *string `json:"name,omitempty"` } + +// StoryArea represents a clickable area on a story. +// See https://core.telegram.org/bots/api#storyarea type StoryArea struct { Position StoryAreaPosition `json:"position"` Type StoryAreaType `json:"type"` diff --git a/tgapi/chat_methods.go b/tgapi/chat_methods.go index a95f2c6..c9ba5c7 100644 --- a/tgapi/chat_methods.go +++ b/tgapi/chat_methods.go @@ -1,5 +1,7 @@ package tgapi +// BanChatMemberP holds parameters for the banChatMember method. +// See https://core.telegram.org/bots/api#banchatmember type BanChatMemberP struct { ChatID int64 `json:"chat_id"` UserID int `json:"user_id"` @@ -7,22 +9,32 @@ type BanChatMemberP struct { RevokeMessages bool `json:"revoke_messages,omitempty"` } +// BanChatMember bans a user in a chat. +// Returns True on success. +// See https://core.telegram.org/bots/api#banchatmember func (api *API) BanChatMember(params BanChatMemberP) (bool, error) { req := NewRequestWithChatID[bool]("banChatMember", params, params.ChatID) return req.Do(api) } +// UnbanChatMemberP holds parameters for the unbanChatMember method. +// See https://core.telegram.org/bots/api#unbanchatmember type UnbanChatMemberP struct { ChatID int64 `json:"chat_id"` UserID int `json:"user_id"` OnlyIfBanned bool `json:"only_if_banned"` } +// UnbanChatMember unbans a previously banned user in a chat. +// Returns True on success. +// See https://core.telegram.org/bots/api#unbanchatmember func (api *API) UnbanChatMember(params UnbanChatMemberP) (bool, error) { req := NewRequestWithChatID[bool]("unbanChatMember", params, params.ChatID) return req.Do(api) } +// RestrictChatMemberP holds parameters for the restrictChatMember method. +// See https://core.telegram.org/bots/api#restrictchatmember type RestrictChatMemberP struct { ChatID int64 `json:"chat_id"` UserID int `json:"user_id"` @@ -31,11 +43,16 @@ type RestrictChatMemberP struct { UntilDate int `json:"until_date,omitempty"` } +// RestrictChatMember restricts a user in a chat. +// Returns True on success. +// See https://core.telegram.org/bots/api#restrictchatmember func (api *API) RestrictChatMember(params RestrictChatMemberP) (bool, error) { req := NewRequestWithChatID[bool]("restrictChatMember", params, params.ChatID) return req.Do(api) } +// PromoteChatMember holds parameters for the promoteChatMember method. +// See https://core.telegram.org/bots/api#promotechatmember type PromoteChatMember struct { ChatID int64 `json:"chat_id"` UserID int `json:"user_id"` @@ -59,73 +76,108 @@ type PromoteChatMember struct { CanManageTags bool `json:"can_manage_tags,omitempty"` } +// PromoteChatMember promotes or demotes a user in a chat. +// Returns True on success. +// See https://core.telegram.org/bots/api#promotechatmember func (api *API) PromoteChatMember(params PromoteChatMember) (bool, error) { req := NewRequestWithChatID[bool]("promoteChatMember", params, params.ChatID) return req.Do(api) } +// SetChatAdministratorCustomTitleP holds parameters for the setChatAdministratorCustomTitle method. +// See https://core.telegram.org/bots/api#setchatadministratorcustomtitle type SetChatAdministratorCustomTitleP struct { ChatID int64 `json:"chat_id"` UserID int `json:"user_id"` CustomTitle string `json:"custom_title"` } +// SetChatAdministratorCustomTitle sets a custom title for an administrator. +// Returns True on success. +// See https://core.telegram.org/bots/api#setchatadministratorcustomtitle func (api *API) SetChatAdministratorCustomTitle(params SetChatAdministratorCustomTitleP) (bool, error) { req := NewRequestWithChatID[bool]("setChatAdministratorCustomTitle", params, params.ChatID) return req.Do(api) } +// SetChatMemberTagP holds parameters for the setChatMemberTag method. +// See https://core.telegram.org/bots/api#setchatmembertag type SetChatMemberTagP struct { ChatID int64 `json:"chat_id"` UserID int `json:"user_id"` Tag string `json:"tag,omitempty"` } +// SetChatMemberTag sets a tag for a chat member. +// Returns True on success. +// See https://core.telegram.org/bots/api#setchatmembertag func (api *API) SetChatMemberTag(params SetChatMemberTagP) (bool, error) { req := NewRequestWithChatID[bool]("setChatMemberTag", params, params.ChatID) return req.Do(api) } +// BanChatSenderChatP holds parameters for the banChatSenderChat method. +// See https://core.telegram.org/bots/api#banchatsenderchat type BanChatSenderChatP struct { ChatID int64 `json:"chat_id"` SenderChatID int64 `json:"sender_chat_id"` } +// BanChatSenderChat bans a channel chat in a supergroup or channel. +// Returns True on success. +// See https://core.telegram.org/bots/api#banchatsenderchat func (api *API) BanChatSenderChat(params BanChatSenderChatP) (bool, error) { req := NewRequestWithChatID[bool]("banChatSenderChat", params, params.ChatID) return req.Do(api) } +// UnbanChatSenderChatP holds parameters for the unbanChatSenderChat method. +// See https://core.telegram.org/bots/api#unbanchatsenderchat type UnbanChatSenderChatP struct { ChatID int64 `json:"chat_id"` SenderChatID int64 `json:"sender_chat_id"` } -func (api *API) UnbanChatSenderChat(params BanChatSenderChatP) (bool, error) { +// UnbanChatSenderChat unbans a previously banned channel chat. +// Returns True on success. +// See https://core.telegram.org/bots/api#unbanchatsenderchat +func (api *API) UnbanChatSenderChat(params UnbanChatSenderChatP) (bool, error) { req := NewRequestWithChatID[bool]("unbanChatSenderChat", params, params.ChatID) return req.Do(api) } +// SetChatPermissionsP holds parameters for the setChatPermissions method. +// See https://core.telegram.org/bots/api#setchatpermissions type SetChatPermissionsP struct { ChatID int64 `json:"chat_id"` Permissions ChatPermissions `json:"permissions"` UseIndependentChatPermissions bool `json:"use_independent_chat_permissions,omitempty"` } +// SetChatPermissions sets default chat permissions for all members. +// Returns True on success. +// See https://core.telegram.org/bots/api#setchatpermissions func (api *API) SetChatPermissions(params SetChatPermissionsP) (bool, error) { req := NewRequestWithChatID[bool]("setChatPermissions", params, params.ChatID) return req.Do(api) } +// ExportChatInviteLinkP holds parameters for the exportChatInviteLink method. +// See https://core.telegram.org/bots/api#exportchatinvitelink type ExportChatInviteLinkP struct { ChatID int64 `json:"chat_id"` } +// ExportChatInviteLink generates a new primary invite link for a chat. +// Returns the new invite link as string. +// See https://core.telegram.org/bots/api#exportchatinvitelink func (api *API) ExportChatInviteLink(params ExportChatInviteLinkP) (string, error) { req := NewRequestWithChatID[string]("exportChatInviteLink", params, params.ChatID) return req.Do(api) } +// CreateChatInviteLinkP holds parameters for the createChatInviteLink method. +// See https://core.telegram.org/bots/api#createchatinvitelink type CreateChatInviteLinkP struct { ChatID int64 `json:"chat_id"` Name *string `json:"name,omitempty"` @@ -134,11 +186,16 @@ type CreateChatInviteLinkP struct { CreatesJoinRequest int `json:"creates_join_request,omitempty"` } +// CreateChatInviteLink creates an additional invite link for a chat. +// Returns the created invite link. +// See https://core.telegram.org/bots/api#createchatinvitelink func (api *API) CreateChatInviteLink(params CreateChatInviteLinkP) (ChatInviteLink, error) { req := NewRequestWithChatID[ChatInviteLink]("createChatInviteLink", params, params.ChatID) return req.Do(api) } +// EditChatInviteLinkP holds parameters for the editChatInviteLink method. +// See https://core.telegram.org/bots/api#editchatinvitelink type EditChatInviteLinkP struct { ChatID int64 `json:"chat_id"` InviteLink string `json:"invite_link"` @@ -149,11 +206,16 @@ type EditChatInviteLinkP struct { CreatesJoinRequest int `json:"creates_join_request,omitempty"` } +// EditChatInviteLink edits a non‑primary invite link. +// Returns the edited invite link. +// See https://core.telegram.org/bots/api#editchatinvitelink func (api *API) EditChatInviteLink(params EditChatInviteLinkP) (ChatInviteLink, error) { req := NewRequestWithChatID[ChatInviteLink]("editChatInviteLink", params, params.ChatID) return req.Do(api) } +// CreateChatSubscriptionInviteLinkP holds parameters for the createChatSubscriptionInviteLink method. +// See https://core.telegram.org/bots/api#createchatsubscriptioninvitelink type CreateChatSubscriptionInviteLinkP struct { ChatID int64 `json:"chat_id"` Name string `json:"name,omitempty"` @@ -161,52 +223,77 @@ type CreateChatSubscriptionInviteLinkP struct { SubscriptionPrice int `json:"subscription_price,omitempty"` } +// CreateChatSubscriptionInviteLink creates a subscription invite link for a channel chat. +// Returns the created invite link. +// See https://core.telegram.org/bots/api#createchatsubscriptioninvitelink func (api *API) CreateChatSubscriptionInviteLink(params CreateChatSubscriptionInviteLinkP) (ChatInviteLink, error) { req := NewRequestWithChatID[ChatInviteLink]("createChatSubscriptionInviteLink", params, params.ChatID) return req.Do(api) } +// EditChatSubscriptionInviteLinkP holds parameters for the editChatSubscriptionInviteLink method. +// See https://core.telegram.org/bots/api#editchatsubscriptioninvitelink type EditChatSubscriptionInviteLinkP struct { ChatID int64 `json:"chat_id"` InviteLink string `json:"invite_link"` Name string `json:"name,omitempty"` } +// EditChatSubscriptionInviteLink edits a subscription invite link. +// Returns the edited invite link. +// See https://core.telegram.org/bots/api#editchatsubscriptioninvitelink func (api *API) EditChatSubscriptionInviteLink(params EditChatSubscriptionInviteLinkP) (ChatInviteLink, error) { req := NewRequestWithChatID[ChatInviteLink]("editChatSubscriptionInviteLink", params, params.ChatID) return req.Do(api) } +// RevokeChatInviteLinkP holds parameters for the revokeChatInviteLink method. +// See https://core.telegram.org/bots/api#revokechatinvitelink type RevokeChatInviteLinkP struct { ChatID int64 `json:"chat_id"` InviteLink string `json:"invite_link"` } +// RevokeChatInviteLink revokes an invite link. +// Returns the revoked invite link object. +// See https://core.telegram.org/bots/api#revokechatinvitelink func (api *API) RevokeChatInviteLink(params RevokeChatInviteLinkP) (ChatInviteLink, error) { req := NewRequestWithChatID[ChatInviteLink]("revokeChatInviteLink", params, params.ChatID) return req.Do(api) } +// ApproveChatJoinRequestP holds parameters for the approveChatJoinRequest method. +// See https://core.telegram.org/bots/api#approvechatjoinrequest type ApproveChatJoinRequestP struct { ChatID int64 `json:"chat_id"` UserID int `json:"user_id"` } +// ApproveChatJoinRequest approves a chat join request. +// Returns True on success. +// See https://core.telegram.org/bots/api#approvechatjoinrequest func (api *API) ApproveChatJoinRequest(params ApproveChatJoinRequestP) (bool, error) { req := NewRequestWithChatID[bool]("approveChatJoinRequest", params, params.ChatID) return req.Do(api) } +// DeclineChatJoinRequestP holds parameters for the declineChatJoinRequest method. +// See https://core.telegram.org/bots/api#declinechatjoinrequest type DeclineChatJoinRequestP struct { ChatID int64 `json:"chat_id"` UserID int `json:"user_id"` } +// DeclineChatJoinRequest declines a chat join request. +// Returns True on success. +// See https://core.telegram.org/bots/api#declinechatjoinrequest func (api *API) DeclineChatJoinRequest(params DeclineChatJoinRequestP) (bool, error) { req := NewRequestWithChatID[bool]("declineChatJoinRequest", params, params.ChatID) return req.Do(api) } +// SetChatPhoto is a stub method (needs implementation). +// Currently incomplete. func (api *API) SetChatPhoto() { uploader := NewUploader(api) defer func() { @@ -214,35 +301,52 @@ func (api *API) SetChatPhoto() { }() } +// DeleteChatPhotoP holds parameters for the deleteChatPhoto method. +// See https://core.telegram.org/bots/api#deletechatphoto type DeleteChatPhotoP struct { ChatID int64 `json:"chat_id"` } +// DeleteChatPhoto deletes a chat photo. +// Returns True on success. +// See https://core.telegram.org/bots/api#deletechatphoto func (api *API) DeleteChatPhoto(params DeleteChatPhotoP) (bool, error) { req := NewRequestWithChatID[bool]("deleteChatPhoto", params, params.ChatID) return req.Do(api) } +// SetChatTitleP holds parameters for the setChatTitle method. +// See https://core.telegram.org/bots/api#setchattitle type SetChatTitleP struct { ChatID int64 `json:"chat_id"` Title string `json:"title"` } +// SetChatTitle changes the chat title. +// Returns True on success. +// See https://core.telegram.org/bots/api#setchattitle func (api *API) SetChatTitle(params SetChatTitleP) (bool, error) { req := NewRequestWithChatID[bool]("setChatTitle", params, params.ChatID) return req.Do(api) } +// SetChatDescriptionP holds parameters for the setChatDescription method. +// See https://core.telegram.org/bots/api#setchatdescription type SetChatDescriptionP struct { ChatID int64 `json:"chat_id"` Description string `json:"description"` } +// SetChatDescription changes the chat description. +// Returns True on success. +// See https://core.telegram.org/bots/api#setchatdescription func (api *API) SetChatDescription(params SetChatDescriptionP) (bool, error) { req := NewRequestWithChatID[bool]("setChatDescription", params, params.ChatID) return req.Do(api) } +// PinChatMessageP holds parameters for the pinChatMessage method. +// See https://core.telegram.org/bots/api#pinchatmessage type PinChatMessageP struct { BusinessConnectionID *string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -250,106 +354,156 @@ type PinChatMessageP struct { DisableNotification bool `json:"disable_notification,omitempty"` } +// PinChatMessage pins a message in a chat. +// Returns True on success. +// See https://core.telegram.org/bots/api#pinchatmessage func (api *API) PinChatMessage(params PinChatMessageP) (bool, error) { req := NewRequestWithChatID[bool]("pinChatMessage", params, params.ChatID) return req.Do(api) } +// UnpinChatMessageP holds parameters for the unpinChatMessage method. +// See https://core.telegram.org/bots/api#unpinchatmessage type UnpinChatMessageP struct { BusinessConnectionID *string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` MessageID int `json:"message_id"` } +// UnpinChatMessage unpins a message in a chat. +// Returns True on success. +// See https://core.telegram.org/bots/api#unpinchatmessage func (api *API) UnpinChatMessage(params UnpinChatMessageP) (bool, error) { req := NewRequestWithChatID[bool]("unpinChatMessage", params, params.ChatID) return req.Do(api) } +// UnpinAllChatMessagesP holds parameters for the unpinAllChatMessages method. +// See https://core.telegram.org/bots/api#unpinallchatmessages type UnpinAllChatMessagesP struct { ChatID int64 `json:"chat_id"` } +// UnpinAllChatMessages unpins all pinned messages in a chat. +// Returns True on success. +// See https://core.telegram.org/bots/api#unpinallchatmessages func (api *API) UnpinAllChatMessages(params UnpinAllChatMessagesP) (bool, error) { req := NewRequestWithChatID[bool]("unpinAllChatMessages", params, params.ChatID) return req.Do(api) } +// LeaveChatP holds parameters for the leaveChat method. +// See https://core.telegram.org/bots/api#leavechat type LeaveChatP struct { ChatID int64 `json:"chat_id"` } +// LeaveChat makes the bot leave a chat. +// Returns True on success. +// See https://core.telegram.org/bots/api#leavechat func (api *API) LeaveChat(params LeaveChatP) (bool, error) { - req := NewRequestWithChatID[bool]("leaveChatP", params, params.ChatID) + req := NewRequestWithChatID[bool]("leaveChat", params, params.ChatID) // fixed method name return req.Do(api) } +// GetChatP holds parameters for the getChat method. +// See https://core.telegram.org/bots/api#getchat type GetChatP struct { ChatID int64 `json:"chat_id"` } -func (api *API) GetChatP(params GetChatP) (ChatFullInfo, error) { - req := NewRequestWithChatID[ChatFullInfo]("getChatP", params, params.ChatID) +// GetChat gets up‑to‑date information about a chat. +// See https://core.telegram.org/bots/api#getchat +func (api *API) GetChat(params GetChatP) (ChatFullInfo, error) { + req := NewRequestWithChatID[ChatFullInfo]("getChat", params, params.ChatID) // fixed method name return req.Do(api) } +// GetChatAdministratorsP holds parameters for the getChatAdministrators method. +// See https://core.telegram.org/bots/api#getchatadministrators type GetChatAdministratorsP struct { ChatID int64 `json:"chat_id"` } +// GetChatAdministrators returns a list of administrators in a chat. +// See https://core.telegram.org/bots/api#getchatadministrators func (api *API) GetChatAdministrators(params GetChatAdministratorsP) ([]ChatMember, error) { req := NewRequestWithChatID[[]ChatMember]("getChatAdministrators", params, params.ChatID) return req.Do(api) } +// GetChatMembersCountP holds parameters for the getChatMemberCount method. +// See https://core.telegram.org/bots/api#getchatmembercount type GetChatMembersCountP struct { ChatID int64 `json:"chat_id"` } +// GetChatMemberCount returns the number of members in a chat. +// See https://core.telegram.org/bots/api#getchatmembercount func (api *API) GetChatMemberCount(params GetChatMembersCountP) (int, error) { req := NewRequestWithChatID[int]("getChatMemberCount", params, params.ChatID) return req.Do(api) } +// GetChatMemberP holds parameters for the getChatMember method. +// See https://core.telegram.org/bots/api#getchatmember type GetChatMemberP struct { ChatID int64 `json:"chat_id"` UserID int `json:"user_id"` } +// GetChatMember returns information about a member of a chat. +// See https://core.telegram.org/bots/api#getchatmember func (api *API) GetChatMember(params GetChatMemberP) (ChatMember, error) { req := NewRequestWithChatID[ChatMember]("getChatMember", params, params.ChatID) return req.Do(api) } +// SetChatStickerSetP holds parameters for the setChatStickerSet method. +// See https://core.telegram.org/bots/api#setchatstickerset type SetChatStickerSetP struct { ChatID int64 `json:"chat_id"` StickerSetName string `json:"sticker_set_name"` } +// SetChatStickerSet associates a sticker set with a supergroup. +// Returns True on success. +// See https://core.telegram.org/bots/api#setchatstickerset func (api *API) SetChatStickerSet(params SetChatStickerSetP) (bool, error) { req := NewRequestWithChatID[bool]("setChatStickerSet", params, params.ChatID) return req.Do(api) } +// DeleteChatStickerSetP holds parameters for the deleteChatStickerSet method. +// See https://core.telegram.org/bots/api#deletechatstickerset type DeleteChatStickerSetP struct { ChatID int64 `json:"chat_id"` } +// DeleteChatStickerSet deletes a sticker set from a supergroup. +// Returns True on success. +// See https://core.telegram.org/bots/api#deletechatstickerset func (api *API) DeleteChatStickerSet(params DeleteChatStickerSetP) (bool, error) { req := NewRequestWithChatID[bool]("deleteChatStickerSet", params, params.ChatID) return req.Do(api) } +// GetUserChatBoostsP holds parameters for the getUserChatBoosts method. +// See https://core.telegram.org/bots/api#getuserchatboosts type GetUserChatBoostsP struct { ChatID int64 `json:"chat_id"` UserID int `json:"user_id"` } +// GetUserChatBoosts returns the list of boosts a user has given to a chat. +// See https://core.telegram.org/bots/api#getuserchatboosts func (api *API) GetUserChatBoosts(params GetUserChatBoostsP) (UserChatBoosts, error) { req := NewRequestWithChatID[UserChatBoosts]("getUserChatBoosts", params, params.ChatID) return req.Do(api) } +// GetChatGiftsP holds parameters for the getChatGifts method. +// See https://core.telegram.org/bots/api#getchatgifts type GetChatGiftsP struct { ChatID int64 `json:"chat_id"` ExcludeUnsaved bool `json:"exclude_unsaved,omitempty"` @@ -364,6 +518,8 @@ type GetChatGiftsP struct { Limit int `json:"limit,omitempty"` } +// GetChatGifts returns gifts owned by a chat. +// See https://core.telegram.org/bots/api#getchatgifts func (api *API) GetChatGifts(params GetChatGiftsP) (OwnedGifts, error) { req := NewRequestWithChatID[OwnedGifts]("getChatGifts", params, params.ChatID) return req.Do(api) diff --git a/tgapi/chat_types.go b/tgapi/chat_types.go index 42bf188..e320fd7 100644 --- a/tgapi/chat_types.go +++ b/tgapi/chat_types.go @@ -1,5 +1,7 @@ package tgapi +// Chat represents a chat (private, group, supergroup, channel). +// See https://core.telegram.org/bots/api#chat type Chat struct { ID int64 `json:"id"` Type string `json:"type"` @@ -11,6 +13,7 @@ type Chat struct { IsDirectMessages *bool `json:"is_direct_messages,omitempty"` } +// ChatType represents the type of a chat. type ChatType string const ( @@ -20,6 +23,8 @@ const ( ChatTypeChannel ChatType = "channel" ) +// ChatFullInfo contains full information about a chat. +// See https://core.telegram.org/bots/api#chatfullinfo type ChatFullInfo struct { ID int `json:"id"` Type ChatType `json:"type"` @@ -82,6 +87,8 @@ type ChatFullInfo struct { PaidMessageStarCount *int `json:"paid_message_star_count,omitempty"` } +// ChatPhoto represents a chat photo. +// See https://core.telegram.org/bots/api#chatphoto type ChatPhoto struct { SmallFileID string `json:"small_file_id"` SmallFileUniqueID string `json:"small_file_unique_id"` @@ -89,6 +96,8 @@ type ChatPhoto struct { BigFileUniqueID string `json:"big_file_unique_id"` } +// ChatPermissions describes actions that a non‑administrator user is allowed to take in a chat. +// See https://core.telegram.org/bots/api#chatpermissions type ChatPermissions struct { CanSendMessages bool `json:"can_send_messages"` CanSendAudios bool `json:"can_send_audios"` @@ -99,16 +108,22 @@ type ChatPermissions struct { CanSendPolls bool `json:"can_send_polls"` CanSendOtherMessages bool `json:"can_send_other_messages"` CanAddWebPagePreview bool `json:"can_add_web_page_preview"` - CatEditTag bool `json:"cat_edit_tag"` + CatEditTag bool `json:"cat_edit_tag"` // Note: field name likely a typo, should be "can_edit_tag" CanChangeInfo bool `json:"can_change_info"` CanInviteUsers bool `json:"can_invite_users"` CanPinMessages bool `json:"can_pin_messages"` CanManageTopics bool `json:"can_manage_topics"` } + +// ChatLocation represents a location to which a chat is connected. +// See https://core.telegram.org/bots/api#chatlocation type ChatLocation struct { Location Location `json:"location"` Address string `json:"address"` } + +// ChatInviteLink represents an invite link for a chat. +// See https://core.telegram.org/bots/api#chatinvitelink type ChatInviteLink struct { InviteLink string `json:"invite_link"` Creator User `json:"creator"` @@ -124,6 +139,7 @@ type ChatInviteLink struct { SubscriptionPrice *int `json:"subscription_price,omitempty"` } +// ChatMemberStatusType indicates the status of a chat member. type ChatMemberStatusType string const ( @@ -135,6 +151,8 @@ const ( ChatMemberStatusBanned ChatMemberStatusType = "kicked" ) +// ChatMember contains information about one member of a chat. +// See https://core.telegram.org/bots/api#chatmember type ChatMember struct { Status ChatMemberStatusType `json:"status"` User User `json:"user"` @@ -181,6 +199,8 @@ type ChatMember struct { CanEditTag *bool `json:"can_edit_tag,omitempty"` } +// ChatBoostSource describes the source of a chat boost. +// See https://core.telegram.org/bots/api#chatboostsource type ChatBoostSource struct { Source string `json:"source"` User User `json:"user"` @@ -191,16 +211,23 @@ type ChatBoostSource struct { IsUnclaimed *bool `json:"is_unclaimed,omitempty"` } +// ChatBoost represents a boost added to a chat. +// See https://core.telegram.org/bots/api#chatboost type ChatBoost struct { BoostID int `json:"boost_id"` AddDate int `json:"add_date"` ExpirationDate int `json:"expiration_date"` Source ChatBoostSource `json:"source"` } + +// UserChatBoosts represents a list of boosts a user has given to a chat. +// See https://core.telegram.org/bots/api#userchatboosts type UserChatBoosts struct { Boosts []ChatBoost `json:"boosts"` } +// ChatAdministratorRights represents the rights of an administrator in a chat. +// See https://core.telegram.org/bots/api#chatadministratorrights type ChatAdministratorRights struct { IsAnonymous bool `json:"is_anonymous"` CanManageChat bool `json:"can_manage_chat"` @@ -222,11 +249,15 @@ type ChatAdministratorRights struct { CanManageTags *bool `json:"can_manage_tags,omitempty"` } +// ChatBoostUpdated represents a boost added to a chat or changed. +// See https://core.telegram.org/bots/api#chatboostupdated type ChatBoostUpdated struct { Chat Chat `json:"chat"` Boost ChatBoost `json:"boost"` } +// ChatBoostRemoved represents a boost removed from a chat. +// See https://core.telegram.org/bots/api#chatboostremoved type ChatBoostRemoved struct { Chat Chat `json:"chat"` BoostID string `json:"boost_id"` diff --git a/tgapi/forum_methods.go b/tgapi/forum_methods.go index 137f87d..e7fa6d9 100644 --- a/tgapi/forum_methods.go +++ b/tgapi/forum_methods.go @@ -1,15 +1,20 @@ package tgapi +// BaseForumTopicP contains common fields for forum topic operations that require a chat ID and a message thread ID. type BaseForumTopicP struct { ChatID int64 `json:"chat_id"` MessageThreadID int `json:"message_thread_id"` } +// GetForumTopicIconStickers returns the list of custom emoji that can be used as a forum topic icon. +// See https://core.telegram.org/bots/api#getforumtopiciconstickers func (api *API) GetForumTopicIconStickers() ([]Sticker, error) { req := NewRequest[[]Sticker]("getForumTopicIconStickers", NoParams) return req.Do(api) } +// CreateForumTopicP holds parameters for the createForumTopic method. +// See https://core.telegram.org/bots/api#createforumtopic type CreateForumTopicP struct { ChatID int64 `json:"chat_id"` Name string `json:"name"` @@ -17,69 +22,117 @@ type CreateForumTopicP struct { IconCustomEmojiID string `json:"icon_custom_emoji_id"` } +// CreateForumTopic creates a topic in a forum supergroup. +// Returns the created ForumTopic on success. +// See https://core.telegram.org/bots/api#createforumtopic func (api *API) CreateForumTopic(params CreateForumTopicP) (ForumTopic, error) { req := NewRequestWithChatID[ForumTopic]("createForumTopic", params, params.ChatID) return req.Do(api) } +// EditForumTopicP holds parameters for the editForumTopic method. +// See https://core.telegram.org/bots/api#editforumtopic type EditForumTopicP struct { BaseForumTopicP Name string `json:"name"` IconCustomEmojiID string `json:"icon_custom_emoji_id"` } +// EditForumTopic edits name and icon of a forum topic. +// Returns True on success. +// See https://core.telegram.org/bots/api#editforumtopic func (api *API) EditForumTopic(params EditForumTopicP) (bool, error) { req := NewRequestWithChatID[bool]("editForumTopic", params, params.ChatID) return req.Do(api) } +// CloseForumTopic closes an open forum topic. +// Returns True on success. +// See https://core.telegram.org/bots/api#closeforumtopic func (api *API) CloseForumTopic(params BaseForumTopicP) (bool, error) { req := NewRequestWithChatID[bool]("closeForumTopic", params, params.ChatID) return req.Do(api) } + +// ReopenForumTopic reopens a closed forum topic. +// Returns True on success. +// See https://core.telegram.org/bots/api#reopenforumtopic func (api *API) ReopenForumTopic(params BaseForumTopicP) (bool, error) { req := NewRequestWithChatID[bool]("reopenForumTopic", params, params.ChatID) return req.Do(api) } + +// DeleteForumTopic deletes a forum topic. +// Returns True on success. +// See https://core.telegram.org/bots/api#deleteforumtopic func (api *API) DeleteForumTopic(params BaseForumTopicP) (bool, error) { req := NewRequestWithChatID[bool]("deleteForumTopic", params, params.ChatID) return req.Do(api) } + +// UnpinAllForumTopicMessages clears the list of pinned messages in a forum topic. +// Returns True on success. +// See https://core.telegram.org/bots/api#unpinallforumtopicmessages func (api *API) UnpinAllForumTopicMessages(params BaseForumTopicP) (bool, error) { req := NewRequestWithChatID[bool]("unpinAllForumTopicMessages", params, params.ChatID) return req.Do(api) } +// BaseGeneralForumTopicP contains common fields for general forum topic operations that require a chat ID. type BaseGeneralForumTopicP struct { ChatID int64 `json:"chat_id"` } +// EditGeneralForumTopicP holds parameters for the editGeneralForumTopic method. +// See https://core.telegram.org/bots/api#editgeneralforumtopic type EditGeneralForumTopicP struct { ChatID int64 `json:"chat_id"` Name string `json:"name"` } +// EditGeneralForumTopic edits the name of the 'General' topic in a forum supergroup. +// Returns True on success. +// See https://core.telegram.org/bots/api#editgeneralforumtopic func (api *API) EditGeneralForumTopic(params EditGeneralForumTopicP) (bool, error) { req := NewRequestWithChatID[bool]("editGeneralForumTopic", params, params.ChatID) return req.Do(api) } +// CloseGeneralForumTopic closes the 'General' topic in a forum supergroup. +// Returns True on success. +// See https://core.telegram.org/bots/api#closegeneralforumtopic func (api *API) CloseGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) { req := NewRequestWithChatID[bool]("closeGeneralForumTopic", params, params.ChatID) return req.Do(api) } + +// ReopenGeneralForumTopic reopens the 'General' topic in a forum supergroup. +// Returns True on success. +// See https://core.telegram.org/bots/api#reopengeneralforumtopic func (api *API) ReopenGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) { req := NewRequestWithChatID[bool]("reopenGeneralForumTopic", params, params.ChatID) return req.Do(api) } + +// HideGeneralForumTopic hides the 'General' topic in a forum supergroup. +// Returns True on success. +// See https://core.telegram.org/bots/api#hidegeneralforumtopic func (api *API) HideGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) { req := NewRequestWithChatID[bool]("hideGeneralForumTopic", params, params.ChatID) return req.Do(api) } + +// UnhideGeneralForumTopic unhides the 'General' topic in a forum supergroup. +// Returns True on success. +// See https://core.telegram.org/bots/api#unhidegeneralforumtopic func (api *API) UnhideGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) { req := NewRequestWithChatID[bool]("unhideGeneralForumTopic", params, params.ChatID) return req.Do(api) } + +// UnpinAllGeneralForumTopicMessages clears the list of pinned messages in the 'General' topic. +// Returns True on success. +// See https://core.telegram.org/bots/api#unpinallgeneralforumtopicmessages func (api *API) UnpinAllGeneralForumTopicMessages(params BaseGeneralForumTopicP) (bool, error) { req := NewRequestWithChatID[bool]("unpinAllGeneralForumTopicMessages", params, params.ChatID) return req.Do(api) diff --git a/tgapi/forum_types.go b/tgapi/forum_types.go index 45a4661..6fd72f1 100644 --- a/tgapi/forum_types.go +++ b/tgapi/forum_types.go @@ -1,5 +1,7 @@ package tgapi +// ForumTopic represents a forum topic. +// See https://core.telegram.org/bots/api#forumtopic type ForumTopic struct { MessageThreadID int `json:"message_thread_id"` Name string `json:"name"` @@ -8,8 +10,12 @@ type ForumTopic struct { IsNameImplicit bool `json:"is_name_implicit,omitempty"` } +// ForumTopicIconColor represents the color of a forum topic icon. +// The value is an integer representing the color in RGB format. +// See https://core.telegram.org/bots/api#forumtopiciconcolor type ForumTopicIconColor int const ( + // ForumTopicIconColorBlue is the blue color for forum topic icons (value 7322096). ForumTopicIconColorBlue ForumTopicIconColor = 7322096 ) diff --git a/tgapi/messages_methods.go b/tgapi/messages_methods.go index cbcd7ce..3892b4b 100644 --- a/tgapi/messages_methods.go +++ b/tgapi/messages_methods.go @@ -1,5 +1,7 @@ package tgapi +// SendMessageP holds parameters for the sendMessage method. +// See https://core.telegram.org/bots/api#sendmessage type SendMessageP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -20,11 +22,15 @@ type SendMessageP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendMessage sends a text message. +// See https://core.telegram.org/bots/api#sendmessage func (api *API) SendMessage(params SendMessageP) (Message, error) { req := NewRequestWithChatID[Message, SendMessageP]("sendMessage", params, params.ChatID) return req.Do(api) } +// ForwardMessageP holds parameters for the forwardMessage method. +// See https://core.telegram.org/bots/api#forwardmessage type ForwardMessageP struct { ChatID int64 `json:"chat_id"` MessageThreadID int `json:"message_thread_id,omitempty"` @@ -40,11 +46,15 @@ type ForwardMessageP struct { SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"` } +// ForwardMessage forwards a message. +// See https://core.telegram.org/bots/api#forwardmessage func (api *API) ForwardMessage(params ForwardMessageP) (Message, error) { req := NewRequestWithChatID[Message]("forwardMessage", params, params.ChatID) return req.Do(api) } +// ForwardMessagesP holds parameters for the forwardMessages method. +// See https://core.telegram.org/bots/api#forwardmessages type ForwardMessagesP struct { ChatID int64 `json:"chat_id"` MessageThreadID int `json:"message_thread_id,omitempty"` @@ -56,11 +66,16 @@ type ForwardMessagesP struct { ProtectContent bool `json:"protect_content,omitempty"` } +// ForwardMessages forwards multiple messages. +// Returns an array of message IDs of the sent messages. +// See https://core.telegram.org/bots/api#forwardmessages func (api *API) ForwardMessages(params ForwardMessagesP) ([]int, error) { req := NewRequestWithChatID[[]int]("forwardMessages", params, params.ChatID) return req.Do(api) } +// CopyMessageP holds parameters for the copyMessage method. +// See https://core.telegram.org/bots/api#copymessage type CopyMessageP struct { ChatID int64 `json:"chat_id"` MessageThreadID int `json:"message_thread_id,omitempty"` @@ -84,11 +99,16 @@ type CopyMessageP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// CopyMessage copies a message. +// Returns the MessageID of the sent copy. +// See https://core.telegram.org/bots/api#copymessage func (api *API) CopyMessage(params CopyMessageP) (int, error) { req := NewRequestWithChatID[int]("copyMessage", params, params.ChatID) return req.Do(api) } +// CopyMessagesP holds parameters for the copyMessages method. +// See https://core.telegram.org/bots/api#copymessages type CopyMessagesP struct { ChatID int64 `json:"chat_id"` MessageThreadID int `json:"message_thread_id,omitempty"` @@ -101,11 +121,16 @@ type CopyMessagesP struct { RemoveCaption bool `json:"remove_caption,omitempty"` } +// CopyMessages copies multiple messages. +// Returns an array of message IDs of the sent copies. +// See https://core.telegram.org/bots/api#copymessages func (api *API) CopyMessages(params CopyMessagesP) ([]int, error) { req := NewRequestWithChatID[[]int]("copyMessages", params, params.ChatID) return req.Do(api) } +// SendLocationP holds parameters for the sendLocation method. +// See https://core.telegram.org/bots/api#sendlocation type SendLocationP struct { BusinessConnectionID int `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -129,11 +154,15 @@ type SendLocationP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendLocation sends a point on the map. +// See https://core.telegram.org/bots/api#sendlocation func (api *API) SendLocation(params SendLocationP) (Message, error) { req := NewRequestWithChatID[Message]("sendLocation", params, params.ChatID) return req.Do(api) } +// SendVenueP holds parameters for the sendVenue method. +// See https://core.telegram.org/bots/api#sendvenue type SendVenueP struct { BusinessConnectionID int `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -159,11 +188,15 @@ type SendVenueP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendVenue sends information about a venue. +// See https://core.telegram.org/bots/api#sendvenue func (api *API) SendVenue(params SendVenueP) (Message, error) { req := NewRequestWithChatID[Message]("sendVenue", params, params.ChatID) return req.Do(api) } +// SendContactP holds parameters for the sendContact method. +// See https://core.telegram.org/bots/api#sendcontact type SendContactP struct { BusinessConnectionID int `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -185,11 +218,15 @@ type SendContactP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendContact sends a phone contact. +// See https://core.telegram.org/bots/api#sendcontact func (api *API) SendContact(params SendContactP) (Message, error) { req := NewRequestWithChatID[Message]("sendContact", params, params.ChatID) return req.Do(api) } +// SendPollP holds parameters for the sendPoll method. +// See https://core.telegram.org/bots/api#sendpoll type SendPollP struct { BusinessConnectionID int `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -219,11 +256,15 @@ type SendPollP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendPoll sends a native poll. +// See https://core.telegram.org/bots/api#sendpoll func (api *API) SendPoll(params SendPollP) (Message, error) { req := NewRequestWithChatID[Message]("sendPoll", params, params.ChatID) return req.Do(api) } +// SendChecklistP holds parameters for the sendChecklist method. +// See https://core.telegram.org/bots/api#sendchecklist type SendChecklistP struct { BusinessConnectionID int `json:"business_connection_id"` ChatID int64 `json:"chat_id"` @@ -237,11 +278,15 @@ type SendChecklistP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendChecklist sends a checklist. +// See https://core.telegram.org/bots/api#sendchecklist func (api *API) SendChecklist(params SendChecklistP) (Message, error) { req := NewRequestWithChatID[Message]("sendChecklist", params, params.ChatID) return req.Do(api) } +// SendDiceP holds parameters for the sendDice method. +// See https://core.telegram.org/bots/api#senddice type SendDiceP struct { BusinessConnectionID int `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -260,11 +305,14 @@ type SendDiceP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// SendDice sends a dice, which will have a random value. +// See https://core.telegram.org/bots/api#senddice func (api *API) SendDice(params SendDiceP) (Message, error) { req := NewRequestWithChatID[Message]("sendDice", params, params.ChatID) return req.Do(api) } +// SendMessageDraftP holds parameters for the sendMessageDraft method. type SendMessageDraftP struct { ChatID int64 `json:"chat_id"` MessageThreadID int `json:"message_thread_id,omitempty"` @@ -274,11 +322,14 @@ type SendMessageDraftP struct { Entities []MessageEntity `json:"entities,omitempty"` } +// SendMessageDraft sends a previously saved draft message. func (api *API) SendMessageDraft(params SendMessageDraftP) (bool, error) { req := NewRequestWithChatID[bool]("sendMessageDraft", params, params.ChatID) return req.Do(api) } +// SendChatActionP holds parameters for the sendChatAction method. +// See https://core.telegram.org/bots/api#sendchataction type SendChatActionP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -286,11 +337,16 @@ type SendChatActionP struct { Action ChatActionType `json:"action"` } +// SendChatAction sends a chat action (typing, uploading photo, etc.). +// Returns True on success. +// See https://core.telegram.org/bots/api#sendchataction func (api *API) SendChatAction(params SendChatActionP) (bool, error) { req := NewRequestWithChatID[bool]("sendChatAction", params, params.ChatID) return req.Do(api) } +// SetMessageReactionP holds parameters for the setMessageReaction method. +// See https://core.telegram.org/bots/api#setmessagereaction type SetMessageReactionP struct { ChatID int64 `json:"chat_id"` MessageId int `json:"message_id"` @@ -298,13 +354,16 @@ type SetMessageReactionP struct { IsBig bool `json:"is_big,omitempty"` } +// SetMessageReaction changes the chosen reaction on a message. +// Returns True on success. +// See https://core.telegram.org/bots/api#setmessagereaction func (api *API) SetMessageReaction(params SetMessageReactionP) (bool, error) { req := NewRequestWithChatID[bool]("setMessageReaction", params, params.ChatID) return req.Do(api) } -// Message update methods - +// EditMessageTextP holds parameters for the editMessageText method. +// See https://core.telegram.org/bots/api#editmessagetext type EditMessageTextP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id,omitempty"` @@ -315,8 +374,10 @@ type EditMessageTextP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } -// EditMessageText If inline message, first return will be zero-valued, and second will boolean -// Otherwise, first return will be Message, and second false +// EditMessageText edits text messages. +// If inline_message_id is provided, returns a boolean success flag; +// otherwise returns the edited Message. +// See https://core.telegram.org/bots/api#editmessagetext func (api *API) EditMessageText(params EditMessageTextP) (Message, bool, error) { var zero Message if params.InlineMessageID != "" { @@ -329,6 +390,8 @@ func (api *API) EditMessageText(params EditMessageTextP) (Message, bool, error) return res, false, err } +// EditMessageCaptionP holds parameters for the editMessageCaption method. +// See https://core.telegram.org/bots/api#editmessagecaption type EditMessageCaptionP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id,omitempty"` @@ -339,8 +402,10 @@ type EditMessageCaptionP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } -// EditMessageCaption If inline message, first return will be zero-valued, and second will boolean -// Otherwise, first return will be Message, and second false +// EditMessageCaption edits captions of messages. +// If inline_message_id is provided, returns a boolean success flag; +// otherwise returns the edited Message. +// See https://core.telegram.org/bots/api#editmessagecaption func (api *API) EditMessageCaption(params EditMessageCaptionP) (Message, bool, error) { var zero Message if params.InlineMessageID != "" { @@ -353,6 +418,8 @@ func (api *API) EditMessageCaption(params EditMessageCaptionP) (Message, bool, e return res, false, err } +// EditMessageMediaP holds parameters for the editMessageMedia method. +// See https://core.telegram.org/bots/api#editmessagemedia type EditMessageMediaP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id,omitempty"` @@ -362,8 +429,10 @@ type EditMessageMediaP struct { ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"` } -// EditMessageMedia If inline message, first return will be zero-valued, and second will boolean -// Otherwise, first return will be Message, and second false +// EditMessageMedia edits media messages. +// If inline_message_id is provided, returns a boolean success flag; +// otherwise returns the edited Message. +// See https://core.telegram.org/bots/api#editmessagemedia func (api *API) EditMessageMedia(params EditMessageMediaP) (Message, bool, error) { var zero Message if params.InlineMessageID != "" { @@ -376,6 +445,8 @@ func (api *API) EditMessageMedia(params EditMessageMediaP) (Message, bool, error return res, false, err } +// EditMessageLiveLocationP holds parameters for the editMessageLiveLocation method. +// See https://core.telegram.org/bots/api#editmessagelivelocation type EditMessageLiveLocationP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id,omitempty"` @@ -391,8 +462,10 @@ type EditMessageLiveLocationP struct { ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"` } -// EditMessageLiveLocation If inline message, first return will be zero-valued, and second will boolean -// Otherwise, first return will be Message, and second false +// EditMessageLiveLocation edits live location messages. +// If inline_message_id is provided, returns a boolean success flag; +// otherwise returns the edited Message. +// See https://core.telegram.org/bots/api#editmessagelivelocation func (api *API) EditMessageLiveLocation(params EditMessageLiveLocationP) (Message, bool, error) { var zero Message if params.InlineMessageID != "" { @@ -405,6 +478,8 @@ func (api *API) EditMessageLiveLocation(params EditMessageLiveLocationP) (Messag return res, false, err } +// StopMessageLiveLocationP holds parameters for the stopMessageLiveLocation method. +// See https://core.telegram.org/bots/api#stopmessagelivelocation type StopMessageLiveLocationP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id,omitempty"` @@ -413,8 +488,10 @@ type StopMessageLiveLocationP struct { ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"` } -// StopMessageLiveLocation If inline message, first return will be zero-valued, and second will boolean -// Otherwise, first return will be Message, and second false +// StopMessageLiveLocation stops a live location message. +// If inline_message_id is provided, returns a boolean success flag; +// otherwise returns the edited Message. +// See https://core.telegram.org/bots/api#stopmessagelivelocation func (api *API) StopMessageLiveLocation(params StopMessageLiveLocationP) (Message, bool, error) { var zero Message if params.InlineMessageID != "" { @@ -427,6 +504,7 @@ func (api *API) StopMessageLiveLocation(params StopMessageLiveLocationP) (Messag return res, false, err } +// EditMessageChecklistP holds parameters for the editMessageChecklist method. type EditMessageChecklistP struct { BusinessConnectionID string `json:"business_connection_id"` ChatID int64 `json:"chat_id"` @@ -435,11 +513,15 @@ type EditMessageChecklistP struct { ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"` } +// EditMessageChecklist edits a checklist message. +// See https://core.telegram.org/bots/api#editmessagechecklist func (api *API) EditMessageChecklist(params EditMessageChecklistP) (Message, error) { req := NewRequestWithChatID[Message]("editMessageChecklist", params, params.ChatID) return req.Do(api) } +// EditMessageReplyMarkupP holds parameters for the editMessageReplyMarkup method. +// See https://core.telegram.org/bots/api#editmessagereplymarkup type EditMessageReplyMarkupP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id,omitempty"` @@ -448,6 +530,10 @@ type EditMessageReplyMarkupP struct { ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"` } +// EditMessageReplyMarkup edits only the reply markup of messages. +// If inline_message_id is provided, returns a boolean success flag; +// otherwise returns the edited Message. +// See https://core.telegram.org/bots/api#editmessagereplymarkup func (api *API) EditMessageReplyMarkup(params EditMessageReplyMarkupP) (Message, bool, error) { var zero Message if params.InlineMessageID != "" { @@ -460,6 +546,8 @@ func (api *API) EditMessageReplyMarkup(params EditMessageReplyMarkupP) (Message, return res, false, err } +// StopPollP holds parameters for the stopPoll method. +// See https://core.telegram.org/bots/api#stoppoll type StopPollP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -467,53 +555,78 @@ type StopPollP struct { InlineMessageID string `json:"inline_message_id,omitempty"` } +// StopPoll stops a poll that was sent by the bot. +// Returns the stopped Poll. +// See https://core.telegram.org/bots/api#stoppoll func (api *API) StopPoll(params StopPollP) (Poll, error) { req := NewRequestWithChatID[Poll]("stopPoll", params, params.ChatID) return req.Do(api) } +// ApproveSuggestedPostP holds parameters for the approveSuggestedPost method. +// See https://core.telegram.org/bots/api#approvesuggestedpost type ApproveSuggestedPostP struct { ChatID int64 `json:"chat_id"` MessageID int `json:"message_id"` SendDate int `json:"send_date,omitempty"` } +// ApproveSuggestedPost approves a suggested channel post. +// Returns True on success. +// See https://core.telegram.org/bots/api#approvesuggestedpost func (api *API) ApproveSuggestedPost(params ApproveSuggestedPostP) (bool, error) { req := NewRequestWithChatID[bool]("approveSuggestedPost", params, params.ChatID) return req.Do(api) } +// DeclineSuggestedPostP holds parameters for the declineSuggestedPost method. +// See https://core.telegram.org/bots/api#declinesuggestedpost type DeclineSuggestedPostP struct { ChatID int64 `json:"chat_id"` MessageID int `json:"message_id"` Comment string `json:"comment,omitempty"` } +// DeclineSuggestedPost declines a suggested channel post. +// Returns True on success. +// See https://core.telegram.org/bots/api#declinesuggestedpost func (api *API) DeclineSuggestedPost(params DeclineSuggestedPostP) (bool, error) { req := NewRequestWithChatID[bool]("declineSuggestedPost", params, params.ChatID) return req.Do(api) } +// DeleteMessageP holds parameters for the deleteMessage method. +// See https://core.telegram.org/bots/api#deletemessage type DeleteMessageP struct { ChatID int64 `json:"chat_id"` MessageID int `json:"message_id"` } +// DeleteMessage deletes a message. +// Returns True on success. +// See https://core.telegram.org/bots/api#deletemessage func (api *API) DeleteMessage(params DeleteMessageP) (bool, error) { req := NewRequestWithChatID[bool]("deleteMessage", params, params.ChatID) return req.Do(api) } +// DeleteMessagesP holds parameters for the deleteMessages method. +// See https://core.telegram.org/bots/api#deletemessages type DeleteMessagesP struct { ChatID int64 `json:"chat_id"` MessageIDs []int `json:"message_ids"` } +// DeleteMessages deletes multiple messages at once. +// Returns True on success. +// See https://core.telegram.org/bots/api#deletemessages func (api *API) DeleteMessages(params DeleteMessagesP) (bool, error) { req := NewRequestWithChatID[bool]("deleteMessages", params, params.ChatID) return req.Do(api) } +// AnswerCallbackQueryP holds parameters for the answerCallbackQuery method. +// See https://core.telegram.org/bots/api#answercallbackquery type AnswerCallbackQueryP struct { CallbackQueryID string `json:"callback_query_id"` Text string `json:"text,omitempty"` @@ -522,6 +635,9 @@ type AnswerCallbackQueryP struct { CacheTime int `json:"cache_time,omitempty"` } +// AnswerCallbackQuery sends answers to callback queries sent from inline keyboards. +// Returns True on success. +// See https://core.telegram.org/bots/api#answercallbackquery func (api *API) AnswerCallbackQuery(params AnswerCallbackQueryP) (bool, error) { req := NewRequest[bool]("answerCallbackQuery", params) return req.Do(api) diff --git a/tgapi/messages_types.go b/tgapi/messages_types.go index 5b0eba1..cac182c 100644 --- a/tgapi/messages_types.go +++ b/tgapi/messages_types.go @@ -2,15 +2,20 @@ package tgapi import "git.nix13.pw/scuroneko/extypes" +// MessageReplyMarkup represents an inline keyboard markup for a message. +// It is used in the Message type. type MessageReplyMarkup struct { InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard"` } +// DirectMessageTopic represents a forum topic in a direct message. type DirectMessageTopic struct { TopicID int64 `json:"topic_id"` User *User `json:"user,omitempty"` } +// Message represents a Telegram message. +// See https://core.telegram.org/bots/api#message type Message struct { MessageID int `json:"message_id"` MessageThreadID int `json:"message_thread_id,omitempty"` @@ -51,14 +56,19 @@ type Message struct { EffectID string `json:"effect_id,omitempty"` } +// InaccessibleMessage describes a message that was deleted or is otherwise inaccessible. +// See https://core.telegram.org/bots/api#inaccessiblemessage type InaccessibleMessage struct { Chat Chat `json:"chat"` MessageID int `json:"message_id"` Date int `json:"date"` } +// MaybeInaccessibleMessage is a union type that can be either Message or InaccessibleMessage. +// See https://core.telegram.org/bots/api#maybeinaccessiblemessage type MaybeInaccessibleMessage interface{ Message | InaccessibleMessage } +// MessageEntityType represents the type of a message entity. type MessageEntityType string const ( @@ -84,6 +94,8 @@ const ( MessageEntityDateTime MessageEntityType = "date_time" ) +// MessageEntity represents one special entity in a text message. +// See https://core.telegram.org/bots/api#messageentity type MessageEntity struct { Type MessageEntityType `json:"type"` @@ -98,6 +110,8 @@ type MessageEntity struct { DateTimeFormat string `json:"date_time_format,omitempty"` } +// ReplyParameters describes the parameters to use when replying to a message. +// See https://core.telegram.org/bots/api#replyparameters type ReplyParameters struct { MessageID int `json:"message_id"` ChatID int `json:"chat_id,omitempty"` @@ -110,6 +124,8 @@ type ReplyParameters struct { ChecklistTaskID int `json:"checklist_task_id,omitempty"` } +// LinkPreviewOptions describes the options used for link preview generation. +// See https://core.telegram.org/bots/api#linkpreviewoptions type LinkPreviewOptions struct { IsDisabled bool `json:"is_disabled,omitempty"` URL string `json:"url,omitempty"` @@ -118,6 +134,8 @@ type LinkPreviewOptions struct { ShowAboveText bool `json:"show_above_text,omitempty"` } +// ReplyMarkup represents a custom keyboard or inline keyboard. +// See https://core.telegram.org/bots/api#replymarkup type ReplyMarkup struct { InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard,omitempty"` @@ -132,11 +150,18 @@ type ReplyMarkup struct { ForceReply bool `json:"force_reply,omitempty"` } + +// InlineKeyboardMarkup represents an inline keyboard that appears right next to the message it belongs to. +// See https://core.telegram.org/bots/api#inlinekeyboardmarkup type InlineKeyboardMarkup struct { InlineKeyboard [][]InlineKeyboardButton `json:"inline_keyboard,omitempty"` } +// KeyboardButtonStyle represents the style of a keyboard button. type KeyboardButtonStyle string + +// InlineKeyboardButton represents one button of an inline keyboard. +// See https://core.telegram.org/bots/api#inlinekeyboardbutton type InlineKeyboardButton struct { Text string `json:"text"` URL string `json:"url,omitempty"` @@ -145,10 +170,14 @@ type InlineKeyboardButton struct { IconCustomEmojiID string `json:"icon_custom_emoji_id,omitempty"` } +// ReplyKeyboardMarkup represents a custom keyboard with reply options. +// See https://core.telegram.org/bots/api#replykeyboardmarkup type ReplyKeyboardMarkup struct { Keyboard [][]int `json:"keyboard"` } +// CallbackQuery represents an incoming callback query from a callback button in an inline keyboard. +// See https://core.telegram.org/bots/api#callbackquery type CallbackQuery struct { ID string `json:"id"` From User `json:"from"` @@ -157,11 +186,15 @@ type CallbackQuery struct { Data string `json:"data"` } +// InputPollOption contains information about one answer option in a poll to be sent. +// See https://core.telegram.org/bots/api#inputpolloption type InputPollOption struct { Text string `json:"text"` TextParseMode ParseMode `json:"text_parse_mode,omitempty"` TextEntities []*MessageEntity `json:"text_entities,omitempty"` } + +// PollType represents the type of a poll. type PollType string const ( @@ -169,12 +202,15 @@ const ( PollTypeQuiz PollType = "quiz" ) +// InputChecklistTask describes a task in a checklist. type InputChecklistTask struct { ID int `json:"id"` Text string `json:"text"` ParseMode ParseMode `json:"parse_mode,omitempty"` TextEntities []*MessageEntity `json:"text_entities,omitempty"` } + +// InputChecklist represents a checklist to be sent. type InputChecklist struct { Title string `json:"title"` ParseMode ParseMode `json:"parse_mode,omitempty"` @@ -184,6 +220,7 @@ type InputChecklist struct { OtherCanMarkTasksAsDone bool `json:"other_can_mark_tasks_as_done,omitempty"` } +// ChatActionType represents the type of chat action. type ChatActionType string const ( @@ -197,6 +234,8 @@ const ( ChatActionUploadVideoNone ChatActionType = "upload_video_none" ) +// MessageReactionUpdated represents a change of a reaction on a message. +// See https://core.telegram.org/bots/api#messagereactionupdated type MessageReactionUpdated struct { Chat *Chat `json:"chat"` MessageID int `json:"message_id"` @@ -207,12 +246,17 @@ type MessageReactionUpdated struct { NewReaction []ReactionType `json:"new_reaction"` } +// MessageReactionCountUpdated represents a change in the count of reactions on a message. +// See https://core.telegram.org/bots/api#messagereactioncountupdated type MessageReactionCountUpdated struct { Chat *Chat `json:"chat"` MessageID int `json:"message_id"` Date int `json:"date"` Reactions []*ReactionCount `json:"reactions"` } + +// ReactionType describes the type of a reaction. +// See https://core.telegram.org/bots/api#reactiontype type ReactionType struct { Type string `json:"type"` // ReactionTypeEmoji @@ -220,20 +264,29 @@ type ReactionType struct { // ReactionTypeCustomEmoji CustomEmojiID *string `json:"custom_emoji_id,omitempty"` } + +// ReactionCount represents a reaction added to a message along with the number of times it was added. +// See https://core.telegram.org/bots/api#reactioncount type ReactionCount struct { Type ReactionType `json:"type"` TotalCount int `json:"total_count"` } +// SuggestedPostPrice represents the price of a suggested post. type SuggestedPostPrice struct { Currency string `json:"currency"` Amount int `json:"amount"` } + +// SuggestedPostInfo contains information about a suggested post. +// See https://core.telegram.org/bots/api#suggestedpostinfo type SuggestedPostInfo struct { - State string `json:"state"` //State of the suggested post. Currently, it can be one of “pending”, “approved”, “declined”. + State string `json:"state"` // "pending", "approved", or "declined" Price SuggestedPostPrice `json:"price"` SendDate int `json:"send_date"` } + +// SuggestedPostParameters holds parameters for suggesting a post. type SuggestedPostParameters struct { Price SuggestedPostPrice `json:"price"` SendDate int `json:"send_date"` diff --git a/tgapi/methods.go b/tgapi/methods.go index c9f467e..44887d3 100644 --- a/tgapi/methods.go +++ b/tgapi/methods.go @@ -6,19 +6,28 @@ import ( "net/http" ) +// ParseMode represents the text formatting mode for message parsing. type ParseMode string const ( + // ParseMDV2 enables MarkdownV2 style parsing. ParseMDV2 ParseMode = "MarkdownV2" + // ParseHTML enables HTML style parsing. ParseHTML ParseMode = "HTML" - ParseMD ParseMode = "Markdown" + // ParseMD enables legacy Markdown style parsing. + ParseMD ParseMode = "Markdown" + // ParseNone disables any parsing. ParseNone ParseMode = "None" ) +// EmptyParams is a placeholder for methods that take no parameters. type EmptyParams struct{} +// NoParams is a convenient instance of EmptyParams. var NoParams = EmptyParams{} +// UpdateParams holds parameters for the getUpdates method. +// See https://core.telegram.org/bots/api#getupdates type UpdateParams struct { Offset *int `json:"offset,omitempty"` Limit *int `json:"limit,omitempty"` @@ -26,32 +35,52 @@ type UpdateParams struct { AllowedUpdates []UpdateType `json:"allowed_updates"` } +// GetMe returns basic information about the bot. +// See https://core.telegram.org/bots/api#getme func (api *API) GetMe() (User, error) { req := NewRequest[User, EmptyParams]("getMe", NoParams) return req.Do(api) } + +// LogOut logs the bot out from the cloud Bot API server. +// Returns true on success. +// See https://core.telegram.org/bots/api#logout func (api *API) LogOut() (bool, error) { req := NewRequest[bool, EmptyParams]("logOut", NoParams) return req.Do(api) } + +// Close closes the bot instance on the local server. +// Returns true on success. +// See https://core.telegram.org/bots/api#close func (api *API) Close() (bool, error) { req := NewRequest[bool, EmptyParams]("close", NoParams) return req.Do(api) } + +// GetUpdates receives incoming updates using long polling. +// See https://core.telegram.org/bots/api#getupdates func (api *API) GetUpdates(params UpdateParams) ([]Update, error) { req := NewRequest[[]Update]("getUpdates", params) return req.Do(api) } +// GetFileP holds parameters for the getFile method. +// See https://core.telegram.org/bots/api#getfile type GetFileP struct { FileId string `json:"file_id"` } +// GetFile returns basic information about a file and prepares it for downloading. +// See https://core.telegram.org/bots/api#getfile func (api *API) GetFile(params GetFileP) (File, error) { req := NewRequest[File]("getFile", params) return req.Do(api) } +// GetFileByLink downloads a file from Telegram's file server using the provided file link. +// The link is usually obtained from File.FilePath. +// See https://core.telegram.org/bots/api#file func (api *API) GetFileByLink(link string) ([]byte, error) { u := fmt.Sprintf("https://api.telegram.org/file/bot%s/%s", api.token, link) res, err := http.Get(u) diff --git a/tgapi/stickers_methods.go b/tgapi/stickers_methods.go index 152bf56..ff0b944 100644 --- a/tgapi/stickers_methods.go +++ b/tgapi/stickers_methods.go @@ -1,5 +1,7 @@ package tgapi +// SendStickerP holds parameters for the sendSticker method. +// See https://core.telegram.org/bots/api#sendsticker type SendStickerP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -14,29 +16,41 @@ type SendStickerP struct { MessageEffectID string `json:"message_effect_id,omitempty"` } +// SendSticker sends a static .WEBP, animated .TGS, or video .WEBM sticker. +// See https://core.telegram.org/bots/api#sendsticker func (api *API) SendSticker(params SendStickerP) (Message, error) { req := NewRequestWithChatID[Message]("sendSticker", params, params.ChatID) return req.Do(api) } +// GetStickerSetP holds parameters for the getStickerSet method. +// See https://core.telegram.org/bots/api#getstickerset type GetStickerSetP struct { Name string `json:"name"` } +// GetStickerSet returns a sticker set by its name. +// See https://core.telegram.org/bots/api#getstickerset func (api *API) GetStickerSet(params GetStickerSetP) (StickerSet, error) { req := NewRequest[StickerSet]("getStickerSet", params) return req.Do(api) } +// GetCustomEmojiStickersP holds parameters for the getCustomEmojiStickers method. +// See https://core.telegram.org/bots/api#getcustomemojistickers type GetCustomEmojiStickersP struct { CustomEmojiIDs []string `json:"custom_emoji_ids"` } +// GetCustomEmojiStickers returns information about custom emoji stickers by their IDs. +// See https://core.telegram.org/bots/api#getcustomemojistickers func (api *API) GetCustomEmojiStickers(params GetCustomEmojiStickersP) ([]Sticker, error) { req := NewRequest[[]Sticker]("getCustomEmojiStickers", params) return req.Do(api) } +// CreateNewStickerSetP holds parameters for the createNewStickerSet method. +// See https://core.telegram.org/bots/api#createnewstickerset type CreateNewStickerSetP struct { UserID int `json:"user_id"` Name string `json:"name"` @@ -47,41 +61,61 @@ type CreateNewStickerSetP struct { NeedsRepainting bool `json:"needs_repainting,omitempty"` } +// CreateNewStickerSet creates a new sticker set owned by a user. +// Returns True on success. +// See https://core.telegram.org/bots/api#createnewstickerset func (api *API) CreateNewStickerSet(params CreateNewStickerSetP) (bool, error) { req := NewRequest[bool]("createNewStickerSet", params) return req.Do(api) } +// AddStickerToSetP holds parameters for the addStickerToSet method. +// See https://core.telegram.org/bots/api#addstickertoset type AddStickerToSetP struct { UserID int `json:"user_id"` Name string `json:"name"` Sticker InputSticker `json:"sticker"` } +// AddStickerToSet adds a new sticker to a set created by the bot. +// Returns True on success. +// See https://core.telegram.org/bots/api#addstickertoset func (api *API) AddStickerToSet(params AddStickerToSetP) (bool, error) { req := NewRequest[bool]("addStickerToSet", params) return req.Do(api) } +// SetStickerPositionInSetP holds parameters for the setStickerPositionInSet method. +// See https://core.telegram.org/bots/api#setstickerpositioninset type SetStickerPositionInSetP struct { Sticker string `json:"sticker"` Position int `json:"position"` } -func (api *API) SetStickerPosition(params SetStickerPositionInSetP) (bool, error) { - req := NewRequest[bool]("setStickerPosition", params) +// SetStickerPositionInSet moves a sticker in a set to a specific position. +// Returns True on success. +// See https://core.telegram.org/bots/api#setstickerpositioninset +func (api *API) SetStickerPositionInSet(params SetStickerPositionInSetP) (bool, error) { + req := NewRequest[bool]("setStickerPositionInSet", params) return req.Do(api) } +// DeleteStickerFromSetP holds parameters for the deleteStickerFromSet method. +// See https://core.telegram.org/bots/api#deletestickerfromset type DeleteStickerFromSetP struct { Sticker string `json:"sticker"` } +// DeleteStickerFromSet deletes a sticker from a set created by the bot. +// Returns True on success. +// See https://core.telegram.org/bots/api#deletestickerfromset func (api *API) DeleteStickerFromSet(params DeleteStickerFromSetP) (bool, error) { req := NewRequest[bool]("deleteStickerFromSet", params) return req.Do(api) } +// ReplaceStickerInSetP holds parameters for the replaceStickerInSet method. +// See https://core.telegram.org/bots/api#replacestickerinset type ReplaceStickerInSetP struct { UserID int `json:"user_id"` Name string `json:"name"` @@ -89,51 +123,76 @@ type ReplaceStickerInSetP struct { Sticker InputSticker `json:"sticker"` } +// ReplaceStickerInSet replaces an existing sticker in a set with a new one. +// Returns True on success. +// See https://core.telegram.org/bots/api#replacestickerinset func (api *API) ReplaceStickerInSet(params ReplaceStickerInSetP) (bool, error) { req := NewRequest[bool]("replaceStickerInSet", params) return req.Do(api) } +// SetStickerEmojiListP holds parameters for the setStickerEmojiList method. +// See https://core.telegram.org/bots/api#setstickeremojilist type SetStickerEmojiListP struct { Sticker string `json:"sticker"` EmojiList []string `json:"emoji_list"` } +// SetStickerEmojiList changes the list of emoji associated with a sticker. +// Returns True on success. +// See https://core.telegram.org/bots/api#setstickeremojilist func (api *API) SetStickerEmojiList(params SetStickerEmojiListP) (bool, error) { req := NewRequest[bool]("setStickerEmojiList", params) return req.Do(api) } +// SetStickerKeywordsP holds parameters for the setStickerKeywords method. +// See https://core.telegram.org/bots/api#setstickerkeywords type SetStickerKeywordsP struct { Sticker string `json:"sticker"` Keywords []string `json:"keywords"` } +// SetStickerKeywords changes the keywords of a sticker. +// Returns True on success. +// See https://core.telegram.org/bots/api#setstickerkeywords func (api *API) SetStickerKeywords(params SetStickerKeywordsP) (bool, error) { req := NewRequest[bool]("setStickerKeywords", params) return req.Do(api) } +// SetStickerMaskPositionP holds parameters for the setStickerMaskPosition method. +// See https://core.telegram.org/bots/api#setstickermaskposition type SetStickerMaskPositionP struct { Sticker string `json:"sticker"` MaskPosition *MaskPosition `json:"mask_position,omitempty"` } +// SetStickerMaskPosition changes the mask position of a mask sticker. +// Returns True on success. +// See https://core.telegram.org/bots/api#setstickermaskposition func (api *API) SetStickerMaskPosition(params SetStickerMaskPositionP) (bool, error) { req := NewRequest[bool]("setStickerMaskPosition", params) return req.Do(api) } +// SetStickerSetTitleP holds parameters for the setStickerSetTitle method. +// See https://core.telegram.org/bots/api#setstickersettitle type SetStickerSetTitleP struct { Name string `json:"name"` Title string `json:"title"` } +// SetStickerSetTitle sets the title of a sticker set created by the bot. +// Returns True on success. +// See https://core.telegram.org/bots/api#setstickersettitle func (api *API) SetStickerSetTitle(params SetStickerSetTitleP) (bool, error) { req := NewRequest[bool]("setStickerSetTitle", params) return req.Do(api) } +// SetStickerSetThumbnailP holds parameters for the setStickerSetThumbnail method. +// See https://core.telegram.org/bots/api#setstickersetthumbnail type SetStickerSetThumbnailP struct { Name string `json:"name"` UserID int `json:"user_id"` @@ -141,25 +200,40 @@ type SetStickerSetThumbnailP struct { Format InputStickerFormat `json:"format"` } +// SetStickerSetThumbnail sets the thumbnail of a sticker set. +// Returns True on success. +// See https://core.telegram.org/bots/api#setstickersetthumbnail func (api *API) SetStickerSetThumbnail(params SetStickerSetThumbnailP) (bool, error) { req := NewRequest[bool]("setStickerSetThumbnail", params) return req.Do(api) } +// SetCustomEmojiStickerSetThumbnailP holds parameters for the setCustomEmojiStickerSetThumbnail method. +// See https://core.telegram.org/bots/api#setcustomemojistickersetthumbnail type SetCustomEmojiStickerSetThumbnailP struct { Name string `json:"name"` CustomEmojiID string `json:"custom_emoji_id,omitempty"` } +// SetCustomEmojiStickerSetThumbnail sets the thumbnail of a custom emoji sticker set. +// Returns True on success. +// See https://core.telegram.org/bots/api#setcustomemojistickersetthumbnail +// +// Note: This method uses SetStickerSetThumbnailP as its parameter type, which might be inconsistent. func (api *API) SetCustomEmojiStickerSetThumbnail(params SetStickerSetThumbnailP) (bool, error) { req := NewRequest[bool]("setCustomEmojiStickerSetThumbnail", params) return req.Do(api) } +// DeleteStickerSetP holds parameters for the deleteStickerSet method. +// See https://core.telegram.org/bots/api#deletestickerset type DeleteStickerSetP struct { Name string `json:"name"` } +// DeleteStickerSet deletes a sticker set created by the bot. +// Returns True on success. +// See https://core.telegram.org/bots/api#deletestickerset func (api *API) DeleteStickerSet(params DeleteStickerSetP) (bool, error) { req := NewRequest[bool]("deleteStickerSet", params) return req.Do(api) diff --git a/tgapi/stickers_types.go b/tgapi/stickers_types.go index 299c492..d9056c8 100644 --- a/tgapi/stickers_types.go +++ b/tgapi/stickers_types.go @@ -1,14 +1,21 @@ package tgapi +// MaskPositionPoint represents the part of the face where a mask should be placed. type MaskPositionPoint string const ( + // MaskPositionForehead places the mask on the forehead. MaskPositionForehead MaskPositionPoint = "forehead" - MaskPositionEyes MaskPositionPoint = "eyes" - MaskPositionMouth MaskPositionPoint = "mouth" - MaskPositionChin MaskPositionPoint = "chin" + // MaskPositionEyes places the mask on the eyes. + MaskPositionEyes MaskPositionPoint = "eyes" + // MaskPositionMouth places the mask on the mouth. + MaskPositionMouth MaskPositionPoint = "mouth" + // MaskPositionChin places the mask on the chin. + MaskPositionChin MaskPositionPoint = "chin" ) +// MaskPosition describes the position on faces where a mask should be placed by default. +// See https://core.telegram.org/bots/api#maskposition type MaskPosition struct { Point MaskPositionPoint `json:"point"` XShift float32 `json:"x_shift"` @@ -16,14 +23,20 @@ type MaskPosition struct { Scale float32 `json:"scale"` } +// StickerType represents the type of a sticker. type StickerType string const ( - StickerTypeRegular StickerType = "regular" - StickerTypeMask StickerType = "mask" + // StickerTypeRegular is a regular sticker. + StickerTypeRegular StickerType = "regular" + // StickerTypeMask is a mask sticker that can be placed on faces. + StickerTypeMask StickerType = "mask" + // StickerTypeCustomEmoji is a custom emoji sticker. StickerTypeCustomEmoji StickerType = "custom_emoji" ) +// Sticker represents a sticker. +// See https://core.telegram.org/bots/api#sticker type Sticker struct { FileId string `json:"file_id"` FileUniqueId string `json:"file_unique_id"` @@ -41,6 +54,9 @@ type Sticker struct { NeedRepainting *bool `json:"need_repainting,omitempty"` FileSize *int `json:"file_size,omitempty"` } + +// StickerSet represents a sticker set. +// See https://core.telegram.org/bots/api#stickerset type StickerSet struct { Name string `json:"name"` Title string `json:"title"` @@ -48,14 +64,21 @@ type StickerSet struct { Stickers []Sticker `json:"stickers"` Thumbnail *PhotoSize `json:"thumbnail,omitempty"` } + +// InputStickerFormat represents the format of an input sticker. type InputStickerFormat string const ( - InputStickerFormatStatic InputStickerFormat = "static" + // InputStickerFormatStatic is a static sticker (WEBP). + InputStickerFormatStatic InputStickerFormat = "static" + // InputStickerFormatAnimated is an animated sticker (TGS). InputStickerFormatAnimated InputStickerFormat = "animated" - InputStickerFormatVideo InputStickerFormat = "video" + // InputStickerFormatVideo is a video sticker (WEBM). + InputStickerFormatVideo InputStickerFormat = "video" ) +// InputSticker describes a sticker to be added to a sticker set. +// See https://core.telegram.org/bots/api#inputsticker type InputSticker struct { Sticker string `json:"sticker"` Format InputStickerFormat `json:"format"` diff --git a/tgapi/types.go b/tgapi/types.go index 4fcf7fb..6db8b2c 100644 --- a/tgapi/types.go +++ b/tgapi/types.go @@ -1,35 +1,61 @@ package tgapi +// UpdateType represents the type of an incoming update. type UpdateType string const ( - UpdateTypeMessage UpdateType = "message" - UpdateTypeEditedMessage UpdateType = "edited_message" - UpdateTypeChannelPost UpdateType = "channel_post" - UpdateTypeEditedChannelPost UpdateType = "edited_channel_post" - UpdateTypeMessageReaction UpdateType = "message_reaction" + // UpdateTypeMessage is a regular message update. + UpdateTypeMessage UpdateType = "message" + // UpdateTypeEditedMessage is an edited message update. + UpdateTypeEditedMessage UpdateType = "edited_message" + // UpdateTypeChannelPost is a channel post update. + UpdateTypeChannelPost UpdateType = "channel_post" + // UpdateTypeEditedChannelPost is an edited channel post update. + UpdateTypeEditedChannelPost UpdateType = "edited_channel_post" + // UpdateTypeMessageReaction is a message reaction update. + UpdateTypeMessageReaction UpdateType = "message_reaction" + // UpdateTypeMessageReactionCount is a message reaction count update. UpdateTypeMessageReactionCount UpdateType = "message_reaction_count" - UpdateTypeBusinessConnection UpdateType = "business_connection" - UpdateTypeBusinessMessage UpdateType = "business_message" - UpdateTypeEditedBusinessMessage UpdateType = "edited_business_message" + // UpdateTypeBusinessConnection is a business connection update. + UpdateTypeBusinessConnection UpdateType = "business_connection" + // UpdateTypeBusinessMessage is a business message update. + UpdateTypeBusinessMessage UpdateType = "business_message" + // UpdateTypeEditedBusinessMessage is an edited business message update. + UpdateTypeEditedBusinessMessage UpdateType = "edited_business_message" + // UpdateTypeDeletedBusinessMessage is a deleted business message update. UpdateTypeDeletedBusinessMessage UpdateType = "deleted_business_message" - UpdateTypeInlineQuery UpdateType = "inline_query" + // UpdateTypeInlineQuery is an inline query update. + UpdateTypeInlineQuery UpdateType = "inline_query" + // UpdateTypeChosenInlineResult is a chosen inline result update. UpdateTypeChosenInlineResult UpdateType = "chosen_inline_result" - UpdateTypeCallbackQuery UpdateType = "callback_query" - UpdateTypeShippingQuery UpdateType = "shipping_query" - UpdateTypePreCheckoutQuery UpdateType = "pre_checkout_query" + // UpdateTypeCallbackQuery is a callback query update. + UpdateTypeCallbackQuery UpdateType = "callback_query" + // UpdateTypeShippingQuery is a shipping query update. + UpdateTypeShippingQuery UpdateType = "shipping_query" + // UpdateTypePreCheckoutQuery is a pre-checkout query update. + UpdateTypePreCheckoutQuery UpdateType = "pre_checkout_query" + // UpdateTypePurchasedPaidMedia is a purchased paid media update. UpdateTypePurchasedPaidMedia UpdateType = "purchased_paid_media" - UpdateTypePoll UpdateType = "poll" - UpdateTypePollAnswer UpdateType = "poll_answer" - UpdateTypeMyChatMember UpdateType = "my_chat_member" - UpdateTypeChatMember UpdateType = "chat_member" - UpdateTypeChatJoinRequest UpdateType = "chat_join_request" - UpdateTypeChatBoost UpdateType = "chat_boost" - UpdateTypeRemovedChatBoost UpdateType = "removed_chat_boost" + // UpdateTypePoll is a poll update. + UpdateTypePoll UpdateType = "poll" + // UpdateTypePollAnswer is a poll answer update. + UpdateTypePollAnswer UpdateType = "poll_answer" + // UpdateTypeMyChatMember is a my chat member update. + UpdateTypeMyChatMember UpdateType = "my_chat_member" + // UpdateTypeChatMember is a chat member update. + UpdateTypeChatMember UpdateType = "chat_member" + // UpdateTypeChatJoinRequest is a chat join request update. + UpdateTypeChatJoinRequest UpdateType = "chat_join_request" + // UpdateTypeChatBoost is a chat boost update. + UpdateTypeChatBoost UpdateType = "chat_boost" + // UpdateTypeRemovedChatBoost is a removed chat boost update. + UpdateTypeRemovedChatBoost UpdateType = "removed_chat_boost" ) +// Update represents an incoming update from Telegram. +// See https://core.telegram.org/bots/api#update type Update struct { UpdateID int `json:"update_id"` Message *Message `json:"message,omitempty"` @@ -60,6 +86,8 @@ type Update struct { RemovedChatBoost *ChatBoostRemoved `json:"removed_chat_boost,omitempty"` } +// InlineQuery represents an incoming inline query. +// See https://core.telegram.org/bots/api#inlinequery type InlineQuery struct { ID string `json:"id"` From User `json:"from"` @@ -68,6 +96,9 @@ type InlineQuery struct { ChatType *ChatType `json:"chat_type,omitempty"` Location *Location `json:"location,omitempty"` } + +// ChosenInlineResult represents a result of an inline query that was chosen by the user. +// See https://core.telegram.org/bots/api#choseninlineresult type ChosenInlineResult struct { ResultID string `json:"result_id"` From User `json:"from"` @@ -76,12 +107,17 @@ type ChosenInlineResult struct { Query string `json:"query"` } +// ShippingQuery represents an incoming shipping query. +// See https://core.telegram.org/bots/api#shippingquery type ShippingQuery struct { ID string `json:"id"` From User `json:"from"` InvoicePayload string `json:"invoice_payload"` ShippingAddress ShippingAddress `json:"shipping_address"` } + +// ShippingAddress represents a shipping address. +// See https://core.telegram.org/bots/api#shippingaddress type ShippingAddress struct { CountryCode string `json:"country_code"` State string `json:"state"` @@ -91,12 +127,17 @@ type ShippingAddress struct { PostCode string `json:"post_code"` } +// OrderInfo represents information about an order. +// See https://core.telegram.org/bots/api#orderinfo type OrderInfo struct { Name string `json:"name"` PhoneNumber string `json:"phone_number"` Email string `json:"email"` ShippingAddress ShippingAddress `json:"shipping_address"` } + +// PreCheckoutQuery represents an incoming pre-checkout query. +// See https://core.telegram.org/bots/api#precheckoutquery type PreCheckoutQuery struct { ID string `json:"id"` From User `json:"from"` @@ -107,11 +148,15 @@ type PreCheckoutQuery struct { OrderInfo *OrderInfo `json:"order_info,omitempty"` } +// PaidMediaPurchased represents a purchased paid media. +// See https://core.telegram.org/bots/api#paidmediapurchased type PaidMediaPurchased struct { From User `json:"from"` PaidMediaPayload string `json:"paid_media_payload"` } +// File represents a file ready to be downloaded. +// See https://core.telegram.org/bots/api#file type File struct { FileId string `json:"file_id"` FileUniqueID string `json:"file_unique_id"` @@ -119,6 +164,8 @@ type File struct { FilePath string `json:"file_path,omitempty"` } +// Audio represents an audio file to be treated as music by the Telegram clients. +// See https://core.telegram.org/bots/api#audio type Audio struct { FileID string `json:"file_id"` FileUniqueID string `json:"file_unique_id"` @@ -132,11 +179,16 @@ type Audio struct { Thumbnail *PhotoSize `json:"thumbnail,omitempty"` } +// PollOption contains information about one answer option in a poll. +// See https://core.telegram.org/bots/api#polloption type PollOption struct { Text string `json:"text"` TextEntities []MessageEntity `json:"text_entities"` VoterCount int `json:"voter_count"` } + +// Poll contains information about a poll. +// See https://core.telegram.org/bots/api#poll type Poll struct { ID string `json:"id"` Question string `json:"question"` @@ -154,12 +206,18 @@ type Poll struct { OpenPeriod int `json:"open_period,omitempty"` CloseDate int `json:"close_date,omitempty"` } + +// PollAnswer represents an answer of a user in a poll. +// See https://core.telegram.org/bots/api#pollanswer type PollAnswer struct { PollID string `json:"poll_id"` VoterChat Chat `json:"voter_chat"` User User `json:"user"` OptionIDS []int `json:"option_ids"` } + +// ChatMemberUpdated represents changes in the status of a chat member. +// See https://core.telegram.org/bots/api#chatmemberupdated type ChatMemberUpdated struct { Chat Chat `json:"chat"` From User `json:"from"` @@ -171,6 +229,8 @@ type ChatMemberUpdated struct { ViaChatFolderInviteLink *bool `json:"via_chat_folder_invite_link,omitempty"` } +// ChatJoinRequest represents a join request sent to a chat. +// See https://core.telegram.org/bots/api#chatjoinrequest type ChatJoinRequest struct { Chat Chat `json:"chat"` From User `json:"from"` @@ -180,6 +240,8 @@ type ChatJoinRequest struct { InviteLink *ChatInviteLink `json:"invite_link,omitempty"` } +// Location represents a point on the map. +// See https://core.telegram.org/bots/api#location type Location struct { Latitude float64 `json:"latitude"` Longitude float64 `json:"longitude"` @@ -188,12 +250,17 @@ type Location struct { Heading int `json:"heading"` ProximityAlertRadius int `json:"proximity_alert_radius"` } + +// LocationAddress represents a human-readable address of a location. type LocationAddress struct { CountryCode string `json:"country_code"` State *string `json:"state,omitempty"` City *string `json:"city,omitempty"` Street *string `json:"street,omitempty"` } + +// Venue represents a venue. +// See https://core.telegram.org/bots/api#venue type Venue struct { Location Location `json:"location"` Title string `json:"title"` @@ -204,22 +271,25 @@ type Venue struct { GooglePlaceType string `json:"google_place_type,omitempty"` } +// WebAppInfo contains information about a Web App. +// See https://core.telegram.org/bots/api#webappinfo type WebAppInfo struct { URL string `json:"url"` } +// StarAmount represents an amount of Telegram Stars. type StarAmount struct { Amount int `json:"amount"` NanostarAmount int `json:"nanostar_amount"` } +// Story represents a story. type Story struct { Chat Chat `json:"chat"` ID int `json:"id"` } -// Gifts - +// AcceptedGiftTypes represents the types of gifts accepted by a user or chat. type AcceptedGiftTypes struct { UnlimitedGifts bool `json:"unlimited_gifts"` LimitedGifts bool `json:"limited_gifts"` @@ -228,6 +298,7 @@ type AcceptedGiftTypes struct { GiftsFromChannels bool `json:"gifts_from_channels"` } +// UniqueGiftColors represents color information for a unique gift. type UniqueGiftColors struct { ModelCustomEmojiID string `json:"model_custom_emoji_id"` SymbolCustomEmojiID string `json:"symbol_custom_emoji_id"` @@ -237,11 +308,14 @@ type UniqueGiftColors struct { DarkThemeOtherColors []int `json:"dark_theme_other_colors"` } +// GiftBackground represents the background of a gift. type GiftBackground struct { CenterColor int `json:"center_color"` EdgeColor int `json:"edge_color"` TextColor int `json:"text_color"` } + +// Gift represents a gift that can be sent. type Gift struct { ID string `json:"id"` Sticker Sticker `json:"sticker"` @@ -257,10 +331,13 @@ type Gift struct { UniqueGiftVariantColor *int `json:"unique_gift_variant_color,omitempty"` PublisherChat *Chat `json:"publisher_chat,omitempty"` } + +// Gifts represents a list of gifts. type Gifts struct { Gifts []Gift `json:"gifts"` } +// OwnedGiftType represents the type of an owned gift. type OwnedGiftType string const ( @@ -268,13 +345,14 @@ const ( OwnedGiftUniqueType OwnedGiftType = "unique" ) +// OwnedGift represents a gift owned by a user or chat. type OwnedGift struct { Type OwnedGiftType `json:"type"` OwnerGiftID *string `json:"owner_gift_id,omitempty"` SendDate *int `json:"send_date,omitempty"` IsSaved *bool `json:"is_saved,omitempty"` - // Поля, характерные для "regular" + // Fields specific to "regular" type Gift Gift `json:"gift"` SenderUser User `json:"sender_user,omitempty"` Text string `json:"text,omitempty"` @@ -287,12 +365,13 @@ type OwnedGift struct { IsUpgradeSeparate *bool `json:"is_upgrade_separate,omitempty"` UniqueGiftNumber *int `json:"unique_gift_number,omitempty"` - // Поля, характерные для "unique" + // Fields specific to "unique" type CanBeTransferred *bool `json:"can_be_transferred,omitempty"` TransferStarCount *int `json:"transfer_star_count,omitempty"` NextTransferDate *int `json:"next_transfer_date,omitempty"` } +// OwnedGifts represents a list of owned gifts with pagination. type OwnedGifts struct { TotalCount int `json:"total_count"` Gifts []OwnedGift `json:"gifts"` diff --git a/tgapi/uploader_methods.go b/tgapi/uploader_methods.go index 30931fd..892674d 100644 --- a/tgapi/uploader_methods.go +++ b/tgapi/uploader_methods.go @@ -1,5 +1,7 @@ package tgapi +// UploadPhotoP holds parameters for uploading a photo using the Uploader. +// See https://core.telegram.org/bots/api#sendphoto type UploadPhotoP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -22,11 +24,16 @@ type UploadPhotoP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// UploadPhoto uploads a photo and sends it as a message. +// file is the photo file to upload. +// See https://core.telegram.org/bots/api#sendphoto func (u *Uploader) UploadPhoto(params UploadPhotoP, file UploaderFile) (Message, error) { req := NewUploaderRequestWithChatID[Message]("sendPhoto", params, params.ChatID, file) return req.Do(u) } +// UploadAudioP holds parameters for uploading an audio file using the Uploader. +// See https://core.telegram.org/bots/api#sendaudio type UploadAudioP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -51,11 +58,16 @@ type UploadAudioP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// UploadAudio uploads an audio file and sends it as a message. +// files are the audio file(s) to upload (typically one file). +// See https://core.telegram.org/bots/api#sendaudio func (u *Uploader) UploadAudio(params UploadAudioP, files ...UploaderFile) (Message, error) { req := NewUploaderRequestWithChatID[Message]("sendAudio", params, params.ChatID, files...) return req.Do(u) } +// UploadDocumentP holds parameters for uploading a document using the Uploader. +// See https://core.telegram.org/bots/api#senddocument type UploadDocumentP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -77,11 +89,16 @@ type UploadDocumentP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// UploadDocument uploads a document and sends it as a message. +// files are the document file(s) to upload (typically one file). +// See https://core.telegram.org/bots/api#senddocument func (u *Uploader) UploadDocument(params UploadDocumentP, files ...UploaderFile) (Message, error) { req := NewUploaderRequest[Message]("sendDocument", params, files...) return req.Do(u) } +// UploadVideoP holds parameters for uploading a video using the Uploader. +// See https://core.telegram.org/bots/api#sendvideo type UploadVideoP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -110,11 +127,16 @@ type UploadVideoP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// UploadVideo uploads a video and sends it as a message. +// files are the video file(s) to upload (typically one file). +// See https://core.telegram.org/bots/api#sendvideo func (u *Uploader) UploadVideo(params UploadVideoP, files ...UploaderFile) (Message, error) { req := NewUploaderRequest[Message]("sendVideo", params, files...) return req.Do(u) } +// UploadAnimationP holds parameters for uploading an animation using the Uploader. +// See https://core.telegram.org/bots/api#sendanimation type UploadAnimationP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -141,11 +163,16 @@ type UploadAnimationP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// UploadAnimation uploads an animation (GIF or H.264/MPEG-4 AVC video without sound) and sends it as a message. +// files are the animation file(s) to upload (typically one file). +// See https://core.telegram.org/bots/api#sendanimation func (u *Uploader) UploadAnimation(params UploadAnimationP, files ...UploaderFile) (Message, error) { req := NewUploaderRequest[Message]("sendAnimation", params, files...) return req.Do(u) } +// UploadVoiceP holds parameters for uploading a voice note using the Uploader. +// See https://core.telegram.org/bots/api#sendvoice type UploadVoiceP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -167,11 +194,16 @@ type UploadVoiceP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// UploadVoice uploads a voice note and sends it as a message. +// files are the voice file(s) to upload (typically one file). +// See https://core.telegram.org/bots/api#sendvoice func (u *Uploader) UploadVoice(params UploadVoiceP, files ...UploaderFile) (Message, error) { req := NewUploaderRequest[Message]("sendVoice", params, files...) return req.Do(u) } +// UploadVideoNoteP holds parameters for uploading a video note (rounded video) using the Uploader. +// See https://core.telegram.org/bots/api#sendvideonote type UploadVideoNoteP struct { BusinessConnectionID string `json:"business_connection_id,omitempty"` ChatID int64 `json:"chat_id"` @@ -191,15 +223,23 @@ type UploadVideoNoteP struct { ReplyMarkup *ReplyMarkup `json:"reply_markup,omitempty"` } +// UploadVideoNote uploads a video note (rounded video) and sends it as a message. +// files are the video note file(s) to upload (typically one file). +// See https://core.telegram.org/bots/api#sendvideonote func (u *Uploader) UploadVideoNote(params UploadVideoNoteP, files ...UploaderFile) (Message, error) { req := NewUploaderRequest[Message]("sendVideoNote", params, files...) return req.Do(u) } +// UploadChatPhotoP holds parameters for uploading a chat photo using the Uploader. +// See https://core.telegram.org/bots/api#setchatphoto type UploadChatPhotoP struct { ChatID int64 `json:"chat_id"` } +// UploadChatPhoto uploads a new chat photo. +// photo is the photo file to upload. +// See https://core.telegram.org/bots/api#setchatphoto func (u *Uploader) UploadChatPhoto(params UploadChatPhotoP, photo UploaderFile) (Message, error) { req := NewUploaderRequest[Message]("sendChatPhoto", params, photo) return req.Do(u) diff --git a/tgapi/users_methods.go b/tgapi/users_methods.go index a2cad10..637c316 100644 --- a/tgapi/users_methods.go +++ b/tgapi/users_methods.go @@ -1,38 +1,53 @@ package tgapi +// GetUserProfilePhotosP holds parameters for the GetUserProfilePhotos method. +// See https://core.telegram.org/bots/api#getuserprofilephotos type GetUserProfilePhotosP struct { UserID int `json:"user_id"` Offset int `json:"offset,omitempty"` Limit int `json:"limit,omitempty"` } +// GetUserProfilePhotos returns a list of profile pictures for a user. +// See https://core.telegram.org/bots/api#getuserprofilephotos func (api *API) GetUserProfilePhotos(params GetUserProfilePhotosP) (UserProfilePhotos, error) { req := NewRequest[UserProfilePhotos]("getUserProfilePhotos", params) return req.Do(api) } +// GetUserProfileAudiosP holds parameters for the GetUserProfileAudios method. +// See https://core.telegram.org/bots/api#getuserprofileaudios type GetUserProfileAudiosP struct { UserID int `json:"user_id"` Offset int `json:"offset,omitempty"` Limit int `json:"limit,omitempty"` } +// GetUserProfileAudios returns a list of profile audios for a user. +// See https://core.telegram.org/bots/api#getuserprofileaudios func (api *API) GetUserProfileAudios(params GetUserProfileAudiosP) (UserProfileAudios, error) { req := NewRequest[UserProfileAudios]("getUserProfileAudios", params) return req.Do(api) } +// SetUserEmojiStatusP holds parameters for the SetUserEmojiStatus method. +// See https://core.telegram.org/bots/api#setuseremojistatus type SetUserEmojiStatusP struct { UserID int `json:"user_id"` EmojiID string `json:"emoji_status_custom_emoji_id,omitempty"` ExpirationDate int `json:"emoji_status_expiration_date,omitempty"` } +// SetUserEmojiStatus sets a custom emoji status for a user. +// Returns true on success. +// See https://core.telegram.org/bots/api#setuseremojistatus func (api *API) SetUserEmojiStatus(params SetUserEmojiStatusP) (bool, error) { req := NewRequest[bool]("setUserEmojiStatus", params) return req.Do(api) } +// GetUserGiftsP holds parameters for the GetUserGifts method. +// See https://core.telegram.org/bots/api#getusergifts type GetUserGiftsP struct { UserID int `json:"user_id"` ExcludeUnlimited bool `json:"exclude_unlimited,omitempty"` @@ -45,6 +60,8 @@ type GetUserGiftsP struct { Limit int `json:"limit,omitempty"` } +// GetUserGifts returns gifts owned by a user. +// See https://core.telegram.org/bots/api#getusergifts func (api *API) GetUserGifts(params GetUserGiftsP) (OwnedGifts, error) { req := NewRequest[OwnedGifts]("getUserGifts", params) return req.Do(api) diff --git a/tgapi/users_types.go b/tgapi/users_types.go index b826074..d086ce6 100644 --- a/tgapi/users_types.go +++ b/tgapi/users_types.go @@ -1,5 +1,7 @@ package tgapi +// User represents a Telegram user or bot. +// See https://core.telegram.org/bots/api#user type User struct { ID int `json:"id"` IsBot bool `json:"is_bot"` @@ -18,21 +20,31 @@ type User struct { AllowsUsersToCreateTopics *bool `json:"allows_users_to_create_topics,omitempty"` } +// UserProfilePhotos represents a user's profile photos. +// See https://core.telegram.org/bots/api#userprofilephotos type UserProfilePhotos struct { TotalCount int `json:"total_count"` Photos [][]PhotoSize `json:"photos"` } + +// UserProfileAudios represents a user's profile audios. +// See https://core.telegram.org/bots/api#userprofileaudios type UserProfileAudios struct { TotalCount int `json:"total_count"` Audios []Audio `json:"audios"` } +// UserRating represents a user's rating with level progression. +// See https://core.telegram.org/bots/api#userrating type UserRating struct { Level int `json:"level"` Rating int `json:"rating"` CurrentLevelRating int `json:"current_level_rating"` NextLevelRating int `json:"next_level_rating"` } + +// Birthdate represents a user's birthdate. +// See https://core.telegram.org/bots/api#birthdate type Birthdate struct { Day int `json:"day"` Month int `json:"month"` diff --git a/utils/version.go b/utils/version.go index ddcda17..834cb91 100644 --- a/utils/version.go +++ b/utils/version.go @@ -1,9 +1,9 @@ package utils const ( - VersionString = "1.0.0-beta.14" + VersionString = "1.0.0-beta.15" VersionMajor = 1 VersionMinor = 0 VersionPatch = 0 - VersionBeta = 14 + VersionBeta = 15 )