bote

type Bot struct {
	// contains filtered or unexported fields
}

type BotConfig struct {
	// ParseMode is the default parse mode for the bot.
	// Default: HTML.
	// Environment variable: BOTE_PARSE_MODE.
	// It can be one of the following:
	// - "HTML"
	// - "Markdown"
	// - "MarkdownV2"
	ParseMode tele.ParseMode `yaml:"mode" json:"mode" env:"BOTE_PARSE_MODE"`

	// Privacy is a configuration for privacy mode.
	Privacy PrivacyConfig `yaml:"privacy" json:"privacy"`

	// DefaultLanguage is the default language code for the bot in ISO 639-1 format.
	// Default: "en".
	// Environment variable: BOTE_DEFAULT_LANGUAGE.
	DefaultLanguage Language `yaml:"default_language" json:"default_language" env:"BOTE_DEFAULT_LANGUAGE"`

	// NoPreview is a flag that disables link preview in bot messages.
	// Default: false.
	// Environment variable: BOTE_NO_PREVIEW.
	NoPreview bool `yaml:"no_preview" json:"no_preview" env:"BOTE_NO_PREVIEW"`

	// DeleteMessages is a flag that enables deleting every user message.
	// Default: true.
	// Environment variable: BOTE_DELETE_MESSAGES.
	DeleteMessages *bool `yaml:"delete_messages" json:"delete_messages" env:"BOTE_DELETE_MESSAGES"`

	// UserCacheCapacity is the capacity of the user cache. Cache will evict users with least activity.
	// Default: 10000.
	// Environment variable: BOTE_USER_CACHE_CAPACITY.
	UserCacheCapacity int `yaml:"user_cache_capacity" json:"user_cache_capacity" env:"BOTE_USER_CACHE_CAPACITY"`

	// UserCacheTTL is the TTL of the user cache.
	// Default: 24 hours.
	// Environment variable: BOTE_USER_CACHE_TTL.
	UserCacheTTL time.Duration `yaml:"user_cache_ttl" json:"user_cache_ttl" env:"BOTE_USER_CACHE_TTL"`
}

type ButtonBuilder interface {
	Btn(name string, callback HandlerFunc, dataList ...string) tele.Btn
}

type Config struct {
	// Mode is the polling mode to use.
	// Default: long.
	// Possible values:
	// - "long" - long polling
	// - "webhook" - webhook
	// - "custom" - custom poller (you should provide poller using [WithPoller] option)
	// Environment variable: BOTE_MODE.
	Mode PollingMode `yaml:"mode" json:"mode" env:"BOTE_MODE"`

	// LongPolling contains long polling configuration.
	LongPolling LongPollingConfig `yaml:"long_polling" json:"long_polling"`

	// Webhook contains webhook configuration.
	Webhook WebhookConfig `yaml:"webhook" json:"webhook"`

	// Bot contains bot configuration.
	Bot BotConfig `yaml:"bot" json:"bot"`

	// Log contains log configuration.
	Log LogConfig `yaml:"log" json:"log"`
}

