plugin

type Bot interface {
	// Ready reports whether the bot is logged in.
	Ready() bool
	// Username is the bot's @username without @, "" before login.
	Username() string
	// SetPage adds or replaces the plugin's page; nil removes it. Pages
	// and settings are removed automatically when the plugin unloads.
	SetPage(p *Page) error
	// Notify sends a view to the owner's bot chat.
	Notify(ctx context.Context, v *View) (int, error)
	// Send posts a view to a chat the bot can write to.
	Send(ctx context.Context, chatID int64, v *View) (int, error)
	// Edit replaces a message the bot sent.
	Edit(ctx context.Context, chatID int64, msgID int, v *View) error
}

type BotContext struct {
	Ctx  context.Context
	Lang string
	Data string
	// Input is the text the owner typed after Ask.
	Input string
	// contains filtered or unexported fields
}

type Button struct {
	Text string
	// Data comes back to Page.Handle as BotContext.Data, at most 32 bytes.
	Data string
	URL  string
	// Style colors the button on clients that support it; others show
	// it plain.
	Style ButtonStyle
}

type ButtonStyle uint8

type Choice struct {
	Value   string
	Label   string
	LabelEN string
}

type Command struct {
	Name        string
	Aliases     []string
	Description string
	// DescEN is the English description; when set it wins over Description
	// for English users (Description stays the Chinese/primary text).
	DescEN string
	Usage  string
	// UsageEN is the English usage line; when empty Usage is reused.
	UsageEN   string
	Plugin    string
	Category  string
	OwnerOnly bool
	Hidden    bool
	RateLimit int
	Handler   Handler
}

type CommandContext struct {
	Command      string
	Args         []string
	RawArgs      string
	Message      *MessageEvent
	Session      *SessionContext
	API          *tg.Client
	PeerResolver PeerResolver
	Emitter      Emitter
	Media        MediaSender
	Downloader   MediaDownloader
	PluginName   string
	// SelfID is the account user id; Message.UserID == SelfID means the
	// owner sent the command, otherwise it is delegated sudo traffic.
	SelfID int64
	// Lang is the active language ("zh-CN"/"en-US") for this command,
	// resolved from the i18n manager. Lets plugins localize static help
	// text without registering a full catalog.
	Lang      string
	StartTime time.Time
	Metadata  map[string]any
	Ctx       context.Context
	Logger    Logger
	I18n      func(key string, args ...any) string
}

type CommandError struct {
	Code    string
	Message string
	Err     error
}

type DescENProvider interface {
	DescEN() string
}

type Emitter interface {
	Emit(ctx context.Context, eventType string, data any) error
}

type Handler func(ctx *CommandContext) error

type Host interface {
	API() *tg.Client
	PeerResolver() PeerResolver
	Media() MediaSender
	Downloader() MediaDownloader
	// SelfID is the logged-in account id (0 before login completes).
	SelfID() int64
	// Logger returns a logger named after the plugin.
	Logger(name string) Logger
	// DataDir returns data/<plugin>, creating it if needed.
	DataDir(plugin string) (string, error)
	// Send posts a Markdown message to chatID and returns its message id.
	// replyTo 0 sends a plain message.
	Send(ctx context.Context, chatID int64, text string, replyTo int) (int, error)
	// Lang is the active language for userID: zh-CN or en-US.
	Lang(userID int64) string
	// Settings registers the plugin's settings panel (spec.Plugin must be
	// the plugin name) and returns its values. Call it from Init. Options
	// are edited in the bot panel, never through commands.
	Settings(spec *SettingsSpec) (Settings, error)
	// Bot returns the companion bot scoped to the named plugin.
	Bot(plugin string) Bot
	// Listen registers a listener for every new and edited message. The
	// returned func removes it; unloading the plugin removes it too.
	Listen(plugin string, fn MessageListener) (remove func())
	// RunCommand runs msg.Text as a command with owner rights, as if the
	// owner had sent it in msg's chat (msg.Message must be a real message,
	// e.g. one the plugin just sent). It reports whether a command matched.
	RunCommand(ctx context.Context, msg *MessageEvent) (bool, error)
	// Prefixes returns the command prefixes, main prefix first.
	Prefixes() []string
}

type InvalidError struct{ Zh, En string }

type Logger interface {
	Debug(msg string, keysAndValues ...any)
	Info(msg string, keysAndValues ...any)
	Warn(msg string, keysAndValues ...any)
	Error(msg string, keysAndValues ...any)
	Named(name string) Logger
	With(keysAndValues ...any) Logger
}

