feat(types): add typed enums and structured error hierarchy

Phase 2 foundation:
- enums.go: named string enums (ParseMode, ChatType, ChatAction,
  MessageEntityType, ChatMemberStatus, PollType, StickerType, and the
  discriminators for the incoming unions) so callers cannot pass bare strings.
- errors.go: Bot-API-shaped *Error (Code/Description/Parameters), ResponseParameters,
  ErrNotImplemented, and AsFloodWait bridging both *Error and tgerr flood waits.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ernado

enums.go

@@ -0,0 +1,156 @@
+package botapi
+
+// This file defines the typed string enums of the Bot API surface. Each is a
+// distinct named type over string so callers cannot pass an arbitrary string
+// where an enum is expected, and the valid values are exported constants.
+
+// ParseMode is the formatting mode for message text and captions.
+//
+// See https://core.telegram.org/bots/api#formatting-options.
+type ParseMode string
+
+const (
+	// ParseModeNone sends text without any entity parsing.
+	ParseModeNone ParseMode = ""
+	// ParseModeHTML parses a subset of HTML tags.
+	ParseModeHTML ParseMode = "HTML"
+	// ParseModeMarkdownV2 parses MarkdownV2-style formatting.
+	ParseModeMarkdownV2 ParseMode = "MarkdownV2"
+	// ParseModeMarkdown is the legacy Markdown mode; prefer ParseModeMarkdownV2.
+	ParseModeMarkdown ParseMode = "Markdown"
+)
+
+// ChatType is the kind of a chat.
+type ChatType string
+
+const (
+	ChatTypePrivate    ChatType = "private"
+	ChatTypeGroup      ChatType = "group"
+	ChatTypeSupergroup ChatType = "supergroup"
+	ChatTypeChannel    ChatType = "channel"
+	// ChatTypeSender is used for inline queries sent from the inline mode of a
+	// private chat with the bot.
+	ChatTypeSender ChatType = "sender"
+)
+
+// ChatAction is a status reported to a chat via SendChatAction.
+type ChatAction string
+
+const (
+	ChatActionTyping          ChatAction = "typing"
+	ChatActionUploadPhoto     ChatAction = "upload_photo"
+	ChatActionRecordVideo     ChatAction = "record_video"
+	ChatActionUploadVideo     ChatAction = "upload_video"
+	ChatActionRecordVoice     ChatAction = "record_voice"
+	ChatActionUploadVoice     ChatAction = "upload_voice"
+	ChatActionUploadDocument  ChatAction = "upload_document"
+	ChatActionChooseSticker   ChatAction = "choose_sticker"
+	ChatActionFindLocation    ChatAction = "find_location"
+	ChatActionRecordVideoNote ChatAction = "record_video_note"
+	ChatActionUploadVideoNote ChatAction = "upload_video_note"
+)
+
+// MessageEntityType is the kind of a MessageEntity.
+type MessageEntityType string
+
+const (
+	EntityMention              MessageEntityType = "mention"
+	EntityHashtag              MessageEntityType = "hashtag"
+	EntityCashtag              MessageEntityType = "cashtag"
+	EntityBotCommand           MessageEntityType = "bot_command"
+	EntityURL                  MessageEntityType = "url"
+	EntityEmail                MessageEntityType = "email"
+	EntityPhoneNumber          MessageEntityType = "phone_number"
+	EntityBold                 MessageEntityType = "bold"
+	EntityItalic               MessageEntityType = "italic"
+	EntityUnderline            MessageEntityType = "underline"
+	EntityStrikethrough        MessageEntityType = "strikethrough"
+	EntitySpoiler              MessageEntityType = "spoiler"
+	EntityBlockquote           MessageEntityType = "blockquote"
+	EntityExpandableBlockquote MessageEntityType = "expandable_blockquote"
+	EntityCode                 MessageEntityType = "code"
+	EntityPre                  MessageEntityType = "pre"
+	EntityTextLink             MessageEntityType = "text_link"
+	EntityTextMention          MessageEntityType = "text_mention"
+	EntityCustomEmoji          MessageEntityType = "custom_emoji"
+)
+
+// ChatMemberStatus is a member's status in a chat.
+type ChatMemberStatus string
+
+const (
+	StatusCreator       ChatMemberStatus = "creator"
+	StatusAdministrator ChatMemberStatus = "administrator"
+	StatusMember        ChatMemberStatus = "member"
+	StatusRestricted    ChatMemberStatus = "restricted"
+	StatusLeft          ChatMemberStatus = "left"
+	StatusBanned        ChatMemberStatus = "kicked"
+)
+
+// PollType is the kind of a poll.
+type PollType string
+
+const (
+	PollRegular PollType = "regular"
+	PollQuiz    PollType = "quiz"
+)
+
+// StickerType is the kind of a sticker (or sticker set).
+type StickerType string
+
+const (
+	StickerRegular     StickerType = "regular"
+	StickerMask        StickerType = "mask"
+	StickerCustomEmoji StickerType = "custom_emoji"
+)
+
+// MessageOriginType discriminates a MessageOrigin variant.
+type MessageOriginType string
+
+const (
+	OriginUser       MessageOriginType = "user"
+	OriginHiddenUser MessageOriginType = "hidden_user"
+	OriginChat       MessageOriginType = "chat"
+	OriginChannel    MessageOriginType = "channel"
+)
+
+// ReactionTypeKind discriminates a ReactionType variant.
+type ReactionTypeKind string
+
+const (
+	ReactionEmoji       ReactionTypeKind = "emoji"
+	ReactionCustomEmoji ReactionTypeKind = "custom_emoji"
+	ReactionPaid        ReactionTypeKind = "paid"
+)
+
+// MenuButtonType discriminates a MenuButton variant.
+type MenuButtonType string
+
+const (
+	MenuButtonCommandsType MenuButtonType = "commands"
+	MenuButtonWebAppType   MenuButtonType = "web_app"
+	MenuButtonDefaultType  MenuButtonType = "default"
+)
+
+// InputMediaType discriminates an InputMedia variant.
+type InputMediaType string
+
+const (
+	InputMediaPhotoType     InputMediaType = "photo"
+	InputMediaVideoType     InputMediaType = "video"
+	InputMediaAnimationType InputMediaType = "animation"
+	InputMediaAudioType     InputMediaType = "audio"
+	InputMediaDocumentType  InputMediaType = "document"
+)
+
+// DiceEmoji is the emoji on which a dice-style value is based.
+type DiceEmoji string
+
+const (
+	DiceDie        DiceEmoji = "🎲"
+	DiceDart       DiceEmoji = "🎯"
+	DiceBasketball DiceEmoji = "🏀"
+	DiceFootball   DiceEmoji = "⚽"
+	DiceBowling    DiceEmoji = "🎳"
+	DiceSlot       DiceEmoji = "🎰"
+)