type Context interface {
	// Tele returns underlying telebot context.
	Tele() tele.Context

	// User returns current User context if chat type is private.
	// WARNING: If chat type is not private, returns public read only user.
	User() User

	// IsPrivate returns true if the current chat type is private.
	IsPrivate() bool

	// ChatID returns the ID of the current chat.
	ChatID() int64

	// ChatType returns the type of the current chat.
	ChatType() tele.ChatType

	// IsMentioned returns true if the bot is mentioned in the current message.
	IsMentioned() bool

	// IsReply returns true if the current message is a reply to the bot's message.
	IsReply() bool

	// MessageID returns an ID of the message.
	// If handler was called from a callback button, message is the one with keyboard.
	// If handler was called from a text message and user's state IsText == true,
	//  message is the one with an active text handler with this state (not sent message!).
	// In other case it is an ID of the message sent to the chat.
	MessageID() int

	// ButtonID returns an ID of the pressed callback button.
	ButtonID() string

	// Data returns callback button data. If there are many items in data, they will be separated by '|'.
	Data() string

	// DataParsed returns all items of button data.
	DataParsed() []string

	// Text returns a text sended by the user.
	Text() string

	// TextWithMessage returns a text sended by the user and the ID of this message (deleted by default).
	TextWithMessage() (string, int)

	// Set sets custom data for the current context.
	Set(key, value string)

	// Get returns custom data from the current context.
	Get(key string) string

	// Btn creates button and registers handler for it. You can provide data for the button.
	// Data items will be separated by '|' in a single data string.
	// Button unique value is generated from hexing button name with 10 random bytes at the end.
	Btn(name string, callback HandlerFunc, dataList ...string) tele.Btn

	// Send sends new main and head messages to the user.
	// Old head message will be deleted. Old main message will becomve historical.
	// newState is a state of the user which will be set after sending message.
	// opts are additional options for sending messages.
	// WARNING: It works only in private chats.
	Send(newState State, mainMsg, headMsg string, mainKb, headKb *tele.ReplyMarkup, opts ...any) (err error)

	// SendMain sends new main message to the user.
	// Old head message will be deleted. Old main message will becomve historical.
	// newState is a state of the user which will be set after sending message.
	// opts are additional options for sending message.
	// WARNING: It works only in private chats.
	SendMain(newState State, msg string, kb *tele.ReplyMarkup, opts ...any) error

	// SendNotification sends a notification message to the user.
	// opts are additional options for sending message.
	// WARNING: It works only in private chats.
	SendNotification(msg string, kb *tele.ReplyMarkup, opts ...any) error

	// SendError sends an error message to the user.
	// opts are additional options for sending message.
	// WARNING: It works only in private chats.
	SendError(msg string, opts ...any) error

	// SendFile sends a file to the user.
	// name is the name of the file to send.
	// file is the file to send.
	// opts are additional options for sending the file.
	// WARNING: It works only in private chats.
	SendFile(name string, file []byte, opts ...any) error

	// SendInChat sends a message to a specific chat ID and thread ID.
	// chatID is the target chat ID, threadID is the target thread ID (0 for no thread).
	// msg is the message to send.
	// kb is the keyboard to send.
	// opts are additional options for sending the message.
	SendInChat(chatID int64, threadID int, msg string, kb *tele.ReplyMarkup, opts ...any) (int, error)

	// Edit edits main and head messages of the user.
	// newState is a state of the user which will be set after editing message.
	// opts are additional options for editing messages.
	// WARNING: It works only in private chats.
	Edit(newState State, mainMsg, headMsg string, mainKb, headKb *tele.ReplyMarkup, opts ...any) (err error)

	// EditMain edits main message of the user.
	// newState is a state of the user which will be set after editing message.
	// opts are additional options for editing message.
	// WARNING: It works only in private chats.
	EditMain(newState State, msg string, kb *tele.ReplyMarkup, opts ...any) error

	// EditMainReplyMarkup edits reply markup of the main message.
	// opts are additional options for editing message.
	// WARNING: It works only in private chats.
	EditMainReplyMarkup(kb *tele.ReplyMarkup, opts ...any) error

	// EditHistory edits message of the user by provided ID.
	// newState is a state of the user which will be set after editing message.
	// msgID is the ID of the message to edit.
	// opts are additional options for editing message.
	// WARNING: It works only in private chats.
	EditHistory(newState State, msgID int, msg string, kb *tele.ReplyMarkup, opts ...any) error

	// EditHistoryReplyMarkup edits reply markup of the history message.
	// opts are additional options for editing message.
	// WARNING: It works only in private chats.
	EditHistoryReplyMarkup(msgID int, kb *tele.ReplyMarkup, opts ...any) error

	// EditHead edits head message of the user.
	// opts are additional options for editing message.
	// WARNING: It works only in private chats.
	EditHead(msg string, kb *tele.ReplyMarkup, opts ...any) error

	// EditHeadReplyMarkup edits reply markup of the head message.
	// opts are additional options for editing message.
	// WARNING: It works only in private chats.
	EditHeadReplyMarkup(kb *tele.ReplyMarkup, opts ...any) error

	// EditInChat edits message in a specific chat ID and thread ID.
	// chatID is the target chat ID, threadID is the target thread ID (0 for no thread).
	// msg is the message to edit.
	// kb is the keyboard to edit.
	// opts are additional options for editing message.
	EditInChat(chatID int64, msgID int, msg string, kb *tele.ReplyMarkup, opts ...any) error

	// DeleteHead deletes head message of the user.
	// WARNING: It works only in private chats.
	DeleteHead() error

	// DeleteHistory deletes provided history message.
	// msgID is the ID of the history message to delete.
	// WARNING: It works only in private chats.
	DeleteHistory(msgID int) error

	// DeleteNotification deletes notification message of the user.
	// WARNING: It works only in private chats.
	DeleteNotification() error

	// DeleteError deletes error message of the user.
	// WARNING: It works only in private chats.
	DeleteError() error

	// DeleteAll deletes all messages of the user from the specified ID.
	// WARNING: It works only in private chats.
	DeleteAll(from int)

	// Delete deletes message by provided chat ID and message ID.
	DeleteInChat(chatID int64, msgID int) error

	// DeleteUser deletes user from the memory and deletes all messages of the user.
	// Returns true if all messages were deleted successfully, false otherwise.
	// It doesn't delete user from the persistent database, so you should make it manually.
	// WARNING: It works only in private chats.
	DeleteUser() bool
}

type EncryptionKey struct {
	// contains filtered or unexported fields
}

type Format string

