v1.0.0 beta 12

Makefile

@@ -0,0 +1,15 @@
+# Проверка наличия golangci-lint
+GO_LINT := $(shell command -v golangci-lint 2>/dev/null)
+
+# Цель: запуск всех проверок кода
+check:
+	@echo "🔍 Running code checks..."
+	@go mod tidy -v
+	@go vet ./...
+	@if [ -n "$(GO_LINT)" ]; then \
+		echo "✅ golangci-lint found, running..." && \
+		golangci-lint run --timeout=5m --verbose; \
+	else \
+		echo "⚠️  golangci-lint not installed. Install with: curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.57.2"; \
+	fi
+	@go test -race -v ./... 2>/dev/null || echo "⚠️  Tests skipped or failed (run manually with 'go test -race ./...')"

bot.go

@@ -1,3 +1,34 @@
+// Package laniakea provides a modular, extensible framework for building scalable
+// Telegram bots with support for plugins, middleware, localization, draft messages,
+// rate limiting, structured logging, and dependency injection.
+//
+// The framework is designed around a fluent API for configuration and separation of concerns:
+//
+//   - Plugins: Handle specific commands or events (e.g., /start, /help)
+//   - Middleware: Intercept and modify updates before plugins run (auth, logging, validation)
+//   - Runners: Background goroutines for cleanup, cron jobs, or monitoring
+//   - DraftProvider: Safely build and resume multi-step messages
+//   - L10n: Multi-language support via key-based translation
+//   - RateLimiter: Enforces Telegram API limits to avoid bans
+//   - Structured Logging: JSON stdout + optional file output with request-level tracing
+//   - Dependency Injection: Inject custom database contexts (e.g., *gorm.DB, *sql.DB)
+//
+// Example usage:
+//
+//	bot := laniakea.NewBot[mydb.DBContext](laniakea.LoadOptsFromEnv()).
+//		DatabaseContext(&myDB).
+//		AddUpdateType(tgapi.UpdateTypeMessage).
+//		AddPrefixes("/", "!").
+//		AddPlugins(&startPlugin, &helpPlugin).
+//		AddMiddleware(&authMiddleware, &logMiddleware).
+//		AddRunner(&cleanupRunner).
+//		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.
 package laniakea
 
 import (
@@ -8,38 +39,90 @@ import (
 	"strconv"
 	"strings"
 	"sync"
+	"time"
 
 	"git.nix13.pw/scuroneko/extypes"
 	"git.nix13.pw/scuroneko/laniakea/tgapi"
+	"git.nix13.pw/scuroneko/laniakea/utils"
 	"git.nix13.pw/scuroneko/slog"
 	"github.com/alitto/pond/v2"
-	"golang.org/x/time/rate"
 )
 
+// BotOpts holds configuration options for initializing a Bot.
+//
+// Values are loaded from environment variables via LoadOptsFromEnv().
+// Use NewOpts() to create a zero-value struct and set fields manually.
 type BotOpts struct {
-	Token       string
+	// Token is the Telegram bot token (required).
+	Token string
+
+	// UpdateTypes is a semicolon-separated list of update types to listen for.
+	// Example: "message;edited_message;callback_query"
+	// Defaults to empty (Telegram will return all types).
 	UpdateTypes []string
 
-	Debug         bool
+	// Debug enables debug-level logging.
+	Debug bool
+
+	// ErrorTemplate is the format string used to wrap error messages sent to users.
+	// Use "%s" to insert the actual error. Example: "❌ Error: %s"
 	ErrorTemplate string
-	Prefixes      []string
 
-	LoggerBasePath   string
+	// Prefixes is a list of command prefixes (e.g., ["/", "!"]).
+	// Defaults to ["/"] if not set via environment.
+	Prefixes []string
+
+	// LoggerBasePath is the directory where log files are written.
+	// Defaults to "./".
+	LoggerBasePath string
+
+	// UseRequestLogger enables detailed logging of all Telegram API requests.
 	UseRequestLogger bool
-	WriteToFile      bool
 
+	// WriteToFile enables writing logs to files (main.log and requests.log).
+	WriteToFile bool
+
+	// UseTestServer uses Telegram's test server (https://api.test.telegram.org).
 	UseTestServer bool
-	APIUrl        string
 
-	RateLimit      int
+	// APIUrl overrides the default Telegram API endpoint (useful for proxies or self-hosted).
+	APIUrl string
+
+	// RateLimit is the maximum number of API requests per second.
+	// Telegram allows up to 30 req/s for most bots. Defaults to 30.
+	RateLimit int
+
+	// DropRLOverflow drops incoming updates when rate limit is exceeded instead of queuing.
+	// Use this to prioritize responsiveness over reliability.
 	DropRLOverflow bool
 }
 
+// NewOpts returns a new BotOpts with zero values.
 func NewOpts() *BotOpts { return new(BotOpts) }
+
+// LoadOptsFromEnv loads BotOpts from environment variables.
+//
+// Environment variables:
+//   - TG_TOKEN: Bot token (required)
+//   - UPDATE_TYPES: semicolon-separated update types (e.g., "message;callback_query")
+//   - DEBUG: "true" to enable debug logging
+//   - ERROR_TEMPLATE: format string for error messages (e.g., "❌ %s")
+//   - PREFIXES: semicolon-separated prefixes (e.g., "/;!bot")
+//   - LOGGER_BASE_PATH: directory for log files (default: "./")
+//   - USE_REQ_LOG: "true" to enable request logging
+//   - WRITE_TO_FILE: "true" to write logs to files
+//   - USE_TEST_SERVER: "true" to use Telegram test server
+//   - API_URL: custom API endpoint
+//   - RATE_LIMIT: max requests per second (default: 30)
+//   - DROP_RL_OVERFLOW: "true" to drop updates on rate limit overflow
+//
+// Returns a populated BotOpts. If TG_TOKEN is missing, behavior is undefined.
 func LoadOptsFromEnv() *BotOpts {
 	rateLimit := 30
 	if rl := os.Getenv("RATE_LIMIT"); rl != "" {
-		rateLimit, _ = strconv.Atoi(rl)
+		if n, err := strconv.Atoi(rl); err == nil {
+			rateLimit = n
+		}
 	}
 
 	return &BotOpts{
@@ -50,6 +133,7 @@ func LoadOptsFromEnv() *BotOpts {
 		ErrorTemplate: os.Getenv("ERROR_TEMPLATE"),
 		Prefixes:      LoadPrefixesFromEnv(),
 
+		LoggerBasePath:   os.Getenv("LOGGER_BASE_PATH"),
 		UseRequestLogger: os.Getenv("USE_REQ_LOG") == "true",
 		WriteToFile:      os.Getenv("WRITE_TO_FILE") == "true",
 
@@ -60,6 +144,9 @@ func LoadOptsFromEnv() *BotOpts {
 		DropRLOverflow: os.Getenv("DROP_RL_OVERFLOW") == "true",
 	}
 }
+
+// LoadPrefixesFromEnv returns the PREFIXES environment variable split by semicolon.
+// Defaults to ["/"] if not set.
 func LoadPrefixesFromEnv() []string {
 	prefixesS, exists := os.LookupEnv("PREFIXES")
 	if !exists {
@@ -68,43 +155,86 @@ func LoadPrefixesFromEnv() []string {
 	return strings.Split(prefixesS, ";")
 }
 
+// DbContext is an interface representing the application's database context.
+// It is injected into plugins and middleware via Bot.DatabaseContext().
+//
+// Example:
+//
+//	type MyDB struct { ... }
+//	bot := NewBot[MyDB](opts).DatabaseContext(&myDB)
+//
+// Use NoDB if no database is needed.
 type DbContext interface{}
+
+// NoDB is a placeholder type for bots that do not use a database.
+// Use Bot[NoDB] to indicate no dependency injection is required.
 type NoDB struct{ DbContext }
+
+// Bot is the core Telegram bot instance.
+//
+// Manages:
+//   - API communication via tgapi
+//   - Update processing pipeline (middleware → plugins)
+//   - Background runners
+//   - Logging and rate limiting
+//   - Localization and draft message support
+//
+// All methods are safe for concurrent use. Direct field access is not recommended.
 type Bot[T DbContext] struct {
 	token         string
 	debug         bool
 	errorTemplate string
+	username      string
 
-	logger        *slog.Logger
+	logger        *slog.Logger                // Main bot logger (JSON stdout + optional file)
-	RequestLogger *slog.Logger
+	RequestLogger *slog.Logger                // Optional request-level API logging
-	extraLoggers  extypes.Slice[*slog.Logger]
+	extraLoggers  extypes.Slice[*slog.Logger] // API, Uploader, and custom loggers
 
-	plugins     []Plugin[T]
+	plugins     []Plugin[T]     // Command/event handlers
-	middlewares []Middleware[T]
+	middlewares []Middleware[T] // Pre-processing filters (sorted by order)
-	prefixes    []string
+	prefixes    []string        // Command prefixes (e.g., "/", "!")
-	runners     []Runner[T]
+	runners     []Runner[T]     // Background tasks (e.g., cleanup, cron)
 
-	api           *tgapi.API
+	api           *tgapi.API      // Telegram API client
-	uploader      *tgapi.Uploader
+	uploader      *tgapi.Uploader // File uploader
-	dbContext     *T
+	dbContext     *T              // Injected database context
-	l10n          *L10n
+	l10n          *L10n           // Localization manager
-	draftProvider *DraftProvider
+	draftProvider *DraftProvider  // Draft message builder
 
 	updateOffsetMu sync.Mutex
-	updateOffset   int
+	updateOffset   int                // Last processed update ID
-	updateTypes    []tgapi.UpdateType
+	updateTypes    []tgapi.UpdateType // Types of updates to fetch
-	updateQueue    chan *tgapi.Update
+	updateQueue    chan *tgapi.Update // Internal queue for processing updates
 }
 
+// NewBot creates and initializes a new Bot instance using the provided BotOpts.
+//
+// Automatically:
+//   - Creates API and Uploader clients
+//   - Initializes structured logging (JSON stdout + optional file)
+//   - Fetches bot username via GetMe()
+//   - Sets up DraftProvider with random IDs
+//   - Adds API and Uploader loggers to extraLoggers
+//
+// Panics if:
+//   - Token is empty
+//   - GetMe() fails (invalid token or network error)
 func NewBot[T any](opts *BotOpts) *Bot[T] {
-	updateQueue := make(chan *tgapi.Update, 512)
+	if opts.Token == "" {
-
+		panic("laniakea: BotOpts.Token is required")
-	var limiter *rate.Limiter
-	if opts.RateLimit > 0 {
-		limiter = rate.NewLimiter(rate.Limit(opts.RateLimit), opts.RateLimit)
 	}
 
-	apiOpts := tgapi.NewAPIOpts(opts.Token).SetAPIUrl(opts.APIUrl).UseTestServer(opts.UseTestServer).SetLimiter(limiter)
+	updateQueue := make(chan *tgapi.Update, 512)
+
+	var limiter *utils.RateLimiter
+	if opts.RateLimit > 0 {
+		limiter = utils.NewRateLimiter()
+	}
+
+	apiOpts := tgapi.NewAPIOpts(opts.Token).
+		SetAPIUrl(opts.APIUrl).
+		UseTestServer(opts.UseTestServer).
+		SetLimiter(limiter)
 	api := tgapi.NewAPI(apiOpts)
 
 	uploader := tgapi.NewUploader(api)
@@ -125,6 +255,8 @@ func NewBot[T any](opts *BotOpts) *Bot[T] {
 		l10n:          &L10n{},
 		draftProvider: NewRandomDraftProvider(api),
 	}
+
+	// Add API and Uploader loggers to extraLoggers for unified output
 	bot.extraLoggers = bot.extraLoggers.Push(api.GetLogger()).Push(uploader.GetLogger())
 
 	if len(opts.ErrorTemplate) > 0 {
@@ -135,15 +267,30 @@ func NewBot[T any](opts *BotOpts) *Bot[T] {
 	}
 	bot.initLoggers(opts)
 
+	// Fetch bot info to validate token and get username
 	u, err := api.GetMe()
 	if err != nil {
 		_ = bot.Close()
 		bot.logger.Fatal(err)
 	}
-	bot.logger.Infof("Authorized as %s\n", u.FirstName)
+	bot.username = Val(u.Username, "")
+	if bot.username == "" {
+		bot.logger.Warn("Can't get bot username. Named command handlers won't work!")
+	}
+	bot.logger.Infof("Authorized as %s (@%s)\n", u.FirstName, u.Username)
 
 	return bot
 }
+
+// Close gracefully shuts down the bot.
+//
+// Closes:
+//   - Uploader (waits for pending uploads)
+//   - API client
+//   - RequestLogger (if enabled)
+//   - Main logger
+//
+// Returns the first error encountered, if any.
 func (bot *Bot[T]) Close() error {
 	if err := bot.uploader.Close(); err != nil {
 		bot.logger.Errorln(err)
@@ -151,14 +298,22 @@ func (bot *Bot[T]) Close() error {
 	if err := bot.api.CloseApi(); err != nil {
 		bot.logger.Errorln(err)
 	}
-	if err := bot.RequestLogger.Close(); err != nil {
+	if bot.RequestLogger != nil {
-		bot.logger.Errorln(err)
+		if err := bot.RequestLogger.Close(); err != nil {
+			bot.logger.Errorln(err)
+		}
 	}
 	if err := bot.logger.Close(); err != nil {
 		return err
 	}
 	return nil
 }
+
+// initLoggers configures the main and optional request loggers.
+//
+// Uses DEBUG flag to set log level (DEBUG if true, FATAL otherwise).
+// Writes to stdout in JSON format by default.
+// If WriteToFile is true, writes to main.log and requests.log in LoggerBasePath.
 func (bot *Bot[T]) initLoggers(opts *BotOpts) {
 	level := slog.FATAL
 	if opts.Debug {
@@ -190,27 +345,59 @@ func (bot *Bot[T]) initLoggers(opts *BotOpts) {
 	}
 }
 
+// GetUpdateOffset returns the current update offset (thread-safe).
 func (bot *Bot[T]) GetUpdateOffset() int {
 	bot.updateOffsetMu.Lock()
 	defer bot.updateOffsetMu.Unlock()
 	return bot.updateOffset
 }
+
+// SetUpdateOffset sets the update offset for next GetUpdates call (thread-safe).
 func (bot *Bot[T]) SetUpdateOffset(offset int) {
 	bot.updateOffsetMu.Lock()
 	defer bot.updateOffsetMu.Unlock()
 	bot.updateOffset = offset
 }
+
+// GetUpdateTypes returns the list of update types the bot is configured to receive.
 func (bot *Bot[T]) GetUpdateTypes() []tgapi.UpdateType { return bot.updateTypes }
-func (bot *Bot[T]) GetLogger() *slog.Logger            { return bot.logger }
+
-func (bot *Bot[T]) GetDBContext() *T                   { return bot.dbContext }
+// GetLogger returns the main bot logger.
-func (bot *Bot[T]) L10n(lang, key string) string       { return bot.l10n.Translate(lang, key) }
+func (bot *Bot[T]) GetLogger() *slog.Logger { return bot.logger }
+
+// GetDBContext returns the injected database context.
+// Returns nil if not set via DatabaseContext().
+func (bot *Bot[T]) GetDBContext() *T { return bot.dbContext }
+
+// L10n translates a key in the given language.
+// Returns empty string if translation not found.
+func (bot *Bot[T]) L10n(lang, key string) string {
+	return bot.l10n.Translate(lang, key)
+}
+
+// SetDraftProvider replaces the default DraftProvider with a custom one.
+// Useful for using LinearDraftIdGenerator to persist draft IDs across restarts.
 func (bot *Bot[T]) SetDraftProvider(p *DraftProvider) *Bot[T] {
 	bot.draftProvider = p
 	return bot
 }
 
+// DbLogger is a function type that returns a slog.LoggerWriter for database logging.
+// Used to inject database-specific log output (e.g., SQL queries, ORM events).
 type DbLogger[T DbContext] func(db *T) slog.LoggerWriter
 
+// AddDatabaseLoggerWriter adds a database logger writer to all loggers.
+//
+// The writer will receive logs from:
+//   - Main bot logger
+//   - Request logger (if enabled)
+//   - API and Uploader loggers
+//
+// Example:
+//
+//	bot.AddDatabaseLoggerWriter(func(db *MyDB) slog.LoggerWriter {
+//	    return db.QueryLogger()
+//	})
 func (bot *Bot[T]) AddDatabaseLoggerWriter(writer DbLogger[T]) *Bot[T] {
 	w := writer(bot.dbContext)
 	bot.logger.AddWriter(w)
@@ -223,31 +410,51 @@ func (bot *Bot[T]) AddDatabaseLoggerWriter(writer DbLogger[T]) *Bot[T] {
 	return bot
 }
 
+// DatabaseContext injects a database context into the bot.
+// This context is accessible to plugins and middleware via GetDBContext().
 func (bot *Bot[T]) DatabaseContext(ctx *T) *Bot[T] {
 	bot.dbContext = ctx
 	return bot
 }
+
+// UpdateTypes sets the list of update types the bot will request from Telegram.
+// Overwrites any previously set types.
 func (bot *Bot[T]) UpdateTypes(t ...tgapi.UpdateType) *Bot[T] {
 	bot.updateTypes = make([]tgapi.UpdateType, 0)
 	bot.updateTypes = append(bot.updateTypes, 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] {
 	bot.updateTypes = append(bot.updateTypes, t...)
 	return bot
 }
+
+// AddPrefixes adds one or more command prefixes (e.g., "/", "!").
+// Must have at least one prefix before Run().
 func (bot *Bot[T]) AddPrefixes(prefixes ...string) *Bot[T] {
 	bot.prefixes = append(bot.prefixes, prefixes...)
 	return bot
 }
+
+// ErrorTemplate sets the format string for error messages sent to users.
+// Use "%s" to insert the error message.
+// Example: "❌ Error: %s" → "❌ Error: Command not found"
 func (bot *Bot[T]) ErrorTemplate(s string) *Bot[T] {
 	bot.errorTemplate = s
 	return bot
 }
+
+// Debug enables or disables debug logging.
 func (bot *Bot[T]) Debug(debug bool) *Bot[T] {
 	bot.debug = debug
 	return bot
 }
+
+// AddPlugins registers one or more plugins.
+// Plugins are executed in registration order unless filtered by middleware.
 func (bot *Bot[T]) AddPlugins(plugin ...*Plugin[T]) *Bot[T] {
 	for _, p := range plugin {
 		bot.plugins = append(bot.plugins, *p)
@@ -255,33 +462,96 @@ func (bot *Bot[T]) AddPlugins(plugin ...*Plugin[T]) *Bot[T] {
 	}
 	return bot
 }
+
+// AddMiddleware registers one or more middleware handlers.
+//
+// Middleware are executed in order of increasing .order value before plugins.
+// If two middleware have the same order, they are sorted lexicographically by name.
+//
+// Middleware can:
+//   - Modify or reject updates before they reach plugins
+//   - Inject context (e.g., user auth state, rate limit status)
+//   - Log, validate, or transform incoming data
+//
+// Example:
+//
+//	bot.AddMiddleware(&authMiddleware, &rateLimitMiddleware)
+//
+// Panics if any middleware has a nil name.
 func (bot *Bot[T]) AddMiddleware(middleware ...Middleware[T]) *Bot[T] {
-	bot.middlewares = append(bot.middlewares, middleware...)
 	for _, m := range middleware {
+		if m.name == "" {
+			panic("laniakea: middleware must have a non-empty name")
+		}
+		bot.middlewares = append(bot.middlewares, m)
 		bot.logger.Debugln(fmt.Sprintf("middleware with name \"%s\" registered", m.name))
 	}
 
+	// Stable sort by order (ascending), then by name (lexicographic)
 	sort.Slice(bot.middlewares, func(i, j int) bool {
 		first := bot.middlewares[i]
 		second := bot.middlewares[j]
-		if first.order == second.order {
+		if first.order != second.order {
-			return first.name < second.name
+			return first.order < second.order
 		}
-		return first.order < second.order
+		return first.name < second.name
 	})
 
 	return bot
 }
+
+// AddRunner registers a background runner to execute concurrently with the bot.
+//
+// Runners are goroutines that run independently of update processing.
+// Common use cases:
+//   - Periodic cleanup (e.g., expiring drafts, clearing temp files)
+//   - Metrics collection or health checks
+//   - Scheduled tasks (e.g., daily announcements)
+//
+// Runners are started immediately after Bot.Run() is called.
+//
+// Example:
+//
+//	bot.AddRunner(&cleanupRunner)
+//
+// Panics if runner has a nil name.
 func (bot *Bot[T]) AddRunner(runner Runner[T]) *Bot[T] {
+	if runner.name == "" {
+		panic("laniakea: runner must have a non-empty name")
+	}
 	bot.runners = append(bot.runners, runner)
 	bot.logger.Debugln(fmt.Sprintf("runner with name \"%s\" registered", runner.name))
 	return bot
 }
+
+// AddL10n sets the localization (i18n) provider for the bot.
+//
+// The L10n instance must be pre-populated with translations.
+// Translations are accessed via Bot.L10n(lang, key).
+//
+// Example:
+//
+//	l10n := l10n.New()
+//	l10n.Add("en", "hello", "Hello!")
+//	l10n.Add("es", "hello", "¡Hola!")
+//	bot.AddL10n(l10n)
+//
+// Replaces any previously set L10n instance.
 func (bot *Bot[T]) AddL10n(l *L10n) *Bot[T] {
+	if l == nil {
+		bot.logger.Warn("AddL10n called with nil L10n; localization will be disabled")
+	}
 	bot.l10n = l
 	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:
@@ -290,6 +560,26 @@ func (bot *Bot[T]) enqueueUpdate(u *tgapi.Update) error {
 		return extypes.QueueFullErr
 	}
 }
+
+// RunWithContext starts the bot with a given context for graceful shutdown.
+//
+// This is the main entry point for bot execution. It:
+//   - Validates required configuration (prefixes, plugins)
+//   - Starts all registered runners as background goroutines
+//   - Begins polling for updates via Telegram's GetUpdates API
+//   - Processes updates concurrently using a worker pool (16 goroutines)
+//
+// The context controls graceful shutdown. When canceled, the bot:
+//   - Stops polling for new updates
+//   - Finishes processing currently queued updates
+//   - Closes all resources (API, uploader, loggers)
+//
+// Example:
+//
+//	ctx, cancel := context.WithCancel(context.Background())
+//	go bot.RunWithContext(ctx)
+//	// ... later ...
+//	cancel() // triggers graceful shutdown
 func (bot *Bot[T]) RunWithContext(ctx context.Context) {
 	if len(bot.prefixes) == 0 {
 		bot.logger.Fatalln("no prefixes defined")
@@ -304,6 +594,8 @@ func (bot *Bot[T]) RunWithContext(ctx context.Context) {
 	bot.ExecRunners()
 
 	bot.logger.Infoln("Bot running. Press CTRL+C to exit.")
+
+	// Start update polling in a goroutine
 	go func() {
 		for {
 			select {
@@ -312,13 +604,14 @@ func (bot *Bot[T]) RunWithContext(ctx context.Context) {
 			default:
 				updates, err := bot.Updates()
 				if err != nil {
-					bot.logger.Errorln(err)
+					bot.logger.Errorln("failed to fetch updates:", err)
+					time.Sleep(2 * time.Second) // exponential backoff
 					continue
 				}
 
 				for _, u := range updates {
 					select {
-					case bot.updateQueue <- new(u):
+					case bot.updateQueue <- u:
 					case <-ctx.Done():
 						return
 					}
@@ -327,14 +620,22 @@ func (bot *Bot[T]) RunWithContext(ctx context.Context) {
 		}
 	}()
 
+	// Start worker pool for concurrent update handling
 	pool := pond.NewPool(16)
 	for update := range bot.updateQueue {
-		update := update
+		update := update // capture loop variable
 		pool.Submit(func() {
 			bot.handle(update)
 		})
 	}
 }
+
+// Run starts the bot using a background context.
+//
+// Equivalent to RunWithContext(context.Background()).
+// Use this for simple bots where graceful shutdown is not required.
+//
+// For production use, prefer RunWithContext to handle SIGINT/SIGTERM gracefully.
 func (bot *Bot[T]) Run() {
 	bot.RunWithContext(context.Background())
 }

cmd_generator.go

@@ -1,3 +1,12 @@
+// Package laniakea provides a framework for building Telegram bots with plugin-based
+// command registration and automatic command scope management.
+//
+// This module automatically generates and registers bot commands across different
+// chat scopes (private, group, admin) based on plugin-defined commands.
+//
+// Commands are derived from Plugin and Command structs, with optional descriptions
+// and argument formatting. Automatic registration avoids manual command setup and
+// ensures consistency across chat types.
 package laniakea
 
 import (
@@ -8,23 +17,52 @@ import (
 	"git.nix13.pw/scuroneko/laniakea/tgapi"
 )
 
+// ErrTooManyCommands is returned when the total number of registered commands
+// exceeds Telegram's limit of 100 bot commands per bot.
+//
+// Telegram Bot API enforces this limit strictly. If exceeded, SetMyCommands
+// will fail with a 400 error. This error helps catch the issue early during
+// bot initialization.
+var ErrTooManyCommands = errors.New("too many commands. max 100")
+
+// generateBotCommand converts a Command[T] into a tgapi.BotCommand with a
+// formatted description that includes usage instructions.
+//
+// The description is built as:
+//
+//	"<original_description>. Usage: /<command> <arg1> [<arg2>] ..."
+//
+// Required arguments are shown as-is; optional arguments are wrapped in square brackets.
+//
+// Example:
+//
+//	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
 	if len(cmd.description) > 0 {
 		desc = cmd.description
 	}
+
 	var descArgs []string
 	for _, a := range cmd.args {
 		if a.required {
-			descArgs = append(descArgs, fmt.Sprintf("%s", a.text))
+			descArgs = append(descArgs, a.text)
 		} else {
 			descArgs = append(descArgs, fmt.Sprintf("[%s]", a.text))
 		}
 	}
+
 	desc = fmt.Sprintf("%s. Usage: /%s %s", desc, cmd.command, strings.Join(descArgs, " "))
 	return tgapi.BotCommand{Command: cmd.command, Description: desc}
 }
 
+// generateBotCommandForPlugin collects all non-skipped commands from a Plugin[T]
+// and converts them into tgapi.BotCommand objects.
+//
+// Commands marked with skipAutoCmd = true are excluded from auto-registration.
+// This allows plugins to opt out of automatic command generation (e.g., for
+// internal or hidden commands).
 func generateBotCommandForPlugin[T any](pl Plugin[T]) []tgapi.BotCommand {
 	commands := make([]tgapi.BotCommand, 0)
 	for _, cmd := range pl.commands {
@@ -36,37 +74,66 @@ func generateBotCommandForPlugin[T any](pl Plugin[T]) []tgapi.BotCommand {
 	return commands
 }
 
-var ErrTooManyCommands = errors.New("too many commands. max 100")
+// AutoGenerateCommands registers all plugin-defined commands with Telegram's Bot API
-
+// across three scopes:
+//   - Private chats (users)
+//   - Group chats
+//   - Group administrators
+//
+// It first deletes existing commands to ensure a clean state, then sets the new
+// set of commands for all scopes. This ensures consistency even if commands were
+// previously modified manually via @BotFather.
+//
+// Returns ErrTooManyCommands if the total number of commands exceeds 100.
+// Returns any API error from Telegram (e.g., network issues, invalid scope).
+//
+// Important: This method assumes the bot has been properly initialized and
+// the API client is authenticated and ready.
+//
+// Usage:
+//
+//	err := bot.AutoGenerateCommands()
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
 func (bot *Bot[T]) AutoGenerateCommands() error {
+	// Clear existing commands to avoid duplication or stale entries
 	_, err := bot.api.DeleteMyCommands(tgapi.DeleteMyCommandsP{})
 	if err != nil {
-		return err
+		return fmt.Errorf("failed to delete existing commands: %w", err)
 	}
 
+	// Collect all non-skipped commands from all plugins
 	commands := make([]tgapi.BotCommand, 0)
 	for _, pl := range bot.plugins {
 		if pl.skipAutoCmd {
 			continue
 		}
-
 		commands = append(commands, generateBotCommandForPlugin(pl)...)
+		bot.logger.Debugf("Registered %d commands from plugin %s", len(pl.commands), pl.name)
 	}
+
+	// Enforce Telegram's 100-command limit
 	if len(commands) > 100 {
 		return ErrTooManyCommands
 	}
 
-	privateChatsScope := &tgapi.BotCommandScope{Type: tgapi.BotCommandScopePrivateType}
+	// Register commands for each scope
-	groupChatsScope := &tgapi.BotCommandScope{Type: tgapi.BotCommandScopeGroupType}
+	scopes := []*tgapi.BotCommandScope{
-	chatAdminsScope := &tgapi.BotCommandScope{Type: tgapi.BotCommandScopeAllChatAdministratorsType}
+		{Type: tgapi.BotCommandScopePrivateType},
-	_, err = bot.api.SetMyCommands(tgapi.SetMyCommandsP{Commands: commands, Scope: privateChatsScope})
+		{Type: tgapi.BotCommandScopeGroupType},
-	if err != nil {
+		{Type: tgapi.BotCommandScopeAllChatAdministratorsType},
-		return err
 	}
-	_, err = bot.api.SetMyCommands(tgapi.SetMyCommandsP{Commands: commands, Scope: groupChatsScope})
+
-	if err != nil {
+	for _, scope := range scopes {
-		return err
+		_, err = bot.api.SetMyCommands(tgapi.SetMyCommandsP{
+			Commands: commands,
+			Scope:    scope,
+		})
+		if err != nil {
+			return fmt.Errorf("failed to set commands for scope %q: %w", scope.Type, err)
+		}
 	}
-	_, err = bot.api.SetMyCommands(tgapi.SetMyCommandsP{Commands: commands, Scope: chatAdminsScope})
+
-	return err
+	return nil
 }

drafts.go

@@ -1,49 +1,176 @@
+// Package laniakea provides a safe, high-level interface for managing Telegram
+// message drafts using the tgapi library. It allows creating, editing, and
+// flushing drafts with automatic ID generation and optional bulk flushing.
+//
+// Drafts are designed to be ephemeral, mutable buffers that can be built up
+// incrementally and then sent as final messages. The package ensures safe
+// state management by copying entities and isolating draft contexts.
+//
+// Two draft ID generation strategies are supported:
+//   - Random: Cryptographically secure random IDs (default). Ideal for distributed systems.
+//   - Linear: Monotonically increasing IDs. Useful for persistence, debugging, or recovery.
+//
+// Example usage:
+//
+//	provider := laniakea.NewRandomDraftProvider(api)
+//	provider.SetChat(-1001234567890, 0).SetParseMode(tgapi.ParseModeHTML)
+//
+//	draft := provider.NewDraft(tgapi.ParseModeMarkdown)
+//	draft.Push("*Hello*").Push(" **world**!")
+//	err := draft.Flush() // Sends message and deletes draft
+//	if err != nil {
+//	    log.Printf("Failed to send draft: %v", err)
+//	}
+//
+//	// Or flush all pending drafts at once:
+//	err = provider.FlushAll() // Sends all drafts and clears them
+//
+// Note: Drafts are NOT thread-safe. Concurrent access requires external synchronization.
 package laniakea
 
 import (
-	"math"
 	"math/rand/v2"
 	"sync/atomic"
 
 	"git.nix13.pw/scuroneko/laniakea/tgapi"
 )
 
+// draftIdGenerator defines an interface for generating unique draft IDs.
 type draftIdGenerator interface {
+	// Next returns the next unique draft ID.
 	Next() uint64
 }
 
-type RandomDraftIdGenerator struct {
+// RandomDraftIdGenerator generates draft IDs using cryptographically secure random numbers.
-	draftIdGenerator
+// Suitable for distributed systems or when ID predictability is undesirable.
-}
+type RandomDraftIdGenerator struct{}
 
+// Next returns a random 64-bit unsigned integer.
 func (g *RandomDraftIdGenerator) Next() uint64 {
-	return rand.Uint64N(math.MaxUint64)
+	return rand.Uint64()
 }
 
+// LinearDraftIdGenerator generates draft IDs using a monotonically increasing counter.
+// Useful for debugging, persistence, or when drafts must be ordered.
 type LinearDraftIdGenerator struct {
-	draftIdGenerator
+	lastId atomic.Uint64
-	lastId uint64
 }
 
+// Next returns the next linear ID, atomically incremented.
 func (g *LinearDraftIdGenerator) Next() uint64 {
-	return atomic.AddUint64(&g.lastId, 1)
+	return g.lastId.Add(1)
 }
 
+// DraftProvider manages a collection of Drafts and provides methods to create and
+// configure them. It holds shared configuration (chat, parse mode, entities) and
+// a draft ID generator.
+//
+// DraftProvider is NOT thread-safe. Concurrent access from multiple goroutines
+// requires external synchronization.
 type DraftProvider struct {
-	api *tgapi.API
+	api       *tgapi.API
+	drafts    map[uint64]*Draft
+	generator draftIdGenerator
 
-	chatID          int
+	// Internal defaults — not exposed directly to users.
+	chatID          int64
 	messageThreadID int
 	parseMode       tgapi.ParseMode
 	entities        []tgapi.MessageEntity
-
-	drafts    map[uint64]*Draft
-	generator draftIdGenerator
 }
-type Draft struct {
-	api *tgapi.API
 
-	chatID          int
+// NewRandomDraftProvider creates a new DraftProvider using random draft IDs.
+//
+// The provider will use cryptographically secure random numbers for draft IDs.
+// All drafts created via this provider will have unpredictable, unique IDs.
+func NewRandomDraftProvider(api *tgapi.API) *DraftProvider {
+	return &DraftProvider{
+		api: api, generator: &RandomDraftIdGenerator{},
+		drafts: make(map[uint64]*Draft),
+	}
+}
+
+// NewLinearDraftProvider creates a new DraftProvider using linear (incrementing) draft IDs.
+//
+// startValue is the initial value for the counter. Use 0 for fresh start, or a known
+// value to resume from persisted state.
+//
+// This is useful when you need to store draft IDs externally (e.g., in a database)
+// and want to reconstruct drafts after restart.
+func NewLinearDraftProvider(api *tgapi.API, startValue uint64) *DraftProvider {
+	g := &LinearDraftIdGenerator{}
+	g.lastId.Store(startValue)
+	return &DraftProvider{
+		api:       api,
+		generator: g,
+		drafts:    make(map[uint64]*Draft),
+	}
+}
+
+// SetChat sets the target chat and optional message thread for all drafts created
+// by this provider. Must be called before NewDraft().
+//
+// If not set, NewDraft() will create drafts with zero chatID, which will cause
+// SendMessageDraft to fail. Use this method to avoid runtime errors.
+func (p *DraftProvider) SetChat(chatID int64, messageThreadID int) *DraftProvider {
+	p.chatID = chatID
+	p.messageThreadID = messageThreadID
+	return p
+}
+
+// SetParseMode sets the default parse mode for all new drafts.
+// Overrides the parse mode passed to NewDraft() only if not specified there.
+func (p *DraftProvider) SetParseMode(mode tgapi.ParseMode) *DraftProvider {
+	p.parseMode = mode
+	return p
+}
+
+// SetEntities sets the default message entities (e.g., bold, links, mentions)
+// to be copied into every new draft.
+//
+// Entities are shallow-copied — if you mutate the slice later, it will affect
+// future drafts. For safety, pass a copy if needed.
+func (p *DraftProvider) SetEntities(entities []tgapi.MessageEntity) *DraftProvider {
+	p.entities = entities
+	return p
+}
+
+// GetDraft retrieves a draft by its ID.
+//
+// Returns the draft and true if found, or nil and false if not found.
+func (p *DraftProvider) GetDraft(id uint64) (*Draft, bool) {
+	draft, ok := p.drafts[id]
+	return draft, ok
+}
+
+// FlushAll sends all pending drafts as final messages and clears them.
+//
+// If any draft fails to send, FlushAll returns the error immediately and
+// leaves other drafts unflushed. This allows for retry logic or logging.
+//
+// After successful flush, each draft is removed from the provider and cleared.
+func (p *DraftProvider) FlushAll() error {
+	var lastErr error
+	for _, draft := range p.drafts {
+		if err := draft.Flush(); err != nil {
+			lastErr = err
+			break // Stop on first error to avoid partial state
+		}
+	}
+	return lastErr
+}
+
+// Draft represents a single message draft that can be edited and flushed.
+//
+// Drafts are safe to use from a single goroutine. Multiple goroutines must
+// synchronize access manually.
+//
+// Drafts are automatically removed from the provider's map when Flush() succeeds.
+type Draft struct {
+	api      *tgapi.API
+	provider *DraftProvider
+
+	chatID          int64
 	messageThreadID int
 	parseMode       tgapi.ParseMode
 	entities        []tgapi.MessageEntity
@@ -52,41 +179,98 @@ type Draft struct {
 	Message string
 }
 
-func NewRandomDraftProvider(api *tgapi.API) *DraftProvider {
+// NewDraft creates a new draft with the provided parse mode.
-	return &DraftProvider{
+//
-		api: api, generator: &RandomDraftIdGenerator{},
+// The draft inherits the provider's chatID, messageThreadID, and entities.
-		drafts: make(map[uint64]*Draft),
+// If parseMode is zero, the provider's default parseMode is used.
+//
+// Panics if chatID is zero — call SetChat() on the provider first.
+func (p *DraftProvider) NewDraft(parseMode tgapi.ParseMode) *Draft {
+	if p.chatID == 0 {
+		panic("laniakea: DraftProvider.SetChat() must be called before NewDraft()")
 	}
-}
+
-func NewLinearDraftProvider(api *tgapi.API, startValue uint64) *DraftProvider {
+	id := p.generator.Next()
-	return &DraftProvider{
+	draft := &Draft{
-		api:       api,
+		api:             p.api,
-		generator: &LinearDraftIdGenerator{lastId: startValue},
+		provider:        p,
-		drafts:    make(map[uint64]*Draft),
+		chatID:          p.chatID,
+		messageThreadID: p.messageThreadID,
+		parseMode:       parseMode,
+		entities:        p.entities, // Shallow copy — caller must ensure immutability
+		ID:              id,
+		Message:         "",
 	}
-}
+	p.drafts[id] = draft
-func (d *DraftProvider) NewDraft() *Draft {
-	id := d.generator.Next()
-	draft := &Draft{d.api, d.chatID, d.messageThreadID, d.parseMode, d.entities, id, ""}
-	d.drafts[id] = draft
 	return draft
 }
 
-func (d *Draft) Push(newText string) error {
+// SetChat overrides the draft's target chat and message thread.
-	d.Message += newText
+//
-	params := tgapi.SendMessageDraftP{
+// This is useful for sending a draft to a different chat than the provider's default.
-		ChatID:    d.chatID,
+func (d *Draft) SetChat(chatID int64, messageThreadID int) *Draft {
-		DraftID:   d.ID,
+	d.chatID = chatID
-		Text:      d.Message,
+	d.messageThreadID = messageThreadID
-		ParseMode: d.parseMode,
+	return d
-		Entities:  d.entities,
-	}
-	if d.messageThreadID > 0 {
-		params.MessageThreadID = d.messageThreadID
-	}
-	_, err := d.api.SendMessageDraft(params)
-	return err
 }
+
+// SetEntities replaces the draft's message entities.
+//
+// Entities are stored by reference. If you plan to mutate the slice later,
+// pass a copy: `SetEntities(append([]tgapi.MessageEntity{}, myEntities...))`
+func (d *Draft) SetEntities(entities []tgapi.MessageEntity) *Draft {
+	d.entities = entities
+	return d
+}
+
+// Push appends text to the draft and attempts to update the server-side draft.
+//
+// Returns an error if the Telegram API rejects the update (e.g., due to network issues).
+// The draft's Message field is always updated, even if the API call fails.
+//
+// Use this method to build the message incrementally.
+func (d *Draft) Push(text string) error {
+	return d.push(text)
+}
+
+// GetMessage returns the current content of the draft.
+//
+// Useful for inspection, logging, or validation before flushing.
+func (d *Draft) GetMessage() string {
+	return d.Message
+}
+
+// Clear resets the draft's message content to empty string.
+//
+// Does not affect server-side draft — use Flush() for that.
+func (d *Draft) Clear() {
+	d.Message = ""
+}
+
+// Delete removes the draft from its provider and clears its content.
+//
+// This is an internal method used by Flush(). You may call it manually if you
+// want to cancel a draft without sending it.
+func (d *Draft) Delete() {
+	if d.provider != nil {
+		delete(d.provider.drafts, d.ID)
+	}
+	d.Clear()
+}
+
+// Flush sends the draft as a final message and clears it locally.
+//
+// If successful:
+//   - The message is sent to Telegram.
+//   - The draft's content is cleared.
+//   - The draft is removed from the provider's map.
+//
+// If an error occurs:
+//   - The message is NOT sent.
+//   - The draft remains in the provider and retains its content.
+//   - You can call Flush() again to retry.
+//
+// If the draft is empty, Flush() returns nil without calling the API.
 func (d *Draft) Flush() error {
 	if d.Message == "" {
 		return nil
@@ -101,6 +285,27 @@ func (d *Draft) Flush() error {
 	if d.messageThreadID > 0 {
 		params.MessageThreadID = d.messageThreadID
 	}
+
 	_, err := d.api.SendMessage(params)
+	if err == nil {
+		d.Delete()
+	}
+	return err
+}
+
+// push is the internal helper for Push(). It updates the server draft via SendMessageDraft.
+func (d *Draft) push(text string) error {
+	d.Message += text
+	params := tgapi.SendMessageDraftP{
+		ChatID:    d.chatID,
+		DraftID:   d.ID,
+		Text:      d.Message,
+		ParseMode: d.parseMode,
+		Entities:  d.entities,
+	}
+	if d.messageThreadID > 0 {
+		params.MessageThreadID = d.messageThreadID
+	}
+	_, err := d.api.SendMessageDraft(params)
 	return err
 }

examples/basic/.env

@@ -0,0 +1,7 @@
+TG_TOKEN=
+PREFIXES=/;!
+DEBUG=true
+USE_REQ_LOG=true
+WRITE_TO_FILE=false
+USE_TEST_SERVER=true
+API_URL=http://127.0.0.1:8081

examples/basic/example.go

@@ -0,0 +1,28 @@
+package main
+
+import (
+	"log"
+
+	"git.nix13.pw/scuroneko/laniakea"
+)
+
+func pong(ctx *laniakea.MsgContext, db *laniakea.NoDB) {
+	ctx.Answer(ctx.Msg.Text)
+}
+
+func main() {
+	bot := laniakea.NewBot[laniakea.NoDB](laniakea.LoadOptsFromEnv())
+	defer bot.Close()
+
+	p := laniakea.NewPlugin[laniakea.NoDB]("ping")
+	p.NewCommand(pong, "ping")
+
+	bot = bot.ErrorTemplate(
+		"Error\n\n%s",
+	).AddPlugins(p)
+
+	if err := bot.AutoGenerateCommands(); err != nil {
+		log.Println(err)
+	}
+	bot.Run()
+}

examples/basic/go.mod

@@ -0,0 +1,16 @@
+module example/basic
+
+go 1.26.1
+
+require git.nix13.pw/scuroneko/laniakea v1.0.0-beta.11
+
+require (
+	git.nix13.pw/scuroneko/extypes v1.2.1 // indirect
+	git.nix13.pw/scuroneko/slog v1.0.2 // indirect
+	github.com/alitto/pond/v2 v2.6.2 // indirect
+	github.com/fatih/color v1.18.0 // indirect
+	github.com/mattn/go-colorable v0.1.14 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/time v0.14.0 // indirect
+)

examples/basic/go.sum

@@ -0,0 +1,19 @@
+git.nix13.pw/scuroneko/extypes v1.2.1 h1:IYrOjnWKL2EAuJYtYNa+luB1vBe6paE8VY/YD+5/RpQ=
+git.nix13.pw/scuroneko/extypes v1.2.1/go.mod h1:uZVs8Yo3RrYAG9dMad6qR6lsYY67t+459D9c65QAYAw=
+git.nix13.pw/scuroneko/laniakea v1.0.0-beta.11 h1:bf+5B8vUL/MEmbbX6pA0Wjf0N1eIZH5/WxoSApMcXD4=
+git.nix13.pw/scuroneko/laniakea v1.0.0-beta.11/go.mod h1:DZgCqOazRzoa+f/GSNuKnTB2wIZ1eJD3cGf34Qya31U=
+git.nix13.pw/scuroneko/slog v1.0.2 h1:vZyUROygxC2d5FJHUQM/30xFEHY1JT/aweDZXA4rm2g=
+git.nix13.pw/scuroneko/slog v1.0.2/go.mod h1:3Qm2wzkR5KjwOponMfG7TcGSDjmYaFqRAmLvSPTuWJI=
+github.com/alitto/pond/v2 v2.6.2 h1:Sphe40g0ILeM1pA2c2K+Th0DGU+pt0A/Kprr+WB24Pw=
+github.com/alitto/pond/v2 v2.6.2/go.mod h1:xkjYEgQ05RSpWdfSd1nM3OVv7TBhLdy7rMp3+2Nq+yE=
+github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
+github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU=
+github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
+github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/time v0.14.0 h1:MRx4UaLrDotUKUdCIqzPC48t1Y9hANFKIRpNx+Te8PI=
+golang.org/x/time v0.14.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4=

go.mod

@@ -5,13 +5,13 @@ go 1.26
 require (
 	git.nix13.pw/scuroneko/extypes v1.2.1
 	git.nix13.pw/scuroneko/slog v1.0.2
-	github.com/alitto/pond/v2 v2.6.2
+	github.com/alitto/pond/v2 v2.7.0
-	golang.org/x/time v0.14.0
+	golang.org/x/time v0.15.0
 )
 
 require (
 	github.com/fatih/color v1.18.0 // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
-	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
 )

go.sum

@@ -2,8 +2,8 @@ git.nix13.pw/scuroneko/extypes v1.2.1 h1:IYrOjnWKL2EAuJYtYNa+luB1vBe6paE8VY/YD+5
 git.nix13.pw/scuroneko/extypes v1.2.1/go.mod h1:uZVs8Yo3RrYAG9dMad6qR6lsYY67t+459D9c65QAYAw=
 git.nix13.pw/scuroneko/slog v1.0.2 h1:vZyUROygxC2d5FJHUQM/30xFEHY1JT/aweDZXA4rm2g=
 git.nix13.pw/scuroneko/slog v1.0.2/go.mod h1:3Qm2wzkR5KjwOponMfG7TcGSDjmYaFqRAmLvSPTuWJI=
-github.com/alitto/pond/v2 v2.6.2 h1:Sphe40g0ILeM1pA2c2K+Th0DGU+pt0A/Kprr+WB24Pw=
+github.com/alitto/pond/v2 v2.7.0 h1:c76L+yN916m/DRXjGCeUBHHu92uWnh/g1bwVk4zyyXg=
-github.com/alitto/pond/v2 v2.6.2/go.mod h1:xkjYEgQ05RSpWdfSd1nM3OVv7TBhLdy7rMp3+2Nq+yE=
+github.com/alitto/pond/v2 v2.7.0/go.mod h1:xkjYEgQ05RSpWdfSd1nM3OVv7TBhLdy7rMp3+2Nq+yE=
 github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
 github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU=
 github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
@@ -11,7 +11,7 @@ github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stg
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
-golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/time v0.14.0 h1:MRx4UaLrDotUKUdCIqzPC48t1Y9hANFKIRpNx+Te8PI=
+golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
-golang.org/x/time v0.14.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4=
+golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=

handler.go

@@ -49,34 +49,34 @@ func (bot *Bot[T]) handleMessage(update *tgapi.Update, ctx *MsgContext) {
 	ctx.From = update.Message.From
 	ctx.Msg = update.Message
 
+	// Убираем префикс
 	text = strings.TrimSpace(text[len(prefix):])
 
+	// Извлекаем команду как первое слово
+	spaceIndex := strings.Index(text, " ")
+	var cmd string
+	var args string
+
+	if spaceIndex == -1 {
+		cmd = text
+		args = ""
+	} else {
+		cmd = text[:spaceIndex]
+		args = strings.TrimSpace(text[spaceIndex:])
+	}
+
+	if strings.Contains(cmd, "@") {
+		botUsername := bot.username
+		if botUsername != "" && strings.HasSuffix(cmd, "@"+botUsername) {
+			cmd = cmd[:len(cmd)-len("@"+botUsername)] // убираем @botname
+		}
+	}
+
+	// Ищем команду по точному совпадению
 	for _, plugin := range bot.plugins {
-		for cmd := range plugin.commands {
+		if _, exists := plugin.commands[cmd]; exists {
-			if !strings.HasPrefix(text, cmd) {
+			ctx.Text = args
-				continue
+			ctx.Args = strings.Fields(args) // Убирает лишние пробелы
-			}
-			requestParts := strings.Split(text, " ")
-			cmdParts := strings.Split(cmd, " ")
-			isValid := true
-			for i, part := range cmdParts {
-				if part != requestParts[i] {
-					isValid = false
-					break
-				}
-			}
-
-			if !isValid {
-				continue
-			}
-
-			ctx.Text = strings.TrimSpace(text[len(cmd):])
-			if ctx.Text == "" {
-				ctx.Args = []string{}
-			} else {
-				ctx.Args = strings.Split(ctx.Text, " ")
-			}
-
 			if !plugin.executeMiddlewares(ctx, bot.dbContext) {
 				return
 			}

keyboard.go

@@ -1,3 +1,13 @@
+// Package laniakea provides a fluent builder system for constructing Telegram
+// inline keyboards with callback data and custom styling.
+//
+// This package supports:
+//   - Button builders with style (danger/success/primary), icons, URLs, and callbacks
+//   - Line-based keyboard layout with configurable max row size
+//   - Structured, JSON-serialized callback data for bot command routing
+//
+// Keyboard construction is stateful and builder-style: methods return the receiver
+// to enable chaining. Call Get() to finalize and retrieve the tgapi.ReplyMarkup.
 package laniakea
 
 import (
@@ -8,12 +18,26 @@ import (
 	"git.nix13.pw/scuroneko/laniakea/tgapi"
 )
 
+// ButtonStyleDanger, ButtonStyleSuccess, ButtonStylePrimary are predefined
+// Telegram keyboard button styles for visual feedback.
+//
+// These values map directly to Telegram Bot API's InlineKeyboardButton style field.
 const (
 	ButtonStyleDanger  tgapi.KeyboardButtonStyle = "danger"
 	ButtonStyleSuccess tgapi.KeyboardButtonStyle = "success"
 	ButtonStylePrimary tgapi.KeyboardButtonStyle = "primary"
 )
 
+// InlineKbButtonBuilder is a fluent builder for creating a single inline keyboard button.
+//
+// Use NewInlineKbButton() to start, then chain methods to configure:
+//   - 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
+//
+// Call build() to produce the final tgapi.InlineKeyboardButton.
+// Builder methods are immutable — each returns a copy.
 type InlineKbButtonBuilder struct {
 	text              string
 	iconCustomEmojiID string
@@ -22,26 +46,48 @@ type InlineKbButtonBuilder struct {
 	callbackData      string
 }
 
+// NewInlineKbButton creates a new button builder with the given display text.
+// The button will have no URL, no style, and no callback data by default.
 func NewInlineKbButton(text string) InlineKbButtonBuilder {
 	return InlineKbButtonBuilder{text: text}
 }
+
+// SetIconCustomEmojiId sets a custom emoji ID to display as the button's icon.
+// This is a Telegram Bot API feature for custom emoji icons.
 func (b InlineKbButtonBuilder) SetIconCustomEmojiId(id string) InlineKbButtonBuilder {
 	b.iconCustomEmojiID = id
 	return b
 }
+
+// SetStyle sets the visual style of the button.
+// Valid values: ButtonStyleDanger, ButtonStyleSuccess, ButtonStylePrimary.
+// If not set, the button uses the default style.
 func (b InlineKbButtonBuilder) SetStyle(style tgapi.KeyboardButtonStyle) InlineKbButtonBuilder {
 	b.style = style
 	return b
 }
+
+// SetUrl sets a URL that will be opened when the button is pressed.
+// If both URL and CallbackData are set, Telegram will prioritize URL.
 func (b InlineKbButtonBuilder) SetUrl(url string) InlineKbButtonBuilder {
 	b.url = url
 	return b
 }
+
+// SetCallbackData 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 {
 	b.callbackData = NewCallbackData(cmd, args...).ToJson()
 	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 {
 	return tgapi.InlineKeyboardButton{
 		Text:              b.text,
@@ -52,12 +98,22 @@ func (b InlineKbButtonBuilder) build() tgapi.InlineKeyboardButton {
 	}
 }
 
+// InlineKeyboard is a stateful builder for constructing Telegram inline keyboard layouts.
+//
+// Buttons are added row-by-row. When a row reaches maxRow, it is automatically flushed.
+// Call AddLine() to manually end a row, or Get() to finalize and retrieve the markup.
+//
+// The keyboard is not thread-safe. Build it in a single goroutine.
 type InlineKeyboard struct {
-	CurrentLine extypes.Slice[tgapi.InlineKeyboardButton]
+	CurrentLine extypes.Slice[tgapi.InlineKeyboardButton] // Current row being built
-	Lines       [][]tgapi.InlineKeyboardButton
+	Lines       [][]tgapi.InlineKeyboardButton            // Completed rows
-	maxRow      int
+	maxRow      int                                       // Max buttons per row (e.g., 3 or 4)
 }
 
+// NewInlineKeyboard creates a new keyboard builder with the specified maximum
+// number of buttons per row.
+//
+// Example: NewInlineKeyboard(3) creates a keyboard with at most 3 buttons per line.
 func NewInlineKeyboard(maxRow int) *InlineKeyboard {
 	return &InlineKeyboard{
 		CurrentLine: make(extypes.Slice[tgapi.InlineKeyboardButton], 0),
@@ -66,6 +122,8 @@ func NewInlineKeyboard(maxRow int) *InlineKeyboard {
 	}
 }
 
+// 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 {
 	if in.CurrentLine.Len() == in.maxRow {
 		in.AddLine()
@@ -74,27 +132,45 @@ func (in *InlineKeyboard) append(button tgapi.InlineKeyboardButton) *InlineKeybo
 	return in
 }
 
+// AddUrlButton adds a button that opens a URL when pressed.
+// No callback data is attached.
 func (in *InlineKeyboard) AddUrlButton(text, url string) *InlineKeyboard {
 	return in.append(tgapi.InlineKeyboardButton{Text: text, URL: url})
 }
+
+// AddUrlButtonStyle adds a button with a visual style that opens a URL.
+// Style must be one of: ButtonStyleDanger, ButtonStyleSuccess, ButtonStylePrimary.
 func (in *InlineKeyboard) AddUrlButtonStyle(text string, style tgapi.KeyboardButtonStyle, url string) *InlineKeyboard {
 	return in.append(tgapi.InlineKeyboardButton{Text: text, Style: style, URL: url})
 }
+
+// AddCallbackButton adds a button that sends a structured callback payload to the bot.
+// The command and args are serialized as JSON using NewCallbackData.
 func (in *InlineKeyboard) AddCallbackButton(text string, cmd string, args ...any) *InlineKeyboard {
 	return in.append(tgapi.InlineKeyboardButton{
-		Text: text, CallbackData: NewCallbackData(cmd, args...).ToJson(),
+		Text:         text,
-	})
-}
-func (in *InlineKeyboard) AddCallbackButtonStyle(text string, style tgapi.KeyboardButtonStyle, cmd string, args ...any) *InlineKeyboard {
-	return in.append(tgapi.InlineKeyboardButton{
-		Text: text, Style: style,
 		CallbackData: NewCallbackData(cmd, args...).ToJson(),
 	})
 }
+
+// AddCallbackButtonStyle adds a styled callback button.
+// Style affects visual appearance; callback data is sent to bot on press.
+func (in *InlineKeyboard) AddCallbackButtonStyle(text string, style tgapi.KeyboardButtonStyle, cmd string, args ...any) *InlineKeyboard {
+	return in.append(tgapi.InlineKeyboardButton{
+		Text:         text,
+		Style:        style,
+		CallbackData: NewCallbackData(cmd, args...).ToJson(),
+	})
+}
+
+// AddButton adds a button pre-configured via InlineKbButtonBuilder.
+// This is the most flexible way to create buttons with custom emoji, style, URL, and callback.
 func (in *InlineKeyboard) AddButton(b InlineKbButtonBuilder) *InlineKeyboard {
 	return in.append(b.build())
 }
 
+// AddLine manually ends the current row and starts a new one.
+// If the current row is empty, nothing happens.
 func (in *InlineKeyboard) AddLine() *InlineKeyboard {
 	if in.CurrentLine.Len() == 0 {
 		return in
@@ -103,6 +179,11 @@ func (in *InlineKeyboard) AddLine() *InlineKeyboard {
 	in.CurrentLine = make(extypes.Slice[tgapi.InlineKeyboardButton], 0)
 	return in
 }
+
+// Get finalizes the keyboard and returns a tgapi.ReplyMarkup.
+// Automatically flushes the current line if not empty.
+//
+// Returns a pointer to a ReplyMarkup suitable for use with tgapi.SendMessage.
 func (in *InlineKeyboard) Get() *tgapi.ReplyMarkup {
 	if in.CurrentLine.Len() > 0 {
 		in.Lines = append(in.Lines, in.CurrentLine)
@@ -110,11 +191,26 @@ func (in *InlineKeyboard) Get() *tgapi.ReplyMarkup {
 	return &tgapi.ReplyMarkup{InlineKeyboard: in.Lines}
 }
 
+// CallbackData represents the structured payload sent when an inline button
+// with callback data is pressed.
+//
+// This structure is serialized to JSON and sent to the bot as a string.
+// The bot should parse this back to determine the command and arguments.
+//
+// Example:
+//
+//	{"cmd":"delete_user","args":["123","confirm"]}
 type CallbackData struct {
-	Command string   `json:"cmd"`
+	Command string   `json:"cmd"`  // The command name to route to
-	Args    []string `json:"args"`
+	Args    []string `json:"args"` // Arguments passed as strings
 }
 
+// NewCallbackData creates a new CallbackData instance with the given command and args.
+//
+// All args are converted to strings using fmt.Sprint. This is safe for primitives
+// (int, string, bool, float64) but may not serialize complex structs meaningfully.
+//
+// Use this to build callback payloads for bot command routing.
 func NewCallbackData(command string, args ...any) *CallbackData {
 	stringArgs := make([]string, len(args))
 	for i, arg := range args {
@@ -125,9 +221,18 @@ func NewCallbackData(command string, args ...any) *CallbackData {
 		Args:    stringArgs,
 	}
 }
+
+// ToJson serializes the CallbackData to a JSON string.
+//
+// If serialization fails (e.g., due to unmarshalable fields), returns a fallback
+// JSON object: {"cmd":""} to prevent breaking Telegram's API.
+//
+// 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)
 	if err != nil {
+		// Fallback: return minimal valid JSON to avoid Telegram API rejection
 		return `{"cmd":""}`
 	}
 	return string(data)

l10n.go

@@ -1,26 +1,86 @@
+// Package laniakea provides a simple, key-based localization system for
+// multi-language text translation.
+//
+// The system supports:
+//   - Multiple language entries per key (e.g., "ru", "en", "es")
+//   - Fallback language for missing translations
+//   - Key-as-fallback behavior: if a key or language is not found, returns the key itself
+//
+// This is designed for lightweight, static localization in bots or services
+// where dynamic translation services are unnecessary.
 package laniakea
 
-// DictEntry {key:{ru:123,en:123}}
+// DictEntry represents a single localized entry with language-to-text mappings.
+// Example: {"ru": "Привет", "en": "Hello"}
 type DictEntry map[string]string
+
+// L10n is a localization manager that maps keys to language-specific strings.
 type L10n struct {
-	entries      map[string]DictEntry
+	entries      map[string]DictEntry // Map of translation keys to language dictionaries
-	fallbackLang string
+	fallbackLang string               // Language code to use when requested language is missing
 }
 
+// NewL10n creates a new L10n instance with the specified fallback language.
+// The fallback language is used when a requested language is not available
+// for a given key.
+//
+// Example: NewL10n("en") will return "Hello" for key "greeting" if "ru" is requested
+// but no "ru" entry exists.
 func NewL10n(fallbackLanguage string) *L10n {
-	return &L10n{make(map[string]DictEntry), fallbackLanguage}
+	return &L10n{
+		entries:      make(map[string]DictEntry),
+		fallbackLang: fallbackLanguage,
+	}
 }
+
+// AddDictEntry adds a new translation entry for the given key.
+// The value must be a DictEntry mapping language codes (e.g., "en", "ru") to their translated strings.
+//
+// If a key already exists, it is overwritten.
+//
+// Returns the L10n instance for method chaining.
 func (l *L10n) AddDictEntry(key string, value DictEntry) *L10n {
 	l.entries[key] = value
 	return l
 }
+
+// GetFallbackLanguage returns the currently configured fallback language code.
 func (l *L10n) GetFallbackLanguage() string {
 	return l.fallbackLang
 }
+
+// Translate retrieves the translation for the given key and language.
+//
+// Behavior:
+//   - If the key exists and the language has a translation → returns the translation
+//   - If the key exists but the language is missing → returns the fallback language's value
+//   - If the key does not exist → returns the key string itself (as fallback)
+//
+// Example:
+//
+//	l.AddDictEntry("greeting", DictEntry{"en": "Hello", "ru": "Привет"})
+//	l.Translate("en", "greeting") → "Hello"
+//	l.Translate("es", "greeting") → "Hello" (fallback to "en")
+//	l.Translate("en", "unknown") → "unknown" (key not found)
+//
+// This behavior ensures that missing translations do not break UI or logs —
+// instead, the original key is displayed, making it easy to identify gaps.
 func (l *L10n) Translate(lang, key string) string {
-	s, ok := l.entries[key]
+	entries, exists := l.entries[key]
-	if !ok {
+	if !exists {
-		return key
+		return key // Return key as fallback when translation is missing
 	}
-	return s[lang]
+
+	// Try requested language
+	if translation, ok := entries[lang]; ok {
+		return translation
+	}
+
+	// Fall back to configured fallback language
+	if fallback, ok := entries[l.fallbackLang]; ok {
+		return fallback
+	}
+
+	// If fallback language is also missing, return the key
+	return key
 }

msg_context.go

@@ -1,16 +1,37 @@
+// Package laniakea provides a high-level context-based API for handling Telegram
+// bot interactions, including message responses, callback queries, inline keyboards,
+// localization, and message drafting. It wraps tgapi and adds convenience methods
+// with built-in rate limiting, error handling, and i18n support.
+//
+// The core type is MsgContext, which encapsulates the state of a Telegram update
+// and provides methods to respond, edit, delete, and translate messages.
+//
+// # Markdown Safety Warning
+//
+// All methods that accept MarkdownV2 formatting (e.g., AnswerMarkdown, EditCallbackfMarkdown)
+// require that user-provided text be escaped using laniakea.EscapeMarkdownV2().
+// Failure to escape user input may result in Telegram API errors, malformed messages,
+// or security issues.
+//
+// Example:
+//
+//	text := laniakea.EscapeMarkdownV2(userInput)
+//	ctx.AnswerMarkdown("You said: " + text)
 package laniakea
 
 import (
+	"context"
 	"fmt"
 
 	"git.nix13.pw/scuroneko/laniakea/tgapi"
-	"git.nix13.pw/scuroneko/laniakea/utils"
 	"git.nix13.pw/scuroneko/slog"
 )
 
+// MsgContext holds the context for handling a Telegram message or callback query.
+// It provides methods to respond, edit, delete, and translate messages, as well as
+// manage inline keyboards and message drafts.
 type MsgContext struct {
-	Api *tgapi.API
+	Api             *tgapi.API
-
 	Msg             *tgapi.Message
 	Update          tgapi.Update
 	From            *tgapi.User
@@ -27,19 +48,23 @@ type MsgContext struct {
 	draftProvider *DraftProvider
 }
 
+// AnswerMessage represents a message sent or edited via MsgContext.
+// It holds metadata to allow further editing or deletion.
 type AnswerMessage struct {
 	MessageID int
 	Text      string
 	IsMedia   bool
-	ctx       *MsgContext
+	ctx       *MsgContext // internal back-reference
 }
 
-func (ctx *MsgContext) edit(messageId int, text string, keyboard *InlineKeyboard) *AnswerMessage {
+// edit is an internal helper to edit a message's text with optional keyboard and parse mode.
+// Used by Edit, EditMarkdown, EditCallback, etc.
+func (ctx *MsgContext) edit(messageId int, text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
 	params := tgapi.EditMessageTextP{
 		MessageID: messageId,
 		ChatID:    ctx.Msg.Chat.ID,
 		Text:      text,
-		ParseMode: tgapi.ParseMD,
+		ParseMode: parseMode,
 	}
 	if keyboard != nil {
 		params.ReplyMarkup = keyboard.Get()
@@ -53,27 +78,67 @@ func (ctx *MsgContext) edit(messageId int, text string, keyboard *InlineKeyboard
 		MessageID: msg.MessageID, ctx: ctx, Text: text, IsMedia: false,
 	}
 }
+
+// Edit replaces the text of the message without changing the keyboard or parse mode.
+// Uses ParseNone (plain text).
 func (m *AnswerMessage) Edit(text string) *AnswerMessage {
-	return m.ctx.edit(m.MessageID, text, nil)
+	return m.ctx.edit(m.MessageID, text, nil, tgapi.ParseNone)
 }
-func (ctx *MsgContext) EditCallback(text string, keyboard *InlineKeyboard) *AnswerMessage {
+
+// EditMarkdown replaces the text of the message using MarkdownV2 formatting.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+// Unescaped input may cause Telegram API errors or broken formatting.
+func (m *AnswerMessage) EditMarkdown(text string) *AnswerMessage {
+	return m.ctx.edit(m.MessageID, text, nil, tgapi.ParseMDV2)
+}
+
+// editCallback is an internal helper to edit the message associated with a callback query.
+// Returns nil if CallbackMsgId is 0 (not a callback context).
+func (ctx *MsgContext) editCallback(text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
 	if ctx.CallbackMsgId == 0 {
 		ctx.botLogger.Errorln("Can't edit non-callback update message")
 		return nil
 	}
-
+	return ctx.edit(ctx.CallbackMsgId, text, keyboard, parseMode)
-	return ctx.edit(ctx.CallbackMsgId, text, keyboard)
 }
+
+// EditCallback edits the callback message using plain text (ParseNone).
+func (ctx *MsgContext) EditCallback(text string, keyboard *InlineKeyboard) *AnswerMessage {
+	return ctx.editCallback(text, keyboard, tgapi.ParseNone)
+}
+
+// EditCallbackMarkdown edits the callback message using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) EditCallbackMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage {
+	return ctx.editCallback(text, keyboard, tgapi.ParseMDV2)
+}
+
+// EditCallbackf formats a string using fmt.Sprintf and edits the callback message with plain text.
 func (ctx *MsgContext) EditCallbackf(format string, keyboard *InlineKeyboard, args ...any) *AnswerMessage {
-	return ctx.EditCallback(fmt.Sprintf(format, args...), keyboard)
+	return ctx.editCallback(fmt.Sprintf(format, args...), keyboard, tgapi.ParseNone)
 }
 
-func (ctx *MsgContext) editPhotoText(messageId int, text string, kb *InlineKeyboard) *AnswerMessage {
+// EditCallbackfMarkdown formats a string using fmt.Sprintf and edits the callback message with MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) EditCallbackfMarkdown(format string, keyboard *InlineKeyboard, args ...any) *AnswerMessage {
+	return ctx.editCallback(fmt.Sprintf(format, args...), keyboard, tgapi.ParseMDV2)
+}
+
+// editPhotoText edits the caption of a photo/video message.
+// Returns nil if messageId is 0.
+func (ctx *MsgContext) editPhotoText(messageId int, text string, kb *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
+	if messageId == 0 {
+		ctx.botLogger.Errorln("Can't edit caption message, message ID zero")
+		return nil
+	}
 	params := tgapi.EditMessageCaptionP{
 		ChatID:    ctx.Msg.Chat.ID,
 		MessageID: messageId,
 		Caption:   text,
-		ParseMode: tgapi.ParseMD,
+		ParseMode: parseMode,
 	}
 	if kb != nil {
 		params.ReplyMarkup = kb.Get()
@@ -87,22 +152,38 @@ func (ctx *MsgContext) editPhotoText(messageId int, text string, kb *InlineKeybo
 		MessageID: msg.MessageID, ctx: ctx, Text: text, IsMedia: true,
 	}
 }
+
+// EditCaption edits the caption of a media message using plain text.
 func (m *AnswerMessage) EditCaption(text string) *AnswerMessage {
-	if m.MessageID == 0 {
+	return m.ctx.editPhotoText(m.MessageID, text, nil, tgapi.ParseNone)
-		m.ctx.botLogger.Errorln("Can't edit caption message, message id is zero")
-		return m
-	}
-	return m.ctx.editPhotoText(m.MessageID, text, nil)
-}
-func (m *AnswerMessage) EditCaptionKeyboard(text string, kb *InlineKeyboard) *AnswerMessage {
-	return m.ctx.editPhotoText(m.MessageID, text, kb)
 }
 
-func (ctx *MsgContext) answer(text string, keyboard *InlineKeyboard) *AnswerMessage {
+// EditCaptionMarkdown edits the caption of a media message using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (m *AnswerMessage) EditCaptionMarkdown(text string) *AnswerMessage {
+	return m.ctx.editPhotoText(m.MessageID, text, nil, tgapi.ParseMDV2)
+}
+
+// EditCaptionKeyboard edits the caption of a media message with a new inline keyboard (plain text).
+func (m *AnswerMessage) EditCaptionKeyboard(text string, kb *InlineKeyboard) *AnswerMessage {
+	return m.ctx.editPhotoText(m.MessageID, text, kb, tgapi.ParseNone)
+}
+
+// EditCaptionKeyboardMarkdown edits the caption of a media message with a new inline keyboard using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (m *AnswerMessage) EditCaptionKeyboardMarkdown(text string, kb *InlineKeyboard) *AnswerMessage {
+	return m.ctx.editPhotoText(m.MessageID, text, kb, tgapi.ParseMDV2)
+}
+
+// answer sends a new message with optional keyboard and parse mode.
+// Uses API limiter to respect Telegram rate limits per chat.
+func (ctx *MsgContext) answer(text string, keyboard *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
 	params := tgapi.SendMessageP{
 		ChatID:    ctx.Msg.Chat.ID,
 		Text:      text,
-		ParseMode: tgapi.ParseMD,
+		ParseMode: parseMode,
 	}
 	if keyboard != nil {
 		params.ReplyMarkup = keyboard.Get()
@@ -114,6 +195,11 @@ func (ctx *MsgContext) answer(text string, keyboard *InlineKeyboard) *AnswerMess
 		params.DirectMessagesTopicID = ctx.Msg.DirectMessageTopic.TopicID
 	}
 
+	cont := context.Background()
+	if err := ctx.Api.Limiter.Wait(cont, ctx.Msg.Chat.ID); err != nil {
+		ctx.botLogger.Errorln(err)
+		return nil
+	}
 	msg, err := ctx.Api.SendMessage(params)
 	if err != nil {
 		ctx.botLogger.Errorln(err)
@@ -123,21 +209,49 @@ func (ctx *MsgContext) answer(text string, keyboard *InlineKeyboard) *AnswerMess
 		MessageID: msg.MessageID, ctx: ctx, IsMedia: false, Text: text,
 	}
 }
+
+// Answer sends a plain text message (ParseNone).
 func (ctx *MsgContext) Answer(text string) *AnswerMessage {
-	return ctx.answer(text, nil)
+	return ctx.answer(text, nil, tgapi.ParseNone)
-}
-func (ctx *MsgContext) Answerf(template string, args ...any) *AnswerMessage {
-	return ctx.answer(fmt.Sprintf(template, args...), nil)
-}
-func (ctx *MsgContext) Keyboard(text string, kb *InlineKeyboard) *AnswerMessage {
-	return ctx.answer(text, kb)
 }
 
-func (ctx *MsgContext) answerPhoto(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
+// AnswerMarkdown sends a message using MarkdownV2 formatting.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) AnswerMarkdown(text string) *AnswerMessage {
+	return ctx.answer(text, nil, tgapi.ParseMDV2)
+}
+
+// Answerf formats a string using fmt.Sprintf and sends it as a plain text message.
+func (ctx *MsgContext) Answerf(template string, args ...any) *AnswerMessage {
+	return ctx.answer(fmt.Sprintf(template, args...), nil, tgapi.ParseNone)
+}
+
+// AnswerfMarkdown formats a string using fmt.Sprintf and sends it using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) AnswerfMarkdown(template string, args ...any) *AnswerMessage {
+	return ctx.answer(fmt.Sprintf(template, args...), nil, tgapi.ParseMDV2)
+}
+
+// Keyboard sends a message with an inline keyboard (plain text).
+func (ctx *MsgContext) Keyboard(text string, kb *InlineKeyboard) *AnswerMessage {
+	return ctx.answer(text, kb, tgapi.ParseNone)
+}
+
+// KeyboardMarkdown sends a message with an inline keyboard using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) KeyboardMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage {
+	return ctx.answer(text, keyboard, tgapi.ParseMDV2)
+}
+
+// answerPhoto sends a photo with optional caption and keyboard.
+func (ctx *MsgContext) answerPhoto(photoId, text string, kb *InlineKeyboard, parseMode tgapi.ParseMode) *AnswerMessage {
 	params := tgapi.SendPhotoP{
 		ChatID:    ctx.Msg.Chat.ID,
 		Caption:   text,
-		ParseMode: tgapi.ParseMD,
+		ParseMode: parseMode,
 		Photo:     photoId,
 	}
 	if kb != nil {
@@ -150,21 +264,50 @@ func (ctx *MsgContext) answerPhoto(photoId, text string, kb *InlineKeyboard) *An
 	msg, err := ctx.Api.SendPhoto(params)
 	if err != nil {
 		ctx.botLogger.Errorln(err)
-		return &AnswerMessage{
+		return nil
-			ctx: ctx, Text: text, IsMedia: true,
-		}
 	}
 	return &AnswerMessage{
 		MessageID: msg.MessageID, ctx: ctx, Text: text, IsMedia: true,
 	}
 }
+
+// AnswerPhoto sends a photo with plain text caption.
 func (ctx *MsgContext) AnswerPhoto(photoId, text string) *AnswerMessage {
-	return ctx.answerPhoto(photoId, text, nil)
+	return ctx.answerPhoto(photoId, text, nil, tgapi.ParseNone)
-}
-func (ctx *MsgContext) AnswerPhotoKeyboard(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
-	return ctx.answerPhoto(photoId, text, kb)
 }
 
+// AnswerPhotoMarkdown sends a photo with MarkdownV2 caption.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) AnswerPhotoMarkdown(photoId, text string) *AnswerMessage {
+	return ctx.answerPhoto(photoId, text, nil, tgapi.ParseMDV2)
+}
+
+// AnswerPhotoKeyboard sends a photo with caption and inline keyboard (plain text).
+func (ctx *MsgContext) AnswerPhotoKeyboard(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
+	return ctx.answerPhoto(photoId, text, kb, tgapi.ParseNone)
+}
+
+// AnswerPhotoKeyboardMarkdown sends a photo with caption and inline keyboard using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) AnswerPhotoKeyboardMarkdown(photoId, text string, kb *InlineKeyboard) *AnswerMessage {
+	return ctx.answerPhoto(photoId, text, kb, tgapi.ParseMDV2)
+}
+
+// AnswerPhotof formats a string and sends it as a photo caption (plain text).
+func (ctx *MsgContext) AnswerPhotof(photoId, template string, args ...any) *AnswerMessage {
+	return ctx.answerPhoto(photoId, fmt.Sprintf(template, args...), nil, tgapi.ParseNone)
+}
+
+// AnswerPhotofMarkdown formats a string and sends it as a photo caption using MarkdownV2.
+//
+// ⚠️ WARNING: User input must be escaped with laniakea.EscapeMarkdownV2() before passing here.
+func (ctx *MsgContext) AnswerPhotofMarkdown(photoId, template string, args ...any) *AnswerMessage {
+	return ctx.answerPhoto(photoId, fmt.Sprintf(template, args...), nil, tgapi.ParseMDV2)
+}
+
+// delete removes a message by ID.
 func (ctx *MsgContext) delete(messageId int) {
 	_, err := ctx.Api.DeleteMessage(tgapi.DeleteMessageP{
 		ChatID:    ctx.Msg.Chat.ID,
@@ -174,9 +317,15 @@ func (ctx *MsgContext) delete(messageId int) {
 		ctx.botLogger.Errorln(err)
 	}
 }
-func (m *AnswerMessage) Delete()        { m.ctx.delete(m.MessageID) }
+
+// Delete removes the message associated with this AnswerMessage.
+func (m *AnswerMessage) Delete() { m.ctx.delete(m.MessageID) }
+
+// CallbackDelete deletes the message that triggered the callback query.
 func (ctx *MsgContext) CallbackDelete() { ctx.delete(ctx.CallbackMsgId) }
 
+// answerCallbackQuery sends a response to a callback query (optional text/alert/url).
+// Does nothing if CallbackQueryId is empty.
 func (ctx *MsgContext) answerCallbackQuery(url, text string, showAlert bool) {
 	if len(ctx.CallbackQueryId) == 0 {
 		return
@@ -189,11 +338,20 @@ func (ctx *MsgContext) answerCallbackQuery(url, text string, showAlert bool) {
 		ctx.botLogger.Errorln(err)
 	}
 }
-func (ctx *MsgContext) AnswerCbQuery()                 { ctx.answerCallbackQuery("", "", false) }
-func (ctx *MsgContext) AnswerCbQueryText(text string)  { ctx.answerCallbackQuery("", text, false) }
-func (ctx *MsgContext) AnswerCbQueryAlert(text string) { ctx.answerCallbackQuery("", text, true) }
-func (ctx *MsgContext) AnswerCbQueryUrl(u string)      { ctx.answerCallbackQuery(u, "", false) }
 
+// AnswerCbQuery answers the callback query with no text or alert.
+func (ctx *MsgContext) AnswerCbQuery() { ctx.answerCallbackQuery("", "", false) }
+
+// AnswerCbQueryText answers the callback query with a text notification.
+func (ctx *MsgContext) AnswerCbQueryText(text string) { ctx.answerCallbackQuery("", text, false) }
+
+// AnswerCbQueryAlert answers the callback query with a user-visible alert.
+func (ctx *MsgContext) AnswerCbQueryAlert(text string) { ctx.answerCallbackQuery("", text, true) }
+
+// AnswerCbQueryUrl answers the callback query with a URL redirect.
+func (ctx *MsgContext) AnswerCbQueryUrl(u string) { ctx.answerCallbackQuery(u, "", false) }
+
+// SendAction sends a chat action (typing, uploading_photo, etc.) to indicate bot activity.
 func (ctx *MsgContext) SendAction(action tgapi.ChatActionType) {
 	params := tgapi.SendChatActionP{
 		ChatID: ctx.Msg.Chat.ID, Action: action,
@@ -207,24 +365,47 @@ func (ctx *MsgContext) SendAction(action tgapi.ChatActionType) {
 	}
 }
 
+// error sends an error message to the user and logs it.
+// Uses errorTemplate to format the message.
+// For callbacks: sends as callback answer (no alert).
+// For regular messages: sends as plain text.
 func (ctx *MsgContext) error(err error) {
-	text := fmt.Sprintf(ctx.errorTemplate, utils.EscapeMarkdown(err.Error()))
+	text := fmt.Sprintf(ctx.errorTemplate, err.Error())
 
 	if ctx.CallbackQueryId != "" {
 		ctx.answerCallbackQuery("", text, false)
 	} else {
-		ctx.answer(text, nil)
+		ctx.answer(text, nil, tgapi.ParseNone)
 	}
 	ctx.botLogger.Errorln(err)
 }
+
+// Error is an alias for error().
 func (ctx *MsgContext) Error(err error) { ctx.error(err) }
 
-func (ctx *MsgContext) NewDraft() *Draft {
+func (ctx *MsgContext) newDraft(parseMode tgapi.ParseMode) *Draft {
-	draft := ctx.draftProvider.NewDraft()
+	c := context.Background()
-	draft.chatID = ctx.Msg.Chat.ID
+	if err := ctx.Api.Limiter.Wait(c, ctx.Msg.Chat.ID); err != nil {
-	draft.messageThreadID = ctx.Msg.MessageThreadID
+		ctx.botLogger.Errorln(err)
+		return nil
+	}
+
+	draft := ctx.draftProvider.NewDraft(parseMode).SetChat(ctx.Msg.Chat.ID, ctx.Msg.MessageThreadID)
 	return draft
 }
+
+// NewDraft creates a new message draft associated with the current chat.
+// Uses the API limiter to avoid rate limiting.
+func (ctx *MsgContext) NewDraft() *Draft {
+	return ctx.newDraft(tgapi.ParseNone)
+}
+
+func (ctx *MsgContext) NewDraftMarkdown() *Draft {
+	return ctx.newDraft(tgapi.ParseMDV2)
+}
+
+// Translate looks up a key in the current user's language.
+// Falls back to the bot's default language if user's language is unknown or unsupported.
 func (ctx *MsgContext) Translate(key string) string {
 	if ctx.From == nil {
 		return key

plugins.go

@@ -1,3 +1,15 @@
+// Package laniakea provides a structured system for defining and executing
+// bot commands and payloads with middleware support, argument validation,
+// and plugin-based organization.
+//
+// The core concepts are:
+//   - Command: A named bot command with arguments, description, and executor.
+//   - Plugin: A collection of commands and payloads, with shared middlewares.
+//   - Middleware: Interceptors that can validate, modify, or block execution.
+//   - CommandArg: Type-safe argument definitions with regex validation.
+//
+// This system is designed to be used with MsgContext from the laniakea package
+// to handle Telegram bot interactions in a modular, type-safe way.
 package laniakea
 
 import (
@@ -7,83 +19,122 @@ import (
 	"git.nix13.pw/scuroneko/extypes"
 )
 
-const (
+// CommandValueType defines the expected type of a command argument.
-	CommandValueStringType CommandValueType = "string"
-	CommandValueIntType    CommandValueType = "int"
-	CommandValueBoolType   CommandValueType = "bool"
-	CommandValueAnyType    CommandValueType = "any"
-)
-
-var (
-	CommandRegexInt    = regexp.MustCompile("\\d+")
-	CommandRegexString = regexp.MustCompile(".+")
-)
-
-var (
-	ErrCmdArgCountMismatch  = errors.New("command arg count mismatch")
-	ErrCmdArgRegexpMismatch = errors.New("command arg regexp mismatch")
-)
-
 type CommandValueType string
+
+const (
+	// CommandValueStringType expects any non-empty string.
+	CommandValueStringType CommandValueType = "string"
+	// CommandValueIntType expects a decimal integer (digits only).
+	CommandValueIntType CommandValueType = "int"
+	// CommandValueBoolType is reserved for future use (not implemented).
+	CommandValueBoolType CommandValueType = "bool"
+	// CommandValueAnyType accepts any input without validation.
+	CommandValueAnyType CommandValueType = "any"
+)
+
+// CommandRegexInt matches one or more digits.
+var CommandRegexInt = regexp.MustCompile(`\d+`)
+
+// CommandRegexString matches any non-empty string.
+var CommandRegexString = regexp.MustCompile(".+")
+
+// ErrCmdArgCountMismatch is returned when the number of provided arguments
+// is less than the number of required arguments.
+var ErrCmdArgCountMismatch = errors.New("command arg count mismatch")
+
+// ErrCmdArgRegexpMismatch is returned when an argument fails regex validation.
+var ErrCmdArgRegexpMismatch = errors.New("command arg regexp mismatch")
+
+// CommandArg defines a single argument for a command, including type, regex,
+// and whether it is required.
 type CommandArg struct {
-	valueType CommandValueType
+	valueType CommandValueType // Type of expected value
-	text      string
+	text      string           // Human-readable description (not used in validation)
-	regex     *regexp.Regexp
+	regex     *regexp.Regexp   // Regex used to validate input
-	required  bool
+	required  bool             // Whether this argument must be provided
 }
 
+// NewCommandArg creates a new CommandArg with the given text and type.
+// Uses a default regex based on the type (string or int).
+// For CommandValueAnyType, no validation is performed.
 func NewCommandArg(text string, valueType CommandValueType) *CommandArg {
 	regex := CommandRegexString
 	switch valueType {
 	case CommandValueIntType:
 		regex = CommandRegexInt
+	case CommandValueAnyType:
+		regex = nil // Skip validation
 	}
 	return &CommandArg{valueType, text, regex, false}
 }
+
+// SetRequired marks this argument as required.
+// Returns the receiver for method chaining.
 func (c *CommandArg) SetRequired() *CommandArg {
 	c.required = true
 	return c
 }
 
+// CommandExecutor is the function type that executes a command.
+// It receives the message context and a database context (generic).
 type CommandExecutor[T DbContext] func(ctx *MsgContext, dbContext *T)
 
+// Command represents a bot command with arguments, description, and executor.
+// Can be registered in a Plugin and optionally skipped from auto-generation.
 type Command[T DbContext] struct {
-	command     string
+	command     string                       // The command trigger (e.g., "/start")
-	description string
+	description string                       // Human-readable description for help
-	exec        CommandExecutor[T]
+	exec        CommandExecutor[T]           // Function to execute when command is triggered
-	args        extypes.Slice[CommandArg]
+	args        extypes.Slice[CommandArg]    // List of expected arguments
-	middlewares extypes.Slice[Middleware[T]]
+	middlewares extypes.Slice[Middleware[T]] // Optional middleware chain
-	skipAutoCmd bool
+	skipAutoCmd bool                         // If true, this command won't be auto-added to help menus
 }
 
+// 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, args, make(extypes.Slice[Middleware[T]], 0), false}
+	return &Command[T]{command, "", exec, extypes.Slice[CommandArg](args), make(extypes.Slice[Middleware[T]], 0), false}
 }
+
+// Use adds a middleware to the command's execution chain.
+// Middlewares are executed in the order they are added.
 func (c *Command[T]) Use(m Middleware[T]) *Command[T] {
 	c.middlewares = c.middlewares.Push(m)
 	return c
 }
+
+// SetDescription sets the human-readable description of the command.
 func (c *Command[T]) SetDescription(desc string) *Command[T] {
 	c.description = desc
 	return c
 }
+
+// SkipCommandAutoGen marks this command to be excluded from auto-generated help menus.
 func (c *Command[T]) SkipCommandAutoGen() *Command[T] {
 	c.skipAutoCmd = true
 	return c
 }
+
+// validateArgs checks if the provided arguments match the command's requirements.
+// Returns ErrCmdArgCountMismatch if too few arguments are provided.
+// Returns ErrCmdArgRegexpMismatch if any argument fails regex validation.
 func (c *Command[T]) validateArgs(args []string) error {
-	cmdArgs := c.args.Filter(func(e CommandArg) bool { return !e.required })
+	// Count required args
-	if len(args) < cmdArgs.Len() {
+	requiredCount := c.args.Filter(func(a CommandArg) bool { return a.required }).Len()
+	if len(args) < requiredCount {
 		return ErrCmdArgCountMismatch
 	}
 
+	// Validate each argument against its regex
 	for i, arg := range args {
 		if i >= c.args.Len() {
+			// Extra arguments beyond defined args are ignored
 			break
 		}
 		cmdArg := c.args.Get(i)
 		if cmdArg.regex == nil {
-			continue
+			continue // Skip validation for CommandValueAnyType
 		}
 		if !cmdArg.regex.MatchString(arg) {
 			return ErrCmdArgRegexpMismatch
@@ -92,57 +143,123 @@ func (c *Command[T]) validateArgs(args []string) error {
 	return nil
 }
 
+// Plugin represents a collection of commands and payloads (e.g., callback handlers),
+// with shared middleware and configuration.
 type Plugin[T DbContext] struct {
-	name        string
+	name        string                       // Name of the plugin (e.g., "admin", "user")
-	commands    map[string]Command[T]
+	commands    map[string]Command[T]        // Registered commands (triggered by message)
-	payloads    map[string]Command[T]
+	payloads    map[string]Command[T]        // Registered payloads (triggered by callback data)
-	middlewares extypes.Slice[Middleware[T]]
+	middlewares extypes.Slice[Middleware[T]] // Shared middlewares for all commands/payloads
-	skipAutoCmd bool
+	skipAutoCmd bool                         // If true, all commands in this plugin are excluded from auto-help
 }
 
+// NewPlugin creates a new Plugin with the given name.
 func NewPlugin[T DbContext](name string) *Plugin[T] {
 	return &Plugin[T]{
-		name, map[string]Command[T]{},
+		name, make(map[string]Command[T]),
-		map[string]Command[T]{}, extypes.Slice[Middleware[T]]{}, false,
+		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
 	return p
 }
+
+// NewCommand creates and immediately adds a new command to the plugin.
+// Returns the created command for further configuration.
 func (p *Plugin[T]) NewCommand(exec CommandExecutor[T], command string, args ...CommandArg) *Command[T] {
-	return NewCommand(exec, command, args...)
+	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
 	return p
 }
+
+// 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] {
 	p.middlewares = p.middlewares.Push(middleware)
 	return p
 }
+
+// SkipCommandAutoGen marks the entire plugin to be excluded from auto-generated help menus.
 func (p *Plugin[T]) SkipCommandAutoGen() *Plugin[T] {
 	p.skipAutoCmd = true
 	return p
 }
 
+// executeCmd finds and executes a command by its trigger string.
+// Validates arguments and runs middlewares before executor.
+// On error, sends an error message to the user via ctx.error().
 func (p *Plugin[T]) executeCmd(cmd string, ctx *MsgContext, dbContext *T) {
-	command := p.commands[cmd]
+	command, exists := p.commands[cmd]
+	if !exists {
+		ctx.error(errors.New("command not found"))
+		return
+	}
+
 	if err := command.validateArgs(ctx.Args); err != nil {
 		ctx.error(err)
 		return
 	}
+
+	// Run plugin middlewares
+	if !p.executeMiddlewares(ctx, dbContext) {
+		return
+	}
+
+	// Run command-specific middlewares
+	for _, m := range command.middlewares {
+		if !m.Execute(ctx, dbContext) {
+			return
+		}
+	}
+
+	// Execute command
 	command.exec(ctx, dbContext)
 }
+
+// executePayload finds and executes a payload by its callback_data string.
+// Validates arguments and runs middlewares before executor.
+// On error, sends an error message to the user via ctx.error().
 func (p *Plugin[T]) executePayload(payload string, ctx *MsgContext, dbContext *T) {
-	pl := p.payloads[payload]
+	command, exists := p.payloads[payload]
-	if err := pl.validateArgs(ctx.Args); err != nil {
+	if !exists {
+		ctx.error(errors.New("payload not found"))
+		return
+	}
+
+	if err := command.validateArgs(ctx.Args); err != nil {
 		ctx.error(err)
 		return
 	}
-	pl.exec(ctx, dbContext)
+
+	// Run plugin middlewares
+	if !p.executeMiddlewares(ctx, dbContext) {
+		return
+	}
+
+	// Run command-specific middlewares
+	for _, m := range command.middlewares {
+		if !m.Execute(ctx, dbContext) {
+			return
+		}
+	}
+
+	// Execute payload
+	command.exec(ctx, dbContext)
 }
+
+// executeMiddlewares runs all plugin middlewares in order.
+// Returns false if any middleware returns false (blocks execution).
 func (p *Plugin[T]) executeMiddlewares(ctx *MsgContext, db *T) bool {
 	for _, m := range p.middlewares {
 		if !m.Execute(ctx, db) {
@@ -152,28 +269,41 @@ func (p *Plugin[T]) executeMiddlewares(ctx *MsgContext, db *T) bool {
 	return true
 }
 
+// MiddlewareExecutor is the function type for middleware logic.
+// Returns true to continue execution, false to block it.
+// If async, return value is ignored.
 type MiddlewareExecutor[T DbContext] func(ctx *MsgContext, db *T) bool
 
-// Middleware
+// Middleware represents a reusable execution interceptor.
-// When async, returned value ignored
+// Can be synchronous (blocking) or asynchronous (non-blocking).
 type Middleware[T DbContext] struct {
-	name     string
+	name     string                // Human-readable name for logging/debugging
-	executor MiddlewareExecutor[T]
+	executor MiddlewareExecutor[T] // Function to execute
-	order    int
+	order    int                   // Optional sort order (not used yet)
-	async    bool
+	async    bool                  // If true, runs in goroutine and doesn't block
 }
 
+// NewMiddleware creates a new synchronous middleware.
 func NewMiddleware[T DbContext](name string, executor MiddlewareExecutor[T]) *Middleware[T] {
 	return &Middleware[T]{name, executor, 0, false}
 }
+
+// SetOrder sets the execution order (currently ignored).
 func (m *Middleware[T]) SetOrder(order int) *Middleware[T] {
 	m.order = order
 	return m
 }
+
+// SetAsync marks the middleware to run asynchronously.
+// Execution continues regardless of its return value.
 func (m *Middleware[T]) SetAsync(async bool) *Middleware[T] {
 	m.async = async
 	return m
 }
+
+// Execute runs the middleware.
+// If async, runs in a goroutine and returns true immediately.
+// Otherwise, returns the result of the executor.
 func (m *Middleware[T]) Execute(ctx *MsgContext, db *T) bool {
 	if m.async {
 		go m.executor(ctx, db)

runners.go

@@ -1,55 +1,123 @@
+// Package laniakea provides a system for managing background and one-time
+// runner functions that operate on a Bot instance, with support for
+// asynchronous execution, timeouts, and lifecycle control.
+//
+// Runners are used for periodic tasks (e.g., cleanup, stats updates) or
+// one-time initialization logic. They are executed via Bot.ExecRunners().
+//
+// Important: Runners are not thread-safe for concurrent modification.
+// Builder methods (Onetime, Async, Timeout) must be called sequentially
+// and only before Execute().
 package laniakea
 
 import (
 	"time"
 )
 
+// RunnerFn is the function type for a runner. It receives a pointer to
+// the Bot and returns an error if execution fails.
 type RunnerFn[T DbContext] func(*Bot[T]) error
+
+// Runner represents a configurable background or one-time task to be
+// executed by a Bot.
+//
+// Runners are configured using builder methods: Onetime(), Async(), Timeout().
+// Once Execute() is called, the Runner should not be modified.
+//
+// Execution semantics:
+//   - onetime=true, async=false: Run once synchronously (blocks).
+//   - onetime=true, async=true:  Run once in a goroutine (non-blocking).
+//   - onetime=false, async=true: Run repeatedly in a goroutine with timeout.
+//   - onetime=false, async=false: Invalid configuration — ignored with warning.
 type Runner[T DbContext] struct {
-	name    string
+	name    string        // Human-readable name for logging
-	onetime bool
+	onetime bool          // If true, runs once; if false, runs periodically
-	async   bool
+	async   bool          // If true, runs in a goroutine; else, runs synchronously
-	timeout time.Duration
+	timeout time.Duration // Duration to wait between periodic executions (ignored if onetime=true)
-	fn      RunnerFn[T]
+	fn      RunnerFn[T]   // The function to execute
 }
 
+// NewRunner creates a new Runner with the given name and function.
+// By default, the Runner is configured as async=true (non-blocking).
+//
+// Builder methods (Onetime, Async, Timeout) can be chained to customize behavior.
+// DO NOT call builder methods concurrently or after Execute().
 func NewRunner[T DbContext](name string, fn RunnerFn[T]) *Runner[T] {
 	return &Runner[T]{
-		name: name, fn: fn, async: true,
+		name:    name,
+		fn:      fn,
+		async:   true, // Default: run asynchronously
+		timeout: 0,    // Default: no timeout (ignored if onetime=true)
 	}
 }
-func (b *Runner[T]) Onetime(onetime bool) *Runner[T] {
+
-	b.onetime = onetime
+// Onetime sets whether the runner executes once or repeatedly.
-	return b
+// If true, the runner runs only once.
-}
+// If false, the runner runs in a loop with the configured timeout.
-func (b *Runner[T]) Async(async bool) *Runner[T] {
+func (r *Runner[T]) Onetime(onetime bool) *Runner[T] {
-	b.async = async
+	r.onetime = onetime
-	return b
+	return r
-}
-func (b *Runner[T]) Timeout(timeout time.Duration) *Runner[T] {
-	b.timeout = timeout
-	return b
 }
 
+// Async sets whether the runner executes synchronously or asynchronously.
+// If true, the runner runs in a goroutine (non-blocking).
+// If false, the runner blocks the caller during execution.
+//
+// Note: If onetime=false and async=false, the runner will be skipped with a warning.
+func (r *Runner[T]) Async(async bool) *Runner[T] {
+	r.async = async
+	return r
+}
+
+// Timeout sets the duration to wait between repeated executions for
+// non-onetime runners.
+//
+// If onetime=true, this value is ignored.
+// If onetime=false and async=true, this timeout determines the sleep interval
+// between loop iterations.
+//
+// A zero value (time.Duration(0)) is allowed but may trigger a warning
+// if used with a background (non-onetime) async runner.
+func (r *Runner[T]) Timeout(timeout time.Duration) *Runner[T] {
+	r.timeout = timeout
+	return r
+}
+
+// ExecRunners executes all runners registered on the Bot.
+//
+// It logs warnings for misconfigured runners:
+//   - Sync, non-onetime runners are skipped (invalid configuration).
+//   - Background (non-onetime, async) runners without a timeout trigger a warning.
+//
+// Execution logic:
+//   - onetime + async: Runs once in a goroutine.
+//   - onetime + sync:  Runs once synchronously; warns if slower than 2 seconds.
+//   - !onetime + async: Runs in an infinite loop with timeout between iterations.
+//   - !onetime + sync: Skipped with warning.
+//
+// This method is typically called once during bot startup.
 func (bot *Bot[T]) ExecRunners() {
 	bot.logger.Infoln("Executing runners...")
 	for _, runner := range bot.runners {
+		// Validate configuration
 		if !runner.onetime && !runner.async {
-			bot.logger.Warnf("Runner %s not onetime, but sync\n", runner.name)
+			bot.logger.Warnf("Runner %s not onetime, but sync — skipping\n", runner.name)
 			continue
 		}
-		if !runner.onetime && runner.async && runner.timeout == (time.Second*0) {
+		if !runner.onetime && runner.async && runner.timeout == 0 {
-			bot.logger.Warnf("Background runner \"%s\" should have timeout", runner.name)
+			bot.logger.Warnf("Background runner \"%s\" has no timeout — may cause tight loop\n", runner.name)
 		}
 
-		if runner.async && runner.onetime {
+		if runner.onetime && runner.async {
-			go func() {
+			// One-time async: fire and forget
-				err := runner.fn(bot)
+			go func(r Runner[T]) {
+				err := r.fn(bot)
 				if err != nil {
-					bot.logger.Warnf("Runner %s failed: %s\n", runner.name, err)
+					bot.logger.Warnf("Runner %s failed: %s\n", r.name, err)
 				}
-			}()
+			}(runner)
-		} else if !runner.async && runner.onetime {
+		} else if runner.onetime && !runner.async {
+			// One-time sync: block until done
 			t := time.Now()
 			err := runner.fn(bot)
 			if err != nil {
@@ -57,18 +125,20 @@ func (bot *Bot[T]) ExecRunners() {
 			}
 			elapsed := time.Since(t)
 			if elapsed > time.Second*2 {
-				bot.logger.Warnf("Runner %s too slow. Elapsed time %s>=2s", runner.name, elapsed)
+				bot.logger.Warnf("Runner %s too slow. Elapsed time %v >= 2s\n", runner.name, elapsed)
 			}
-		} else if !runner.onetime {
+		} else if !runner.onetime && runner.async {
-			go func() {
+			// Background loop: periodic execution
+			go func(r Runner[T]) {
 				for {
-					err := runner.fn(bot)
+					err := r.fn(bot)
 					if err != nil {
-						bot.logger.Warnf("Runner %s failed: %s\n", runner.name, err)
+						bot.logger.Warnf("Runner %s failed: %s\n", r.name, err)
 					}
-					time.Sleep(runner.timeout)
+					time.Sleep(r.timeout)
 				}
-			}()
+			}(runner)
 		}
+		// Note: !onetime && !async is already skipped above
 	}
 }

tgapi/api.go

@@ -4,7 +4,6 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -12,49 +11,73 @@ import (
 
 	"git.nix13.pw/scuroneko/laniakea/utils"
 	"git.nix13.pw/scuroneko/slog"
-	"golang.org/x/time/rate"
 )
 
+// APIOpts holds configuration options for initializing the Telegram API client.
+// Use the provided setter methods to build options — do not construct directly.
 type APIOpts struct {
 	token         string
 	client        *http.Client
 	useTestServer bool
 	apiUrl        string
 
-	limiter           *rate.Limiter
+	limiter           *utils.RateLimiter
 	dropOverflowLimit bool
 }
 
-var ErrPoolUnexpected = errors.New("unexpected response from pool")
+// NewAPIOpts creates a new APIOpts with default values.
-
+// Use setter methods to customize behavior.
 func NewAPIOpts(token string) *APIOpts {
-	return &APIOpts{token: token, client: nil, useTestServer: false, apiUrl: "https://api.telegram.org"}
+	return &APIOpts{
+		token:         token,
+		client:        nil,
+		useTestServer: false,
+		apiUrl:        "https://api.telegram.org",
+	}
 }
+
+// SetHTTPClient sets a custom HTTP client. Use this for timeouts, proxies, or custom transport.
+// If not set, a default client with 45s timeout is used.
 func (opts *APIOpts) SetHTTPClient(client *http.Client) *APIOpts {
 	if client != nil {
 		opts.client = client
 	}
 	return opts
 }
+
+// UseTestServer enables use of Telegram's test server (https://api.test.telegram.org).
+// Only for development/testing.
 func (opts *APIOpts) UseTestServer(use bool) *APIOpts {
 	opts.useTestServer = use
 	return opts
 }
+
+// SetAPIUrl overrides the default Telegram API URL.
+// Useful for self-hosted bots or proxies.
 func (opts *APIOpts) SetAPIUrl(apiUrl string) *APIOpts {
 	if apiUrl != "" {
 		opts.apiUrl = apiUrl
 	}
 	return opts
 }
-func (opts *APIOpts) SetLimiter(limiter *rate.Limiter) *APIOpts {
+
+// SetLimiter sets a rate limiter to enforce Telegram's API limits.
+// Recommended: use utils.NewRateLimiter() for correct per-chat and global throttling.
+func (opts *APIOpts) SetLimiter(limiter *utils.RateLimiter) *APIOpts {
 	opts.limiter = limiter
 	return opts
 }
+
+// SetLimiterDrop enables "drop mode" for rate limiting.
+// If true, requests exceeding limits return ErrDropOverflow immediately.
+// If false, requests block until capacity is available.
 func (opts *APIOpts) SetLimiterDrop(b bool) *APIOpts {
 	opts.dropOverflowLimit = b
 	return opts
 }
 
+// API is the main Telegram Bot API client.
+// It manages HTTP requests, rate limiting, retries, and connection pooling.
 type API struct {
 	token         string
 	client        *http.Client
@@ -62,63 +85,116 @@ type API struct {
 	useTestServer bool
 	apiUrl        string
 
-	pool              *WorkerPool
+	pool              *workerPool
-	limiter           *rate.Limiter
+	Limiter           *utils.RateLimiter
 	dropOverflowLimit bool
 }
 
+// NewAPI creates a new API client from options.
+// Always call CloseApi() when done to release resources.
 func NewAPI(opts *APIOpts) *API {
 	l := slog.CreateLogger().Level(utils.GetLoggerLevel()).Prefix("API")
 	l.AddWriter(l.CreateJsonStdoutWriter())
+
 	client := opts.client
 	if client == nil {
 		client = &http.Client{Timeout: time.Second * 45}
 	}
-	pool := NewWorkerPool(16, 256)
+
-	pool.Start(context.Background())
+	pool := newWorkerPool(16, 256)
+	pool.start(context.Background())
+
 	return &API{
-		opts.token, client, l,
+		token:             opts.token,
-		opts.useTestServer, opts.apiUrl,
+		client:            client,
-		pool, opts.limiter, opts.dropOverflowLimit,
+		logger:            l,
+		useTestServer:     opts.useTestServer,
+		apiUrl:            opts.apiUrl,
+		pool:              pool,
+		Limiter:           opts.limiter,
+		dropOverflowLimit: opts.dropOverflowLimit,
 	}
 }
+
+// CloseApi shuts down the internal worker pool and closes the logger.
+// Must be called to avoid resource leaks.
 func (api *API) CloseApi() error {
-	api.pool.Stop()
+	api.pool.stop()
 	return api.logger.Close()
 }
-func (api *API) GetLogger() *slog.Logger { return api.logger }
 
-type ApiResponse[R any] struct {
+// GetLogger returns the internal logger for custom logging.
-	Ok          bool   `json:"ok"`
+func (api *API) GetLogger() *slog.Logger {
-	Description string `json:"description,omitempty"`
+	return api.logger
-	Result      R      `json:"result,omitempty"`
-	ErrorCode   int    `json:"error_code,omitempty"`
 }
+
+// ResponseParameters contains Telegram API response metadata (e.g., retry_after, migrate_to_chat_id).
+type ResponseParameters struct {
+	MigrateToChatID *int64 `json:"migrate_to_chat_id,omitempty"`
+	RetryAfter      *int   `json:"retry_after,omitempty"`
+}
+
+// ApiResponse is the standard Telegram Bot API response structure.
+// Generic over Result type R.
+type ApiResponse[R any] struct {
+	Ok          bool                `json:"ok"`
+	Description string              `json:"description,omitempty"`
+	Result      R                   `json:"result,omitempty"`
+	ErrorCode   int                 `json:"error_code,omitempty"`
+	Parameters  *ResponseParameters `json:"parameters,omitempty"`
+}
+
+// TelegramRequest is an internal helper struct.
+// DO NOT USE NewRequest or NewRequestWithChatID — they are unsafe and discouraged.
+// Instead, use explicit methods like SendMessage, GetUpdates, etc.
+//
+// Why? Because using generics with arbitrary types P and R leads to:
+//   - No compile-time validation of parameters
+//   - No IDE autocompletion
+//   - Runtime panics on malformed JSON
+//   - Hard-to-debug errors
+//
+// Recommended: Define specific methods for each Telegram method (see below).
 type TelegramRequest[R, P any] struct {
 	method string
 	params P
+	chatId int64
 }
 
+// NewRequest and NewRequestWithChatID are DEPRECATED.
+// They encourage unsafe, untyped usage and bypass Go's type safety.
+// Instead, define explicit, type-safe methods for each Telegram API endpoint.
+//
+// Example:
+//
+//	func (api *API) SendMessage(ctx context.Context, chatID int64, text string) (Message, error) { ... }
+//
+// This provides:
+//
+//	✅ Compile-time validation
+//	✅ IDE autocompletion
+//	✅ Clear API surface
+//	✅ Better error messages
+//
+// DO NOT use these constructors in production code.
+// This can be used ONLY for testing or if you NEED method, that wasn't added as function.
 func NewRequest[R, P any](method string, params P) TelegramRequest[R, P] {
-	return TelegramRequest[R, P]{method: method, params: params}
+	return TelegramRequest[R, P]{method, params, 0}
 }
+
+func NewRequestWithChatID[R, P any](method string, params P, chatId int64) TelegramRequest[R, P] {
+	return TelegramRequest[R, P]{method, params, chatId}
+}
+
+// doRequest performs a single HTTP request to Telegram API.
+// Handles rate limiting, retries on 429, and parses responses.
+// Must be called within a worker pool context if using DoWithContext.
 func (r TelegramRequest[R, P]) doRequest(ctx context.Context, api *API) (R, error) {
 	var zero R
-	if api.limiter != nil {
-		if api.dropOverflowLimit {
-			if !api.limiter.Allow() {
-				return zero, errors.New("rate limited")
-			}
-		} else {
-			if err := api.limiter.Wait(ctx); err != nil {
-				return zero, err
-			}
-		}
-	}
 
 	data, err := json.Marshal(r.params)
 	if err != nil {
-		return zero, err
+		return zero, fmt.Errorf("failed to marshal request: %w", err)
 	}
 	buf := bytes.NewBuffer(data)
 
@@ -127,36 +203,82 @@ func (r TelegramRequest[R, P]) doRequest(ctx context.Context, api *API) (R, erro
 		methodPrefix = "/test"
 	}
 	url := fmt.Sprintf("%s/bot%s%s/%s", api.apiUrl, api.token, methodPrefix, r.method)
+
 	req, err := http.NewRequestWithContext(ctx, "POST", url, buf)
 	if err != nil {
-		return zero, err
+		return zero, fmt.Errorf("failed to create request: %w", err)
 	}
+
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("Accept", "application/json")
 	req.Header.Set("User-Agent", fmt.Sprintf("Laniakea/%s", utils.VersionString))
+	req.Header.Set("Accept-Encoding", "gzip")
+	req.ContentLength = int64(len(data))
 
-	api.logger.Debugln("REQ", api.apiUrl, r.method, buf.String())
+	for {
-	res, err := api.client.Do(req)
+		// Apply rate limiting before making the request
-	if err != nil {
+		if api.Limiter != nil {
-		return zero, err
+			if err := api.Limiter.Check(ctx, api.dropOverflowLimit, r.chatId); err != nil {
-	}
+				return zero, err
-	defer func(Body io.ReadCloser) {
+			}
-		_ = Body.Close()
+		}
-	}(res.Body)
 
-	data, err = readBody(res.Body)
+		api.logger.Debugln("REQ", url, string(data))
-	if err != nil {
+
-		return zero, err
+		resp, err := api.client.Do(req)
+		if err != nil {
+			return zero, fmt.Errorf("HTTP request failed: %w", err)
+		}
+
+		data, err = readBody(resp.Body)
+		_ = resp.Body.Close() // ensure body is closed
+		if err != nil {
+			return zero, fmt.Errorf("failed to read response body: %w", err)
+		}
+
+		api.logger.Debugln("RES", r.method, string(data))
+
+		response, err := parseBody[R](data)
+		if err != nil {
+			return zero, fmt.Errorf("failed to parse response: %w", err)
+		}
+
+		if !response.Ok {
+			// Handle rate limiting (429)
+			if response.ErrorCode == 429 && response.Parameters != nil && response.Parameters.RetryAfter != nil {
+				after := *response.Parameters.RetryAfter
+				api.logger.Warnf("Rate limited by Telegram, retry after %d seconds (chat: %d)", after, r.chatId)
+
+				// Apply cooldown to global or chat-specific limiter
+				if r.chatId > 0 {
+					api.Limiter.SetChatLock(r.chatId, after)
+				} else {
+					api.Limiter.SetGlobalLock(after)
+				}
+
+				// Wait and retry
+				select {
+				case <-ctx.Done():
+					return zero, ctx.Err()
+				case <-time.After(time.Duration(after) * time.Second):
+					continue // retry request
+				}
+			}
+
+			// Other API errors
+			return zero, fmt.Errorf("[%d] %s", response.ErrorCode, response.Description)
+		}
+
+		return response.Result, nil
 	}
-	api.logger.Debugln("RES", r.method, string(data))
-	if res.StatusCode != http.StatusOK {
-		return zero, fmt.Errorf("unexpected status code: %d, %s", res.StatusCode, string(data))
-	}
-	return parseBody[R](data)
 }
+
+// DoWithContext executes the request asynchronously via the worker pool.
+// Returns result or error via channel. Respects context cancellation.
 func (r TelegramRequest[R, P]) DoWithContext(ctx context.Context, api *API) (R, error) {
 	var zero R
-	result, err := api.pool.Submit(ctx, func(ctx context.Context) (any, error) {
+
+	resultChan, err := api.pool.submit(ctx, func(ctx context.Context) (any, error) {
 		return r.doRequest(ctx, api)
 	})
 	if err != nil {
@@ -166,33 +288,45 @@ func (r TelegramRequest[R, P]) DoWithContext(ctx context.Context, api *API) (R,
 	select {
 	case <-ctx.Done():
 		return zero, ctx.Err()
-	case res := <-result:
+	case res := <-resultChan:
-		if res.Err != nil {
+		if res.err != nil {
-			return zero, res.Err
+			return zero, res.err
 		}
-		if val, ok := res.Value.(R); ok {
+		if val, ok := res.value.(R); ok {
 			return val, nil
 		}
 		return zero, ErrPoolUnexpected
 	}
 }
+
+// Do executes the request synchronously with a background context.
+// Use only for simple, non-critical calls.
 func (r TelegramRequest[R, P]) Do(api *API) (R, error) {
 	return r.DoWithContext(context.Background(), api)
 }
 
+// readBody reads and limits response body to prevent memory exhaustion.
+// Telegram responses are typically small (<1MB), but we cap at 10MB.
 func readBody(body io.ReadCloser) ([]byte, error) {
-	reader := io.LimitReader(body, 10<<20)
+	reader := io.LimitReader(body, 10<<20) // 10 MB
 	return io.ReadAll(reader)
 }
-func parseBody[R any](data []byte) (R, error) {
+
-	var zero R
+// parseBody unmarshals Telegram API response and returns structured result.
+// Returns ErrRateLimit internally if error_code == 429 — caller must handle via response.Ok check.
+func parseBody[R any](data []byte) (ApiResponse[R], error) {
 	var resp ApiResponse[R]
 	err := json.Unmarshal(data, &resp)
 	if err != nil {
-		return zero, err
+		return resp, fmt.Errorf("failed to unmarshal JSON: %w", err)
 	}
+
 	if !resp.Ok {
-		return zero, fmt.Errorf("[%d] %s", resp.ErrorCode, resp.Description)
+		if resp.ErrorCode == 429 {
+			return resp, ErrRateLimit // internal use only
+		}
+		return resp, fmt.Errorf("[%d] %s", resp.ErrorCode, resp.Description)
 	}
-	return resp.Result, nil
+
+	return resp, nil
 }

tgapi/attachments_methods.go

@@ -2,7 +2,7 @@ package tgapi
 
 type SendPhotoP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -24,13 +24,13 @@ type SendPhotoP struct {
 }
 
 func (api *API) SendPhoto(params SendPhotoP) (Message, error) {
-	req := NewRequest[Message]("sendPhoto", params)
+	req := NewRequestWithChatID[Message]("sendPhoto", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendAudioP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -53,13 +53,13 @@ type SendAudioP struct {
 }
 
 func (api *API) SendAudio(params SendAudioP) (Message, error) {
-	req := NewRequest[Message]("sendAudio", params)
+	req := NewRequestWithChatID[Message]("sendAudio", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendDocumentP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -79,13 +79,13 @@ type SendDocumentP struct {
 }
 
 func (api *API) SendDocument(params SendDocumentP) (Message, error) {
-	req := NewRequest[Message]("sendDocument", params)
+	req := NewRequestWithChatID[Message]("sendDocument", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendVideoP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -114,13 +114,13 @@ type SendVideoP struct {
 }
 
 func (api *API) SendVideo(params SendVideoP) (Message, error) {
-	req := NewRequest[Message]("sendVideo", params)
+	req := NewRequestWithChatID[Message]("sendVideo", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendAnimationP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -145,13 +145,13 @@ type SendAnimationP struct {
 }
 
 func (api *API) SendAnimation(params SendAnimationP) (Message, error) {
-	req := NewRequest[Message]("sendAnimation", params)
+	req := NewRequestWithChatID[Message]("sendAnimation", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendVoiceP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -171,13 +171,13 @@ type SendVoiceP struct {
 }
 
 func (api *API) SendVoice(params *SendVoiceP) (Message, error) {
-	req := NewRequest[Message]("sendVoice", params)
+	req := NewRequestWithChatID[Message]("sendVoice", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendVideoNoteP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -195,13 +195,13 @@ type SendVideoNoteP struct {
 }
 
 func (api *API) SendVideoNote(params SendVideoNoteP) (Message, error) {
-	req := NewRequest[Message]("sendVideoNote", params)
+	req := NewRequestWithChatID[Message]("sendVideoNote", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendPaidMediaP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 	StarCount             int    `json:"star_count,omitempty"`
@@ -222,13 +222,13 @@ type SendPaidMediaP struct {
 }
 
 func (api *API) SendPaidMedia(params SendPaidMediaP) (Message, error) {
-	req := NewRequest[Message]("sendPaidMedia", params)
+	req := NewRequestWithChatID[Message]("sendPaidMedia", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendMediaGroupP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -241,6 +241,6 @@ type SendMediaGroupP struct {
 }
 
 func (api *API) SendMediaGroup(params SendMediaGroupP) (Message, error) {
-	req := NewRequest[Message]("sendMediaGroup", params)
+	req := NewRequestWithChatID[Message]("sendMediaGroup", params, params.ChatID)
 	return req.Do(api)
 }

tgapi/chat_methods.go

@@ -1,30 +1,30 @@
 package tgapi
 
 type BanChatMemberP struct {
-	ChatID         int  `json:"chat_id"`
+	ChatID         int64 `json:"chat_id"`
-	UserID         int  `json:"user_id"`
+	UserID         int   `json:"user_id"`
-	UntilDate      int  `json:"until_date,omitempty"`
+	UntilDate      int   `json:"until_date,omitempty"`
-	RevokeMessages bool `json:"revoke_messages,omitempty"`
+	RevokeMessages bool  `json:"revoke_messages,omitempty"`
 }
 
 func (api *API) BanChatMember(params BanChatMemberP) (bool, error) {
-	req := NewRequest[bool]("banChatMember", params)
+	req := NewRequestWithChatID[bool]("banChatMember", params, params.ChatID)
 	return req.Do(api)
 }
 
 type UnbanChatMemberP struct {
-	ChatID       int  `json:"chat_id"`
+	ChatID       int64 `json:"chat_id"`
-	UserID       int  `json:"user_id"`
+	UserID       int   `json:"user_id"`
-	OnlyIfBanned bool `json:"only_if_banned"`
+	OnlyIfBanned bool  `json:"only_if_banned"`
 }
 
 func (api *API) UnbanChatMember(params UnbanChatMemberP) (bool, error) {
-	req := NewRequest[bool]("unbanChatMember", params)
+	req := NewRequestWithChatID[bool]("unbanChatMember", params, params.ChatID)
 	return req.Do(api)
 }
 
 type RestrictChatMemberP struct {
-	ChatID                        int             `json:"chat_id"`
+	ChatID                        int64           `json:"chat_id"`
 	UserID                        int             `json:"user_id"`
 	Permissions                   ChatPermissions `json:"permissions"`
 	UseIndependentChatPermissions bool            `json:"use_independent_chat_permissions,omitempty"`
@@ -32,14 +32,14 @@ type RestrictChatMemberP struct {
 }
 
 func (api *API) RestrictChatMember(params RestrictChatMemberP) (bool, error) {
-	req := NewRequest[bool]("restrictChatMember", params)
+	req := NewRequestWithChatID[bool]("restrictChatMember", params, params.ChatID)
 	return req.Do(api)
 }
 
 type PromoteChatMember struct {
-	ChatID      int  `json:"chat_id"`
+	ChatID      int64 `json:"chat_id"`
-	UserID      int  `json:"user_id"`
+	UserID      int   `json:"user_id"`
-	IsAnonymous bool `json:"is_anonymous,omitempty"`
+	IsAnonymous bool  `json:"is_anonymous,omitempty"`
 
 	CanManageChat           bool `json:"can_manage_chat,omitempty"`
 	CanDeleteMessages       bool `json:"can_delete_messages,omitempty"`
@@ -60,74 +60,74 @@ type PromoteChatMember struct {
 }
 
 func (api *API) PromoteChatMember(params PromoteChatMember) (bool, error) {
-	req := NewRequest[bool]("promoteChatMember", params)
+	req := NewRequestWithChatID[bool]("promoteChatMember", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SetChatAdministratorCustomTitleP struct {
-	ChatID      int    `json:"chat_id"`
+	ChatID      int64  `json:"chat_id"`
 	UserID      int    `json:"user_id"`
 	CustomTitle string `json:"custom_title"`
 }
 
 func (api *API) SetChatAdministratorCustomTitle(params SetChatAdministratorCustomTitleP) (bool, error) {
-	req := NewRequest[bool]("setChatAdministratorCustomTitle", params)
+	req := NewRequestWithChatID[bool]("setChatAdministratorCustomTitle", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SetChatMemberTagP struct {
-	ChatID int    `json:"chat_id"`
+	ChatID int64  `json:"chat_id"`
 	UserID int    `json:"user_id"`
 	Tag    string `json:"tag,omitempty"`
 }
 
 func (api *API) SetChatMemberTag(params SetChatMemberTagP) (bool, error) {
-	req := NewRequest[bool]("setChatMemberTag", params)
+	req := NewRequestWithChatID[bool]("setChatMemberTag", params, params.ChatID)
 	return req.Do(api)
 }
 
 type BanChatSenderChatP struct {
-	ChatID       int `json:"chat_id"`
+	ChatID       int64 `json:"chat_id"`
-	SenderChatID int `json:"sender_chat_id"`
+	SenderChatID int64 `json:"sender_chat_id"`
 }
 
 func (api *API) BanChatSenderChat(params BanChatSenderChatP) (bool, error) {
-	req := NewRequest[bool]("banChatSenderChat", params)
+	req := NewRequestWithChatID[bool]("banChatSenderChat", params, params.ChatID)
 	return req.Do(api)
 }
 
 type UnbanChatSenderChatP struct {
-	ChatID       int `json:"chat_id"`
+	ChatID       int64 `json:"chat_id"`
-	SenderChatID int `json:"sender_chat_id"`
+	SenderChatID int64 `json:"sender_chat_id"`
 }
 
 func (api *API) UnbanChatSenderChat(params BanChatSenderChatP) (bool, error) {
-	req := NewRequest[bool]("unbanChatSenderChat", params)
+	req := NewRequestWithChatID[bool]("unbanChatSenderChat", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SetChatPermissionsP struct {
-	ChatID                        int             `json:"chat_id"`
+	ChatID                        int64           `json:"chat_id"`
 	Permissions                   ChatPermissions `json:"permissions"`
 	UseIndependentChatPermissions bool            `json:"use_independent_chat_permissions,omitempty"`
 }
 
 func (api *API) SetChatPermissions(params SetChatPermissionsP) (bool, error) {
-	req := NewRequest[bool]("setChatPermissions", params)
+	req := NewRequestWithChatID[bool]("setChatPermissions", params, params.ChatID)
 	return req.Do(api)
 }
 
 type ExportChatInviteLinkP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }
 
 func (api *API) ExportChatInviteLink(params ExportChatInviteLinkP) (string, error) {
-	req := NewRequest[string]("exportChatInviteLink", params)
+	req := NewRequestWithChatID[string]("exportChatInviteLink", params, params.ChatID)
 	return req.Do(api)
 }
 
 type CreateChatInviteLinkP struct {
-	ChatID             int     `json:"chat_id"`
+	ChatID             int64   `json:"chat_id"`
 	Name               *string `json:"name,omitempty"`
 	ExpireDate         int     `json:"expire_date,omitempty"`
 	MemberLimit        int     `json:"member_limit,omitempty"`
@@ -135,12 +135,12 @@ type CreateChatInviteLinkP struct {
 }
 
 func (api *API) CreateChatInviteLink(params CreateChatInviteLinkP) (ChatInviteLink, error) {
-	req := NewRequest[ChatInviteLink]("createChatInviteLink", params)
+	req := NewRequestWithChatID[ChatInviteLink]("createChatInviteLink", params, params.ChatID)
 	return req.Do(api)
 }
 
 type EditChatInviteLinkP struct {
-	ChatID     int    `json:"chat_id"`
+	ChatID     int64  `json:"chat_id"`
 	InviteLink string `json:"invite_link"`
 
 	Name               string `json:"name,omitempty"`
@@ -150,206 +150,208 @@ type EditChatInviteLinkP struct {
 }
 
 func (api *API) EditChatInviteLink(params EditChatInviteLinkP) (ChatInviteLink, error) {
-	req := NewRequest[ChatInviteLink]("editChatInviteLink", params)
+	req := NewRequestWithChatID[ChatInviteLink]("editChatInviteLink", params, params.ChatID)
 	return req.Do(api)
 }
 
 type CreateChatSubscriptionInviteLinkP struct {
-	ChatID             int    `json:"chat_id"`
+	ChatID             int64  `json:"chat_id"`
 	Name               string `json:"name,omitempty"`
 	SubscriptionPeriod int    `json:"subscription_period,omitempty"`
 	SubscriptionPrice  int    `json:"subscription_price,omitempty"`
 }
 
 func (api *API) CreateChatSubscriptionInviteLink(params CreateChatSubscriptionInviteLinkP) (ChatInviteLink, error) {
-	req := NewRequest[ChatInviteLink]("createChatSubscriptionInviteLink", params)
+	req := NewRequestWithChatID[ChatInviteLink]("createChatSubscriptionInviteLink", params, params.ChatID)
 	return req.Do(api)
 }
 
 type EditChatSubscriptionInviteLinkP struct {
-	ChatID     int    `json:"chat_id"`
+	ChatID     int64  `json:"chat_id"`
 	InviteLink string `json:"invite_link"`
 	Name       string `json:"name,omitempty"`
 }
 
 func (api *API) EditChatSubscriptionInviteLink(params EditChatSubscriptionInviteLinkP) (ChatInviteLink, error) {
-	req := NewRequest[ChatInviteLink]("editChatSubscriptionInviteLink", params)
+	req := NewRequestWithChatID[ChatInviteLink]("editChatSubscriptionInviteLink", params, params.ChatID)
 	return req.Do(api)
 }
 
 type RevokeChatInviteLinkP struct {
-	ChatID     int    `json:"chat_id"`
+	ChatID     int64  `json:"chat_id"`
 	InviteLink string `json:"invite_link"`
 }
 
 func (api *API) RevokeChatInviteLink(params RevokeChatInviteLinkP) (ChatInviteLink, error) {
-	req := NewRequest[ChatInviteLink]("revokeChatInviteLink", params)
+	req := NewRequestWithChatID[ChatInviteLink]("revokeChatInviteLink", params, params.ChatID)
 	return req.Do(api)
 }
 
 type ApproveChatJoinRequestP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
-	UserID int `json:"user_id"`
+	UserID int   `json:"user_id"`
 }
 
 func (api *API) ApproveChatJoinRequest(params ApproveChatJoinRequestP) (bool, error) {
-	req := NewRequest[bool]("approveChatJoinRequest", params)
+	req := NewRequestWithChatID[bool]("approveChatJoinRequest", params, params.ChatID)
 	return req.Do(api)
 }
 
 type DeclineChatJoinRequestP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
-	UserID int `json:"user_id"`
+	UserID int   `json:"user_id"`
 }
 
 func (api *API) DeclineChatJoinRequest(params DeclineChatJoinRequestP) (bool, error) {
-	req := NewRequest[bool]("declineChatJoinRequest", params)
+	req := NewRequestWithChatID[bool]("declineChatJoinRequest", params, params.ChatID)
 	return req.Do(api)
 }
 
 func (api *API) SetChatPhoto() {
 	uploader := NewUploader(api)
-	defer uploader.Close()
+	defer func() {
+		_ = uploader.Close()
+	}()
 }
 
 type DeleteChatPhotoP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }
 
 func (api *API) DeleteChatPhoto(params DeleteChatPhotoP) (bool, error) {
-	req := NewRequest[bool]("deleteChatPhoto", params)
+	req := NewRequestWithChatID[bool]("deleteChatPhoto", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SetChatTitleP struct {
-	ChatID int    `json:"chat_id"`
+	ChatID int64  `json:"chat_id"`
 	Title  string `json:"title"`
 }
 
 func (api *API) SetChatTitle(params SetChatTitleP) (bool, error) {
-	req := NewRequest[bool]("setChatTitle", params)
+	req := NewRequestWithChatID[bool]("setChatTitle", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SetChatDescriptionP struct {
-	ChatID      int    `json:"chat_id"`
+	ChatID      int64  `json:"chat_id"`
 	Description string `json:"description"`
 }
 
 func (api *API) SetChatDescription(params SetChatDescriptionP) (bool, error) {
-	req := NewRequest[bool]("setChatDescription", params)
+	req := NewRequestWithChatID[bool]("setChatDescription", params, params.ChatID)
 	return req.Do(api)
 }
 
 type PinChatMessageP struct {
 	BusinessConnectionID *string `json:"business_connection_id,omitempty"`
-	ChatID               int     `json:"chat_id"`
+	ChatID               int64   `json:"chat_id"`
 	MessageID            int     `json:"message_id"`
 	DisableNotification  bool    `json:"disable_notification,omitempty"`
 }
 
 func (api *API) PinChatMessage(params PinChatMessageP) (bool, error) {
-	req := NewRequest[bool]("pinChatMessage", params)
+	req := NewRequestWithChatID[bool]("pinChatMessage", params, params.ChatID)
 	return req.Do(api)
 }
 
 type UnpinChatMessageP struct {
 	BusinessConnectionID *string `json:"business_connection_id,omitempty"`
-	ChatID               int     `json:"chat_id"`
+	ChatID               int64   `json:"chat_id"`
 	MessageID            int     `json:"message_id"`
 }
 
 func (api *API) UnpinChatMessage(params UnpinChatMessageP) (bool, error) {
-	req := NewRequest[bool]("unpinChatMessage", params)
+	req := NewRequestWithChatID[bool]("unpinChatMessage", params, params.ChatID)
 	return req.Do(api)
 }
 
 type UnpinAllChatMessagesP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }
 
 func (api *API) UnpinAllChatMessages(params UnpinAllChatMessagesP) (bool, error) {
-	req := NewRequest[bool]("unpinAllChatMessages", params)
+	req := NewRequestWithChatID[bool]("unpinAllChatMessages", params, params.ChatID)
 	return req.Do(api)
 }
 
 type LeaveChatP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }
 
 func (api *API) LeaveChat(params LeaveChatP) (bool, error) {
-	req := NewRequest[bool]("leaveChatP", params)
+	req := NewRequestWithChatID[bool]("leaveChatP", params, params.ChatID)
 	return req.Do(api)
 }
 
 type GetChatP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }
 
 func (api *API) GetChatP(params GetChatP) (ChatFullInfo, error) {
-	req := NewRequest[ChatFullInfo]("getChatP", params)
+	req := NewRequestWithChatID[ChatFullInfo]("getChatP", params, params.ChatID)
 	return req.Do(api)
 }
 
 type GetChatAdministratorsP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }
 
 func (api *API) GetChatAdministrators(params GetChatAdministratorsP) ([]ChatMember, error) {
-	req := NewRequest[[]ChatMember]("getChatAdministrators", params)
+	req := NewRequestWithChatID[[]ChatMember]("getChatAdministrators", params, params.ChatID)
 	return req.Do(api)
 }
 
 type GetChatMembersCountP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }
 
 func (api *API) GetChatMemberCount(params GetChatMembersCountP) (int, error) {
-	req := NewRequest[int]("getChatMemberCount", params)
+	req := NewRequestWithChatID[int]("getChatMemberCount", params, params.ChatID)
 	return req.Do(api)
 }
 
 type GetChatMemberP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
-	UserID int `json:"user_id"`
+	UserID int   `json:"user_id"`
 }
 
 func (api *API) GetChatMember(params GetChatMemberP) (ChatMember, error) {
-	req := NewRequest[ChatMember]("getChatMember", params)
+	req := NewRequestWithChatID[ChatMember]("getChatMember", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SetChatStickerSetP struct {
-	ChatID         int    `json:"chat_id"`
+	ChatID         int64  `json:"chat_id"`
 	StickerSetName string `json:"sticker_set_name"`
 }
 
 func (api *API) SetChatStickerSet(params SetChatStickerSetP) (bool, error) {
-	req := NewRequest[bool]("setChatStickerSet", params)
+	req := NewRequestWithChatID[bool]("setChatStickerSet", params, params.ChatID)
 	return req.Do(api)
 }
 
 type DeleteChatStickerSetP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }
 
 func (api *API) DeleteChatStickerSet(params DeleteChatStickerSetP) (bool, error) {
-	req := NewRequest[bool]("deleteChatStickerSet", params)
+	req := NewRequestWithChatID[bool]("deleteChatStickerSet", params, params.ChatID)
 	return req.Do(api)
 }
 
 type GetUserChatBoostsP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
-	UserID int `json:"user_id"`
+	UserID int   `json:"user_id"`
 }
 
 func (api *API) GetUserChatBoosts(params GetUserChatBoostsP) (UserChatBoosts, error) {
-	req := NewRequest[UserChatBoosts]("getUserChatBoosts", params)
+	req := NewRequestWithChatID[UserChatBoosts]("getUserChatBoosts", params, params.ChatID)
 	return req.Do(api)
 }
 
 type GetChatGiftsP struct {
-	ChatID                      int    `json:"chat_id"`
+	ChatID                      int64  `json:"chat_id"`
 	ExcludeUnsaved              bool   `json:"exclude_unsaved,omitempty"`
 	ExcludeSaved                bool   `json:"exclude_saved,omitempty"`
 	ExcludeUnlimited            bool   `json:"exclude_unlimited,omitempty"`
@@ -363,6 +365,6 @@ type GetChatGiftsP struct {
 }
 
 func (api *API) GetChatGifts(params GetChatGiftsP) (OwnedGifts, error) {
-	req := NewRequest[OwnedGifts]("getChatGifts", params)
+	req := NewRequestWithChatID[OwnedGifts]("getChatGifts", params, params.ChatID)
 	return req.Do(api)
 }

tgapi/chat_types.go

@@ -1,7 +1,7 @@
 package tgapi
 
 type Chat struct {
-	ID               int     `json:"id"`
+	ID               int64   `json:"id"`
 	Type             string  `json:"type"`
 	Title            *string `json:"title,omitempty"`
 	Username         *string `json:"username,omitempty"`

tgapi/errors.go

@@ -0,0 +1,7 @@
+package tgapi
+
+import "errors"
+
+var ErrRateLimit = errors.New("rate limit exceeded")
+var ErrPoolUnexpected = errors.New("unexpected response from pool")
+var ErrPoolQueueFull = errors.New("worker pool queue full")

tgapi/forum_methods.go

@@ -1,24 +1,24 @@
 package tgapi
 
 type BaseForumTopicP struct {
-	ChatID          int `json:"chat_id"`
+	ChatID          int64 `json:"chat_id"`
-	MessageThreadID int `json:"message_thread_id"`
+	MessageThreadID int   `json:"message_thread_id"`
 }
 
-func (api *API) GetForumTopicIconSet() ([]Sticker, error) {
+func (api *API) GetForumTopicIconStickers() ([]Sticker, error) {
-	req := NewRequest[[]Sticker]("getForumTopicIconSet", NoParams)
+	req := NewRequest[[]Sticker]("getForumTopicIconStickers", NoParams)
 	return req.Do(api)
 }
 
 type CreateForumTopicP struct {
-	ChatID            int                 `json:"chat_id"`
+	ChatID            int64               `json:"chat_id"`
 	Name              string              `json:"name"`
 	IconColor         ForumTopicIconColor `json:"icon_color"`
 	IconCustomEmojiID string              `json:"icon_custom_emoji_id"`
 }
 
 func (api *API) CreateForumTopic(params CreateForumTopicP) (ForumTopic, error) {
-	req := NewRequest[ForumTopic]("createForumTopic", params)
+	req := NewRequestWithChatID[ForumTopic]("createForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
@@ -29,58 +29,58 @@ type EditForumTopicP struct {
 }
 
 func (api *API) EditForumTopic(params EditForumTopicP) (bool, error) {
-	req := NewRequest[bool]("editForumTopic", params)
+	req := NewRequestWithChatID[bool]("editForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
 func (api *API) CloseForumTopic(params BaseForumTopicP) (bool, error) {
-	req := NewRequest[bool]("closeForumTopic", params)
+	req := NewRequestWithChatID[bool]("closeForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) ReopenForumTopic(params BaseForumTopicP) (bool, error) {
-	req := NewRequest[bool]("reopenForumTopic", params)
+	req := NewRequestWithChatID[bool]("reopenForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) DeleteForumTopic(params BaseForumTopicP) (bool, error) {
-	req := NewRequest[bool]("deleteForumTopic", params)
+	req := NewRequestWithChatID[bool]("deleteForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) UnpinAllForumTopicMessages(params BaseForumTopicP) (bool, error) {
-	req := NewRequest[bool]("unpinAllForumTopicMessages", params)
+	req := NewRequestWithChatID[bool]("unpinAllForumTopicMessages", params, params.ChatID)
 	return req.Do(api)
 }
 
 type BaseGeneralForumTopicP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }
 
 type EditGeneralForumTopicP struct {
-	ChatID int    `json:"chat_id"`
+	ChatID int64  `json:"chat_id"`
 	Name   string `json:"name"`
 }
 
 func (api *API) EditGeneralForumTopic(params EditGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("editGeneralForumTopic", params)
+	req := NewRequestWithChatID[bool]("editGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 
 func (api *API) CloseGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("closeGeneralForumTopic", params)
+	req := NewRequestWithChatID[bool]("closeGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) ReopenGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("reopenGeneralForumTopic", params)
+	req := NewRequestWithChatID[bool]("reopenGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) HideGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("hideGeneralForumTopic", params)
+	req := NewRequestWithChatID[bool]("hideGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) UnhideGeneralForumTopic(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("unhideGeneralForumTopic", params)
+	req := NewRequestWithChatID[bool]("unhideGeneralForumTopic", params, params.ChatID)
 	return req.Do(api)
 }
 func (api *API) UnpinAllGeneralForumTopicMessages(params BaseGeneralForumTopicP) (bool, error) {
-	req := NewRequest[bool]("unpinAllGeneralForumTopicMessages", params)
+	req := NewRequestWithChatID[bool]("unpinAllGeneralForumTopicMessages", params, params.ChatID)
 	return req.Do(api)
 }

tgapi/messages_methods.go

@@ -2,7 +2,7 @@ package tgapi
 
 type SendMessageP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int64  `json:"direct_messages_topic_id,omitempty"`
 
@@ -21,52 +21,52 @@ type SendMessageP struct {
 }
 
 func (api *API) SendMessage(params SendMessageP) (Message, error) {
-	req := NewRequest[Message, SendMessageP]("sendMessage", params)
+	req := NewRequestWithChatID[Message, SendMessageP]("sendMessage", params, params.ChatID)
 	return req.Do(api)
 }
 
 type ForwardMessageP struct {
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
-	MessageThreadID       int `json:"message_thread_id,omitempty"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
-	DirectMessagesTopicID int `json:"direct_messages_topic_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
 
-	MessageID           int  `json:"message_id,omitempty"`
+	MessageID           int   `json:"message_id,omitempty"`
-	FromChatID          int  `json:"from_chat_id,omitempty"`
+	FromChatID          int64 `json:"from_chat_id,omitempty"`
-	VideoStartTimestamp int  `json:"video_start_timestamp,omitempty"`
+	VideoStartTimestamp int   `json:"video_start_timestamp,omitempty"`
-	DisableNotification bool `json:"disable_notification,omitempty"`
+	DisableNotification bool  `json:"disable_notification,omitempty"`
-	ProtectContent      bool `json:"protect_content,omitempty"`
+	ProtectContent      bool  `json:"protect_content,omitempty"`
 
 	MessageEffectID         string                   `json:"message_effect_id,omitempty"`
 	SuggestedPostParameters *SuggestedPostParameters `json:"suggested_post_parameters,omitempty"`
 }
 
 func (api *API) ForwardMessage(params ForwardMessageP) (Message, error) {
-	req := NewRequest[Message]("forwardMessage", params)
+	req := NewRequestWithChatID[Message]("forwardMessage", params, params.ChatID)
 	return req.Do(api)
 }
 
 type ForwardMessagesP struct {
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
-	MessageThreadID       int `json:"message_thread_id,omitempty"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
-	DirectMessagesTopicID int `json:"direct_messages_topic_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
 
-	FromChatID          int   `json:"from_chat_id,omitempty"`
+	FromChatID          int64 `json:"from_chat_id,omitempty"`
 	MessageIDs          []int `json:"message_ids,omitempty"`
 	DisableNotification bool  `json:"disable_notification,omitempty"`
 	ProtectContent      bool  `json:"protect_content,omitempty"`
 }
 
 func (api *API) ForwardMessages(params ForwardMessagesP) ([]int, error) {
-	req := NewRequest[[]int]("forwardMessages", params)
+	req := NewRequestWithChatID[[]int]("forwardMessages", params, params.ChatID)
 	return req.Do(api)
 }
 
 type CopyMessageP struct {
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
-	MessageThreadID       int `json:"message_thread_id,omitempty"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
-	DirectMessagesTopicID int `json:"direct_messages_topic_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
 
-	FromChatID          int       `json:"from_chat_id"`
+	FromChatID          int64     `json:"from_chat_id"`
 	MessageID           int       `json:"message_id"`
 	VideoStartTimestamp int       `json:"video_start_timestamp,omitempty"`
 	Caption             string    `json:"caption,omitempty"`
@@ -85,16 +85,16 @@ type CopyMessageP struct {
 }
 
 func (api *API) CopyMessage(params CopyMessageP) (int, error) {
-	req := NewRequest[int]("copyMessage", params)
+	req := NewRequestWithChatID[int]("copyMessage", params, params.ChatID)
 	return req.Do(api)
 }
 
 type CopyMessagesP struct {
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
-	MessageThreadID       int `json:"message_thread_id,omitempty"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
-	DirectMessagesTopicID int `json:"direct_messages_topic_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
 
-	FromChatID          int   `json:"from_chat_id,omitempty"`
+	FromChatID          int64 `json:"from_chat_id,omitempty"`
 	MessageIDs          []int `json:"message_ids,omitempty"`
 	DisableNotification bool  `json:"disable_notification,omitempty"`
 	ProtectContent      bool  `json:"protect_content,omitempty"`
@@ -102,15 +102,15 @@ type CopyMessagesP struct {
 }
 
 func (api *API) CopyMessages(params CopyMessagesP) ([]int, error) {
-	req := NewRequest[[]int]("copyMessages", params)
+	req := NewRequestWithChatID[[]int]("copyMessages", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendLocationP struct {
-	BusinessConnectionID  int `json:"business_connection_id,omitempty"`
+	BusinessConnectionID  int   `json:"business_connection_id,omitempty"`
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
-	MessageThreadID       int `json:"message_thread_id,omitempty"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
-	DirectMessagesTopicID int `json:"direct_messages_topic_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
 
 	Latitude             float64 `json:"latitude"`
 	Longitude            float64 `json:"longitude"`
@@ -130,15 +130,15 @@ type SendLocationP struct {
 }
 
 func (api *API) SendLocation(params SendLocationP) (Message, error) {
-	req := NewRequest[Message]("sendLocation", params)
+	req := NewRequestWithChatID[Message]("sendLocation", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendVenueP struct {
-	BusinessConnectionID  int `json:"business_connection_id,omitempty"`
+	BusinessConnectionID  int   `json:"business_connection_id,omitempty"`
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
-	MessageThreadID       int `json:"message_thread_id,omitempty"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
-	DirectMessagesTopicID int `json:"direct_messages_topic_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
 
 	Latitude        float64 `json:"latitude"`
 	Longitude       float64 `json:"longitude"`
@@ -160,15 +160,15 @@ type SendVenueP struct {
 }
 
 func (api *API) SendVenue(params SendVenueP) (Message, error) {
-	req := NewRequest[Message]("sendVenue", params)
+	req := NewRequestWithChatID[Message]("sendVenue", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendContactP struct {
-	BusinessConnectionID  int `json:"business_connection_id,omitempty"`
+	BusinessConnectionID  int   `json:"business_connection_id,omitempty"`
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
-	MessageThreadID       int `json:"message_thread_id,omitempty"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
-	DirectMessagesTopicID int `json:"direct_messages_topic_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
 
 	PhoneNumber string `json:"phone_number"`
 	FirstName   string `json:"first_name"`
@@ -186,14 +186,14 @@ type SendContactP struct {
 }
 
 func (api *API) SendContact(params SendContactP) (Message, error) {
-	req := NewRequest[Message]("sendContact", params)
+	req := NewRequestWithChatID[Message]("sendContact", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendPollP struct {
-	BusinessConnectionID int `json:"business_connection_id,omitempty"`
+	BusinessConnectionID int   `json:"business_connection_id,omitempty"`
-	ChatID               int `json:"chat_id"`
+	ChatID               int64 `json:"chat_id"`
-	MessageThreadID      int `json:"message_thread_id,omitempty"`
+	MessageThreadID      int   `json:"message_thread_id,omitempty"`
 
 	Question              string            `json:"question"`
 	QuestionParseMode     ParseMode         `json:"question_mode,omitempty"`
@@ -220,13 +220,13 @@ type SendPollP struct {
 }
 
 func (api *API) SendPoll(params SendPollP) (Message, error) {
-	req := NewRequest[Message]("sendPoll", params)
+	req := NewRequestWithChatID[Message]("sendPoll", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendChecklistP struct {
 	BusinessConnectionID int            `json:"business_connection_id"`
-	ChatID               int            `json:"chat_id"`
+	ChatID               int64          `json:"chat_id"`
 	Checklist            InputChecklist `json:"checklist"`
 
 	DisableNotification bool   `json:"disable_notification,omitempty"`
@@ -238,15 +238,15 @@ type SendChecklistP struct {
 }
 
 func (api *API) SendChecklist(params SendChecklistP) (Message, error) {
-	req := NewRequest[Message]("sendChecklist", params)
+	req := NewRequestWithChatID[Message]("sendChecklist", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendDiceP struct {
-	BusinessConnectionID  int `json:"business_connection_id,omitempty"`
+	BusinessConnectionID  int   `json:"business_connection_id,omitempty"`
-	ChatID                int `json:"chat_id"`
+	ChatID                int64 `json:"chat_id"`
-	MessageThreadID       int `json:"message_thread_id,omitempty"`
+	MessageThreadID       int   `json:"message_thread_id,omitempty"`
-	DirectMessagesTopicID int `json:"direct_messages_topic_id,omitempty"`
+	DirectMessagesTopicID int   `json:"direct_messages_topic_id,omitempty"`
 
 	Emoji string `json:"emoji,omitempty"`
 
@@ -261,12 +261,12 @@ type SendDiceP struct {
 }
 
 func (api *API) SendDice(params SendDiceP) (Message, error) {
-	req := NewRequest[Message]("sendDice", params)
+	req := NewRequestWithChatID[Message]("sendDice", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendMessageDraftP struct {
-	ChatID          int             `json:"chat_id"`
+	ChatID          int64           `json:"chat_id"`
 	MessageThreadID int             `json:"message_thread_id,omitempty"`
 	DraftID         uint64          `json:"draft_id"`
 	Text            string          `json:"text"`
@@ -275,31 +275,31 @@ type SendMessageDraftP struct {
 }
 
 func (api *API) SendMessageDraft(params SendMessageDraftP) (bool, error) {
-	req := NewRequest[bool]("sendMessageDraft", params)
+	req := NewRequestWithChatID[bool]("sendMessageDraft", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SendChatActionP struct {
 	BusinessConnectionID string         `json:"business_connection_id,omitempty"`
-	ChatID               int            `json:"chat_id"`
+	ChatID               int64          `json:"chat_id"`
 	MessageThreadID      int            `json:"message_thread_id,omitempty"`
 	Action               ChatActionType `json:"action"`
 }
 
 func (api *API) SendChatAction(params SendChatActionP) (bool, error) {
-	req := NewRequest[bool]("sendChatAction", params)
+	req := NewRequestWithChatID[bool]("sendChatAction", params, params.ChatID)
 	return req.Do(api)
 }
 
 type SetMessageReactionP struct {
-	ChatId    int            `json:"chat_id"`
+	ChatID    int64          `json:"chat_id"`
 	MessageId int            `json:"message_id"`
 	Reaction  []ReactionType `json:"reaction"`
 	IsBig     bool           `json:"is_big,omitempty"`
 }
 
 func (api *API) SetMessageReaction(params SetMessageReactionP) (bool, error) {
-	req := NewRequest[bool]("setMessageReaction", params)
+	req := NewRequestWithChatID[bool]("setMessageReaction", params, params.ChatID)
 	return req.Do(api)
 }
 
@@ -307,7 +307,7 @@ func (api *API) SetMessageReaction(params SetMessageReactionP) (bool, error) {
 
 type EditMessageTextP struct {
 	BusinessConnectionID string       `json:"business_connection_id,omitempty"`
-	ChatID               int          `json:"chat_id,omitempty"`
+	ChatID               int64        `json:"chat_id,omitempty"`
 	MessageID            int          `json:"message_id,omitempty"`
 	InlineMessageID      string       `json:"inline_message_id,omitempty"`
 	Text                 string       `json:"text"`
@@ -320,18 +320,18 @@ type EditMessageTextP struct {
 func (api *API) EditMessageText(params EditMessageTextP) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
-		req := NewRequest[bool]("editMessageText", params)
+		req := NewRequestWithChatID[bool]("editMessageText", params, params.ChatID)
 		res, err := req.Do(api)
 		return zero, res, err
 	}
-	req := NewRequest[Message]("editMessageText", params)
+	req := NewRequestWithChatID[Message]("editMessageText", params, params.ChatID)
 	res, err := req.Do(api)
 	return res, false, err
 }
 
 type EditMessageCaptionP struct {
 	BusinessConnectionID string       `json:"business_connection_id,omitempty"`
-	ChatID               int          `json:"chat_id,omitempty"`
+	ChatID               int64        `json:"chat_id,omitempty"`
 	MessageID            int          `json:"message_id,omitempty"`
 	InlineMessageID      string       `json:"inline_message_id,omitempty"`
 	Caption              string       `json:"caption"`
@@ -344,18 +344,18 @@ type EditMessageCaptionP struct {
 func (api *API) EditMessageCaption(params EditMessageCaptionP) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
-		req := NewRequest[bool]("editMessageCaption", params)
+		req := NewRequestWithChatID[bool]("editMessageCaption", params, params.ChatID)
 		res, err := req.Do(api)
 		return zero, res, err
 	}
-	req := NewRequest[Message]("editMessageCaption", params)
+	req := NewRequestWithChatID[Message]("editMessageCaption", params, params.ChatID)
 	res, err := req.Do(api)
 	return res, false, err
 }
 
 type EditMessageMediaP struct {
 	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
-	ChatID               int                   `json:"chat_id,omitempty"`
+	ChatID               int64                 `json:"chat_id,omitempty"`
 	MessageID            int                   `json:"message_id,omitempty"`
 	InlineMessageID      string                `json:"inline_message_id,omitempty"`
 	Message              InputMedia            `json:"message"`
@@ -367,18 +367,18 @@ type EditMessageMediaP struct {
 func (api *API) EditMessageMedia(params EditMessageMediaP) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
-		req := NewRequest[bool]("editMessageMedia", params)
+		req := NewRequestWithChatID[bool]("editMessageMedia", params, params.ChatID)
 		res, err := req.Do(api)
 		return zero, res, err
 	}
-	req := NewRequest[Message]("editMessageMedia", params)
+	req := NewRequestWithChatID[Message]("editMessageMedia", params, params.ChatID)
 	res, err := req.Do(api)
 	return res, false, err
 }
 
 type EditMessageLiveLocationP struct {
 	BusinessConnectionID string `json:"business_connection_id,omitempty"`
-	ChatID               int    `json:"chat_id,omitempty"`
+	ChatID               int64  `json:"chat_id,omitempty"`
 	MessageID            int    `json:"message_id,omitempty"`
 	InlineMessageID      string `json:"inline_message_id,omitempty"`
 
@@ -396,18 +396,18 @@ type EditMessageLiveLocationP struct {
 func (api *API) EditMessageLiveLocation(params EditMessageLiveLocationP) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
-		req := NewRequest[bool]("editMessageLiveLocation", params)
+		req := NewRequestWithChatID[bool]("editMessageLiveLocation", params, params.ChatID)
 		res, err := req.Do(api)
 		return zero, res, err
 	}
-	req := NewRequest[Message]("editMessageLiveLocation", params)
+	req := NewRequestWithChatID[Message]("editMessageLiveLocation", params, params.ChatID)
 	res, err := req.Do(api)
 	return res, false, err
 }
 
 type StopMessageLiveLocationP struct {
 	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
-	ChatID               int                   `json:"chat_id,omitempty"`
+	ChatID               int64                 `json:"chat_id,omitempty"`
 	MessageID            int                   `json:"message_id,omitempty"`
 	InlineMessageID      string                `json:"inline_message_id,omitempty"`
 	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
@@ -418,31 +418,31 @@ type StopMessageLiveLocationP struct {
 func (api *API) StopMessageLiveLocation(params StopMessageLiveLocationP) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
-		req := NewRequest[bool]("stopMessageLiveLocation", params)
+		req := NewRequestWithChatID[bool]("stopMessageLiveLocation", params, params.ChatID)
 		res, err := req.Do(api)
 		return zero, res, err
 	}
-	req := NewRequest[Message]("stopMessageLiveLocation", params)
+	req := NewRequestWithChatID[Message]("stopMessageLiveLocation", params, params.ChatID)
 	res, err := req.Do(api)
 	return res, false, err
 }
 
 type EditMessageChecklistP struct {
 	BusinessConnectionID string                `json:"business_connection_id"`
-	ChatID               int                   `json:"chat_id"`
+	ChatID               int64                 `json:"chat_id"`
 	MessageID            int                   `json:"message_id"`
 	Checklist            InputChecklist        `json:"checklist"`
 	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
 }
 
 func (api *API) EditMessageChecklist(params EditMessageChecklistP) (Message, error) {
-	req := NewRequest[Message]("editMessageChecklist", params)
+	req := NewRequestWithChatID[Message]("editMessageChecklist", params, params.ChatID)
 	return req.Do(api)
 }
 
 type EditMessageReplyMarkupP struct {
 	BusinessConnectionID string                `json:"business_connection_id,omitempty"`
-	ChatID               int                   `json:"chat_id,omitempty"`
+	ChatID               int64                 `json:"chat_id,omitempty"`
 	MessageID            int                   `json:"message_id,omitempty"`
 	InlineMessageID      string                `json:"inline_message_id,omitempty"`
 	ReplyMarkup          *InlineKeyboardMarkup `json:"reply_markup,omitempty"`
@@ -451,66 +451,66 @@ type EditMessageReplyMarkupP struct {
 func (api *API) EditMessageReplyMarkup(params EditMessageReplyMarkupP) (Message, bool, error) {
 	var zero Message
 	if params.InlineMessageID != "" {
-		req := NewRequest[bool]("editMessageReplyMarkup", params)
+		req := NewRequestWithChatID[bool]("editMessageReplyMarkup", params, params.ChatID)
 		res, err := req.Do(api)
 		return zero, res, err
 	}
-	req := NewRequest[Message]("editMessageReplyMarkup", params)
+	req := NewRequestWithChatID[Message]("editMessageReplyMarkup", params, params.ChatID)
 	res, err := req.Do(api)
 	return res, false, err
 }
 
 type StopPollP struct {
 	BusinessConnectionID string `json:"business_connection_id,omitempty"`
-	ChatID               int    `json:"chat_id"`
+	ChatID               int64  `json:"chat_id"`
 	MessageID            int    `json:"message_id"`
 	InlineMessageID      string `json:"inline_message_id,omitempty"`
 }
 
 func (api *API) StopPoll(params StopPollP) (Poll, error) {
-	req := NewRequest[Poll]("stopPoll", params)
+	req := NewRequestWithChatID[Poll]("stopPoll", params, params.ChatID)
 	return req.Do(api)
 }
 
 type ApproveSuggestedPostP struct {
-	ChatID    int `json:"chat_id"`
+	ChatID    int64 `json:"chat_id"`
-	MessageID int `json:"message_id"`
+	MessageID int   `json:"message_id"`
-	SendDate  int `json:"send_date,omitempty"`
+	SendDate  int   `json:"send_date,omitempty"`
 }
 
 func (api *API) ApproveSuggestedPost(params ApproveSuggestedPostP) (bool, error) {
-	req := NewRequest[bool]("approveSuggestedPost", params)
+	req := NewRequestWithChatID[bool]("approveSuggestedPost", params, params.ChatID)
 	return req.Do(api)
 }
 
 type DeclineSuggestedPostP struct {
-	ChatID    int    `json:"chat_id"`
+	ChatID    int64  `json:"chat_id"`
 	MessageID int    `json:"message_id"`
 	Comment   string `json:"comment,omitempty"`
 }
 
 func (api *API) DeclineSuggestedPost(params DeclineSuggestedPostP) (bool, error) {
-	req := NewRequest[bool]("declineSuggestedPost", params)
+	req := NewRequestWithChatID[bool]("declineSuggestedPost", params, params.ChatID)
 	return req.Do(api)
 }
 
 type DeleteMessageP struct {
-	ChatID    int `json:"chat_id"`
+	ChatID    int64 `json:"chat_id"`
-	MessageID int `json:"message_id"`
+	MessageID int   `json:"message_id"`
 }
 
 func (api *API) DeleteMessage(params DeleteMessageP) (bool, error) {
-	req := NewRequest[bool]("deleteMessage", params)
+	req := NewRequestWithChatID[bool]("deleteMessage", params, params.ChatID)
 	return req.Do(api)
 }
 
 type DeleteMessagesP struct {
-	ChatID     int   `json:"chat_id"`
+	ChatID     int64 `json:"chat_id"`
 	MessageIDs []int `json:"message_ids"`
 }
 
 func (api *API) DeleteMessages(params DeleteMessagesP) (bool, error) {
-	req := NewRequest[bool]("deleteMessages", params)
+	req := NewRequestWithChatID[bool]("deleteMessages", params, params.ChatID)
 	return req.Do(api)
 }
 

tgapi/methods.go

@@ -12,6 +12,7 @@ const (
 	ParseMDV2 ParseMode = "MarkdownV2"
 	ParseHTML ParseMode = "HTML"
 	ParseMD   ParseMode = "Markdown"
+	ParseNone ParseMode = "None"
 )
 
 type EmptyParams struct{}
@@ -57,6 +58,8 @@ func (api *API) GetFileByLink(link string) ([]byte, error) {
 	if err != nil {
 		return nil, err
 	}
-	defer res.Body.Close()
+	defer func() {
+		_ = res.Body.Close()
+	}()
 	return io.ReadAll(res.Body)
 }

tgapi/pool.go

@@ -2,91 +2,141 @@ package tgapi
 
 import (
 	"context"
-	"errors"
 	"sync"
 )
 
-var ErrPoolQueueFull = errors.New("worker pool queue full")
+// workerPool — приватная структура, управляющая пулом воркеров.
-
+// Внешний код не может создавать или напрямую взаимодействовать с этой структурой.
-type RequestEnvelope struct {
+// Используется только через экспортируемые методы newWorkerPool, start, stop, submit.
-	DoFunc   func(context.Context) (any, error) // функция, которая выполнит запрос и вернет any
+type workerPool struct {
-	ResultCh chan RequestResult                 // канал для результата
+	taskCh    chan requestEnvelope // канал для принятия задач (буферизованный)
-}
+	queueSize int                  // максимальный размер очереди
-type RequestResult struct {
+	workers   int                  // количество воркеров (горутин)
-	Value any
+	wg        sync.WaitGroup       // синхронизирует завершение всех воркеров при остановке
-	Err   error
+	quit      chan struct{}        // канал для сигнала остановки
+	started   bool                 // флаг, указывающий, запущен ли пул
+	startedMu sync.Mutex           // мьютекс для безопасного доступа к started
 }
 
-// WorkerPool управляет воркерами и очередью
+// requestEnvelope — приватная структура, инкапсулирующая задачу и канал для результата.
-type WorkerPool struct {
+// Используется только внутри пакета для передачи задач воркерам.
-	taskCh    chan RequestEnvelope
+type requestEnvelope struct {
-	queueSize int
+	doFunc   func(context.Context) (any, error) // функция, выполняющая запрос
-	workers   int
+	resultCh chan requestResult                 // канал, через который воркер вернёт результат
-	wg        sync.WaitGroup
-	quit      chan struct{}
-	started   bool
-	startedMu sync.Mutex
 }
 
-func NewWorkerPool(workers int, queueSize int) *WorkerPool {
+// requestResult — приватная структура, представляющая результат выполнения задачи.
-	return &WorkerPool{
+// Внешний код получает его через канал, но не знает структуры — только через <-chan requestResult.
-		taskCh:    make(chan RequestEnvelope, queueSize),
+type requestResult struct {
+	value any   // значение, возвращённое задачей
+	err   error // ошибка, если возникла
+}
+
+// newWorkerPool создаёт новый пул воркеров с заданным количеством горутин и размером очереди.
+// Это единственный способ создать workerPool — внешний код не может создать его напрямую.
+func newWorkerPool(workers int, queueSize int) *workerPool {
+	if workers <= 0 {
+		workers = 1 // защита от некорректных значений
+	}
+	if queueSize <= 0 {
+		queueSize = 100 // разумный дефолт
+	}
+
+	return &workerPool{
+		taskCh:    make(chan requestEnvelope, queueSize),
 		queueSize: queueSize,
 		workers:   workers,
 		quit:      make(chan struct{}),
 	}
 }
 
-// Start запускает воркеров
+// start запускает воркеры (горутины), которые будут обрабатывать задачи из очереди.
-func (p *WorkerPool) Start(ctx context.Context) {
+// Метод идемпотентен: если пул уже запущен — ничего не делает.
+// Должен вызываться перед первым вызовом submit.
+func (p *workerPool) start(ctx context.Context) {
 	p.startedMu.Lock()
 	defer p.startedMu.Unlock()
 	if p.started {
-		return
+		return // уже запущен — ничего не делаем
 	}
 	p.started = true
+
+	// Запускаем воркеры — каждый будет обрабатывать задачи в бесконечном цикле
 	for i := 0; i < p.workers; i++ {
 		p.wg.Add(1)
-		go p.worker(ctx)
+		go p.worker(ctx) // запускаем горутину с контекстом
 	}
 }
 
-// Stop останавливает пул (ждет завершения текущих задач)
+// stop останавливает пул воркеров.
-func (p *WorkerPool) Stop() {
+// Отправляет сигнал остановки через quit-канал и ждёт завершения всех активных задач.
-	close(p.quit)
+// Безопасно вызывать многократно — после остановки повторные вызовы не имеют эффекта.
-	p.wg.Wait()
+func (p *workerPool) stop() {
+	close(p.quit) // сигнал для всех воркеров — выйти из цикла
+	p.wg.Wait()   // ждём, пока все воркеры завершатся
 }
 
-// Submit отправляет задачу в очередь и возвращает канал для результата
+// submit отправляет задачу в очередь и возвращает канал, через который будет получен результат.
-func (p *WorkerPool) Submit(ctx context.Context, do func(context.Context) (any, error)) (<-chan RequestResult, error) {
+// Если очередь переполнена — возвращает ErrPoolQueueFull.
+// Канал результата имеет буфер 1, чтобы не блокировать воркера при записи.
+// Контекст используется для отмены задачи, если клиент отменил запрос до отправки.
+func (p *workerPool) submit(ctx context.Context, do func(context.Context) (any, error)) (<-chan requestResult, error) {
+	// Проверяем, не превышена ли очередь
 	if len(p.taskCh) >= p.queueSize {
 		return nil, ErrPoolQueueFull
 	}
 
-	resultCh := make(chan RequestResult, 1) // буфер 1, чтобы не блокировать воркера
+	// Создаём канал для результата — буферизованный, чтобы не блокировать воркера
-	envelope := RequestEnvelope{do, resultCh}
+	resultCh := make(chan requestResult, 1)
+
+	// Создаём обёртку задачи
+	envelope := requestEnvelope{
+		doFunc:   do,
+		resultCh: resultCh,
+	}
+
+	// Пытаемся отправить задачу в очередь
 	select {
 	case <-ctx.Done():
+		// Клиент отменил операцию до отправки — возвращаем ошибку отмены
 		return nil, ctx.Err()
 	case p.taskCh <- envelope:
+		// Успешно отправлено — возвращаем канал для чтения результата
 		return resultCh, nil
 	default:
+		// Очередь переполнена — не должно происходить при проверке len(p.taskCh), но на всякий случай
 		return nil, ErrPoolQueueFull
 	}
 }
 
-// worker выполняет задачи
+// worker — приватная горутина, выполняющая задачи из очереди.
-func (p *WorkerPool) worker(ctx context.Context) {
+// Каждый воркер работает в бесконечном цикле, пока не получит сигнал остановки.
-	defer p.wg.Done()
+// При получении задачи:
+//   - вызывает doFunc с контекстом
+//   - записывает результат в resultCh
+//   - закрывает канал, чтобы клиент мог прочитать и завершить
+//
+// После закрытия quit-канала — воркер завершает работу.
+func (p *workerPool) worker(ctx context.Context) {
+	defer p.wg.Done() // уменьшаем WaitGroup при завершении горутины
+
 	for {
 		select {
 		case <-p.quit:
+			// Получен сигнал остановки — выходим из цикла
 			return
+
 		case envelope := <-p.taskCh:
-			// Выполняем задачу с переданным контекстом (или можно использовать свой)
+			// Выполняем задачу с переданным контекстом (клиентский или общий)
-			val, err := envelope.DoFunc(ctx)
+			value, err := envelope.doFunc(ctx)
-			envelope.ResultCh <- RequestResult{Value: val, Err: err}
+
-			close(envelope.ResultCh)
+			// Записываем результат в канал — не блокируем, т.к. буфер 1
+			envelope.resultCh <- requestResult{
+				value: value,
+				err:   err,
+			}
+			// Закрываем канал — клиент знает, что результат пришёл и больше не будет
+			close(envelope.resultCh)
 		}
 	}
 }

tgapi/stickers_methods.go

@@ -2,7 +2,7 @@ package tgapi
 
 type SendStickerP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -15,7 +15,7 @@ type SendStickerP struct {
 }
 
 func (api *API) SendSticker(params SendStickerP) (Message, error) {
-	req := NewRequest[Message]("sendSticker", params)
+	req := NewRequestWithChatID[Message]("sendSticker", params, params.ChatID)
 	return req.Do(api)
 }
 

tgapi/types.go

@@ -261,20 +261,20 @@ type Gifts struct {
 	Gifts []Gift `json:"gifts"`
 }
 
+type OwnedGiftType string
+
 const (
 	OwnedGiftRegularType OwnedGiftType = "regular"
 	OwnedGiftUniqueType  OwnedGiftType = "unique"
 )
 
-type OwnedGiftType string
+type OwnedGift struct {
-type BaseOwnedGift struct {
 	Type        OwnedGiftType `json:"type"`
 	OwnerGiftID *string       `json:"owner_gift_id,omitempty"`
 	SendDate    *int          `json:"send_date,omitempty"`
 	IsSaved     *bool         `json:"is_saved,omitempty"`
-}
+
-type OwnedGiftRegular struct {
+	// Поля, характерные для "regular"
-	BaseOwnedGift
 	Gift                    Gift            `json:"gift"`
 	SenderUser              User            `json:"sender_user,omitempty"`
 	Text                    string          `json:"text,omitempty"`
@@ -286,18 +286,15 @@ type OwnedGiftRegular struct {
 	PrepaidUpgradeStarCount *int            `json:"prepaid_upgrade_star_count,omitempty"`
 	IsUpgradeSeparate       *bool           `json:"is_upgrade_separate,omitempty"`
 	UniqueGiftNumber        *int            `json:"unique_gift_number,omitempty"`
-}
+
-type OwnedGiftUnique struct {
+	// Поля, характерные для "unique"
-	BaseOwnedGift
 	CanBeTransferred  *bool `json:"can_be_transferred,omitempty"`
 	TransferStarCount *int  `json:"transfer_star_count,omitempty"`
 	NextTransferDate  *int  `json:"next_transfer_date,omitempty"`
 }
+
 type OwnedGifts struct {
-	TotalCount int `json:"total_count"`
+	TotalCount int         `json:"total_count"`
-	Gifts      []struct {
+	Gifts      []OwnedGift `json:"gifts"`
-		OwnedGiftRegular
+	NextOffset string      `json:"next_offset"`
-		OwnedGiftUnique
-	} `json:"gifts"`
-	NextOffset string `json:"next_offset"`
 }

tgapi/uploader_api.go

@@ -8,6 +8,7 @@ import (
 	"mime/multipart"
 	"net/http"
 	"path/filepath"
+	"time"
 
 	"git.nix13.pw/scuroneko/laniakea/utils"
 	"git.nix13.pw/scuroneko/slog"
@@ -59,24 +60,17 @@ type UploaderRequest[R, P any] struct {
 	method string
 	files  []UploaderFile
 	params P
+	chatId int64
 }
 
 func NewUploaderRequest[R, P any](method string, params P, files ...UploaderFile) UploaderRequest[R, P] {
-	return UploaderRequest[R, P]{method, files, params}
+	return UploaderRequest[R, P]{method: method, files: files, params: params, chatId: 0}
+}
+func NewUploaderRequestWithChatID[R, P any](method string, params P, chatId int64, files ...UploaderFile) UploaderRequest[R, P] {
+	return UploaderRequest[R, P]{method: method, files: files, params: params, chatId: chatId}
 }
 func (r UploaderRequest[R, P]) doRequest(ctx context.Context, up *Uploader) (R, error) {
 	var zero R
-	if up.api.limiter != nil {
-		if up.api.dropOverflowLimit {
-			if !up.api.limiter.Allow() {
-				return zero, errors.New("rate limited")
-			}
-		} else {
-			if err := up.api.limiter.Wait(ctx); err != nil {
-				return zero, err
-			}
-		}
-	}
 
 	buf, contentType, err := prepareMultipart(r.files, r.params)
 	if err != nil {
@@ -95,26 +89,66 @@ func (r UploaderRequest[R, P]) doRequest(ctx context.Context, up *Uploader) (R,
 	req.Header.Set("Content-Type", contentType)
 	req.Header.Set("Accept", "application/json")
 	req.Header.Set("User-Agent", fmt.Sprintf("Laniakea/%s", utils.VersionString))
+	req.Header.Set("Accept-Encoding", "gzip")
+	req.ContentLength = int64(buf.Len())
 
-	up.logger.Debugln("UPLOADER REQ", r.method)
+	for {
-	res, err := up.api.client.Do(req)
+		if up.api.Limiter != nil {
-	if err != nil {
+			if up.api.dropOverflowLimit {
-		return zero, err
+				if !up.api.Limiter.GlobalAllow() {
+					return zero, errors.New("rate limited")
+				}
+			} else {
+				if err := up.api.Limiter.GlobalWait(ctx); err != nil {
+					return zero, err
+				}
+			}
+		}
+
+		up.logger.Debugln("UPLOADER REQ", r.method)
+		resp, err := up.api.client.Do(req)
+		if err != nil {
+			return zero, err
+		}
+
+		body, err := readBody(resp.Body)
+		_ = resp.Body.Close()
+		if err != nil {
+			return zero, err
+		}
+		up.logger.Debugln("UPLOADER RES", r.method, string(body))
+
+		response, err := parseBody[R](body)
+		if err != nil {
+			return zero, err
+		}
+
+		if !response.Ok {
+			if response.ErrorCode == 429 && response.Parameters != nil && response.Parameters.RetryAfter != nil {
+				after := *response.Parameters.RetryAfter
+				up.logger.Warnf("Rate limited, retry after %d seconds (chat: %d)", after, r.chatId)
+				if r.chatId > 0 {
+					up.api.Limiter.SetChatLock(r.chatId, after)
+				} else {
+					up.api.Limiter.SetGlobalLock(after)
+				}
+
+				select {
+				case <-ctx.Done():
+					return zero, ctx.Err()
+				case <-time.After(time.Duration(after) * time.Second):
+					continue // Повторяем запрос
+				}
+			}
+			return zero, fmt.Errorf("[%d] %s", response.ErrorCode, response.Description)
+		}
+		return response.Result, nil
 	}
-	defer res.Body.Close()
-
-	body, err := readBody(res.Body)
-	up.logger.Debugln("UPLOADER RES", r.method, string(body))
-	if res.StatusCode != http.StatusOK {
-		return zero, fmt.Errorf("unexpected status code: %d, %s", res.StatusCode, string(body))
-	}
-
-	return parseBody[R](body)
 }
 func (r UploaderRequest[R, P]) DoWithContext(ctx context.Context, up *Uploader) (R, error) {
 	var zero R
 
-	result, err := up.api.pool.Submit(ctx, func(ctx context.Context) (any, error) {
+	result, err := up.api.pool.submit(ctx, func(ctx context.Context) (any, error) {
 		return r.doRequest(ctx, up)
 	})
 	if err != nil {
@@ -125,10 +159,10 @@ func (r UploaderRequest[R, P]) DoWithContext(ctx context.Context, up *Uploader)
 	case <-ctx.Done():
 		return zero, ctx.Err()
 	case res := <-result:
-		if res.Err != nil {
+		if res.err != nil {
-			return zero, res.Err
+			return zero, res.err
 		}
-		if val, ok := res.Value.(R); ok {
+		if val, ok := res.value.(R); ok {
 			return val, nil
 		}
 		return zero, ErrPoolUnexpected
@@ -145,24 +179,29 @@ func prepareMultipart[P any](files []UploaderFile, params P) (*bytes.Buffer, str
 	for _, file := range files {
 		fw, err := w.CreateFormFile(string(file.field), file.filename)
 		if err != nil {
-			_ = w.Close()
+			_ = w.Close() // Закрываем, чтобы не было утечки
-			return buf, w.FormDataContentType(), err
+			return nil, "", err
 		}
 
 		_, err = fw.Write(file.data)
 		if err != nil {
 			_ = w.Close()
-			return buf, w.FormDataContentType(), err
+			return nil, "", err
 		}
 	}
 
-	err := utils.Encode(w, params)
+	err := utils.Encode(w, params) // Предполагается, что это записывает в w
 	if err != nil {
 		_ = w.Close()
-		return buf, w.FormDataContentType(), err
+		return nil, "", err
 	}
-	err = w.Close()
+
-	return buf, w.FormDataContentType(), err
+	err = w.Close() // ✅ ОБЯЗАТЕЛЬНО вызвать в конце — иначе запрос битый!
+	if err != nil {
+		return nil, "", err
+	}
+
+	return buf, w.FormDataContentType(), nil
 }
 
 func uploaderTypeByExt(filename string) UploaderFileType {

tgapi/uploader_methods.go

@@ -2,7 +2,7 @@ package tgapi
 
 type UploadPhotoP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -23,13 +23,13 @@ type UploadPhotoP struct {
 }
 
 func (u *Uploader) UploadPhoto(params UploadPhotoP, file UploaderFile) (Message, error) {
-	req := NewUploaderRequest[Message]("sendPhoto", params, file)
+	req := NewUploaderRequestWithChatID[Message]("sendPhoto", params, params.ChatID, file)
 	return req.Do(u)
 }
 
 type UploadAudioP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -52,13 +52,13 @@ type UploadAudioP struct {
 }
 
 func (u *Uploader) UploadAudio(params UploadAudioP, files ...UploaderFile) (Message, error) {
-	req := NewUploaderRequest[Message]("sendAudio", params, files...)
+	req := NewUploaderRequestWithChatID[Message]("sendAudio", params, params.ChatID, files...)
 	return req.Do(u)
 }
 
 type UploadDocumentP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -84,7 +84,7 @@ func (u *Uploader) UploadDocument(params UploadDocumentP, files ...UploaderFile)
 
 type UploadVideoP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -117,7 +117,7 @@ func (u *Uploader) UploadVideo(params UploadVideoP, files ...UploaderFile) (Mess
 
 type UploadAnimationP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -148,7 +148,7 @@ func (u *Uploader) UploadAnimation(params UploadAnimationP, files ...UploaderFil
 
 type UploadVoiceP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -174,7 +174,7 @@ func (u *Uploader) UploadVoice(params UploadVoiceP, files ...UploaderFile) (Mess
 
 type UploadVideoNoteP struct {
 	BusinessConnectionID  string `json:"business_connection_id,omitempty"`
-	ChatID                int    `json:"chat_id"`
+	ChatID                int64  `json:"chat_id"`
 	MessageThreadID       int    `json:"message_thread_id,omitempty"`
 	DirectMessagesTopicID int    `json:"direct_messages_topic_id,omitempty"`
 
@@ -197,7 +197,7 @@ func (u *Uploader) UploadVideoNote(params UploadVideoNoteP, files ...UploaderFil
 }
 
 type UploadChatPhotoP struct {
-	ChatID int `json:"chat_id"`
+	ChatID int64 `json:"chat_id"`
 }
 
 func (u *Uploader) UploadChatPhoto(params UploadChatPhotoP, photo UploaderFile) (Message, error) {

utils.go

@@ -1,6 +1,10 @@
 package laniakea
 
-import "git.nix13.pw/scuroneko/laniakea/utils"
+import (
+	"strings"
+
+	"git.nix13.pw/scuroneko/laniakea/utils"
+)
 
 func Ptr[T any](v T) *T { return &v }
 func Val[T any](p *T, def T) T {
@@ -9,7 +13,45 @@ func Val[T any](p *T, def T) T {
 	}
 	return def
 }
-func EscapeMarkdown(s string) string   { return utils.EscapeMarkdown(s) }
-func EscapeMarkdownV2(s string) string { return utils.EscapeMarkdownV2(s) }
 
-const VersionString = utils.VersionString
+// EscapeMarkdown
+// Deprecated. Use MarkdownV2
+func EscapeMarkdown(s string) string {
+	s = strings.ReplaceAll(s, "_", `\_`)
+	s = strings.ReplaceAll(s, "*", `\*`)
+	s = strings.ReplaceAll(s, "[", `\[`)
+	return strings.ReplaceAll(s, "`", "\\`")
+}
+
+// EscapeHTML escapes special characters for Telegram HTML parse mode.
+func EscapeHTML(s string) string {
+	s = strings.ReplaceAll(s, "&", "&")
+	s = strings.ReplaceAll(s, "<", "&lt;")
+	s = strings.ReplaceAll(s, ">", "&gt;")
+	return s
+}
+
+// EscapeMarkdownV2 escapes special characters for Telegram MarkdownV2.
+// https://core.telegram.org/bots/api#markdownv2-style
+func EscapeMarkdownV2(s string) string {
+	symbols := []string{"\\", "_", "*", "[", "]", "(", ")", "~", "`", ">", "#", "+", "-", "=", "|", "{", "}", ".", "!"}
+	for _, symbol := range symbols {
+		s = strings.ReplaceAll(s, symbol, "\\"+symbol)
+	}
+	return s
+}
+func EscapePunctuation(s string) string {
+	symbols := []string{".", "!", "-"}
+	for _, symbol := range symbols {
+		s = strings.ReplaceAll(s, symbol, "\\"+symbol)
+	}
+	return s
+}
+
+const (
+	VersionString = utils.VersionString
+	VersionMajor  = utils.VersionMajor
+	VersionMinor  = utils.VersionMinor
+	VersionPatch  = utils.VersionPatch
+	VersionBeta   = utils.VersionBeta
+)

utils/limiter.go

@@ -0,0 +1,204 @@
+package utils
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"time"
+
+	"golang.org/x/time/rate"
+)
+
+var ErrDropOverflow = errors.New("drop overflow limit")
+
+// RateLimiter implements per-chat and global rate limiting with optional blocking.
+// It supports two modes:
+//   - "drop" mode: immediately reject if limits are exceeded.
+//   - "wait" mode: block until capacity is available.
+type RateLimiter struct {
+	globalLockUntil time.Time     // global cooldown timestamp (set by API errors)
+	globalLimiter   *rate.Limiter // global token bucket (30 req/sec)
+	globalMu        sync.RWMutex  // protects globalLockUntil and globalLimiter
+
+	chatLocks    map[int64]time.Time     // per-chat cooldown timestamps
+	chatLimiters map[int64]*rate.Limiter // per-chat token buckets (1 req/sec)
+	chatMu       sync.Mutex              // protects chatLocks and chatLimiters
+}
+
+// NewRateLimiter creates a new RateLimiter with default limits.
+// Global: 30 requests per second, burst 30.
+// Per-chat: 1 request per second, burst 1.
+func NewRateLimiter() *RateLimiter {
+	return &RateLimiter{
+		globalLimiter: rate.NewLimiter(30, 30),
+		chatLimiters:  make(map[int64]*rate.Limiter),
+		chatLocks:     make(map[int64]time.Time),
+	}
+}
+
+// SetGlobalLock sets a global cooldown period (e.g., after receiving 429 from Telegram).
+// If retryAfter <= 0, no lock is applied.
+func (rl *RateLimiter) SetGlobalLock(retryAfter int) {
+	if retryAfter <= 0 {
+		return
+	}
+	rl.globalMu.Lock()
+	defer rl.globalMu.Unlock()
+	rl.globalLockUntil = time.Now().Add(time.Duration(retryAfter) * time.Second)
+}
+
+// SetChatLock sets a cooldown for a specific chat (e.g., after 429 for that chat).
+// If retryAfter <= 0, no lock is applied.
+func (rl *RateLimiter) SetChatLock(chatID int64, retryAfter int) {
+	if retryAfter <= 0 {
+		return
+	}
+	rl.chatMu.Lock()
+	defer rl.chatMu.Unlock()
+	rl.chatLocks[chatID] = time.Now().Add(time.Duration(retryAfter) * time.Second)
+}
+
+// GlobalWait blocks until a global request can be made.
+// Waits for both global cooldown and token bucket availability.
+func (rl *RateLimiter) GlobalWait(ctx context.Context) error {
+	if err := rl.waitForGlobalUnlock(ctx); err != nil {
+		return err
+	}
+	return rl.globalLimiter.Wait(ctx)
+}
+
+// Wait blocks until a request for the given chat can be made.
+// Waits for: chat cooldown → global cooldown → chat token bucket.
+// Note: Global limit is checked *before* chat limit to avoid overloading upstream.
+func (rl *RateLimiter) Wait(ctx context.Context, chatID int64) error {
+	if err := rl.waitForChatUnlock(ctx, chatID); err != nil {
+		return err
+	}
+	if err := rl.waitForGlobalUnlock(ctx); err != nil {
+		return err
+	}
+	limiter := rl.getChatLimiter(chatID)
+	return limiter.Wait(ctx)
+}
+
+// GlobalAllow checks if a global request can be made without blocking.
+// Returns false if either global cooldown is active or token bucket is exhausted.
+func (rl *RateLimiter) GlobalAllow() bool {
+	rl.globalMu.RLock()
+	until := rl.globalLockUntil
+	rl.globalMu.RUnlock()
+
+	if !until.IsZero() && time.Now().Before(until) {
+		return false
+	}
+	return rl.globalLimiter.Allow()
+}
+
+// Allow checks if a request for the given chat can be made without blocking.
+// Returns false if: global cooldown, chat cooldown, global limiter, or chat limiter denies.
+// Note: Global limiter is checked before chat limiter — upstream limits take priority.
+func (rl *RateLimiter) Allow(chatID int64) bool {
+	// Check global cooldown
+	rl.globalMu.RLock()
+	globalUntil := rl.globalLockUntil
+	rl.globalMu.RUnlock()
+	if !globalUntil.IsZero() && time.Now().Before(globalUntil) {
+		return false
+	}
+
+	// Check chat cooldown
+	rl.chatMu.Lock()
+	chatUntil, ok := rl.chatLocks[chatID]
+	rl.chatMu.Unlock()
+	if ok && !chatUntil.IsZero() && time.Now().Before(chatUntil) {
+		return false
+	}
+
+	// Check global token bucket
+	if !rl.globalLimiter.Allow() {
+		return false
+	}
+
+	// Check chat token bucket
+	limiter := rl.getChatLimiter(chatID)
+	return limiter.Allow()
+}
+
+// Check applies rate limiting based on configuration.
+// If dropOverflow is true:
+//   - Immediately returns ErrDropOverflow if either global or chat limit is exceeded.
+//
+// Else:
+//   - If chatID != 0: waits for chat-specific capacity (including global limit).
+//   - If chatID == 0: waits for global capacity only.
+//
+// chatID == 0 means no specific chat context (e.g., inline query, webhook without chat).
+func (rl *RateLimiter) Check(ctx context.Context, dropOverflow bool, chatID int64) error {
+	if dropOverflow {
+		if chatID != 0 && !rl.Allow(chatID) {
+			return ErrDropOverflow
+		}
+		if !rl.GlobalAllow() {
+			return ErrDropOverflow
+		}
+	} else if chatID != 0 {
+		if err := rl.Wait(ctx, chatID); err != nil {
+			return err
+		}
+	} else {
+		if err := rl.GlobalWait(ctx); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// waitForGlobalUnlock blocks until global cooldown expires or context is done.
+// Does not check token bucket — only cooldown.
+func (rl *RateLimiter) waitForGlobalUnlock(ctx context.Context) error {
+	rl.globalMu.RLock()
+	until := rl.globalLockUntil
+	rl.globalMu.RUnlock()
+
+	if until.IsZero() || time.Now().After(until) {
+		return nil
+	}
+
+	select {
+	case <-time.After(time.Until(until)):
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+// waitForChatUnlock blocks until the specified chat's cooldown expires or context is done.
+// Does not check token bucket — only cooldown.
+func (rl *RateLimiter) waitForChatUnlock(ctx context.Context, chatID int64) error {
+	rl.chatMu.Lock()
+	until, ok := rl.chatLocks[chatID]
+	rl.chatMu.Unlock()
+
+	if !ok || until.IsZero() || time.Now().After(until) {
+		return nil
+	}
+
+	select {
+	case <-time.After(time.Until(until)):
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+// getChatLimiter returns the rate limiter for the given chat, creating it if needed.
+// Uses 1 request per second with burst of 1 — conservative for per-user limits.
+// Must be called with rl.chatMu held.
+func (rl *RateLimiter) getChatLimiter(chatID int64) *rate.Limiter {
+	if lim, ok := rl.chatLimiters[chatID]; ok {
+		return lim
+	}
+	lim := rate.NewLimiter(1, 1)
+	rl.chatLimiters[chatID] = lim
+	return lim
+}

utils/multipart.go

@@ -1,7 +1,6 @@
 package utils
 
 import (
-	"encoding/json"
 	"fmt"
 	"io"
 	"mime/multipart"
@@ -26,33 +25,31 @@ func Encode[T any](w *multipart.Writer, req T) error {
 		field := v.Field(i)
 		fieldType := t.Field(i)
 
-		formTags := strings.Split(fieldType.Tag.Get("json"), ",")
+		jsonTag := fieldType.Tag.Get("json")
-		fieldName := ""
+		if jsonTag == "" {
-		if len(formTags) == 0 {
+			jsonTag = fieldType.Name
-			formTags = strings.Split(fieldType.Tag.Get("json"), ",")
 		}
 
-		if len(formTags) > 0 {
+		parts := strings.Split(jsonTag, ",")
-			fieldName = formTags[0]
+		fieldName := parts[0]
-			if fieldName == "-" {
+		if fieldName == "-" {
-				continue
+			continue
-			}
+		}
-			if slices.Index(formTags, "omitempty") >= 0 {
+
-				if field.IsZero() {
+		// Handle omitempty
-					continue
+		isEmpty := field.IsZero()
-				}
+		if slices.Contains(parts, "omitempty") && isEmpty {
-			}
+			continue
-		} else {
-			fieldName = strings.ToLower(fieldType.Name)
 		}
 
 		var (
 			fw  io.Writer
 			err error
 		)
+
 		switch field.Kind() {
 		case reflect.String:
-			if field.String() != "" {
+			if !isEmpty {
 				fw, err = w.CreateFormField(fieldName)
 				if err == nil {
 					_, err = fw.Write([]byte(field.String()))
@@ -80,45 +77,47 @@ func Encode[T any](w *multipart.Writer, req T) error {
 			}
 		case reflect.Slice:
 			if field.Type().Elem().Kind() == reflect.Uint8 && !field.IsNil() {
+				// Handle []byte as file upload (e.g., thumbnail)
 				filename := fieldType.Tag.Get("filename")
 				if filename == "" {
 					filename = fieldName
 				}
-
-				ext := ""
-				filename = filename + ext
-
 				fw, err = w.CreateFormFile(fieldName, filename)
 				if err == nil {
 					_, err = fw.Write(field.Bytes())
 				}
 			} else if !field.IsNil() {
-				// Handle slice of primitive values (as multiple form fields with the same name)
+				// Handle []string, []int, etc. — send as multiple fields with same name
 				for j := 0; j < field.Len(); j++ {
 					elem := field.Index(j)
 					fw, err = w.CreateFormField(fieldName)
-					if err == nil {
+					if err != nil {
-						switch elem.Kind() {
+						break
-						case reflect.String:
+					}
-							_, err = fw.Write([]byte(elem.String()))
+					switch elem.Kind() {
-						case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+					case reflect.String:
-							_, err = fw.Write([]byte(strconv.FormatInt(elem.Int(), 10)))
+						_, err = fw.Write([]byte(elem.String()))
-						case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+					case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
-							_, err = fw.Write([]byte(strconv.FormatUint(elem.Uint(), 10)))
+						_, err = fw.Write([]byte(strconv.FormatInt(elem.Int(), 10)))
-						}
+					case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+						_, err = fw.Write([]byte(strconv.FormatUint(elem.Uint(), 10)))
+					case reflect.Bool:
+						_, err = fw.Write([]byte(strconv.FormatBool(elem.Bool())))
+					case reflect.Float32, reflect.Float64:
+						_, err = fw.Write([]byte(strconv.FormatFloat(elem.Float(), 'f', -1, 64)))
+					}
+					if err != nil {
+						break
 					}
 				}
 			}
 
 		case reflect.Struct:
-			var jsonData []byte
+			// Don't serialize structs as JSON — flatten them!
-			jsonData, err = json.Marshal(field.Interface())
+			// Telegram doesn't support nested JSON in form-data.
-			if err == nil {
+			// If you need nested data, use separate fields (e.g., ParseMode, CaptionEntities)
-				fw, err = w.CreateFormField(fieldName)
+			// This is a design choice — you should avoid nested structs in params.
-				if err == nil {
+			return fmt.Errorf("nested structs are not supported in params — use flat fields")
-					_, err = fw.Write(jsonData)
-				}
-			}
 		}
 
 		if err != nil {

utils/utils.go

@@ -1,9 +1,7 @@
 package utils
 
 import (
-	"fmt"
 	"os"
-	"strings"
 
 	"git.nix13.pw/scuroneko/slog"
 )
@@ -15,18 +13,3 @@ func GetLoggerLevel() slog.LogLevel {
 	}
 	return level
 }
-
-func EscapeMarkdown(s string) string {
-	s = strings.ReplaceAll(s, "_", `\_`)
-	s = strings.ReplaceAll(s, "*", `\*`)
-	s = strings.ReplaceAll(s, "[", `\[`)
-	return strings.ReplaceAll(s, "`", "\\`")
-}
-
-func EscapeMarkdownV2(s string) string {
-	symbols := []string{"_", "*", "[", "]", "(", ")", "~", "`", ">", "#", "+", "-", "=", "|", "{", "}", ".", "!"}
-	for _, symbol := range symbols {
-		s = strings.ReplaceAll(s, symbol, fmt.Sprintf("\\%s", symbol))
-	}
-	return s
-}

utils/version.go

@@ -1,9 +1,9 @@
 package utils
 
 const (
-	VersionString = "1.0.0-beta.6"
+	VersionString = "1.0.0-beta.12"
 	VersionMajor  = 1
 	VersionMinor  = 0
 	VersionPatch  = 0
-	Beta          = 6
+	VersionBeta   = 12
 )