type Manager interface {
	RegisterPlugin(p Plugin) error
	RegisterCommand(cmd *Command) error
	UnregisterCommand(name string)
	UnregisterPlugin(name string)
	Commands() RegistryProvider
	GetInfo(name string) (PluginInfo, bool)
	GetAllInfo() []PluginInfo
	GetPlugin(name string) (Plugin, bool)
	Emit(ctx context.Context, eventType string, data any) error
	InitAll(ctx context.Context) error
	StartAll(ctx context.Context) error
	StopAll(ctx context.Context) error
	// Host exposes long-lived runtime services so plugins can work outside
	// command handlers (schedulers, restored jobs, event listeners).
	Host() Host
}

type MediaDownloader interface {
	DownloadMedia(ctx context.Context, msg *MessageEvent) (string, error)
}

type MediaSender interface {
	SendFile(ctx context.Context, chatID int64, path string, caption string, replyTo int) error
}

type MessageEvent struct {
	Update    tg.UpdatesClass
	Message   *tg.Message
	Text      string
	UserID    int64
	ChatID    int64
	IsOut     bool
	IsReply   bool
	ReplyToID int
	Entities  []tg.MessageEntityClass
	Media     tg.MessageMediaClass
	Date      int
	PeerID    tg.PeerClass
	Raw       any
}

type MessageListener func(ctx context.Context, msg *MessageEvent, edited bool)

type Middleware func(next Handler) Handler

type Page struct {
	Title   string
	TitleEN string
	// Command optionally opens the page with /<Command> in the bot chat.
	Command string
	// Handle renders the page. Data is "" when the page opens, otherwise
	// the Data of the pressed button (or the Ask key with Input set).
	// The bot appends a back button; do not add one.
	Handle func(ctx *BotContext) (*View, error)
}

type PeerResolver interface {
	ResolveFromChatID(ctx context.Context, chatID int64) (tg.InputPeerClass, error)
	ResolveUserInChannel(ctx context.Context, channelPeer tg.InputChannelClass, userID int64) (tg.InputPeerClass, error)
	ResolveUserFromMessage(ctx context.Context, peer tg.InputPeerClass, msgID int, userID int64) (tg.InputPeerClass, error)
	ResolveUsername(ctx context.Context, username string) (tg.InputPeerClass, error)
}

type Plugin interface {
	Name() string
	Description() string
	Init(ctx context.Context, mgr Manager) error
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

type PluginInfo struct {
	Name        string
	Description string
	DescEN      string
	Status      PluginStatus
}

type PluginMetadata struct {
	Name        string
	Description string
	DescEN      string
	Version     string
	Author      string
	MinVersion  string
}

type PluginStatus int

type RegistryProvider interface {
	Get(name string) (*Command, bool)
	GetAll() map[string]*Command
	GetByPlugin(plugin string) map[string]*Command
	GetPrefix() string
	GetPrefixes() []string
	// SetPrefixes replaces all command prefixes (main prefix first).
	SetPrefixes(prefixes []string)
	// AddUserAlias registers a runtime alias expanded once during parsing.
	// The value is a full command line, e.g. "exec ./deploy.sh".
	AddUserAlias(name, cmd string)
	RemoveUserAlias(name string)
	UserAliases() map[string]string
}

type Session struct {
	UserID    int64
	ChatID    int64
	State     string
	Data      map[string]any
	Timestamp int64
}

type SessionContext struct {
	Session *Session
	Context context.Context
	Data    map[string]any
}

type Setting struct {
	// Key is the stable id, lowercase letters, digits and _ only.
	Key     string
	Label   string
	LabelEN string
	// Hint is one line shown on the edit screen.
	Hint   string
	HintEN string
	Kind   SettingKind
	// Default must match Kind: bool, string or int.
	Default any
	Choices []Choice
	// Min and Max bound a SettingNumber; both 0 means unbounded.
	Min, Max int
	// Validate checks typed text (SettingText) and may normalize it.
	// Return Invalid(zh, en) so the owner reads the reason in their language.
	Validate func(string) (string, error)
	// Secret masks the value in the panel.
	Secret bool
}

type SettingKind int

type Settings interface {
	Bool(key string) bool
	String(key string) string
	Int(key string) int
	// Set stores a value; its type must match the setting's Kind.
	Set(key string, value any) error
}

type SettingsSpec struct {
	Plugin   string
	Title    string // defaults to the plugin name
	TitleEN  string
	Settings []Setting
	// OnChange runs after a value changes, from the panel or from Set.
	OnChange func(key string)
}

type View struct {
	Text    string
	Buttons [][]Button
}