type FullUserID struct {
	// IDPlain is Telegram user ID in plain format.
	// It is empty if privacy mode is strict.
	IDPlain *int64 `json:"id_plain,omitempty" bson:"id_plain,omitempty" db:"id_plain,omitempty"`

	// IDHMAC is a HMAC of IDPlain. It is used for searching user in DB by ID with plain ID is disabled.
	// It is used if privacy mode is strict. It has a hex encoded string.
	IDHMAC *string `json:"id_hmac,omitempty" bson:"id_hmac,omitempty" db:"id_hmac,omitempty"`
	// IDEnc is an encrypted Telegram user ID. It is used to get readable IDPlain from IDEnc (HMAC is one way function).
	// It is used instead of IDPlain when privacy mode is strict. It has a hex encoded string.
	IDEnc *string `json:"id_enc,omitempty" bson:"id_enc,omitempty" db:"id_enc,omitempty"`
	// HMACKeyVersion is a version of HMAC key for IDHMAC that used for HMAC of IDHMAC.
	// It is used if privacy mode is strict.
	HMACKeyVersion *int64 `json:"hmac_key_version,omitempty" bson:"hmac_key_version,omitempty" db:"hmac_key_version,omitempty"`
	// EncKeyVersion is a version of encryption key for IDEnc that used for encryption and decryption of IDEnc.
	// It is used if privacy mode is strict.
	EncKeyVersion *int64 `json:"enc_key_version,omitempty" bson:"enc_key_version,omitempty" db:"enc_key_version,omitempty"`
}

type HandlerFunc func(Context) error

type InitBundle struct {
	// Handler is a handler for [State]. It will be called for initing user.
	// It is required.
	Handler HandlerFunc
	// Data is a callback data, that can be obtained from [Context.Data] inside [HandlerFunc].
	// It is optional and shoud be provided if you use [Context.Data] in your [InitBundle.Handler].
	Data string
	// Text is a text of simulating message, that can be obtained from [Context.Text] inside [HandlerFunc].
	// It is optional and shoud be provided if you use [Context.Text] in your [InitBundle.Handler].
	Text string
}

type Keyboard struct {
	// contains filtered or unexported fields
}

type KeyboardWithContext struct {
	*Keyboard
	// contains filtered or unexported fields
}

type KeysProvider interface {
	// GetEncryptionKey returns the encryption key for the bot.
	// It is used to encrypt and decrypt UserID in strict privacy mode.
	GetEncryptionKey() *EncryptionKey
	// GetHMACKey returns the HMAC key for the bot.
	// It is used to HMAC UserID in strict privacy mode.
	GetHMACKey() *EncryptionKey
}

type Language string

type LogConfig struct {
	// Enable is a flag that enables logging of bot activity (except updates logging).
	// Use default slog to stderr if another logger is not provided using [WithLogger] option.
	// Default: true.
	// Environment variable: BOTE_ENABLE_LOGGING.
	Enable *bool `yaml:"enable" json:"enable" env:"BOTE_LOG_ENABLE"`

	// LogUpdates is a flag that enables logging of bot updates.
	// Use default slog to stderr if another logger is not provided using [WithUpdateLogger] option.
	// Default: true.
	// Environment variable: BOTE_LOG_UPDATES.
	LogUpdates *bool `yaml:"log_updates" json:"log_updates" env:"BOTE_LOG_UPDATES"`

	// Level is the log level. Logger will log messages with level greater than or equal to this level.
	// Default: info.
	// Possible values:
	// - "debug"
	// - "info"
	// - "warn"
	// - "error"
	// Environment variable: BOTE_LOG_LEVEL.
	Level string `yaml:"level" json:"level" env:"BOTE_LOG_LEVEL"`

	// HideUserData is a flag that enables hiding user messages, callback data and pressed buttons from logs.
	// Default: false (even in strict privacy because in strict we use HMAC user_id that prevents from identification)
	// Environment variable: BOTE_LOG_HIDE_USER_DATA.
	HideUserData bool `yaml:"hide_user_data" json:"hide_user_data" env:"BOTE_LOG_HIDE_USER_DATA"`

	// DebugIncomingUpdates is a flag that enables logging of incoming updates.
	// It is not for production use.
	// Default: false.
	// Environment variable: BOTE_LOG_DEBUG_INCOMING_UPDATES.
	DebugIncomingUpdates bool `yaml:"debug_incoming_updates" json:"debug_incoming_updates" env:"BOTE_LOG_DEBUG_INCOMING_UPDATES"`
}

type Logger interface {
	Debug(string, ...any)
	Info(string, ...any)
	Warn(string, ...any)
	Error(string, ...any)
}

