Rename tgapi request structs

Add MaybeInaccessibleMessage tests and godoc
Update wiki and Bot API docs for the new naming
This commit is contained in:
2026-04-06 16:06:57 +03:00
parent d55f58c092
commit 83bcab6415
40 changed files with 1946 additions and 914 deletions
+354 -82
View File
@@ -1,64 +1,222 @@
package tgapi
import "git.scuroneko.dev/scuroneko/extypes"
import (
"encoding/json"
"git.scuroneko.dev/scuroneko/extypes"
)
// MessageID represents a message identifier wrapper returned by some API methods.
type MessageID struct {
MessageID int `json:"message_id"`
}
// 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"`
}
type MessageOriginType string
const (
MessageOriginUserType = "user"
MessageOriginHiddenUserType = "hidden_user"
MessageOriginChatType = "chat"
MessageOriginChannel = "channel"
)
type MessageOrigin struct {
Type MessageOriginType `json:"type"`
Date int64 `json:"date"`
SenderUser *User `json:"sender_user,omitempty"`
SenderUserName string `json:"sender_user_name,omitempty"`
SenderChat *Chat `json:"sender_chat,omitempty"`
Chat *Chat `json:"chat,omitempty"`
MessageID int `json:"message_id"`
AuthorSignature string `json:"author_signature,omitempty"`
}
type ExternalReplyInfo struct {
Origin MessageOrigin `json:"origin"`
Chat *Chat `json:"chat,omitempty"`
MessageID int `json:"message_id,omitempty"`
LinkPreviewOptions *LinkPreviewOptions `json:"link_preview_options,omitempty"`
Animation *Animation `json:"animation,omitempty"`
Audio *Audio `json:"audio,omitempty"`
Document *Document `json:"document,omitempty"`
PaidMedia *PaidMediaInfo `json:"paid_media,omitempty"`
Photo []PhotoSize `json:"photo,omitempty"`
Sticker *Sticker `json:"sticker,omitempty"`
Story *Story `json:"story,omitempty"`
Video *Video `json:"video,omitempty"`
VideoNote *VideoNote `json:"video_note,omitempty"`
Voice *Voice `json:"voice,omitempty"`
HasMediaSpoiler bool `json:"has_media_spoiler,omitempty"`
Checklist *Checklist `json:"checklist,omitempty"`
Contact *Contact `json:"contact,omitempty"`
Dice *Dice `json:"dice,omitempty"`
Game *Game `json:"game,omitempty"`
Giveaway *Giveaway `json:"giveaway,omitempty"`
GiveawayWinners *GiveawayWinners `json:"giveaway_winners,omitempty"`
Invoice *Invoice `json:"invoice,omitempty"`
Location *Location `json:"location,omitempty"`
Poll *Poll `json:"poll,omitempty"`
Venue *Venue `json:"venue,omitempty"`
}
type TextQuote struct {
Text string `json:"text"`
Entities []MessageEntity `json:"entities"`
Position int `json:"position"`
IsManual bool `json:"is_manual,omitempty"`
}
type MessageAutoDeleteTimerChanged struct {
MessageAutoDeleteTime int `json:"message_auto_delete_time"`
}
type DirectMessagePriceChanged struct {
AreDirectMessagesEnabled bool `json:"are_direct_messages_enabled"`
DirectMessageStarCount int `json:"direct_message_star_count,omitempty"`
}
type PaidMessagePriceChanged struct {
PaidMessageStarCount int `json:"paid_message_star_count"`
}
// 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"`
DirectMessageTopic *DirectMessageTopic `json:"direct_message_topic,omitempty"`
BusinessConnectionId string `json:"business_connection_id,omitempty"`
From *User `json:"from,omitempty"`
MessageID int `json:"message_id"`
MessageThreadID int `json:"message_thread_id,omitempty"`
DirectMessageTopic *DirectMessageTopic `json:"direct_message_topic,omitempty"`
From *User `json:"from,omitempty"`
SenderChat *Chat `json:"sender_chat,omitempty"`
SenderBoostCount int `json:"sender_boost_count,omitempty"`
SenderBusinessBot *User `json:"sender_business_bot,omitempty"`
SenderTag string `json:"sender_tag,omitempty"`
Chat *Chat `json:"chat,omitempty"`
SenderChat *Chat `json:"sender_chat,omitempty"`
SenderBoostCount int `json:"sender_boost_count,omitempty"`
SenderBusinessBot *User `json:"sender_business_bot,omitempty"`
SenderTag string `json:"sender_tag,omitempty"`
Date int `json:"date"`
BusinessConnectionId string `json:"business_connection_id,omitempty"`
Chat *Chat `json:"chat,omitempty"`
ForwardOrigin *MessageOrigin `json:"forward_origin,omitempty"`
IsTopicMessage bool `json:"is_topic_message,omitempty"`
IsAutomaticForward bool `json:"is_automatic_forward,omitempty"`
IsFromOffline bool `json:"is_from_offline,omitempty"`
IsPaidPost bool `json:"is_paid_post,omitempty"`
MediaGroupId string `json:"media_group_id,omitempty"`
AuthorSignature string `json:"author_signature,omitempty"`
PaidStarCount int `json:"paid_star_count,omitempty"`
ReplyToMessage *Message `json:"reply_to_message,omitempty"`
IsTopicMessage bool `json:"is_topic_message,omitempty"`
IsAutomaticForward bool `json:"is_automatic_forward,omitempty"`
ReplyToMessage *Message `json:"reply_to_message,omitempty"`
ExternalReply *ExternalReplyInfo `json:"external_reply,omitempty"`
Quote *TextQuote `json:"quote,omitempty"`
Text string `json:"text"`
Photo extypes.Slice[PhotoSize] `json:"photo,omitempty"`
Caption string `json:"caption,omitempty"`
CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
Date int `json:"date"`
EditDate int `json:"edit_date"`
ReplyMarkup *MessageReplyMarkup `json:"reply_markup,omitempty"`
ReplyToStory *Story `json:"reply_to_story,omitempty"`
ReplyToChecklistTaskID int `json:"reply_to_checklist_task_id,omitempty"`
ReplyToPollOptionID string `json:"reply_to_poll_option_id,omitempty"`
ViaBot *User `json:"via_bot,omitempty"`
EditDate int `json:"edit_date,omitempty"`
HasProtectedContent bool `json:"has_protected_content,omitempty"`
IsFromOffline bool `json:"is_from_offline,omitempty"`
IsPaidPost bool `json:"is_paid_post,omitempty"`
MediaGroupId string `json:"media_group_id,omitempty"`
AuthorSignature string `json:"author_signature,omitempty"`
PaidStarCount int `json:"paid_star_count,omitempty"`
Text string `json:"text"`
Entities []MessageEntity `json:"entities,omitempty"`
LinkPreviewOptions *LinkPreviewOptions `json:"link_preview_options,omitempty"`
SuggestedPostInfo *SuggestedPostInfo `json:"suggested_post_info,omitempty"`
EffectID string `json:"effect_id,omitempty"`
EffectID string `json:"effect_id,omitempty"`
Animation *Animation `json:"animation,omitempty"`
Audio *Audio `json:"audio,omitempty"`
Document *Document `json:"document,omitempty"`
PaidMedia *PaidMediaInfo `json:"paid_media,omitempty"`
Photo extypes.Slice[PhotoSize] `json:"photo,omitempty"`
Sticker *Sticker `json:"sticker,omitempty"`
Story *Story `json:"story,omitempty"`
Video *Video `json:"video,omitempty"`
VideoNote *VideoNote `json:"video_note,omitempty"`
Voice *Voice `json:"voice,omitempty"`
Caption string `json:"caption,omitempty"`
CaptionEntities []MessageEntity `json:"caption_entities,omitempty"`
ShowCaptionAboveMedia bool `json:"show_caption_above_media,omitempty"`
HasMediaSpoiler bool `json:"has_media_spoiler,omitempty"`
Checklist *Checklist `json:"checklist,omitempty"`
Contact *Contact `json:"contact,omitempty"`
Dice *Dice `json:"dice,omitempty"`
Game *Game `json:"game,omitempty"`
Poll *Poll `json:"poll,omitempty"`
Venue *Venue `json:"venue,omitempty"`
Location *Location `json:"location,omitempty"`
NewChatMembers []User `json:"new_chat_members,omitempty"`
LeftChatMember *User `json:"left_chat_member,omitempty"`
ChatOwnerLeft *ChatOwnerLeft `json:"chat_owner_left,omitempty"`
ChatOwnerChanged *ChatOwnerChanged `json:"chat_owner_changed,omitempty"`
NewChatTitle string `json:"new_chat_title,omitempty"`
NewChatPhoto []PhotoSize `json:"new_chat_photo,omitempty"`
DeleteChatPhoto bool `json:"delete_chat_photo,omitempty"`
GroupChatCreated bool `json:"group_chat_created,omitempty"`
SupergroupChatCreated bool `json:"supergroup_chat_created,omitempty"`
ChannelChatCreated bool `json:"channel_chat_created,omitempty"`
MessageAutoDeleteTimerChanged *MessageAutoDeleteTimerChanged `json:"message_auto_delete_timer_changed,omitempty"`
MigrateToChatID int64 `json:"migrate_to_chat_id,omitempty"`
MigrateFromChatID int64 `json:"migrate_from_chat_id,omitempty"`
PinnedMessage *MaybeInaccessibleMessage `json:"pinned_message,omitempty"`
Invoice *Invoice `json:"invoice,omitempty"`
SuccessfulPayment *SuccessfulPayment `json:"successful_payment,omitempty"`
RefundedPayment *RefundedPayment `json:"refunded_payment,omitempty"`
UsersShared *UsersShared `json:"users_shared,omitempty"`
ChatShared *ChatShared `json:"chat_shared,omitempty"`
Gift *GiftInfo `json:"gift,omitempty"`
UniqueGift *UniqueGiftInfo `json:"unique_gift,omitempty"`
GiftUpgradeSent *GiftInfo `json:"gift_upgrade_sent,omitempty"`
ConnectedWebsite string `json:"connected_website,omitempty"`
WriteAccessAllowed *WriteAccessAllowed `json:"write_access_allowed,omitempty"`
PassportData *PassportData `json:"passport_data,omitempty"`
ProximityAlertTriggered *ProximityAlertTriggered `json:"proximity_alert_triggered,omitempty"`
BoostAdded *ChatBoostAdded `json:"boost_added,omitempty"`
ChatBackgroundSet *ChatBackground `json:"chat_background_set,omitempty"`
ChecklistTaskDone *ChecklistTaskDone `json:"checklist_task_done,omitempty"`
ChecklistTasksAdded *ChecklistTasksAdded `json:"checklist_tasks_added,omitempty"`
DirectMessagePriceChanged *DirectMessagePriceChanged `json:"direct_message_price_changed,omitempty"`
ForumTopicCreated *ForumTopicCreated `json:"forum_topic_created,omitempty"`
ForumTopicEdited *ForumTopicEdited `json:"forum_topic_edited,omitempty"`
ForumTopicClosed *ForumTopicClosed `json:"forum_topic_closed,omitempty"`
ForumTopicReopened *ForumTopicReopened `json:"forum_topic_reopened,omitempty"`
GeneralForumTopicHidden *GeneralForumTopicHidden `json:"general_forum_topic_hidden,omitempty"`
GeneralForumTopicUnhidden *GeneralForumTopicUnhidden `json:"general_forum_topic_unhidden,omitempty"`
GiveawayCreated *GiveawayCreated `json:"giveaway_created,omitempty"`
Giveaway *Giveaway `json:"giveaway,omitempty"`
GiveawayWinners *GiveawayWinners `json:"giveaway_winners,omitempty"`
GiveawayCompleted *GiveawayCompleted `json:"giveaway_completed,omitempty"`
ManagedBotCreated *ManagedBotCreated `json:"managed_bot_created,omitempty"`
PaidMessagePriceChanged *PaidMessagePriceChanged `json:"paid_message_price_changed,omitempty"`
PollOptionAdded *PollOptionAdded `json:"poll_option_added,omitempty"`
PollOptionDeleted *PollOptionDeleted `json:"poll_option_deleted,omitempty"`
SuggestedPostApproved *SuggestedPostApproved `json:"suggested_post_approved,omitempty"`
SuggestedPostApprovalFailed *SuggestedPostApprovalFailed `json:"suggested_post_approval_failed,omitempty"`
SuggestedPostDeclined *SuggestedPostDeclined `json:"suggested_post_declined,omitempty"`
SuggestedPostPaid *SuggestedPostPaid `json:"suggested_post_paid,omitempty"`
SuggestedPostRefunded *SuggestedPostRefunded `json:"suggested_post_refunded,omitempty"`
VideoChatScheduled *VideoChatScheduled `json:"video_chat_scheduled,omitempty"`
VideoChatStarted *VideoChatStarted `json:"video_chat_started,omitempty"`
VideoChatEnded *VideoChatEnded `json:"video_chat_ended,omitempty"`
VideoChatParticipantsInvited *VideoChatParticipantsInvited `json:"video_chat_participants_invited,omitempty"`
WebAppData *WebAppData `json:"web_app_data,omitempty"`
ReplyMarkup *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
}
// InaccessibleMessage describes a message that was deleted or is otherwise inaccessible.
@@ -71,7 +229,80 @@ type InaccessibleMessage struct {
// 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 }
type MaybeInaccessibleMessage struct {
msg *Message
ina *InaccessibleMessage
}
// UnmarshalJSON decodes either an accessible Message or an InaccessibleMessage.
func (m *MaybeInaccessibleMessage) UnmarshalJSON(data []byte) error {
tmp := struct {
Date int `json:"date"`
}{}
if err := json.Unmarshal(data, &tmp); err != nil {
return err
}
var err error
if tmp.Date > 0 {
err = json.Unmarshal(data, &m.msg)
} else {
err = json.Unmarshal(data, &m.ina)
}
if err != nil {
return err
}
return nil
}
// MarshalJSON encodes the populated accessible or inaccessible message payload.
func (m *MaybeInaccessibleMessage) MarshalJSON() ([]byte, error) {
if m.msg != nil {
return json.Marshal(m.msg)
} else if m.ina != nil {
return json.Marshal(m.ina)
}
return json.Marshal(nil)
}
// Message returns the accessible message payload when present.
func (m *MaybeInaccessibleMessage) Message() *Message {
return m.msg
}
// InaccessibleMessage returns the inaccessible message payload when present.
func (m *MaybeInaccessibleMessage) InaccessibleMessage() *InaccessibleMessage {
return m.ina
}
// IsAccessible reports whether the payload is an accessible message.
func (m *MaybeInaccessibleMessage) IsAccessible() bool {
return m.msg != nil
}
// IsInaccessible reports whether the payload is an inaccessible message.
func (m *MaybeInaccessibleMessage) IsInaccessible() bool {
return m.ina != nil
}
// MessageID returns the message identifier from either payload form.
func (m *MaybeInaccessibleMessage) MessageID() int {
if m.IsAccessible() {
return m.msg.MessageID
} else if m.IsInaccessible() {
return m.ina.MessageID
}
return 0
}
// Chat returns the chat from either payload form.
func (m *MaybeInaccessibleMessage) Chat() *Chat {
if m.IsAccessible() {
return m.msg.Chat
} else if m.IsInaccessible() {
return &m.ina.Chat
}
return nil
}
// MessageEntityType represents the type of a message entity.
type MessageEntityType string
@@ -147,6 +378,7 @@ type ReplyParameters struct {
QuoteEntities []MessageEntity `json:"quote_entities,omitempty"`
QuotePosition int `json:"quote_position,omitempty"`
ChecklistTaskID int `json:"checklist_task_id,omitempty"`
PollOptionID string `json:"poll_option_id,omitempty"`
}
// LinkPreviewOptions describes the options used for link preview generation.
@@ -197,15 +429,16 @@ const (
// KeyboardButton represents one button of the reply keyboard.
// See https://core.telegram.org/bots/api#keyboardbutton
type KeyboardButton struct {
Text string `json:"text"`
IconCustomEmojiID string `json:"icon_custom_emoji_id,omitempty"`
Style KeyboardButtonStyle `json:"style,omitempty"`
RequestUsers *KeyboardButtonRequestUsers `json:"request_users,omitempty"`
RequestChat *KeyboardButtonRequestChat `json:"request_chat,omitempty"`
RequestContact bool `json:"request_contact,omitempty"`
RequestLocation bool `json:"request_location,omitempty"`
RequestPoll *KeyboardButtonPollType `json:"request_poll,omitempty"`
WebApp *WebAppInfo `json:"web_app,omitempty"`
Text string `json:"text"`
IconCustomEmojiID string `json:"icon_custom_emoji_id,omitempty"`
Style KeyboardButtonStyle `json:"style,omitempty"`
RequestUsers *KeyboardButtonRequestUsers `json:"request_users,omitempty"`
RequestChat *KeyboardButtonRequestChat `json:"request_chat,omitempty"`
RequestManagedBot *KeyboardButtonRequestManagedBot `json:"request_managed_bot,omitempty"`
RequestContact bool `json:"request_contact,omitempty"`
RequestLocation bool `json:"request_location,omitempty"`
RequestPoll *KeyboardButtonPollType `json:"request_poll,omitempty"`
WebApp *WebAppInfo `json:"web_app,omitempty"`
}
// KeyboardButtonRequestUsers defines criteria used to request suitable users.
@@ -236,6 +469,14 @@ type KeyboardButtonRequestChat struct {
RequestPhoto bool `json:"request_photo,omitempty"`
}
// KeyboardButtonRequestManagedBot defines criteria used to request a managed bot.
// See https://core.telegram.org/bots/api#keyboardbuttonrequestmanagedbot
type KeyboardButtonRequestManagedBot struct {
RequestID int32 `json:"request_id"`
SuggestedName string `json:"suggested_name,omitempty"`
SuggestedUsername string `json:"suggested_username,omitempty"`
}
// KeyboardButtonPollType represents the type of a poll that may be created from a keyboard button.
// See https://core.telegram.org/bots/api#keyboardbuttonpolltype
type KeyboardButtonPollType struct {
@@ -275,42 +516,6 @@ type CallbackQuery struct {
GameShortName string `json:"game_short_name,omitempty"`
}
// 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 (
// PollTypeRegular identifies a regular poll.
PollTypeRegular PollType = "regular"
// PollTypeQuiz identifies a quiz poll.
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"`
TitleEntities []MessageEntity `json:"title_entities,omitempty"`
Tasks []InputChecklistTask `json:"tasks"`
OtherCanAddTasks bool `json:"other_can_add_tasks,omitempty"`
OtherCanMarkTasksAsDone bool `json:"other_can_mark_tasks_as_done,omitempty"`
}
// ChatActionType represents the type of chat action.
type ChatActionType string
@@ -392,3 +597,70 @@ type SuggestedPostParameters struct {
Price SuggestedPostPrice `json:"price"`
SendDate int `json:"send_date"`
}
// ManagedBotCreated describes a service message about a newly created managed bot.
// See https://core.telegram.org/bots/api#managedbotcreated
type ManagedBotCreated struct {
Bot User `json:"bot"`
}
// ManagedBotUpdated describes an update about a managed bot and its manager.
// See https://core.telegram.org/bots/api#managedbotupdated
type ManagedBotUpdated struct {
User User `json:"user"`
Bot User `json:"bot"`
}
type SharedUser struct {
UserID int64 `json:"user_id"`
FirstName string `json:"first_name,omitempty"`
LastName string `json:"last_name,omitempty"`
Username string `json:"username,omitempty"`
Photo []PhotoSize `json:"photo,omitempty"`
}
type UsersShared struct {
RequestID int `json:"request_id"`
Users []SharedUser `json:"users"`
}
type ChatShared struct {
RequestID int `json:"request_id"`
ChatID int64 `json:"chat_id"`
Title string `json:"title,omitempty"`
Username string `json:"username,omitempty"`
Photo []PhotoSize `json:"photo,omitempty"`
}
type SuggestedPostApproved struct {
SuggestedPostMessage *Message `json:"suggested_post_message,omitempty"`
Price SuggestedPostPrice `json:"price"`
SendDate int `json:"send_date"`
}
type SuggestedPostApprovalFailed struct {
SuggestedPostMessage *Message `json:"suggested_post_message,omitempty"`
Price SuggestedPostPrice `json:"price"`
}
type SuggestedPostDeclined struct {
SuggestedPostMessage *Message `json:"suggested_post_message,omitempty"`
Comment string `json:"comment,omitempty"`
}
type SuggestedPostPaid struct {
SuggestedPostMessage *Message `json:"suggested_post_message,omitempty"`
Currency string `json:"currency"`
Amount int `json:"amount"`
StarAmount *StarAmount `json:"star_amount,omitempty"`
}
type SuggestedPostRefunded struct {
SuggestedPostMessage *Message `json:"suggested_post_message,omitempty"`
Reason string `json:"reason,omitempty"`
}
type VideoChatScheduled struct {
StartDate int64 `json:"start_date"`
}
type VideoChatStarted struct{}
type VideoChatEnded struct {
Duration int64 `json:"duration"`
}
type VideoChatParticipantsInvited struct {
Users []User `json:"users"`
}