errors.go

@@ -0,0 +1,65 @@
+package botapi
+
+import (
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/gotd/td/tgerr"
+)
+
+// ResponseParameters describes why a request failed and how to recover, mirroring
+// the Bot API "ResponseParameters" object.
+type ResponseParameters struct {
+	// MigrateToChatID is the new chat identifier when the group was migrated to a
+	// supergroup. Zero when not applicable.
+	MigrateToChatID int64 `json:"migrate_to_chat_id,omitempty"`
+	// RetryAfter is the number of seconds to wait before repeating the request
+	// when a flood-wait limit was hit. Zero when not applicable.
+	RetryAfter int `json:"retry_after,omitempty"`
+}
+
+// Error is a Bot-API-shaped error. Methods return it (wrapped) so callers can
+// branch on a stable Code/Description regardless of the underlying MTProto error.
+//
+// Use errors.As to extract it:
+//
+//	var apiErr *botapi.Error
+//	if errors.As(err, &apiErr) && apiErr.Code == 403 { ... }
+type Error struct {
+	// Code is the Bot-API-compatible error code (e.g. 400, 403, 429).
+	Code int
+	// Description is a human-readable message.
+	Description string
+	// Parameters carries optional recovery hints (retry_after, migrate_to_chat_id).
+	Parameters *ResponseParameters
+	// err is the wrapped underlying error (typically *tgerr.Error), if any.
+	err error
+}
+
+// Error implements the error interface.
+func (e *Error) Error() string {
+	if e.Description == "" {
+		return fmt.Sprintf("botapi: error %d", e.Code)
+	}
+	return fmt.Sprintf("botapi: %d: %s", e.Code, e.Description)
+}
+
+// Unwrap returns the underlying error, enabling errors.Is/errors.As to reach it.
+func (e *Error) Unwrap() error { return e.err }
+
+// ErrNotImplemented is returned by methods whose translation is not yet wired.
+var ErrNotImplemented = errors.New("botapi: not implemented")
+
+// AsFloodWait reports whether err (or anything it wraps) is a flood-wait error
+// and, if so, how long the caller should wait before retrying.
+//
+// It understands both this package's *Error (via Parameters.RetryAfter) and the
+// underlying github.com/gotd/td/tgerr flood-wait representation.
+func AsFloodWait(err error) (retryAfter time.Duration, ok bool) {
+	var apiErr *Error
+	if errors.As(err, &apiErr) && apiErr.Parameters != nil && apiErr.Parameters.RetryAfter > 0 {
+		return time.Duration(apiErr.Parameters.RetryAfter) * time.Second, true
+	}
+	return tgerr.AsFloodWait(err)
+}

errors_test.go

@@ -0,0 +1,50 @@
+package botapi
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/gotd/td/tgerr"
+)
+
+func TestAsFloodWait(t *testing.T) {
+	t.Run("FromError", func(t *testing.T) {
+		err := &Error{Code: 429, Description: "Too Many Requests", Parameters: &ResponseParameters{RetryAfter: 5}}
+		d, ok := AsFloodWait(err)
+		if !ok || d != 5*time.Second {
+			t.Fatalf("got (%v, %v), want (5s, true)", d, ok)
+		}
+	})
+	t.Run("FromWrappedError", func(t *testing.T) {
+		err := fmt.Errorf("send: %w", &Error{Code: 429, Parameters: &ResponseParameters{RetryAfter: 3}})
+		if d, ok := AsFloodWait(err); !ok || d != 3*time.Second {
+			t.Fatalf("got (%v, %v), want (3s, true)", d, ok)
+		}
+	})
+	t.Run("FromTGErr", func(t *testing.T) {
+		err := &tgerr.Error{Code: 420, Type: "FLOOD_WAIT", Argument: 7}
+		if d, ok := AsFloodWait(err); !ok || d != 7*time.Second {
+			t.Fatalf("got (%v, %v), want (7s, true)", d, ok)
+		}
+	})
+	t.Run("NotFloodWait", func(t *testing.T) {
+		if _, ok := AsFloodWait(errors.New("boom")); ok {
+			t.Fatal("plain error should not be a flood wait")
+		}
+	})
+}
+
+func TestErrorUnwrap(t *testing.T) {
+	sentinel := errors.New("underlying")
+	err := &Error{Code: 400, Description: "Bad Request", err: sentinel}
+	if !errors.Is(err, sentinel) {
+		t.Fatal("errors.Is should reach the wrapped error")
+	}
+
+	var apiErr *Error
+	if !errors.As(fmt.Errorf("ctx: %w", err), &apiErr) || apiErr.Code != 400 {
+		t.Fatal("errors.As should extract *Error through a wrap")
+	}
+}