type LongPollingConfig struct {
	// Timeout is the long polling timeout.
	// Default: 15 seconds.
	// Environment variable: BOTE_LP_TIMEOUT.
	Timeout time.Duration `yaml:"timeout" json:"timeout"  env:"BOTE_LP_TIMEOUT"`

	// Limit is the maximum number of updates to be returned in a single request.
	// Default: 0, no limit.
	// Environment variable: BOTE_LP_LIMIT.
	Limit int `yaml:"limit" json:"limit" env:"BOTE_LP_LIMIT"`

	// LastUpdateID is the last update ID to be returned.
	// It sets an offset for the starting update to return.
	// It is used to continue long polling from the last update ID.
	// Default: 0.
	// Environment variable: BOTE_LP_LAST_UPDATE_ID.
	LastUpdateID int `yaml:"last_update_id" json:"last_update_id" env:"BOTE_LP_LAST_UPDATE_ID"`

	// AllowedUpdates is a list of update types the bot wants to receive.
	// Empty list means all update types.
	// Possible values:
	//		message
	// 		edited_message
	// 		channel_post
	// 		edited_channel_post
	// 		inline_query
	// 		chosen_inline_result
	// 		callback_query
	// 		shipping_query
	// 		pre_checkout_query
	// 		poll
	// 		poll_answer
	//
	// Environment variable: BOTE_ALLOWED_UPDATES (comma-separated).
	AllowedUpdates []string `yaml:"allowed_updates" json:"allowed_updates" env:"BOTE_ALLOWED_UPDATES" envSeparator:","`
}

type MessageBuilder struct {
	strings.Builder
}

type MessageProvider interface {
	// Messages returns messages for a specific language.
	Messages(language Language) Messages
}

type Messages interface {
	// CloseBtn is a message on inline keyboard button that closes the error message.
	// Remain it empty if you don't want to show this button.
	CloseBtn() string

	// GeneralError is a general error message that sends when an unhandled error occurs.
	GeneralError() string

	// PrepareMessage calls before every Send, SendMain, Edit, EditMain or EditHistory.
	// Provide zero msgID in Send and SendMain methods.
	// If isHistorical is true, it means that the message is a history message called by EditHistory.
	PrepareMessage(msg string, u User, newState State, msgID int, isHistorical bool) string
}

type MessagesState struct {
	// Main is the main state of the user, state of the Main message.
	Main UserState `bson:"main" json:"main" db:"main"`
	// MessageStates contains all states of the user for all messages. It is a map of message_id -> state.
	MessageStates map[int]UserState `bson:"message_states" json:"message_states" db:"message_states"`
	// MessagesAwaitingText is a unique stack that contains all messages IDs that awaits text.
	// Every message can produce text state and they should be handled as LIFO.
	MessagesAwaitingText []int `bson:"messages_awaiting_text" json:"messages_awaiting_text" db:"messages_awaiting_text"`
	// contains filtered or unexported fields
}

type MetricsConfig struct {
	Registry    *prometheus.Registry
	Namespace   string
	Subsystem   string
	ConstLabels prometheus.Labels
}

type MiddlewareFunc func(*tele.Update, User) bool

type MiddlewareFuncTele func(*tele.Update) bool

type Options struct {
	// Config contains bote configuration. It is optional and has default values for all fields.
	// You also can set values using environment variables.
	Config Config

	// UserDB is a storage for users. It uses in-memory storage by default.
	// You should implement it in your application if you want to persist users between applicataion restarts.
	UserDB UsersStorage

	// Msgs is a message provider. It uses default messages by default.
	// You should implement it in your application if you want to use custom messages.
	Msgs MessageProvider

	// Logger is a logger. It uses slog logger by default if EnableLogging == true (by default).
	Logger Logger

	// UpdateLogger is a logger for updates. It uses Logger and logs in debug level by default.
	// It will log updates even if EnableLogging == false.
	// You should set LogUpdates == false to disable updates logging.
	UpdateLogger UpdateLogger

	// Poller is a poller for the bot. It uses default poller by default.
	// You should implement it in your application if you want to use custom poller (e.g. for testing).
	// Note: If WebhookConfig is provided, this will be ignored and webhook poller will be used.
	Poller tele.Poller

	// Metrics is a configuration for prometheus metrics.
	// It registers metrics in the provided registry.
	// It do not register metris if Registry is nil.
	Metrics MetricsConfig

	// Offline is a flag that enables offline mode.
	// It is used to create a bot without network for testing purposes.
	Offline bool

	// KeysProvider is a provider of encryption and HMAC keys for the bot.
	// It is used to provide encryption and HMAC keys for the bot in strict privacy mode.
	KeysProvider KeysProvider
	// contains filtered or unexported fields
}

type PollingMode string

type PrivacyConfig struct {
	// Mode is the privacy mode for the bot.
	// Default: "no".
	// Possible values:
	// - "no" - no privacy mode (all data is stored and logged)
	// - "low" - low privacy mode (store UserID + Username)
	// - "strict" - strict mode (only encrypted and HMACed UserID is stored)
	// Environment variable: BOTE_PRIVACY_MODE.
	Mode PrivacyMode `yaml:"mode" json:"mode" env:"BOTE_PRIVACY_MODE"`

	// EncryptionKey is the encryption key for the bot.
	// It is used to encrypt and decrypt UserID in strict privacy mode.
	// Key should be a hex encoded string of 32 bytes.
	// Default: nil.
	// Environment variable: BOTE_ENCRYPTION_KEY.
	EncryptionKey *string `yaml:"encryption_key" json:"encryption_key" env:"BOTE_ENCRYPTION_KEY"`

	// EncryptionKeyVersion is the version of the encryption key.
	// It is used to identify the version of the encryption key.
	// Default: nil.
	// Environment variable: BOTE_ENCRYPTION_KEY_VERSION.
	EncryptionKeyVersion *int64 `yaml:"enc_key_version" json:"enc_key_version" env:"BOTE_ENCRYPTION_KEY_VERSION"`

	// HMACKey is the HMAC key for the bot.
	// It is used to HMAC UserID in strict privacy mode.
	// Key should be a hex encoded string of 32 bytes.
	// Default: nil.
	// Environment variable: BOTE_HMAC_KEY.
	HMACKey *string `yaml:"hmac_key" json:"hmac_key" env:"BOTE_HMAC_KEY"`

	// HMACKeyVersion is the version of the HMAC key.
	// It is used to identify the version of the HMAC key.
	// Default: nil.
	// Environment variable: BOTE_HMAC_KEY_VERSION.
	HMACKeyVersion *int64 `yaml:"hmac_key_version" json:"hmac_key_version" env:"BOTE_HMAC_KEY_VERSION"`
}

type PrivacyMode string

type RuneSizeType string

type State interface {
	fmt.Stringer
	IsText() bool
	NotChanged() bool
}

type UpdateLogger interface {
	Log(UpdateType, ...any)
}

type UpdateType string

type User interface {
	// ID returns plain Telegram user ID if it is called from [Context.User] (in handler)
	ID() int64
	// IDFull returns full user ID with encrypted and HMAC parts if they are set.
	IDFull() FullUserID
	// Username returns Telegram username (without @).
	// It is empty if privacy mode is strict.
	Username() string
	// Language returns Telegram user language code.
	Language() Language
	// Info returns user info.
	// It is empty if privacy mode is strict.
	Info() UserInfo
	// State returns current state for the given message ID.
	State(msgID int) (State, bool)
	// StateMain returns state for the Main message.
	StateMain() State
	// Messages returns all message IDs.
	Messages() UserMessages
	// IsDisabled returns true if user disabled the bot.
	IsDisabled() bool
	// String returns user string representation in format '[@username|id]'.
	String() string

	// Stats returns user stats.
	Stats() UserStat
	// LastSeenTime returns the time when user interacts with provided message.
	// If message ID is not provided, it returns the time when user interacts with bot's any message.
	LastSeenTime(optionalMsgID ...int) time.Time

	// UpdateLanguage updates user language.
	UpdateLanguage(language Language)

	// GetValue returns value from user context.
	GetValue(key string) (any, bool)

	// SetValue sets value in user context (persistent).
	SetValue(key string, value any)

	// DeleteValue deletes value from user context (persistent).
	DeleteValue(key string)

	// ClearCache deletes all values from SetValue function.
	ClearCache()
}

type UserInfo struct {
	// Username is Telegram username (without @).
	// It is empty if privacy mode is strict.
	Username string `bson:"username,omitempty" json:"username,omitempty" db:"username,omitempty"`
	// FirstName is Telegram user first name.
	// It is empty if privacy mode is enabled.
	FirstName string `bson:"first_name,omitempty" json:"first_name,omitempty" db:"first_name,omitempty"`
	// LastName is Telegram user last name.
	// It is empty if privacy mode is enabled.
	LastName string `bson:"last_name,omitempty" json:"last_name,omitempty" db:"last_name,omitempty"`
	// IsPremium is true if Telegram user has Telegram Premium.
	// It is empty if privacy mode is strict.
	IsPremium *bool `bson:"is_premium,omitempty" json:"is_premium,omitempty" db:"is_premium,omitempty"`
}

type UserInfoDiff struct {
	FirstName *string `bson:"first_name" json:"first_name" db:"first_name"`
	LastName  *string `bson:"last_name" json:"last_name" db:"last_name"`
	Username  *string `bson:"username" json:"username" db:"username"`
	IsPremium *bool   `bson:"is_premium" json:"is_premium" db:"is_premium"`
}

type UserMessages struct {
	// Main message is the last and primary one in the chat.
	MainID int `bson:"main_id" json:"main_id" db:"main_id"`
	// Head message is sent right before main message for making bot more interactive.
	HeadID int `bson:"head_id" json:"head_id" db:"head_id"`
	// Notification message can be sent in any time. Old notification message will be deleted when new one is sent.
	NotificationID int `bson:"notification_id" json:"notification_id" db:"notification_id"`
	// Error message can be sent in any time in case of error and deleted automically after next action.
	ErrorID int `bson:"error_id" json:"error_id" db:"error_id"`
	// History message is the previous main messages. Main message becomes History message after new Main sending.
	HistoryIDs []int `bson:"history_ids" json:"history_ids" db:"history_ids"`
	// LastActions contains time of last interaction of user with every message.
	LastActions map[int]time.Time `bson:"last_actions" json:"last_actions" db:"last_actions"`
}

type UserMessagesDiff struct {
	MainID         *int              `bson:"main_id" json:"main_id" db:"main_id"`
	HeadID         *int              `bson:"head_id" json:"head_id" db:"head_id"`
	NotificationID *int              `bson:"notification_id" json:"notification_id" db:"notification_id"`
	ErrorID        *int              `bson:"error_id" json:"error_id" db:"error_id"`
	HistoryIDs     []int             `bson:"history_ids" json:"history_ids" db:"history_ids"`
	LastActions    map[int]time.Time `bson:"last_actions" json:"last_actions" db:"last_actions"`
}

type UserModel struct {
	// ID is user ID.
	ID FullUserID `bson:"id" json:"id" db:"id"`
	// LanguageCode is Telegram user language code.
	// It is not encrypted even in strict privacy mode because it has low cardinality and cannot be used for identification.
	LanguageCode Language `bson:"language_code" json:"language_code" db:"language_code"`
	// ForceLanguageCode is a custom language code for user that can be set by user actions in bot.
	// It is not encrypted even in strict privacy mode because it has low cardinality and cannot be used for identification.
	ForceLanguageCode Language `bson:"force_language_code" json:"force_language_code" db:"force_language_code"`
	// Info contains user info, that can be obtained from Telegram.
	// It is empty if privacy mode is strict.
	Info UserInfo `bson:"info" json:"info" db:"info"`
	// Messages contains IDs of user messages.
	Messages UserMessages `bson:"messages" json:"messages" db:"messages"`
	// State contains state for every user's message.
	State MessagesState `bson:"state" json:"state" db:"state"`
	// Stats contains user stats.
	Stats UserStat `bson:"stats" json:"stats" db:"stats"`
	// IsBot is true if Telegram user is a bot.
	IsBot bool `bson:"is_bot" json:"is_bot" db:"is_bot"`
	// IsDisabled returns true if user is disabled. Disabled means that user blocks bot.
	IsDisabled bool `bson:"is_disabled" json:"is_disabled" db:"is_disabled"`

	// Values is a map of user values.
	Values map[string]any `bson:"values" json:"values" db:"values"`
}

type UserModelDiff struct {
	LanguageCode      *Language         `bson:"language_code" json:"language_code" db:"language_code"`
	ForceLanguageCode *Language         `bson:"force_language_code" json:"force_language_code" db:"force_language_code"`
	Info              *UserInfoDiff     `bson:"info" json:"info" db:"info"`
	Messages          *UserMessagesDiff `bson:"messages" json:"messages" db:"messages"`
	State             *UserStateDiff    `bson:"state" json:"state" db:"state"`
	Stats             *UserStatDiff     `bson:"stats" json:"stats" db:"stats"`
	IsDisabled        *bool             `bson:"is_disabled" json:"is_disabled" db:"is_disabled"`
	IsBot             *bool             `bson:"is_bot" json:"is_bot" db:"is_bot"`
	Values            map[string]any    `bson:"values" json:"values" db:"values"`
}

type UserStat struct {
	// NumberOfStateChangesTotal is the total number of actions user made.
	NumberOfStateChangesTotal int `bson:"number_of_state_changes_total" json:"number_of_state_changes_total" db:"number_of_state_changes_total"`
	// LastSeenTime is the last time user interacted with the bot.
	LastSeenTime time.Time `bson:"last_seen_time" json:"last_seen_time" db:"last_seen_time"`
	// CreatedTime is the time when user was created.
	CreatedTime time.Time `bson:"created_time" json:"created_time" db:"created_time"`
	// DisabledTime is the time when user was disabled.
	DisabledTime time.Time `bson:"disabled_time" json:"disabled_time" db:"disabled_time"`
}

type UserStatDiff struct {
	NumberOfStateChanges *int       `bson:"number_of_state_changes_total" json:"number_of_state_changes_total" db:"number_of_state_changes_total"`
	LastSeenTime         *time.Time `bson:"last_seen_time" json:"last_seen_time" db:"last_seen_time"`
	DisabledTime         *time.Time `bson:"disabled_time" json:"disabled_time" db:"disabled_time"`
}

type UserState string

type UserStateDiff struct {
	Main                 *UserState        `bson:"main" json:"main" db:"main"`
	MessageStates        map[int]UserState `bson:"message_states" json:"message_states" db:"message_states"`
	MessagesAwaitingText []int             `bson:"messages_awaiting_text" json:"messages_awaiting_text" db:"messages_awaiting_text"`
}

type UsersStorage interface {
	// Insert inserts user in storage.
	// It is better to NOT modify document before saving to make everything working properly.
	Insert(ctx context.Context, userModel UserModel) error
	// Find returns user from storage. It returns true as a second argument if user was found without error.
	Find(ctx context.Context, id FullUserID) (UserModel, bool, error)

	// UpdateAsync updates user model in storage. The idea of that method is that it calls on every user action
	// (e.g. for update state), so it should be async to make it faster for user (without IO latency).
	// So this method doesn't accept context and doesn't return error because it should be called in async goroutine.
	//
	// Warning! You can't use simple worker pool, because updates should be ordered. If you don't want to
	// make it async, you may use sync operation in this method and handle error using channels, for example.
	// You may be intersting in https://github.com/maxbolgarin/mongox for async operations in MongoDB or
	// https://github.com/maxbolgarin/gorder for general async queue if you use another db.
	//
	// If you want stable work of bote package, don't update user model by yourself. Bote will do it for you.
	// If you want to expand user model by your additional fields, create an another table/collection in your db.
	UpdateAsync(id FullUserID, userModel *UserModelDiff)
}

type WebhookConfig struct {
	// URL is the webhook endpoint URL that Telegram will use to send updates.
	// Must be HTTPS and accessible from the internet.
	// Example: "https://yourdomain.com/bot/webhook"
	URL string `yaml:"url" json:"url" env:"BOTE_WEBHOOK_URL"`

	// Listen is the address to bind the webhook server to.
	// Default: ":8443"
	// Environment variable: BOTE_WEBHOOK_LISTEN.
	Listen string `yaml:"listen" json:"listen" env:"BOTE_WEBHOOK_LISTEN"`

	// ReadTimeout is the maximum duration for reading the entire request.
	// Default: 30 seconds.
	// Environment variable: BOTE_WEBHOOK_READ_TIMEOUT.
	ReadTimeout time.Duration `yaml:"read_timeout" json:"read_timeout" env:"BOTE_WEBHOOK_READ_TIMEOUT"`

	// IdleTimeout is the maximum amount of time to wait for the next request.
	// Default: 120 seconds.
	// Environment variable: BOTE_WEBHOOK_IDLE_TIMEOUT.
	IdleTimeout time.Duration `yaml:"idle_timeout" json:"idle_timeout" env:"BOTE_WEBHOOK_IDLE_TIMEOUT"`

	// MaxConnections is the maximum allowed number of simultaneous HTTPS connections to the webhook.
	// Valid range: 1-100. Default: 40.
	// Environment variable: BOTE_WEBHOOK_MAX_CONNECTIONS.
	MaxConnections int `yaml:"max_connections" json:"max_connections" env:"BOTE_WEBHOOK_MAX_CONNECTIONS"`

	// DropPendingUpdates specifies whether to drop pending updates when setting webhook.
	// Default: false.
	// Environment variable: BOTE_WEBHOOK_DROP_PENDING_UPDATES.
	DropPendingUpdates bool `yaml:"drop_pending_updates" json:"drop_pending_updates" env:"BOTE_WEBHOOK_DROP_PENDING_UPDATES"`

	// MetricsPath is the path to serve metrics.
	// Default: "/metrics".
	// Environment variable: BOTE_WEBHOOK_METRICS_PATH.
	MetricsPath string `yaml:"metrics_path" json:"metrics_path" env:"BOTE_WEBHOOK_METRICS_PATH"`

	// EnableMetrics is a flag that enables metrics serving.
	// It uses provided registry to register metrics or a default one if registry is nil.
	// Default: false.
	// Environment variable: BOTE_WEBHOOK_ENABLE_METRICS.
	EnableMetrics bool `yaml:"enable_metrics" json:"enable_metrics" env:"BOTE_WEBHOOK_ENABLE_METRICS"`

	// Security contains security configuration.
	Security WebhookSecurityConfig `yaml:"security" json:"security"`

	// RateLimit contains rate limiting configuration.
	RateLimit WebhookRateLimitConfig `yaml:"rate_limit" json:"rate_limit"`

	// AllowedUpdates is a list of update types the bot wants to receive.
	// Empty list means all update types.
	// Possible values:
	//		message
	// 		edited_message
	// 		channel_post
	// 		edited_channel_post
	// 		inline_query
	// 		chosen_inline_result
	// 		callback_query
	// 		shipping_query
	// 		pre_checkout_query
	// 		poll
	// 		poll_answer
	//
	// Environment variable: BOTE_ALLOWED_UPDATES (comma-separated).
	AllowedUpdates []string `yaml:"allowed_updates" json:"allowed_updates" env:"BOTE_ALLOWED_UPDATES" envSeparator:","`
	// contains filtered or unexported fields
}

type WebhookRateLimitConfig struct {
	// Enabled enables rate limiting. Default: true.
	// Environment variable: BOTE_WEBHOOK_RATE_LIMIT_ENABLED.
	Enabled *bool `yaml:"enabled" json:"enabled" env:"BOTE_WEBHOOK_RATE_LIMIT_ENABLED"`

	// RequestsPerSecond is the maximum requests per second allowed.
	// Default: 30 (Telegram's recommended limit).
	// Environment variable: BOTE_WEBHOOK_RATE_LIMIT_RPS.
	RequestsPerSecond int `yaml:"requests_per_second" json:"requests_per_second" env:"BOTE_WEBHOOK_RATE_LIMIT_RPS"`

	// BurstSize is the burst size for rate limiting.
	// Default: 10.
	// Environment variable: BOTE_WEBHOOK_RATE_LIMIT_BURST.
	BurstSize int `yaml:"burst_size" json:"burst_size" env:"BOTE_WEBHOOK_RATE_LIMIT_BURST"`
}

type WebhookSecurityConfig struct {
	// SecretToken is used for webhook request verification.
	// Highly recommended for security. Will be generated automatically if not provided.
	// Environment variable: BOTE_WEBHOOK_SECRET_TOKEN.
	SecretToken string `yaml:"secret_token" json:"secret_token" env:"BOTE_WEBHOOK_SECRET_TOKEN"`

	// StartHTTPS indicates if using HTTPS in the current server.
	// If true, it will start current server as HTTPS server with provided certificate and key.
	// If false, it will start current server as HTTP server.
	// Default: false.
	// Environment variable: BOTE_WEBHOOK_START_HTTPS.
	StartHTTPS bool `yaml:"start_https" json:"start_https" env:"BOTE_WEBHOOK_START_HTTPS"`

	// LoadCertInTelegram indicates that current certificate (public part) should be loaded to Telegram.
	// It is required for Telegram webhook if you use self-signed certificate.
	// If true, will upload certificate to Telegram and providing certificate is required.
	// If false, it is expected that you use trusted certificate.
	// Default: false.
	// Environment variable: BOTE_WEBHOOK_LOAD_CERT_IN_TELEGRAM.
	LoadCertInTelegram bool `yaml:"load_cert_in_telegram" json:"load_cert_in_telegram" env:"BOTE_WEBHOOK_LOAD_CERT_IN_TELEGRAM"`

	// CertFile is the path to the TLS certificate file.
	// Required if StartHTTPS is true or LoadCertInTelegram is true.
	// If it is empty it is expected that there is a LB in front of the server that termmintaes TLS.
	// HTTPS is strictly required for Telegram webhook.
	// Environment variable: BOTE_WEBHOOK_CERT_FILE.
	CertFile string `yaml:"cert_file" json:"cert_file" env:"BOTE_WEBHOOK_CERT_FILE"`

	// KeyFile is the path to the TLS private key file.
	// Required if StartHTTPS is true or LoadCertInTelegram is true.
	// If it is empty it is expected that there is a LB in front of the server that termmintaes TLS.
	// HTTPS is strictly required for Telegram webhook.
	// Environment variable: BOTE_WEBHOOK_KEY_FILE.
	KeyFile string `yaml:"key_file" json:"key_file" env:"BOTE_WEBHOOK_KEY_FILE"`

	// CheckTLSInRequest indicates that current server should check TLS in request.
	// If true, it will check TLS in request and return 400 if it is not TLS.
	// It will try to find TLS config in request or https in X-Forwarded-Proto header.
	// If false, it will not check TLS in request.
	// Default: true.
	// Environment variable: BOTE_WEBHOOK_CHECK_TLS_IN_REQUEST.
	CheckTLSInRequest *bool `yaml:"check_tls_in_request" json:"check_tls_in_request" env:"BOTE_WEBHOOK_CHECK_TLS_IN_REQUEST"`

	// SecurityHeaders is a flag that enables security headers in response.
	// Default: true.
	// It will set the following headers:
	// - X-Frame-Options: DENY
	// - X-Content-Type-Options: nosniff
	// - X-XSS-Protection: 1; mode=block
	// - Referrer-Policy: strict-origin-when-cross-origin
	// Environment variable: BOTE_WEBHOOK_SECURITY_HEADERS.
	SecurityHeaders *bool `yaml:"security_headers" json:"security_headers" env:"BOTE_WEBHOOK_SECURITY_HEADERS"`

	// GenerateSelfSignedCert is a flag that enables generation of self-signed certificate and upload it to Telegram.
	// It will generate certificate and key files and upload them to Telegram.
	// It will set StartHTTPS to true and LoadCertInTelegram to true.
	// Default: false.
	// Environment variable: BOTE_WEBHOOK_GENERATE_SELF_SIGNED_CERT.
	GenerateSelfSignedCert *bool `yaml:"generate_self_signed_cert" json:"generate_self_signed_cert" env:"BOTE_WEBHOOK_GENERATE_SELF_SIGNED_CERT"`

	// AllowedTelegramIPs is a flag that adds Telegram IPs to allowed IPs.
	// Default: false.
	// Environment variable: BOTE_WEBHOOK_ALLOW_TELEGRAM_IPS.
	AllowTelegramIPs *bool `yaml:"allow_telegram_ips" json:"allow_telegram_ips" env:"BOTE_WEBHOOK_ALLOW_TELEGRAM_IPS"`

	// AllowedIPs contains allowed IP addresses/CIDR blocks.
	// Only requests from these IPs will be accepted.
	// Default: [] to allow all IPs.
	// Environment variable: BOTE_WEBHOOK_ALLOWED_IPS (comma-separated).
	AllowedIPs []string `yaml:"allowed_ips" json:"allowed_ips" env:"BOTE_WEBHOOK_ALLOWED_IPS" envSeparator:","`
}